picos.expressions.exp_affine

Implements affine expression types.

Classes

class picos.expressions.exp_affine.AffineExpression(string, shape=(1, 1), coefficients={})[source]

Bases: picos.expressions.exp_affine.ComplexAffineExpression

A multidimensional real affine expression.

__eq__(other)[source]

Return an equality constraint concerning the expression.

__ge__(other)[source]

Return a constraint that the expression is lower-bounded.

__le__(other)[source]

Return a constraint that the expression is upper-bounded.

property H

The regular transpose of the AffineExpression.

property conj

The AffineExpression as is.

property exp[source]

The exponential function applied to the expression.

property imag[source]

A zero of same shape as the AffineExpression.

property isreal

Always true for AffineExpression instances.

property log[source]

The Logarithm of the expression.

property real

The AffineExpression as is.

class picos.expressions.exp_affine.ComplexAffineExpression(string, shape=(1, 1), coefficients={})[source]

Bases: picos.expressions.exp_biaffine.BiaffineExpression

A multidimensional (complex) affine expression.

Base class for the real AffineExpression.

__abs__()[source]

Denote the default norm of the expression.

The norm used depends on the expression’s domain. It is

  1. the absolute value of a real scalar,

  2. the modulus of a complex scalar,

  3. the Euclidean norm of a vector, and

  4. the Frobenius norm of a matrix.

__eq__(other)[source]

Return an equality constraint concerning the expression.

__mul__(other)[source]

Denote multiplication with another expression on the right.

__or__(other)[source]

Denote the scalar product with another expression on the right.

For (complex) vectors a and b this is the dot product

(a \mid b)
&= \langle a, b \rangle \\
&= a \cdot b \\
&= b^H a.

For (complex) matrices A and B this is the Frobenius inner product

(A \mid B)
&= \langle A, B \rangle_F \\
&= A : B \\
&= \operatorname{tr}(B^H A) \\
&= \operatorname{vec}(B)^H \operatorname{vec}(\overline{A})

Note

Write (A|B) instead of A|B for the scalar product of A and B to obtain correct operator binding within a larger expression context.

__xor__(other)[source]

Denote the entrywise product with another expression on the right.

scipy_sparse_matrix_form(varOffsetMap, *, offset=0, padding=0, dense_b=False)[source]

Like sparse_matrix_form but returns SciPy types.

See sparse_matrix_form for details and arguments.

Returns tuple(scipy.sparse.csc_matrix)

A pair (A, b) of SciPy sparse matrices in CSC format representing the matrix A and the column vector b. (If dense_b=True, then b is returned as a 1-D NumPy array instead.)

Raises

ModuleNotFoundError – If the optional dependency scipy is not installed.

sparse_matrix_form(varOffsetMap, *, offset=0, padding=0, dense_b=False)[source]

Return a representation suited for embedding in constraint matrices.

This computes a sparse matrix A and a sparse column vector b such that Ax + b represents the vectorized expression, where x is a vertical concatenation of a number of variables, including those that appear in the expression. The size and ordering of x is given through varOffsetMap, which maps PICOS variables to their starting position within x.

If the optional parameters offset and padding are given, then both A and b are padded with zero rows from above and below, respectively.

This method is used by PICOS internally to assemble constraint matrices.

Parameters
  • varOffsetMap (dict) – Maps variables to column offsets.

  • offset (int) – Number of zero rows to insert at the top of A and b.

  • offset – Number of zero rows to insert at the bottom of A and b.

  • dense_b (bool) – Whether to return b as a dense vector. Not compatible with nonzero offset or padding.

Returns tuple(cvxopt.spmatrix)

A pair (A, b) of CVXOPT sparse matrices representing the matrix A and the column vector b. (If dense_b=True, then b is returned as a dense CVXOPT column vector instead.)

sparse_rows(varOffsetMap)[source]

Yield a sparse list representation of the expression.

This is similar to sparse_matrix_form (with default arguments) but instead of returning A and b at once, this yields for every row of [A \mid b], each representing a scalar entry of the expression’s vectorization, a triplet containing a list of column indices and values of that row of A and the entry of b.

Parameters

varOffsetMap – Maps variables to column offsets.

Yields tuple(list, list, float)

Triples (J, V, c) where J contains column indices (representing scalar variables), V contains coefficients for each column index, and where c is a constant term.

property imag[source]

Override imag.

The result is returned as an AffineExpression.

property real[source]

Override real.

The result is returned as an AffineExpression.

Functions

picos.expressions.exp_affine.Constant(name_or_value, value=None, shape=None)[source]

Create a constant PICOS expression.

Loads the given numeric value as a constant ComplexAffineExpression or AffineExpression, depending on the value. Optionally, the value is broadcasted or reshaped according to the shape argument.

Parameters
  • name_or_value (str) – Symbolic string description of the constant. If None or the empty string, a string will be generated. If this is the only positional parameter (i.e.``value`` is not given), then this position is used as the value argument instead!

  • value – The numeric constant to load.

See load_data for supported data formats and broadcasting and reshaping rules.

Example

>>> from picos import Constant
>>> Constant(1)
<1×1 Real Constant: 1>
>>> Constant(1, shape=(2, 2))
<2×2 Real Constant: [1]>
>>> Constant("one", 1)
<1×1 Real Constant: one>
>>> Constant("J", 1, (2, 2))
<2×2 Real Constant: J>