EOSManager API Reference

class RIFT.physics.EOSManager.EOSBranchView(source, branch_id)

Bases: object

A selected stable-family branch with the historical scalar EOS surface.

This wrapper is deliberately small: attributes not related to the stellar family are delegated to the source EOS, while all mass-radius-tidal queries are pinned to branch_id. It is the compatibility bridge for callers such as CIP and hyperpipe that cannot pass a branch keyword on every lookup.

A branch is bounded at BOTH ends: a twin-star branch typically starts well above the family minimum mass, so mMinMsun is published next to mMaxMsun and consumers that mask draws should mask against both.

LAMBDA_OUT_OF_BRANCH = -inf: lambda_from_m value for a mass with no stable star on this branch. Legacy consumers mask only on mMaxMsun, so masses below mMinMsun still reach us; returning the same flag lalsimutils uses for its own failed conversions keeps one such draw from aborting an entire batch. It is a flag, not a tidal deformability: the consumer must reject the row, which is why CIP filters nonfinite converted coordinates ahead of the likelihood fit and drops such samples on export.

branches_for_m(m)

estimate_baryon_mass_from_mg(m): Estimate baryonic mass using this branch’s 1.4-Msun radius.

lambda_from_m(m)

lambda_from_m_vector(m)

radius_from_m(m)

test_speed_of_sound_causal(test_only_under_mmax=True, fast_test=True): Test causality only up to this branch’s maximum-mass star.

class RIFT.physics.EOSManager.EOSConcrete(name=None)

Bases: object

Class characterizing a specific EOS solution. This structure SHOULD

auto-build the mass-radius via a TOV solve

provides ability to query the lambda(m) relationship and (in the future) higher-order multipole moments; etc

As many of these features are already provided by lalsimulation, we just front-end them

branches_for_m(m): Return stable LAL family branches available at mass m.

estimate_baryon_mass_from_mg(m, branch_id=None)

Estimate m_b = m_g + m_g^2/(R_{1.4}/km) based on https://arxiv.org/pdf/1905.03784.pdf Eq. (6) Note baryon mass can be computed exactly with a TOV solution integral (e.g., Eq. 6.21 of Haensel’s book)

N_b = 4pi (1+z_{surf}) int_0^R e^{Phi} (rho + P/c^2)/m_b sqrt(1-2 G m(r)/r c^2)

but lalsuite doesn’t provide access to this low-level info !! This function is only for use when LALEOS is created. Use RePrimAnd’s baryon_mass_from_mg preferably for most other purposes!!

for_branch(branch_id)

Return a legacy-scalar view restricted to one stable LAL branch.

Existing RIFT consumers call lambda_from_m(m) without a branch keyword. The view preserves that API while making the branch choice explicit at construction time.

lambda_from_m(m, branch_id=None)

lambda_from_m_vector(m, branch_id=None)

pressure_density_on_grid(logrho_grid, reference_pair=None, enforce_causal=False)

pressure_density_on_grid. Input and output grid units are in SI (rho: kg/m^3; p = N/m^2) POTENTIAL PROBLEMS OF USING LALSUITE

lalinference_o2 / master: Unless patched, the rest mass density is not reliable. To test with the unpatched LI version, use reference_pair to specify a low-density EOS. This matching is highly suboptimal, so preferably test either (a) a patched code or (b) the alternative code below

pressure_density_on_grid_alternate(logrho_grid, enforce_causal=False): pressure_density_on_grid. Input and output grid units are in SI (rho: kg/m^3; p = N/m^2) Pressure provided by lalsuite (=EOM integration) Density computed by m*n = (epsilon+p)/c^2mn exp(-h), which does NOT rely on lalsuite implementation

radius_from_m(m, branch_id=None): Return radius in metres; require branch_id for twin stars.

test_speed_of_sound_causal(test_only_under_mmax=True, fast_test=True, branch_id=None)

Test if EOS satisfies speed of sound. Relies on low-level lalsimulation interpolation routines to get v(h) and as such is not very reliable

By DEFAULT, we are testing the part of the EOS that is

at the largest pressure (assuming monotonic sound speed)
associated with the maximum mass NS that is stable

We can also test the full table that is provided to us. https://git.ligo.org/lscsoft/lalsuite/blob/lalinference_o2/lalinference/src/LALInference.c#L2513

test_speed_of_sound_causal_builtin()

class RIFT.physics.EOSManager.EOSFromDataFile(name=None, fname=None)

Bases: EOSConcrete

