-
Notifications
You must be signed in to change notification settings - Fork 5
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
322 changed files
with
208,716 additions
and
12,874 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,54 @@ | ||
FROM ros:humble-ros-base-jammy | ||
|
||
# Set environment variables to avoid interactive prompts during installation and optimize Python environment | ||
ENV DEBIAN_FRONTEND=noninteractive \ | ||
PYTHONFAULTHANDLER=1 \ | ||
PYTHONUNBUFFERED=1 \ | ||
PYTHONHASHSEED=random \ | ||
PIP_NO_CACHE_DIR=off \ | ||
PIP_DISABLE_PIP_VERSION_CHECK=on \ | ||
PIP_DEFAULT_TIMEOUT=100 \ | ||
POETRY_HOME='/root/.local/bin' \ | ||
POETRY_NO_INTERACTION=1 \ | ||
POETRY_VIRTUALENVS_CREATE=false \ | ||
YOUR_ENV=default_value \ | ||
PATH="/root/.local/bin:${PATH}" | ||
|
||
# Version pinning as ARGs for easier updates | ||
ARG PYTHON_VERSION=3.10 | ||
ARG POETRY_VERSION=1.7.1 | ||
|
||
# Update the package list, install necessary packages in one layer, including Python 3.10, CMake, BLAS libraries, and clean up | ||
RUN apt-get update && apt-get upgrade -y && apt-get install -y \ | ||
make \ | ||
build-essential \ | ||
software-properties-common \ | ||
curl \ | ||
ssh \ | ||
git \ | ||
python3-pip \ | ||
python3-dev \ | ||
libopenblas-dev \ | ||
&& add-apt-repository -y ppa:deadsnakes/ppa \ | ||
&& apt-get install -y python3.10 python3.10-dev python3.10-venv \ | ||
&& apt-get clean \ | ||
&& rm -rf /var/lib/apt/lists/* \ | ||
&& update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.10 1 | ||
|
||
# Install Poetry using pip and pin the version | ||
RUN python3.10 -m pip install poetry==$POETRY_VERSION | ||
|
||
# Expose the port that Jupyter Notebook will run on | ||
EXPOSE 8888 | ||
|
||
WORKDIR /home/cbfkit_internal | ||
|
||
# Copy the project files | ||
COPY pyproject.toml poetry.lock ./ | ||
|
||
# Set the PYTHONPATH to include /home and project directories | ||
ENV PYTHONPATH="/home:/home/cbfkit_internal:/home/cbfkit_internal/src:${PYTHONPATH}" | ||
|
||
# Project initialization and conditionally install cvxopt if on x86 architecture | ||
RUN poetry install --no-interaction && \ | ||
if [ "$(uname -m)" = "x86_64" ]; then poetry add cvxopt; fi |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1 +1,28 @@ | ||
TBD | ||
BSD 3-Clause License | ||
|
||
Copyright (c) 2023, TMNA | ||
|
||
Redistribution and use in source and binary forms, with or without | ||
modification, are permitted provided that the following conditions are met: | ||
|
||
1. Redistributions of source code must retain the above copyright notice, this | ||
list of conditions and the following disclaimer. | ||
|
||
2. Redistributions in binary form must reproduce the above copyright notice, | ||
this list of conditions and the following disclaimer in the documentation | ||
and/or other materials provided with the distribution. | ||
|
||
3. Neither the name of the copyright holder nor the names of its | ||
contributors may be used to endorse or promote products derived from | ||
this software without specific prior written permission. | ||
|
||
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" | ||
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | ||
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE | ||
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE | ||
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | ||
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR | ||
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER | ||
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, | ||
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE | ||
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,31 +1,118 @@ | ||
# CBFKit | ||
# CBFKit: A Control Barrier Function Toolbox for Robotics Applications | ||
|
||
A Control Barrier Function Toolbox for Robotics Applications. | ||
CBFKit is a Python/ROS2 toolbox designed to facilitate safe planning and control for robotics applications, particularly in uncertain environments. The toolbox utilizes Control Barrier Functions (CBFs) to provide formal safety guarantees while offering flexibility and ease of use. | ||
|
||
## Description | ||
## Table of Contents | ||
- [Key Features](#key-features) | ||
- [Supported Models](#supported-models) | ||
- [Applications](#applications) | ||
- [Installation](#installation) | ||
- [Tutorials](#tutorials) | ||
- [ROS2](#ros2) | ||
- [Citing CBFKit](#citing-cbfkit) | ||
- [Contributing](#contributing) | ||
- [License](#license) | ||
- [Contact](#contact) | ||
|
||
CBFKit is a Python toolbox for control barrier functions (CBFs) for robotics applications. The toolbox includes functions for synthesizing controllers that satisfy the CBF conditions. | ||
## Key Features | ||
- **Generalized Framework:** Supports the design of CBFs for various robotic systems operating in both deterministic and stochastic settings. | ||
- **ROS Integration:** Seamlessly connects with ROS2, enabling multi-robot applications, environment and map encoding, and integration with motion planning algorithms. | ||
- **Diverse CBF Options:** Provides a variety of CBF formulations and algorithms to address different control scenarios. | ||
- **Model-based and Model-free Control:** Accommodates both model-based control strategies using system dynamics and model-free control approaches. | ||
- **Safety Guarantee:** CBFs provide mathematically rigorous guarantees of safety by ensuring the system remains within a defined safe operating region. | ||
- **Flexibility:** Allows users to specify custom safety constraints and barrier functions to tailor the control behavior to specific needs. | ||
- **Efficiency:** Leverages JAX for efficient automatic differentiation and jaxopt for fast quadratic program (QP) solving, enabling real-time control applications. | ||
- **Code Generation:** Simplifies model creation with automatic code generation for dynamics, controllers, and certificate functions. | ||
- **Usability:** Includes tutorials and examples for a smooth learning curve and rapid prototyping. | ||
|
||
## Installation | ||
## Supported Models | ||
CBFKit accommodates a range of control-affine system models: | ||
- **Deterministic Continuous-time ODEs:** $\dot{x} = f(x) + g(x)u$ | ||
- **ODEs with Bounded Disturbances:** $\dot{x} = f(x) + g(x)u + Mw$ | ||
- **Stochastic Differential Equations (SDEs):** $dx = (f(x) + g(x)u)dt + \sigma(x)dw$ | ||
|
||
To install CBFKit, you need to have Python 3.8 or later installed on your system. Then, run the following command in the root directory of the repository: | ||
## Applications | ||
CBFKit can be applied to diverse robotics applications, including: | ||
- **Autonomous Navigation:** Ensure collision avoidance with static and dynamic obstacles. | ||
- **Human-Robot Interaction:** Guarantee safety during collaborative tasks and physical interaction. | ||
- **Manipulation:** Control robot arms while avoiding obstacles and joint limits. | ||
- **Multi-Robot Coordination:** Coordinate the movement of multiple robots while maintaining safe distances and avoiding collisions. | ||
|
||
```bash | ||
poetry install | ||
``` | ||
## Installation | ||
CBFKit is readily deployable via a Docker image. After setting up Docker (refer to the [official Docker documentation](https://docs.docker.com/get-started/) for detailed instructions), proceed with one of the following methods: | ||
|
||
## Usage | ||
### 1. VS Code DevContainer Launch | ||
1. Open the project in VS Code. | ||
2. Click the green button at the bottom right of the window to launch the DevContainer. | ||
3. All necessary components are pre-installed for immediate use. | ||
|
||
To use CBFKit in your Python code, simply import it as follows: | ||
### 2. Docker Command Line | ||
1. Build the image: | ||
``` | ||
docker build -t cbfkit:latest -f Dockerfile.$(uname -m) . | ||
``` | ||
2. Run the container: | ||
``` | ||
docker run -it --name container-name -v .:/workspace cbfkit:latest | ||
``` | ||
|
||
```python | ||
import cbfkit | ||
## Tutorials | ||
Explore the `tutorials` directory to help you get started with CBFKit. Open the Python notebook in the `tutorials` directory to get started. The script `simulate_new_control_system.ipynb` automatically generates the controller, plant, and certificate function for a Van der Pol oscillator. It also generates ROS2 nodes for the plant, controller, sensor, and estimator. These serve as a starting point for developing your own CBF-based controller. | ||
|
||
Generated files/folders: | ||
``` | ||
van_der_pol_oscillator | ||
┣ certificate_functions | ||
┃ ┣ barrier_functions | ||
┃ ┃ ┣ __init__.py | ||
┃ ┃ ┣ barrier_1.py | ||
┃ ┃ ┗ barrier_2.py | ||
┃ ┣ lyapunov_functions | ||
┃ ┃ ┣ __init__.py | ||
┃ ┃ ┗ lyapunov_1.py | ||
┃ ┗ __init__.py | ||
┣ controllers | ||
┃ ┣ __init__.py | ||
┃ ┣ controller_1.py | ||
┃ ┗ zero_controller.py | ||
┣ ros2 | ||
┃ ┣ __init__.py | ||
┃ ┣ config.py | ||
┃ ┣ controller.py | ||
┃ ┣ estimator.py | ||
┃ ┣ plant_model.py | ||
┃ ┗ sensor.py | ||
┣ __init__.py | ||
┣ constants.py | ||
┣ plant.py | ||
┗ run_ros2_nodes.sh | ||
``` | ||
|
||
## Tutorials | ||
## ROS2 | ||
The ROS2 nodes are generated in the `ros2` directory. The nodes are generated for the plant, controller, sensor, and estimator. | ||
|
||
To run the nodes, execute the following command in the `van_der_pol_oscillator` directory: | ||
```bash | ||
bash run_ros2_nodes.sh | ||
``` | ||
The generated nodes interact as follows: | ||
- The `plant_model` node simulates the physical system and publishes the system state. | ||
- The `sensor` node receives the system state and adds noise to simulate real-world measurements. | ||
- The `estimator` node receives the noisy measurements and estimates the true system state. | ||
- The `controller` node receives the estimated state and computes the control input based on the CBF formulation. | ||
|
||
To run the tutorials, please see the `tutorials` directory. | ||
## Citing CBFKit | ||
If you use CBFKit in your research, please cite the following paper: | ||
```bibtex | ||
@misc{black2024cbfkit, | ||
title={CBFKIT: A Control Barrier Function Toolbox for Robotics Applications}, | ||
author={Mitchell Black and Georgios Fainekos and Bardh Hoxha and Hideki Okamoto and Danil Prokhorov}, | ||
year={2024}, | ||
eprint={2404.07158}, | ||
archivePrefix={arXiv}, | ||
primaryClass={cs.RO} | ||
} | ||
``` | ||
|
||
## License | ||
|
||
CBFKit is licensed under the MIT license. See the `LICENSE` file for more information. | ||
CBFKit is distributed under the BSD 3-Clause License. Refer to the `LICENSE` file for detailed terms. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,22 @@ | ||
The following is the template for module-level docstrings: | ||
|
||
""" | ||
title | ||
================ | ||
|
||
Description of module | ||
|
||
Functions | ||
--------- | ||
-function(a): description | ||
|
||
Notes | ||
----- | ||
Various notes here | ||
|
||
Examples | ||
-------- | ||
>>> import title | ||
>>> run code | ||
|
||
""" |
38 changes: 38 additions & 0 deletions
38
examples/fixed_wing/reach_drop_point/ra_fxt_clbf/barrier_functions.py
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,38 @@ | ||
""" | ||
Module docstring | ||
""" | ||
from typing import List | ||
from jax import Array | ||
from cbfkit.utils.user_types import BarrierTuple | ||
from cbfkit.models.fixed_wing_uav.certificate_functions.barrier_function_catalog import obstacle_ff | ||
|
||
|
||
# Future-Focused Obstacle Avoidance CBF | ||
def obstacle_ff_barriers( | ||
obstacles: List[Array], r_obs: List[float], tfuture: float | ||
) -> BarrierTuple: | ||
"""Generates Lyapunov functions, jacobians, hessians for use in CLF control law. | ||
Args: | ||
obstacles (List[Array]): list of obstacle (center of volume) locations | ||
r_obs (List[float]): list of obstacle radii | ||
tfuture (float): maximum lookahead time | ||
Returns: | ||
LyapunovTuple: all inforrmation needed for CLF constraint in QP | ||
""" | ||
barrier_functions = [] | ||
barrier_jacobians = [] | ||
barrier_hessians = [] | ||
barrier_times = [] | ||
for obstacle, r in zip(obstacles, r_obs): | ||
bf, bj, bh, bt = obstacle_ff(obstacle, r, tfuture) | ||
barrier_functions.append(bf) | ||
barrier_jacobians.append(bj) | ||
barrier_hessians.append(bh) | ||
barrier_times.append(bt) | ||
|
||
def funcs(): | ||
return barrier_functions, barrier_jacobians, barrier_hessians, barrier_times | ||
|
||
return funcs |
48 changes: 48 additions & 0 deletions
48
...es/fixed_wing/reach_drop_point/ra_fxt_clbf/ekf_state_estimation/fixed_wing_tutorial.ipynb
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,48 @@ | ||
{ | ||
"cells": [ | ||
{ | ||
"cell_type": "code", | ||
"execution_count": null, | ||
"id": "eab32af0-a3f0-4d5d-a905-1174204f99fa", | ||
"metadata": {}, | ||
"outputs": [], | ||
"source": [ | ||
"# Generic imports\n", | ||
"from typing import List\n", | ||
"import jax.numpy as jnp\n", | ||
"from jax import jacfwd, Array\n", | ||
"\n", | ||
"# CBFkit imports\n", | ||
"import cbfkit.simulation.simulator as sim\n", | ||
"import cbfkit.controllers.model_based.cbf_clf_controllers.cbf_clf_controllers as cbf_clf_controllers\n", | ||
"from cbfkit.controllers.model_based.cbf_clf_controllers.utils.ra_params import RiskAwareParams\n", | ||
"from cbfkit.controllers.utils.certificate_packager import concatenate_certificates\n", | ||
"from cbfkit.controllers.utils.lyapunov_conditions import fxt_s\n", | ||
"from cbfkit.sensors import unbiased_gaussian_noise as sensor\n", | ||
"from cbfkit.estimators import ct_ekf_dtmeas\n", | ||
"from cbfkit.integration import forward_euler as integrator" | ||
] | ||
} | ||
], | ||
"metadata": { | ||
"kernelspec": { | ||
"display_name": "Python 3 (ipykernel)", | ||
"language": "python", | ||
"name": "python3" | ||
}, | ||
"language_info": { | ||
"codemirror_mode": { | ||
"name": "ipython", | ||
"version": 3 | ||
}, | ||
"file_extension": ".py", | ||
"mimetype": "text/x-python", | ||
"name": "python", | ||
"nbconvert_exporter": "python", | ||
"pygments_lexer": "ipython3", | ||
"version": "3.8.10" | ||
} | ||
}, | ||
"nbformat": 4, | ||
"nbformat_minor": 5 | ||
} |
Oops, something went wrong.