@ -25,8 +25,10 @@ struct CelestialBody {
char name[64];
double mass; // kg
double radius; // meters
Vec3 position; // meters from origin
Vec3 velocity; // m/s
Vec3 local_position; // position relative to parent (meters)
Vec3 local_velocity; // velocity relative to parent (m/s)
Vec3 position; // global position (meters from origin)
Vec3 velocity; // global velocity (m/s)
double soi_radius; // sphere of influence radius (meters)
int parent_index; // index of gravitational parent (-1 for root)
float color[3]; // RGB for rendering
@ -78,10 +80,39 @@ struct AccelerationContext {
};
```
### OrbitalMetrics (test_utilities.h)
```cpp
struct OrbitalMetrics {
double kinetic_energy;
double potential_energy;
double total_energy;
double orbital_radius;
double velocity_magnitude;
double angular_position;
};
```
### OrbitTracker (test_utilities.h)
```cpp
struct OrbitTracker {
double initial_angle;
double previous_angle;
int quadrant_transitions;
bool orbit_completed;
double time_at_completion;
int body_index;
double min_time_days;
};
```
## Module Overview
### Physics (physics.cpp/h)
Vector math and gravity calculations. RK4 (Runge-Kutta 4th order) integration with `rk4_step()` .
Vector math and gravity calculations. RK4 (Runge-Kutta 4th order) integration with `rk4_step()` . Physics module is independent of simulation structures and accepts direct parameters for improved modularity.
**Key functions:**
- `rk4_step(Vec3* position, Vec3* velocity, double dt, double body_mass, double parent_mass)` - RK4 integration using position/velocity pointers
- `evaluate_acceleration(Vec3 relative_pos, double body_mass, double parent_mass)` - computes gravitational acceleration from parent
### Simulation (simulation.cpp/h)
Simulation state management and updates. SOI detection using Hill sphere: `r_soi = a * (m/M)^(2/5)` .
@ -90,8 +121,16 @@ Simulation state management and updates. SOI detection using Hill sphere: `r_soi
- `find_dominant_body()` - determines which body has gravitational dominance
- `update_soi()` - calculates sphere of influence radius using Hill sphere
- `update_simulation()` - runs one physics step: finds dominant parent, calculates gravity, applies RK4 integration
- `initialize_local_coordinates()` - converts global to local coordinates on load
- `compute_global_coordinates()` - converts local to global coordinates after update
- Dynamic parent switching when bodies cross SOI boundaries (with hysteresis)
**Update Order:**
- Root bodies updated first (in their own frame = global)
- Global coordinates computed for roots
- Child bodies updated in parent's local frame
- Global coordinates computed for all children
### Config Loader (config_loader.cpp/h)
TOML-based config parser using tomlc17 library. Auto-calculates circular orbit velocities and SOI radii.
@ -104,6 +143,7 @@ TOML-based config parser using tomlc17 library. Auto-calculates circular orbit v
- TOML array of tables: `[[bodies]]`
- Comments start with `#`
- `parent_index = -1` indicates root body (star)
- Supports nested orbits (planets with moons)
**Config format (TOML):**
```toml
@ -131,12 +171,50 @@ semi_major_axis = 1.496e11
### Renderer (renderer.cpp/h)
Raylib 3D visualization with logarithmic distance scaling and size scaling for visibility.
**Orbit rendering:**
- Elliptical orbits: e < 0.98
- Parabolic orbits: 0.98 ≤ e ≤ 1.02 (uses escape trajectory formula)
- Hyperbolic orbits: e > 1.02 (shows asymptotic behavior)
- `render_parabolic_orbit()` renders escape paths with true anomaly range: -π*0.95 to π*0.95
### Test Utilities (test_utilities.cpp/h)
Test helper functions for orbital mechanics validation.
**Key functions:**
- `calculate_kinetic_energy()` - computes kinetic energy of a body
- `calculate_potential_energy_pair()` - computes gravitational potential energy between two bodies
- `calculate_system_total_energy()` - sums total energy of entire system
- `calculate_orbital_metrics()` - returns comprehensive orbital state metrics
- `create_orbit_tracker()` - initializes orbit completion tracking
- `update_orbit_tracker()` - tracks orbital progress and detects completion
- `compare_double()` / `compare_vec3()` - floating-point comparison with tolerance
### Local Coordinate Frames (simulation.cpp/h)
Hierarchical coordinate system for improved numerical precision in nested orbits.
**Key functions:**
- `initialize_local_coordinates()` - initializes local frame positions/velocities from global coordinates
- `compute_global_coordinates()` - computes global positions/velocities from local frames
**Benefits:**
- Eliminates large offsets in floating-point calculations (moon at 3.8×10⁸ m instead of 1.5×10¹¹ m)
- Isolates moon orbits from planetary perturbations
- Maintains full floating-point precision for small orbital changes
- Improved Earth-Moon orbital stability (20% drift → stable)
**Implementation Details:**
- Dual coordinate storage: both local and global coordinates maintained
- Parent bodies treated as origin in child's reference frame during integration
- RK4 integration operates on local coordinates
- Global coordinates computed after each physics step for rendering and SOI checks
### Main Program (main.cpp)
GUI-only application with interactive 3D visualization.
- Initializes simulation with MAX_BODIES=100, TIME_STEP=60 seconds
- Runs 100 physics steps per frame (adjustable with speed multiplier)
- Game loop: input handling → camera update → physics update (if not paused) → rendering
- Supports speed multiplier (2x/0.5x per keypress, min 0.125x)
- Default config: `tests/configs/solar_system.toml`
**Controls:**
- Arrow keys: Rotate and zoom camera
@ -145,6 +223,62 @@ GUI-only application with interactive 3D visualization.
- I: Toggle info display
- ESC: Quit
## Build System
### Makefile Targets
- `make` - Build raylib (first time) and compile sources to `orbit_sim`
- `make rebuild` - Clean and rebuild
- `make clean` - Remove build artifacts
- `make clean-all` - Clean everything including raylib
- `make run` - Build and run the simulation
- `make test` - Run full automated test suite
- `make test-build` - Build test executable
### Dependencies
- g++ (C++14)
- raylib (built automatically from `ext/raylib/src` )
- tomlc17 (included in `ext/tomlc17/src` )
- Catch2 (for testing)
- libX11, libGL, libpthread (system libraries)
### Test Infrastructure
- **Framework** : Catch2 for unit testing
- **Test Configs** : `tests/configs/` contains test scenarios
- `solar_system.toml` - Full solar system with moons
- `earth_circular.toml` , `mars_circular.toml` - Simple orbital tests
- `parabolic_comet.toml` - Parabolic orbit (e=1.0)
- `hyperbolic_comet.toml` - Hyperbolic orbit (e>1.0)
- `soi_transition.toml` - SOI crossing test (3-body system)
- **Test Files** :
- `test_energy.cpp` - Energy conservation validation
- `test_moon_orbits.cpp` - Moon orbital stability tests
- `test_orbital_period.cpp` - Orbital period verification
- `test_parabolic_orbit.cpp` - Parabolic orbit tests
- `test_hyperbolic_orbit.cpp` - Hyperbolic orbit tests
- `test_soi_transition.cpp` - SOI transition validation
## Orbit Types
### Elliptical Orbits (0 ≤ e < 1 )
- Standard planetary and moon orbits
- Eccentricity e = 0 (circular) to e < 1 ( elliptical )
- Total energy is negative (bound to parent)
- Velocity follows vis-viva equation: `v² = GM(2/r - 1/a)`
### Parabolic Orbits (e = 1)
- Escape trajectories with exactly escape velocity
- Total energy is zero (marginally unbound)
- Escape velocity: `v² = 2GM/r`
- Rendered using true anomaly range: -π*0.95 to π*0.95
- Used for comets on escape trajectories
### Hyperbolic Orbits (e > 1)
- Fast escape trajectories exceeding escape velocity
- Total energy is positive (unbound)
- Asymptotic velocity: `v∞ = √(2GM/|a|)` where a < 0
- Shows open curve with asymptotic behavior
- Used for high-speed comets and interstellar objects
## Data Flow
### Initialization Sequence
@ -173,16 +307,25 @@ GUI-only application with interactive 3D visualization.
- Phase 1-4: Core physics, simulation, config loading, and rendering
- Raylib integration with 3D camera
- Distance and size scaling for visualization
- TOML config file system with solar_system.toml and test_simple.toml
- TOML config file system with solar system configs (includes Sun + 8 planets + 6 moons)
- RK4 (Runge-Kutta 4th order) integration for improved accuracy
- Time scaling controls (speed up/slow down simulation)
- Pause/resume functionality
- Orbital elements calculation
- **Hierarchical coordinate frames (local + global storage)**
- **Parent-first update order for stability**
- **Parabolic orbit support (e=1.0)**
- **Hyperbolic orbit support (e>1.0)**
- **Physics module refactoring (parameter-based signatures)**
- **Comprehensive test suite (8 test files, 39+ assertions)**
- **Build system with automated testing**
### 🔨 Remaining/Future Work
- More accurate integration methods (Newton-Raphson propagation)
- Interactive body selection
- Reference frame switching
- SOI transition frame transformations (Phase 3 of hierarchical frames)
- Io and Titan orbital stability tuning
## Technical Notes
@ -191,6 +334,7 @@ GUI-only application with interactive 3D visualization.
- All headers use include guards
- Memory management uses malloc/free
- Layer separation: Physics, Simulation, Configuration, Rendering layers
- Physics module is independent of simulation structures (parameter-based signatures)
### Scaling for Visualization
- Distance: logarithmic/power-law scaling for solar system scale
@ -205,9 +349,12 @@ GUI-only application with interactive 3D visualization.
- Simulation time per frame: 60s * 100 = 6000 seconds at 1x speed
- SOI (Sphere of Influence) uses Hill sphere approximation: `r_soi = a * (m/M)^(2/5)`
- SOI transitions use 0.5x distance hysteresis to prevent oscillation
- Parabolic orbits use escape velocity: `v² = 2GM/r`
- Hyperbolic orbits have positive total energy and asymptotic velocity
## Future Enhancements
- More accurate integration methods (Newton-Raphson propagation)
- Interactive body selection
- Reference frame switching
- 3D orbital visualization with inclination
- SOI transition frame transformations (Phase 3 of hierarchical frames)
