Configuration Reference: Case YAML

Table of Contents

• 1. properties
• 2. run_control
• 3. grid
  • 3.1 mode: programmatic_c
  • 3.2 mode: file
  • 3.3 mode: grid_gen
• 4. models
• 5. boundary_conditions
• 6. solver_parameters (Advanced)

For the full commented template, see:

case.yml defines physical setup, grid source, domain topology, and boundary conditions.

1. properties

properties:
  scaling:
    length_ref: 0.1
    velocity_ref: 1.5
  fluid:
    density: 1000.0
    viscosity: 0.001
  initial_conditions:
    mode: "Constant"
    u_physical: 1.5
    v_physical: 0.0
    w_physical: 0.0

Key mappings:

• scaling.length_ref -> -scaling_L_ref
• scaling.velocity_ref -> -scaling_U_ref
• fluid.density and fluid.viscosity are used by pic.flow to compute Reynolds number -> -ren
• initial_conditions.mode -> -finit (Zero, Constant, Poiseuille)
• u_physical/v_physical/w_physical -> -ucont_x/-ucont_y/-ucont_z

For the scaling model and conversion logic, see Non-Dimensionalization Model. For detailed startup behavior of field initialization modes, see Initial Condition Modes.

2. run_control

run_control:
  dt_physical: 0.0001
  start_step: 0
  total_steps: 2000

Mappings:

• dt_physical -> -dt (non-dimensionalized)
• start_step -> -start_step
• total_steps -> -totalsteps

3. grid

Supported modes:

• programmatic_c
• file
• grid_gen

3.1 mode: programmatic_c

programmatic_settings supports per-block lists for geometry arrays:

• im/jm/km
• xMins/xMaxs, yMins/yMaxs, zMins/zMaxs
• rxs/rys/rzs

Important constraint:

• da_processors_x/y/z are scalar integers only (global DMDA layout). Per-block processor decomposition is not implemented.

3.2 mode: file

grid:
  mode: file
  source_file: my_grid.picgrid

pic.flow validates existence and prepares normalized grid data for C-side ingestion.

3.3 mode: grid_gen

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"]

This runs scripts/grid.gen before solver launch and stages generated grid artifacts into the run config.

4. models

models:
  domain:
    blocks: 1
    i_periodic: false
    j_periodic: false
    k_periodic: false
  physics:
    dimensionality: "3D"
    turbulence:
      les: false
    particles:
      count: 0
      init_mode: "Surface"
      restart_mode: "init"

Common mappings:

• domain.blocks -> -nblk
• periodic flags -> -i_periodic/-j_periodic/-k_periodic
• physics.dimensionality: "2D" -> -TwoD 1
• physics.turbulence.les -> -les
• physics.particles.count -> -numParticles
• physics.particles.init_mode -> -pinit (Surface, Volume, PointSource, SurfaceEdges)
• physics.particles.restart_mode -> -particle_restart_mode
• point source coordinates -> -psrc_x/-psrc_y/-psrc_z

For mode-specific particle behavior and restart flow, see Particle Initialization and Restart Guide.

5. boundary_conditions

Single-block syntax: list of 6 face entries. Multi-block syntax: list-of-lists, one 6-face list per block.

Supported face names:

• -Xi, +Xi, -Eta, +Eta, -Zeta, +Zeta

Supported type/handler combinations:

• INLET + constant_velocity (vx/vy/vz)
• INLET + parabolic (v_max)
• OUTLET + conservation
• WALL + noslip
• PERIODIC + geometric
• PERIODIC + constant_flux (target_flux, optional apply_trim)

All six faces must be explicitly provided for each block. For detailed handler semantics, validation constraints, and C dispatch path, see Boundary Conditions Guide.

6. solver_parameters (Advanced)

Optional escape hatch for flags not yet exposed in structured schema:

solver_parameters:
  -read_fields: true
  -some_new_flag: 123

Use sparingly and prefer structured keys when available.

9. Next Steps

Proceed to Configuration Reference: Solver YAML.

Cross-file contract/mapping:

• Configuration Contract (YAML -> Generated Artifacts -> Runtime)
• Developer Ingestion Map
• Analytical Solution Modes
• Initial Condition Modes
• Boundary Conditions Guide
• Particle Initialization and Restart Guide