claudes_game/docs/planning/newton_raphson_test_plan.md

Newton-Raphson Test Plan

Overview

Test cases for Newton-Raphson analytical propagation implementation, organized by implementation phase and test category.

File Organization

Each test file requires a dedicated config file (1:1 mapping). Total estimated test files: 13-14

Current Progress (2026-01-31)

Completed Tests (6/14 files)

1. ✅ test_cartesian_to_elements_basic.cpp + .toml

• Status: FAILING (cartesian_to_orbital_elements implementation needs debugging)
• Issue: NaN values in reconstructed radius/velocity
• Config: Moderate eccentricity (e=0.5), zero inclination
• Tests:
  • Round-trip conversion: orbital elements → state vectors → orbital elements
  • Position/velocity magnitude preservation
  • Semi-major axis, eccentricity accuracy

2. ✅ test_newton_raphson_convergence.cpp (NO CONFIG)

• Status: PASSING (24/25 assertions)
• Config: Programmatically varied parameters
• Failing test: Low eccentricity (e=0.001) - error 0.001 > 1.0e-6 tolerance
• Tests:
  • Very low eccentricity (e < 0.01): convergence rate verification
  • High eccentricity (0.9 < e < 0.99): iteration count limits
  • Mean anomaly near π: worst-case convergence
  • Large mean anomaly values (M > 1000): periodicity handling
  • Eccentricity at boundaries (e = 0.9999, 1.0001)

3. ✅ test_analytical_propagation_apsides.cpp + .toml

• Status: PASSING (4/5 assertions)
• Config: Elliptical orbit (e=0.6, a=2e7)
• Failing test: "v_perigee > v_before" - test logic issue (both at same anomaly)
• Tests:
  • Propagation through perigee (velocity maximum)
  • Propagation through apogee (velocity minimum)
  • At exact orbital period: should return to initial state
  • True anomaly accuracy after full orbit
  • Vis-viva equation holds at multiple points

4. ✅ test_analytical_propagation_timesteps.cpp + .toml

• Status: PASSING (4/7 assertions)
• Config: Standard orbit (e=0.4, a=1.5e7)
• Failing tests:
  • Small timestep position change (tolerance too tight for orbital motion)
  • Relative error calculation (division by zero when expected error is 0)
  • True anomaly after 100 periods (2π wrapping issue)
• Tests:
  • Large timesteps: dt > 1 orbit period
  • Very small timesteps: dt < 1 second
  • Accuracy vs. timestep size relationship
  • Mean anomaly accumulation over long propagation

5. ✅ test_extreme_eccentricity.cpp + .toml

• Status: FAILING (config validation)
• Config: Multiple spacecraft (e=0.99, e=0.95, e=1.5)
• Issue: Config validation failing for spacecraft too close to parent
• Notes: Modified configs multiple times to satisfy distance validation
• Tests:
  • Numerical stability near e=1.0
  • Hyperbolic solver switching
  • Velocity magnitude accuracy
  • Period calculation (or lack thereof for e≥1)

6. ✅ test_precision_boundaries.cpp + .toml

• Status: PASSING (14/15 assertions)
• Config: Multiple boundary cases (e=0, i=π/2, i=π)
• Failing test: Polar orbit Z-coordinate (expected Z=7.5e6, actual Z=0)
• Notes: Fixed create_simulation calls to use max_craft=3
• Tests:
  • Eccentricity at exactly 0
  • Inclination at 0°, 90°, 180°
  • Semi-major axis sign change
  • Angular momentum conservation

Implementation Summary

Code Changes:

• Added to src/orbital_mechanics.h: Function declarations for

  • cartesian_to_orbital_elements(Vec3, Vec3, double)
  • solve_kepler_equation(double, double)
  • get_initial_trial_value(double, double)
  • propagate_orbital_elements(const OrbitalElements&, double, double)

• Added to src/orbital_mechanics.cpp: Full implementations

  • Newton-Raphson solver with 1e-10 tolerance, max 50 iterations
  • Series expansion initial guess: M + e*sin(M) + (e²/2)*sin(2M)
  • Cartesian to orbital elements conversion algorithm

• Removed from src/test_utilities.h/.cpp: propagate_orbital_elements()

• Added to src/config_validator.cpp: TODO comment about parabolic tolerance (0.005 too broad)

Test Results: 66 passed, 14 failed (out of 80 test cases)

Remaining Tests (8 files)

7. ⬜ test_cartesian_to_elements_extreme.cpp + .toml

• Purpose: Edge cases in orbital parameters
• Config: Multiple spacecraft in same config
  • Near-circular (e=0.001)
  • Highly eccentric (e=0.99)
  • Equatorial (i<0.001)
  • Polar (i≈π/2)
  • Retrograde (i>π/2)
