pycvxset

https://merlresearch.github.io/pycvxset/
Admin
pycvxset is a Python package for manipulation and visualization of convex sets, supporting...
Tokens:131,194
Snippets:892
Trust Score:9.7
Update:5 months ago
Show doc for...
Tokens:
Raw
### Example of handling NotImplementedError with CVXPY solvers

Source: https://merlresearch.github.io/pycvxset/pycvxset.Ellipsoid.html

This example demonstrates how to handle `NotImplementedError` when a CVXPY solver fails, by attempting to use an alternative solver. It shows how to switch solvers for a `Polytope` object.

```python
from pycvxset import Polytope
P = Polytope(A=[[1, 1], [-1, -1]], b=[1, 1])
P.cvxpy_args_lp = {'solver': 'CLARABEL'}    # Default solver used in pycvxset
try:
    print('Is polytope bounded?', P.is_bounded)
except NotImplementedError as err:
    print(str(err))
P.cvxpy_args_lp = {'solver': 'OSQP'}
print('Is polytope bounded?', P.is_bounded)
```

```text
Unable to solve the task (support function evaluation of the set at eta = [-0. -1.]). CVXPY returned error:
Solver 'CLARABEL' failed. Try another solver, or solve with verbose=True for more information.

Is polytope bounded? False
```

--------------------------------

### CVXPY Problem Setup for DC Optimization

Source: https://merlresearch.github.io/pycvxset/_modules/pycvxset/common.html

Sets up the CVXPY problem for the difference of convex (DC) optimization approach. It defines variables for point locations, separation, and slack variables, along with constraints for pairwise and standard vector separations.

```python
if verbose:
                    print(f"{iter_count}/{MAX_ITERATIONS}. Setting up the CVXPY problem...")

                x = cp.Variable((n_points_first_quad, dim))
                separation = cp.Variable(nonneg=True)
                pairwise_separation_slack_var = cp.Variable((n_points_first_quad, n_points_first_quad), nonneg=True)
                standard_vector_separation_slack_var = cp.Variable((n_points_first_quad, dim), nonneg=True)
                minimum_norm_slack_var = cp.Variable((n_points_first_quad,), nonneg=True)
                # Constraint 1: Enforces the separation constraint is satisfied by reflections about quadrant planes
                constraints: list[cp.Constraint] = [
                    np.power(2, 1 / dim) * x >= separation,
                ]
                # Constraint 2: Set the unused slack variables to zero
                constraints += [pairwise_separation_slack_var[np.triu_indices(n_points_first_quad, -1)] == 0]
                for pt_index_1 in range(n_points_first_quad):
                    if verbose:
                        print(f"{pt_index_1:2d} | ", end="")
                        if ((pt_index_1 - 9) % 10 == 0) or pt_index_1 == n_points_first_quad - 1:
                            print("")

                    # Constraint 3: Enforces the pairwise separation constraint ||x_i - x_j||^2 >= r^2
                    x_i_prev = x_iter[pt_index_1, :]
                    for pt_index_2 in range(pt_index_1):
                        x_j_prev = x_iter[pt_index_2, :]
                        constraints.append(
                            (x_i_prev - x_j_prev) @ (x_i_prev - x_j_prev)
                            + 2 * ((x_i_prev - x_j_prev) @ (x[pt_index_1, :] - x_i_prev))
                            - 2 * ((x_i_prev - x_j_prev) @ (x[pt_index_2, :] - x_j_prev))
                            + pairwise_separation_slack_var[pt_index_1, pt_index_2]
                            >= cp.square(separation)
                        )
```

--------------------------------

### Import necessary packages for pycvxset

Source: https://merlresearch.github.io/pycvxset/tutorials/polytope.html

Imports the Polytope and Ellipsoid classes from pycvxset, along with numpy and matplotlib for numerical operations and plotting. This setup is required before running notebook examples.

```python
from pycvxset import Polytope, Ellipsoid, spread_points_on_a_unit_sphere
import numpy as np
import matplotlib.pyplot as plt
```

--------------------------------

### Initialize and Check Boundedness of a Polytope

Source: https://merlresearch.github.io/pycvxset/pycvxset.Polytope.html

Demonstrates initializing a Polytope with half-space representation and checking its boundedness using different solvers. Note that solver failures might occur.

```python
P = Polytope(A=[[1, 1], [-1, -1]], b=[1, 1])
P.cvxpy_args_lp = {'solver': 'CLARABEL'}    # Default solver used in pycvxset
try:
    print('Is polytope bounded?', P.is_bounded)
except NotImplementedError as err:
    print(str(err))
P.cvxpy_args_lp = {'solver': 'OSQP'}
print('Is polytope bounded?', P.is_bounded)
```

--------------------------------

### Install pycddlib on MacOS

Source: https://merlresearch.github.io/pycvxset/index.html

Installs GMP and cddlib using Homebrew, then installs pycddlib with specific compiler flags.

```bash
% brew install gmp cddlib
% python3 -m pip install --upgrade pip
% env "CFLAGS=-I$(brew --prefix)/include -L$(brew --prefix)/lib" python -m pip install pycddlib==3.0.0
```

--------------------------------

### Create and Describe Polytopes in Python

Source: https://merlresearch.github.io/pycvxset/tutorials/acc2025_code_snippets.html

Demonstrates creating polytopes from vertex (V-Rep) and half-space (H-Rep) definitions. Vertex enumeration is triggered when accessing the .V attribute for H-Rep polytopes.

