From ecf225310a57e38f18a7a44ac897013bda554307 Mon Sep 17 00:00:00 2001 From: cinnaboot Date: Mon, 19 Jan 2026 10:29:13 -0500 Subject: [PATCH] Remove deprecated mission planning doc backup --- docs/mission_planning.md.old | 843 ----------------------------------- 1 file changed, 843 deletions(-) delete mode 100644 docs/mission_planning.md.old diff --git a/docs/mission_planning.md.old b/docs/mission_planning.md.old deleted file mode 100644 index 64cd576..0000000 --- a/docs/mission_planning.md.old +++ /dev/null @@ -1,843 +0,0 @@ -# Mission Planning Module - Implementation Plan - -**Date:** January 16, 2026 -**Status:** Phase 1-3 Complete ✅, Phase 4 Debugging Required 🔄 -**Branch:** patched-conics -**Implementation Progress:** 70% complete (3/6 phases complete, 1 phase debugging) - -## Implementation Progress - -### ✅ Phase 1: Core Transfer Calculations - COMPLETE -**Status:** All tests passing (3/3) -**Date Completed:** January 16, 2026 - -**Implemented:** -- `calculate_hohmann_transfer()` - Computes transfer orbit parameters -- `calculate_angular_position()` - Calculates body angle in XY plane -- `calculate_required_phase_angle()` - Computes optimal launch phase angle - -**Validation:** -- Earth→Mars transfer time: 258.8 days (±0.08% of expected) -- Required phase angle: 44.3° (±0.08° of expected) -- Delta-v injection: 2.94 km/s (±0.01% of expected) -- All NASA reference values validated within 5% - -**Tests:** `tests/test_mission_planning.cpp` - 17 assertions, 6 test cases, all pass - ---- - -### ✅ Phase 2: Launch Window Detection - COMPLETE -**Status:** All tests passing -**Date Completed:** January 16, 2026 - -**Implemented:** -- `check_launch_window()` - Tests if current phase angle allows optimal launch -- `wait_for_launch_window()` - Fast-forwards simulation to launch window - -**Validation:** -- Launch window detection works correctly -- Fast-forward advances simulation to correct phase (within 1°) -- Wait time: ~94 days for Earth→Mars transfer window -- Phase angle wrapping handled correctly (0-360° range) - -**Tests:** Integrated into mission planning test suite - all pass - ---- - -### ✅ Phase 3: Spacecraft Spawning - COMPLETE -**Status:** All tests passing (9/9 assertions) -**Date Completed:** January 16, 2026 - -**Implemented:** -- `add_body_to_simulation()` - Dynamic body creation in simulation.cpp -- `spawn_spacecraft_on_transfer()` - Creates spacecraft with correct velocity - -**Validation:** -- Spacecraft spawns at correct position (0m error from departure body) -- Spacecraft velocity = departure velocity + Δv (0% error) -- Spacecraft parent = Sun (index 0) -- Local/global coordinates initialized correctly -- SOI radius calculated correctly - -**Tests:** `tests/test_hohmann_transfer.cpp::Spacecraft spawning` - 9 assertions, all pass - -**Key Implementation Details:** -- Uses departure body's actual velocity direction (not computed from position) -- Spacecraft mass = 1.0 kg (test particle, mass cancels in physics) -- Position and velocity set before adding to simulation -- Coordinate transforms handle parent=0 (Sun) correctly - ---- - -### ⏸️ Phase 4: Full Transfer Test - DEBUGGING REQUIRED -**Status:** Partially implemented, trajectory issue identified -**Date Started:** January 16, 2026 -**Issue:** Spacecraft trajectory deviates from expected Hohmann transfer orbit - -**Implemented:** -- Test framework for Earth→Mars transfer -- Launch window detection and waiting -- Spacecraft spawning with transfer parameters -- Energy drift tracking and validation - -**Current Issue:** -- Spacecraft spawns with correct initial conditions (position, velocity, parent) -- Initial orbital energy: -3.52×10⁸ J (correct for transfer orbit) -- After first `update_simulation()` call, spacecraft trajectory diverges -- Final orbital energy: +3.51×10²³ J (huge energy error, wrong sign!) -- Spacecraft not following Hohmann transfer ellipse -- Energy drift: 9.98×10¹⁶% (unphysically large) - -**Debugging Findings:** -1. Spacecraft spawns correctly: - - Global position matches Earth: (-6.94×10⁹, -1.49×10¹¹, 0) m - - Global velocity correct: (-32697.6, 1518.47, 0) m/s - - Parent = Sun (index 0) - - Local position initially correct relative to Sun - -2. After first `update_simulation()`: - - Local position jumps incorrectly to: (6.11×10⁷, -2.84×10⁶, 0) m - - This suggests `compute_global_coordinates()` or local frame integration is wrong - -3. Possible root causes: - - Bug in `update_simulation()` coordinate transforms for newly added bodies - - Issue with local frame integration when parent = 0 (Sun) - - `compute_global_coordinates()` not called correctly after body addition - - SOI transition logic interfering with spacecraft (only 1 SOI transition detected) - -4. Investigation needed: - - Add debug output to `update_simulation()` to track coordinate transforms - - Check if `find_dominant_body()` incorrectly changing spacecraft's parent - - Verify RK4 integration is using correct reference frame - - Test with spacecraft starting at parent ≠ 0 (compare behavior) - -**Tests:** `tests/test_hohmann_transfer.cpp::Earth → Mars Hohmann Transfer - Basic` -- Current: 4/5 assertions pass -- Failing: Energy drift validation (expect < 5%, actual 9.98×10¹⁶%) - -**Next Steps for Debugging:** -1. Add detailed logging to `update_simulation()` to track coordinate transforms -2. Verify spacecraft's local position/velocity before/after each update -3. Check if parent index changes unexpectedly during simulation -4. Consider if `add_body_to_simulation()` needs to call `compute_global_coordinates()` -5. Test with simplified scenario (e.g., Earth → fake destination at 1.2 AU) - -**Estimated Time to Resolve:** 2-3 hours of focused debugging - ---- - -### ⏸️ Phase 5: Enhance Root Body Transition Tests - NOT STARTED -**Status:** Deferred until Phase 4 debugged -**Dependency:** Phase 4 (working transfer orbits required) - ---- - -### ⏸️ Phase 6: Round-Trip Mission - NOT STARTED -**Status:** Deferred until Phase 4 debugged -**Dependency:** Phase 4 (single-leg transfer must work first) - ---- - -## Overview -Add a mission planning module to calculate realistic interplanetary transfers with proper departure windows, replacing manual config positioning with computed trajectories. This enables proper testing of patched conics mechanics and provides a foundation for spacecraft simulation. - -## Design Decisions - -1. **Spacecraft Mass**: Use small but non-zero (1.0 kg) - works with existing physics (mass cancels out in acceleration) -2. **Capture Burns**: Skip for initial implementation - implement flyby missions only -3. **Inclination**: Planar first (z=0), defer 3D to future work -4. **Scope**: Full mission planner with departure window timing, launch window detection, and spacecraft spawning - -## Key Technical Discovery - -The physics engine already supports test particles correctly. The acceleration calculation is: -``` -acceleration = (G × body_mass × parent_mass / r²) / body_mass = G × parent_mass / r² -``` - -Body mass cancels out, so any small mass works. We'll use 1.0 kg. - -## Data Structures - -### TransferParameters -```cpp -struct TransferParameters { - double semi_major_axis; // Transfer orbit semi-major axis (meters) - double eccentricity; // Transfer orbit eccentricity - double periapsis; // Closest approach (departure radius) - double apoapsis; // Furthest distance (arrival radius) - double transfer_time; // Time required for transfer (seconds) - double departure_velocity; // Required velocity at departure (m/s) - double arrival_velocity; // Velocity at arrival (relative to Sun, m/s) - double phase_angle_deg; // Required phase angle for launch (degrees) - double delta_v_injection; // Delta-V needed for transfer injection (m/s) - double delta_v_capture; // Delta-V needed for capture (optional, future) -}; -``` - -## Implementation Phases - -### Phase 1: Core Transfer Calculations (1 day) - -**Goal:** Implement orbital mechanics calculations for Hohmann transfers - -**Files:** -- `src/mission_planning.h` (new) - Function declarations -- `src/mission_planning.cpp` (new) - Core calculations -- `tests/test_mission_planning.cpp` (new) - Unit tests for formulas - -**Functions to implement:** - -#### 1.1 `calculate_hohmann_transfer()` -Calculates transfer orbit parameters given departure and arrival radii. - -**Algorithm:** -``` -a_transfer = (r_departure + r_arrival) / 2 -e = (r_arrival - r_departure) / (r_arrival + r_departure) -T_transfer = π × sqrt(a³ / GM) - -v_departure = sqrt(G × M × (2/r_departure - 1/a)) -v_arrival = sqrt(G × M × (2/r_arrival - 1/a)) -v_circular = sqrt(G × M / r_departure) - -Δv_injection = v_departure - v_circular -``` - -**Validation:** Earth→Mars values: -- Transfer time: ~259 days -- Phase angle: ~44.3° -- Δv: ~2.94 km/s - -#### 1.2 `calculate_angular_position()` -Calculates angular position of a body relative to its center (in XY plane). - -**Algorithm:** -``` -rel_pos = body_position - center_position -angle = atan2(y, x) -Normalize to [0, 2π) -``` - -#### 1.3 `calculate_required_phase_angle()` -Calculates optimal phase angle for launch. - -**Algorithm:** -``` -ω_departure = 2π / T_departure -α = ω_departure × T_transfer -phase_angle = π - α (in radians) -Convert to degrees -``` - -**Tests:** -- Validate transfer parameters against NASA reference values (±5%) -- Verify angular position calculations for circular orbits -- Test phase angle formula with known cases - -**Expected outcome:** -- ✅ Accurate transfer orbit calculations -- ✅ Verified against known mission parameters - -**Estimated complexity:** Low -**Risk:** Low (well-known orbital mechanics formulas) - ---- - -### Phase 2: Launch Window Detection (1 day) - -**Goal:** Detect when launch window is open and advance simulation to it - -**Files:** -- `src/mission_planning.cpp` (extend) -- `tests/test_launch_window.cpp` (new) - -**Functions to implement:** - -#### 2.1 `check_launch_window()` -Tests if current positions allow optimal launch. - -**Algorithm:** -``` -θ_depart = calculate_angular_position(departure, sun) -θ_arrival = calculate_angular_position(arrival, sun) - -current_phase = θ_arrival - θ_depart (normalize to [0, 2π)) -current_phase_deg = current_phase × (180/π) - -error = |current_phase_deg - required_phase_angle_deg| -Handle wrap-around: if error > 180°, use |error - 360°| - -return error <= tolerance -``` - -#### 2.2 `wait_for_launch_window()` -Advances simulation until launch window opens. - -**Algorithm:** -``` -while !check_launch_window(...): - Fast-forward by 1 day per iteration (for efficiency) - for i in 0..(86400 / dt): - update_simulation(sim) -``` - -**Tests:** -- Create Earth+Mars config at wrong phase angle -- Call `wait_for_launch_window()` - should advance simulation -- Verify phase angle is now within tolerance (1°) -- Measure time waited - should be reasonable (weeks to months) - -**Expected outcome:** -- ✅ Can detect proper launch windows -- ✅ Can advance simulation to launch window -- ✅ Phase angle accuracy within 1° - -**Estimated complexity:** Low-Medium -**Risk:** Low (simulation fast-forward is safe) - ---- - -### Phase 3: Spacecraft Spawning (1.5 days) - -**Goal:** Create spacecraft at departure with correct velocity - -**Files:** -- `src/simulation.h` (+3 lines) - Add function declaration -- `src/simulation.cpp` (+30 lines) - Implement dynamic body addition -- `src/mission_planning.cpp` (+40 lines) - Spacecraft spawning logic - -**Functions to implement:** - -#### 3.1 `add_body_to_simulation()` (in simulation.cpp) -Adds a new body to the simulation at runtime. - -**Algorithm:** -``` -Check capacity (body_count < max_bodies) -Copy body to next available slot -Initialize local coordinates: - if parent_index >= 0: - local_pos = global_pos - parent_pos - local_vel = global_vel - parent_vel - else: - local_pos = global_pos - local_vel = global_vel -Calculate SOI radius (if has parent) -Increment body_count -Return new body index -``` - -#### 3.2 `spawn_spacecraft_on_transfer()` (in mission_planning.cpp) -Creates spacecraft on transfer trajectory at departure. - -**Algorithm:** -``` -Create spacecraft body: - name = "Spacecraft" - mass = 1.0 kg (negligible but non-zero) - radius = 1.0 km (for visualization) - color = magenta/pink - eccentricity = transfer.eccentricity - semi_major_axis = transfer.semi_major_axis - -Position = departure.position - -Velocity = departure.velocity + Δv_injection: - departure_pos = departure.position - sun.position - orbit_dir = normalize(cross(departure_pos, z_axis)) - delta_v = orbit_dir × transfer.delta_v_injection - spacecraft.velocity = departure.velocity + delta_v - -Parent = Sun (index 0) -Add to simulation via add_body_to_simulation() -Return spacecraft index -``` - -**Tests:** -- Spawn spacecraft at Earth -- Verify initial position matches Earth -- Verify velocity = Earth velocity + Δv -- Verify parent = Sun -- Verify local coordinates initialized correctly - -**Expected outcome:** -- ✅ Spacecraft spawns correctly at departure -- ✅ Initial velocity matches transfer requirements -- ✅ Parent set to Sun for transfer orbit -- ✅ Local/global coordinates consistent - -**Estimated complexity:** Medium -**Risk:** Medium (dynamic body addition affects simulation state) - ---- - -### Phase 4: Full Transfer Test (1.5 days) - -**Goal:** End-to-end test of Earth→Mars Hohmann transfer - -**Files:** -- `tests/test_hohmann_transfer.cpp` (new) - Main integration test -- `tests/configs/earth_mars_simple.toml` (new) - Simple 3-body config - -**Test scenario:** -```cpp -TEST_CASE("Earth → Mars Hohmann Transfer", "[mission][hohmann]") { - // 1. Load Earth+Mars system - // 2. Calculate transfer parameters - // 3. Wait for launch window (within 1° tolerance) - // 4. Record departure time - // 5. Spawn spacecraft on transfer trajectory - // 6. Simulate until arrival (transfer_time × 1.1) - // 7. Track SOI transitions (Earth→Sun→Mars) - // 8. Verify arrival at Mars (distance < 2×SOI) - // 9. Verify transfer time accuracy (±10%) -} -``` - -**Success criteria:** -- Spacecraft enters Mars SOI -- Transfer time: 259 ± 26 days -- Final distance to Mars < 2 × Mars_SOI -- SOI transitions: Earth→Sun→Mars (tracked) -- Energy drift < 1% during transfer - -**Expected outcome:** -- ✅ Complete end-to-end transfer validated -- ✅ Patched conics mechanics tested (3 SOI changes) -- ✅ Transfer trajectory matches prediction - -**Estimated complexity:** Medium-High -**Risk:** Medium-High (integration test may reveal edge cases) - ---- - -### Phase 5: Enhance Root Body Transition Tests (0.5 days) - -**Goal:** Replace manual config positioning with calculated transfers - -**Files:** -- `tests/test_root_body_transitions.cpp` (refactor) -- Remove `tests/configs/manual_root_transition.toml` - -**Changes:** -1. Replace "Root body transition - Earth to Sun" test: - - Use `spawn_spacecraft_on_transfer()` instead of manual config - - Calculate transfer parameters - - Wait for launch window - - Verify Earth→Sun transition happens - -2. Replace "Root body round-trip" test: - - Calculate Earth→Mars transfer - - Wait for window - - Spawn spacecraft - - Verify round-trip SOI transitions - -3. Add better validation: - - Verify transition order (Earth→Sun→Mars) - - Verify arrival distance < threshold - - Verify energy conservation - - Verify spacecraft follows predicted trajectory - -**Expected outcome:** -- ✅ Realistic mission-based testing -- ✅ Better validation than `sun_transitions >= 1` -- ✅ Eliminates manual config positioning -- ✅ Tests use actual orbital mechanics - -**Estimated complexity:** Low -**Risk:** Low (refactoring existing tests) - ---- - -### Phase 6: Round-Trip Mission (1 day) - Optional - -**Goal:** Validate full mission lifecycle with return journey - -**Files:** -- `tests/test_round_trip.cpp` (new) - -**Test scenario:** -```cpp -TEST_CASE("Earth → Mars → Earth Round Trip", "[mission][round-trip]") { - // 1. Earth→Mars transfer - // 2. Verify arrival at Mars - // 3. Wait for Mars→Earth return window - // 4. Spawn new spacecraft at Mars for return - // 5. Simulate Mars→Earth return - // 6. Verify both transfers complete - // 7. Verify return arrival at Earth -} -``` - -**Success criteria:** -- Both transfers complete successfully -- Return time: ~259 ± 26 days -- Final distance to Earth < 2 × Earth_SOI -- Energy conserved across entire round-trip - -**Expected outcome:** -- ✅ Full mission lifecycle validated -- ✅ Multiple departure windows handled -- ✅ Patched conics round-trip confirmed - -**Estimated complexity:** Medium -**Risk:** Medium (long simulation time) - ---- - -## Integration with Existing Code - -### Reuses Existing Components: - -**Physics Module:** -- `rk4_step()` - RK4 integration works with any mass -- `evaluate_acceleration()` - Mass cancels out, test particles work - -**Simulation Module:** -- `find_dominant_body()` - SOI transitions work with parent_index = 0 (Sun) -- `update_simulation()` - Handles root bodies correctly -- Coordinate frames - Local/global transformations already work - -**Test Utilities:** -- `calculate_orbital_metrics()` - Can use for trajectory validation -- `OrbitTracker` - Can track orbital progress - -### New Components: - -**Mission Planning Module:** -- `mission_planning.h/cpp` - Mission calculations -- TransferParameters struct - Transfer orbit description -- Phase angle calculations - Launch window detection - -**Simulation Extensions:** -- `add_body_to_simulation()` - Dynamic spacecraft creation -- Runtime body addition - No more config-only initialization - ---- - -## Build System Changes - -### Makefile Modifications - -**Add to OBJECTS list:** -```makefile -OBJECTS = main.o physics.o simulation.o config_loader.o renderer.o \ - test_utilities.o mission_planning.o -``` - -**Add build rule:** -```makefile -mission_planning.o: src/mission_planning.cpp src/mission_planning.h - $(CXX) $(CXXFLAGS) -c src/mission_planning.cpp -o mission_planning.o -``` - -**Add to test build:** -```makefile -# Test executable includes mission_planning.o -test: test_build - ./orbit_test -``` - ---- - -## Test Configurations - -### earth_mars_simple.toml -Simple 3-body system for transfer testing: -```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 -``` - ---- - -## Success Criteria - -### ✅ Phase 1-2 Success - COMPLETE -- [x] Transfer parameters match NASA reference (±5%) -- [x] Phase angle calculations accurate (±1°) -- [x] Launch window detection works -- [x] Fast-forward to launch window succeeds - -### ✅ Phase 3 Success - COMPLETE -- [x] Spacecraft spawns at correct position -- [x] Initial velocity = Earth velocity + Δv -- [x] Parent = Sun for transfer orbit -- [x] Local/global coordinates consistent - -### ⏸️ Phase 4 Success - IN PROGRESS (DEBUGGING) -- [ ] Earth→Mars transfer completes (time ±10%) -- [ ] Spacecraft reaches Mars SOI (distance < 2×SOI) -- [ ] SOI transitions: Earth→Sun→Mars tracked correctly -- [ ] Energy drift < 1% during transfer (currently 9.98×10¹⁶%) - -### ⏸️ Phase 5 Success - NOT STARTED -- [ ] Root body transition tests use calculated trajectory -- [ ] Manual config positioning eliminated -- [ ] Better validation than `sun_transitions >= 1` - -### ⏸️ Phase 6 Success - NOT STARTED -- [ ] Round-trip mission completes -- [ ] Both transfers validated -- [ ] Return journey matches expectations - ---- - -## Timeline Estimate vs. Actual - -### Planned: -- **Phase 1:** 1 day - Core transfer calculations ✅ COMPLETED (1 day) -- **Phase 2:** 1 day - Launch window detection ✅ COMPLETED (same day) -- **Phase 3:** 1.5 days - Spacecraft spawning ✅ COMPLETED (same day) -- **Phase 4:** 1.5 days - Full transfer integration test ⏸️ IN DEBUGGING -- **Phase 5:** 0.5 days - Enhanced transition tests ⏸️ NOT STARTED -- **Phase 6:** 1 day - Round-trip mission (optional) ⏸️ NOT STARTED - -### Actual Progress (January 16, 2026): -- **Phase 1:** ✅ COMPLETE - All transfer calculations validated -- **Phase 2:** ✅ COMPLETE - Launch window detection working -- **Phase 3:** ✅ COMPLETE - Spacecraft spawning functional -- **Phase 4:** 🔄 PARTIAL - Test framework complete, trajectory bug identified -- **Phase 5:** ⏸️ BLOCKED - Waiting on Phase 4 -- **Phase 6:** ⏸️ BLOCKED - Waiting on Phase 4 - -**Time Invested:** ~6 hours (Phases 1-3) -**Estimated Time to Complete Phase 4:** 2-3 hours debugging -**Total for Phases 1-5:** **~1 day** (excluding Phase 4 debug time) - ---- - -## Files Summary - -### New Files Created: -- `src/mission_planning.h` (+40 lines) ✅ -- `src/mission_planning.cpp` (+150 lines) ✅ -- `tests/test_mission_planning.cpp` (+95 lines) ✅ -- `tests/test_hohmann_transfer.cpp` (+73 lines) ✅ (Phase 4 partial) -- `tests/configs/earth_mars_simple.toml` (+30 lines) ✅ - -### Modified Files: -- `src/simulation.h` (+3 lines) ✅ -- `src/simulation.cpp` (+33 lines) ✅ -- `Makefile` (+5 lines) ✅ -- `tests/test_root_body_transitions.cpp` (refactor - PENDING Phase 5) - -### Net Lines: ~+429 lines (Phases 1-3 complete, Phase 4 partial) - ---- - -## Debugging Notes - -### Phase 4 Trajectory Bug - -**Symptom:** Spacecraft does not follow expected Hohmann transfer orbit - -**Initial Conditions (Correct):** -``` -Spacecraft global position: (-6.94×10⁹, -1.49×10¹¹, 0) m -Spacecraft global velocity: (-32697.6, 1518.47, 0) m/s -Spacecraft parent: 0 (Sun) -Initial orbital energy: -3.52×10⁸ J (correct for Hohmann transfer) -``` - -**After First update_simulation() (Incorrect):** -``` -Spacecraft local position: (6.11×10⁷, -2.84×10⁶, 0) m -Energy: +3.51×10²³ J (wrong sign, unphysically large) -Energy drift: 9.98×10¹⁶% (should be < 5%) -``` - -**Expected Behavior:** -``` -Spacecraft should follow ellipse: -- Periapsis: 1.496×10¹¹ m (Earth distance) -- Apoapsis: 2.279×10¹¹ m (Mars distance) -- Semi-major axis: 1.888×10¹¹ m -- Period: ~518 days (full orbit), ~259 days (half-orbit to Mars) -``` - -**Actual Behavior:** -- Spacecraft trajectory diverges immediately -- Not following Hohmann ellipse -- Energy becomes positive (hyperbolic, unbound) -- Position magnitude grows to ~10¹³ AU (wrong scale) - -**Hypothesis:** -The issue is likely in `update_simulation()` coordinate transforms for newly added bodies. Specifically: - -1. **Local frame integration error:** `rk4_step()` integrates local coordinates, but newly added spacecraft may have incorrect local coordinates after first update. - -2. **compute_global_coordinates() not called:** After spawning spacecraft, we set both local and global coordinates manually. The first `update_simulation()` may recalculate local coordinates incorrectly. - -3. **SOI transition interference:** Spacecraft parent = 0 (Sun), but `find_dominant_body()` might incorrectly switch parent during first few updates. - -4. **Order of operations issue:** In `update_simulation()`: - - Check SOI transition - - If transition: convert local→global, switch parent, convert global→local - - Integrate: `rk4_step()` on local coordinates - - Compute global: `compute_global_coordinates()` - - The problem: Newly added spacecraft already has correct global coordinates, but `compute_global_coordinates()` may recalculate them incorrectly from possibly corrupted local coordinates. - -**Investigation Plan:** -1. Add printf statements to `update_simulation()` to print spacecraft local/global coordinates before/after each operation -2. Check if `find_dominant_body()` is changing spacecraft parent unexpectedly -3. Verify `rk4_step()` is using correct parameters (position, velocity, dt, body_mass, parent_mass) -4. Test with spacecraft starting at parent ≠ 0 to see if issue is specific to Sun-centered orbits -5. Consider calling `compute_global_coordinates()` immediately after `add_body_to_simulation()` to ensure consistency - -**Key Code Sections to Examine:** -- `src/simulation.cpp::update_simulation()` - lines 95-141 -- `src/simulation.cpp::add_body_to_simulation()` - lines 29-67 -- `src/physics.cpp::rk4_step()` - lines 56-89 -- `src/physics.cpp::evaluate_acceleration()` - lines 91-104 - -**Potential Fix:** -The issue may be that we're setting spacecraft global coordinates manually in `add_body_to_simulation()`, but `update_simulation()` expects to compute them from local coordinates. The fix might be to: -1. Set only local coordinates when adding spacecraft -2. Let `update_simulation()` handle global coordinate computation -3. OR: Add a flag to skip `compute_global_coordinates()` for the first few updates after spawning - -**Workaround for Testing:** -For now, test Phase 1-3 components separately without running full transfer simulation. The core functionality (calculations, launch window, spawning) is validated and working correctly. - ---- - -## Risks and Mitigations - -### High Risk -- **Energy conservation during transfer** - - Mitigation: Verify with energy tracking in tests - - Backup: Use smaller timestep if needed - -- **SOI transition edge cases** - - Mitigation: Comprehensive transition tracking in tests - - Backup: Adjust hysteresis if oscillation occurs - -### Medium Risk -- **Launch window calculation accuracy** - - Mitigation: Validate against known missions (NASA data) - - Backup: Increase tolerance window if needed - -- **Spacecraft spawning bugs** - - Mitigation: Unit tests for velocity/position - - Backup: Manual verification with visualization - -### Low Risk -- **Fast-forward simulation stability** - - Mitigation: Use existing `update_simulation()` (tested) - - Backup: Reduce fast-forward steps if needed - ---- - -## Future Work (Post-Implementation) - -### Immediate Next Steps -1. **Inclination Support** - Extend to 3D transfers - - Need 3D angular position calculations - - Longitude of ascending node, inclination, argument of periapsis - - Phase angle calculations in 3D - -2. **Capture Burns** - Add velocity reduction at arrival - - Simulate retrograde burns for orbital capture - - Calculate Δv needed for circularization - -3. **Lambert Solver** - General transfer solver - - Not just Hohmann transfers - - Arbitrary departure/arrival positions and times - - Non-planar transfers - -### Visualization Features -4. **Mission GUI** - Interactive departure window visualization - - Show current phase angle vs. required - - Countdown to launch window - - Transfer trajectory preview - -5. **Multiple Burns** - Support for course corrections - - Mid-course corrections - - Gravity assist maneuvers - - Powered flybys - -6. **SOI Visualization** - Render SOI boundaries - - Wireframe spheres for each body - - Color-coded by mass - - Toggle with keyboard - -### Advanced Features -7. **Mission Planner** - Complete mission design tool - - Multi-leg missions - - Optimization (minimum Δv, minimum time) - - Launch date search - -8. **Real Ephemeris** - Use actual planetary positions - - JPL Horizons API integration - - Date-based initialization - - Real mission planning - ---- - -## References - -- `docs/patched_conics_plan.md` - SOI transition implementation -- `docs/hierarchical_frames_plan.md` - Local frame integration (archived) -- `docs/implementation_plan.md` - Overall system architecture -- NASA Technical Memorandum "Hohmann Transfer Calculations" -- Orbital Mechanics for Engineering Students (Curtis) - ---- - -## Notes - -**Coordinate System:** -- All calculations assume planar motion (z = 0) for initial implementation -- Angular positions measured in XY plane -- Future work: Extend to 3D with inclination - -**Timekeeping:** -- Simulation time in seconds, conversions to days for display -- Fast-forward uses 1-day steps for efficiency -- Timestep remains 60s during fast-forward - -**Mass Strategy:** -- Spacecraft mass = 1.0 kg (negligible but non-zero) -- Physics engine handles test particles correctly (mass cancels) -- No N-body perturbations from spacecraft - -**Validation Strategy:** -- Compare against NASA reference missions (Viking, Curiosity, etc.) -- Energy conservation tracking -- Transfer time accuracy -- SOI transition verification - -**Testing Approach:** -- Unit tests for each function (formulas, calculations) -- Integration tests for full missions -- Regression tests against manual config approach