pycvxset.Ellipsoid

class pycvxset.Ellipsoid(**kwargs)[source]

Bases: object

Ellipsoid class.

We can define a bounded, non-empty ellipsoid \(\mathcal{P}\) using one of the following combinations:

  1. \((c, Q)\) for a full-dimensional ellipsoid in the quadratic form \(\mathcal{P}=\{x \in \mathbb{R}^n\ |\ (x - c)^T Q^{-1} (x - c) \leq 1\}\) with a n-dimensional positive-definite matrix \(Q\) and a n-dimensional vector \(c\). Here, pycvxset computes a n-dimensional lower-triangular, square matrix \(G\) that satisfies \(GG^T=Q\).

  2. \((c, G)\) for a full-dimensional or a degenerate ellipsoid as an affine transformation of a unit-ball \(\mathcal{P} = \{x \in \mathbb{R}^n\ |\ \exists u\in\mathbb{R}^N,\ x = c + G u,\ {\|u\|}_2 \leq 1\}\) with a n x N matrix \(G\). Here, pycvxset computes \(Q=GG^T\).

Parameters:

  • c (array_like) – Center of the ellipsoid c. Vector of length (self.dim,)

  • Q (array_like, optional) – Shape matrix of the ellipsoid Q. Q must be a positive definite matrix (self.dim times self.dim).

  • G (array_like, optional) – Square root of the shape matrix of the ellipsoid G that satisfies \(GG^T=Q\). Need not be a square matrix, but must have self.dim rows.

  • r (scalar, optional) – Non-negative scalar that provides the radius of the self.dim-dimensional ball.

Raises:

  • ValueError – When more than one of Q, G, r was provided

  • ValueError – When c or Q or G or r does not satisfy implicit properties

Notes

  1. Empty ellipsoids are not permitted (c is a required keyword argument).

  2. When provided G is such that \(Q=GG^T\) is positive definite, we overwrite \(G\) with a lower-triangular, square, n-dimensional matrix for consistency. Here, \(G\) has strictly positive diagonal elements, and its determinant is the product of its diagonal elements (see volume computation).

  3. We use the eigenvalues of \(Q\) to determine the radii of the maximum volume inscribing ball (Chebyshev radius \(R^-\)) and the minimum volume circumscribing ball \(R^+\geq R^-\).

    1. The ellipsoid represents a singleton when \(R^+\) is negligible.

    2. The ellipsoid is full-dimensional when \(R^-\) is non-trivial.

__init__(**kwargs)[source]

Constructor for Ellipsoid

Methods

__init__(**kwargs)

Constructor for Ellipsoid

affine_hull()

Compute the left null space of self.G to identify the affine hull.

affine_map(M)

Compute the affine transformation of the given ellipsoid based on a given scalar/matrix.

chebyshev_centering()

Compute the Chebyshev center and radius of the ellipsoid.

closest_point(points[, p])

Wrapper for project() to compute the point in the convex set closest to the given point.

containment_constraints(x[, flatten_order])

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

contains(Q)

Check containment of a set or a collection of points in an ellipsoid.

copy()

Create a copy of the ellipsoid.

deflate(set_to_be_centered)

Compute the minimum volume ellipsoid that covers the given set (also known as Lowner-John Ellipsoid).

distance(points[, p])

Wrapper for project() to compute distance of a point to a convex set.

extreme(eta)

Wrapper for support() to compute the extreme point.

inflate(set_to_be_centered)

Compute the maximum volume ellipsoid that fits within the given set.

inflate_ball(set_to_be_centered)

Compute the largest ball (Chebyshev ball) of a given set.

interior_point()

Compute an interior point to the Ellipsoid

intersection_with_affine_set(Ae, be)

Compute the intersection of an ellipsoid with an affine set.

inverse_affine_map_under_invertible_matrix(M)

Compute the inverse affine transformation of an ellipsoid based on a given scalar/matrix.

maximum_volume_inscribing_ellipsoid()

Compute the maximum volume inscribing ellipsoid for a given ellipsoid.

minimize(x, objective_to_minimize, cvxpy_args)

Solve a convex program with CVXPY objective subject to containment constraints.

minimum_volume_circumscribing_ball()

Compute the radius of the ball that circumscribes the ellipsoid and has the minimum volume.

minimum_volume_circumscribing_ellipsoid()

Compute the minimum volume circumscribing ellipsoid for a given ellipsoid.

minimum_volume_circumscribing_rectangle()

Compute the minimum volume circumscribing rectangle for a set.

plot([method, ax, direction_vectors, ...])

Plot a polytopic approximation of the set.

plus(point)

Add a point to an ellipsoid

polytopic_inner_approximation([...])

Compute a polytopic inner-approximation of a given set via ray shooting.

polytopic_outer_approximation([...])

Compute a polytopic outer-approximation of a given set via ray shooting.

project(x[, p])

Project a point or a collection of points on to a set.

projection(project_away_dims)

Orthogonal projection of a set \(\mathcal{P}\) after removing some user-specified dimensions.

quadratic_form_as_a_symmetric_matrix()

Define a (self.dim + 1)-dimensional symmetric matrix M where self = {x | [x, 1] @ M @ [x, 1] <= 0}.

slice(dims, constants)

Slice a set restricting certain dimensions to constants.

slice_then_projection(dims, constants)

Wrapper for slice() and projection().

support(eta)

Evaluates the support function and support vector of a set.

volume()

Compute the volume of the ellipsoid.

Attributes

G

Affine transformation matrix \(G\) that satisfies \(GG^T=Q\)

Q

Shape matrix of the ellipsoid \(Q\)

c

Center of the ellipsoid \(c\)

cvxpy_args_lp

CVXPY arguments in use when solving a linear program

cvxpy_args_sdp

CVXPY arguments in use when solving a semi-definite program

cvxpy_args_socp

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

dim

Dimension of the ellipsoid \(dim\)

is_empty

Check if the ellipsoid is empty.

is_full_dimensional

Check if the ellipsoid is full-dimensional, i.e., sqrt of all eigenvalues of Q are above PYCVXSET_ZERO

is_singleton

Check if the ellipsoid is a singleton, i.e., sqrt of all eigenvalues of Q are below PYCVXSET_ZERO

latent_dim

Latent dimension of the ellipsoid \(dim\)