claudes_game/docs/planning/molniya-orbit-test-plan.md

Molniya Orbit Test Implementation - Summary

Current Status

✅ Molniya orbit tests created and passing (except 3D z-coordinate checks)

What Was Done

1. Test Implementation

• Created tests/test_inclined_orbits.toml - Earth as root with Molniya spacecraft
• Created tests/test_inclined_orbits.cpp - 4 test cases:
  • Position verification at 4 true anomalies (perigee, π/2, apogee, 3π/2)
  • Orbital period verification (~12 hours)
  • Generic inclined orbit test (45°)
  • Inclination parameter preservation (config loading only)

2. Bug Fixed: Altitude Parameter

Problem: Config loader unconditionally added parent radius to spacecraft semi_major_axis, causing massive position errors (1.7M m at perigee, 11.1M m at apogee)

Solution: Removed altitude parameter entirely

• Only 3 test configs used it (0 production configs)
• High complexity vs minimal benefit
• Replaced with explicit semi_major_axis calculations in configs

Files modified:

• 3 test configs: test_maneuver_planning.toml, test_maneuvers.toml, test_orbit_rendering.toml
• src/config_loader.cpp: Removed altitude parsing and buggy post-processing loop
• docs/technical_reference.md: Removed altitude documentation

Results: Molniya position tests now pass with 0 m error (was 1.7M-11.1M m)

3. Code Refactoring

Extracted duplicate orbit parsing logic into parse_toml_orbit() helper function

• Eliminated ~82 lines of duplication
• Single source of truth for orbit validation
• All tests passing

Test Results

test cases:     39 |     36 passed | 3 failed as expected
assertions: 239378 | 239372 passed | 6 failed as expected

Failed tests (expected - 3D not implemented yet):

• Molniya position tests: z-coordinate = 0 (should be non-zero)
• Generic inclined orbit: z-coordinate = 0 (should be non-zero)

Remaining Work

1. OrbitTracker Period Test

Status: Not completing orbits for Molniya spacecraft

Investigation needed:

• Increase MAX_SIMULATION_HOURS (currently 15, theoretical ~12)
• Check quadrant transition logic for highly elliptical orbits
• May need angle comparison tolerance adjustment

Location: src/test_utilities.cpp update_orbit_tracker() function

2. 3D Orientation Implementation (Future Work)

Current state:

• OrbitalElements struct has: inclination, longitude_of_ascending_node, argument_of_periapsis
• orbital_elements_to_cartesian() only produces 2D orbits (x, y, z=0)
• Config parser loads these parameters correctly
• Tests expect 3D and fail with [!mayfail] tags

Required changes (for next session):

1. Modify src/orbital_mechanics.cpp orbital_elements_to_cartesian() to apply 3D rotations:

   • Start with 2D position/velocity in orbital plane
   • Apply rotation matrix for argument of periapsis (ω) about z-axis
   • Apply rotation matrix for inclination (i) about x-axis
   • Apply rotation matrix for longitude of ascending node (Ω) about z-axis

2. Rotation sequence (z-x-z Euler angles):

   r_final = R_z(Ω) · R_x(i) · R_z(ω) · r_orbital_plane
   v_final = R_z(Ω) · R_x(i) · R_z(ω) · v_orbital_plane
   

3. After implementation:

   • Remove [!mayfail] tags from passing tests
   • Verify Molniya orbit has correct orientation (apogee at northernmost point)
   • Test ascending/descending node crossings

Reference: Standard orbital mechanics conversion from Keplerian elements to Cartesian coordinates with 3D orientation

Commits on Branch

1. cfb2c92 - Add Molniya orbit test cases and document config loader bug
2. b221251 - Remove altitude parameter to fix spacecraft initialization bug
3. 840623d - Refactor config loader to extract orbit parsing into helper function