Diagnose an instability
Identify the first equation or field that becomes unstable before changing solver settings.
Preserve the evidence
Check the terminal status and completed flag. A diverged run retains a result bundle for diagnosis; an error or killed run does not. Download iteration_info.csv and the submitted request before creating a variant.
Find the first unstable equation
Read or plot these columns around the first sustained residual increase or NaN:
| Columns | What they identify |
|---|---|
residual_x_velocity, residual_y_velocity, residual_z_velocity | Momentum instability |
residual_pressure | Pressure-correction instability |
residual_temperature | Energy instability |
residual_tke, residual_sdr | Turbulence instability |
*_linear_iterations | Work required by the retained inner linear solve |
*_right_preconditioner | Preconditioner retained after any fallback attempts |
A sudden linear-iteration increase before the outer residual grows points toward a poorly conditioned linear system. A change in *_right_preconditioner shows that a fallback was required. Repeated outer-residual oscillation without unusual inner work points more toward relaxation or coupled boundary behavior.
The first NaN not necessarily the root cause: one failed equation can produce erroneous non-NaN values (e.g. a negative TKE) which contaminate equations solved later in the same SIMPLE iteration. Errors rarely appear from nowhere, they almost always build up over several SIMPLE iterations. Start with the earliest sustained change in residuals, linear iterations, monitored fields, or iteration runtime.
Add field diagnostics
If the existing history is insufficient, add minimum and maximum monitors for the suspect field, conservation monitors, and probes near the expected problem region. Run the variant long enough to capture the onset rather than waiting only for the terminal status.
Use temperature extrema and energy balance for an energy failure, pressure or velocity probes and mass balance for a flow failure, and the relevant residuals for turbulence. Monitor histories appear as monitor_* columns in iteration_info.csv.
Choose the next strategy
- If several fields depart together, start with Correct modeling problems and Improve mesh quality.
- If the current preset is not
stable, try Switch numerics presets. - If one outer equation oscillates, use stronger numerical relaxation.
- If its linear iterations spike or a preconditioner fails, use Change preconditioning.
- If the unstable field uses
second_order_upwind, return it to first-order advection. - If temperature is responsible, follow Stabilize the energy solve.
See also
- Residuals and linear-solver convergence explains the outer and inner diagnostics.
- Monitors and derived quantities explains available field and conservation monitors.
- Simulation status and result files explains which failed runs retain results.