214 lines
5.8 KiB
Markdown
214 lines
5.8 KiB
Markdown
# 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 <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
|
|
```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 <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
|
|
|
|
```bash
|
|
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
|
|
|
|
```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 <repository-url>
|
|
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. |