Native states and references#

Native thermodynamic declarations and results.

Notes

All component indices are zero based in declared component_ids order. Molar quantities use mol as their amount basis; mass-based inputs name their solvent or mixture basis explicitly. Arrays are ordinary Python sequences.

Every native enum provides name (the symbolic string) and value (the native integer code). These introspection properties have no physical unit. Individual enum declarations link here rather than duplicating this convention.

Native enum introspection#

For every native enumeration, name is its symbolic string and value is its numeric integer value, not a physical quantity.

epcsaft._core.GAS_CONSTANT_J_PER_MOL_K: float#

Molar gas constant in J/(mol K), fixed by the native physical_constants owner.

epcsaft._core.EOS_STANDARD_STATE_ID: str#

(rho*x/(1 mol/m^3))*exp(mu_res/(RT)), dimensionless.

Type:

Native reaction activity identity

class epcsaft._core.ParameterError#

Bases: ValueError

A parameter value, unit, shape or declaration is inadmissible.

class epcsaft._core.EosError#

Bases: RuntimeError

A native thermodynamic evaluation cannot supply the requested result.

class epcsaft._core.DensityStructureError#

Bases: EosError

The density search cannot establish the requested root structure.

Notes

A failed or incomplete scan is not evidence of a unique stable root. See ALG-DENSITY in engine/docs/science/algorithms.md.

first_numerical_failure: Convergence | None#

Earlier native refusal, when retained separately from final convergence.

record: Convergence | None#

Final native refusal, or None when unmeasured.

class epcsaft._core.ConvergenceError#

Bases: EosError

A native iterative calculation stops without an admitted result.

Notes

The exception message retains the residual, stopping criterion and available convergence diagnostics.

first_numerical_failure: Convergence | None#

Earlier native refusal, when retained separately from final convergence.

record: Convergence#

Final native refusal, or None when unmeasured.

class epcsaft._core.DeclarationError#

Bases: ParameterError

A required physical declaration is absent or inadmissible.

first_numerical_failure: Convergence | None#

Earlier native refusal, when retained separately from final convergence.

record: Convergence | None#

Final native refusal, or None when unmeasured.

class epcsaft._core.Stop#

Reason an iterative calculation stopped.

Notes

Native enum name/value properties follow the module convention in epcsaft._core.

budget_exhausted: Stop#

An iteration, evaluation or elapsed-time limit was reached.

converged: Stop#

Residual meets the requested criterion.

converged_to_floor: Stop#

Residual meets the estimated numerical floor criterion; the requested tolerance need not be met.

infeasible: Stop#

The declared constraints could not be satisfied by this calculation; no global infeasibility proof is implied.

left_domain: Stop#

The calculation left its admitted physical or numerical domain.

nonfinite: Stop#

A required value or diagnostic is nonfinite.

singular: Stop#

A required linear system is singular.

stalled: Stop#

Residual contraction does not support further progress.

class epcsaft._core.Category#

Provenance category of a numerical criterion.

Notes

Native enum name/value properties follow the module convention in epcsaft._core.

AlgorithmTolerance: Category#

An algorithmic stopping or admission tolerance.

ThermodynamicConstraint: Category#

A constraint imposed by the thermodynamic formulation.

class epcsaft._core.Tolerance#

Named immutable numerical criterion and its source.

category: Category#

Whether the criterion expresses a thermodynamic constraint or an algorithm tolerance.

factor: float#

Declared amplification factor, dimensionless.

name: str#

Policy identifier, not a physical quantity.

source: str#

Source citation or derivation identifying the criterion.

upstream: Tolerance | None#

Parent criterion from which this value derives, or None for an independent criterion.

value: float#

Criterion magnitude in the residual’s units or dimensionless normalization; no common unit applies to all policies.

epcsaft._core.tolerances() → list[Tolerance]#

Read immutable source defaults for numerical policies.

Returns:

List of Tolerance records in native policy order; effective caller settings are reported by each result.solver_options.

Return type:

list[Tolerance]

class epcsaft._core.Convergence#

Residual and work evidence for one iterative calculation.

amplification: float | None#

Estimated dimensionless numerical error amplification, or None when not estimated.

backward_error: float | None#

Dimensionless measured linear backward error, or None when unavailable.

cause: str#

Producing operation and actual refused operands; empty without an observation.

contraction: float | None#

Dimensionless geometric residual contraction per iteration, or None without sufficient history.

criterion: Tolerance | None#

Effective requested tolerance, or None when no criterion is attached.

evaluations: int#

Number of evaluations performed, a count; its scope is the producing calculation.

floor: float | None#

Estimated attainable residual floor in residual units, or None when not estimated.

iterations: int#

Number of iterations performed, a count.

rank: NumericalRank | None#

Rank in the named matrix basis, or None without a factor observation.

residual: float#

Final residual magnitude in the producing calculation’s units or normalization.

property residual_over_criterion: float | None#

Read the final residual relative to the requested criterion.

Returns:

Dimensionless residual/criterion.value, or None without an attached criterion.

Return type:

Optional[float]

property residual_over_floor: float | None#

Read the final residual relative to the estimated floor.

Returns:

Dimensionless residual/floor, or None without an estimated floor.

Return type:

Optional[float]

stop: Stop#

Stopping reason; convergence to a floor is distinct from meeting the requested tolerance.

class epcsaft._core.Event#

One named numerical probe within a captured span.

iteration: int#

Producer’s iteration counter; zero may denote an uniterated probe.

name: str#

Probe identifier supplied by the native producer.

reason: str#

Producer’s explanation, possibly empty.

span: int#

Zero-based index into Trace.spans identifying the parent span.

values: list[float]#

Probe values in producer-defined order and units; there is no common physical basis for different event names.

class epcsaft._core.Span#

Timing and convergence of one captured native operation.

convergence: Convergence | None#

Attached convergence evidence, or None if this operation did not attach a record.

name: str#

Native operation identifier.

parent: int | None#

Zero-based parent index in Trace.spans, or None for a root span.

wall_us: float#

Elapsed wall time in microseconds.

class epcsaft._core.Trace#

Ordered native timing spans and numerical probes.

current: int | None#

Currently active span index, or None when no span is open.

events: list[Event]#

Events in observation order; span indices refer to spans.

incomplete: bool#

True if opening the requested Ipopt log failed; diagnostic allocation failure propagates normally.

ipopt_log_error: str#

Opening error for the requested Ipopt destination; empty without an error.

spans: list[Span]#

Spans in creation order; parent indices refer to this list.

class epcsaft._core.Capture(diagnostics: bool = False, ipopt_log: str = '', ipopt_print_level: int = 12)#

Capture native numerical traces in a context manager.

Notes

Capture observes calculations without changing their stopping criteria. Detailed probes are enabled by diagnostics; exceptions from the enclosed calculation are not suppressed.

__enter__() → Capture#

Begin recording native operations.

Returns:

This capture instance; its completed trace is unavailable until closure.

Return type:

Capture

__exit__(exc_type: object, exc_value: object, traceback: object) → bool#

Close capture and retain the recorded trace.

Parameters:
  • exc_type (object) – Exception type supplied by the context-manager protocol, or None.

  • exc_value (object) – Exception instance supplied by the protocol, or None.

  • traceback (object) – Exception traceback supplied by the protocol, or None.

Returns:

False, so an enclosed exception is propagated.

Return type:

bool

__init__(diagnostics: bool = False, ipopt_log: str = '', ipopt_print_level: int = 12) → None#

Initialize Capture from the declared inputs.

Parameters:
  • diagnostics (bool) – Enable detailed numerical probes in addition to operation spans.

  • ipopt_log (str) – Optional absolute destination for the original calculation’s sequential Ipopt log.

  • ipopt_print_level (int) – Ipopt journal level of every category in that log; J_MAIN is capped at 5.

Returns:

None.

Return type:

None

events: list[Event]#

Completed trace events; access before closure raises RuntimeError.

spans: list[Span]#

Completed trace spans; access before closure raises RuntimeError.

trace: Trace | None#

Completed trace, or None until the context closes.

class epcsaft._core.ParameterEntry#

One source-identified parameter magnitude and declared unit.

__init__() → None#

Initialize ParameterEntry from the declared inputs.

Returns:

None.

Return type:

None

field: str#

Native parameter field name; it selects the required index arity and unit.

identity: str#

Source identity used to identify this entry in diagnostics.

index: list[int]#

Zero-based component or site indices in document order; scalar fields use an empty list.

magnitude: float#

Declared value in unit; native construction performs the admitted conversion.

unit: str#

Explicit unit string accepted for field, such as angstrom, kelvin or dimensionless.

class epcsaft._core.ParameterDocument#

Ordered component, site, model-choice and coefficient declarations.

Notes

build_parameters owns admission; an omitted required coefficient is not inferred from an application name.

__init__() → None#

Initialize ParameterDocument from the declared inputs.

Returns:

None.

Return type:

None

association_choice: str#

Declared association model identifier.

base_choice: str#

