Property packages¶

One object that owns phase equilibrium and energy for a set of components: the PropertyPackage protocol and its cubic, gamma-phi, PC-SAFT, and reference-fluid implementations, plus the generic two-phase properties, stability search, saturation points, and energy-specified flashes built on top of them. Every solve method has a checked _with_info form, and its value-only form returns NaN when the solve fails.

See the property-packages guide for the concepts and worked examples.

package ¶

Property packages: one object that owns phase equilibrium and energy.

A process simulator needs two things from its thermodynamics: "what splits?" (fugacities, K-values, flashes) and "how much energy?" (enthalpy, entropy, volume). A PropertyPackage answers both through one interface that every energy-balanced unit operation, the rigorous column, and the equation-oriented engine consume. It is implemented for all four method classes Fugacio carries:

CubicPackage: phi-phi on a cubic EOS (PR, SRK, RK, vdW), the default;
GammaPhiPackage: an activity-coefficient liquid (NRTL, UNIQUAC, Wilson, UNIFAC, ...) with an ideal or EOS vapour. Its liquid enthalpy is the pure-liquid enthalpies plus the excess enthalpy obtained by automatic differentiation of the excess Gibbs energy (Gibbs-Helmholtz), so heat of mixing comes for free and stays consistent with the activity coefficients themselves;
SAFTPackage: PC-SAFT with Wertheim association, residual properties from the temperature derivatives of the residual Helmholtz energy;
HelmholtzPackage: a pure reference fluid (IAPWS-95 water, Span-Wagner CO2, ...) wrapped as a one-component package, so steam and refrigerant loops can be simulated with reference-grade properties inside the same flowsheet engine.

One contract for every package. Each iterative calculation has a checked *_with_info method returning the best state and a fugacio.thermo.diagnostics.SolveReport: flash_pt_with_info, bubble_pressure_with_info, dew_pressure_with_info, bubble_temperature_with_info, dew_temperature_with_info, flash_ph_with_info, and flash_ps_with_info. The matching value-only method returns NaN whenever that report fails, so a failed or out-of-domain solve never returns a finite number. stability runs the shared tangent-plane search (fugacio.thermo.stability) on the package's own fugacity branches.

A new thermodynamic method plugs into the whole engine by subclassing _PackageBase and implementing the single-phase primitives (ln_phi, enthalpy, entropy, volume); every other method, including a generic flash, saturation solves, stability, and energy flashes, is derived from them and may be overridden with a faster specialized solver. Packages are registered JAX pytrees whose model parameters are differentiable leaves, so a flowsheet built on any of them is differentiable with respect to the thermodynamic parameters as well as the operating conditions.

Enthalpy and entropy are relative to the ideal-gas reference at T_REF / P_REF, except for HelmholtzPackage, whose reference is the one built into the published formulation. Only differences are physical, and any consistent reference cancels in a balance, so do not mix packages with different references across one energy balance.

Classes:

Name	Description
`EnergySolveResult`	A PH/PS flash state and its independently verified solve report.
`PropertyPackage`	Structural type of a property package (equilibrium + energy + volume).
`CubicPackage`	Phi-phi property package on a cubic equation of state.
`GammaPhiPackage`	Gamma-phi property package: activity-coefficient liquid, ideal or EOS vapour.
`SAFTPackage`	PC-SAFT property package (phi-phi on the molecular equation of state).
`HelmholtzPackage`	One-component package on a reference multiparameter Helmholtz EOS.

Functions:

Name	Description
`excess_enthalpy`	Excess (mixing) enthalpy `h^E = -R T^2 d(g^E/RT)/dT` (J/mol) by autodiff.
`excess_entropy`	Excess entropy `s^E = (h^E - g^E) / T` (J/mol/K).
`cubic_package`	Construct a `CubicPackage` from component constants and `Cp` coefficients.
`gamma_phi_package`	Construct a `GammaPhiPackage` from an activity model and component constants.
`saft_package`	Construct a `SAFTPackage` from PC-SAFT parameters, seeding constants, and `Cp`.
`helmholtz_package`	Wrap a reference fluid as a one-component `HelmholtzPackage`.
`energy_flash_report`	Verify an energy flash independently from its temperature iteration.

EnergySolveResult ¶

Bases: NamedTuple

A PH/PS flash state and its independently verified solve report.

PropertyPackage ¶

Bases: Protocol

Structural type of a property package (equilibrium + energy + volume).

Implementations bundle their component constants and model parameters, so callers pass only the state (T, P, composition). phase is "liquid" or "vapor" and selects the phase branch to evaluate. Subclassing _PackageBase supplies every derived method.

Methods:

