Courant

Physics acceptance testing for machine-produced simulation.

Courant is a read-only, deterministic gate between a simulation (an AI agent's or an engineer's) and the person who signs it. Without a task specification it decides whether an OpenFOAM run is valid. With the task the run was asked to solve, it decides whether the run is the problem that was asked.

Every verdict is accept, reject or insufficient, and every reason cites the file it read, the method, the threshold and the value. Deterministic code decides every verdict; no language model is in the verdict's path. Courant never edits a case, never runs a solver, and its checks never use the network.

courant.dev · Results · Getting started · PyPI: courant-dev · Releases

Two real OpenFOAM v2406 runs of the pitzDaily tutorial, from certification/corpus/. Run A is the tutorial as shipped. Run B is the same case with its pressure solver's tolerance loosened from 1e-06 to 0.01. The solver ends both with End, exit 0. Their residuals are read by the parser the verdict uses, and the verdicts are courant verify --json on the same two files: A is accepted (rule VER-5.6); B is rejected (rule VER-5.4), first reason residual.not_converged.

What it catches

Every figure is drawn from real solver output and Courant's own verdicts, and its numbers are the published ones, under Benchmarks and in RESULTS.md. Click one to see it full size.

Install

pip install 'courant-dev[mcp]'      # Python 3.11 or later; the command is `courant`

The distribution is named courant-dev (PyPI's courant is an unrelated project); the import package and the commands are courant and courant-mcp.

A single-file binary for Linux and macOS, which needs no Python, is attached to every release, with SHA256SUMS and its Ed25519 signature:

curl -fsSL https://github.com/courantdev/courant/releases/latest/download/install.sh | sh

The installer checks the binary's SHA-256 against the release's SHA256SUMS, and the signature of SHA256SUMS against the release key it carries when python3 with the cryptography package or OpenSSL 3 is on the machine. With neither, it says that only the checksum was checked and how to check the signature by hand; COURANT_REQUIRE_SIGNATURE=1 makes it refuse instead. courant update installs nothing unless the signature verifies against the key built into the binary.

Try it offline

These run on the real OpenFOAM runs that ship inside the package, with no network:

courant demo                     # four real runs and an HTML report
courant verify --about           # the error rates published for this version

What a verdict looks like

courant demo --keep DIR writes the demo's runs to a folder you keep. One of them is the icoFoam cavity with a timestep ten times too large:

courant demo --keep ./demo
courant verify demo/icoFoam_cavity__cfl_blowup/icoFoam_cavity__cfl_blowup.log.gz --case-json demo/icoFoam_cavity__cfl_blowup/icoFoam_cavity__cfl_blowup.case.json   # exit 2

$ courant verify demo/icoFoam_cavity__cfl_blowup/icoFoam_cavity__cfl_blowup.log.gz --case-json demo/icoFoam_cavity__cfl_blowup/icoFoam_cavity__cfl_blowup.case.json
VERDICT   reject   (rule VER-5.3)
BASIS     validity
GRADE     C
RUN       icoFoam_cavity::cfl_blowup · icoFoam

WHY
  1  cfl.max — Courant number exceeds stability limit: max Co=9.66 at t=0.15 exceeds limit 1.0; still 8.92 over the final fifth of the run
     read    icoFoam_cavity__cfl_blowup.log.gz (t = 0.15)
     method  checker cfl
     value   9.66086   threshold 1.0
  2  convergence.residual — transient solve judged on stability rather than a residual threshold — Courant number settled at 8.92, above the stability limit of 1 — a transient solve that does not respect its timestep criterion is not converged, whatever the residuals say (final worst residual 3.61e-01)
     read    icoFoam_cavity__cfl_blowup.log.gz
     method  check convergence.residual (Residuals converged below tolerance)
     value   0.361172   threshold —
  3  cfl.climbing — Courant number climbing on a fixed timestep: Co rose 0 -> 9.66; icoFoam has no adaptive timestep
     read    icoFoam_cavity__cfl_blowup.log.gz
     method  checker cfl
     value   0.0   threshold 1.0

PROBABLE CAUSES
  1  NUM.CFL_VIOLATION — Courant number too high
  2  NUM.MISSING_ADJUSTABLE_DT — Fixed dt without adjustableRunTime

NOT CHECKED
  - Solution fields were not read: no time directory with fields was found.
  - Discretisation error was not quantified: a single mesh was supplied.
  - Accuracy against a reference was not assessed: no reference data was supplied.
  - Field values physically plausible: no internal fields
  - Flow regime matches turbulence modeling: not implemented (Courant derives no length scale for a Reynolds number from the case)
  - Near-wall y+ compatible with wall treatment: not implemented (Courant reads no y+, neither a yPlus field nor the yPlus function object's output)
  - Net boundary mass flux ~ 0: no field flux data
  - No specification given: conformance to the task was not assessed.

NEXT  Suggested, not applied: Reduce deltaT in controlDict

This is the beginning of the README. Read the rest at the original. Read the full README ↗