csml-rpi/ai-cfd-scientist/cfd-mesh-gate

cfd-mesh-gate

⚠ HARD STOP — read this before any other step

For routes 1, 2, 6 (research / code_mod / open_discovery): if <out-dir>/checkpoints/requirements_done.json does not exist (or for code_mod, if code_mod_done.json does not exist), STOP. Return to Skill cfd-orchestrator and start the chain from literature. Mesh-refining a starter geometry before requirements (and code-mod for route 2) have been authored is a shortcut that produces a mesh selected against the wrong physics. The route-3 mesh-independence-only path has no upstream predecessors and passes through trivially — but routes 1/2/6 require the upstream chain.

Mesh independence is mandatory for every CFD Scientist study (per CLAUDE.md). This skill is the canonical implementation. The full mesh-sensitivity protocol — STEPS A–E — is embedded below; the per-level case execution goes through cfd-experiment (which itself wraps scripts/foam_run.py with --mesh-gate-role); the analysis (QoI comparison, percent-difference, GCI) is fully agent-driven.

Step 0 — Preflight gate (HARD; slice 14)

Before any mesh-level case is launched:

python scripts/stage_gate_audit.py --out-dir <out-dir> --mode preflight --target-stage mesh_gate

If rc != 0, STOP. On routes 1, 2, and 6 the script requires literature_done, baseline_setup_done, metric_setup_done, hypothesis_done, requirements_done (and code_mod_done on route 2) before mesh-gate can launch. Mesh refinement against a starter geometry without the upstream requirement set is the failure mode where the agent treats mesh-gate as the first stage of the run. Route 3 (mesh-independence-only) has no upstream predecessors and passes preflight trivially.

When to use

After cfd-requirements (or after cfd-code-modify) and before bulk cfd-experiment calls. Every pathway — general, code-mod, OED — passes through this gate.

Inputs

• out-dir (required) — must contain requirements.json
• starter-dir (optional) — starter case for baseline geometry/numerics
• qoi_tolerance_percent (optional, default 5.0) — threshold for declaring mesh-insensitivity
• near_wall_tolerance_percent (optional, default 10.0) — looser threshold for wall-bounded QoIs

Starter directory is READ-ONLY (per skills/cfd-orchestrator/SKILL.md non-negotiable constraints). Each mesh level's case lives at <out-dir>/mesh_gate/<group>/<level>/; copy from starter via cp -r before any mesh-refinement edits.

Outputs

• <out-dir>/selected_mesh_spec.json — per-physics-group selected mesh:

``json { "version": 2, "groups": { "<group_id>": { "selected_level": "baseline|refined_v1|refined_v2|...", "stable_name": "<dirname>", "baseline_case": "<path>", "analysis_path": "<path>/mesh_analysis.json", "levels": [{"level": 0, "cells": <n>, "qois": {...}}, ...], "requirement_suffix": "MESH POLICY: …" } }, "case_to_group": {"case_001": "<group_id>", ...} } ``

• <out-dir>/mesh_independence_context.json — paper-ready context (per-group cells, QoIs, figure paths) consumed by cfd-paper's Writer
• <out-dir>/mesh_gate/<group>/mesh_analysis.json per group

Mesh sensitivity protocol (recipe — STEPS A–E)

The protocol below is the canonical mesh-sensitivity assessment for CFD Scientist. Follow it exactly.

STEP A — Identify reference scales

Before modifying any mesh, for each physics group (defined in Step 1 below):

1. Identify the most appropriate characteristic length scale L_ref for the geometry. Choose the dominant physical length: chord, diameter, body height, hydraulic diameter, gap/clearance scale, or another clearly justified reference dimension. State your choice and the reason in the per-group mesh_analysis.json.

1. Identify primary quantities of interest (QoI). Examples: force/moment coefficients, pressure drop, mass-flow rate, separation/reattachment location, wake properties, heat-transfer quantities, or other geometry-specific metrics. List 3–6 QoIs per group.

STEP B — Create comparison mesh (10% near-wall, 5% away-from-wall)

Start with one modified mesh relative to baseline:

• Near-wall region: wall-adjacent boundary-layer mesh attached to all no-slip solid surfaces. Reduce local mesh size by ~10% relative to baseline. Include comparable reduction in first-layer thickness and consistent scaling of wall-normal layered mesh. Keep same number of layers and approximately same growth ratio unless adjustment is needed for mesh quality. If using wall functions, ensure refinement does not push y+ outside intended range.

• Away-from-wall region: outer/core/wake flow region outside wall-adjacent layers. Reduce characteristic mesh size by ~5% relative to baseline.

• Preserve: current mesh topology, domain extent, blocking strategy, and mesh-generation methodology.

• If no inflation/prism layers exist: define near-wall as all cells within d_w <= 0.05 * L_ref from any no-slip wall. Apply consistently.

These percentages are guidance, not strict rules — what matters is that the refined mesh is meaningfully finer than baseline in both regions while preserving topology.

STEP C — Run both meshes

Use IDENTICAL: physical models, turbulence models, material properties, BCs, reference values, solver settings, schemes, relaxation, time-step, convergence criteria. Only the mesh changes.

• Steady: ensure both solutions are converged — judge by BOTH residual reduction AND stabilization of integral quantities.
• Unsteady: ensure transients have decayed; compare statistically converged results with the same averaging procedure and window.

STEP D — Monitor and compare

Select representative monitoring locations: probe points, lines, planes, or surface stations in regions important to flow physics (near-wall, stagnation, separated shear layers, wakes, recirculation, jet cores, mixing regions, far field).

Compare between baseline and modified meshes:

• Converged velocity and pressure at monitoring locations
• Wall skin-friction coefficient Cf where applicable
• Pressure coefficient Cp where applicable
• Heat-flux or Nusselt-number distributions where relevant
• All key global/integral quantities: lift, drag, moments, pressure loss, flow split, mass-flow rate, or other case-specific outputs

For both meshes, report:

• Total cell count
• Near-wall y+ statistics where relevant
• Mesh-quality indicators (skewness, non-orthogonality, aspect ratio)
• Confirmation that the refined mesh remains valid and acceptable quality

STEP E — Quantify and assess

For each monitored quantity:

• Compute percent difference between baseline and modified meshes.
• Identify any locations/regions/global metrics where change exceeds 5% relative to converged baseline (or another tolerance if clearly justified — near_wall_tolerance_percent allows looser threshold for wall-bounded QoIs).
• Assess whether surface distributions show meaningful differences.
• State conclusion: whether the current mesh appears sufficiently mesh-insensitive, or whether a more systematic multi-level study is required.
• If further refinement is needed: identify which regions/quantities are driving that conclusion.
• Continue refinement progression until an acceptable mesh-insensitive level is reached for primary QoIs, then mark that as selected_mesh_spec.

Implementation steps

Step 1 — Group cases by physics

Cases that share solver + turbulence model + custom-code class form a physics group. Examples:

• sa_builtin_baseline — built-in Spalart-Allmaras, no custom code
• custom_sa_mods — a case-local compiled custom SA modification (one mesh study per code-mod variant only if the variant changes the BL physics significantly; otherwise share with the baseline group)
• kOmegaSST_with_wallfunction vs kOmegaSST_lowRe — different y+ targets ⇒ different groups

For each case in requirements.json, decide its group (the agent uses solver + turbulence model + customModels lib name as the key). Write the grouping to <out-dir>/mesh_gate_resume.json:

{
  "groups": {
    "<group_id>": {
      "case_ids": ["case_001", "case_003"],
      "physics_signature": {"solver": "simpleFoam", "turbulence": "SpalartAllmaras", "custom_lib": null},
      "L_ref_basis": "step height = 0.038 m",
      "qois": ["Cf_along_lower_wall", "x_reattach", "Cp_along_lower_wall", "y_plus_max"]
    }
  }
}

Step 2 — Build baseline + refined requirement texts

For each group:

Baseline requirement — derive from the first case in the group's case_ids. Strip any case-specific parameter sweep value (we want the baseline to be a single canonical setup); keep solver, turbulence model, BCs, geometry, and the baseline mesh size from the original requirement (or from the starter case if starter-dir was given).

Refined requirement — copy the baseline; modify per STEP B:

• Add an explicit "MESH-GATE REFINEMENT: this case is the refined-level mesh for the mesh-independence study; reduce near-wall cell size by ~10% (incl. first-layer thickness and layer-stack scaling) and reduce away-from-wall cell size by ~5%, preserving topology and domain extent."
• State explicit cell counts (or nx×ny×nz), the chosen L_ref, and confirm y+ stays in target range.

Step 3 — Execute baseline + refined

Use cfd-experiment for each level:

/cfd-experiment out-dir=<out-dir> requirement_text=<baseline_req> case_dir=<out-dir>/mesh_gate/<group>/baseline mesh_gate_role=baseline
/cfd-experiment out-dir=<out-dir> requirement_text=<refined_req>  case_dir=<out-dir>/mesh_gate/<group>/refined  mesh_gate_role=refined

Or directly via the underlying script (the gate uses the existing --mesh-gate-role flag in foam_run.py):

python scripts/foam_run.py \
  --requirement "<baseline req text>" \
  --output-dir <out-dir>/mesh_gate/<group>/baseline \
  --mesh-gate-role baseline \
  --timeline <out-dir>/timeline.json
 
python scripts/foam_run.py \
  --requirement "<refined req text>" \
  --output-dir <out-dir>/mesh_gate/<group>/refined \
  --mesh-gate-role refined \
  --timeline <out-dir>/timeline.json

Step 4 — Extract QoIs (agent-driven)

For each level dir, agent computes:

• Cell count — parse log.checkMesh ("Cells: N"), or run checkMesh if missing.
• y+ statistics — parse postProcessing/yPlus*/<time>/yPlus.dat (min/mean/max).
• Per-QoI numbers — depends on QoI type:
• Cf: read <time>/wallShearStress boundary file → magnitude / (0.5 ρ U_ref²) → write Cf_along_<patch>.csv (x, Cf)
• Cp: read <time>/p boundary file → (p − p_ref) / (0.5 ρ U_ref²)
• x_reattach (separation/reattachment): find first sign-change of Cf along lower wall downstream of the step lip, skipping the trapped-bubble first crossing. Use the strongest-derivative crossing if multiple.
• x_separation: first sign-change going downstream into the recirculation
• Integrated quantities (lift, drag, mass flow): from postProcessing/forces/<time>/forces.dat or equivalent
• Profile metrics (peak |U|, RMS): sample along a probe line; use pyvista.OpenFOAMReader for spatial sampling

The agent writes a single <group>/mesh_analysis.json with per-level QoI vectors.

Step 5 — Compute deltas (agent-driven, STEP E)

For each QoI:

delta_pct = 100 * |QoI_refined - QoI_baseline| / |QoI_baseline|

Classify:

• Converged: all QoIs change by less than qoi_tolerance_percent (5% default), and y+ stays in target range, and mesh quality on the refined mesh is acceptable. → SELECT BASELINE.
• Marginally not-converged: one QoI exceeds threshold by a small margin (≤ 2× threshold). → run a second refinement (refined_v2).
• Strongly not-converged: a QoI changes by ≥ 2× threshold or trend is monotone-divergent. → run refined_v2, fit Richardson extrapolation, compute GCI: