Reference

Loading and Saving EOS

eos_barotr EOS_Toolkit::load_eos_barotr(std::string fname, const units &u = units::geom_solar())

Load barotropic EOS from hdf5 file.

Parameters

  • fname – Filename of EOS file

  • Unit – system the returned EOS should use. The unit system needs to be geometric, i.e. \( G=c=1 \). Default is to fix the mass unit to \( 1 M_\odot \).

Returns

Generic interface to the EOS

void EOS_Toolkit::save_eos_barotr(std::string fname, eos_barotr eos, std::string info = "")

Save barotropic EOS to hdf5 file.

Parameters

  • fname – Filename of EOS file

  • eos – EOS object to save

  • info – Free-form description text (optional)

Creating EOS from sampled data

To create a EOS based on spline interpolation from given sample points, there are three options. Depending on whether the pseudo-enthalpy and/or specific energy are known accurately, one should use one of the following.

auto EOS_Toolkit::make_eos_barotr_spline(const std::vector<real_t> &gm1, const std::vector<real_t> &rho, const std::vector<real_t> &eps, const std::vector<real_t> &press, const std::vector<real_t> &csnd, const std::vector<real_t> &temp, const std::vector<real_t> &efrac, bool isentropic, interval<real_t> rg_rho, real_t n_poly, units u = units::geom_solar(), std::size_t pts_per_mag = 200) -> eos_barotr

Create barotropic EOS based on splines.

This EOS type internally uses regularly-spaced cardinal cubic splines. The regular spacing implies that the evaluation cost is independent from the table resolution. Most quantities are interpolated with respect to logarithmic pseudo-enthalpy. In addition there is an interpolation spline that computes logarithmic pseudo-enthalpy from logarithmic density, which is used when the EOS is evaluated based on density. The soundspeed is interpolated as function of logarithmic density.

The samples used for creating the EOS need to provide both pseudo-enthalpy and density, but may be arbitrarily spaced. They are resampled to the required spacing using monotonic spline interpolation.

The range of the internal interpolation spline of the EOS has to be specified. It can span less than the range of the provided points. Below the interpolation range, the EOS will use a matching generalised polytropic EOS with the specified adiabatic index. The density range that needs to be covered by the interpolation range naturally depends on the application. It might therefore make sense to not use the full density range provided by the original EOS source.

One can specify whether the EOS is isentropic. If the temperature is zero, the EOS must be specified as isentropic or an exception is thrown. Note that physically, the pseudo-enthalpy is already determined by pressure, density, and specific energy. For isentropic EOS, energy density follows from density and pressure. The consistency of the provided samples is not checked and in the responsibility of the user. There are however similar functions which computes the pseudo-enthalpy itself using numerical integration, or both pseudo enthalpy and specific energy (only possible for isentropic case).

The parameters are w.r.t EOS units, which have to be provided as a parameter and will be stored with the EOS for bookkeeping.

Parameters

  • gm1 – Samples for pseudo enthalpy \( g-1 \). Must be strictly increasing.

  • rho – Samples for mass density \( \rho \). Must be strictly increasing and strictly positive.

  • eps – Samples for specific energy \( \epsilon \). Must be strictly increasing and obey \( \epsilon > -1 \)

  • press – Samples for pressure \( P \ge 0 \).

  • csnd – Samples for soundspeed. Must obey \( 0 \le c_s < 1 \)

  • temp – Samples for temperature or empty vector (equivalent to all-zero). Must obey \( T\ge 0 \).

  • efrac – Electron fraction or empty vector (in which case the EOS will not provide electron fraction).

  • isentropic – Whether the EOS is isentropic, e.g. for degenerate matter.

  • rg_rho – Range of \( \rho \) where EOS is computed from sample points. Below, a polytrope is used. Range must be within the provided sample points.

  • n_poly – Polytropic index used to extent EOS to zero density.

  • u – Unit system (w.r.t. SI) of the EOS

  • pts_per_mag – Sample points per magnitude to be used internally for EOS splines

Returns

Generic interface employing tabulated barotropic EOS


auto EOS_Toolkit::make_eos_barotr_spline(const std::vector<real_t> &rho, const std::vector<real_t> &eps, const std::vector<real_t> &press, const std::vector<real_t> &csnd, const std::vector<real_t> &temp, const std::vector<real_t> &efrac, bool isentropic, interval<real_t> rg_rho, real_t n_poly, units u = units::geom_solar(), std::size_t pts_per_mag = 200) -> eos_barotr

