Orbital Simulator
A comprehensive N-body orbital mechanics simulator with multiple interfaces: Web Browser, Desktop GUI, CLI, and Python Tools. Built in Rust for performance with React/Three.js for visualization.
🚀 Features
Core Simulation
- High-performance N-body gravitational simulation
- Normalized units for numerical stability
- Real-time and batch processing modes
- Energy conservation monitoring
- Configurable time steps and integration methods
Multiple Interfaces
- 🌐 Web Interface: Browser-based with 3D visualization
- 🖥️ Desktop GUI: Native application with Tauri
- ⚡ CLI Tools: Command-line batch processing
- 📊 Python Tools: Scientific plotting and analysis
- 🔌 REST API: Programmatic access and integration
Visualization
- Real-time 3D orbital mechanics
- Interactive camera controls
- Particle trails and body labels
- Energy plots and statistics
- Animation export capabilities
📦 Installation
Prerequisites
- Rust (2021 edition or later)
- Node.js 18+ and npm
- Python 3.7+ (for analysis tools)
- Git
Quick Setup
git clone <repository-url>
cd orbital_simulator
chmod +x start_interfaces.sh test_interfaces.sh
./test_interfaces.sh # Verify everything works
./start_interfaces.sh # Start all interfaces
Manual Installation
# Install Rust dependencies
cargo build --release --no-default-features
# Install web dependencies
cd web && npm install && cd ..
# Install Python dependencies
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
# Optional: Install Tauri for desktop GUI
cargo install tauri-cli
🎯 Quick Start
Web Interface (Recommended)
./start_interfaces.sh
# Open http://localhost:5173 in your browser
CLI Simulation
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
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-onlyor--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
🐳 Docker Deployment
The easiest way to deploy the Orbital Simulator is using Docker:
Quick Start with Docker
# Clone the repository
git clone <repository-url>
cd orbital_simulator
# Start with Docker Compose
docker-compose up --build
# Access the application at http://localhost:3000
Production Deployment
# Start with Nginx reverse proxy
docker-compose --profile production up --build -d
# Access at http://localhost (port 80)
See DOCKER.md for detailed deployment documentation.