• Tests:
  • Numerical precision at boundary values
  • Degenerate Ω calculation for equatorial
  • Rotation singularities for polar

8. ⬜ test_cartesian_to_elements_quadrature.cpp + .toml

• Purpose: Test calculations at orbital quadrature points
• Config: Spacecraft at true anomalies: 0, π/2, π, 3π/2
• Tests:
  • Cross product calculations at quadrants
  • Eccentricity vector accuracy
  • Position/velocity vector relationships

9. ⬜ test_hybrid_impulse_burns.cpp + .toml

• Purpose: Impulsive burn handling
• Config: Spacecraft with pre-configured maneuvers
• Tests:
  • Hohmann transfer (2 burns)
  • Plane change at nodes (inclination change only)
  • Impulsive burns at apsides (perigee/apogee)
  • Minimal burns (Δv < 1 m/s)
  • Large burns (Δv > orbital velocity)

10. ⬜ test_hybrid_continuous_thrust.cpp + .toml

• Purpose: Continuous thrust integration
• Config: Spacecraft with finite-duration burns
• Tests:
  • Continuous low-thrust burns (ion engines)
  • Multi-burn sequences
  • Numerical vs. analytical mode transitions
  • Energy conservation during burns

11. ⬜ test_hybrid_energy_conservation.cpp + .toml

• Purpose: Compare analytical vs. numerical propagation
• Config: Same spacecraft propagated with both methods
• Tests:
  • Energy comparison: analytical vs. RK4
  • Pre/post burn energy validation
  • Long-term energy drift comparison

12. ⬜ test_extreme_orientation.cpp + .toml

• Purpose: 3D orientation edge cases
• Config:
  • Polar orbit (i=90°)
  • Retrograde orbit (i=180°)
  • Mixed: high inclination + high eccentricity
• Tests:
  • Rotation matrix behavior at i=π/2
  • Ω and ω singularity handling
  • Z-coordinate preservation for polar
  • Velocity vector orientation

13. ⬜ test_extreme_timescales.cpp + .toml

• Purpose: Orbital period extremes
• Config:
  • Mercury-like orbiter (period ~88 days)
  • Very long period orbit (period > 10 years)
  • Very low perigee (altitude < 100 km)
  • Super-synchronous orbit
• Tests:
  • Fast orbits: numerical precision challenges
  • Slow orbits: mean anomaly accumulation
  • Low altitude: atmospheric boundary (if applicable)
  • Long-duration propagation (10+ periods)

14. ⬜ test_energy_conservation_analytical.cpp + .toml (OPTIONAL)

• Purpose: Long-term energy conservation validation
• Config: Standard circular/elliptical orbit
• Tests:
  • Energy drift over 10+ orbital periods
  • Kinetic/potential energy consistency
  • Vis-viva equation verification at all anomalies

Phase 1: Core Math Functions

Cartesian to Orbital Elements (3 files)

1. test_cartesian_to_elements_basic.cpp + .toml

• Purpose: Basic round-trip conversion accuracy
• Config: Moderate eccentricity, zero inclination orbit
• Tests:
  • Round-trip conversion: orbital elements → state vectors → orbital elements
  • Position/velocity magnitude preservation
  • Semi-major axis, eccentricity accuracy

2. test_cartesian_to_elements_extreme.cpp + .toml

• Purpose: Edge cases in orbital parameters
• Config: Multiple spacecraft in same config
  • Near-circular (e=0.001)
  • Highly eccentric (e=0.99)
  • Equatorial (i<0.001)
  • Polar (i≈π/2)
  • Retrograde (i>π/2)
• Tests:
  • Numerical precision at boundary values
  • Degenerate Ω calculation for equatorial
  • Rotation singularities for polar

3. test_cartesian_to_elements_quadrature.cpp + .toml

• Purpose: Test calculations at orbital quadrature points
• Config: Spacecraft at true anomalies: 0, π/2, π, 3π/2
• Tests:
  • Cross product calculations at quadrants
  • Eccentricity vector accuracy
  • Position/velocity vector relationships

Newton-Raphson Solver (1-2 files)

4. test_newton_raphson_convergence.cpp + .toml

• Purpose: Verify convergence behavior across eccentricity ranges
• Config: Spacecraft with programmatically varied parameters
• Tests:
  • Very low eccentricity (e < 0.01): convergence rate verification
  • High eccentricity (0.9 < e < 0.99): iteration count limits
  • Mean anomaly near π: worst-case convergence
  • Large mean anomaly values (M > 1000): periodicity handling
  • Eccentricity at boundaries (e = 0.9999, 1.0001)
• Note: Could split to separate config if boundary cases need dedicated config

Analytical Propagation (2 files)

5. test_analytical_propagation_apsides.cpp + .toml

