User How-To Guides

Table of Contents

• 1. Setup and Physics
  • 1.1 Change Reynolds Number
  • 1.2 Run in 2D
  • 1.3 Increase Grid Resolution
  • 2.1 Set a Constant-Velocity Inlet and Walls
  • 2.2 Enable Periodicity in One Direction
  • 3.1 Run in Parallel and Control DMDA Layout
  • 3.2 Run on Slurm (Generate and Submit)
  • 3.3 Restart from a Saved Step
  • 3.4 Enable Targeted Debug Logging
• 4. Post-Processing Recipes
  • 4.1 Postprocess an Existing Run
  • 4.2 Add Q-Criterion to Eulerian Pipeline
  • 4.3 Enable Statistics Output (MSD)

This page provides operational recipes for common PICurv tasks. Each recipe includes what to change, why it matters, and a quick verification action.

1. Setup and Physics

1.1 Change Reynolds Number

What to change (in case.yml):

properties:
  scaling:
    length_ref: 0.1
    velocity_ref: 1.5
  fluid:
    density: 1000.0
    viscosity: 0.001

Why:

\[ Re = \frac{\rho U L}{\mu} \]

These values set the non-dimensional operating point consumed by solver controls.

Quick check:

• rerun pic.flow validate ...,
• inspect generated .control file for updated values.

1.2 Run in 2D

models:
  physics:
    dimensionality: "2D"
 
grid:
  mode: programmatic_c
  programmatic_settings:
    km: [3]

Why:

• 2D mode still uses a thin third dimension for structured-grid machinery,
• small km is typically enough for planar scenarios.

Quick check:

• confirm generated run uses expected Z resolution.

1.3 Increase Grid Resolution

• programmatic_c: increase im/jm/km arrays,
• file: use finer .picgrid,
• grid_gen: increase generator resolution args.

Verification:

• compare runtime memory/cost and key output metrics across resolutions.

5. boundary_conditions

2.1 Set a Constant-Velocity Inlet and Walls

boundary_conditions:
  - face: "-Zeta"
    type: "INLET"
    handler: "constant_velocity"
    params: {vx: 0.0, vy: 0.0, vz: 1.5}
  - face: "-Eta"
    type: "WALL"
    handler: "noslip"
  # define all remaining faces explicitly

Why:

• handler/type compatibility is validated,
• all faces must be covered for each block.

Verification:

• use validate first and check BC generation files under runs/<run_id>/config/.

2.2 Enable Periodicity in One Direction

models:
  domain:
    i_periodic: true

Use PERIODIC BC type on both paired faces with supported handlers:

• geometric
• constant_flux (requires target_flux)

Verification:

• confirm paired-face consistency in validation output.

5. Run Solver and Postprocessor

3.1 Run in Parallel and Control DMDA Layout

./scripts/pic.flow run -n 16 --solve ...

Optional partition hints:

grid:
  mode: programmatic_c
  programmatic_settings:
    da_processors_x: 4
    da_processors_y: 2
    da_processors_z: 2

Note: da_processors_* are scalar globals, not per-block vectors.

3.2 Run on Slurm (Generate and Submit)

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

Generate-only mode:

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

Verification:

• inspect scheduler/*.sbatch and submission.json in run directory.

3.3 Restart from a Saved Step

run_control:
  start_step: 1000
  total_steps: 2000

Meaning:

• run resumes from step 1000 and advances 2000 additional steps.

Verification:

• confirm restart directory and step indices in run logs.

3.4 Enable Targeted Debug Logging

logging:
  verbosity: "DEBUG"
  enabled_functions:
    - Projection
    - UpdatePressure

Use this for local diagnosis of instability or boundary anomalies. Prefer narrow function lists to keep logs manageable.

4. Post-Processing Recipes

4.1 Postprocess an Existing Run

./scripts/pic.flow run --post-process \
  --run-dir runs/flat_channel_20240401-153000 \
  --post my_study/standard_analysis.yml

Use when solver outputs already exist and you are iterating only on analysis pipeline.

4.2 Add Q-Criterion to Eulerian Pipeline

eulerian_pipeline:
  - task: nodal_average
    input_field: Ucat
    output_field: Ucat_nodal
  - task: q_criterion
 
io:
  eulerian_fields:
    - Ucat_nodal
    - Qcrit

Verification:

• open VTK output and confirm Qcrit field is present.

4.3 Enable Statistics Output (MSD)

statistics_pipeline:
  output_prefix: "Stats"
  tasks:
    - task: msd

Verification:

• check Stats_msd.csv in configured output location.

3. sweep: Parameter Study via Slurm Arrays

python3 scripts/pic.flow sweep \
  --study my_study/study.yml \
  --cluster my_study/cluster.yml

What you get:

• expanded case matrix,
• scheduler array scripts,
• aggregated metrics table,
• optional plots.

See Sweep and Study Guide for full contract details.

9. Next Steps

• Full capability map: Capabilities Summary
• Config references: Configuration Reference: Case YAML, Configuration Reference: Solver YAML, Configuration Reference: Monitor YAML, Configuration Reference: Postprocessor YAML
• Troubleshooting and quality: Common Fatal Errors and Fixes, Testing, Smoke, and Quality Gates Guide