Native parameter estimation#

class epcsaft._core.ObservationKind#

Observation quantity or numerical requirement supplied to native parameter estimation.

Notes

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

See ALG-FIT and engine/docs/regression/science/pure-saturation-regression.md for observation algebra, bases and admission. Parameter fitting is calibration, not independent physical validation.

AdditionEnthalpy: ObservationKind#

Endpoint extensive-enthalpy difference less added-feed enthalpy, divided by added feed mol, J/mol of total added feed; negative is exothermic.

BulkRelativePermittivity: ObservationKind#

Dimensionless bulk relative permittivity, or a dimensionless two-state ratio when a reference composition is declared.

Density: ObservationKind#

Pressure-closed molar density in mol/m^3, or mass density in kg/m^3 with mass_basis.

EquilibriumIsobaricHeatCapacity: ObservationKind#

Reacting equilibrium isobaric heat capacity per feed mole, J/(mol-feed K).

EquilibriumPressure: ObservationKind#

Solved bubble/dew/saturation pressure in Pa.

EquilibriumTemperature: ObservationKind#

Solved bubble/dew/saturation temperature in K.

IsobaricHeatCapacity: ObservationKind#

Total homogeneous molar Cp at fixed composition, J/(mol K).

LogEquilibriumConstant: ObservationKind#

Natural logarithm of the named source K at fixed problem temperature, dimensionless; no equilibrium solve or reference transfer.

MeanIonicActivityCoefficient: ObservationKind#

Dimensionless mean ionic activity coefficient on the declared molality scale.

MixtureOsmoticCoefficient: ObservationKind#

Dimensionless practical osmotic coefficient -ln(a_w)/(M_w*sum(m_j)) for a full electroneutral liquid composition and one solvent.

OsmoticCoefficient: ObservationKind#

Dimensionless single-solvent practical osmotic coefficient of the formula salt.

PartialPressure: ObservationKind#

Solved system pressure times the selected phase mole-fraction sum, Pa.

PhaseAmountRatio: ObservationKind#

Selected numerator component amount divided by selected denominator amount, dimensionless; denominator must be nonzero.

PhaseDensity: ObservationKind#

Selected equilibrium phase density in mol/m^3, or kg/m^3 with mass_basis.

PhaseFraction: ObservationKind#

Selected phase amount divided by the sum of solved fluid-phase amounts, dimensionless; not divided by feed_total.

PhaseMoleFraction: ObservationKind#

Sum of selected component mole fractions in one phase, dimensionless.

SaturationCappedAdditionEnthalpy: ObservationKind#
SolvationGibbsEnergy: ObservationKind#

Single-ion infinite-dilution solvation Gibbs energy, J/mol on the native reference convention.

Stability: ObservationKind#
TransferGibbsEnergy: ObservationKind#

Single-ion transfer Gibbs energy, solvent B minus reference solvent A, J/mol on the matched convention.

class epcsaft._core.ResidualForm#

Dimensionless residual formed from a prediction and its observation.

Notes

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

Difference: ResidualForm#

(prediction-observed)/scale, with positive scale in the observation unit.

LogRatio: ResidualForm#

ln(prediction/observed); both arguments must be positive, and scale is unused.

class epcsaft._core.ObservationStatus#

Availability or refusal cause of an observation row.

Notes

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

ActionUnavailable: ObservationStatus#

A required exact native action was refused.

Available: ObservationStatus#

Requested prediction or derivative is available.

CentralSolveUnavailable: ObservationStatus#

No admitted central equilibrium state is available.

DensityUnavailable: ObservationStatus#

The declared pressure-closed density was refused.

InadmissibleTrial: ObservationStatus#

Native admission or evaluation raised at this trial; the original explanation is retained.

MissingMolarMass: ObservationStatus#

Mass conversion requires an occupied-species molar mass that is missing or nonpositive.

Nonfinite: ObservationStatus#

A required prediction, residual or column is nonfinite.

NonpositiveLogArgument: ObservationStatus#

A logarithmic prediction/residual requires a positive argument.

NotEvaluated: ObservationStatus#

This row was skipped or evaluation stopped before reaching it.

ReferenceUnavailable: ObservationStatus#

A required reference value or limiting column is unavailable.

ThermochemistryUnavailable: ObservationStatus#

Required caloric data are absent, outside their interval or nonfinite.

TopologyEvent: ObservationStatus#

A phase disappeared or phases coalesced, so the declared observation is unavailable.

class epcsaft._core.Observation#

Inputs, reported value and residual convention for one fitting row.

Notes

Only the fields consumed by kind define its observation. A failed prediction is unavailable with a cause, never a successful zero residual. Endpoint reaction/reference identities and component balances must match for AdditionEnthalpy.

basis_amount: float#
branch: DensityBranch#

Density branch for a pressure-closed state or added-feed state.

composition: list[float]#

Length n, normalized dimensionless composition in component order; electrolyte kinds interpret it as the declared solvent or full mixture as specified by kind.

denominator_phase: int#

Denominator fluid-phase index for PhaseAmountRatio.

denominator_species: list[int]#

Nonempty denominator component-index set for PhaseAmountRatio.

feed_amount: float#

Positive added-feed amount in mol for AdditionEnthalpy.

final_problem: EquilibriumProblem#

Final equilibrium endpoint for AdditionEnthalpy; unused by single-endpoint kinds.

finite_solute_molalities: list[float] | None#

Formula-unit salt concentration in mol/kg solvent for formula-salt observations.

form: ResidualForm#

Dimensionless residual transformation.

ion_indices: tuple[int, int]#

Two component indices in (cation, anion) order for the formula-salt reference.

kind: ObservationKind#

Observation quantity, unit and native consumer; see ObservationKind.

loading_bounds: tuple[float, float]#
loading_cap: float#
loading_grid: list[float]#
mass_basis: bool#

For Density/PhaseDensity, request kg/m^3 rather than mol/m^3 through declared molar masses.

molality: float#
observed: float#

Reported measured/source value in the selected prediction unit; not a residual.

phase: int#

Selected declared fluid-phase index.

pressure: float#

Pressure-closed or added-feed-state pressure in Pa; equilibrium observations use problem.pressure instead.