```python
import numpy as np
from pycvxset import Polytope

V = [[-1, 0.5], [-1, 1], [1, 1], [1, -1], [0.5, -1]]
P1 = Polytope(V=V)
print("P1 is a", repr(P1))
A, b = -np.eye(3), np.zeros((3,)))
Ae, be = [1, 1, 1], 1
P2 = Polytope(A=A, b=b, Ae=Ae, be=be)
print("P2 is a", P2)
print("Vertices of P2 are:\n", P2.V)
print("P2 is a", P2)
```

--------------------------------

### Ellipsoid Initialization with Q

Source: https://merlresearch.github.io/pycvxset/_modules/pycvxset/Ellipsoid.html

Initialize an Ellipsoid using its center (c) and shape matrix (Q). Q must be a positive-definite matrix.

```python
Ellipsoid(c=np.array([1, 2]), Q=np.array([[1, 0.5], [0.5, 1]]))
```

--------------------------------

### Install pycddlib on Ubuntu

Source: https://merlresearch.github.io/pycvxset/index.html

Installs GMP, cddlib, and Python development headers required for pycddlib on Ubuntu.

```bash
$ sudo apt-get install libgmp-dev libcdd-dev python3-dev
```

--------------------------------

### Initialize Polytope from Vertices (V-Rep)

Source: https://merlresearch.github.io/pycvxset/_modules/pycvxset/Polytope.html

Sets polytope attributes from a list of vertices. Ensures the input is a 2D numpy array. Automatically marks the polytope as non-empty and bounded. The polytope is considered to be in V-rep if the vertex list is not empty.

```python
V = np.asarray(V, dtype=float)
        if V.ndim != 2:
            raise ValueError("Expected V to be a 2-D numpy array.")
        n = V.shape[1]
        if n == 0:
            self._set_polytope_to_empty(n)
        else:  # in_V_rep if V is not an empty array
            self._in_V_rep = True
            self._V = V
            self._dim = n
            self._is_empty, self._is_bounded = False, True
            self._is_singleton = self.n_vertices == 1
            # We have not assigned self._is_full_dimensional
        if erase_H_rep:
```

--------------------------------

### Polytope Constructor Initialization Logic

Source: https://merlresearch.github.io/pycvxset/_modules/pycvxset/Polytope.html

This code demonstrates the internal logic of the Polytope constructor, checking various keyword arguments to determine how the polytope is defined. It handles cases for empty polytopes, definition by vertices, or definition by bounds.

```python
def __init__(self, **kwargs: Any) -> None:
        """Constructor for Polytope class."""
        # The following attributes are accessible to the user via a getter to avoid end-user interactions
        ##########################################
        # Attributes set by _set_attributes_from_X
        ##########################################
        self._type_of_set: str = "Polytope"
        self._dim: int = 0
        self._A, self._b = np.empty((0, 1)), np.empty((0,))
        self._Ae, self._be = np.empty((0, 1)), np.empty((0,))
        self._V = np.empty((0, 1))
        self._in_H_rep: bool = False
        self._in_V_rep: bool = False
        # These attributes are computed if necessary within _set_attributes_from_X
        self._is_full_dimensional: Optional[bool] = None
        self._is_empty: Optional[bool] = None
        self._is_bounded: Optional[bool] = None
        self._is_singleton: Optional[bool] = None
        # These attributes are used by CVXPY to solve problems
        self._cvxpy_args_lp = DEFAULT_CVXPY_ARGS_LP
        self._cvxpy_args_socp = DEFAULT_CVXPY_ARGS_SOCP
        self._cvxpy_args_sdp = DEFAULT_CVXPY_ARGS_SDP
        # Check how the constructor was called.
        empty_polytope_via_n = ("dim" in kwargs) or not kwargs
        V_passed = any(kw in kwargs for kw in ("V"))
        A_and_b_passed = all(k in kwargs for k in ("A", "b"))
        Ae_and_be_passed = all(k in kwargs for k in ("Ae", "be"))
        lb_and_ub_passed = all(kw in kwargs for kw in ("lb", "ub"))
        c_and_h_passed = all(kw in kwargs for kw in ("c", "h"))

        # Check valid combination of inputs
        if empty_polytope_via_n:
            if len(kwargs) <= 1:
                # Calling Polytope() or without n as a kwarg:
                self._set_polytope_to_empty(kwargs.get("dim", 0))
            else:
                raise ValueError("Cannot set dimension dim with other arguments")
        elif V_passed:
            if len(kwargs) == 1:
                # Calling Polytope(V=?)
                self._set_attributes_from_V(kwargs.get("V"))
            else:
                raise ValueError("Cannot set vertices V with other arguments")
        elif lb_and_ub_passed:
            if len(kwargs) == 2:

```

--------------------------------

### polytopic_outer_approximation

Source: https://merlresearch.github.io/pycvxset/_modules/pycvxset/ConstrainedZonotope.html

Get the polytopic outer approximation of the constrained zonotope.

```APIDOC
## polytopic_outer_approximation

### Description
Get the polytopic outer approximation of the constrained zonotope.
```

--------------------------------

### polytopic_inner_approximation

Source: https://merlresearch.github.io/pycvxset/_modules/pycvxset/ConstrainedZonotope.html

Get the polytopic inner approximation of the constrained zonotope.

```APIDOC
## polytopic_inner_approximation

### Description
Get the polytopic inner approximation of the constrained zonotope.
```

--------------------------------

### Initialize Polytope from Bounds (H-Rep)

Source: https://merlresearch.github.io/pycvxset/_modules/pycvxset/Polytope.html

Initializes a polytope using lower (lb) and upper (ub) bounds. Handles cases where lb equals ub (singleton vertex), lb < ub (inequalities only), or a mix of equality and inequality constraints. Assumes lb and ub are convertible to 1D float numpy arrays and have the same shape.