Declared base Helmholtz model identifier.

component_ids: list[str]#

Component identities in the order used by all component arrays, length n.

electrolyte_choice: str#

Declared electrolyte contribution identifier.

entries: list[ParameterEntry]#

Source-identified scalar entries with explicit indices and units.

ionic_dispersion_choice: str#

Declared ionic dispersion rule identifier.

permittivity_choice: str#

Declared bulk relative-permittivity model identifier.

polar_choice: str#

Declared polar contribution identifier.

site_component: list[int]#

Owning component index for each association site, length s.

site_ids: list[str]#

component_id/site_id for each association site, length s, or empty; names sites in messages.

site_multiplicity: list[int]#

Positive count of equivalent sites for each site type, length s.

class epcsaft._core.Parameters#

Admitted native EOS parameters in declared component and site order.

Notes

Lengths used throughout this module are n = component_count, s = site_count, and a = the number of active parameter directions. Construction uses build_parameters, not direct mutation.

property charge_number: list[int]#

Read component charges.

Returns:

Length n in component_ids order, elementary charges.

Return type:

list[int]

property component_count: int#

Read the number of declared components.

Returns:

Dimensionless component count n.

Return type:

int

ideal_gas: bool#
property molar_masses: list[float]#

Read component molar masses.

Returns:

Length n in component_ids order, kg/mol; quantities requiring mass refuse missing or nonpositive occupied-species masses.

Return type:

list[float]

property site_count: int#

Read the number of declared association-site types.

Returns:

Dimensionless site-type count s.

Return type:

int

property temperature_law_coefficient_identities: list[str]#

Read identities of native temperature-law coefficient slots.

Returns:

Coefficient identity strings in native slot order.

Return type:

list[str]

epcsaft._core.build_parameters(document: ParameterDocument) → Parameters#

Admit a source-identified parameter document.

Parameters:

document (ParameterDocument) – Complete physical declarations, ordered identities and coefficients with explicit units.

Returns:

Native Parameters in the document component and site order.

Return type:

Parameters

Notes

Missing or inconsistent fields, shapes, units and physical values raise ParameterError; required coefficients are not inferred.

epcsaft._core.prepare_thermochemistry(record: ThermochemistryRecord, source_gas_constant: float) → ThermochemistryRecord#

Convert source NASA9 coefficients to the Engine gas-constant convention.

Parameters:
  • record (ThermochemistryRecord) – Source thermochemistry in component order.

  • source_gas_constant (float) – Positive gas constant used by the source, J/(mol K).

Returns:

Prepared thermal record; source intervals and pressure standards are retained.

Return type:

ThermochemistryRecord

Notes

Every interval must contain NASA9; other ideal forms are refused by this preparation operation. Each coefficient is multiplied by source_gas_constant/GAS_CONSTANT_J_PER_MOL_K. Intervals and source pressures remain unchanged; no entropy pressure transfer or parameter fit occurs here.

epcsaft._core.fitted_document(start: ParameterDocument, fitted: Parameters) → ParameterDocument#

Write fitted native parameter magnitudes into a starting source document.

Parameters:
  • start (ParameterDocument) – Source document retaining ordered identities and unit declarations.

  • fitted (Parameters) – Fitted native Parameters to reproduce.

Returns:

Document that reconstructs fitted bitwise through build_parameters.

Return type:

ParameterDocument

Notes

Refuses a document that cannot represent the supplied parameters exactly; source identities are not changed into evidence of physical validation.

class epcsaft._core.IdealPolynomial(coefficients: Sequence[float], reference_temperature: float, reference_enthalpy: float, reference_entropy: float)#

Ideal-gas centered polynomial molar heat-capacity correlation.

Notes

See cp_ideal_polynomial in engine/docs/equations.md and ALG-CALORICS in engine/docs/science/algorithms.md. Coefficients do not define their own validity interval.

__init__(coefficients: Sequence[float], reference_temperature: float, reference_enthalpy: float, reference_entropy: float) → None#

Initialize IdealPolynomial from the declared inputs.

Parameters:
  • coefficients (Sequence[float]) – Initial value of IdealPolynomial.coefficients; see its attribute description for units and ordering.

  • reference_temperature (float) – Initial value of IdealPolynomial.reference_temperature; see its attribute description for units and ordering.

  • reference_enthalpy (float) – Initial value of IdealPolynomial.reference_enthalpy; see its attribute description for units and ordering.

  • reference_entropy (float) – Initial value of IdealPolynomial.reference_entropy; see its attribute description for units and ordering.

Returns:

None.

Return type:

None

coefficients: list[float]#

Coefficients a[k] in Cp = sum(a[k]*(T-Tref)**k), ascending k; units J/(mol K**(k+1)), nonempty.

reference_enthalpy: float#

Ideal-gas molar enthalpy at the anchor, J/mol.

reference_entropy: float#

Ideal-gas molar entropy at the anchor and source pressure, J/(mol K).

reference_temperature: float#

Enthalpy and entropy anchor temperature in K, within the owning interval.

class epcsaft._core.IdealShomate(coefficients: Sequence[float], formation_enthalpy: float)#

NIST Shomate ideal-gas molar thermochemistry.

Notes

See cp_ideal_shomate in engine/docs/equations.md; preserve the source pressure, integration constants and validity interval.

__init__(coefficients: Sequence[float], formation_enthalpy: float) → None#

Initialize IdealShomate from the declared inputs.

Parameters:
  • coefficients (Sequence[float]) – Initial value of IdealShomate.coefficients; see its attribute description for units and ordering.

  • formation_enthalpy (float) – Initial value of IdealShomate.formation_enthalpy; see its attribute description for units and ordering.

Returns:

None.

Return type:

None

coefficients: list[float]#

Cp and S use J/(mol K), the enthalpy increment uses kJ/mol before native conversion to J/mol.

Type:

Eight unmodified NIST values [A, B, C, D, E, F, G, H] with t=T/1000 K

formation_enthalpy: float#

Source formation enthalpy in J/mol added to the Shomate enthalpy increment; not inferred from the coefficient H.

class epcsaft._core.IdealNASA7(coefficients: Sequence[float])#

NASA7 ideal-gas molar thermochemistry.

Notes

See cp_ideal_nasa7 in engine/docs/equations.md. Coefficients must be enclosed in an explicit IdealInterval.

__init__(coefficients: Sequence[float]) → None#

Initialize IdealNASA7 from the declared inputs.

Parameters:

coefficients (Sequence[float]) – Initial value of IdealNASA7.coefficients; see its attribute description for units and ordering.

Returns:

None.

Return type:

None

coefficients: list[float]#

Seven coefficients [a0, a1, a2, a3, a4, a5, a6] in source order, with T in K. Cp/R uses powers T**0 through T**4; a5/T and a6 are the h/(RT) and s/R integration terms. Units are dimensionless for a0 and a6, K**(-k) for a[k] with k=1 through 4, and K for a5. Native evaluation uses GAS_CONSTANT_J_PER_MOL_K; prepare_thermochemistry accepts NASA9 only.

class epcsaft._core.IdealNASA9(coefficients: Sequence[float])#

NASA9 ideal-gas molar thermochemistry.

Notes

See cp_ideal_nasa9 in engine/docs/equations.md. Coefficients must be enclosed in an explicit IdealInterval.

__init__(coefficients: Sequence[float]) → None#

Initialize IdealNASA9 from the declared inputs.

Parameters:

coefficients (Sequence[float]) – Initial value of IdealNASA9.coefficients; see its attribute description for units and ordering.

Returns:

None.

Return type:

None

coefficients: list[float]#

9 values in source order a0 through a8; temperature is in K. Heat capacity divided by R uses powers T**-2 through T**4; a7/T and a8 are the enthalpy and entropy integration terms. Coefficient units follow these powers; retain the source gas constant until prepare_thermochemistry.

class epcsaft._core.IdealDIPPR107(coefficients: Sequence[float], reference_temperature: float, reference_enthalpy: float, reference_entropy: float)#

Ideal-gas DIPPR equation 107 molar heat-capacity correlation.

Notes

See cp_ideal_dippr_107 in engine/docs/equations.md and ALG-CALORICS in engine/docs/science/algorithms.md. Coefficients do not define their own validity interval.

__init__(coefficients: Sequence[float], reference_temperature: float, reference_enthalpy: float, reference_entropy: float) → None#

Initialize IdealDIPPR107 from the declared inputs.

Parameters:
  • coefficients (Sequence[float]) – Initial value of IdealDIPPR107.coefficients; see its attribute description for units and ordering.

  • reference_temperature (float) – Initial value of IdealDIPPR107.reference_temperature; see its attribute description for units and ordering.

  • reference_enthalpy (float) – Initial value of IdealDIPPR107.reference_enthalpy; see its attribute description for units and ordering.

  • reference_entropy (float) – Initial value of IdealDIPPR107.reference_entropy; see its attribute description for units and ordering.

Returns:

None.

Return type:

None

coefficients: list[float]#