FromDataFileEquationOfState (just accepts filename…not attempting to parse a catalog)

eos_ls(): EOS tables described by Ozel here and downloadable here. LALSim utilizes this tables, but needs some interfacing (i.e. conversion to SI units, and conversion from non monotonic to monotonic pressure density tables)

interp_eos_nb_of_p()

interp_eos_p_of_rho()

interp_eos_rho_of_p()

p_rho_arrays()

class RIFT.physics.EOSManager.EOSFromTabularData(name=None, eos_data=None, eos_units=None, reject_phase_transitions=False, debug=False, add_low_density=False, skip_family=False)

Bases: EOSConcrete

Input:

Tabular data (baryon_density = n , pressure = p, energy density = rho)
method for primitives: this information is partially redundant, in that ln n_b/n_ref = int c^2 [d rho] / (P(rho) + rho c^2), etc
Need some specific choice for inter-edge interpolation (and redundance resolution)
Low-density approximation (if desired) for filling down to surface density.
WARNING: Will generally match imperfectly, need some resolution to that procedure

Creates

LALSimulation data structure as desired

Warning:

Currently generates intermediate data file by writing to disk

class RIFT.physics.EOSManager.EOSLALSimulation(name): Bases: EOSConcrete

class RIFT.physics.EOSManager.EOSLALSimulationFromFile(fname, name=None, dirty_phase_transitions=False, skip_family=False, minimal_family=True, phase_transition_aware=False, family_log_pressure_min=None)

Bases: EOSConcrete

Load a released two-column or reviewed nine-column LAL EOS table.

The reviewed LALSimulation reader detects clean phase transitions in both formats and preserves all thermodynamic columns in the new format. Set dirty_phase_transitions to request its opt-in correction of numerically imperfect pressure plateaus.

class RIFT.physics.EOSManager.EOSLindblomSpectral(name=None, spec_params=None, verbose=False, use_lal_spec_eos=False, check_cs=False, check_cs_builtin=True, no_eos_fam=False)

Bases: EOSConcrete

make_spec_param_eos(npts=500, plot=False, verbose=False, save_dat=False, ligo_units=False, interpolate=False, eosname_lalsuite='SLY4')

Load values from table of spectral parameterization values Table values taken from https://arxiv.org/pdf/1009.0738.pdf Comments:

eos_vals is recorded as pressure,density pairs, because the spectral representation is for energy density vs pressure

units swap between geometric and CGS

eosname_lalsuite is used for the low-density EOS

test_bounded_adiabatic_index(bounds=[0.6, 4.5]): Gamma(p) in bounds Uses xmax and other parameters from spectral result

class RIFT.physics.EOSManager.EOSLindblomSpectralSoundSpeedVersusPressure(name=None, spec_params=None, verbose=False, use_lal_spec_eos=True, no_eos_fam=False)

Bases: EOSConcrete

Based on https://journals.aps.org/prd/abstract/10.1103/PhysRevD.105.063031 <-> https://arxiv.org/pdf/2202.12285.pdf

EOS spectral representation of sound speed versus pressure, as expansion of Upsilon(p): see Eq. (11). Uses function call to lalsuite to implement low-level interface

make_spec_param_eos(xvar='energy_density', yvar='pressure', npts=500, plot=False, verbose=False, save_dat=False, ligo_units=False, interpolate=False, eosname_lalsuite='SLY4')

Load values from table of spectral parameterization values from separate calculations. Comments:

eos_vals is recorded as pressure,density pairs, because the spectral representation is for energy density vs pressure

units swap between geometric and CGS

eosname_lalsuite is used for the low-density EOS

class RIFT.physics.EOSManager.EOSPiecewisePolytrope(name, param_dict=None): Bases: EOSConcrete

class RIFT.physics.EOSManager.EOSReprimand(name=None, param_dict=None, lalsim_eos=None, load_eos=None, specific_internal_energy=True, m_b_units=1.672621923684145e-27, RePrimAnd_scale=1e-06)

Bases: EOSConcrete

Pass param_dict as the dictionary of ‘pseudo_enthalpy’,’rest_mass_density’,’energy_density’,’pressure’,’sound_speed_over_c’ for being resolved into a TOV sequence. CGS Units only except sound_speed_over_c. Instead you can send a lalsim_eos which processes lalsim eos object type and produces a TOV sequence. load_eos takes a 2D array with pressure, energy_density and rest_mass_density (not tested).

baryon_mass_from_mg(mg)

lambda_from_m(mg)

