picos.expressions.vectorizations

Implement special matrix vectorization formats.

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

Classes

class picos.expressions.vectorizations.BaseVectorization(shape)

Bases: 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)

Initialize a vectorization format for a fixed matrix shape.

static __new__(cls, shape)

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

devectorize(vector)

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)

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 mutable 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 Mutable object to the BiaffineExpression instance that represents the mutable in algebraic operations.

property shape

The shape of matrices being vectorized.

class picos.expressions.vectorizations.ComplexVectorization(shape)

Bases: BaseVectorization

An isometric vectorization that stacks real and imaginary parts.

vectorize(matrix)

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.

class picos.expressions.vectorizations.FullVectorization(shape)

Bases: BaseVectorization

A basic column-major matrix vectorization.

devectorize(vector)

Override BaseVectorization.devectorize for speed reasons.

vectorize(matrix)

Override BaseVectorization.vectorize for speed reasons.

class picos.expressions.vectorizations.HermitianVectorization(shape)

Bases: BaseVectorization

An isometric hermitian matrix vectorization.

The vectorization is isometric with respect to the Hermitian inner product on the matrices and the real dot product on their vectorizations.

__init__(shape)

Initialize a vectorization format for hermitian matrices.

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

vectorize(matrix)

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.

class picos.expressions.vectorizations.LowerTriangularVectorization(shape)

Bases: BaseVectorization

An isometric lower triangular matrix vectorization.

class picos.expressions.vectorizations.SkewSymmetricVectorization(shape)

Bases: BaseVectorization

An isometric skew-symmetric matrix vectorization.

class picos.expressions.vectorizations.SymmetricVectorization(shape)

Bases: 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.

class picos.expressions.vectorizations.UpperTriangularVectorization(shape)

Bases: BaseVectorization

An isometric upper triangular matrix vectorization.

Objects

picos.expressions.vectorizations.CACHE_BULK_REMOVE

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

Default value

25

picos.expressions.vectorizations.CACHE_SIZE

Number of instances to cache per vectorization format.

Default value

100