Five values [A, B, C, D, E] for Cp = A+B*((C/T)/sinh(C/T))**2+D*((E/T)/cosh(E/T))**2; A/B/D in J/(mol K), C/E in K.

reference_enthalpy: float#

Ideal-gas molar enthalpy at the anchor, J/mol.

reference_entropy: float#

Ideal-gas molar entropy at the anchor and source pressure, J/(mol K).

reference_temperature: float#

Enthalpy and entropy anchor temperature in K, within the owning interval.

class epcsaft._core.IdealCorrelation(form: IdealForm, source_pressure: float)#

One ideal-gas functional form with its source pressure.

Notes

Native thermochemistry transfers entropy to ThermochemistryRecord.standard_pressure; it does not change source enthalpy anchors.

__init__(form: IdealForm, source_pressure: float) → None#

Initialize IdealCorrelation from the declared inputs.

Parameters:
  • form (IdealForm) – Initial value of IdealCorrelation.form; see its attribute description for units and ordering.

  • source_pressure (float) – Initial value of IdealCorrelation.source_pressure; see its attribute description for units and ordering.

Returns:

None.

Return type:

None

form: IdealForm#

Selected ideal-gas correlation; its coefficients retain their source convention.

source_pressure: float#

Positive pressure of the source entropy standard in Pa.

class epcsaft._core.IdealInterval(lower: float, upper: float, lower_inclusive: bool, upper_inclusive: bool, correlation: IdealCorrelation)#

Explicit temperature domain and endpoint ownership for one correlation.

Notes

Adjacent intervals must meet with exactly one owning endpoint. Gaps and overlaps are rejected. Endpoint values do not imply derivatives through an unqualified join.

__init__(lower: float, upper: float, lower_inclusive: bool, upper_inclusive: bool, correlation: IdealCorrelation) → None#

Initialize IdealInterval from the declared inputs.

Parameters:
  • lower (float) – Initial value of IdealInterval.lower; see its attribute description for units and ordering.

  • upper (float) – Initial value of IdealInterval.upper; see its attribute description for units and ordering.

  • lower_inclusive (bool) – Initial value of IdealInterval.lower_inclusive; see its attribute description for units and ordering.

  • upper_inclusive (bool) – Initial value of IdealInterval.upper_inclusive; see its attribute description for units and ordering.

  • correlation (IdealCorrelation) – Initial value of IdealInterval.correlation; see its attribute description for units and ordering.

Returns:

None.

Return type:

None

correlation: IdealCorrelation#

Ideal-gas correlation valid on this interval.

lower: float#

Positive lower temperature in K.

lower_inclusive: bool#

Whether the lower endpoint belongs to this interval.

upper: float#

Upper temperature in K, greater than lower.

upper_inclusive: bool#

Whether the upper endpoint belongs to this interval.

class epcsaft._core.ThermochemistryRecord(standard_pressure: float, component_intervals: Sequence[Sequence[IdealInterval]])#

Species ideal-gas caloric records on one pressure standard.

Notes

Ideal and total calorics consume this record. Missing or out-of-range records do not remove independently available residual quantities.

__init__(standard_pressure: float, component_intervals: Sequence[Sequence[IdealInterval]]) → None#

Initialize ThermochemistryRecord from the declared inputs.

Parameters:
  • standard_pressure (float) – Initial value of ThermochemistryRecord.standard_pressure; see its attribute description for units and ordering.

  • component_intervals (Sequence[Sequence[IdealInterval]]) – Initial value of ThermochemistryRecord.component_intervals; see its attribute description for units and ordering.

Returns:

None.

Return type:

None

component_intervals: list[list[IdealInterval]]#

Ragged array of n interval lists in component_ids order; each retained species list states its own temperature intervals and endpoint ownership.

standard_pressure: float#

Positive common ideal-gas standard pressure in Pa.

class epcsaft._core.ReactionLogPolynomial(a: float, b: float, c: float, d: float, reference_temperature: float, temperature_min: float, temperature_max: float, standard_state_id: str, e: float = 0.0, f: float = 0.0)#

Source equilibrium law ln K = a + b/T + c ln(T/Tref) + d T + e/T² + f T².

Notes

See reaction_constant_ln_polynomial in engine/docs/equations.md. Without an explicit ReactionReference, equilibrium requires EOS_STANDARD_STATE_ID. With a source reference and the problem neutral_reference, native code converts the source standard. An isothermal K alone supplies no caloric derivative.

__init__(a: float, b: float, c: float, d: float, reference_temperature: float, temperature_min: float, temperature_max: float, standard_state_id: str, e: float = 0.0, f: float = 0.0) → None#

Initialize ReactionLogPolynomial from the declared inputs.

Parameters:
  • a (float) – Initial value of ReactionLogPolynomial.a; see its attribute description for units and ordering.

  • b (float) – Initial value of ReactionLogPolynomial.b; see its attribute description for units and ordering.

  • c (float) – Initial value of ReactionLogPolynomial.c; see its attribute description for units and ordering.

  • d (float) – Initial value of ReactionLogPolynomial.d; see its attribute description for units and ordering.

  • reference_temperature (float) – Initial value of ReactionLogPolynomial.reference_temperature; see its attribute description for units and ordering.

  • temperature_min (float) – Initial value of ReactionLogPolynomial.temperature_min; see its attribute description for units and ordering.

  • temperature_max (float) – Initial value of ReactionLogPolynomial.temperature_max; see its attribute description for units and ordering.

  • standard_state_id (str) – Initial value of ReactionLogPolynomial.standard_state_id; see its attribute description for units and ordering.

  • e (float) – Inverse-square-temperature coefficient in K².

  • f (float) – Square-temperature coefficient in 1/K².

Returns:

None.

Return type:

None

a: float#

Natural-log constant coefficient, dimensionless.

b: float#

Reciprocal-temperature coefficient, K.

c: float#

Log-temperature coefficient, dimensionless.

d: float#

Linear-temperature coefficient, 1/K.

e: float#

Inverse-square-temperature coefficient, K²; defaults to zero.

f: float#

Square-temperature coefficient, 1/K²; defaults to zero.

reference_temperature: float#

Positive logarithm reference temperature Tref in K.

standard_state_id: str#

Identity of the source activity standard; K is dimensionless on this standard.

temperature_max: float#

Inclusive upper validity temperature in K.

temperature_min: float#

Inclusive lower validity temperature in K.

class epcsaft._core.ParameterFamily#

Native independent parameter family and coordinate units.

Notes

Native enum name/value properties follow the module convention in epcsaft._core.

Indices select native storage slots, not component tuples. A symmetric tied parameter may identify multiple flattened slots. Native parameter construction owns the selected model and admitted slots.

AssociationEnergyOverK: ParameterFamily#

Association energy divided by Boltzmann’s constant, K, flattened site-pair slots.

AssociationVolume: ParameterFamily#

Association bonding-volume coefficient, dimensionless, flattened site-pair slots.

BornCDielectric: ParameterFamily#

Born dielectric coefficient, dimensionless; scalar slot.

BornDiameter: ParameterFamily#

Born diameter in angstrom, component slots.

CationPairMixing: ParameterFamily#

Declared cation-pair mixing coefficient in kg/mol; slot in sorted cation-pair order.

CationTripleMixing: ParameterFamily#

Declared cation-triple mixing coefficient in kg^2/mol^2; slot in sorted cation-pair order.

DebyeHuckelDiameter: ParameterFamily#

Debye-Huckel closest-approach diameter in angstrom, component slots.

DielectricTemperature: ParameterFamily#

Solvent dielectric temperature coefficient in K, component slots.

DielectricVolume: ParameterFamily#

Solvent dielectric molar-volume coefficient in m^3/mol, component slots.

DispersionEnergyOverK: ParameterFamily#

Dispersion energy divided by Boltzmann’s constant, K, component slots.

IonSuppressionCoefficient: ParameterFamily#

Ion suppression coefficient, dimensionless, in charged-component slots.

IonicRegionRelativePermittivity: ParameterFamily#

Ionic-region relative permittivity, dimensionless; scalar slot.

Kij: ParameterFamily#

Unlike dispersion interaction coefficient, dimensionless, flattened component-pair slots.

KijReciprocalTemperatureSlope: ParameterFamily#

b_ij in k_ij(T)=k_ij+b_ij*(1/T-1/Tref), K, flattened component-pair slots.

Lij: ParameterFamily#

Unlike size interaction coefficient, dimensionless, flattened component-pair slots.

PackingDiameter: ParameterFamily#

Ionic packing diameter in angstrom, component slots.

PathwayWeight: ParameterFamily#

Pathway weight coefficient b_0, b_alpha or b_T, dimensionless; slots 0, 1, 2.

SegmentCount: ParameterFamily#

Segment count per molecule, dimensionless, component slots.

SigmaConstant: ParameterFamily#

Constant segment diameter in angstrom, component slots.

TemperatureLawCoefficient: ParameterFamily#

