Core package

The core page documents the package-level exports together with the utility modules that support kinematics and nuclear data, and shared helper functions.

Public package entry points for jitr.

Utilities

The jitr.utils package re-exports the most common helper modules and functions. The defining modules are documented below so objects only appear once in the API index.

Physical constants used throughout jitr.

Analytic and tabulated proton/neutron density utilities.

class jitr.utils.density.DensityTable(A, Z, model, symbol, dr, radial_grid, proton_density_grid, neutron_density_grid)

Bases: object

Tabulated proton and neutron densities for a single nuclide.

Parameters:

• A (int) – Atomic mass number.

• Z (int) – Atomic number.

• model (str) – Density-model identifier.

• symbol (str) – Chemical symbol used by the packaged table.

• dr (float) – Nominal radial-grid spacing in fm.

• radial_grid (ndarray[tuple[Any, ...], dtype[double]]) – Tabulated radial grid in fm.

• proton_density_grid (ndarray[tuple[Any, ...], dtype[double]]) – Proton density sampled on radial_grid.

• neutron_density_grid (ndarray[tuple[Any, ...], dtype[double]]) – Neutron density sampled on radial_grid.

A: int

Z: int

model: str

symbol: str

dr: float

radial_grid: ndarray[tuple[Any, ...], dtype[float64]]

proton_density_grid: ndarray[tuple[Any, ...], dtype[float64]]

neutron_density_grid: ndarray[tuple[Any, ...], dtype[float64]]

property N: int

Return the neutron number.

densities(r)

Return proton and neutron densities on the requested radial grid.

Parameters:

r (float | TypeAliasType) – Radial coordinate or coordinates in fm.

Return type:

tuple[ndarray[tuple[Any, ...], dtype[double]], ndarray[tuple[Any, ...], dtype[double]]]

Returns:

Tuple of proton and neutron density arrays.

proton_density(r)

Return the proton density on the requested radial grid.

Parameters:

r (float | TypeAliasType) – Radial coordinate or coordinates in fm.

Return type:

ndarray[tuple[Any, ...], dtype[double]]

Returns:

Proton density values sampled at r.

neutron_density(r)

Return the neutron density on the requested radial grid.

Parameters:

r (float | TypeAliasType) – Radial coordinate or coordinates in fm.

Return type:

ndarray[tuple[Any, ...], dtype[double]]

Returns:

Neutron density values sampled at r.

matter_density(r)

Return the total matter density on the requested radial grid.

Parameters:

r (float | TypeAliasType) – Radial coordinate or coordinates in fm.

Return type:

ndarray[tuple[Any, ...], dtype[double]]

Returns:

Matter density values sampled at r.

class jitr.utils.density.TwoParameterFermiDensity(R, a, rho0=None, N=None)

Bases: object

Callable two-parameter Fermi density profile.

Parameters:

• R (float) – Half-density radius in fm.

• a (float) – Surface diffuseness in fm.

• rho0 (float | None) – Central density normalization. Mutually exclusive with N.

• N (float | None) – Integrated particle number. Mutually exclusive with rho0.

Raises:

ValueError – If neither rho0 nor N is provided.

R: float

a: float

rho0: float | None = None

N: float | None = None

jitr.utils.density.densities(A, Z, r, model='d1m')

Return proton and neutron densities on the requested radial grid.

Parameters:

• A (int) – Atomic mass number.

• Z (int) – Atomic number.

• r (float | TypeAliasType) – Radial coordinate or coordinates in fm.

• model (str) – Density-model identifier.

Return type:

tuple[ndarray[tuple[Any, ...], dtype[double]], ndarray[tuple[Any, ...], dtype[double]]]

Returns:

Tuple of proton and neutron density arrays.

jitr.utils.density.density_from_array(r_array, rho_array, clip_negative=True)

Wrap a tabulated radial density as a callable interpolator.

Parameters:

• r_array (float | TypeAliasType) – Strictly increasing tabulated radii in fm.

• rho_array (float | TypeAliasType) – Density values sampled on r_array.

• clip_negative (bool) – Whether to clip interpolated negative values to zero.

Return type:

Callable[[float | TypeAliasType], ndarray[tuple[Any, ...], dtype[double]]]

Returns:

A callable density interpolator that returns zero outside the tabulated range and exposes r_max as the maximum tabulated radius.

Raises:

