🚀 TensorAeroSpace

Open-source aerospace simulation toolkit + adaptive control catalogue

Pure-NumPy 6-DoF dynamics · Gymnasium-native envs · Classical / ADP / Deep RL agents

📖 Documentation • 🚀 Quickstart • 💡 Examples • 🤝 Contributing

📑 Contents

• 🌟 Overview
• 📊 How it compares
• 🧭 Application areas
• 🚀 Quickstart
• 🤖 Supported algorithms
• ✈️ Aircraft & spacecraft library
• 🎮 Simulation environments
• 📚 Examples & guides
• ⚠️ Known limitations
• 🛠️ Development
• 🎓 How to cite
• 📖 Documentation
• 🤝 Community & support
• ⭐ Star history
• 📄 License

🌟 Overview

TensorAeroSpace ships 12+ aircraft and spacecraft models (7 of them as full nonlinear 6-DoF airframes with peer-reviewed source data), 20+ control algorithms spanning classical PID/MPC through the full incremental-ADP family to modern deep RL, and 100+ runnable example notebooks covering trim, cruise, coordinated turns, in-flight damage and fault recovery — all glued together by the standard Gymnasium API.

Why it stands out:

• 🎯 Real airframes, not toys. B-747 transcribed from NASA CR-2144, X-15 from NASA TM X-1669, Skywalker X8 from CEAS Aeronautical Journal 2025, B-737 from JSBSim + Roskam, RQ-7 Shadow from Beard & McLain. Trim-points reach machine precision.
• ⚡ Pure NumPy core. No proprietary simulators, no MATLAB licence, no compiled binaries — lightweight for control-synthesis sweeps with no startup overhead or XML parsing.
• 🧠 Unique adaptive-control catalogue. Standard RL stack (PPO, SAC, DDPG, DQN, A2C, A3C, GAIL) plus the full incremental-ADP family (IHDP, IM-GDHP, ET-DHP, iADP, AA-INDI, AIDI) — rarely co-located in a single OSS package.
• 💥 Damage subsystem built-in. Per-surface effectiveness loss, hard-overs, jam events, asymmetric-thrust engine-out, flap-jam configuration override — all composable into DamageProfile instances.
• 🧪 Locked down by regression coverage. Trim convergence, surface-deflection sign conventions, propellant burnout times — all under unit tests.
• 🤗 Hugging Face Hub native. All PyTorch agents inherit from_pretrained / publish_to_hub from tensoraerospace.agent.base — pretrained checkpoints live at huggingface.co/TensorAeroSpace.

📊 How it compares

How TensorAeroSpace positions against the tools control engineers and RL researchers usually reach for:

Pick TensorAeroSpace when you need a single Python package that ships realistic airframes and the controllers to fly them — including online adaptive critics rarely co-located in any other OSS toolkit.

🧭 Application areas

1. Automatic flight control — stabilisation, trajectory tracking, attitude control for aircraft, UAVs, experimental vehicles.
2. Rocket / spacecraft control — launch vehicles, satellites in different orbital classes, ascent-trajectory optimisation.
3. Hybrid control synthesis — designing and tuning loops that combine classical and intelligent methods.
4. Algorithm benchmarking — automated hyperparameter search, head-to-head comparisons, metric visualisation.
5. Simulator integration — game engines (Unity ML-Agents), CAD/CAE (Simulink, SimInTech), bidirectional model exchange.
6. Reliability and FTC research — failure-mode studies, controller-reconfiguration assessment, dataset preparation.

Each area has working examples and documentation (see 📚 Examples & guides).

🚀 Quickstart

💡 Interactive walkthrough: open quickstart.ipynb to run a SAC benchmark on the B-747 end-to-end in Jupyter / VS Code.

✅ System requirements

📦 Installation

Poetry (recommended)

git clone https://github.com/tensoraerospace/tensoraerospace.git
cd tensoraerospace
poetry install
eval $(poetry env activate)  # activate the venv
poetry run pytest   # quick smoke test

pip

pip install tensoraerospace                  # core (NumPy, gymnasium, PyTorch)
pip install 'tensoraerospace[ray]'           # + Ray RLlib for distributed training

Additional development environments are exposed as Poetry groups (used when working from a clone):

Combine groups: poetry install --with dev,jupyter reproduces the CI environment used by notebooks-smoke.yml.

🐳 Docker

Image launches JupyterLab by default (see Dockerfile).

docker pull ghcr.io/tensoraerospace/tensoraerospace:latest
docker run --rm -it -p 8888:8888 \
  -v "$(pwd)/projects:/workspace/projects" \
  ghcr.io/tensoraerospace/tensoraerospace:latest

# GPU (NVIDIA Container Toolkit)
docker run --rm -it --gpus all -p 8888:8888 \
  -v "$(pwd)/projects:/workspace/projects" \
  ghcr.io/tensoraerospace/tensoraerospace:latest

