Imported from lzwei196/KISS-Knowledge-Infrastructure-for-Scientific-Simulation (models/OpenFOAM/SKILL.md). Install upstream with npx skills add lzwei196/KISS-Knowledge-Infrastructure-for-Scientific-Simulation --skill OpenFOAM. Copyright stays with the author.

MANDATORY EXECUTION POLICY — READ BEFORE PROCEEDING

You MUST run the actual model binary or package described in this document. If the model fails to import, compile, or execute, you MUST:

1. Check diagnostics/triplets.yaml for a matching error pattern
2. Try the fix suggested in the triplet's remedy section
3. If still failing, report the error to the user with full details

You MUST NOT substitute a simplified Python formula, regression equation, or hand-coded approximation in place of the real model.

Before starting, run: python preflight_check.py (in this KI directory) to verify that the model binary/package and required data are available.

DEBUGGING PROTOCOL — When something goes wrong, follow this order:

1. Check triplets — diagnostics/triplets.yaml may already cover this error
2. Read official docs — The model's own documentation for expected formats/units
3. Find working examples — Check outputs/ or the model's shipped test data
4. Fix the tool — With knowledge of what "correct" looks like

Do NOT write custom debug scripts. The answers are in the docs and examples.

KI map — what to read, and when

Projected 2026-08-17 from the KI's actual contents — 9 components present. Refresh: python3 ki_tools_common/generate_skill_map.py --ki_dir <this KI>.

Executable tool index (projected — complete by construction)

Every public tool in this KI, by exact path. What each is FOR lives in the human-written Tool Inventory above; --help on any of these prints its arguments.

7 public tools; _-prefixed helpers and packaging files excluded.

OpenFOAM Knowledge Infrastructure

Data Preparation

Forcing data

Data Sources: Use from ki_tools_common.load_forcing import load_daily_forcing for CMFD/MSWX/NASA POWER.

Data Validation Reference: See data_ki/CMFD/SKILL.md for atmospheric forcing documentation. See data_ki/NOAA_Tides/SKILL.md for tidal observation data. See data_ki/NDBC/SKILL.md for wave buoy observations.

1. Overview

OpenFOAM (Open Field Operation and Manipulation) is a free, open-source CFD toolbox written in C++. It solves complex fluid flows involving chemical reactions, turbulence, heat transfer, acoustics, solid dynamics, and electromagnetics using the Finite Volume Method (FVM).

Key Capabilities for Hydraulics:

• Incompressible and compressible flow (Navier-Stokes equations)
• Free-surface flows via Volume of Fluid (VoF) method (interFoam / incompressibleVoF)
• Multiphase Eulerian and Lagrangian particle tracking
• Turbulence: RANS (k-epsilon, k-omega SST, Spalart-Allmaras), LES, DES, DNS
• Adaptive mesh refinement and dynamic mesh motion
• Fully parallelized via MPI domain decomposition

Architecture (dev version): The development version uses a modular solver architecture where foamRun dynamically loads solver modules (e.g., incompressibleFluid, fluid, incompressibleVoF). Legacy solver binaries (simpleFoam, icoFoam, interFoam) are thin wrappers calling foamRun.

2. Installation

2.1 Prerequisites

• C++ compiler: GCC >= 7, Clang, or Intel
• MPI: OpenMPI or MPICH (for parallel runs)
• Scotch or METIS (mesh partitioning)
• flex (lexer generator)
• ParaView (optional, for visualization)

2.2 Build from Source

# Clone repository
git clone https://github.com/OpenFOAM/OpenFOAM-dev.git OpenFOAM-dev

# Source environment
cd OpenFOAM-dev
source etc/bashrc

# Build everything (libraries + solvers + utilities)
./Allwmake -j$(nproc) 2>&1 | tee log.Allwmake

# Verify
blockMesh -help
foamRun -help

2.3 Environment Variables

2.4 Test Installation

mkdir -p $FOAM_RUN && cd $FOAM_RUN
cp -r $FOAM_TUTORIALS/incompressibleFluid/cavity .
cd cavity
blockMesh
foamRun

3. Case Directory Structure

Every OpenFOAM simulation is defined by a case directory:

caseDir/
+-- 0/                  # Initial and boundary conditions
|   +-- p               # Pressure field
|   +-- U               # Velocity field
|   +-- k               # Turbulent kinetic energy (if turbulent)
|   +-- epsilon          # Turbulent dissipation (if turbulent)
+-- constant/           # Time-invariant properties
|   +-- polyMesh/       # Mesh definition (generated)
|   |   +-- points      # Vertex coordinates
|   |   +-- faces       # Face definitions
|   |   +-- owner       # Face-to-cell ownership
|   |   +-- neighbour   # Face-to-cell adjacency
|   |   +-- boundary    # Patch definitions
|   +-- physicalProperties   # Fluid viscosity, density
|   +-- momentumTransport    # Turbulence model config
+-- system/             # Solver configuration
    +-- controlDict     # Time stepping, write control, solver
    +-- fvSchemes       # Discretization schemes
    +-- fvSolution      # Linear solver settings, PIMPLE config
    +-- blockMeshDict   # Mesh generation parameters
    +-- decomposeParDict # Parallel decomposition

4. Pipeline Stages

5. Input Formats and Units

5.1 FoamFile Header (all field/dictionary files)

FoamFile
{
    format      ascii;              // ascii or binary
    class       volScalarField;     // field type
    location    "0";                // time directory
    object      p;                  // field name
}

5.2 Dimension Array

OpenFOAM enforces dimensional consistency via a 7-element array:

dimensions [kg  m  s  K  mol  A  cd]
           [M   L  T  Th N    J  Lum]

5.3 Boundary Condition Types

6. Output Description

This section restates dag.yaml; if this body ever disagrees with the dag, the dag wins.

Headline output (validation_rank: 1):

alpha.water - VoF phase fraction; the iso-surface alpha=0.5 defines the free surface, from which water-level / wave elevation is derived. (dimensionless 0-1)

Other dag outputs supplied by the KI facts are: U, p, phi, k.

8. Unit Conversion Table

Exact I/O shapes live in docs/format_spec.yaml. This body table restates the model units and the conversions already documented in this KI; do not use it to override dag or format-spec facts.

8.1 Unit Trap Table

These are the most dangerous unit/format traps that cause silent errors or crashes:

7. Solver Reference

7.1 Key Solvers (foamRun modules)

7.2 Key Utilities

7.3 PIMPLE Algorithm Settings

PIMPLE
{
    nOuterCorrectors    50;     // Outer PIMPLE loops (1=PISO, >1=PIMPLE)
    nCorrectors         2;      // Pressure correction steps per outer
    nNonOrthogonalCorrectors 1; // Non-orthogonal correction
    pRefCell            0;      // Reference cell for pressure
    pRefValue           0;      // Reference pressure value
    residualControl
    {
        U               1e-5;   // Convergence criterion
        p               1e-5;
    }
}

8. Critical Domain Knowledge

dk_001: Kinematic vs Dynamic Pressure

OpenFOAM's incompressible solvers use kinematic pressure p/rho with dimensions [0 2 -2 0 0 0 0] (m^2/s^2), NOT dynamic pressure in Pascal. When coupling with external tools that output Pa, you MUST divide by density. This is the single most common source of error for new users.

dk_002: convertToMeters in blockMeshDict

The convertToMeters factor is applied to ALL vertex coordinates. If your vertices are already in meters, set it to 1. If vertices are in millimeters, set 0.001. Forgetting this produces a mesh at the wrong scale -- all velocities and Reynolds numbers will be wrong, but the simulation may still converge, producing silently incorrect results.

dk_003: Boundary Patch Consistency

Patch names in 0/U, 0/p, etc. MUST exactly match those defined in constant/polyMesh/boundary (generated by blockMesh/snappyHexMesh). A single character mismatch causes a fatal "patch not found" error. After regenerating the mesh, always update boundary condition files.

dk_004: Courant Number and Time Stepping

For explicit or semi-implicit time schemes, the Courant number Co = U*dt/dx must remain below ~1. Use adjustTimeStep yes with maxCo 1 in controlDict for adaptive stepping. For steady-state (SIMPLE), this does not apply -- use large pseudo-time steps instead.

dk_005: Gravity Direction in Hydraulic Simulations

For free-surface flows (VoF), gravity MUST be defined in constant/g as a uniformDimensionedVectorField. The standard convention is (0 -9.81 0) for Y-up or (0 0 -9.81) for Z-up. Using the wrong axis or sign produces inverted buoyancy -- heavy fluid rises, light fluid sinks.