Name	Description
`signature`	Hashable description of the package structure (not its values).
`ln_phi`	Log fugacity coefficients `ln phi_i` of the phase at `(T, P, x)`.
`enthalpy`	Single-phase molar enthalpy (J/mol).
`entropy`	Single-phase molar entropy (J/mol/K).
`volume`	Single-phase molar volume (m^3/mol).
`ln_phi_function`	A composition-only `ln phi` at fixed `(T, P)` for repeated trial evaluations.
`in_domain`	Whether the model is defined for the components present at `(T, P)`.
`k_values`	Equilibrium ratios `K_i = phi_i^L(x) / phi_i^V(y)`.
`k_seed`	Composition-light K-value estimate used to initialise solvers.
`flash_pt_with_info`	Isothermal-isobaric vapour-liquid flash and its report.
`flash_pt`	Isothermal-isobaric flash; NaN on failure.
`stability`	Tangent-plane stability of feed `z` at `(T, P)`.
`bubble_pressure_with_info`	Bubble pressure and incipient vapour at fixed `T`, `x`, with a report.
`bubble_pressure`	Bubble pressure and incipient vapour `(P, y)`; NaN on failure.
`dew_pressure_with_info`	Dew pressure and incipient liquid at fixed `T`, `y`, with a report.
`dew_pressure`	Dew pressure and incipient liquid `(P, x)`; NaN on failure.
`bubble_temperature_with_info`	Bubble temperature and incipient vapour at fixed `P`, `x`, with a report.
`bubble_temperature`	Bubble temperature and incipient vapour `(T, y)`; NaN on failure.
`dew_temperature_with_info`	Dew temperature and incipient liquid at fixed `P`, `y`, with a report.
`dew_temperature`	Dew temperature and incipient liquid `(T, x)`; NaN on failure.
`mixture_enthalpy`	Two-phase-aware molar enthalpy of a feed `z` at `(T, P)` (J/mol).
`mixture_entropy`	Two-phase-aware molar entropy of a feed `z` at `(T, P)` (J/mol/K).
`mixture_volume`	Two-phase-aware molar volume of a feed `z` at `(T, P)` (m^3/mol).
`flash_ph_with_info`	Isenthalpic flash with an independent energy and equilibrium report.
`flash_ph`	Isenthalpic flash; NaN on failure.
`flash_ps_with_info`	Isentropic flash with an independent entropy and equilibrium report.
`flash_ps`	Isentropic flash; NaN on failure.

Attributes:

Name	Type	Description
`component_names`	`tuple[str, ...]`	Canonical component names, in the package's composition order.
`evidence`	`PackageEvidence`	Parameter provenance and the observed ranges behind the package.
`n_components`	`int`	Number of components the package describes.

component_names `property` ¶

component_names: tuple[str, ...]

Canonical component names, in the package's composition order.

evidence `property` ¶

evidence: PackageEvidence

Parameter provenance and the observed ranges behind the package.

n_components `property` ¶

n_components: int

Number of components the package describes.

signature ¶

signature() -> tuple[Any, ...]

Hashable description of the package structure (not its values).

ln_phi ¶

ln_phi(
    t: ArrayLike, p: ArrayLike, x: Array, *, phase: str
) -> Array

Log fugacity coefficients ln phi_i of the phase at (T, P, x).

enthalpy ¶

enthalpy(
    t: ArrayLike, p: ArrayLike, x: Array, *, phase: str
) -> Array

Single-phase molar enthalpy (J/mol).

entropy ¶

entropy(
    t: ArrayLike, p: ArrayLike, x: Array, *, phase: str
) -> Array

Single-phase molar entropy (J/mol/K).

volume ¶

volume(
    t: ArrayLike, p: ArrayLike, x: Array, *, phase: str
) -> Array

Single-phase molar volume (m^3/mol).

ln_phi_function ¶

ln_phi_function(
    t: ArrayLike, p: ArrayLike, *, phase: str
) -> LnPhiFn

A composition-only ln phi at fixed (T, P) for repeated trial evaluations.

in_domain ¶

in_domain(t: ArrayLike, p: ArrayLike, z: Array) -> Array

Whether the model is defined for the components present at (T, P).

k_values ¶

k_values(
    t: ArrayLike, p: ArrayLike, x: Array, y: Array
) -> Array

Equilibrium ratios K_i = phi_i^L(x) / phi_i^V(y).

k_seed ¶

k_seed(t: ArrayLike, p: ArrayLike, x: Array) -> Array

Composition-light K-value estimate used to initialise solvers.

flash_pt_with_info ¶

flash_pt_with_info(
    t: ArrayLike, p: ArrayLike, z: Array
) -> FlashSolveResult

Isothermal-isobaric vapour-liquid flash and its report.

flash_pt ¶

flash_pt(
    t: ArrayLike, p: ArrayLike, z: Array
) -> FlashResult

Isothermal-isobaric flash; NaN on failure.

stability ¶

stability(
    t: ArrayLike, p: ArrayLike, z: Array
) -> StabilityResult

Tangent-plane stability of feed z at (T, P).

bubble_pressure_with_info ¶

bubble_pressure_with_info(
    t: ArrayLike, x: Array
) -> SaturationSolveResult

Bubble pressure and incipient vapour at fixed T, x, with a report.

bubble_pressure ¶

bubble_pressure(t: ArrayLike, x: Array) -> SaturationResult

Bubble pressure and incipient vapour (P, y); NaN on failure.

dew_pressure_with_info ¶

dew_pressure_with_info(
    t: ArrayLike, y: Array
) -> SaturationSolveResult

Dew pressure and incipient liquid at fixed T, y, with a report.

dew_pressure ¶

dew_pressure(t: ArrayLike, y: Array) -> SaturationResult

Dew pressure and incipient liquid (P, x); NaN on failure.

bubble_temperature_with_info ¶

bubble_temperature_with_info(
    p: ArrayLike,
    x: Array,
    *,
    t_min: ArrayLike | None = None,
    t_max: ArrayLike | None = None,
) -> SaturationSolveResult

Bubble temperature and incipient vapour at fixed P, x, with a report.

bubble_temperature ¶

bubble_temperature(
    p: ArrayLike,
    x: Array,
    *,
    t_min: ArrayLike | None = None,
    t_max: ArrayLike | None = None,
) -> SaturationResult

