Of Doctor

---
name: of-doctor
description: Diagnose and fix failing OpenFOAM v2412 runs - crashes (FOAM FATAL), divergence, bounding spam, MPI/decomposition errors, mesh-quality failures. Use when an OpenFOAM solver run fails, diverges, produces nan, or a case errors out, e.g. "my simpleFoam run diverged", "icoFoam crashed", "why does checkMesh fail". Input: case path (and optionally a specific log file). Produces root-cause diagnosis + minimal fix + optional rerun. If a custom-solver-specific diagnosis command exists for your project, prefer it for that solver.
---

# of-doctor: OpenFOAM failure diagnosis

If of-sim is not already loaded, Read the sibling skill's SKILL.md -
skills/of-sim/SKILL.md in this suite - section 0 (Environment + invocation), and
references/environment.md (generated by /of-setup) BEFORE the first command.
Mode A (Windows host + WSL) canonical invocation:
`MSYS_NO_PATHCONV=1 wsl.exe -d <distro> --exec bash <scripts>/<script>.sh <args>`
Mode B (native Linux): `bash <scripts>/<script>.sh <args>`
`<scripts>` = this suite's skills/of-sim/scripts/ dir.

## Procedure

1. **Collect evidence** (do all, cheap):
   - `ofmon.sh errors <case>` -> FATAL block if any
   - `ofmon.sh status <case>` + `ofmon.sh residuals <case>` -> verdict, residual history
   - `ofcase.sh info <case>` -> application, times, patches
   - If mesh suspect: `ofrun.sh run <case> checkMesh` (add `-allTopology -allGeometry` for detail)
2. **Classify** against the taxonomy below (first match wins; check FATAL text verbatim).
3. **Report** root cause in one sentence + the minimal fix; show the exact dict diff.
4. **Apply** the fix (foamDictionary via `ofcase.sh set`, or Write full file), rerun the
   failing step, confirm with `ofmon.sh status`. If user only asked "why" - diagnose, don't fix.
5. Two failed fix attempts -> step back, re-derive from physics (wrong solver? wrong BC
   system?), present analysis instead of thrashing.

Crash signature set (what counts as FATAL): `FOAM FATAL`, `sigFpe::sigHandler`,
`error::printStack`. The startup banner `trapFpe: Floating point exception trapping
enabled (FOAM_SIGFPE)` is NOT a crash - never match on generic "Floating point".

## Failure taxonomy

