From 40ffc65a54f3e52d25ea98bc6248e94154683ee2 Mon Sep 17 00:00:00 2001
From: cinnaboot <cinnaboot@protonmail.com>
Date: Mon, 19 Jan 2026 10:28:11 -0500
Subject: [PATCH] Update mission planning doc with test config, future work,
 and reference sections

---
 docs/leospacecraft_impulse_burn_plan.md | 170 ++++++++++++++++++++++++
 1 file changed, 170 insertions(+)

diff --git a/docs/leospacecraft_impulse_burn_plan.md b/docs/leospacecraft_impulse_burn_plan.md
index 84fd988..199d356 100644
--- a/docs/leospacecraft_impulse_burn_plan.md
+++ b/docs/leospacecraft_impulse_burn_plan.md
@@ -672,3 +672,173 @@ Spacecraft may not enter Mars SOI due to:
 - Phase 5 (Cleanup): 20 minutes
 
 **Total**: 2-3 hours
+
+---
+
+## Test Configuration Reference
+
+### earth_mars_simple.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 = "Spacecraft"
+mass = 1.0
+radius = 1000.0
+# Position and velocity will be initialized at runtime for LEO orbit
+position = { x = 0.0, y = 0.0, z = 0.0 }
+velocity = { x = 0.0, y = 0.0, z = 0.0 }
+parent_index = 1  # Earth
+color = { r = 1.0, g = 0.0, b = 0.5 }
+eccentricity = 0.0
+# Semi-major axis will be: Earth radius + 200km
+semi_major_axis = 6.571e6  # Placeholder, will be set during initialization
+```
+
+---
+
+## Future Work (Post-Implementation)
+
+### Immediate Next Steps
+
+#### 1. Config Format Improvements
+- Support Earth-relative position specification (e.g., `{ altitude_km = 200.0 }`)
+- Support Earth-relative orbit specification (e.g., `{ orbit_type = "circular" }`)
+- More intuitive spacecraft mission parameters in TOML config
+- Support multiple spacecraft in single config file
+
+#### 2. Improved Patched Conics Implementation
+- Calculate Δv to reach SOI boundary (escape trajectory)
+- Calculate velocity at SOI boundary
+- Add transfer Δv at SOI boundary
+- Combine into equivalent single impulse
+- Test accuracy of two-impulse vs single-impulse approach
+
+#### 3. Inclination Support
+- Extend to 3D transfers
+- Need 3D angular position calculations
+- Longitude of ascending node, inclination, argument of periapsis
+- Phase angle calculations in 3D
+- Out-of-plane maneuver calculations
+
+#### 4. Capture Burns
+- Simulate retrograde burns for orbital capture at destination
+- Calculate Δv needed for circularization
+- Support parking orbits at arrival body
+- Validate Mars capture burns (~1.4 km/s for Mars)
+
+### Visualization Features
+
+#### 5. Mission GUI
+- Interactive departure window visualization
+- Show current phase angle vs. required phase angle
+- Countdown to launch window
+- Transfer trajectory preview (predicted path)
+- Delta-v budget display
+
+#### 6. Multiple Burns Support
+- Mid-course corrections
+- Gravity assist maneuvers
+- Powered flybys
+- Multi-stage missions
+
+#### 7. SOI Visualization
+- Render SOI boundaries as wireframe spheres
+- Color-coded by mass
+- Toggle with keyboard shortcut
+- Show SOI transitions in real-time
+
+### Advanced Features
+
+#### 8. Mission Planner
+- Complete mission design tool
+- Multi-leg missions (Earth→Mars→Phobos)
+- Optimization algorithms (minimum Δv, minimum time)
+- Launch date search across windows
+- Mission timeline visualization
+
+#### 9. Real Ephemeris Integration
+- Use actual planetary positions (JPL Horizons API)
+- Date-based initialization
+- Real mission planning with actual ephemeris data
+- Compare simulation to historical missions
+
+#### 10. Enhanced Trajectory Analysis
+- Lambert solver for general transfers
+- Not just Hohmann transfers
+- Arbitrary departure/arrival positions and times
+- Non-planar transfers
+
+---
+
+## 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 during launch window wait
+- 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 in acceleration)
+- No N-body perturbations from spacecraft on planetary bodies
+
+### Validation Strategy
+- Compare against NASA reference missions (Viking, Curiosity, Perseverance)
+- Energy conservation tracking during transfer
+- Transfer time accuracy (±10% tolerance)
+- SOI transition verification (Earth→Sun→Mars)
+
+### Testing Approach
+- Unit tests for each function (formulas, calculations)
+- Integration tests for full missions (LEO initialization, impulse burn, transfer)
+- Regression tests against expected Hohmann transfer parameters
+
+### LEO Orbit Considerations
+- LEO orbit at 200 km altitude (r = 6.571×10⁶ m)
+- LEO velocity: ~7,788 m/s at 200 km
+- LEO period: ~88.5 minutes
+- Spacecraft LEO phase changes significantly during multi-day wait periods
+- Transfer burn must account for spacecraft's actual heliocentric velocity (not just Earth's)
+
+---
+
+## References
+
+- `docs/implementation_plan.md` - Overall system architecture
+- NASA Technical Memorandum "Hohmann Transfer Calculations"
+- Orbital Mechanics for Engineering Students (Curtis)
+- Fundamentals of Astrodynamics (Bate, Mueller, White)