pressure_ratio: float#
pressure_reference: EquilibriumProblem | None#
problem: EquilibriumProblem#

Declared equilibrium specification, or initial endpoint for AdditionEnthalpy; also owns the named source law for ln K observations.

reaction: str#

Named source reaction for LogEquilibriumConstant, matched within problem.reactions.

reference_composition: list[float]#

Optional length-n reference solvent composition, dimensionless in component order; used for transfer A or a relative-permittivity denominator.

scale: float#

Positive Difference nondimensionalization scale in the observation unit; not an uncertainty unless explicitly declared as such by the measurement model.

species: list[int]#

Nonempty selected component-index set within the phase support; mole-fraction and partial-pressure kinds sum the set.

stability_options: StabilityOptions#
stoichiometry: tuple[int, int]#

Two positive ion counts per formula unit in (cation, anion) order, with zero net formula charge.

temperature: float#

Pressure-closed or feed-state temperature in K; equilibrium observations use problem.temperature instead.

class epcsaft._core.Prediction#

One native observation prediction with physical units and failure evidence.

added_amount: float | None#
branch: DensityBranch | None#

Resolved density branch, or None without pressure-closure branch evidence; Unspecified is not a phase classification.

cap_branch: str#
convergence: Convergence | None#

Consumed equilibrium/density convergence record, or None without one.

endpoint_loading: float | None#
first_numerical_failure: Convergence | None#

First producer refusal, including recovered causes.

message: str#

Native explanation, including the failing state/reference when relevant.

pressure_reference: Prediction | None#
requested_tolerance_met: bool | None#

Whether a retained central solve meets the caller criterion, or None without that evidence.

residual: float | None#

Unweighted dimensionless residual in the declared ResidualForm, or None when unavailable.

saturation: SaturationSearch | None#
saturation_loading: float | None#
solver_options: list[dict[str, Any]]#

Effective named numerical settings and provenance.

stability: StabilityMeasure | None#
stability_raw_gradient: list[float]#
stable_root_count: int | None#

Mechanically stable root count if established, otherwise None.

status: ObservationStatus#

Availability or specific refusal cause.

unit: str#

Physical unit of the predicted observation.

value: float | None#

Predicted physical quantity in unit, or None with status/message.

class epcsaft._core.PredictionGradient#
first_numerical_failure: Convergence | None#

First native action refusal, including a successful retry.

message: str#

Derivative refusal explanation, possibly empty.

parameter_actions: list[ResidualEnergyAction]#

Exact first partials of one physical prediction.

Notes

These are prediction columns, not residual or weighted columns. A missing derivative is not a numerical zero.

raw_minimum: list[float]#
status: ObservationStatus#

Availability or blocking native action cause.

value: list[float]#

Physical prediction partials in model active-parameter order, with requested reaction-coordinate columns where the consumer supplies them; unit divided by each native coefficient unit. Empty on refusal.

class epcsaft._core.ReactionCoefficient#

Source reaction coordinate and its physical unit.

Notes

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

A: ReactionCoefficient#

Natural-log constant coefficient a, dimensionless.

B: ReactionCoefficient#

Reciprocal-temperature coefficient b, K.

C: ReactionCoefficient#

Log-temperature coefficient c, dimensionless.

D: ReactionCoefficient#

Linear-temperature coefficient d, 1/K.

EnthalpyShift: ReactionCoefficient#

Source reaction enthalpy increment in J/mol, with a required pivot temperature; preserves ln K at the pivot.

class epcsaft._core.ReactionCoordinate#

Named source coefficient or enthalpy-shift coordinate.

Notes

Plain assignments precede an enthalpy-shift addition on a fresh observation copy. Duplicate assignments and two shifts on one reaction are refused. Sequence starts and minimax admit EnthalpyShift as an offset from the declared correlation; see ALG-FIT.

coefficient: ReactionCoefficient#

Selected a/b/c/d coefficient or pivoted enthalpy increment.

name: str#

Reaction name shared by every matching observation/source law.

pivot_temperature: float#

Positive pivot in K within the source interval, required for EnthalpyShift; otherwise unused.

class epcsaft._core.CoordinateTarget#

One native EOS target of an affine optimizer coordinate.

coefficient: float#

Multiplier mapping base coordinate q to this target; units are target units divided by q units, so cross-family targets need not share a unit.

family: ParameterFamily#

Native parameter family, physical meaning and unit.

indices: list[int]#

Native storage slots tied to the target; same flattened-slot convention as ActiveParameter.

class epcsaft._core.Coordinate#

Affine physical coordinate q = origin + scale*v.

Notes

q uses the reaction-coefficient unit or the units declared by its EOS target map. Optimizer v is dimensionless. Native admission owns tied-slot consistency, target conflicts and valid bounds; see affine_parameter_coordinate_map in engine/docs/equations.md.

lower: float#

Inclusive lower physical bound on q, in q units; may be negative infinity when undeclared.

origin: float#

Physical base value of q at dimensionless optimizer v=0, in q units.

reaction: ReactionCoordinate | None#

Optional named source coordinate; mutually exclusive with EOS targets.

scale: float#

Positive finite affine scale in q units per dimensionless optimizer increment.

targets: list[CoordinateTarget]#

Ordered EOS targets, each equal to coefficient*q; empty for a reaction coordinate.

upper: float#

Inclusive upper physical bound on q, in q units; may be positive infinity when undeclared.

class epcsaft._core.CoordinateSet#

Ordered affine parameter coordinates for native estimation.

Notes

Physical rows are EOS targets in coordinate/target order, then held Born diameters where evaluated, then reaction rows. ActiveParameter lists contain EOS rows only; reaction coordinates are separate.

active() → list[ActiveParameter]#

Read EOS physical derivative directions from the coordinate declarations.

Returns:

One ActiveParameter per declared EOS target, in coordinate/target order; excludes reaction coordinates and unevaluated holds.

Return type:

list[ActiveParameter]

coordinates: list[Coordinate]#

Optimizer coordinates in declaration order; this order owns all optimizer columns.

start(parameters: Parameters, observations: list[Observation] = ..., thermochemistry: ThermochemistryRecord | None = ...) → list[float]#

Read dimensionless optimizer starts from current physical parameters and source laws.

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

  • observations (list[Observation]) – Optional observation/source declarations needed to identify named reaction coordinates.

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

