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.

Tabulated densities ship with the package as one compressed .npz file per density model under data/densities/ (e.g. d1m.npz, bskg3.npz). Each file stores the proton and neutron densities of every nuclide on a uniform radial grid as float32 (the source tables carry 5-6 significant digits). The original 11-column ASCII .rad tables can be converted with scripts/convert_density_tables.py (see read_rad_file() and write_density_npz()).

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

Bases: object

Tabulated proton and neutron densities for a single nuclide.

Parameters:
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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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')[source]

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)[source]

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()[source]

Return the list of available density models.

Return type:

list[str]

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

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)[source]

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()[source]

Load the packaged density tables into memory if needed.

Return type:

None

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

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')[source]

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')[source]

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.read_rad_file(path, model)[source]

Parse all nuclide blocks from an ASCII .rad density table.

This is the conversion-time reader for the original tables; the runtime loader reads the packaged .npz files instead. Each block starts with a header line Z A n_points dr followed by n_points rows of 11 columns, of which column 0 (radius), column 1 (proton density) and column 6 (neutron density) are used. The file stem must be the element symbol for Z.

Parameters:

  • path (Path) – Path to the .rad file.

  • model (str) – Density-model identifier for the parsed tables.

Return type:

list[DensityTable]

Returns:

Parsed density-table records from path.

Raises:

ValueError – If the file contents are malformed.

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

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.

jitr.utils.density.write_density_npz(tables, path)[source]

Pack density tables into a compressed .npz file.

The radial grid is not stored: every table must be tabulated on a uniform grid np.arange(n_points) * dr (checked here), so it is rebuilt on load. Densities are stored as float32; nuclides may have different n_points.

Layout (format_version = DENSITY_NPZ_FORMAT_VERSION):

Z, A, n_points : int16   (N,)
dr             : float64 (N,)
offsets        : int64   (N + 1,)   cumulative n_points, starting at 0
rho_p, rho_n   : float32 (M,)       densities of nuclide i are
                                    rho[offsets[i]:offsets[i + 1]]
Parameters:
Raises:

ValueError – If a table is not on a uniform radial grid or if two tables share the same (A, Z).

Return type:

None

Free-particle and Coulomb asymptotic solutions.

jitr.utils.free_solutions.Gamow_factor(l, eta)[source]

Return the Coulomb Gamow factor for angular momentum l.

Return type:

float

Parameters:
class jitr.utils.free_solutions.CoulombHankelTable(Hp, Hm, Hpp, Hmp)[source]

Bases: NamedTuple

Coulomb-Hankel functions H± = G ± iF and derivatives for l = 0..lmax.

Parameters:
Hp: ndarray[tuple[Any, ...], dtype[complex128]]

Alias for field number 0

Hm: ndarray[tuple[Any, ...], dtype[complex128]]

Alias for field number 1

Hpp: ndarray[tuple[Any, ...], dtype[complex128]]

Alias for field number 2

Hmp: ndarray[tuple[Any, ...], dtype[complex128]]

Alias for field number 3

jitr.utils.free_solutions.coulomb_hankel_table(rho, eta, lmax, wronskian_tol=1e-08)[source]

Return H+, H-, H+' and H-' at rho for l = 0..lmax.

For eta == 0 the functions are Riccati-Bessel functions from scipy; otherwise F and G come from the three-term recurrence anchored on two mpmath evaluations. The derivatives follow from the exact recurrence. Every l is verified against the Wronskian F' G - F G' = 1; any l failing wronskian_tol is recomputed with mpmath directly.

Return type:

CoulombHankelTable

Parameters:
jitr.utils.free_solutions.H_plus(s, l, eta)[source]

Return the outgoing Coulomb-Hankel function G + iF at s.

Return type:

complex

Parameters:
jitr.utils.free_solutions.H_minus(s, l, eta)[source]

Return the incoming Coulomb-Hankel function G - iF at s.

Return type:

complex

Parameters:
jitr.utils.free_solutions.H_plus_prime(s, l, eta)[source]

Return the derivative of the outgoing Coulomb-Hankel function at s.

Return type:

complex

Parameters:
jitr.utils.free_solutions.H_minus_prime(s, l, eta)[source]

Return the derivative of the incoming Coulomb-Hankel function at s.

Return type:

complex

Parameters:

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

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

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
jitr.utils.kinematics.semi_relativistic_kinematics(mass_target, mass_projectile, Elab, Zz=0)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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

Return type:

cdouble

Parameters:

matrix (ndarray)

jitr.utils.utils.block(matrix, block_index, block_size)[source]

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=())[source]

Evaluate the scaled radial Schrödinger operator.

Return type:

complex

Parameters:
jitr.utils.utils.schrodinger_eqn_ivp_order1(s, y, channel, interaction, args=())[source]

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

Return type:

list[complex]

Parameters:
jitr.utils.utils.smatrix(Rl, a, l, eta)[source]

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

Return type:

complex

Parameters:
jitr.utils.utils.delta(Sl)[source]

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)[source]

Evaluate a local interaction in dimensionless coordinates.

Return type:

complex

Parameters:
jitr.utils.utils.eval_scaled_nonlocal_interaction(s, sp, interaction, ch, args)[source]

Evaluate a nonlocal interaction in dimensionless coordinates.

Return type:

complex

Parameters:
jitr.utils.utils.interaction_range(A, rA=1.2, r0=0.0)[source]

Estimate an interaction radius in femtometers.

Return type:

float

Parameters:
jitr.utils.utils.suggested_dimensionless_channel_radius(interaction_range, k)[source]

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:
jitr.utils.utils.suggested_basis_size(a, zeros_per_node=5)[source]

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

Return type:

int

Parameters:

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

jitr.utils.mass.init_mass_db()[source]

Load the packaged mass tables into memory if needed.

Return type:

None

jitr.utils.mass.mass_db_row(A, Z)[source]

Return the matching mass-table row for a nuclide.

Return type:

DataFrame

Parameters:
jitr.utils.mass.mass_models()[source]

Return the list of available mass models.

Return type:

list[str]

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

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:
jitr.utils.mass.mass(A, Z, **kwargs)[source]

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

Return type:

tuple[float, float | None]

Parameters:
jitr.utils.mass.binding_energy(A, Z, **kwargs)[source]

Return the total binding energy and uncertainty in MeV.

Return type:

tuple[float, float | None]

Parameters:
jitr.utils.mass.neutron_separation_energy(A, Z, **kwargs)[source]

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

Return type:

tuple[float, float | None]

Parameters:
jitr.utils.mass.proton_separation_energy(A, Z, **kwargs)[source]

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

Return type:

tuple[float, float | None]

Parameters:
jitr.utils.mass.neutron_fermi_energy(A, Z, **kwargs)[source]

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

Return type:

tuple[float, float | None]

Parameters:
jitr.utils.mass.proton_fermi_energy(A, Z, **kwargs)[source]

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

Return type:

tuple[float, float | None]

Parameters:

Evaluate low-order polynomials and their derivatives.

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

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)[source]

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)[source]

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')[source]

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".