Capabilities Summary

Table of Contents

• 1. Input and Grid Capabilities
• 2. Physics and Model Selection
  • 2.1 Turbulence Models
• 3. Numerical Solver Stack
• 4. Boundary and Runtime Controls
• 5. Post-Processing and Statistics
• 6. Cluster and Study Orchestration
• 7. Workspace, Assets, and Data Lifecycle
• 8. Run Inspection and Plotting
• 9. Extensibility Status
• 10. Suggested Reading Order

Type ReferenceFor All readersStatus Capability statuses enforced by make audit-capability

This page summarizes current capabilities from YAML + picurv without editing C source. It is organized by workflow stage rather than just a feature bullet list.

1. Input and Grid Capabilities

PICurv currently supports three grid ingestion modes:

• programmatic_c: C-side structured grid generation,
• file: external .picgrid read path with scaling/validation,
• grid_gen: pre-run Python generator orchestration.

grid_gen offers two composed geometries rather than a list of named shapes: box, a Cartesian block whose bounding walls are piecewise height fields, and sweep, a cross-section carried along a piecewise centreline. Both accept an ordered placement and similarity transform list. Both are supported: every feature closes a uniform flow in the solver's metrics, and a solve on a swept circle converges at second order. See Grid Generator Guide: generators/grid.gen.

Domain controls include:

• models.physics.dimensionality: 2D, which holds the i velocity component fixed on an unchanged 3-D grid,
• per-direction geometric periodicity for Eulerian fields, derived from paired BCs and requiring matching surfaces under a constant translation,
• optional DMDA partition hints (da_processors_x/y/z).

2. Physics and Model Selection

Supported high-level operation modes:

• solve from numerically evolved Eulerian fields,
• load/restart from prior field outputs,
• analytical Eulerian field modes (TGV3D, ZERO_FLOW, UNIFORM_FLOW).
• file-grid analytical support for the non-custom analytical modes (ZERO_FLOW, UNIFORM_FLOW).

Particle controls include:

• particle count,
• initialization modes (Surface, Volume, PointSource, SurfaceEdges),
• restart modes (init, load),
• grid-to-particle interpolation method (Trilinear direct cell-center or CornerAveraged legacy),
• scalar micromixing update path (IEM-style Psi model).

Particle positions are not currently wrapped across periodic boundaries.

2.1 Turbulence Models

Four LES closures are selectable. constant_smagorinsky applies a prescribed coefficient and allocates no coefficient field. dynamic_smagorinsky measures the coefficient each update through the Germano identity and Lilly's least-squares contraction, with selectable grid filter width, test-filter kernel and width ratio, coefficient averaging set, and limiting policy. vreman and wale need no coefficient field, test filter or averaging and vanish in pure shear; vreman resolves each grid direction by the cell's own spacing. Entries and full detail at 5. LES Subgrid Models; the formulation is derived in LES Turbulence Closure.

Note

All four models are supported. On the AGARD HOM02 benchmark, started from a DNS field, every one removes the energy pile-up an unmodelled run builds at the grid cutoff, and the dynamic coefficient settles at 0.18-0.19; none keeps the resolved energy decay within 10% of the DNS during start-up (10. Status and Evidence). The dynamic model with homogeneous averaging and the Werner wall model reproduces Lee & Moser's Re_tau = 1000 channel within criteria fixed beforehand. The geometric_mean width is supported on orthogonal cells, where it reproduces cube_root_volume. The simpson_ik test filter is supported for planes homogeneous in xi and zeta, after a fix to its dynamic-procedure weighting.

There is no RANS closure. A k_omega selector existed until 2026-09-22, but nothing behind it was ever implemented, so it was removed and the subsystem returned to planned; models.physics.turbulence.rans is now refused at validation (6a. RANS Closures). Wall functions are configured separately from the LES closure, and offer three laws - log_law, werner, and cabot; log_law and werner are supported on that channel validation, and cabot is experimental: on the same channel its pressure-gradient term put the friction velocity 22% low. The correction is applied inside the momentum solve and again before the LES strain rates are formed, so a wall-modelled large-eddy simulation is coupled in both directions, and the modelled stress reaches the momentum equation through an effective eddy viscosity installed at the wall face.

Note

A wall model is not independent of the turbulence model in the way its configuration placement suggests. It supplies the stress of a layer the mesh does not resolve, which is only meaningful if the unresolved motions are modelled somewhere, so a wall model with LES disabled is rejected - there is no implicit-LES scheme here to stand in - and a wall model on a laminar case is rejected outright. Whether the first cell falls in the selected law's valid range depends on the mesh and is checked at runtime instead.

3. Numerical Solver Stack

Momentum:

• named momentum strategy selection,
• active implementations: Explicit RK4, Dual Time Picard Jameson RK, and Newton Krylov (see 3. Momentum Solver Entries for the comparison and status of each),
• tunable tolerances and pseudo-CFL controls (Picard-Jameson only).

Note