Returns:

Length u optimizer vector in coordinate declaration order.

Return type:

list[float]

Notes

Tied slots must agree; invalid or conflicting reaction sources are refused. This reads a start and performs no fit.

tie() → list[int]#

Read the physical-row to optimizer-coordinate membership.

Returns:

Optimizer-coordinate index per physical EOS/reaction row in native physical-row order; held rows arise only during evaluation.

Return type:

list[int]

class epcsaft._core.FitControls(*, maximum_iterations: int, maximum_elapsed_time_seconds: float, function_tolerance: float = 0.0, gradient_tolerance: float = 0.0, parameter_tolerance: float = 0.0, workers: int = 0, solver_options: Mapping[str, float] | None = None)#

Native estimator tolerances, budgets and state-group workers.

Notes

Least squares uses Ceres with exact native columns. Minimax uses its explicit request and native Ipopt controls; no failed check silently selects it. See ALG-FIT.

__init__(*, maximum_iterations: int, maximum_elapsed_time_seconds: float, function_tolerance: float = 0.0, gradient_tolerance: float = 0.0, parameter_tolerance: float = 0.0, workers: int = 0, solver_options: Mapping[str, float] | None = None) → None#

Initialize FitControls from the declared inputs.

Parameters:
  • maximum_iterations (int) – Initial value of FitControls.maximum_iterations; see its attribute description for units and ordering.

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

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

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

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

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

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

Returns:

None.

Return type:

None

function_tolerance: float#

Dimensionless Ceres relative cost-change tolerance; zero selects the named source default.

gradient_tolerance: float#

Ceres projected-gradient criterion in normalized optimizer/objective coordinates; zero selects its named default.

maximum_elapsed_time_seconds: float#

Required positive elapsed-time budget in seconds.

maximum_iterations: int#

Required positive iteration limit, a count.

parameter_tolerance: float#

Dimensionless Ceres optimizer-step criterion; zero selects its named default.

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

Effective named numerical settings, including criterion provenance.

workers: int#

Requested native state-group process count including the caller; zero selects hardware concurrency, bounded by eligible groups. Minimax/point readers and active trace capture use one process.

class epcsaft._core.TrialFailure#
first_numerical_failure: Convergence | None#

First cause in this trial’s serial row prefix.

jacobian: bool#

Whether the refusal occurred while derivative columns were requested.

message: str#

Original native explanation; not replaced by an apparent zero residual.

observation: int#

Zero-based failing observation row; the observation count itself denotes a request/model exception without a specific row.

optimizer: list[float]#

Dimensionless optimizer point, including active measurement corrections where declared.

parameter_actions: list[ResidualEnergyAction]#

Retained refusal at one optimizer trial.

status: ObservationStatus#

Typed native refusal cause.

trial: int#

Native trial counter.

class epcsaft._core.FitCovariance#

Local least-squares covariance and rank evidence.

Notes

The unscaled matrix is the inverse local weighted normal matrix; apply variance_factor only under the stated unknown-common-variance assumption. No covariance is claimed for unfinished, rank-deficient, active-bound or minimax estimates. Model discrepancy and physical validation are outside this local estimate.

active_bounds: list[int]#

Indices of complete optimizer coordinates lying within the native bound-activity distance.

assumption: str#

Explicit local linearization/error assumptions; these limit interpretation of any returned covariance.

left_vectors: list[float]#

Optional flattened row-major thin left singular vectors (M, min(M,U)) of the complete objective Jacobian; objective_rows labels rows. Empty unless requested and evaluated.

objective_rows: list[int]#

Positive-weight observation row indices followed by observation_count+input_column labels for measurement penalties.

optimizer: list[float]#

Flattened symmetric (u, u) model-coordinate covariance block after eliminating input corrections; native column-major storage (symmetry gives the same flat order as row-major). Empty unless available.

physical: list[float]#

Flattened symmetric (r, r) covariance D*optimizer*D^T in physical-row order; units are products of physical-row units. Empty unless available.

projected_gradient_norm: float#

Maximum absolute projected objective-gradient component in native normalized optimizer coordinates; may be nonfinite when unavailable.

rank: int#

Numerical rank of the complete weighted/whitened objective Jacobian, a count.

right_vectors: list[float]#

Optional flattened row-major thin right singular vectors (U, min(M,U)); U includes active input corrections, and columns pair with singular_values. Empty unless requested and evaluated.

singular_values: list[float]#

Descending singular values of the complete objective Jacobian, length min(M,U), in normalized residual/optimizer units.

status: str#

available, not_converged, rank_deficient, active_bound, unavailable or minimax_unavailable.

Type:

Covariance availability

variance_factor: float | None#

Optional sum(weight*r^2)/(objective_row_count-rank) for an unknown common residual variance; absent with known measurement sigmas/covariance or insufficient degrees of freedom.

class epcsaft._core.MinimaxRequest#

Explicit constrained estimate of the largest absolute decadic target error.

Notes

This selects the native constrained estimator explicitly. It supplies exact first columns and limited-memory curvature, not a parameter Hessian or global optimum certificate. See ALG-FIT, Guarded minimax.

__init__() → None#

Initialize MinimaxRequest from the declared inputs.

Returns:

None.

Return type:

None

activity_distance: float#

Positive dimensionless normalized distance used to identify active variable bounds.

group_scales: list[float]#

One positive constraint scale per check group, in that group’s error unit; report-only groups remain omitted from trial constraints.

margin: float#

Positive dimensionless initial interior margin; epigraph starts at target maximum + margin*q and slacks at absolute error + margin*group scale.

q: float#

Positive epigraph scale in log10 decades; the minimized dimensionless objective is t/q.

targets: list[int]#

Unique observation-row indices with positive log-ratio arguments; their maximum absolute log10 error is minimized.

tolerance: float#

Positive dimensionless tolerance for scaled feasibility and first-order stationarity diagnostics.

class epcsaft._core.MinimaxRow#

One scaled inequality of the native minimax problem.

auxiliary: int | None#

Epigraph/slack point index subtracted by this row, or None for no such auxiliary.

group: int#

Check-group index; target rows use the number of check groups as a sentinel.

kind: str#

target, maximum, link or mean.

Type:

