Case Design Guide

Table of Contents

• 1. The Order That Matters
• 2. Geometry and Grid
• 3. Boundary Topology
• 4. Scaling and Properties
• 5. Numerical Method
• 6. Stability and Convergence
• 7. Observability
• 8. Outputs and Analysis
• 9. Before The First Expensive Run
• 10. Where This Ends
• 11. Related Documentation

Type ExplanationFor Users building a new caseStatus Decision guidance - not an executable recipe

Building a case from scratch is a different journey from adapting an example, and "read all four YAML references" is not an answer to it. This page walks the decisions in the order they constrain each other, and links out for the exact syntax at each step.

Note

This is decision guidance, not an executable recipe. It does not end with a working case, because the choices below are yours to make. For a path that does end with a running simulation, use Quick Start and then adapt what it produced.

Warning

Adapting a shipped example is almost always cheaper and safer. Start at Example Catalog and only come back here when nothing shipped is close enough to your problem.

1. The Order That Matters

Decisions constrain each other in one direction, so taking them out of order means redoing work:

physical problem
  -> geometry and grid
    -> boundary topology
      -> scaling and properties
        -> numerical method
          -> stability and convergence
            -> observability
              -> outputs and analysis

Geometry constrains which boundaries are possible; boundaries constrain which scalings make sense; scaling constrains which timestep is stable. Choosing a solver before you know your grid is choosing in the dark.

At each step: build the smallest valid configuration first, validate it, and only then add complexity.

2. Geometry and Grid

Minimum viable choice. A programmatically generated box (grid.mode: programmatic_c). It needs no external files and validates fastest.

Alternatives. A file-based curvilinear grid when the geometry is not a box, or grid_gen when you want the shipped generator to build it. See Grid Generator Guide: generators/grid.gen.

Constraints to check now, not later.

• Each axis should remain coarsenable for the multigrid depth you intend — see 2. Multigrid/KSP Stack In Code if the Poisson solve later refuses your level count.
• Periodic directions impose a translation contract on the grid; a grid that is not truly periodic is rejected, not approximated. See 2. Grid Contract.

Syntax. 3. grid.

3. Boundary Topology

Decide the shape of the problem before the numbers: which faces are walls, which admit flow, which are homogeneous.

Choose the type first, then the handler — not every handler is legal for every type. The compatibility matrix and the entries for both are at 2. Boundary Types and 4. Handler Entries.

Common topologies.

Problem	Topology
Through-flow channel or duct	inlet + outlet + wall
Statistically homogeneous, decaying	periodic on the homogeneous axes with geometric
Sustained wall-bounded turbulence	periodic streamwise with a driven handler, wall on the others

The trap. A periodic wall-bounded flow decays under wall friction unless it is driven. If you want sustained turbulence, you need constant_flux or initial_flux, on both faces of the pair.

4. Scaling and Properties

Values in YAML are physical; picurv non-dimensionalizes them before the runtime sees them. Getting this wrong produces plausible-looking wrong answers rather than errors, which makes it the highest-risk step on this page.

• Set the reference scales deliberately; do not inherit them by accident.
• target_flux is a volumetric flux, not a velocity.
• The project-wide scaling conventions are in Non-Dimensionalization Model; 5. Non-Dimensionalization Before C Input covers the boundary-condition specifics.

5. Numerical Method

Minimum viable choice. Dual Time Picard Jameson RK, the default production solver. It tolerates far larger timesteps than the explicit path.

Alternatives and why they exist. Compare against siblings at 3. Momentum Solver Entries before switching. Newton Krylov is the right escalation when pseudo-time stalls; Explicit RK4 currently has no positive-path verification (see Capability Evidence Matrix) and should not be a first choice.

Turbulence model. Use none unless the grid genuinely cannot resolve the flow.

Note

Both LES models are experimental: implemented and unit-tested, but with no validated coefficient magnitude. If you need a subgrid model, prefer dynamic_smagorinsky with averaging.mode: homogeneous wherever the flow has a homogeneous direction, since the local coefficient is noisy and the least-squares closure it comes from assumes an averaging set. Enable diagnostics and read Cs(t) before trusting the result.

6. Stability and Convergence

1. Start with a conservative timestep and loosen it once the case runs.
2. Leave solver tolerances at their defaults for the first successful run. Tuning tolerances before you have a baseline means you cannot tell what your change did.
3. Run a handful of steps and confirm convergence behavior before committing to a long run. 2. The Solver Does Not Converge covers what to look at.

7. Observability

Configure this before the first expensive run, not after it fails:

• Logging cadence frequent enough to see divergence early, sparse enough not to dominate runtime.
• Checkpoint cadence that lets you restart without losing meaningful work.
• Field statistics if you need averages — starting them late costs a rerun. See Field Statistics.

Syntax. 2. io.

8. Outputs and Analysis

Decide what you will actually compute from the run, because it determines what must be written. Configuration Reference: Postprocessor YAML covers the pipelines; Tutorial: A Guide to Visualizing Your Results covers getting pictures out.

9. Before The First Expensive Run

• [ ] picurv validate passes on all four roles.
• [ ] --dry-run output shows the artifacts and commands you expect.
• [ ] The case ran for a few steps locally and converged.
• [ ] Boundary handlers in the startup banner are the ones you intended.
• [ ] Units checked against 5. Non-Dimensionalization Before C Input.
• [ ] Output cadence will not exhaust your storage quota.
• [ ] Checkpoint cadence lets you resume without losing meaningful work.
• [ ] You know which capabilities you are relying on that are unverified (Capability Evidence Matrix).

10. Where This Ends

You finish this page with decisions, not with a case. To turn them into one:

1. ./bin/picurv init <closest example> --dest my_case — start from the nearest shipped case rather than an empty file.
2. Apply your decisions one at a time, running picurv validate between each.
3. Work through the checklist in section 9.
4. Run a few steps locally before committing to anything expensive.

11. Related Documentation

• Workflow Recipes and Config Cookbook — recombining profiles
• Run Artifact Lifecycle Contract — running, restarting, archiving
• Troubleshooting by Symptom — when it does not work