1. How to Read This Catalog

Kind says what the example is for:

Tutorial — meant to be followed end to end while learning. Cheap, robust, and documented step by step.
Verification — isolates one mechanism and checks it against an exact or analytic answer. Small and fast; a failure means the code is wrong, not that the physics is hard.
Benchmark — reproduces a published or in-tree reference result.
Characterization — instruments behavior to produce measurements rather than to pass or fail.

Evidence uses the facet vocabulary from Capability Status Vocabulary.

Cost is deliberately blank where it has not been measured on stated hardware. An unmeasured cost is recorded as unknown rather than estimated, because a wrong runtime estimate is worse than none when someone is sizing a cluster request.

2. Start Here

Example	Kind	Demonstrates	Execution	Cost
`flat_channel`	Tutorial	Laminar channel on a programmatically generated grid; the canonical first run	serial / MPI	not yet measured
`bent_channel`	Tutorial	The same workflow driven by a file-based curvilinear grid	serial / MPI	not yet measured

flat_channel is the case Quick Start walks you through. Run it before anything else on this page.

3. Particle Verification Family

These isolate one term of the particle update each, which is why they are the right place to look when particle behavior is suspect: each failure points at one mechanism.

Example	Kind	Isolates	Evidence
`drift_uniform_flow`	Verification	Deterministic advection by interpolated velocity	Designed for analytical comparison; threshold not gated
`drift_diffusivity_gradient`	Verification	The `grad D * dt` drift term	Designed for analytical comparison; threshold not gated
`brownian_motion`	Verification	The stochastic displacement, against a diffusion solution	Designed for analytical comparison; threshold not gated
`interpolation_test`	Verification	Grid-to-particle interpolation accuracy	Designed for analytical comparison; threshold not gated
`scatter_verification`	Verification	The particle-to-grid scatter path	Designed for analytical comparison; threshold not gated
`search_robustness`	Characterization	Walking-search and migration behavior under stress	Benchmark characterized

Together these address every term in the displacement equation documented at Particle Model and Coupling Overview.

Note: These cases are designed to compare against exact or analytic answers, but a numerical acceptance threshold has not been run and gated as part of the current documentation work. That is why Capability Evidence Matrix records no analytical facet for them: design intent is not evidence.

4. Flow and Turbulence

Example	Kind	Demonstrates	Status
`decaying_isotropic_turbulence`	Benchmark	LES decay in a triply periodic box, 64³ cells	Selects an experimental model — see below
`turbulent_channel`	Benchmark	Wall-modelled LES of a driven channel at `Re_tau ~ 1000`	Plumbing verified; ships a laminar IC — see below
`periodic_test/driven_channel`	Benchmark	Driven periodic channel; DNS and LES variants	See caveat below
`periodic_test/driven_duct`	Benchmark	Square duct with secondary flow of the second kind	See caveat below

Note: The shipped LES configuration is experimental. decaying_isotropic_turbulence selects model: dynamic_smagorinsky with averaging.mode: homogeneous, which on a triply periodic box gives one coefficient for the whole domain and writes Cs(t) to <run.runtime_logs>/les_coefficient.csv. The formulation is unit-tested but the coefficient magnitude has not been validated: this case is the run that would settle it, and Cs(t) is expected to settle near 0.16-0.17. Until that is recorded, treat the magnitude as uncharacterized.

turbulent_channel is the wall-model counterpart to the case above it. Where decaying_isotropic_turbulence exercises the subgrid closure in a flow with no wall, this one exercises the wall model, its three laws, and coefficient averaging over the two homogeneous axes of a wall-normal-inhomogeneous flow. Its uniform wall-normal grid puts the first cell at y+ ~ 51, which is where a wall model belongs and why the same mesh cannot be reused with the wall model switched off. It is distinct from periodic_test/driven_channel/les_retau180, which is wall-resolved constant-Smagorinsky at a Reynolds number forty times lower.

Warning: turbulent_channel ships the laminar Poiseuille profile that carries its target flux, and will not become turbulent from it - nothing in a well-behaved implicit solve makes a one-dimensional laminar channel three-dimensional. A perturbed field is needed, and no generator in this repository produces one for a wall-bounded domain: generators/ic.gen projects onto a solenoidal field by a spectral method that assumes periodicity in all three directions. What the case is verified as is a configuration and plumbing exercise; treat statistics gathered from the shipped initial condition as laminar. Its literature anchors - the log law, Dean's correlation, and Lee & Moser (2015) at Re_tau = 1000 - are what it is built to be compared against, not comparisons that have been run.; The periodic_test campaigns carry an open status: pseudo-time momentum convergence on periodic wall-bounded flow was observed to stall on 2026-08-24 and requires re-characterization at current HEAD after the convergence-criterion change. Read 5.7 Known limitations before planning a campaign around them. Use the periodic boundary handlers documented at geometric and the driven handlers; note the LES caveat above applies to their LES variants.

5. Using an Example as a Starting Point

The intended workflow is to copy and adapt rather than author from scratch:

./bin/picurv init flat_channel --dest my_case

Then change one thing at a time, re-validating between changes. Workflow Recipes and Config Cookbook covers profile recombination, and examples/master_template documents every available key with commentary — it is a reference, not a runnable case.

6. Related Documentation

Quick Start — the guided first run
Testing and Validation Guide — which examples CI exercises
Capability Status Vocabulary — what the evidence words mean