1. Core Workflow Idea

PICurv is designed around modular config roles:

case.yml: physics, grid, BCs, run duration
solver.yml: numerical strategy
monitor.yml: logging, output cadence, directories
post.yml: analysis recipe
optional cluster.yml: scheduler policy
optional study.yml: parameter sweep definition

The intended UX is:

keep each file focused on one concern,
reuse stable profiles across many runs,
only clone and specialize the roles that actually changed.

2. Common Mix-and-Match Patterns

Pattern A: same case, different monitoring

keep one trusted case.yml
pair it with a lightweight monitor.yml for fast iteration
switch to a richer monitor.yml for production output

Pattern B: same case, different analysis

run once with a standard monitor profile
post-process the same run directory multiple times with different post.yml recipes

Pattern C: same solver profile reused across many cases

keep one validated solver.yml for a known momentum strategy
pair it with multiple physical cases as long as the strategy is appropriate

Pattern D: same cluster profile across many jobs

reuse one cluster.yml for site policy
vary only case/solver/monitor/post inputs

3. Command Recipes

First-time local workflow:

python3 scripts/pic.flow init flat_channel --dest my_case
python3 scripts/pic.flow validate --case my_case/flat_channel.yml --solver my_case/Imp-MG-Standard.yml --monitor my_case/Standard_Output.yml --post my_case/standard_analysis.yml
python3 scripts/pic.flow run --solve --post-process -n 4 --case my_case/flat_channel.yml --solver my_case/Imp-MG-Standard.yml --monitor my_case/Standard_Output.yml --post my_case/standard_analysis.yml

Solver-only run:

python3 scripts/pic.flow run --solve -n 8 --case case.yml --solver solver.yml --monitor monitor.yml

Post-process an existing run with a different recipe:

python3 scripts/pic.flow run --post-process --run-dir runs/<run_id> --post alt_analysis.yml

Dry-run planning:

python3 scripts/pic.flow run --solve --post-process --case case.yml --solver solver.yml --monitor monitor.yml --post post.yml --dry-run --format json

Cluster generation without submit:

python3 scripts/pic.flow run --solve --post-process --case case.yml --solver solver.yml --monitor monitor.yml --post post.yml --cluster cluster.yml --no-submit

7. Authoring Examples

Programmatic baseline:

case: examples/flat_channel/flat_channel.yml
solver: examples/flat_channel/Imp-MG-Standard.yml
monitor: examples/flat_channel/Standard_Output.yml
post: examples/flat_channel/standard_analysis.yml

File-grid baseline:

case: examples/bent_channel/bent_channel.yml
solver: examples/bent_channel/Imp-MG-Standard.yml
monitor: examples/bent_channel/Standard_Output.yml
post: examples/bent_channel/standard_analysis.yml

Analytical zero-flow Brownian verification:

case: examples/brownian_motion/brownian_motion.yml
solver: examples/brownian_motion/Analytical-Zero.yml
monitor: examples/brownian_motion/Standard_Output.yml
post: examples/brownian_motion/brownian_analysis.yml

These are examples, not fixed bundles. You can intentionally swap roles when the contract makes sense.

5. Configuration Patterns Worth Reusing

Minimal zero-flow startup:

properties:
  initial_conditions:
    mode: "Zero"

Poiseuille with a clear scalar input:

properties:
  initial_conditions:
    mode: "Poiseuille"
    peak_velocity_physical: 1.25

Generated grid workflow:

grid:
  mode: grid_gen
  generator:
    config_file: config/grids/coarse_square_tube_curved.cfg
    grid_type: cpipe
    cli_args: ["--ncells-i", "96", "--ncells-j", "96"]

Restart with explicit particle re-initialization:

run_control:
  start_step: 200
 
models:
  physics:
    particles:
      count: 10000
      restart_mode: "init"

7. When To Use Which Grid Path

Choose flat_channel when:

you want the simplest first runnable case,
you are learning programmatic_c,
you want a clean baseline for solver/monitor/post swaps.

Choose bent_channel when:

you need file-based curvilinear geometry,
you want to understand grid.mode: file,
you plan to compare against grid_gen later.

Choose brownian_motion when:

you want an analytical zero-flow validation case,
you want a particle-focused test with minimal flow complexity,
you want a reference for ZERO_FLOW analytical mode.

Table of Contents