Update hierarchical frames plan and add patched conics implementation plan

- Update hierarchical_frames_plan.md with recent work (Jan 13, 2026) - Add comprehensive patched conics implementation plan - Document SOI transition requirements and implementation phases - Include 4 open questions for strategy discussion - Add 6 test scenarios for multi-body transitions - Document success criteria and timeline estimates
6 months ago · 1d361189b5
2 changed files with 836 additions and 21 deletions
--- a/docs/hierarchical_frames_plan.md
+++ b/docs/hierarchical_frames_plan.md
@ -1,15 +1,22 @@
 # Hierarchical Coordinate Frames Implementation Plan
-## Status: Phase 2 Complete ✅
+## Status: Phase 4 Complete ✅
-**Last Updated:** 2026-01-09
+**Last Updated:** 2026-01-13
 **Current Progress:**
 - ✅ Phase 1: Foundation (Dual coordinate storage)
 - ✅ Phase 2: Local frame integration (Earth Moon test passing!)
 - ⏸️ Phase 3: SOI transitions with frame transforms (deferred)
- ⏸️ Phase 4: Parent-first update order (deferred)
+- ✅ Phase 4: Parent-first update order (fully implemented)
- ⏸️ Phase 5: Validation & optimization (deferred)
+- ⏸️ Phase 5: Validation & optimization (partial - documentation complete)
 **Recent Work (January 13, 2026):**
 - ✅ Physics module refactoring (removed simulation dependencies)
 - ✅ Parabolic orbit support (e=1.0 escape trajectories)
 - ✅ Hyperbolic orbit support (e>1.0 with asymptotic velocity)
 - ✅ Simplified SOI transition test (3-body system)
 - ✅ Comprehensive test suite (8 test files, 39+ assertions)
 **Test Results After Phase 2:**
 - Tests passing: 7/9 (78%)
@ -17,9 +24,19 @@
 - Io orbital stability: ❌ Still failing (orbit not completing)
 - Titan orbital stability: ❌ Still failing (NaN drift)
 **Current Test Status (January 13, 2026):**
 - Total test files: 8 (energy, hyperbolic, parabolic, SOI transition, moon orbits, orbital period, integration, main)
 - Total assertions: 39+ (all new orbit type tests passing)
 - New orbit types validated: Parabolic (e=1.0) and Hyperbolic (e>1.0)
 - SOI transition test: Passes with 3-body simplified system
 **Commits:**
 - `92be7f8` - Phase 1: Add local coordinate frame storage (no behavior change)
 - `052efff` - Phase 2: Local frame integration (Earth Moon test now passing!)
 - `ed1e50e` - Remove simulation dependencies from physics module
 - `1ec6249` - Add parabolic orbit support and test case
 - `63a1144` - Add hyperbolic orbit test case and configuration
 - `08cdfeb` - Add simplified SOI transition test case
 ---
@ -247,7 +264,7 @@ The local frame integration provides improved numerical precision by:
 **Files to modify:**
 - `src/simulation.cpp` (SOI transition logic)
- `tests/test_comet_orbit.cpp` (verify transitions)
+- `tests/test_soi_transition.cpp` (verify transitions)
 **Estimated complexity:** Medium
 **Risk:** Medium (affects patched conics later)
@ -268,7 +285,7 @@ transformations during transitions: `new_local = global - new_parent_global`.
 ### Phase 4: Parent-First Update Order
 **Goal:** Update hierarchy in correct order
-**Status:** Partially implemented
+**Status:** FULLY IMPLEMENTED ✅
 **Tasks:**
 1. Refactor `update_simulation()` to update roots first, then children
@ -285,21 +302,23 @@ transformations during transitions: `new_local = global - new_parent_global`.
 - ✅ Hierarchical update order implemented
 - ✅ Parent positions current when updating children
-**Status:** Partially implemented
+**Status:** FULLY IMPLEMENTED ✅
-**Current Implementation:**
+**Implementation Details:**
- Root bodies are updated first
+- Root bodies updated first (in their own frame = global)
 - `compute_global_coordinates()` called after root update
- Then child bodies updated (using updated parent global positions)
+- Child bodies updated in parent's local frame (using updated parent positions)
 - `compute_global_coordinates()` called again after child update
-**This is effectively parent-first order!** Root bodies complete integration before
+**This is parent-first order!** Root bodies complete integration before
-children start, and children use current parent positions. However, children still
+children start, and children use current parent positions. Children
-use parent positions from START of timestep during their RK4 integration.
+use parent positions from START of timestep during their RK4 integration
 (semi-implicit approach that works well).
