epcsaft.eos#
Construct native Helmholtz fluid models and request state properties.
Temperatures use K, pressure Pa, molar density mol/m³ and mole fractions a
dimensionless molar basis. Total caloric state properties are molar and
require explicit ideal-gas thermochemistry; residual properties retain their
native reference. Exact physical directional actions follow ALG-ACTIONS.
Parameter names and array order come from Parameters.
- class epcsaft.eos.ThermochemistryPacket(path: str | pathlib.Path)#
Load and prepare source NASA9 ideal-gas thermochemistry once.
- Variables:
species_ids (tuple of str) – Source species identifiers in packet order; no physical unit.
Notes
Input temperatures are K and standard pressure is Pa. Native preparation rescales the nine NASA9 coefficients by the source gas constant divided by the Engine gas constant (both J/(mol K)). Intervals are lower-inclusive and upper-exclusive except for the last interval, whose upper end is included.
selectonly copies and reorders the prepared records (ALG-CALORICS).- __init__(path: str | pathlib.Path) None#
Read a NASA9 record file and prepare it in the Engine’s gas-constant basis.
- Parameters:
path (str or pathlib.Path) – JSON file with
nasa-glenn-nasa9-recordsversion 1 and coefficient ordera1 a2 a3 a4 a5 a6 a7 b1 b2. Interval bounds use K, standard pressure Pa, and the source gas constant J/(mol K).- Raises:
ParameterError – The form/version/order is unsupported, species identifiers repeat, or native thermochemistry admission refuses the records.
OSError – The file cannot be read.
json.JSONDecodeError – The file is not valid JSON. Missing required keys raise
KeyError.
- select(species_ids: collections.abc.Sequence[str]) ThermochemistryRecord#
Copy prepared thermochemistry into the requested species order.
- Parameters:
species_ids (sequence of str) – Identifiers to select, in the consuming model’s component order.
- Returns:
record – Prepared NASA9 intervals, retaining K bounds and standard pressure in Pa.
- Return type:
- Raises:
ParameterError – Any identifier is absent from the packet.
- class epcsaft.eos.Mixture(parameters: epcsaft.parameters.Parameters, *, thermochemistry: ThermochemistryRecord | None = None, active_parameters: collections.abc.Sequence[ActiveParameter] | None = None, solver_options: collections.abc.Mapping[str, float] | None = None)#
Evaluate a fluid mixture with an explicit mole-fraction composition.
- Variables:
Notes
At least two components are required for
Mixtureitself.Pureuses the same calculations at dimensionless mole fractionx = (1,). Native construction copies parameter, thermochemistry and solver inputs; subsequent caller edits do not redefine the constructed native model. An explicit x sequence needs one finite nonnegative entry per component and a sum of one within native tolerance; an empty sequence is refused. State and property-action requests also require electroneutrality.- __init__(parameters: epcsaft.parameters.Parameters, *, thermochemistry: ThermochemistryRecord | None = None, active_parameters: collections.abc.Sequence[ActiveParameter] | None = None, solver_options: collections.abc.Mapping[str, float] | None = None) None#
Construct the native Helmholtz model for the declared components.
- Parameters:
parameters (epcsaft.parameters.Parameters) – Ordered physical parameter declaration; at least two components.
thermochemistry (ThermochemistryRecord, optional) – Ideal-gas molar thermochemistry in component order, with temperature intervals in K and reference pressure in Pa. Required for total calorics.
active_parameters (sequence of ActiveParameter, optional) – Native parameter coordinates whose exact derivatives are requested. Each coordinate retains the physical unit of its parameter family.
solver_options (mapping of str to float, optional) – Native solver tolerances and work limits; each named option retains its native unit (ALG-TERMINATION).
- Raises:
ParameterError – Fewer than two components, or native input admission fails.
- property active_parameter_values: list[float]#
Active parameter values in active order, each in its family’s native unit.
- counters() epcsaft._core.SweepCounters#
Read native work counts accumulated by this model.
- Returns:
counters – Dimensionless counts of native evaluations and solver work since reset.
- Return type:
- density_actions(T: float, rho: float, *, x: collections.abc.Sequence[float] | None = None, observables: collections.abc.Sequence[PropertyObservable], directions: collections.abc.Sequence[DensityActionDirection]) PropertyActionBatch#
Evaluate exact first through third directional property actions.
- Parameters:
T (float) – Temperature in K.
rho (float) – Molar density in mol/m³.
x (sequence of float, optional) – Dimensionless mole fractions in component order; required for a mixture.
observables (sequence of PropertyObservable) – Requested native properties in output order.
directions (sequence of DensityActionDirection) – One to three physical directions: temperature in K, rho in mol/m³, composition dimensionless and parameters in native family units. Each composition increment must have one entry per component; a mixture refuses an empty increment and one component reads it as zero.
- Returns:
batch – Values and directional contractions in each observable’s unit: molar energy in J/mol and entropy/heat capacity in J/(mol K). LogFugacityCoefficient requires pressure_actions. Unavailable entries retain their native causes.
- Return type:
- Raises:
ParameterError – Inputs, branch, composition or direction dimensions are inadmissible.
EosError – The native state evaluation fails.
Notes
Composition directions must preserve normalization and charge balance. Directions are physical increments, not dimensionless coordinate labels; contracted derivatives retain the observable unit. Higher mixed actions use the supplied directions together, rather than separate first actions (ALG-ACTIONS).
- density_diagnostics(T: float, P: float, *, x: collections.abc.Sequence[float] | None = None, nodes: collections.abc.Sequence[float] | None = None, density_tolerance: float | None = None, log_tolerance: float | None = None, max_evaluations: int | None = None, max_seconds: float | None = None, adaptive: bool | None = None, finite_upper: float | None = None, evaluation_order: DerivativeOrder | None = None, finite_anchor: float | None = None) DensityDiagnostics#
Inspect pressure roots and mechanical turning points on a declared grid.
- Parameters:
T (float) – Temperature in K.
P (float) – Target pressure in Pa.
x (sequence of float, optional) – Dimensionless mole fractions in component order; required for a mixture.
nodes (sequence of float, optional) – At least two increasing positive densities in mol/m³, below the geometric density cap. The default geometric grid uses the
DENSITY_DIAGNOSTIC_NODESnode count andDENSITY_DIAGNOSTIC_LOWERlower density in mol/m³. Its upper density is the geometric cap timesDENSITY_UPPER_FRACTION. These entries are available fromepcsaft.tolerances().density_tolerance (float, optional) – Positive absolute density-bracket width in mol/m³. Default: the
DENSITY_DIAGNOSTIC_ABSOLUTE_WIDTHentry ofepcsaft.tolerances().log_tolerance (float, optional) – Positive dimensionless bracket width in natural log density ratio. Default: the
DENSITY_DIAGNOSTIC_LOG_WIDTHentry ofepcsaft.tolerances().max_evaluations (int, optional) – Positive maximum number of native pressure evaluations. Default: the
DENSITY_DIAGNOSTIC_MAX_EVALUATIONSentry ofepcsaft.tolerances().max_seconds (float, optional) – Positive wall-time budget in s. Default: the
DENSITY_DIAGNOSTIC_MAX_SECONDSentry ofepcsaft.tolerances().adaptive (bool, default True) – Enable native adaptive grid investigation.
finite_upper (float, default 0.0) – Finite-domain upper density in mol/m³ when an anchor is supplied; otherwise unused.
evaluation_order (DerivativeOrder, default PressureSlope) – Gradient, PressureSlope or Hessian for finite-domain evaluation.
finite_anchor (float, optional) – Positive finite-domain anchor density in mol/m³, below the geometric cap and
finite_upper.
- Returns:
diagnostics – Sampled pressure in Pa, densities and brackets in mol/m³, mechanical signs, work counts and native stop causes. Root residuals use Pa; spinodal residuals are pressure slopes divided by RT, dimensionless.
- Return type:
- Raises:
ParameterError – The grid, budgets, composition, domain or derivative order is invalid.
EosError – Thermodynamic evaluation cannot be prepared.
Notes
Bracket refinement requires both absolute and natural-log width criteria. Partial results retain budget/domain causes; a finite scan is not a proof that no additional root exists (ALG-DENSITY).
- log_fugacity_terms(T: float, rho: float, x: collections.abc.Mapping[str, float] | collections.abc.Sequence[float] | None = None) LogFugacityTerms#
Return each residual Helmholtz term’s share of ln phi_i at T (K), rho (mol/m³) and x.
Every field holds
d(n a_k)/dn_iper component, dimensionless; ln phi_i is their sum minuslog_compressibility_factor(ln Z, reported once). Charged components on an ion-free support are None, as inState.log_fugacity_coefficient.
- molar_density_upper_bound(T: float, *, x: collections.abc.Sequence[float] | None = None) float#
Return the geometric packing limit for the declared composition.
- Parameters:
- Returns:
rho_cap – Upper geometric density in mol/m³; not a stable-liquid density.
- Return type:
- Raises:
ParameterError – Composition or temperature is inadmissible.
- outside_domains(x: collections.abc.Sequence[float]) list[dict[str, Any]]#
Report declared composition bounds exceeded by one phase, in component order.
- parameters: epcsaft.parameters.Parameters#
- pressure_action_difference(T: float, P: float, *, x: collections.abc.Sequence[float] | None = None, phase: str, observables: collections.abc.Sequence[PropertyObservable], direction: PressureActionDirection, step: float, tau: float, kappa: float) list[epcsaft._core.DifferenceCheck]#
Compare first-order
pressure_actionswith native central differences.- Parameters:
T – As for
pressure_actions.P – As for
pressure_actions.x – As for
pressure_actions.phase – As for
pressure_actions.observables – As for
pressure_actions.direction (PressureActionDirection) – One direction: temperature in K, pressure in Pa and a composition increment whose entries sum to zero. A composition increment that does not sum to zero, or a nonzero parameter entry, is reported as
unsupported_directionwithout evaluation.step (float) – Positive scalar multiplying
direction.tau (float) – Positive relative and roundoff-multiple allowances.
kappa (float) – Positive relative and roundoff-multiple allowances.
- Returns:
checks – One record per result: exact action A, D = (f(+h) - f(-h))/(2h), roundoff r,
ratio = |D - A| / (tau |A| + kappa r)andstatuspassed,failed,nonfinite,unsupported_direction,neighbor_unavailableorbranch_changed.- Return type:
list of DifferenceCheck
Notes
Verification only (ALG-ACTIONS): neighbors are evaluated natively on the central root through its density anchor.
- pressure_actions(T: float, P: float, *, x: collections.abc.Sequence[float] | None = None, phase: str, observables: collections.abc.Sequence[PropertyObservable], directions: collections.abc.Sequence[PressureActionDirection], anchor: State | None = None) PropertyActionBatch#
Evaluate exact first through third directional property actions.
- Parameters:
T (float) – Temperature in K.
P (float) – Pressure in Pa.
x (sequence of float, optional) – Dimensionless mole fractions in component order; required for a mixture.
observables (sequence of PropertyObservable) – Requested native properties in output order.
directions (sequence of PressureActionDirection) – One to three physical directions: temperature in K, P in Pa, composition dimensionless and parameters in native family units. Each composition increment must have one entry per component; a mixture refuses an empty increment and one component reads it as zero.
phase ({'liquid', 'vapor'}) – Branch retained by the pressure-closed derivative calculation.
anchor (State, optional) – Density anchor in mol/m³ for that branch.
- Returns:
batch – Values and directional contractions in each observable’s unit: molar energy in J/mol, entropy/heat capacity in J/(mol K), and dimensionless natural ln(phi), with one fugacity result per component in component order. Unavailable entries retain their native causes.
- Return type:
- Raises:
ParameterError – Inputs, branch, composition or direction dimensions are inadmissible.
EosError – The native state evaluation fails.
Notes
Composition directions must preserve normalization and charge balance. Directions are physical increments, not dimensionless coordinate labels; contracted derivatives retain the observable unit. Higher mixed actions use the supplied directions together, rather than separate first actions (ALG-ACTIONS).
- reference(T: float, P: float, *, solvent_fractions: collections.abc.Sequence[float], ions: tuple[str, str] | None = None, stoichiometry: tuple[int, int] | None = None) epcsaft.reference.Reference#
Solve a solvent or electrolyte infinite-dilution reference at fixed T and P.
- Parameters:
T (float) – Reference temperature in K.
P (float) – Reference pressure in Pa.
solvent_fractions (sequence of float) – Dimensionless solvent-only mole fractions in component order.
ions (tuple of str, optional) – Two ion identifiers in the order used for returned ionic quantities.
stoichiometry (tuple of int, optional) – Positive formula stoichiometric counts in ion order; required exactly when
ionsis supplied.
- Returns:
reference – Immutable physical inputs and native reference fugacity coefficients.
- Return type:
- Raises:
ParameterError – Only one of ions/stoichiometry is given, identifiers are unknown, ionic reference/composition inputs are invalid, or native model input admission, such as temperature or pressure, fails.
EosError – An ionic reference state or dilution limit cannot be evaluated.
Notes
The solvent-only path supports solvent activity and neutral Henry constants. An inadmissible solvent composition or numerical density failure returns a Reference with pure_solvent_log_fugacity set to None; its solvent_activity result retains the native status and cause. The ionic path follows the native charge-neutral dilution ladder and convergence checks (ALG-REFERENCE). Input sequences are copied.
- reset_counters() None#
Reset this model’s accumulated native work counts to zero.
- Returns:
Subsequent
countersreports work accumulated after this call.- Return type:
None
- state(T: float, *, rho: float | None = None, P: float | None = None, x: collections.abc.Sequence[float] | collections.abc.Mapping[str, float] | None = None, phase: str | None = None, anchor: State | None = None, derived_properties: bool | None = None) State#
Evaluate a state at fixed molar density or solve density at fixed pressure.
- Parameters:
T (float) – Absolute temperature in K.
rho (float, optional) – Molar density in mol/m³; specify exactly one of
rhoandP.P (float, optional) – Pressure in Pa for a native density solve.
x (sequence of float or mapping of str to float, optional) – Dimensionless mole fractions in component order. Unnamed mapping components are zero; a mixture requires an explicit composition.
phase ({'liquid', 'vapor', None}, optional) – Density branch for a pressure solve;
Noneleaves it unspecified.anchor (State, optional) – Previous density (mol/m³) used as a pressure-solve anchor.
derived_properties (bool, optional) – Request derived properties;
Noneis passed as false.
- Returns:
state – Native state: pressure in Pa, density in mol/m³, dimensionless residual Helmholtz energy divided by RT, and available molar calorics in J/mol or J/(mol K). Optional properties retain their availability diagnostics.
- Return type:
- Raises:
ParameterError – Both/neither density and pressure are supplied, phase is unknown, composition is missing or names/physical inputs are inadmissible.
DensityStructureError – The requested pressure-density branch cannot be established.
EosError – Native thermodynamic evaluation fails.
Notes
For a density input, branch and anchor do not select a root. Density solves and their finite-search limits follow ALG-DENSITY. State availability does not establish global phase stability.
- states(T: collections.abc.Sequence[float], *, rho: float | collections.abc.Sequence[float] | None = None, P: float | collections.abc.Sequence[float] | None = None, x: collections.abc.Sequence[float] | collections.abc.Mapping[str, float] | collections.abc.Sequence[collections.abc.Sequence[float]] | None = None, phase: str | None = None, derived_properties: bool | None = None) StateBatch#
Evaluate independent homogeneous states in one native call.
- Parameters:
T (sequence of float) – Row-aligned absolute temperatures in K.
rho (float or sequence of float, optional) – Shared or row-aligned molar density in mol/m³. Specify rho or P.
P (float or sequence of float, optional) – Shared or row-aligned pressure in Pa. Specify rho or P.
x (sequence or mapping, optional) – Shared mole fractions or an N-by-C component-order matrix. Pure defaults to (1,); a mixture requires composition.
phase ({'liquid', 'vapor', None}, optional) – Shared pressure-density branch, with no preceding-row anchor.
derived_properties (bool, optional) – Request the scalar derived properties on every row.
- Returns:
Ordered stored States, property list columns in scalar SI units, and per-row exception categories, causes and numerical records. Failed rows have None values; optional outputs retain scalar availability.
- Return type:
StateBatch
- Raises:
ParameterError – Structural inputs disagree, composition is missing, or phase is unknown.
TypeError – Numeric arrays cannot be converted to the declared shapes.
Notes
Physical refusals affect only their row. There is no implicit continuation or global phase-stability claim.
- virial_coefficient_actions(T: float, x: collections.abc.Mapping[str, float] | collections.abc.Sequence[float] | None = None, *, temperature_direction: float | None = None, composition_direction: collections.abc.Mapping[str, float] | collections.abc.Sequence[float] | None = None) VirialCoefficientActions#
Return B and C with their exact derivatives along a direction in T (K) and x.
second_action and third_action are dB and dC per unit of the direction: temperature_direction=1 gives d/dT; a composition direction must sum to zero (fixed total) and [1, -1] gives d/dx of the first component of a binary.
- virial_coefficients(T: float, x: collections.abc.Mapping[str, float] | collections.abc.Sequence[float] | None = None) VirialCoefficients#
Return exact neutral-model B (m³/mol) and C (m⁶/mol²) at T in K.
Composition follows component order or component identifiers. Charged declarations refuse even on an ion-free composition face.
- class epcsaft.eos.Pure(parameters: epcsaft.parameters.Parameters, *, thermochemistry: ThermochemistryRecord | None = None, active_parameters: collections.abc.Sequence[ActiveParameter] | None = None, solver_options: collections.abc.Mapping[str, float] | None = None)#
Bases:
MixtureEvaluate one component at mole fraction one, including saturation declarations.
Notes
Exactly one component is required. Component names, sites and parameters are the inherited
Mixtureattributes. State, reference and work-count methods followMixture; no explicit composition is needed for a state. Saturation returns a declaration for the native equilibrium driver.- __init__(parameters: epcsaft.parameters.Parameters, *, thermochemistry: ThermochemistryRecord | None = None, active_parameters: collections.abc.Sequence[ActiveParameter] | None = None, solver_options: collections.abc.Mapping[str, float] | None = None) None#
Construct the one-component native Helmholtz model; inputs as for
Mixture.
- saturation(T: float) epcsaft.equilibrium.Problem#
Declare isothermal liquid-vapor saturation without solving it.
- Parameters:
T (float) – Fixed temperature in K.
- Returns:
problem – One mol of this component, liquid
Land incipient vaporVpinned at zero mol, with pressure free in Pa.- Return type:
Notes
Call
solve_equilibriumto solve the returned problem. This declaration alone establishes neither existence nor stability of a saturation state.
- epcsaft.eos.property_asl_record(model: Mixture, require_phase_identity: bool | None = None, solids: collections.abc.Sequence[epcsaft._core.SolidSpec] | None = None, neutral_reference: epcsaft._core.NeutralReferenceDeclaration | None = None) str#
Serialize a declared model for native ASL property callbacks.
- Parameters:
model (Mixture) – Model whose parameters retain their source document; its thermochemistry and solver options are serialized with it.
require_phase_identity (bool, default False) – Refuse unclassified pressure roots in the declared initial VLE domain; false admits them for single-phase endpoint diagnostics.
solids (Sequence[SolidSpec], optional) – Pure solids, each with a ln K(T) correlation (a scalar K is refused); each adds one solid row.
neutral_reference (NeutralReferenceDeclaration or None) – Source-basis neutral reference, required when solids are given.
- Returns:
Native record string containing the parameter, thermochemistry and solid declarations.
- Return type:
- Raises:
ValueError – The parameters retain no document, or carry the stored cause a fit could not be written into it.
Notes
Serialization supplies no state prediction. The native ASL adapter owns subsequent values and exact derivatives.
Re-exported names#
epcsaft.eos.Parameters→epcsaft.parameters.Parametersepcsaft.eos.Reference→epcsaft.reference.Referenceepcsaft.eos.State→epcsaft._core.Stateepcsaft.eos.IdealPolynomial→epcsaft._core.IdealPolynomialepcsaft.eos.IdealShomate→epcsaft._core.IdealShomateepcsaft.eos.IdealNASA7→epcsaft._core.IdealNASA7epcsaft.eos.IdealNASA9→epcsaft._core.IdealNASA9epcsaft.eos.IdealDIPPR107→epcsaft._core.IdealDIPPR107epcsaft.eos.IdealCorrelation→epcsaft._core.IdealCorrelationepcsaft.eos.IdealInterval→epcsaft._core.IdealIntervalepcsaft.eos.ThermochemistryRecord→epcsaft._core.ThermochemistryRecordepcsaft.eos.ThermochemistryStatus→epcsaft._core.ThermochemistryStatusepcsaft.eos.DensityBranch→epcsaft._core.DensityBranchepcsaft.eos.DensityDiagnostics→epcsaft._core.DensityDiagnosticsepcsaft.eos.DerivativeOrder→epcsaft._core.DerivativeOrderepcsaft.eos.ParameterFamily→epcsaft._core.ParameterFamilyepcsaft.eos.ActiveParameter→epcsaft._core.ActiveParameterepcsaft.eos.GAS_CONSTANT_J_PER_MOL_K→epcsaft._core.GAS_CONSTANT_J_PER_MOL_Kepcsaft.eos.PropertyObservable→epcsaft._core.PropertyObservableepcsaft.eos.PropertyActionStatus→epcsaft._core.PropertyActionStatusepcsaft.eos.DensityActionDirection→epcsaft._core.DensityActionDirectionepcsaft.eos.PressureActionDirection→epcsaft._core.PressureActionDirectionepcsaft.eos.ParameterActionDirection→epcsaft._core.ParameterActionDirectionepcsaft.eos.PropertyActionDiagnostics→epcsaft._core.PropertyActionDiagnosticsepcsaft.eos.PropertyActionResult→epcsaft._core.PropertyActionResultepcsaft.eos.PropertyActionBatch→epcsaft._core.PropertyActionBatchepcsaft.eos.ParameterError→epcsaft._core.ParameterErrorepcsaft.eos.EosError→epcsaft._core.EosErrorepcsaft.eos.DensityStructureError→epcsaft._core.DensityStructureError