Native equilibrium#

class epcsaft._core.PhaseKind#

Declared fluid phase branch.

Notes

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

Liquid: PhaseKind#

Liquid-side density branch; not proof of global stability.

Vapor: PhaseKind#

Vapor-side density branch; not proof of global stability.

class epcsaft._core.AmountKind#

Whether a phase amount is solved or prescribed.

Notes

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

Free: AmountKind#

Phase amount is an unknown.

Pinned: AmountKind#

Phase amount is fixed as a fraction of the resolved feed amount; zero declares an incipient phase.

class epcsaft._core.FeedKind#

Physical basis used to interpret the feed values.

Notes

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

Amounts: FeedKind#

Absolute component amounts in mol.

MassFractions: FeedKind#

Dimensionless component mass fractions on a one-kg mixture basis; divided by molar masses in kg/mol to obtain native molar amounts.

Molalities: FeedKind#

Solute amounts in mol/kg of declared solvent; solvent fractions and solvent_mass_kg supply the absolute basis.

MoleFractions: FeedKind#

Dimensionless component mole fractions, giving a one-mole total feed basis.

class epcsaft._core.AmountSpec#

Free phase amount or prescribed feed-relative fraction.

__init__() → None#

Initialize AmountSpec from the declared inputs.

Returns:

None.

Return type:

None

fraction: float#

Dimensionless pinned amount divided by resolved total feed mol; ignored for a free amount. Zero denotes an incipient phase.

static free() → AmountSpec#

Declare a solved phase amount.

Returns:

Free AmountSpec; no fixed amount fraction.

Return type:

AmountSpec

kind: AmountKind#

Whether to solve the amount or pin its feed-relative fraction.

static pinned(value: float) → AmountSpec#

Declare a feed-relative pinned phase amount.

Parameters:

value (float) – Dimensionless phase amount divided by resolved total feed mol.

Returns:

Pinned AmountSpec; zero declares an incipient phase.

Return type:

AmountSpec

class epcsaft._core.FreeValue#

Fixed intensive value or solved intensive with an optional seed.

__init__() → None#

Initialize FreeValue from the declared inputs.

Returns:

None.

Return type:

None

static fixed(value: float) → FreeValue#

Declare a fixed temperature or pressure.

Parameters:

value (float) – Positive temperature in K or pressure in Pa, according to its consuming field.

Returns:

Fixed FreeValue.

Return type:

FreeValue

free: bool#

True when the intensive is solved rather than held fixed.

value: float#

Fixed value or declared initial guess; K for temperature and Pa for pressure. A missing variable guess is retained natively, not a physical zero.

static variable(guess: float | None = None) → FreeValue#

Declare a solved intensive and optional seed.

Parameters:

guess (Optional[float]) – Optional positive temperature in K or pressure in Pa; None requests native initialization.

Returns:

Variable FreeValue retaining whether a guess was supplied.

Return type:

FreeValue

class epcsaft._core.PhaseSpec#

One declared fluid phase, support and initialization.

Notes

Support and charge admission are owned by compile_problem. A seed supplies no new thermodynamic constraints.

__init__() → None#

Initialize PhaseSpec from the declared inputs.

Returns:

None.

Return type:

None

amount: AmountSpec#

Free amount or dimensionless feed-relative pinned fraction.

composition_guess: list[float]#

Dimensionless mole-fraction seed in support order, length len(support), or empty for native initialization. For direct supplied stability trials, use n entries in component order with zero outside support.

kind: PhaseKind#

Declared liquid or vapor density branch.

name: str#

Caller phase label; it does not select a physical model.

packing_guess: float | None#

Optional dimensionless packing-fraction seed, not a density in mol/m^3.

support: list[int]#

Ordered component indices allowed in this phase; an explicit support cannot acquire extra components.

support_declared: bool#

Whether support is explicit; an omitted support may be completed, while a declared empty support is rejected.

class epcsaft._core.FeedSpec#

Feed declaration with explicit amount or composition basis.

Notes

Native conversion enforces normalization, required molar masses and electroneutrality. Amounts remain absolute; mole fractions establish a one-mole feed.

__init__() → None#

Initialize FeedSpec from the declared inputs.

Returns:

None.

Return type:

None

kind: FeedKind#

Basis selecting the interpretation and native conversion of values.

solvent: list[int]#

Solvent component indices for a molality feed; non-solvent entries of values are solute molalities.

solvent_mass_kg: float#

Positive solvent mass in kg setting the absolute scale of a molality feed; not a total mixture mass.

values: list[float]#

mol for Amounts, dimensionless for mole/mass fractions, or relative solvent molar amounts plus solute mol/kg solvent for Molalities.

Type:

Length n in component_ids order

class epcsaft._core.SpeciesReference#

Species standard selected for a neutral reaction reference.

Notes

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

InfiniteDilution: SpeciesReference#

Solute at infinite dilution in the declared solvent and dilution path.

PureGas: SpeciesReference#

Pure-component vapor reference at the source pressure.

PureLiquid: SpeciesReference#

Pure-component liquid reference at the source pressure.

class epcsaft._core.NeutralReferenceDeclaration#

Solvent and charge-neutral dilution path for source-standard transfer.

Notes

Mixed pure-species overrides require the admitted raw mole-fraction source basis. See ALG-REFERENCE in engine/docs/science/algorithms.md.

__init__() → None#

Initialize NeutralReferenceDeclaration from the declared inputs.

Returns:

None.

Return type:

None

solute_molality_ratios: list[float]#

Length n of dimensionless all-solute molality ratios in component_ids order; solvent entry is zero and the solute path is charge neutral.

solvent_index: int | None#

Index of the single pure neutral solvent, or None before declaration.

species_reference: list[SpeciesReference]#

Optional length-n map in component_ids order; empty retains the default solvent liquid and solute infinite-dilution references.

standard_molality_mol_per_kg: float#

Positive source standard molality in mol/kg solvent.

class epcsaft._core.ReferenceSourceBasis#

Declared activity convention of a source equilibrium constant.

Notes

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

CommonMolalityInfiniteDilution: ReferenceSourceBasis#

Common standard molality with solute infinite-dilution references; solvent-mass conversion is applied once.

RawMoleFractionInfiniteDilution: ReferenceSourceBasis#

Raw mole-fraction reference convention; its basis terms cancel in the native density-standard conversion.

class epcsaft._core.NeutralReferenceStatus#

Availability or refusal cause of a source-reference calculation.

Notes

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

Available: NeutralReferenceStatus#

Requested reference quantity is available.

BranchChange: NeutralReferenceStatus#

The reference path did not retain its declared density branch.

DensityUnavailable: NeutralReferenceStatus#

A required reference density could not be resolved.

FreePressure: NeutralReferenceStatus#

This reference consumer does not admit the requested free-pressure declaration.

FreeTemperature: NeutralReferenceStatus#

This reference consumer does not admit the requested free-temperature declaration.

InvalidDeclaration: NeutralReferenceStatus#

The solvent, path or reference declaration is inadmissible.

NonNeutralDeclaration: NeutralReferenceStatus#

The solvent or solute dilution path violates charge neutrality.

Nonfinite: NeutralReferenceStatus#

A reference quantity is nonfinite.

UnsupportedSourceBasis: NeutralReferenceStatus#

The requested source/species reference combination is unsupported.

class epcsaft._core.NeutralReferenceReactionDiagnostic#

Reference transfer for one declared reaction.

density_convergence: Convergence | None#
diagnostics: PropertyActionDiagnostics#
message: str#

Native explanation retaining the failing reference calculation.

observed_terminal_change: float | None#

Dimensionless change between consecutive terminal extrapolations, or None when unavailable; a local numerical estimate, not a universal error bound.

reaction_index: int#

Zero-based reaction index in the declaration.

reference_pressure_pa: float#

Resolved source reference pressure in Pa.

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

Effective named numerical settings and provenance.

status: NeutralReferenceStatus#

Reference availability or specific refusal cause.

terminal_contraction: float | None#

Dimensionless terminal reaction contraction used for standard-state transfer, or None when unavailable.

terminal_contraction_pressure_derivative: float | None#

First partial of the contraction with respect to system pressure at fixed temperature, 1/Pa; exactly zero for a fixed source pressure, or None when the requested column is unavailable or was not evaluated.

terminal_contraction_pressure_second_derivative: float | None#