Bubble temperature and incipient vapour (T, y); NaN on failure.

dew_temperature_with_info ¶

dew_temperature_with_info(
    p: ArrayLike,
    y: Array,
    *,
    t_min: ArrayLike | None = None,
    t_max: ArrayLike | None = None,
) -> SaturationSolveResult

Dew temperature and incipient liquid at fixed P, y, with a report.

dew_temperature ¶

dew_temperature(
    p: ArrayLike,
    y: Array,
    *,
    t_min: ArrayLike | None = None,
    t_max: ArrayLike | None = None,
) -> SaturationResult

Dew temperature and incipient liquid (T, x); NaN on failure.

mixture_enthalpy ¶

mixture_enthalpy(
    t: ArrayLike, p: ArrayLike, z: Array
) -> Array

Two-phase-aware molar enthalpy of a feed z at (T, P) (J/mol).

mixture_entropy ¶

mixture_entropy(
    t: ArrayLike, p: ArrayLike, z: Array
) -> Array

Two-phase-aware molar entropy of a feed z at (T, P) (J/mol/K).

mixture_volume ¶

mixture_volume(
    t: ArrayLike, p: ArrayLike, z: Array
) -> Array

Two-phase-aware molar volume of a feed z at (T, P) (m^3/mol).

flash_ph_with_info ¶

flash_ph_with_info(
    p: ArrayLike,
    h: ArrayLike,
    z: Array,
    *,
    t_init: ArrayLike = ...,
    t_min: float = ...,
    t_max: float = ...,
    tol: float = ...,
    max_iter: int = ...,
) -> EnergySolveResult

Isenthalpic flash with an independent energy and equilibrium report.

flash_ph ¶

flash_ph(
    p: ArrayLike, h: ArrayLike, z: Array, **options: Any
) -> EnergyFlashResult

Isenthalpic flash; NaN on failure.

flash_ps_with_info ¶

flash_ps_with_info(
    p: ArrayLike,
    s: ArrayLike,
    z: Array,
    *,
    t_init: ArrayLike = ...,
    t_min: float = ...,
    t_max: float = ...,
    tol: float = ...,
    max_iter: int = ...,
) -> EnergySolveResult

Isentropic flash with an independent entropy and equilibrium report.

flash_ps ¶

flash_ps(
    p: ArrayLike, s: ArrayLike, z: Array, **options: Any
) -> EnergyFlashResult

Isentropic flash; NaN on failure.

CubicPackage `dataclass` ¶

CubicPackage(
    tc: Array,
    pc: Array,
    omega: Array,
    cp: CpCoeffs,
    kij: Array | None = None,
    eos: CubicEOS = PR,
    component_names: tuple[str, ...] = (),
    evidence: PackageEvidence = PackageEvidence(),
)

Bases: _PackageBase

Phi-phi property package on a cubic equation of state.

Attributes:

Name	Type	Description
`tc`	`Array`	Critical temperatures (K).
`pc`	`Array`	Critical pressures (Pa).
`omega`	`Array`	Acentric factors.
`cp`	`CpCoeffs`	Ideal-gas heat-capacity coefficient arrays `(a, b, c, d, e)`.
`kij`	`Array \| None`	Binary interaction matrix (`None` means zeros).
`eos`	`CubicEOS`	Cubic equation of state (static; default Peng-Robinson).

Methods:

Name	Description
`signature`	Class, component count, cubic, and whether a `kij` matrix is present.
`ln_phi`	Log fugacity coefficients from the cubic EOS.
`enthalpy`	Ideal-gas enthalpy plus the cubic residual enthalpy (J/mol).
`entropy`	Ideal-gas entropy (with mixing) plus the cubic residual entropy (J/mol/K).
`volume`	Molar volume `Z R T / P` on the requested cubic root (m^3/mol).
`flash_pt_with_info`	Isothermal-isobaric vapour-liquid flash via the cubic EOS.
`bubble_pressure_with_info`	Bubble pressure and incipient vapour at fixed `T`, `x`, with a report.
`dew_pressure_with_info`	Dew pressure and incipient liquid at fixed `T`, `y`, with a report.

n_components `property` ¶

n_components: int

Number of components.

signature ¶

signature() -> tuple[Any, ...]

Class, component count, cubic, and whether a kij matrix is present.

ln_phi ¶

ln_phi(
    t: ArrayLike, p: ArrayLike, x: Array, *, phase: str
) -> Array

Log fugacity coefficients from the cubic EOS.

enthalpy ¶

enthalpy(
    t: ArrayLike, p: ArrayLike, x: Array, *, phase: str
) -> Array

Ideal-gas enthalpy plus the cubic residual enthalpy (J/mol).

entropy ¶

entropy(
    t: ArrayLike, p: ArrayLike, x: Array, *, phase: str
) -> Array

Ideal-gas entropy (with mixing) plus the cubic residual entropy (J/mol/K).

volume ¶

volume(
    t: ArrayLike, p: ArrayLike, x: Array, *, phase: str
) -> Array

Molar volume Z R T / P on the requested cubic root (m^3/mol).

flash_pt_with_info ¶

flash_pt_with_info(
    t: ArrayLike,
    p: ArrayLike,
    z: Array,
    *,
    tol: float = 1e-12,
    max_iter: int = 300,
) -> FlashSolveResult

Isothermal-isobaric vapour-liquid flash via the cubic EOS.

bubble_pressure_with_info ¶

bubble_pressure_with_info(
    t: ArrayLike, x: Array
) -> SaturationSolveResult