Coefficient slot of a declared temperature law; units depend on the declared form and polynomial power.

class epcsaft._core.ActiveParameter(family: ParameterFamily, indices: Sequence[int])#

One independent parameter value assigned to native storage slots.

__init__(family: ParameterFamily, indices: Sequence[int]) → None#

Initialize ActiveParameter from the declared inputs.

Parameters:
  • family (ParameterFamily) – Initial value of ActiveParameter.family; see its attribute description for units and ordering.

  • indices (Sequence[int]) – Initial value of ActiveParameter.indices; see its attribute description for units and ordering.

Returns:

None.

Return type:

None

family: ParameterFamily#

Family that determines physical meaning and units; see ParameterFamily.

indices: list[int]#

Native zero-based storage slots sharing this value, length at least one; pair slots are flattened in row-major order.

class epcsaft._core.DerivativeOrder#

Requested derivative information from the native energy owner.

Notes

Native enum name/value properties follow the module convention in epcsaft._core.

Gradient: DerivativeOrder#

Value and first partial derivatives.

Hessian: DerivativeOrder#

Value, gradient and second partial derivatives.

PressureSlope: DerivativeOrder#

Reduced energy information sufficient for a pressure slope; not a full Hessian and not admitted by neutral_property.

Value: DerivativeOrder#

Central value only; derivative arrays are empty.

class epcsaft._core.NeutralProperty#

Observable for the restricted single-neutral-component derivative reader.

Notes

Native enum name/value properties follow the module convention in epcsaft._core.

Pressure: NeutralProperty#

Pressure in Pa.

ResidualHelmholtz: NeutralProperty#

Residual Helmholtz energy divided by nRT, dimensionless.

class epcsaft._core.NeutralPropertyDerivatives#

Single-component property partial derivatives on (T, rho).

gradient: list[float]#

Length 2 in [T, rho] order when requested, otherwise empty; observable units divided by K or mol/m^3.

hessian: list[float]#

Flattened row-major (2, 2) array in [T, rho] order when requested, otherwise empty; units divide the observable unit by both coordinate units.

value: float#

dimensionless residual Helmholtz energy or pressure in Pa.

Type:

Requested observable

class epcsaft._core.PropertyObservable#

Homogeneous-state observable and its molar units.

Notes

Native enum name/value properties follow the module convention in epcsaft._core.

Heat capacities hold composition fixed. Ideal and total properties require admitted thermochemistry. Actions retain these observable units, because path variables are dimensionless.

IdealEnthalpy: PropertyObservable#

Ideal molar enthalpy, J/mol.

IdealEntropy: PropertyObservable#

Ideal molar entropy, J/(mol K).

IdealInternalEnergy: PropertyObservable#

Ideal molar internal energy, J/mol.

IdealIsobaricHeatCapacity: PropertyObservable#

Ideal molar isobaric heat capacity, J/(mol K).

IdealIsochoricHeatCapacity: PropertyObservable#

Ideal molar isochoric heat capacity, J/(mol K).

LogFugacityCoefficient: PropertyObservable#

Natural logarithm of the component fugacity coefficient, dimensionless; pressure-chart only, one returned result per component.

ResidualEnthalpy: PropertyObservable#

Residual molar enthalpy, J/mol.

ResidualEntropy: PropertyObservable#

Residual molar entropy, J/(mol K).

ResidualInternalEnergy: PropertyObservable#

Residual molar internal energy, J/mol.

ResidualIsobaricHeatCapacity: PropertyObservable#

Residual molar isobaric heat capacity, J/(mol K).

ResidualIsochoricHeatCapacity: PropertyObservable#

Residual molar isochoric heat capacity, J/(mol K).

TotalEnthalpy: PropertyObservable#

Total molar enthalpy, J/mol.

TotalEntropy: PropertyObservable#

Total molar entropy, J/(mol K).

TotalInternalEnergy: PropertyObservable#

Total molar internal energy, J/mol.

TotalIsobaricHeatCapacity: PropertyObservable#

Total molar isobaric heat capacity, J/(mol K).

TotalIsochoricHeatCapacity: PropertyObservable#

Total molar isochoric heat capacity, J/(mol K).

class epcsaft._core.PropertyActionStatus#

Availability or refusal cause for a homogeneous-state property action.

Notes

Native enum name/value properties follow the module convention in epcsaft._core.

AssociationIllConditioned: PropertyActionStatus#

Association-site conditioning fails the declared criterion.

AssociationResidual: PropertyActionStatus#

The association residual does not meet its admission criterion.

AssociationSingular: PropertyActionStatus#

The implicit association-site Jacobian is singular.

Available: PropertyActionStatus#

Requested quantity is available on the admitted branch.

CentralPropertyUnavailable: PropertyActionStatus#

The central observable is unavailable.

DensityUnavailable: PropertyActionStatus#

A required pressure-closed density is unavailable.

IonicInsertion: PropertyActionStatus#

Requested charged insertion is unavailable on an ion-free support.

MissingThermochemistry: PropertyActionStatus#

Required species thermochemistry is absent.

Nonfinite: PropertyActionStatus#

A required value or derivative is nonfinite.

OutsideInterval: PropertyActionStatus#

Temperature lies outside a required source interval.

PressureSingular: PropertyActionStatus#

The pressure-density slope does not admit the requested implicit action.

SupportChange: PropertyActionStatus#

Requested derivative leaves the admitted composition support or meets a singular insertion.

ThermalBoundary: PropertyActionStatus#

Requested thermal derivative crosses an unqualified source-interval endpoint.

class epcsaft._core.ParameterActionDirection(family: ParameterFamily, indices: Sequence[int], value: float)#

Physical increment of one native parameter direction.

__init__(family: ParameterFamily, indices: Sequence[int], value: float) → None#

Initialize ParameterActionDirection from the declared inputs.

Parameters:
  • family (ParameterFamily) – Initial value of ParameterActionDirection.family; see its attribute description for units and ordering.

  • indices (Sequence[int]) – Initial value of ParameterActionDirection.indices; see its attribute description for units and ordering.

  • value (float) – Initial value of ParameterActionDirection.value; see its attribute description for units and ordering.

Returns:

None.

Return type:

None

family: ParameterFamily#

Parameter family and its physical unit; see ParameterFamily.

indices: list[int]#

Native storage slots receiving the increment, in the same convention as ActiveParameter.indices.

value: float#

Physical increment in the selected family’s native units, not a dimensionless derivative normalization.

class epcsaft._core.DensityActionDirection(temperature: float = 0.0, molar_density: float = 0.0, composition: Sequence[float] = (), parameter: Sequence[ParameterActionDirection] = ())#

Direction on the homogeneous density chart.

Notes

The path variable is dimensionless. Mixed actions contract all supplied directions; divide by each physical increment to form a partial derivative.

__init__(temperature: float = 0.0, molar_density: float = 0.0, composition: Sequence[float] = (), parameter: Sequence[ParameterActionDirection] = ()) → None#

Initialize DensityActionDirection from the declared inputs.

Parameters:
  • temperature (float) – Initial value of DensityActionDirection.temperature; see its attribute description for units and ordering.

  • molar_density (float) – Initial value of DensityActionDirection.molar_density; see its attribute description for units and ordering.

  • composition (Sequence[float]) – Initial value of DensityActionDirection.composition; see its attribute description for units and ordering.

  • parameter (Sequence[ParameterActionDirection]) – Initial value of DensityActionDirection.parameter; see its attribute description for units and ordering.

Returns:

None.

Return type:

None

composition: list[float]#

Dimensionless mole-fraction increments, length n in component_ids order. Supply n zeros for no composition motion; an empty vector is rejected by the native action readers. Increments must preserve normalization and charge balance.

molar_density: float#

Molar density increment in mol/m^3.

parameter: list[ParameterActionDirection]#

Physical parameter increments, in declaration order; empty means no parameter motion.

temperature: float#

Temperature increment in K.

class epcsaft._core.PressureActionDirection(temperature: float = 0.0, pressure: float = 0.0, composition: Sequence[float] = (), parameter: Sequence[ParameterActionDirection] = ())#

Direction on the homogeneous pressure chart.

Notes

The path variable is dimensionless. Mixed actions contract all supplied directions; divide by each physical increment to form a partial derivative.

__init__(temperature: float = 0.0, pressure: float = 0.0, composition: Sequence[float] = (), parameter: Sequence[ParameterActionDirection] = ()) → None#

Initialize PressureActionDirection from the declared inputs.

Parameters:
  • temperature (float) – Initial value of PressureActionDirection.temperature; see its attribute description for units and ordering.

  • pressure (float) – Initial value of PressureActionDirection.pressure; see its attribute description for units and ordering.

  • composition (Sequence[float]) – Initial value of PressureActionDirection.composition; see its attribute description for units and ordering.

  • parameter (Sequence[ParameterActionDirection]) – Initial value of PressureActionDirection.parameter; see its attribute description for units and ordering.

Returns:

None.

Return type:

None

composition: list[float]#

