Skip to content

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 rho(T, P) for a reference Helmholtz EOS.

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 (rho, T).

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 alpha(delta, tau) and its derivatives by autodiff.

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 alpha that every property formula needs.

Functions:

Name Description
molar_density

Molar density rho(T, P) (mol/m^3) on the requested branch.

has_reference_fluid

Whether reference_fluid knows the named fluid.

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 t (K) and molar density rho (mol/m^3).

water_viscosity

Viscosity of water (Pa*s) at t (K) and molar density rho (mol/m^3).

compressibility_factor

Compressibility factor Z = P/(rho R T).

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 f = phi * P (Pa) of the pure fluid.

gibbs_energy

Molar Gibbs energy (J/mol); equal in both phases at saturation.

helmholtz_energy

Molar Helmholtz energy a = R T alpha (J/mol).

internal_energy

Molar internal energy (J/mol).

isobaric_expansivity

Volumetric thermal expansion coefficient alpha_V = (dV/dT)_P / V (1/K).

isobaric_heat_capacity

Molar isobaric heat capacity cp (J/mol/K); diverges at the critical point.

isochoric_heat_capacity

Molar isochoric heat capacity cv (J/mol/K).

isothermal_compressibility

Isothermal compressibility kappa_T = -(dV/dP)_T / V (1/Pa).

joule_thomson

Joule-Thomson coefficient (dT/dP)_h (K/Pa).

ln_fugacity_coefficient

Log fugacity coefficient ln(phi) = ar + Z - 1 - ln(Z) of the pure fluid.

pressure

Pressure (Pa) at molar density rho (mol/m^3) and t (K).

second_virial

Second virial coefficient B(T) = ar_d(delta -> 0) / rho_reducing (m^3/mol).

speed_of_sound

Speed of sound (m/s).

third_virial

Third virial coefficient C(T) = ar_dd(delta -> 0) / rho_reducing^2 (m6/mol2).

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 (rho_liquid, rho_vapor) at t (K).

saturation_pressure

Saturation pressure (Pa) from the Maxwell construction at t (K).

saturation_state

The coexistence state at a given temperature or pressure.

saturation_temperature

Saturation (boiling) temperature (K) at pressure p (Pa).

state_ph

The state at pressure p (Pa) and molar enthalpy h (J/mol).

state_pq

The two-phase state at saturation pressure p (Pa) and quality q.

state_ps

The state at pressure p (Pa) and molar entropy s (J/mol/K).

state_tp

The single-phase state at temperature t (K) and pressure p (Pa).

state_tq

The two-phase state at saturation temperature t (K) and quality q.

surface_tension

Vapor-liquid surface tension (N/m) at t (K); zero at and above Tc.

alpha_derivatives

All alpha partials at molar density rho (mol/m^3) and t (K).

ideal_alpha

Ideal-gas part alpha0(delta, tau) of the reduced Helmholtz energy.

residual_alpha

Residual part alphar(delta, tau) of the reduced Helmholtz energy.

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 theta.

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 Tc/T.

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 P/(rho R T).

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); nan in the dome.

cp Array

Molar isobaric heat capacity (J/mol/K); nan in the dome.

w Array

Speed of sound (m/s); nan in the dome.

q Array

Vapor quality (mole basis); nan for single-phase states.

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

"liquid" or "vapor" select the subcritical branch by seeding Newton from the saturated-liquid ancillary or the ideal gas; "supercritical" runs a bracketed bisection over the whole density range (robust whenever the isotherm is monotonic, i.e. above t_critical).

'supercritical'

Returns:

Type Description
Array

The converged molar density; differentiable in t, p, and the

Array

EOS coefficients via the implicit function theorem. For states near

Array

the critical point (within ~0.1% of t_critical) prefer the

Array

bracketed branch.

has_reference_fluid

has_reference_fluid(name: str) -> bool

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 ("water", "carbon dioxide", "R134a", ...) or a common alias ("steam", "co2"); case insensitive.

required

Returns:

Type Description
HelmholtzFluid

The cached HelmholtzFluid.

Raises:

Type Description
KeyError

If no reference EOS is vendored for the name (see reference_fluid_names).

reference_fluid_names

reference_fluid_names() -> tuple[str, ...]

Names of every fluid with a vendored reference EOS, sorted.

water_thermal_conductivity

water_thermal_conductivity(
    t: ArrayLike, rho: ArrayLike
) -> Array

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

water_viscosity(t: ArrayLike, rho: ArrayLike) -> Array

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.