```python
if lb.shape != ub.shape or lb.ndim != 1:
            raise ValueError(
                f"Expected lb, ub to 1D numpy arrays of same shape. Got lb: {np.array2string(np.array(lb)):s} "
                f"and ub: {np.array2string(np.array(ub)):s}!"
            )
        else:
            n = lb.size
            if np.any(lb > ub):
                self._set_polytope_to_empty(dim=n)
            elif np.isinf(lb).any() or np.isinf(ub).any():
                raise ValueError("Polytope is not bounded in some directions!")
            else:  # lb <= ub
                lb_ub_indices_for_equality = np.where(np.abs(ub - lb) <= PYCVXSET_ZERO)[0]
                if lb_ub_indices_for_equality.size == n:  # lb = ub. So a single vertex!
                    self._set_attributes_from_V(np.array([(lb + ub) / 2]), erase_H_rep=True)
                elif lb_ub_indices_for_equality.size == 0:
                    # No equality constraints: lb <= x <= ub with lb < ub <===> x <= ub, -x <= -lb
                    A_bound = np.vstack((np.eye(n), -np.eye(n)))
                    b_bound = np.hstack((ub, -lb))
                    # Help _set_attributes_from_Ab_Aebe by setting discernable attributes
                    self._is_full_dimensional, self._is_empty, self._is_bounded, self._is_singleton = (
                        True,
                        False,
                        True,
                        False,
                    )
                    self._set_attributes_from_Ab_Aebe(A_bound, b_bound, erase_V_rep=True)
                else:
                    # Some equality and some inequality constraints
                    n_equalities = lb_ub_indices_for_equality.size
                    n_inequalities = n - n_equalities
                    # Populate Ae, be
                    Ae = np.zeros((n_equalities, n))
                    be = np.zeros((n_equalities,))
                    for Ae_index, dim in enumerate(lb_ub_indices_for_equality):
                        Ae[Ae_index, dim] = 1
                        be[Ae_index] = (lb[dim] + ub[dim]) / 2
                    # Populate A, b
                    lb_ub_indices_for_inequality = np.where(np.abs(ub - lb) > PYCVXSET_ZERO)[0]
                    A = np.zeros((2 * n_inequalities, n))
                    b = np.zeros((2 * n_inequalities,))
                    for A_index, dim in enumerate(lb_ub_indices_for_inequality):
                        A[A_index, dim] = 1
                        A[n_inequalities + A_index, dim] = -1
                        b[A_index] = ub[dim]
                        b[n_inequalities + A_index] = -lb[dim]
                    # Help _set_attributes_from_Ab_Aebe by setting discernable attributes
                    self._is_full_dimensional, self._is_empty, self._is_bounded, self._is_singleton = (
                        False,
                        False,
                        True,
                        False,
                    )
                    self._set_attributes_from_Ab_Aebe(A, b, Ae=Ae, be=be, erase_V_rep=True)
```

--------------------------------

### containment_constraints

Source: https://merlresearch.github.io/pycvxset/api_summary/pycvxset.Polytope.html

Get CVXPY constraints for containment of x (a cvxpy.Variable) in a polytope.

```APIDOC
## containment_constraints

### Description
Get CVXPY constraints for containment of x (a cvxpy.Variable) in a polytope.

### Method
`containment_constraints(x[, flatten_order])`

### Parameters
#### Path Parameters
- **x** (cvxpy.Variable) - Required - Description
- **flatten_order** (type) - Optional - Description
```

--------------------------------

### Constructor

Source: https://merlresearch.github.io/pycvxset/pycvxset.ConstrainedZonotope.html

Initializes a ConstrainedZonotope object. Multiple constructor signatures are available.

```APIDOC
## Constructor

### Description
Initializes a ConstrainedZonotope object.

### Signatures

1. `__init__(_*_ , _lb : Sequence[float] | ndarray_, _ub : Sequence[float] | ndarray_)
2. `__init__(_*_ , _c : Sequence[float] | ndarray_, _h : float | Sequence[float] | ndarray_)
3. `__init__(_*_ , _polytope : Polytope_)
```

--------------------------------

### containment_constraints

Source: https://merlresearch.github.io/pycvxset/api_summary/pycvxset.Ellipsoid.html

Get CVXPY constraints for containment of x (a cvxpy.Variable) in an ellipsoid.

```APIDOC
## containment_constraints(x[, flatten_order])

### Description
Get CVXPY constraints for containment of x (a cvxpy.Variable) in an ellipsoid.

### Parameters
- **x** - A cvxpy.Variable to check for containment.
- **flatten_order** (optional) - Specifies the flattening order for the variable.

### Method
`containment_constraints(x[, flatten_order])`
```

--------------------------------

### containment_constraints

Source: https://merlresearch.github.io/pycvxset/_modules/pycvxset/ConstrainedZonotope.html

Get CVXPY constraints for containment of x (a cvxpy.Variable) in a constrained zonotope.

```APIDOC
## containment_constraints

### Description
Get CVXPY constraints for containment of x (a cvxpy.Variable) in a constrained zonotope.

### Arguments
- x (cvxpy.Variable): CVXPY variable to be optimized.
- flatten_order (Literal["F", "C"]): Order to use for flatten (choose between "F", "C"). Defaults to "F", which implements column-major flatten. In 2D, column-major flatten results in stacking rows horizontally to achieve a single horizontal row.

### Raises
- ValueError: When constrained zonotope is empty

