States and properties#

A state is one homogeneous phase at a specified temperature and composition. Supply either molar density or pressure. At pressure, declare a density branch when it matters. The water notebook checks pressure closure; the methane caloric notebook adds published ideal thermal records. See density closure and calorics for their definitions.

Choose the independent quantities#

model.state(T, rho=..., x=...) evaluates the T–density chart. model.state(T, P=..., x=..., phase="liquid") solves density at pressure. For Pure, omit x. For Mixture, provide fractions in component_ids order or a mapping from component names. Omitted mapping entries are zero. Fractions are dimensionless; temperature is K, pressure Pa and density mol/m³. Physical electrolyte compositions must preserve charge balance.

A pressure solve may accept an available state as anchor. This is a numerical start on the requested branch, not an instruction to accept an inconsistent density. Check density_convergence, the achieved pressure and pressure_density_derivative. A positive slope is a mechanical condition; it is not a complete phase-stability test.

The model reference owns these call signatures and the native state fields describe the returned values and causes.

Distinguish Ideal, Residual and Total#

Returned quantity

Meaning and unit

residual_helmholtz and individual contributions

residual A/(nRT), dimensionless

residual_enthalpy, residual_internal_energy

departure from the ideal gas at the same T and density, J/mol

Entropy and heat capacities

J/(mol K)

residual_chemical_potential_over_rt

residual chemical potential divided by RT, component order

log_fugacity_coefficient

dimensionless ln φ at the state’s T and pressure

molar_density

mol/m³; multiply by mixture molar mass in kg/mol for kg/m³

Total calorics add the ideal and residual quantities at the same state. A residual enthalpy is not an absolute total enthalpy. Heat capacities in the state record hold composition fixed; a reacting equilibrium heat capacity also includes composition response and is a different observable.

Supply ideal thermal records#

The Engine reads polynomial, Shomate, NASA7, NASA9 and DIPPR107 ideal thermal forms through declared intervals and reference constants. A ThermochemistryRecord follows the EOS component order and supplies its pressure standard. ThermochemistryPacket reads the supported NASA9 packet and selects named species into that order. The native reader converts the source gas constant to the Engine convention.

Keep source interval endpoints and anchors. Gaps and ambiguous overlaps are refused; a piecewise endpoint with an available value need not have an available derivative across the join. Do not extend or smooth a source correlation to obtain a requested quantity. The methane notebook checks published NASA9 values and the exact enthalpy temperature action against Cp; it does not establish agreement with calorimetry.

Interpret unavailable outputs#

Without thermal inputs, residual properties can remain available while Ideal and Total calorics are None. Inspect thermochemistry_status for MissingRecord, OutsideInterval or another named cause. Do not substitute zero or the residual part for an unavailable total property.

derived_properties=True requests additional fixed-composition properties such as compressibility and expansivity. Their availability depends on mechanical regularity and, for caloric consumers, the required thermal inputs. A component chemical potential may be unavailable for ionic insertion on an ion-free support even when the central state is available.

Electrolyte reference quantities#

For activities, construct a reference at the same T, P, parameters and solvent basis. An ionic reference declares the ion pair and formula stoichiometry; Reference.activity takes formula-unit molality in mol/kg. Solvent activity and the practical osmotic coefficient use their declared solvent-mass basis. The NaCl notebook, reference definitions and reference calls show these operations. They do not supply an arbitrary single-ion convention or a global stability proof.

Derived state outputs include speed of sound, Joule–Thomson coefficient and compressibilities when requested and available. Partial molar volume, enthalpy and entropy are also available through the property interfaces. Ideal and total calorics require caller-supplied ideal-gas thermochemistry; residual calorics do not. Inspect each result’s availability before using it.

Arrays of independent states#

Mixture.states and Pure.states evaluate declared rows sequentially in one native call. Temperature is a one-dimensional sequence in K. Specify exactly one of rho (mol/m³) and P (Pa), either a shared scalar or one value per row. Composition is a shared component-order vector, a shared name mapping, or a matrix with one component-order vector per row. A mixture requires composition; a pure fluid can omit it. There is no Cartesian product or implicit continuation.

result = mixture.states([280.0, 300.0], rho=200.0, x=[0.4, 0.6])
pressures = result.pressure  # Pa, one list entry per declared row

Each property column has the same name and units as on State. Columns are ordinary Python lists, assembled from stored native states when read. Component and association-site lists preserve their scalar ordering. rows contains the stored State or None; status and cause explain a failed row. A failed row has None in every property column. Missing ideal calorics, absent charged insertions and unrequested derived properties retain the scalar None values and diagnostics without discarding valid residual properties. Set derived_properties=True to request the same derived outputs as scalar state.

A shared phase selects the pressure-density branch using the scalar rules. Every pressure row starts without an anchor; previous rows never initialize a later density solve. Density declarations retain the scalar behavior for phase. A failed physical row leaves other rows available. Structural errors, such as array lengths or composition widths that disagree, reject the declaration. failure_record and first_numerical_failure retain available native failure evidence. DomainError identifies a scalar domain refusal (Python ValueError), including nonfinite ideal-gas density closure. A returned homogeneous state does not establish global phase stability. No speed advantage is implied by batching.