-**Future Refinement (if needed):**
+**Results:**
-Could pass updated parent position into child RK4 steps for even higher accuracy.
+- Earth-Moon orbital stability achieved (20% drift → stable)
-Current approach is semi-implicit and works well for Phase 2 results.
+- Improved numerical precision for nested orbits
 - All tests pass with this approach
 ---
@ -311,7 +330,7 @@ Current approach is semi-implicit and works well for Phase 2 results.
 1. Add test for frame transformations
 2. Profile performance (should be similar or better)
 3. Add documentation comments explaining coordinate systems
-4. Update implementation_plan.md
+4. ~~Update implementation_plan.md~~ ✅ Already completed (January 14, 2026)
 **Files to modify:**
 - `tests/` (new frame transform tests)
@ -326,6 +345,100 @@ Current approach is semi-implicit and works well for Phase 2 results.
 ---
 ## Recent Work: January 13, 2026
 ### Physics Module Refactoring
 **Goal:** Improve modularity by removing simulation dependencies from physics module
 **Changes:**
 - Removed `SimulationState*` and `CelestialBody*` parameters from physics functions
 - Updated `rk4_step()` to accept `Vec3* position, Vec3* velocity, double dt, double body_mass, double parent_mass`
 - Updated `evaluate_acceleration()` to accept `Vec3 relative_pos, double body_mass, double parent_mass`
 - Physics module now independent of simulation structures
 **Benefits:**
 - Better separation of concerns
 - Physics functions can be used independently
 - Clearer function signatures showing all required parameters
 - Easier unit testing
 **Files modified:**
 - `src/physics.h` (+11, -7 lines)
 - `src/physics.cpp` (+21, -37 lines)
 - `src/simulation.cpp` (+3, -6 lines)
 **Commit:** `ed1e50e` - Remove simulation dependencies from physics module
 ### Parabolic Orbit Support
 **Goal:** Add support for parabolic orbits (eccentricity e=1.0) for escape trajectories
 **Changes:**
 - Modified `compute_orbital_velocity_from_vis_viva()` to detect e=1.0
 - Uses escape velocity formula `v² = 2GM/r` for parabolic orbits
 - Added `render_parabolic_orbit()` function for visualization
 - True anomaly range: -π*0.95 to π*0.95 (almost full escape path)
 **Tests:**
 - `tests/test_parabolic_orbit.cpp` - 9 assertions, 2 test cases
 - `tests/configs/parabolic_comet.toml` - Sun + parabolic comet config
 **Validation:**
 - Total energy ≈ 0 (marginally unbound)
 - Velocity = escape velocity
 - Energy drift < 1%
 **Commits:**
 - `1ec6249` - Add parabolic orbit support and test case
 - `84502a7` - Add parabolic orbit rendering function
 ### Hyperbolic Orbit Support
 **Goal:** Add support for hyperbolic orbits (eccentricity e > 1.0) for fast escape trajectories
 **Changes:**
 - Renderer updated to show asymptotic behavior for e > 1.02
 - Validation of asymptotic velocity `v∞ = √(2GM/|a|)` where a < 0
 **Tests:**
 - `tests/test_hyperbolic_orbit.cpp` - 18 assertions, 3 test cases
 - `tests/configs/hyperbolic_comet.toml` - Sun + hyperbolic comet config
 **Validation:**
 - Total energy > 0 (unbound)
 - Velocity > escape velocity
 - Asymptotic velocity validation at 18+ AU distance
 - Energy drift < 1%
 **Commits:**
 - `63a1144` - Add hyperbolic orbit test case and configuration
 ### Simplified SOI Transition Test
 **Goal:** Replace complex 7-body SOI test with focused 3-body system
 **Changes:**
 - Removed `tests/test_comet_orbit.cpp` (7-body complex system)
 - Created `tests/test_soi_transition.cpp` with 3-body system (Sun + Mars + SmallBody)
 - Removed `configs/test_simple.toml` (redundant)
 **Test validation:**
 - SOI transition from Sun to Mars
 - SOI radii verification using Hill sphere: `r_soi = a * (m/M)^(2/5)`
 - Mars SOI ~0.004 AU (verified range: 0.003-0.005 AU)
 - Documents hysteresis behavior (0.5 factor creates one-way barrier)
 **Commits:**
 - `08cdfeb` - Add simplified SOI transition test case
 - `2e9e747` - Remove deprecated comet orbit test and config
 ### Overall Test Results (January 13, 2026)
 - **Total test files:** 8 (energy, hyperbolic, parabolic, SOI transition, moon orbits, orbital period, integration, main)
 - **Total assertions:** 39+ (all new orbit type tests passing)
 - **New orbit types validated:** Parabolic (e=1.0) and Hyperbolic (e>1.0)
 - **Visualization verified:** All three orbit types (elliptical, parabolic, hyperbolic) render correctly
 **Summary:** Net +600/-246 lines (+364 lines) - cleaner test structure, better documentation
 ---
 ## Summary of Current State
 ### What Works:
@ -335,22 +448,34 @@ Current approach is semi-implicit and works well for Phase 2 results.
 4. ✅ Earth-Moon orbital stability (major success!)
 5. ✅ Improved numerical precision for nested orbits
 6. ✅ Clean separation of local/global coordinate systems
 7. ✅ Parent-first hierarchical update order
 8. ✅ Physics module refactoring (simulation-independent)
 9. ✅ Parabolic orbit support (e=1.0 escape trajectories)
 10. ✅ Hyperbolic orbit support (e>1.0 with asymptotic velocity)
 11. ✅ Simplified SOI transition testing (3-body system)
 12. ✅ Comprehensive test suite (8 test files, 39+ assertions)
 ### What's Deferred:
-1. ⏸️ SOI transition frame transformations (Phase 3)
+1. ⏸️ SOI transition frame transformations (Phase 3) - critical for spacecraft SOI crossing
-2. ⏸️ Full validation suite (Phase 5)
+2. ⏸️ Full validation suite (Phase 5) - documentation already updated in implementation_plan.md
-3. ⏸️ Io and Titan orbital tuning
+3. ⏸️ Io and Titan orbital tuning - may require adaptive timesteps
 4. ⏸️ Interactive body selection and reference frame switching
 ### Ready For:
 - Continued development of patched conics (after Phase 3)
 - Satellite/spacecraft simulation (will need Phase 3 for SOI crossing)
 - Further orbital mechanics improvements
 - Testing all three orbit types (elliptical, parabolic, hyperbolic)
 - Physics module reuse in other projects (now simulation-independent)
 ### Notes for Future Development:
 - Phase 3 (SOI transitions) is critical for spacecraft that cross SOI boundaries
 - Current SOI transitions work but don't transform coordinates properly
 - May need adaptive timesteps or smaller fixed timesteps for outer moons (Io, Titan)
 - Consider adding orbit tracker diagnostics to debug remaining failures
 - Physics module now independent - can be reused for other projects
 - All three orbit types now validated and visualized (elliptical, parabolic, hyperbolic)
 - Implementation_plan.md fully updated with current project state
 ## Design Decisions
@ -389,7 +514,10 @@ Per-level timesteps deferred for future optimization.
 After all phases complete:
 - ✅ Moon orbital stability vastly improved (test failures fixed)
 - ✅ Numerical precision improved for nested orbits
- ✅ SOI transitions with proper coordinate frame transformations
+- ⏸️ SOI transitions with proper coordinate frame transformations (Phase 3 - deferred)
 - ✅ Foundation for patched conics and satellite simulation
 - ✅ Parent-first hierarchical update order
 - ✅ Fully documented coordinate system architecture
 - ✅ Support for all three orbit types (elliptical, parabolic, hyperbolic)
 - ✅ Physics module refactoring for better modularity
 - ✅ Comprehensive test suite (39+ assertions across 8 test files)