• Purpose: Propagation through orbital apsides
• Config: Elliptical orbit
• Tests:
  • Propagation through perigee (velocity maximum)
  • Propagation through apogee (velocity minimum)
  • At exact orbital period: should return to initial state
  • True anomaly accuracy after full orbit

6. test_analytical_propagation_timesteps.cpp + .toml

• Purpose: Timestep size validation
• Config: Standard orbit
• Tests:
  • Large timesteps: dt > 1 orbit period
  • Very small timesteps: dt < 1 second
  • Accuracy vs. timestep size relationship
  • Mean anomaly accumulation over long propagation

Phase 2: Hybrid Integration

7. test_hybrid_impulse_burns.cpp + .toml

• Purpose: Impulsive burn handling
• Config: Spacecraft with pre-configured maneuvers
• Tests:
  • Hohmann transfer (2 burns)
  • Plane change at nodes (inclination change only)
  • Impulsive burns at apsides (perigee/apogee)
  • Minimal burns (Δv < 1 m/s)
  • Large burns (Δv > orbital velocity)

8. test_hybrid_continuous_thrust.cpp + .toml

• Purpose: Continuous thrust integration
• Config: Spacecraft with finite-duration burns
• Tests:
  • Continuous low-thrust burns (ion engines)
  • Multi-burn sequences
  • Numerical vs. analytical mode transitions
  • Energy conservation during burns

9. test_hybrid_energy_conservation.cpp + .toml

• Purpose: Compare analytical vs. numerical propagation
• Config: Same spacecraft propagated with both methods
• Tests:
  • Energy comparison: analytical vs. RK4
  • Pre/post burn energy validation
  • Long-term energy drift comparison

Extreme Orbits (3 files)

10. test_extreme_eccentricity.cpp + .toml

• Purpose: Near-parabolic boundary behavior
• Config:
  • Highly eccentric (e=0.99)
  • Near parabolic (e=0.9999, e=1.0001)
• Tests:
  • Numerical stability near e=1.0
  • Hyperbolic solver switching
  • Velocity magnitude accuracy
  • Period calculation (or lack thereof for e≥1)

11. test_extreme_orientation.cpp + .toml

• Purpose: 3D orientation edge cases
• Config:
  • Polar orbit (i=90°)
  • Retrograde orbit (i=180°)
  • Mixed: high inclination + high eccentricity
• Tests:
  • Rotation matrix behavior at i=π/2
  • Ω and ω singularity handling
  • Z-coordinate preservation for polar
  • Velocity vector orientation

12. test_extreme_timescales.cpp + .toml

• Purpose: Orbital period extremes
• Config:
  • Mercury-like orbiter (period ~88 days)
  • Very long period orbit (period > 10 years)
  • Very low perigee (altitude < 100 km)
  • Super-synchronous orbit
• Tests:
  • Fast orbits: numerical precision challenges
  • Slow orbits: mean anomaly accumulation
  • Low altitude: atmospheric boundary (if applicable)
  • Long-duration propagation (10+ periods)

Numerical Precision (1-2 files)

13. test_precision_boundaries.cpp + .toml

• Purpose: Exact boundary value handling
• Config:
  • Perfect circle (e=0)
  • Polar orbit (i=π/2)
  • Retrograde orbit (i=π)
  • Zero/very small radius or velocity
• Tests:
  • Eccentricity at exactly 0
  • Eccentricity at exactly 1 (parabolic)
  • Inclination at 0°, 90°, 180°
  • Semi-major axis sign change
  • Angular momentum conservation
• Note: If energy conservation needs separate config, this becomes 2 files

14. (Optional) test_energy_conservation_analytical.cpp + .toml

• Purpose: Long-term energy conservation validation
• Config: Standard circular/elliptical orbit
• Tests:
  • Energy drift over 10+ orbital periods
  • Kinetic/potential energy consistency
  • Vis-viva equation verification at all anomalies

Overlap Analysis with Existing Tests

Existing Test Coverage Summary

Orbital Parameters Currently Tested:

• Eccentricity: e=0.0 (circular), 0.74 (Molniya), 1.0 (parabolic), 1.5 (hyperbolic)
• Inclination: i=0.0 (equatorial), 1.107 rad (63.4°, Molniya)
• Orbital Periods: 1 day, 10 days, 15.95 days (Titan), 27.3 days (Moon), 60 days, 365 days (Earth), 687 days (Mars), 300-2000 days

Test Scenarios Currently Tested:

• Energy conservation (RK4 only)
• Orbital period measurement
• Prograde/retrograde/normal impulsive burns
• Time-based and true anomaly triggers
• Inclined orbits (Molniya)
• Parabolic and hyperbolic orbits
• Moon orbital stability
• SOI transitions (deferred)
• Root body transitions (deferred)

Overlaps Identified:

test_inclined_orbits.cpp (Molniya: e=0.74, i=63.4°)

• Overlaps: Extreme eccentricity, Extreme orientation
• Gap: Need e=0.99+, retrograde (i>π/2), polar (i=π/2 exactly)

test_moon_orbits.cpp (Moon ~27 day period)

• Overlaps: Extreme timescales
• Gap: Need Mercury-like (~88 days), very slow (>10 years)

test_energy.cpp (circular orbit energy)

• Overlaps: Energy conservation tests
• Gap: Need analytical propagation validation, method comparison

test_orbital_period.cpp (Earth 365 days, Mars 687 days)

• Overlaps: Extreme timescales
• Gap: Need <10 days, ~88 days, >3650 days

test_parabolic_orbit.cpp (e=1.0)

• Overlaps: Extreme eccentricity
• Gap: Need e=0.99, e=0.9999, e=1.0001

test_hyperbolic_orbit.cpp (e=1.5)

• Overlaps: Extreme eccentricity
• Gap: Need e=0.9999 near-parabolic boundary

test_maneuvers.cpp (prograde/retrograde/normal burns)

• Overlaps: Hybrid impulse burns
• Gap: Need continuous thrust, Hohmann sequence, apsides burns

test_maneuver_planning.cpp (time/true anomaly triggers)

• Overlaps: Hybrid impulse burns
• Gap: Need burns at apsides, Hohmann transfer

Config Sharing Opportunities

Can Share Configs (Partial Overlap):

1. test_extreme_eccentricity ↔ test_parabolic_orbit/hyperbolic_orbit

   • Existing: e=1.0, 1.5
   • New: e=0.99, 0.9999, 1.0001
   • May need new config for e=0.99, 0.9999 cases

2. test_hybrid_impulse_burns ↔ test_maneuvers

   • Can reuse burn infrastructure
   • New scenarios require separate config (Hohmann, apsides burns)

3. test_hybrid_energy_conservation ↔ test_energy

   • Different objectives (comparison vs. drift)
   • Could share circular orbit config

Cannot Share Configs (Different Parameters):

1. test_extreme_orientation vs test_inclined_orbits

   • Existing: i=1.107 (63.4°)
   • New: i=π/2 (90°), i>π/2 (retrograde)

2. test_cartesian_to_elements_extreme vs all existing

   • New test category (no existing tests)

Unique New Test Categories

Entirely New Functionality:

1. Cartesian to orbital elements conversion (Phase 1.1) - 3 tests
2. Newton-Raphson solver convergence (Phase 1.2) - 1 test
3. Analytical propagation accuracy (Phase 1.3) - 2 tests
4. Hybrid continuous thrust integration (Phase 2.2) - 1 test
5. Energy comparison: analytical vs. RK4 (Phase 2.3) - 1 test
6. Propagation through apsides - 1 test

New Orbital Regimes: 7. Retrograde orbits (i > 90°) - 1 test 8. Extremely fast orbits (Mercury-like, <100 days) - 1 test 9. Extremely slow orbits (>10 years) - 1 test 10. Boundary values (e=0, i=π/2, i=π) - 1 test

Minimal File Count with Sharing

Current estimate: 13-14 files

Optimization opportunities:

• Combine e=0.99 with parabolic/hyperbolic configs → -1 file
• Share energy config between test_energy and test_hybrid_energy_conservation → -1 file
• Use existing Molniya config for some extreme orientation tests → -1 file

Optimized estimate: ~11 files

Recommended: Keep 13-14 files

• Each test has self-documenting config
• Easier to debug isolated failures
• Config reuse doesn't save much (configs are small)
• Clear separation of concerns

Implementation Priority

Phase 1 (Foundation)

1. test_cartesian_to_elements_basic.cpp (round-trip conversion)
2. test_newton_raphson_convergence.cpp (solver validation)
3. test_analytical_propagation_apsides.cpp (basic propagation)

Phase 2 (Hybrid Integration)

4. test_hybrid_impulse_burns.cpp (impulsive burns)
5. test_hybrid_continuous_thrust.cpp (continuous burns)
6. test_hybrid_energy_conservation.cpp (method comparison)

Phase 3 (Edge Cases)

7. test_extreme_eccentricity.cpp (e≈1.0)
8. test_extreme_orientation.cpp (polar/retrograde)
9. test_extreme_timescales.cpp (fast/slow periods)
10. test_precision_boundaries.cpp (exact values)
11. test_cartesian_to_elements_extreme.cpp (edge cases)
12. test_cartesian_to_elements_quadrature.cpp (quadrants)
13. test_analytical_propagation_timesteps.cpp (large/small dt)

Notes

• Config files are shared with existing tests where possible
• Each .cpp file requires corresponding .toml config
• Some test categories can share configs if parameters align
• SOI transition tests deferred per user requirements