Create barotropic EOS based on splines.

This EOS type internally uses regularly-spaced cardinal cubic splines. The regular spacing implies that the evaluation cost is independent from the table resolution. Most quantities are interpolated with respect to logarithmic pseudo-enthalpy. In addition there is an interpolation spline that computes logarithmic pseudo-enthalpy from logarithmic density, which is used when the EOS is evaluated based on density. The soundspeed is interpolated as function of logarithmic density.

The sample points provided for creating the EOS do not have to be regularly spaced. They are resampled to the required spacing using (arbitrary spaced) monotonic spline interpolation.

The samples are provided with respect to density. The pseudo-enthalpy does not have to be provided, but is computed using numerical integration via the trapezoidal rule. If sample points of density are further apart than the specified minimum points per magnitude, additional sample points are inserted via cubic monotonic spline interpolation before the numerical integration. This ensures that the final EOS is a consistent representation of a cubic monotonic spline interpolation of the sample points with respect to density.

Note there is a similar function where the pseudo-enthalpy is provided as samples as well. This should be used if it is know accurately, e.g for EOS based on analytic expressions. Another function specially for isentropic EOS recomputes the specific energy as well as the pseudo enthalpy.

The range of the internal interpolation spline of the final EOS has to be specified. It can span less than the range of the provided points. Below the interpolation range, the EOS will use a matching generalised polytropic EOS with the specified adiabatic index. The density range that needs to be covered by the interpolation range naturally depends on the application. It might therefore make sense to not use the full density range provided by the original EOS source.

One can specify whether the EOS is isentropic. If the temperature is zero, the EOS must be specified as isentropic or an exception is thrown. Note that physically, energy density follows from density and pressure for the case of isentropic EOS. The consistency of the provided samples is not checked and in the responsibility of the user.

The parameters are w.r.t EOS units, which have to be provided as a parameter and will be stored with the EOS for bookkeeping.

Parameters

  • rho – Samples for mass density \( \rho \). Must be strictly increasing and strictly positive.

  • eps – Samples for specific energy \( \epsilon \). Must be strictly increasing and obey \( \epsilon > -1 \)

  • press – Samples for pressure \( P \ge 0 \).

  • csnd – Samples for soundspeed. Must obey \( 0 \le c_s < 1 \)

  • temp – Samples for temperature or empty vector (equivalent to all-zero). Must obey \( T\ge 0 \).

  • efrac – Electron fraction or empty vector (in which case the EOS will not provide electron fraction).

  • isentropic – Whether the EOS is isentropic, e.g. for degenerate matter.

  • rg_rho – Range of \( \rho \) where EOS is computed from sample points. Below, a polytrope is used. Range must be within the provided sample points.

  • n_poly – Polytropic index used to extent EOS to zero density.

  • u – Unit system (w.r.t. SI) of the EOS

  • pts_per_mag – Sample points per magnitude to be used internally for EOS splines

Returns

Generic interface employing tabulated barotropic EOS


auto EOS_Toolkit::make_eos_barotr_spline(const std::vector<real_t> &rho, const std::vector<real_t> &press, const std::vector<real_t> &csnd, const std::vector<real_t> &temp, const std::vector<real_t> &efrac, interval<real_t> rg_rho, real_t n_poly, real_t eps0, units u = units::geom_solar(), std::size_t pts_per_mag = 200) -> eos_barotr

Create barotropic EOS based on splines.

This EOS type internally uses regularly-spaced cardinal cubic splines. The regular spacing implies that the evaluation cost is independent from the table resolution. Most quantities are interpolated with respect to logarithmic pseudo-enthalpy. In addition there is an interpolation spline that computes logarithmic pseudo-enthalpy from logarithmic density, which is used when the EOS is evaluated based on density. The soundspeed is interpolated as function of logarithmic density.

The sample points provided for creating the EOS do not have to be regularly spaced. They are resampled to the required spacing using (arbitrary spaced) monotonic spline interpolation.

