A phase calculation combines several independently fallible pieces: a physical model, a choice of unknowns, residual equations, derivatives, a nonlinear algorithm, and result interpretation. Treat these as separate layers when debugging. Otherwise, a unit error can look like a convergence problem, and a small residual can hide convergence to the wrong branch.
This page is a source-reading and modification guide. The user equilibrium pages explain which calculation to choose; the testing guide explains how to verify an implementation.
For the routine you are changing, identify:
Search for both the routine that packs X and the routine that unpacks it.
Index positions are part of the internal contract. PT, PX, TX, three-phase,
and general multiphase equations do not all use the same layout.
Suppose . A residual derivative with respect to the packed unknown is not simply its pressure derivative:
Log coordinates keep pressure positive, but they do not by themselves make the
iteration well scaled or prevent overflow. A finite-difference check must
perturb u, not physical pressure, if the Jacobian is defined with respect to
the packed vector.
Several solver families coexist. Similar routine names do not imply identical interfaces or guarantees.
| Source | Role to inspect |
|---|---|
src/math/newton.f90 |
Configurable Newton solver with diagnostics and safeguarding |
src/math/nonlineal.f90 |
Another multivariate Newton implementation and homotopy helpers |
src/math/math.f90 |
Scalar Newton, numerical helpers, and MINPACK adapters |
src/math/linalg.f90 |
Dense linear-system and eigenproblem wrappers |
src/math/continuation.f90 |
Predictor/corrector driver with callback interfaces |
src/models/solvers/saturation_point.f90 |
Saturation equations and local point correctors |
src/equilibria/ |
Problem-specific loops and phase logic |
When reading an unqualified call newton(...), follow its use association
to the actual module. Before replacing a solver, compare callback signatures,
output status conventions, scaling, maximum-iteration behavior, and which
quantities the caller assumes were filled on return.
Do not infer that a low-level linear solve propagates all LAPACK errors simply because it calls LAPACK. Check whether the wrapper exposes or handles the status. If you need stronger error reporting, plan that as an explicit interface change with tests rather than quietly changing a caller’s assumed semantics.
For , Newton’s method solves , where . A useful central-difference check of column is
Use a relative and absolute scale for so a zero coordinate still gets a nonzero perturbation. Try more than one step size: an extremely small step can amplify roundoff, while a large step measures curvature rather than the local derivative. Avoid crossing invalid domains or switching volume branches when comparing derivatives intended for one smooth branch.
If the Jacobian is wrong, inspect unpacking, chain-rule factors, component ordering, and phase conventions before changing damping. In particular, the user convention may be represented internally as an incipient phase divided by the feed phase; dew calculations can therefore use inverted ratios. Check the actual reconstruction equations.
A phase boundary is a curve, not a single root. A continuation method fixes one specification to select a point, corrects the equilibrium equations, then predicts a nearby point using a tangent. For equations ,
The generic driver in src/math/continuation.f90 exposes callbacks for
residuals/derivatives, optional specification updates, postprocessing, point
correction, and stopping. Read the call site to see which callbacks a given
envelope actually supplies.
The current generic driver’s default specification update selects the largest
absolute tangent component and rescales the tangent and step. It does not
apply the 0.05 step cap shown in an example comment. If a branch needs a
physical step limit, identify the active callback that supplies it or add a
tested policy deliberately.
The generic result has a fixed row count, with unfilled rows initialized to zero. That is a storage convention, not proof that every requested point was accepted. Specialized envelope routines can use other storage conventions. Do not interpret padding as a zero-temperature equilibrium point.
A converged negative phase fraction can be useful in a mathematical continuation formulation but is not an ordinary physical phase split. Likewise, forcing a liquid root may intentionally follow a metastable branch. Preserve the distinction in names, documentation, tests, and wrappers.
Near a critical point, phases become indistinguishable and the equations may be nearly singular. Tolerances and step control matter, but singularity can also reflect the formulation itself. A full mixture criticality condition includes the ideal contribution to the stability matrix; a residual-energy Hessian alone is not the general mixture condition.
When an envelope fails at point 137, save the last accepted state, the predictor, selected specification, residual norms, and relevant parameters. Try to reproduce the single point correction before rerunning a long curve. This makes it easier to tell whether the problem began with a bad predictor, an invalid phase reconstruction, or a broken residual/Jacobian.
For a flash regression, check the feed balance in addition to a solver flag:
For multiple phases, use the representation and reference-phase convention of that routine rather than extrapolating the two-phase array layout. Never compare two implementations’ raw packed vectors until you have checked that they pack the same variables in the same order.
Changing a tolerance, line search, initial guess, or root choice can change which solution is found. Record why the change is needed and test more than the failing example: one ordinary case, the regression, a relevant limiting case, and a failure path. For performance changes, compare both outputs and timings under the same compiler/profile.
Avoid broadly increasing iteration limits to hide unexplained regressions. Preserve a minimal test of the failure and document any remaining limitation. The end-to-end walkthrough shows how to carry that evidence through a contribution.