Dimensionless mole-fraction increments, length n in component_ids order. Supply n zeros for no composition motion; an empty vector is rejected by the native action readers. Increments must preserve normalization and charge balance.

parameter: list[ParameterActionDirection]#

Physical parameter increments, in declaration order; empty means no parameter motion.

pressure: float#

Pressure increment in Pa.

temperature: float#

Temperature increment in K.

class epcsaft._core.PropertyActionResult#

Central property and one mixed directional contraction.

action: float | None#

Mixed contraction over all supplied directions, or None with the status cause; retains the observable unit.

component: int | None#

Component index for log fugacity, or None for a mixture caloric property.

energy_order: int#

Highest Helmholtz derivative order required for this result, a count.

observable: PropertyObservable#

Observable identifying the value and action units; see PropertyObservable.

status: PropertyActionStatus#

Availability or specific refusal cause; an available central value can survive an unavailable action.

value: float | None#

Central molar property, or None when unavailable; units follow observable.

class epcsaft._core.DensityBranch#

Requested or established side of the pressure-density structure.

Notes

Native enum name/value properties follow the module convention in epcsaft._core.

A mechanically stable root alone does not establish global phase stability. See ALG-DENSITY in engine/docs/science/algorithms.md.

Liquid: DensityBranch#

Requested liquid-side root.

Unspecified: DensityBranch#

No liquid/vapor branch classification established; this is not a third physical phase.

Vapor: DensityBranch#

Requested vapor-side root.

__int__() → int#

Read the native enum code.

Returns:

Integer enum value; see the module enum-property convention.

Return type:

int

class epcsaft._core.ThermochemistryStatus#

Availability of ideal-gas thermochemistry at the state temperature.

Notes

Native enum name/value properties follow the module convention in epcsaft._core.

Available: ThermochemistryStatus#

The required ideal-gas calorics are available.

MissingRecord: ThermochemistryStatus#

No required thermochemistry record was supplied.

Nonfinite: ThermochemistryStatus#

A required caloric evaluation is nonfinite.

OutsideInterval: ThermochemistryStatus#

A required species temperature interval excludes the state.

class epcsaft._core.PropertyActionDiagnostics#
association_residual: float#

Dimensionless association mass-action residual magnitude.

branch: DensityBranch#

Established density-branch label, or Unspecified.

directional_paths: int#

Number of polarized directional paths.

first_numerical_failure: Convergence | None#

Earliest observed numerical refusal, separate from final convergence.

forward_sweeps: int#

Number of forward derivative sweeps.

pressure_density_derivative: float#

Pressure-chart central dP/drho at fixed T and composition, Pa m^3/mol. Zero when no pressure root was supplied; the density chart does not compute this diagnostic.

pressure_factorizations: int#

Number of implicit pressure factorizations.

pressure_residual: float#

Pressure-chart EOS pressure minus prescribed pressure, Pa. Zero when no pressure root was supplied; this default does not establish pressure closure.

pressure_solves: int#

Number of implicit pressure linear solves.

recordings: int#

Number of automatic-differentiation recordings.

returned_branch: DensityBranch#

Root side classified with the native negative-slope witness, or Unspecified.

site_conditioning: NumericalRank | None#

Numerical work and conditioning for one property-action batch.

site_factorizations: int#

Number of association Jacobian factorizations.

site_pivot_ratio: float#

Dimensionless largest/smallest absolute association pivot ratio when the smallest pivot is positive. Zero when not computed or when the smallest pivot is zero; inspect the action status before interpreting conditioning.

site_rank: int#

Rank of the association-site Jacobian, a count.

site_solves: int#

Number of association linear solves.

stability_determinant: float#

Pressure-chart dimensionless slope (dP/drho)/(RT); mechanical regularity evidence rather than global stability. Zero when no pressure root was supplied; this default does not identify a spinodal.

stable_root_count: int | None#

Number of mechanically stable roots established by the search, or None when not established.

thermal_evaluations: int#

Number of thermal-correlation evaluations.

class epcsaft._core.PropertyActionBatch#

Property actions sharing one central state and implicit work.

density_action: list[float]#

First density action per direction, mol/m^3; empty when density actions are unavailable.

density_convergence: Convergence | None#

Density-closure failure record when a ConvergenceFailure was caught. None for successful pressure closure and for failures without that record.

density_message: str#

Native density refusal explanation, possibly empty.

density_mixed_action: float | None#

Mixed density action over two or three directions, mol/m^3, or None when not requested or unavailable.

density_status: PropertyActionStatus#

Availability or refusal cause for the implicit density actions.

diagnostics: PropertyActionDiagnostics#

Shared conditioning, work and pressure-closure diagnostics.

maximum_energy_order: int#

Reported Helmholtz derivative-order requirement for the batch. It can be populated when evaluation is refused and does not establish completed derivative work.

molar_density: float | None#

Pressure-closed central density in mol/m^3, or None when unavailable or not supplied by this chart.

results: list[PropertyActionResult]#

Results in observable order; log-fugacity requests expand into component_ids order.

solver_options: list[dict[str, Any]]#

Effective numerical settings as named dictionaries with values, provenance and units where declared.

class epcsaft._core.State#
association: float#

Association contribution to A_res/(nRT), dimensionless.

born: float#

Born contribution to A_res/(nRT), dimensionless.

bulk_relative_permittivity: float#

Bulk relative permittivity, dimensionless.

cation_mixing: float#

Cation mixing contribution to A_res/(nRT), dimensionless.

component_property_status: list[PropertyActionStatus]#

Length n, component_ids order; explains component-property availability, including IonicInsertion.

compressibility_factor: float#

Compressibility factor P/(rho RT), dimensionless.

debye_huckel: float#

Debye-Huckel contribution to A_res/(nRT), dimensionless.

density_branch: DensityBranch#

Established density-root branch or Unspecified for a state without a classified root.

density_branch_mismatch: bool#

True only for explicit, opposite requested and returned branches. False means no established mismatch, including an unknown side or an Unspecified request.

density_convergence: Convergence | None#

Pressure-root convergence evidence, or None for a direct density state.

dipolar: float#

Declared polar contribution to A_res/(nRT), dimensionless.

dispersion: float#

Dispersion contribution to A_res/(nRT), dimensionless.

first_numerical_failure: Convergence | None#

Earliest observed numerical refusal, separate from final convergence.

hard_chain: float#

Hard-chain contribution to A_res/(nRT), dimensionless.

heat_capacity_ratio: float | None#

Total Cp/Cv, dimensionless; None unless requested and the required total heat capacities and positive pressure slope are available.

ideal_enthalpy: float | None#

Ideal molar enthalpy in J/mol. None when required ideal-gas thermochemistry is unavailable.

ideal_entropy: float | None#

Ideal molar entropy in J/(mol K). None when required ideal-gas thermochemistry is unavailable.

ideal_internal_energy: float | None#

Ideal molar internal energy in J/mol. None when required ideal-gas thermochemistry is unavailable.

ideal_isobaric_heat_capacity: float | None#

Ideal molar isobaric heat capacity in J/(mol K). None when required ideal-gas thermochemistry is unavailable.

ideal_isochoric_heat_capacity: float | None#

Ideal molar isochoric heat capacity in J/(mol K). None when required ideal-gas thermochemistry is unavailable.

isentropic_compressibility: float | None#

Fixed-composition isentropic compressibility in 1/Pa; None unless requested and total heat capacities and positive pressure slope are available.

isobaric_expansivity: float | None#

Fixed-composition isobaric expansivity in 1/K; None unless requested and the pressure slope is positive.

isothermal_compressibility: float | None#

Fixed-composition isothermal compressibility in 1/Pa; None unless derived properties were requested and the pressure slope is positive.

joule_thomson_coefficient: float | None#

Fixed-composition Joule-Thomson coefficient in K/Pa; None unless requested and the required total Cp and positive pressure slope are available.

log_fugacity_coefficient: list[float | None] | None#

Dimensionless component ln(phi_i), length n in component_ids order. Direct-density states subtract ln(compressibility_factor) from mu_res_i/(RT); pressure-closed states subtract ln(P_target/(rho RT)) using the prescribed pressure. The list is None unless the EOS compressibility factor is positive and finite; unavailable component chemical potentials give None entries.

log_fugacity_parameter_derivative: list[float | None]#

Flattened row-major (n, a) first partials of ln(phi_i) at fixed T/P/x, in inverse native parameter units. Populated only when the fugacity list exists and dP/drho is finite and positive; otherwise empty. Within a populated array, unavailable component insertions have None entries.

molar_density: float#

Molar density in mol/m^3. Multiply by mixture molar mass in kg/mol to obtain kg/m^3.

partial_molar_enthalpy: list[float | None] | None#

Partial molar enthalpies in J/mol, in component_ids order. None when derived properties were not requested; otherwise a length-n list. Entries are None without a positive finite pressure slope or admitted thermochemistry, for unavailable insertions, or for nonfinite results.

partial_molar_entropy: list[float | None] | None#

