# 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 ```bash git clone 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 ```bash # 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) ```bash ./start_interfaces.sh # Open http://localhost:5173 in your browser ``` ### CLI Simulation ```bash 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: ```toml [[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 ```bash cargo run --bin simulator -- [OPTIONS] ``` Key options: - `-c, --config ` - Configuration file - `-t, --time ` - How long to simulate (e.g., 10s, 5m, 2h, 100d) - `-s, --step-size ` - Integration step size (default: 10.0) - `-o, --output-file ` - Where to save trajectory data - `-w, --force-overwrite` - Skip confirmation when overwriting files ### Visualization ```bash python3 plot_trajectories.py [OPTIONS] ``` Useful options: - `--animate` - Show animated trajectories instead of static plots - `--center ` - Center the view on a specific body - `--save-animation ` - 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 ```bash # 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 ```bash # Clone the repository git clone cd orbital_simulator # Start with Docker Compose docker-compose up --build # Access the application at http://localhost:3000 ``` ### Production Deployment ```bash # Start with Nginx reverse proxy docker-compose --profile production up --build -d # Access at http://localhost (port 80) ``` See [DOCKER.md](DOCKER.md) for detailed deployment documentation.