Residuals and linear-solver convergence

Vanellus solves a steady simulation with two nested iterative processes. The outer SIMPLE loop couples pressure, velocity, temperature, and, when enabled, turbulence. Within each SIMPLE iteration, those equations are solved as separate linear systems.

Every linear system uses the biconjugate gradient stabilized method, or BiCGSTAB. This creates two related but distinct uses of residuals:

Both use the same scaling, but they are sampled at different points and compared with different tolerances.

What a scaled residual means

For an assembled linear system \(A\phi = b\), the unscaled residual is the remaining equation imbalance:

\[ r = b - A\phi \]

Its raw magnitude depends on the equation, mesh, units, and coefficient sizes. A raw pressure residual and a raw temperature residual therefore cannot share a meaningful convergence target.

Vanellus converts the residual to a dimensionless value, \(R\), using:

\[ R = \frac{\left\lVert b - A\phi \right\rVert_2} {\left\lVert A\phi - A\bar{\phi} \right\rVert_2 + \left\lVert b - A\bar{\phi} \right\rVert_2} \]

Here, \(\bar{\phi}\) is a reference field formed from the mean value of \(\phi\). Cells that do not participate in an equation retain their enforced values in this reference. The denominator represents the scale of the assembled equation around that mean field.

This scaling makes the value dimensionless and allows pressure, velocity, temperature, and turbulence residuals to use a common outer target. It does not turn the residual into a percentage error, and a residual of 1e-4 does not mean that a field is accurate to 0.01%.

The normalization is calculated at the beginning of each linear solve and held fixed during that solve. A new system and normalization are produced as the SIMPLE loop advances.

SIMPLE residuals

At the start of each equation solve, Vanellus evaluates how well the incoming field satisfies the newly assembled equation. This scaled initial value becomes the SIMPLE residual for that field.

These are the values exposed as residual_* columns in iteration_info.csv. They show how the equation imbalances presented to successive linear solves change as pressure, flow, and temperature become mutually consistent.

After a SIMPLE iteration, Vanellus compares every solved-field residual with target_residual. The simulation reaches residual_converged only when they are all at or below that target. The default target_residual is 1e-4.

The recorded value is not the residual at the end of BiCGSTAB. That final residual controls the inner solve, while the initial residual is retained as the outer convergence history.

Linear-solver residuals

Within an equation solve, BiCGSTAB repeatedly updates the field and its scaled residual. The solve converges when that residual reaches its effective linear tolerance.

For pressure, temperature, and each turbulence equation, Vanellus calculates the tolerance from the previous SIMPLE residual, \(R_{\mathrm{previous}}\):

\[ T_{\mathrm{linear}} = \max\left(\mathtt{atol}, \mathtt{rtol} \times R_{\mathrm{previous}}\right) \]

Momentum uses the mean of the previous x-, y-, and z-velocity residuals to set one tolerance for its component solves. On the first SIMPLE iteration, the previous residual reference is initialized to 1.

The two controls serve different purposes:

• rtol makes the linear solves tighten as the outer SIMPLE residual falls. It is relative to the previous SIMPLE residual, not the initial residual of the current BiCGSTAB solve.
• atol is the lower limit on that tolerance. Once rtol × previous SIMPLE residual falls below atol, the solve continues to use atol rather than demanding an ever-smaller residual.

Early in the SIMPLE loop, a large relative stopping threshold deliberately avoids reducing an inner linear residual further than is useful. The coupled state is still changing substantially, so the next SIMPLE iteration assembles a different linear system. As the SIMPLE residual falls, rtol lowers the stopping threshold and asks each inner solve for a more accurate correction.

For example, with rtol: 1e-3, atol: 1e-8, and a previous temperature residual of 2e-2, the next energy solve uses a tolerance of 2e-5. If the previous residual later reaches 5e-7, the relative value would be 5e-10, so the 1e-8 absolute tolerance takes over.

An unnecessarily low stopping threshold spends time solving an intermediate system; one that is too high produces weak corrections that can slow or destabilize outer convergence. The standard numerics presets balance these effects.

Reading the diagnostics

Each row of iteration_info.csv represents one SIMPLE iteration:

• residual_* is the scaled initial residual used for SIMPLE convergence;
• *_linear_iterations is the number of BiCGSTAB iterations used by the retained linear-solver attempt; and
• *_right_preconditioner identifies the preconditioner used by that attempt.

The public max_iterations setting limits SIMPLE iterations, not BiCGSTAB iterations. Vanellus selects the inner linear-iteration limit automatically from the system size. If an inner solve is unsuccessful, an ordered preconditioner fallback can retry it before the SIMPLE loop continues.

A falling residual history shows that the discrete equations are becoming mutually consistent. It does not establish mesh independence, physical accuracy, or the suitability of the model.

See also

• Diagnose an instability uses these diagnostics to identify the first unstable equation.
• What the Vanellus solver does for the relationship between a steady physical result and numerical iterations.
• Preconditioners and fallbacks for the available methods and retry behavior.
• Numerics presets compares the linear tolerances in each standard preset.
• How simulations stop for all terminal conditions.
• API reference for exact fields and allowed values.