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	Dynamic model characterized on HOM02 — see below
`turbulent_channel`	Benchmark	Seeded wall-resolved channel startup at nominal `Re_tau ~ 180`	Experimental seed; developed turbulence not validated — 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: 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.analysis.metrics>/les_coefficient.csv. Its random k4_exponential seed is not a reference flow. The model itself was characterized on the AGARD HOM02 benchmark, started from Wray's DNS field (hom02-les-execution-2026-10-09): at 64^3 Cs settles at 0.19 and the cutoff pile-up is removed, while the resolved energy decay runs up to 18% from the DNS during start-up (hom02-les-accuracy-2026-10-09, not met). See 10. Status and Evidence.

turbulent_channel now uses channel_spectral_velocity for a seeded perturbation about a bulk-normalized parabolic mean, with LES and wall functions disabled. Its 128 x 128 x 256 cell grid spans 2*pi x 2 x 4*pi and clusters toward both walls. Nominal Re_tau ~ 180 guides the spacing; achieved wall stress determines the actual friction Reynolds number. The example includes physical plane spectra of the seed and checkpoint fields. See its README and p33_cap_gen_channel_spectral_velocity.

Warning: This is a candidate DNS startup, not a validated turbulent benchmark. A finite perturbation does not guarantee sustained transition. Establish stationary wall stress, velocity fluctuations and Reynolds shear stress before collecting statistics, then assess resolution and sampling uncertainty against a matching channel reference. Long campaigns require a measured pilot and cluster resources.

The pseudo-time stall once recorded for these periodic wall-bounded cases was re-characterized on 2026-09-18 and does not reproduce; the laminar channel reproduces its exact parabola at second order (5.7 Known limitations). Use the periodic boundary handlers documented at geometric and the driven handlers. periodic_test/driven_channel/les_wallmodel_retau1000 is the wall-modelled LES reference case: with the Werner wall model it reproduces Lee & Moser's Re_tau = 1000 channel within the criteria of wmles-channel-retau1000-werner-2026-10-09 (friction velocity 2.9% high, bulk-unit mean velocity 1.1% RMS).

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