### Returns
- tuple: A tuple with two items:
  #. constraint_list (list): CVXPY constraints for the containment of x in the constrained zonotope.
  #. xi (cvxpy.Variable | None): CVXPY variable representing the latent dimension variable. It is None,
```

--------------------------------

### Polytope Constructors

Source: https://merlresearch.github.io/pycvxset/api_summary/pycvxset.Polytope.html

Various ways to initialize a Polytope object.

```APIDOC
## Polytope Constructors

### Description
These are the different ways to initialize a Polytope object.

### Signatures
- `__init__(*args, dim: int)`: Initializes a Polytope of a given dimension.
- `__init__(*args, V: Sequence[Sequence[float]] | ndarray)`: Initializes a Polytope from a sequence of vertices.
- `__init__(*args, A: Sequence[Sequence[float]] | ndarray, b: Sequence[float] | ndarray)`: Initializes a Polytope from inequality constraints (Ax <= b).
- `__init__(*args, A: Sequence[Sequence[float]] | ndarray, b: Sequence[float] | ndarray, Ae: Sequence[Sequence[float]] | ndarray, be: Sequence[float] | ndarray)`: Initializes a Polytope from both inequality and equality constraints.
- `__init__(*args, lb: Sequence[float] | ndarray, ub: Sequence[float] | ndarray)`: Initializes a Polytope from lower and upper bounds.
- `__init__(*args, c: Sequence[float] | ndarray, h: float | Sequence[float] | ndarray)`: Initializes a Polytope from a center and radius (for a ball, a specific type of polytope).
```

--------------------------------

### ConstrainedZonotope Initialization from Polytope

Source: https://merlresearch.github.io/pycvxset/_modules/pycvxset/ConstrainedZonotope.html

Handles initialization from a polytope object. It requires the polytope to be convex and compact. If the polytope is empty, it initializes an empty constrained zonotope. Otherwise, it computes bounds and constraints to represent the polytope.

```python
elif polytope_passed:
            if len(kwargs) != 1:
                raise ValueError("Cannot construct constrained zonotope from polytope if other arguments are provided")
            polytope: Polytope | None = kwargs.get("polytope")
            if polytope is None or not is_polytope(polytope):
                raise ValueError("Expected a polytope when constructing a constrained zonotope.")
            self._is_full_dimensional, self._is_empty = polytope.is_full_dimensional, polytope.is_empty
            if not polytope.is_bounded:
                raise ValueError("Expected a convex and compact polytope!")
            elif polytope.is_empty:
                self._G, self._c, self._Ae, self._be = self._get_Gc_Aebe_for_empty_constrained_zonotope(polytope.dim, 0)
            else:
                if polytope.in_H_rep:
                    # Compute zonotope Z_0 ={G \xi + c| ||\xi||_\infty \leq 1, \xi\in R^n_g} s.t. polytope <= Z_0.
                    lb, ub = polytope.minimum_volume_circumscribing_rectangle()
                    Z_0 = self.__class__(lb=lb, ub=ub)

                    # sigma satisfies sigma <= H z <= k for all z \in polytope where H is polytope.A (using Scott's
                    # notation in the paper [SDGR16]_)
                    H = polytope.A
                    sigma, k = -polytope.support(-H)[0], polytope.b

                    # Implement (21) from Scott's paper (with additional equality constraints when needed)
```

--------------------------------

### Compute Volume of a Polytope

Source: https://merlresearch.github.io/pycvxset/tutorials/polytope.html

Computes the volume of a polytope using scipy.spatial.ConvexHull. This example verifies the volume of a unit l1-norm ball.

```python
L1_norm_ball = Polytope(V=np.vstack((np.eye(2), -np.eye(2))))
volume_of_an_isosceles_triangle_with_unit_base = 0.5
volume_of_unit_l1_norm_ball = L1_norm_ball.volume()
print(
    "Is the volume of the unit l1-norm ball 2?",
    np.isclose(
        volume_of_unit_l1_norm_ball,
        4 * volume_of_an_isosceles_triangle_with_unit_base,
    ),
)

```

--------------------------------

### CVXPY Solver Arguments

Source: https://merlresearch.github.io/pycvxset/_modules/pycvxset/Polytope.html

Properties to get and set arguments used by CVXPY for solving different types of optimization problems.

```APIDOC
## cvxpy_args_lp

### Description
CVXPY arguments in use when solving a linear program.

### Returns
- dict: CVXPY arguments in use for LP. Defaults to `pycvxset.common.DEFAULT_CVXPY_ARGS_LP`.

## cvxpy_args_lp.setter

### Description
Update CVXPY arguments in use when solving a linear program.

### Args
- value (dict): Dictionary with new CVXPY arguments for LP.

## cvxpy_args_socp

### Description
CVXPY arguments in use when solving a second-order cone program.

### Returns
- dict: CVXPY arguments in use for SOCP. Defaults to `pycvxset.common.DEFAULT_CVXPY_ARGS_SOCP`.

## cvxpy_args_socp.setter

### Description
Update CVXPY arguments in use when solving a second-order cone program.

### Args
- value (dict): Dictionary with new CVXPY arguments for SOCP.

## cvxpy_args_sdp

### Description
CVXPY arguments in use when solving a semi-definite program.

### Returns
- dict: CVXPY arguments in use for SDP. Defaults to `pycvxset.common.DEFAULT_CVXPY_ARGS_SDP`.

## cvxpy_args_sdp.setter

### Description
Update CVXPY arguments in use when solving a semi-definite program.

### Args
- value (dict): Dictionary with new CVXPY arguments for SDP.
```

--------------------------------

### ConstrainedZonotope Initialization from G and c

Source: https://merlresearch.github.io/pycvxset/_modules/pycvxset/ConstrainedZonotope.html

Handles initialization using the generator matrix G and center vector c. It supports both zonotopes (G, c) and constrained zonotopes (G, c, Ae, be). Includes validation for argument consistency and dimension matching.

```python
elif G_and_c_passed:
            # Either it is a zonotope (G, c) or a constrained zonotope (G, c, Ae, be)
            if len(kwargs) != 2 and (len(kwargs) != 4 and not Ae_and_be_passed):
                raise ValueError(
                    "Cannot set zonotope (G, c) or constrained zonotope (G, c, Ae, be) with other arguments"
                )
            G_val, c_val = sanitize_Gc(kwargs.get("G"), kwargs.get("c"))
            self._G, self._c = G_val, c_val
            if Ae_and_be_passed:
                sanitized_Ae, sanitized_be = sanitize_Aebe(kwargs.get("Ae"), kwargs.get("be"))
                if G_val.size == 0 and (sanitized_Ae is not None or sanitized_be is not None):
                    raise ValueError("When G is None and (Ae, be) was passed, then (Ae, be) must be (None, None)!")
                else:
                    if sanitized_Ae is None:
                        self._Ae, self._be = np.empty((0, self.dim)), np.empty((0,))
                    else:
                        self._Ae, self._be = sanitized_Ae, sanitized_be
                        if self.Ae.shape[1] != self.latent_dim:  # Check if (Ae, be) and (A, b) can go together?
                            raise ValueError(
                                f"Expected Ae to have {self.latent_dim:d} number of columns. Got Ae.shape: "
                                f"{self.Ae.shape}!"
                            )
                    # ConstrainedZonotope emptiness and full-dimensionality needs to be confirmed
            else:
                # Zonotope => Set only (Ae, be) to empty | Full-dimensionality needs to be confirmed
                _, _, self._Ae, self._be = self._get_Gc_Aebe_for_empty_constrained_zonotope(self.dim, self.latent_dim)
                self._is_empty = c_val is None
                if G_val.size == 0 and not self._is_empty:
                    self._is_full_dimensional = self.dim == 1
```

--------------------------------

### Polytope Initialization with H-Rep (A, b, Ae, be)

Source: https://merlresearch.github.io/pycvxset/_modules/pycvxset/Polytope.html

Initializes a Polytope using the H-representation, accepting both inequality (A, b) and equality (Ae, be) constraints. Supports initialization with only (A, b) or with both sets of constraints. Raises ValueError for invalid argument combinations.

```python
self._set_attributes_from_Ab_Aebe(kwargs.get("A"), kwargs.get("b"))
```

```python
self._set_attributes_from_Ab_Aebe(kwargs.get("A"), kwargs.get("b"), kwargs.get("Ae"), kwargs.get("be"))
```

--------------------------------

### Get Polytope Dimension

Source: https://merlresearch.github.io/pycvxset/_modules/pycvxset/Polytope.html

Returns the dimension of the polytope. For H-Rep, this is the number of columns in A. For V-Rep, it's the number of components in each vertex.

```python
return self._dim
```

--------------------------------

### Polytope Initialization with Bounds (c, h)

Source: https://merlresearch.github.io/pycvxset/_modules/pycvxset/Polytope.html

Initializes a Polytope using center (c) and half-range (h) bounds. Handles cases where h is a scalar or a 1D array, ensuring compatibility with c. Raises ValueError for invalid input types or shapes.

```python
c = np.atleast_1d(np.squeeze(kwargs.get("c"))).astype(float)
h = np.squeeze(kwargs.get("h")).astype(float)
if c.ndim >= 2:
    raise ValueError(
        f"Expected c to be a 1-dimensional array-like object! Got c: {np.array2string(np.array(c))}."
    )
if h.ndim >= 2:
    raise ValueError(
        "Expected h to be a 0-dimensional or 1-dimensional array-like object "
        f"Got {np.array2string(np.array(h))}."
    )
elif h.ndim == 1:
    if h.shape != c.shape:
        raise ValueError(
            "Expected c and 1-dimensional h to match in dimensions. Got {c.shape} and {h.shape}"
        )
    lb = c - h
    ub = c + h
else:
    lb = c - h * np.ones_like(c)
    ub = c + h * np.ones_like(c)
self._set_attributes_from_bounds(lb, ub)
```

--------------------------------

### Get Inequality Coefficients (A)

Source: https://merlresearch.github.io/pycvxset/_modules/pycvxset/Polytope.html

Returns the inequality coefficient matrix `A` for the polytope in H-Rep. If the polytope is not in H-Rep, it first calls `determine_H_rep()`. Returns an empty array for an empty polytope.

```python
if not self.in_H_rep:
    self.determine_H_rep()
