Installation

Get TensorAeroSpace running in 60 seconds — from pip install to a converged trim point.

TL;DR

pip install tensoraerospace
python -c "import tensoraerospace; from tensoraerospace.aerospacemodel.b747.nonlinear import trim; r = trim(altitude_ft=20_000.0, V_ft_s=674.0); print(f'B-747 trim residual = {r.residual:.2e}, converged = {r.converged}')"
# → B-747 trim residual = 8.66e-14, converged = True

---

System requirements

Component	Minimum	Recommended
OS	Linux x86_64, Windows 10, macOS 13	Ubuntu 22.04 LTS / Windows 11 / macOS 14
Python	3.10	3.11 or 3.12
CPU	4 cores, AVX	8+ cores, AVX2 / FMA
RAM	8 GB	16–32 GB for RL training
Disk	2 GB	5 GB (PyTorch wheels + checkpoints)
GPU (optional)	—	NVIDIA RTX with ≥ 8 GB VRAM, CUDA 12.2
MATLAB (optional)	—	R2022b+ for the Simulink-bridge example
Unity (optional)	—	2021.3.5f1 / 2023.2.20f1 for the Unity ML-Agents bridge

Why these constraints? PyTorch wheels on PyPI bundle compiled CUDA kernels and require AVX. The published nonlinear airframe models (B-747, X-15, B-737) integrate at dt = 0.01 s with an RK4 integrator — a single 60 s episode runs in under 1 second on a modern laptop, so heavy hardware is only needed for RL training, not for control synthesis.

:material-python: Python	Status	Notes
3.10		Minimum supported
3.11		Recommended
3.12		Recommended for latest PyTorch
3.13		Experimental — some optional deps may lag
≤ 3.9		Unsupported (uses 3.10+ syntax)

---

Quick install (PyPI)

pippoetrycondauv

pip install -U pip setuptools wheel
pip install tensoraerospace

Recommended for projects that want lockfile-pinned dependencies:

poetry add tensoraerospace

conda create -n tas python=3.11 -y
conda activate tas
pip install -U pip setuptools wheel
pip install tensoraerospace

Fast modern alternative to pip:

uv venv --python 3.11
source .venv/bin/activate     # Windows: .venv\Scripts\activate
uv pip install tensoraerospace

Wheel size

The wheel itself is small (~ 5 MB) but pulls in PyTorch (~ 800 MB), Gymnasium, NumPy, SciPy, matplotlib. First install takes 1–3 minutes depending on bandwidth.

---

Verify the installation

Run the three checks below — they cover (1) Python imports, (2) Gymnasium env registration, and (3) numerical correctness of the trim solver.

1. Module import

python -c "import tensoraerospace as tas; print('TensorAeroSpace', tas.__version__, 'OK')"

Expected: TensorAeroSpace 0.3.x OK (no traceback).

2. Env registry

import gymnasium as gym
import tensoraerospace  # registers ~ 30 envs

# All nonlinear 6-DoF aircraft envs:
for env_id in [
    "NonlinearLongitudinalF16-v0",
    "NonlinearAngularF16-v0",
    "NonlinearB747-v0",
    "NonlinearB737-v0",
    "NonlinearX15-v0",
    "NonlinearSkywalkerX8-v0",
    "NonlinearAAIShadow-v0",
]:
    env = gym.make(env_id, trim_at=(20_000.0, 674.0)
                   if env_id == "NonlinearB747-v0" else None,
                   number_time_steps=10)
    print(f"  ✓ {env_id}")

3. Numerical sanity (trim convergence)

from tensoraerospace.aerospacemodel.b747.nonlinear import trim

result = trim(altitude_ft=20_000.0, V_ft_s=674.0)
assert result.converged, "trim solver should converge"
assert result.residual < 1e-6, f"residual too high: {result.residual}"
print(f"B-747 trim @ FL200, V=674 ft/s: residual = {result.residual:.2e} ✓")
# → B-747 trim @ FL200, V=674 ft/s: residual = 8.66e-14 ✓

If all three pass, the install is fully functional — both Python wiring and numerical computation are correct.

Optional: full test sweep (dev install only)

poetry run pytest tests/aerospacemodel/ tests/envs/ -q
# → 894 passed in ~ 19 s

---

GPU acceleration

NVIDIA CUDAApple Silicon (M1/M2/M3)CPU only

PyTorch wheels on PyPI bundle CUDA 12.x by default. To verify:

import torch
print("CUDA available:", torch.cuda.is_available())
print("Device count:", torch.cuda.device_count())
print("CUDA version:", torch.version.cuda)

For specific CUDA versions, install matching PyTorch wheels first:

pip install torch --index-url https://download.pytorch.org/whl/cu121
pip install tensoraerospace

See the official PyTorch install matrix.

Native Metal Performance Shaders (MPS) backend:

import torch
print("MPS available:", torch.backends.mps.is_available())
# → MPS available: True

Pretrained agents auto-detect MPS:

from tensoraerospace.agent.sac import SAC
agent = SAC.from_pretrained("TensorAeroSpace/sac-b747")
# device picked automatically: "mps" on Apple Silicon

No GPU? The default wheels work fine:

• Control synthesis (PID, MPC, classical ADP, IHDP) — CPU is plenty.
• Deep RL training (SAC, PPO, DDPG) — slower but possible (10–50× slower than GPU).
• Trim / simulation — CPU only, no GPU benefit.

To install CPU-only PyTorch (smaller download):