Native inequality role

members: list[int]#

Point indices of mean-group slacks; empty for a scalar row.

metric: CheckMetric#

Absolute-difference or absolute-log10-ratio error convention.

row: int#

Observation index for a scalar error row; unused for a mean-group row.

scale: float#

Positive physical row scale in the same units as the inequality.

sign: float#

Dimensionless +1 or -1 for paired signed error inequalities; zero where unused.

threshold: float#

Frozen physical error threshold in the metric’s units.

class epcsaft._core.MinimaxResult#

Candidate inequalities, multipliers and local first-order diagnostics.

Notes

Availability, optimizer termination, feasibility, stationarity and final check acceptance are distinct. Interpret post-solve scalar diagnostics, physical_values, multiplier conversions, bound distances/activity and hold/root diagnostics only when availability is ‘available’. Point-only evaluation sets ‘values_only’: point, bounds, scaled values, Jacobian, row identities and frozen checks are retained, while post-solve diagnostics keep uncomputed defaults. Its actual epigraph is point[len(FitResult.optimizer)], not the default t field. Local infeasibility is not proof of global infeasibility. Point evaluation supplies no optimization certificate; minimax supplies no covariance. See ALG-FIT.

active_lower: list[int]#

Point indices near their lower bounds under activity_distance.

active_upper: list[int]#

Point indices near their upper bounds under activity_distance.

application_status: str#

Native application-level termination or point-reader outcome.

availability: str#

Whether complete candidate values and derivative diagnostics were evaluated; not an optimality claim.

complementarity: float#

Maximum scaled multiplier-times-constraint or bound-distance residual.

dual_sign: float#

Maximum wrong-sign inequality/bound multiplier violation for the scaled objective.

feasible: bool#

Whether recomputed scaled primal/bound violations meet the declared tolerance.

frozen_checks: list[CheckResult]#

Check reports fixing baseline thresholds before optimization.

full_stationarity: list[float]#

Physical-objective stationarity in independent optimizer order followed by held-diameter rows; units are decades per corresponding optimizer/diameter unit.

gap: float#

t minus target_maximum, in decades.

hold_causes: list[str]#

Full-space multiplier availability explanation per hold.

hold_multipliers: list[float]#

Reconstructed physical-objective multiplier per hydration hold, decades/(J/mol); nonfinite for an unavailable full-space reconstruction.

ipopt_diagnostics: IpoptDiagnostics | None#

Actual invocation summary; absent for a point reader.

jacobian: list[float]#

Flattened row-major (m, v) scaled-inequality Jacobian, v=len(point); column units are inverse point-entry units.

linear_solver: str#

Actual native Ipopt linear-solver name.

lower: list[float]#

Per-point lower bounds in each point entry’s units.

lower_distances: list[float]#

Dimensionless point-minus-lower distances divided by the declared variable scales.

multipliers: list[float]#

Scaled-objective inequality multipliers lambda, rows order.

physical_multipliers: list[float]#

Physical-objective inequality multipliers q*lambda/row.scale, decades per row-error unit.

physical_values: list[float]#

Length m of unscaled inequalities C in each row’s error unit.

physical_z_lower: list[float]#

Physical-objective lower-bound multipliers q*z_lower, decades per point-entry unit.

physical_z_upper: list[float]#

Physical-objective upper-bound multipliers q*z_upper, decades per point-entry unit.

point: list[float]#

dimensionless model optimizer coordinates, physical t in decades, then physical group slacks in declaration order.

Type:

Full point

primal: float#

Maximum scaled inequality or bound violation, dimensionless.

root_errors: list[float]#

Local dimensionless inequality error estimate from held-root diameter uncertainty, one per inequality; not an enclosure.

rows: list[MinimaxRow]#

Inequality identities/scales in values and Jacobian row order.

slack_groups: list[int]#

Check-group index per mean-error slack, in slack declaration order.

slack_rows: list[int]#

Observation-row index per mean-error slack, same order as slack_groups.

solver_status: str#

Ipopt optimizer termination name; separate from feasibility and stationarity.

stationarity: float#

Maximum absolute stationarity residual of the t/q objective in the native point coordinates.

stationary: bool#

Whether stationarity, dual-sign and complementarity residuals meet the declared tolerance; separate from feasibility.

t: float#

Nonnegative physical epigraph in log10 decades.

target_maximum: float#

Maximum actual absolute target log10 error, in decades.

upper: list[float]#

Per-point upper bounds in each point entry’s units; may include infinity.

upper_distances: list[float]#

Dimensionless upper-minus-point distances divided by the declared variable scales.

values: list[float]#

Length m of dimensionless scaled inequalities c=C/scale, rows order, feasible when <=0.

z_lower: list[float]#

Lower-bound multipliers for t/q, point order, inverse point-entry units.

z_upper: list[float]#

Upper-bound multipliers for t/q, point order, inverse point-entry units.

class epcsaft._core.MeasuredInputKind#

Physical input whose reported uncertainty is declared.

Notes

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

Molality: MeasuredInputKind#

Formula-unit molality, mol/kg solvent.

MoleFraction: MeasuredInputKind#

Independent component mole fraction, dimensionless.

Pressure: MeasuredInputKind#

Pressure, Pa.

Temperature: MeasuredInputKind#

Absolute temperature, K.

class epcsaft._core.MeasuredInput#

One bounded physical input and its known standard uncertainty.

__init__() → None#

Initialize MeasuredInput from the declared inputs.

Returns:

None.

Return type:

None

kind: MeasuredInputKind#

Input quantity and its required physical unit.

lower: float#

Inclusive lower physical input bound in unit, not a standardized correction.

sigma: float#

Nonnegative known standard deviation in unit; zero eliminates this correction coordinate.

species: int#

Component index for MoleFraction; unused for other input kinds.

unit: str#

Explicit input unit admitted for kind; no basis is inferred from a bare magnitude.

upper: float#

Inclusive upper physical input bound in unit.

class epcsaft._core.MeasurementGroup#

Rows sharing the same measured physical inputs.

Notes

Unsupported observation/input combinations, overlapping groups and nonphysical input boxes are refused. See declared-measurement-uncertainty in the native parameter-estimation formulation.

__init__() → None#

Initialize MeasurementGroup from the declared inputs.

