cbfpy 0.0.1__tar.gz → 0.0.3__tar.gz

{cbfpy-0.0.1 → cbfpy-0.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: cbfpy
-Version: 0.0.1
+Version: 0.0.3
 Summary: Control Barrier Functions in Python
 Author-email: Daniel Morton <danielpmorton@gmail.com>
 Project-URL: Documentation, https://danielpmorton.github.io/cbfpy/
@@ -8,15 +8,14 @@ Project-URL: Repository, https://github.com/danielpmorton/cbfpy/
 Keywords: control,barrier,function,CBF,Jax
 Classifier: Programming Language :: Python :: 3
 Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: OS Independent
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: numpy<2
+Requires-Dist: numpy
 Requires-Dist: jax
 Requires-Dist: jaxlib
 Requires-Dist: qpax
 Provides-Extra: examples
-Requires-Dist: pybullet; extra == "examples"
+Requires-Dist: pybullet>=3.2.7; extra == "examples"
 Requires-Dist: pygame; extra == "examples"
 Requires-Dist: wheel; extra == "examples"
 Requires-Dist: matplotlib; extra == "examples"
@@ -26,12 +25,19 @@ Requires-Dist: mkdocstrings[python]; extra == "dev"
 Requires-Dist: pylint; extra == "dev"
 Requires-Dist: black; extra == "dev"
 Provides-Extra: all
-Requires-Dist: pylint; extra == "all"
-Requires-Dist: black; extra == "all"
-Requires-Dist: pybullet; extra == "all"
+Requires-Dist: pybullet>=3.2.7; extra == "all"
 Requires-Dist: pygame; extra == "all"
+Requires-Dist: wheel; extra == "all"
+Requires-Dist: matplotlib; extra == "all"
 Requires-Dist: mkdocs-material; extra == "all"
 Requires-Dist: mkdocstrings[python]; extra == "all"
+Requires-Dist: pylint; extra == "all"
+Requires-Dist: black; extra == "all"
+Dynamic: license-file
+
+<div align="center">
+<img src="https://github.com/user-attachments/assets/0304752c-cb75-4d53-b45f-b6b1a0912d9c" alt="logo"></img>
+</div>
 
 # CBFpy: Control Barrier Functions in Python and Jax
 
@@ -43,20 +49,20 @@ CBFpy is an easy-to-use and high-performance framework for constructing and solv
 
 For API reference, see the following [documentation](https://danielpmorton.github.io/cbfpy)
 
-If you use CBFpy in your research, please use the following citation:
+If you use CBFpy in your research, please cite the following [paper](https://arxiv.org/abs/2503.06736):
 
 ```
-@software{Morton_CBFpy_2024,
-  author = {Morton, Daniel},
-  license = {MIT},
-  title = {{CBFpy: Control Barrier Functions in Python and Jax}},
-  url = {https://github.com/danielpmorton/cbfpy},
-  version = {0.0.1},
-  month = Dec,
-  year = {2024}
+@article{morton2025oscbf,
+  author = {Morton, Daniel and Pavone, Marco},
+  title = {Safe, Task-Consistent Manipulation with Operational Space Control Barrier Functions},
+  year = {2025},
+  journal = {arXiv preprint arXiv:2503.06736},
+  note = {Accepted to IEEE/RSJ International Conference on Intelligent Robots and Systems (IROS), Hangzhou, 2025},
 }
 ```
 
+[![Paper](http://img.shields.io/badge/arXiv-2503.06736-B31B1B.svg)](https://arxiv.org/abs/2503.06736)
+
 ## Installation 
 
 ### From PyPI

{cbfpy-0.0.1 → cbfpy-0.0.3}/README.md

@@ -1,3 +1,7 @@
+<div align="center">
+<img src="https://github.com/user-attachments/assets/0304752c-cb75-4d53-b45f-b6b1a0912d9c" alt="logo"></img>
+</div>
+
 # CBFpy: Control Barrier Functions in Python and Jax
 
 CBFpy is an easy-to-use and high-performance framework for constructing and solving Control Barrier Functions (CBFs) and Control Lyapunov Functions (CLFs), using [Jax](https://github.com/google/jax) for:
@@ -8,20 +12,20 @@ CBFpy is an easy-to-use and high-performance framework for constructing and solv
 
 For API reference, see the following [documentation](https://danielpmorton.github.io/cbfpy)
 
-If you use CBFpy in your research, please use the following citation:
+If you use CBFpy in your research, please cite the following [paper](https://arxiv.org/abs/2503.06736):
 
 ```
-@software{Morton_CBFpy_2024,
-  author = {Morton, Daniel},
-  license = {MIT},
-  title = {{CBFpy: Control Barrier Functions in Python and Jax}},
-  url = {https://github.com/danielpmorton/cbfpy},
-  version = {0.0.1},
-  month = Dec,
-  year = {2024}
+@article{morton2025oscbf,
+  author = {Morton, Daniel and Pavone, Marco},
+  title = {Safe, Task-Consistent Manipulation with Operational Space Control Barrier Functions},
+  year = {2025},
+  journal = {arXiv preprint arXiv:2503.06736},
+  note = {Accepted to IEEE/RSJ International Conference on Intelligent Robots and Systems (IROS), Hangzhou, 2025},
 }
 ```
 
+[![Paper](http://img.shields.io/badge/arXiv-2503.06736-B31B1B.svg)](https://arxiv.org/abs/2503.06736)
+
 ## Installation 
 
 ### From PyPI
@@ -188,4 +192,4 @@ Use a CBF to keep a drone inside a safe box, while avoiding a moving obstacle. T
 
 This is the same CBF which was used in the ["Drone Fencing" demo](https://danielpmorton.github.io/drone_fencing/) at the Stanford Robotics center.
 
-![Image: Quadrotor avoiding an obstacle](https://raw.githubusercontent.com/danielpmorton/cbfpy/refs/heads/main/images/drone_demo.gif)
+![Image: Quadrotor avoiding an obstacle](https://raw.githubusercontent.com/danielpmorton/cbfpy/refs/heads/main/images/drone_demo.gif)

{cbfpy-0.0.1 → cbfpy-0.0.3}/cbfpy/cbfs/cbf.py

@@ -33,14 +33,8 @@ from jax.typing import ArrayLike
 import qpax
 
 from cbfpy.config.cbf_config import CBFConfig
-from cbfpy.utils.jax_utils import conditional_jit
 from cbfpy.utils.general_utils import print_warning
 
-# Debugging flags to disable jit in specific sections of the code.
-# Note: If any higher-level jits exist, those must also be set to debug (disable jit)
-DEBUG_SAFETY_FILTER = False
-DEBUG_QP_DATA = False
-
 
 @jax.tree_util.register_static
 class CBF:
@@ -73,8 +67,8 @@ class CBF:
         u_min: Optional[tuple],
         u_max: Optional[tuple],
         control_constrained: bool,
-        relax_cbf: bool,
-        cbf_relaxation_penalty: float,
+        relax_qp: bool,
+        constraint_relaxation_penalties: tuple,
         h_1: Callable[[ArrayLike], Array],
         h_2: Callable[[ArrayLike], Array],
         f: Callable[[ArrayLike], Array],
@@ -91,8 +85,8 @@ class CBF:
         self.u_min = u_min
         self.u_max = u_max
         self.control_constrained = control_constrained
-        self.relax_cbf = relax_cbf
-        self.cbf_relaxation_penalty = cbf_relaxation_penalty
+        self.relax_qp = relax_qp
+        self.constraint_relaxation_penalties = constraint_relaxation_penalties
         self.h_1 = h_1
         self.h_2 = h_2
         self.f = f
@@ -102,10 +96,6 @@ class CBF:
         self.P_config = P
         self.q_config = q
         self.solver_tol = solver_tol
-        if relax_cbf:
-            self.qp_solver: Callable = jax.jit(qpax.solve_qp_elastic)
-        else:
-            self.qp_solver: Callable = jax.jit(qpax.solve_qp)
 
     @classmethod
     def from_config(cls, config: CBFConfig) -> "CBF":
@@ -124,8 +114,8 @@ class CBF:
             config.u_min,
             config.u_max,
             config.control_constrained,
-            config.relax_cbf,
-            config.cbf_relaxation_penalty,
+            config.relax_qp,
+            config.constraint_relaxation_penalties,
             config.h_1,
             config.h_2,
             config.f,
@@ -158,7 +148,7 @@ class CBF:
                 + "Please provide an initial seed for these args in the config's init_args input"
             )
 
-    @conditional_jit(not DEBUG_SAFETY_FILTER)
+    @jax.jit
     def safety_filter(self, z: Array, u_des: Array, *h_args) -> Array:
         """Apply the CBF safety filter to a nominal control
 
@@ -171,17 +161,17 @@ class CBF:
             Array: Safe control input, shape (m,)
         """
         P, q, A, b, G, h = self.qp_data(z, u_des, *h_args)
-        if self.relax_cbf:
-            x_qp, t_qp, s1_qp, s2_qp, z1_qp, z2_qp, converged, iters = self.qp_solver(
+        if self.relax_qp:
+            x_qp = qpax.solve_qp_elastic_primal(
                 P,
                 q,
                 G,
                 h,
-                self.cbf_relaxation_penalty,
+                penalty=jnp.asarray(self.constraint_relaxation_penalties),
                 solver_tol=self.solver_tol,
             )
         else:
-            x_qp, s_qp, z_qp, y_qp, converged, iters = self.qp_solver(
+            x_qp, s_qp, z_qp, y_qp, converged, iters = qpax.solve_qp(
                 P,
                 q,
                 A,
@@ -190,10 +180,6 @@ class CBF:
                 h,
                 solver_tol=self.solver_tol,
             )
-        if DEBUG_SAFETY_FILTER:
-            print(
-                f"{'Converged' if converged else 'Did not converge'}. Iterations: {iters}"
-            )
         return x_qp[: self.m]
 
     def h(self, z: ArrayLike, *h_args) -> Array:
@@ -341,7 +327,6 @@ class CBF:
         else:
             return h
 
-    @conditional_jit(not DEBUG_QP_DATA)
     def qp_data(
         self, z: Array, u_des: Array, *h_args
     ) -> Tuple[Array, Array, Array, Array, Array, Array]:

{cbfpy-0.0.1 → cbfpy-0.0.3}/cbfpy/cbfs/clf_cbf.py

@@ -1,7 +1,7 @@
 """
 # Control Lyapunov Function / Control Barrier Functions (CLF-CBFs)
 
-Whereas a CBF acts as a safety filter on top of a nominal controller, a CLF-CBF acts as a safe controller itself, 
+Whereas a CBF acts as a safety filter on top of a nominal controller, a CLF-CBF acts as a safe controller itself,
 based on a control objective defined by the CLF and a safety constraint defined by the CBF. Note that the CLF
 objective should be quadratic and positive-definite to fit in this QP framework.
 
@@ -46,14 +46,8 @@ from jax.typing import ArrayLike
 import qpax
 
 from cbfpy.config.clf_cbf_config import CLFCBFConfig
-from cbfpy.utils.jax_utils import conditional_jit
 from cbfpy.utils.general_utils import print_warning
 
-# Debugging flags to disable jit in specific sections of the code.
-# Note: If any higher-level jits exist, those must also be set to debug (disable jit)
-DEBUG_CONTROLLER = False
-DEBUG_QP_DATA = False
-
 
 @jax.tree_util.register_static
 class CLFCBF:
@@ -87,9 +81,9 @@ class CLFCBF:
         u_min: Optional[tuple],
         u_max: Optional[tuple],
         control_constrained: bool,
-        relax_cbf: bool,
-        cbf_relaxation_penalty: float,
+        relax_qp: bool,
         clf_relaxation_penalty: float,
+        constraint_relaxation_penalties: tuple,
         h_1: Callable[[ArrayLike], Array],
         h_2: Callable[[ArrayLike], Array],
         f: Callable[[ArrayLike], Array],
@@ -111,9 +105,9 @@ class CLFCBF:
         self.u_min = u_min
         self.u_max = u_max
         self.control_constrained = control_constrained
-        self.relax_cbf = relax_cbf
-        self.cbf_relaxation_penalty = cbf_relaxation_penalty
+        self.relax_qp = relax_qp
         self.clf_relaxation_penalty = clf_relaxation_penalty
+        self.constraint_relaxation_penalties = constraint_relaxation_penalties
         self.h_1 = h_1
         self.h_2 = h_2
         self.f = f
@@ -127,10 +121,6 @@ class CLFCBF:
         self.H = H
         self.F = F
         self.solver_tol = solver_tol
-        if relax_cbf:
-            self.qp_solver: Callable = jax.jit(qpax.solve_qp_elastic)
-        else:
-            self.qp_solver: Callable = jax.jit(qpax.solve_qp)
 
     @classmethod
     def from_config(cls, config: CLFCBFConfig) -> "CLFCBF":
@@ -151,9 +141,9 @@ class CLFCBF:
             config.u_min,
             config.u_max,
             config.control_constrained,
-            config.relax_cbf,
-            config.cbf_relaxation_penalty,
+            config.relax_qp,
             config.clf_relaxation_penalty,
+            config.constraint_relaxation_penalties,
             config.h_1,
             config.h_2,
             config.f,
@@ -189,13 +179,13 @@ class CLFCBF:
                 "Cannot test Lgh; missing additional arguments.\n"
                 + "Please provide an initial seed for these args in the config's init_args input"
             )
-        test_lgv = self.LgV(test_z)
+        test_lgv = self.LgV(test_z, test_z)
         if jnp.allclose(test_lgv, 0):
             print_warning(
                 "LgV is zero. Consider increasing the relative degree or modifying the Lyapunov function."
             )
 
-    @conditional_jit(not DEBUG_CONTROLLER)
+    @jax.jit
     def controller(self, z: Array, z_des: Array, *h_args) -> Array:
         """Compute the CLF-CBF optimal control input, optimizing for the CLF objective while
         satisfying the CBF safety constraint.
@@ -209,17 +199,17 @@ class CLFCBF:
             Array: Safe control input, shape (m,)
         """
         P, q, A, b, G, h = self.qp_data(z, z_des, *h_args)
-        if self.relax_cbf:
-            x_qp, t_qp, s1_qp, s2_qp, z1_qp, z2_qp, converged, iters = self.qp_solver(
+        if self.relax_qp:
+            x_qp = qpax.solve_qp_elastic_primal(
                 P,
                 q,
                 G,
                 h,
-                self.cbf_relaxation_penalty,
+                penalty=jnp.asarray(self.constraint_relaxation_penalties),
                 solver_tol=self.solver_tol,
             )
         else:
-            x_qp, s_qp, z_qp, y_qp, converged, iters = self.qp_solver(
+            x_qp, s_qp, z_qp, y_qp, converged, iters = qpax.solve_qp(
                 P,
                 q,
                 A,
@@ -228,10 +218,6 @@ class CLFCBF:
                 h,
                 solver_tol=self.solver_tol,
             )
-        if DEBUG_CONTROLLER:
-            print(
-                f"{'Converged' if converged else 'Did not converge'}. Iterations: {iters}"
-            )
         return x_qp[: self.m]
 
     def h(self, z: ArrayLike, *h_args) -> Array:
@@ -300,49 +286,63 @@ class CLFCBF:
 
     ## CLF functions ##
 
-    def V(self, z: ArrayLike) -> Array:
+    def V(self, z: ArrayLike, z_des: ArrayLike) -> Array:
         """Control Lyapunov Function(s)
 
         Args:
             z (ArrayLike): State, shape (n,)
+            z_des (ArrayLike): Desired state, shape (n,)
 
         Returns:
             Array: CLF evaluation, shape (num_clf,)
         """
+
+        def _V_2(state):
+            return self.V_2(state, z_des)
+
         # Take any relative-degree-2 CLFs and convert them to relative-degree-1
         # NOTE: If adding args to the CLF, create a wrapper func like with the barrier function
-        V_2, dV_2_dt = jax.jvp(self.V_2, (z,), (self.f(z),))
+        V_2, dV_2_dt = jax.jvp(_V_2, (z,), (self.f(z),))
         V2_rd1 = dV_2_dt + self.gamma_2(V_2)
 
         # Merge the relative-degree-1 and relative-degree-2 CLFs
-        return jnp.concatenate([self.V_1(z), V2_rd1])
+        return jnp.concatenate([self.V_1(z, z_des), V2_rd1])
 
-    def V_and_LfV(self, z: ArrayLike) -> Tuple[Array, Array]:
+    def V_and_LfV(self, z: ArrayLike, z_des: ArrayLike) -> Tuple[Array, Array]:
         """Lie derivative of the CLF wrt the autonomous dynamics `f(z)`
 
         The evaluation of the CLF is also returned "for free", a byproduct of the jacobian-vector-product
 
         Args:
             z (ArrayLike): State, shape (n,)
+            z_des (ArrayLike): Desired state, shape (n,)
 
         Returns:
             V (Array): CLF evaluation, shape (1,)
             LfV (Array): Lie derivative of `V` w.r.t. `f`, shape (1,)
         """
-        return jax.jvp(self.V, (z,), (self.f(z),))
 
-    def LgV(self, z: ArrayLike) -> Array:
+        def _V(state):
+            return self.V(state, z_des)
+
+        return jax.jvp(_V, (z,), (self.f(z),))
+
+    def LgV(self, z: ArrayLike, z_des: ArrayLike) -> Array:
         """Lie derivative of the CLF wrt the control dynamics `g(z)u`
 
         Args:
             z (ArrayLike): State, shape (n,)
+            z_des (ArrayLike): Desired state, shape (n,)
 
         Returns:
             Array: LgV, shape (m,)
         """
 
+        def _V(state):
+            return self.V(state, z_des)
+
         def _jvp(g_column):
-            return jax.jvp(self.V, (z,), (g_column,))[1]
+            return jax.jvp(_V, (z,), (g_column,))[1]
 
         return jax.vmap(_jvp, in_axes=1, out_axes=1)(self.g(z))
 
@@ -401,7 +401,7 @@ class CLFCBF:
         """
         G = jnp.block(
             [
-                [self.LgV(z), -1.0 * jnp.ones((self.num_clf, 1))],
+                [self.LgV(z, z_des), -1.0 * jnp.ones((self.num_clf, 1))],
                 [-self.Lgh(z, *h_args), jnp.zeros((self.num_cbf, 1))],
             ]
         )
@@ -433,7 +433,7 @@ class CLFCBF:
             Array: h vector, shape (num_constraints,)
         """
         hz, lfh = self.h_and_Lfh(z, *h_args)
-        vz, lfv = self.V_and_LfV(z)
+        vz, lfv = self.V_and_LfV(z, z_des)
         h = jnp.concatenate(
             [
                 -lfv - self.gamma(vz),
@@ -447,7 +447,6 @@ class CLFCBF:
         else:
             return h
 
-    @conditional_jit(not DEBUG_QP_DATA)
     def qp_data(
         self, z: Array, z_des: Array, *h_args
     ) -> Tuple[Array, Array, Array, Array, Array, Array]:

{cbfpy-0.0.1 → cbfpy-0.0.3}/cbfpy/config/cbf_config.py

@@ -3,13 +3,13 @@
 
 ## Defining the problem:
 
-CBFs have two primary implementation requirements: the dynamics functions, and the barrier function(s). 
+CBFs have two primary implementation requirements: the dynamics functions, and the barrier function(s).
 These can be specified through the `f`, `g`, and `h` methods, respectively. Note that the main requirements
 for these functions are that (1) the dynamics are control-affine, and (2) the barrier function(s) are "zeroing"
 barriers, as opposed to "reciprocal" barriers. A zeroing barrier is one which is positive in the interior of the
-safe set, and zero on the boundary. 
+safe set, and zero on the boundary.
 
-Depending on the relative degree of your barrier function(s), you should implement the `h_1` method 
+Depending on the relative degree of your barrier function(s), you should implement the `h_1` method
 (for a relative-degree-1 barrier), and/or the `h_2` method (for a relative-degree-2 barrier).
 
 ## Tuning the CBF:
@@ -30,7 +30,7 @@ does require that P is positive semi-definite.
 Depending on the construction of the barrier functions and if control limits are provided, the CBF QP may not always be
 feasible. If allowing for relaxation in the CBFConfig, a slack variable will be introduced to ensure that the
 problem is always feasible, with a high penalty on any infeasibility. This is generally useful for controller
-robustness, but means that safety is not guaranteed. 
+robustness, but means that safety is not guaranteed.
 
 If strict enforcement of the CBF is desired, your higest-level controller should handle the case where the QP
 is infeasible.
@@ -38,6 +38,7 @@ is infeasible.
 
 from typing import Optional, Callable
 from abc import ABC, abstractmethod
+import warnings
 
 import numpy as np
 import jax
@@ -67,9 +68,12 @@ class CBFConfig(ABC):
         m (int): Control dimension
         u_min (ArrayLike, optional): Minimum control input, shape (m,). Defaults to None (Unconstrained).
         u_max (ArrayLike, optional): Maximum control input, shape (m,). Defaults to None (Unconstrained).
-        relax_cbf (bool, optional): Whether to allow for relaxation in the CBF QP. Defaults to True.
-        cbf_relaxation_penalty (float, optional): Penalty on the slack variable in the relaxed CBF QP. Defaults to 1e3.
-            Note: only applies if relax_cbf is True.
+        relax_qp (bool, optional): Whether to allow for relaxation in the CBF QP. Defaults to True.
+            Note: this is required for differentiability through the QP.
+        cbf_relaxation_penalty (float, optional): Penalty on the CBF slack variables in the relaxed QP.
+            Defaults to 1e3. Note: only applies if relax_qp is True.
+        control_relaxation_penalty (float, optional): Penalty on the control constraint slack variables in the
+            relaxed QP. Defaults to 1e5. Note: only applies if relax_qp is True.
         solver_tol (float, optional): Tolerance for the QP solver. Defaults to 1e-3.
         init_args (tuple, optional): If your barrier function relies on additional arguments other than just the state,
             include an initial seed for these arguments here. This is to help test the output of the barrier function.
@@ -82,8 +86,9 @@ class CBFConfig(ABC):
         m: int,
         u_min: Optional[ArrayLike] = None,
         u_max: Optional[ArrayLike] = None,
-        relax_cbf: bool = True,
+        relax_qp: bool = True,
         cbf_relaxation_penalty: float = 1e3,
+        control_relaxation_penalty: float = 1e5,
         solver_tol: float = 1e-3,
         init_args: tuple = (),
     ):
@@ -95,9 +100,9 @@ class CBFConfig(ABC):
             raise ValueError(f"m must be a positive integer. Got: {m}")
         self.m = m
 
-        if not isinstance(relax_cbf, bool):
-            raise ValueError(f"relax_cbf must be a boolean. Got: {relax_cbf}")
-        self.relax_cbf = relax_cbf
+        if not isinstance(relax_qp, bool):
+            raise ValueError(f"relax_qp must be a boolean. Got: {relax_qp}")
+        self.relax_qp = relax_qp
 
         if not (
             isinstance(cbf_relaxation_penalty, (int, float))
@@ -112,10 +117,25 @@ class CBFConfig(ABC):
             raise ValueError(f"solver_tol must be a positive value. Got: {solver_tol}")
         self.solver_tol = float(solver_tol)
 
+        if self.solver_tol > 1e-2:
+            print(
+                f"WARNING: solver tolerance is quite high ({self.solver_tol}). "
+                + " Solution will likely be poor."
+            )
+
         if not isinstance(init_args, tuple):
             raise ValueError(f"init_args must be a tuple. Got: {init_args}")
         self.init_args = init_args
 
+        if not (
+            isinstance(control_relaxation_penalty, (int, float))
+            and control_relaxation_penalty >= 0
+        ):
+            raise ValueError(
+                f"control_relaxation_penalty must be a non-negative value. Got: {control_relaxation_penalty}"
+            )
+        self.control_relaxation_penalty = float(control_relaxation_penalty)
+
         # Control limits require a bit of extra handling. They can be both None if unconstrained,
         # but we should not have one limit as None and the other as some value
         u_min = np.asarray(u_min, dtype=float).flatten() if u_min is not None else None
@@ -137,6 +157,12 @@ class CBFConfig(ABC):
         self.u_min = u_min
         self.u_max = u_max
 
+        if (
+            self.control_constrained
+            and self.control_relaxation_penalty < self.cbf_relaxation_penalty
+        ):
+            print("WARNING: Control constraints have a lower penalty than the CBFs.")
+
         # Test if the methods are provided and verify their output dimension
         z_test = jnp.ones(self.n)
         u_test = jnp.ones(self.m)
@@ -197,6 +223,25 @@ class CBFConfig(ABC):
         if not self._is_symmetric_psd(P_test):
             raise ValueError("P matrix must be symmetric positive semi-definite")
 
+        # Handle QP relaxation penalties, if relaxation is enabled
+        num_qp_constraints = (
+            self.num_cbf if not self.control_constrained else self.num_cbf + 2 * self.m
+        )
+        if self.control_constrained:
+            self.constraint_relaxation_penalties = tuple(
+                np.concatenate(
+                    [
+                        self.cbf_relaxation_penalty * np.ones(self.num_cbf),
+                        self.control_relaxation_penalty * np.ones(2 * self.m),
+                    ]
+                )
+            )
+        else:
+            self.constraint_relaxation_penalties = tuple(
+                self.cbf_relaxation_penalty * np.ones(self.num_cbf)
+            )
+        assert len(self.constraint_relaxation_penalties) == num_qp_constraints
+
     ## Control Affine Dynamics ##
 
     @abstractmethod

{cbfpy-0.0.1 → cbfpy-0.0.3}/cbfpy/config/clf_cbf_config.py

@@ -3,11 +3,11 @@
 
 ## Defining the problem:
 
-As with the CBF, we require implementation of the dynamics functions `f` and `g`, as well as the barrier function(s) 
+As with the CBF, we require implementation of the dynamics functions `f` and `g`, as well as the barrier function(s)
 `h`. Now, with the CLF-CBF, we require the definition of the Control Lyapunov Function (CLF) `V`. This CLF must be a
-positive definite function of the state. 
+positive definite function of the state.
 
-Depending on the relative degree of your barrier function(s), you should implement the `h_1` method 
+Depending on the relative degree of your barrier function(s), you should implement the `h_1` method
 (for a relative-degree-1 barrier), and/or the `h_2` method (for a relative-degree-2 barrier).
 
 Likewise, for the CLF, you should implement the `V_1` method (for a relative-degree-1 CLF), and/or the `V_2` method
@@ -24,7 +24,7 @@ CLF objective. These can be used to adjust the weightings between inputs, for in
 
 ## Relaxation:
 
-If the CBF constraints are not necessarily globally feasible, you can enable further relaxation in the CLFCBFConfig. 
+If the CBF constraints are not necessarily globally feasible, you can enable further relaxation in the CLFCBFConfig.
 However, since the CLF constraint was already relaxed with respect to the CBF constraint, this means that tuning the
 relaxation parameters is critical. In general, the penalty on the CBF relaxation should be much higher than the penalty
 on the CLF relaxation.
@@ -35,6 +35,7 @@ is infeasible.
 
 from typing import Optional
 
+import numpy as np
 import jax.numpy as jnp
 from jax import Array
 from jax.typing import ArrayLike
@@ -66,10 +67,13 @@ class CLFCBFConfig(CBFConfig):
         m (int): Control dimension
         u_min (ArrayLike, optional): Minimum control input, shape (m,). Defaults to None (Unconstrained).
         u_max (ArrayLike, optional): Maximum control input, shape (m,). Defaults to None (Unconstrained).
-        relax_cbf (bool, optional): Whether to allow for relaxation in the CBF QP. Defaults to True.
-        cbf_relaxation_penalty (float, optional): Penalty on the slack variable in the relaxed CBF QP. Defaults to 1e4.
-            Note: only applies if relax_cbf is True.
+        relax_qp (bool, optional): Whether to allow for relaxation in the CLF-CBF QP. Defaults to True.
+            Note: this is required for differentiability through the QP.
+        cbf_relaxation_penalty (float, optional): Penalty on the slack variable in the relaxed QP. Defaults to 1e4.
+            Note: only applies if relax_qp is True.
         clf_relaxation_penalty (float): Penalty on the CLF slack variable when enforcing the CBF. Defaults to 1e2
+        control_relaxation_penalty (float, optional): Penalty on the control constraint slack variables in the
+            relaxed QP. Defaults to 1e5. Note: only applies if relax_qp is True.
         solver_tol (float, optional): Tolerance for the QP solver. Defaults to 1e-3.
         init_args (tuple, optional): If your barrier function relies on additional arguments other than just the state,
             include an initial seed for these arguments here. This is to help test the output of the barrier function.
@@ -82,9 +86,10 @@ class CLFCBFConfig(CBFConfig):
         m: int,
         u_min: Optional[ArrayLike] = None,
         u_max: Optional[ArrayLike] = None,
-        relax_cbf: bool = True,
+        relax_qp: bool = True,
         cbf_relaxation_penalty: float = 1e4,
         clf_relaxation_penalty: float = 1e2,
+        control_relaxation_penalty: float = 1e5,
         solver_tol: float = 1e-3,
         init_args: tuple = (),
     ):
@@ -93,8 +98,9 @@ class CLFCBFConfig(CBFConfig):
             m,
             u_min,
             u_max,
-            relax_cbf,
+            relax_qp,
             cbf_relaxation_penalty,
+            control_relaxation_penalty,
             solver_tol,
             init_args,
         )
@@ -108,10 +114,19 @@ class CLFCBFConfig(CBFConfig):
             )
         self.clf_relaxation_penalty = float(clf_relaxation_penalty)
 
+        # If relaxing the QP, need to have CLF penalty < CBF penalty < Control constraint penalty
+        if self.cbf_relaxation_penalty < self.clf_relaxation_penalty:
+            print("WARNING: CBF constraints have a lower penalty than the CLFs")
+        if (
+            self.control_constrained
+            and self.control_relaxation_penalty < self.clf_relaxation_penalty
+        ):
+            print("WARNING: Control constraints have a lower penalty than the CLFs")
+
         # Check on CLF dimension
         z_test = jnp.ones(self.n)
-        v1_test = self.V_1(jnp.ones(self.n))
-        v2_test = self.V_2(jnp.ones(self.n))
+        v1_test = self.V_1(z_test, z_test)
+        v2_test = self.V_2(z_test, z_test)
         if v1_test.ndim != 1 or v2_test.ndim != 1:
             raise ValueError("CLF(s) must output 1D arrays")
         self.num_rd1_clf = v1_test.shape[0]
@@ -144,9 +159,35 @@ class CLFCBFConfig(CBFConfig):
             )
         if not self._is_symmetric_psd(H_test):
             raise ValueError("H(z) must be symmetric positive semi-definite")
-        # TODO: add a warning if the CLF relaxation penalty > the QP relaxation penalty?
 
-    def V_1(self, z: ArrayLike) -> Array:
+        # Handle QP relaxation penalties, if relaxation is enabled
+        num_qp_constraints = (
+            self.num_cbf + self.num_clf
+            if not self.control_constrained
+            else self.num_cbf + self.num_clf + 2 * self.m
+        )
+        if self.control_constrained:
+            self.constraint_relaxation_penalties = tuple(
+                np.concatenate(
+                    [
+                        self.clf_relaxation_penalty * np.ones(self.num_clf),
+                        self.cbf_relaxation_penalty * np.ones(self.num_cbf),
+                        self.control_relaxation_penalty * np.ones(2 * self.m),
+                    ]
+                )
+            )
+        else:
+            self.constraint_relaxation_penalties = tuple(
+                np.concatenate(
+                    [
+                        self.clf_relaxation_penalty * np.ones(self.num_clf),
+                        self.cbf_relaxation_penalty * np.ones(self.num_cbf),
+                    ]
+                )
+            )
+        assert len(self.constraint_relaxation_penalties) == num_qp_constraints
+
+    def V_1(self, z: ArrayLike, z_des: ArrayLike) -> Array:
         """Relative-Degree-1 Control Lyapunov Function (CLF)
 
         A CLF is a positive-definite function which evaluates to zero at the equilibrium point, and is
@@ -161,6 +202,7 @@ class CLFCBFConfig(CBFConfig):
 
         Args:
             z (ArrayLike): State, shape (n,)
+            z_des (ArrayLike): Desired state, shape (n,)
 
         Returns:
             Array: V(z): The RD1 CLF evaluation, shape (num_rd1_clf,)
@@ -168,7 +210,7 @@ class CLFCBFConfig(CBFConfig):
         return jnp.array([])
 
     # TODO: Check if the math behind this is actually valid
-    def V_2(self, z: ArrayLike) -> Array:
+    def V_2(self, z: ArrayLike, z_des: ArrayLike) -> Array:
         """Relative-Degree-2 (high-order) Control Lyapunov Function (CLF)
 
         A CLF is a positive-definite function which evaluates to zero at the equilibrium point, and is
@@ -184,6 +226,7 @@ class CLFCBFConfig(CBFConfig):
 
         Args:
             z (ArrayLike): State, shape (n,)
+            z_des (ArrayLike): Desired state, shape (n,)
 
         Returns:
             Array: V(z): The RD2 CLF evaluation, shape (num_rd2_clf,)

{cbfpy-0.0.1 → cbfpy-0.0.3}/cbfpy/envs/base_env.py

@@ -3,7 +3,7 @@
 
 This is a convenient structure for building demo environments to test CBFs. However, it is not necessary to use this.
 
-For instance, going back to the CBF usage pseudocode, 
+For instance, going back to the CBF usage pseudocode,
 ```
 while True:
     z = get_state()
@@ -11,10 +11,10 @@ while True:
     u_nom = nominal_controller(z, z_des)
     u = cbf.safety_filter(z, u_nom)
     apply_control(u)
-    step() 
+    step()
 ```
 We use this base environment to set up the `get_state`, `get_desired_state`, `apply_control`, and `step` methods in
-any derived environments. 
+any derived environments.
 """
 
 from abc import ABC, abstractmethod

{cbfpy-0.0.1 → cbfpy-0.0.3}/cbfpy/envs/drone_env.py

@@ -1,5 +1,5 @@
 """
-# Drone Environment 
+# Drone Environment
 
 This is a wrapper around the gym-pybullet-drones environment, using velocity control.
 """

{cbfpy-0.0.1 → cbfpy-0.0.3}/cbfpy/examples/adaptive_cruise_control_demo.py

@@ -49,10 +49,11 @@ class ACCConfig(CLFCBFConfig):
             u_max=u_max,
             # Note: Relaxing the CLF-CBF QP is tricky because there is an additional relaxation
             # parameter already, balancing the CLF and CBF constraints.
-            relax_cbf=False,
-            # If indeed relaxing, ensure that the QP relaxation >> the CLF relaxation
+            relax_qp=False,
+            # If indeed relaxing, ensure that the CBF relaxation >> the CLF relaxation
             clf_relaxation_penalty=10.0,
-            cbf_relaxation_penalty=1e6,
+            cbf_relaxation_penalty=1e5,
+            control_relaxation_penalty=1e6,
         )
 
     def drag_force(self, v: float) -> float:
@@ -82,7 +83,7 @@ class ACCConfig(CLFCBFConfig):
             [D - self.T * v_f - 0.5 * (v_l - v_f) ** 2 / (self.cd * self.gravity)]
         )
 
-    def V_1(self, z: ArrayLike) -> float:
+    def V_1(self, z: ArrayLike, z_des: ArrayLike) -> float:
         # CLF: Squared error between the follower velocity and the desired velocity
         return jnp.array([(z[0] - self.v_des) ** 2])
 

{cbfpy-0.0.1 → cbfpy-0.0.3}/cbfpy/examples/drone_demo.py

@@ -38,7 +38,7 @@ class DroneConfig(CBFConfig):
         super().__init__(
             n=6,  # State = [position, velocity]
             m=3,  # Control = [velocity]
-            relax_cbf=True,
+            relax_qp=True,
             init_args=(init_z_obs,),
             cbf_relaxation_penalty=1e6,
         )
@@ -73,7 +73,9 @@ class DroneConfig(CBFConfig):
                 - padding
             ]
         )
-        h_box_containment = jnp.concatenate([self.pos_max - z[:3], z[:3] - self.pos_min])
+        h_box_containment = jnp.concatenate(
+            [self.pos_max - z[:3], z[:3] - self.pos_min]
+        )
         return jnp.concatenate([h_obstacle_avoidance, h_box_containment])
 
     def alpha(self, h):

{cbfpy-0.0.1 → cbfpy-0.0.3}/cbfpy/examples/joint_limits_demo.py

@@ -6,7 +6,7 @@ within the limits (+ some margin)
 
 This uses a single-integrator reduced model of the manipulator dynamics.
 We define the state as the joint positions and assume that we can directly control the joint velocities
-i.e. z = [q1, q2, q3] and u = [q1_dot, q2_dot, q3_dot] 
+i.e. z = [q1, q2, q3] and u = [q1_dot, q2_dot, q3_dot]
 """
 
 import numpy as np

{cbfpy-0.0.1 → cbfpy-0.0.3}/cbfpy/examples/point_robot_obstacle_demo.py

@@ -9,8 +9,8 @@ This demo is interactive: click and drag the obstacle to move it around.
 Here, we have double integrator dynamics: z = [position, velocity], u = [acceleration]
 and we also use the state of the obstacle as an input to the CBF: z_obs = [position, velocity]
 
-This example includes both relative-degree-1 and relative-degree-2 CBFs. Staying inside the safe-set box is 
-RD2, since we have a positional barrier with acceleration inputs. Avoiding the obstacle is relative-degree-1, 
+This example includes both relative-degree-1 and relative-degree-2 CBFs. Staying inside the safe-set box is
+RD2, since we have a positional barrier with acceleration inputs. Avoiding the obstacle is relative-degree-1,
 because this is based on the relative velocity between the two objects.
 """
 

{cbfpy-0.0.1 → cbfpy-0.0.3}/cbfpy.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: cbfpy
-Version: 0.0.1
+Version: 0.0.3
 Summary: Control Barrier Functions in Python
 Author-email: Daniel Morton <danielpmorton@gmail.com>
 Project-URL: Documentation, https://danielpmorton.github.io/cbfpy/
@@ -8,15 +8,14 @@ Project-URL: Repository, https://github.com/danielpmorton/cbfpy/
 Keywords: control,barrier,function,CBF,Jax
 Classifier: Programming Language :: Python :: 3
 Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: OS Independent
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: numpy<2
+Requires-Dist: numpy
 Requires-Dist: jax
 Requires-Dist: jaxlib
 Requires-Dist: qpax
 Provides-Extra: examples
-Requires-Dist: pybullet; extra == "examples"
+Requires-Dist: pybullet>=3.2.7; extra == "examples"
 Requires-Dist: pygame; extra == "examples"
 Requires-Dist: wheel; extra == "examples"
 Requires-Dist: matplotlib; extra == "examples"
@@ -26,12 +25,19 @@ Requires-Dist: mkdocstrings[python]; extra == "dev"
 Requires-Dist: pylint; extra == "dev"
 Requires-Dist: black; extra == "dev"
 Provides-Extra: all
-Requires-Dist: pylint; extra == "all"
-Requires-Dist: black; extra == "all"
-Requires-Dist: pybullet; extra == "all"
+Requires-Dist: pybullet>=3.2.7; extra == "all"
 Requires-Dist: pygame; extra == "all"
+Requires-Dist: wheel; extra == "all"
+Requires-Dist: matplotlib; extra == "all"
 Requires-Dist: mkdocs-material; extra == "all"
 Requires-Dist: mkdocstrings[python]; extra == "all"
+Requires-Dist: pylint; extra == "all"
+Requires-Dist: black; extra == "all"
+Dynamic: license-file
+
+<div align="center">
+<img src="https://github.com/user-attachments/assets/0304752c-cb75-4d53-b45f-b6b1a0912d9c" alt="logo"></img>
+</div>
 
 # CBFpy: Control Barrier Functions in Python and Jax
 
@@ -43,20 +49,20 @@ CBFpy is an easy-to-use and high-performance framework for constructing and solv
 
 For API reference, see the following [documentation](https://danielpmorton.github.io/cbfpy)
 
-If you use CBFpy in your research, please use the following citation:
+If you use CBFpy in your research, please cite the following [paper](https://arxiv.org/abs/2503.06736):
 
 ```
-@software{Morton_CBFpy_2024,
-  author = {Morton, Daniel},
-  license = {MIT},
-  title = {{CBFpy: Control Barrier Functions in Python and Jax}},
-  url = {https://github.com/danielpmorton/cbfpy},
-  version = {0.0.1},
-  month = Dec,
-  year = {2024}
+@article{morton2025oscbf,
+  author = {Morton, Daniel and Pavone, Marco},
+  title = {Safe, Task-Consistent Manipulation with Operational Space Control Barrier Functions},
+  year = {2025},
+  journal = {arXiv preprint arXiv:2503.06736},
+  note = {Accepted to IEEE/RSJ International Conference on Intelligent Robots and Systems (IROS), Hangzhou, 2025},
 }
 ```
 
+[![Paper](http://img.shields.io/badge/arXiv-2503.06736-B31B1B.svg)](https://arxiv.org/abs/2503.06736)
+
 ## Installation 
 
 ### From PyPI

{cbfpy-0.0.1 → cbfpy-0.0.3}/cbfpy.egg-info/SOURCES.txt

@@ -25,7 +25,6 @@ cbfpy/examples/drone_demo.py
 cbfpy/examples/joint_limits_demo.py
 cbfpy/examples/point_robot_demo.py
 cbfpy/examples/point_robot_obstacle_demo.py
-cbfpy/temp/test_import.py
 cbfpy/utils/__init__.py
 cbfpy/utils/general_utils.py
 cbfpy/utils/jax_utils.py

{cbfpy-0.0.1 → cbfpy-0.0.3}/cbfpy.egg-info/requires.txt

@@ -1,15 +1,17 @@
-numpy<2
+numpy
 jax
 jaxlib
 qpax
 
 [all]
-pylint
-black
-pybullet
+pybullet>=3.2.7
 pygame
+wheel
+matplotlib
 mkdocs-material
 mkdocstrings[python]
+pylint
+black
 
 [dev]
 mkdocs-material
@@ -18,7 +20,7 @@ pylint
 black
 
 [examples]
-pybullet
+pybullet>=3.2.7
 pygame
 wheel
 matplotlib

{cbfpy-0.0.1 → cbfpy-0.0.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "cbfpy"
-version = "0.0.1"
+version = "0.0.3"
 description = "Control Barrier Functions in Python"
 authors = [{ name = "Daniel Morton", email = "danielpmorton@gmail.com" }]
 readme = "README.md"
@@ -12,12 +12,11 @@ keywords = ["control", "barrier", "function", "CBF", "Jax"]
 classifiers = [
     "Programming Language :: Python :: 3",
     "License :: OSI Approved :: MIT License",
-    "Operating System :: OS Independent",
 ]
 dependencies = [
-    "numpy<2", # Pybullet has trouble with numpy 2.0
-    "jax",
-    "jaxlib",
+    "numpy",
+    "jax",  # 0.4.30 recommended for best CPU performance
+    "jaxlib",  # 0.4.30 recommended for best CPU performance
     "qpax",
 ]
 
@@ -27,7 +26,8 @@ Repository = "https://github.com/danielpmorton/cbfpy/"
 
 [project.optional-dependencies]
 examples = [
-    "pybullet",
+    # Note: older versions of Pybullet have trouble with numpy 2.0
+    "pybullet>=3.2.7",
     "pygame",
     # "gym_pybullet_drones @ git+https://github.com/danielpmorton/gym-pybullet-drones.git",
     "wheel",
@@ -35,13 +35,15 @@ examples = [
 ]
 dev = ["mkdocs-material", "mkdocstrings[python]", "pylint", "black"]
 all = [
-    "pylint",
-    "black",
-    "pybullet",
+    "pybullet>=3.2.7",
     "pygame",
     # "gym_pybullet_drones @ git+https://github.com/danielpmorton/gym-pybullet-drones.git",
+    "wheel",
+    "matplotlib",
     "mkdocs-material",
     "mkdocstrings[python]",
+    "pylint",
+    "black",
 ]
 
 [tool.setuptools.packages.find]

{cbfpy-0.0.1 → cbfpy-0.0.3}/test/test_speed.py

@@ -1,11 +1,11 @@
 """Speed tests for the CBF solver
 
 We evaluate the speed of the solver NOT just via the QP solve but via the whole process
-(solving for the nominal control input, constructing the QP matrices, and then solving). 
+(solving for the nominal control input, constructing the QP matrices, and then solving).
 This provides a more accurate view of what the controller frequency would actually be if
 deployed on the robot.
 
-These test cases can also be used to check that modifications to the CBF implementation 
+These test cases can also be used to check that modifications to the CBF implementation
 do not significantly degrade performance
 """
 

cbfpy-0.0.1/cbfpy/temp/test_import.py

@@ -1,3 +0,0 @@
-import cbfpy
-
-cbfpy.CBF()