pttools.models.model

Template for equations of state

Classes

class pttools.models.model.Model(V_s, V_b=DEFAULT_V_B, T_ref=1, T_min=None, T_max=None, T_crit_guess=None, name=None, label_latex=None, label_unicode=None, gen_critical=True, gen_cs2=True, gen_cs2_neg=True, implicit_V=False, temperature_is_physical=None, silence_temp=False, allow_invalid=False, log_info=True)

Bases: BaseModel, ABC

Template for equations of state

Parameters:

• T_ref (float) – reference temperature. Be careful when using a thermodynamics-based model that there are no conflicts in the choices of units.

• T_min (float) – minimum temperature at which the model is valid

• V_s (float) – the constant term in the expression of \(p\) in the symmetric phase

• V_b (float) – the constant term in the expression of \(p\) in the broken phase

• name (str) – custom name for the model

• gen_cs2 (bool) – used internally for postponing the generation of the cs2 function

• T_max (float)

• T_crit_guess (float)

• label_latex (str)

• label_unicode (str)

• gen_critical (bool)

• gen_cs2_neg (bool)

• implicit_V (bool)

• temperature_is_physical (bool)

• silence_temp (bool)

• allow_invalid (bool)

• log_info (bool)

ALPHA_N_MIN_FIND_SAFETY_FACTOR_ALPHA: float = 0.999

DEFAULT_V_B = 0

Psi_n(wn)

Inverse enthalpy ratio at nucleation temperature \(\psi_n\), Ai et al., 2023, p. 9

With validation check

Parameters:

wn (float | float64 | ndarray)

Return type:

float | float64 | ndarray

V(phase)

Potential \(V(\phi)\)

Parameters:

phase (float | float64 | ndarray) – phase \(\phi\)

Return type:

float | float64 | ndarray

alpha_n(wn, error_on_invalid=True, nan_on_invalid=True, log_invalid=True)

Transition strength parameter at nucleation temperature, \(\alpha_n\), Hindmarsh et al., 2021, eq. 7.40.