Bubble pressure and incipient vapour at fixed T, x, with a report.

dew_pressure_with_info ¶

dew_pressure_with_info(
    t: ArrayLike, y: Array
) -> SaturationSolveResult

Dew pressure and incipient liquid at fixed T, y, with a report.

GammaPhiPackage `dataclass` ¶

GammaPhiPackage(
    activity: ActivityModel,
    tc: Array,
    pc: Array,
    omega: Array,
    cp: CpCoeffs,
    kij: Array | None = None,
    eos: CubicEOS = PR,
    vapor: str = "ideal",
    poynting: bool = False,
    phi_saturation: bool = False,
    component_names: tuple[str, ...] = (),
    evidence: PackageEvidence = PackageEvidence(),
)

Bases: _PackageBase

Gamma-phi property package: activity-coefficient liquid, ideal or EOS vapour.

The liquid fugacity is x_i gamma_i f_i^{0,L}(T, P) (see fugacio.thermo.reference), expressed here as an effective liquid fugacity coefficient phi_i^L = gamma_i f_i^{0,L} / P so the package presents the same ln_phi interface as the phi-phi routes. The liquid enthalpy is

h^L(T, P, x) = sum_i x_i h_i^{L,pure}(T, P) + h^E(T, x)

with each pure-liquid enthalpy taken from the cubic EOS at that component's saturation point (plus the small v_i^L (P - Psat_i) pressure term that partners the Poynting factor) and the excess enthalpy from excess_enthalpy (autodiff Gibbs-Helmholtz on the activity model). The liquid entropy follows the same construction with the ideal entropy of mixing and s^E.

The saturation-based reference exists only below each component's critical temperature: a state with a present supercritical component is out of the package's domain (every checked calculation reports OUT_OF_DOMAIN).

Attributes:

Name	Type	Description
`activity`	`ActivityModel`	Liquid activity-coefficient model (a differentiable pytree).
`tc`	`Array`	Critical temperatures (K).
`pc`	`Array`	Critical pressures (Pa).
`omega`	`Array`	Acentric factors.
`cp`	`CpCoeffs`	Ideal-gas heat-capacity coefficient arrays `(a, b, c, d, e)`.
`kij`	`Array \| None`	Binary interaction matrix for an EOS vapour (`None` means zeros).
`eos`	`CubicEOS`	Cubic EOS used for the saturation reference and, if selected, the vapour.
`vapor`	`str`	`"ideal"` (phi^V = 1) or `"eos"` (static).
`poynting`	`bool`	Include the Poynting correction in the reference (static).
`phi_saturation`	`bool`	Include the saturation fugacity coefficient (static).

Methods:

Name	Description
`signature`	Class, component count, activity-model class, and the static flags.
`in_domain`	Every present component must have a saturation reference at `T`.
`ln_phi`	Effective `ln phi`: `ln gamma + ln f^{0,L} - ln P` (liquid) or the vapour model.
`ln_phi_function`	Liquid trials reuse one reference fugacity; only `ln gamma` varies.
`enthalpy`	Liquid: pure saturated-liquid enthalpies plus `h^E`; vapour: ideal gas (+ EOS).
`entropy`	Liquid: saturated-liquid entropies, ideal mixing, `s^E`; vapour: ideal gas (+ EOS).
`volume`	Liquid: mole-fraction sum of pure saturated-liquid volumes; vapour: ideal gas or EOS.
`flash_pt_with_info`	Isothermal-isobaric gamma-phi flash.
`k_seed`	`gamma_i(x) Psat_i / P`: the modified Raoult K-values (ideal vapour).
`bubble_pressure_with_info`	Bubble pressure and incipient vapour at fixed `T`, `x`, with a report.
`dew_pressure_with_info`	Dew pressure and incipient liquid at fixed `T`, `y`, with a report.
`bubble_temperature_with_info`	Bubble temperature and incipient vapour (native gamma-phi solve).
`dew_temperature_with_info`	Dew temperature and incipient liquid (native gamma-phi solve).

n_components `property` ¶

n_components: int

Number of components.

signature ¶

signature() -> tuple[Any, ...]

Class, component count, activity-model class, and the static flags.

in_domain ¶

in_domain(t: ArrayLike, p: ArrayLike, z: Array) -> Array

Every present component must have a saturation reference at T.

ln_phi ¶

ln_phi(
    t: ArrayLike, p: ArrayLike, x: Array, *, phase: str
) -> Array

Effective ln phi: ln gamma + ln f^{0,L} - ln P (liquid) or the vapour model.

ln_phi_function ¶

ln_phi_function(
    t: ArrayLike, p: ArrayLike, *, phase: str
) -> LnPhiFn

Liquid trials reuse one reference fugacity; only ln gamma varies.

enthalpy ¶

enthalpy(
    t: ArrayLike, p: ArrayLike, x: Array, *, phase: str
) -> Array

Liquid: pure saturated-liquid enthalpies plus h^E; vapour: ideal gas (+ EOS).

entropy ¶

entropy(
    t: ArrayLike, p: ArrayLike, x: Array, *, phase: str
) -> Array

Liquid: saturated-liquid entropies, ideal mixing, s^E; vapour: ideal gas (+ EOS).

volume ¶

volume(
    t: ArrayLike, p: ArrayLike, x: Array, *, phase: str
) -> Array

Liquid: mole-fraction sum of pure saturated-liquid volumes; vapour: ideal gas or EOS.