ValueError – If the tabulated arrays have different shapes or the radial grid is not strictly increasing.

jitr.utils.density.density_models()

Return the list of available density models.

Return type:

list[str]

jitr.utils.density.density_table(A, Z, model='d1m')

Return the tabulated density table for a nuclide.

Parameters:

• A (int) – Atomic mass number.

• Z (int) – Atomic number.

• model (str) – Density-model identifier.

Return type:

DensityTable

Returns:

The packaged density table for (A, Z).

Raises:

KeyError – If no table exists for the requested nuclide/model.

jitr.utils.density.density_targets(model='d1m', Z=None)

Return the available nuclides for a density model.

Parameters:

• model (str) – Density-model identifier.

• Z (int | None) – Optional atomic-number filter.

Return type:

list[tuple[int, int]]

Returns:

Sorted (A, Z) target tuples available for model.

jitr.utils.density.init_density_db()

Load the packaged density tables into memory if needed.

Return type:

None

jitr.utils.density.matter_density(A, Z, r, model='d1m')

Return the total matter density on the requested radial grid.

Parameters:

• A (int) – Atomic mass number.

• Z (int) – Atomic number.

• r (float | TypeAliasType) – Radial coordinate or coordinates in fm.

• model (str) – Density-model identifier.

Return type:

ndarray[tuple[Any, ...], dtype[double]]

Returns:

Matter density values sampled at r.

jitr.utils.density.neutron_density(A, Z, r, model='d1m')

Return the neutron density on the requested radial grid.

Parameters:

• A (int) – Atomic mass number.

• Z (int) – Atomic number.

• r (float | TypeAliasType) – Radial coordinate or coordinates in fm.

• model (str) – Density-model identifier.

Return type:

ndarray[tuple[Any, ...], dtype[double]]

Returns:

Neutron density values sampled at r.

jitr.utils.density.proton_density(A, Z, r, model='d1m')

Return the proton density on the requested radial grid.

Parameters:

• A (int) – Atomic mass number.

• Z (int) – Atomic number.

• r (float | TypeAliasType) – Radial coordinate or coordinates in fm.

• model (str) – Density-model identifier.

Return type:

ndarray[tuple[Any, ...], dtype[double]]

Returns:

Proton density values sampled at r.

jitr.utils.density.two_parameter_fermi(r, R, a, rho0=None, N=None)

Return a two-parameter Fermi density.

Parameters:

• r (float | TypeAliasType) – Radial coordinate or coordinates in fm.

• R (float) – Half-density radius in fm.

• a (float) – Surface diffuseness in fm.

• rho0 (float | None) – Central density normalization. Mutually exclusive with N.

• N (float | None) – Integrated particle number used to normalize the profile.

Return type:

ndarray[tuple[Any, ...], dtype[double]]

Returns:

Density values sampled at r.

Raises:

ValueError – If neither rho0 nor N is provided.

Free-particle and Coulomb asymptotic solutions.

jitr.utils.free_solutions.Gamow_factor(l, eta)

Return the Coulomb Gamow factor for angular momentum l.

Return type:

float

Parameters:

• l (int)

• eta (float)

class jitr.utils.free_solutions.FreeAsymptotics

Bases: object

Spherical-Bessel asymptotics for neutral-particle scattering.

static F(s, l, _eta=None)

Return the regular free solution.

Return type:

double

Parameters:

• s (float)

• l (int)

• _eta (float | None)

static G(s, l, _eta=None)

Return the irregular free solution.

Return type:

double

Parameters:

• s (float)

• l (int)

• _eta (float | None)

class jitr.utils.free_solutions.CoulombAsymptotics

Bases: object

Coulomb asymptotic functions evaluated through mpmath.

static F(s, l, eta)

Return the regular Coulomb function.

Return type:

cdouble

Parameters:

• s (float)

• l (int)

• eta (float)

static G(s, l, eta)

Return the irregular Coulomb function.

Return type:

cdouble

Parameters:

• s (float)

• l (int)

• eta (float)

jitr.utils.free_solutions.H_plus(s, l, eta, asym=<class 'jitr.utils.free_solutions.CoulombAsymptotics'>)

Return the outgoing Coulomb-Hankel function.

Return type:

complex

Parameters:

• s (float)

• l (int)

• eta (float)

• asym (type)

