jesterTOV.eos.crust.Crust

class Crust(name, min_density=None, max_density=None, filter_zero_pressure=True)

Bases: object

Neutron star crust equation of state data handler.

This class provides validated loading, preprocessing, and access to crust EOS data with automatic zero-pressure filtering and density range masking. It eliminates code duplication across EOS models by centralizing all crust preprocessing logic.

The crust data files contain tabulated values of number density \(n\), pressure \(p\), and energy density \(\varepsilon\) for the low-density outer and inner crust regions of neutron stars.

Parameters:

• name (str) – Name of the crust model to load (e.g., ‘BPS’, ‘DH’, ‘SLy’) or a filename with .npz extension for custom files.

• min_density (float, optional) – Minimum density cutoff [\(\mathrm{fm}^{-3}\)]. Points with density below this value are excluded. Default is None (no minimum cutoff).

• max_density (float, optional) – Maximum density cutoff [\(\mathrm{fm}^{-3}\)]. Points with density above this value are excluded. Default is None (no maximum cutoff).

• filter_zero_pressure (bool, optional) – If True, remove points with zero or negative pressure to avoid numerical issues in logarithmic calculations. Default is True.

Raises:

ValueError – If the specified crust model is not found in the crust directory.

Variables:

• n (Float[Array, "n_points"]) – Number densities [\(\mathrm{fm}^{-3}\)] after filtering and masking

• p (Float[Array, "n_points"]) – Pressures [\(\mathrm{MeV} \, \mathrm{fm}^{-3}\)] after filtering and masking

• e (Float[Array, "n_points"]) – Energy densities [\(\mathrm{MeV} \, \mathrm{fm}^{-3}\)] after filtering and masking

• mu_lowest (Float) – Chemical potential at lowest density point: \((\varepsilon_0 + p_0) / n_0\)

• cs2 (Float[Array, "n_points"]) – Speed of sound squared \(c_s^2 = dp/d\varepsilon\)

• max_density (Float) – Maximum density in filtered crust [\(\mathrm{fm}^{-3}\)]

• min_density (Float) – Minimum density in filtered crust [\(\mathrm{fm}^{-3}\)]

Examples

Load a crust model with default settings:

>>> from jesterTOV.eos.crust import Crust
>>> crust = Crust("DH")
>>> print(f"Loaded {len(crust)} crust points")
>>> n, p, e = crust.get_data()

Load with density range masking:

>>> crust = Crust("DH", min_density=0.001, max_density=0.1)
>>> print(f"Density range: {crust.min_density:.4f} - {crust.max_density:.4f} fm^-3")

Check available crusts before loading:

>>> available = Crust.list_available()
>>> if Crust.validate("BPS"):
...     crust = Crust("BPS")

Access derived quantities:

>>> crust = Crust("DH")
>>> print(f"Chemical potential: {crust.mu_lowest:.2f} MeV")
>>> print(f"Sound speed squared: {crust.cs2[0]:.4f}")

See also

SpectralDecomposition_EOS_model

Spectral EOS using crust stitching

MetaModel_EOS_model

Meta-model EOS using crust stitching

Notes

Available built-in crust models can be found in the crust_files directory (accessible via the CRUST_DIR constant or the get_crust_dir() class method). The class automatically handles:

• Zero-pressure point filtering (avoids log(0) in calculations)

• Density range masking (for crust-core matching)

• Monotonicity validation

__init__(name, min_density=None, max_density=None, filter_zero_pressure=True)

Initialize and load crust EOS data with optional preprocessing.

The initialization process: 1. Validates crust existence 2. Loads raw data from .npz file 3. Applies zero-pressure filtering (if enabled) 4. Applies density range masking (if specified) 5. Validates data quality (monotonicity, positivity) 6. Stores filtered arrays for property access

Parameters:

• name (str) – Crust model name or path to .npz file

• min_density (float, optional) – Minimum density cutoff [\(\\mathrm{fm}^{-3}\)]

• max_density (float, optional) – Maximum density cutoff [\(\\mathrm{fm}^{-3}\)]

• filter_zero_pressure (bool, optional) – Remove zero/negative pressure points (default: True)

Methods

__init__(name[, min_density, max_density, ...])	Initialize and load crust EOS data with optional preprocessing.
get_crust_dir()	Return the path to the crust data directory.
get_data()	Return (n, p, e) tuple for convenient unpacking.
list_available()	List all available crust model names.
validate(name)	Check if a crust model exists without loading it.

