# leggedrobotics/ocs2 architecture

> Architecture diagram of the GitHub repository leggedrobotics/ocs2, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/leggedrobotics/ocs2
- Repository: https://github.com/leggedrobotics/ocs2

## Overview

##### Project type and purpose
- This is an open‐source C++ toolbox (OCS2) for optimal control of switched systems, offering multiple solver algorithms (DDP, iLQR, SQP, SLQ, PISOC), automatic differentiation, URDF-based model setup, ROS interfaces, Python bindings, documentation, and robotic examples.

##### High-level architectural layers
A. Third-party libraries
- cppad, cppadcg, ipopt, Eigen, BLASFEO, HPIPM, Pinocchio, Raisim, etc.
- Footprint: `ocs2_thirdparty`, `blasfeo_catkin`, `hpipm_catkin`
B. Core computation layer (`ocs2_core`)
- Numeric traits, integrators, differentiators, constraints, costs, dynamics, loop-shaping, penalties, thread support
- Auto-diff engine and solver pre‐computation
C. Solver modules
- Differential dynamic programming: `ocs2_ddp`
- Interior point multiple-shooting: `ocs2_ipm`
- Sequential linear quadratic (SLQ): `ocs2_slp`
- Sequential quadratic programming (SQP): `ocs2_sqp/ocs2_sqp`
- Classical multiple-shooting: `ocs2_oc`
- Aggregator/upper‐level control: `ocs2_ocs2`
- Gradient‐based solvers: `ocs2_frank_wolfe`
D. Interfaces and bindings
- ROS messages & topics: `ocs2_msgs`
- ROS wrapper & visualization: `ocs2_ros_interfaces`
- Python bindings: `ocs2_python_interface`, `ocs2_mpcnet_core` + per-robot MPCNet packages
E. Robotics examples and deployment
- Robot-specific modules: `ocs2_robotic_examples/*` (ballbot, cartpole, legged, mobile manipulator, anymal, quadrotor)
- Physics-based rollout: `ocs2_raisim` (Raisim core, visualization, ROS converters)
F. Documentation and CI
- Sphinx and Doxygen: `ocs2_doc`
- GitHub Actions, Jenkins pipelines, Dockerfile

##### Data and control flow
1) User supplies URDF & configuration →
2) Model generator (in core or examples) produces system dynamics, cost, constraints →
3) Core pre‐computation & auto-diff →
4) Solver module (DDP/SPQ/SLQ/IPM/etc.) computes optimal control →
5) Rollout & performance indices →
6) Interfaces publish results via ROS topics (`ocs2_msgs`) →
7) Visualization in RViz or execution on hardware
8) Python layer (MPCNet or Python API) can drive training or call C++ library

##### Architectural patterns and principles
- Layered modular design: clear separation of core math, solver algorithms, interfaces, and applications
- Plugin-style solver modules share common core interfaces
- Use of CMake for multi-package build, ROS catkin style for message and interface packages
- Python bindings via Pybind11 layered on top of C++ core
- Automatic differentiation isolates derivative code from high-level logic

## Diagram (Mermaid)

