This document provides a high-level introduction to Aligator, a C++ trajectory optimization library for robotics and optimal control. It explains the library's purpose, core abstractions, and architectural organization.
For installation instructions and initial setup, see Getting Started. For detailed information on the ProxDDP solver algorithm, see ProxDDP Solver. For modeling components (costs, dynamics, constraints), see Problem Modeling.
Aligator is designed to solve constrained optimal control problems for robotic systems. It provides:
The library is particularly suited for:
Sources: README.md1-100
Aligator follows a modular, layered design separating problem definition, solver algorithms, and linear algebra routines.
Diagram: High-Level Component Flow
The user defines a TrajOptProblemTpl composed of multiple StageModelTpl instances (one per time step). Each stage combines:
CostAbstractTpl (or CostStackTpl for multiple costs)DynamicsModelTpl (discrete or continuous dynamics)ConstraintSetTpl instancesThe solver (SolverProxDDPTpl or SolverFDDPTpl) iteratively optimizes this problem, storing intermediate data in WorkspaceTpl and returning the final trajectory in ResultsTpl. Linear-quadratic subproblems are delegated to a RiccatiSolverBase implementation.
Sources: README.md17-32 Diagram 1 from high-level architecture
A trajectory optimization problem in Aligator consists of:
Diagram: Problem Structure in Code
The TrajOptProblemTpl class (include/aligator/core/traj-opt-problem.hpp) aggregates stages and terminal conditions. Each StageModelTpl (include/aligator/core/stage-model.hpp) encapsulates the state/control manifolds, dynamics, cost, and constraints for a single time step.
Sources: README.md17-32 Diagram 3 from high-level architecture
States and controls lie on manifolds represented by ManifoldAbstractTpl:
| Manifold Type | Code Class | Description |
|---|---|---|
| Euclidean space | VectorSpaceTpl | Standard $\mathbb{R}^n$ |
| Lie groups | proxsuite::nlp::SE2Tpl, SE3Tpl | Rotations, poses |
| Multibody configuration | MultibodyConfiguration, MultibodyPhaseSpace | Robot joint spaces (via Pinocchio) |
| Cartesian product | CartesianProductTpl | Composite manifolds |
Sources: Diagram 3 from high-level architecture, README.md24
Aligator implements two main algorithms:
The primary solver, SolverProxDDPTpl (include/aligator/solvers/proxddp/solver-proxddp.hpp), uses an augmented Lagrangian approach:
Diagram: ProxDDP Execution Flow
The backward pass delegates to a RiccatiSolverBase implementation, which can be:
ProximalRiccatiSolver (serial)ParallelRiccatiSolver (multi-threaded via OpenMP)RiccatiSolverDense (stage-dense factorization)Sources: README.md28-31 Diagram 2 from high-level architecture
The alternative solver, SolverFDDPTpl (include/aligator/solvers/fddp/solver-fddp.hpp), maintains trajectory feasibility throughout optimization and is primarily used for unconstrained or simply-constrained problems.
Sources: README.md28-31 Diagram 2 from high-level architecture
Costs are represented by the abstract base class CostAbstractTpl with implementations:
| Cost Type | Class | Description |
|---|---|---|
| Quadratic | QuadraticCostTpl | Direct $\frac{1}{2}x^T Q x + x^T q$ form |
| Residual-based | QuadraticResidualCostTpl | $\frac{1}{2}|r(x,u)|_W^2$ with user-defined residual |
| Stacked costs | CostStackTpl | Weighted sum of multiple costs |
Residuals (subclass of StageFunctionTpl) enable flexible cost definitions. Common residuals include:
StateErrorResidual for state trackingControlErrorResidual for control regularizationFramePlacementResidual for end-effector positioning (Pinocchio-based)FrameVelocityResidual for velocity trackingFrameCollisionResidual for obstacle avoidanceSources: Diagram 3 from high-level architecture, README.md17-27
The DynamicsModelTpl hierarchy includes:
Diagram: Dynamics Model Hierarchy
Continuous dynamics are discretized via IntegratorAbstract subclasses. For multibody systems, MultibodyFreeFwdDynamicsTpl computes forward dynamics using Pinocchio's ABA algorithm with automatic differentiation.
Sources: Diagram 3 from high-level architecture, README.md24
Constraints are organized into sets via ConstraintSetTpl, which aggregates individual ConstraintObjectTpl instances. Each constraint has an associated constraint set:
| Constraint Set Type | Class | Mathematical Form |
|---|---|---|
| Box constraints | BoxConstraintTpl | $u_{min} \leq u \leq u_{max}$ |
| Equality | EqualityConstraintSet | $g(x,u) = 0$ |
| Negative orthant | NegativeOrthantTpl | $g(x,u) \leq 0$ |
The ProxDDP solver projects constraint violations onto these sets during the constraint handling phase.
Sources: Diagram 3 from high-level architecture
Aligator deeply integrates with Pinocchio (github.com/stack-of-tasks/pinocchio):
Diagram: Pinocchio Integration Points
Multibody dynamics leverage Pinocchio's pinocchio::Model and pinocchio::Data structures. Aligator's MultibodyFreeFwdDynamicsTpl calls aba() and computeRNEADerivatives() to compute dynamics and derivatives. Frame-based residuals use forwardKinematics() and Jacobian functions.
Sources: README.md24-25 Diagram 6 from high-level architecture
The aligator_croc_compat library provides a bridge to Crocoddyl:
Diagram: Crocoddyl Compatibility Layer
This allows users to define problems using Crocoddyl's API and solve them with Aligator's solvers.
Sources: README.md25-26 Diagram 6 from high-level architecture
The Python interface is built using Boost.Python and eigenpy:
Diagram: Python Binding Architecture
The bindings expose template instantiations for Scalar=double. Users access classes like aligator.TrajOptProblem, aligator.SolverProxDDP, etc. The eigenpy library automatically converts between NumPy arrays and Eigen matrices.
Sources: Diagram 4 from high-level architecture, README.md26
C++ users directly instantiate template classes:
Sources: README.md95-99 doc/advanced-user-guide.md1-20
The following diagram illustrates the key data structures and their relationships during solver execution:
Diagram: Data Structures in Solver Execution
During setup, the solver allocates a WorkspaceTpl which holds:
problem_data: evaluation results for each stage's dynamics, costs, and constraintslqr_problem: the linearized-quadratic approximation solved in the backward passUpon convergence, ResultsTpl contains the optimized state trajectory (xs), control trajectory (us), and Lagrange multipliers (lams).
Sources: README.md28-31 Diagram 2 from high-level architecture
The Generalized Algebraic Riccati (GAR) sublibrary (include/aligator/gar/) solves time-varying linear-quadratic subproblems:
Diagram: GAR Riccati Solver Structure
Each solver implementation provides:
backward(): computes value function and feedback gainsforward(): applies feedback policy to generate control trajectoryThe parallel solver splits the time horizon across threads for reduced wall-clock time.
Sources: Diagram 2 from high-level architecture, README.md23
Aligator uses CMake with optional features controlled by flags:
| CMake Option | Effect |
|---|---|
BUILD_WITH_PINOCCHIO_SUPPORT | Enable Pinocchio integration |
BUILD_CROCODDYL_COMPAT | Build Crocoddyl compatibility layer |
BUILD_PYTHON_INTERFACE | Generate Python bindings |
ENABLE_TEMPLATE_INSTANTIATION | Explicitly instantiate templates for double |
BUILD_WITH_OPENMP_SUPPORT | Enable parallel Riccati solver |
The library can be installed via:
conda install -c conda-forge aligatorpixi run test (for development)Sources: README.md33-92 package.xml1-26 Diagram 5 from high-level architecture
For real-time and high-performance applications:
Parallel execution: Enable ParallelRiccatiSolver and configure OpenMP threads
Template instantiation: Use ENABLE_TEMPLATE_INSTANTIATION=ON to avoid compile-time overhead
Memory management: Aligator uses polymorphic allocators with mimalloc for optimized allocations
Rollout type: ROLLOUT_LINEAR is faster but ROLLOUT_NONLINEAR may converge in fewer iterations
Sources: README.md101-102 doc/advanced-user-guide.md56-156
Aligator provides a modular, high-performance framework for trajectory optimization:
TrajOptProblemTpl, StageModelTpl, SolverProxDDPTpl/SolverFDDPTplFor details on specific components, refer to the subsequent sections of this documentation.
Sources: README.md1-171 All architecture diagrams
Refresh this wiki
This wiki was recently refreshed. Please wait 1 day to refresh again.