wiso/relaxed

Provides differentiable versions of common HEP operations and objectives.

😴
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

In your virtual environment:

python3 -m pip install relaxed

Examples

<- Click here to start playing with our examples straight away (thanks to Binder)!

If you'd rather run the example notebooks locally from examples/, you can clone the repository, then:

python3 -m venv venv  # or virtualenv
source venv/bin/activate
pip install --upgrade pip setuptools wheel
pip install relaxed
cd examples
pip install -r requirements.txt

Then launch jupyter through your preferred medium (vscode, jupyterlab, etc.), making sure to use this virtual env as your kernel (e.g. you can pip install and run jupyter lab in this env).

Sharp bits

For serious 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 ;)