dk_006: Turbulence Model Initialization

Under-initialized turbulence fields (k, epsilon, omega) cause the first few iterations to diverge. Use the estimations:

• k = 1.5 * (U_ref * TI)^2 where TI = turbulence intensity (typically 0.01-0.1)
• epsilon = C_mu^0.75 * k^1.5 / l where l = characteristic length scale
• omega = k^0.5 / (C_mu^0.25 * l)

dk_007: writeControl vs writeInterval Semantics

• writeControl timeStep; writeInterval 100; writes every 100 time steps
• writeControl runTime; writeInterval 0.1; writes every 0.1 seconds of simulation time
• writeControl adjustableRunTime; adjusts dt to hit exact write times Mixing these up produces unexpected output frequency.

dk_008: VoF Phase Fraction alpha

In VoF simulations, alpha.water (or alpha.phase1) ranges 0-1. The field must be initialized correctly: 1 = water, 0 = air. Using setFields with boxToCell or cylinderToCell is required. An all-zero alpha field means no water exists.

dk_010: incompressibleVoF vs shallowWaterFoam for Ocean Domains

incompressibleVoF is designed for lab-scale problems (wave tank, ship waves, dam break). It is NOT appropriate for basin-scale ocean/storm surge domains (>100 km horizontal) because:

1. Mass loss: MULES numerical diffusion smears alpha into the air cell layer; open atmosphere BCs then let diffused alpha escape. At 40m depth with 10m cells, mass loss rate ~4.7e-7/s.
2. Standing waves: Closed slip-wall domain has no wave absorption. Initial pressure transients create resonant gravity waves (period T = 2L/c ≈ 27 h for 977 km basin). deltaT permanently oscillates at 0.25-1.5s — 100× slower than needed.
3. Zero surge from uniform forcing: Domain-averaged uniform p_atm has ∇p_atm = 0. The IB surface rise is exactly cancelled by the p_rgh change at the gauge → net surge = 0.
4. VoF scale constraint: For a 977km × 674km × 50m domain, VoF must resolve both the 40m water column AND the 977km horizontal dynamics simultaneously — computationally intractable.

Use shallowWaterFoam instead ($WM_PROJECT_DIR/applications/legacy/incompressible/shallowWaterFoam/):

• Solves 2D depth-integrated SWE: ∂h/∂t + ∇·(hU) = 0; ∂(hU)/∂t + ∇·(UhU) + g·h·∇(h+h0) = 0
• Fields: h (depth), hU (depth-integrated velocity), h0 (bed topography)
• Typical dt = 0.5 × dx / √(g·h) = 0.5 × 4886 / √(9.81×40) = 123s → 4320 steps for 5 days
• Barometric forcing: set h0(x,y,t) = −(p_atm − p_ref)/(ρ·g) (inverted barometer)
• Reference performance: IB-only gives NSE=0.51, R=0.84 vs NOAA obs @ Grand Isle for Laura 2020

dk_011: libparallel.so Must Be Built Before decomposePar

When building individual OpenFOAM utilities (not running Allwmake), the dependency libparallel.so in src/parallel/parallel/ must be compiled first or decomposePar will fail with "cannot find -lparallel". Fix:

cd $WM_PROJECT_DIR/src/parallel/parallel && wmake libso
# Then retry decomposePar

dk_012: MULESCorr yes Causes Rayleigh-Taylor Instability

MULESCorr yes (the MULES correction step) applies an additional corrective flux after the bounded MULES step. This correction can overshoot, producing alpha > 1 in interface cells. When alpha > 1 in an upper cell, that cell has density > ρ_water, sitting above normal water → Rayleigh-Taylor unstable. The velocity grows exponentially until NaN. Always use MULESCorr no for large domains or when alpha Max > 1 is observed. nSubCycles 1-2 is sufficient; nSubCycles 5 with MULESCorr no is stable but slow.

dk_013: runTimeModifiable Does Not Apply to 0/ Field Files

runTimeModifiable true in controlDict allows hot-editing of system/fvSchemes, system/fvSolution, and system/controlDict. It does NOT re-read boundary conditions from 0/ field files. For a running parallel case, BC changes must be made to ALL processor*/0/fieldName files and require a solver restart.

dk_014: Water Level Extraction from p_rgh Probe (VoF)

