Reference fluids (Helmholtz)¶
Multiparameter Helmholtz-energy equations of state of the REFPROP/CoolProp class
(IAPWS-95 water/steam, Span-Wagner CO2, and more), implemented as one scalar
Helmholtz energy whose every property and solver is an exact jax.grad
derivative. Includes differentiable saturation lines, steam-table state
functions, and the IAPWS transport formulations for water.
See the reference-fluids & steam-tables guide for worked examples.
helmholtz
¶
Reference multiparameter (Helmholtz-energy) equations of state.
This subpackage gives Fugacio reference-grade pure-fluid properties: the
same class of model behind NIST REFPROP and CoolProp, namely IAPWS-95 for
water/steam, Span & Wagner for CO2, Setzmann & Wagner for methane, and the
short technical formulations for the other vendored process fluids
(reference_fluid_names lists all 26).
The entire model is one scalar function, the reduced Helmholtz energy
alpha(delta, tau); every property is an exact jax.grad derivative
of it (terms,
props). Saturation lines come from a
differentiable Maxwell construction
(saturation), (T, P) / (P, h) /
(P, s) / quality states from steam-table style resolvers
(states), and water carries the full IAPWS
transport formulations with autodiff critical enhancements
(iapws).
Validation is layered like the rest of Fugacio: hermetic unit tests pin the
published IAPWS-95/Span-Wagner check tables, consistency tests assert
first-principles identities through the solvers (Clausius-Clapeyron along the
solved saturation line, Maxwell relations, cp - cv), and the opt-in
oracle suite grades dense property grids for every fluid against CoolProp.
Example::
from fugacio.thermo.helmholtz import reference_fluid, saturation_state, state_ph
import jax
steam = reference_fluid("water")
sat = saturation_state(steam, p=10e5) # 10 bar saturation
sat.t, sat.h_vaporization # 453.03 K, 2014.6 kJ/kg * M
# d(Tsat)/dP along the solved line, the Clausius-Clapeyron slope:
jax.grad(lambda p: saturation_state(steam, p=p).t)(10e5)
Modules:
| Name | Description |
|---|---|
density |
Density solves |
fluids |
Reference-fluid registry: published Helmholtz EOS as JAX-ready dataclasses. |
iapws |
IAPWS reference transport properties of water, with autodiff enhancements. |
props |
Thermodynamic properties from a reference Helmholtz EOS, at |
saturation |
Vapor-liquid saturation of a reference Helmholtz EOS (Maxwell construction). |
states |
Steam-table style state functions for reference fluids. |
surface |
Surface tension of reference fluids (Mulero-Cachadina-IAPWS correlations). |
terms |
Reduced Helmholtz energy |
Classes:
| Name | Description |
|---|---|
Ancillary |
One saturation ancillary equation (initial guesses for the Maxwell solve). |
HelmholtzFluid |
A pure fluid described by a reference multiparameter Helmholtz EOS. |
SaturationState |
The full vapor-liquid coexistence state of a pure fluid. |
FluidState |
A resolved thermodynamic state of a pure reference fluid. |
AlphaDerivatives |
The partial derivatives of |
Functions:
| Name | Description |
|---|---|
molar_density |
Molar density |
has_reference_fluid |
Whether |
reference_fluid |
The reference Helmholtz EOS for a named fluid. |
reference_fluid_names |
Names of every fluid with a vendored reference EOS, sorted. |
water_thermal_conductivity |
Thermal conductivity of water (W/m/K) at |
water_viscosity |
Viscosity of water (Pa*s) at |
compressibility_factor |
Compressibility factor |
enthalpy |
Molar enthalpy (J/mol) on the fluid's published reference state. |
entropy |
Molar entropy (J/mol/K) on the fluid's published reference state. |
fugacity |
Fugacity |
gibbs_energy |
Molar Gibbs energy (J/mol); equal in both phases at saturation. |
helmholtz_energy |
Molar Helmholtz energy |
internal_energy |
Molar internal energy (J/mol). |
isobaric_expansivity |
Volumetric thermal expansion coefficient |
isobaric_heat_capacity |
Molar isobaric heat capacity |
isochoric_heat_capacity |
Molar isochoric heat capacity |
isothermal_compressibility |
Isothermal compressibility |
joule_thomson |
Joule-Thomson coefficient |
ln_fugacity_coefficient |
Log fugacity coefficient |
pressure |
Pressure (Pa) at molar density |
second_virial |
Second virial coefficient |
speed_of_sound |
Speed of sound (m/s). |
third_virial |
Third virial coefficient |
psat_ancillary |
Ancillary (initial-guess) saturation pressure (Pa). |
rho_liquid_ancillary |
Ancillary saturated-liquid molar density (mol/m^3). |
rho_vapor_ancillary |
Ancillary saturated-vapor molar density (mol/m^3). |
saturation_densities |
Coexisting molar densities |
saturation_pressure |
Saturation pressure (Pa) from the Maxwell construction at |
saturation_state |
The coexistence state at a given temperature or pressure. |
saturation_temperature |
Saturation (boiling) temperature (K) at pressure |
state_ph |
The state at pressure |
state_pq |
The two-phase state at saturation pressure |
state_ps |
The state at pressure |
state_tp |
The single-phase state at temperature |
state_tq |
The two-phase state at saturation temperature |
surface_tension |
Vapor-liquid surface tension (N/m) at |
alpha_derivatives |
All |
ideal_alpha |
Ideal-gas part |
residual_alpha |
Residual part |
Ancillary
dataclass
¶
Ancillary(
n: Array,
t: Array,
reducing: float,
t_reducing: float,
using_tau_r: bool,
noexp: bool,
)
One saturation ancillary equation (initial guesses for the Maxwell solve).
Evaluates reducing * exp(f * sum(n_i * theta**t_i)) with
theta = 1 - T/t_reducing and f = t_reducing/T when using_tau_r
(else 1); the noexp family is reducing * (1 + sum(n_i * theta**t_i)).
Attributes:
| Name | Type | Description |
|---|---|---|
n |
Array
|
Coefficients of the expansion. |
t |
Array
|
Exponents of |
reducing |
float
|
Reducing value (Pa for pressure, mol/m^3 for density). |
t_reducing |
float
|
Reducing temperature (K). |
using_tau_r |
bool
|
Whether the exponential is premultiplied by |
noexp |
bool
|
Whether the expansion is affine rather than exponential. |
HelmholtzFluid
dataclass
¶
HelmholtzFluid(
name: str,
cas: str,
bibtex_eos: str,
molar_mass: float,
gas_constant: float,
t_reducing: float,
rho_reducing: float,
t_critical: float,
p_critical: float,
rho_critical: float,
t_triple: float,
p_triple: float,
t_max: float,
p_max: float,
rho_max: float,
acentric: float,
sigma_tc: float,
lead_a1: Array,
lead_a2: Array,
log_tau: Array,
ideal_power_n: Array,
ideal_power_t: Array,
pe_n: Array,
pe_t: Array,
power_n: Array,
power_t: Array,
power_d: Array,
power_l: Array,
gauss_n: Array,
gauss_t: Array,
gauss_d: Array,
gauss_eta: Array,
gauss_beta: Array,
gauss_gamma: Array,
gauss_epsilon: Array,
na_n: Array,
na_a: Array,
na_b: Array,
na_beta: Array,
na_big_a: Array,
na_big_b: Array,
na_big_c: Array,
na_big_d: Array,
gaob_n: Array,
gaob_t: Array,
gaob_d: Array,
gaob_eta: Array,
gaob_beta: Array,
gaob_gamma: Array,
gaob_epsilon: Array,
gaob_b: Array,
sigma_a: Array,
sigma_e: Array,
anc_psat: Ancillary,
anc_rho_liquid: Ancillary,
anc_rho_vapor: Ancillary,
)
A pure fluid described by a reference multiparameter Helmholtz EOS.
The reduced Helmholtz energy alpha = a/(R T) is split into an ideal-gas
part and a residual part, each a sum of standard term families evaluated at
delta = rho/rho_reducing and tau = t_reducing/T
(fugacio.thermo.helmholtz.terms). Coefficient arrays are pytree
leaves; scalar metadata (bounds, reducing constants) is static.
Note gas_constant is the molar gas constant the EOS was published
with, which may differ from CODATA in the last digits; using it is
required to reproduce reference values exactly.
SaturationState
dataclass
¶
SaturationState(
t: Array,
p: Array,
rho_liquid: Array,
rho_vapor: Array,
h_liquid: Array,
h_vapor: Array,
s_liquid: Array,
s_vapor: Array,
h_vaporization: Array,
)
The full vapor-liquid coexistence state of a pure fluid.
Attributes:
| Name | Type | Description |
|---|---|---|
t |
Array
|
Saturation temperature (K). |
p |
Array
|
Saturation pressure (Pa). |
rho_liquid |
Array
|
Saturated-liquid molar density (mol/m^3). |
rho_vapor |
Array
|
Saturated-vapor molar density (mol/m^3). |
h_liquid |
Array
|
Saturated-liquid molar enthalpy (J/mol). |
h_vapor |
Array
|
Saturated-vapor molar enthalpy (J/mol). |
s_liquid |
Array
|
Saturated-liquid molar entropy (J/mol/K). |
s_vapor |
Array
|
Saturated-vapor molar entropy (J/mol/K). |
h_vaporization |
Array
|
Latent heat of vaporization (J/mol). |
FluidState
dataclass
¶
FluidState(
t: Array,
p: Array,
rho: Array,
z: Array,
u: Array,
h: Array,
s: Array,
g: Array,
cv: Array,
cp: Array,
w: Array,
q: Array,
two_phase: Array,
)
A resolved thermodynamic state of a pure reference fluid.
Attributes:
| Name | Type | Description |
|---|---|---|
t |
Array
|
Temperature (K). |
p |
Array
|
Pressure (Pa). |
rho |
Array
|
Bulk molar density (mol/m^3). |
z |
Array
|
Compressibility factor |
u |
Array
|
Molar internal energy (J/mol). |
h |
Array
|
Molar enthalpy (J/mol). |
s |
Array
|
Molar entropy (J/mol/K). |
g |
Array
|
Molar Gibbs energy (J/mol). |
cv |
Array
|
Molar isochoric heat capacity (J/mol/K); |
cp |
Array
|
Molar isobaric heat capacity (J/mol/K); |
w |
Array
|
Speed of sound (m/s); |
q |
Array
|
Vapor quality (mole basis); |
two_phase |
Array
|
Whether the state lies inside the vapor-liquid dome. |
AlphaDerivatives
dataclass
¶
AlphaDerivatives(
a0: Array,
a0_t: Array,
a0_tt: Array,
ar: Array,
ar_d: Array,
ar_dd: Array,
ar_t: Array,
ar_tt: Array,
ar_dt: Array,
)
The partial derivatives of alpha that every property formula needs.
Subscripts denote reduced-variable partials: ar_d is
d(alphar)/d(delta) at constant tau, a0_tt is
d^2(alpha0)/d(tau)^2, and so on. All are produced by jax.grad
of the scalar term sums: no hand-derived derivative code exists in this
package.
molar_density
¶
molar_density(
fluid: HelmholtzFluid,
t: ArrayLike,
p: ArrayLike,
*,
phase: str = "supercritical",
) -> Array
Molar density rho(T, P) (mol/m^3) on the requested branch.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
fluid
|
HelmholtzFluid
|
Reference EOS. |
required |
t
|
ArrayLike
|
Temperature (K). |
required |
p
|
ArrayLike
|
Pressure (Pa). |
required |
phase
|
str
|
|
'supercritical'
|
Returns:
| Type | Description |
|---|---|
Array
|
The converged molar density; differentiable in |
Array
|
EOS coefficients via the implicit function theorem. For states near |
Array
|
the critical point (within ~0.1% of |
Array
|
bracketed branch. |
has_reference_fluid
¶
Whether reference_fluid knows the named fluid.
reference_fluid
¶
reference_fluid(name: str) -> HelmholtzFluid
The reference Helmholtz EOS for a named fluid.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
name
|
str
|
Fugacio component name ( |
required |
Returns:
| Type | Description |
|---|---|
HelmholtzFluid
|
The cached |
Raises:
| Type | Description |
|---|---|
KeyError
|
If no reference EOS is vendored for the name (see
|
reference_fluid_names
¶
Names of every fluid with a vendored reference EOS, sorted.
water_thermal_conductivity
¶
Thermal conductivity of water (W/m/K) at t (K) and molar density rho (mol/m^3).
IAPWS R15-11 including the critical enhancement; the correlation length is
built from autodiff compressibilities of IAPWS-95 and the enhancement's
cp, cv and (non-enhanced) viscosity come from the same graph.
water_viscosity
¶
Viscosity of water (Pa*s) at t (K) and molar density rho (mol/m^3).
IAPWS R12-08 including the critical enhancement, with the required
(d rho/d P)_T derivatives taken from IAPWS-95 by autodiff.
compressibility_factor
¶
compressibility_factor(
fluid: HelmholtzFluid, rho: ArrayLike, t: ArrayLike
) -> Array
Compressibility factor Z = P/(rho R T).
enthalpy
¶
enthalpy(
fluid: HelmholtzFluid, rho: ArrayLike, t: ArrayLike
) -> Array
Molar enthalpy (J/mol) on the fluid's published reference state.
entropy
¶
entropy(
fluid: HelmholtzFluid, rho: ArrayLike, t: ArrayLike
) -> Array
Molar entropy (J/mol/K) on the fluid's published reference state.
fugacity
¶
fugacity(
fluid: HelmholtzFluid, rho: ArrayLike, t: ArrayLike
) -> Array
Fugacity f = phi * P (Pa) of the pure fluid.
gibbs_energy
¶
gibbs_energy(
fluid: HelmholtzFluid, rho: ArrayLike, t: ArrayLike
) -> Array
Molar Gibbs energy (J/mol); equal in both phases at saturation.
helmholtz_energy
¶
helmholtz_energy(
fluid: HelmholtzFluid, rho: ArrayLike, t: ArrayLike
) -> Array
Molar Helmholtz energy a = R T alpha (J/mol).
internal_energy
¶
internal_energy(
fluid: HelmholtzFluid, rho: ArrayLike, t: ArrayLike
) -> Array
Molar internal energy (J/mol).
isobaric_expansivity
¶
isobaric_expansivity(
fluid: HelmholtzFluid, rho: ArrayLike, t: ArrayLike
) -> Array
Volumetric thermal expansion coefficient alpha_V = (dV/dT)_P / V (1/K).
isobaric_heat_capacity
¶
isobaric_heat_capacity(
fluid: HelmholtzFluid, rho: ArrayLike, t: ArrayLike
) -> Array
Molar isobaric heat capacity cp (J/mol/K); diverges at the critical point.
isochoric_heat_capacity
¶
isochoric_heat_capacity(
fluid: HelmholtzFluid, rho: ArrayLike, t: ArrayLike
) -> Array
Molar isochoric heat capacity cv (J/mol/K).
isothermal_compressibility
¶
isothermal_compressibility(
fluid: HelmholtzFluid, rho: ArrayLike, t: ArrayLike
) -> Array
Isothermal compressibility kappa_T = -(dV/dP)_T / V (1/Pa).
joule_thomson
¶
joule_thomson(
fluid: HelmholtzFluid, rho: ArrayLike, t: ArrayLike
) -> Array
Joule-Thomson coefficient (dT/dP)_h (K/Pa).
ln_fugacity_coefficient
¶
ln_fugacity_coefficient(
fluid: HelmholtzFluid, rho: ArrayLike, t: ArrayLike
) -> Array
Log fugacity coefficient ln(phi) = ar + Z - 1 - ln(Z) of the pure fluid.
pressure
¶
pressure(
fluid: HelmholtzFluid, rho: ArrayLike, t: ArrayLike
) -> Array
Pressure (Pa) at molar density rho (mol/m^3) and t (K).
second_virial
¶
second_virial(fluid: HelmholtzFluid, t: ArrayLike) -> Array
Second virial coefficient B(T) = ar_d(delta -> 0) / rho_reducing (m^3/mol).
speed_of_sound
¶
speed_of_sound(
fluid: HelmholtzFluid, rho: ArrayLike, t: ArrayLike
) -> Array
Speed of sound (m/s).
third_virial
¶
third_virial(fluid: HelmholtzFluid, t: ArrayLike) -> Array
Third virial coefficient C(T) = ar_dd(delta -> 0) / rho_reducing^2 (m6/mol2).
Evaluated at a vanishing reduced density rather than exactly zero: the
second power-rule derivative of the d = 1 terms is the indeterminate
0 * delta**-1 at the origin, which autodiff cannot cancel symbolically.
The offset changes the result by O(1e-12).
psat_ancillary
¶
psat_ancillary(
fluid: HelmholtzFluid, t: ArrayLike
) -> Array
Ancillary (initial-guess) saturation pressure (Pa).
rho_liquid_ancillary
¶
rho_liquid_ancillary(
fluid: HelmholtzFluid, t: ArrayLike
) -> Array
Ancillary saturated-liquid molar density (mol/m^3).
rho_vapor_ancillary
¶
rho_vapor_ancillary(
fluid: HelmholtzFluid, t: ArrayLike
) -> Array
Ancillary saturated-vapor molar density (mol/m^3).
saturation_densities
¶
saturation_densities(
fluid: HelmholtzFluid, t: ArrayLike
) -> tuple[Array, Array]
Coexisting molar densities (rho_liquid, rho_vapor) at t (K).
Valid for t_triple <= t < t_critical (callers should clip; the Newton
Jacobian degenerates at the critical point where both densities merge).
Differentiable in t and the EOS coefficients.
saturation_pressure
¶
saturation_pressure(
fluid: HelmholtzFluid, t: ArrayLike
) -> Array
Saturation pressure (Pa) from the Maxwell construction at t (K).
saturation_state
¶
saturation_state(
fluid: HelmholtzFluid,
*,
t: ArrayLike | None = None,
p: ArrayLike | None = None,
) -> SaturationState
The coexistence state at a given temperature or pressure.
Exactly one of t (K) or p (Pa) must be supplied; the other is
solved from the Maxwell construction. All returned fields are
differentiable with respect to the given specification.
saturation_temperature
¶
saturation_temperature(
fluid: HelmholtzFluid, p: ArrayLike
) -> Array
Saturation (boiling) temperature (K) at pressure p (Pa).
Valid for p_triple <= p < p_critical (callers should clip).
Differentiable in p and the EOS coefficients.
state_ph
¶
state_ph(
fluid: HelmholtzFluid, p: ArrayLike, h: ArrayLike
) -> FluidState
The state at pressure p (Pa) and molar enthalpy h (J/mol).
Inside the vapor-liquid dome the result has two_phase=True, the
saturation temperature, and the vapor quality q = (h - h')/(h'' - h');
outside it the temperature solves h(T, P) = h on the stable branch
(enthalpy is strictly increasing in T at fixed P, so the bracketed
solve is unconditionally convergent within the EOS range).
state_pq
¶
state_pq(
fluid: HelmholtzFluid, p: ArrayLike, q: ArrayLike
) -> FluidState
The two-phase state at saturation pressure p (Pa) and quality q.
state_ps
¶
state_ps(
fluid: HelmholtzFluid, p: ArrayLike, s: ArrayLike
) -> FluidState
The state at pressure p (Pa) and molar entropy s (J/mol/K).
The isentropic twin of state_ph, the building block of ideal
compressor/turbine outlets. Same dome semantics.
state_tp
¶
state_tp(
fluid: HelmholtzFluid,
t: ArrayLike,
p: ArrayLike,
*,
phase: str = "auto",
) -> FluidState
The single-phase state at temperature t (K) and pressure p (Pa).
With phase="auto" the stable branch is chosen by comparing p
against the solved saturation pressure (subcritical) or by a bracketed
density solve (supercritical). Pass "liquid" / "vapor" /
"supercritical" to skip the saturation solve when the branch is known,
or to evaluate a metastable branch on purpose.
state_tq
¶
state_tq(
fluid: HelmholtzFluid, t: ArrayLike, q: ArrayLike
) -> FluidState
The two-phase state at saturation temperature t (K) and quality q.
surface_tension
¶
surface_tension(
fluid: HelmholtzFluid, t: ArrayLike
) -> Array
Vapor-liquid surface tension (N/m) at t (K); zero at and above Tc.
alpha_derivatives
¶
alpha_derivatives(
fluid: HelmholtzFluid, rho: ArrayLike, t: ArrayLike
) -> AlphaDerivatives
All alpha partials at molar density rho (mol/m^3) and t (K).
First derivatives come from one reverse pass over the packed
(delta, tau) vector; second derivatives from one forward-over-reverse
Hessian. Nothing is hand-derived.
ideal_alpha
¶
ideal_alpha(
fluid: HelmholtzFluid, delta: ArrayLike, tau: ArrayLike
) -> Array
Ideal-gas part alpha0(delta, tau) of the reduced Helmholtz energy.
residual_alpha
¶
residual_alpha(
fluid: HelmholtzFluid, delta: ArrayLike, tau: ArrayLike
) -> Array
Residual part alphar(delta, tau) of the reduced Helmholtz energy.