jitr.utils.free_solutions.H_minus(s, l, eta, asym=<class 'jitr.utils.free_solutions.CoulombAsymptotics'>)

Return the incoming Coulomb-Hankel function.

Return type:

complex

Parameters:

• s (float)

• l (int)

• eta (float)

• asym (type)

jitr.utils.free_solutions.coulomb_func_deriv(func, s, l, eta)

Differentiate Coulomb or Coulomb-Hankel functions using recurrence relations.

Return type:

complex

Parameters:

• func (Callable[[float, int, float], complex])

• s (float)

• l (int)

• eta (float)

jitr.utils.free_solutions.H_plus_prime(s, l, eta, asym=<class 'jitr.utils.free_solutions.CoulombAsymptotics'>)

Return the derivative of the outgoing Coulomb-Hankel function.

Return type:

complex

Parameters:

• s (float)

• l (int)

• eta (float)

• asym (type)

jitr.utils.free_solutions.H_minus_prime(s, l, eta, dx=1e-06, asym=<class 'jitr.utils.free_solutions.CoulombAsymptotics'>)

Return the derivative of the incoming Coulomb-Hankel function.

Return type:

complex

Parameters:

• s (float)

• l (int)

• eta (float)

• dx (float)

• asym (type)

Kinematic helpers for entrance, exit, and frame-conversion calculations.

class jitr.utils.kinematics.ChannelKinematics(Elab, Ecm, mu, k, eta)

Bases: object

Kinematic quantities for a single reaction channel.

Variables:

• Elab – Laboratory-frame kinetic energy in MeV.

• Ecm – Center-of-mass kinetic energy in MeV.

• mu – Reduced mass in MeV/c^2.

• k – Center-of-mass wavenumber in fm^-1.

• eta – Sommerfeld parameter.

Parameters:

• Elab (float)

• Ecm (float)

• mu (float)

• k (float)

• eta (float)

Elab: float

Ecm: float

mu: float

k: float

eta: float

jitr.utils.kinematics.semi_relativistic_kinematics(mass_target, mass_projectile, Elab, Zz=0)

Compute semi-relativistic entrance-channel kinematics.

Uses the approximation from Ingemarsson (1974) for a projectile scattering from a fixed target.

Parameters:

• mass_target (float) – Target rest mass in MeV/c^2.

• mass_projectile (float) – Projectile rest mass in MeV/c^2.

• Elab (float) – Laboratory-frame kinetic energy in MeV.

• Zz (int) – Product of projectile and target charges.

Return type:

ChannelKinematics

Returns:

A populated ChannelKinematics instance.

jitr.utils.kinematics.classical_kinematics(mass_target, mass_projectile, Elab, Zz=0)

Compute non-relativistic kinematics from a laboratory energy.

Parameters:

• mass_target (float) – Target rest mass in MeV/c^2.

• mass_projectile (float) – Projectile rest mass in MeV/c^2.

• Elab (float) – Laboratory-frame kinetic energy in MeV.

• Zz (int) – Product of projectile and target charges.

Return type:

ChannelKinematics

Returns:

A populated ChannelKinematics instance.

jitr.utils.kinematics.classical_kinematics_cm(mass_target, mass_projectile, Ecm, Zz=0)

Compute non-relativistic kinematics from a center-of-mass energy.

Parameters:

• mass_target (float) – Target rest mass in MeV/c^2.

• mass_projectile (float) – Projectile rest mass in MeV/c^2.

• Ecm (float) – Center-of-mass kinetic energy in MeV.

• Zz (int) – Product of projectile and target charges.

Return type:

ChannelKinematics

Returns:

A populated ChannelKinematics instance.

jitr.utils.kinematics.cm_to_lab_frame(angles_cm_deg, ma, mb, mc, md, E, Q)

Convert center-of-mass angles to laboratory angles.

Parameters:

• angles_cm_deg (TypeAliasType) – Input angles in degrees.

• ma (float) – Mass of projectile a.

• mb (float) – Mass of target b.

• mc (float) – Mass of ejectile c.

• md (float) – Mass of recoil d.

• E (float) – Laboratory-frame energy in MeV.

• Q (float) – Reaction Q-value in MeV.

Return type:

ndarray[tuple[Any, ...], dtype[double]]

Returns:

A NumPy array of laboratory-frame angles in degrees.