update(param_dict, specific_internal_energy, RePrimAnd_scale=1e-06)

class RIFT.physics.EOSManager.EOSSequenceBranchView(source, branch_id)

Bases: EOSBranchView

EOSBranchView for one stable branch of an NMB sequence EOS.

Mass-radius-tidal queries are pinned to branch_id; mMinMsun and mMaxMsun (and mMaxMsun_all) are that branch’s mass bounds and number_of_branches is 1. branches_for_m still reports the source’s branch id. lambda_from_m interpolates inside the branch, returns 1e-8 above it, and raises ValueError below it.

R_from_m(m_Msun)

lambda_from_m(m)

RIFT.physics.EOSManager.EOSSequenceFromFile(fname=None, **kwargs)

Open an EOS sequence file, auto-detecting the format.

Dispatches on the HDF5 representation / schema_version attribute:

pca_hc (nmbackend.pca) -> EOSSequencePCA (compressed);
tabular (nmbackend.nss) -> EOSSequenceNMB (tabular);
anything else -> EOSSequenceLandry (legacy/LCEHL).

All expose the identical consumer API (oned_order_values, lambda_of_m_indx, R_of_m_indx, m_max_of_indx, lookup_closest), so callers can pass any of the three file types transparently.

class RIFT.physics.EOSManager.EOSSequenceLandry(name=None, fname=None, load_eos=False, load_ns=False, oned_order_name=None, oned_order_mass=None, no_sort=True, verbose=False, eos_tables_units=None)

Bases: object

Class characterizing a sequence of specific EOS solutions, using the Landry format. Assumes user provides (a) EOS realization, (b) precomputed results from TOV solve; and (c) discrete ID

PENDING

mMax access

R_of_m_indx(m_Msun, indx)

R(m) evaluated for a single m_Msun value (almost always), for a specific indexed EOS

Generally we assume the value is UNIQUE and associated with a single stable phase; should FIX?

extract_one_eos_object(indx=None, name_eos=None, fail_if=None, **kwargs): Extract EOS using either the EOS index or the EOS name. Requires the EOS is available

interpolate_eos_tables(interp_base: str, n_points: int = 1000, verbose: bool = None)

Interpolates all EOS tables to the same grid. User can choose the base for interpolation, and the number of points on the output grid. User must load the EOS tables when initializing EOSSequenceLandry class. (EOSSequenceLandry(load_eos=True))

Parameters

interp_basestr: The column name to be used as a base for interpolation. Should be one of ‘pressure’, ‘energy_density, ‘baryon_density’, if units are GGS or SI! If no unit conversion applied (EOSSequenceLandry(eos_tables_units=None)), should be one of ‘pressurec2’, ‘energy_densityc2’, ‘baryon_density’.
n_pointsint: The number of points on the output grid. Default is 1000.
verbosebool: If True, prints the progress of the interpolation. Default is self.verbose. (verbose from the class initialization)

Returns

eos_tables_interpdict: A dictionary with the same keys as self.eos_tables, but with the values being the interpolated tables.

Raises

ValueError: If the EOS tables are not loaded.
KeyError: If the interp_base is not one of the allowed column names.

Developer Notes

This is a simple interpolation, and can be extended to thermodynamical interpolation in the future.
The interpolation is done in log-space, so the output grid is logarithmically spaced.
The interpolation base is returned as the uniformly spaced grid in log-scale. Can be extended to interpolate the base grid as well in the future.
The interpolated columns remain in their original limits. Might need to add extrapolation in the future.
Visualization of the progress using tqdm can be added in the future.

lambda_of_m_indx(m_Msun, indx)

lambda(m) evaluated for a single m_Msun value (almost always), for a specific indexed EOS

Generally we assume the value is UNIQUE and associated with a single stable phase

lookup_closest(order_val): Given a proposed ordering statistic value, provides the index of the closest value. Assumes scalar input Does not require ordering

m_max_of_indx(indx)

class RIFT.physics.EOSManager.EOSSequenceNMB(name=None, fname=None, load_eos=False, load_ns=True, oned_order_name=None, oned_order_mass=None, no_sort=True, verbose=False, eos_tables_units=None)

Bases: EOSSequenceLandry

Drop-in reader for the NuclearMatter-Backend NSSequence HDF5 format.