Explicit RK4 and Dual Time Picard Jameson RK are supported, with measured orders at 3. Momentum Solver Entries. Newton Krylov is supported within its documented scope, with a 144-rank channel campaign using no preconditioner; its quantitative DNS discrepancy is recorded at 10.2 Retained turbulent-channel campaign (2026-09-29). The frozen-Jacobian preconditioner is supported on a three-grid laminar curved-duct campaign (10.1 Retained laminar curved-duct campaign (2026-10-07)), with no performance claim. Dual Time Picard Jameson RK is the production default.

Pressure:

• multigrid Poisson workflow with an fgmres or cg outer method,
• level/sweep/semi-coarsening controls,
• PETSc passthrough flags for advanced tuning.

See method details in Methods and Models Overview.

4. Boundary and Runtime Controls

Boundary capabilities include validated type-handler pairings across inlet/outlet/wall/periodic classes. Runtime controls include:

• fixed run-owned output, restart-input, log, and analysis homes,
• function-level logging allowlists,
• profiling critical function lists,
• monitor verbosity and cadence controls,
• online field-statistics windows accumulated during the solve, checkpointed with the flow state and resumed on continuation.

5. Post-Processing and Statistics

Pipeline capabilities include:

• Eulerian transforms (dimensionalization, nodal averaging, Q-criterion, normalization),
• Lagrangian particle tasks,
• particle statistics reduction pipeline (currently MSD family),
• derived Eulerian field statistics: Reynolds stresses, RMS, turbulent kinetic energy, and turbulent fluxes from windows the solver accumulated online,
• output field selection from checkpoint payloads (input extensions are fixed to dat),
• optional physical-time PVD collections spanning compatible restart ancestry, controlled by post.yml -> io.paraview_series; see Physical-Time ParaView Collections (post.pipeline) for the direct tests and unverified scenarios.

6. Cluster and Study Orchestration

Single-run cluster flow (run --cluster ...):

• scheduler script generation,
• optional submission,
• solver/post dependency chaining,
• run manifests.

Study flow (sweep):

• parameter matrix expansion,
• array script generation,
• metric aggregation and optional plots,
• study manifest and reproducible directory structure.

7. Workspace, Assets, and Data Lifecycle

picurv init creates a workspace whose editable configuration, imported inputs, reusable assets, runs, and studies each have a fixed home. Run-owned directory names are part of that contract rather than a monitor setting; the topology and the guards that hold it are in 4. Artifact Topology.

External files enter a workspace explicitly. picurv inputs import <kind> <source> records a checksum and an ownership mode, and reference mode registers a path without copying it, so an unavailable external target fails loudly instead of silently. Entries at 12.1 Workspace Input Import Mode Entries.

picurv precompute resolves the grid, initial-condition, and inlet-profile provider graph and publishes each result as an immutable content-addressed object in the workspace asset store. Identity covers the normalized provider settings, the checksums of referenced files, and the PICurv build, so an unchanged input reuses its object and any change selects a new one. Runs materialize what they need by reflink, hardlink, or copy and record the mapping. --require-precomputed refuses to build a missing object instead of quietly rebuilding it; --fetch-missing looks in configured storage first. A provider that only exists inside the simulator is reported rather than imitated.

Branching a run with --restart-from carries the checkpoint's physical fields but starts field-statistics accumulators empty unless --statistics-state carry asks for the saved window state. Entries at 8.6 Restart Statistics State Entries.

picurv storage moves finished runs, studies, and study members through an rclone remote. protect uploads and verifies while keeping every local file; offload does the same and then prunes the verified payload according to an offload policy that chooses what stays local, with --retain/--drop adjusting that preset one component at a time. Compression policy entries are at 9.1 Compression Policy Entries, offload policy entries at 9.2 Offload Policy Entries, and retention component entries at 9.3 Retention Component Entries. Cold data is marked, so continuation, post-processing, submission, and study reaggregation refuse it with the restore command rather than mistaking pruned output for output that was never produced.

picurv version, picurv versions, and picurv source report and select the release and build identity that runs, checkpoints, and archives are stamped with. picurv version status additionally validates that the conductor, both executables, and any workspace version requirement agree, and exits non-zero when they do not.

8. Run Inspection and Plotting

picurv summarize supports:

• curated run, case, solver, and monitor configuration dashboards,
• selected-step health summaries from continuity, particles, momentum, Poisson, profiling, memory, and convergence logs,
• discovery of available plottable numeric histories with --list-plot-series,
• full or last-N append-order time-history plots with --plot and --last,
• per-block and per-function lines, automatic positive residual/norm log scaling, explicit saves, and headless fallback.

PICurv owns run/log interpretation; standalone generators/plot.gen renders versioned normalized JSON requests without knowing run-directory layouts.

9. Extensibility Status

Current extension pathways are documented and active for:

• YAML contract extension,
• ingestion mapping updates,
• workflow orchestration growth,
• method-level and model-level solver extension.

Reference pages:

• Configuration Contract (YAML -> Generated Artifacts -> Runtime)
• Developer Ingestion Map
• Configuration Extension Playbook

10. Suggested Reading Order

1. Code Architecture
2. Methods and Models Overview
3. Momentum Solver Implementations
4. Particle Model and Coupling Overview