Skip to content

Commit

Permalink
version 0.2.0
Browse files Browse the repository at this point in the history
  • Loading branch information
bardhh committed Apr 11, 2024
1 parent 3ab9543 commit cc15e3b
Show file tree
Hide file tree
Showing 322 changed files with 208,716 additions and 12,874 deletions.
54 changes: 54 additions & 0 deletions Dockerfile
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
29 changes: 28 additions & 1 deletion LICENSE
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.
121 changes: 104 additions & 17 deletions README.md
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.
22 changes: 22 additions & 0 deletions docs/docstring.txt
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

"""
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
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
}
Loading

0 comments on commit cc15e3b

Please sign in to comment.