# 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: 11 (reduced from 14 after overlap analysis)

## Current Progress (2026-01-31)

### Completed Tests (8/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)

### 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()

**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 93 tests passing (239,872 assertions) - includes 11 Barker's equation tests

### Remaining Tests (5 files)

#### 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_mixed.cpp + .toml
- Purpose: Combined high inclination + high eccentricity
- Config:
  - High inclination (i>π/3) + high eccentricity (e>0.8)
- Tests:
  - Rotation matrix behavior at extreme combinations
  - Ω and ω singularity handling
  - Velocity vector orientation
  - NOTE: Removed duplicate polar/retrograde tests (covered by test_precision_boundaries)

#### 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)

## 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_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: 10/14 files fully passing (8/14 previously plus 2 new cartesian_to_elements tests)
- Additional test added: test_barkers_equation.cpp (parabolic propagation, 11 tests)