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.