Metadata-Version: 2.4
Name: barrier-states-python
Version: 0.1.0
Summary: Barrier States for safety-embedded control and trajectory optimization in Python
Author: Hassan Almubarak
License-Expression: Apache-2.0
Project-URL: Repository, https://github.com/CORTx-Lab/barrier-states-python
Project-URL: Issues, https://github.com/CORTx-Lab/barrier-states-python/issues
Project-URL: MATLAB Toolbox, https://github.com/CORTx-Lab/barrier-states-matlab
Keywords: Barrier States,safety-critical control,safety-embedded control,nonlinear control,optimal control,trajectory optimization,robotics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=2.0
Requires-Dist: scipy>=1.13
Requires-Dist: control>=0.10.2
Requires-Dist: matplotlib>=3.9
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Dynamic: license-file

# Barrier States Python Library

<p align="center">
  <img
    src="docs/assets/readme/barrier_states_python_library_workflow_with_cortx_logo.svg"
    alt="Barrier States Python Library workflow"
    width="100%">
</p>

<p align="center">
  <b>A Python library for safe control using Barrier States (BaS) and safety-embedded systems.</b>
</p>

<p align="center">
  <a href="#installation"><img src="https://img.shields.io/badge/Python-%E2%89%A53.10-3776AB?logo=python&logoColor=white" alt="Python 3.10+"></a>
  <a href="#testing"><img src="https://img.shields.io/badge/tests-pytest-0A9EDC?logo=pytest&logoColor=white" alt="Tests"></a>
  <a href="#license"><img src="https://img.shields.io/badge/license-Apache--2.0-green" alt="Apache-2.0 License"></a>
  <a href="#status"><img src="https://img.shields.io/badge/status-active%20development-orange" alt="Status"></a>
</p>

---

## What is Barrier States-python?

This repository provides a modular Python implementation of Barrier States (BaS) for safety-critical control.

Rather than treating safety only as a constraint to be checked or enforced through an external safety filter, the Barrier States framework converts safety information into a dynamical state. The library constructs the Barrier State dynamics and embeds them with the original plant to form a safety-embedded system.

In this augmented model, safety is addressed through boundedness and regulation of the Barrier States while the controller or optimizer continues to pursue the original performance objective. This makes the framework compatible with classical feedback, nonlinear control, trajectory optimization, and receding-horizon control.

The library follows the complete BaS-based control workflow:

```text
plant modeling
    → safety constraints
    → barrier construction
    → Barrier State realization
    → safety embedding
    → controller or solver
    → simulation and visualization
```

The library is designed for:

- safe regulation and stabilization;
- obstacle avoidance;
- multi-agent safety;
- adaptive cruise control;
- safety-embedded optimal control and trajectory optimization;
- integration with LQR, PID-style control, SDRE, DDP/iLQR, and MPC;
- simulation, plotting, diagnostics, and animation;
- readable and reproducible BaS control workflows.

---

## Why Barrier States?

Many safety-critical control methods enforce constraints through pointwise barrier inequalities or online optimization filters. Barrier States take a different route: they **embed safety directly into the system dynamics**.

Consider the nonlinear control system

$$
\dot{x} = f(x,u),
$$

with the safe set

$$
\mathcal{S} = \lbrace x \in \mathcal{X} \mid h(x) > 0 \rbrace.
$$

The safety convention used throughout the library is

$$
h(x) > 0 \quad \text{safe}, \qquad
h(x) = 0 \quad \text{boundary}, \qquad
h(x) < 0 \quad \text{unsafe}.
$$

A barrier coordinate is constructed by applying a barrier operator $B$ to the safety function:

$$
\beta(x) = B(h(x)).
$$

The barrier is finite inside the safe set and becomes unbounded as the state approaches the safety boundary:

$$
\beta(x) \rightarrow \infty
\qquad \text{as} \qquad
h(x) \rightarrow 0^{+}.
$$

The built-in reciprocal and logarithmic barriers are

$$
B_{\mathrm{inv}}(h) = \frac{\alpha}{h},
\qquad
B_{\log}(h) = \alpha \ \log(\frac{1+h}{h}),
\qquad
\alpha > 0.
$$

### Barrier State realization

Rather than prescribing only an inequality for the rate of change of the barrier, BaS introduces a dynamical state $z$ that realizes the barrier behavior.

For stabilization about an equilibrium, let $\beta_0 = \beta(x_{\mathrm{eq}})$. A continuous-time Barrier State can be written as

$$
\dot{z} = f_{z}(x,z,u),
$$

where

