# 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 test files: 13 main files + test_barkers_equation.cpp = 14 total ✅ COMPLETE

## Current Progress (2026-02-02)

### Completed Tests (13/14 files fully passing)

#### 1. ✅ test_cartesian_to_elements_basic.cpp + .toml: Round-trip conversion with fixed true anomaly calculation (PASSING 12/12)

#### 2. ✅ test_newton_raphson_convergence.cpp: Convergence across eccentricity ranges with separated solvers (PASSING 28/28)

#### 3. ✅ test_analytical_propagation_apsides.cpp: Propagation through apsides with fixed velocity comparison (PASSING 5/5)

#### 4. ✅ test_analytical_propagation_timesteps.cpp: Timestep validation with fixed test design bugs (PASSING 7/7)

#### 5. ✅ test_extreme_eccentricity.cpp: Near-parabolic/hyperbolic boundaries with validation fixes (PASSING 28/28)

#### 6. ✅ test_precision_boundaries.cpp: Boundary value handling with fixed circular orbit velocity (PASSING 15/15)

#### 7. ✅ test_cartesian_to_elements_extreme.cpp + .toml: Parabolic test fixed and tolerances tightened (PASSING with 93 tests)

#### 8. ✅ test_cartesian_to_elements_quadrature.cpp + .toml: Argument of periapsis fix with atan2() (PASSING with 93 tests)

#### 9. ✅ test_hybrid_impulse_burns.cpp + .toml: Impulsive burn handling with full maneuver system (PASSING with 96 assertions)
- Hohmann transfers (2 burns)
- Plane changes at nodes
- Impulsive burns at apsides
- Minimal burns (Δv < 1 m/s) to large burns (Δv > orbital velocity)
- Multiple burn sequences
- Uses full maneuver system (execute_maneuver not just apply_impulsive_burn)

#### 10. ✅ test_hybrid_continuous_thrust.cpp + .toml: Continuous thrust integration (PASSING with 40 assertions)
- Continuous low-thrust burns (ion engines)
- Multi-burn sequences with separate burn phases
- Mode transitions between analytical propagation and Cartesian burns
- Energy conservation during finite-duration burns
- Numerical stability during 120 burn/conversion cycles

#### 11. ✅ test_hybrid_energy_conservation.cpp + .toml: Analytical vs numerical propagation comparison (PASSING with 89 assertions)
- Energy comparison for circular, elliptical, high eccentricity, inclined, fast, and slow orbits
- Pre/post burn energy validation (ΔE = v·Δv + 0.5Δv²)
- Long-term energy drift comparison (10 orbits)
- Analytical propagation: Zero energy drift (exact conservation)
- Numerical RK4: 1.7e-07 (circular) to 3.6e-03 (high eccentricity) relative drift

#### 12. ✅ test_extreme_orientation_mixed.cpp + .toml: Combined high inclination + high eccentricity (PASSING with 157 assertions)
- Rotation matrix behavior at extreme inclination/eccentricity combinations
- Ω and ω singularity handling
- Velocity vector orientation at apsides
- Round-trip conversion for extreme orientation parameters
- Rotation matrix verification

#### 13. ✅ test_extreme_timescales.cpp + .toml: Orbital period extremes (PASSING with 55 assertions)
- Fast orbits (LEO, Mercury-like) for numerical precision
- Slow orbits (Jupiter-like) for mean anomaly accumulation
- Low altitude (~100 km) and super-synchronous orbits
- Geosynchronous orbit period accuracy (23.9347 hours, sidereal day)
- Period consistency across different true anomalies
- Energy conservation across all timescales

### Implementation Summary

**Code Changes:**
- Added functions to `src/orbital_mechanics.h`: Newton-Raphson solver, cartesian→elements conversion, modular API (elliptical/hyperbolic solvers), Barker's equation
- Implemented in `src/orbital_mechanics.cpp`: 1e-10 tolerance, max 50 iterations, series expansion initial guess, fixed true_anomaly calculation and circular orbit velocity, parabolic propagation with Barker's equation
- Removed `propagate_orbital_elements()` from `src/test_utilities.h/.cpp`
- Added `validate_true_anomaly_ranges()` to `src/config_validator.cpp`
- Standardized parabolic detection (PARABOLIC_TOLERANCE = 1e-3)
- Fixed argument_of_periapsis calculation using atan2()

