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