Folding package

The folding page documents the finite-range folding helpers and JLM/JLMB parameterizations. The reusable analytic/tabulated density helpers live in jitr.utils.density and are documented on the core API page.

Quadrature and folding helpers

ILDA quadrature and folding helpers.

class jitr.folding.folding.ILDAFolder(r_max=20.0, n_quad=200)[source]

Bases: object

Quadrature helper for ILDA Coulomb and Gaussian folding.

The folder owns a Gauss-Legendre grid on [0, r_max] and exposes interpolation, integration, Coulomb, and Gaussian-folding helpers on that grid.

Variables:

  • r_q – Quadrature nodes on [0, r_max] in fm.

  • w_q – Quadrature weights on [0, r_max] in fm.

Parameters:
e2 = 1.4399645472428273
interp_to_quad(r_grid, f_grid)[source]

Interpolate tabulated data onto the quadrature grid.

Parameters:

  • r_grid (TypeAliasType) – Source radial grid in fm.

  • f_grid (TypeAliasType) – Tabulated values sampled on r_grid.

Return type:

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

Returns:

Values interpolated onto self.r_q.

integrate(f_q)[source]

Integrate a quantity sampled on the quadrature grid.

Parameters:

f_q (TypeAliasType) – Function values sampled on self.r_q.

Return type:

float

Returns:

Approximation to ∫_0^{r_max} f(r) dr.

differentiate(f_q)[source]

Differentiate a quantity sampled on the quadrature grid.

Uses the Lagrange–Gauss-Legendre differentiation matrix (Baye 2015). Exact for polynomials of degree ≤ n_quad − 1; requires no grid-uniformity assumption.

The off-diagonal elements are derived from the Lagrange-Legendre barycentric weights λ̃_j = √(r_j (r_max − r_j) w_j):

D_{ij} = (−1)^(i+j) λ̃_j / (λ̃_i (r_i − r_j)) i ≠ j

The diagonal is set by the row-sum condition ∑_j D_{ij} = 0, which holds because d/dr [∑_j l_j(r)] = 0 for any Lagrange basis.

Parameters:

f_q (TypeAliasType) – Function values sampled on self.r_q.

Return type:

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

Returns:

Derivative df/dr sampled on self.r_q.

Z_from_density(rho_q)[source]

Compute the particle number implied by a spherical density.

Parameters:

rho_q (TypeAliasType) – Density values sampled on self.r_q.

Return type:

float

Returns:

Value of 4π ∫ r² ρ(r) dr.

rms_radius(rho_q)[source]

Compute the RMS radius of a spherical density.

Parameters:

rho_q (TypeAliasType) – Density values sampled on self.r_q.

Return type:

float

Returns:

Root-mean-square radius in fm.

Raises:

ValueError – If the density integrates to a non-positive norm.

V_coulomb(rho_p_q, mode='density', R_C=None, include_exchange=False, r_out=None)[source]

Compute the Coulomb potential for a proton density.

Parameters:

  • rho_p_q (float | ndarray[tuple[Any, ...], dtype[double]]) – Proton density sampled on self.r_q.

  • mode (str) – Coulomb model, either "density" or "uniform_sphere".

  • R_C (str | float | None) – Coulomb radius for the uniform-sphere mode, or "auto" to infer it from the RMS radius.

  • include_exchange (bool) – Whether to add the Slater exchange correction.

  • r_out (float | ndarray[tuple[Any, ...], dtype[double]] | None) – Optional output grid in fm. Defaults to self.r_q.

Return type:

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

Returns:

Coulomb potential values in MeV sampled on r_out.

Raises:

ValueError – If mode is not recognized.

gaussian_fold(U_q, t, r_out=None)[source]

Fold a radial quantity with a three-dimensional Gaussian.

Parameters:
Return type:

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

Returns:

Folded values sampled on r_out.

Raises:

ValueError – If t is non-positive.

JLM parameterization

JLM and JLMB local-density optical-potential helpers.