**Phase 2 Tests (Hybrid Integration) - Added 2026-02-02:**
- test_hybrid_impulse_burns.cpp: Impulsive burn handling with full maneuver system (426 lines, 96 assertions)
- test_hybrid_continuous_thrust.cpp: Continuous thrust integration (565 lines, 40 assertions)
- test_hybrid_energy_conservation.cpp: Analytical vs numerical propagation comparison (810 lines, 89 assertions)

**Phase 3 Tests (Edge Cases) - Added 2026-02-02:**
- test_extreme_orientation_mixed.cpp: Combined high inclination + high eccentricity (392 lines, 157 assertions)
- test_extreme_timescales.cpp: Orbital period extremes (417 lines, 55 assertions)

**Bug Fixes:**
- Fixed true_anomaly calculation: corrected formula and added clamping
- Fixed test_extreme_eccentricity config and validation
- Fixed test_newton_raphson_convergence expectations
- Fixed test_analytical_propagation_apsides velocity comparison
- Fixed 3 test design issues in test_analytical_propagation_timesteps
- Fixed test_precision_boundaries Z-coordinate check
- Fixed orbital_elements_to_cartesian circular orbit velocity
- Standardized parabolic detection across codebase
- Fixed near-parabolic numerical instability in eccentric_to_true_anomaly()
- Fixed argument_of_periapsis quadrature ambiguity with atan2()
- Fixed true_anomaly normalization to handle negative values
- Fixed parabolic test design in test_cartesian_to_elements_extreme.cpp

**Test Results:** All 134 test cases passing (240,299 assertions) - includes all Newton-Raphson validation tests

### Remaining Tests (1 file)

#### 14. ✅ test_barkers_equation.cpp: Parabolic propagation (PASSING with 11 tests)
- Purpose: Validate Barker's equation for parabolic orbits (e≈1.0)
- Tests: Parabolic propagation accuracy
- Status: Previously completed, integrated into main test suite

## Implementation Priority

### Phase 1 (Foundation) ✅ COMPLETE
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) ✅ COMPLETE
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) ✅ COMPLETE
7. ✅ test_extreme_eccentricity.cpp (e≈1.0)
8. ✅ test_extreme_orientation_mixed.cpp (high inclination + high eccentricity)
9. ✅ test_extreme_timescales.cpp (fast/slow periods)
10. ✅ test_precision_boundaries.cpp (exact values)
11. ✅ test_cartesian_to_elements_extreme.cpp (parabolic test fixed and tolerances tightened)
12. ✅ test_cartesian_to_elements_quadrature.cpp (argument of periapsis fix)
13. ✅ test_analytical_propagation_timesteps.cpp (large/small dt)

## Ready for Production Switch

All validation tests are complete and passing. The simulation is ready to switch from RK4 numerical integration to analytical propagation using `propagate_orbital_elements()`.

### Burn Handling Workflow Validated ✅
```
1. Spacecraft starts with orbital elements
2. Convert to Cartesian (orbital_elements_to_cartesian)
3. Apply impulsive burn (modify velocity)
4. Convert back to orbital elements (cartesian_to_orbital_elements)
5. New orbital elements ready for analytical propagation
```

### Key Validation Results
- **Burn handling:** All burn types, orbit types, and magnitudes validated
- **Continuous thrust:** Up to 120 burn/conversion cycles without error accumulation
- **Energy conservation:**
  - Analytical propagation: Zero energy drift (exact conservation)
  - Numerical RK4: 1.7e-07 to 3.6e-03 relative drift depending on orbit type

### Next Steps
1. Switch simulation to analytical propagation in `src/simulation.cpp`
2. Add orbital element conversion after burns in `src/maneuver.cpp`
3. Test with real-world scenarios (multiple spacecraft, SOI transitions, burns)

### 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_mixed.cpp (high inclination + high eccentricity)
9. ✅ test_extreme_timescales.cpp (fast/slow periods)
10. ✅ test_precision_boundaries.cpp (exact values)
11. ✅ test_cartesian_to_elements_extreme.cpp (parabolic test fixed and tolerances tightened)
12. ✅ test_cartesian_to_elements_quadrature.cpp (argument of periapsis fix)
13. ✅ test_analytical_propagation_timesteps.cpp (large/small dt)

## Notes
- Each .cpp file requires corresponding .toml config when creating a 2 body system
- SOI transition tests deferred per user requirements
- Test count: 13/13 main test files fully passing ✅ COMPLETE
- Additional test: test_barkers_equation.cpp (parabolic propagation, 11 tests) ✅ COMPLETE
- All Phase 1, 2, and 3 tests complete and passing (240,299 assertions)
- Ready to switch simulation from RK4 to analytical propagation