Second partial with respect to system pressure at fixed temperature, 1/Pa^2; exactly zero for a fixed source pressure, or None when the requested column is unavailable or was not evaluated.

class epcsaft._core.ReactionReference(source_basis: ReferenceSourceBasis, reference_pressure_pa: float | None = None)#

Source activity basis and pressure of a reaction constant.

__init__(source_basis: ReferenceSourceBasis, reference_pressure_pa: float | None = None) → None#

Initialize ReactionReference from the declared inputs.

Parameters:
  • source_basis (ReferenceSourceBasis) – Initial value of ReactionReference.source_basis; see its attribute description for units and ordering.

  • reference_pressure_pa (Optional[float]) – Initial value of ReactionReference.reference_pressure_pa; see its attribute description for units and ordering.

Returns:

None.

Return type:

None

reference_pressure_pa: float | None#

Fixed source pressure in Pa, or None to use current system pressure; it does not silently become a fixed standard.

source_basis: ReferenceSourceBasis#

Declared source convention used for native standard-state transfer.

class epcsaft._core.ReactionSpec#

One stoichiometric reaction and exactly one thermodynamic target.

Notes

No target silently overrides another. A scalar isothermal constant supplies no temperature derivative. See reaction_affinity and reaction_standard_state_conversion in engine/docs/equations.md.

__init__() → None#

Initialize ReactionSpec from the declared inputs.

Returns:

None.

Return type:

None

affinity_j_per_mol: float | None#

Optional reaction affinity target in J/mol of reaction; mutually exclusive with K and correlation.

correlation: ReactionLogPolynomial | None#

Optional source ln K(T) law with interval and standard identity; mutually exclusive with scalar targets.

equilibrium_constant: float | None#

Optional positive dimensionless K on the native EOS standard without reference, or on the declared source basis with reference. Mutually exclusive with affinity and correlation.

name: str#

Reaction identity used for source matching and diagnostics.

reference: ReactionReference | None#

Optional explicit source-reference declaration; requires the problem’s neutral_reference.

stoichiometry: list[float]#

Length n in component_ids order, products positive and reactants negative; dimensionless stoichiometric numbers.

class epcsaft._core.SolidSpec#

Pure stoichiometric solid in equilibrium with declared fluid species.

Notes

Native classification retains solid amount and saturation-index complementarity. See solid_standard_gibbs, solid_saturation_index and solid_amount_complementarity in engine/docs/equations.md.

__init__() → None#

Initialize SolidSpec from the declared inputs.

Returns:

None.

Return type:

None

amount: AmountSpec#

Free solid amount or Pinned(0) absent solid; other pinned fractions are not admitted.

correlation: ReactionLogPolynomial | None#

Optional source ln K(T) law on an explicit standard and interval.

equilibrium_constant: float | None#

Optional positive dimensionless dissolution K; exactly one of this and correlation is required.

molar_volume_m3_per_mol: float#

Solid molar volume in m^3/mol for its pressure correction.

name: str#

Solid identity used for declaration and diagnostics.

reference: ReactionReference | None#

Source convention and pressure used for native solid-standard conversion.

stoichiometry: list[float]#

Length n of dissolution numbers for solid -> sum(nu_i A_i), in component_ids order; dimensionless and charge neutral.

class epcsaft._core.StabilityOptions#

Finite declared trial search for a tangent-plane descent witness.

Notes

A finite search with no resolved descent is not a global stability certificate. See ALG-STABILITY in engine/docs/science/algorithms.md.

__init__() → None#

Initialize StabilityOptions from the declared inputs.

Returns:

None.

Return type:

None

declaration_budget: int | None#

Optional count limiting candidate topology declarations.

evaluate_supplied_trials: bool#

Evaluate supplied trial points directly rather than optimizing their compositions.

mode: DiscoveryMode#

full default or explicitly limited fast search.

Type:

Discovery only

standard_uncertainty_over_rt: list[float]#

Optional length-n dimensionless species-standard uncertainty estimates in component order.

trial_budget: int | None#

Optional count limiting trial searches.

trials: list[PhaseSpec] | None#

Explicit trial phases, or None for the admitted default supports and seeds; an empty list remains an explicit declaration.

class epcsaft._core.StabilityTrial#

One tangent-plane trial, numerical diagnostics and finite-split evidence.

basis: list[list[float]]#

Rectangular (b, n) conserved trial basis, with b basis rows and n component columns in component order; coefficients are dimensionless. Empty when no compiled trial basis is retained.

composition: list[float]#

Length n, normalized dimensionless trial mole fractions in component order when reconstructed; otherwise empty.

diagnostic_cause: str#

Original density refusal/exception cause; empty when diagnostics complete or not requested. Diagnostic root retention adds density_side, raw root_density_side (0 unspecified, 1 vapor, 2 liquid), identity_root_log_displacement and identity_root_residual to quantities. No side is written on anchor refusal; partial identity quantities survive. This reporting changes neither trial evidence nor measure availability.

donor: int | None#

Candidate donor phase index, or None without an admitted donor.

evidence: str#

Native classification of the observed trial evidence.

message: str#

Trial explanation, including unresolved or refused work.

optimizer: EquilibriumResult#

Retained trial solve and numerical evidence; a solve success alone does not prove descent.

phase: PhaseSpec#

Declared trial phase and support.

present_phase_comparisons: list[StabilityPhaseComparison]#

In declaration order on explicit indeterminate trials; empty on internal searches.

quantities: dict[str, float]#

Named trial quantities; physical units are encoded by each native key and no shared unit applies. Error estimates are local, not enclosures.

raw_coordinates: list[float]#

Native trial chart coordinates in its compiled order; dimensionless logarithms and scaled coordinates are not mole fractions.

raw_residuals: list[float]#

Defining-row residuals in the trial’s native row normalization.

resolved_descent: bool#

True only when a finite descent witness exceeds its numerical uncertainty; not a global search result.

row_transformation: list[list[float]]#

Rows mapping the native trial constraints into the retained basis; dimensionless matrix in producer order.

seed: str#

Native seed label, not an additional physical constraint.

split_checks: list[dict[str, float]]#

Finite donor/split comparisons in trial order; each dictionary retains named values and units in its keys.

split_coordinates: list[float]#

supported log mole fractions, phase amount in mol and log packing. Multipliers are omitted; empty without a retained finite split.

Type:

Finite-split seed blocks for existing phases in declaration order followed by the added trial phase

class epcsaft._core.StabilityReport#

Finite tangent-plane trial evidence for one candidate.

candidate_coordinates: list[float]#

supported log mole fractions, phase amount in mol and log packing. Includes an amount entry for every phase and omits multipliers and free-intensive coordinates; this is not a full CompiledSystem point.

Type:

Repaired candidate phase blocks in declaration order

completed: bool#

Whether the declared finite search completed; does not certify global stability.

first_numerical_failure: Convergence | None#

Earliest observed numerical refusal, separate from final convergence.

last_rank: NumericalRank | None#

Rank of the candidate amount correction, when measured.

message: str#

Search conclusion and any stopping limitation.

no_descent_in_trial_set: bool#
plane_over_rt: list[float]#

Length n of the tangent-plane coefficients divided by RT, dimensionless, in component order.

present_phases: list[dict[str, float]]#

Named present-phase consistency quantities per phase; units follow native dictionary keys.

standard_over_rt: list[float]#

Length n of species standard Gibbs terms divided by RT, dimensionless, in component order.

trials: list[StabilityTrial]#

Trial records in attempted order, including failed or unresolved trials.

work: dict[str, float]#

Counts for this finite search; absent keys have no retained count. root_calls counts density-solve attempts, root_evaluations counts energy evaluations inside those roots, and energy_evaluations counts all energy evaluations. These request-local interval counts are charged by the numerical owners independently of tracing. trial_invocations counts rooted, distinct trials admitted to direct evaluation or search; reconstruction_evaluations counts completed composition reconstructions. driver_invocations and trial_driver_invocations count shared-driver trial calls; iterations, evaluations and hessian_calls sum their returned work. trial_tangent_plane_invocations, trial_tangent_plane_iterations and trial_tangent_plane_newton_steps report the separate reduced tangent-plane search work. association_diagnostic_evaluations counts extra association diagnostics; finite_split_evaluations counts finite donor/split energy comparisons. All are counts; no elapsed time is retained.

class epcsaft._core.DiscoveryRecord#