```mermaid
flowchart TD
    URDF["URDF & Configuration"]:::input
    subgraph "Third-Party Libraries"
        direction TB
        TP1["CppAD & CppADCodeGen"]:::thirdparty
        TP2["BLASFEO"]:::thirdparty
        TP3["HPIPM"]:::thirdparty
    end

    subgraph "Core Computation (ocs2_core)"
        direction TB
        OC_inc["include/ocs2_core"]:::core
        OC_src["src"]:::core
        OC_test["test"]:::core
        AD["Auto-Diff & Pre-Comp"]:::core
    end

    subgraph "Solver Modules"
        direction TB
        DDP["ocs2_ddp"]:::solv
        IPM["ocs2_ipm"]:::solv
        SLP["ocs2_slp"]:::solv
        SQP["ocs2_sqp"]:::solv
        OC_mod["ocs2_oc"]:::solv
        OCS2["ocs2_ocs2"]:::solv
        FW["ocs2_frank_wolfe"]:::solv
    end

    subgraph "Interfaces & Bindings"
        direction TB
        ROS_msgs["ocs2_msgs"]:::interface
        ROS_if["ocs2_ros_interfaces"]:::interface
        Py_int["ocs2_python_interface"]:::interface
        MPC_core["ocs2_mpcnet_core"]:::interface
        MPC_robot["MPCNet Robot Packages"]:::interface
    end

    subgraph "Robotic Examples & Deployment"
        direction TB
        Examples["ocs2_robotic_examples/*"]:::example
        Raisim["ocs2_raisim"]:::example
    end

    subgraph "Documentation & CI"
        direction TB
        Docs["ocs2_doc"]:::doc
        GH[".github/workflows"]:::doc
        Jenkins["jenkins-pipeline"]:::doc
    end

    RViz["RViz / Hardware"]:::ext

    %% Data Flow
    URDF -->|"URDF & config"| OC_inc
    OC_inc -->|"dynamics, cost, constraints"| AD
    TP1 --> OC_inc
    TP2 --> OC_inc
    TP3 --> OC_inc
    AD -->|"models"| DDP
    AD -->|"models"| IPM
    AD -->|"models"| SLP
    AD -->|"models"| SQP
    AD -->|"models"| OC_mod
    AD -->|"models"| OCS2
    AD -->|"models"| FW
    DDP -->|"optimal control commands"| ROS_msgs
    IPM --> ROS_msgs
    SLP --> ROS_msgs
    SQP --> ROS_msgs
    OC_mod --> ROS_msgs
    OCS2 --> ROS_msgs
    FW --> ROS_msgs
    ROS_msgs --> ROS_if
    ROS_if --> RViz
    DDP --> Raisim
    IPM --> Raisim
    SLP --> Raisim
    SQP --> Raisim
    OC_mod --> Raisim
    OCS2 --> Raisim
    FW --> Raisim
    Raisim --> ROS_if
    OC_inc <--> Py_int
    OC_inc <--> MPC_core
    MPC_core <--> MPC_robot
    Examples --> OC_inc
    Examples --> ROS_if

    %% Click Events
    click TP1 "https://github.com/leggedrobotics/ocs2/tree/main/ocs2_thirdparty/"
    click TP2 "https://github.com/leggedrobotics/ocs2/tree/main/ocs2_sqp/blasfeo_catkin/"
    click TP3 "https://github.com/leggedrobotics/ocs2/tree/main/ocs2_sqp/hpipm_catkin/"
    click OC_inc "https://github.com/leggedrobotics/ocs2/tree/main/ocs2_core/include/ocs2_core/"
    click OC_src "https://github.com/leggedrobotics/ocs2/tree/main/ocs2_core/src/"
    click OC_test "https://github.com/leggedrobotics/ocs2/tree/main/ocs2_core/test/"
    click DDP "https://github.com/leggedrobotics/ocs2/tree/main/ocs2_ddp/"
    click IPM "https://github.com/leggedrobotics/ocs2/tree/main/ocs2_ipm/"
    click SLP "https://github.com/leggedrobotics/ocs2/tree/main/ocs2_slp/"
    click SQP "https://github.com/leggedrobotics/ocs2/tree/main/ocs2_sqp/ocs2_sqp/"
    click OC_mod "https://github.com/leggedrobotics/ocs2/tree/main/ocs2_oc/"
    click OCS2 "https://github.com/leggedrobotics/ocs2/tree/main/ocs2_ocs2/"
    click FW "https://github.com/leggedrobotics/ocs2/tree/main/ocs2_frank_wolfe/"
    click ROS_msgs "https://github.com/leggedrobotics/ocs2/tree/main/ocs2_msgs/"
    click ROS_if "https://github.com/leggedrobotics/ocs2/tree/main/ocs2_ros_interfaces/"
    click Py_int "https://github.com/leggedrobotics/ocs2/tree/main/ocs2_python_interface/"
    click MPC_core "https://github.com/leggedrobotics/ocs2/tree/main/ocs2_mpcnet/ocs2_mpcnet_core/"
    click MPC_robot "https://github.com/leggedrobotics/ocs2/tree/main/ocs2_mpcnet/ocs2_ballbot_mpcnet/"
    click Examples "https://github.com/leggedrobotics/ocs2/tree/main/ocs2_robotic_examples/ocs2_ballbot/"
    click Raisim "https://github.com/leggedrobotics/ocs2/tree/main/ocs2_raisim/"
    click Docs "https://github.com/leggedrobotics/ocs2/tree/main/ocs2_doc/"
    click GH "https://github.com/leggedrobotics/ocs2/tree/main/.github/workflows/"
    click Jenkins "https://github.com/leggedrobotics/ocs2/tree/main/jenkins-pipeline/"

    %% Styles
    classDef thirdparty fill:#d3d3d3,stroke:#555;
    classDef core fill:#ffdead,stroke:#555;
    classDef solv fill:#98fb98,stroke:#555;
    classDef interface fill:#add8e6,stroke:#555;
    classDef example fill:#dda0dd,stroke:#555;
    classDef doc fill:#ffffe0,stroke:#555;
    classDef input fill:#f0e68c,stroke:#555;
    classDef ext fill:#fffafa,stroke:#555,stroke-dasharray: 5 5;
```
