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
• 7. Practical Checks
• 8. Related Pages
  • CFD Reader Guidance and Practical Use
    • What To Extract Before Changing A Case
    • Practical CFD Troubleshooting Pattern

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/picurv 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

Preferred Poiseuille form:

properties:
  initial_conditions:
    mode: "Poiseuille"
    peak_velocity_physical: 1.5

picurv 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.
• peak_velocity_physical (Poiseuille only) -> picurv infers the unique inlet axis from boundary_conditions and maps the scalar peak speed onto the matching -ucont_* component.

Launcher-side contract:

• mode should be set explicitly.
• for Zero, velocity components may be omitted and default to zero.
• for Constant, explicit component values are required.
• for Poiseuille, use either:
  • peak_velocity_physical, or
  • u_physical/v_physical/w_physical but not both in the same block.

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.
• treats the inlet-aligned input component as the profile peak (Vmax / centerline speed), not bulk-average velocity.

This means peak_velocity_physical is the clearest user-facing representation for Poiseuille mode.

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).

Operational note:

• StartStep identifies the saved restart state being loaded, not the first new step to compute.
• If a run completed through step N, restart with start_step: N; the first newly advanced step will be N+1.

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. Practical 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,
• supplying a bulk/mean velocity to Poiseuille mode when the current implementation expects Vmax,
• forgetting that initialization sets interior only; boundary handlers then overwrite face behavior,
• comparing u_physical directly to Ucont without accounting for metric-face scaling.

8. Related Pages

• Configuration Reference: Case YAML
• Configuration Contract (YAML -> Generated Artifacts -> Runtime)
• Analytical Solution Modes
• Workflow Recipes and Config Cookbook
• Boundary Conditions Guide
• Particle Initialization and Restart Guide
• Particle Model and Coupling Overview
• Common Fatal Errors and Fixes
• Modular Selector Extension Guide

CFD Reader Guidance and Practical Use

This page describes Initial Condition Modes within the PICurv workflow. For CFD users, the most reliable reading strategy is to map the page content to a concrete run decision: what is configured, what runtime stage it influences, and which diagnostics should confirm expected behavior.

Treat this page as both a conceptual reference and a runbook. If you are debugging, pair the method/procedure described here with monitor output, generated runtime artifacts under runs/<run_id>/config, and the associated solver/post logs so numerical intent and implementation behavior stay aligned.

What To Extract Before Changing A Case

• Identify which YAML role or runtime stage this page governs.
• List the primary control knobs (tolerances, cadence, paths, selectors, or mode flags).
• Record expected success indicators (convergence trend, artifact presence, or stable derived metrics).
• Record failure signals that require rollback or parameter isolation.

Practical CFD Troubleshooting Pattern

1. Reproduce the issue on a tiny case or narrow timestep window.
2. Change one control at a time and keep all other roles/configs fixed.
3. Validate generated artifacts and logs after each change before scaling up.
4. If behavior remains inconsistent, compare against a known-good baseline example and re-check grid/BC consistency.