| signature (in log) | root cause | fix |
|---|---|---|
| `FOAM FATAL IO ERROR` + `keyword ... is undefined` / `Entry '...' not found` | missing dict entry (often a div scheme `div(phi,X)` or solver entry for a new field) | add the named entry; for schemes copy nearest analog from numerics.md preset |
| `cannot find file` ending in `0/<field>` | template/solver field mismatch (e.g. switched turbulence model: needs omega not epsilon) | create the missing 0/ field per case-anatomy.md tables |
| `different dimensions` / `dimensions ... [..]` mismatch | wrong `dimensions` in a 0/ field or property (classic: incompressible p must be m2/s2) | correct dimensions per table |
| `Unable to set reference cell for field p` | closed domain, no pressure BC fixes level | add `pRefCell 0; pRefValue 0;` to SIMPLE/PISO/PIMPLE block |
| `Continuity error cannot be removed by adjusting the outflow` | no outlet can balance inflow (BC combination wrong, or inletOutlet everywhere) | ensure one pressure-fixed or zeroGradient outflow path; check patch areas/values |
| `Maximum number of iterations exceeded` (thermo) | thermodynamics out of bounds (T<=0 or huge) from bad init/BC | fix initial T/p values; lower relaxation on h/e equation; check g + p_rgh consistency |
| Courant number explodes over steps | dt too large / velocity spike from BC or bad cell | adjustTimeStep + maxCo 0.5, or halve deltaT; if localized -> checkMesh worst cells |
| deltaT collapses while local Co explodes (moving-mesh case, near the first revolution) | impulsive rotor start: full omega at t=0 | ramp omega via Function1 table (~1 s / half rev) + rotating-machinery preset in of-sim numerics.md (PIMPLE relax, maxCo 2, maxDeltaT 1-2 deg/step) |
| run completes rc=0 but final residuals high (e.g. p ~0.5) or Courant far above intent | degraded-but-completed: COMPLETED_ENDTIME verdict alone cannot catch quality loss | judge via of-sim P5 gates (final residual level, continuity, QoI stability); fix cause (dt/relaxation), rerun |
| residuals nan/inf immediately (iter 1-2) | inconsistent BCs (e.g. fixedValue p everywhere + fixedValue U inlet), or zero density/nu, or garbage internalField | re-derive BC set from case-anatomy.md tables; verify transport/thermo values |
| residuals stall high (1e-1..1e-2, steady) | mesh too coarse / wrong relaxation / unsteadiness at heart (vortex shedding) | SIMPLEC+0.9 or classic 0.3/0.7; if physical unsteadiness -> switch to pimpleFoam |
| `bounding k`/`bounding epsilon`/`bounding omega` spam persisting | bad turbulence inflow values (orders off) or mesh quality | recompute k/omega/epsilon (formulas in case-anatomy.md); upwind turbulence divs |
| `--> FOAM FATAL ERROR` + `request for volScalarField ... from objectRegistry` | solver expects a model/field the case lacks (e.g. radiation, fvOptions reference) | enable/disable the corresponding model dict consistently |
| MPI abort / `processor directories ... do not match` / `Case is already decomposed ... use the -force option` | stale processor* dirs vs decomposeParDict | `rm -rf processor*`, redo decomposePar with current dict (shortcut: `decomposePar -force`) |
| solver restarts at Time=0 after a completed parallel run, or reconstructPar prints `No times selected` | latest time exists only in processor*/ | `reconstructPar -latestTime` before any serial step, or keep the rerun parallel |
| checkMesh: non-orthogonality > 75 / skewness > 4 / negative volumes | mesh defect | regenerate mesh (grading, snap settings); interim: limited 0.33 laplacian + nonOrthoCorrectors 2 (NOT for negative volumes - always remesh) |
| `Cannot find locationInMesh` / `... is not inside the mesh` | locationInMesh outside the background mesh or inside the solid | move locationInMesh to a point certainly in the fluid and inside the blockMesh box (meshing.md route 3), re-run snappy |
| `Wrong number of arguments` / usage print | bad CLI invocation | fix command line (check -help) |
| solver not found (`command not found`) | environment not sourced (raw call outside wrappers) | always use ofrun.sh |
| `sigFpe::sigHandler` / `error::printStack` stack frames, NO `FOAM FATAL` text | numerical blow-up (divide-by-zero from collapsed dt, zero denominator, bad cells) | read the top `#N` frames for the failing operator, then follow the divergence deep-dive (residuals.csv + ladder), not this table |

## Divergence deep-dive (no FATAL, verdict DIVERGED)

Read `<case>/residuals.csv`: which field rises first?
- p first -> pressure-velocity coupling: relaxation ladder, nNonOrthogonalCorrectors,
  GAMG -> PCG fallback for diagnosis.
- U first -> convection: upwind div(phi,U), check inflow magnitude/direction.
- k/omega first -> inflow estimates, wall functions vs y+ (run yPlus), bounding messages.
Then apply of-sim numerics.md "remediation ladder" one step at a time, rerunning a SHORT
horizon (e.g. 50 iterations / 10 timesteps: temporarily set endTime) to test cheaply.

## Mesh-failure quick visual
`ofrun.sh run <case> foamToVTK -constant` then tell the user the VTK
path (mode A Windows view: \\wsl.localhost\<distro>\...) to inspect in ParaView; or
`checkMesh -writeFields '(nonOrthoAngle skewness)'` and threshold in ParaView.

## After the session
Diagnosed a signature not in the taxonomy? Add the row above before closing
(skill retrospective - see of-sim P8).