A fast N-body orbital mechanics simulator written in Rust with Python visualization tools. Simulate planetary motion using Newtonian gravity with configurable parameters and create animations of the results.

Features

N-body gravitational simulation with normalized units
Configurable mass, distance, and time scales
JSON and TOML configuration support
Binary trajectory output format
2D and 3D trajectory plotting
Animated simulations with customizable reference frames
Energy conservation analysis
Video export (requires ffmpeg)
Pre-built configurations for solar system scenarios

Installation

You'll need Rust (2021 edition or later) and Python 3.7+. For video export, install ffmpeg.

git clone <repository-url>
cd orbital_simulator
cargo build --release
pip install -r requirements.txt

Quick Examples

Simulate the inner solar system for one year:

cargo run --release --bin simulator -- \
  --config config/inner_solar_system.toml \
  --time 365d \
  --step-size 3600 \
  --output-file solar_system.bin

python3 plot_trajectories.py solar_system.bin --animate

Or try a simple Earth-Sun system:

cargo run --release --bin simulator -- \
  --config config/earthsun_corrected.toml \
  --time 30d \
  --step-size 3600 \
  --output-file earth_sun.bin

python3 plot_trajectories.py earth_sun.bin --animate --center Earth

Configuration

Configuration files define the initial state of your celestial bodies:

[[bodies]]
name = "Sun"
mass = 1.989e30
position = [0.0, 0.0, 0.0]
velocity = [0.0, 0.0, 0.0]

[[bodies]]
name = "Earth"
mass = 5.972e24
position = [1.496e11, 0.0, 0.0]  # 1 AU from Sun
velocity = [0.0, 29789.0, 0.0]   # Orbital velocity

# Optionally specify custom units
[normalization]
m_0 = 5.972e24  # Earth mass
r_0 = 6.378e6   # Earth radius  
t_0 = 5023.0    # Time unit

Several configurations are included:

planets.toml - Complete solar system (16 bodies)
solar_system.toml - Major planets only (9 bodies)
inner_solar_system.toml - Inner planets + Moon (6 bodies)
earthsun_corrected.toml - Simple Earth-Sun system (2 bodies)

Usage

Running Simulations

cargo run --bin simulator -- [OPTIONS]

Key options:

-c, --config <FILE> - Configuration file
-t, --time <DURATION> - How long to simulate (e.g., 10s, 5m, 2h, 100d)
-s, --step-size <SECONDS> - Integration step size (default: 10.0)
-o, --output-file <FILE> - Where to save trajectory data
-w, --force-overwrite - Skip confirmation when overwriting files

Visualization

python3 plot_trajectories.py [OPTIONS] <trajectory_file>

Useful options:

--animate - Show animated trajectories instead of static plots
--center <BODY> - Center the view on a specific body
--save-animation <PREFIX> - Export animation as MP4 video
--energy - Include energy conservation plots
--list-bodies - Show what bodies are in the trajectory file
--2d-only or --3d-only - Limit to 2D or 3D plots

Examples

# See what bodies are available
python3 plot_trajectories.py trajectory.bin --list-bodies

# Animate from different perspectives
python3 plot_trajectories.py trajectory.bin --animate --center Sun
python3 plot_trajectories.py trajectory.bin --animate --center Jupiter

# Create a video
python3 plot_trajectories.py trajectory.bin --animate --save-animation solar_system

# Check energy conservation
python3 plot_trajectories.py trajectory.bin --energy

How It Works

The simulator uses Newtonian gravity (F = G·m₁·m₂/r²) with explicit Euler integration. All bodies interact gravitationally with each other. The system normalizes units to Earth-based scales by default but you can specify custom normalization constants.

Animations automatically scale to about 60 seconds and show the time compression ratio (like "3.6 hours of simulation per second"). You can center the view on any body to see orbital mechanics from different reference frames.

The simulator includes safety features like confirmation prompts before overwriting files, and exports data in an efficient binary format.

Project Structure

src/
├── bin/
│   ├── simulator.rs         # Main simulation program
│   └── orbiter.rs           # 3D visualizer
├── config.rs                # Configuration loading
├── simulation.rs            # Physics simulation
├── types.rs                 # Data types and units
└── lib.rs                   # Library interface

config/                      # Pre-made configurations
plot_trajectories.py         # Visualization script
inspect_trajectories.py      # Data inspection tool

License

MIT License - see source for details.

Author

Thomas Faour

Languages

Rust 28.6%

TypeScript 28.5%

Python 25.1%

Shell 10.3%

CSS 5.5%

Other 2%