Getting started

jitr is a nuclear reaction toolkit, production ready for calibration and uncertainty-quantification, featuring:

• fast calculable \(\mathcal{R}\)-matrix solver for parametric reaction models

• built in uncertainty-quantified optical potentials

• built in nuclear data

• plenty of examples demonstrating the propagation of uncertainties into reaction observables and model calibration

Give your nuclear reaction UQ workflow a caffeine-kick with jitr!

Description

Under the hood, jitr solves the Shrödinger equation using the calculable \(\mathcal{R}\)-Matrix method on a Lagrange-Legendre mesh. It is fast because it gives users the tools to precompute everything that they can for a system and reaction of interest, so given a single parameter sample, the minimal amount of compute is required to spit a cross section back out. For this reason, jitr is really suited to calculating an ensemble of observables corresponding to an ensemble of reactions. Additionally, jitr relies on vectorized operations from numpy, as well as just-in-time (JIT) compilation from numba for the small subset of performance-critical code.

The theory generally follows:

• Baye, D. (2015). The Lagrange-mesh method. Physics reports, 565, 1-107

• Descouvemont, P. (2016). An R-matrix package for coupled-channel problems in nuclear physics. Computer physics communications, 200, 199-219

• Descouvemont P. and Baye D. (2010). The R-matrix theory. Rep. Prog. Phys. 73 036301

Installation

Install the latest published package with:

pip install jitr

If you use uv, add it to an existing project with:

uv add jitr

or install it into the current environment with:

uv pip install jitr

To check the installed version:

python -c "import jitr; print(jitr.__version__)"

Examples and tutorials

Tutorials live in examples/notebooks/ in the repository, and rendered copies are listed on the examples page.

Run them in your browser

Every notebook carries an Open in Colab badge at the top, and you can browse them all in Colab or jump straight to the quickstart.

Run them locally

For real work, clone the repo and open the notebooks with the default Python 3 (ipykernel) kernel, which lives inside the uv-managed environment. This way, you can be sure that all the dependencies are correct and that the notebooks will run as expected. No kernel registration is needed.

git clone https://github.com/beykyle/jitr.git
cd jitr

Before you can run the notebooks, there are some additional requirements which need to be installed into the environment. They live in the examples dependency group. To install them, from the main project directory, run:

uv sync --group examples

Then, you can launch jupyter inside the uv-managed environment. For example, to spin up a JupyterLab server:

uv run --group examples jupyter lab

Then, you can run the notebooks in-browser. See the Advanced users and developers page for more information about setting up a local editable installation of jitr, about uv, and other environment management related things.

Quick start

The quickstart example gives a fast end-to-end walk-through for:

• compiling a solver for a given reaction system (\(\alpha\) + \(^{44}\)Ca)

• defining a parametric interaction potential and calculating a cross section

• fitting the potential parameters to real experimental data

A follow-up notebook extends this example to a full Bayesian calibration over multiple target isotopes, and checks the posterior predictive against the experimental data.

API reference and development

Use the API reference for detailed documentation of the codebase.

For development setup, test commands, and documentation builds, see Advanced users and developers and Tests.

BAND

jitr is one of the software packages included in the BAND Framework.

Citations

Please consider citing both jitr and the BAND Framework if you use the code in your research. The BibTeX entries are:

@software{Beyer_JITR_2024,
author = {Beyer, Kyle},
license = {BSD-3-Clause},
month = oct,
title = {{JITR}},
url = {https://github.com/beykyle/jitr},
version = {1.3.0},
year = {2024}
}

@techreport{bandframework,
    title       = {{BANDFramework: An} Open-Source Framework for {Bayesian} Analysis of Nuclear Dynamics},
    author      = {Kyle Beyer and Landon Buskirk and Manuel Catacora Rios and Moses Y-H. Chan and Tyler H. Chang and Troy Dasher 
    and Richard James DeBoer and Christian Drischler and Richard J. Furnstahl and Pablo Giuliani and
    Kyle Godbey and Kevin Ingles and Sunil Jaiswal and An Le and Dananjaya Liyanage and Filomena M. Nunes
    and Daniel Odell and David O'Gara and Jared O'Neal and Daniel R. Phillips and Matthew Plumlee
    and Matthew T. Pratola and Scott Pratt and Oleh Savchuk and Alexandra C. Semposki and \"Ozge S\"urer and
    Stefan M. Wild and John C. Yannotty},
    institution = {},
    number      = {Version 0.5.0},
    year        = {2025},
    url         = {https://github.com/bandframework/bandframework}
}