# commonroad/commonroad-control architecture

> Architecture diagram of the GitHub repository commonroad/commonroad-control, 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/commonroad/commonroad-control
- Repository: https://github.com/commonroad/commonroad-control

## Overview

CommonRoad Control is a motion-control and dynamic-simulation toolbox for autonomous driving. A planner’s trajectory can be converted into supported vehicle-model representations, extended into a controller reference, and used by MPC or PID control; the simulation advances vehicle dynamics and provides modeled sensor feedback. The toolbox also exposes easy planner APIs, uncertainty models, multiple vehicle models, and visualization utilities. The main runtime wiring is partly supported by the source index and simulation excerpts; unsampled controller and easy-API internals are represented conservatively, and their links are documented or marked unverified.

Main entry points: [`commonroad_control/cr_control_easy_api/mpc_for_dedicated_planner.py`](https://github.com/commonroad/commonroad-control/blob/develop/commonroad_control/cr_control_easy_api/mpc_for_dedicated_planner.py) (MPC planner API), [`commonroad_control/simulation/simulation/simulation.py`](https://github.com/commonroad/commonroad-control/blob/develop/commonroad_control/simulation/simulation/simulation.py) (Dynamic simulation), [`commonroad_control/planning_converter/reactive_planner_converter.py`](https://github.com/commonroad/commonroad-control/blob/develop/commonroad_control/planning_converter/reactive_planner_converter.py) (Reactive planner converter), [`commonroad_control/vehicle_dynamics/vehicle_model_interface.py`](https://github.com/commonroad/commonroad-control/blob/develop/commonroad_control/vehicle_dynamics/vehicle_model_interface.py) (Vehicle model interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_planning["Planning Integration"]
  node_easy_mpc["MPC planner API"]
  node_easy_pid["PID planner API"]
  node_converter["Reactive planner converter"]
end

subgraph group_control["Control"]
  node_reference["Reference trajectory"]
  node_mpc["MPC controllers"]
  node_pid["PID controllers"]
end

subgraph group_simulation["Simulation and Sensing"]
  node_sim["Dynamic simulation<br/>[simulation.py]"]
  node_sensor["Sensor models"]
  node_feedback["Full-state feedback"]
  node_uncertainty["Uncertainty models"]
end

subgraph group_dynamics["Vehicle Dynamics"]
  node_vehicle_interface["Vehicle model interface"]
  node_dynamic_bicycle["Dynamic bicycle<br/>[dynamic_bicycle.py]"]
  node_kinematic_bicycle["Kinematic bicycle"]
  node_db_factory["Dynamic bicycle factory<br/>[db_sidt_factory.py]"]
  node_kb_factory["Kinematic bicycle factory<br/>[kb_sidt_factory.py]"]
  node_trajectory["Trajectory representation"]
  node_vehicle_params["Vehicle parameters"]
end

subgraph group_support["Utilities and Visualization"]
  node_clcs["Curvilinear utilities"]
  node_conversion["State conversion<br/>[conversion_util.py]"]
  node_visual_state["Control visualization"]
  node_visual_traj["Trajectory visualization"]
end

node_planner(("Motion planner"))

node_planner -.->|"provides plan"| node_easy_mpc
node_planner -.->|"provides plan"| node_easy_pid
node_easy_mpc -->|"uses converter"| node_converter
node_converter -->|"converts states"| node_conversion
node_converter -->|"builds trajectories"| node_db_factory
node_converter -->|"builds trajectories"| node_kb_factory
node_easy_mpc -->|"builds reference"| node_reference
node_easy_mpc -->|"invokes controller"| node_mpc
node_easy_pid -.->|"invokes controller"| node_pid
node_easy_mpc -->|"simulates motion"| node_sim
node_sim -->|"advances dynamics"| node_vehicle_interface
node_sim -->|"requests measurements"| node_sensor
node_sim -->|"samples disturbance"| node_uncertainty
node_sim -->|"defaults sensor"| node_feedback
node_feedback -.->|"implements interface"| node_sensor
node_dynamic_bicycle -.->|"implements model"| node_vehicle_interface
node_kinematic_bicycle -.->|"implements model"| node_vehicle_interface
node_db_factory -->|"creates trajectories"| node_trajectory
node_kb_factory -->|"creates trajectories"| node_trajectory
node_vehicle_interface -->|"uses parameters"| node_vehicle_params
node_reference -->|"creates reference data"| node_trajectory
node_easy_mpc -->|"extends reference"| node_clcs
node_easy_mpc -->|"visualizes state"| node_visual_state
node_easy_mpc -->|"visualizes trajectories"| node_visual_traj

click node_easy_mpc "https://github.com/commonroad/commonroad-control/blob/develop/commonroad_control/cr_control_easy_api/mpc_for_dedicated_planner.py"
click node_easy_pid "https://github.com/commonroad/commonroad-control/blob/develop/commonroad_control/cr_control_easy_api/pid_for_dedicated_planner.py"
click node_converter "https://github.com/commonroad/commonroad-control/blob/develop/commonroad_control/planning_converter/reactive_planner_converter.py"
click node_reference "https://github.com/commonroad/commonroad-control/blob/develop/commonroad_control/control/reference_trajectory_factory.py"
click node_mpc "https://github.com/commonroad/commonroad-control/blob/develop/commonroad_control/control/model_predictive_control/optimal_control/optimal_control_scvx.py"
click node_pid "https://github.com/commonroad/commonroad-control/tree/develop/commonroad_control/control/pid"
click node_sim "https://github.com/commonroad/commonroad-control/blob/develop/commonroad_control/simulation/simulation/simulation.py"
click node_sensor "https://github.com/commonroad/commonroad-control/blob/develop/commonroad_control/simulation/sensor_models/sensor_model_interface.py"
click node_feedback "https://github.com/commonroad/commonroad-control/blob/develop/commonroad_control/simulation/sensor_models/full_state_feedback/full_state_feedback.py"
click node_uncertainty "https://github.com/commonroad/commonroad-control/blob/develop/commonroad_control/simulation/uncertainty_model/gaussian_distribution.py"
click node_vehicle_interface "https://github.com/commonroad/commonroad-control/blob/develop/commonroad_control/vehicle_dynamics/vehicle_model_interface.py"
click node_dynamic_bicycle "https://github.com/commonroad/commonroad-control/blob/develop/commonroad_control/vehicle_dynamics/dynamic_bicycle/dynamic_bicycle.py"
click node_kinematic_bicycle "https://github.com/commonroad/commonroad-control/blob/develop/commonroad_control/vehicle_dynamics/kinematic_bicycle/kinematic_bicycle.py"
click node_db_factory "https://github.com/commonroad/commonroad-control/blob/develop/commonroad_control/vehicle_dynamics/dynamic_bicycle/db_sidt_factory.py"
click node_kb_factory "https://github.com/commonroad/commonroad-control/blob/develop/commonroad_control/vehicle_dynamics/kinematic_bicycle/kb_sidt_factory.py"
click node_trajectory "https://github.com/commonroad/commonroad-control/blob/develop/commonroad_control/vehicle_dynamics/trajectory_interface.py"
click node_vehicle_params "https://github.com/commonroad/commonroad-control/blob/develop/commonroad_control/vehicle_parameters/vehicle_parameters.py"
click node_clcs "https://github.com/commonroad/commonroad-control/blob/develop/commonroad_control/util/clcs_control_util.py"
click node_conversion "https://github.com/commonroad/commonroad-control/blob/develop/commonroad_control/util/conversion_util.py"
click node_visual_state "https://github.com/commonroad/commonroad-control/blob/develop/commonroad_control/util/visualization/visualize_control_state.py"
click node_visual_traj "https://github.com/commonroad/commonroad-control/blob/develop/commonroad_control/util/visualization/visualize_trajectories.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_easy_mpc,node_easy_pid,node_converter toneBlue
class node_reference,node_mpc,node_pid toneAmber
class node_sim,node_sensor,node_feedback,node_uncertainty toneMint
class node_vehicle_interface,node_dynamic_bicycle,node_kinematic_bicycle,node_db_factory,node_kb_factory,node_trajectory,node_vehicle_params toneRose
class node_clcs,node_conversion,node_visual_state,node_visual_traj,node_planner toneIndigo
```

## Components

### Planning Integration

- [MPC planner API](https://github.com/commonroad/commonroad-control/blob/develop/commonroad_control/cr_control_easy_api/mpc_for_dedicated_planner.py): `commonroad_control/cr_control_easy_api/mpc_for_dedicated_planner.py`
- [PID planner API](https://github.com/commonroad/commonroad-control/blob/develop/commonroad_control/cr_control_easy_api/pid_for_dedicated_planner.py): `commonroad_control/cr_control_easy_api/pid_for_dedicated_planner.py`
- [Reactive planner converter](https://github.com/commonroad/commonroad-control/blob/develop/commonroad_control/planning_converter/reactive_planner_converter.py): `commonroad_control/planning_converter/reactive_planner_converter.py`

### Control

- [Reference trajectory](https://github.com/commonroad/commonroad-control/blob/develop/commonroad_control/control/reference_trajectory_factory.py): `commonroad_control/control/reference_trajectory_factory.py`
- [MPC controllers](https://github.com/commonroad/commonroad-control/blob/develop/commonroad_control/control/model_predictive_control/optimal_control/optimal_control_scvx.py): `commonroad_control/control/model_predictive_control/optimal_control/optimal_control_scvx.py`
- [PID controllers](https://github.com/commonroad/commonroad-control/tree/develop/commonroad_control/control/pid): `commonroad_control/control/pid`

### Simulation and Sensing

- [Dynamic simulation](https://github.com/commonroad/commonroad-control/blob/develop/commonroad_control/simulation/simulation/simulation.py): `commonroad_control/simulation/simulation/simulation.py`
- [Sensor models](https://github.com/commonroad/commonroad-control/blob/develop/commonroad_control/simulation/sensor_models/sensor_model_interface.py): `commonroad_control/simulation/sensor_models/sensor_model_interface.py`
- [Full-state feedback](https://github.com/commonroad/commonroad-control/blob/develop/commonroad_control/simulation/sensor_models/full_state_feedback/full_state_feedback.py): `commonroad_control/simulation/sensor_models/full_state_feedback/full_state_feedback.py`
- [Uncertainty models](https://github.com/commonroad/commonroad-control/blob/develop/commonroad_control/simulation/uncertainty_model/gaussian_distribution.py): `commonroad_control/simulation/uncertainty_model/gaussian_distribution.py`

### Vehicle Dynamics

- [Vehicle model interface](https://github.com/commonroad/commonroad-control/blob/develop/commonroad_control/vehicle_dynamics/vehicle_model_interface.py): `commonroad_control/vehicle_dynamics/vehicle_model_interface.py`
- [Dynamic bicycle](https://github.com/commonroad/commonroad-control/blob/develop/commonroad_control/vehicle_dynamics/dynamic_bicycle/dynamic_bicycle.py): `commonroad_control/vehicle_dynamics/dynamic_bicycle/dynamic_bicycle.py`
- [Kinematic bicycle](https://github.com/commonroad/commonroad-control/blob/develop/commonroad_control/vehicle_dynamics/kinematic_bicycle/kinematic_bicycle.py): `commonroad_control/vehicle_dynamics/kinematic_bicycle/kinematic_bicycle.py`
- [Dynamic bicycle factory](https://github.com/commonroad/commonroad-control/blob/develop/commonroad_control/vehicle_dynamics/dynamic_bicycle/db_sidt_factory.py): `commonroad_control/vehicle_dynamics/dynamic_bicycle/db_sidt_factory.py`
- [Kinematic bicycle factory](https://github.com/commonroad/commonroad-control/blob/develop/commonroad_control/vehicle_dynamics/kinematic_bicycle/kb_sidt_factory.py): `commonroad_control/vehicle_dynamics/kinematic_bicycle/kb_sidt_factory.py`
- [Trajectory representation](https://github.com/commonroad/commonroad-control/blob/develop/commonroad_control/vehicle_dynamics/trajectory_interface.py): `commonroad_control/vehicle_dynamics/trajectory_interface.py`
- [Vehicle parameters](https://github.com/commonroad/commonroad-control/blob/develop/commonroad_control/vehicle_parameters/vehicle_parameters.py): `commonroad_control/vehicle_parameters/vehicle_parameters.py`

### Utilities and Visualization

- [Curvilinear utilities](https://github.com/commonroad/commonroad-control/blob/develop/commonroad_control/util/clcs_control_util.py): `commonroad_control/util/clcs_control_util.py`
- [State conversion](https://github.com/commonroad/commonroad-control/blob/develop/commonroad_control/util/conversion_util.py): `commonroad_control/util/conversion_util.py`
- [Control visualization](https://github.com/commonroad/commonroad-control/blob/develop/commonroad_control/util/visualization/visualize_control_state.py): `commonroad_control/util/visualization/visualize_control_state.py`
- [Trajectory visualization](https://github.com/commonroad/commonroad-control/blob/develop/commonroad_control/util/visualization/visualize_trajectories.py): `commonroad_control/util/visualization/visualize_trajectories.py`

### Other components

- **Motion planner**

## Connections

- Motion planner → MPC planner API: provides plan
- Motion planner → PID planner API: provides plan
- MPC planner API → Reactive planner converter: uses converter (evidence: `commonroad_control/cr_control_easy_api/mpc_for_dedicated_planner.py`)
- Reactive planner converter → State conversion: converts states (evidence: `commonroad_control/planning_converter/reactive_planner_converter.py`)
- Reactive planner converter → Dynamic bicycle factory: builds trajectories (evidence: `commonroad_control/planning_converter/reactive_planner_converter.py`)
- Reactive planner converter → Kinematic bicycle factory: builds trajectories (evidence: `commonroad_control/planning_converter/reactive_planner_converter.py`)
- MPC planner API → Reference trajectory: builds reference (evidence: `commonroad_control/cr_control_easy_api/mpc_for_dedicated_planner.py`)
- MPC planner API → MPC controllers: invokes controller (evidence: `commonroad_control/cr_control_easy_api/mpc_for_dedicated_planner.py`)
- PID planner API → PID controllers: invokes controller (evidence: `commonroad_control/cr_control_easy_api/pid_for_dedicated_planner.py`)
- MPC planner API → Dynamic simulation: simulates motion (evidence: `commonroad_control/cr_control_easy_api/mpc_for_dedicated_planner.py`)
- Dynamic simulation → Vehicle model interface: advances dynamics (evidence: `commonroad_control/simulation/simulation/simulation.py`)
- Dynamic simulation → Sensor models: requests measurements (evidence: `commonroad_control/simulation/simulation/simulation.py`)
- Dynamic simulation → Uncertainty models: samples disturbance (evidence: `commonroad_control/simulation/simulation/simulation.py`)
- Dynamic simulation → Full-state feedback: defaults sensor (evidence: `commonroad_control/simulation/simulation/simulation.py`)
- Full-state feedback → Sensor models: implements interface (evidence: `commonroad_control/simulation/sensor_models/full_state_feedback/full_state_feedback.py`)
- Dynamic bicycle → Vehicle model interface: implements model (evidence: `commonroad_control/vehicle_dynamics/dynamic_bicycle/dynamic_bicycle.py`)
- Kinematic bicycle → Vehicle model interface: implements model
- Dynamic bicycle factory → Trajectory representation: creates trajectories (evidence: `commonroad_control/vehicle_dynamics/dynamic_bicycle/db_sidt_factory.py`)
- Kinematic bicycle factory → Trajectory representation: creates trajectories (evidence: `commonroad_control/vehicle_dynamics/kinematic_bicycle/kb_sidt_factory.py`)
- Vehicle model interface → Vehicle parameters: uses parameters (evidence: `commonroad_control/vehicle_dynamics/vehicle_model_interface.py`)
- Reference trajectory → Trajectory representation: creates reference data (evidence: `commonroad_control/control/reference_trajectory_factory.py`)
- MPC planner API → Curvilinear utilities: extends reference (evidence: `commonroad_control/cr_control_easy_api/mpc_for_dedicated_planner.py`)
- MPC planner API → Control visualization: visualizes state (evidence: `commonroad_control/cr_control_easy_api/mpc_for_dedicated_planner.py`)
- MPC planner API → Trajectory visualization: visualizes trajectories (evidence: `commonroad_control/cr_control_easy_api/mpc_for_dedicated_planner.py`)