For an incompressibleVoF storm surge simulation, the water level anomaly at a gauge located at height z_probe (within the water column) is:

η(t) = (p_rgh_probe(t) − p_rgh_probe(0)) / ((ρ_water − ρ_air) × g)

This only gives correct surge if: (a) mass is conserved (no alpha leakage), AND (b) the forcing has spatial variation at the gauge location (∇p_atm ≠ 0). With uniform domain-averaged forcing: the IB rise and p_rgh change cancel → η = 0.

dk_009: Parallel Run MPI Consistency

mpirun -np N foamRun -parallel requires:

1. system/decomposeParDict with numberOfSubdomains N;
2. decomposePar run first to create processor0/ ... processorN-1/ directories
3. The N values MUST match. A mismatch causes immediate MPI abort.

9. Calibration and Tuning Parameters

10. Data Requirements

11. Validated Results

This section restates the KI's validation facts and docs/validation_convention.yaml convention bars. A missing/null convention band is written as "no cited threshold"; no threshold is inferred.

Recorded Validation Cases

Performance Metrics -- judged against the field's bar, not intuition

No convention bar for the rank-1 dag output alpha.water was supplied in the extracted validation-convention facts. The available convention bars supplied by the KI are:

Achieved Metrics Against Convention Bars

Data Replacement Tracking

12. Quick Start

# 1. Source environment
source $WM_PROJECT_DIR/etc/bashrc

# 2. Copy tutorial case
cp -r $FOAM_TUTORIALS/incompressibleFluid/cavity myCase && cd myCase

# 3. Generate mesh
blockMesh

# 4. Check mesh quality
checkMesh

# 5. Run solver
foamRun

# 6. Convert output for visualization
foamToVTK

# 7. Parallel execution (4 cores)
decomposePar
mpirun -np 4 foamRun -parallel
reconstructPar

13. Output Format

13.1 Time Directories

Each write produces a directory named by the simulation time (e.g., 0.1/, 0.2/):

0.1/
+-- p           # Pressure field (all cells + boundaries)
+-- U           # Velocity field
+-- phi         # Face flux field
+-- uniform/    # Uniform fields (time info)

13.2 Field File Format

internalField   nonuniform List<scalar>
1000            // number of cells
(
    0.0
    0.00123
    ...
)
;

boundaryField
{
    inlet { type calculated; value nonuniform List<scalar> 20 (...); }
    ...
}

13.3 Log File

The solver writes residuals, Courant number, and execution time to stdout. Typical log line:

Time = 0.5
smoothSolver:  Solving for Ux, Initial residual = 0.00234, Final residual = 1.2e-07, No Iterations 3
GAMG:  Solving for p, Initial residual = 0.0156, Final residual = 4.5e-07, No Iterations 12
ExecutionTime = 1.23 s  ClockTime = 2 s

13.4 Function Objects

Post-processing probes, forces, and field averages are written to postProcessing/:

postProcessing/
+-- forces/
|   +-- 0/
|       +-- force.dat         # Time series of forces
+-- probes/
    +-- 0/
        +-- p                 # Probed pressure values
        +-- U                 # Probed velocity values

14. Coupling Points

15. Diagnostic Triplets Summary

See diagnostics/triplets.yaml for full definitions.

16. File Structure

ki/
+-- SKILL.md                    # This file
+-- tools/
|   +-- convert_forcing_to_openfoam.py    # Forcing/BC converter
|   +-- convert_properties_to_openfoam.py # Physical properties converter
|   +-- generate_mesh.py                  # Mesh generation wrapper
|   +-- run_openfoam.py                   # Execution wrapper
|   +-- parse_openfoam_output.py          # Output parser
|   +-- configure_case.py                 # Case configuration generator
|   +-- check_case.py                     # Pre-run validation
+-- docs/
|   +-- s0_configuration.md       # Case configuration skill
|   +-- s1_mesh_generation.md     # Mesh generation skill
|   +-- s2_boundary_conditions.md # Forcing/BC setup skill
|   +-- s3_physical_properties.md # Property configuration skill
|   +-- s4_solver_setup.md        # Solver and scheme selection skill
|   +-- s5_execution.md           # Running OpenFOAM skill
|   +-- s6_postprocessing.md      # Output analysis skill
+-- diagnostics/
    +-- triplets.yaml             # 20 diagnostic triplets