API Reference

CBF Classes

class cbfpy.cbf.CBFBase[source]

Bases: object

CBF base class

The CBF optimization problem is formulated as:: minimize_{u} {objective function} subject to G*u + alpha(h) >= 0

G

constraint matrix (=dh/dx)

Type:: numpy.ndarray[tuple[int, …], numpy.dtype[numpy._typing._array_like._ScalarType_co]]

h

constraint value (=h(x))

Type:: float

get_constraints() → tuple[ndarray[tuple[int, ...], dtype[_ScalarType_co]], float][source]

Returns:: constraint matrix alpha(h): value of alpha function applied to h
Return type:: G

class cbfpy.cbf.CircleCBF(center: ndarray[tuple[int, ...], dtype[_ScalarType_co]], radius: float, keep_inside: bool = True)[source]

Bases: CBFBase

CBF for circular area constraint.

center: center of circular area in world coordinate. shape=(2,)

radius: radius of the circular area

keep_inside: flag to prohibit going outside of the area

G

constraint matrix (=dh/dx). shape=(2,)

Type:: numpy.ndarray[tuple[int, …], numpy.dtype[numpy._typing._array_like._ScalarType_co]]

h

constraint value (=h(x))

Type:: float

calc_constraints(agent_position: ndarray[tuple[int, ...], dtype[_ScalarType_co]]) → None[source]

Parameters:: agent_position – agent position in world coordinate. shape=(2,)

Note

Division by radius is a remnant of the transformation.

set_parameters(center: ndarray[tuple[int, ...], dtype[_ScalarType_co]], radius: float, keep_inside: bool = True) → None[source]: Set parameters and rebuild symbolic functions.

class cbfpy.cbf.GeneralCBF(G: ndarray[tuple[int, ...], dtype[_ScalarType_co]], h: float)[source]

Bases: CBFBase

General-purpose CBF with manually specified constraints.

G

constraint matrix (=dh/dx). shape=(N,)

Type:: numpy.ndarray[tuple[int, …], numpy.dtype[numpy._typing._array_like._ScalarType_co]]

h

constraint value (=h(x))

Type:: float

class cbfpy.cbf.LiDARCBF(width: ndarray[tuple[int, ...], dtype[_ScalarType_co]], keep_upper: bool = True)[source]

Bases: CBFBase

CBF for LiDAR-based obstacle avoidance.

width: half length of the major and minor axis of ellipse that match the x and y axis in the agent coordinate. shape=(2,)

keep_upper: flag to prohibit going lower of the limit

G

constraint matrix (=dh/dx). shape=(2,)

Type:: numpy.ndarray[tuple[int, …], numpy.dtype[numpy._typing._array_like._ScalarType_co]]

h

constraint value (=h(x))

Type:: float

set_parameters(width: ndarray[tuple[int, ...], dtype[_ScalarType_co]], keep_upper: bool = True) → None[source]: Set parameters and rebuild symbolic functions.

class cbfpy.cbf.Pnorm2dCBF(center: ndarray[tuple[int, ...], dtype[_ScalarType_co]], width: ndarray[tuple[int, ...], dtype[_ScalarType_co]], theta: float = 0.0, p: float = 2.0, keep_inside: bool = True)[source]

Bases: CBFBase

CBF for p-norm shaped area constraint.

center: center of area in world coordinate. shape=(2,)

width: half length of the major and minor axis of ellipse that match the x and y axis in the area coordinate. shape=(2,)

theta: rotation angle (rad) from world to area coordinate

p: multiplier for p-norm

keep_inside: flag to prohibit going outside of the area

G

constraint matrix (=dh/dx). shape=(2,)

Type:: numpy.ndarray[tuple[int, …], numpy.dtype[numpy._typing._array_like._ScalarType_co]]

h

constraint value (=h(x))

Type:: float

calc_constraints(agent_position: ndarray[tuple[int, ...], dtype[_ScalarType_co]]) → None[source]

Parameters:: agent_position – agent position in world coordinate. shape=(2,)

Note

Division by width is a remnant of the transformation.

set_parameters(center: ndarray[tuple[int, ...], dtype[_ScalarType_co]], width: ndarray[tuple[int, ...], dtype[_ScalarType_co]], theta: float = 0.0, p: float = 2.0, keep_inside: bool = True) → None[source]: Set parameters and rebuild symbolic functions.

class cbfpy.cbf.ScalarCBF(limit: float, keep_upper: bool = True)[source]

Bases: CBFBase

CBF for scalar state variable.

If keep_upper is True, the safety set is x - limit >= 0.

limit: limit for scalar state variable

keep_upper: flag to prohibit going lower of the limit

G

constraint matrix (=dh/dx). shape=(1,)

Type:: numpy.ndarray[tuple[int, …], numpy.dtype[numpy._typing._array_like._ScalarType_co]]

h

constraint value (=h(x))

Type:: float

set_parameters(limit: float, keep_upper: bool = True) → None[source]: Set parameters and rebuild symbolic functions.

class cbfpy.cbf.ScalarRangeCBF(a: float, b: float, keep_inside: bool = True)[source]

Bases: CBFBase

CBF for scalar state variable with range constraint.

If keep_inside is True, the safety set is a <= x <= b.

a: lower limit for scalar state variable

b: upper limit for scalar state variable

