From 625b4cfad0bc7d5ad2ea7dfc1bedb4da4144b6cd Mon Sep 17 00:00:00 2001 From: cinnaboot Date: Mon, 6 Apr 2026 13:03:05 +0000 Subject: [PATCH] add rendezvous planning doc --- docs/planning/rendezvous_planning.md | 366 +++++++++++++++++++++++++++ 1 file changed, 366 insertions(+) create mode 100644 docs/planning/rendezvous_planning.md diff --git a/docs/planning/rendezvous_planning.md b/docs/planning/rendezvous_planning.md new file mode 100644 index 0000000..de7d520 --- /dev/null +++ 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: `` +- 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"