Partial molar entropies in J/(mol K), in component_ids order. None when derived properties were not requested; otherwise a length-n list. Entries are None without a positive finite pressure slope or admitted thermochemistry, for zero-fraction species or unavailable insertions, or for nonfinite results.

partial_molar_volume: list[float | None] | None#

Partial molar volumes in m^3/mol, in component_ids order. None when derived properties were not requested; otherwise a length-n list. Entries are None without a positive finite pressure slope, for unavailable insertions, or for nonfinite results.

pathway_weight: float | None#

Pathway weight w at this phase’s temperature and composition, or None when no weight is declared.

pressure: float#

Calculated EOS pressure in Pa; a pressure-closed state retains its closure residual.

pressure_density_derivative: float#

dP/drho at fixed temperature and composition, Pa m^3/mol.

rank_records: list[NumericalRank]#

One homogeneous state with SI molar quantities.

Notes

Component arrays use the declared component_ids order. Heat capacities and derived response functions hold composition fixed; they are not reacting equilibrium heat capacities. See full-eos.md, ALG-CALORICS and ALG-ACTIONS in engine/docs/science/.

requested_density_branch: DensityBranch#

Branch requested by pressure closure; Unspecified for direct density states.

residual_chemical_potential_over_rt: list[float | None]#

mu_res/(RT) against ideal gas at the same T and rho; an entry is None for unavailable charged insertion.

Type:

Length n in component_ids order

residual_enthalpy: float#

Residual molar enthalpy in J/mol. Residual means minus ideal gas at the same T and rho.

residual_entropy: float#

Residual molar entropy in J/(mol K). Residual means minus ideal gas at the same T and rho.

residual_helmholtz: float#

Residual molar Helmholtz energy divided by RT, dimensionless.

residual_internal_energy: float#

Residual molar internal energy in J/mol. Residual means minus ideal gas at the same T and rho.

residual_isobaric_heat_capacity: float | None#

Residual molar isobaric heat capacity in J/(mol K). Residual means minus ideal gas at the same T and rho. None when the pressure slope does not admit the Cp calculation.

residual_isochoric_heat_capacity: float#

Residual molar isochoric heat capacity in J/(mol K). Residual means minus ideal gas at the same T and rho.

returned_density_branch: DensityBranch#

Side from existing finite-search evidence or the locally admitted anchor label. Unspecified when no side is established. A wrongly labelled external anchor can conceal a mismatch; this attribute does not independently validate its physical phase.

site_fractions: list[float]#

Length s of dimensionless unbonded fractions in declared site order.

solver_options: list[dict[str, Any]]#

Effective named solver settings with provenance.

speed_of_sound: float | None#

Thermodynamic sound speed at frozen composition in m/s; None unless requested, the pressure slope and calorics are admitted, and occupied components have positive molar masses.

stable_root_count: int | None#

Number of mechanically stable roots established by a pressure search, or None when not established.

thermochemistry_status: ThermochemistryStatus#

Availability of the ideal-gas thermochemistry used by ideal and total quantities.

total_enthalpy: float | None#

Total molar enthalpy in J/mol. None when required ideal-gas thermochemistry is unavailable.

total_entropy: float | None#

Total molar entropy in J/(mol K). None when required ideal-gas thermochemistry is unavailable.

total_internal_energy: float | None#

Total molar internal energy in J/mol. None when required ideal-gas thermochemistry is unavailable.

total_isobaric_heat_capacity: float | None#

Total molar isobaric heat capacity in J/(mol K). None when required ideal-gas thermochemistry is unavailable.

total_isochoric_heat_capacity: float | None#

Total molar isochoric heat capacity in J/(mol K). None when required ideal-gas thermochemistry is unavailable.

unavailable_properties: list[tuple[str, PropertyActionStatus]]#
class epcsaft._core.DensityDiagnosticPoint#

One sampled or refined point on a fixed-composition isotherm.

cause: str#

Native failure or refinement explanation, possibly empty.

declared: bool#

False for extra samples introduced by the adaptive slope search; True for records retaining the declared-evidence default, including failed declared nodes and unresolved brackets. This marker does not indicate successful resolution.

linked: bool#

Whether the diagnostic linked this point through its scan/refinement logic; not a global phase-stability statement.

lower: float#

Lower density bracket endpoint, mol/m^3.

mechanical_sign: int#

+1 for positive slope and -1 for negative slope. Spinodal records force this value to zero even when their retained slope is not exactly zero; unevaluated records also retain zero.

Type:

Sign of dP/drho for ordinary evaluated samples and pressure roots

molar_density: float#

Point density in mol/m^3.

packing_fraction: float#

Dimensionless packing fraction; may be nonfinite for an unevaluated or failed point.

pressure: float#

EOS pressure in Pa; may be nonfinite after evaluation failure.

pressure_density_derivative: float#

dP/drho at fixed T/x, Pa m^3/mol; may be nonfinite after evaluation failure.

residual: float#

pressure in Pa for pressure crossings or dimensionless (dP/drho)/(RT) for spinodals; may be nonfinite after refusal.

Type:

Producer’s root residual

stop: str#

Native diagnostic termination name.

upper: float#

Upper density bracket endpoint, mol/m^3.

class epcsaft._core.DensityDiagnosticBracket#

A declared pressure-crossing density bracket.

lower: float#

Lower molar density in mol/m^3.

lower_residual: float#

Pressure minus target pressure at lower, Pa.

upper: float#

Upper molar density in mol/m^3.

upper_residual: float#

Pressure minus target pressure at upper, Pa.

class epcsaft._core.DensityDiagnostics#

Finite pressure-root and mechanical-loop search evidence.

declared_brackets: list[DensityDiagnosticBracket]#

Pressure-crossing brackets declared by the finite search.

declared_crossings: int#

Number of strict sign-changing pressure brackets between connected declared nodes; equals len(declared_brackets). Exact-zero samples and additional adaptive crossings do not increase this count.

evaluation_order: DerivativeOrder#

Derivative order used to test finite evaluability.

evaluations: int#

Number of diagnostic EOS evaluations.

finite_domain: DensityDiagnosticPoint | None#

Refined finite-domain boundary point, or None if no such search was requested or retained. Only its density bounds, stopping cause and availability cause are defined.

first_numerical_failure: Convergence | None#

Earliest observed site or density refusal during this search.

geometric_cap: float#

Packing-derived upper density bound in mol/m^3; not proof of finite evaluability below it.

pressure_roots: list[DensityDiagnosticPoint]#

Refined pressure crossings; each point retains its bracket and cause.

samples: list[DensityDiagnosticPoint]#

Sampled points in the retained evaluation order.

solver_options: list[dict[str, Any]]#

Effective named numerical settings and provenance.

spinodals: list[DensityDiagnosticPoint]#

Refined zeros of dP/drho, not global coexistence states.

stop: str#

Diagnostic termination explanation; an incomplete search does not establish uniqueness.

unresolved: list[DensityDiagnosticPoint]#

Points or intervals not resolved within the declared work and domain.

class epcsaft._core.SweepCounters#
directional_paths: int#
forward: int#

Number of forward derivative sweeps.

hessian_calls: int#

Number of Hessian evaluations.

maximum_energy_order: int#

Cumulative derivative work counts for a HelmholtzModel.

recordings: int#

Number of automatic-differentiation recordings.

reverse: int#

Number of reverse derivative sweeps.

class epcsaft._core.HelmholtzModel(parameters: Parameters, active_parameters: Sequence[ActiveParameter] = (), thermochemistry: ThermochemistryRecord | None = None, solver_options: Mapping[str, float] | None = None)#

Native Helmholtz EOS, exact actions and pressure closure.

Notes

Parameters and optional thermochemistry remain fixed for this model. Active parameters declare exact derivative coordinates; no finite differences are used for calculation. See ALG-DENSITY and ALG-ACTIONS in engine/docs/science/algorithms.md.

__init__(parameters: Parameters, active_parameters: Sequence[ActiveParameter] = (), thermochemistry: ThermochemistryRecord | None = None, solver_options: Mapping[str, float] | None = None) → None#

Initialize HelmholtzModel from the declared inputs.

Parameters:
  • parameters (Parameters) – Admitted native EOS parameters.

  • active_parameters (Sequence[ActiveParameter]) – Independent native parameter slots in requested derivative-column order.

  • thermochemistry (Optional[ThermochemistryRecord]) – Optional species thermal records in component order; absence leaves ideal/total consumers unavailable.

  • solver_options (Mapping[str, float] | None) – Initial value of HelmholtzModel.solver_options; see its attribute description for units and ordering.

Returns:

None.

Return type:

None

active_parameter_values: list[float]#

Active parameter values in active order, each in its family’s native unit.

counters() → SweepCounters#

Read cumulative differentiation work.

Returns:

SweepCounters since model construction or reset_counters.

Return type:

SweepCounters

density_actions(temperature: float, molar_density: float, mole_fractions: Sequence[float], observables: Sequence[PropertyObservable], directions: Sequence[DensityActionDirection]) → PropertyActionBatch#