Retained candidate topology and the finite discovery sequence.

Notes

Discovery changes declared topology only through admitted finite witnesses and work limits. It does not supply a global equilibrium certificate.

candidate: EquilibriumResult#

Retained candidate and its numerical evidence.

declaration: EquilibriumProblem#

Final phase declaration; its phase order owns the returned candidate arrays.

declaration_attempt_coordinates: list[list[float]]#

Native attempted coordinates per declaration; preserved even when no state was admitted.

declaration_roles: list[str]#

Role label per retained declaration attempt.

declarations: list[EquilibriumResult]#

Attempted candidate solves in retained attempt order.

mode: DiscoveryMode#
rounds: list[StabilityReport]#

Stability reports in discovery-round order.

termination: str#
unsearched: list[str]#
work: dict[str, float]#

Accumulated search and shared-driver counts, using StabilityReport.work meanings. driver_invocations, iterations, evaluations and hessian_calls include declaration solves; declaration_invocations counts those driver calls and declaration_initialization_failures counts attempts that failed before invoking the driver. root_calls, root_evaluations and energy_evaluations are numerical-owner counts over the whole discovery request. Non-detailed capture now exposes spans and events previously hidden by the internal counting capture; detailed diagnostic records are unchanged. When a phase removal is attempted, removal_component_error_mol and removal_moiety_error_mol retain the latest maximum absolute component and moiety conservation errors in mol. No elapsed time is retained.

epcsaft._core.cooling_onset(compiled: CompiledSystem) → tuple[EquilibriumResult, list[StabilityReport]]#

Run the native cooling-onset search for an admitted compiled declaration.

Parameters:

compiled (CompiledSystem) – Admitted native compiled system; its HelmholtzModel must remain alive.

Returns:

Tuple of the retained EquilibriumResult and ordered StabilityReports.

Return type:

tuple[EquilibriumResult, list[StabilityReport]]

Notes

The native ALG-EQUILIBRIUM cooling-onset consumer owns eligible declarations, step selection and refusal. Reports retain the finite stability-search limits; no kinetic onset or global certificate is implied.

epcsaft._core.stability_test(compiled: CompiledSystem, central: EquilibriumResult, options: StabilityOptions = ...) → StabilityReport#

Search declared tangent-plane trials around an admitted candidate.

Parameters:
  • compiled (CompiledSystem) – Admitted native compiled system; its HelmholtzModel must remain alive.

  • central (EquilibriumResult) – Admitted candidate from the same compiled declaration.

  • options (StabilityOptions) – Explicit finite trial supports, seeds and work limits.

Returns:

StabilityReport with finite-search evidence, work and unresolved causes.

Return type:

StabilityReport

Notes

Resolved descent is a finite witness. No witness after a finite search is not a global stability proof; see ALG-STABILITY.

class epcsaft._core.CriticalDeclaration#

Seed for the neutral critical-equation candidate.

Notes

The admitted critical cell has one free neutral phase with free T and P. A critical-equation root is not a stability certificate.

__init__() → None#

Initialize CriticalDeclaration from the declared inputs.

Returns:

None.

Return type:

None

density_guess_mol_per_m3: float#

Positive molar-density guess in mol/m^3.

mode_guess: list[float]#

Optional unnormalized amount-perturbation vector in component order; empty selects the lowest seed mode.

class epcsaft._core.EnvelopeCoordinate#

Dimensionless local coordinate selecting an envelope condition.

Notes

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

LogK: EnvelopeCoordinate#

ln(x_incipient[k])-ln(x_feed[k]) for the selected component.

LogPressure: EnvelopeCoordinate#

ln(P/(1 Pa)).

LogTemperature: EnvelopeCoordinate#

ln(T/(1 K)).

class epcsaft._core.EnvelopeCondition#

One local equation used to trace an incipient phase envelope.

__init__() → None#

Initialize EnvelopeCondition from the declared inputs.

Returns:

None.

Return type:

None

component: int#

Component index used by LogK; ignored for LogTemperature and LogPressure.

kind: EnvelopeCoordinate#

Logarithmic local coordinate of the condition.

target: float#

Dimensionless target value of the selected logarithmic coordinate.

class epcsaft._core.CriticalRecord#

Bases: HelmholtzModeRecord

Necessary critical-equation candidate; no global phase stability certificate.

cubic: float#

Dimensionless F_nnn contraction along the normalized amount mode.

class epcsaft._core.EquilibriumProblem#

Declared fluid/reaction/solid equilibrium and extensive constraints.

Notes

Native compilation owns support, conservation, charge, rank and specification admission. Extensive constraints require the consumed species calorics; missing calorics are not inferred from an isothermal constant. See ALG-EQUILIBRIUM.

__init__() → None#

Initialize EquilibriumProblem from the declared inputs.

Returns:

None.

Return type:

None

azeotrope: bool#

Request the admitted binary bubble/dew azeotrope condition; feed composition is its seed.

critical: CriticalDeclaration | None#
discovery: StabilityOptions | None#

Optional finite stability/discovery request; None retains the declared topology solve.

enthalpy_j: float | None#

Optional extensive enthalpy specification in J on the absolute feed basis; not J/mol.

entropy_j_per_k: float | None#

Optional extensive entropy specification in J/K on the absolute feed basis; not J/(mol K).

envelope: EnvelopeCondition | None#

Optional incipient envelope condition.

feed: FeedSpec#

Feed values with an explicit molar, mass or solvent-molality basis.

internal_energy_j: float | None#

Total internal energy in J; UV has free T/P, specified volume and complete ideal records.

neutral_reference: NeutralReferenceDeclaration | None#

Optional explicit solvent/path declaration for source-standard transfers.

phases: list[PhaseSpec]#

Fluid phase declarations in the order used by every phase array.

pressure: FreeValue#

Fixed or free system pressure, Pa.

reactions: list[ReactionSpec]#

Ordered reaction declarations and source targets.

row_tolerance: float#

Caller criterion applied to the maximum absolute classified row residual. Most rows are dimensionless; absent free-solid amount rows retain mol. Numerical floor admission is reported separately.

solids: list[SolidSpec]#

Solid declarations in the order used by solid_amounts and solid_affinity_decades.

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

Read or set effective named numerical solver settings.

Returns:

Named settings with values and provenance when read; None on assignment.

Return type:

list[dict[str, Any]]

spinodal: SpinodalDeclaration | None#

Optional neutral critical-equation declaration.

standard_gibbs_j_per_mol: list[float]#

Optional length-n supplied species Gibbs standards, J/mol in component_ids order; not independent of conflicting reaction targets.

temperature: FreeValue#

Fixed or free absolute temperature, K.

topology_declared: bool#

Whether the supplied phase topology is declared for the solve.

volume_m3: float | None#

Optional total-volume target in m³ on the absolute feed basis; fixed T and solved P.

class epcsaft._core.InventoryBound#

Conservation-only upper-bound evidence for one species.

Notes

These bounds use conservation and nonnegative amounts only. They do not prove phase equilibrium or stability.

amounts_mol: list[float]#

Finite reconstructed component amounts in mol, component_ids order, when available; otherwise empty.

balance_residual: float#

Conservation residual magnitude on the native feed-normalized linear-program chart, dimensionless.

feasibility_termination: str#

Termination explanation for the finite-witness calculation.

feed_normalized_amount: float | None#

Dimensionless maximum amount divided by feed_total for amount bounds; None for a fraction bound or unavailable result.

finite_residual: float#

Dimensionless maximum finite-witness feasibility residual; may be nonfinite if unresolved.

finite_witness: list[float]#

Witness of the finite-feasibility check in native normalized column order, or empty without an optimal finite witness.

floor: float#

Caller-declared dimensionless inventory support floor.

limiting: bool#

Whether the result is a limiting bound rather than an attained finite witness.

log_fraction: float | None#

Natural log of a positive maximum mole fraction, dimensionless; None for zero, amount mode or unavailable result.

lower_bound_residual: float#

Dimensionless lower-bound violation in the normalized linear program.

lp_error: float#

Dimensionless native linear-program error estimate; may be nonfinite if unresolved.

maximum: float | None#

Maximum species amount in mol, or dimensionless mole fraction when fraction=True; None when unresolved or unbounded.

normalization_residual: float#

Dimensionless fractional-chart normalization residual.

species: int#

Component index in component_ids order.

