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 A/(nRT), dimensionless |
|
departure from the ideal gas at the same T and density, J/mol |
Entropy and heat capacities |
J/(mol K) |
|
residual chemical potential divided by RT, component order |
|
dimensionless ln φ at the state’s T and pressure |
|
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.
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.