$$
f_z(x,z,u)  = \bigl(B' \circ B^{-1}\bigr)(z+\beta_0)\, \nabla h(x)^\top f(x,u) - \gamma\bigl(z+\beta_0-\beta(x)\bigr),  \qquad \gamma>0.
$$

With the consistent initialization

$$
z(0)=\beta(x(0))-\beta_0,
$$

the Barrier State satisfies

$$
z(t)=\beta(x(t))-\beta_0.
$$

More generally, the correction term drives the Barrier State toward the shifted barrier coordinate. Under the assumptions of the BaS construction, boundedness of the Barrier State corresponds to boundedness of the barrier coordinate; because the barrier diverges at the safety boundary, bounded Barrier State evolution is the mechanism through which safety is encoded.

For multiple safety constraints, the library can construct either one aggregated Barrier State or a vector of Barrier States,

$$
z =
\begin{bmatrix}
z_1 & \cdots & z_{n_z}
\end{bmatrix}^{\!\top}.
$$

or construct one aggregated Barrier State, depending on the selected barrier aggregation.

### Safety-embedded dynamics

The Barrier State dynamics are augmented with the physical plant:

$$
\dot{x}=f(x,u),
$$

$$
\dot{z}=f_z(x,z,u).
$$

Defining the embedded state

$$ \bar{x} = \begin{bmatrix} x \\\\ z \end{bmatrix}, $$ 

the complete safety-embedded system becomes

$$ \dot{\bar{x}} = \bar{f}(\bar{x},u) = \begin{bmatrix} f(x,u) \\\\ f_{z}(x,z,u) \end{bmatrix}. $$ 

The controller is then designed for the augmented state,

$$
u = \pi(\bar{x}),
$$

so that the original performance objective is pursued while the Barrier States are regulated.

For discrete-time models, 

$$
x_{k+1}=F(x_k,u_k),
$$

the library follows the corresponding construction

$$
z_{k+1}=F_z(x_k,z_k,u_k),
$$

$$ \bar{x}_{k+1} = \bar{F}(\bar{x}_{k},u_{k}), \qquad \bar{x}_{k}= \begin{bmatrix} x_{k} \\\\ z_{k} \end{bmatrix}. $$

This formulation allows the same safety-embedding idea to be paired with several control and optimization methods, including:

- LQR-style state feedback;
- PID-style BaS feedback;
- SDRE feedback;
- DDP/iLQR trajectory optimization;
- DDP-based receding-horizon MPC;
- custom feedback policies.

> [!IMPORTANT]
> BaS is not a universal safety wrapper for an arbitrary controller. Safety conclusions depend on the assumptions of the selected Barrier State construction, safe initialization, numerical validity, and successful bounded regulation of the embedded safety dynamics. The resulting guarantees also depend on the chosen controller and its ability to regulate the nonlinear embedded system over the relevant region of operation.

For more detail, see [`docs/concepts.md`](docs/concepts.md).

---

## Feature highlights

| Area | Included |
|---|---|
| **Models** | Linear systems, double integrator, differential drive, cart-pole, planar quadrotor, 12-state quadrotor, multi-agent single integrators, and adaptive cruise control |
| **Constraints** | State limits, 2D and 3D obstacles, ACC time headway, multi-agent distance, and combined constraints |
| **Barriers** | Reciprocal and logarithmic operators with component-wise, harmonic, and barrier-sum constructions |
| **BaS realizations** | Continuous BaS, discrete BaS, shifted coordinates, vector or aggregated Barrier States, and SDC-aware continuous BaS |
| **Embedding** | Continuous and discrete safety-embedded models with analytical first-order derivatives |
| **Controllers** | Fixed state feedback, BaS-PID feedback, SDRE feedback, trajectory policies, and DDP-based MPC |
| **Costs** | Model-independent quadratic discrete-time trajectory costs |
| **Solvers** | Unified DDP-family solver with `method="ilqr"` or `method="ddp"`, regularization, line search, and optional control saturation |
| **Simulation** | Continuous and discrete closed-loop simulation, open-loop rollout, and prescribed ACC leader profiles |
| **Visualization** | 2D/3D trajectories, state/control/BaS histories, constraint histories, solver convergence, MPC predictions, DDP iterations, and GIF/MP4 animation |
| **Testing** | Unit and workflow tests across models, derivatives, constraints, barriers, embeddings, controllers, solvers, simulation, plotting, and animation |

---

## Example gallery

<table>
  <tr>
    <td width="50%" align="center" valign="top">
      <img
        src="./docs/assets/readme/differential_drive_ddp_iterations.gif"
        width="100%"
        alt="Differential-drive obstacle avoidance with BaS-DDP optimization iterations">
      <br>
      <b>Differential-drive obstacle avoidance — BaS-DDP</b>
    </td>
    <td width="50%" align="center" valign="top">
      <img
        src="./docs/assets/readme/quadrotor_3d_bas_ddp.gif"
        width="100%"
        alt="Three-dimensional quadrotor obstacle avoidance with BaS-DDP">
      <br>
      <b>3D quadrotor obstacle avoidance — BaS-DDP</b>
    </td>
  </tr>

  <tr>
    <td width="50%" align="center" valign="top">
      <img
        src="./docs/assets/readme/acc_pid_bas.gif"
        width="100%"
        alt="Adaptive cruise control with BaS-PID">
      <br>
      <b>Adaptive cruise control — BaS-PID</b>
    </td>
    <td width="50%" align="center" valign="top">
      <img
        src="./docs/assets/readme/double_integrator_bas_mpc.gif"
        width="100%"
        alt="Double-integrator safety-embedded MPC with Barrier States">
      <br>
      <b>Double integrator — BaS-MPC</b>
    </td>
  </tr>

  <tr>
    <td width="50%" align="center" valign="top">
      <img
        src="./docs/assets/readme/multiagent_bas_feedback.gif"
        width="100%"
        alt="Multi-agent safety with Barrier States feedback control">
      <br>
      <b>Multi-agent safety — BaS feedback</b>
    </td>
    <td width="50%" align="center" valign="top">
      <img
        src="./docs/assets/readme/cart_pole_swingup_bas_ddp.gif"
        width="100%"
        alt="Cart-pole swing-up with BaS-DDP">
      <br>
      <b>Cart-pole swing-up — BaS-DDP</b>
    </td>
  </tr>
</table>

<p align="center">
  <img
    src="./docs/assets/readme/multiagent_bas_feedback_min_distance.png"
    width="55%"
    alt="Minimum inter-agent distance during the multi-agent BaS feedback example">
</p>

<p align="center">
  <b>Multi-agent safety diagnostic — minimum inter-agent distance</b>
</p>

---

## Installation

Clone the repository and install from source:

```bash
git clone https://github.com/CORTx-Lab/Barrier States-python.git
cd Barrier States-python
python -m pip install -e .
```

For development and testing:

```bash
python -m pip install -e ".[dev]"
```

---

## Requirements

- Python 3.10 or newer
- NumPy
- SciPy
- python-control
- Matplotlib
- pytest for development

GIF export uses Matplotlib's Pillow writer. MP4 export additionally requires an FFmpeg installation available on the system path.

---

## Quick start

Run the shortest introductory example:

```bash
python examples/toy_linear_bas_lqr.py
```

Other representative examples:

```bash
python examples/adaptive_cruise_control_pid_bas.py
python examples/planar_quadrotor_bas_sdre.py
python examples/differential_drive_bas_ddp.py
python examples/double_integrator_bas_mpc.py
python examples/multiagent_single_integrator_bas_feedback.py
```

---

## Minimal BaS example

The following example shows a compact continuous-time BaS-LQR workflow. See the example scripts for complete runnable versions with diagnostics and visualization.

```python
import numpy as np
import control as ct

from barrier_states.barriers import reciprocal
from barrier_states.bas import DynamicContinuous
from barrier_states.constraints import obstacles_2d
from barrier_states.controllers import StateFeedback
from barrier_states.embedding import EmbeddedContinuous
from barrier_states.models import toy_linear_system
from barrier_states.simulation import simulate_continuous

# Plant
model = toy_linear_system()
x_ref = np.zeros(model.n)
u_ref = np.zeros(model.m)

# Safety constraint
constraint = obstacles_2d(centers=np.array([[2.0, 1.5]]), radii=np.array([0.5]), state_dim=model.n)

# Barrier
barrier = reciprocal(constraint, lpha=1.0, aggregate="none")

# Dynamic Barrier State
bas = DynamicContinuous(model, barrier, gamma=1.0, reference_state=x_ref)

# Safety embedding
embedded = EmbeddedContinuous(model, bas)

x0 = np.array([6.0, 4.5])
xbar0 = embedded.augment_state(x0)
xbar_ref = embedded.augment_state(x_ref)

# LQR design on the embedded linearization
A = embedded.flow_x(xbar_ref, u_ref)
B = embedded.flow_u(xbar_ref, u_ref)

Q = 0.5 * np.eye(embedded.n)
Q[embedded.physical_dim:, embedded.physical_dim:] = 10.0
R = 0.5 * np.eye(embedded.m)

K, _, _ = ct.lqr(A, B, Q, R)

controller = StateFeedback(embedded, np.asarray(K), reference_state=xbar_ref, reference_input=u_ref)

# Simulate
time = np.linspace(0.0, 5.0, 501)

simulation = simulate_continuous(embedded, controller, time, x0=xbar0)
```

---

## Documentation

Additional technical details are available in:

| Document | Purpose |
|---|---|
| [`Concepts`](docs/concepts.md) | BaS concepts, shifted coordinates, continuous/discrete realizations, safety embedding, SDRE, and MPC |
| [`Conventions`](docs/conventions.md) | Array shapes, model contracts, safety convention, derivatives, input bounds, plotting behavior, and feedback-gain signs |
| [`API reference`](docs/api_reference.md) | Compact package-by-package reference for the public API |
| [`Trajectory optimization`](docs/trajectory_optimization.md) | DDP/iLQR behavior, solution objects, solver diagnostics, trajectory policies, and DDP-based MPC |

The scripts under [`examples/`](examples/) provide complete runnable workflows.

---

## Important conventions

### Safety sign convention

All scalar safety functions use

```text
h(x) > 0   safe
h(x) = 0   boundary
h(x) < 0   unsafe
```

Safe initial and reference states must lie strictly inside the safe set.

### Feedback-gain sign convention

The library uses two feedback-gain sign conventions because designed controller gains and DDP/iLQR solver gains are defined differently.

Designed gains use the standard negative-feedback form:

$$ u = u_{\\mathrm{ref}} - K \\left( \\bar{x}-\\bar{x}_{\\mathrm{ref}} \\right). $$

`StateFeedback` and `SDREFeedback` use this convention. `PIDBaSFeedback` likewise subtracts its proportional, integral, derivative, and Barrier State terms.

The DDP/iLQR backward pass instead returns gains of the form

$$ K_k = -Q_{uu,k}^{-1}Q_{ux,k}. $$

Because this sign is already included in the solver gain, `TrajectoryPolicy` applies

$$ u_k = u_k^{\star} + K_k \\left( \\bar{x}_k-\\bar{x}_k^{\star} \\right). $$

> [!WARNING]
> `StateFeedback` and `TrajectoryPolicy` use different gain conventions. Gains from standard LQR/CARE designs are intended for `StateFeedback`, while `solution.feedback_gains` are DDP/iLQR policy gains intended for `TrajectoryPolicy`. Do not pass `solution.feedback_gains[k]` directly into `StateFeedback`. The solver gain is already negated; `StateFeedback` would negate it again and apply the wrong feedback sign.

See [`docs/conventions.md`](docs/conventions.md) for the full array, derivative, controller, and simulation conventions.

---

## Examples

| Example | System / task | Method |
|---|---|---|
| `toy_linear_bas_lqr.py` | Introductory safe stabilization of a linear system | BaS-LQR |
| `adaptive_cruise_control_pid_bas.py` | Time-headway safety in adaptive cruise control | BaS-PID |
| `toy_linear_bas_sdre.py` | Safe stabilization with pointwise Riccati feedback | BaS-SDRE |
| `planar_quadrotor_bas_sdre.py` | Planar quadrotor obstacle avoidance | BaS-SDRE |
| `differential_drive_bas_ddp.py` | Differential-drive obstacle-course navigation | BaS-DDP/iLQR |
| `cart_pole_bas_ddp.py` | Cart-pole swing-up with cart-position limits | BaS-DDP/iLQR |
| `quadrotor_3d_bas_ddp.py` | 12-state quadrotor navigation through spherical obstacles | BaS-DDP/iLQR |
| `multiagent_single_integrator_bas_feedback.py` | Inter-agent and obstacle avoidance | Direct BaS feedback |
| `double_integrator_bas_mpc.py` | Online obstacle avoidance with receding-horizon optimization | BaS-DDP-MPC |

Run any example from the repository root, for example:

```bash
python examples/differential_drive_bas_ddp.py
```

---

## Repository layout

```text
Barrier States-python/
├── src/barrier_states/
│   ├── models/                  # plant models
│   ├── constraints/             # safety constraints
│   ├── barriers/                # barrier constructions
│   ├── bas/                     # continuous and discrete BaS realizations
│   ├── embedding/               # safety-embedded systems
│   ├── controllers/             # feedback controllers and trajectory policies
│   ├── costs/                   # trajectory costs
│   ├── solvers/                 # DDP/iLQR trajectory optimization
│   ├── simulation/              # simulation utilities
│   └── plotting/                # plotting and animation helpers
├── examples/                    # runnable examples
├── tests/                       # unit and workflow tests
├── docs/
│   ├── api_reference.md
│   ├── concepts.md
│   ├── conventions.md
│   ├── trajectory_optimization.md
│   └── assets/readme/           # README figures and animations
├── CITATION.cff
├── pyproject.toml
├── README.md
└── LICENSE
```

---

## Testing

Run the complete test suite from the repository root:

```bash
python -m pytest -q
```

The tests cover the core mathematical and software workflows, including model derivatives, constraints, barriers, continuous/discrete BaS realizations, safety embeddings, controllers, DDP/iLQR, MPC, simulation, plotting, and animation smoke tests.

---

## Theory and papers

The library implements ideas developed in the following Barrier States publications.

### Core Barrier States theory

- **Barrier States Theory for Safety-Critical Multiobjective Control**  
  H. Almubarak, N. Sadegh, and E. A. Theodorou, 2025. *IEEE Transactions on Automatic Control*, vol. 70, no. 12, pp. 8149–8164.  
  General Barrier States theory, Barrier State realizations, safety-embedded systems, safe stabilization, input constraints, and robustness.  
  [arXiv](https://arxiv.org/abs/2310.07022) · [DOI](https://doi.org/10.1109/TAC.2025.3584908)

### Discrete-time trajectory optimization

- **Safety Embedded Differential Dynamic Programming Using Discrete Barrier States**  
  H. Almubarak, K. Stachowicz, N. Sadegh, and E. A. Theodorou, 2022. *IEEE Robotics and Automation Letters*, vol. 7, no. 2, pp. 2755–2762.  
  Discrete Barrier States and safety-embedded DDP trajectory optimization.  
  [arXiv](https://arxiv.org/abs/2105.14608) · [DOI](https://doi.org/10.1109/LRA.2022.3143301)

### Early continuous-time safety-embedded control

- **Safety Embedded Control of Nonlinear Systems via Barrier States**  
  H. Almubarak, N. Sadegh, and E. A. Theodorou, 2022. *IEEE Control Systems Letters*, vol. 6, pp. 1328–1333.  
  Continuous-time Barrier States and safety-embedded feedback control.  
  [arXiv](https://arxiv.org/abs/2102.10253) · [DOI](https://doi.org/10.1109/LCSYS.2021.3093255)

Additional publications and application papers are available from the [CORTx Laboratory publications page](https://cortx-lab.github.io/publications.html).

---

## Citation

Please cite the associated Barrier States papers if you use this library.

```bibtex
@article{almubarak2025barrier_states_theory,
  author  = {Almubarak, Hassan and Sadegh, Nader and Theodorou, Evangelos A.},
  title   = {Barrier States Theory for Safety-Critical Multiobjective Control},
  journal = {IEEE Transactions on Automatic Control},
  year    = {2025},
  volume  = {70},
  number  = {12},
  pages   = {8149--8164},
  doi     = {10.1109/TAC.2025.3584908}
}

@article{almubarak2022safety_embedded_ddp,
  author  = {Almubarak, Hassan and Stachowicz, Kyle and Sadegh, Nader and Theodorou, Evangelos A.},
  title   = {Safety Embedded Differential Dynamic Programming Using Discrete Barrier States},
  journal = {IEEE Robotics and Automation Letters},
  year    = {2022},
  volume  = {7},
  number  = {2},
  pages   = {2755--2762},
  doi     = {10.1109/LRA.2022.3143301}
}

@article{almubarak2022safety_embedded_control,
  author  = {Almubarak, Hassan and Sadegh, Nader and Theodorou, Evangelos A.},
  title   = {Safety Embedded Control of Nonlinear Systems via Barrier States},
  journal = {IEEE Control Systems Letters},
  year    = {2022},
  volume  = {6},
  pages   = {1328--1333},
  doi     = {10.1109/LCSYS.2021.3093255}
}
```

---

## Related project

The corresponding MATLAB implementation is available in the [Barrier States MATLAB Toolbox](https://github.com/CORTx-Lab/barrier-states-matlab).

The Python and MATLAB projects share the same mathematical workflow while following the conventions and strengths of their respective languages.

---

## Contributing

Issues, bug reports, examples, and focused pull requests are welcome. Please include tests for behavioral changes and keep additions consistent with the library's compact NumPy-oriented style.

Before submitting a change:

```bash
python -m pytest -q
```

---

## License

This project is licensed under the Apache License 2.0.

See the [`LICENSE`](LICENSE) file for details.

---

## Status

Version `v0.1.0` is the first public release of Barrier States Python.

The library is under active development. The core modeling, constraint, barrier, BaS realization, embedding, feedback, PID, SDRE, DDP/iLQR, MPC, multi-agent, simulation, plotting, and animation workflows are implemented, while public interfaces may continue to evolve as the library matures.