--- a/docs/patched_conics_plan.md
+++ b/docs/patched_conics_plan.md
@ -0,0 +1,687 @@
 # Patched Conics and SOI Transition Implementation Plan
 **Date:** January 14, 2026
 **Status:** Planning Phase
 **Branch:** To be created
 ## Overview
 This plan implements support for patched conics trajectory simulation, enabling satellites to transition between multiple spheres of influence (SOI) in complex orbital scenarios:
 - Planet → Star → Planet transfers
 - Star → Planet → Moon rendezvous
 - Multi-leg interplanetary missions
 ## Current State Analysis
 ### ✅ What's Already Working
 1. **SOI Transitions Are Already Implemented**
   - Lines 103-121 in `simulation.cpp` show coordinate transformation logic
   - Converts local→global using old parent, then global→local using new parent
   - This is essentially Phase 3 implementation from hierarchical_frames_plan.md
 2. **Local Frame Integration** (Phase 2) ✅
   - All bodies integrate in local coordinates
   - Global coordinates computed after each timestep
   - Improved numerical precision for nested orbits
 3. **Parent-First Update Order** (Phase 4) ✅
   - Root bodies skipped in loop (fixed at origin)
   - Child bodies integrate using parent coordinates
   - Hierarchical update order implemented
 ### 🔴 Critical Issues for Patched Conics
 **Issue 1: Cannot Transition to Root Bodies**
 ```cpp
 if (new_parent != body->parent_index && new_parent != -1) {
    // ... transition logic
 }
 ```
 The `new_parent != -1` condition prevents switching to Sun (parent_index = -1). This breaks the scenario: Planet→Sun→Moon rendezvous is impossible.
 **Issue 2: Hysteresis Barrier**
 The 0.5x hysteresis factor in `find_dominant_body()` (line 71) creates one-way barriers:
 - Planet→Sun: Possible (easy entry)
 - Sun→Planet: **Impossible** (can't exit due to hysteresis)
 **Issue 3: Integration After Transition**
 Transition happens before integration in the same timestep, using coordinates from the end of the previous timestep. This may cause velocity discontinuities.
 ### ⚠️ Potential Issues
 **Issue 4: Numerical Precision**
 Satellites crossing between star/planet/moon scales will see position magnitude changes of 10⁸ to 10¹¹ meters, potentially losing precision.
 **Issue 5: Fixed Timestep**
 60s timestep may be too coarse for fast orbital phases (moon capture) and too slow for deep-space phases.
 ## Implementation Phases
 ### Phase 1: Fix Root Body Transitions (Critical)
 **Goal:** Allow satellites to switch to/from Sun (parent_index = -1)
 **Changes:**
 1. Remove `new_parent != -1` check in `simulation.cpp` line 104
 2. Add special handling for root body transitions:
   ```cpp
   if (new_parent != body->parent_index) {
       // Convert local → global using old parent
       if (body->parent_index >= 0) {
           // old_parent is a real body
           CelestialBody* old_parent = &sim->bodies[body->parent_index];
           body->position = vec3_add(body->local_position, old_parent->position);
           body->velocity = vec3_add(body->local_velocity, old_parent->velocity);
       } else {
           // old_parent is root (Sun): local = global
           body->position = body->local_position;
           body->velocity = body->local_velocity;
       }
       body->parent_index = new_parent;
       // Convert global → local using new parent
       if (new_parent >= 0) {
           // new_parent is a real body
           CelestialBody* new_parent_body = &sim->bodies[new_parent];
           body->local_position = vec3_sub(body->position, new_parent_body->position);
           body->local_velocity = vec3_sub(body->velocity, new_parent_body->velocity);
       } else {
           // new_parent is root (Sun): global = local
           body->local_position = body->position;
           body->local_velocity = body->velocity;
       }
   }
   ```
 3. **Update `find_dominant_body()`** to properly handle -1 returns
 **Files to modify:**
 - `src/simulation.cpp` (lines 103-121)
 - `src/simulation.h` (no changes needed)
 **Estimated complexity:** Low
 **Risk:** Medium (affects core transition logic)
 **Expected outcome:**
 - ✅ Satellites can transition to/from Sun
 - ✅ Enables Planet→Sun→Planet transfers
 - ✅ Enables Star→Planet→Moon rendezvous
 **Tests to add:**
 - Test satellite transitioning from Earth to Sun
 - Test satellite transitioning from Sun to Mars
 - Test full round-trip: Earth→Sun→Earth
 ---
 ### Phase 2: Remove or Modify Hysteresis (Critical for Round-Trips)
 **Current Problem:**
 The 0.5x hysteresis factor prevents oscillation but creates one-way barriers:
 ```cpp
 if (distance < dist_to_current * 0.5) {
    dominant = i;
 }
 ```
 **Option A: Remove Hysteresis**
 - Remove 0.5x factor (line 71 in `simulation.cpp`)
 - Allow switching to closest body at all times
 - **Pros:** Simple, enables all transitions
 - **Cons:** May cause oscillation at SOI boundaries
 **Option B: Adaptive Hysteresis (Recommended)**
 - Keep hysteresis but only apply when already in SOI
 - Allow free switching when outside current SOI
 - **Pros:** Prevents oscillation while enabling round-trips
 - **Cons:** More complex logic
 **Option B Implementation:**
 ```cpp
 if (can_switch && i != dominant) {
    if (dominant == -1) {
        dominant = i;
    } else {
        CelestialBody* current_parent = &sim->bodies[dominant];
        double dist_to_current = vec3_distance(body->position, current_parent->position);
        if (outside_current_soi) {
            // Outside current SOI: switch to closest body (no hysteresis)
            if (distance < dist_to_current) {
                dominant = i;
            }
        } else {
            // Inside current SOI: apply hysteresis to prevent oscillations
            if (distance < dist_to_current * 0.5) {
                dominant = i;
            }
        }
    }
 }
 ```
 **Files to modify:**
 - `src/simulation.cpp` (line 70-75)
 **Estimated complexity:** Low-Medium
 **Risk:** Medium (may affect transition behavior)
 **Expected outcome:**
 - ✅ Enables round-trip transitions (Earth→Sun→Earth)
 - ✅ Maintains stability by preventing oscillation when inside SOI
 - ✅ Allows free switching when outside current SOI
 **Tests to add:**
 - Validate Satellite→Planet→Satellite round-trip
 - Validate Earth→Sun→Mars→Sun→Earth full round-trip
 ---
 ### Phase 3: Refactor Transition to Separate Function
 **Goal:** Cleaner code, easier to test, better separation of concerns
 **Current state:** Transition logic is inline in `update_simulation()` (lines 105-120)
 **Proposed refactoring:**
 **Add to `simulation.h`:**
 ```cpp
 void transition_to_new_parent(SimulationState* sim, CelestialBody* body,
                           int old_parent_idx, int new_parent_idx);
 ```
 **Add to `simulation.cpp`:**
 ```cpp
 void transition_to_new_parent(SimulationState* sim, CelestialBody* body,
                           int old_parent_idx, int new_parent_idx) {
    // Current state is in old parent's frame
    Vec3 old_local_pos = body->local_position;
    Vec3 old_local_vel = body->local_velocity;
    // Convert to global coordinates using old parent
    if (old_parent_idx >= 0 && old_parent_idx < sim->body_count) {
        CelestialBody* old_parent = &sim->bodies[old_parent_idx];
        body->position = vec3_add(old_local_pos, old_parent->position);
        body->velocity = vec3_add(old_local_vel, old_parent->velocity);
    } else {
        // old_parent is root (Sun): local = global
        body->position = old_local_pos;
        body->velocity = old_local_vel;
    }
    // Update parent index
    body->parent_index = new_parent_idx;
    // Convert to local coordinates using new parent
    if (new_parent_idx >= 0 && new_parent_idx < sim->body_count) {
        CelestialBody* new_parent_body = &sim->bodies[new_parent_idx];
        body->local_position = vec3_sub(body->position, new_parent_body->position);
        body->local_velocity = vec3_sub(body->velocity, new_parent_body->velocity);
    } else {
        // new_parent is root (Sun): global = local
        body->local_position = body->position;
        body->local_velocity = body->velocity;
    }
 }
 ```
 **Update `update_simulation()`:**
 ```cpp
 int new_parent = find_dominant_body(sim, i);
 if (new_parent != body->parent_index) {
    transition_to_new_parent(sim, body, body->parent_index, new_parent);
 }
 ```
 **Files to modify:**
 - `src/simulation.h` (add function declaration)
 - `src/simulation.cpp` (extract and refactor transition logic)
 **Estimated complexity:** Low
 **Risk:** Low (pure refactor, no behavior change)
 **Expected outcome:**
 - ✅ Cleaner code with better separation of concerns
 - ✅ Easier to unit test transition logic
 - ✅ Follows Phase 3 plan from hierarchical_frames_plan.md
 **Tests to add:**
 - Unit tests for `transition_to_new_parent()` with all scenarios:
  - Body→Body transition
  - Body→Root transition
  - Root→Body transition
  - Root→Root transition (edge case)
 ---
 ### Phase 4: Multi-Body Transition Test Configs
 **Goal:** Create realistic test scenarios for patched conics
 #### Test Config 1: Satellite Rendezvous
 **File:** `tests/configs/satellite_rendezvous.toml`
 ```toml
 [[bodies]]
 name = "Sun"
 mass = 1.989e30
 radius = 6.96e8
 position = { x = 0.0, y = 0.0, z = 0.0 }
 parent_index = -1
 color = { r = 1.0, g = 1.0, b = 0.0 }
 eccentricity = 0.0
 semi_major_axis = 0.0
 [[bodies]]
 name = "Earth"
 mass = 5.972e24
 radius = 6.371e6
 position = { x = 1.496e11, y = 0.0, z = 0.0 }
 parent_index = 0
 color = { r = 0.0, g = 0.5, b = 1.0 }
 eccentricity = 0.0
 semi_major_axis = 1.496e11
 [[bodies]]
 name = "Moon"
 mass = 7.342e22
 radius = 1.737e6
 position = { x = 1.49984e11, y = 0.0, z = 0.0 }
 parent_index = 1
 color = { r = 0.7, g = 0.7, b = 0.7 }
 eccentricity = 0.0
 semi_major_axis = 3.844e8
 [[bodies]]
 name = "Satellite"
 mass = 1.0e3
 radius = 1.0e1
 position = { x = 1.500e11, y = 1.0e8, z = 0.0 }
 parent_index = 1
 color = { r = 1.0, g = 0.0, b = 1.0 }
 eccentricity = 0.2
 semi_major_axis = 4.0e8
 ```
 **Scenario:** Satellite launches from Earth, transfers to Moon, returns
 #### Test Config 2: Interplanetary Transfer
 **File:** `tests/configs/interplanetary_transfer.toml`
 ```toml
 [[bodies]]
 name = "Sun"
 mass = 1.989e30
 radius = 6.96e8
 position = { x = 0.0, y = 0.0, z = 0.0 }
 parent_index = -1
 color = { r = 1.0, g = 1.0, b = 0.0 }
 eccentricity = 0.0
 semi_major_axis = 0.0
 [[bodies]]
 name = "Earth"
 mass = 5.972e24
 radius = 6.371e6
 position = { x = 1.496e11, y = 0.0, z = 0.0 }
 parent_index = 0
 color = { r = 0.0, g = 0.5, b = 1.0 }
 eccentricity = 0.0
 semi_major_axis = 1.496e11
 [[bodies]]
 name = "Mars"
 mass = 6.39e23
 radius = 3.3895e6
 position = { x = 2.279e11, y = 0.0, z = 0.0 }
 parent_index = 0
 color = { r = 0.8, g = 0.3, b = 0.1 }
 eccentricity = 0.0
 semi_major_axis = 2.279e11
 [[bodies]]
 name = "Probe"
 mass = 1.0e3
 radius = 1.0e1
 position = { x = 1.496e11, y = 0.0, z = 0.0 }
 parent_index = 1
 color = { r = 0.0, g = 1.0, b = 0.0 }
 eccentricity = 0.5
 semi_major_axis = 1.888e11
 ```
 **Scenario:** Probe: Earth→Sun→Mars
 #### Test Config 3: Moon Capture
 **File:** `tests/configs/moon_capture.toml`
 ```toml
 [[bodies]]
 name = "Sun"
 mass = 1.989e30
 radius = 6.96e8
 position = { x = 0.0, y = 0.0, z = 0.0 }
 parent_index = -1
 color = { r = 1.0, g = 1.0, b = 0.0 }
 eccentricity = 0.0
 semi_major_axis = 0.0
 [[bodies]]
 name = "Jupiter"
 mass = 1.898e27
 radius = 6.9911e7
 position = { x = 7.785e11, y = 0.0, z = 0.0 }
 parent_index = 0
 color = { r = 0.9, g = 0.7, b = 0.5 }
 eccentricity = 0.0
 semi_major_axis = 7.785e11
 [[bodies]]
 name = "Ganymede"
 mass = 1.48e23
 radius = 2.634e6
 position = { x = 7.796e11, y = 0.0, z = 0.0 }
 parent_index = 1
 color = { r = 0.6, g = 0.6, b = 0.5 }
 eccentricity = 0.0
 semi_major_axis = 1.070e9
 [[bodies]]
 name = "Comet"
 mass = 1.0e14
 radius = 5.0e3
 position = { x = 1.0e12, y = 0.0, z = 0.0 }
 parent_index = 0
 color = { r = 0.5, g = 0.8, b = 1.0 }
 eccentricity = 2.0
 semi_major_axis = -5.0e11
 ```
 **Scenario:** Comet: Sun→Jupiter→Ganymede→Sun
 **Files to create:**
 - `tests/configs/satellite_rendezvous.toml`
 - `tests/configs/interplanetary_transfer.toml`
 - `tests/configs/moon_capture.toml`
 **Estimated complexity:** Low
 **Risk:** Low (configs only, no code changes)
 **Expected outcome:**
 - ✅ Realistic test scenarios for patched conics
 - ✅ Covers multi-leg missions
 - ✅ Tests root body transitions
 ---
 ### Phase 5: Adaptive Timestepping (Performance + Accuracy)
 **Goal:** Different timesteps for different orbital phases
 **Problem:** Fixed 60s timestep is:
 - Too coarse for fast orbital phases (moon capture)
 - Too slow for deep-space phases
 **Proposed solution:** Adaptive timestep based on orbital period
 **Implementation:**
 ```cpp
 double calculate_adaptive_timestep(CelestialBody* body, CelestialBody* parent) {
    if (parent == NULL || body->semi_major_axis <= 0.0) {
        return 60.0;  // Default timestep
    }
    // Calculate orbital period using Kepler's third law
    double T = 2.0 * M_PI * sqrt(pow(body->semi_major_axis, 3) / (G * parent->mass));
    // Use 1/1000 of orbital period as timestep
    double adaptive_dt = T / 1000.0;
    // Clamp to reasonable bounds
    adaptive_dt = fmax(adaptive_dt, 10.0);   // Minimum 10s
    adaptive_dt = fmin(adaptive_dt, 600.0);  // Maximum 600s
    return adaptive_dt;
 }
 ```
 **Changes required:**
 1. Add per-body timesteps to `SimulationState`
 2. Update `update_simulation()` to use adaptive timesteps
 3. Add synchronization mechanism (multiple timesteps)
 **Complexity:** High
 **Risk:** High (may affect energy conservation, requires careful testing)
 **Expected outcome:**
 - ✅ Better accuracy for fast orbits (moon capture)
 - ✅ Faster simulation for deep-space phases
 - ✅ Energy conserved across transitions
 **Tests to add:**
 - Verify energy drift with adaptive timesteps
 - Verify orbital period accuracy with adaptive timesteps
 - Test stability across SOI transitions
 ---
 ### Phase 6: Enhanced Debugging & Visualization
 **Goal:** Better tools for debugging transitions and planning missions
 **Features to add:**
 #### 6.1 Transition Logging
 ```cpp
 void log_transition(SimulationState* sim, CelestialBody* body,
                  int old_parent, int new_parent, double time) {
    printf("[%.2f days] %s: parent %d → %d\n",
           time / 86400.0, body->name, old_parent, new_parent);
 }
 ```
 #### 6.2 Visual SOI Boundaries
 - Add wireframe spheres in renderer for SOI radii
 - Toggle with keyboard key
 - Use different colors for different bodies
 #### 6.3 Trajectory Prediction
 - Predict future trajectory for given time span
 - Show predicted SOI crossings
 - Assist with mission planning
 **Files to modify:**
 - `src/simulation.cpp` (logging)
 - `src/renderer.cpp` (SOI visualization)
 - `src/renderer.cpp` (trajectory prediction - new function)
 **Estimated complexity:** Medium
 **Risk:** Low (mostly UI/visualization)
 **Expected outcome:**
 - ✅ Better debugging tools for transitions
 - ✅ Visual SOI boundaries
 - ✅ Trajectory prediction for mission planning
 ---
 ## Open Questions
 ### Question 1: Hysteresis Strategy
 **Context:** The 0.5x hysteresis factor prevents oscillation but creates one-way barriers.
 **Options:**
 - **Option A:** Remove hysteresis entirely
  - Pros: Simple, enables all transitions
  - Cons: May cause oscillation at SOI boundaries
 - **Option B:** Adaptive hysteresis (recommended)
  - Pros: Prevents oscillation while enabling round-trips
  - Cons: More complex logic
 **Recommendation:** Option B - keep stability while enabling your use case
 **Decision needed:** Which approach should we implement?
 ---
 ### Question 2: Integration Timing
 **Context:** Transition happens before integration in the same timestep, using coordinates from the end of the previous timestep. This may cause velocity discontinuities.
 **Options:**
 - **Option A:** Keep current approach (transition at start of timestep)
  - Pros: Simple, works for most cases
  - Cons: May have slight velocity discontinuities
 - **Option B:** Transition in middle of timestep (half-step approach)
  - Pros: Better accuracy, smoother transitions
  - Cons: More complex, requires half-step RK4
 - **Option C:** Transition after integration, then integrate again
  - Pros: Ensures continuity
  - Cons: Doubles computation, complex
 **Recommendation:** Start with Option A, move to Option B if needed
 **Decision needed:** Should we implement half-step transitions for better accuracy?
 ---
 ### Question 3: Test Priorities
 **Context:** We have three test scenarios to validate patched conics.
 **Options:**
 - **Option A:** Start with "Satellite Rendezvous" (Earth→Moon→Earth)
  - Pros: Simpler, 2-body transition, quick to implement
  - Cons: Doesn't test root body transitions
 - **Option B:** Start with "Interplanetary Transfer" (Earth→Sun→Mars)
  - Pros: Tests root body transitions, realistic scenario
  - Cons: More complex, longer simulation time
 - **Option C:** Implement all three in parallel
  - Pros: Comprehensive coverage
  - Cons: More work upfront
 **Recommendation:** Option A first, then Option B, then Option C
 **Decision needed:** Which test scenario should we start with?
 ---
 ### Question 4: Adaptive Timesteps Priority
 **Context:** Fixed 60s timestep may be suboptimal for different orbital phases.
 **Options:**
 - **Option A:** Implement adaptive timesteps now
  - Pros: Better accuracy and performance from the start
  - Cons: Adds complexity, may delay other features
 - **Option B:** Use fixed timesteps for now, optimize later
  - Pros: Simpler implementation, focus on transitions first
  - Cons: May need to revisit later
 **Recommendation:** Option B - get transitions working first, then optimize
 **Decision needed:** Is adaptive timestepping critical for your use case?
 ---
 ## Success Criteria
 ### Phase 1 Success
 - [ ] Satellite can transition to/from Sun
 - [ ] Tests pass for Earth→Sun→Mars
 - [ ] No energy conservation issues during transitions
 ### Phase 2 Success
 - [ ] Round-trip transitions work (Earth→Sun→Earth)
 - [ ] No oscillation at SOI boundaries
 - [ ] Tests validate stability
 ### Phase 3 Success
 - [ ] Transition logic extracted to separate function
 - [ ] Unit tests cover all transition scenarios
 - [ ] Code is cleaner and more maintainable
 ### Phase 4 Success
 - [ ] Three test configs created
 - [ ] All test scenarios pass
 - [ ] Configs are realistic and well-documented
 ### Phase 5 Success (Optional)
 - [ ] Adaptive timesteps implemented
 - [ ] Energy drift < 1% with adaptive timesteps
 - [ ] Performance improved for deep-space phases
 ### Phase 6 Success (Optional)
 - [ ] Transition logging works
 - [ ] SOI boundaries visualized
 - [ ] Trajectory prediction functional
 ---
 ## Timeline Estimate
 - **Phase 1:** 1-2 days (fix root body transitions)
 - **Phase 2:** 1 day (adaptive hysteresis)
 - **Phase 3:** 0.5 days (refactoring)
 - **Phase 4:** 1 day (test configs)
 - **Phase 5:** 2-3 days (adaptive timesteps - optional)
 - **Phase 6:** 1-2 days (debugging/visualization - optional)
 **Total for core features (Phases 1-4):** 4-5 days
 **Total with all features:** 8-10 days
 ---
 ## Dependencies
 ### Required
 - ✅ Hierarchical coordinate frames (complete)
 - ✅ Local frame integration (complete)
 - ✅ Parent-first update order (complete)
 - ⏸️ Root body transitions (Phase 1 - pending)
 ### Optional
 - ⏸️ Adaptive timesteps (Phase 5 - optional)
 - ⏸️ Debugging tools (Phase 6 - optional)
 ---
 ## Risks and Mitigations
 ### High Risk
 - **Energy conservation during transitions**
  - Mitigation: Careful testing, energy drift checks
  - Backup: Keep old code for rollback
 - **Numerical precision across scales**
  - Mitigation: Use local frames (already implemented)
  - Backup: Double precision (already used)
 ### Medium Risk
 - **Oscillation at SOI boundaries**
  - Mitigation: Adaptive hysteresis (Phase 2)
  - Backup: Increase hysteresis factor if needed
 - **Timestep too coarse for fast orbits**
  - Mitigation: Adaptive timesteps (Phase 5 - optional)
  - Backup: Reduce fixed timestep if needed
 ### Low Risk
 - **Code complexity increases**
  - Mitigation: Good unit tests, refactoring (Phase 3)
  - Backup: Keep functions small and focused
 ---
 ## References
 - `docs/hierarchical_frames_plan.md` - Phase 3: SOI Transition with Frame Transform
 - `docs/implementation_plan.md` - SOI Transition Mechanics section
 - `src/simulation.cpp` - Current SOI transition implementation (lines 103-121)
 - `tests/test_soi_transition.cpp` - Current SOI transition tests