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
|
# Orbital Simulator
|
||||||
|
|
||||||
A fast N-body orbital mechanics simulator written in Rust.
|
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.
|
||||||
Simulate the motion of celestial bodies under Newtonian gravity, with easy configuration and efficient output for visualization.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Features
|
## Features
|
||||||
|
|
||||||
- **N-body simulation**
|
- N-body gravitational simulation with normalized units
|
||||||
- **Configurable initial conditions** via JSON
|
- Configurable mass, distance, and time scales
|
||||||
- **Binary trajectory files**
|
- JSON and TOML configuration support
|
||||||
- **Progress bar**
|
- Binary trajectory output format
|
||||||
- **Unit normalization**
|
- 2D and 3D trajectory plotting
|
||||||
- **Ready for visualization** (Coming Soon)
|
- Animated simulations with customizable reference frames
|
||||||
|
- Energy conservation analysis
|
||||||
|
- Video export (requires ffmpeg)
|
||||||
|
- Pre-built configurations for solar system scenarios
|
||||||
|
|
||||||
---
|
## Installation
|
||||||
|
|
||||||
## Getting Started
|
You'll need Rust (2021 edition or later) and Python 3.7+. For video export, install ffmpeg.
|
||||||
|
|
||||||
### 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
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
|
git clone <repository-url>
|
||||||
|
cd orbital_simulator
|
||||||
cargo build --release
|
cargo build --release
|
||||||
|
pip install -r requirements.txt
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
## Quick Examples
|
||||||
|
|
||||||
## Running the Simulator (CLI)
|
|
||||||
|
|
||||||
|
Simulate the inner solar system for one year:
|
||||||
```bash
|
```bash
|
||||||
cargo run --release --bin simulator -- \
|
cargo run --release --bin simulator -- \
|
||||||
--config path/to/your_config.json \
|
--config config/inner_solar_system.toml \
|
||||||
--time 30d \
|
--time 365d \
|
||||||
--step-size 10.0 \
|
--step-size 3600 \
|
||||||
--output-file trajectory.bin
|
--output-file solar_system.bin
|
||||||
|
|
||||||
|
python3 plot_trajectories.py solar_system.bin --animate
|
||||||
```
|
```
|
||||||
|
|
||||||
**Arguments:**
|
Or try a simple Earth-Sun system:
|
||||||
- `--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`)
|
|
||||||
|
|
||||||
```bash
|
```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
|
## Configuration
|
||||||
|
|
||||||
The config file is a JSON file describing the initial state of each body.
|
Configuration files define the initial state of your celestial bodies:
|
||||||
Examples provided in `config/`
|
|
||||||
|
|
||||||
```json
|
```toml
|
||||||
{
|
[[bodies]]
|
||||||
"bodies": [
|
name = "Sun"
|
||||||
{
|
mass = 1.989e30
|
||||||
"name": "BodyName",
|
position = [0.0, 0.0, 0.0]
|
||||||
"mass": 1e10, //kg
|
velocity = [0.0, 0.0, 0.0]
|
||||||
"position": [0.0, 0.0, 0.0], //meters
|
|
||||||
"velocity": [0.0, 0.0, 0.0] // m/s
|
[[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:**
|
Several configurations are included:
|
||||||
- Mass: kilograms (kg)
|
- `planets.toml` - Complete solar system (16 bodies)
|
||||||
- Position: meters (m)
|
- `solar_system.toml` - Major planets only (9 bodies)
|
||||||
- Velocity: meters per second (m/s)
|
- `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/).
|
```bash
|
||||||
- Each snapshot contains the simulation time and the real (de-normalized) positions, velocities, and masses of all bodies.
|
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.
|
```bash
|
||||||
- Adjust step size and simulation time for accuracy/performance trade-offs.
|
python3 plot_trajectories.py [OPTIONS] <trajectory_file>
|
||||||
- The code is modular and ready for extension (e.g., new force laws, output formats, or integrators).
|
```
|
||||||
|
|
||||||
---
|
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
|
## License
|
||||||
|
|
||||||
MIT License
|
MIT License - see source for details.
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 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
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Author
|
## Author
|
||||||
|
|
||||||
- Thomas Faour
|
Thomas Faour
|
||||||
Loading…
x
Reference in New Issue
Block a user