code/ezflow_v3/cfd/README.md

# ezflow_v2/cfd — OpenFOAM RANS data-generation pipeline

Generates the high-Re training dataset: parametric/ModelNet geometry → OpenFOAM
steady RANS k-ω-SST → per-case fields + QC metadata. Runs in WSL2 Ubuntu with
OpenFOAM v2512 (see `../../OPENFOAM_GUIDE.md` for the environment).

## Scripts

| Script | Role |
|---|---|
| `family_to_stl.py` | Build a normalized (max-extent L=1, centered) STL from a scripted family OR a ModelNet STL; computes the frontal (y-z) area for Cd. |
| `gen_dataset_jobs.py` | `calib` (80-case diverse subset) or `full` (~1350: 14 external families × 15 LHS + 240 ModelNet, each at 3 cases with **independent log-uniform Re ∈ [500,1e5]** + random yaw). Exports STLs + writes `manifest_*.csv`. |
| `of_produce_case.sh` | One case: STL → `surfaceFeatureExtract` + `snappyHexMesh` (feature capture + 4 boundary layers) → `simpleFoam` k-ω-SST → forceCoeffs + in-solver y⁺ → export `internal.vtu`+`boundary.vtm`+`meta.json` → delete raw case. Args: `cid source stl Aref Re yaw layers dataset_dir`. |
| `of_produce_batch.sh` | Parallel (N-wide), **resumable** driver over a manifest (skips cases with an existing `meta.json`), retries mesh failures with no layers, collects `results.csv`. Args: `manifest [maxjobs]`. |
| `of_external.sh` / `of_sphere.sh` | Generic single-STL case / unit-sphere cross-check (vs experiment & Kratos). |
| `of_export.sh`, `render_of.py` | foamToVTK export + pyvista off-screen figures. |
| `of_status.sh`, `of_cdcheck.sh` | Live monitoring (active cases, Cd stability). |
| `of_install.sh` | Install OpenFOAM v2512 in Ubuntu (reproducibility). |

## Conventions
- **Non-dimensional**: `U_inf=1`, `rho=1`, body `L_ref=1`, `nu=1/Re`. Air enters only at serving (see `gnn/fluids.py`).
- **QC / convergence gate** in `meta.json`: `converged_force` (1 if Cd std over last 100 iters < 2% of \|Cd\|), `cd_rel_drift`, `final_res_U/p`, `yplus_{min,max,avg}`. The ETL keeps only `converged_force==1`.

## Run (from WSL, repo at /mnt/c/dev/EZFlow)
```bash
# generate STLs + manifest (on Windows python: gmsh+trimesh)
python gen_dataset_jobs.py full manifest_full.csv
# run the sweep (in WSL; resumable). Output dir via $EZFLOW_DATASET_DIR or the default.
tr -d '\r' < of_produce_batch.sh > /tmp/b.sh && bash /tmp/b.sh manifest_full.csv 12
```

## Paths
Scripts currently default the dataset output to `C:\dev\ezflow_eval\dataset_of`
(`/mnt/c/...` in WSL). `of_produce_batch.sh` honors `$EZFLOW_DATASET_DIR`. STL +
manifest live in `C:\dev\ezflow_eval\` during generation. These are the working
copies; the live run is driven from `ezflow_eval` (scratch). After a sweep completes,
the dataset can be relocated to a permanent home (see `../docs/DATASET.md`).

> Hard-won gotchas baked in: isolate `$@` before `source`-ing the OpenFOAM bashrc
> (it sources `$1` as a settings file); compute y⁺ via the in-solver functionObject
> (generic `postProcess` can't load the turbulence model); strip CRLF from
> Windows-authored `.sh` (`tr -d '\r'`); solve in the Linux fs, not `/mnt/c`.