Metadata-Version: 2.4
Name: aeroprop-x
Version: 0.1.0
Summary: Open-source rocket nozzle design, Method-of-Characteristics solver, and aerothermodynamic performance analysis.
Author: Aryuemaan Chowdhury
License: MIT
Project-URL: Homepage, https://github.com/aryuemaan/aeroprop_X
Project-URL: Documentation, https://github.com/aryuemaan/aeroprop_X
Project-URL: Issues, https://github.com/aryuemaan/aeroprop_X/issues
Keywords: rocket,nozzle,method-of-characteristics,aerospace,gas-dynamics,propulsion,cfd
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Education
Classifier: License :: OSI Approved :: MIT License
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.22
Requires-Dist: scipy>=1.8
Provides-Extra: plot
Requires-Dist: matplotlib>=3.5; extra == "plot"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: matplotlib>=3.5; extra == "dev"
Provides-Extra: all
Requires-Dist: matplotlib>=3.5; extra == "all"
Dynamic: license-file

# AeroProp-X

**Open-source rocket nozzle design, Method-of-Characteristics (MOC) solver, and
aerothermodynamic performance analysis — in pure Python.**

AeroProp-X turns chamber conditions and a target expansion into a
mathematically-grounded converging–diverging (de Laval) nozzle contour. It
generates minimum-length MOC bells, Rao thrust-optimised bells, and conical
baselines; maps the supersonic flow field; analyses over/under-expansion and
flow separation; and exports CAD (CSV / DXF / FreeCAD-STEP) you can open in
Fusion 360, SolidWorks, or FreeCAD. No paywalled toolbox required.

> **Scope and honesty.** AeroProp-X models steady, inviscid, adiabatic,
> shock-free flow of a calorically-perfect gas. Results are **ideal
> preliminary-design estimates** — excellent for learning, sizing, and early
> trade studies, but not a replacement for CFD or hot-fire testing. Every
> approximation is documented in [`docs/theory.md`](docs/theory.md).

---

## Architecture

```
            ┌─────────────────────────────────────────────┐
            │     High-pressure combustion chamber (p0,T0) │
            └───────────────────────┬─────────────────────┘
                                    ▼
                          Converging section
                       (subsonic acceleration)
                                    │
                                    ▼
                          Throat  (M = 1, sonic)
                                    │
                                    ▼
              ┌──────────────── Diverging section ───────────────┐
              │           supersonic expansion, M > 1            │
              │                                                  │
              │   gasdynamics ──► moc ──► nozzle ──► flowfield   │
              │   (isentropic +   (char.   (MOC/Rao/  (Mach/p/T   │
              │    Prandtl-Meyer)  mesh)    conical)   field)     │
              └──────────────────────┬───────────────────────────┘
                                    ▼
                 performance  ──►  cad_export / plotting
            (C_F, c*, Isp, thrust,   (CSV / DXF / FreeCAD-STEP,
             expansion regime)        contour & flow-field figures)
                                    │
                                    ▼
                    Optimal contour: max thrust, shock-free,
                            uniform axial exit
```

> **Note on the original project brief.** The brief that seeded this repo
> contained pipeline labels copied from an unrelated speech/NLP template —
> "Linguistic & Acoustic Decomposition", "Neural Synthesis Module",
> "Linguistic/Acoustic Expansion Lane". Those concepts have no meaning in
> nozzle aerodynamics and are **not** implemented. The architecture above
> reflects the actual gas-dynamics pipeline.

---

## Installation

```bash
git clone https://github.com/your-org/aeroprop-x
cd aeroprop-x
pip install .            # core (numpy, scipy)
pip install .[plot]      # add matplotlib for figures
pip install .[dev]       # add pytest for the test-suite
```

Requires Python ≥ 3.9.

## Quick start (Python)

```python
from aeroprop_x import moc_nozzle, evaluate, to_freecad_macro

# 1. Minimum-length MOC contour for exit Mach 2.6, 40 mm throat radius.
contour = moc_nozzle(exit_mach=2.6, n_characteristics=80, throat_radius=0.04)
print(contour.area_ratio, contour.length, contour.meta["area_ratio_error"])

# 2. Ideal performance at 10 km (pa ~ 26.5 kPa).
perf = evaluate(exit_mach=2.6, p0=5e6, pa=26_500, gamma=1.4,
                R=287, T0=3000, throat_area=3.14159 * 0.04**2)
print(perf.report())          # C_F, c*, Isp, thrust, expansion regime

# 3. Export a FreeCAD macro that revolves the contour and writes STEP.
to_freecad_macro(contour, "nozzle.FCMacro")
```