jitr.utils.kinematics.lab_to_cm_frame(angles_lab_deg, ma, mb, mc, md, E, Q)

Convert laboratory angles to center-of-mass angles.

Parameters:

• angles_lab_deg (TypeAliasType) – Input angles in degrees.

• ma (float) – Mass of projectile a.

• mb (float) – Mass of target b.

• mc (float) – Mass of ejectile c.

• md (float) – Mass of recoil d.

• E (float) – Laboratory-frame energy in MeV.

• Q (float) – Reaction Q-value in MeV.

Return type:

ndarray[tuple[Any, ...], dtype[double]]

Returns:

A NumPy array of center-of-mass angles in degrees.

General-purpose numerical helpers used across jitr.

jitr.utils.utils.complex_det(matrix)

Return sqrt(det(A A^†)) for a complex matrix.

Return type:

cdouble

Parameters:

matrix (ndarray)

jitr.utils.utils.block(matrix, block_index, block_size)

Extract a sub-block from a block-structured matrix.

Parameters:

• matrix (ndarray) – Input matrix containing equally sized blocks.

• block_index (tuple[int, int]) – (row, column) index of the desired block.

• block_size (tuple[int, int]) – Shape of each block as (rows, columns).

Return type:

ndarray

Returns:

The requested submatrix view.

jitr.utils.utils.second_derivative_op(s, channel, interaction, args=())

Evaluate the scaled radial Schrödinger operator.

Return type:

complex

Parameters:

• s (float)

• channel (Any)

• interaction (Callable[[...], complex])

• args (tuple[Any, ...])

jitr.utils.utils.schrodinger_eqn_ivp_order1(s, y, channel, interaction, args=())

Convert the radial Schrödinger equation to a first-order system.

Return type:

list[complex]

Parameters:

• s (float)

• y (Sequence[complex] | ndarray[tuple[Any, ...], dtype[float64]] | ndarray[tuple[Any, ...], dtype[complex128]])

• channel (Any)

• interaction (Callable[[...], complex])

• args (tuple[Any, ...])

jitr.utils.utils.smatrix(Rl, a, l, eta, asym=<class 'jitr.utils.free_solutions.CoulombAsymptotics'>)

Compute an S-matrix element from a channel R-matrix value.

Return type:

complex

Parameters:

• Rl (complex)

• a (float)

• l (int)

• eta (float)

• asym (type)

jitr.utils.utils.delta(Sl)

Return the phase shift and attenuation in degrees.

Return type:

tuple[double, double]

Parameters:

Sl (complex)

jitr.utils.utils.eval_scaled_interaction(s, interaction, ch, args)

Evaluate a local interaction in dimensionless coordinates.

Return type:

complex

Parameters:

• s (float)

• interaction (Callable[[...], complex])

• ch (Any)

• args (tuple[Any, ...])

jitr.utils.utils.eval_scaled_nonlocal_interaction(s, sp, interaction, ch, args)

Evaluate a nonlocal interaction in dimensionless coordinates.

Return type:

complex

Parameters:

• s (float)

• sp (float)

• interaction (Callable[[...], complex])

• ch (Any)

• args (tuple[Any, ...])

jitr.utils.utils.interaction_range(A, rA=1.2, r0=0.0)

Estimate an interaction radius in femtometers.

Return type:

float

Parameters:

• A (int)

• rA (float)

• r0 (float)

jitr.utils.utils.suggested_dimensionless_channel_radius(interaction_range, k)

Suggest a dimensionless channel radius for a given interaction range.

The estimate leaves roughly one asymptotic wavelength beyond the interaction region.

Return type:

float

Parameters:

• interaction_range (float)

• k (float)

jitr.utils.utils.suggested_basis_size(a, zeros_per_node=5)

Suggest an R-matrix basis size for a dimensionless channel radius.

Return type:

int

Parameters:

• a (float)

• zeros_per_node (int)

Mass-table accessors and simple derived nuclear-mass observables.

jitr.utils.mass.init_mass_db()

Load the packaged mass tables into memory if needed.

Return type:

None

jitr.utils.mass.mass_db_row(A, Z)

Return the matching mass-table row for a nuclide.

Return type:

DataFrame

Parameters:

• A (int)

• Z (int)

jitr.utils.mass.mass_models()

Return the list of available mass models.

Return type:

list[str]

jitr.utils.mass.mass_excess(A, Z, model='ame2020')