keep_inside: flag to prohibit going outside of the range

G

constraint matrix (=dh/dx). shape=(1,)

Type:: numpy.ndarray[tuple[int, …], numpy.dtype[numpy._typing._array_like._ScalarType_co]]

h

constraint value (=h(x))

Type:: float

set_parameters(a: float, b: float, keep_inside: bool = True) → None[source]: Set parameters and rebuild symbolic functions.

class cbfpy.cbf.UnicycleCircleCBF(center: ndarray[tuple[int, ...], dtype[_ScalarType_co]], radius: float, keep_inside: bool = True)[source]

Bases: CircleCBF

CBF for circular area constraint with unicycle model.

center: center of circular area in world coordinate. shape=(2,)

radius: radius of the circular area

keep_inside: flag to prohibit going outside of the area

G

constraint matrix (=dh/dx). shape=(2,)

Type:: numpy.ndarray[tuple[int, …], numpy.dtype[numpy._typing._array_like._ScalarType_co]]

h

constraint value (=h(x))

Type:: float

calc_constraints(agent_pose: ndarray[tuple[int, ...], dtype[_ScalarType_co]]) → None[source]

Parameters:: agent_pose – agent pose in world coordinate. shape=(3,) [x, y, theta]

Note

Division by radius is a remnant of the transformation.

set_parameters(center: ndarray[tuple[int, ...], dtype[_ScalarType_co]], radius: float, keep_inside: bool = True) → None[source]: Set parameters and rebuild symbolic functions.

class cbfpy.cbf.UnicyclePnorm2dCBF(center: ndarray[tuple[int, ...], dtype[_ScalarType_co]], width: ndarray[tuple[int, ...], dtype[_ScalarType_co]], theta: float = 0.0, p: float = 2.0, keep_inside: bool = True)[source]

Bases: Pnorm2dCBF

CBF for p-norm shaped area constraint with unicycle model.

center: center of area in world coordinate. shape=(2,)

width: half length of the major and minor axis of ellipse that match the x and y axis in the area coordinate. shape=(2,)

theta: rotation angle (rad) from world to area coordinate

p: multiplier for p-norm

keep_inside: flag to prohibit going outside of the area

G

constraint matrix (=dh/dx). shape=(2,)

Type:: numpy.ndarray[tuple[int, …], numpy.dtype[numpy._typing._array_like._ScalarType_co]]

h

constraint value (=h(x))

Type:: float

calc_constraints(agent_pose: ndarray[tuple[int, ...], dtype[_ScalarType_co]]) → None[source]

Parameters:: agent_pose – agent pose in world coordinate. shape=(3,) [x, y, theta]

Note

Division by width is a remnant of the transformation.

set_parameters(center: ndarray[tuple[int, ...], dtype[_ScalarType_co]], width: ndarray[tuple[int, ...], dtype[_ScalarType_co]], theta: float = 0.0, p: float = 2.0, keep_inside: bool = True) → None[source]: Set parameters and rebuild symbolic functions.

cbfpy.cbf.rotation_matrix_2d(rad: float) → ndarray[tuple[int, ...], dtype[_ScalarType_co]][source]

Create a 2D rotation matrix.

Parameters:: rad – rotation angle in radians
Returns:: 2x2 rotation matrix

QP Solvers

class cbfpy.cbf_qp_solver.CBFNomQPSolver[source]

Bases: object

CBF-QP solver that tracks a nominal input.

optimize(nominal_input: ndarray[tuple[int, ...], dtype[_ScalarType_co]], P: ndarray[tuple[int, ...], dtype[_ScalarType_co]], G_list: Sequence[ndarray[tuple[int, ...], dtype[_ScalarType_co]]], alpha_h_list: list[float]) → tuple[str, ndarray[tuple[int, ...], dtype[_ScalarType_co]]][source]

Solve the CBF-QP optimization problem with nominal input tracking.

minimize_{u} (1/2) * (u-nominal_input)^T*P*(u-nominal_input) subject to G*u + alpha(h) >= 0

Parameters:

nominal_input – nominal input. shape=(N,)
P – optimization weight matrix. shape=(N, N)
G_list – constraint matrix list. [(N,), (N,), …]
alpha_h_list – constraint value list

Returns:

“optimal” on success optimal_input: optimal input. shape=(N,)

Return type:

status

class cbfpy.cbf_qp_solver.CBFQPSolver[source]

Bases: object

CBF-QP solver for general quadratic cost.

optimize(P: ndarray[tuple[int, ...], dtype[_ScalarType_co]], q: ndarray[tuple[int, ...], dtype[_ScalarType_co]], G_list: Sequence[ndarray[tuple[int, ...], dtype[_ScalarType_co]]], alpha_h_list: list[float]) → tuple[str, ndarray[tuple[int, ...], dtype[_ScalarType_co]]][source]

Solve the CBF-QP optimization problem.

minimize_{u} (1/2) * u^T*P*u + q^T*u subject to G*u <= alpha(h)

Parameters:

P – optimization weight matrix. shape=(N, N)
q – optimization weight vector. shape=(N,) or (N, 1)
G_list – constraint matrix list. [(N,), (N,), …]
alpha_h_list – constraint value list

Returns:

“optimal” on success optimal_input: optimal input. shape=(N,)

Return type:

status