class jitr.folding.jlm.JLMParameterization(name, coeffs_A, coeffs_B, coeffs_C, coeffs_D, coeffs_F, coeffs_E_F, low_energy_E_F_offset=None, low_energy_E_F_coeffs=None, E_F_blend_energy=9.0, E_F_blend_width=2.0, D_damping=600.0, F_damping=1.0, local_jlm_real_mode='linearized_delta_c')[source]

Bases: object

Bundled coefficient and low-energy choices for JLM/JLMB helpers.

Variables:

  • name – Human-readable identifier.

  • coeffs_A – Real isoscalar coefficient table.

  • coeffs_B – Real isovector coefficient table.

  • coeffs_C – Momentum-dependent mass coefficient table.

  • coeffs_D – Imaginary isoscalar coefficient table.

  • coeffs_F – Imaginary isovector coefficient table.

  • coeffs_E_F – High-energy Fermi-energy coefficients.

  • low_energy_E_F_offset – Constant term for the low-energy Fermi branch.

  • low_energy_E_F_coeffs – Density coefficients for the low-energy branch.

  • E_F_blend_energy – Logistic blend center in MeV.

  • E_F_blend_width – Logistic blend width in MeV.

  • D_damping – Imaginary isoscalar damping parameter in MeV².

  • F_damping – Imaginary isovector damping parameter in MeV.

  • local_jlm_real_mode – Real-part Coulomb treatment for potential_JLM().

Parameters:
name: str
coeffs_A: ndarray[tuple[Any, ...], dtype[float64]]
coeffs_B: ndarray[tuple[Any, ...], dtype[float64]]
coeffs_C: ndarray[tuple[Any, ...], dtype[float64]]
coeffs_D: ndarray[tuple[Any, ...], dtype[float64]]
coeffs_F: ndarray[tuple[Any, ...], dtype[float64]]
coeffs_E_F: ndarray[tuple[Any, ...], dtype[float64]]
low_energy_E_F_offset: float | None = None
low_energy_E_F_coeffs: ndarray[tuple[Any, ...], dtype[float64]] | None = None
E_F_blend_energy: float = 9.0
E_F_blend_width: float = 2.0
D_damping: float = 600.0
F_damping: float = 1.0
local_jlm_real_mode: Literal['linearized_delta_c', 'shifted'] = 'linearized_delta_c'
jitr.folding.jlm.resolve_parameterization(parameterization)[source]

Resolve a named or explicit JLM parameterization bundle.

Return type:

JLMParameterization | None

Parameters:

parameterization (str | JLMParameterization | None)

jitr.folding.jlm.fermi_energy_MeV(rho_fm3, coeffs=array([-510.8, 3222., -6250.]), projectile_energy_MeV=None, low_energy_offset=None, low_energy_coeffs=None, blend_energy=9.0, blend_width=2.0)[source]

Return the local Fermi energy in MeV.

Parameters:
Return type:

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

Returns:

Fermi energy evaluated at rho_fm3.

jitr.folding.jlm.V0(rho_fm3, E_MeV, coeffs=array([[-9.740e+02, 1.126e+01, -4.250e-02], [7.097e+03, -1.257e+02, 5.853e-01], [-1.953e+04, 4.180e+02, -2.054e+00]]))[source]

Return the real isoscalar JLM self-energy component.

Parameters:
Return type:

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

Returns:

Real isoscalar self-energy values in MeV.

jitr.folding.jlm.W0(rho_fm3, E_MeV, E_F, coeffs=array([[-1.483e+03, 3.718e+01, -3.549e-01, 1.119e-03], [2.988e+04, -9.318e+02, 9.591e+00, -3.160e-02], [-2.128e+05, 7.209e+03, -7.752e+01, 2.611e-01], [5.125e+05, -1.796e+04, 1.980e+02, -6.753e-01]]), damping=600.0, damping_eps=1e-12)[source]

Return the imaginary isoscalar JLM self-energy component.

Parameters:
Return type:

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

Returns:

Imaginary isoscalar self-energy values in MeV.

jitr.folding.jlm.m_tilde_over_m(rho_fm3, E_MeV, coeffs=array([[4.557e+00, -5.291e-03, 6.108e-06], [-2.051e+00, -4.906e-01, 1.812e-03], [-6.509e+01, 3.095e+00, -1.190e-02]]))[source]

Return the JLM momentum-dependent mass ratio.

Parameters:
Return type:

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

Returns:

Values of m̃ / m.

jitr.folding.jlm.eff_mass(rho_fm3, E_MeV, coeffs=array([[-9.740e+02, 1.126e+01, -4.250e-02], [7.097e+03, -1.257e+02, 5.853e-01], [-1.953e+04, 4.180e+02, -2.054e+00]]))[source]

Return the JLM effective-mass ratio.

Parameters:
Return type:

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

Returns:

Values of m* / m.

jitr.folding.jlm.E_mass(rho_fm3, E_MeV, coeffs_A=array([[-9.740e+02, 1.126e+01, -4.250e-02], [7.097e+03, -1.257e+02, 5.853e-01], [-1.953e+04, 4.180e+02, -2.054e+00]]), coeffs_C=array([[4.557e+00, -5.291e-03, 6.108e-06], [-2.051e+00, -4.906e-01, 1.812e-03], [-6.509e+01, 3.095e+00, -1.190e-02]]))[source]

Return the JLM energy-dependent mass ratio.

Parameters:
Return type:

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

Returns:

Values of m̄ / m obtained from m* / m = (m̃ / m) (m̄ / m).

jitr.folding.jlm.V1(rho_fm3, E_MeV, E_F, coeffs_B=array([[3.601e+02, -5.224e+00, 2.051e-02], [-2.691e+03, 5.130e+01, -2.470e-01], [7.733e+03, -1.717e+02, 8.846e-01]]), coeffs_C=array([[4.557e+00, -5.291e-03, 6.108e-06], [-2.051e+00, -4.906e-01, 1.812e-03], [-6.509e+01, 3.095e+00, -1.190e-02]]))[source]

Return the real isovector JLM self-energy component.

Parameters:
Return type:

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

Returns:

Real isovector self-energy values in MeV.

jitr.folding.jlm.W1(rho_fm3, E_MeV, E_F, coeffs_F=array([[5.461e+02, -1.120e+01, 1.065e-01, -3.541e-04], [-8.471e+03, 2.300e+02, -2.439e+00, 8.544e-03], [5.172e+04, -1.520e+03, 1.717e+01, -6.211e-02], [-1.140e+05, 3.543e+03, -4.169e+01, 1.537e-01]]), coeffs_A=array([[-9.740e+02, 1.126e+01, -4.250e-02], [7.097e+03, -1.257e+02, 5.853e-01], [-1.953e+04, 4.180e+02, -2.054e+00]]), coeffs_C=array([[4.557e+00, -5.291e-03, 6.108e-06], [-2.051e+00, -4.906e-01, 1.812e-03], [-6.509e+01, 3.095e+00, -1.190e-02]]), damping=1.0, damping_eps=1e-12)[source]

Return the imaginary isovector JLM self-energy component.

Parameters:
Return type:

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

Returns:

Imaginary isovector self-energy values in MeV.

jitr.folding.jlm.Delta_C(rho_fm3, E_MeV, V_C_MeV, coeffs_A=array([[-9.740e+02, 1.126e+01, -4.250e-02], [7.097e+03, -1.257e+02, 5.853e-01], [-1.953e+04, 4.180e+02, -2.054e+00]]), linear=True)[source]

Return the real Coulomb correction for protons.

Parameters:
Return type:

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

Returns:

Coulomb correction values in MeV.

jitr.folding.jlm.potential_JLM(rgrid, rho_grid, projectile, target, E, V_C=None, parameterization=None, coeffs_A=array([[-9.740e+02, 1.126e+01, -4.250e-02], [7.097e+03, -1.257e+02, 5.853e-01], [-1.953e+04, 4.180e+02, -2.054e+00]]), coeffs_B=array([[3.601e+02, -5.224e+00, 2.051e-02], [-2.691e+03, 5.130e+01, -2.470e-01], [7.733e+03, -1.717e+02, 8.846e-01]]), coeffs_C=array([[4.557e+00, -5.291e-03, 6.108e-06], [-2.051e+00, -4.906e-01, 1.812e-03], [-6.509e+01, 3.095e+00, -1.190e-02]]), coeffs_D=array([[-1.483e+03, 3.718e+01, -3.549e-01, 1.119e-03], [2.988e+04, -9.318e+02, 9.591e+00, -3.160e-02], [-2.128e+05, 7.209e+03, -7.752e+01, 2.611e-01], [5.125e+05, -1.796e+04, 1.980e+02, -6.753e-01]]), D_damping=600.0, coeffs_F=array([[5.461e+02, -1.120e+01, 1.065e-01, -3.541e-04], [-8.471e+03, 2.300e+02, -2.439e+00, 8.544e-03], [5.172e+04, -1.520e+03, 1.717e+01, -6.211e-02], [-1.140e+05, 3.543e+03, -4.169e+01, 1.537e-01]]), F_damping=1.0, coeffs_E_F=array([-510.8, 3222., -6250.]), r_out=None)[source]

Evaluate the local-density JLM optical potential.

Parameters:
Return type:

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

Returns:

Tuple of real and imaginary optical-potential arrays in MeV.

Raises:

ValueError – If projectile is not neutron or proton, or if V_C is missing or malformed for proton calls.

jitr.folding.jlm.lambda_v0(E_MeV)[source]

Return the JLMB real-isoscalar normalization factor.

Parameters:

E_MeV (float | ndarray[tuple[Any, ...], dtype[double]]) – Projectile energy in MeV.

Return type:

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

Returns:

Real isoscalar normalization values.

jitr.folding.jlm.lambda_w0(E_MeV, mode=0)[source]

Return the JLMB imaginary-isoscalar normalization factor.

Parameters:

  • E_MeV (float | ndarray[tuple[Any, ...], dtype[double]]) – Projectile energy in MeV.

  • mode (int) – TALYS jlmmode selector (0–3). Mode 3 doubles the result relative to mode 2 to improve low-energy (E < 1 MeV) accuracy. Modes 0, 1, 2 do not affect λW; see lambda_w1() for those.

Return type:

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

Returns:

Imaginary isoscalar normalization values.

jitr.folding.jlm.lambda_v1(E_MeV)[source]

Return the JLMB real-isovector normalization factor.

Parameters:

E_MeV (float | ndarray[tuple[Any, ...], dtype[double]]) – Projectile energy in MeV.

Return type:

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

Returns:

Real isovector normalization values.

jitr.folding.jlm.lambda_w1(E_MeV, mode=0)[source]

Return the JLMB imaginary-isovector normalization factor.

The mode parameter selects the TALYS jlmmode prescription for the alam amplitude in the sigmoid correction to the 1.1 base value. Coefficients taken from talys/source/mom.f90 (authoritative; the TALYS manual has typographical errors for modes 1 and 2).

Parameters:

  • E_MeV (float | ndarray[tuple[Any, ...], dtype[double]]) – Projectile energy in MeV.

  • mode (int) –

    TALYS jlmmode selector:

    • 0 (default): alam = 0.44 (Eq. 11.47 standard)

    • 1: alam = 1.10 * exp(-0.4 * E**0.25)

    • 2: alam = 1.375 * exp(-0.2 * sqrt(E))

    • 3: same alam as mode 2 (λW doubled via lambda_w0())

Return type:

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

Returns:

Imaginary isovector normalization values.

jitr.folding.jlm.lambda_vso(E_MeV)[source]

Return the JLMB real spin-orbit normalization depth.

From talys/source/mom.f90: lvso = 40 + exp(-E*0.013)*130.

Parameters:

E_MeV (float | ndarray[tuple[Any, ...], dtype[double]]) – Projectile energy in MeV.

Return type:

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

Returns:

Real spin-orbit depth in MeV.

jitr.folding.jlm.lambda_wso(E_MeV)[source]

Return the JLMB imaginary spin-orbit normalization depth.

From talys/source/mom.f90: lwso = -0.2*(E - 20). Zero at E = 20 MeV.

Parameters:

E_MeV (float | ndarray[tuple[Any, ...], dtype[double]]) – Projectile energy in MeV.

Return type:

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

Returns:

Imaginary spin-orbit depth in MeV.

jitr.folding.jlm.spin_orbit_jlmb(r_q, rho_n_q, rho_p_q, projectile, r_out=None)[source]

Return the JLMB spin-orbit form factor F(r) = -½ (1/r) dρ_SO/dr.

Uses the Scheerbaum prescription (Nucl. Phys. A257, 77, 1976): the effective spin-orbit density up-weights the minority species:

  • neutron projectile: ρ_SO = (2ρ_p + ρ_n) / 3

  • proton projectile: ρ_SO = (2ρ_n + ρ_p) / 3

The derivative dρ_SO/dr is evaluated via CubicSpline fitted to the density values at r_q. The leading factor of −½ matches the TALYS/ECIS type-5 spin-orbit convention (Scheerbaum form stored with opposite sign and halved, confirmed numerically against ECIS output for n + ¹²⁰Sn at 10 MeV).

The full complex spin-orbit potential is assembled by the caller as:

V_SO(r) = (lambda_vso(E) + 1j * lambda_wso(E)) * spin_orbit_jlmb(...)

and passed to workspace.xs(spin_orbit_potential=...). jitr applies the L·S eigenvalue (l/2 for j=l+½, −(l+1)/2 for j=l−½) internally.

Parameters:
Return type:

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

Returns:

Form factor F(r) sampled on r_out, in fm⁻⁴.

jitr.folding.jlm.potential_JLMB(folder, rho_n_q, rho_p_q, projectile, target, E, V_C=None, parameterization=None, coeffs_A=array([[-9.740e+02, 1.126e+01, -4.250e-02], [7.097e+03, -1.257e+02, 5.853e-01], [-1.953e+04, 4.180e+02, -2.054e+00]]), coeffs_B=array([[3.601e+02, -5.224e+00, 2.051e-02], [-2.691e+03, 5.130e+01, -2.470e-01], [7.733e+03, -1.717e+02, 8.846e-01]]), coeffs_C=array([[4.557e+00, -5.291e-03, 6.108e-06], [-2.051e+00, -4.906e-01, 1.812e-03], [-6.509e+01, 3.095e+00, -1.190e-02]]), coeffs_D=array([[-1.483e+03, 3.718e+01, -3.549e-01, 1.119e-03], [2.988e+04, -9.318e+02, 9.591e+00, -3.160e-02], [-2.128e+05, 7.209e+03, -7.752e+01, 2.611e-01], [5.125e+05, -1.796e+04, 1.980e+02, -6.753e-01]]), coeffs_F=array([[5.461e+02, -1.120e+01, 1.065e-01, -3.541e-04], [-8.471e+03, 2.300e+02, -2.439e+00, 8.544e-03], [5.172e+04, -1.520e+03, 1.717e+01, -6.211e-02], [-1.140e+05, 3.543e+03, -4.169e+01, 1.537e-01]]), coeffs_E_F=array([-510.8, 3222., -6250.]), D_damping=600.0, F_damping=1.0, lambda_V=1, lambda_W=1, lambda_V1=1, lambda_W1=1, t_r=1.25, t_i=1.35, r_out=None)[source]

Evaluate the finite-range JLMB optical potential.

Parameters:
Return type:

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

Returns:

Tuple of folded real and imaginary optical-potential arrays in MeV.

Raises:

ValueError – If projectile is not neutron or proton, or if V_C is missing or malformed for proton calls.