The samples are provided with respect to density. The pseudo-enthalpy does not have to be provided, but is computed using numerical integration via the trapezoidal rule. It is assumed that the EOS is isentropic. The specific energy is recomputed from the pressure and density samples under this assumption. If sample points of density are further apart than the specified minimum points per magnitude, additional sample points are inserted via cubic monotonic spline interpolation before the numerical integrations of pseudo-enthalpy and specific energy. This ensures that the final EOS is a consistent representation of a cubic monotonic spline interpolation of the sample points with respect to density.

Note there are similar functions where specific energy or specific energy and pseudo-enthalpy are provided as samples as well. This should be used if they are know accurately, e.g, for EOS based on analytic expressions.

The range of the internal interpolation spline of the final EOS has to be specified. It can span less than the range of the provided points. Below the interpolation range, the EOS will use a matching generalised polytropic EOS with the specified adiabatic index. The density range that needs to be covered by the interpolation range naturally depends on the application. It might therefore make sense to not use the full density range provided by the original EOS source.

If a temperature is given, its consistency with the assumption of isentropy cannot be checked and is in the responsability of the user.

The parameters are w.r.t EOS units, which have to be provided as a parameter and will be stored with the EOS for bookkeeping.

Parameters

  • rho – Samples for mass density \( \rho \). Must be strictly increasing and strictly positive.

  • press – Samples for pressure \( P \ge 0 \).

  • csnd – Samples for soundspeed. Must obey \( 0 \le c_s < 1 \)

  • temp – Samples for temperature or empty vector (equivalent to all-zero). Must obey \( T\ge 0 \).

  • efrac – Electron fraction or empty vector (in which case the EOS will not provide electron fraction).

  • rg_rho – Range of \( \rho \) where EOS is computed from sample points. Below, a polytrope is used. Range must be within the provided sample points.

  • n_poly – Polytropic index used to extent EOS to zero density.

  • eps0 – Specific energy at zero density

  • u – Unit system (w.r.t. SI) of the EOS

  • pts_per_mag – Sample points per magnitude to be used internally for EOS splines

Returns

Generic interface employing tabulated barotropic EOS


It is also possible to sample an existing EOS:

auto EOS_Toolkit::make_eos_barotr_spline(const eos_barotr &eos, interval<real_t> rg_rho, real_t n_poly, std::size_t pts_per_mag = 200) -> eos_barotr

Create barotropic EOS based on splines.

This allows to represent existing EOS objects of any type as a spline EOS by sampling them it.

Parameters

  • eos – The EOS to be sampled

  • rg_rho – The density range that should be represented by interpolating splines

  • n_poly – Polytropic index used to extent EOS to zero density.

  • pts_per_mag – Sample points per magnitude to be used internally for EOS splines

Returns

Generic interface employing tabulated barotropic EOS


Creating Polytropic EOS

eos_barotr EOS_Toolkit::make_eos_barotr_poly(real_t n, real_t rmd_p, real_t rho_max, units units_ = units::geom_solar())

Create a polytropic EOS.

The valid range always starts at zero density up to user specified maximum. If the polytropic index is less than one, the valid range is reduced avoid superluminal soundspeed, if necessary. The parameters are w.r.t EOS units. The EOS units given in the last parameter are stored for bookkeeping.

Parameters

  • n – Polytropic index \( n > 0 \)

  • rmd_p – Polytropic density scale \( \rho_p > 0 \)

  • rho_max – Maximum allowed mass density

  • units – Unit system (w.r.t. SI) of the EOS

Returns

eos_barotr generic interface employing polytropic EOS


Creating Piecewise Polytropic EOS

eos_barotr EOS_Toolkit::make_eos_barotr_pwpoly(real_t rmdp0, const std::vector<real_t> &segm_bound, const std::vector<real_t> &segm_gamma, real_t rho_max_, units units_ = units::geom_solar())

Create piecewise polytropic EOS.

The valid range always starts at zero density up to user specified maximum. If the polytropic index of some segments is less than one, the valid range is reduced, if necessary, to avoid superluminal soundspeed. The parameters are w.r.t EOS units. The EOS units given in the last parameter are stored for bookkeeping.

Parameters

  • rmdp0 – Polytropic density scale \(\rho_{p,0} > 0\) of first segment

  • segm_bound – Segment boundaries mass densities

  • segm_gamma – Polytropic exponents \( \Gamma_i > 1 \) for all segments

  • rho_max_ – Maximum allowed mass density

  • units – Unit system (w.r.t. SI) of the EOS