status: str#

Native classification of the bound and its witness; not a thermodynamic equilibrium result.

supported: bool#

Whether the finite inventory can support this species.

termination: str#

Linear-program termination explanation.

witness: list[float]#

Linear-program witness in native column order; fraction mode includes its normalization variable, not just component molar amounts.

epcsaft._core.inventory_bounds(compiled: CompiledSystem, species: Sequence[int], fraction: bool, floor: float) → list[InventoryBound]#

Bound species inventory using conservation and nonnegativity.

Parameters:
  • compiled (CompiledSystem) – Admitted native compiled system; its HelmholtzModel must remain alive.

  • species (Sequence[int]) – Ordered component indices whose inventory bounds are requested.

  • fraction (bool) – True requests dimensionless mole-fraction bounds; False requests absolute mol bounds.

  • floor (float) – Finite nonnegative mole-fraction floor; must be zero when fraction=False. In fraction mode, the number of supported species times floor must not exceed one.

Returns:

One InventoryBound per requested species, preserving input order.

Return type:

list[InventoryBound]

Notes

This calculation has no thermodynamic objective and supplies no phase-stability result.

class epcsaft._core.RowKind#

Physical equation represented by a compiled equilibrium row.

Notes

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

AzeotropeCondition: RowKind#

Binary azeotrope composition equality, dimensionless.

Chemical: RowKind#

Chemical-potential stationarity, normalized by RT.

CriticalCubic: RowKind#

Critical cubic-form condition, native dimensionless normalization.

CriticalMode: RowKind#

Critical-mode null-vector equation, native dimensionless normalization.

CriticalNormalization: RowKind#

Critical-mode normalization, dimensionless.

Electro: RowKind#

Per-phase electroneutrality, dimensionless charge-number contraction.

Enthalpy: RowKind#

Extensive enthalpy specification in its native dimensionless normalization.

Entropy: RowKind#

Extensive entropy specification in its native dimensionless normalization.

EnvelopeCondition: RowKind#

Selected dimensionless logarithmic envelope condition.

InternalEnergy: RowKind#

Extensive internal energy specification divided by feed RT.

Moiety: RowKind#

Conserved moiety balance normalized on the feed basis.

Normalization: RowKind#

Phase mole-fraction normalization, dimensionless.

Pressure: RowKind#

Pressure equality in the native dimensionless row normalization.

ReactionMassAction: RowKind#

Direct logarithmic mole-fraction mass action, dimensionless.

ReactionMolarity: RowKind#

Direct logarithmic molarity mass action, dimensionless.

SaturationPressure: RowKind#

Declared target pressure, normalized by that pressure.

SolidAffinity: RowKind#

-A_s/(RT), dimensionless. Absent free solid: n_s, in mol. Pinned(0) solids have no row.

Type:

Present free solid

SpinodalMode: RowKind#
SpinodalNormalization: RowKind#
Volume: RowKind#

Total extensive volume specification in its native dimensionless normalization.

class epcsaft._core.Row#

Identity of a defining or classification equation.

eqid: str#

Canonical equation-registry identity owning the row’s mathematical definition.

index: int#

Family-specific component, conserved-balance, mode or solid ordinal; not a common species index for all rows.

kind: RowKind#

Physical equation family.

phase: int#

Zero-based declared phase index where applicable; not meaningful for a system-wide row.

class epcsaft._core.PointEvaluation#

Defining rows, objective and numerical floor at a compiled point.

floor: float#

Dimensionless estimated residual floor at this point.

objective: float#

A/(RT) for TV and G/(RT) otherwise. Ideal activity models return zero. A value alone does not establish equilibrium.

Type:

EOS physical potential in mol on the absolute feed basis

values: list[float]#

Length m of defining-row residuals in CompiledSystem.rows order. Most rows are dimensionless; an absent free-solid row is its amount in mol.

class epcsaft._core.CompiledSystem#

Admitted equilibrium chart and exact defining-equation readers.

Notes

The model must outlive this compiled object. The full point has d = primal_size + rank + charge_row_count entries: each fluid phase’s log compositions, free amount when present and log packing; then free-solid amounts in solid declaration order; then mode and free-intensive coordinates where present; then dimensionless conserved and electrical multipliers. Free amounts use mol, free temperature uses K and free pressure uses Pa. See ALG-EQUILIBRIUM and equilibrium/formulation.md.

charge_row_count: int#

Number of per-phase charge constraints.

conserves_total_moles: bool#

Whether the admitted stoichiometry conserves total molar amount.

coordinate_labels() → list[str]#

Quantity and basis of each solved-chart coordinate, in coordinate order.

evaluate(point: Sequence[float]) → PointEvaluation#

Evaluate native defining rows at a full chart point.

Parameters:

point (Sequence[float]) – Full native point in compiled chart order, length d including multipliers; not a flattened physical composition.

Returns:

PointEvaluation with m defining residuals, objective and floor.

Return type:

PointEvaluation

feed_total: float#

Total resolved feed amount in mol; one mol for MoleFractions.

free_intensive_count: int#

Number of solved temperature/pressure coordinates.

generic_nullity: int#

Nullity measured at the generic seed; not a guarantee of rank at a solution.

generic_point() → list[float]#

Construct the native generic chart seed.

Returns:

Full point of length d in the compiled chart; a seed, not an equilibrium result.

Return type:

list[float]

has_ions: bool#

Whether the admitted model contains charged species.

has_reaction: bool#

Whether reaction declarations are present.

hessian(point: Sequence[float], constraint_multipliers: Sequence[float] = ...) → list[float]#

Evaluate exact native Lagrangian curvature.

Parameters:
  • point (Sequence[float]) – Full native point in compiled chart order, length d including multipliers; not a flattened physical composition.

  • constraint_multipliers (Sequence[float]) – Optional optimizer constraint multipliers in native constraint order; empty requests the default curvature.

Returns:

Flattened row-major (d, d) optimizer Lagrangian Hessian in full-point order. Gibbs cells include G/(RT) curvature; feasibility cells have a zero objective and return constraint curvature only.

Return type:

list[float]

jacobian(point: Sequence[float]) → list[float]#

Differentiate defining rows with respect to the full chart.

Parameters:

point (Sequence[float]) – Full native point in compiled chart order, length d including multipliers; not a flattened physical composition.

Returns:

Flattened row-major (m, d) Jacobian; rows follow rows and columns follow the full point.

Return type:

list[float]

jacobian_difference(point: Sequence[float], relative_step: float, tau: float, kappa: float) → list[DifferenceCheck]#

Compare each Jacobian entry with central differences of the rows (verification only).

jacobian_rank: int#

Defining-Jacobian rank measured at the generic point.

last_rank: NumericalRank | None#
lever_jacobian(point: Sequence[float]) → list[float]#

Differentiate defining rows with respect to external physical controls.

Parameters:

point (Sequence[float]) – Full native point in compiled chart order, length d including multipliers; not a flattened physical composition.

Returns:

Flattened row-major (m, 2+n+a) matrix in [T, P, feed amounts, active parameters] order; each column is row units per K, Pa, mol or native parameter unit.

Return type:

list[float]

Notes

A free T/P uses its solved state coordinate; the corresponding external control is unused. Source-reference lever requests retain native refusal limits. See ALG-ACTIONS.

numerical_estimates(coordinates: Sequence[float], temperature: float, pressure: float, amounts: Sequence[float], composition: Sequence[float], densities: Sequence[float], packing: Sequence[float]) → EquilibriumNumericalEstimates#

Estimate a frozen endpoint in this declaration; admission remains the reader’s original outcome.

objective_gradient(point: Sequence[float]) → list[float]#

Differentiate the native optimizer objective; feasibility cells return a zero vector.

Parameters:

point (Sequence[float]) – Full native point in compiled chart order, length d including multipliers; not a flattened physical composition.

Returns:

Length d in full-point order. Gibbs cells differentiate G/(RT), in mol, with respect to each chart coordinate. Feasibility cells use a zero optimizer objective and do not differentiate PointEvaluation.objective.

Return type:

list[float]

pinned_count: int#

Number of pinned fluid phases.

primal_size: int#

Number of primal state coordinates before conserved/electrical multipliers.

rank: int#

Rank of the independent conserved-moiety basis, a count.

rank_records: list[NumericalRank]#

Latest observed rank per named operation; no extra admission rule.

removed_species: list[int]#

