Boundary Conditions Guide

Table of Contents

• 1. Boundary-Condition Grammar
• 2. Supported User-Facing Combinations (<tt>pic.flow</tt>)
• 3. Non-Dimensionalization Before C Input
• 4. Periodicity Consistency Rules
• 5. C-Side Parsing and Dispatch
• 6. Exposed vs Latent Options
• 7. Authoring Examples
• 8. Common Failure Modes

This page is the detailed reference for boundary-condition authoring in case.yml. It documents what is currently supported by the Python conductor and what is currently wired in C.

1. Boundary-Condition Grammar

case.yml -> boundary_conditions supports:

• single-block form: one list with 6 faces,
• multi-block form: list-of-lists, one 6-face list per block.

Face names:

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

Every block must provide all six faces exactly once.

2. Supported User-Facing Combinations (<tt>pic.flow</tt>)

The validator accepts these type/handler pairs:

Type	Handler	Required params	Optional params	Units expected in YAML
WALL	noslip	none	none	n/a
INLET	constant_velocity	vx, vy, vz	none	m/s
INLET	parabolic	v_max	none	m/s
OUTLET	conservation	none	none	n/a
PERIODIC	geometric	none	none	n/a
PERIODIC	constant_flux	target_flux	apply_trim	m^3/s

Notes:

• legacy params.vector and params.velocity are rejected; use scalar vx/vy/vz,
• unknown params are rejected per handler,
• constant_flux must be configured on both faces of the periodic pair.

3. Non-Dimensionalization Before C Input

pic.flow converts physical BC values to solver-scale values before writing bcs.run:

\[ v^* = \frac{v}{U_{ref}}, \qquad Q^* = \frac{Q}{U_{ref} L_{ref}^{2}}. \]

Specifically:

• vx/vy/vz/v_max are divided by properties.scaling.velocity_ref,
• target_flux is divided by velocity_ref * length_ref^2.

4. Periodicity Consistency Rules

Validator checks:

1. each axis pair must match periodicity:
   • (-Xi,+Xi), (-Eta,+Eta), (-Zeta,+Zeta) are both periodic or both non-periodic.
2. driven periodic handler (constant_flux) must match on both faces of a periodic pair.
3. incomplete face sets fail validation immediately.

The C side also performs periodic consistency checks while deriving global periodicity in DeterminePeriodicity.

5. C-Side Parsing and Dispatch

Generated bcs.run lines use:

<face> <type> <handler> key=value key=value ...

C ingestion path:

1. ParseAllBoundaryConditions parses and broadcasts face configs.
2. StringToBCFace, StringToBCType, StringToBCHandlerType convert tokens.
3. ValidateBCHandlerForBCType enforces type-handler compatibility.
4. BoundaryCondition_Create maps handler enums to concrete implementations.

Current factory-wired handlers include:

• wall no-slip,
• inlet constant velocity,
• inlet parabolic,
• outlet conservation,
• periodic geometric,
• periodic driven constant flux.

6. Exposed vs Latent Options

Important contributor note:

• C enums include additional BC categories and handlers (for example symmetry-family and initial_flux enum entries),
• but the current end-to-end user contract intentionally exposes the validated subset listed above.

If you add a new BC mode, update all three layers in one change:

1. Python validator/writer (scripts/pic.flow),
2. C parser/factory/handler implementation,
3. docs and tests (fixtures + smoke checks).

7. Authoring Examples

Constant-velocity inlet + outlet conservation:

boundary_conditions:
  - face: "-Xi"
    type: INLET
    handler: constant_velocity
    params: { vx: 1.5, vy: 0.0, vz: 0.0 }
  - face: "+Xi"
    type: OUTLET
    handler: conservation
  - face: "-Eta"
    type: WALL
    handler: noslip
  - face: "+Eta"
    type: WALL
    handler: noslip
  - face: "-Zeta"
    type: WALL
    handler: noslip
  - face: "+Zeta"
    type: WALL
    handler: noslip

Driven periodic flux on Xi:

boundary_conditions:
  - face: "-Xi"
    type: PERIODIC
    handler: constant_flux
    params: { target_flux: 0.02, apply_trim: true }
  - face: "+Xi"
    type: PERIODIC
    handler: constant_flux
    params: { target_flux: 0.02, apply_trim: true }
  - face: "-Eta"
    type: WALL
    handler: noslip
  - face: "+Eta"
    type: WALL
    handler: noslip
  - face: "-Zeta"
    type: WALL
    handler: noslip
  - face: "+Zeta"
    type: WALL
    handler: noslip

8. Common Failure Modes

• ‘missing required key 'face’/'type'/'handler': malformed BC entry object. -Duplicate face: same face declared twice in one block. -incomplete ... Missing faces: not all 6 faces provided. -Inconsistent periodicity: one side periodic and opposite side non-periodic. -Unknown params`: extra keys not allowed for selected handler.

1. Reference Scales

• Configuration Reference: Case YAML
• Initial Condition Modes
• Particle Initialization and Restart Guide
• Code Architecture
• Common Fatal Errors and Fixes