The NSSequence file stores every quantity as a function of central pseudo-enthalpy h_c (monotone along the sequence), with an explicit stable flag, in a single (n_eos, n_pts, n_fields) dataset (see docs/rift-sequence-audit.md in NuclearMatter-Backend). This subclass reads that file, extracts the stable rising branch (M increasing up to M_max) for each EOS into the same in-memory eos_ns_tov dict of {M,R,Lambda} structured arrays that EOSSequenceLandry uses – so all inherited accessors (lambda_of_m_indx, R_of_m_indx, m_max_of_indx, lookup_closest, oned_order_values) work unchanged and are branch-safe by construction.

Only load_ns is honoured (TOV sequence); the optional microphysical EOS tables are not read here (use the legacy emitter / EOSSequenceLandry for those).

R_of_m_indx(m_Msun, indx, branch_id=None): R(m) in the file’s units (km) for EOS indx.

branches_at_m_indx(m_Msun, indx): Ids of the stable branches whose closed [Mmin, Mmax] contains m_Msun.

branches_of_indx(indx): List of {M, R, Lambda} records, one per stable branch.

lambda_of_m_indx(m_Msun, indx, branch_id=None): Lambda(m) for EOS indx; see the branch-aware accessor notes.

m_max_of_indx(indx, branch='primary', branch_id=None)

Maximum stable mass of EOS indx.

branch is "primary" (v1 default), "all" (largest mass on any stable branch), or an integer branch id; branch_id is an alias for branch.

m_min_of_indx(indx, branch='primary', branch_id=None): Minimum stored stable mass of EOS indx (branch as in m_max_of_indx).

n_branches_of_indx(indx): Number of stable branches of EOS indx.

class RIFT.physics.EOSManager.EOSSequencePCA(name=None, fname=None, load_eos=False, load_ns=True, oned_order_name=None, oned_order_mass=None, no_sort=True, verbose=False, eos_tables_units=None)

Bases: EOSSequenceNMB

Reader for the compressed NuclearMatter-Backend pca_hc/1 representation.

The file stores a per-channel PCA decomposition of the M(u), R(u), logLambda(u) curves (mean + basis components + per-EOS coeffs). We reconstruct each EOS’s curves, take the stable rising branch, and populate the same in-memory eos_ns_tov dict EOSSequenceLandry/EOSSequenceNMB use – so every inherited accessor works unchanged. Self-contained (numpy only); no nmbackend dependency.

Branch ids are representation-specific. The file carries no stability flag, so a point counts as stable when M rises (diff(M) > 0). Reconstruction wiggles therefore split curves into extra short branches (17 branches of at most 6 points in the paper-1 prior archive), so the branch count and ids of an EOS can differ from its nss original. A wiggle can also end the primary branch early (0.81 vs 1.59 Msun for some EOS); this primary-branch behaviour is the v1 reader’s and is unchanged.

class RIFT.physics.EOSManager.EOSSequenceSingleIndex(fname=None, index=0, name=None, sequence=None)

Bases: object

A SINGLE EOS realization drawn from a sequence file, exposed with the fixed-EOS (--using-eos) interface: lambda_from_m(m_Msun).

This enables the exact per-EOS-evidence pattern (one full CIP evidence per realization, MARG-style) for tabular/compressed sequence files – the reference computation against which the ordering-statistic (tabular hyperpipeline) approximation is validated.

Branch surface (NMB sequences only), mirroring EOSConcrete: branches_for_m, for_branch, and a branch_id keyword on lambda_from_m, lambda_from_m_vector, radius_from_m and R_from_m. branch_id=None keeps the v1 primary-branch projection (it never raises for twin-star masses); mMaxMsun is the primary-branch maximum and mMaxMsun_all the maximum over every stable branch.

R_from_m(m_Msun, branch_id=None): Radius in the file’s units (km); NaN outside an explicit branch.

branch_maximum_mass_msun(branch_id)

branch_minimum_mass_msun(branch_id)

branches_for_m(m): Return stable branch ids whose closed mass interval contains m.

for_branch(branch_id)

Return a legacy-scalar view restricted to one stable branch.

"primary" selects branch 0.

lambda_from_m(m, branch_id=None)

Dimensionless Lambda(m); m in Msun or SI kg.

branch_id=None (or "primary"): v1 primary branch, 1e-8 above 0.999 * mMaxMsun. Integer branch_id: interpolate inside that branch, 1e-8 above 0.999 * mMaxMsun_all, ValueError otherwise.

lambda_from_m_vector(m, branch_id=None)

radius_from_m(m, branch_id=None)

Return radius in metres.

branch_id=None uses the primary-branch projection (as R_from_m); an explicit branch raises ValueError outside that branch.

