add rendezvous planning doc

3 months ago · 625b4cfad0
1 changed files with 366 additions and 0 deletions
--- a/docs/planning/rendezvous_planning.md
+++ b/docs/planning/rendezvous_planning.md
@ -0,0 +1,366 @@
 # Orbital Rendezvous Planning - Implementation Plan
 ## Overview
 This document outlines the implementation plan for adding orbital rendezvous planning capabilities to the simulation.
 ## Architecture
 - C-style C++ (structs/functions, NO classes/templates)
 - Follow existing patterns in src/
 - Use existing orbital mechanics functions (orbital_mechanics.h/cpp)
 - Integrate with maneuver system (maneuver.h/cpp)
 ## Implementation Plan
 ### Phase 1: Core - Lambert Solver, Relative Orbit Analysis
 #### 1.1 Create Rendezvous Target Structure
 **Location:** `maneuver.h`
 ```cpp
 struct RendezvousTarget {
    int target_craft_index;
    OrbitalElements target_elements;
    Vec3 target_position;
    Vec3 target_velocity;
    double max_encounter_distance;
    double max_relative_velocity;
 };
 ```
 **Purpose:** Hold target state for rendezvous calculations
 #### 1.2 Implement Lambert's Problem Solver
 **Location:** `maneuver.cpp`
 ```cpp
 // Solve two-point boundary value problem
 // Given: r1, r2, time_of_flight
 // Returns: v1 (departure velocity), v2 (arrival velocity)
 bool solve_lambert(Vec3 r1, Vec3 r2, double time_of_flight,
                   double central_mass, Vec3* v1, Vec3* v2);
 ```
 **Algorithm:** Universal variable formulation (Gooding's method)
 - Handle elliptical, parabolic, and hyperbolic transfers
 - Iterative solution with convergence tolerance
 - Return success/failure status
 #### 1.3 Implement Relative Orbit Analysis
 **Location:** `maneuver.cpp`
 ```cpp
 // Calculate relative orbit using Clohessy-Wiltshire (Hill's) equations
 // Returns relative orbital elements in LVLH frame
 void calculate_relative_orbit(Vec3 r_rel, Vec3 v_rel, double mu,
                              Vec3* h_rel, Vec3* e_rel);
 // Calculate relative position/velocity in LVLH frame
 void lvih_frame_transform(Vec3 r, Vec3 v, Vec3 r_parent, Vec3 v_parent,
                          Vec3* r_rel, Vec3* v_rel);
 ```
 **Purpose:** Enable precise phasing calculations
 ---
 ### Phase 2: Planning - Phasing Maneuvers, Rendezvous Planning
 #### 2.1 Implement Phasing Maneuver Planning
 **Location:** `maneuver.cpp`
 ```cpp
 // Calculate phasing orbit to adjust relative position along orbit
 // Returns required delta-v and phasing orbit parameters
 bool calculate_phasing_maneuver(Spacecraft* craft, Spacecraft* target,
                                double phasing_angle, double central_mass,
                                double* dv, double* phasing_period);
 ```
 **Algorithm:**
 - Compute current phase difference
 - Calculate semi-major axis for phasing orbit
 - Determine delta-v for phasing burn
 - Compute phasing orbit period
 #### 2.2 Implement Rendezvous Transfer Planning
 **Location:** `maneuver.cpp`
 ```cpp
 // Calculate optimal rendezvous transfer
 // Returns departure burn parameters and transfer duration
 bool calculate_rendezvous_transfer(Spacecraft* craft, Spacecraft* target,
                                   double central_mass, double max_transfer_time,
                                   double* departure_dv, double* transfer_time,
                                   Vec3* departure_direction);
 ```
 **Algorithm:**
 - Use Lambert solver to find transfer orbit
 - Optimize for minimum delta-v
 - Calculate departure burn direction and magnitude
 - Determine insertion burn requirements
 ---
 ### Phase 3: Integration - Complete calculate_rendezvous(), Configuration Support
 #### 3.1 Add Rendezvous Maneuver Type
 **Location:** `maneuver.h`
 ```cpp
 enum RendezvousType {
    RENDEZVOUS_PROGRADE,
    RENDEZVOUS_RETROGRADE,
    RENDEZVOUS_PHASING,
    RENDEZVOUS_CUSTOM
 };
 struct Maneuver {
    // ... existing fields ...
    RendezvousType rendezvous_type;
    int target_craft_index;
    double max_encounter_distance;
    double max_relative_velocity;
 };
 ```
 **Purpose:** Store rendezvous-specific parameters
 #### 3.2 Add New Trigger Type
 **Location:** `maneuver.h`
 ```cpp
 enum TriggerType {
    TRIGGER_TIME,
    TRIGGER_TRUE_ANOMALY,
    TRIGGER_RENDZVOUS_COMPLETE  // New trigger for rendezvous completion
 };
 ```
 #### 3.3 Extend Config Loader
 **Location:** `config_loader.cpp`
 ```cpp
 // Parse rendezvous parameters from TOML
 bool load_rendezvous_config(toml::table* root, SimulationState* sim);
 ```
 **Config Format:**
 ```toml
 [[rendezvous]]
 craft_index = 0
 target_craft_index = 1
 max_encounter_distance = 1000.0  # meters
 max_relative_velocity = 0.1      # m/s
 ```
 ---
 ### Phase 4: Execution - Multi-burn Handling, Rendezvous Detection
 #### 4.1 Implement Rendezvous Execution Logic
 **Location:** `maneuver.cpp`
 ```cpp
 // Execute rendezvous maneuver with multi-burn sequence
 void execute_rendezvous_maneuver(Maneuver* maneuver, Spacecraft* craft,
                                 SimulationState* sim, double current_time);
 // Handle mid-course corrections during transfer
 void execute_mid_course_correction(Maneuver* maneuver, Spacecraft* craft,
                                   SimulationState* sim);
 ```
 **Features:**
 - Multi-burn sequences (departure, mid-course, insertion)
 - Update target orbital elements as simulation progresses
 - Track rendezvous progress
 #### 4.2 Implement Rendezvous Detection
 **Location:** `maneuver.cpp`
 ```cpp
 // Check if rendezvous is complete
 bool check_rendezvous_complete(Spacecraft* craft, Spacecraft* target,
                               RendezvousTarget* target_params);
 // Calculate encounter state
 void compute_encounter_state(Spacecraft* craft, Spacecraft* target,
                             double central_mass, double* encounter_distance,
                             double* relative_velocity);
 ```
 **Checks:**
 - Distance within encounter parameters
 - Relative velocity within bounds
 - Proper phasing achieved
 ---
 ### Phase 5: Validation - Tests, Feasibility Checks
 #### 5.1 Add Rendezvous Validation Functions
 **Location:** `maneuver.cpp`
 ```cpp
 // Validate rendezvous parameters
 bool validate_rendezvous_parameters(Spacecraft* craft, Spacecraft* target,
                                    RendezvousTarget* target_params,
                                    double central_mass);
 // Check if rendezvous is feasible
 bool is_rendezvous_feasible(Spacecraft* craft, Spacecraft* target,
                            double central_mass, double max_dv_budget);
 ```
 **Validation:**
 - Delta-v budget feasibility
 - Target reachability
 - Encounter geometry validity
 #### 5.2 Create Supporting Utility Functions
 **Location:** `maneuver.cpp`
 ```cpp
 // Calculate optimal transfer time
 double calculate_transfer_time(Vec3 r1, Vec3 r2, double central_mass);
 // Compute target state at encounter time
 void compute_target_state_at_time(Spacecraft* target, double encounter_time,
                                  SimulationState* sim,
                                  Vec3* position, Vec3* velocity);
 // Calculate insertion delta-v
 double calculate_insertion_dv(Vec3 v_arrival, Vec3 v_target,
                              double max_relative_velocity);
 ```
 #### 5.3 Create Unit Tests
 **Location:** `tests/test_rendezvous.cpp`
 **Test Cases:**
 1. Lambert solver accuracy (known solutions)
 2. Relative orbit calculations (Clohessy-Wiltshire verification)
 3. Phasing maneuver calculations (phase angle accuracy)
 4. Rendezvous feasibility checks (delta-v budget)
 5. End-to-end rendezvous planning workflow
 6. Rendezvous detection (distance/velocity thresholds)
 7. Multi-burn sequence execution
 8. Mid-course correction accuracy
 **Testing Guidelines:**
 - Use `WithinAbs()` for floating-point comparisons (NOT `Approx()`)
 - Required header: `<catch2/matchers/catch_matchers_floating_point.hpp>`
 - Test with various orbital configurations (elliptical, circular, inclined)
 ---
 ## Technical Considerations
 ### Lambert's Problem
 - **Universal Variable Formulation:** More robust than classical methods
 - **Convergence:** Newton-Raphson iteration with tolerance ~1e-10
 - **Time of Flight:** Key variable affecting delta-v
 - **Multiple Solutions:** Handle short-way and long-way transfers
 ### Relative Orbit Analysis
 - **Clohessy-Wiltshire Equations:** Linearized relative motion in LVLH frame
 - **Validity:** Small relative distances (< 10% of orbital radius)
 - **Extensions:** Non-linear corrections for large separations
 ### Phasing Maneuvers
 - **Semi-major Axis Selection:** Determines phasing orbit period
 - **Phase Angle:** Angular separation along orbit
 - **Delta-v:** Varies with phase angle and orbital parameters
 ### Multi-Body Considerations
 - **Patched Conics:** For interplanetary rendezvous (advanced)
 - **SOI Transitions:** Handle frame changes during transfer
 - **Third-Body Perturbations:** For high-precision requirements
 ### Implementation Notes
 - Use existing vector/orbital element functions for consistency
 - Follow ZII (Zero Is Initialization) pattern: `MyStruct s = {0};`
 - Minimal comments - code should be self-documenting
 - No decorative comment blocks (===, ---, etc.)
 - Small, focused functions
 - Follow existing patterns in src/
 ---
 ## Priority Order
 1. **Critical Path:** Lambert solver, relative orbit analysis
 2. **Core Functionality:** Phasing maneuvers, rendezvous planning
 3. **Integration:** Complete `calculate_rendezvous()`, configuration support
 4. **Execution:** Multi-burn handling, rendezvous detection
 5. **Validation:** Tests, feasibility checks
 ---
 ## Dependencies
 ### Existing Modules
 - `physics.h/cpp` - Vector/matrix math
 - `orbital_mechanics.h/cpp` - Orbital element conversions, propagation
 - `simulation.h/cpp` - Simulation state management
 - `spacecraft.h` - Spacecraft structure
 - `maneuver.h/cpp` - Maneuver system (primary integration point)
 - `config_loader.h/cpp` - TOML parsing
 ### New Files (Optional)
 - `rendezvous.h` - Rendezvous-specific structures and declarations
 - `rendezvous.cpp` - Rendezvous implementation (if code becomes large)
 ---
 ## Testing Strategy
 ### Unit Tests
 - Lambert solver with known solutions
 - Relative orbit calculations vs analytical solutions
 - Phasing maneuver accuracy
 - Feasibility checks
 ### Integration Tests
 - End-to-end rendezvous planning
 - Multi-burn sequence execution
 - Rendezvous detection accuracy
 ### Validation Tests
 - Energy conservation during transfers
 - Orbital element consistency
 - Long-term stability of rendezvous orbits
 ---
 ## Future Enhancements
 ### Advanced Features
 - **Optimal Control:** Minimize fuel consumption
 - **Autonomous Navigation:** Real-time rendezvous planning
 - **Docking Procedures:** Final approach and docking sequence
 - **Formation Flying:** Multiple spacecraft coordination
 - **Gravity Assist:** Use planetary flybys for rendezvous
 ### Performance Optimizations
 - **Adaptive Time Stepping:** Smaller steps during critical maneuvers
 - **Parallel Computation:** Multi-threaded Lambert solver
 - **GPU Acceleration:** For large-scale simulations
 ---
 ## References
 ### Orbital Mechanics
 - Curtis, H. D. "Orbital Mechanics for Engineering Students"
 - Battin, R. H. "An Introduction to the Mathematics and Methods of Astrodynamics"
 - Vallado, D. A. "Fundamentals of Astrodynamics and Applications"
 ### Lambert's Problem
 - Gooding, R. H. "A Procedure for the Solution of Lambert's Problem"
 - Izzo, D. "Revisiting Lambert's Problem"
 ### Relative Orbit
 - Clohessy, W. H., & Wiltshire, R. S. "Terminal Guidance System for Satellite Rendezvous"
 - Hill, G. W. "Researches in the Lunar Theory"