Diagnostics#

Read the cause, available values and achieved residuals together. Declaration errors, unavailable candidates and finite candidates outside a requested tolerance describe different outcomes. The water notebook, caloric notebook and discovery notebook show pressure closure, missing thermal outputs and finite-search evidence respectively.

Start with the declaration#

A ParameterError identifies an invalid or incomplete declaration, such as an unknown component, an unsupported unit or specifying both P and density. An EosError can identify a thermodynamic evaluation failure. Use the Python declarations and native state records to distinguish exceptions from returned availability causes.

Keep the smallest physical input that reproduces the cause: source selection, component order, T in K, P in Pa or density in mol/m³, composition, support, reference and requested observable. A raw optimizer message without those inputs does not identify a thermodynamic failure.

Inspect candidates and convergence#

For equilibrium, check that temperature and pressure are present and the state arrays are populated before consuming the candidate. Then inspect success, message, topology_event, first_numerical_failure, convergence, and raw and classified residuals. A finite candidate can miss the requested tolerance; retain its achieved residual instead of reporting a successful physical result from the optimizer termination alone. No finite candidate means there is no state to substitute into a downstream calculation.

Balances use the feed’s declared basis. A pressure residual has units of Pa; a reported scaled/classified row uses its own normalization. Compare a row with the tolerance defined for that row rather than mixing raw residuals with unrelated dimensionless thresholds. The native equilibrium reference describes the result fields.

A numerical floor estimates attainable accuracy from the reported inner-solve and input errors. It is not automatically a rigorous error bound or a reason to silently relax a requested tolerance. Conditioning, residual refinement and an independent identity provide different evidence.

Diagnose the density branch#

A state at pressure retains its density convergence record and branch information. density_diagnostics requests a bounded report over declared density nodes, with evaluation order, tolerances, time and evaluation budgets. It can return samples, pressure crossings, spinodals, declared brackets and unresolved points. Samples use mol/m³, pressure Pa and pressure-density slope Pa m³/mol. Read unavailable sample causes before using their fields.

The density algorithm defines the finite search and connected-cell meanings. A finite scan does not enumerate all roots by proof. The water notebook checks its selected branch’s pressure closure; it does not demonstrate complete root enumeration.

Preserve partial availability#

A missing ideal thermal record leaves Total calorics unavailable while valid residual work remains readable. A singular action can leave a central value available. Inspect thermochemistry_status, component-property causes and per-action causes separately; never replace an unavailable value with zero. The state guide and action guide explain those distinctions.

Observe work explicitly#

epcsaft.trace(diagnostics=True) is a context manager for explicit native observations. Run the calculation inside it and read the captured spans and events afterwards. A span can retain its convergence record; an event names its iteration, values and reason. Model counters record derivative work; continuation and discovery have their own accepted-state/trial records. Tracing is an explicit observation, not permission to rerun a hidden search or to change tolerances. The trace definitions and equilibrium algorithm describe the available records.

When reporting a problem, include requested tolerance, achieved residuals, physical inputs and the exact unavailable cause. State whether the evidence is a source-parameter prediction, numerical verification or an independent physical comparison. A convergence record alone establishes none of the last category.

Example: a declared split#

from epcsaft import Mixture, Parameters
from epcsaft.equilibrium import Amounts, Phase, Problem, bubble_point, solve_equilibrium

parameters = Parameters.from_packets("data/packets", [("gross-2001-methane-ethane/3", ["methane", "ethane"])])
model = Mixture(parameters)
feed = Amounts({"methane": 0.3, "ethane": 0.7})
problem = Problem(phases=[Phase("L", kind="liquid"), Phase("V", kind="vapor")],
                  T=250.0, P=1e5, feed=feed)
result = solve_equilibrium(model, problem)
print(result.success, result.message, result.topology_event,
      result.first_numerical_failure, result.convergence)
# Inner convergence does not make a coalesced declared split successful.
bubble = bubble_point(liquid=Phase("L", kind="liquid"), T=230.0, feed=feed)
report = model.density_diagnostics(250.0, 1e5, x=[0.3, 0.7])
print(report.unresolved)

bubble is a declaration; solve it with solve_equilibrium(model, bubble). Density diagnostics describes a finite search, not proof of all roots.