flash_pt_with_info ¶

flash_pt_with_info(
    t: ArrayLike,
    p: ArrayLike,
    z: Array,
    *,
    tol: float = 1e-12,
    max_iter: int = 300,
) -> FlashSolveResult

Isothermal-isobaric gamma-phi flash.

k_seed ¶

k_seed(t: ArrayLike, p: ArrayLike, x: Array) -> Array

gamma_i(x) Psat_i / P: the modified Raoult K-values (ideal vapour).

bubble_pressure_with_info ¶

bubble_pressure_with_info(
    t: ArrayLike, x: Array
) -> SaturationSolveResult

Bubble pressure and incipient vapour at fixed T, x, with a report.

dew_pressure_with_info ¶

dew_pressure_with_info(
    t: ArrayLike, y: Array
) -> SaturationSolveResult

Dew pressure and incipient liquid at fixed T, y, with a report.

bubble_temperature_with_info ¶

bubble_temperature_with_info(
    p: ArrayLike,
    x: Array,
    *,
    t_min: ArrayLike | None = None,
    t_max: ArrayLike | None = None,
) -> SaturationSolveResult

Bubble temperature and incipient vapour (native gamma-phi solve).

dew_temperature_with_info ¶

dew_temperature_with_info(
    p: ArrayLike,
    y: Array,
    *,
    t_min: ArrayLike | None = None,
    t_max: ArrayLike | None = None,
) -> SaturationSolveResult

Dew temperature and incipient liquid (native gamma-phi solve).

SAFTPackage `dataclass` ¶

SAFTPackage(
    params: SaftParameters,
    tc: Array,
    pc: Array,
    omega: Array,
    cp: CpCoeffs,
    component_names: tuple[str, ...] = (),
    evidence: PackageEvidence = PackageEvidence(),
)

Bases: _PackageBase

PC-SAFT property package (phi-phi on the molecular equation of state).

Residual enthalpy and entropy come from the temperature derivatives of the reduced residual Helmholtz energy (fugacio.thermo.saft.properties), so association effects on the heat of mixing and vaporisation are captured.

Attributes:

Name	Type	Description
`params`	`SaftParameters`	PC-SAFT parameter set (a differentiable pytree).
`tc`	`Array`	Critical temperatures (K), used to seed the flash K-values.
`pc`	`Array`	Critical pressures (Pa), used to seed the flash K-values.
`omega`	`Array`	Acentric factors, used to seed the flash K-values.
`cp`	`CpCoeffs`	Ideal-gas heat-capacity coefficient arrays `(a, b, c, d, e)`.

Methods:

Name	Description
`signature`	Class and component count.
`ln_phi`	Log fugacity coefficients on the PC-SAFT density branch `phase`.
`enthalpy`	Ideal-gas enthalpy plus the PC-SAFT residual enthalpy (J/mol).
`entropy`	Ideal-gas entropy (with mixing) plus the PC-SAFT residual entropy (J/mol/K).
`volume`	Molar volume `1 / rho` on the requested density branch (m^3/mol).
`flash_pt_with_info`	Isothermal-isobaric vapour-liquid flash via PC-SAFT.
`bubble_pressure_with_info`	Bubble pressure and incipient vapour at fixed `T`, `x`, with a report.
`dew_pressure_with_info`	Dew pressure and incipient liquid at fixed `T`, `y`, with a report.

n_components `property` ¶

n_components: int

Number of components.

signature ¶

signature() -> tuple[Any, ...]

Class and component count.

ln_phi ¶

ln_phi(
    t: ArrayLike, p: ArrayLike, x: Array, *, phase: str
) -> Array

Log fugacity coefficients on the PC-SAFT density branch phase.

enthalpy ¶

enthalpy(
    t: ArrayLike, p: ArrayLike, x: Array, *, phase: str
) -> Array

Ideal-gas enthalpy plus the PC-SAFT residual enthalpy (J/mol).

entropy ¶

entropy(
    t: ArrayLike, p: ArrayLike, x: Array, *, phase: str
) -> Array

Ideal-gas entropy (with mixing) plus the PC-SAFT residual entropy (J/mol/K).

volume ¶

volume(
    t: ArrayLike, p: ArrayLike, x: Array, *, phase: str
) -> Array

Molar volume 1 / rho on the requested density branch (m^3/mol).

flash_pt_with_info ¶

flash_pt_with_info(
    t: ArrayLike,
    p: ArrayLike,
    z: Array,
    *,
    tol: float = 1e-12,
    max_iter: int = 300,
) -> FlashSolveResult

Isothermal-isobaric vapour-liquid flash via PC-SAFT.

bubble_pressure_with_info ¶

bubble_pressure_with_info(
    t: ArrayLike, x: Array
) -> SaturationSolveResult

Bubble pressure and incipient vapour at fixed T, x, with a report.

dew_pressure_with_info ¶

dew_pressure_with_info(
    t: ArrayLike, y: Array
) -> SaturationSolveResult

Dew pressure and incipient liquid at fixed T, y, with a report.

HelmholtzPackage `dataclass` ¶

HelmholtzPackage(
    fluid: HelmholtzFluid,
    component_names: tuple[str, ...] = (),
    evidence: PackageEvidence = PackageEvidence(),
)

Bases: _PackageBase

One-component package on a reference multiparameter Helmholtz EOS.