Component indices eliminated by exact inventory/support restrictions.

rows: list[Row]#

Ordered defining/classification rows; this order owns residual and Jacobian rows.

solve() → EquilibriumResult#

Solve this declaration from a fresh start through the native equilibrium driver.

solve_saturation() → EquilibriumResult#
class epcsaft._core.EquilibriumResult#
amounts: list[float]#

Length p of fluid phase amounts in mol on the feed basis, in declaration order; empty without a state.

classified_residuals: list[float]#

Rows used for admission, including free-amount weighting and trace-inventory normalization where applicable. Most are dimensionless; absent free-solid amount rows retain mol.

constraint_multipliers: list[float]#

reconstructed extensive-objective multipliers for rows excluding Chemical, Pressure and SolidAffinity, preserving rows order. Material and charge values are -feed_total*lambda and -phase_amount*phi; other retained rows are zero. Feasibility cells: raw Ipopt constraint multipliers, or zeros for a Newton result.

Type:

Gibbs cells

convergence: Convergence#

Residual, effective criterion, floor and stopping evidence.

coordinates: list[float]#

Full native state chart including multipliers; follows the compiled point order and is not a flat physical composition array.

critical: CriticalRecord | None#

Failure-only pure critical starts and all candidate results, absent on an unchanged declared success.

diagnostic_options_file: str#

Native diagnostic options-file path, or an empty string without one.

discovery: DiscoveryRecord | None#

Finite discovery sequence, or None for an ordinary declared solve.

evaluations: int#

Native equilibrium evaluation count.

first_numerical_failure: Convergence | None#

Earliest observed numerical refusal, separate from final convergence.

generic_nullity: int#

Nullity of the generic compiled chart.

hessian_calls: int#

Exact Hessian evaluation count.

ipopt_diagnostics: IpoptDiagnostics | None#

Latest actually invoked Ipopt attempt, including initialization-only attempts.

iterations: int#

Iterations including retained seed sub-solves where the producer accumulates them.

jacobian_rank: int#

Reported defining-Jacobian rank.

last_full_evaluation: Convergence | None#
last_rank: NumericalRank | None#

Most recent evaluated rank decision; its basis identifies the matrix.

linear_solve_diagnostics: LinearSolveDiagnostics | None#

Reduced-system accuracy at the returned state, or explicitly rejected-attempt evidence on failure.

linear_solver: str#

Actual Ipopt linear solver name; empty when no Ipopt solve ran.

message: str#

Native conclusion and refusal explanation.

molar_densities: list[float]#

Length p of phase molar densities in mol/m^3, empty without a state.

mole_fractions: list[float]#

Flattened row-major (p, n) dimensionless mole fractions; entry phase*n+component, empty without a state.

multipliers: list[float]#

Dimensionless conserved-moiety and electrical multipliers in compiled order.

neutral_reference_diagnostics: list[NeutralReferenceReactionDiagnostic]#

Reference-transfer evidence in declared reaction order where consumed.

numerical_estimates: EquilibriumNumericalEstimates | None#

Endpoint estimates on detailed capture; None when unrequested.

objective: float#

A/(RT) for TV and G/(RT) otherwise. Ideal activity models return zero.

Type:

EOS physical potential at the retained candidate, in mol on the absolute feed basis

packing_fractions: list[float]#

Length p of dimensionless packing fractions, empty without a state.

phase_count: int#

Number p of declared fluid phases.

phase_mole_fractions(phase: int) → list[float]#

Read one declared fluid phase composition.

Parameters:

phase (int) – Zero-based phase ordinal in the result declaration; invalid indices are refused.

Returns:

Length n of dimensionless mole fractions in component_ids order.

Return type:

list[float]

phase_pressures: list[float]#

Solved phases and numerical evidence on the declared feed basis.

Notes

For discovery, discovery.declaration.phases owns the final phase ordering. Temperature/pressure are None and physical state lists are empty after a refused solve. Diagnostics can survive without a state. See ALG-EQUILIBRIUM; a successful local solve is not a global stability or physical-validation claim.

pressure: float | None#

Resolved pressure in Pa, or None without an admitted state.

rank_records: list[NumericalRank]#

Latest observed rank per named operation; no extra admission rule.

recovered_ipopt_diagnostics: IpoptDiagnostics | None#

Earliest superseded restoration-bearing attempt.

recovery_stability: StabilityReport | None#
reduced_hessian_minimum: float#

Minimum eigenvalue of the native reduced Hessian; local curvature evidence, not a global certificate.

rejected_reduction: EquilibriumResult | None#
requested_tolerance_met: bool | None#

Whether the finite final residual meets the caller criterion, or None without a finite final residual; floor convergence need not be True.

residuals: list[float]#

Unclassified defining rows in rows order. Most are dimensionless; an absent free-solid row is its amount in mol.

rows: list[Row]#

Equation identities in residual order.

solid_affinity_decades: list[float]#

Saturation index in log10 decades per declared solid; interpreted with solid amount and complementarity.

solid_amounts: list[float]#

Amount in mol per declared solid, declaration order; empty without retained solid values.

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

Effective named Engine numerical settings and provenance.

solver_settings: dict[str, float]#

Effective named Ipopt settings; units and meanings follow the named solver option.

solver_status: str#

Optimizer termination name; separate from residual and topology admission.

spinodal: SpinodalRecord | None#

Critical-equation diagnostics, or None outside a retained critical candidate.

success: bool#

Whether the native solve admitted a state; does not establish global equilibrium or physical validation.

temperature: float | None#

Resolved temperature in K, or None without an admitted state.

terminal_numerical_failure: Convergence | None#
topology_event: TopologyEvent#

First vanished free phase, otherwise first coincident pair, when detected.

topology_pair: tuple[int, int] | None#

Declared phase-index pair for coalescence, or None without this event.

topology_phase: int | None#

Index of the vanished phase, or None without this event.

unknown_count: int#

Full state-chart dimension including multipliers.

vanished_phase_stability: StabilityReport | None#

trials of a vanished phase’s kind and support from the declaration without it.

Type:

Failure-only

class epcsaft._core.TopologyEvent#

Candidate topology change detected by the native solve.

Notes

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

None_: TopologyEvent#

No vanished-phase or coincident-phase event detected.

PhaseDisappeared: TopologyEvent#

First vanished free phase in declaration order.

PhasesCoalesced: TopologyEvent#

First coincident pair in lexicographic phase-index order, if no free phase vanished.

class epcsaft._core.ContinuationStop#

Terminal condition of a declared continuation or envelope trace.

Notes

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

branch_lost: ContinuationStop#

The declared density branch was lost.

budget_exhausted: ContinuationStop#

A step/work/retry budget was exhausted.

critical_endpoint: ContinuationStop#

Envelope tracing reached its declared critical stopping condition.

infeasible: ContinuationStop#

A corrector could not satisfy the declared constraints; no global infeasibility proof.

initial_failure: ContinuationStop#

No admitted starting state.

invalid_path: ContinuationStop#

Path declarations or controls are inadmissible.

left_domain: ContinuationStop#

The path left an admitted physical/source domain.

nonfinite: ContinuationStop#

A required path value is nonfinite.

phase_disappeared: ContinuationStop#

A free phase vanished.

phases_coalesced: ContinuationStop#

Two declared phases became coincident.

reached_target: ContinuationStop#

Ordinary path reached its target, or an envelope trace completed its closing step.

singular_jacobian: ContinuationStop#

Required defining Jacobian is singular.

stalled: ContinuationStop#

The corrector or path stopped making admitted progress.

step_too_small: ContinuationStop#

A halved retry step fell below minimum_step.

turning_point: ContinuationStop#

a fold of the declared branch.

Type:

Steps failed where the tangent’s path component extrapolates to zero

class epcsaft._core.ContinuationOptions#

Step and retry controls for continuation and phase envelopes.

Notes

Envelope mode ignores initial_step and the target problem after the shared rejection of solids in either endpoint. Explicit T/P guesses are optional; absent free-intensive guesses use native initialization. After an accepted envelope step the predictor density error sizes the next step; retryable ordinary rejection halves it. A failed critical crossing, closing step or terminal refusal ends the trace with accepted states retained. See ALG-EQUILIBRIUM.

__init__() → None#

