Troubleshooting

The controls are the fields of solver and discretization in the case; on the command line --set solver.max_steps=400. The remedies are listed in the order to try them. They follow from how the iteration works (see the block below); they are not the outcome of a study of failures.

maximum number of steps reached. Look at the residual history first (gyre run prints it; result.json and the job events hold it).

• The residual is still falling and the CFL still growing: the solve needed more steps. Raise solver.max_steps (default 150).
• The CFL stays small or keeps being cut: the start is too far from the solution. Start from a converged neighbour instead (a session or flow.solve() after set_inputs warm-starts from the last converged state), approach the target condition in smaller increments, or lower solver.cfl0 (default 5).
• The Krylov iteration count per step sits at its limit (krylov_dim × restarts, default 40 × 2) and the residual falls slowly: the linear systems are not being solved. Raise solver.krylov_dim, or use solver.smoother: gmres; keep solver.levels: auto. On a wall-resolved mesh (cells much longer than thick at the wall) use solver.smoother: line, which solves exactly along the lines of thin cells (measured on the turbulent flat plate).

residual stalled above tolerance. The residual did not halve in six consecutive steps although the CFL had reached $10^4$. Usual causes: an unsteady or marginally stable flow that has no steady state at this resolution (a wake that wants to shed, a shock that moves between nodes), or linear solves that do not reach lin_tol.

• Check the last entries of the history: linear_reduction well above lin_tol means the linear solver is the limit — raise solver.krylov_dim or solver.restarts.
• A flow with a shock needs discretization.shock_capturing: true; a larger discretization.av_coef (default 1) smooths the shock further at the price of accuracy.
• A coarser tolerance is a decision about the result, not a fix: with tol_rel above the plateau the solve “converges” to the same state. Compare the plateau with the accuracy you need before doing that.

residual is not finite. This reason describes the starting point, not the iteration: the residual of the initial state — the uniform free stream, or the warm-start state evaluated with the new inputs — is nan or inf. The line search never accepts an update with a non-finite residual, so the reason cannot appear after the first step, and no solver control (cfl0, cfl_growth, max_steps) changes it.

• Check the inputs: the Mach number, gamma, and the boundary data in flow.extra must give positive density and pressure.
• Check the mesh: gyre mesh info reports inverted or badly scaled elements (messages and remedies).
• Check the start state: a state restored from a checkpoint or set by hand, or the iterate of a failed solve passed on as a start, may itself be inadmissible.

pseudo-time step collapsed (no admissible update). Every update, at every step length, either produced negative density or pressure, gave a non-finite residual, or failed to reduce the residual, and cutting the pseudo-time step did not help. This is how a transient that leaves the admissible range ends (the scheme does not enforce positivity); if the step limit is reached first, the same cause is reported as maximum number of steps reached.

• Start from a converged neighbouring condition, or lower solver.cfl0 and solver.cfl_growth (default 10) so that the transient is followed more closely.
• Under-resolved strong gradients: enable discretization.shock_capturing, lower the polynomial degree (discretization.order), or refine the mesh where the gradient is.
• In a design loop it usually means the last step in the design variables was too large — the kept state is still the last converged one, so take a smaller step.

Converged, but residual stagnated at round-off floor. Not a failure: the residual reached the conditioning-limited floor before tol_rel. The result is as converged as double precision allows on this mesh; a smaller tol_rel cannot be met.

• The outputs in the result are those of the iterate the failed attempt ended at; they are not a solution.
• The discipline keeps the last converged state and warm-starts the next solve from it. Repeating the same request repeats the same failure.
• Gradients and error estimates are not computed for a failed point: the result record (result.json, a job result) and the summary printed by gyre run list them under skipped, next to the reason the solve ended with; sessions answer 422, and the Python calls raise RuntimeError (Python API, MDO integration).
• Order selection (--target-error) ends at the first degree that does not converge and reports the last degree that did.

Each step solves a linearised pseudo-time problem to the relative tolerance lin_tol and tries the update with step lengths 1, ½, …, down to 1/32. A step length is accepted if the new state has positive density and pressure, a finite residual, and a smaller pseudo-transient residual. After an accepted full step the CFL grows by the factor by which the residual fell, limited to between 1.5 and cfl_growth; after a shortened step it stays (a step shortened to a quarter or less multiplies it by solver.cfl_shrink, which is 1 by default); if no step length is accepted the CFL is divided by ten and the step is repeated. Stagnation is declared after six steps without halving the best residual once the CFL is at least $10^4$. The reference residual is that of the uniform free stream, also for warm starts. See the implicit solver.