From 59e535d818920b0792e6cbbd88ecbb8c19bb2648 Mon Sep 17 00:00:00 2001 From: cinnaboot Date: Wed, 14 Jan 2026 12:19:51 -0500 Subject: [PATCH] Record implementation decisions for patched conics Decisions made: 1. Hysteresis: Adaptive approach (Option B) - prevents oscillation while enabling round-trips 2. Integration timing: Current approach (Option A) - defer half-step optimization to future TODO 3. Test priorities: Create all 3 test cases first - expect failures for unimplemented features 4. Adaptive timesteps: Deferred to later work - focus on SOI transitions first Updated plan with: - Decisions Made section documenting all 4 choices - Updated implementation phases with decisions - Updated timeline and success criteria - Marked Phase 5 as deferred - Ready to begin Phase 1 implementation --- docs/patched_conics_plan.md | 153 ++++++++++++++++++------------------ 1 file changed, 77 insertions(+), 76 deletions(-) diff --git a/docs/patched_conics_plan.md b/docs/patched_conics_plan.md index 2614716..fbd554e 100644 --- a/docs/patched_conics_plan.md +++ b/docs/patched_conics_plan.md @@ -1,8 +1,16 @@ # Patched Conics and SOI Transition Implementation Plan **Date:** January 14, 2026 -**Status:** Planning Phase -**Branch:** To be created +**Status:** Implementation Ready (Decisions Made) +**Branch:** patched-conics + +**Decisions Made:** +1. ✅ Hysteresis: Adaptive approach (Option B) +2. ✅ Integration timing: Current approach (Option A), TODO for future +3. ✅ Test priorities: Create all 3 test cases first +4. ✅ Adaptive timesteps: Deferred to later work (Phase 5) + +**Next Step:** Begin Phase 1 - Fix Root Body Transitions ## Overview @@ -116,7 +124,7 @@ Satellites crossing between star/planet/moon scales will see position magnitude --- -### Phase 2: Remove or Modify Hysteresis (Critical for Round-Trips) +### Phase 2: Adaptive Hysteresis (Critical for Round-Trips) **Current Problem:** The 0.5x hysteresis factor prevents oscillation but creates one-way barriers: @@ -126,13 +134,8 @@ if (distance < dist_to_current * 0.5) { } ``` -**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 +**Decision:** Adaptive Hysteresis (Option B) - **DECIDED ✅** -**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 @@ -261,6 +264,14 @@ if (new_parent != body->parent_index) { **Goal:** Create realistic test scenarios for patched conics +**Decision:** Create all three test cases first, expect failures for unimplemented features - **DECIDED ✅** + +**Implementation approach:** +1. Create all three test configurations +2. Run tests to establish baseline failures +3. Tests validate features as they're implemented +4. Comprehensive coverage from the start + #### Test Config 1: Satellite Rendezvous **File:** `tests/configs/satellite_rendezvous.toml` @@ -421,6 +432,8 @@ semi_major_axis = -5.0e11 **Goal:** Different timesteps for different orbital phases +**Decision:** DEFERRED to later work - **DECIDED ✅** + **Problem:** Fixed 60s timestep is: - Too coarse for fast orbital phases (moon capture) - Too slow for deep-space phases @@ -435,7 +448,7 @@ double calculate_adaptive_timestep(CelestialBody* body, CelestialBody* parent) { } // Calculate orbital period using Kepler's third law - double T = 2.0 * M_PI * sqrt(pow(body->semi_major_axis, 3) / (G * parent->mass)); + 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; @@ -508,85 +521,67 @@ void log_transition(SimulationState* sim, CelestialBody* body, --- -## Open Questions - -### Question 1: Hysteresis Strategy -**Context:** The 0.5x hysteresis factor prevents oscillation but creates one-way barriers. +## Decisions Made -**Options:** -- **Option A:** Remove hysteresis entirely - - Pros: Simple, enables all transitions - - Cons: May cause oscillation at SOI boundaries +### Decision 1: Hysteresis Strategy ✅ +**Chosen:** Option B - Adaptive hysteresis approach -- **Option B:** Adaptive hysteresis (recommended) - - Pros: Prevents oscillation while enabling round-trips - - Cons: More complex logic +**Rationale:** +- Prevents oscillation while enabling round-trips +- Maintains stability during normal operation +- Allows free switching when outside current SOI +- Best balance between stability and flexibility -**Recommendation:** Option B - keep stability while enabling your use case - -**Decision needed:** Which approach should we implement? +**Implementation:** Will use adaptive hysteresis in Phase 2 (lines 70-75 in simulation.cpp) --- -### 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 +### Decision 2: Integration Timing ✅ +**Chosen:** Option A - Keep current approach (transition at start of timestep) -- **Option B:** Transition in middle of timestep (half-step approach) - - Pros: Better accuracy, smoother transitions - - Cons: More complex, requires half-step RK4 +**Rationale:** +- Simple, works for most cases +- Start with proven approach +- Defer optimization to future work -- **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? +**TODO:** Consider half-step transitions (Option B) if velocity discontinuities become problematic --- -### 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 +### Decision 3: Test Priorities ✅ +**Chosen:** Option C - Implement all three test cases first -- **Option C:** Implement all three in parallel - - Pros: Comprehensive coverage - - Cons: More work upfront +**Rationale:** +- Create all test configurations upfront +- Expect failures for unimplemented features +- Use tests as validation throughout implementation +- Comprehensive coverage from the start -**Recommendation:** Option A first, then Option B, then Option C +**Implementation:** +1. Create all three test configs (Phase 4) +2. Run tests to establish baseline failures +3. Implement features to make tests pass +4. Re-run tests after each phase -**Decision needed:** Which test scenario should we start with? +**Test scenarios:** +- Satellite Rendezvous (Earth→Moon→Earth) +- Interplanetary Transfer (Earth→Sun→Mars) +- Moon Capture (Sun→Jupiter→Ganymede→Sun) --- -### 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 +### Decision 4: Adaptive Timesteps Priority ✅ +**Chosen:** Option B - Defer to later work -- **Option B:** Use fixed timesteps for now, optimize later - - Pros: Simpler implementation, focus on transitions first - - Cons: May need to revisit later +**Rationale:** +- Focus on SOI transitions first +- Fixed 60s timestep works adequately for testing +- Optimize performance and accuracy after core features complete -**Recommendation:** Option B - get transitions working first, then optimize - -**Decision needed:** Is adaptive timestepping critical for your use case? +**TODO:** Implement adaptive timesteps in future update (Phase 5) +- Will address: Too coarse for fast orbits, too slow for deep space +- Estimated complexity: High +- Timeline: 2-3 days --- @@ -609,10 +604,10 @@ void log_transition(SimulationState* sim, CelestialBody* body, ### Phase 4 Success - [ ] Three test configs created -- [ ] All test scenarios pass +- [ ] Baseline test failures documented - [ ] Configs are realistic and well-documented -### Phase 5 Success (Optional) +### Phase 5 Success (Deferred) - [ ] Adaptive timesteps implemented - [ ] Energy drift < 1% with adaptive timesteps - [ ] Performance improved for deep-space phases @@ -627,14 +622,20 @@ void log_transition(SimulationState* sim, CelestialBody* body, ## Timeline Estimate - **Phase 1:** 1-2 days (fix root body transitions) -- **Phase 2:** 1 day (adaptive hysteresis) +- **Phase 2:** 1 day (adaptive hysteresis - decision made ✅) - **Phase 3:** 0.5 days (refactoring) -- **Phase 4:** 1 day (test configs) -- **Phase 5:** 2-3 days (adaptive timesteps - optional) +- **Phase 4:** 1 day (test configs - create all three first) +- **Phase 5:** 2-3 days (adaptive timesteps - DEFERRED ⏸️) - **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 +**Total with all features:** 8-10 days (including deferred Phases 5-6) + +**Implementation approach:** +1. Create all three test configs (Phase 4) +2. Implement core transition features (Phases 1-3) +3. Validate with tests after each phase +4. Defer Phases 5-6 to future work ---