Package: pyshaper
SHAPER (v1.2.0)SHAPERis 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). 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 theSHAPERalgorithm computes the value of the observable and optimal parameters.TheSHAPERframework contains::Pre-built observables, includingN-subjettinessandisotropy.Novel pre-built observables and jet algorithms for finding ring, disk, or ellipse-like jets, with optional centers for collinear radiation and optional pileup radiationModules 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.InstallationFrom PyPIIn your Python environment runpython -m pip install pyshaper
# python -m pip install --upgrade 'pyshaper[all]'  # for all extrasFrom this repository locallyIn your Python environment from the top level of this repository runpython -m pip install .
# python -m pip install --upgrade '.[all]'  # for all extrasFrom GitHubIn your Python environment runpython -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 extrasExample UsageFor an example of how to useSHAPER, see the notebookexamples/example.ipynb. This notebook contains example code for loading data, using pre-built shape observables, defining custom shape observables, running theSHAPERalgorithm to evaluate these observables, and making plots.To run the example, you will need to havepyshaperinstalled 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.DependenciesTo useSHAPER, the following packages must be installed as prerequisites:PyTorch: A standard tensor operation library.GeomLoss: A library for optimal transport.pyjet: A package for jet clustering, needed for default observable definitions.Energyflow: A suite of particle physics tools. This package is OPTIONAL; however, many of the example datasets withinSHAPERrequire this package to load. Not necessary if you provide and format your own data. Included as part of the 'energyflow' extra.imageio: An image manipulation package. Needed for automatic gif creation -- not needed otherwise. Included as part of the 'viz' extra.Standard python packages:numpy,scipy,matplotlibCitationIf you useSHAPER, 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"
}Changelogv1.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)Bugs, Fixes, Ideas, or Questions? Contact me atrikab@mit.eduTo discuss finer mathematical details (model convergence, optimization guarantees, etc), you may also contact Akshunna S. Dogra atadogra@nyu.edu