Metadata-Version: 2.4
Name: aerorare-studio
Version: 0.3.0
Summary: Open-source CFD workbench for hypersonic, reentry and rarefied-flow analysis (SU2 + SPARTA + Gmsh + ParaView orchestration)
Author: nsclk
License: MIT
Project-URL: Repository, https://github.com/nsclk/aerorare-studio
Project-URL: Changelog, https://github.com/nsclk/aerorare-studio/blob/main/DEVELOPMENT.md
Keywords: cfd,hypersonic,dsmc,su2,sparta,reentry,rarefied-gas,aerothermodynamics
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20
Requires-Dist: PyYAML>=5.4
Provides-Extra: mesh
Requires-Dist: gmsh>=4.11; extra == "mesh"
Provides-Extra: cad
Requires-Dist: cadquery>=2.4; extra == "cad"
Provides-Extra: gui
Requires-Dist: PySide6>=6.5; extra == "gui"
Requires-Dist: vtk<9.5,>=9.2; extra == "gui"
Provides-Extra: results
Requires-Dist: vtk<9.5,>=9.2; extra == "results"
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Dynamic: license-file

# AeroRare Studio

Open-source CFD workbench for **hypersonic**, **atmospheric reentry** and
**rarefied-flow / DSMC** analysis. AeroRare Studio is not a solver: it
orchestrates [SU2](https://su2code.github.io/) (continuum CFD),
[SPARTA](https://sparta.github.io/) (DSMC), [Gmsh](https://gmsh.info/)
(meshing) and ParaView/VTK (post-processing) behind a single physics-first
workflow. You describe the physical problem; the studio generates geometry,
meshes, solver input files, run commands and reports.

The full product concept is described (in Turkish) in
[`docs/hyperrare_studio_spec.md`](docs/hyperrare_studio_spec.md). This package is the
engine layer: every screen of the planned GUI maps onto a module here.

## Toolchain status (this machine)

All five external tools are installed and detected by `aerorare tools`:
SU2 8.0.0, SPARTA (24 Sep 2025, built from `../sparta-master`), Gmsh 4.14,
ParaView 5.11.2 (`pvpython` in the app bundle), Open MPI 5.0.8. Python side:
CadQuery 2.5.2 (bundled OCCT 7.7 kernel via OCP) and VTK 9.3.1; OCCT 7.9.3
(brew) and FreeCAD 1.x (`/Applications/FreeCAD.app`) for CAD work.

## Status — v0.3.0 ("slip-regime physics + scope")

v0.3.0 deepens the physics that is the product's niche and broadens the
template/report scope:

* **Slip walls** — Smoluchowski-Maxwell velocity-slip / temperature-jump
  walls (NEMO); a no-slip vs slip vs DSMC [case study](docs/slip_study.md)
  shows slip halving the continuum–DSMC heating discrepancy at Kn=0.01.
* **Catalytic walls** — non/partial/supercatalytic (NEMO); a
  [case study](docs/catalytic_study.md) shows supercatalytic heating
  +38.5% once dissociation is active (with the high-altitude frozen-flow
  finding documented).
* **New templates** — `compression-ramp` (SWBLI) and a `nozzle`
  internal-flow path (inlet/outlet, verified subsonic→supersonic).
* **Quality & reporting** — mesh quality report (§9.1), CAD surface
  patch splitting (§4.2), LaTeX report export (§16), an `aerorare
  compare` multi-run overlay, `generate --restart-from` warm starts.
* **GUI** — Validation page with a Generate+Run+Check pipeline and a
  live SPARTA field stream on the Run page.

The Lofthouse heating band was closed with a definitive finding:
refining the continuum wall *widens* the SU2–DSMC gap (it is
continuum-breakdown physics — missing temperature jump — not mesh
resolution), for which slip walls are the remedy.

Earlier hardening (v0.2.0): staged NEMO convergence (CFL ladder,
mesh-scaled budgets, post-run bow-shock gate), exact B-rep prism BL on
all four 3D templates, concave-corner BL handling, `generate --robust`.

| Concept (spec §) | Module | State |
|---|---|---|
| System check (§2) | `aerorare/tools.py` | ✅ detects SU2, SPARTA, Gmsh, ParaView, MPI |
| Project Setup (§3) | `aerorare/project.py` | ✅ project.yaml, folder layout, run versioning |
| Geometry Studio (§4) | `aerorare/geometry.py` | ✅ parametric 2D/axisymmetric templates (blunt cone, capsule, sphere, cylinder, wedge, flat plate); CAD import planned |
| Geometry Health Check (§5) | `Contour.health_check` | ✅ basic checks |
| Boundary Assignment (§6) | `aerorare/boundaries.py` | ✅ types, auto-detection, consistency check, colour legend |
| Physics Wizard (§7) | `aerorare/freestream.py`, `aerorare/atmosphere.py`, `aerorare/gas.py` | ✅ US76 atmosphere, altitude & direct modes, gas models |
| Regime Selector (§8) | `aerorare/regime.py` | ✅ Kn bands, solver recommendation, override warnings |
| Mesh Studio (§9) | `aerorare/meshing.py`, `aerorare/sparta.py` | ✅ mesh plan + Gmsh .geo + SU2 mesh; DSMC grid plan w/ λ checks |
| Solver Setup (§10) | `aerorare/su2.py`, `aerorare/sparta.py` | ✅ SU2 .cfg and SPARTA input generation |
| Case Validation (§11) | `aerorare/validation.py` | ✅ Ready/Warning/Error gate |
| Run Monitor (§12) | `aerorare/runner.py` | ✅ `aerorare run`: MPI launch + live residual/particle tracking |
| Results Viewer (§13) | `aerorare/postprocess.py` | ✅ pvpython offscreen contours (percentile-clamped, body-framed) + dependency-free SVG wall/convergence plots |
| Comparison Studio (§14) | `results.compare_surfaces` | ✅ common arc-length resampling, % differences, overlay plots |
| Common Result Model (§15) | `aerorare/results.py` | ✅ SU2 CSV/VTU + SPARTA dump parsers → shared surface/volume model |
| Report Generator (§16) | `aerorare/report.py` | ✅ Markdown case report |
| 3D geometries (§4) | `aerorare/geometry3d.py` | ✅ CadQuery solids (sphere, blunt cone, capsule, cone-cylinder), revolve-from-contour, STL export, watertight check |
| CAD import (§4.2) | `aerorare/cad.py` | ✅ STEP/IGES/BREP/STL/OBJ, unit scaling, health report |
| SPARTA 3D | `sparta.write_surface_file_3d` etc. | ✅ triangle surfaces + 3D grid plan + input (verified with a live 3D run) |
| SSH / SLURM environments (§12) | `aerorare/hpc.py` | ✅ `aerorare env` + remote stage/submit/fetch, sbatch generation |
| Desktop GUI | `aerorare/gui.py` | ✅ MVP: PySide6, software-rendered geometry viewport, clickable boundary assignment (§6 colour legend), workflow sidebar, live run log, results gallery (`aerorare gui`) |
| SU2 NEMO (§7.2) | `su2.py` (`--thermal two-temperature`) | ✅ AIR-5 two-temperature configs patterned on SU2's nonequilibrium test cases; NEMO_EULER verified converging on SU2 8.0.0 |
| 3D SU2 mesh from STEP | `meshing.py` (`MeshPlan3D`) | ✅ gmsh OpenCASCADE boolean (STEP body − sphere farfield), body/farfield markers, distance-field refinement; verified with a live 3D SU2 run |
| 3D boundary-layer inflation | `blmesh.py` (`generate --bl`) | ✅ prism layers via gmsh `extrudeBoundaryLayer` (smooth bodies; sharp edges fall back to isotropic); hybrid prism+tet mesh verified in SU2 |
| 3D results (§13–15) | `results.py` 3D loaders | ✅ meridional collapse (x, r → s) + azimuthal averaging, slice/surface pvpython renders, SU2-vs-SPARTA comparison on the meridian |
| HTML/PDF reports (§16) | `report.py` (`report --format html/pdf`) | ✅ dependency-free MD→HTML with figures embedded (base64/inline SVG); PDF via Qt QPdfWriter |
| Geometry auto-repair (§5) | `geometry3d.repair_mesh` (`new --repair`) | ✅ duplicate removal, winding fix, small-hole fill |
| Docker environment (§12) | `hpc.docker_command` (`env --kind docker`) | ✅ containerised runs with live monitoring (command-generation tested; docker not installed here) |
| Restart flows | `generate --restart` | ✅ SU2 RESTART_SOL + staged 2nd-order upgrade; SPARTA read_restart continuation (verified live) |
| Analysis tools (§13.3) | `analysis.py` (`aerorare analyze`) | ✅ stagnation region, shock stand-off vs Billig, centerline probes |
| Mesh Studio GUI | `gui.py` Mesh page | ✅ plan editor with persisted overrides + live residual/particle charts |

Development history and roadmap: [DEVELOPMENT.md](DEVELOPMENT.md).

## Install

```bash
cd aerorare_studio
python3 -m pip install -e ".[dev]"       # engine + tests
# optional external tools:
#   gmsh     -> mesh generation      (brew install gmsh / pip install gmsh)
#   SU2      -> continuum solver     (https://su2code.github.io/download.html)
#   SPARTA   -> DSMC solver          (https://sparta.github.io/download.html)
```

### Building SPARTA from source (macOS)

The vendored tree in `../sparta-master` builds with CMake; clang/libc++
needs the C++11 hash-map flag:

```bash
cd ../sparta-master && mkdir -p build install && cd build
cmake -DCMAKE_INSTALL_PREFIX=../install -DBUILD_MPI=ON \
      -DCMAKE_CXX_FLAGS="-DSPARTA_UNORDERED_MAP" ../cmake
make -j8 && make install
ln -sf "$PWD/../install/bin/spa_" /opt/homebrew/bin/spa_
```

The studio locates SPARTA's species/VSS data files (`air.species`,
`air.vss`, ...) next to the executable or via `$SPARTA_DATA_DIR`, and
copies them into each run directory.

### Doc-compliance notes (validated against the vendored sources)

* **SPARTA** — generated inputs follow the manual and the `examples/axi`
  case: `boundary oo ar pp` + box `ylo=0` + `global ... weight cell radius`
  for axisymmetric models (manual §6.2); surface files obey the `read_surf`
  right-hand orientation rule (outward normal `N = z × (p2−p1)`) and the
  watertight rule (endpoints exactly on a box edge — near-axis points are
  snapped to `y=0`); open profiles ending off-axis are auto-closed at the
  base. Dump columns use `xlo/ylo/xhi/yhi` (there is no `xc/yc`).
* **SU2** — every emitted option exists in `SU2-master/config_template.cfg`;
  viscous cases set `INIT_OPTION= TD_CONDITIONS`, `FREESTREAM_OPTION=
  TEMPERATURE_FS` plus `REYNOLDS_NUMBER` (required by SU2 8.x for
  NAVIER_STOKES). Verified by running SU2_CFD 8.0.0 on a generated case.
* **Gmsh** — `.geo` scripts use OpenCASCADE factory + `Physical Curve`
  groups whose names become SU2 markers via `gmsh -2 -format su2`.
  Verified with Gmsh 4.14 (markers arrive in the `.su2` mesh intact).

## Quick start — Mach 15 blunt-body reentry at 80 km

```bash
aerorare tools                                  # check SU2/SPARTA/Gmsh/MPI
aerorare new reentry --template blunt-cone \
    --param nose_radius=0.05 --param half_angle_deg=15 --param length=0.3
aerorare physics reentry --mach 15 --altitude 80000 --wall-temp 1000
aerorare regime reentry                         # -> slip regime, su2+sparta
aerorare generate reentry --quick               # coarse preview setup (drop --quick for production)
aerorare validate reentry                       # pre-run gate
aerorare run reentry --ranks 4                  # SU2 + SPARTA with live monitoring
aerorare results reentry                        # contour PNGs, wall SVGs, SU2-vs-SPARTA comparison
aerorare report reentry                         # reports/case_report.md
```

With the full toolchain the quick demo takes ~20 s of solver time and
produces, under `results/run_NNN/`: ParaView Mach/pressure/temperature/
density contours framed on the body, SU2 wall pressure / heat-flux / Cp and
convergence plots, SPARTA wall distributions, overlaid SU2-vs-SPARTA
comparison charts and a `comparison.md` with mean/max percentage
differences.

Everything needed to reproduce a case lives in `project.yaml`; each
`generate` allocates a fresh `solvers/run_NNN/` so earlier setups are kept.

## Tests

```bash
python3 -m pytest tests/ -q
```