Returns:

None.

Return type:

None

dependent_species: list[int]#

Component indices reconstructed by the admitted normalization/charge chart; not independent measurement coordinates.

feed_total_mol: float#

Required positive total feed mol for an equilibrium feed chart; fixes the extensive basis while fractions move.

inputs: list[MeasuredInput]#

Measured inputs in declaration order. A positive-sigma input becomes a standardized correction column only when the group contains at least one positive-weight output.

rows: list[int]#

Observation-row indices sharing this explicitly declared measurement; equal state values alone do not establish sharing.

class epcsaft._core.MeasurementUncertainty#

Known output/input Gaussian measurement-error declaration.

Notes

The matrix must be finite, symmetric under the native criterion and positive definite; correlations have unit diagonal. Native admission never repairs, jitters or pseudo-inverts it. Whitened residuals use one retained Cholesky factor. See errors_in_variables_objective in engine/docs/equations.md.

__init__() → None#

Initialize MeasurementUncertainty from the declared inputs.

Returns:

None.

Return type:

None

correlation: list[float] | None#

Optional flattened row-major (M, M) dimensionless known correlation in the same order; mutually exclusive with covariance.

covariance: list[float] | None#

positive-weight outputs in observation order, then active input correction columns in group/input order. Entry units are products of the corresponding physical units.

Type:

Optional flattened row-major (M, M) known physical covariance

groups: list[MeasurementGroup]#

Explicit shared-input measurement groups in declaration order.

output_sigma: list[float]#

Length-N output standard deviations in observation order and each observation’s physical unit. Positive-weight outputs require finite positive values; excluded zero-weight entries are unused. Difference residuals and unit positive relative weights are required.

class epcsaft._core.InputReconciliation#

Candidate physical input corrections and their objective contribution.

Notes

Reconciled inputs and parameters are fitted candidates. Final checks at the original measured inputs retain a distinct meaning from reconciled-input predictions.

column_groups: list[int]#

Measurement-group index per active positive-sigma input column.

column_inputs: list[int]#

Within-group MeasuredInput index per active input column.

corrections: list[float]#

Dimensionless standardized physical corrections (value-measured)/sigma, in input-column order; these remain unwhitened under a declared matrix.

input_cost: float#

Half the squared input residual norm, dimensionless; with joint covariance it is conditional on the outputs.

jacobian: list[float]#

Flattened row-major (observation_count+input_count, complete_optimizer_count) standardized objective Jacobian; whitened under a declared matrix.

output_cost: float#

Half the squared standardized/whitened output residual norm, dimensionless.

penalties: list[float]#

Squared standardized input residuals, or squared whitened input components with a matrix, in input-column order.

row_groups: list[int]#

Measurement-group identity per output row followed by each input penalty row; native sentinel denotes an ungrouped output.

values: list[float]#

Reconciled positive-sigma input values in group/input-column order, with each MeasuredInput.unit.

class epcsaft._core.FitResult#

Native parameter-estimation candidate, objective and local evidence.

Notes

Only positive-weight objective rows enter least-squares trial values/rank/variance. Zero-weight rows receive final reporting and checks. Fitted parameters are candidates; neither convergence nor covariance proves independent physical validation. See ALG-FIT.

acceptance: str#

Native check acceptance classification, separate from optimizer termination and usable.

chart: EvaluatedCoordinates#

Evaluated physical parameter chart, holds and completed reaction laws at the candidate.

checks: list[CheckResult]#

Final native check reports at stored candidate parameters, without resolving a hydration hold.

covariance: FitCovariance#

Local least-squares uncertainty/rank evidence with explicit availability and assumptions; unavailable for minimax.

data_cost: float#
failures: list[TrialFailure]#

Rejected native trials with original cause and optimizer point.

final_cost: float#

Least-squares final cost in the same convention as initial_cost; NaN for minimax. A zero after refusal is not evidence of a perfect fit.

first_numerical_failure: Convergence | None#

First chronological producer refusal, retained after successful recovery.

initial_cost: float#

Least-squares starting cost 0.5*sum(weight*r^2), extended for measurement errors; NaN for minimax. Failed evaluations may leave zero, which is meaningful only with status/usable.

iteration_costs: list[float]#

Per-Ceres-iteration dimensionless half squared weighted residual norm; entry zero is the start.

iteration_seconds: list[float]#

Per-Ceres-iteration elapsed timing in seconds; entry zero is the starting iteration.

iterations: int#

Estimator iteration count.

jacobian_evaluations: int#

Number of exact Jacobian evaluations.

message: str#

Estimator conclusion and failure explanation.

minimax: MinimaxResult | None#

Constrained-estimator evidence, or None for least squares.

optimizer: list[float]#

Dimensionless model coordinates in declaration order; fitted input corrections are published separately in reconciliation.corrections.

optimizer_jacobian: list[float]#

row-major weighted/whitened output residual columns (N, u) for model coordinates only; complete input/penalty columns are in reconciliation.jacobian. Minimax: raw prediction columns in model optimizer order, not Ceres weighted columns.

Type:

Least squares

parameters: Parameters#

Stored candidate native EOS parameters, including resolved held diameters.

physical: list[float]#

EOS targets, held Born diameters, then reaction coordinates. The first len(chart.active) entries match chart.active; units vary by row.

Type:

Physical rows in chart order

physical_jacobian: list[float]#

Flattened row-major (N, r) physical prediction partials in observation/physical-row order; row units divided by physical-coordinate units.

predictions: list[float]#

Length N of physical predictions in observation order, each ObservationKind unit; inspect statuses for unavailable entries.

rank_records: list[NumericalRank]#

Numerical determination of the complete weighted optimizer Jacobian.

reconciliation: InputReconciliation | None#

Candidate input corrections and standardized objective evidence, or None without a declared measurement model.

residual_evaluations: int#

Number of residual evaluations.

residuals: list[float]#

Length N of unweighted dimensionless residuals in the declared form; statuses retain missing-row causes.

saturation_predictions: list[Prediction | None]#
solver_options: list[dict[str, Any]]#

Effective named numerical settings and provenance.

stability_cost: float#
stability_predictions: list[Prediction | None]#
stability_transitions: list[StabilityTransition]#
status: str#

