Barrier States Python Library

A Python library for safe control using Barrier States (BaS) and safety-embedded systems.

---

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:

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.

---

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

Differential-drive obstacle avoidance — BaS-DDP	3D quadrotor obstacle avoidance — BaS-DDP
Adaptive cruise control — BaS-PID	Double integrator — BaS-MPC
Multi-agent safety — BaS feedback	Cart-pole swing-up — BaS-DDP

Multi-agent safety diagnostic — minimum inter-agent distance

---

Installation

Clone the repository and install from source:

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

For development and testing:

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:

python examples/toy_linear_bas_lqr.py

Other representative examples:

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.

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	BaS concepts, shifted coordinates, continuous/discrete realizations, safety embedding, SDRE, and MPC
Conventions	Array shapes, model contracts, safety convention, derivatives, input bounds, plotting behavior, and feedback-gain signs
API reference	Compact package-by-package reference for the public API
Trajectory optimization	DDP/iLQR behavior, solution objects, solver diagnostics, trajectory policies, and DDP-based MPC

The scripts under examples/ provide complete runnable workflows.

---

Important conventions

Safety sign convention

All scalar safety functions use

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 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:

python examples/differential_drive_bas_ddp.py

---

Repository layout

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:

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 · DOI

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 · DOI

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 · DOI

Additional publications and application papers are available from the CORTx Laboratory publications page.

---

Citation

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

@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.

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:

python -m pytest -q

---

License

This project is licensed under the Apache License 2.0.

See the 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.