🏃‍♂️ Quick example — PID + linear F-16

import gymnasium as gym
import numpy as np
from tensoraerospace.agent.pid import PID
from tensoraerospace.utils import generate_time_period
from tensoraerospace.signals.standard import unit_step

dt = 0.01
tp = generate_time_period(tn=10, dt=dt)
N = len(tp)
reference = unit_step(degree=5, tp=tp, time_step=100, output_rad=True).reshape(1, -1)

env = gym.make('LinearLongitudinalF16-v0',
               number_time_steps=N, initial_state=[[0], [0]],
               reference_signal=reference, use_reward=False)
pid = PID(env, kp=-14.290, ki=-8.240, kd=-1.299, dt=dt)
# Tip: skip the magic numbers and let the autotuner find them
#      pid = PID(env, dt=dt); pid.tune_matlab_style()

obs, _ = env.reset()
for t in range(N - 1):
    u = pid.select_action(reference[0, t], float(obs[0]))
    obs, *_ = env.step(np.array([[float(u)]], dtype=np.float32))

💥 In-flight damage modelling

Compose damage events declaratively, run any controller — agent sees a different plant the moment the event fires.

import numpy as np
from tensoraerospace.aerospacemodel.f16.nonlinear.damage import WING_STRIKE_LEFT_TIP
from tensoraerospace.envs.f16.nonlinear_angular import NonlinearAngularF16

env = NonlinearAngularF16(
    initial_state=np.zeros(14),
    number_time_steps=2000,
    damage_profile=WING_STRIKE_LEFT_TIP,  # left-tip loss at t=10s
    split_stab=True,                      # split stabilator into left/right halves for asymmetric damage
)
obs, _ = env.reset()
for _ in range(2000):
    obs, r, term, trunc, info = env.step(np.zeros(4))
    if info.get("damage_events_triggered"):
        print(info["damage_events_triggered"])  # → ['left_tip_full_loss']

What's modelled: section loss (mass / S / b / MAC / c.g. / inertia tensor / aero coefficients all recomputed via Huygens-Steiner), surface failure (jam / efficiency loss / lost), engine flameout (partial / full thrust scaling), structural events (payload drop, icing, Δm / Δc.g. / ΔJ).

📖 Aircraft damage modelling guide

🤖 Supported algorithms

Classical control

Deep RL — on-policy

Deep RL — off-policy

Imitation learning

Adaptive Dynamic Programming (model-based critics)

Online adaptive critics for fault-tolerant flight

✈️ Aircraft & spacecraft library

🛩️ Fixed-wing (nonlinear 6-DoF, peer-reviewed source data)

🪶 Linear longitudinal models

• F-4C Phantom II (LongitudinalF4C) — military fighter-bomber, Roskam-derived linear longitudinal channel + improved env wrapper.
• Other linear plants — LongitudinalF16, LongitudinalB747, LongitudinalX15, LongitudinalUAV, LongitudinalCessna170, LongitudinalSuperSonic — live alongside their nonlinear counterparts; see 📊 State-space matrices for classical synthesis.

🚁 UAVs and drones

• LAPAN LSU-05 — Indonesian surveillance UAV
• Ultrastick-25e — RC airplane model
• Generic UAV — customisable state-space dynamics
• Quadrotor — full nonlinear 6-DoF + per-rotor damage subsystem + X-config allocator

🚀 Rockets and satellites

• ELV (Expendable Launch Vehicle) — booster dynamics
• Generic missile — customisable simulation
• GeoSat — geostationary orbital mechanics
• ComSat — communication-satellite dynamics and control

🎮 Simulation environments

🎯 Unity ML-Agents integration

• 🎮 3D visualisation in real time
• 🔄 Realistic training — agents learn in physics-rich scenes
• 📊 Sensor suite — camera, LiDAR, physical sensors
• 🌍 Custom scenarios — author your own aerospace tasks

📁 Example environment: UnityAirplaneEnvironment

🔧 MATLAB / Simulink integration (experimental)

What ships today:

• 📦 Reference Simulink models under tensoraerospace/aerospacemodel/simulinkModel/ — F-4C and X-15 plant models in .slx format for cross-validating Python implementations.
• 🎛️ MATLAB-style PID autotuning — the PID.tune_matlab_style() API extracts (A, B, C, D) from any linear env and runs differential-evolution gain optimisation. See example/pid_controllers/pid_matlab_tuning.ipynb.
• 📚 Hands-on lessons — Lesson 4: MATLAB scripting and Lesson 5: Simulink models walk through the import / validation workflow.

Status: Simulink interop is community-maintained — model parsing helpers live in the lessons rather than being a turnkey importer. PRs welcome.

📊 State-space matrices for classical synthesis

Linear plant models expose (A, B, C, D) for direct use with classical-control workflows:

• 🧮 LongitudinalF16 (f16/linear/longitudinal/) — F-16 short-period + phugoid
• 🪶 LongitudinalF4C, LongitudinalB747, LongitudinalX15, LongitudinalUAV, LongitudinalCessna170, LongitudinalSuperSonic — extra peer-validated linear plants under tensoraerospace/aerospacemodel/
• 🎛️ PID.tune_matlab_style(env) — autotunes gains against the env's state-space matrices via differential-evolution against a step-response criterion

📚 Examples & guides

The example/ directory ships 100+ runnable notebooks, organised by controller class. The folder was recently restructured for predictable navigation — see example/README.md for the full map.

🌟 Featured examples

Quick run commands

# Run pretrained SAC on B-747
poetry run python example/reinforcement_learning/deep_rl/sac-b747-render.py --render --dt 0.1

# Run pretrained DDPG
poetry run python example/reinforcement_learning/deep_rl/ddpg-b747-render.py --repo TensorAeroSpace/ddpg-b747

# Train DSAC step-response
poetry run python example/reinforcement_learning/deep_rl/train_dsac_b747_step_response.py

📖 Detailed walkthroughs:

• Example SAC F-16
• B-737 coordinated turn (IHDP)
• B-747 engine-out heading hold (ET-DHP)
• Optuna optimisation
• Unity guide

⚠️ Known limitations

We are deliberate about scope — calling out what's intentionally not modelled prevents users wasting time on edge cases the project does not yet cover.

• 🚀 X-15 — atmospheric envelope (M = 0.4–6.7, h ≤ 250 kft) only. Exoatmospheric attitude control via peroxide RCS thrusters is not modelled.
• ✈️ B-737 — clean cruise envelope only. High-lift devices (flaps, slats, gear) have coefficient hooks but values are not yet applied.
• 💥 Damage subsystem coverage:
  • F-16 nonlinear — fully covered (sections, surfaces, engine, structural).
  • B-747 nonlinear — engine flameout + flap-jam events; no section-loss or icing.
  • Other airframes (B-737, X-15, Skywalker X8, AAI Shadow, Quadrotor) — engine / per-rotor failures only; no aero / mass / inertia recomputation.
• 🔧 Simulink interop — community-maintained: reference .slx plants ship for cross-validation, but there is no turnkey Simulink → Python importer yet.
• 🛰️ Spacecraft envs (ELV, GeoSat, ComSat, Generic missile) — basic dynamics only; no atmospheric re-entry, no orbit perturbations beyond two-body.
• 🎮 Unity ML-Agents bridge — lives in a separate repo and requires manual scene setup; no automated CI for that interaction layer.

PRs filling any of these gaps are warmly welcome — see CONTRIBUTING.md.

🛠️ Development

git clone https://github.com/tensoraerospace/tensoraerospace.git
cd tensoraerospace
poetry install --with dev
poetry run pytest                      # full suite
poetry run pytest tests/aerospacemodel # specific category
poetry run mkdocs serve -a 0.0.0.0:8000 # docs preview

See CONTRIBUTING.md for guidelines.

🎓 How to cite

If TensorAeroSpace contributed to your research or product, please cite it:

@software{tensoraerospace,
  title  = {TensorAeroSpace: Open-source aerospace simulation toolkit and adaptive control catalogue},
  author = {{TensorAeroSpace contributors}},
  year   = {2026},
  url    = {https://github.com/TensorAeroSpace/TensorAeroSpace},
  note   = {Pure-NumPy 6-DoF dynamics, Gymnasium-native environments, classical / ADP / Deep RL agents}
}

Plain-text form: TensorAeroSpace contributors. (2026). TensorAeroSpace: Open-source aerospace simulation toolkit and adaptive control catalogue. https://github.com/TensorAeroSpace/TensorAeroSpace

📖 Documentation

• 📚 Full docs: tensoraerospace.readthedocs.io
• 🚀 API reference: detailed module-by-module
• 📝 16-recipe cookbook: from hello-world to FTC under damage
• 💡 11-lesson tutorial: state-space → controllability → RL fundamentals → XFLR5 / Simulink hands-on
• 🤗 Pretrained agents on Hugging Face: huggingface.co/TensorAeroSpace — SAC / DDPG / PPO checkpoints. Load via Agent.from_pretrained("TensorAeroSpace/<repo>") in Python, or pass --repo TensorAeroSpace/<name> to the bundled render scripts (e.g. ddpg-b747-render.py).
• ❓ Q&A: DeepWiki AI assistant

🤝 Community & support

• 💬 GitHub Discussions
• 🐛 Issue tracker

⭐ Star history

📄 License

MIT — see LICENSE.

🙏 Acknowledgements

• The Gymnasium / OpenAI Gym team for the canonical RL environment API
• The Unity ML-Agents team for 3D simulation infrastructure
• The aerospace research community for decades of open published derivative data (sources cited inline in the aircraft library)
• Every contributor who has made this project possible