Native estimator termination classification; a finite candidate can be usable after reaching a limit.

statuses: list[ObservationStatus]#

One observation availability cause per row, including NotEvaluated after skipped/failed evaluation.

trial_failures: int#

Number of rejected native trial evaluations.

usable: bool#

Whether the native estimator marks the retained candidate usable. Least squares requires a published candidate with finite physical values and a termination other than failed; a limit may still be usable. This does not establish convergence, check acceptance or physical validity.

weighted_residuals: list[float]#

Length N of least-squares output objective residuals sqrt(weight)*residual, whitened when declared; input penalties are published separately in reconciliation. Excluded rows are zero and unavailable rows are not successful zeros.

epcsaft._core.predict(model: HelmholtzModel, observation: Observation) → Prediction#

Evaluate one declared physical observation natively.

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

  • observation (Observation) – Reported quantity, physical inputs and declared residual convention.

Returns:

Prediction with physical unit, unweighted residual and independent refusal evidence.

Return type:

Prediction

Notes

Native validation precedes state/reference/equilibrium evaluation. A failed physical state is unavailable, not a zero prediction or residual.

epcsaft._core.differentiate(model: HelmholtzModel, observation: Observation) → PredictionGradient#

Evaluate exact first columns of one declared physical prediction.

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

  • observation (Observation) – Physical row to evaluate and differentiate.

Returns:

PredictionGradient in active native coordinate order, or an empty gradient with cause.

Return type:

PredictionGradient

Notes

Columns are prediction partials, not weighted residual columns. The native property/reference/solved-state owner supplies them.

epcsaft._core.fit(parameters: Parameters, thermochemistry: ThermochemistryRecord | None, coordinates: Sequence[Coordinate], observations: Sequence[Observation], weights: Sequence[float], controls: FitControls, holds: Sequence[HydrationHold] = ..., checks: Sequence[CheckGroup] = ..., baseline: Parameters | None = ..., singular_vectors: bool = ..., starts: Sequence[Sequence[float]] | None = None, iterations: int | None = None, seconds: float | None = None, minimax: MinimaxRequest | None = ..., uncertainty: MeasurementUncertainty | None = ...) → FitResult | list[FitResult]#

Estimate bounded parameters with native least squares or explicitly requested minimax.

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

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

  • coordinates (Sequence[Coordinate]) – Ordered affine physical parameter/source coordinates.

  • observations (Sequence[Observation]) – Ordered reported quantities with physical inputs, source conventions and residual forms.

  • weights (Sequence[float]) – Nonnegative relative row weights; empty means all one. Least-squares residuals are sqrt(weight)*r; zero-weight rows are final reports. Known measurement models require unit positive weights.

  • controls (FitControls) – Required iteration/elapsed budgets and named native tolerances.

  • holds (Sequence[HydrationHold]) – Ordered dependent Born-diameter constraints, resolved by exact native held-row solves.

  • checks (Sequence[CheckGroup]) – Declared final error groups; these do not silently change the estimator.

  • baseline (Parameters | None) – Optional separately stored source parameters used to freeze baseline check thresholds.

  • singular_vectors (bool) – Request local objective-Jacobian singular vectors in the returned covariance evidence.

  • starts (Optional[Sequence[Sequence[float]]]) – Optional ordered dimensionless model optimizer starts; None requests a single start. Sequence mode has shared budgets and refuses unsupported coordinate/measurement forms.

  • iterations (Optional[int]) – Optional shared sequence iteration budget; None uses controls.maximum_iterations.

  • seconds (Optional[float]) – Optional shared sequence wall-time budget in seconds; None uses controls.maximum_elapsed_time_seconds.

  • minimax (MinimaxRequest | None) – Explicit constrained-estimation request; None selects Ceres least squares.

  • uncertainty (MeasurementUncertainty | None) – Optional known Gaussian physical measurement-error declaration, including shared input corrections and optional covariance.

Returns:

One FitResult, or ordered list for explicit sequence starts; each retains its own termination, checks and availability.

Return type:

Union[FitResult, list[FitResult]]

Notes

Ceres uses exact native columns. Minimax has distinct local feasibility/stationarity evidence and no covariance. Failed trials retain their original cause; returned candidates remain calibration results, not physical validation. See ALG-FIT.

class epcsaft._core.CheckMetric#

Error convention for native parameter-estimation checks.

Notes

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

AbsoluteDifference: CheckMetric#

Absolute prediction-minus-observation difference in the observation unit; the retained signed error is prediction-observation.

AbsoluteLog10Ratio: CheckMetric#

Absolute log10(prediction/observation), in decades; both arguments must be positive, and retained row errors keep their sign.

class epcsaft._core.HydrationHold#

Eliminate one Born diameter by holding a single-ion solvation target.

Notes

Both inner criteria apply. The dependent derivative is formed from the exact held-row slope; a failed hold is not substituted by a fixed guessed diameter. See dependent_born_diameter_derivative in engine/docs/equations.md.

__init__() → None#

Initialize HydrationHold from the declared inputs.

Returns:

None.

Return type:

None

diameter_tolerance: float#

Positive achieved diameter-uncertainty criterion in angstrom.

energy_tolerance: float#

Positive target energy-residual criterion in J/mol.

lower: float#

Lower Born-diameter bracket in angstrom.

maximum_iterations: int#

Positive inner safeguarded-Newton iteration limit.

reference: Observation#

SolvationGibbsEnergy observation defining the target in observed, J/mol.

upper: float#

Upper Born-diameter bracket in angstrom.

class epcsaft._core.HoldResult#

Held-diameter residual and exact implicit derivatives.

correction: float#

Magnitude of the last Newton correction abs(H/H_d), angstrom.

derivative: float#

Held-row partial H_d in J/(mol angstrom).

energy_error: float#

Signed held solvation-energy residual in J/mol.

iterations: int#

Inner safeguarded-Newton iteration count.

parameter_derivative: list[float]#

independent EOS targets followed by held Born diameters, excluding reaction-coordinate rows. Units are J/mol divided by each active parameter’s native unit.

Type:

Held energy-row partials in EvaluatedCoordinates.active order

rank: NumericalRank#

Scalar hold derivative rank and its actual cutoff.

uncertainty: float#

Achieved diameter uncertainty min(correction, bracket width), angstrom; a local numerical estimate.

class epcsaft._core.EvaluatedCoordinates#

Mapped candidate parameters, dependent diameters and reaction laws.

active: list[ActiveParameter]#

EOS physical-row ActiveParameters, independent targets followed by held Born diameters; reaction rows are not ActiveParameters.

holds: list[HoldResult]#

HoldResult per declared hold in input order.

map: list[float]#

Flattened row-major (r, u) exact D=d(physical)/d(model optimizer), including holds and target multipliers; row units per dimensionless optimizer increment.

parameters: Parameters#

Native EOS parameters after affine mapping and held-diameter resolution.

physical: list[float]#

Physical target values in EOS-target, held-diameter, then reaction order, with each row’s native unit.

reaction_laws: dict[str, ReactionLogPolynomial]#

Completed native ln K(T) laws keyed by reaction name; replay these laws without applying the fitted coordinates again.

class epcsaft._core.CheckGroup#

Declared final error group and optional fixed or baseline thresholds.

Notes

Checks re-evaluate stored parameters at the original observations without resolving hydration holds. A failed group is not proof that no feasible fit exists.

__init__() → None#

Initialize CheckGroup from the declared inputs.

Returns:

None.

Return type:

None

baseline: bool#

Freeze thresholds from the separately supplied baseline parameter set under the native check rules.

maximum: float | None#

Optional maximum-error threshold in the metric unit.

mean: float | None#

Optional arithmetic mean-absolute-error threshold in the metric unit.

metric: CheckMetric#

Absolute-difference or absolute-decades error convention.

name: str#

Caller check-group identity.

report_only: bool#

Report failures without changing candidate acceptance; omitted from minimax trial constraints.

rows: list[int]#

Observation indices in the group, in declared reporting order.

class epcsaft._core.CheckResult#

Signed row errors and absolute-error group statistics.

argmax: int#

Observation-row index attaining the maximum absolute error; meaningful only for an available group.

baseline_maximum: float | None#

Frozen baseline maximum absolute error in unit; native binding returns None when no baseline value exists.

baseline_mean: float | None#

Frozen baseline mean absolute error in unit; native binding returns None when no baseline value exists.

errors: list[float]#

Signed physical differences or signed log10 ratios, corresponding to rows; group statistics use absolute values.

failed_rows: list[int]#

Observation indices whose final check evaluation was unavailable or whose absolute error exceeded the maximum threshold; a mean-only failure need not identify an individual row.

maximum: float#

Maximum retained absolute error in unit; interpret only with status, since an unavailable row need not replace a partial maximum.

maximum_threshold: float | None#

Effective maximum threshold in unit, or None without one.

mean: float#

Arithmetic mean absolute error in unit; interpret only with status and failed_rows.

mean_threshold: float | None#

Effective mean threshold in unit, or None without one.

name: str#

Declared check-group identity.

report_only: bool#

Whether this group’s failure is excluded from acceptance decisions.

rows: list[int]#

Observation indices in reporting order.

slopes: list[float]#

1 for Difference or 1/(prediction*ln(10)) for log10 ratio; inverse prediction units for the latter.

Type:

Signed-error derivative with respect to prediction

status: str#

Native availability and threshold outcome; unavailable rows remain explicit.

unit: str#

physical observation unit for Difference or log10 decades for ratio errors.

Type:

Metric unit

epcsaft._core.evaluate_coordinates(parameters: Parameters, set: CoordinateSet, optimizer: Sequence[float], holds: Sequence[HydrationHold], thermochemistry: ThermochemistryRecord | None = ..., solver_options: Mapping[str, float] | None = None) → EvaluatedCoordinates#

Map one optimizer point and solve its declared dependent diameters.

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

  • set (CoordinateSet) – Ordered native CoordinateSet.

  • optimizer (Sequence[float]) – Length u of dimensionless model coordinates.

  • holds (Sequence[HydrationHold]) – Ordered hydration holds, each with a declared bracket and two numerical criteria.

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

  • solver_options (Mapping[str, float] | None) – Optional mapping of admitted named numerical settings; None uses source defaults.

Returns:

EvaluatedCoordinates including physical target order, exact map and completed reaction laws.

Return type:

EvaluatedCoordinates

Notes

The exact map includes target coefficients and implicit held-diameter derivatives; failed inner admission is not replaced by a guessed value.

epcsaft._core.evaluate_checks(stored: Parameters, observations: Sequence[Observation], checks: Sequence[CheckGroup], baseline: Parameters | None = ..., solver_options: Mapping[str, float] | None = None) → list[CheckResult]#

Re-evaluate final check groups at stored physical parameters.

Parameters:
  • stored (Parameters) – Stored native parameter set; held diameters are consumed as stored, not resolved again.

  • observations (Sequence[Observation]) – Original declared physical observations.

  • checks (Sequence[CheckGroup]) – Ordered final check groups.

  • baseline (Parameters | None) – Optional stored source parameters for native baseline threshold rules.

  • solver_options (Mapping[str, float] | None) – Optional mapping of admitted named numerical settings; None uses source defaults.

Returns:

CheckResult list in check-group order, preserving unavailable rows.

Return type:

list[CheckResult]

Notes

This is a point check and does not fit parameters. Report-only failures are retained independently of acceptance.

epcsaft._core.observations_at(parameters: Parameters, coordinates: Sequence[Coordinate], optimizer: Sequence[float], holds: Sequence[HydrationHold], observations: Sequence[Observation], errors: Sequence[float], thermochemistry: ThermochemistryRecord | None = None, solver_options: Mapping[str, float] | None = None) → list[Observation]#

Construct observation values at a declared native parameter point with signed errors.

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

  • coordinates (Sequence[Coordinate]) – Ordered affine physical coordinate declarations.

  • optimizer (Sequence[float]) – Dimensionless model point in coordinate order.

  • holds (Sequence[HydrationHold]) – Ordered native hydration holds.

  • observations (Sequence[Observation]) – Template observations supplying physical states and source conventions.

  • errors (Sequence[float]) – One signed physical difference or signed log10 error per observation in native check-error convention, not an uncertainty.

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

  • solver_options (Mapping[str, float] | None) – Optional mapping of admitted named numerical settings; None uses source defaults.

