readme update
This commit is contained in:
Thomas Faour
parent
19fcf445e4
commit
a8fcb5a7d9
211
README.md
211
README.md
@ -1,128 +1,159 @@
|
||||
# Orbital Simulator
|
||||
|
||||
A fast N-body orbital mechanics simulator written in Rust.
|
||||
Simulate the motion of celestial bodies under Newtonian gravity, with easy configuration and efficient output for visualization.
|
||||
|
||||
---
|
||||
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 simulation**
|
||||
- **Configurable initial conditions** via JSON
|
||||
- **Binary trajectory files**
|
||||
- **Progress bar**
|
||||
- **Unit normalization**
|
||||
- **Ready for visualization** (Coming Soon)
|
||||
- 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
|
||||
|
||||
## Getting Started
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- [Rust](https://www.rust-lang.org/tools/install) (edition 2021 or later)
|
||||
- [Bevy dependencies](https://bevyengine.org/learn/book/getting-started/setup/) (for 3D visualization; see Bevy's docs for Linux requirements)
|
||||
|
||||
### Build
|
||||
You'll need Rust (2021 edition or later) and Python 3.7+. For video export, install ffmpeg.
|
||||
|
||||
```bash
|
||||
git clone <repository-url>
|
||||
cd orbital_simulator
|
||||
cargo build --release
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Running the Simulator (CLI)
|
||||
## Quick Examples
|
||||
|
||||
Simulate the inner solar system for one year:
|
||||
```bash
|
||||
cargo run --release --bin simulator -- \
|
||||
--config path/to/your_config.json \
|
||||
--time 30d \
|
||||
--step-size 10.0 \
|
||||
--output-file trajectory.bin
|
||||
--config config/inner_solar_system.toml \
|
||||
--time 365d \
|
||||
--step-size 3600 \
|
||||
--output-file solar_system.bin
|
||||
|
||||
python3 plot_trajectories.py solar_system.bin --animate
|
||||
```
|
||||
|
||||
**Arguments:**
|
||||
- `--config` (required): Path to your JSON config file with initial body states.
|
||||
- `--time` (required): Total simulation time (e.g. `10s`, `5m`, `2h`, `100d`).
|
||||
- `--step-size`: Simulation step size in seconds (default: `10.0`).
|
||||
- `--output-file` (required): Where to save the trajectory data.
|
||||
- `--steps-per-save`: How often to update the progress bar and save (default: `1000`).
|
||||
|
||||
---
|
||||
|
||||
## Running the 3D Visualizer (`orbiter`)
|
||||
|
||||
Or try a simple Earth-Sun system:
|
||||
```bash
|
||||
cargo run --release --bin orbiter
|
||||
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
|
||||
```
|
||||
|
||||
- Opens a 3D window with a camera and a blue sphere (placeholder for future simulation data).
|
||||
- **Camera controls:**
|
||||
- **Right mouse drag:** Orbit around the origin
|
||||
- **Scroll wheel:** Zoom in/out
|
||||
|
||||
Future updates will allow loading and animating simulation output.
|
||||
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
The config file is a JSON file describing the initial state of each body.
|
||||
Examples provided in `config/`
|
||||
Configuration files define the initial state of your celestial bodies:
|
||||
|
||||
```json
|
||||
{
|
||||
"bodies": [
|
||||
{
|
||||
"name": "BodyName",
|
||||
"mass": 1e10, //kg
|
||||
"position": [0.0, 0.0, 0.0], //meters
|
||||
"velocity": [0.0, 0.0, 0.0] // m/s
|
||||
},
|
||||
...
|
||||
]
|
||||
}
|
||||
```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
|
||||
```
|
||||
|
||||
- **Units:**
|
||||
- Mass: kilograms (kg)
|
||||
- Position: meters (m)
|
||||
- Velocity: meters per second (m/s)
|
||||
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
|
||||
|
||||
## Output
|
||||
### Running Simulations
|
||||
|
||||
- The simulator writes binary snapshots of the system state to the output file using [bincode](https://docs.rs/bincode/).
|
||||
- Each snapshot contains the simulation time and the real (de-normalized) positions, velocities, and masses of all bodies.
|
||||
```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
|
||||
|
||||
## Extending
|
||||
### Visualization
|
||||
|
||||
- Add more bodies or change initial conditions in the config file.
|
||||
- Adjust step size and simulation time for accuracy/performance trade-offs.
|
||||
- The code is modular and ready for extension (e.g., new force laws, output formats, or integrators).
|
||||
```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
|
||||
|
||||
---
|
||||
|
||||
## Acknowledgments
|
||||
|
||||
- [Rust](https://www.rust-lang.org/)
|
||||
- [Bevy](https://bevyengine.org/) for 3D visualization
|
||||
- [glam](https://crates.io/crates/glam) for fast vector math
|
||||
- [clap](https://crates.io/crates/clap) for CLI parsing
|
||||
- [indicatif](https://crates.io/crates/indicatif) for progress bars
|
||||
- [serde](https://crates.io/crates/serde) and [bincode](https://crates.io/crates/bincode) for serialization
|
||||
|
||||
---
|
||||
MIT License - see source for details.
|
||||
|
||||
## Author
|
||||
|
||||
- Thomas Faour
|
||||
Thomas Faour
|
||||
Loading…
x
Reference in New Issue
Block a user