\[\alpha_n = \frac{4(\theta(w_n,\phi_s) - \theta(w_n,\phi_b)}{3w_n}\]

Parameters:

• wn (float | float64 | ndarray) – \(w_n\), enthalpy of the symmetric phase at the nucleation temperature

• error_on_invalid (bool) – raise error for invalid values

• nan_on_invalid (bool) – return nan for invalid values

• log_invalid (bool) – log negative values

Return type:

float | float64 | ndarray

alpha_n_from_alpha_theta_bar_n(alpha_theta_bar_n, wn=None, wn_guess=None, error_on_invalid=True, nan_on_invalid=True, log_invalid=True)

Conversion from \(\alpha_{\bar{\theta}_n}\) of Giese et al., 2021, eq. 13 to \(\alpha_n\)

Parameters:

• alpha_theta_bar_n (float | float64 | ndarray)

• wn (float)

• wn_guess (float)

• error_on_invalid (bool)

• nan_on_invalid (bool)

• log_invalid (bool)

Return type:

float | float64 | ndarray

alpha_n_min_find(w_min=None, w_max=None)

Find \(\text{min} \alpha_n(w)\) for \(w \in ({w}_\text{min}, {w}_\text{max})\)

Parameters:

• w_min (float)

• w_max (float)

Return type:

Tuple[float, float]

alpha_n_min_find_params(alpha_n_min_target, V_s_default, V_b, safety_factor_alpha=ALPHA_N_MIN_FIND_SAFETY_FACTOR_ALPHA)

Find the model parameters that allow the given \(\alpha_{n,\text{min,target}}\)

Parameters:

• alpha_n_min_target (float)

• V_s_default (float)

• V_b (float)

• safety_factor_alpha (float)

alpha_plus(wp, wm, vp_tilde=None, sol_type=None, error_on_invalid=True, nan_on_invalid=True, log_invalid=True)

Transition strength parameter \(\alpha_+\)

\[\alpha_+ = \frac{4\Delta \theta}{3{w}_+} = \frac{4(\theta({w}_+,\phi_s) - \theta({w}_-,\phi_b)}{3{w}_+}\]

Parameters:

• wp (float | float64 | ndarray) – \(w_+\)

• wm (float | float64 | ndarray) – \(w_-\)

• error_on_invalid (bool) – raise error for invalid values

• nan_on_invalid (bool) – return nan for invalid values

• log_invalid (bool) – whether to log invalid values

• vp_tilde (float)

• sol_type (SolutionType)

Return type:

float | float64 | ndarray

alpha_theta_bar_n(wn, error_on_invalid=True, nan_on_invalid=True, log_invalid=True)

Transition strength parameter, Giese et al., 2021, eq. 13

\[\alpha_{\bar{\theta}+} = \frac{D \bar{\theta}(T_n)}{3 w_n}\]

Parameters:

• wn (float | float64 | ndarray)

• error_on_invalid (bool)

• nan_on_invalid (bool)

• log_invalid (bool)

Return type:

float | float64 | ndarray

alpha_theta_bar_n_from_alpha_n(alpha_n, wn=None, wn_guess=None)

Conversion from \(\alpha_n\) to \(\alpha_{\bar{\theta}_n}\) of Giese et al., 2021, eq. 13

Parameters:

• alpha_n (float)

• wn (float)

• wn_guess (float)

Return type:

float

alpha_theta_bar_plus(wp, error_on_invalid=True, nan_on_invalid=True, log_invalid=True)

Transition strength parameter, Giese et al., 2021, eq. 9

\[\alpha_{\bar{\theta}+} = \frac{D \bar{\theta}(T_+)}{3 w_+}\]

Parameters:

• wp (float | float64 | ndarray)

• error_on_invalid (bool)

• nan_on_invalid (bool)

• log_invalid (bool)

Return type:

float | float64 | ndarray

static check_alpha_plus(alpha_plus, vp_tilde=None, sol_type=None, error_on_invalid=True, nan_on_invalid=True, log_invalid=True)

Check that the given \(\alpha_+\) values are in the valid range $0 <= \alpha_+ < 1/3

Modifies the given array.

Parameters:

• alpha_plus (float | float64 | ndarray)

• vp_tilde (float | float64 | ndarray)

• sol_type (SolutionType)

• error_on_invalid (bool)

• nan_on_invalid (bool)

• log_invalid (bool)

Return type:

float | float64 | ndarray

static check_delta_theta(delta_theta, wp, wm, theta_s=None, theta_b=None, error_on_invalid=True, nan_on_invalid=True, log_invalid=True)

Parameters:

• delta_theta (float | float64 | ndarray)

• wp (float | float64 | ndarray)

• wm (float | float64 | ndarray)

• theta_s (float | float64 | ndarray)

• theta_b (float | float64 | ndarray)

• error_on_invalid (bool)

• nan_on_invalid (bool)

• log_invalid (bool)

Return type:

float | float64 | ndarray

check_p(wn, allow_fail=False)

Parameters:

• wn (float | float64 | ndarray)

• allow_fail (bool)

check_p_temp(temp_n, allow_fail=False)

For the phase transition to happen \(p_s(T_n) < p_b(T_n)\)

Parameters:

• temp_n (float | float64 | ndarray)

• allow_fail (bool)

check_w_for_alpha(w, w_min=None, w_max=None, error_on_invalid=True, nan_on_invalid=True, log_invalid=True, name='w', alpha_name='alpha')

Check that \(w \in ({w}_\text{min}, {w}_\text{max})\) for the given \(w\).

Parameters:

• w (float | float64 | ndarray)

• w_min (float)

• w_max (float)

• error_on_invalid (bool)

• nan_on_invalid (bool)

• log_invalid (bool)

• name (str)

• alpha_name (str)

Return type:

float | ndarray

critical_temp(guess=None, guess_backup=2, t_max_backup=10000, allow_fail=False)

Solves for the critical temperature \(T_c\), where \(p_s(T_c)=p_b(T_c)\)

Parameters:

• guess (float) – starting guess for \(T_\text{crit}\)

• guess_backup (float) – alternative guess that is used if guess is None

• t_max_backup (float) – alternative \(T_\text{max}\) that is used if \(T_\text{max}\) is None

• allow_fail (bool) – do not raise exceptions on errors

Return type:

float

critical_temp_const: float

\[\frac{90}{\pi^2} (V_b - V_s)\]

critical_temp_opt(temp)

This function should be zero at the critical temperature \(T_c\), where $p_s(T_c)=p_b(T_c).

Parameters:

temp (float)

Return type:

float

criticals(t_crit_guess, allow_fail=False, log_info=True)

Parameters:

• t_crit_guess (float)

• allow_fail (bool)

• log_info (bool)

cs2(w, phase)

Speed of sound squared \(c_s^2(w,\phi)\). This must be a Numba-compiled function.

\[c_s^2 \equiv \left( \frac{\partial p}{\partial e} \right)_s = \frac{dp/dT}{de/dT}\]

Relativistic hydrodynamics, Rezzolla, Zanotti, 2013, eq. 2.168 Giese et al., 2021, eq. 3

Parameters:

• w (float | float64 | ndarray) – enthalpy \(w\)

• phase (float | float64 | ndarray) – phase \(\phi\)

Return type:

float | float64 | ndarray

cs2_max(w_max, phase, w_min=0, allow_fail=False, **kwargs)

Parameters:

• w_max (float)

• phase (Phase)

• w_min (float)

• allow_fail (bool)

Return type:

Tuple[float, float]

cs2_min(w_max, phase, w_min=0, allow_fail=False, **kwargs)

Parameters:

• w_max (float)

• phase (Phase)

• w_min (float)

• allow_fail (bool)

Return type:

Tuple[float, float]

cs2_neg(w, phase)

Speed of sound squared with a minus sign. This is needed for finding the maximum of cs2.

Parameters:

• w (float | float64 | ndarray)

• phase (float | float64 | ndarray)

Return type:

float | float64 | ndarray

cs2_temp(temp, phase)

Parameters:

• temp (float | float64 | ndarray)

• phase (float | float64 | ndarray)

Return type:

float | float64 | ndarray

delta_theta(wp, wm, error_on_invalid=True, nan_on_invalid=True, log_invalid=True)

Parameters:

• wp (float | float64 | ndarray)

• wm (float | float64 | ndarray)

• error_on_invalid (bool)

• nan_on_invalid (bool)

• log_invalid (bool)

Return type:

float | float64 | ndarray

delta_theta_bar(w, phase_of_w)

Pseudotrace difference \(D\bar{\theta}(w)\), Giese et al., 2021, eq. 10

\[D\bar{\theta}(w) = \bar{\theta}(T) - \bar{\theta}(T)\]

Parameters:

• w (float | float64 | ndarray)

• phase_of_w (float | float64 | ndarray)

Return type:

float | float64 | ndarray

delta_theta_bar_temp(temp)

Pseudotrace difference \(D\bar{\theta}(T)\), Giese et al., 2021, eq. 10

\[D\bar{\theta}(T) = \bar{\theta}(T) - \bar{\theta}(T)\]

Parameters:

temp (float | float64 | ndarray)

Return type:

float | float64 | ndarray

df_dtau_ptr()

Return type:

(float64, float64*, float64*, float64*) -> none*

e(w, phase)

Energy density \(e(w,\phi)\). Calls the temperature-based function.

Parameters:

• w (float | float64 | ndarray) – enthalpy \(w\)

• phase (float | float64 | ndarray) – phase \(\phi\)

Return type:

float | float64 | ndarray

abstract e_temp(temp, phase)

Energy density \(e(T,\phi)\)

\[e \equiv T \frac{\partial p}{\partial T} - p\]

Giese et al., 2021, eq. 2

Parameters:

• temp (float | float64 | ndarray) – temperature \(T\)

• phase (float | float64 | ndarray) – phase \(\phi\)

Return type:

float | float64 | ndarray

enthalpy_ratio(temp)

Enthalpy ratio \(r(T)\)

\[r(T) = \frac{w_s(T)}{w_b(T)}\]

:param temp: temperature \(T\)

Parameters:

temp (float | float64 | ndarray)

Return type:

float | float64 | ndarray

export()

Export the model parameters to a dictionary. User-created model classes should extend this.

Return type:

Dict[str, any]

ge(w, phase)

Effective degrees of freedom for energy density, \(g_{\text{eff},e}(w,\phi)\)

Parameters:

• w (float | float64 | ndarray)

• phase (float | float64 | ndarray)

Return type:

float | float64 | ndarray

abstract ge_temp(temp, phase)

Parameters:

• temp (float | float64 | ndarray)

• phase (float | float64 | ndarray)

Return type:

float | float64 | ndarray

gp(w, phase)

Effective degrees of freedom for pressure, \(g_{\text{eff},p}(w,\phi)\)

Parameters:

• w (float | float64 | ndarray)

• phase (float | float64 | ndarray)

Return type:

float | float64 | ndarray

abstract gp_temp(temp, phase)

Parameters:

• temp (float | float64 | ndarray)

• phase (float | float64 | ndarray)

Return type:

float | float64 | ndarray

gs(w, phase)

Effective degrees of freedom for entropy, \(g_{\text{eff},s}(w,\phi)\)

Parameters:

• w (float | float64 | ndarray)

• phase (float | float64 | ndarray)

Return type:

float | float64 | ndarray

abstract gs_temp(temp, phase)

Parameters:

• temp (float | float64 | ndarray)

• phase (float | float64 | ndarray)

Return type:

float | float64 | ndarray

inverse_enthalpy_ratio(temp)

Inverse enthalpy ratio \(\Psi(T)\) Ai et al., 2023, eq. 19

\[\Psi(T) = \frac{w_b(T)}{w_s(T)}\]

:param temp: temperature \(T\)

Parameters:

temp (float | float64 | ndarray)

Return type:

float | float64 | ndarray

nu_gdh2024(w, phase=Phase.BROKEN)

\[\nu = \frac{1 - 3\omega}{1 + 3\omega}\]

Giombi et al., 2024 eq. 2.11

Parameters:

• w (float | float64 | ndarray)

• phase (float | float64 | ndarray)

Return type:

float | float64 | ndarray

omega(w, phase)

Barotropic equation of state parameter \(\omega\)

Parameters:

• w (float | float64 | ndarray)

• phase (float | float64 | ndarray)

Return type:

float | float64 | ndarray

p(w, phase)

Pressure \(p(w,\phi)\). Calls the temperature-based function.

Parameters:

• w (float | float64 | ndarray) – enthalpy \(w\)

• phase (float | float64 | ndarray) – phase \(\phi\)

Return type:

float | float64 | ndarray

abstract p_temp(temp, phase)

Pressure \(p(T,\phi)\)

Parameters:

• temp (float | float64 | ndarray) – temperature \(T\)

• phase (float | float64 | ndarray) – phase \(\phi\)

Return type:

float | float64 | ndarray

abstract params_str()

Model parameters as a string

Return type:

str

s(w, phase)

Entropy density \(s(w,\phi)\). Calls the temperature-based function.

Parameters:

• w (float | float64 | ndarray) – enthalpy \(w\)

• phase (float | float64 | ndarray) – phase \(\phi\)

Return type:

float | float64 | ndarray

abstract s_temp(temp, phase)

Entropy density \(s(T,\phi)=\frac{dp}{dT}\)

Parameters:

• temp (float | float64 | ndarray) – temperature \(T\)

• phase (float | float64 | ndarray) – phase \(\phi\)

Return type:

float | float64 | ndarray

solution_type(v_wall, alpha_n, wn=None, wn_guess=None, wm_guess=None)

Parameters:

• v_wall (float)

• alpha_n (float)

• wn (float)

• wn_guess (float)

• wm_guess (float)

Return type:

SolutionType

abstract temp(w, phase)

Temperature \(T(w,\phi)\)

Parameters:

• w (float | float64 | ndarray) – enthalpy \(w\)

• phase (float | float64 | ndarray) – phase \(\phi\)

Return type:

float | float64 | ndarray

theta(w, phase)

Trace anomaly \(\theta(w,\phi)\), Hindmarsh et al., 2021, eq. 7.24

\[\theta = \frac{1}{4}(e - 3p)\]

Parameters:

• w (float | float64 | ndarray) – enthalpy \(w\)

• phase (float | float64 | ndarray) – phase \(\phi\)

Return type:

float | float64 | ndarray

theta_bar(w, phase)

Pseudotrace \(\bar{\theta}\), Giese et al., 2021, eq. 9, Ai et al., 2023, eq. 19

\[\bar{\theta} = e - \frac{p}{c_{s,b}^2}\]

Parameters:

• w (float | float64 | ndarray) – enthalpy \(w\)

• phase (float | float64 | ndarray) – phase \(\phi\)

Return type:

float | float64 | ndarray

theta_bar_temp(temp, phase)

Pseudotrace \(\bar{\theta}\), Giese et al., 2021, eq. 9, Ai et al., 2023, eq. 19

\[\bar{\theta} = e - \frac{p}{c_{s,b}^2}\]

Parameters:

• temp (float | float64 | ndarray) – temperature \(T\)

• phase (float | float64 | ndarray) – phase \(\phi\)

Return type:

float | float64 | ndarray

tn(alpha_n, wn_guess=None, theta_bar=False, error_on_invalid=True, nan_on_invalid=True, log_invalid=True)

Parameters:

• alpha_n (float | float64 | ndarray)

• wn_guess (float)

• theta_bar (bool)

• error_on_invalid (bool)

• nan_on_invalid (bool)

• log_invalid (bool)

Return type:

float | float64 | ndarray

validate_alpha_n(alpha_n, allow_invalid=False, log_invalid=True)

Validate that \(\alpha_{n,\text{min}} < \alpha_n < 1\)

Parameters:

• alpha_n (float)

• allow_invalid (bool)

• log_invalid (bool)

vp_vm_tilde_ratio_giese(vp_tilde, vm_tilde, wp, wm)

Giese approximation for \(\frac{\tilde{v}_+}{\tilde{v}_-}\), Giese et al., 2021 eq. 11

$$frac{tilde{v}_+}{tilde{v}_-} approx frac{

(tilde{v}_+ tilde{v}_- / c_{s,b}^2 - 1) + 3alpha_{bar{theta}_+} }{ (tilde{v}_+ tilde{v}_- / c_{s,b}^2 - 1) + 3 tilde{v}_+ tilde{v}_- alpha_{bar{theta}}_+

}$$

Parameters:

• vp_tilde (float | float64 | ndarray) – \(\tilde{v}_+\)

• vm_tilde (float | float64 | ndarray) – \(\tilde{v}_-\)

• wp (float) – \(w_+\)

• wm (float | float64 | ndarray) – \(w_-\)

Returns:

\(\frac{\tilde{v}_+}{\tilde{v}_-}\)

Return type:

float | float64 | ndarray

abstract w(temp, phase)

Enthalpy \(w(T,\phi)\)

Parameters:

• temp (float | float64 | ndarray) – temperature \(T\)

• phase (float | float64 | ndarray) – phase \(\phi\)

Return type:

float | float64 | ndarray

wn(alpha_n, wn_guess=None, theta_bar=False, error_on_invalid=True, nan_on_invalid=True, log_invalid=True)

Enthalpy at nucleation temperature \(w_n\) with given \(\alpha_n\)

Parameters:

• alpha_n (float | float64 | ndarray)

• wn_guess (float)

• theta_bar (bool)

• error_on_invalid (bool)

• nan_on_invalid (bool)

• log_invalid (bool)

Return type:

float | float64 | ndarray

wn_error_msg(alpha_n, param, param_name, info=None)

Parameters:

• alpha_n (float | float64 | ndarray)

• param (float | float64 | ndarray)

• param_name (str)

• info (str)

Return type:

str