Validation
Benchmarks with numbers, against published answers somebody else produced.
This section is not marketing. In CAE the question “how do you know it is right” arrives before the second meeting, and the only acceptable answer is a page with a table on it that the reader can reproduce.
A benchmark earns a page here only if it has a published reference, so that agreeing with it means something. Agreeing with ourselves does not.
| Benchmark | Reference | Checks | State |
|---|---|---|---|
| Lid-driven cavity, Re = 100 | Ghia, Ghia & Shin (1982), Table I | Incompressible laminar, pressure–velocity coupling, wall conditions, 2-D | Written up — comparison table complete, citable |
| Backward-facing step | Armaly et al. (1983) | Separation and reattachment length | Skeleton — reference and set-up recorded, our results not. Not citable |
| Flow over a cylinder | Roshko (1954); Williamson (1988, 1989, 1996) | Vortex shedding, Strouhal number | Skeleton — reference and set-up recorded, our results not. Not citable |
| Turbulent channel | Moser, Kim & Mansour (1999) | Wall functions, near-wall treatment | Skeleton, reference column filled — the DNS data is bundled with OpenFOAM and has been transcribed. Only our results are missing. Not citable |
| NACA 0012 aerofoil | Abbott & von Doenhoff; NASA TMR | Lift and drag, turbulence models | Named |
| Dam break | Martin & Moyce (1952) | Free surface, VoF | Named |
| Buoyant cavity | de Vahl Davis (1983) | Natural convection, Nusselt number | Named |
| Ahmed body | Ahmed et al. (1984) | External aerodynamics, separated wake | Named |
Three states, and they are not degrees of the same thing:
- Written up — the comparison table is complete. Cite it.
- Skeleton — the page exists, the published reference and the set-up are on it, and every cell that needs a result of ours says so. Nothing on a skeleton page may be cited. The banner at the top of each says this too.
- Named — a line in this table and nothing else.
Written up versus run
Section titled “Written up versus run”These are not the same thing and the difference is worth stating plainly.
More has been run in development than has been written up. An undocumented run is not a citable result — it cannot be reproduced by a reader, defended in a review, or handed to somebody who asks. That is why this table says “named” rather than claiming coverage.
Writing up even three of the runs already done would change what the product can honestly claim, and it is documentation work rather than simulation work. It is the highest-value item in this entire manual.
The three skeletons exist to make that writing-up fast. Everything on them that does not require a run is already there: the full citation, what the benchmark tests, which analysis type and solver in the product would run it, the geometry and Reynolds-number definitions the reference used, and the comparison table with its station rows laid out. What remains is transcribing numbers.
Why these three
Section titled “Why these three”The cavity checks incompressible laminar flow, the pressure–velocity coupling, wall conditions and 2-D handling. It is a genuine result and it is a narrow one. Three things it cannot say anything about account for most of what a customer’s work actually depends on:
| Untested behaviour | The benchmark that tests it | Why the cavity cannot |
|---|---|---|
| Separation and reattachment | Backward-facing step | The cavity’s recirculation is put there by the geometry. Nothing asks the solver to find where a shear layer detaches or lands |
| Unsteady, periodic flow | Flow over a cylinder | The cavity is transient only as a route to a steady answer. There is no frequency in it to get right |
| Near-wall turbulence treatment | Turbulent channel | icoFoam has no turbulence model at all. Every RANS model, and every wall function, is untouched |
Between them they exercise the largest span of what is currently unchecked, and they do it with the least overlap: a steady separated flow, a time-accurate unsteady one, and a fully turbulent wall-bounded one with a DNS to compare against. The remaining named benchmarks are each valuable, but each adds one physics module — free surface, buoyancy, an aerofoil polar — rather than a whole class of behaviour.
They also happen to be cheap. The channel needs no geometry at all; the cavity route shows that a benchmark which only agrees when it is expensive is not much of a reassurance.
Format
Section titled “Format”Follow _TEMPLATE.md, which is derived from
the cavity page — the one that already gets this
right: the set-up in full, the comparison table station by station, what the
remaining difference is attributable to, and — importantly — what the
benchmark does not cover. The cavity checks four things and says so.
The integrity rule
Section titled “The integrity rule”No number in this section may be written by anyone who has not read it off a run or off a published source. Not estimated, not interpolated, not reasonably assumed, not carried over from another code’s write-up.
A fabricated validation figure is the most damaging thing that could be put in this repository. Every other kind of documentation error wastes somebody’s afternoon; this one leads an engineer to trust a result that was never checked.
Two placeholder markers make the gaps searchable. Keep them exact:
| Marker | Meaning |
|---|---|
_(to be filled from run)_ |
Our number. It stays until somebody reads it off a run |
_(read from <source>)_ |
A published number that exists but has not been transcribed. Transcribe it from the named table or figure — not from memory, not from a secondary source |
A page containing either marker keeps its “not yet written up” banner.
Where the cavity write-up lives
Section titled “Where the cavity write-up lives”The canonical version is 01-lid-driven-cavity.md. docs/validation.md is the original and is kept, with a pointer at the top; it is no longer the version to edit.