Returns:

Fresh Observation list in input order with manufactured reported values.

Return type:

list[Observation]

Notes

This makes numerical recovery cases, not new measurements or physical validation. Native code evaluates the point before changing observation values.

class epcsaft._core.ObservationEvaluation#

Native point predictions, exact columns and optional measurement evidence.

Notes

For Difference, dr/dv=(dy/dv)/scale; for LogRatio, dr/dv=(dy/dv)/prediction. These point-reader prediction columns must not be confused with weighted Ceres residual columns. See ALG-FIT.

chart: EvaluatedCoordinates#

Evaluated physical coordinate map, held diameters and completed reaction laws.

data_cost: float#
first_numerical_failure: Convergence | None#

First producer refusal in the eligible row prefix.

first_numerical_failure_observation: int#

Source row, meaningful only when a first cause is present.

gradient: list[float]#

Flattened row-major (N, r) exact raw physical prediction partials, observation/physical-row order; prediction units per native physical-row unit.

optimizer_gradient: list[float]#

Flattened row-major prediction columns in model optimizer order, including physical input-motion columns when declared; prediction units per dimensionless optimizer increment.

predictions: list[float]#

Length N of physical predictions in observation order; units depend on ObservationKind and statuses retain refusals.

reconciliation: InputReconciliation | None#

Standardized candidate input corrections and complete objective columns, or None without a measurement declaration.

reference_values: list[list[float]]#

Ragged per-observation dimensionless reference ln fugacity coefficients in cation/anion order, followed by pure-solvent ln fugacity coefficient when present; otherwise empty.

residual_optimizer_gradient: list[float]#

Unit-weight dimensionless residual columns in optimizer order; with uncertainty, the complete standardized and optionally whitened objective columns including input penalties.

saturation_predictions: list[Prediction | None]#
solver_options: list[dict[str, Any]]#

Effective named numerical settings and provenance.

stability_cost: float#
stability_predictions: list[Prediction | None]#
state_densities: list[list[float]]#

Ragged per-observation density evidence in mol/m^3 when retained for uncertainty evaluation: central state/declared phases first, then reference ladder and pure-solvent states where present; otherwise empty.

statuses: list[ObservationStatus]#

One availability or refusal cause per observation in input order.

epcsaft._core.evaluate_observations(parameters: Parameters, coordinates: Sequence[Coordinate], optimizer: Sequence[float], holds: Sequence[HydrationHold], observations: Sequence[Observation], thermochemistry: ThermochemistryRecord | None = None, uncertainty: MeasurementUncertainty | None = ..., solver_options: Mapping[str, float] | None = None) → ObservationEvaluation#

Evaluate declared predictions and exact point columns without optimizing.

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

  • coordinates (Sequence[Coordinate]) – Ordered affine physical parameter/source coordinates.

  • optimizer (Sequence[float]) – Dimensionless model coordinates, extended by standardized input corrections when declared.

  • holds (Sequence[HydrationHold]) – Ordered native hydration holds.

  • observations (Sequence[Observation]) – Ordered physical observation declarations.

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

  • uncertainty (MeasurementUncertainty | None) – Optional known measurement-error model for shared input corrections and whitening.

  • solver_options (Mapping[str, float] | None) – Optional mapping of admitted named numerical settings; None uses source defaults.

Returns:

ObservationEvaluation with physical and optimizer prediction columns and unit-weight residual columns.

Return type:

ObservationEvaluation

Notes

No optimizer success is inferred from point evaluation. Raw prediction columns and standardized/whitened residual columns have distinct meanings.

epcsaft._core.evaluate_minimax(parameters: Parameters, coordinates: Sequence[Coordinate], optimizer: Sequence[float], holds: Sequence[HydrationHold], observations: Sequence[Observation], checks: Sequence[CheckGroup], baseline: Parameters | None, minimax: MinimaxRequest, thermochemistry: ThermochemistryRecord | None = None, solver_options: Mapping[str, float] | None = None) → FitResult#

Evaluate the native minimax rows at the declared starting point without optimizing.

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

  • coordinates (Sequence[Coordinate]) – Ordered affine physical coordinates supported by minimax.

  • optimizer (Sequence[float]) – Dimensionless model optimizer point.

  • holds (Sequence[HydrationHold]) – Ordered native hydration holds.

  • observations (Sequence[Observation]) – Ordered physical observations.

  • checks (Sequence[CheckGroup]) – Declared final/error guard groups.

  • baseline (Parameters | None) – Optional source parameter set for frozen check thresholds.

  • minimax (MinimaxRequest) – Explicit positive epigraph, row-scale and feasibility controls.

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

  • solver_options (Mapping[str, float] | None) – Optional mapping of admitted named numerical settings; None uses source defaults.

Returns:

FitResult with minimax row values/columns and frozen checks; no optimization or stationarity certificate.

Return type:

FitResult

Notes

The native point reader shares the constrained estimator row algebra and retains its local availability limits.

epcsaft._core.formula_composition(solvent_fractions: Sequence[float], parameters: Parameters, ion_indices: tuple[int, int], stoichiometry: tuple[int, int], molality: float) → list[float]#

Convert one charge-neutral salt formula molality into explicit mole fractions.

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

  • parameters (Parameters) – Admitted native EOS parameters.

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

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

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

Returns:

Length n normalized dimensionless mole fractions in component_ids order.

Return type:

list[float]

Notes

Uses declared solvent molar masses and positive ion counts; formula molality is mol salt/kg solvent. The native owner enforces solvent and formula electroneutrality. See formula_unit_composition in engine/docs/equations.md.

epcsaft._core.reaction_log10_reciprocal(law: ReactionLogPolynomial) → list[float]#

Convert a natural-log reaction law to a decadic reciprocal-temperature form.

Parameters:

law (ReactionLogPolynomial) – Native ln K=a+b/T+c*ln(T/Tref)+d*T source correlation.

Returns:

Three coefficients [A, B, C] of -log10 K = A/T + B + C*T, in K, dimensionless and 1/K.

Return type:

list[float]

Notes

Returns [-b/ln(10), -a/ln(10), -d/ln(10)]. A nonzero logarithmic coefficient c is refused; no refit, standard-state change or validity-range extension is performed.