Attributes

cs2	Speed of sound squared \(c_s^2 = dp/d\varepsilon\).
e	Energy density [\(\mathrm{MeV} \, \mathrm{fm}^{-3}\)] after filtering and masking.
max_density	Maximum density in filtered crust [\(\mathrm{fm}^{-3}\)].
min_density	Minimum density in filtered crust [\(\mathrm{fm}^{-3}\)].
mu_lowest	Chemical potential at the lowest density point.
n	Number density [\(\mathrm{fm}^{-3}\)] after filtering and masking.
p	Pressure [\(\mathrm{MeV} \, \mathrm{fm}^{-3}\)] after filtering and masking.

property cs2: Float[Array, 'n_points']

Speed of sound squared \(c_s^2 = dp/d\varepsilon\).

Computed using numerical differentiation via gradient.

Returns:

Float[Array, “n_points”] – Array of sound speed squared values (dimensionless)

Examples

>>> crust = Crust("DH")
>>> cs2 = crust.cs2
>>> print(f"Sound speed range: {cs2.min():.4f} - {cs2.max():.4f}")

Notes

The speed of sound should satisfy \(0 < c_s^2 \leq 1\) (in units where \(c = 1\)) for physical crust models.

property e: Float[Array, 'n_points']

Energy density [\(\mathrm{MeV} \, \mathrm{fm}^{-3}\)] after filtering and masking.

Returns:

Float[Array, “n_points”] – Array of energy densities

classmethod get_crust_dir()

Return the path to the crust data directory.

Return type:

str

Returns:

str – Absolute path to the crust directory

Examples

>>> crust_dir = Crust.get_crust_dir()
>>> print(f"Crust data stored in: {crust_dir}")

get_data()

Return (n, p, e) tuple for convenient unpacking.

This method provides a convenient way to get all three arrays at once, useful for code patterns that expect tuple unpacking.

Return type:

tuple[Float[Array, 'n_points'], Float[Array, 'n_points'], Float[Array, 'n_points']]

Returns:

tuple[Float[Array, “n_points”], Float[Array, “n_points”], Float[Array, “n_points”]] – Tuple of (number density, pressure, energy density) arrays

Examples

>>> crust = Crust("DH")
>>> n, p, e = crust.get_data()
>>> assert jnp.array_equal(n, crust.n)

classmethod list_available()

List all available crust model names.

Return type:

list[str]

Returns:

list[str] – List of available crust model names (without .npz extension)

Examples

>>> available = Crust.list_available()
>>> print(f"Available crusts: {', '.join(available)}")
Available crusts: BPS, DH, SLy

property max_density: Float

Maximum density in filtered crust [\(\mathrm{fm}^{-3}\)].

Returns:

Float – Maximum number density value

property min_density: Float

Minimum density in filtered crust [\(\mathrm{fm}^{-3}\)].

Returns:

Float – Minimum number density value

property mu_lowest: Float

Chemical potential at the lowest density point.

Computed as \(\mu_0 = (\varepsilon_0 + p_0) / n_0\) where subscript 0 denotes the first (lowest density) point in the crust. This value is used as the starting point for integrating thermodynamic quantities in the meta-model EOS construction.

Returns:

Float – Chemical potential [\(\mathrm{MeV}\)]

Examples

>>> crust = Crust("DH")
>>> mu = crust.mu_lowest
>>> print(f"Lowest chemical potential: {mu:.2f} MeV")

property n: Float[Array, 'n_points']

Number density [\(\mathrm{fm}^{-3}\)] after filtering and masking.

Returns:

Float[Array, “n_points”] – Array of number densities

property p: Float[Array, 'n_points']

Pressure [\(\mathrm{MeV} \, \mathrm{fm}^{-3}\)] after filtering and masking.

Returns:

Float[Array, “n_points”] – Array of pressures

classmethod validate(name)

Check if a crust model exists without loading it.

This is useful for validation before instantiation, allowing fail-fast behavior in configuration parsing or user input validation.

Parameters:

name (str) – Crust model name to validate

Return type:

bool

Returns:

bool – True if crust exists, False otherwise

Examples

>>> if Crust.validate("DH"):
...     crust = Crust("DH")
>>> else:
...     print("Crust not found")