return self._A
```

--------------------------------

### ConstrainedZonotope Initialization from Bounds

Source: https://merlresearch.github.io/pycvxset/_modules/pycvxset/ConstrainedZonotope.html

This method defines a ConstrainedZonotope from lower (lb) and upper (ub) bounds. It handles cases where the bounds define an empty set or a single point, and otherwise transforms the bounds into the G, c, Ae, be representation.

```python
    def _get_Gc_Aebe_from_bounds(
        self, lb: Sequence[float] | np.ndarray, ub: Sequence[float] | np.ndarray
    ) -> tuple[np.ndarray, Optional[np.ndarray], np.ndarray, np.ndarray, np.ndarray, np.ndarray]:
        r"""Define a zonotope from bounds (lb, ub), i.e., a zonotope that is equivalent to the polytope defined from the
        bounds (lb, ub).

        Args:
            lb (Sequence[float] | numpy.ndarray): Lower bound of the constrained zonotope.
            ub (Sequence[float] | numpy.ndarray): Upper bound of the constrained zonotope.

        Raises:
            ValueError: Mismatch in lb, ub shape
            ValueError: lb, ub is not convertible into 1D numpy float arrays

        Notes:
            When :math:`lb_i > ub_i` for any :math:`i`, then the zonotope is empty. Otherwise, we uses the following
            simple manipulations to define a zonotope from the bounds lb, ub:

            .. math ::
                newobj  &= {x\ |\ lb \leq x \leq ub}
                        &= {x\ |\ - (ub - lb)/2 \leq x - (ub + lb)/2 \leq + (ub - lb)/2}
                        &= {x\ |\ - d \leq x - c \leq d}
                        &= {x\ |\ -1 \leq diag(1./d)(x - c) \leq 1}
                        &= {diag(d)z + c\ |\ -1 \leq z \leq 1}

            Embedded zonotopes (some dimension is held constant) also have their latent dimension equal to set
            dimension.
        """
        try:
            lb_arr: np.ndarray = np.atleast_1d(np.squeeze(lb)).astype(float)
            ub_arr: np.ndarray = np.atleast_1d(np.squeeze(ub)).astype(float)
        except (TypeError, ValueError) as err:
            raise ValueError("Expected lb, ub to convertible into 1D float numpy arrays") from err
        if lb_arr.shape != ub_arr.shape or lb_arr.ndim != 1:
            raise ValueError("Expected lb, ub to 1D numpy arrays of same shape")
        elif np.any(ub_arr < lb_arr):
            return *self._get_Gc_Aebe_for_empty_constrained_zonotope(lb_arr.shape[0], 0), lb_arr, ub_arr
        elif np.allclose(lb_arr, ub_arr):
            G, _, Ae, be = self._get_Gc_Aebe_for_empty_constrained_zonotope(lb_arr.shape[0], 0)
            c = lb_arr
            return G, c, Ae, be, lb_arr, ub_arr
        else:
            dim, latent_dim = lb_arr.shape[0], lb_arr.shape[0]
            _, _, Ae, be = self._get_Gc_Aebe_for_empty_constrained_zonotope(dim, latent_dim)
            d = (ub_arr - lb_arr) / 2

```

--------------------------------

### Get Inequality Constants (b)

Source: https://merlresearch.github.io/pycvxset/_modules/pycvxset/Polytope.html

Returns the inequality constant vector `b` for the polytope in H-Rep. If the polytope is not in H-Rep, it first calls `determine_H_rep()`. Returns an empty array for an empty polytope.

```python
if not self.in_H_rep:
    self.determine_H_rep()
return cast(np.ndarray, self._b)
```

--------------------------------

### Initialize Optimization Vectors

Source: https://merlresearch.github.io/pycvxset/_modules/pycvxset/common.html

Initializes the vectors for the optimization process. If no points are to be spread, it returns standard axes. Otherwise, it sets up initial vectors for the difference of convex (DC) approach.

```python
if n_points_first_quad == 0:
            # Return the standard axes and their reflections
            opt_locations_first_quad = np.eye(dim)
            minimum_separation = float(np.sqrt(2))
            if verbose:
                print("Skipped spacing vectors! Returned the standard axes!")
        else:
            if verbose:
                print(f"Spreading {n_points_int} unit-length vectors in {dim}-dim space")
                print(f"Analyzing {n_points_first_quad} unit-length vectors in first quadrant")

            if cvxpy_socp_args is None:
                cvxpy_socp_args = DEFAULT_CVXPY_ARGS_SOCP

            # Difference of convex approach
            # INITIAL_TAU times SCALING_TAU ^ MAX_ITERATIONS = TAU_MAX
            MAX_ITERATIONS = SPOAUS_ITERATIONS_AT_TAU_MAX + int(
                np.log(SPOAUS_TAU_MAX) / (np.log(SPOAUS_SCALING_TAU) + np.log(SPOAUS_INITIAL_TAU))
            )

            # Initialize counter for iterations
            continue_condition = True
            tau_iter = SPOAUS_INITIAL_TAU
            iter_count = 1

            # Initialize vectors by assigning all along the unit-norm vector equidistant from all standard vectors
            x_iter = np.ones((n_points_first_quad, dim)) / np.sqrt(dim)

            # For DC approach, initialize the previous costs
            separation_prev = 0.0
            sum_slack_var_prev = 0.0
            objective_value_prev = 0.0
            cost_prev_with_new_tau_iter = 0.0
            while continue_condition:
```

--------------------------------

### Get Halfspace Representation (H)

Source: https://merlresearch.github.io/pycvxset/_modules/pycvxset/Polytope.html

Returns the combined inequality constraints `H = [A, b]` for the polytope in H-Rep. If the polytope is not in H-Rep, it first calls `determine_H_rep()`. Returns an empty array for an empty polytope.

```python
return np.hstack((self.A, np.array([self.b]).T))
```

--------------------------------

### Get CVXPY Constraints for Polytope Containment

Source: https://merlresearch.github.io/pycvxset/_modules/pycvxset/Polytope.html

Generates CVXPY constraints to ensure a variable `x` is contained within the polytope. Supports both H-Rep and V-Rep definitions. For V-Rep, it returns constraints involving a convex combination coefficient `theta`.

```python
import cvxpy as cp