Returns

eos_barotr generic interface employing piecewise polytropic EOS

Generic Interface

class eos_barotr : private EOS_Toolkit::detail::eos_barotr_base

Interface for generic barotropic EOS.

Public Types

using range = interval<real_t>

Synonym for interval.

Public Functions

inline explicit eos_barotr(spimpl_t eos)

Constructor from pointer to implementation.

This is intended for EOS implementors. Users should use the functions provided by a given implementation to obtain the EOS.

Parameters

eos – Shared pointer to implementation

eos_barotr() = default

Default constructor.

Creates uninitialized EOS. Any attemt to use resulting object throws an exception. One can use it after copying another EOS to it.

eos_barotr(const eos_barotr&) = default

Copy constructor.

eos_barotr(eos_barotr&&) = default

Move constructor.

eos_barotr &operator=(const eos_barotr&) = default

Assignment operator.

eos_barotr &operator=(eos_barotr&&) = default

Move assignment operator.

~eos_barotr() = default

Destructor.

The EOS implementation will be destructed when no other copy of the EOS is using it (“last person turns off the light”).

auto at_rho(real_t rho) const -> state

Specify a matter state based on mass density.

Parameters

rho – Mass density \( \rho \)

Throws

std::runtime_error – if called for unitialized object

Returns

Object representing matter state

auto at_gm1(real_t gm1) const -> state

Specify a matter state based on pseudo enthalpy.

Parameters

gm1 – Pseudo enthalpy \( g - 1 \)

Throws

std::runtime_error – if called for unitialized object

Returns

Object representing matter state

inline auto is_isentropic() const -> bool
Throws

std::runtime_error – if called for unitialized object

Returns

Whether EOS is isentropic

inline auto is_zero_temp() const -> bool
Throws

std::runtime_error – if called for unitialized object

Returns

Whether EOS is zero-temperature (or false if temperature not implemented)

inline auto has_temp() const -> bool
Throws

std::runtime_error – if called for unitialized object

Returns

Whether EOS provides temperature

inline auto has_efrac() const -> bool
Throws

std::runtime_error – if called for unitialized object

Returns

Whether EOS provides electron fraction

inline auto range_rho() const -> const range&
Throws

std::runtime_error – if called for unitialized object

Returns

Validity range for mass density

inline auto range_gm1() const -> const range&
Throws

std::runtime_error – if called for unitialized object

Returns

Validity range for pseudo enthalpy \( g - 1 \)

inline auto minimal_h() const -> real_t
Throws

std::runtime_error – if called for unitialized object

Returns

Global lower bound for relativistic enthalpy.

auto is_rho_valid(real_t rho) const -> bool
Parameters

rho – Mass density \( \rho \)

Throws

std::runtime_error – if called for unitialized object

Returns

Wether density is in valid range

auto is_gm1_valid(real_t gm1) const -> bool
Parameters

gm1 – Pseudo enthalpy \( g - 1 \)

Throws

std::runtime_error – if called for unitialized object

Returns

Whether pseudo enthalpy is in valid range

auto gm1_at_rho(real_t rho) const -> real_t

Compute pseudo enthalpy from mass density.

Parameters

rho – Mass density \( \rho \)

Throws

std::runtime_error – if called for unitialized object

Returns

Pseudo enthalpy \( g - 1 \) if state is valid else NAN

Post

Guarantees \( g \ge 1 \) (unless NAN)

auto press_at_rho(real_t rho) const -> real_t

Compute pressure from mass density.

Parameters

rho – Mass density \( \rho \)

Throws

std::runtime_error – if called for unitialized object

Returns

Pressure if state is valid else NAN

Post

Guarantees \( P\ge 0 \) (unless NAN)

auto eps_at_rho(real_t rho) const -> real_t

Compute specific energy from mass density.

Parameters

rho – Mass density \( \rho \)

Throws

std::runtime_error – if called for unitialized object

Returns

\( \epsilon \) if state is valid else NAN

Post

Guarantees \( \epsilon \ge -1 \) (unless NAN)

auto hm1_at_rho(real_t rho) const -> real_t

Compute specific enthalpy from mass density.

Parameters

