# learnsyslab/safe-control-gym architecture

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

- Interactive diagram: https://gitdiagram.com/learnsyslab/safe-control-gym
- Repository: https://github.com/learnsyslab/safe-control-gym

## Overview

safe-control-gym is a robotics benchmark and safe-learning control suite. A typical workflow configures a task and controller, constructs them through the registry, trains or runs the controller against a physics-based environment, and evaluates logged performance. The product also includes classical, MPC, and RL controller families; symbolic dynamics, constraints, and disturbances; and CBF/MPSC safety filters. Edges reflect the README, excerpts, and SOURCE INDEX references; some broader integrations are documented but their detailed runtime wiring was not sampled.

Main entry points: [`safe_control_gym/controllers`](https://github.com/learnsyslab/safe-control-gym/tree/main/safe_control_gym/controllers) (Controller families), [`safe_control_gym/experiments/train_rl_controller.py`](https://github.com/learnsyslab/safe-control-gym/blob/main/safe_control_gym/experiments/train_rl_controller.py) (RL training), [`safe_control_gym/envs/benchmark_env.py`](https://github.com/learnsyslab/safe-control-gym/blob/main/safe_control_gym/envs/benchmark_env.py) (Benchmark environment), [`safe_control_gym/envs/gym_pybullet_drones/quadrotor.py`](https://github.com/learnsyslab/safe-control-gym/blob/main/safe_control_gym/envs/gym_pybullet_drones/quadrotor.py) (Quadrotor task)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Experiment orchestration"]
  node_training["RL training"]
  node_experiment["Experiment runner<br/>[base_experiment.py]"]
  node_registry["Object registry<br/>[registration.py]"]
end

subgraph group_controllers["Control algorithms"]
  node_controller_base["Controller interface<br/>[base_controller.py]"]
  node_controller_families["Controller families"]
  node_lqr_utils["LQR utilities<br/>[lqr_utils.py]"]
  node_gp_utils["GP-MPC utilities<br/>[gp_utils.py]"]
  node_mpc_utils["MPC utilities<br/>[mpc_utils.py]"]
  node_ppo_utils["PPO utilities<br/>[ppo_utils.py]"]
end

subgraph group_environments["Robotics environments"]
  node_benchmark["Benchmark environment<br/>[benchmark_env.py]"]
  node_cartpole["CartPole task<br/>[cartpole.py]"]
  node_quadrotor["Quadrotor task<br/>[quadrotor.py]"]
  node_aviary["PyBullet dynamics<br/>[base_aviary.py]"]
  node_constraints["Safety constraints<br/>[constraints.py]"]
  node_disturbances["Disturbance models<br/>[disturbances.py]"]
  node_episode_stats["Episode statistics"]
end

subgraph group_safety["Safety filters"]
  node_safety_base["Safety filter interface"]
  node_cbf["CBF filters<br/>[cbf.py]"]
  node_cbf_nn["Neural CBF<br/>[cbf_nn.py]"]
  node_mpsc["MPSC filters<br/>[mpsc.py]"]
end

subgraph group_models["Models and utilities"]
  node_symbolic["Symbolic systems"]
  node_neural["Neural networks<br/>[neural_networks.py]"]
  node_normalization["Normalization<br/>[normalization.py]"]
  node_configuration["Configuration<br/>[configuration.py]"]
  node_logging["Logging<br/>[logging.py]"]
  node_metrics["Performance metrics"]
end

node_user(("Experiment user"))

node_user -->|"configures and starts"| node_training
node_training -->|"loads configuration"| node_configuration
node_training -->|"creates task and controller"| node_registry
node_training -.->|"calls learn"| node_controller_base
node_experiment -->|"uses performance metrics"| node_metrics
node_benchmark -->|"uses constraints"| node_constraints
node_benchmark -->|"uses disturbances"| node_disturbances
node_cartpole -->|"extends benchmark"| node_benchmark
node_cartpole -->|"uses constraints"| node_constraints
node_quadrotor -->|"extends benchmark"| node_benchmark
node_quadrotor -->|"uses constraints"| node_constraints
node_quadrotor -->|"uses dynamics base"| node_aviary
node_controller_families -.->|"implements interface"| node_controller_base
node_controller_families -.->|"includes LQR methods"| node_lqr_utils
node_controller_families -.->|"includes GP-MPC methods"| node_gp_utils
node_controller_families -.->|"includes MPC methods"| node_mpc_utils
node_controller_families -.->|"includes PPO methods"| node_ppo_utils
node_cbf -->|"implements filter interface"| node_safety_base
node_cbf_nn -->|"builds on CBF"| node_cbf
node_cbf_nn -->|"uses neural networks"| node_neural
node_mpsc -->|"implements filter interface"| node_safety_base
node_mpsc -->|"uses MPC utilities"| node_mpc_utils
node_benchmark -.->|"provides symbolic models"| node_symbolic
node_training -.->|"writes training logs"| node_logging

click node_training "https://github.com/learnsyslab/safe-control-gym/blob/main/safe_control_gym/experiments/train_rl_controller.py"
click node_experiment "https://github.com/learnsyslab/safe-control-gym/blob/main/safe_control_gym/experiments/base_experiment.py"
click node_registry "https://github.com/learnsyslab/safe-control-gym/blob/main/safe_control_gym/utils/registration.py"
click node_controller_base "https://github.com/learnsyslab/safe-control-gym/blob/main/safe_control_gym/controllers/base_controller.py"
click node_controller_families "https://github.com/learnsyslab/safe-control-gym/tree/main/safe_control_gym/controllers"
click node_lqr_utils "https://github.com/learnsyslab/safe-control-gym/blob/main/safe_control_gym/controllers/lqr/lqr_utils.py"
click node_gp_utils "https://github.com/learnsyslab/safe-control-gym/blob/main/safe_control_gym/controllers/mpc/gp_utils.py"
click node_mpc_utils "https://github.com/learnsyslab/safe-control-gym/blob/main/safe_control_gym/controllers/mpc/mpc_utils.py"
click node_ppo_utils "https://github.com/learnsyslab/safe-control-gym/blob/main/safe_control_gym/controllers/ppo/ppo_utils.py"
click node_benchmark "https://github.com/learnsyslab/safe-control-gym/blob/main/safe_control_gym/envs/benchmark_env.py"
click node_cartpole "https://github.com/learnsyslab/safe-control-gym/blob/main/safe_control_gym/envs/gym_control/cartpole.py"
click node_quadrotor "https://github.com/learnsyslab/safe-control-gym/blob/main/safe_control_gym/envs/gym_pybullet_drones/quadrotor.py"
click node_aviary "https://github.com/learnsyslab/safe-control-gym/blob/main/safe_control_gym/envs/gym_pybullet_drones/base_aviary.py"
click node_constraints "https://github.com/learnsyslab/safe-control-gym/blob/main/safe_control_gym/envs/constraints.py"
click node_disturbances "https://github.com/learnsyslab/safe-control-gym/blob/main/safe_control_gym/envs/disturbances.py"
click node_episode_stats "https://github.com/learnsyslab/safe-control-gym/blob/main/safe_control_gym/envs/env_wrappers/record_episode_statistics.py"
click node_safety_base "https://github.com/learnsyslab/safe-control-gym/blob/main/safe_control_gym/safety_filters/base_safety_filter.py"
click node_cbf "https://github.com/learnsyslab/safe-control-gym/blob/main/safe_control_gym/safety_filters/cbf/cbf.py"
click node_cbf_nn "https://github.com/learnsyslab/safe-control-gym/blob/main/safe_control_gym/safety_filters/cbf/cbf_nn.py"
click node_mpsc "https://github.com/learnsyslab/safe-control-gym/blob/main/safe_control_gym/safety_filters/mpsc/mpsc.py"
click node_symbolic "https://github.com/learnsyslab/safe-control-gym/blob/main/safe_control_gym/math_and_models/symbolic_systems.py"
click node_neural "https://github.com/learnsyslab/safe-control-gym/blob/main/safe_control_gym/math_and_models/neural_networks.py"
click node_normalization "https://github.com/learnsyslab/safe-control-gym/blob/main/safe_control_gym/math_and_models/normalization.py"
click node_configuration "https://github.com/learnsyslab/safe-control-gym/blob/main/safe_control_gym/utils/configuration.py"
click node_logging "https://github.com/learnsyslab/safe-control-gym/blob/main/safe_control_gym/utils/logging.py"
click node_metrics "https://github.com/learnsyslab/safe-control-gym/blob/main/safe_control_gym/math_and_models/metrics/performance_metrics.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_training,node_experiment,node_registry,node_user toneBlue
class node_controller_base,node_controller_families,node_lqr_utils,node_gp_utils,node_mpc_utils,node_ppo_utils toneAmber
class node_benchmark,node_cartpole,node_quadrotor,node_aviary,node_constraints,node_disturbances,node_episode_stats toneMint
class node_safety_base,node_cbf,node_cbf_nn,node_mpsc toneRose
class node_symbolic,node_neural,node_normalization,node_configuration,node_logging,node_metrics toneIndigo
```

## Components

### Experiment orchestration

- [RL training](https://github.com/learnsyslab/safe-control-gym/blob/main/safe_control_gym/experiments/train_rl_controller.py): `safe_control_gym/experiments/train_rl_controller.py`
- [Experiment runner](https://github.com/learnsyslab/safe-control-gym/blob/main/safe_control_gym/experiments/base_experiment.py): `safe_control_gym/experiments/base_experiment.py`
- [Object registry](https://github.com/learnsyslab/safe-control-gym/blob/main/safe_control_gym/utils/registration.py): `safe_control_gym/utils/registration.py`

### Control algorithms

- [Controller interface](https://github.com/learnsyslab/safe-control-gym/blob/main/safe_control_gym/controllers/base_controller.py): `safe_control_gym/controllers/base_controller.py`
- [Controller families](https://github.com/learnsyslab/safe-control-gym/tree/main/safe_control_gym/controllers): `safe_control_gym/controllers`
- [LQR utilities](https://github.com/learnsyslab/safe-control-gym/blob/main/safe_control_gym/controllers/lqr/lqr_utils.py): `safe_control_gym/controllers/lqr/lqr_utils.py`
- [GP-MPC utilities](https://github.com/learnsyslab/safe-control-gym/blob/main/safe_control_gym/controllers/mpc/gp_utils.py): `safe_control_gym/controllers/mpc/gp_utils.py`
- [MPC utilities](https://github.com/learnsyslab/safe-control-gym/blob/main/safe_control_gym/controllers/mpc/mpc_utils.py): `safe_control_gym/controllers/mpc/mpc_utils.py`
- [PPO utilities](https://github.com/learnsyslab/safe-control-gym/blob/main/safe_control_gym/controllers/ppo/ppo_utils.py): `safe_control_gym/controllers/ppo/ppo_utils.py`

### Robotics environments

- [Benchmark environment](https://github.com/learnsyslab/safe-control-gym/blob/main/safe_control_gym/envs/benchmark_env.py): `safe_control_gym/envs/benchmark_env.py`
- [CartPole task](https://github.com/learnsyslab/safe-control-gym/blob/main/safe_control_gym/envs/gym_control/cartpole.py): `safe_control_gym/envs/gym_control/cartpole.py`
- [Quadrotor task](https://github.com/learnsyslab/safe-control-gym/blob/main/safe_control_gym/envs/gym_pybullet_drones/quadrotor.py): `safe_control_gym/envs/gym_pybullet_drones/quadrotor.py`
- [PyBullet dynamics](https://github.com/learnsyslab/safe-control-gym/blob/main/safe_control_gym/envs/gym_pybullet_drones/base_aviary.py): `safe_control_gym/envs/gym_pybullet_drones/base_aviary.py`
- [Safety constraints](https://github.com/learnsyslab/safe-control-gym/blob/main/safe_control_gym/envs/constraints.py): `safe_control_gym/envs/constraints.py`
- [Disturbance models](https://github.com/learnsyslab/safe-control-gym/blob/main/safe_control_gym/envs/disturbances.py): `safe_control_gym/envs/disturbances.py`
- [Episode statistics](https://github.com/learnsyslab/safe-control-gym/blob/main/safe_control_gym/envs/env_wrappers/record_episode_statistics.py): `safe_control_gym/envs/env_wrappers/record_episode_statistics.py`

### Safety filters

- [Safety filter interface](https://github.com/learnsyslab/safe-control-gym/blob/main/safe_control_gym/safety_filters/base_safety_filter.py): `safe_control_gym/safety_filters/base_safety_filter.py`
- [CBF filters](https://github.com/learnsyslab/safe-control-gym/blob/main/safe_control_gym/safety_filters/cbf/cbf.py): `safe_control_gym/safety_filters/cbf/cbf.py`
- [Neural CBF](https://github.com/learnsyslab/safe-control-gym/blob/main/safe_control_gym/safety_filters/cbf/cbf_nn.py): `safe_control_gym/safety_filters/cbf/cbf_nn.py`
- [MPSC filters](https://github.com/learnsyslab/safe-control-gym/blob/main/safe_control_gym/safety_filters/mpsc/mpsc.py): `safe_control_gym/safety_filters/mpsc/mpsc.py`

### Models and utilities

- [Symbolic systems](https://github.com/learnsyslab/safe-control-gym/blob/main/safe_control_gym/math_and_models/symbolic_systems.py): `safe_control_gym/math_and_models/symbolic_systems.py`
- [Neural networks](https://github.com/learnsyslab/safe-control-gym/blob/main/safe_control_gym/math_and_models/neural_networks.py): `safe_control_gym/math_and_models/neural_networks.py`
- [Normalization](https://github.com/learnsyslab/safe-control-gym/blob/main/safe_control_gym/math_and_models/normalization.py): `safe_control_gym/math_and_models/normalization.py`
- [Configuration](https://github.com/learnsyslab/safe-control-gym/blob/main/safe_control_gym/utils/configuration.py): `safe_control_gym/utils/configuration.py`
- [Logging](https://github.com/learnsyslab/safe-control-gym/blob/main/safe_control_gym/utils/logging.py): `safe_control_gym/utils/logging.py`
- [Performance metrics](https://github.com/learnsyslab/safe-control-gym/blob/main/safe_control_gym/math_and_models/metrics/performance_metrics.py): `safe_control_gym/math_and_models/metrics/performance_metrics.py`

### Other components

- **Experiment user**

## Connections

- Experiment user → RL training: configures and starts (evidence: `safe_control_gym/experiments/train_rl_controller.py`)
- RL training → Configuration: loads configuration (evidence: `safe_control_gym/experiments/train_rl_controller.py`)
- RL training → Object registry: creates task and controller (evidence: `safe_control_gym/experiments/train_rl_controller.py`)
- RL training → Controller interface: calls learn
- Experiment runner → Performance metrics: uses performance metrics (evidence: `safe_control_gym/experiments/base_experiment.py`)
- Benchmark environment → Safety constraints: uses constraints (evidence: `safe_control_gym/envs/benchmark_env.py`)
- Benchmark environment → Disturbance models: uses disturbances (evidence: `safe_control_gym/envs/benchmark_env.py`)
- CartPole task → Benchmark environment: extends benchmark (evidence: `safe_control_gym/envs/gym_control/cartpole.py`)
- CartPole task → Safety constraints: uses constraints (evidence: `safe_control_gym/envs/gym_control/cartpole.py`)
- Quadrotor task → Benchmark environment: extends benchmark (evidence: `safe_control_gym/envs/gym_pybullet_drones/quadrotor.py`)
- Quadrotor task → Safety constraints: uses constraints (evidence: `safe_control_gym/envs/gym_pybullet_drones/quadrotor.py`)
- Quadrotor task → PyBullet dynamics: uses dynamics base (evidence: `safe_control_gym/envs/gym_pybullet_drones/quadrotor.py`)
- Controller families → Controller interface: implements interface (evidence: `safe_control_gym/controllers/safe_explorer/safe_ppo.py`)
- Controller families → LQR utilities: includes LQR methods (evidence: `safe_control_gym/controllers/mpc/gp_mpc.py`)
- Controller families → GP-MPC utilities: includes GP-MPC methods (evidence: `safe_control_gym/controllers/mpc/gp_mpc.py`)
- Controller families → MPC utilities: includes MPC methods (evidence: `safe_control_gym/controllers/mpc/gp_mpc.py`)
- Controller families → PPO utilities: includes PPO methods (evidence: `safe_control_gym/controllers/safe_explorer/safe_ppo.py`)
- CBF filters → Safety filter interface: implements filter interface (evidence: `safe_control_gym/safety_filters/cbf/cbf.py`)
- Neural CBF → CBF filters: builds on CBF (evidence: `safe_control_gym/safety_filters/cbf/cbf_nn.py`)
- Neural CBF → Neural networks: uses neural networks (evidence: `safe_control_gym/safety_filters/cbf/cbf_nn.py`)
- MPSC filters → Safety filter interface: implements filter interface (evidence: `safe_control_gym/safety_filters/mpsc/mpsc.py`)
- MPSC filters → MPC utilities: uses MPC utilities (evidence: `safe_control_gym/safety_filters/mpsc/mpsc.py`)
- Benchmark environment → Symbolic systems: provides symbolic models
- RL training → Logging: writes training logs
