picos.expressions.vectorizations

Implement special matrix vectorization formats.

These formats are used to efficiently store structured variable types such as symmetric matrix variables in the form of real variable vectors.

Outline

Classes

BaseVectorization

Abstract base class for special matrix vectorization formats.

ComplexVectorization

An isometric vectorization that stacks real and imaginary parts.

FullVectorization

A basic column-major matrix vectorization.

HermitianVectorization

An isometric hermitian matrix vectorization.

LowerTriangularVectorization

An isometric lower triangular matrix vectorization.

SkewSymmetricVectorization

An isometric skew-symmetric matrix vectorization.

SymmetricVectorization

An isometric symmetric matrix vectorization.

UpperTriangularVectorization

An isometric upper triangular matrix vectorization.

Classes

BaseVectorization

class picos.expressions.vectorizations.BaseVectorization(shape)[source]

Bases: abc.ABC, object

Abstract base class for special matrix vectorization formats.

Subclass instances are cached: If multiple instances of the same vectorization format and concerning matrices of the same shape are requested successively, then the instance created to serve the first request is retrieved from a cache on successive requests. The module attributes CACHE_SIZE and CACHE_BULK_REMOVE control the size of the cache for each vectorization format.

Warning

Due to how caching is implemented, derived classes may not inherit from each other but only from BaseVectorization directly!

__init__(shape)[source]

Initialize a vectorization format for a fixed matrix shape.

static __new__(cls, shape)[source]

Lookup or create a vectorization format for a fixed matrix shape.

devectorize(vector)[source]

Given a special vectorization, return the corresponding matrix.

Raises

TypeError – If the input isn’t a CVXOPT column vector or does not have the expected numeric type or length.

vectorize(matrix)[source]

Given a matrix, return its special vectorization.

Raises
  • TypeError – If the input isn’t a CVXOPT matrix or does not have the expected numeric type or shape.

  • ValueError – If the matrix does not have the expected structure.

property dim

The length of the vectorization.

This corresponds to the dimension of a matrix variable being vectorized.

property identity

A linear mapping from the special to the full vectorization.

The term identity comes from the fact that these matrices are used as the coefficients that map the internal (vectorized) representation of a BaseVariable object to the ComplexAffineExpression that it represents.

property shape

The shape of matrices being vectorized.

ComplexVectorization

class picos.expressions.vectorizations.ComplexVectorization(shape)[source]

Bases: picos.expressions.vectorizations.BaseVectorization

An isometric vectorization that stacks real and imaginary parts.

vectorize(matrix)[source]

Override BaseVectorization.vectorize.

This is necessary because extracting the real and the imaginary part cannot be done with a linear transformation matrix as is done for other vectorization formats.

FullVectorization

class picos.expressions.vectorizations.FullVectorization(shape)[source]

Bases: picos.expressions.vectorizations.BaseVectorization

A basic column-major matrix vectorization.

devectorize(vector)[source]

Override BaseVectorization.devectorize for speed reasons.

vectorize(matrix)[source]

Override BaseVectorization.vectorize for speed reasons.

HermitianVectorization

class picos.expressions.vectorizations.HermitianVectorization(shape)[source]

Bases: picos.expressions.vectorizations.BaseVectorization

An isometric hermitian matrix vectorization.

The vectorization is isometric with respect to the Hermitian inner product \langle A, B \rangle = \operatorname{tr}(B^H A) on the matrices and the real dot product on their vectorizations.

__init__(shape)[source]

Initialize a vectorization format for hermitian matrices.

Uses SymmetricVectorization (for the real part) and SkewSymmetricVectorization (for the imaginary part) internally.

vectorize(matrix)[source]

Override BaseVectorization.vectorize.

This is necessary because extracting the real and the imaginary part cannot be done with a linear transformation matrix as is done for other vectorization formats.

LowerTriangularVectorization

class picos.expressions.vectorizations.LowerTriangularVectorization(shape)[source]

Bases: picos.expressions.vectorizations.BaseVectorization

An isometric lower triangular matrix vectorization.

SkewSymmetricVectorization

class picos.expressions.vectorizations.SkewSymmetricVectorization(shape)[source]

Bases: picos.expressions.vectorizations.BaseVectorization

An isometric skew-symmetric matrix vectorization.

SymmetricVectorization

class picos.expressions.vectorizations.SymmetricVectorization(shape)[source]

Bases: picos.expressions.vectorizations.BaseVectorization

An isometric symmetric matrix vectorization.

See [svec] for the precise vectorization used.

svec

Dattorro, J. (2018). Isomorphism of symmetric matrix subspace. In Convex Optimization & Euclidean Distance Geometry (2nd ed.) (pp. 47f.). California, Meboo Publishing USA. Retrieved from https://meboo.convexoptimization.com/Meboo.html.

UpperTriangularVectorization

class picos.expressions.vectorizations.UpperTriangularVectorization(shape)[source]

Bases: picos.expressions.vectorizations.BaseVectorization

An isometric upper triangular matrix vectorization.

Data

picos.expressions.vectorizations.CACHE_BULK_REMOVE

Number of cached instances to drop at random when the cache is full.

picos.expressions.vectorizations.CACHE_SIZE

Number of instances to cache per vectorization format.