From 620d7b8957aa980e53841b3647cc79219f80d933 Mon Sep 17 00:00:00 2001 From: cinnaboot Date: Wed, 14 Jan 2026 11:17:57 -0500 Subject: [PATCH] update implementation_plan to match current project state --- docs/implementation_plan.md | 155 +++++++++++++++++++++++++++++++++++- 1 file changed, 151 insertions(+), 4 deletions(-) diff --git a/docs/implementation_plan.md b/docs/implementation_plan.md index 5da0690..a090402 100644 --- a/docs/implementation_plan.md +++ b/docs/implementation_plan.md @@ -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)