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.
A required exact native action was refused.
- Available: ObservationStatus#
Requested prediction or derivative is available.
No admitted central equilibrium state is available.
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.
A required reference value or limiting column is unavailable.
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.
- 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.
- 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.
- mass_basis: bool#
For Density/PhaseDensity, request kg/m^3 rather than mol/m^3 through declared molar masses.
- pressure: float#
Pressure-closed or added-feed-state pressure in Pa; equilibrium observations use problem.pressure instead.
- pressure_reference: EquilibriumProblem | None#
- problem: EquilibriumProblem#
Declared equilibrium specification, or initial endpoint for AdditionEnthalpy; also owns the named source law for ln K observations.
- 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#
- class epcsaft._core.Prediction#
One native observation prediction with physical units and failure evidence.
- branch: DensityBranch | None#
Resolved density branch, or None without pressure-closure branch evidence; Unspecified is not a phase classification.
- convergence: Convergence | None#
Consumed equilibrium/density convergence record, or None without one.
- first_numerical_failure: Convergence | None#
First producer refusal, including recovered causes.
- 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.
- status: ObservationStatus#
Availability or specific refusal cause.
- class epcsaft._core.PredictionGradient#
- first_numerical_failure: Convergence | None#
First native action refusal, including a successful retry.
- 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.
- status: ObservationStatus#
Availability or blocking native action cause.
- 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.
- 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.
- 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.
- reaction: ReactionCoordinate | None#
Optional named source coordinate; mutually exclusive with EOS targets.
- targets: list[CoordinateTarget]#
Ordered EOS targets, each equal to coefficient*q; empty for a reaction coordinate.
- 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:
- 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:
Notes
Tied slots must agree; invalid or conflicting reaction sources are refused. This reads a start and performs no fit.
- 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.
- parameter_tolerance: float#
Dimensionless Ceres optimizer-step criterion; zero selects its named default.
- class epcsaft._core.TrialFailure#
- first_numerical_failure: Convergence | None#
First cause in this trial’s serial row prefix.
- 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.
- status: ObservationStatus#
Typed native refusal cause.
- 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.
- 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.
- 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.
- 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.
- metric: CheckMetric#
Absolute-difference or absolute-log10-ratio error convention.
- 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.
- availability: str#
Whether complete candidate values and derivative diagnostics were evaluated; not an optimality claim.
- dual_sign: float#
Maximum wrong-sign inequality/bound multiplier violation for the scaled objective.
- 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.
- hold_multipliers: list[float]#
Reconstructed physical-objective multiplier per hydration hold, decades/(J/mol); nonfinite for an unavailable full-space reconstruction.
- jacobian: list[float]#
Flattened row-major (m, v) scaled-inequality Jacobian, v=len(point); column units are inverse point-entry units.
- lower_distances: list[float]#
Dimensionless point-minus-lower distances divided by the declared variable scales.
- physical_multipliers: list[float]#
Physical-objective inequality multipliers q*lambda/row.scale, decades per row-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
- 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.
- 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.
- upper_distances: list[float]#
Dimensionless upper-minus-point distances divided by the declared variable scales.
- 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.
- 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.
- 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.
- 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.
- 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.
- penalties: list[float]#
Squared standardized input residuals, or squared whitened input components with a matrix, in input-column order.
- 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.
- 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.
- 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.
- residuals: list[float]#
Length N of unweighted dimensionless residuals in the declared form; statuses retain missing-row causes.
- saturation_predictions: list[Prediction | None]#
- stability_predictions: list[Prediction | None]#
- 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.
- 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:
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:
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:
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
- reference: Observation#
SolvationGibbsEnergy observation defining the target in observed, J/mol.
- class epcsaft._core.HoldResult#
Held-diameter residual and exact implicit derivatives.
- 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.
- 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.
- baseline: bool#
Freeze thresholds from the separately supplied baseline parameter set under the native check rules.
- metric: CheckMetric#
Absolute-difference or absolute-decades error convention.
- 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.
- 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:
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:
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:
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.
- 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]#
- 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:
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:
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:
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:
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.