claudes_game/docs/planning/rendezvous_planning.md

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

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

// 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

// 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

// 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

// 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

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

enum TriggerType {
    TRIGGER_TIME,
    TRIGGER_TRUE_ANOMALY,
    TRIGGER_RENDZVOUS_COMPLETE  // New trigger for rendezvous completion
};

3.3 Extend Config Loader

Location: config_loader.cpp

// Parse rendezvous parameters from TOML
bool load_rendezvous_config(toml::table* root, SimulationState* sim);

Config Format:

[[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

// 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

// 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

// 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

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