rho – Mass density \( \rho \)

Throws

std::runtime_error – if called for unitialized object

Returns

\( h - 1 \) if state is valid else NAN

Post

Guarantees \( h > 0 \) (unless NAN)

auto csnd_at_rho(real_t rho) const -> real_t

Compute sound speed from mass density.

Parameters

rho – Mass density \( \rho \)

Throws

std::runtime_error – if called for unitialized object

Returns

\( c_s \) if state is valid else NAN

Post

Guarantees \( 0\le c_s < 1 \) (unless NAN)

auto temp_at_rho(real_t rho) const -> real_t

Compute temperature from mass density.

Parameters

rho – Mass density \( \rho \)

Throws

  • std::runtime_error – if temperature not available for EOS

  • std::runtime_error – if called for unitialized object

Returns

\( T \) if state is valid else NAN

Post

Guarantees \( T\ge 0 \) (unless NAN)

auto ye_at_rho(real_t rho) const -> real_t

Compute electron fraction from mass density.

Parameters

rho – Mass density \( \rho \)

Throws

  • std::runtime_error – if electron fraction not available for EOS

  • std::runtime_error – if called for unitialized object

Returns

\( Y_e \) if state is valid else NAN

auto rho_at_gm1(real_t gm1) const -> real_t

Compute mass density from pseudo enthalpy.

Parameters

gm1 – Pseudo enthalpy \( g - 1 \)

Throws

std::runtime_error – if called for unitialized object

Returns

\( \rho \) if state is valid else NAN

Post

Guarantees \( \rho \ge 0 \) (unless NAN)

auto press_at_gm1(real_t gm1) const -> real_t

Compute pressure from pseudo enthalpy.

Parameters

gm1 – Pseudo enthalpy \( g - 1 \)

Throws

std::runtime_error – if called for unitialized object

Returns

Pressure if state is valid else NAN

Post

Guarantees \( P\ge 0 \) (unless NAN)

auto eps_at_gm1(real_t gm1) const -> real_t

Compute specific energy from pseudo enthalpy.

Parameters

gm1 – Pseudo enthalpy \( g - 1 \)

Throws

std::runtime_error – if called for unitialized object

Returns

\( \epsilon \) if state is valid else NAN

Post

Guarantees \( \epsilon \ge -1 \) (unless NAN)

auto hm1_at_gm1(real_t gm1) const -> real_t

Compute specific enthalpy from pseudo enthalpy.

Parameters

gm1 – Pseudo enthalpy \( g - 1 \)

Throws

std::runtime_error – if called for unitialized object

Returns

\( h - 1 \) if state is valid else NAN

Post

Guarantees \( h > 0 \) (unless NAN)

auto csnd_at_gm1(real_t gm1) const -> real_t

Compute sound speed from pseudo enthalpy.

Parameters

gm1 – Pseudo enthalpy \( g - 1 \)

Throws

std::runtime_error – if called for unitialized object

Returns

\( c_s \) if state is valid else NAN

Post

Guarantees \( 0\le c_s < 1 \) (unless NAN)

auto temp_at_gm1(real_t gm1) const -> real_t

Compute temperature from from pseudo enthalpy.

Parameters

gm1 – Pseudo enthalpy \( g - 1 \)

Throws

  • std::runtime_error – if temperature not available for EOS

  • std::runtime_error – if called for unitialized object

Returns

\( T \) if state is valid else NAN

Post

Guarantees \( T\ge 0 \) (unless NAN)

auto ye_at_gm1(real_t gm1) const -> real_t

Compute electron fraction from pseudo enthalpy.

Parameters

gm1 – Pseudo enthalpy \( g - 1 \)

Throws

  • std::runtime_error – if electron fraction not available for EOS

  • std::runtime_error – if called for unitialized object

Returns

\( Y_e \) if state is valid else NAN

auto units_to_SI() const -> const units&

Return the EOS units.

This returns the conversion factors to express the units used by the EOS into SI units. The units are specified by the user when creating the EOS and stored for bookkeeping.

void save(datasink s) const

Save EOS to a datastore.

This allows saving the EOS to a datastore. This is also used internally by the EOS file functionality.

auto descr_str() const -> std::string

Short description string.

Returns

Short auto-generated EOS type-specific description string