Initialize ContinuationOptions from the declared inputs.

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

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

  • max_steps (int) – Initial value of ContinuationOptions.max_steps; see its attribute description for units and ordering.

  • max_retries_per_step (int) – Initial value of ContinuationOptions.max_retries_per_step; see its attribute description for units and ordering.

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

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

Returns:

None.

Return type:

None

envelope_max_log_step: float#

Maximum dimensionless envelope log-coordinate increment; bounds ordinary envelope steps.

envelope_straddle: float#

Positive near-critical absolute log-K straddle threshold; requires 2*envelope_straddle <= envelope_max_log_step.

initial_step: float#

Largest dimensionless fraction of the ordinary start-to-target path; rejected steps halve and accepted ordinary steps never grow. Ignored for envelope tracing.

max_retries_per_step: int#

Maximum consecutive retryable rejections; exceeding it stops with budget_exhausted and preserves the cause.

max_steps: int#

Maximum number of continuation steps, a count.

minimum_step: float#

Positive minimum step in the active path coordinate; a smaller halved step stops the trace.

class epcsaft._core.ContinuationRequest#

Start, target and physical parameter endpoints of a native trace.

__init__() → None#

Initialize ContinuationRequest from the declared inputs.

Returns:

None.

Return type:

None

options: ContinuationOptions#

Declared steps, retry limits and envelope controls.

parameter_targets: Sequence[float]#

Physical endpoint values in model active-parameter order, with each family’s native units; empty means no parameter path.

start_problem: EquilibriumProblem#

Starting physical declaration; an envelope condition selects envelope tracing.

start_result: EquilibriumResult | None#

Optional admitted starting result on the same declaration, or None to solve the start.

target_problem: EquilibriumProblem#

Ordinary-path endpoint. Envelope tracing ignores it after the shared rejection of solids in either endpoint.

class epcsaft._core.ContinuationResult#

Accepted states, work and terminal cause of a continuation.

accepted_steps: int#

Number of accepted continuation steps.

attempted_path: float | None#

Path fraction or envelope target of the most recent rejected attempt, retained across later accepted steps; None if no attempt was rejected.

attempts: int#

Number of attempted corrector steps.

cause_convergence: Convergence | None#

Underlying corrector convergence evidence, or None without a record.

cause_message: str | None#

Underlying refusal explanation, or None without a distinct cause.

cause_stop: ContinuationStop | None#

Underlying retry/terminal stop, or None when no distinct cause is retained.

conditions: list[EnvelopeCondition]#

Envelope condition per accepted envelope state; empty for ordinary continuation.

critical_points: list[EquilibriumResult]#

Critical-equation candidate results in encounter order, not globally validated critical points.

critical_seeds: list[list[float]]#

Per-candidate [ln(T/(1 K)), ln(P/(1 Pa)), ln(rho/(1 mol/m^3))] seeds, dimensionless.

event_pair: tuple[int, int] | None#

Coalesced phase-index pair, or None without this event.

event_phase: int | None#

Vanished phase index, or None without this topology event.

first_numerical_failure: Convergence | None#

Earliest observed numerical refusal, separate from final convergence.

ipopt_diagnostics: IpoptDiagnostics | None#

Latest actually invoked Ipopt attempt, including initialization-only attempts.

last_result: EquilibriumResult | None#

Result retained from the most recent rejected attempt, possibly refused; None if no rejected attempt retained a result. The latest accepted result is in states.

message: str#

Trace conclusion or terminal refusal explanation.

parameter_values: list[list[float]]#

Physical active-parameter vector per accepted state only for a declared parameter path, in model active order and family units; empty for ordinary feed/intensive paths and envelope traces.

path_values: list[float]#

One dimensionless path fraction per accepted ordinary state, or the envelope condition target per accepted envelope state.

rank_records: list[NumericalRank]#

Latest observed rank per named operation; no extra admission rule.

reached_path: float#

Path fraction or envelope target of the last accepted corrector step, dimensionless; remains zero before the first accepted step, even when an initialized envelope has a nonzero starting target.

recovered_ipopt_diagnostics: IpoptDiagnostics | None#

Earliest superseded restoration-bearing attempt.

retries: int#

Number of rejected retry attempts.

states: list[EquilibriumResult]#

Accepted EquilibriumResults in path order; retained on later failure.

stop: ContinuationStop#

Terminal continuation condition.

success: bool#

Whether the trace completed its declared success condition; inspect stop and retained states.

epcsaft._core.continue_equilibrium(model: HelmholtzModel, request: ContinuationRequest) → ContinuationResult#

Trace a declared equilibrium path or incipient phase envelope.

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

  • request (ContinuationRequest) – Start/target declarations, physical parameter endpoints and explicit continuation controls.

Returns:

ContinuationResult retaining accepted states and the terminal cause.

Return type:

ContinuationResult

Notes

Ordinary continuation follows the start-to-target path. Both endpoint declarations are first checked for unsupported solids; an envelope start then selects the native envelope controller and ignores the target declaration.

class epcsaft._core.SolvedStateObservableKind#

Quantity extracted from the admitted equilibrium state.

Notes

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

EquilibriumIsobaricHeatCapacity: SolvedStateObservableKind#

Reacting equilibrium isobaric heat capacity normalized by feed mol, J/(mol K); not frozen-composition Cp.

PhaseAmount: SolvedStateObservableKind#

Fluid phase amount, mol on the absolute feed basis.

PhaseComponentAmount: SolvedStateObservableKind#

Component amount in one phase, mol.

PhaseGibbsMolarVolume: SolvedStateObservableKind#

Gibbs-conjugate phase molar volume, m^3/mol; includes admitted source-standard pressure dependence.

PhaseLogActivity: SolvedStateObservableKind#

ln[(rho*x_i/(1 mol/m^3))*exp(mu_res_i/(RT))], dimensionless on EOS_STANDARD_STATE_ID; excludes an added source-standard term.

PhaseMolarDensity: SolvedStateObservableKind#

Fluid molar density, mol/m^3.

PhaseMoleFraction: SolvedStateObservableKind#

Component mole fraction in one phase, dimensionless.

PhasePackingFraction: SolvedStateObservableKind#

Phase packing fraction, dimensionless.

PhasePressure: SolvedStateObservableKind#

EOS phase pressure, Pa.

PhaseProperty: SolvedStateObservableKind#

Selected homogeneous molar property in PropertyObservable units; log fugacity is not admitted by this solved-state consumer.

PhaseResidualChemicalPotentialOverRt: SolvedStateObservableKind#

Component residual chemical potential divided by RT, dimensionless.

PhaseVolume: SolvedStateObservableKind#

Fluid phase volume, m^3.

Pressure: SolvedStateObservableKind#

System pressure, Pa.

SolidAmount: SolvedStateObservableKind#

Solid amount in mol; phase selects the solid ordinal.

SolidSaturationIndex: SolvedStateObservableKind#

Solid saturation index in log10 decades; phase selects the solid ordinal.

SystemEnthalpy: SolvedStateObservableKind#

Extensive system enthalpy, J on the absolute feed basis.

Temperature: SolvedStateObservableKind#

System temperature, K.

class epcsaft._core.SolvedStateObservable(kind: SolvedStateObservableKind, phase: int = 0, component: int = 0, property: PropertyObservable = ...)#

Observable with declared phase/component selection.

__init__(kind: SolvedStateObservableKind, phase: int = 0, component: int = 0, property: PropertyObservable = ...) → None#

Initialize SolvedStateObservable from the declared inputs.

Parameters:
  • kind (SolvedStateObservableKind) – Initial value of SolvedStateObservable.kind; see its attribute description for units and ordering.

  • phase (int) – Initial value of SolvedStateObservable.phase; see its attribute description for units and ordering.

  • component (int) – Initial value of SolvedStateObservable.component; see its attribute description for units and ordering.

  • property (PropertyObservable) – Initial value of SolvedStateObservable.property; see its attribute description for units and ordering.

Returns:

None.

Return type:

None

component: int#

Component index for component observables; ignored otherwise.

kind: SolvedStateObservableKind#

Quantity and unit selected; see SolvedStateObservableKind.

phase: int#

Fluid phase ordinal, or solid ordinal for SolidAmount/SolidSaturationIndex; ignored for a system quantity.

property: PropertyObservable#

Molar property selection when kind is PhaseProperty; ignored for other kinds.