x_reshaped = cp.reshape(x, (x.size,), order=flatten_order)
if self.in_V_rep:
    theta = cp.Variable((self.n_vertices,), nonneg=True)
    constraints: list[cp.Constraint] = [x_reshaped == self.V.T @ theta, cast(cp.Constraint, cp.sum(theta) == 1)]
    return constraints, theta
elif self.in_H_rep:
    polytope_containment_constraints: list[cp.Constraint] = [self.A @ x_reshaped <= self.b]
    if self.n_equalities > 0:
        polytope_containment_constraints += [self.Ae @ x_reshaped == self.be]
    return polytope_containment_constraints, None
else:
    raise ValueError("Containment constraints can not be generated for an empty polytope!")
```

--------------------------------

### Create Ellipsoids in Python

Source: https://merlresearch.github.io/pycvxset/tutorials/acc2025_code_snippets.html

Illustrates the creation of both full-dimensional and degenerate ellipsoids using center and quadratic/generator matrix definitions.

```python
from pycvxset import Ellipsoid

E1 = Ellipsoid(c=[2, -1], Q=np.diag([1, 4]))
print("E1 is an", E1)
E2 = Ellipsoid(c=[0, 1, 0], G=np.diag([1, 2, 3]))
print("E2 is an", E2)
```

--------------------------------

### ConstrainedZonotope Initialization from Bounds

Source: https://merlresearch.github.io/pycvxset/_modules/pycvxset/ConstrainedZonotope.html

Handles initialization when lower (lb) and upper (ub) bounds are provided. It validates input dimensions and types, converting them to numpy arrays. It also determines if the zonotope is full-dimensional or empty based on the bounds.

```python
except (TypeError, ValueError) as err:
                    raise ValueError(
                        "Expected c and h to be convertible into a numpy 1D array and scalar/1D array of "
                        f"float respectively! Got c: {np.array2string(np.array(kwargs.get('c')))} and "
                        f"h: {np.array2string(np.array(kwargs.get('h')))}"
                    ) from err
                if c.ndim >= 2:
                    raise ValueError(
                        f"Expected c to be a 1-dimensional array-like object! Got c: {np.array2string(np.array(c))}."
                    )
                if h.ndim >= 2:
                    raise ValueError(
                        "Expected h to be a 0-dimensional or 1-dimensional array-like object "
                        f"Got {np.array2string(np.array(h))}."
                    )
                elif h.ndim == 1:
                    if h.shape != c.shape:
                        raise ValueError(
                            "Expected c and 1-dimensional h to match in dimensions. Got {c.shape} and {h.shape}"
                        )
                    lb = c - h
                    ub = c + h
                else:
                    lb = c - h * np.ones_like(c)
                    ub = c + h * np.ones_like(c)
            self._G, self._c, self._Ae, self._be, lb, ub = self._get_Gc_Aebe_from_bounds(lb, ub)
            self._is_full_dimensional = (self.dim == 1) or (np.abs(ub - lb) > PYCVXSET_ZERO).all()
            self._is_empty = self.c is None