Return the mass excess and uncertainty in MeV.

The uncertainty is None when the mass table does not include an uncertainty for the requested model, or when the nuclide is not found.

Return type:

tuple[float, float | None]

Parameters:

• A (int)

• Z (int)

• model (str)

jitr.utils.mass.mass(A, Z, **kwargs)

Return the nuclear mass and uncertainty in MeV/c^2.

Return type:

tuple[float, float | None]

Parameters:

• A (int)

• Z (int)

• kwargs (str)

jitr.utils.mass.binding_energy(A, Z, **kwargs)

Return the total binding energy and uncertainty in MeV.

Return type:

tuple[float, float | None]

Parameters:

• A (int)

• Z (int)

• kwargs (str)

jitr.utils.mass.neutron_separation_energy(A, Z, **kwargs)

Return the one-neutron separation energy and uncertainty in MeV.

Return type:

tuple[float, float | None]

Parameters:

• A (int)

• Z (int)

• kwargs (str)

jitr.utils.mass.proton_separation_energy(A, Z, **kwargs)

Return the one-proton separation energy and uncertainty in MeV.

Return type:

tuple[float, float | None]

Parameters:

• A (int)

• Z (int)

• kwargs (str)

jitr.utils.mass.neutron_fermi_energy(A, Z, **kwargs)

Return the neutron Fermi-energy estimate and uncertainty in MeV.

Return type:

tuple[float, float | None]

Parameters:

• A (int)

• Z (int)

• kwargs (str)

jitr.utils.mass.proton_fermi_energy(A, Z, **kwargs)

Return the proton Fermi-energy estimate and uncertainty in MeV.

Return type:

tuple[float, float | None]

Parameters:

• A (int)

• Z (int)

• kwargs (str)

Evaluate low-order polynomials and their derivatives.

jitr.utils.poly.poly1d(x, coeffs, start_i=0)

Evaluate a one-dimensional polynomial in ascending-power form.

Parameters:

• x (float | TypeAliasType) – Evaluation point or points.

• coeffs (TypeAliasType) – Polynomial coefficients where coeffs[i] multiplies x ** (start_i + i).

• start_i (int) – Lowest polynomial power represented by coeffs.

Return type:

ndarray[tuple[Any, ...], dtype[double]] | double

Returns:

Polynomial values evaluated at x.

jitr.utils.poly.poly2d(x, y, coeffs, start_i=0, start_j=0)

Evaluate a two-dimensional polynomial in ascending-power form.

Parameters:

• x (float | TypeAliasType) – First evaluation coordinate or coordinates.

• y (float | TypeAliasType) – Second evaluation coordinate or coordinates.

• coeffs (TypeAliasType) – Coefficient matrix where coeffs[i, j] multiplies x ** (start_i + i) * y ** (start_j + j).

• start_i (int) – Lowest power represented along the x axis.

• start_j (int) – Lowest power represented along the y axis.

Return type:

ndarray[tuple[Any, ...], dtype[double]] | double

Returns:

Polynomial values evaluated on the paired x and y inputs.

jitr.utils.poly.poly1d_deriv(coeffs, start_i=0)

Differentiate a one-dimensional ascending-power polynomial.

Parameters:

• coeffs (TypeAliasType) – Polynomial coefficients where coeffs[i] multiplies x ** (start_i + i).

• start_i (int) – Lowest polynomial power represented by coeffs.

Return type:

tuple[ndarray[tuple[Any, ...], dtype[double]], int]

Returns:

Tuple of derivative coefficients and the new lowest represented power.

jitr.utils.poly.poly2d_deriv(coeffs, start_i=0, start_j=0, wrt='y')

Differentiate a two-dimensional ascending-power polynomial.

Parameters:

• coeffs (TypeAliasType) – Coefficient matrix where coeffs[i, j] multiplies x ** (start_i + i) * y ** (start_j + j).

• start_i (int) – Lowest power represented along the x axis.

• start_j (int) – Lowest power represented along the y axis.

• wrt (str) – Coordinate to differentiate with respect to, either "x" or "y".

Return type:

tuple[ndarray[tuple[Any, ...], dtype[double]], int, int]

Returns:

Tuple of derivative coefficients and the new start_i/start_j values suitable for passing back into poly2d().

Raises:

ValueError – If wrt is not "x" or "y".