class epcsaft._core.SolvedStateActionDirection(temperature_k: float, pressure_pa: float, feed_amounts_mol: Sequence[float], active_parameters: Sequence[float], reaction_coefficients: Sequence[Sequence[float]] = ..., enthalpy_j: float = ..., entropy_j_per_k: float = ..., volume_m3: float = ..., internal_energy_j: float = ...)#

Physical external increments for an implicit equilibrium action.

Notes

Every path variable is dimensionless, so first and mixed contractions retain observable units. Directions do not authorize differentiation through a support, topology or source-interval change.

__init__(temperature_k: float, pressure_pa: float, feed_amounts_mol: Sequence[float], active_parameters: Sequence[float], reaction_coefficients: Sequence[Sequence[float]] = ..., enthalpy_j: float = ..., entropy_j_per_k: float = ..., volume_m3: float = ..., internal_energy_j: float = ...) → None#

Initialize SolvedStateActionDirection from the declared inputs.

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

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

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

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

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

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

  • volume_m3 (float) – Total-volume target direction in m³.

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

Returns:

None.

Return type:

None

active_parameters: list[float]#

Physical parameter increments in model active order, each family’s native units.

enthalpy_j: float#

Increment of the extensive enthalpy target in J.

entropy_j_per_k: float#

Increment of the extensive entropy target in J/K.

feed_amounts_mol: list[float]#

Length n of feed-amount increments in mol, component order; not mole-fraction increments.

internal_energy_j: float#

Internal-energy target increment in J.

pressure_pa: float#

External pressure increment in Pa; must be zero when pressure is solved.

reaction_coefficients: list[list[float]]#

One [da, db, dc, dd] vector per declared reaction law, or empty for no source motion; units are 1, K, 1 and 1/K, evaluated along the temperature path.

temperature_k: float#

External temperature increment in K; must be zero when temperature is solved.

volume_m3: float#

Total-volume target direction in m³; zero if no volume target is declared.

class epcsaft._core.SolvedStateActionRequest(observables: Sequence[SolvedStateObservable], directions: Sequence[SolvedStateActionDirection])#

Observables and ordered directions for one implicit mixed action.

Notes

solved_state_first_actions is the separate batching operation for independent first directions. Availability depends on the selected energy order, reference terms and branch regularity; see ALG-ACTIONS.

__init__(observables: Sequence[SolvedStateObservable], directions: Sequence[SolvedStateActionDirection]) → None#

Initialize SolvedStateActionRequest from the declared inputs.

Parameters:
  • observables (Sequence[SolvedStateObservable]) – Initial value of SolvedStateActionRequest.observables; see its attribute description for units and ordering.

  • directions (Sequence[SolvedStateActionDirection]) – Initial value of SolvedStateActionRequest.directions; see its attribute description for units and ordering.

Returns:

None.

Return type:

None

directions: list[SolvedStateActionDirection]#

Ordered physical increments for the mixed contraction, not independent first-order batches.

observables: list[SolvedStateObservable]#

Ordered quantity selections; each result follows this order.

class epcsaft._core.SolvedStateActionStatus#

Availability or refusal cause for an implicit solved-state action.

Notes

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

AssociationIllConditioned: SolvedStateActionStatus#

Association-site conditioning fails the declared criterion.

AssociationResidual: SolvedStateActionStatus#

The association residual does not meet its admission criterion.

AssociationSingular: SolvedStateActionStatus#

The implicit association-site Jacobian is singular.

Available: SolvedStateActionStatus#

Requested quantity is available on the admitted branch.

CentralPropertyUnavailable: SolvedStateActionStatus#

The central observable is unavailable.

CentralSolveUnavailable: SolvedStateActionStatus#

No admitted central equilibrium state is available.

DefiningEquationsNotSatisfied: SolvedStateActionStatus#

The central defining-row residual fails action admission.

DensityUnavailable: SolvedStateActionStatus#

A required pressure-closed density is unavailable.

EnergyOrderUnavailable: SolvedStateActionStatus#

The requested action needs an energy order not supplied by this consumer.

IllConditioned: SolvedStateActionStatus#

The defining system fails the declared conditioning criterion.

IonicInsertion: SolvedStateActionStatus#

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

LinearSolveResidual: SolvedStateActionStatus#

The implicit linear solve fails its residual criterion.

MissingThermochemistry: SolvedStateActionStatus#

Required species thermochemistry is absent.

Nonfinite: SolvedStateActionStatus#

A required value or derivative is nonfinite.

NonfiniteJacobian: SolvedStateActionStatus#

A required defining-Jacobian entry is nonfinite.

NonuniqueCoalescedPhases: SolvedStateActionStatus#

Coincident phase labels make the requested derivative nonunique.

OutsideInterval: SolvedStateActionStatus#

Temperature lies outside a required source interval.

PhaseBoundaryNotDifferentiable: SolvedStateActionStatus#

A vanished-phase boundary does not admit the requested local derivative.

PressureSingular: SolvedStateActionStatus#

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

RankDeficient: SolvedStateActionStatus#

The defining Jacobian lacks full required rank.

ReferenceUnavailable: SolvedStateActionStatus#

A consumed source-reference value or derivative is unavailable.

SupportChange: SolvedStateActionStatus#

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

ThermalBoundary: SolvedStateActionStatus#

Requested thermal derivative crosses an unqualified source-interval endpoint.

class epcsaft._core.SolvedStateActionResult#

Central observable and admitted mixed implicit contraction.

action: float | None#

Mixed contraction in unit, or None with the status cause.

diagnostic_message: str | None#

Specific native action/reference refusal explanation, or None without one.

observable: SolvedStateObservable#

Requested quantity and phase/component selection.

order: int#

Number of contracted directions, a derivative-order count.

property_diagnostics: PropertyActionDiagnostics | None#

Consumed homogeneous-property work/conditioning, or None when none is retained.

status: SolvedStateActionStatus#

Availability or specific refusal cause.

unit: str#

Physical unit shared by value and action; path variables are dimensionless.

value: float | None#

Central observable in unit, or None if unavailable; may survive an unavailable outer action.

class epcsaft._core.SolvedStateActionDiagnostics#

Defining-equation conditioning and shared implicit work.

central_floor: float | None#

Dimensionless estimated central residual floor, or None without an estimate.

central_residual: float | None#

Dimensionless central defining-row residual, or None without a retained evaluation.

condition_estimate: float | None#

Dimensionless condition estimate, or None when unavailable.

equation_count: int#

Number of defining equations.

linear_solves: int#

Number of implicit linear solves.

maximum_energy_order: int#

Maximum required Helmholtz derivative order.

maximum_linear_residual: float | None#

Maximum dimensionless normalized implicit linear residual, or None without a solve.

rank: int | None#

Numerical defining-Jacobian rank, or None without an admitted factorization.

state_dimension: int#

Number of full compiled state coordinates.

state_factorizations: int#

Number of shared defining-Jacobian factorizations.

class epcsaft._core.SolvedStateActionBatch#

Ordered solved-state actions sharing one prepared center.

diagnostics: SolvedStateActionDiagnostics#

Shared defining-equation work and conditioning.

results: list[SolvedStateActionResult]#

Per-observable results in request order, each with its own cause and units.

epcsaft._core.solved_state_actions(compiled: CompiledSystem, central: EquilibriumResult, request: SolvedStateActionRequest) → SolvedStateActionBatch#

Contract implicit equilibrium derivatives on one admitted branch.

Parameters:
  • compiled (CompiledSystem) – Admitted native compiled system; its HelmholtzModel must remain alive.

  • central (EquilibriumResult) – Admitted result from the same compiled declaration.

  • request (SolvedStateActionRequest) – Ordered observables and physical mixed directions.

Returns:

SolvedStateActionBatch in observable order with per-action availability.

Return type:

SolvedStateActionBatch

Notes

Contractions use dimensionless path variables and retain observable units. This operation does not reinterpret mixed directions as independent first-action batches. See ALG-ACTIONS.

epcsaft._core.solved_state_first_actions(compiled: CompiledSystem, central: EquilibriumResult, observables: Sequence[SolvedStateObservable], directions: Sequence[SolvedStateActionDirection]) → list[SolvedStateActionBatch]#

Evaluate independent first directions at one shared solved center.

