csml-rpi/ai-cfd-scientist/cfd-cross-analyze

cfd-cross-analyze

⚠ HARD STOP — read this before any other step

If <out-dir>/checkpoints/analysis_done.json AND <out-dir>/checkpoints/paper_experiment_plan_done.json do not both exist, STOP. The orchestrator chain enters this skill only after cfd-analyze and cfd-paper Stage 0 have completed. Stage 0 may propose additional cases that this skill compares against; running cross-analysis before Stage 0 produces comparison figures on an incomplete case set. Return to Skill cfd-orchestrator (or Skill cfd-skills/cfd-analyze), then come back.

cfd-paper writes the manuscript; cfd-cross-analyze produces the cross-case quantitative evidence the manuscript discusses. This skill mirrors the LangGraph workflow's analysis_agent.run_cross_experiment_data_processing + _interpret_cross_experiment_outputs. The agent (you) authors Python scripts that read every PROCEED case via PyVista or sampled CSVs, computes cross-case metrics, generates publication-quality plots, and interprets them through a vision-LLM pass.

Step 0 — Preflight gate (HARD; slice 14)

Before reading any case or authoring any script:

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

If rc != 0, STOP. The script requires analysis_done and paper_experiment_plan_done (Stage 0 of cfd-paper) to be on disk first. The Stage-0 plan tells this skill which cases (existing + newly proposed) are in scope — running cross-analysis before Stage 0 means producing comparison figures on a possibly-incomplete case set, exactly the failure mode that produced an H12 "only 1 figure type" gate trip.

Without this skill running, papers produced by cfd-paper will only contain per-case PyVista contours and a metrics table — no Cf-overlay-vs-reference, no RMSE bar charts, no parametric-trend plots, no Δ-field comparisons. Those are exactly the figures that justify a paper's claims.

When to use

After cfd-experiment (the full set of cases for the study) and cfd-analyze (per-case metrics), and before cfd-paper. Required for routes 1, 2, 6 (any route that produces a paper) when:

• The study compares ≥ 2 cases on a shared QoI (sensitivity studies, code-mod baseline-vs-modified, parametric sweeps, OED candidate ranking).
• Reference data exists (DNS / experiment / correlation) AND the topic asks for comparison against it.
• A primary claim of the topic is quantitative ("model X reduces error by N%", "x_r/h matches DNS within Y%").

If none of these apply (single-case demonstration with no comparison QoI), you can skip — but document the skip in the timeline.

Inputs

• out-dir (required) — must contain cases/case_*/ with run_result.json and decision.json (each case must be PROCEED), plus analysis.json.
• Optional: <out-dir>/reference_data_manifest.json or <out-dir>/<reference_csv> for any reference dataset to overlay against.
• Optional: <out-dir>/selected_mesh_spec.json (so cross-case plots note which mesh level was used).
• Optional: topic (string) — used to decide which cross-case figures matter for THIS paper. If not passed, read from <out-dir>/state.json#topic.

Outputs

All under <out-dir>/cross_experiment_analysis/:

cross_experiment_analysis/
├─ case_context.json                 deterministic per-case context (numerics, mesh, BC, model)
├─ case_context_normalized.json      LLM-summarized per-case context for cross-comparison
├─ planner_objectives.json           {needs_processing, objectives[], rationale}
├─ scripts/
│  ├─ attempt_01_script.py           agent's first Python attempt
│  ├─ attempt_02_script.py           (any retries; max 10)
│  └─ final_script.py                successful one (also copied here)
├─ aggregate.csv                     per-case metric table (rows = cases, cols = QoIs)
├─ data_processing_report.md         what was computed + any UNRESOLVED notes
├─ *.png                             cross-experiment plots (the figures cfd-paper will use)
└─ cross_experiment_interpretation.md vision-LLM interpretation written for the writer

Recipe (primary, agent-driven)

Step 1 — Build the case inventory + deterministic context

For each PROCEED case under cases/case_*/:

1. Read run_result.json (case_solver, wall_time_s, loop_count).
2. Read decision.json (must have status: PROCEED; cases with RERUN or REVISE are excluded).
3. Read <case_dir>/system/controlDict for application + endTime + writeInterval.
4. Read <case_dir>/constant/momentumTransport (or turbulenceProperties) for the active model + coefficients.
5. Read <case_dir>/constant/transportProperties (or physicalProperties) for nu / rho / EOS info.
6. Read <case_dir>/0/U, <case_dir>/0/p for boundary conditions (just the structure, not full data).
7. Read <case_dir>/constant/polyMesh/owner size for cell count.

Persist everything as cross_experiment_analysis/case_context.json (one entry per case). This is the authoritative metadata source for the script.

Step 2 — Normalize case contexts via LLM

For each case context entry, ask the LLM (using cfd_langgraph model) to produce a normalized summary that flags inconsistencies and resolves any ambiguous values (e.g., U_inf might appear in different forms across cases — pick one canonical form per case, with provenance).

Write to cross_experiment_analysis/case_context_normalized.json. The normalized version is non-authoritative — case_context.json remains source-of-truth; the script must cross-check the two.

