# bardhh/cbfkit architecture

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

- Interactive diagram: https://gitdiagram.com/bardhh/cbfkit
- Repository: https://github.com/bardhh/cbfkit

## Overview

##### Project Type and Purpose
- CBFKit is an open‐source Python/ROS2 toolbox dedicated to safe control and planning for robotics applications via Control Barrier Functions (CBFs). It facilitates formal safety guarantees in uncertain and dynamic environments.
- The README highlights its use for both model‐based and model‐free control, simulation of multiple robotic systems (e.g., unicycle, fixed-wing, quadrotor), and seamless integration with ROS2 for multi-robot applications.

##### Main Architectural Components
a. Core Modules (Library and Functionality):
- “src/cbfkit” is the core of the project and contains functional modules such as:
- Controllers: Under “src/cbfkit/controllers/model_based” (with submodules for various CBF/CLF formulations and QP-based control laws).
- Estimators: Under “src/cbfkit/estimators” (including modules for EKF, UKF, and a naive estimator).
- Integration: Provides numerical integration methods (e.g., “forward_euler” and solve_ivp) used to simulate dynamics.
- Modeling: Contains system modeling capabilities and neural network support.
- Optimization: Houses components for solving quadratic programs via multiple solvers (e.g., Casadi, CVXOPT, jaxopt).
- Systems: Contains definitions for various robotic platforms (fixed-wing UAVs, non-linear 2D systems, unicycles, quadrotors, van der Pol, etc.). Each system folder holds dynamics, certificate functions (barrier and Lyapunov functions), and controllers.
- Code Generation: The “codegen” directory provides tools to automatically generate system models and related controller code.
- ROS/ROS2 Integration: Separate modules under “src/cbfkit/ros” and “src/cbfkit/ros2” encapsulate node implementations for controllers, sensors, dynamics, and experiments.
- Sensors: Provides modules for state sensing (e.g., “full_state” and perfect measurements).

b. Auxiliary Components:
- Examples: A rich set of executable examples in the “examples” directory demonstrating how to integrate and run simulations for various robotic models.
- Tutorials: Jupyter notebooks and Python scripts in the “tutorials” folder that not only document usage but also illustrate integrated workflows including automatic code generation and ROS2 node creation.
- Tests: Under the “tests” directory, numerous unit and integration tests ensure the robustness of controllers, simulators, and model generation.

##### Relationships and Interactions
- Data Flow Loop in Simulation/Control:
- The simulation loop typically starts with a plant/model (from the “systems” modules) representing the robot dynamics.
- A numerical integrator (from “integration”) updates the system state based on the control input.
- Sensors (from “sensors”, e.g., perfect measurements) feed the current state into an estimator (from “estimators”) if needed.
- The controller (from “controllers”) computes the control action by integrating safety constraints (via CBFs) and optimization routines (from “optimization”).
- This control input is then re-applied to the plant and the loop continues.
- ROS2 Integration:
- In ROS2 mode, separate nodes are auto-generated for the plant, sensor, estimator, and controller. These interact via ROS topics and services.
- The “ros2” module encapsulates the communication infrastructure and manages real-time data flows.
- Code Generation:
- The “codegen” module bridges user-defined system setups with the auto-generated models, controllers, and certificate function skeletons for rapid prototyping.
- Testing and Extensibility:
- The “tests” folder reinforces that interactions between modules (e.g., controllers with different QP solvers and integration steps) are validated.

##### Architectural Patterns and Design Principles
- Modular Design: Separation of concerns is evident—each submodule (controllers, estimators, systems, optimization, etc.) handles a specific aspect of robotics control.
- Functional Programming Principles: Data immutability and stateless operations are emphasized to help with determinism and easier unit testing.
- Reusability and Extensibility: The presence of a code generation layer and extensive examples/tutorials indicate that extensibility is a first-class principle.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Simulation Pipeline
    subgraph "Simulation Pipeline"
        sensor["\"Sensors\""]:::simulation
        estimator["\"Estimators\""]:::simulation
        controller["\"Controllers\""]:::control
        optimization["\"Optimization\""]:::control
        systems["\"Systems/Models\""]:::simulation
        integration["\"Numerical Integration\""]:::simulation
        modeling["\"Modeling\""]:::simulation
        codegen["\"Code Generation\""]:::simulation
    end

    sensor -->|"sensing_data"| estimator
    estimator -->|"state_estimate"| controller
    controller -->|"control_signal"| systems
    controller -->|"QP_solving"| optimization
    systems -->|"simulate_state"| integration
    integration -->|"feedback"| sensor
    modeling -->|"develop_models"| systems
    codegen -->|"generate_for"| controller
    codegen -->|"generate_for"| systems

    %% ROS2 Ecosystem
    subgraph "ROS2 Ecosystem"
        snode["\"Sensor Node\""]:::communication
        enode["\"Estimator Node\""]:::communication
        cnode["\"Controller Node\""]:::communication
        pnode["\"Plant Node\""]:::communication
    end

    snode -->|"publish_state"| enode
    enode -->|"compute_control"| cnode
    cnode -->|"send_command"| pnode
    pnode -->|"publish_state"| snode

    %% Legacy ROS Integration
    ros1["\"ROS Integration\""]:::communication

    %% Auxiliary Workflows
    subgraph "Auxiliary Workflows"
        ex["\"Examples\""]:::auxiliary
        tut["\"Tutorials\""]:::auxiliary
        tst["\"Tests\""]:::auxiliary
    end

    %% Interconnections between Simulation and ROS2 Ecosystem
    sensor ---|"ROS_data"| snode
    cnode ---|"control_feedback"| controller

    %% Click Events
    click controller "https://github.com/bardhh/cbfkit/tree/main/src/cbfkit/controllers/model_based"
    click estimator "https://github.com/bardhh/cbfkit/tree/main/src/cbfkit/estimators"
    click sensor "https://github.com/bardhh/cbfkit/tree/main/src/cbfkit/sensors"
    click integration "https://github.com/bardhh/cbfkit/tree/main/src/cbfkit/integration"
    click modeling "https://github.com/bardhh/cbfkit/tree/main/src/cbfkit/modeling"
    click optimization "https://github.com/bardhh/cbfkit/tree/main/src/cbfkit/optimization"
    click systems "https://github.com/bardhh/cbfkit/tree/main/src/cbfkit/systems"
    click codegen "https://github.com/bardhh/cbfkit/tree/main/src/cbfkit/codegen"
    click ros1 "https://github.com/bardhh/cbfkit/tree/main/src/cbfkit/ros"
    click snode "https://github.com/bardhh/cbfkit/tree/main/src/cbfkit/ros2"
    click ex "https://github.com/bardhh/cbfkit/tree/main/examples"
    click tut "https://github.com/bardhh/cbfkit/tree/main/tutorials"
    click tst "https://github.com/bardhh/cbfkit/tree/main/tests"

    %% Style Definitions
    classDef simulation fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef control fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef communication fill:#FFA500,stroke:#000,stroke-width:2px;
    classDef auxiliary fill:#DDA0DD,stroke:#000,stroke-width:2px;
```
