| Name | pyshaper JSON |
| Version |
1.2.0
JSON |
| download |
| home_page | |
| Summary | framework for defining, building, and evaluating generalized shape observables for collider physics |
| upload_time | 2024-02-28 01:26:18 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.7 |
| license | MIT |
| keywords |
jet physics
shape observables
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# SHAPER (v1.2.0)
[](https://github.com/rikab/shaper)
[](https://doi.org/10.5281/zenodo.7689890)
[](https://pypi.org/project/pyshaper/)
[](https://pypi.org/project/pyshaper/)
`SHAPER` is a framework for defining, building, and evaluating generalized shape observables for collider physics, as defined in ["SHAPER: Can You Hear the Shape of a Jet?" (arxiv:2302.12266)](https://arxiv.org/abs/2302.12266). This package can be used for evaluating an extremely large class of IRC-safe observables, with modules in place to define custom observables and jet algorithms using an intuitive geometric language.
Pictured: Example of a custom jet algorithm, "3-(Ellipse+Point)iness+Pileup", as evaluated on an example top jet, as the `SHAPER` algorithm computes the value of the observable and optimal parameters.
The `SHAPER` framework contains::
- Pre-built observables, including [N-subjettiness](https://inspirehep.net/literature/876746) and [isotropy](https://inspirehep.net/literature/1791220).
- Novel pre-built observables and jet algorithms for finding ring, disk, or ellipse-like jets, with optional centers for collinear radiation and optional pileup radiation
- Modules for defining arbitrary shape observables using parameterized manifolds, and building new complex observables from old ones.
- Modules for evaluating defined shape observables on event data, using the Sinkhorn divergence approximation of the Wasserstein metric. This returns both the shape value ("shapiness") and the optimal shape parameters.
- Modules for visualizing shape observables and their optimization, as in the GIF above.
## Installation
### From PyPI
In your Python environment run
```
python -m pip install pyshaper
# python -m pip install --upgrade 'pyshaper[all]' # for all extras
```
### From this repository locally
In your Python environment from the top level of this repository run
```
python -m pip install .
# python -m pip install --upgrade '.[all]' # for all extras
```
### From GitHub
In your Python environment run
```
python -m pip install "pyshaper @ git+https://github.com/rikab/shaper.git"
# python -m pip install --upgrade "pyshaper[all] @ git+https://github.com/rikab/shaper.git" # for all extras
```
## Example Usage
For an example of how to use `SHAPER`, see the notebook `examples/example.ipynb`. This notebook contains example code for loading data, using pre-built shape observables, defining custom shape observables, running the `SHAPER` algorithm to evaluate these observables, and making plots.
To run the example, you will need to have `pyshaper` installed with all extras. This can be done using (assuming a PyPi installation):
```
python -m pip install --upgrade 'pyshaper[all]'
```
See the Installation section above for more details.
## Dependencies
To use `SHAPER`, the following packages must be installed as prerequisites:
- [PyTorch](https://github.com/pytorch/pytorch): A standard tensor operation library.
- [GeomLoss](https://www.kernel-operations.io/geomloss/): A library for optimal transport.
- [pyjet](https://github.com/scikit-hep/pyjet): A package for jet clustering, needed for default observable definitions.
- [Energyflow](https://energyflow.network/): A suite of particle physics tools. This package is OPTIONAL; however, many of the example datasets within `SHAPER` require this package to load. Not necessary if you provide and format your own data. Included as part of the 'energyflow' extra.
- [imageio](https://pypi.org/project/imageio/): An image manipulation package. Needed for automatic gif creation -- not needed otherwise. Included as part of the 'viz' extra.
- Standard python packages: [numpy](https://numpy.org/), [scipy](https://scipy.org/), [matplotlib](https://matplotlib.org/)
## Citation
If you use `SHAPER`, please cite both this code archive and the corresponding paper, "Can You Hear the Shape of a Jet"?:
@software{SHAPER,
author = {Rikab Gambhir, Akshunna S. Dogra, Abiy Tasissa, Demba Ba, Jesse Thaler},
title = "{pyshaper: v1.1.0}",
version = {1.1.0},
doi = {10.5281/zenodo.7689890},
url = {doi.org/10.5281/zenodo.7689890},
note = {https://github.com/rikab/SHAPER/releases/tag/v1.1.0}
}
@article{Ba:2023hix,
author = "Ba, Demba and Dogra, Akshunna S. and Gambhir, Rikab and Tasissa, Abiy and Thaler, Jesse",
title = "{SHAPER: Can You Hear the Shape of a Jet?}",
eprint = "2302.12266",
archivePrefix = "arXiv",
primaryClass = "hep-ph",
reportNumber = "MIT-CTP 5535",
month = "2",
year = "2023"
}
## Changelog
- v1.2.0: 27 February 2024. New Default array format. New functions for pairwise and isometric EMD. Bugfix in CommonObservables beta assignment.
- v1.1.1: 28 June 2023. Pairwise EMDs added.
- v1.1.0: 5 May 2023. Updated Geomloss dependency.
- v1.0.1: 10 March 2023. PyPi-installable release. Minor changes to example and optional dependency handling.
- v1.0.0: 24 February 2023. Official public release.
Based on the work in ["SHAPER: Can You Hear the Shape of a Jet?" (arxiv:2302.12266)](https://arxiv.org/abs/2302.12266)
Bugs, Fixes, Ideas, or Questions? Contact me at rikab@mit.edu
To discuss finer mathematical details (model convergence, optimization guarantees, etc), you may also contact Akshunna S. Dogra at adogra@nyu.edu
Raw data
{
"_id": null,
"home_page": "",
"name": "pyshaper",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "jet physics,shape observables",
"author": "",
"author_email": "Rikab Gambhir <rikab@mit.edu>",
"download_url": "https://files.pythonhosted.org/packages/95/b2/d2237ea19496a58acdacd2003a9b5b31fb3230b129b53fb1d40093ad462d/pyshaper-1.2.0.tar.gz",
"platform": null,
"description": "# SHAPER (v1.2.0)\n\n[](https://github.com/rikab/shaper)\n[](https://doi.org/10.5281/zenodo.7689890)\n\n[](https://pypi.org/project/pyshaper/)\n[](https://pypi.org/project/pyshaper/)\n\n`SHAPER` is a framework for defining, building, and evaluating generalized shape observables for collider physics, as defined in [\"SHAPER: Can You Hear the Shape of a Jet?\" (arxiv:2302.12266)](https://arxiv.org/abs/2302.12266). This package can be used for evaluating an extremely large class of IRC-safe observables, with modules in place to define custom observables and jet algorithms using an intuitive geometric language.\n\n\n\nPictured: Example of a custom jet algorithm, \"3-(Ellipse+Point)iness+Pileup\", as evaluated on an example top jet, as the `SHAPER` algorithm computes the value of the observable and optimal parameters.\n\nThe `SHAPER` framework contains::\n\n- Pre-built observables, including [N-subjettiness](https://inspirehep.net/literature/876746) and [isotropy](https://inspirehep.net/literature/1791220).\n- Novel pre-built observables and jet algorithms for finding ring, disk, or ellipse-like jets, with optional centers for collinear radiation and optional pileup radiation\n- Modules for defining arbitrary shape observables using parameterized manifolds, and building new complex observables from old ones.\n- Modules for evaluating defined shape observables on event data, using the Sinkhorn divergence approximation of the Wasserstein metric. This returns both the shape value (\"shapiness\") and the optimal shape parameters.\n- Modules for visualizing shape observables and their optimization, as in the GIF above.\n\n## Installation\n\n### From PyPI\n\nIn your Python environment run\n\n```\npython -m pip install pyshaper\n# python -m pip install --upgrade 'pyshaper[all]' # for all extras\n```\n\n### From this repository locally\n\nIn your Python environment from the top level of this repository run\n\n```\npython -m pip install .\n# python -m pip install --upgrade '.[all]' # for all extras\n```\n\n### From GitHub\n\nIn your Python environment run\n\n```\npython -m pip install \"pyshaper @ git+https://github.com/rikab/shaper.git\"\n# python -m pip install --upgrade \"pyshaper[all] @ git+https://github.com/rikab/shaper.git\" # for all extras\n```\n\n## Example Usage\n\nFor an example of how to use `SHAPER`, see the notebook `examples/example.ipynb`. This notebook contains example code for loading data, using pre-built shape observables, defining custom shape observables, running the `SHAPER` algorithm to evaluate these observables, and making plots.\n\nTo run the example, you will need to have `pyshaper` installed with all extras. This can be done using (assuming a PyPi installation):\n\n```\npython -m pip install --upgrade 'pyshaper[all]'\n```\n\nSee the Installation section above for more details.\n\n## Dependencies\n\nTo use `SHAPER`, the following packages must be installed as prerequisites:\n\n- [PyTorch](https://github.com/pytorch/pytorch): A standard tensor operation library.\n- [GeomLoss](https://www.kernel-operations.io/geomloss/): A library for optimal transport.\n- [pyjet](https://github.com/scikit-hep/pyjet): A package for jet clustering, needed for default observable definitions.\n- [Energyflow](https://energyflow.network/): A suite of particle physics tools. This package is OPTIONAL; however, many of the example datasets within `SHAPER` require this package to load. Not necessary if you provide and format your own data. Included as part of the 'energyflow' extra.\n- [imageio](https://pypi.org/project/imageio/): An image manipulation package. Needed for automatic gif creation -- not needed otherwise. Included as part of the 'viz' extra.\n- Standard python packages: [numpy](https://numpy.org/), [scipy](https://scipy.org/), [matplotlib](https://matplotlib.org/)\n\n## Citation\n\nIf you use `SHAPER`, please cite both this code archive and the corresponding paper, \"Can You Hear the Shape of a Jet\"?:\n\n @software{SHAPER,\n author = {Rikab Gambhir, Akshunna S. Dogra, Abiy Tasissa, Demba Ba, Jesse Thaler},\n title = \"{pyshaper: v1.1.0}\",\n version = {1.1.0},\n doi = {10.5281/zenodo.7689890},\n url = {doi.org/10.5281/zenodo.7689890},\n note = {https://github.com/rikab/SHAPER/releases/tag/v1.1.0}\n }\n\n @article{Ba:2023hix,\n author = \"Ba, Demba and Dogra, Akshunna S. and Gambhir, Rikab and Tasissa, Abiy and Thaler, Jesse\",\n title = \"{SHAPER: Can You Hear the Shape of a Jet?}\",\n eprint = \"2302.12266\",\n archivePrefix = \"arXiv\",\n primaryClass = \"hep-ph\",\n reportNumber = \"MIT-CTP 5535\",\n month = \"2\",\n year = \"2023\"\n }\n\n## Changelog\n\n- v1.2.0: 27 February 2024. New Default array format. New functions for pairwise and isometric EMD. Bugfix in CommonObservables beta assignment. \n- v1.1.1: 28 June 2023. Pairwise EMDs added.\n- v1.1.0: 5 May 2023. Updated Geomloss dependency.\n- v1.0.1: 10 March 2023. PyPi-installable release. Minor changes to example and optional dependency handling.\n- v1.0.0: 24 February 2023. Official public release.\n\nBased on the work in [\"SHAPER: Can You Hear the Shape of a Jet?\" (arxiv:2302.12266)](https://arxiv.org/abs/2302.12266)\n\nBugs, Fixes, Ideas, or Questions? Contact me at rikab@mit.edu\n\nTo discuss finer mathematical details (model convergence, optimization guarantees, etc), you may also contact Akshunna S. Dogra at adogra@nyu.edu\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "framework for defining, building, and evaluating generalized shape observables for collider physics",
"version": "1.2.0",
"project_urls": {
"Documentation": "https://github.com/rikab/SHAPER",
"Homepage": "https://github.com/rikab/SHAPER",
"Issue Tracker": "https://github.com/rikab/SHAPER/issues",
"Releases": "https://github.com/rikab/SHAPER/releases",
"Source Code": "https://github.com/rikab/SHAPER"
},
"split_keywords": [
"jet physics",
"shape observables"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "408dfd0315bf0d1c6131da1c44ce3574f46334dcd9a133350733c88e6f14cf9b",
"md5": "d79843aa2520728c3a36056e62585c59",
"sha256": "b1d35f8be3ce9829eb595bd13bc45fc01bb9eba74ec4d8d6ff9da93f3f14380d"
},
"downloads": -1,
"filename": "pyshaper-1.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d79843aa2520728c3a36056e62585c59",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 18634,
"upload_time": "2024-02-28T01:26:17",
"upload_time_iso_8601": "2024-02-28T01:26:17.211359Z",
"url": "https://files.pythonhosted.org/packages/40/8d/fd0315bf0d1c6131da1c44ce3574f46334dcd9a133350733c88e6f14cf9b/pyshaper-1.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "95b2d2237ea19496a58acdacd2003a9b5b31fb3230b129b53fb1d40093ad462d",
"md5": "b497b36df833233a4ecaf8d4e2059b38",
"sha256": "6357ac9e264bb5c8df9c362e517d8b3496d920da9f91d5800189a64dc9ff4916"
},
"downloads": -1,
"filename": "pyshaper-1.2.0.tar.gz",
"has_sig": false,
"md5_digest": "b497b36df833233a4ecaf8d4e2059b38",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 17188,
"upload_time": "2024-02-28T01:26:18",
"upload_time_iso_8601": "2024-02-28T01:26:18.338685Z",
"url": "https://files.pythonhosted.org/packages/95/b2/d2237ea19496a58acdacd2003a9b5b31fb3230b129b53fb1d40093ad462d/pyshaper-1.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-28 01:26:18",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "rikab",
"github_project": "SHAPER",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "pyshaper"
}