## Quick start (CLI)

```bash
# Design a minimum-length MOC contour and save CSV + DXF + a PNG.
aeroprop-x design moc --exit-mach 2.4 --throat-radius 0.05 \
    --csv nozzle.csv --dxf nozzle.dxf --plot contour.png

# Design an 80% Rao bell from an area ratio.
aeroprop-x design bell --area-ratio 25 --throat-radius 0.05 --csv bell.csv

# Evaluate performance at altitude.
aeroprop-x analyze --area-ratio 25 --p0 7e6 --pa 26500 \
    --gamma 1.22 --R 320 --T0 3500 --throat-area 0.01

# Export an MOC design straight to a FreeCAD STEP macro.
aeroprop-x export moc --exit-mach 3.0 --throat-radius 0.04 --freecad nozzle.FCMacro
```

## What it does

1. **Nozzle contour generation.** A rigorous **planar minimum-length MOC**
   solver (sharp-corner centred expansion, shock-free wall cancellation),
   plus a **Rao thrust-optimised parabolic bell** and a **conical** baseline.
   Enter exit Mach *or* area ratio.
2. **Supersonic flow-field plotting.** Extract Mach, pressure, and temperature
   over the characteristic mesh and interpolate onto a regular grid for
   colour-mapped field plots.
3. **Expansion & separation analysis.** Classify perfectly / under / over-
   expanded operation against ambient pressure and flag likely flow separation
   (Summerfield criterion).
4. **CAD export.** Write CSV, ASCII DXF polylines, or a FreeCAD `.FCMacro`
   that revolves the contour to a solid and exports STEP for SolidWorks /
   Fusion 360 / FreeCAD.

## Repository layout

```
aeroprop-x/
├── src/aeroprop_x/
│   ├── gasdynamics.py     isentropic + Prandtl-Meyer relations
│   ├── moc.py             Method-of-Characteristics min-length solver
│   ├── nozzle.py          MOC / Rao bell / conical contour generators
│   ├── flowfield.py       mesh -> Mach/p/T field extraction & gridding
│   ├── performance.py     C_F, c*, Isp, thrust, expansion analysis
│   ├── cad_export.py      CSV / DXF / FreeCAD-STEP export
│   ├── plotting.py        contour, mesh, and field figures (matplotlib)
│   └── cli.py             `aeroprop-x` command-line interface
├── tests/                 pytest suite (gas dynamics, MOC, nozzle, perf)
├── examples/              quickstart.py, design_ssme_like.py
├── docs/theory.md         equations, derivations, assumptions
├── validation_cases/      comparison vs tables & historical engines
├── pyproject.toml         packaging + console-script entry point
├── CHANGELOG.md  CONTRIBUTING.md  LICENSE (MIT)
```

## Validation

- Isentropic and Prandtl–Meyer outputs match standard compressible-flow tables
  to table precision.
- The MOC solver self-tests: for planar flow the exit height ratio converges to
  the exact isentropic `A/A*` (relative error ≈ 3×10⁻⁴ at n = 160 for M = 2.4),
  the peak centreline Mach equals the design Mach, and the exit flow leaves
  parallel to the axis.

See [`validation_cases/README.md`](validation_cases/README.md) for the full
tables and reproduction commands.

## Key limitations (read before trusting a number)

- **Planar MOC.** The MOC solver is 2-D. Revolving its contour as axisymmetric
  overshoots the design area ratio by `√(A/A*)`; for accurate axisymmetric area
  ratios use `rao_bell`. A true axisymmetric MOC is on the roadmap.
- **Ideal gas, inviscid.** No boundary layers, finite-rate chemistry, heat
  transfer, or real-gas effects; Isp and thrust are ideal upper estimates.
- **Approximate defaults.** Rao wall angles are coarse chart interpolations;
  the Summerfield separation threshold is an engineering estimate.

## License

MIT — see [`LICENSE`](LICENSE). Contributions welcome; see
[`CONTRIBUTING.md`](CONTRIBUTING.md).

## References

Anderson, *Modern Compressible Flow* (MOC, minimum-length nozzle) · Sutton &
Biblarz, *Rocket Propulsion Elements* · Rao, "Exhaust Nozzle Contour for
Optimum Thrust" (1958).