pip install torch --index-url https://download.pytorch.org/whl/cpu
pip install tensoraerospace

---

Optional dependencies

Feature	Install command	When you need it
Hugging Face Hub integration	bundled — already installed	Loading pretrained agents (from_pretrained), publishing models
Unity ML-Agents	pip install mlagents-envs==0.30.0	Running the Unity airplane environment
MATLAB / Simulink bridge	MATLAB R2022b+ + python -m matlab.engine.install	Running Simulink interop examples
3D flight viewer	bundled (uses three.js)	env.render() returning interactive 3D scene
Optuna hyperparameter search	pip install optuna	Hyperparameter optimisation cookbook
TensorBoard logging	pip install tensorboard	Real-time metrics during agent training

---

Install from source (development)

When you want to modify the library, run the test suite, or build the documentation locally:

Poetry (recommended)pip + venv

git clone https://github.com/TensorAeroSpace/TensorAeroSpace.git
cd TensorAeroSpace

poetry install --with dev   # main + dev dependencies (pytest, mkdocs, etc.)
eval $(poetry env activate)  # activate venv

# Run tests
poetry run pytest tests/aerospacemodel/ tests/envs/ -q

# Build docs locally
poetry run mkdocs serve -a 0.0.0.0:8000

git clone https://github.com/TensorAeroSpace/TensorAeroSpace.git
cd TensorAeroSpace

python -m venv .venv
source .venv/bin/activate    # Windows: .venv\Scripts\activate

pip install -U pip setuptools wheel
pip install -e ".[dev]"

pytest tests/ -q

After cloning, run a quick smoke test:

poetry run python example/aircraft/example_b747_nonlinear.py
# → Trim @ FL200, V=674 ft/s: alpha=+3.603°, delta_e=-0.722°, throttle=0.555
# → Healthy step response, damaged step response, trajectory plot saved

---

Run with Docker

Recommended for reproducible environments

The official image bundles JupyterLab with all 101 example notebooks ready to run. No host-side Python setup needed.

Pull the published imageBuild locallyGPU passthrough

docker pull ghcr.io/tensoraerospace/tensoraerospace:latest

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

Open the URL printed in the terminal (usually http://127.0.0.1:8888) and navigate to /workspace/example/quickstart.ipynb.

git clone https://github.com/TensorAeroSpace/TensorAeroSpace.git
cd TensorAeroSpace
docker build -t tas:local . --platform=linux/amd64

docker run --rm -it -p 8888:8888 \
  -v "$(pwd)/projects:/workspace/projects" \
  tas:local

Requires the NVIDIA Container Toolkit:

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

---

Update or uninstall

UpdateUninstall

# pip
pip install -U tensoraerospace

# poetry
poetry update tensoraerospace

To get the latest unreleased changes from main:

pip install -U git+https://github.com/TensorAeroSpace/TensorAeroSpace.git@main

pip uninstall tensoraerospace
# or
poetry remove tensoraerospace

To also free disk space taken by PyTorch and other deps:

pip uninstall tensoraerospace torch numpy scipy gymnasium matplotlib

---

Troubleshooting

ImportError: No module named tensoraerospace

The package is not visible to the active Python. Check:

which python && python -c "import sys; print(sys.executable)"
pip show tensoraerospace

Both should point to the same environment. If they don't, activate the right venv (source .venv/bin/activate or poetry env activate or conda activate tas).

PyTorch version conflicts (undefined symbol, RuntimeError: CUDA error)

Likely your installed PyTorch CUDA version doesn't match the system driver, or a stale wheel cache is in use.

pip uninstall torch torchvision torchaudio -y
pip cache purge
pip install torch --index-url https://download.pytorch.org/whl/cu121
pip install --upgrade --force-reinstall tensoraerospace

macOS (Apple Silicon) — torch can't find OpenMP

Apple's Xcode CLT ships clang without OpenMP. Either install via brew (brew install libomp) or rely on PyTorch's bundled MPS backend (no OpenMP needed for inference).

Trim solver fails to converge for my (h, V) point

For most aircraft this means the operating point is outside the cruise envelope. Check:

• Below stall: V too low for the required lift at this weight.
• Above ceiling: density too low for the engine's installed thrust.
• X-15 specifically: the rocket-engine model has no level-cruise envelope — use gamma_rad=… for climbing trim or level_trim() for the unphysical case. See X-15 trim docs.

Permissions / corporate proxy

Use pip install --user to install into the user site (no admin needed), or run inside Docker. For corporate proxies set PIP_INDEX_URL / HTTP_PROXY:

export PIP_INDEX_URL=https://your-mirror.example.com/simple
export HTTP_PROXY=http://proxy:8080
pip install tensoraerospace

CUDA available but agent runs on CPU

Some pretrained agents have a hardcoded device in their checkpoint. Force-move:

import torch
agent = SAC.from_pretrained("TensorAeroSpace/sac-b747")
device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
agent.policy = agent.policy.to(device)
agent.critic = agent.critic.to(device)
agent.critic_target = agent.critic_target.to(device)
agent.device = device

Could not find platform-independent libraries on Windows

Usually a corrupted Python install. Reinstall Python 3.11 from python.org (don't use the Windows Store version), then recreate your venv.

---

What next?

You're ready to build.

30-second quickstart Models Algorithms 16-recipe cookbook Lessons

If you hit a snag the troubleshooting section didn't cover, ping us on GitHub Discussions or open an issue.