claudes_game/docs/session_summaries/2026-01-18-mission-planning-leo-impulse-burn.md

Session Summary: Mission Planning - LEO Spacecraft and Impulse Burn

Date: January 18, 2026 Session Length: ~2 hours Branch: mission-planning Goals:

1. Replace dynamic spacecraft spawning with config-based LEO spacecraft
2. Implement patched conics impulse burn for Hohmann transfer
3. Add comprehensive test verification

---

Work Completed

Phase 0: Git Workflow ✅

• Stashed debug changes on main branch
• Switched to mission-planning branch
• Applied debug printf statements to mission-planning branch
• All debug output from spacecraft parent investigation preserved

Phase 1: Configuration File ✅

File: tests/configs/earth_mars_simple.toml

Changes:

• Added Spacecraft body to config
• Configured with placeholder position/velocity (set at runtime)
• Parent set to Earth (index 1)
• Initial semi-major axis placeholder: 6.571e6 m (Earth radius + 200km)

Phase 2: Mission Planning Module ✅

Function Declarations Added:

void initialize_spacecraft_leo(CelestialBody* spacecraft, CelestialBody* parent,
                              double altitude_m);
void apply_transfer_burn(SimulationState* sim, int spacecraft_idx,
                       int departure_idx, TransferParameters* params);
double calculate_phase_angle(SimulationState* sim, int departure_idx, int arrival_idx);

Function Implementations:

1. initialize_spacecraft_leo() - Sets circular LEO orbit at specified altitude

   • Calculates orbital radius = Earth radius + altitude
   • Positions spacecraft radially outward from Sun
   • Calculates LEO velocity: v = sqrt(G * M_earth / r)
   • Sets prograde orientation (tangential to Earth-Sun line)
   • Verified to produce correct LEO velocity (~7788 m/s at 200km altitude)

2. calculate_phase_angle() - Computes phase angle between two bodies

   • Calculates angular positions relative to Sun
   • Returns phase difference normalized to [0°, 360°)
   • Used for launch window verification

3. apply_transfer_burn() - Applies impulse burn for Hohmann transfer

   • Calculates required heliocentric velocity magnitude from transfer parameters
   • Calculates prograde direction (tangential to Earth-Sun line)
   • Computes delta-v vector: Δv = v_target - v_current
   • Applies impulse to spacecraft velocity
   • Updates local velocity relative to departure body

Phase 3: Comprehensive Test Case ✅

Test Structure:

1. Load config with 4 bodies (Sun, Earth, Mars, Spacecraft)
2. Initialize spacecraft in 200km LEO around Earth
3. Verify LEO orbit stability (parent, position, velocity, energy)
4. Calculate Hohmann transfer parameters
5. Wait for Earth-Mars launch window (within 1°)
6. Verify phase angle accuracy
7. Apply impulse burn for transfer
8. Verify post-burn energy >= 0 (escape trajectory)
9. Simulate transfer for 110% of expected duration
10. Track SOI transitions (Earth→Sun→Mars)
11. Verify final parent and energy conservation
12. If Mars SOI entry, verify distance

Test Results (Current Status):

✅ PASSED (8 assertions):

• Config loading (4 bodies loaded)
• Spacecraft loaded correctly
• Spacecraft parent = Earth (index 1)
• LEO position within expected radius (<1km error)
• LEO velocity matches expected (<10 m/s error)
• LEO total energy negative (bound to Earth)
• Launch window opened after ~94 days
• Phase angle error < 1°

❌ FAILED (1 assertion):

• Post-burn heliocentric energy >= 0.0 (expected)
  • Actual: -3.5e8 J (negative, still bound)
  • Expected: ≥ 0 J (positive, escape trajectory)

Phase 4: Build System ✅

• Makefile already configured for mission_planning.o
• Test executable builds successfully
• All warnings noted (unused variables, harmless)

Phase 5: Cleanup ⏸️

• Not yet started (waiting on test fix)

---

Test Status

Before Session

• Previous mission planning implementation with spacecraft spawning

After Session

• Test framework complete with LEO spacecraft initialization
• 8/9 assertions passing in Hohmann transfer test
• 1 assertion failing: post-burn energy validation

---

Code Statistics

Files Modified (3)

• tests/configs/earth_mars_simple.toml - Added spacecraft body (+13 lines)
• src/mission_planning.h - Added function declarations (+3 lines)
• src/mission_planning.cpp - Implemented new functions (~100 lines)
• tests/test_hohmann_transfer.cpp - Added comprehensive test (~175 lines)

Net Changes

• ~+291 lines (estimated, not yet committed)

---

Documentation

Updated

• docs/mission_planning.md - Implementation plan for LEO spacecraft approach
  • Added test configuration reference
  • Added future work section
  • Added notes and references

---

Current Issue

Problem: Incorrect Delta-V Direction After Multi-Day Wait

Symptom:

• Spacecraft enters LEO orbit correctly with negative energy (bound to Earth)
• Waits 94 days for Earth-Mars launch window
• During wait period, spacecraft completes ~6.3 LEO orbits
• LEO orbit phase changes significantly over 94 days
• After wait, apply_transfer_burn() applies delta-v assuming spacecraft is at Earth's current orbital phase
• Result: Delta-v applied in wrong direction, resulting in retrograde burn
• Post-burn energy remains negative (spacecraft still bound to Earth)