Step 3 — Decide cross-experiment objectives

System prompt (mirrored from LangGraph analysis_agent.run_cross_experiment_data_processing planner)

You are a CFD cross-experiment data-processing planner.
Given topic + experiment requirements + available artifacts, decide whether additional quantitative post-processing is needed beyond image-based interpretation.
Examples: trend/correlation plots, regression fits, summary tables, derived metrics, error decomposition, parametric scaling, Δ-field comparisons.
For mesh independence / baseline-vs-refined style comparisons, plan work that uses the final written timestep in each case (same nominal endTime); do not require QoIs aggregated over all intermediate times unless the study is explicitly transient.
Return ONLY JSON with keys:
  needs_processing (bool)
  objectives (list[str]): each is one short imperative ("compute Cf vs x/h overlay across all cases including DNS", "produce RMSE bar chart", "fit β vs Re trend if applicable", "Δ-nut contour modified − baseline")
  rationale (str): why these objectives, why not others

User prompt template

Study topic:
{topic}
 
Experiment manifest (per-case context):
{case_context_json}
 
Normalized case context (LLM summary):
{case_context_normalized_json}
 
Reference data available:
{reference_data_summary}
 
Decide which cross-experiment quantitative post-processing is needed for stronger analysis/paper evidence.

Persist response as cross_experiment_analysis/planner_objectives.json. If needs_processing: false AND the topic is genuinely single-case-with-no-comparison, skip to Step 6 with an empty interpretation. Otherwise continue.

Step 4 — Author the cross-experiment Python script

This is the heart of the skill. The agent writes ONE Python script that loads every case and produces all the figures in objectives[]. Use the embedded prompt below verbatim.

System prompt (verbatim from LangGraph analysis_agent.run_cross_experiment_data_processing script-writer)

You write robust Python post-processing scripts for CFD cross-experiment analysis.
Return ONLY raw Python code (no markdown).
 
Script requirements:
- Read available experiment artifacts from the manifest.
- Use case_context.json / normalized context as authoritative metadata inputs.
- Do not invent physical constants or defaults (e.g., U_bulk, nu, rho, Re).
- For every quantity used in computation, resolve from case_context first and cite source path in the report.
- If required values are missing/inconsistent, mark that metric as UNRESOLVED and explain why in the report.
- Parse configuration with a model-aware source-of-truth policy instead of assuming one fixed dictionary.
- Automatically discover and read all relevant case configuration artifacts for physics, numerics, mesh, forcing/boundary driving, model selection, and experiment metadata/verification context.
- Determine the authoritative location of model parameters from the active model family and study mode, and cross-check against supporting dictionaries and metadata before extracting coefficients.
- Validate consistency of key controls that can be duplicated across files (e.g., driving conditions, target parameters, model activation) and report any mismatch explicitly before computing comparisons.
- For OpenFOAM field-based comparisons (e.g. mesh refinement, two cases same physics), load each case at its **latest/final write time** only for scalar QoIs and difference maps used in convergence checks; assume both runs share the same endTime unless manifest shows otherwise — do not integrate metrics across all saved timesteps unless an objective explicitly asks for transient analysis.
- Compute requested cross-experiment metrics/trends only when data is available.
- Save outputs under output_dir: (1) data_processing_report.md, (2) aggregate.csv, (3) one or more plot PNGs per objective.
- Be defensive: if some files are missing, continue with available data and explain limitations in report.
- Prefer PyVista for reading OpenFOAM case data/fields when needed (do NOT depend on ParaView GUI).
- Any matplotlib or PyVista PNGs intended for the paper: large fonts (ticks >= 14–18 pt, titles/labels >= 18–22 pt), no colorbar or legend overlapping data (use tight_layout with padding, horizontal colorbar, bbox_to_anchor for legends, or PyVista scalar_bar_args position/size).
- NumPy integration: use `np.trapezoid(y, x)` (NumPy 2+) or `getattr(np, "trapezoid", np.trapz)(y, x)` — do not call `np.trapz` alone (removed in NumPy 2.0).
- For 2D contour plots of elongated domains (e.g. channel flow), match figure or window aspect to domain extents so the channel is not a thin line.
- Exit 0 on success.
 
JOURNAL-QUALITY MATPLOTLIB STYLING (HARD — audit gate H30 catches under-styled PNGs):
 
Begin the script with the following rcParams block so every plot inherits publication styling:
 

import matplotlib matplotlib.use("Agg") import matplotlib.pyplot as plt plt.rcParams.update({ "figure.figsize": (8.0, 5.5), "figure.dpi": 180, "savefig.dpi": 180, "savefig.bbox": "tight", "savefig.pad_inches": 0.15, "font.size": 14, "axes.titlesize": 16, "axes.labelsize": 16, "xtick.labelsize": 13, "ytick.labelsize": 13, "legend.fontsize": 12, "legend.frameon": True, "legend.framealpha": 0.92, "axes.grid": True, "grid.alpha": 0.3, "lines.linewidth": 2.0, "lines.markersize": 7, "axes.spines.top": False, "axes.spines.right": False, })