jesterTOV.utils module

jesterTOV.utils module#

Utility functions for unit conversions, physical constants, and numerical methods.

Utility functions for neutron star physics calculations.

This module provides essential utility functions for equation of state interpolation, unit conversions, numerical integration, and auxiliary calculations needed for TOV equation solving.

Units: The module defines conversion factors between different unit systems commonly used in neutron star physics.

calculate_rest_mass_density(e, p)[source]#

Compute rest-mass density from energy density and pressure.

This function solves the first law of thermodynamics to obtain the rest-mass density (baryon density) from the energy density and pressure. The relation is given by:

\[\frac{d\rho}{d\varepsilon} = \frac{\rho}{p + \varepsilon}\]

where \(\rho\) is the rest-mass density, \(\varepsilon\) is the energy density, and \(p\) is the pressure.

Parameters:

  • e (Float[Array, "n"]) – Energy density array [geometric units].

  • p (Float[Array, "n"]) – Pressure array [geometric units].

Returns:

Array – Rest-mass density array [geometric units].

Note

This function uses diffrax for ODE integration and may have compatibility issues with some diffrax versions. The initial condition assumes \(\rho(\varepsilon_0) = \varepsilon_0\).

cubic_root_for_proton_fraction(coefficients)[source]#

Vectorized version of cubic_root_for_proton_fraction. Takes similar arguments as cubic_root_for_proton_fraction but with additional array axes over which cubic_root_for_proton_fraction is mapped.

Original documentation:

Solve cubic equation for proton fraction in beta-equilibrium.

This function solves the cubic equation that arises from the beta-equilibrium condition in neutron star matter:

\[ax^3 + bx^2 + cx + d = 0\]

where the coefficients are related to the symmetry energy and electron chemical potential. Uses Cardano’s formula for exact analytical solution.

Args:

coefficients (Array): Cubic polynomial coefficients [a, b, c, d].

Returns:

Array: Three roots of the cubic equation (may be complex).

Note:

This function is vectorized to handle multiple coefficient sets simultaneously for different densities.

cubic_spline(xq, xp, fp)[source]#

Cubic spline interpolation using interpax.

This function creates a cubic spline interpolator through the given data points and evaluates it at the query points. Cubic splines provide smooth interpolation with continuous first and second derivatives.

Parameters:

  • xq (Float[Array, "n"]) – Query points for evaluation.

  • xp (Float[Array, "n"]) – Known x-coordinates of data points.

  • fp (Float[Array, "n"]) – Known y-coordinates, i.e., fp = f(xp).

Returns:

Array – Interpolated values at query points xq.

Note

Uses the interpax library for JAX-compatible spline interpolation. See: f0uriest/interpax

cumtrapz(y, x)[source]#

Cumulatively integrate y(x) using the composite trapezoidal rule.

This function performs cumulative integration using the trapezoidal rule, which is essential for computing thermodynamic quantities like enthalpy and chemical potential from EOS data.

The trapezoidal rule approximates:

\[\int_{x_0}^{x_i} y(x) dx \approx \sum_{j=1}^{i} \frac{\Delta x_j}{2}(y_{j-1} + y_j)\]
Parameters:

  • y (Array) – Values to integrate.

  • x (Array) – The coordinate to integrate along.

Returns:

Array – The result of cumulative integration of y along x.

Note

The result array has the same length as the input, with the first element set to a small value (1e-30) to avoid logarithm issues.

interp_in_logspace(x, xs, ys)[source]#

Perform logarithmic interpolation.

This function performs interpolation in logarithmic space, which is more appropriate for quantities that span many orders of magnitude (like pressure and density in neutron stars).

The interpolation is performed as:

\[\log y(x) = \text{interp}(\log x, \log x_s, \log y_s)\]
Parameters:

  • x (float) – Point at which to evaluate the interpolation.

  • xs (Array) – Known x-coordinates (must be positive).

  • ys (Array) – Known y-coordinates (must be positive).

Returns:

float – Interpolated value at x.

Note

All input values must be positive since logarithms are taken.

limit_by_MTOV(pc, m, r, l)[source]#

Truncate neutron star family at maximum TOV mass.

This function limits the mass-radius relation to the stable branch by truncating at the maximum TOV mass (MTOV). Points beyond MTOV correspond to unstable configurations and are replaced with duplicates of the MTOV values to maintain array shape for JIT compilation.

The maximum mass occurs when:

\[\frac{dM}{dp_c} = 0\]
Parameters:

  • pc (Array) – Central pressure array.

  • m (Array) – Gravitational mass array.

  • r (Array) – Radius array.

  • l (Array) – Tidal deformability array.

Return type:

tuple[Array, Array, Array, Array]

Returns:

tuple –

Truncated arrays (pc, m, r, l) where unstable configurations

are replaced with MTOV values.

Note

This approach maintains static array shapes required for JAX JIT compilation while effectively removing unstable configurations.

sigmoid(x)[source]#

Sigmoid activation function.

Computes the sigmoid function:

\[\sigma(x) = \frac{1}{1 + e^{-x}}\]
Parameters:

x (Array) – Input values.

Return type:

Array

Returns:

Array – Sigmoid function values in range (0, 1).

Physical Constants#

The module provides physical constants in geometric units where \(G = c = 1\):

  • Nuclear saturation density: \(n_{\text{sat}} = 0.16 \text{ fm}^{-3}\)

  • Solar mass: \(M_{\odot} = 1.477 \text{ km}\)

  • Conversion factors between CGS and geometric units

Numerical Methods#

Key numerical utilities include:

  • Cubic spline interpolation: For smooth interpolation between data points

  • Cumulative trapezoidal integration: For integrating differential equations

  • Unit conversions: Between different unit systems used in neutron star physics

Contents