Contract exact homogeneous-property derivatives on the density chart.

Parameters:
  • temperature (float) – Positive absolute temperature in K.

  • molar_density (float) – Positive molar density in mol/m^3.

  • mole_fractions (Sequence[float]) – Length n, dimensionless mole fractions in component_ids order; normalized and charge neutral.

  • observables (Sequence[PropertyObservable]) – Ordered property selections; values and contractions use PropertyObservable units.

  • directions (Sequence[DensityActionDirection]) – Ordered physical increments defining one mixed property contraction.

Returns:

PropertyActionBatch with central values, contractions and per-result causes.

Return type:

PropertyActionBatch

Notes

One through three directions form the mixed contraction. All action units equal the observable unit. LogFugacityCoefficient is refused on this chart; see ALG-ACTIONS.

density_diagnostics(temperature: float, pressure: float, composition: Sequence[float], request: DensityDiagnosticRequest) → DensityDiagnostics#

Inspect a finite isotherm grid and refine crossings.

Parameters:
  • temperature (float) – Positive absolute temperature in K.

  • pressure (float) – Positive prescribed pressure in Pa.

  • composition (Sequence[float]) – Length n, dimensionless mole fractions in component_ids order; normalized and charge neutral.

  • request (DensityDiagnosticRequest) – Grid, bracket widths, budgets and optional finite-domain search.

Returns:

DensityDiagnostics with pressure roots, slope zeros and unresolved intervals.

Return type:

DensityDiagnostics

Notes

Both absolute and logarithmic bracket-width criteria apply. Unresolved finite searches retain their cause and do not prove a unique root.

log_fugacity_terms(temperature: float, molar_density: float, mole_fractions: Sequence[float]) → LogFugacityTerms#

Return each residual Helmholtz term’s contribution to ln phi_i and ln Z at a T-rho state.

molar_density_upper_bound(temperature: float, composition: Sequence[float]) → float#

Read the packing-derived density limit.

Parameters:
  • temperature (float) – Positive absolute temperature in K.

  • composition (Sequence[float]) – Length n, dimensionless mole fractions in component_ids order; normalized and charge neutral.

Returns:

Geometric molar-density bound in mol/m^3; finite EOS evaluation throughout the interval is not established.

Return type:

float

neutral_property(temperature: float, molar_density: float, property: NeutralProperty, order: DerivativeOrder) → NeutralPropertyDerivatives#

Evaluate a single-neutral-component property and exact partials.

Parameters:
  • temperature (float) – Positive absolute temperature in K.

  • molar_density (float) – Positive molar density in mol/m^3.

  • property (NeutralProperty) – Select dimensionless residual Helmholtz energy or pressure in Pa.

  • order (DerivativeOrder) – Value, Gradient or Hessian; PressureSlope is refused here.

Returns:

Value, gradient and row-major Hessian on [T (K), rho (mol/m^3)].

Return type:

NeutralPropertyDerivatives

Notes

Restricted to one neutral component without association sites, active parameters, electrolyte or permittivity declarations. Arrays not requested by order are empty.

packing_fraction_coefficient(temperature: float, composition: list[float]) → float#

Evaluate the coefficient in eta = kappa(T,x) rho.

Parameters:
  • temperature (float) – Positive absolute temperature in K.

  • composition (list[float]) – Length n, dimensionless mole fractions in component_ids order; normalized and charge neutral.

Returns:

Packing coefficient kappa in m^3/mol; eta is dimensionless.

Return type:

float

pressure_action_difference(temperature: float, pressure: float, mole_fractions: Sequence[float], branch: DensityBranch, observables: Sequence[PropertyObservable], direction: PressureActionDirection, step: float, tau: float, kappa: float) → list[DifferenceCheck]#

Compare first-order pressure actions with native central differences (verification only).

pressure_actions(temperature: float, pressure: float, mole_fractions: Sequence[float], branch: DensityBranch, observables: Sequence[PropertyObservable], directions: Sequence[PressureActionDirection], anchor_density: float | None = None) → PropertyActionBatch#

Contract exact property derivatives through pressure closure.

Parameters:
  • temperature (float) – Positive absolute temperature in K.

  • pressure (float) – Positive prescribed pressure in Pa.

  • mole_fractions (Sequence[float]) – Length n, dimensionless mole fractions in component_ids order; normalized and charge neutral.

  • branch (DensityBranch) – Requested density branch; a stable root need not be globally stable.

  • observables (Sequence[PropertyObservable]) – Ordered property selections; values and contractions use PropertyObservable units.

  • directions (Sequence[PressureActionDirection]) – Ordered physical increments; mixed actions contract all directions, whereas each first density action is reported separately.

  • anchor_density (Optional[float]) – Optional previous density in mol/m^3 for the same branch; None requests an unanchored search.

Returns:

PropertyActionBatch with pressure-root evidence and density actions.

Return type:

PropertyActionBatch

Notes

One through three directions form the mixed contraction on the admitted branch. Each log-fugacity observable expands into component order. A central value can remain available when an action is refused.

reset_counters() → None#

Reset cumulative derivative-work counts.

Returns:

None.

Return type:

None

solver_options: list[dict[str, Any]]#

Effective named numerical settings with values and provenance.

state(temperature: float, molar_density: float, mole_fractions: Sequence[float], derived_properties: bool = False) → State#

Evaluate one homogeneous state on the density chart.

Parameters:
  • temperature (float) – Positive absolute temperature in K.

  • molar_density (float) – Positive molar density in mol/m^3.

  • mole_fractions (Sequence[float]) – Length n, dimensionless mole fractions in component_ids order; normalized and charge neutral.

  • derived_properties (bool) – Request fixed-composition response functions and partial molar quantities in addition to the ordinary state.

Returns:

State at the supplied T, rho and composition.

Return type:

State

Notes

No pressure root is solved. Invalid physical inputs raise ParameterError; native evaluation failures raise EosError. Derived quantities preserve their independent unavailability causes.

state_at_pressure(temperature: float, pressure: float, mole_fractions: Sequence[float], branch: DensityBranch, anchor_density: float | None = None, derived_properties: bool = False) → State#

Close the EOS pressure on a declared density branch.

Parameters:
  • temperature (float) – Positive absolute temperature in K.

  • pressure (float) – Positive prescribed pressure in Pa.

  • mole_fractions (Sequence[float]) – Length n, dimensionless mole fractions in component_ids order; normalized and charge neutral.

  • branch (DensityBranch) – Requested density branch; a stable root need not be globally stable.

  • anchor_density (Optional[float]) – Optional previous density in mol/m^3 for the same branch; None requests an unanchored search.

  • derived_properties (bool) – Request fixed-composition response functions and partial molar quantities in addition to the ordinary state.

Returns:

State at the resolved molar density, including density convergence and root-count evidence.

Return type:

State

Notes

The search follows ALG-DENSITY. A structurally incomplete root search raises DensityStructureError; an iterative refusal may raise ConvergenceError. A returned root is not a global stability certificate.

states(temperature: Sequence[float], input: Sequence[float], composition: Sequence[Sequence[float]], at_pressure: bool, branch: DensityBranch, derived_properties: bool) → StateBatch#
virial_coefficient_actions(temperature: float, composition: Sequence[float], temperature_direction: float, composition_direction: Sequence[float]) → VirialCoefficientActions#

Return B, C and their exact derivatives along a direction; the composition direction sums to zero.

virial_coefficients(temperature: float, composition: Sequence[float]) → VirialCoefficients#

Return exact B and C for a neutral declaration at temperature in K.

epcsaft._core.property_asl_record(document: ParameterDocument, model: HelmholtzModel, require_phase_identity: bool, solids: Sequence[SolidSpec], neutral_reference: NeutralReferenceDeclaration | None) → str#

Serialize document with the model’s native declarations; epcsaft.eos.property_asl_record owns the arguments.

class epcsaft._core.InfiniteDilutionReference#

Analytic ion reference, with solvent closure and association diagnostics (ALG-REFERENCE).

convergence_error: float | None#

no terminal sequence is measured; inner diagnostics are separate.

Type:

None

diagnostics: list[PropertyActionDiagnostics]#
log_fugacity: tuple[float, float]#
molality: float#

Zero mol/kg at the infinite-dilution limit.

parameter_derivative: list[tuple[ResidualEnergyAction, ResidualEnergyAction]]#

Ion log-fugacity partials in inverse native parameter units, independently unavailable.

pure_solvent_log_fugacity: float | None#
pure_solvent_state: State | None#
solvent_cause: str#
solvent_convergence: Convergence | None#
solvent_state: State | None#
solvent_status: PropertyActionStatus#
solver_options: list[dict[str, Any]]#
class epcsaft._core.SolventActivity#

Same-temperature/pressure solvent activity and practical osmotic coefficient.

Notes

