Initial Condition Modes

Table of Contents

• 1. Where Initialization Happens
• 2. Eulerian Field Initialization (<tt>properties.initial_conditions</tt>)
• 3. Eulerian Mode Details
• 4. Contravariant Initialization Note
• 5. Eulerian Restart Branches
• 6. Particle Initialization Relation

This page documents how PICurv initializes Eulerian velocity fields and particles at startup. It covers both user-facing YAML inputs and the C implementation path that applies them.

1. Where Initialization Happens

Startup sequence:

1. scripts/pic.flow converts YAML to control flags (-finit, -ucont_*, -pinit, etc.).
2. InitializeEulerianState chooses fresh-start, load, or analytical branch.
3. For fresh starts, SetInitialInteriorField initializes interior Ucont.
4. Boundary handlers then enforce face values and ghost-cell consistency.
5. If particles are enabled, InitializeParticleSwarm runs independently after Eulerian setup.

2. Eulerian Field Initialization (<tt>properties.initial_conditions</tt>)

YAML:

properties:
  initial_conditions:
    mode: "Constant"   # Zero | Constant | Poiseuille
    u_physical: 1.5
    v_physical: 0.0
    w_physical: 0.0

pic.flow mapping:

• mode -> -finit via normalize_field_init_mode:
  • Zero (or 0) -> 0
  • Constant (or 1) -> 1
  • Poiseuille (or 2) -> 2
• u_physical/v_physical/w_physical -> -ucont_x/-ucont_y/-ucont_z after non-dimensionalization by U_ref.

C-side entry points:

• InitializeEulerianState
• SetInitialInteriorField
• FieldInitializationToString

3. Eulerian Mode Details

-finit = 0 (Zero):

• sets interior contravariant velocity to zero.

-finit = 1 (Constant Normal Velocity):

• uses inlet-face orientation to select the normal component,
• uses InitialConstantContra as target normal speed,
• applies sign according to inlet on min or max face.

-finit = 2 (Poiseuille-like Normal Velocity):

• computes a separable parabolic profile using index-space normalized cross-stream coordinates,
• applies profile in the two cross-stream directions,
• clamps small negative roundoff to zero.

4. Contravariant Initialization Note

Initialization is applied to contravariant velocity components, scaled by face-area metrics:

\[ U_n = v_n\,A_n, \]

where face areas are derived from metric vectors (Csi, Eta, Zet) and sign is aligned with inlet face orientation.

This is why equivalent physical inflow speed can map to different Ucont magnitudes on stretched/curved meshes.

5. Eulerian Restart Branches

In InitializeEulerianState:

• StartStep == 0:
  • eulerian_field_source=solve: fresh initialization path.
  • eulerian_field_source=load: reads initial fields from restart files.
  • eulerian_field_source=analytical: uses analytical initializer.
• StartStep > 0:
  • load source reloads restart fields for the requested step.
  • analytical source regenerates analytical field at current (t, step).

6. Particle Initialization Relation

Particle initialization is configured in case.yml -> models.physics.particles, but executed by a separate subsystem.

For full particle mode and restart details, use:

• Particle Initialization and Restart Guide
• Particle Model and Coupling Overview

7. First Validation Checks

After startup, confirm:

• banner line shows expected field initialization mode,
• no warnings about missing inlet face (for inlet-driven setups),
• first output step has non-empty Ucat/Ucont fields.

Common pitfalls:

• using Poiseuille in strongly non-rectangular topology and expecting textbook cylindrical profile,
• forgetting that initialization sets interior only; boundary handlers then overwrite face behavior,
• comparing u_physical directly to Ucont without accounting for metric-face scaling.

1. Reference Scales

• Configuration Reference: Case YAML
• Analytical Solution Modes
• Boundary Conditions Guide
• Particle Initialization and Restart Guide
• Particle Model and Coupling Overview
• Common Fatal Errors and Fixes