Wraps a fugacio.thermo.helmholtz.HelmholtzFluid (IAPWS-95 water, Span-Wagner CO2, ...) so a pure utility or working fluid can flow through the ordinary unit operations with reference-grade properties. Compositions are the one-element vector [1.0]; the "flash" is the saturation-line test of a pure substance (vapour fraction 0 or 1 away from the dome), and the energy flashes resolve directly to the steam-table state functions state_ph / state_ps, including the quality inside the dome.

Enthalpy and entropy carry the reference state of the published formulation (not the ideal-gas T_REF reference of the mixture packages).

Attributes:

Name	Type	Description
`fluid`	`HelmholtzFluid`	The reference fluid.

Methods:

Name	Description
`signature`	Class and fluid name.
`ln_phi`	Pure-fluid `ln phi` on the requested density branch, as a length-1 vector.
`enthalpy`	Molar enthalpy on the requested branch (J/mol).
`entropy`	Molar entropy on the requested branch (J/mol/K).
`volume`	Molar volume `1 / rho` on the requested branch (m^3/mol).
`in_domain`	Within the published range of the formulation.
`flash_pt_with_info`	Pure-fluid phase test: all vapour below `Psat(T)` (or above `Tc`), else liquid.
`stability`	A pure fluid is stable on its lower-Gibbs branch; the test compares the branches.
`k_seed`	`Psat(T) / P` as a length-1 vector.
`mixture_enthalpy`	Stable-branch molar enthalpy at `(T, P)` (J/mol).
`mixture_entropy`	Stable-branch molar entropy at `(T, P)` (J/mol/K).
`mixture_volume`	Stable-branch molar volume at `(T, P)` (m^3/mol).
`flash_ph_with_info`	Steam-table `(P, h)` state, with an independent verification report.
`flash_ps_with_info`	Steam-table `(P, s)` state, with an independent verification report.
`bubble_pressure_with_info`	Saturation pressure at `T` (pure fluid), with a report.
`dew_pressure_with_info`	Saturation pressure at `T` (pure fluid), with a report.
`bubble_temperature_with_info`	Saturation temperature at `P` (pure fluid), with a report.
`dew_temperature_with_info`	Saturation temperature at `P` (pure fluid), with a report.

n_components `property` ¶

n_components: int

Always one.

signature ¶

signature() -> tuple[Any, ...]

Class and fluid name.

ln_phi ¶

ln_phi(
    t: ArrayLike, p: ArrayLike, x: Array, *, phase: str
) -> Array

Pure-fluid ln phi on the requested density branch, as a length-1 vector.

enthalpy ¶

enthalpy(
    t: ArrayLike, p: ArrayLike, x: Array, *, phase: str
) -> Array

Molar enthalpy on the requested branch (J/mol).

entropy ¶

entropy(
    t: ArrayLike, p: ArrayLike, x: Array, *, phase: str
) -> Array

Molar entropy on the requested branch (J/mol/K).

volume ¶

volume(
    t: ArrayLike, p: ArrayLike, x: Array, *, phase: str
) -> Array

Molar volume 1 / rho on the requested branch (m^3/mol).

in_domain ¶

in_domain(t: ArrayLike, p: ArrayLike, z: Array) -> Array

Within the published range of the formulation.

flash_pt_with_info ¶

flash_pt_with_info(
    t: ArrayLike,
    p: ArrayLike,
    z: Array,
    *,
    tol: float = 1e-12,
    max_iter: int = 300,
) -> FlashSolveResult

Pure-fluid phase test: all vapour below Psat(T) (or above Tc), else liquid.

Exactly on the saturation line a PT specification can't fix the phase amounts; use a PH/PS specification (or a stream's retained inventory).

stability ¶

stability(
    t: ArrayLike,
    p: ArrayLike,
    z: Array,
    *,
    iterations: int = 160,
    tol: float = 1e-07,
) -> StabilityResult

A pure fluid is stable on its lower-Gibbs branch; the test compares the branches.

k_seed ¶

k_seed(t: ArrayLike, p: ArrayLike, x: Array) -> Array

Psat(T) / P as a length-1 vector.

mixture_enthalpy ¶

mixture_enthalpy(
    t: ArrayLike, p: ArrayLike, z: Array
) -> Array

Stable-branch molar enthalpy at (T, P) (J/mol).

mixture_entropy ¶

mixture_entropy(
    t: ArrayLike, p: ArrayLike, z: Array
) -> Array

Stable-branch molar entropy at (T, P) (J/mol/K).

mixture_volume ¶

mixture_volume(
    t: ArrayLike, p: ArrayLike, z: Array
) -> Array

Stable-branch molar volume at (T, P) (m^3/mol).

flash_ph_with_info ¶

flash_ph_with_info(
    p: ArrayLike,
    h: ArrayLike,
    z: Array,
    *,
    t_init: ArrayLike = 300.0,
    t_min: float = 50.0,
    t_max: float = 1500.0,
    tol: float = 1e-08,
    max_iter: int = 100,
) -> EnergySolveResult

Steam-table (P, h) state, with an independent verification report.

The reference-fluid state functions initialize themselves, so the iteration options of the mixture packages are accepted but unused.

flash_ps_with_info ¶

flash_ps_with_info(
    p: ArrayLike,
    s: ArrayLike,
    z: Array,
    *,
    t_init: ArrayLike = 300.0,
    t_min: float = 50.0,
    t_max: float = 1500.0,
    tol: float = 1e-08,
    max_iter: int = 100,
) -> EnergySolveResult

Steam-table (P, s) state, with an independent verification report.

bubble_pressure_with_info ¶