The osmotic coefficient uses mol/kg solvent and the pure-solvent reference at the same T/P. Preserve None and the precision-floor Stop value rather than substituting zero; see practical_osmotic_coefficient in engine/docs/equations.md.

cause: str#

Solvent-activity refusal explanation, possibly empty.

osmotic_cause: str#

Independent osmotic-coefficient refusal explanation, possibly empty.

osmotic_coefficient: float | Stop | None#

Dimensionless practical molality osmotic coefficient; None when unavailable, or Stop.converged_to_floor when precision is unresolved below the declared molality floor.

osmotic_parameter_derivative: list[float | None]#

Length a of first osmotic-coefficient partials in inverse parameter units; columns also require an empty osmotic_cause.

parameter_cause: list[str]#

Length a of activity-column explanations.

parameter_status: list[PropertyActionStatus]#

Length a of activity-column availability causes.

solvent_activity: float | None#

Dimensionless solvent activity against the pure-solvent liquid reference, or None with status/cause.

solvent_activity_parameter_derivative: list[float | None]#

Length a of first activity partials in inverse parameter units, with None per unavailable column.

state: State#

Retained mixture state, or the pure-solvent state for a pure-solvent input, when evaluated. After an early refusal this may be a default State or carry only density-convergence evidence; inspect status and cause before consuming its physical fields.

status: PropertyActionStatus#

Solvent-activity availability or refusal cause.

class epcsaft._core.HenryConstant#

Infinite-dilution Henry pressure constant on the mole-fraction scale.

Notes

H_i^px = R*T*rho0*exp(raw_log_reference), with rho0 = 1 mol/m^3. See henry_constant_px in engine/docs/equations.md.

component_index: int#

Solute component index in component_ids order.

henry_constant_px: float | None#

H_i^px = lim(f_i/x_i) in Pa, or None unless the reference is available.

message: str#

Native reference explanation, possibly empty.

observed_terminal_change: float | None#

Dimensionless change between the terminal reference extrapolations, or None without the comparison.

raw_log_reference: float | None#

Dimensionless raw reference contraction on the native density standard, or None when unavailable.

status: NeutralReferenceStatus#

Reference availability or refusal cause.

epcsaft._core.henry_constants(model: HelmholtzModel, temperature: float, pressure: float, solvent_fractions: Sequence[float], solute_indices: Sequence[int]) → list[HenryConstant]#

Evaluate dilute-solute Henry pressure constants.

Parameters:
  • model (HelmholtzModel) – Native Helmholtz model with declared parameters, active coordinates and optional thermochemistry.

  • temperature (float) – Positive absolute temperature in K.

  • pressure (float) – Positive prescribed pressure in Pa.

  • solvent_fractions (Sequence[float]) – Length n in component_ids order, with exactly one pure neutral solvent fraction equal to 1 and all other entries zero.

  • solute_indices (Sequence[int]) – Nonempty sequence of distinct known solute component indices excluding the solvent; native output is sorted by component index.

Returns:

One HenryConstant per requested solute, returned in ascending component-index order.

Return type:

list[HenryConstant]

Notes

See henry_constant_px and ALG-REFERENCE. Constants are in Pa at the supplied T/P with one pure-solvent liquid reference. All model components must be neutral; a charged model returns NonNeutralDeclaration results.

epcsaft._core.solvent_reference(model: HelmholtzModel, temperature: float, pressure: float, solvent_fractions: Sequence[float]) → InfiniteDilutionReference#

Build the same-T/P pure-solvent reference used for solvent activity.

Parameters:
  • model (HelmholtzModel) – Native Helmholtz model with declared parameters, active coordinates and optional thermochemistry.

  • temperature (float) – Positive absolute temperature in K.

  • pressure (float) – Positive prescribed pressure in Pa.

  • solvent_fractions (Sequence[float]) – Length n of normalized, charge-neutral solvent mole fractions in component_ids order; no formula ions are inserted here.

Returns:

InfiniteDilutionReference carrying the pure-solvent state and its independent availability.

Return type:

InfiniteDilutionReference

Notes

The native solvent-reference consumer requires one pure neutral solvent; it does not construct an ionic gauge or infer a mixed-solvent osmotic convention.

epcsaft._core.solvent_activity(model: HelmholtzModel, temperature: float, pressure: float, composition: Sequence[float], reference: InfiniteDilutionReference) → SolventActivity#

Evaluate solvent activity and the practical osmotic coefficient.

Parameters:
  • model (HelmholtzModel) – Native Helmholtz model with declared parameters, active coordinates and optional thermochemistry.

  • temperature (float) – Positive absolute temperature in K.

  • pressure (float) – Positive prescribed pressure in Pa.

  • composition (Sequence[float]) – Length n, dimensionless mole fractions in component_ids order; normalized and charge neutral.

  • reference (InfiniteDilutionReference) – Reference carrying an admitted pure-solvent state for the same model, T/P and numerical settings; solvent_reference is sufficient and no ionic limit is required.

Returns:

SolventActivity with a finite-composition state and independent quantity/column causes.

Return type:

SolventActivity

Notes

Requires an admitted pure-solvent reference at the same T/P. Precision-floor refusal of the osmotic coefficient does not remove other available properties.

class epcsaft._core.ElectrolyteActivity#
mean_ionic_log_molality_scale: float#

Natural logarithm of the mean ionic molality-scale activity coefficient, dimensionless.

mean_ionic_molality_scale: float#

Mean ionic activity coefficient on the mol/kg-solvent scale, dimensionless.

mean_ionic_mole_fraction_scale: float#

Stoichiometric mean ionic activity coefficient on the mole-fraction scale, dimensionless.

mean_ionic_parameter_derivative: list[ResidualEnergyAction]#

One charge-neutral salt activity on an infinite-dilution convention.

Notes

The formula molality is mol of salt formula units per kg of declared solvent. Explicit ion amounts follow stoichiometry and charge balance. See ALG-REFERENCE in engine/docs/science/algorithms.md.

osmotic_coefficient: float | Stop | None#

Dimensionless practical molality osmotic coefficient; None without an admitted solvent reference, or Stop.converged_to_floor when unresolved below the declared precision floor.

single_ion: tuple[float, float]#

Two dimensionless mole-fraction-scale coefficients in (cation, anion) order; their convention is the supplied reference, not independently measurable single-ion activities.

solver_options: list[dict[str, Any]]#

Effective numerical settings for the calculation.

epcsaft._core.infinite_dilution_reference(model: HelmholtzModel, temperature: float, pressure: float, solvent_fractions: Sequence[float], ion_indices: tuple[int, int], stoichiometry: tuple[int, int]) → InfiniteDilutionReference#

Follow the declared charge-neutral salt dilution path.

Parameters:
  • model (HelmholtzModel) – Native Helmholtz model with declared parameters, active coordinates and optional thermochemistry.

  • temperature (float) – Positive absolute temperature in K.

  • pressure (float) – Positive prescribed pressure in Pa.

  • solvent_fractions (Sequence[float]) – Length n of normalized, charge-neutral solvent mole fractions in component_ids order; no formula ions are inserted here.

  • ion_indices (tuple[int, int]) – Two component indices in (cation, anion) order.

  • stoichiometry (tuple[int, int]) – Two positive formula-unit ion counts in (cation, anion) order; the resulting formula must be charge neutral.

Returns:

InfiniteDilutionReference in (cation, anion) order, including terminal change and per-parameter availability.

Return type:

InfiniteDilutionReference

Notes

The retained molality is finite and source-convention specific; terminal agreement is numerical evidence, not a universal limit-error bound. See ALG-REFERENCE.

epcsaft._core.electrolyte_activity(model: HelmholtzModel, temperature: float, pressure: float, solvent_fractions: Sequence[float], ion_indices: tuple[int, int], stoichiometry: tuple[int, int], molality: float, reference: InfiniteDilutionReference) → ElectrolyteActivity#

Evaluate salt activity at a declared formula molality.

Parameters:
  • model (HelmholtzModel) – Native Helmholtz model with declared parameters, active coordinates and optional thermochemistry.

  • temperature (float) – Positive absolute temperature in K.

  • pressure (float) – Positive prescribed pressure in Pa.

  • solvent_fractions (Sequence[float]) – Length n of normalized, charge-neutral solvent mole fractions in component_ids order; no formula ions are inserted here.

  • ion_indices (tuple[int, int]) – Two component indices in (cation, anion) order.

  • stoichiometry (tuple[int, int]) – Two positive formula-unit ion counts in (cation, anion) order; the resulting formula must be charge neutral.

  • molality (float) – Finite positive formula-unit concentration in mol/kg declared solvent; zero is rejected.

  • reference (InfiniteDilutionReference) – Infinite-dilution reference for the same model, T/P, solvent, ions and stoichiometry.

Returns:

ElectrolyteActivity with dimensionless ionic coefficients and a separately available osmotic coefficient.

Return type:

ElectrolyteActivity

Notes

Ion mole fractions are formed natively from formula stoichiometry and solvent mass. This operation requires a matching admitted reference; it does not change source parameter validity.