maptor 0.1.2

Multiphase Adaptive Trajectory Optimizer

MAPTOR: Multiphase Adaptive Trajectory Optimizer

A Python framework for trajectory optimization using optimal control. MAPTOR solves problems involving the motion of vehicles, robots, spacecraft, and other dynamic systems through space and time using the Legendre-Gauss-Radau pseudospectral method and phs-adaptive mesh refinement.

What is Trajectory Optimization?

Trajectory optimization finds the best path for a dynamic system to follow, considering:

• Physics: System dynamics and constraints
• Objectives: Minimize time, fuel, energy, or tracking error
• Constraints: Safety limits, obstacle avoidance, boundary conditions

Mathematical Foundation: MAPTOR applies optimal control theory to transform continuous trajectory optimization problems into solvable nonlinear programming problems through spectral collocation methods.

Core Methodology

MAPTOR implements the Legendre-Gauss-Radau pseudospectral method with:

• Spectral accuracy: Exponential convergence for smooth solutions
• Adaptive mesh refinement: Automatic error control through phs-adaptive mesh refinement method
• Multiphase capability: Complex missions with automatic phase linking
• Symbolic computation: Built on CasADi for exact differentiation and optimization

Quick Start

import maptor as mtor
import numpy as np

# Minimum-time trajectory: reach target with bounded control
problem = mtor.Problem("Minimum Time to Target")
phase = problem.set_phase(1)

# Variables
t = phase.time(initial=0.0)  # Free final time
position = phase.state("position", initial=0.0, final=1.0)
velocity = phase.state("velocity", initial=0.0, final=0.0)
force = phase.control("force", boundary=(-2.0, 2.0))

# Dynamics and objective
phase.dynamics({position: velocity, velocity: force})
problem.minimize(t.final)

# Solve
phase.mesh([8], [-1.0, 1.0])
solution = mtor.solve_adaptive(problem)

if solution.status["success"]:
    print(f"Optimal time: {solution.status['objective']:.3f}")
    solution.plot()

Problem Classes

Beyond Spatial Trajectories: MAPTOR also handles abstract optimal control problems where "trajectory" refers to the evolution of any system state over time (chemical processes, financial optimization, resource allocation).

Installation

pip install maptor

Requirements: Python 3.10+, NumPy, SciPy, CasADi, Matplotlib

Development Installation:

git clone https://github.com/maptor/maptor.git
cd maptor
pip install -e .

Documentation

Resource	Description
Installation Guide	Setup and dependencies
Quick Start	Basic workflow and first example
Problem Definition Tutorial	Comprehensive problem construction guide
Solution Analysis Tutorial	Working with optimization results
Examples Gallery	Complete problems with mathematical formulations
API Reference	Detailed function documentation

Example Trajectories

The examples gallery demonstrates trajectory optimization across multiple domains:

Advanced Aerospace Applications

• Low-Thrust Orbit Transfer: Orbital mechanics with J2/J3/J4 gravitational perturbations and modified equinoctial elements
• Multiphase Vehicle Launch: Realistic rocket trajectory with stage separations and orbital insertion
• Shuttle Reentry: Atmospheric entry with heat rate constraints and crossrange maximization
• Aero-Assisted Plane Change: Atmospheric maneuvers for orbital inclination change

Advanced Robotics and Control

• Quadcopter Flight: Quadcopter dynamics with obstacle avoidance
• Dynamic Obstacle Avoidance: Dynamic bicycle model moving obstacles
• Overtaking Maneuver: Complex street scenario with dual moving obstacles
• Container Crane Control: Advanced control with swing suppression

Atmospheric and Environmental Systems

• Hang Glider Flight: Thermal soaring optimization with atmospheric updrafts

Interdisciplinary Applications

• Two-Strain Tuberculosis Model: Epidemiological optimal control with drug resistance dynamics

Benchmark and Classical Problems

• Hypersensitive Problem: Challenging optimal control benchmark with sensitive dynamics
• Brachistochrone: Classical fastest descent problem

Architecture

MAPTOR provides a layered architecture separating trajectory design from numerical implementation:

User API (Problem, solve_adaptive, solve_fixed_mesh)
         ↓
Trajectory Definition (States, controls, dynamics, constraints)
         ↓
Mathematical Framework (Radau pseudospectral method)
         ↓
Symbolic Computation (CasADi expressions and differentiation)
         ↓
Optimization (IPOPT nonlinear programming solver)

Key Design Principles:

• Intuitive API: Define trajectories naturally without numerical details
• Automatic differentiation: CasADi handles complex derivative computations
• Adaptive precision: Mesh refinement ensures solution accuracy
• Multiphase support: Complex missions with automatic phase transitions

Contributing

We currently do not accept code submissions, but we welcome issues and feedback reports from the trajectory optimization and optimal control community. Please use GitHub Issues to:

• Report bugs or unexpected behavior
• Request new features or enhancements
• Ask questions about usage or implementation
• Suggest improvements to documentation or examples
• Share feedback on your experience with MAPTOR

Your input helps improve MAPTOR for the entire community.

License

MAPTOR is licensed under the GNU Lesser General Public License v3.0. This allows use in both open source and proprietary applications while ensuring improvements to the core library remain open.

Citation

If you use MAPTOR in academic research, please cite:

@software{maptor2025,
  title={MAPTOR: Multiphase Adaptive Trajectory Optimizer},
  author={Timothy, David},
  year={2025},
  url={https://github.com/maptor/maptor},
  version={0.1.0}
}

References

MAPTOR builds upon established methods in computational optimal control:

Optimal Control Theory and Methods:

• Betts, J. T. (2020). Practical Methods for Optimal Control Using Nonlinear Programming, Third Edition. Society for Industrial and Applied Mathematics. https://doi.org/10.1137/1.9781611976199

Pseudospectral Methods:

• Agamawi, Y. M., & Rao, A. V. (2020). CGPOPS: A C++ Software for Solving Multiple-Phase Optimal Control Problems Using Adaptive Gaussian Quadrature Collocation and Sparse Nonlinear Programming. ACM Transactions on Mathematical Software, 46(3), Article 25. https://doi.org/10.1145/3390463

Adaptive Mesh Refinement:

• Haman III, G. V., & Rao, A. V. (2024). Adaptive Mesh Refinement and Error Estimation Method for Optimal Control Using Direct Collocation. arXiv preprint arXiv:2410.07488. https://arxiv.org/abs/2410.07488

Symbolic Computation Framework:

• Andersson, J. A. E., Gillis, J., Horn, G., Rawlings, J. B., & Diehl, M. (2019). CasADi -- A software framework for nonlinear optimization and optimal control. Mathematical Programming Computation, 11(1), 1-36. https://doi.org/10.1007/s12532-018-0139-4

Support

• Documentation: https://maptor.github.io/maptor
• Issues: GitHub Issues

Acknowledgments

MAPTOR implements methods from the computational optimal control literature, particularly pseudospectral collocation techniques and adaptive mesh refinement strategies. The framework leverages CasADi for symbolic computation and automatic differentiation.

---

Next Steps: Begin with the Quick Start Guide or explore the Examples Gallery to see MAPTOR applied to trajectory optimization problems in your domain.