bubble_pressure_with_info(
    t: ArrayLike, x: Array
) -> SaturationSolveResult

Saturation pressure at T (pure fluid), with a report.

dew_pressure_with_info ¶

dew_pressure_with_info(
    t: ArrayLike, y: Array
) -> SaturationSolveResult

Saturation pressure at T (pure fluid), with a report.

bubble_temperature_with_info ¶

bubble_temperature_with_info(
    p: ArrayLike,
    x: Array,
    *,
    t_min: ArrayLike | None = None,
    t_max: ArrayLike | None = None,
) -> SaturationSolveResult

Saturation temperature at P (pure fluid), with a report.

dew_temperature_with_info ¶

dew_temperature_with_info(
    p: ArrayLike,
    y: Array,
    *,
    t_min: ArrayLike | None = None,
    t_max: ArrayLike | None = None,
) -> SaturationSolveResult

Saturation temperature at P (pure fluid), with a report.

excess_enthalpy ¶

excess_enthalpy(
    activity: ActivityModel, x: Array, t: ArrayLike
) -> Array

Excess (mixing) enthalpy h^E = -R T^2 d(g^E/RT)/dT (J/mol) by autodiff.

The Gibbs-Helmholtz relation turns the temperature derivative of the excess Gibbs energy into the heat of mixing. Taking that derivative with automatic differentiation keeps h^E exactly consistent with the activity coefficients (and their temperature dependence), with no separate correlation to maintain.

Parameters:

Name	Type	Description	Default
`activity`	`ActivityModel`	Liquid activity-coefficient model.	required
`x`	`Array`	Liquid mole fractions.	required
`t`	`ArrayLike`	Temperature (K).	required

Returns:

Type	Description
`Array`	The molar excess enthalpy of the liquid mixture.

excess_entropy ¶

excess_entropy(
    activity: ActivityModel, x: Array, t: ArrayLike
) -> Array

Excess entropy s^E = (h^E - g^E) / T (J/mol/K).

cubic_package ¶

cubic_package(
    tc: Array,
    pc: Array,
    omega: Array,
    cp: CpCoeffs,
    *,
    kij: Array | None = None,
    eos: CubicEOS = PR,
) -> CubicPackage

Construct a CubicPackage from component constants and Cp coefficients.

gamma_phi_package ¶

gamma_phi_package(
    activity: ActivityModel,
    tc: Array,
    pc: Array,
    omega: Array,
    cp: CpCoeffs,
    *,
    kij: Array | None = None,
    eos: CubicEOS = PR,
    vapor: str = "ideal",
    poynting: bool = False,
    phi_saturation: bool = False,
) -> GammaPhiPackage

Construct a GammaPhiPackage from an activity model and component constants.

Raises:

Type	Description
`ValueError`	If `vapor` isn't `"ideal"` or `"eos"`.

saft_package ¶

saft_package(
    params: SaftParameters,
    tc: Array,
    pc: Array,
    omega: Array,
    cp: CpCoeffs,
) -> SAFTPackage

Construct a SAFTPackage from PC-SAFT parameters, seeding constants, and Cp.

helmholtz_package ¶

helmholtz_package(
    fluid: HelmholtzFluid,
) -> HelmholtzPackage

Wrap a reference fluid as a one-component HelmholtzPackage.

energy_flash_report ¶

energy_flash_report(
    pkg: PropertyPackage,
    result: EnergyFlashResult,
    p: ArrayLike,
    target: ArrayLike,
    z: Array,
    *,
    prop: str = "enthalpy",
    tol: float = 1e-07,
) -> SolveReport

Verify an energy flash independently from its temperature iteration.

The residual checks component closure, composition normalization, phase fractions, equifugacity of present phases, and the specified molar property. The iteration count is zero because this is a verification of the returned state, not its iteration log. A state outside the package's domain is OUT_OF_DOMAIN.

Consistency checks¶

Data-free thermodynamic identities, including the Gibbs-Helmholtz and fugacity-enthalpy checks that tie a package's energy side to its equilibrium side.

consistency ¶

First-principles thermodynamic consistency laws (data-free oracles).

These checks need no external reference data: they encode laws that any correct model must obey, and return a residual that should be zero (to numerical precision). They are the backbone of the README's "executable acceptance harness": thousands of small graded checks that anchor correctness as the engine grows.

Implemented laws:

partial_molar_symmetry_residual: the Gibbs-Duhem relation, expressed as the symmetry of the Hessian of n_T g^E (equivalently of the Jacobian of ln gamma_i, or ln phi_i, with respect to mole numbers). This holds at constant T, P for any model derived from a single Gibbs-energy surface.
equifugacity_residual: equality of component fugacities between phases at equilibrium, x_i phi_i^L = y_i phi_i^V.
fugacity_pressure_residual: the pure-fluid identity (d ln phi / dP)_T = (Z - 1) / P, a direct consequence of dG = V dP.
gibbs_helmholtz_residual: H = -T^2 (d(G/T)/dT)_P on one branch of a property package, which ties its enthalpy to its entropy.
fugacity_enthalpy_residual: H^V - H^L = -R T^2 d/dT sum_i x_i (ln phi_i^V - ln phi_i^L) for a property package, which ties the fugacity coefficients that decide phase equilibrium to the enthalpies that close energy balances.

Functions:

Name	Description
`partial_molar_symmetry_residual`	Gibbs-Duhem residual for a vector of log partial-molar coefficients.
`gibbs_duhem_residual`	Gibbs-Duhem residual for an activity-coefficient model (see module docs).
`equifugacity_residual`	Max equilibrium fugacity mismatch `\|ln(x_i phi_i^L) - ln(y_i phi_i^V)\|`.
`fugacity_pressure_residual`	Residual of the pure-fluid identity `(d ln phi / dP)_T = (Z - 1) / P`.
`gibbs_helmholtz_residual`	Relative residual of `H = -T^2 (d(G/T)/dT)_{P,x}` on one branch of a package.
`fugacity_enthalpy_residual`	Relative residual of `H^V - H^L = -R T^2 d/dT sum_i x_i (ln phi_i^V - ln phi_i^L)`.

partial_molar_symmetry_residual ¶

partial_molar_symmetry_residual(
    ln_coeff_fn: LogActivityFn, x: Array
) -> Array

Gibbs-Duhem residual for a vector of log partial-molar coefficients.

Given ln_coeff_fn mapping mole fractions to ln(gamma_i) (activity) or ln(phi_i) (fugacity, at fixed T, P), this forms the Jacobian with respect to mole numbers and returns the max-norm of its antisymmetric part. A thermodynamically consistent model gives zero (to machine precision), because the coefficients are first derivatives of one scalar potential.

gibbs_duhem_residual ¶

gibbs_duhem_residual(
    ln_gamma_fn: LogActivityFn, x: Array
) -> Array

Gibbs-Duhem residual for an activity-coefficient model (see module docs).

equifugacity_residual ¶

equifugacity_residual(
    eos: CubicEOS,
    t: ArrayLike,
    p: ArrayLike,
    x: Array,
    y: Array,
    tc: Array,
    pc: Array,
    omega: Array,
    *,
    kij: Array | None = None,
) -> Array

Max equilibrium fugacity mismatch |ln(x_i phi_i^L) - ln(y_i phi_i^V)|.

fugacity_pressure_residual ¶

fugacity_pressure_residual(
    eos: CubicEOS,
    t: ArrayLike,
    p: ArrayLike,
    tc: ArrayLike,
    pc: ArrayLike,
    omega: ArrayLike,
    *,
    phase: str = "vapor",
) -> Array

Residual of the pure-fluid identity (d ln phi / dP)_T = (Z - 1) / P.

gibbs_helmholtz_residual ¶

gibbs_helmholtz_residual(
    pkg: PropertyPackage,
    t: ArrayLike,
    p: ArrayLike,
    x: Array,
    *,
    phase: str,
) -> Array

Relative residual of H = -T^2 (d(G/T)/dT)_{P,x} on one branch of a package.

G = H - T S is built from the package's own enthalpy and entropy, so a nonzero residual means the two disagree ((dS/dT)_P != C_P / T).

fugacity_enthalpy_residual ¶

fugacity_enthalpy_residual(
    pkg: PropertyPackage,
    t: ArrayLike,
    p: ArrayLike,
    x: Array,
) -> Array

Relative residual of H^V - H^L = -R T^2 d/dT sum_i x_i (ln phi_i^V - ln phi_i^L).

Evaluate at a (T, P, x) where both branches exist. A reference fluid uses the gas constant of its own formulation.

Property packages¶

package ¶

EnergySolveResult ¶

PropertyPackage ¶

component_names property ¶

evidence property ¶

n_components property ¶

signature ¶

ln_phi ¶

enthalpy ¶

entropy ¶

volume ¶

ln_phi_function ¶

in_domain ¶

k_values ¶

k_seed ¶

flash_pt_with_info ¶

flash_pt ¶

stability ¶

bubble_pressure_with_info ¶

bubble_pressure ¶

dew_pressure_with_info ¶

dew_pressure ¶

bubble_temperature_with_info ¶

bubble_temperature ¶

dew_temperature_with_info ¶

dew_temperature ¶

mixture_enthalpy ¶

mixture_entropy ¶

mixture_volume ¶

flash_ph_with_info ¶

flash_ph ¶

flash_ps_with_info ¶

flash_ps ¶

CubicPackage dataclass ¶

n_components property ¶

signature ¶

ln_phi ¶

enthalpy ¶

entropy ¶

volume ¶

flash_pt_with_info ¶

bubble_pressure_with_info ¶

dew_pressure_with_info ¶

GammaPhiPackage dataclass ¶

n_components property ¶

signature ¶

in_domain ¶

ln_phi ¶

ln_phi_function ¶

enthalpy ¶

entropy ¶

volume ¶

flash_pt_with_info ¶

k_seed ¶

bubble_pressure_with_info ¶

dew_pressure_with_info ¶

bubble_temperature_with_info ¶

dew_temperature_with_info ¶

SAFTPackage dataclass ¶

n_components property ¶

signature ¶

ln_phi ¶

enthalpy ¶

entropy ¶

volume ¶

flash_pt_with_info ¶

bubble_pressure_with_info ¶

dew_pressure_with_info ¶

HelmholtzPackage dataclass ¶

n_components property ¶

signature ¶

ln_phi ¶

enthalpy ¶

entropy ¶

volume ¶

in_domain ¶

flash_pt_with_info ¶

stability ¶

k_seed ¶

component_names `property` ¶

evidence `property` ¶

n_components `property` ¶

CubicPackage `dataclass` ¶

n_components `property` ¶

GammaPhiPackage `dataclass` ¶

n_components `property` ¶

SAFTPackage `dataclass` ¶

n_components `property` ¶

HelmholtzPackage `dataclass` ¶

n_components `property` ¶