# abuibaid/roboplan_mpc architecture

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

- Interactive diagram: https://gitdiagram.com/abuibaid/roboplan_mpc
- Repository: https://github.com/abuibaid/roboplan_mpc

## Overview

roboplan_MPC is a joint-space model-predictive controller for robot arms, with C++ and Python APIs. Its example workflow builds a RoboPlan scene, converts Cartesian targets to joint goals with OInK, sets the MPC goal, and repeatedly solves from the measured state; the predicted trajectory can then be followed or visualized. Internally, the MPC formulates a constrained multiple-shooting problem, using Pinocchio dynamics and symbolic forward kinematics for environment limits, and CasADi solvers. The example and solve flow are excerpted; several solver and trajectory details are documented in the README rather than fully shown in source excerpts.

Main entry points: [`roboplan_mpc_examples/python/example_mpc.py`](https://github.com/abuibaid/roboplan_mpc/blob/main/roboplan_mpc_examples/python/example_mpc.py) (MPC example), [`src/mpc.cpp`](https://github.com/abuibaid/roboplan_mpc/blob/main/src/mpc.cpp) (MPC controller), [`bindings/python/roboplan/mpc/__init__.py`](https://github.com/abuibaid/roboplan_mpc/blob/main/bindings/python/roboplan/mpc/__init__.py) (Python API), [`bindings/src/mpc.cpp`](https://github.com/abuibaid/roboplan_mpc/blob/main/bindings/src/mpc.cpp) (Nanobind bindings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_application["Application workflow"]
  node_example["MPC example<br/>[example_mpc.py]"]
  node_trajectory["Predicted trajectory"]
  node_visualization["Trajectory visualization<br/>[example_mpc.py]"]
end

subgraph group_api["MPC API"]
  node_python_api["Python API<br/>[__init__.py]"]
  node_python_bindings["Nanobind bindings<br/>[mpc.cpp]"]
  node_mpc_contract["MPC API contract<br/>[mpc.hpp]"]
end

subgraph group_control["Control formulation"]
  node_mpc["MPC controller<br/>[mpc.cpp]"]
  node_formulation["MPC formulation<br/>[mpc.cpp]"]
  node_robot_transform["Symbolic kinematics"]
end

subgraph group_integrations["Robot integrations"]
  node_oink["OInK IK"]
  node_scene["RoboPlan Scene"]
  node_pinocchio["Pinocchio dynamics"]
  node_casadi["CasADi solver"]
end

node_operator(("Operator"))
node_robot["Robot controller"]

node_operator -->|"runs example"| node_example
node_example -->|"builds scene"| node_scene
node_example -->|"solves IK"| node_oink
node_example -->|"imports API"| node_python_api
node_python_api -->|"loads extension"| node_python_bindings
node_python_bindings -->|"exposes methods"| node_mpc
node_mpc -->|"implements API"| node_mpc_contract
node_mpc -->|"uses scene"| node_scene
node_mpc -->|"sets up problem"| node_formulation
node_formulation -->|"builds constraints"| node_robot_transform
node_formulation -->|"computes dynamics"| node_pinocchio
node_formulation -->|"solves NLP"| node_casadi
node_example -->|"sets goal and solves"| node_mpc
node_example -->|"receives prediction"| node_trajectory
node_mpc -->|"returns trajectory"| node_trajectory
node_trajectory -.->|"follows plan"| node_robot
node_example -->|"plots and animates"| node_visualization

click node_example "https://github.com/abuibaid/roboplan_mpc/blob/main/roboplan_mpc_examples/python/example_mpc.py"
click node_python_api "https://github.com/abuibaid/roboplan_mpc/blob/main/bindings/python/roboplan/mpc/__init__.py"
click node_python_bindings "https://github.com/abuibaid/roboplan_mpc/blob/main/bindings/src/mpc.cpp"
click node_mpc "https://github.com/abuibaid/roboplan_mpc/blob/main/src/mpc.cpp"
click node_mpc_contract "https://github.com/abuibaid/roboplan_mpc/blob/main/include/roboplan_mpc/mpc.hpp"
click node_formulation "https://github.com/abuibaid/roboplan_mpc/blob/main/src/mpc.cpp"
click node_robot_transform "https://github.com/abuibaid/roboplan_mpc/blob/main/src/robot_transformation.cpp"
click node_visualization "https://github.com/abuibaid/roboplan_mpc/blob/main/roboplan_mpc_examples/python/example_mpc.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_example,node_trajectory,node_visualization toneBlue
class node_python_api,node_python_bindings,node_mpc_contract toneAmber
class node_mpc,node_formulation,node_robot_transform toneMint
class node_oink,node_scene,node_pinocchio,node_casadi toneRose
class node_operator,node_robot toneIndigo
```

## Components

### Application workflow

- [MPC example](https://github.com/abuibaid/roboplan_mpc/blob/main/roboplan_mpc_examples/python/example_mpc.py): `roboplan_mpc_examples/python/example_mpc.py`
- **Predicted trajectory**
- [Trajectory visualization](https://github.com/abuibaid/roboplan_mpc/blob/main/roboplan_mpc_examples/python/example_mpc.py): `roboplan_mpc_examples/python/example_mpc.py`

### MPC API

- [Python API](https://github.com/abuibaid/roboplan_mpc/blob/main/bindings/python/roboplan/mpc/__init__.py): `bindings/python/roboplan/mpc/__init__.py`
- [Nanobind bindings](https://github.com/abuibaid/roboplan_mpc/blob/main/bindings/src/mpc.cpp): `bindings/src/mpc.cpp`
- [MPC API contract](https://github.com/abuibaid/roboplan_mpc/blob/main/include/roboplan_mpc/mpc.hpp): `include/roboplan_mpc/mpc.hpp`

### Control formulation

- [MPC controller](https://github.com/abuibaid/roboplan_mpc/blob/main/src/mpc.cpp): `src/mpc.cpp`
- [MPC formulation](https://github.com/abuibaid/roboplan_mpc/blob/main/src/mpc.cpp): `src/mpc.cpp`
- [Symbolic kinematics](https://github.com/abuibaid/roboplan_mpc/blob/main/src/robot_transformation.cpp): `src/robot_transformation.cpp`

### Robot integrations

- **OInK IK**
- **RoboPlan Scene**
- **Pinocchio dynamics**
- **CasADi solver**

### Other components

- **Operator**
- **Robot controller**

## Connections

- Operator → MPC example: runs example (evidence: `README.md`)
- MPC example → RoboPlan Scene: builds scene (evidence: `roboplan_mpc_examples/python/example_mpc.py`)
- MPC example → OInK IK: solves IK (evidence: `roboplan_mpc_examples/python/example_mpc.py`)
- MPC example → Python API: imports API (evidence: `roboplan_mpc_examples/python/example_mpc.py`)
- Python API → Nanobind bindings: loads extension (evidence: `bindings/python/roboplan/mpc/__init__.py`)
- Nanobind bindings → MPC controller: exposes methods (evidence: `bindings/src/mpc.cpp`)
- MPC controller → MPC API contract: implements API (evidence: `include/roboplan_mpc/mpc.hpp`)
- MPC controller → RoboPlan Scene: uses scene
- MPC controller → MPC formulation: sets up problem (evidence: `src/mpc.cpp`)
- MPC formulation → Symbolic kinematics: builds constraints (evidence: `src/mpc.cpp`)
- MPC formulation → Pinocchio dynamics: computes dynamics (evidence: `README.md`)
- MPC formulation → CasADi solver: solves NLP (evidence: `src/mpc.cpp`)
- MPC example → MPC controller: sets goal and solves (evidence: `roboplan_mpc_examples/python/example_mpc.py`)
- MPC example → Predicted trajectory: receives prediction (evidence: `README.md`)
- MPC controller → Predicted trajectory: returns trajectory
- Predicted trajectory → Robot controller: follows plan (evidence: `README.md`)
- MPC example → Trajectory visualization: plots and animates (evidence: `roboplan_mpc_examples/python/example_mpc.py`)