class state : private EOS_Toolkit::detail::eos_barotr_base::state_base

Class representing the matter state for the eos_barotr interface.

Public Functions

state(const state&) = default

Copy constructor.

state(state&&) = default

Move constructor.

state &operator=(const state&) = delete

Objects not meant to be assigned.

state &operator=(state&&) = delete

Objects not meant to be assigned.

inline explicit operator bool() const noexcept

Conversion operator to bool.

Returns

If state is valid.

auto gm1() const -> real_t
Throws

std::runtime_error – if state is invalid

Returns

Pseudo enthalpy \( g - 1 \)

Post

Guarantees \( g \ge 1 \)

auto rho() const -> real_t
Throws

std::runtime_error – if state is invalid

Returns

Mass density \( \rho \)

Post

Guarantees \( \rho \ge 0 \)

auto press() const -> real_t
Throws

std::runtime_error – if state is invalid

Returns

Pressure \( P \)

Post

Guarantees \( P\ge 0 \)

auto eps() const -> real_t
Throws

std::runtime_error – if state is invalid

Returns

Specific internal energy \( \epsilon \)

Post

Guarantees \( \epsilon \ge -1 \)

auto hm1() const -> real_t
Throws

std::runtime_error – if state is invalid

Returns

Specific enthalpy \( h - 1 \)

Post

Guarantees \( h > 0 \) (not \( h >= 1 \))

auto csnd() const -> real_t
Throws

std::runtime_error – if state is invalid

Returns

Speed of sound \( c_s \)

Post

Guarantees \( 0\le c_s < 1 \)

auto temp() const -> real_t
Throws

  • std::runtime_error – if state is invalid

  • std::runtime_error – if temperature not available for EOS

Returns

Temperature \( T \)

Post

Guarantees \( T\ge 0 \)

auto ye() const -> real_t
Throws

  • std::runtime_error – if state is invalid

  • std::runtime_error – if composition not available for EOS

Returns

Electron fraction \( Y_e \)

Deprecated EOS

In older versions, there was no spline based EOS. Instead there was eos_barotr_table based on linear interpolation. This type can still be used for sake of reproducing old results, but for new EOS its use is discouraged.

Deprecated since version 1.5: Use make_eos_barotr_spline instead make_eos_barotr_table

eos_barotr EOS_Toolkit::make_eos_barotr_table(const std::vector<real_t> &gm1, const std::vector<real_t> &rho, const std::vector<real_t> &eps, const std::vector<real_t> &pbr, const std::vector<real_t> &cs2, const std::vector<real_t> &temp, const std::vector<real_t> &efrac, bool isentropic_, real_t n_poly_, units units_ = units::geom_solar())

Create tabulated barotropic EOS.

The internally used regularly log-spaced lookup tables are set up from irregularly spaced sample points provided as vectors, using cubic monotonic spline interpolation.

One can specify whether the EOS is isentropic. If the temperature is zero, the EOS must be specified as isentropic or an exception is thrown. Even for isentropic EOS, it is still necessary to provide specific energy and pseudo-enthalpy, even though they become redundant. Consistency is not checked and in the responsibility of the user.

The validity range will start at zero up to the largest provided sample point. Between zero and the lowest sample point, a polytropic EOS will be used.

The parameters are w.r.t EOS units. The EOS units given in the last parameter are stored for bookkeeping.

Parameters

  • gm1 – Samples for pseudo enthalpy \( g-1 \). Must be strictly increasing.

  • rho – Samples for mass density \( \rho \). Must be strictly increasing.

  • eps – Samples for specific energy \( \epsilon \). Must be strictly increasing and obey \( \epsilon > -1 \)

  • pbr – Samples for \( P / \rho \ge 0 \).

  • cs2 – Samples for squared soundspeed. Must obey \( 0 \le c_s^2 < 1 \)

  • temp – Samples for temperature or empty vector (equivalent to all-zero). Must obey \( T\ge 0 \).

  • efrac – Electron fraction or empty vector (in which case the EOS will not provide electron fraction).

  • isentropic_ – Whether the EOS is isentropic, e.g. for degenerate matter.

  • n_poly_ – Polytropic index used to extent EOS to zero density.

  • units – Unit system (w.r.t. SI) of the EOS

Returns

Generic interface employing tabulated barotropic EOS