{"id":23762083,"url":"https://github.com/tkkim-robot/online_adaptive_cbf","last_synced_at":"2025-09-05T06:31:45.076Z","repository":{"id":270427323,"uuid":"819154033","full_name":"tkkim-robot/online_adaptive_cbf","owner":"tkkim-robot","description":"Implementation of the Online Adaptive CBF for safety-critical navigation for input constrained systems.","archived":false,"fork":false,"pushed_at":"2025-08-18T21:04:06.000Z","size":2316,"stargazers_count":41,"open_issues_count":0,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-18T22:29:29.363Z","etag":null,"topics":["cbf","cbf-learning","control","mpc","navigation","obstacle-avoidance","robotics","safety-critical"],"latest_commit_sha":null,"homepage":"https://www.taekyung.me/online-adaptive-cbf","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tkkim-robot.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-06-23T23:43:02.000Z","updated_at":"2025-08-17T23:07:57.000Z","dependencies_parsed_at":"2024-12-31T04:33:59.864Z","dependency_job_id":"bff48fef-6672-4cee-b216-1a62073a126a","html_url":"https://github.com/tkkim-robot/online_adaptive_cbf","commit_stats":null,"previous_names":["tkkim-robot/online_adaptive_cbf"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/tkkim-robot/online_adaptive_cbf","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tkkim-robot%2Fonline_adaptive_cbf","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tkkim-robot%2Fonline_adaptive_cbf/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tkkim-robot%2Fonline_adaptive_cbf/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tkkim-robot%2Fonline_adaptive_cbf/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tkkim-robot","download_url":"https://codeload.github.com/tkkim-robot/online_adaptive_cbf/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tkkim-robot%2Fonline_adaptive_cbf/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273722717,"owners_count":25156300,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-05T02:00:09.113Z","response_time":402,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cbf","cbf-learning","control","mpc","navigation","obstacle-avoidance","robotics","safety-critical"],"created_at":"2024-12-31T21:16:21.511Z","updated_at":"2025-09-05T06:31:45.061Z","avatar_url":"https://github.com/tkkim-robot.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# online_adaptive_cbf\n\nThis repository contains the implementation of an online adaptive framework for Control Barrier Functions (CBFs) in input-constrained nonlinear systems. The algorithm dynamically adapts CBF parameters to optimize performance while ensuring safety, particularly for robotic navigation tasks. Please see our paper [\"Learning to Refine Input Constrained Control Barrier Functions via Uncertainty-Aware Online Parameter Adaptation\"]() for more details.\n\n\n\u003cdiv align=\"center\"\u003e\n\u003cimg src=\"https://github.com/user-attachments/assets/d047f394-008f-4eb2-9e79-3e2f7a074b47\" width=\"700px\"\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n[[Homepage]](https://www.taekyung.me/online-adaptive-cbf)\n[[Arxiv]](https://arxiv.org/abs/2409.14616)\n[[Video]](https://youtu.be/255IUS1f6Lo)\n[[Research Group]](https://dasc-lab.github.io/)\n\n\u003c/div\u003e\n\u003c/div\u003e\n\n\n## Features\n\n- Implementation of the Probabilistic Ensemble Neural Network ([PENN](https://github.com/tkkim-robot/online_adaptive_cbf/tree/main/nn_model/penn)) which offers parallelized inference without an outer for loop. The predicted output can be interpreted as a Gaussian Mixture Model (GMM). (see [Kim et al.](https://arxiv.org/abs/2305.12240))\n- Measurement of [closed-form epistemic uncertainty](https://github.com/tkkim-robot/online_adaptive_cbf/blob/main/nn_model/penn/divergence/utility.py) from the PENN model's predictions. (see [Kim et al.](https://arxiv.org/abs/2305.12240))\n- Integration with the [`safe_control`](https://github.com/tkkim-robot/safe_control) repository for simulating robotic navigation, offering various robot dynamics, controllers, and RGB-D type sensor simulation.\n- Implementation of the Online Adaptive ICCBF, adapting ICCBF parameters online based on the robot's current state and nearby environment.\n\n\n## Installation\nTo install this project, follow these steps:\n\n1. Clone the repository:\n   ```bash\n   git --recursive clone https://github.com/tkkim-robot/online_adaptive_cbf.git\n   cd online_adaptive_cbf\n   ```\n\n   If you've already cloned the repository without the --recursive flag, you can initialize and update the submodules with:\n   ```bash\n   submodule update --init --recursive\n   ```\n\n2. (Optional) Create and activate a virtual environment\n\n3. Install the package and its dependencies:\n   ```bash\n   python -m pip install -e .\n   ```\n   Or, install packages manually (see [`setup.py`](https://github.com/tkkim-robot/online_adaptive_cbf/blob/main/setup.py)).\n\n\n## Getting Started\n\nFamiliarize with APIs and examples with the scripts in [`online_adaptive_cbf.py`](https://github.com/tkkim-robot/online_adaptive_cbf/blob/main/online_adaptive_cbf.py)\n\n### Basic Example\nYou can run our test example by:\n\n```bash\npython online_adaptive_cbf.py\n```\n\nThe MPC-CBF framework is implemented in our [`safe_control`](https://github.com/tkkim-robot/safe_control) repository. It imports `LocalTrackingController` class and uses the `mpc_cbf` implementation:\n```python\nfrom safe_control.tracking import LocalTrackingController\ncontroller = LocalTrackingController(x_init, robot_spec,\n                                control_type='mpc_cbf')\n```\n\nThen, it uses `OnlineCBFAdapter` to adapt the CBF parameters online.\n\n```python\nonline_cbf_adapter = OnlineCBFAdapter(nn_model, scaler)\n\nfor _ in range(int(tf / self.dt)):\n   ret = controller.control_step()\n   controller.draw_plot()\n\n   best_gamma0, best_gamma1 = online_cbf_adapter.cbf_param_adaptation(controller)\n   controller.pos_controller.cbf_param['alpha1'] = best_gamma0\n   controller.pos_controller.cbf_param['alpha2'] = best_gamma1    \n```\n\nYou can also test with compared methods:\n\n- Fixed CBF parameters:\n   - `mpc_cbf` with conservatie fixed parameters: Set lower values to CBF parameters. (* MPC-CBF: An MPC controller using discrete-time CBF, ref: [[1]](https://ieeexplore.ieee.org/document/9483029))\n      ```python\n         controller.pos_controller.cbf_param['alpha1'] = {low value}\n         controller.pos_controller.cbf_param['alpha2'] = {low value}\n      ```\n   - `mpc_cbf` with aggressive fixed parameters: Similarly, set higher values to CBF parameters.\n- Adaptive parameter methods:\n   - `optimal_decay_cbf_qp`: A modified CBF-QP for point-wise feasibility guarantee (ref: [[2]](https://ieeexplore.ieee.org/document/9482626))\n      ```python\n      controller = LocalTrackingController(..., control_type='optimal_decay_cbf_qp')\n      ```\n   - `optimal_decay_mpc_cbf`: The same technique applied to MPC-CBF (ref: [[3]](https://ieeexplore.ieee.org/document/9683174))\n      ```python\n      controller = LocalTrackingController(..., control_type='optimal_decay_mpc_cbf')\n      ```\n\n\nThe sample results from the basic example:\n\n|     MPC-CBF w/ low parameters            |       MPC-CBF w/ high parameters     |\n| :------------------: | :--------------------------: |\n|  \u003cimg src=\"https://github.com/user-attachments/assets/6a67bf2d-0c0f-437f-8fc0-8d21511b9ab6\"  height=\"170px\"\u003e | \u003cimg src=\"https://github.com/user-attachments/assets/8151d102-6fbe-4a93-8967-7004c8e0b2cb\"  height=\"170px\"\u003e |\n\n|     Optimal Decay CBF-QP  |       Optimal Decay MPC-CBF    |\n| :---------------------: | :----------------------------: |\n|  \u003cimg src=\"https://github.com/user-attachments/assets/e43f72bc-475a-403d-bac8-41a077acdaf1\"  height=\"170px\"\u003e | \u003cimg src=\"https://github.com/user-attachments/assets/ae2ecb58-254b-4334-84d6-8c52508c9973\"  height=\"170px\"\u003e |\n\n\n|     Ours (Online Adaptive MPC-ICCBF)      |\n| :-------------------------------: |\n|  \u003cimg src=\"https://github.com/user-attachments/assets/5d5806c1-31a9-42fb-806f-04ece91d54ba\"  height=\"170px\"\u003e |\n\nThe green point is the goal location, and the gray circles are the obstacles that are known a priori.\n\n## Module Breakdown\n\n### Safety Loss Density Function\n\nThe [`safety loss density function`](https://github.com/tkkim-robot/online_adaptive_cbf/blob/main/safety_loss_function.py) is designed to quantify the collision risk between the robot and obstacles. This safety loss is computed based on the robot's state and the obstacles' locations.\n\n|    Mean Predicted Risk Level    |\n| :-------------------------------: |\n|  \u003cimg src=\"https://github.com/user-attachments/assets/9d8d2e21-ab83-4445-9cc4-de09029550b2\"  height=\"350px\"\u003e |\n\n### Data Generation\n\nYou can use [`data_generation.py`](https://github.com/tkkim-robot/online_adaptive_cbf/blob/main/data_generation.py) to collect training dataset. It will store `risk_level` and `deadlock_time` as the ground truth. \n\nThe `risk_level` refers to the maximum safety loss value recorded during the navigation (see the illustration below).\n\n|    Safety Loss during Navigation     |\n| :-------------------------------: |\n|  \u003cimg src=\"https://github.com/user-attachments/assets/591813c0-15e3-4857-8949-eef009a2697a\"  height=\"250px\"\u003e |\n\n\n### PENN Prediction\n\nTo train the PENN model, use the script [`penn/train_data.py`](https://github.com/tkkim-robot/online_adaptive_cbf/blob/main/nn_model/train_data.py). An example of the prediction results after training is shown below: \n\n|    Mean Predicted Risk Level    |\n| :-------------------------------: |\n|  \u003cimg src=\"https://github.com/user-attachments/assets/611dea04-93df-4635-97eb-34b93a5850ad\"  height=\"350px\"\u003e |\n\nYou can observe that the predicted risk level becomes higher as the CBF parameter increases, the distance to the obstacle decreases, the velocity increases, and the relative angle to the obstacle becomes smaller.\n\n### Distributionally Robust CVaR\n\n\u003cp align=\"left\"\u003e\n  \u003cimg src=\"https://github.com/user-attachments/assets/a55809d8-a027-4dfc-a215-eb92fe592d4f\" height=\"200px\"\u003e\n\u003c/p\u003e\n\nPlease refer to our repository [`cvar-gmm-filter`](https://github.com/signalkee/cvar-gmm-filter/tree/7405e05f7455f320b2c7b0ae72cef31a82d4a4f8) for more details.\n\n### Visualize Prediction Results for CBF Parameters of Interest\n\n[`test_plot.py`](https://github.com/tkkim-robot/online_adaptive_cbf/blob/main/test_plot.py) provides an online plotting tool to visualize the predicted GMM distribution of the candidate CBF parameters. Here is the example of visualizing the predicted `risk_level` with three candidates, without adapting the paremeters.\n\n\n|    Single Obstacle         |    Multiple Obstacles    |\n| :------------------: | :--------------------------: |\n|  \u003cimg src=\"https://github.com/user-attachments/assets/3a883e17-bda5-4719-a6ac-92104e0209ff\"  height=\"250px\"\u003e | \u003cimg src=\"https://github.com/user-attachments/assets/f62659bd-9d4d-4ff1-9b9b-9f24f0dd85c7\"  height=\"250px\"\u003e |\n\n\n\n## Citing\n\nIf you find this repository useful, please consider citing our paper:\n\n```\n@inproceedings{kim2025learning, \n    author    = {Kim, Taekyung and Kee, Robin Inho and Panagou, Dimitra},\n    title     = {Learning to Refine Input Constrained Control Barrier Functions via Uncertainty-Aware Online Parameter Adaptation}, \n    booktitle = {IEEE International Conference on Robotics and Automation (ICRA)},\n    shorttitle = {Online-Adaptive-CBF},\n    year      = {2025}\n}\n```\n\nOur paper with more theoretical analysis:\n```\n@inproceedings{kim2025learning, \n    author    = {Kim, Taekyung and Kee, Robin Inho and Panagou, Dimitra},\n    title     = {Learning to Refine Input Constrained Control Barrier Functions via Uncertainty-Aware Online Parameter Adaptation}, \n    booktitle = {IEEE International Conference on Robotics and Automation (ICRA)},\n    shorttitle = {Online-Adaptive-CBF},\n    year      = {2025}\n}\n```\n\n## Related Works\n\nHere are some related projects/codes that you might be interested:\n\n- [Visibility-Aware RRT*](https://github.com/tkkim-robot/visibility-rrt): Safety-critical Global Path Planning (GPP) using Visibility Control Barrier Functions\n\n- [UGV Experiments with ROS2](https://github.com/tkkim-robot/px4_ugv_exp): Environmental setup for rovers using PX4, ros2 humble, Vicon MoCap, and NVIDIA VSLAM + NvBlox\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftkkim-robot%2Fonline_adaptive_cbf","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftkkim-robot%2Fonline_adaptive_cbf","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftkkim-robot%2Fonline_adaptive_cbf/lists"}