Preconditioners and fallbacks

Every Vanellus linear solve uses BiCGSTAB. A preconditioner helps it solve a difficult system with fewer iterations or greater numerical robustness; it is not a different linear-solver algorithm. See Residuals and linear-solver convergence for how Vanellus decides that a linear solve has converged.

Preconditioning has its own cost. Stronger options generally require more setup and more work per iteration, so the option with the fewest linear iterations is not always the fastest overall.

The API options below are all right preconditioners. Vanellus handles any additional internal scaling automatically.

Available right preconditioners

The following families cover every right preconditioner selectable through the public API.

No preconditioner: `none`

none runs BiCGSTAB without a right preconditioner. It has the lowest cost per linear iteration and can be efficient for easy systems. Poorly conditioned systems may instead require many iterations or fail to converge, making a preconditioned solve faster overall.

Multigrid: `mg32` and `mg64`

Multigrid works across progressively coarser mesh levels. The fine level resolves local error, while the coarse levels efficiently address error that extends across many cells. This makes multigrid particularly effective for pressure and other systems with a strong diffusive component, such as temperature.

Both options apply the same multigrid process but use different precision within the multigrid hierarchy:

mg32 uses 32-bit values. It is generally the faster and less expensive option, so it is the usual starting point.
mg64 uses 64-bit values. It requires more work and memory traffic but can help when the 32-bit hierarchy is sensitive to round-off.

The suffix only describes the multigrid calculation; it does not change the precision of the final result fields.

Incomplete LU: `ilu13`, `ilu15`, `ilu24`, and `ilu55`

Incomplete LU, or ILU, approximates a lower-and-upper triangular factorization of the linear system. It is often effective for advection-dominated equations such as momentum and turbulence.

In iluXY, X is the number of iterations used to approximate the LU factors during setup, and Y is the number of iterations used to apply those factors each time the preconditioner is called. The available options are therefore:

ilu13: 1 setup iteration and 3 application iterations;
ilu15: 1 setup iteration and 5 application iterations;
ilu24: 2 setup iterations and 4 application iterations; and
ilu55: 5 setup iterations and 5 application iterations.

Higher counts spend more work building or applying the approximation and can produce a stronger preconditioner. ilu13 is the least expensive starting point, while ilu55 is the most aggressive and expensive option. The digits are not an ILU fill level: ilu15, for example, does not mean fifteen iterations.

Schwarz: `schwarz2`

schwarz2 divides the mesh into connected 2×2×2 blocks and inverts the cells within each block together. This captures local cell-to-cell coupling more strongly than treating each cell independently, so it can help when neighbouring values are tightly coupled.

The 2 is the block length in each coordinate direction, not an iteration count. In three dimensions, each block contains eight cells. Coupling within a block is handled by its local inverse; coupling between blocks remains for BiCGSTAB to resolve.

Choosing a preconditioner

The standard numerics presets already make equation-specific choices. In general:

multigrid is a strong starting point for pressure and temperature systems with a significant diffusive component;
ILU is often effective for advection-dominated momentum and turbulence systems;
schwarz2 is an alternative when stronger local coupling is useful; and
none is reasonable only when the system is easy enough that preconditioning overhead would dominate.

These are tendencies, not guarantees. Mesh resolution, material-property jumps, advection strength, and boundary conditions all change the matrix. Compare total runtime and the engineering result as well as linear-iteration counts, and prefer a tested preset unless a case gives a clear reason to override one equation.

How ordered fallbacks work

right_preconditioner accepts either one name or a non-empty ordered list. For example:

"numerics": {
  "stable": {
    "linear_solvers": {
      "energy": {
        "right_preconditioner": ["mg32", "mg64", "ilu55"]
      }
    }
  }
}

For a linear system, the solver tries the eligible entries from left to right. It stops at the first one for which every component of that system converges. Reaching the linear-iteration limit, producing a non-finite result, or another unsuccessful BiCGSTAB exit causes the next preconditioner to be tried. A vector momentum solve falls back as a whole if any velocity component is unsuccessful.

The entries are alternatives, not stages that are combined: a successful mg64 attempt does not also apply mg32 or ilu55.

The solver remembers the most recently failed preconditioner separately for each equation. That method is omitted from subsequent solves of the equation while another method continues to succeed. If that other method later fails, the remembered exclusion moves to it and the earlier method becomes eligible again. This avoids repeatedly paying for a method that has just failed while still allowing it to recover as the linear system changes between SIMPLE iterations.

If every eligible entry fails, the final attempt is returned; a fallback list cannot make an invalid or diverging physical setup valid. The *_right_preconditioner columns in iteration_info.csv identify the method whose result was retained. The corresponding *_linear_iterations value describes that final attempt, not the total work spent on earlier failed attempts.

Vanellus Guide