Native equilibrium#
- class epcsaft._core.PhaseKind#
Declared fluid phase branch.
Notes
Native enum name/value properties follow the module convention in epcsaft._core.
- 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.
- MassFractions: FeedKind#
Dimensionless component mass fractions on a one-kg mixture basis; divided by molar masses in kg/mol to obtain native molar amounts.
- class epcsaft._core.AmountSpec#
Free phase amount or prescribed feed-relative fraction.
- 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:
- 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:
- class epcsaft._core.FreeValue#
Fixed intensive value or solved intensive with an optional seed.
- 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.
- 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.
- 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.
- packing_guess: float | None#
Optional dimensionless packing-fraction seed, not a density in mol/m^3.
- 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.
- solvent: list[int]#
Solvent component indices for a molality feed; non-solvent entries of values are solute molalities.
- 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.
- species_reference: list[SpeciesReference]#
Optional length-n map in component_ids order; empty retains the default solvent liquid and solute infinite-dilution references.
- 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.
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#
- observed_terminal_change: float | None#
Dimensionless change between consecutive terminal extrapolations, or None when unavailable; a local numerical estimate, not a universal error bound.
- 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.
- 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.
- 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.
- reference: ReactionReference | None#
Optional explicit source-reference declaration; requires the problem’s neutral_reference.
- 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.
- 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.
- reference: ReactionReference | None#
Source convention and pressure used for native solid-standard conversion.
- 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
- 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
- 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.
- optimizer: EquilibriumResult#
Retained trial solve and numerical evidence; a solve success alone does not prove descent.
- 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.
- 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.
- 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
- first_numerical_failure: Convergence | None#
Earliest observed numerical refusal, separate from final convergence.
- 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.
- declarations: list[EquilibriumResult]#
Attempted candidate solves in retained attempt order.
- mode: DiscoveryMode#
- rounds: list[StabilityReport]#
Stability reports in discovery-round order.
- 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:
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:
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.
- 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
- kind: EnvelopeCoordinate#
Logarithmic local coordinate of the condition.
- class epcsaft._core.CriticalRecord#
Bases:
HelmholtzModeRecordNecessary critical-equation candidate; no global phase stability certificate.
- 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.
- 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.
- 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.
- 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.
- 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.
- log_fraction: float | None#
Natural log of a positive maximum mole fraction, dimensionless; None for zero, amount mode or unavailable result.
- 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.
- 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:
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.
- class epcsaft._core.Row#
Identity of a defining or classification equation.
- class epcsaft._core.PointEvaluation#
Defining rows, objective and numerical floor at a compiled point.
- 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.
- 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:
- hessian(point: Sequence[float], constraint_multipliers: Sequence[float] = ...) list[float]#
Evaluate exact native Lagrangian curvature.
- Parameters:
- 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:
- jacobian(point: Sequence[float]) list[float]#
Differentiate defining rows with respect to the full chart.
- 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).
- 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:
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:
- rank_records: list[NumericalRank]#
Latest observed rank per named operation; no extra admission rule.
- 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#
- critical_search: CriticalSearch | None#
Failure-only pure critical starts and all candidate results, absent on an unchanged declared success.
- discovery: DiscoveryRecord | None#
Finite discovery sequence, or None for an ordinary declared solve.
- 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_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.
- 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
- 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.
- 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.
- 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_settings: dict[str, float]#
Effective named Ipopt settings; units and meanings follow the named solver option.
- 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.
- 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.
- 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.
- 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.
- 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.
- cause_convergence: Convergence | None#
Underlying corrector convergence evidence, or None without a record.
- 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.
- 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.
- 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.
- states: list[EquilibriumResult]#
Accepted EquilibriumResults in path order; retained on later failure.
- stop: ContinuationStop#
Terminal continuation condition.
- 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:
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
- 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.
- feed_amounts_mol: list[float]#
Length n of feed-amount increments in mol, component order; not mole-fraction increments.
- 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.
The central observable is unavailable.
No admitted central equilibrium state is available.
- DefiningEquationsNotSatisfied: SolvedStateActionStatus#
The central defining-row residual fails action admission.
A required pressure-closed density is unavailable.
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.
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.
- diagnostic_message: str | None#
Specific native action/reference refusal explanation, or None without one.
- observable: SolvedStateObservable#
Requested quantity and phase/component selection.
- property_diagnostics: PropertyActionDiagnostics | None#
Consumed homogeneous-property work/conditioning, or None when none is retained.
- status: SolvedStateActionStatus#
Availability or specific refusal cause.
- 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.
- 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:
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:
- 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:
- 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:
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
documentwith the model’s native declarations and the feed map;epcsaft.equilibrium.asl_recordowns 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:
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:
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.
- previous: EquilibriumResult | None#
Optional previous EquilibriumResult supplying a compatible starting state; not a replacement physical declaration.
- 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
- class epcsaft._core.EquilibriumStartsResult#
Ordered start outcomes and actual budget use.
- results: list[EquilibriumResult | None]#
One optional result per declared start in input order; None preserves an unrun/refused attempt with causes.
- 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:
Notes
All attempts use the same native solve and stopping admission. A finite seed search is not proof of global equilibrium.