Root Cause Analysis:

The apply_transfer_burn() function calculates:

1. Required heliocentric transfer velocity magnitude: v_transfer = 32,697 m/s
2. Prograde direction based on Earth's current position: transfer_dir = prograde(t_current)
3. Target velocity: v_target = v_transfer * transfer_dir

However, after 94 days:

• Earth has moved to different orbital phase
• Spacecraft in LEO is still orbiting Earth
• Spacecraft's current heliocentric velocity includes Earth's motion + LEO motion
• The calculated transfer direction is based on Earth's instantaneous position, not spacecraft's actual heliocentric velocity vector
• This results in delta-v that doesn't account for spacecraft's phase in LEO

What Should Happen:

1. Calculate spacecraft's current heliocentric velocity vector: v_current
2. Calculate required heliocentric velocity for transfer orbit: v_transfer
3. Apply delta-v: Δv = v_transfer - v_current (vector subtraction, not magnitude-based)

What Currently Happens:

1. Assumes spacecraft starts at Earth's orbital position (ignores LEO phase)
2. Calculates transfer direction based on Earth's current prograde vector
3. Applies magnitude-based delta-v without considering spacecraft's actual velocity direction
4. Results in incorrect burn direction

Solution Required

Modify apply_transfer_burn() to:

1. Calculate spacecraft's actual heliocentric velocity:

Vec3 v_current_helio = spacecraft->velocity;  // Already in global frame

2. Calculate required heliocentric transfer velocity:

double v_transfer_mag = params->departure_velocity;  // ~32,697 m/s

// Direction: prograde to Sun (same as Earth's orbital direction)
Vec3 sun_to_earth = vec3_sub(departure->position, sun->position);
Vec3 sun_to_earth_norm = vec3_normalize(sun_to_earth);
Vec3 transfer_dir = (Vec3){-sun_to_earth_norm.y, sun_to_earth_norm.x, 0.0};
Vec3 v_transfer_helio = vec3_scale(transfer_dir, v_transfer_mag);

3. Calculate delta-v as vector difference:

Vec3 delta_v = vec3_sub(v_transfer_helio, v_current_helio);

4. Apply impulse:

spacecraft->velocity = vec3_add(spacecraft->velocity, delta_v);
spacecraft->local_velocity = vec3_sub(spacecraft->velocity, departure->velocity);

This approach:

• Accounts for spacecraft's actual heliocentric velocity (includes LEO phase)
• Uses vector subtraction instead of magnitude-based calculation
• Produces correct delta-v direction regardless of LEO phase
• Should result in positive post-burn energy (escape trajectory)

---

Next Steps

High Priority

1. Fix Delta-V Direction Bug

   • Modify apply_transfer_burn() to use vector subtraction
   • Test with actual spacecraft heliocentric velocity
   • Verify post-burn energy becomes positive
   • Estimated time: 30 minutes

2. Complete Full Transfer Test

   • Verify Mars SOI entry after fix
   • Validate energy conservation during transfer
   • Confirm SOI transitions (Earth→Sun→Mars)
   • Estimated time: 1 hour

Medium Priority

3. Phase 5: Cleanup
   • Remove spawn_spacecraft_on_transfer() function
   • Update documentation
   • Estimated time: 20 minutes

---

Technical Decisions

1. Config-Based vs Dynamic Spawning

• Decision: Use config-based LEO spacecraft initialization
• Rationale: Cleaner approach, spacecraft in config from start
• Result: Spacecraft loaded with placeholder position/velocity, set at runtime

2. Single-Impulse vs Patched Conics

• Decision: Single impulse as initial approximation
• Rationale: Simpler to implement, adequate for initial testing
• Future: Can refine to two-impulse burn for higher accuracy

3. LEO Orbit Phase

• Issue: Spacecraft LEO phase changes during multi-day wait
• Impact: Delta-v must account for spacecraft's actual heliocentric velocity
• Fix: Use vector subtraction with spacecraft's actual velocity

---

Achievements

1. ✅ Config-based LEO spacecraft initialization
2. ✅ Three new functions in mission planning module
3. ✅ Comprehensive test framework with SOI transition tracking
4. ✅ LEO orbit validated (position, velocity, energy)
5. ✅ Launch window detection working
6. ✅ Root cause identified for delta-v direction bug
7. ✅ Clear solution path defined

---

Risks and Blockers

Current Blockers

1. Delta-V Direction Bug - Blocks completion of transfer test
   • Impact: Can't validate full Hohmann transfer
   • Severity: Low - solution is clear and simple
   • Mitigation: Fix identified, implementation straightforward

---

Conclusion

Session focused on implementing config-based LEO spacecraft initialization and impulse burn for Hohmann transfer. Core implementation complete, test framework working. One bug identified (delta-v direction) with clear solution path.

Session Outcome: Productive with clear fix required for final test validation.

Estimated Time to Complete: 1.5-2 hours (fix bug, complete test, cleanup)