aerorare-studio 0.4.0

Open-source CFD workbench for hypersonic, reentry and rarefied-flow analysis (SU2 + SPARTA + Gmsh + ParaView orchestration)

AeroRare Studio

Open-source CFD workbench for hypersonic, atmospheric reentry and rarefied-flow / DSMC analysis. AeroRare Studio is not a solver: it orchestrates SU2 (continuum CFD), SPARTA (DSMC), Gmsh (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. 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.4.0 ("unsteady, turbulence, ionization & GUI depth")

v0.4.0 adds time-accurate and turbulent flows, an ionizing gas model, and brings the CLI-only features into the GUI:

• Unsteady flows — SU2 dual-time stepping + SPARTA transient sampling; aerorare timeseries extracts force-history FFT / Strouhal; a cylinder-shedding valcase (St≈0.28).
• RANS turbulence — Spalart-Allmaras / SST for viscous perfect-gas runs; a supersonic flat-plate-turbulent valcase agrees with the Eckert reference-temperature skin-friction correlation to ~5% (y+≈1, live SU2).
• Ionized & frozen chemistry — air-7 (weakly ionized, Gupta-Yos transport) and a frozen-chemistry (FROZEN_MIXTURE) option for NEMO.
• Derived visualization (§13) — gradient-length-local Knudsen number and a shock indicator computed from the SU2 volume (continuum-breakdown maps), plus the NEMO vibrational temperature.
• GUI depth — turbulence/unsteady/chemistry controls on the Physics page, 3D CAD patch splitting on the Geometry page, and a time-series frame animator on the Results page.

Earlier (v0.3.0): Smoluchowski-Maxwell slip walls and non/super-catalytic walls (NEMO) with slip and catalytic case studies; compression-ramp and nozzle templates; mesh quality report (§9.1), CAD patch splitting (§4.2), LaTeX report export (§16), aerorare compare, generate --restart-from. The Lofthouse heating band was closed as continuum-breakdown physics (missing temperature jump), 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.

Install

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:

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

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

python3 -m pytest tests/ -q