relaxed 0.2.0

Differentiable versions of common operations in high-energy physics.

:sleeping:
relaxed

Provides differentiable ("relaxed") versions of common operations in high-energy physics.

Based on jax. Where possible, function APIs try to mimic their commonly used counterparts, e.g. fitting and hypothesis testing in pyhf.

currently implemented:

• basic operations:
  • relaxed.hist: histograms via kernel density estimation (tunable bandwidth).
  • relaxed.cut: approximates a hard cut with a sigmoid function (tunable slope).
• fitting routines:
  • relaxed.mle.fit: global MLE fit.
  • relaxed.mle.fixed_poi_fit: constrained fit given a value of a parameter of interest.
• inference:
  • relaxed.infer.hypotest: hypothesis test based on the profile likelihood. Supports test statistics for both limit setting (q) and discovery (q_0).
  • relaxed.fisher_info: the fisher information matrix (of a pyhf-type model).
  • relaxed.cramer_rao_uncert: inverts the fisher information matrix to provide uncertainties valid through the Cramér-Rao bound.
• metrics:
  • relaxed.metrics.gaussianity: an experimental metric that quantifies the mean-squared difference of a likelihood function with respect to its gaussian approximation (covariance calculated using the Cramér-Rao bound above).
  • relaxed.metrics.asimov_sig: easy access to the (single- and multi-bin) stat-only expected significance.

We're maintaining a list of desired differentiable operations in list_of_operations.md (thanks to @cranmer) -- feel free to take inspiration or contribute with a PR if there's one you can handle :)

install

python3 -m pip install relaxed

For use with pyhf, e.g. in a neos-type workflow, it is temporarily recommended to install pyhf using a specific branch that is designed to be differentiable with respect to model construction:

python3 -m pip install git+http://github.com/scikit-hep/pyhf.git@make_difffable_model_ctor

We plan to merge this into pyhf when it's stable, and will then drop this instruction :)

cite

If you use relaxed, please cite us! You should be able to do that from the github UI (top-right, under 'cite this repository'), but if not, see our Zenodo DOI or our CITATION.cff.

acknowledgments

Big thanks to all the developers of the main packages we use (jax, pyhf, jaxopt). Thanks also to @dfm for the README header inspiration ;)