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"