🌩️ Nimbus

A massively parallelisable JAX flight simulation

---

Overview | Features | Installation | Quick Start | Demo | Project Structure

---

📖 Overview

Nimbus is a differentiable flight simulator written in JAX. It supports full 6DOF dynamics and vectorised execution on hardware accelerators for research and education in aerodynamics and control.

✨ Features

• ⚡ Massive Parallelisation: Simulate millions of aircraft simultaneously on consumer hardware
• 🎮 6DOF Flight Model: Full six degrees of freedom rigid body dynamics
• 🔄 Quaternion Rotation Engine: Singularity-free 3D rotations
• 🎯 RK4 Physics Integrator: Fourth-order Runge-Kutta for high numerical accuracy
• 🏔️ Layered Simplex Noise Terrain: Procedurally generated terrain
• 💥 Supersonic Dynamics: Drag rise from shockwaves at transonic speeds
• 🌬️ Atmospheric Modeling: Exponential atmosphere model with stochastic wind gusts
• 🛡️ G-Limiter: PID G-force limiting
• 🐻 3D Visualisation: Real-time rendering with Ursina engine

📦 Installation

# Basic installation
pip install git+https://github.com/auxeno/nimbus

# With interactive demo support (includes Ursina and Pillow)
pip install "nimbus[viz] @ git+https://github.com/auxeno/nimbus"

For local development:

git clone https://github.com/auxeno/nimbus.git
cd nimbus
pip install -e .         # basic installation
pip install -e ".[viz]"  # with visualisation

For GPU acceleration (requires compatible OS and GPU):

pip install --upgrade "jax[cuda12]"

🚀 Quick Start

Single Aircraft Simulation

import jax
from nimbus import quick_scenario, step, SimulationConfig

# Generate a complete scenario with terrain and waypoints
simulation, heightmap, waypoint_route = quick_scenario(seed=42)

# Configure and execute a single simulation step
key = jax.random.PRNGKey(0)
config = SimulationConfig()
step_fn = jax.jit(step, static_argnames=("config",))
next_sim, next_route = step_fn(key, simulation, heightmap, waypoint_route, config)

Massive Parallel Simulation

import jax
from nimbus import (
    InitialConditions, SimulationConfig, generate_simulation, quick_scenario, step
)

# Set up shared terrain and waypoint route
_, heightmap, waypoint_route = quick_scenario(seed=0)

# Generate 1 million unique aircraft simulation states
num_aircraft = 1_000_000
key = jax.random.PRNGKey(0)
keys = jax.random.split(key, num=num_aircraft)
simulation_states = jax.vmap(generate_simulation, in_axes=(0, None))(
    keys, 
    InitialConditions.default()
)

# Compile and vectorise the step function
config = SimulationConfig()
step_fn = jax.jit(step, static_argnames=("config",))
step_parallel = jax.vmap(step_fn, in_axes=(None, 0, None, None, None))

# Execute one simulation step for all aircraft
stepped_states = step_parallel(
    key, simulation_states, heightmap, waypoint_route, config
)

🎬 Demo

For a demonstration of Nimbus capabilities, check out the Nimbus demo notebook:

The notebook demonstrates:

• Simulating 1 million aircraft in parallel
• Extended temporal simulations
• Interactive 3D scenario visualisation with Plotly
• Custom scenario generation
• Terrain and aircraft configuration
• Benchmarking

3D Visualisation

Run the Interactive Demo

requires local installation with the optional [viz] command..

from nimbus.visual import InteractiveDemo

demo = InteractiveDemo()
demo.run()

Key	Action
W	Pitch down (nose down)
S	Pitch up (nose up)
A	Yaw left
D	Yaw right
Q	Roll left
E	Roll right
1-5	Set throttle position (0%, 25%, 50%, 75%, 100%)
P	Pause/unpause simulation
Scroll	Zoom camera in/out

🏗️ Project Structure

nimbus/
├── core/
│   ├── config.py       # simulation configuration dataclasses
│   ├── interface.py    # high-level physics interface
│   ├── logic.py        # control logic (PID controllers)
│   ├── physics.py      # aerodynamic forces and moments
│   ├── primitives.py   # type definitions
│   ├── quaternion.py   # 3D rotation operations
│   ├── scenario.py     # scenario management
│   ├── simulation.py   # numerical integration (RK4/Euler)
│   ├── spatial.py      # spatial operations and collision
│   ├── state.py        # aircraft and simulation state
│   ├── terrain.py      # procedural terrain generation
│   └── wind.py         # wind and turbulence modeling
└── visual/
    ├── config.py       # visualisation configuration
    ├── entities.py     # 3D entities (aircraft, terrain)
    ├── runtime.py      # Ursina runtime
    └── utils.py        # visualisation utilities

📊 Benchmarks

Benchmark Methodology

The code used for benchmarking can be found at the end of the demo notebook for easy results replication. Each data point is the average of 10 runs.

Hardware Configurations

Hardware	Type	Memory	Max Throughput	Sim Time Ratio
Apple M2 Air @ 3.5GHz	CPU	16 GB	9.2M steps/second	1.8 days/second
i7 14770k @ 5.6GHz	CPU	64 GB	10.0M steps/second	1.9 days/second
Google Colab T4	GPU	16 GB VRAM	112M steps/second	22 days/second
NVIDIA RTX 4090	GPU	24 GB VRAM	983M steps/second	190 days/second

Max Throughput: Peak aircraft-steps per second | Sim Time Ratio: Simulated seconds per wall-clock second

📚 Citation

If you use Nimbus in your research, please cite:

@software{nimbus2025,
  title = {Nimbus: A Massively Parallelisable JAX Flight Simulation},
  author = {Alex Goddard},
  year = {2025},
  url = {https://github.com/auxeno/nimbus}
}

📜 License

Apache 2.0 - See licence for details.

🌟 Acknowledgments

Built with JAX • Visualised with Ursina