This project implements a 3D powered descent guidance algorithm using successive convexification. It solves for an optimal trajectory that starts at a high altitude and lands at a lower altitude, considering an obstacle avoidance constraint.

.
├── main.py
└── src
    ├── trajectory.py
    ├── solver.py
    └── visualization.py

• main.py
  Entrypoint. Calls the solver (gfold_3d_successive_convexification) and plots the solution if one is found.

• src/trajectory.py
  Contains the function gfold_3d_successive_convexification that performs successive convexification:

  1. Initializes a guess for the position, velocity, and mass profiles.
  2. Iteratively calls the subproblem solver (solve_subproblem in solver.py).
  3. Checks convergence by comparing the new solution to the previous one.
  4. Returns the final solution if convergence is achieved (or if the iteration limit is reached).

• src/solver.py
  Defines solve_subproblem, which sets up a single convex subproblem and solves it using CVXPY. Key points:

  • Enforces dynamics constraints through linearization around the previous trajectory.
  • Constrains thrust magnitude, tilt, mass depletion, and obstacle avoidance.
  • Minimizes total thrust usage (sum(T_mag)).
  • Uses SCS as the solver by default.

• src/visualization.py
  Contains visualize_3d_solution, which uses Matplotlib to produce a 3D plot of the trajectory. It also plots a wireframe sphere representing the obstacle, if provided.

1. Install Dependencies

   • Python 3.9+ recommended
   • Required packages: numpy, matplotlib, cvxpy, scs, ecos

     pip install -r requirements.txt

2. Run the Main Script
   From the project root, execute:

   # Single-phase powered descent (default)
   python main.py
   
   # Multi-phase example with a thrust–coast–thrust profile and a 100 kg stage drop
   python main.py --multi-phase
   
   # Run a 20-sample Monte-Carlo campaign (parallel workers)
   python main.py --mc 20
   
   # Same as above but disable multiprocessing (useful on Windows)
   python main.py --mc 20 --no-parallel

   The script reports fuel usage and opens a 3-D Matplotlib plot. If the optimisation is infeasible, consider loosening constraints (e.g., increasing T_max or available propellant).

• Successive Convexification:
  The technique linearizes the non-convex parts around the previous iteration's solution. After each iteration, it updates the reference trajectory and repeats until convergence or an iteration limit is reached.

• Obstacle Avoidance:
  The algorithm includes a simple obstacle avoidance constraint by enforcing a half-space constraint around the obstacle for each time step, based on the previous trajectory's relative distance to the obstacle.

• Thrust & Propulsion Constraints:

  • Per-step lower/upper thrust limits support multi-phase profiles (e.g., coast arcs with T_max = 0).
  • Variable specific impulse (Isp) profiles allow throttle-efficiency curves.
  • Stage-drop array instantaneously subtracts dry-mass at specified timesteps.

• Aerodynamic Drag (new):
  Includes a quadratic drag model linearised about the previous iteration. Air-density ρ, drag coefficient C_D and reference area A_ref are configurable.

• Multi-Phase Powered Descent (new):
  Activate with --multi-phase to run a built-in demo featuring a thrust-coast-thrust sequence and a 100 kg stage separation event. You can customise the profiles by calling gfold_3d_successive_convexification directly with T_min_profile, T_max_profile, Isp_profile, and stage_drops arrays.

• Attitude & Gimbal Limits (new):
  Small-angle Euler states (φ, θ, ψ) and body rates (p, q, r) are now part of the optimisation. Thrust components are linearised around the relation
  Tx ≈ −θ |T|, Ty ≈ φ |T|, and the slider θ_max imposes a physical gimbal envelope. Legacy behaviour (no attitude) is recovered automatically when attitude variables remain zero.

• Monte-Carlo Driver (new):
  src/mc_driver.py wraps the optimiser, perturbs user-defined parameters, distributes runs across CPU cores, and returns summary statistics.

• Interactive Dashboard (new):
  visualize_multi_run() launches an interactive Matplotlib figure with:
  • a 3-D trajectory pane
  • velocity-magnitude and mass time-series
  • a slider to flip through individual Monte-Carlo samples.

• Plotting:

  • Single-run: start (green), end (red), trajectory (blue), obstacle (translucent red sphere).
  • Flight-envelope helper (plot_flight_envelope) shows velocity, mass, and thrust histories.
  • Monte-Carlo slider dashboard combines both views.

MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.