Parameters:
  • compiled (CompiledSystem) – Admitted native compiled system; its HelmholtzModel must remain alive.

  • central (EquilibriumResult) – Admitted result from the same compiled declaration.

  • observables (Sequence[SolvedStateObservable]) – Ordered solved-state quantity selections.

  • directions (Sequence[SolvedStateActionDirection]) – Independent physical first directions; these are separate columns, not one mixed contraction.

Returns:

One SolvedStateActionBatch per direction in input order.

Return type:

list[SolvedStateActionBatch]

epcsaft._core.linear_solver() → str#

Read the compiled native equilibrium linear-solver selection.

Returns:

Linear solver name; a result.linear_solver separately records an actual solve.

Return type:

str

epcsaft._core.compile_problem(model: HelmholtzModel | IdealMoleFraction, problem: EquilibriumProblem) → CompiledSystem#

Admit and compile the physical equilibrium declaration.

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

  • problem (EquilibriumProblem) – Native physical declaration with ordered phases, feed, reactions, solids and constraints.

Returns:

CompiledSystem with rows, native chart and structural rank evidence.

Return type:

CompiledSystem

Notes

Invalid support, units, charge, rank or constraint combinations are refused before solving. Keep model alive while the compiled object is used.

epcsaft._core.equilibrium_asl_record(document: ParameterDocument, model: HelmholtzModel, problem: EquilibriumProblem, continuation: ContinuationOptions, feed_offset: Sequence[float], feed_matrix: Sequence[Sequence[float]], anchor_controls: Sequence[float], identity_component: int, minimum_gap: float) → str#

Serialize document with the model’s native declarations and the feed map; epcsaft.equilibrium.asl_record owns the arguments.

epcsaft._core.sensitivity(compiled: CompiledSystem, point: Sequence[float], lever: Sequence[float]) → list[float]#

Solve the native implicit first-sensitivity equations.

Parameters:
  • compiled (CompiledSystem) – Admitted native compiled system; its HelmholtzModel must remain alive.

  • point (Sequence[float]) – Full native point in compiled chart order, length d including multipliers; not a flattened physical composition.

  • lever (Sequence[float]) – Length 2+n+a of physical increments in [T (K), P (Pa), feed (mol), active parameter] order, optionally extended by [da, db, dc, dd] per reaction and extensive H (J), S (J/K) increments.

Returns:

Length d of state-coordinate actions, or an empty list when the defining solve is singular or not admitted.

Return type:

list[float]

Notes

Solves J dy = -F_controls dcontrols using exact native columns. An empty result is unavailable sensitivity, not a zero derivative.

epcsaft._core.solve_equilibrium(model: HelmholtzModel | IdealMoleFraction, problem: EquilibriumProblem, start: EquilibriumResult | None = ...) → EquilibriumResult#

Solve the declared equilibrium problem natively.

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

  • problem (EquilibriumProblem) – Native physical declaration; phase order owns result arrays.

  • start (Optional[EquilibriumResult]) – Optional compatible admitted result used only as a seed.

Returns:

EquilibriumResult with admitted physical state or retained refusal diagnostics.

Return type:

EquilibriumResult

Notes

Uses the native equilibrium driver, exact derivatives and declared numerical settings. A returned success is local numerical admission; global stability requires separate evidence. See ALG-EQUILIBRIUM.

class epcsaft._core.EquilibriumStart(*, coordinates: Sequence[float] = ..., amounts: Sequence[float] = ..., compositions: Sequence[Sequence[float]] = ..., packing_fractions: Sequence[float | None] = ..., temperature: float | None = None, pressure: float | None = None, previous: EquilibriumResult | None = None)#

One seed for the same thermodynamic declaration.

Notes

Seeds carry no thermodynamic constraints. Native admission rejects incompatible or conflicting seed representations.

__init__(*, coordinates: Sequence[float] = ..., amounts: Sequence[float] = ..., compositions: Sequence[Sequence[float]] = ..., packing_fractions: Sequence[float | None] = ..., temperature: float | None = None, pressure: float | None = None, previous: EquilibriumResult | None = None) → None#

Initialize EquilibriumStart from the declared inputs.

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

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

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

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

  • temperature (Optional[float]) – Initial value of EquilibriumStart.temperature; see its attribute description for units and ordering.

  • pressure (Optional[float]) – Initial value of EquilibriumStart.pressure; see its attribute description for units and ordering.

  • previous (Optional[EquilibriumResult]) – Initial value of EquilibriumStart.previous; see its attribute description for units and ordering.

Returns:

None.

Return type:

None

amounts: list[float]#

Optional fluid-phase amount guesses in mol, phase order; empty leaves them unspecified.

compositions: list[list[float]]#

Optional ragged mole-fraction guesses in phase order. Each nonempty row follows that phase’s declared support, with one entry per declared support component; an empty row leaves that phase unspecified.

coordinates: list[float]#

Optional full native compiled coordinate vector, including multipliers; empty selects physical seed construction.

packing_fractions: list[float | None]#

Optional per-phase dimensionless packing guesses; each None leaves that phase unspecified.

pressure: float | None#

Optional positive pressure guess in Pa for a free pressure.

previous: EquilibriumResult | None#

Optional previous EquilibriumResult supplying a compatible starting state; not a replacement physical declaration.

temperature: float | None#

Optional positive temperature guess in K for a free temperature.

class epcsaft._core.EquilibriumWorkLimits(*, attempts: int | None = None, iterations: int | None = None, attempt_iterations: int | None = None, seconds: float | None = None, attempt_seconds: float | None = None)#

Shared and per-attempt budgets for declared equilibrium starts.

Notes

None leaves that limit undeclared. Limits are checked by the native driver; a callback/evaluation in progress can overrun the elapsed deadline.

__init__(*, attempts: int | None = None, iterations: int | None = None, attempt_iterations: int | None = None, seconds: float | None = None, attempt_seconds: float | None = None) → None#

Initialize EquilibriumWorkLimits from the declared inputs.

Parameters:
  • attempts (Optional[int]) – Initial value of EquilibriumWorkLimits.attempts; see its attribute description for units and ordering.

  • iterations (Optional[int]) – Initial value of EquilibriumWorkLimits.iterations; see its attribute description for units and ordering.

  • attempt_iterations (Optional[int]) – Initial value of EquilibriumWorkLimits.attempt_iterations; see its attribute description for units and ordering.

  • seconds (Optional[float]) – Initial value of EquilibriumWorkLimits.seconds; see its attribute description for units and ordering.

  • attempt_seconds (Optional[float]) – Initial value of EquilibriumWorkLimits.attempt_seconds; see its attribute description for units and ordering.

Returns:

None.

Return type:

None

attempt_iterations: int | None#

Optional maximum iterations within one attempt.

attempt_seconds: float | None#

Optional per-attempt elapsed-time budget in seconds.

attempts: int | None#

Optional maximum attempted-start count.

iterations: int | None#

Optional shared iteration budget across attempts and seed sub-solves.

seconds: float | None#

Optional total elapsed-time budget in seconds.

class epcsaft._core.EquilibriumStartsResult#

Ordered start outcomes and actual budget use.

attempt_seconds: list[float]#

Elapsed seconds per declared start.

budget_exhausted: bool#

Whether a declared shared work limit was exhausted.

causes: list[str]#

Explanation per start, including why an attempt was not run.

iterations: int#

Total consumed iterations across attempts.

overrun_seconds: float#

Elapsed deadline overrun in seconds, reported rather than hidden.

results: list[EquilibriumResult | None]#

One optional result per declared start in input order; None preserves an unrun/refused attempt with causes.

seconds: float#

Total elapsed wall time in seconds.

selected: int | None#

Index of the first result with success=True and requested_tolerance_met=True, or None without such a result; a retained floor-admitted state need not be selected.

epcsaft._core.solve_equilibrium_starts(model: HelmholtzModel, problem: EquilibriumProblem, starts: list[EquilibriumStart], limits: EquilibriumWorkLimits) → EquilibriumStartsResult#

Evaluate declared seeds under shared native work limits.

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

  • problem (EquilibriumProblem) – One thermodynamic declaration shared by every seed.

  • starts (list[EquilibriumStart]) – Ordered native seeds; none selects new physical inputs.

  • limits (EquilibriumWorkLimits) – Declared shared and per-attempt work limits.

Returns:

EquilibriumStartsResult preserving input order, unrun causes and selected-result identity.

Return type:

EquilibriumStartsResult

Notes

All attempts use the same native solve and stopping admission. A finite seed search is not proof of global equilibrium.