```

--------------------------------

### Check Polytope Containment and Equality

Source: https://merlresearch.github.io/pycvxset/tutorials/polytope.html

Use the `contains` method or overloaded operators (`<=`, `<`, `>=`, `>`, `in`) to check if one polytope covers another. Equality can be checked with `==`. This example visualizes two pairs of polytopes and prints the results of various containment and equality checks.

```python
P5 = 0.5 * (
    OLD_POLYTOPE_1 - OLD_POLYTOPE_1.interior_point("centroid")
) + OLD_POLYTOPE_1.interior_point("centroid")
fig, ax = plt.subplots(1, 2)
OLD_POLYTOPE_1.plot(
    ax=ax[0], patch_args={\"facecolor\": OLD_POLYTOPE_COLOR_1, \"label\": \"P1\"}
)
P5.plot(ax=ax[0], patch_args={\"facecolor\": \"black\", \"label\": \"P5\"})
ax[0].legend(loc=\"best\")
print(f"Does P1 cover P5? {OLD_POLYTOPE_1.contains(P5)}")
print(f"Is P1 >= P5? {OLD_POLYTOPE_1 >= P5}")
print(f"Is P1 > P5? {OLD_POLYTOPE_1 > P5}")
print(f"Is P5 in P1? {P5 in OLD_POLYTOPE_1}")
print(f"Is P1 <= P5? {OLD_POLYTOPE_1 <= P5}")
print(f"Is P1 < P5? {OLD_POLYTOPE_1 < P5}")
print(f"Is P1 in P5? {OLD_POLYTOPE_1 in P5}")
OLD_POLYTOPE_2.plot(
    ax=ax[1], patch_args={\"facecolor\": OLD_POLYTOPE_COLOR_2, \"label\": \"P2\"}
)
P4.plot(ax=ax[1], patch_args={\"facecolor\": \"grey\", \"label\": \"P4\"})
ax[1].legend(loc=\"best\")
print(f"

Does P2 cover P4? {OLD_POLYTOPE_2.contains(P4)}")
print(f"Is P2 >= P4? {OLD_POLYTOPE_2 >= P4}")
print(f"Is P2 > P4? {OLD_POLYTOPE_2 > P4}")
print(f"Is P4 in P2? {P4 in OLD_POLYTOPE_2}")
print(f"Is P2 <= P4? {OLD_POLYTOPE_2 <= P4}")
print(f"Is P2 < P4? {OLD_POLYTOPE_2 < P4}")
print(f"Is P2 in P4? {OLD_POLYTOPE_2 in P4}")
plt.suptitle("Containment check for two sets of polytopes");
```

```text
Does P1 cover P5? True
Is P1 >= P5? True
Is P1 > P5? True
Is P5 in P1? True
Is P1 <= P5? False
Is P1 < P5? False
Is P1 in P5? False


Does P2 cover P4? False
Is P2 >= P4? False
Is P2 > P4? False
Is P4 in P2? False
Is P2 <= P4? False
Is P2 < P4? False
Is P2 in P4? False

```

--------------------------------

### Polytope Initialization from Bounds

Source: https://merlresearch.github.io/pycvxset/_modules/pycvxset/Polytope.html

Initializes a Polytope object using lower and upper bounds for each dimension. This method handles cases where bounds define a single vertex, inequalities, or a combination of both.

```APIDOC
## Polytope Initialization from Bounds

### Description
Initializes a Polytope object using lower and upper bounds for each dimension. This method handles cases where bounds define a single vertex, inequalities, or a combination of both.

### Method
`__init__(self, lb, ub)`

### Parameters
- **lb** (numpy.ndarray): Lower bounds for each dimension.
- **ub** (numpy.ndarray): Upper bounds for each dimension.

### Notes
- When `lb == ub`, a polytope in V-Rep (a single vertex) is generated.
- Otherwise, a polytope in H-Rep (defined by inequalities) is generated.
- Raises `ValueError` if `lb` and `ub` are not convertible to 1D float numpy arrays of the same shape, or if the polytope is not bounded in some directions.
```

--------------------------------

### ConstrainedZonotope Initialization Logic

Source: https://merlresearch.github.io/pycvxset/_modules/pycvxset/ConstrainedZonotope.html

Handles the initialization of the ConstrainedZonotope class by checking the provided keyword arguments and setting the internal attributes (_G, _c, _Ae, _be, _is_full_dimensional, _is_empty). It supports initialization from dimension, bounds, center and half-side length, or generators and center.

```python
def __init__(self, **kwargs: Any) -> None:
    """Constructor for ConstrainedZonotope class"""
    self._type_of_set: str = "ConstrainedZonotope"
    self._G: Optional[np.ndarray] = None
    self._c: Optional[np.ndarray] = None
    self._Ae: Optional[np.ndarray] = None
    self._be: Optional[np.ndarray] = None
    self._is_full_dimensional: Optional[bool] = None
    self._is_empty: Optional[bool] = None
    self._is_singleton: Optional[bool] = None
    # These attributes are used by CVXPY to solve problems
    self._cvxpy_args_lp = DEFAULT_CVXPY_ARGS_LP
    self._cvxpy_args_socp = DEFAULT_CVXPY_ARGS_SOCP

    # Check how the constructor was called.
    empty_constrained_zonotope_passed = ("dim" in kwargs) or not kwargs
    lb_and_ub_passed = all(kw in kwargs for kw in ("lb", "ub"))
    c_and_h_passed = all(kw in kwargs for kw in ("c", "h"))
    G_and_c_passed = all(k in kwargs for k in ("G", "c"))
    Ae_and_be_passed = all(k in kwargs for k in ("Ae", "be"))
    polytope_passed = "polytope" in kwargs

    # Set _G, _c, _Ae, _be, _is_empty, _is_full_dimensional
    if empty_constrained_zonotope_passed:
        if len(kwargs) > 1:
            raise ValueError("Cannot set dimension dim with other arguments")
        else:
            dim = kwargs.get("dim", 0)
            self._G, self._c, self._Ae, self._be = self._get_Gc_Aebe_for_empty_constrained_zonotope(dim, 0)
            self._is_full_dimensional, self._is_empty = (dim == 0), True
    elif lb_and_ub_passed or c_and_h_passed:
        if lb_and_ub_passed:
            if len(kwargs) != 2:
                raise ValueError("Cannot set bounds (lb, ub) with other arguments")
            lb, ub = kwargs.get("lb"), kwargs.get("ub")
        else:  # We have c_and_h_passed is True
            if len(kwargs) != 2:
                raise ValueError("Cannot set up constrained zonotope from (c, h) with other arguments")
            try:
                c = np.atleast_1d(np.squeeze(kwargs.get("c"))).astype(float)
                h = np.squeeze(kwargs.get("h")).astype(float)

```

--------------------------------

### copy

Source: https://merlresearch.github.io/pycvxset/api_summary/pycvxset.Polytope.html

Create a copy of the polytope.

```APIDOC
## copy

### Description
Create a copy of the polytope.

### Method
`copy()`
```

--------------------------------

### Create Constrained Zonotopes in Python

Source: https://merlresearch.github.io/pycvxset/tutorials/acc2025_code_snippets.html

Shows how to create constrained zonotopes from existing polytopes or by specifying bounds. The library automatically detects if a constrained zonotope is also a zonotope.

```python
from pycvxset import ConstrainedZonotope

C1 = ConstrainedZonotope(polytope=P1)
print("C1 is a", repr(C1))
print("P1 is a", repr(P1))
C2 = ConstrainedZonotope(lb=[-1, -1], ub=[1, 1])
print("C2 is a", repr(C2))
```

--------------------------------

### Ellipsoid Initialization as a Ball

Source: https://merlresearch.github.io/pycvxset/_modules/pycvxset/Ellipsoid.html

Initialize an Ellipsoid as a ball with a given center (c) and radius (r).

```python
Ellipsoid(c=np.array([1, 2]), r=5.0)
```

--------------------------------

### Ellipsoid Initialization as a Singleton

Source: https://merlresearch.github.io/pycvxset/_modules/pycvxset/Ellipsoid.html

Initialize an Ellipsoid as a singleton set defined by its center (c).

```python
Ellipsoid(c=np.array([1, 2]))
```
Tokens:
Raw