RIFT.physics.EOSManager.LookupCrustEpsilonAtPressure(p_ref, eosname_lalsuite='SLY4')

Tool for spectral EOS manager to find epsilon(p) via lookup tables from the lalsuite data files. Units are CGS Uses linear interpolation in the log.

Warning: lalsuite files use lal units (epsilon, p in 1/m^2), but we will presume p and epsilon are in energy density

class RIFT.physics.EOSManager.QueryLS_EOS(eos)

Bases: object

ExtractorFromEOS: Class to repeatedly query a single lalsuite EOS object, using a common interface (e.g., to extract array outputs by name, unit conversions, etc)

convert(var, var_name=None)

extract_param(p, pseudo_enthalpy)

RIFT.physics.EOSManager.check_monotonic(monotonic_params, other_params=None, preserve_same_length=False): Checks monotonicity of monotonic_params and removes non-monotonic parts in it for both monotonic_params and other_params. By default this will reduce the length of data due to deletion of non-monotonic patches, but preserve_same_length can be turned true to keep length of data intact.

RIFT.physics.EOSManager.check_sound_speed_causal(param_dict, preserve_same_length=False): Checks if sound speed exceeds 1 anywhere, and depending on the option preserve_same_length removes that region or forces it =1.

RIFT.physics.EOSManager.eos_monotonic_parts_and_causal_sound_speed(param_dict, preserve_same_length=False): rest_mass_density , energy_density, pressure, pseudo_enthalpy, and sound_speed_over_c are the dictionary parameters that this function expects.

RIFT.physics.EOSManager.epsilon(x, p0, eps0, coeffs, use_ode=True): Eq. 7 from https://arxiv.org/pdf/1009.0738.pdf

RIFT.physics.EOSManager.gamma_of_x(x, coeffs): Eq 6 from https://arxiv.org/pdf/1009.0738.pdf

RIFT.physics.EOSManager.just_check_monotonicity_and_causality(param_dict): To be used for only checking monotonicity and causality True means good. False means violation.

RIFT.physics.EOSManager.make_compactness_from_lambda_approximate(lambda_vals)

Eq (B1) from https://arxiv.org/pdf/1812.04803.pdf, based on Maselli et al 2013, Yagi and Yunes 2017

Note this will yield extreme compactnesses for poorly-constrained GW observations, as the ‘lambda’ inferred will be wildly large/prior-dominated

RIFT.physics.EOSManager.make_mr_lambda(eos, use_lal=False): construct mass-radius curve from EOS DOES NOT YET WORK RELIABLY

RIFT.physics.EOSManager.make_mr_lambda_lal(eos, n_bins=100, branch_id=None, multipart=None, family_adapter=None, reviewed_multibranch=None)

Construct mass-radius curve from EOS Based on modern code resources (https://git.ligo.org/publications/gw170817/bns-eos/blob/master/scripts/eos-params.py) which access low-level structures

branch_id is optional for released/single-branch LALSimulation. It is required for a multibranch family so an overlapping twin-star interval is never collapsed silently.

RIFT.physics.EOSManager.make_mr_lambda_lal_branches(eos, n_bins=100, multipart=None, family_adapter=None, reviewed_multibranch=None): Return {branch_id: [M, R, Lambda]} for every stable LAL branch.

RIFT.physics.EOSManager.make_mr_lambda_reprimand(eos, n_bins=800, save_tov_sequence=False, read_tov_sequence=False, return_eos_object=False, m_b_units=1.672621923684145e-27, RePrimAnd_scale=1e-06): Construct mass-radius curve from EOS using RePrimAnd (https://wokast.github.io/RePrimAnd/tov_solver.html). Parameter eos should be in RePrimAnd’s eos object format, made with something like make_eos_barotr_spline (https://wokast.github.io/RePrimAnd/eos_barotr_ref.html). By default this returns the Mass_g-Radius-Lambda-Mass_b. But if return_eos_object is True, this will also return the RePrimAnd EOS object. Wolfgang Kastaun, Jay Vijay Kalinani, and Riccardo Ciolfi. Robust recovery of primitive variables in relativistic ideal magnetohydrodynamics. Phys. Rev. D, 103(2):023018, 2021. doi:10.1103/PhysRevD.103.023018. Roland Haas and Wolfgang Kastaun. (2023). wokast/RePrimAnd: Release 1.6 (v1.6). Zenodo. https://doi.org/10.5281/zenodo.7700296

RIFT.physics.EOSManager.mu(x, coeffs): Eq 8 from https://arxiv.org/pdf/1009.0738.pdf