picos.expressions

Mathematical expression types.

Outline

Classes

AffineExpression

A multidimensional real affine expression.

Ball

A ball of radius r according to a (generalized) p-norm.

BaseVariable

Primary base class for all variable types.

BinaryVariable

A \{0,1\}-valued variable.

ComplexAffineExpression

A multidimensional complex affine expression.

ComplexVariable

A complex-valued variable.

DetRootN

The n-th root of the determinant of an n\times n matrix.

Entropy

Entropy or negative relative entropy of an affine expression.

ExponentialCone

The exponential cone.

Expression

Abstract base class for mathematical expressions, including variables.

ExpressionType

The detailed type of an expression for predicting constraint outcomes.

GeometricMean

Geometric mean of an affine expression.

HermitianVariable

A hermitian matrix variable.

IntegerVariable

An integer-valued variable.

LogSumExp

Logarithm of the sum of elementwise exponentials of an expression.

Logarithm

Logarithm of a scalar affine expression.

LowerTriangularVariable

A lower triangular matrix variable.

NegativeEntropy

Negative or relative entropy of an affine expression.

Norm

Entrywise p-norm or L_{p,q}-norm of an expression.

NuclearNorm

The nuclear norm of a matrix.

PowerTrace

The trace of the p-th power of a hermitian matrix.

QuadraticExpression

A scalar quadratic expression of the form x^TQx + a^Tx + b.

RealVariable

A real-valued variable.

RotatedSecondOrderCone

The (narrowed or widened) rotated second order cone.

SecondOrderCone

The second order cone.

Set

Abstract base class for mathematical set expressions.

SetType

ExpressionType for sets.

Simplex

A (truncated, symmetrized) real simplex.

SkewSymmetricVariable

A skew-symmetric matrix variable.

SpectralNorm

The spectral norm of a matrix.

SumExponentials

Sum of elementwise exponentials of an affine expression.

SumExtremes

Sum of the k largest or smallest elements or eigenvalues.

SymmetricVariable

A symmetric matrix variable.

UpperTriangularVariable

An upper triangular matrix variable.

Functions

Constant

Create a constant PICOS expression.

ball

Legacy shorthand for Ball.

detrootn

Legacy shorthand for DetRootN.

diag

Form a diagonal matrix from the column-major vectorization of x.

diag_vect

Extract the diagonal of x as a column vector.

exp

Denote the exponential.

expcone

Shorthand for ExponentialCone.

flow_Constraint

Legacy shorthand for FlowConstraint.

geomean

Shorthand for GeometricMean.

kldiv

Shorthand for NegativeEntropy.

kron

Denote the kronecker product.

kullback_leibler

Legacy shorthand for NegativeEntropy.

lambda_max

Wrapper for SumExtremes.

lambda_min

Wrapper for SumExtremes.

log

Denote the natural logarithm.

logsumexp

Legacy shorthand for LogSumExp.

lse

Shorthand for LogSumExp.

maindiag

Extract the diagonal of x as a column vector.

max

Wrapper for SumExtremes.

min

Wrapper for SumExtremes.

new_param

Create a constant or a list or dict or tuple thereof.

norm

Legacy shorthand for Norm.

partial_trace

See expressions.ComplexAffineExpression.partial_trace.

partial_transpose

See expressions.ComplexAffineExpression.partial_transpose.

rsoc

Shorthand for RotatedSecondOrderCone.

simplex

Create a standard simplex of radius \gamma.

soc

Shorthand for SecondOrderCone.

sum

Sum PICOS expressions and give the result a meaningful description.

sum_k_largest

Wrapper for SumExtremes.

sum_k_largest_lambda

Wrapper for SumExtremes.

sum_k_smallest

Wrapper for SumExtremes.

sum_k_smallest_lambda

Wrapper for SumExtremes.

sumexp

Shorthand for SumExponentials.

trace

Denote the trace of a square matrix.

tracepow

Legacy shorthand for PowerTrace.

truncated_simplex

Create a truncated simplex of radius \gamma.

Exceptions

NotValued

The operation cannot be performed due to a variable without a value.

Submodules

picos.expressions.algebra

Implements functions that create or modify algebraic expressions.

picos.expressions.data

Functions to load and work with raw numeric data.

picos.expressions.exp_affine

Implements affine expression types.

picos.expressions.exp_detrootn

Implements DetRootN.

picos.expressions.exp_entropy

Implements Entropy and NegativeEntropy.

picos.expressions.exp_geomean

Implements GeometricMean.

picos.expressions.exp_logarithm

Implements Logarithm.

picos.expressions.exp_logsumexp

Implements LogSumExp.

picos.expressions.exp_norm

Implements Norm.

picos.expressions.exp_powtrace

Implements PowerTrace.

picos.expressions.exp_quadratic

Implements QuadraticExpression.

picos.expressions.exp_sumexp

Implements SumExponentials.

picos.expressions.exp_sumxtr

Implements SumExtremes.

picos.expressions.expression

Backend for expression type implementations.

picos.expressions.set

Backend for mathematical set type implementations.

picos.expressions.set_ball

Implements Ball.

picos.expressions.set_expcone

Implements ExponentialCone.

picos.expressions.set_rsoc

Implements RotatedSecondOrderCone.

picos.expressions.set_simplex

Implements Simplex.

picos.expressions.set_soc

Implements SecondOrderCone.

picos.expressions.variables

Implements all mathematical variable types.

picos.expressions.vectorizations

Implement special matrix vectorization formats.

Classes

AffineExpression

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

Bases: picos.expressions.exp_affine.ComplexAffineExpression

A multidimensional real affine expression.

property H

The regular transpose of the AffineExpression.

property conj

The AffineExpression as is.

property exp

The exponential function applied to the expression.

property imag

A zero of same shape as the AffineExpression.

property isreal

Always true for AffineExpression instances.

property log

The Logarithm of the expression.

property real

The AffineExpression as is.

Ball

class picos.expressions.Ball(radius=<1×1 Real Constant: 1>, p=2, denominator_limit=1000)[source]

Bases: picos.expressions.set.Set

A ball of radius r according to a (generalized) p-norm.

Definition

In the following, \lVert \cdot \rVert_p refers to the vector p-norm or to the entrywise matrix p-norm, depending on the argument. See Norm for definitions.

Let r \in \mathbb{R}.

  1. For p \in [1, \inf), this is the convex set

    \{x \in \mathbb{K} \mid \lVert x \rVert_p \leq r\}

    for any

    \mathbb{K} \in \bigcup_{m, n \in \mathbb{Z}_{\geq 1}}
    \left( \mathbb{C}^n \cup \mathbb{C}^{m \times n} \right).

  2. For a generalized p-norm with p \in (0, 1), this is the convex set

    \{x \in \mathbb{R} \mid \lVert x \rVert_p \geq r \land x \geq 0\}

    for any

    \mathbb{K} \in \bigcup_{m, n \in \mathbb{Z}_{\geq 1}}
    \left( \mathbb{R}^n \cup \mathbb{R}^{m \times n} \right).

Note that x may not be complex if p < 1 due to the implicit x \geq 0 constraint in this case, which is not meaningful on the complex field.

Note further that r may be any scalar affine expression, it does not need to be constant.

__init__(radius=<1×1 Real Constant: 1>, p=2, denominator_limit=1000)[source]

Construct a p-norm ball of given radius.

Parameters
  • radius (float or AffineExpression) – The ball’s radius.

  • p (float) – The value for p, which is cast to a limited precision fraction.

  • denominator_limit (int) – The largest allowed denominator when casting p to a fraction. Higher values can yield a greater precision at reduced performance.

property p

The value p defining the p-norm used.

This is a limited precision version of the paramter used when the ball was constructed.

property r

The ball’s radius r.

BaseVariable

class picos.expressions.BaseVariable(name, vectorization, lower=None, upper=None)[source]

Bases: object

Primary base class for all variable types.

Variables need to inherit this class with priority (first class listed) and ComplexAffineExpression or AffineExpression without priority.

class VarSubtype(dim, bnd)

Bases: tuple

static __new__(_cls, dim, bnd)

Create new instance of VarSubtype(dim, bnd)

bnd

Alias for field number 1

dim

Alias for field number 0

__init__(name, vectorization, lower=None, upper=None)[source]

Perform basic initialization for BaseVariable instances.

Parameters
  • name (str) – Name of the variable. A leading “__” denotes a private variable and is replaced by a sequence containing the variable’s unique ID.

  • vectorization (BaseVectorization) – Vectorization format used to store the value.

  • lower – Constant lower bound on the variable. May contain float("-inf") to denote unbounded elements.

  • upper – Constant upper bound on the variable. May contain float("inf") to denote unbounded elements.

copy(new_name=None)[source]

Return an independent copy of the variable.

id_at(index)[source]

Return the unique ID of a scalar entry, assigned at creation.

classmethod make_var_type(*args, **kwargs)[source]

Create a detailed variable type from subtype parameters.

See also var_type.

property bound_constraint

The variable bounds as a PICOS constraint, or None.

property bound_dicts

Variable bounds as a pair of mappings from index to scalar bound.

The indices and bound values are with respect to the internal representation of the variable, whose value can be accessed with internal_value.

Upper and lower bounds set to float("inf") and float("-inf") on variable creation, respectively, are not included.

property dim

The variable’s dimension on the real field.

This corresponds to the length of its vectorized value.

property id

The unique (starting) ID of the variable, assigned at creation.

property internal_value

The internal (special vectorized) value of the variable.

property long_string

Long string representation for printing a Problem.

property name

The name of the variable.

property num_bounds

Number of scalar bounds associated with the variable.

property var_subtype

The subtype part of the detailed variable type.

See also var_type.

property var_type

The detailed variable type.

This intentionally does not override Expression.type so that the variable still behaves as the affine expression that it represents when prediction constraint outcomes.

BinaryVariable

class picos.expressions.BinaryVariable(name, shape=1, 1)[source]

Bases: picos.expressions.variables.BaseVariable, picos.expressions.exp_affine.AffineExpression

A \{0,1\}-valued variable.

__init__(name, shape=1, 1)[source]

Create a BinaryVariable.

Parameters
  • name (str) – The variable’s name, used for both string description and identification.

  • shape (int or tuple or list) – The shape of a vector or matrix variable.

ComplexAffineExpression

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

Bases: picos.expressions.expression.Expression

A multidimensional complex affine expression.

Base class for the real AffineExpression.

Htranspose()[source]

Return the conjugate (or Hermitian) transpose.

Deprecated since version 2.0: Use H instead.

__init__(string, shape=1, 1, coefficients={}, constant=0j)[source]

Initialize a (complex) affine expression.

This constructor is meant for internal use. As a user, you will most likely want to build expressions starting from variables or a Constant.

Parameters
  • string (str) – A symbolic string description.

  • shape (int or tuple or list) – Shape of a vector or matrix expression.

  • coefficients (dict) – The linear part of the affine expression; maps the vectorization of variables to their coefficients.

  • constant – The constant part of the affine expression.

Warning

If the given coefficients and constant are already of the desired (numeric) type and shape, they are stored by reference. Modifying such data can lead to unexpected results as PICOS expressions are supposed to be immutable (to allow caching of results).

If you create affine expressions by any other means than this constructor, PICOS makes a copy of your data to prevent future modifications to it from causing inconsistencies.

broadcasted(shape)[source]

Return the expression broadcasted to the given shape.

Example

>>> from picos import Constant
>>> C = Constant("C", range(6), (2, 3))
>>> print(C)
[ 0.00e+00  2.00e+00  4.00e+00]
[ 1.00e+00  3.00e+00  5.00e+00]
>>> print(C.broadcasted((6, 6)))
[ 0.00e+00  2.00e+00  4.00e+00  0.00e+00  2.00e+00  4.00e+00]
[ 1.00e+00  3.00e+00  5.00e+00  1.00e+00  3.00e+00  5.00e+00]
[ 0.00e+00  2.00e+00  4.00e+00  0.00e+00  2.00e+00  4.00e+00]
[ 1.00e+00  3.00e+00  5.00e+00  1.00e+00  3.00e+00  5.00e+00]
[ 0.00e+00  2.00e+00  4.00e+00  0.00e+00  2.00e+00  4.00e+00]
[ 1.00e+00  3.00e+00  5.00e+00  1.00e+00  3.00e+00  5.00e+00]
conjugate()[source]

Return the complex conjugate.

Deprecated since version 2.0: Use conj instead.

copy()[source]

Return a deep copy of the expression.

Deprecated since version 2.0: PICOS expressions are now immutable.

dupdiag(n)[source]

Return a matrix with the (repeated) expression on the diagonal.

Vectorization is performed in column-major order.

Parameters

n (int) – Number of times to duplicate the vectorization.

dupvec(n)[source]

Return a (repeated) column-major vectorization of the expression.

Parameters

n (int) – Number of times to duplicate the vectorization.

Returns

A column vector.

Example

>>> from picos import Constant
>>> A = Constant("A", [[1, 2], [3, 4]])
>>> A.dupvec(1) is A.vec
True
>>> A.dupvec(3).equals(A.vec // A.vec // A.vec)
True
equals(other, absTol=None, relTol=None)[source]

Check mathematical equality with another affine expression.

Checks whether the affine expression involves the same variables with the same coefficients and an equal constant term as the given PICOS (affine) expression or constant term.

The type of both expressions may differ. In particular, a ComplexAffineExpression with real coefficients and constant can be equal to an AffineExpression.

If the argument is a constant term, no reshaping or broadcasting is used to bring it to the same shape as this expression. In particular,

  • 0 refers to a scalar zero (see also is0),

  • lists and tuples are treated as column vectors and

  • algebraic strings must specify a shape (see load_data).

Parameters
  • other – Another PICOS expression or a constant numeric data value supported by load_data.

  • absTol – As long as all absolute differences between scalar entries of the coefficient matrices and the constant terms being compared does not exceed this bound, consider the expressions equal.

  • relTol – As long as all absolute differences between scalar entries of the coefficient matrices and the constant terms being compared divided by the maximum absolute value found in either term does not exceed this bound, consider the expressions equal.

Example

>>> from picos import Constant
>>> A = Constant("A", 0, (5,5))
>>> repr(A)
'<5×5 Real Constant: A>'
>>> A.is0
True
>>> A.equals(0)
False
>>> A.equals("|0|(5,5)")
True
>>> repr(A*1j)
'<5×5 Complex Constant: A·1j>'
>>> A.equals(A*1j)
True
classmethod fromMatrix(matrix, size=None)[source]

Create a ComplexAffineExpression from a numeric matrix.

Deprecated since version 2.0: Use from_constant instead.

classmethod fromScalar(scalar)[source]

Create a ComplexAffineExpression from a numeric scalar.

Deprecated since version 2.0: Use from_constant instead.

classmethod from_constant(constant, shape=None, name=None)[source]

Create a class instance from the given numeric constant.

Loads the given constant as a PICOS expression, optionally broadcasted or reshaped to the given shape and named as specified.

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

Unlike Constant, this class method always creates an instance of the class that it is called on, instead of tailoring towards the numeric type of the data.

Note

When an operation involves both a PICOS expression and a constant value of another type, PICOS converts the constant on the fly so that you rarely need to use this method.

hadamard(fact)[source]

Denote the elementwise (or Hadamard) product.

Deprecated since version 2.0: Use object.__xor__ instead.

isconstant()[source]

Whether the expression involves no variables.

Deprecated since version 2.0: Use constant instead.

kron(other)[source]

Denote the Kronecker product from the right hand side.

Python 3 users can use the infix @ operator instead.

leftkron(other)[source]

Denote the Kronecker product from the left hand side.

Python 3 users can use the infix @ operator instead.

partial_trace(subsystems, dimensions=2)[source]

Return the partial trace over selected subsystems.

If the expression can be written as A_0 \otimes \cdots \otimes A_{n-1} for matrices A_0, \ldots, A_{n-1} with shapes given in dimensions, then this returns B_0 \otimes \cdots \otimes B_{n-1} with B_i = \operatorname{tr}(A_i), if i in subsystems (with i = -1 read as n-1), and B_i = A_i, otherwise.

Parameters
  • subsystems (int or tuple or list) – A collection of or a single subystem number, indexed from zero, corresponding to subsystems that shall be traced over. The value -1 refers to the last subsystem.

  • dimensions (int or tuple or list) – Either an integer d so that the subsystems are assumed to be all of shape d \times d, or a sequence of subsystem shapes where an integer d within the sequence is read as d \times d. In any case, the elementwise product over all subsystem shapes must equal the expression’s shape.

Raises
  • TypeError – If the subsystems do not match the expression or if a non-square subsystem is to be traced over.

  • IndexError – If the subsystem selection is invalid in any other way.

Example

>>> from picos import Constant
>>> A = Constant("A", range(16), (4, 4))
>>> print(A) 
[ 0.00e+00  4.00e+00  8.00e+00  1.20e+01]
[ 1.00e+00  5.00e+00  9.00e+00  1.30e+01]
[ 2.00e+00  6.00e+00  1.00e+01  1.40e+01]
[ 3.00e+00  7.00e+00  1.10e+01  1.50e+01]
>>> A0 = A.partial_trace(0); A0
<2×2 Real Constant: A.{tr([2×2])⊗[2×2]}>
>>> print(A0) 
[ 1.00e+01  1.80e+01]
[ 1.20e+01  2.00e+01]
>>> A1 = A.partial_trace(1); A1
<2×2 Real Constant: A.{[2×2]⊗tr([2×2])}>
>>> print(A1) 
[ 5.00e+00  2.10e+01]
[ 9.00e+00  2.50e+01]
partial_transpose(subsystems, dimensions=2)[source]

Return the expression with selected subsystems transposed.

If the expression can be written as A_0 \otimes \cdots \otimes A_{n-1} for matrices A_0, \ldots, A_{n-1} with shapes given in dimensions, then this returns B_0 \otimes \cdots \otimes B_{n-1} with B_i = A_i^T, if i in subsystems (with i = -1 read as n-1), and B_i = A_i, otherwise.

Parameters
  • subsystems (int or tuple or list) – A collection of or a single subystem number, indexed from zero, corresponding to subsystems that shall be transposed. The value -1 refers to the last subsystem.

  • dimensions (int or tuple or list) – Either an integer d so that the subsystems are assumed to be all of shape d \times d, or a sequence of subsystem shapes where an integer d within the sequence is read as d \times d. In any case, the elementwise product over all subsystem shapes must equal the expression’s shape.

Raises
  • TypeError – If the subsystems do not match the expression.

  • IndexError – If the subsystem selection is invalid.

Example

>>> from picos import Constant
>>> A = Constant("A", range(16), (4, 4))
>>> print(A) 
[ 0.00e+00  4.00e+00  8.00e+00  1.20e+01]
[ 1.00e+00  5.00e+00  9.00e+00  1.30e+01]
[ 2.00e+00  6.00e+00  1.00e+01  1.40e+01]
[ 3.00e+00  7.00e+00  1.10e+01  1.50e+01]
>>> A0 = A.partial_transpose(0); A0
<4×4 Real Constant: A.{[2×2]ᵀ⊗[2×2]}>
>>> print(A0) 
[ 0.00e+00  4.00e+00  2.00e+00  6.00e+00]
[ 1.00e+00  5.00e+00  3.00e+00  7.00e+00]
[ 8.00e+00  1.20e+01  1.00e+01  1.40e+01]
[ 9.00e+00  1.30e+01  1.10e+01  1.50e+01]
>>> A1 = A.partial_transpose(1); A1
<4×4 Real Constant: A.{[2×2]⊗[2×2]ᵀ}>
>>> print(A1) 
[ 0.00e+00  1.00e+00  8.00e+00  9.00e+00]
[ 4.00e+00  5.00e+00  1.20e+01  1.30e+01]
[ 2.00e+00  3.00e+00  1.00e+01  1.10e+01]
[ 6.00e+00  7.00e+00  1.40e+01  1.50e+01]
renamed(string)[source]

Return the expression with a modified string description.

reshaped(shape)[source]

Return the expression reshaped in column-major order.

Example

>>> from picos import Constant
>>> C = Constant("C", range(6), (2, 3))
>>> print(C)
[ 0.00e+00  2.00e+00  4.00e+00]
[ 1.00e+00  3.00e+00  5.00e+00]
>>> print(C.reshaped((3, 2)))
[ 0.00e+00  3.00e+00]
[ 1.00e+00  4.00e+00]
[ 2.00e+00  5.00e+00]
reshaped_or_broadcasted(shape)[source]

Return the expression reshaped or broadcasted.

Unlike with reshaped and broadcasted, the target shape may not contain a wildcard character.

If the wildcard-free target shape has the same number of elements as the current shape, then this is the same as reshaped, otherwise it is the same as broadcasted.

same_as(other)[source]

Check mathematical equality with another affine expression.

Deprecated since version 2.0: Use equals instead.

soft_copy()[source]

Return a shallow copy of the expression.

Deprecated since version 2.0: PICOS expressions are now immutable.

sparse_rows(varOffsetMap, lowerTriangle=False, upperTriangle=False, indexFunction=None)[source]

Return a sparse list representation of the expression.

The method is intended for internal use: It simplifies passing affine constraints to solvers that support only scalar constraints. The idea is to pose the constraint as a single (multidimensional) affine expression bounded by zero, and use the coefficients and the constant term of this expression to fill the solver’s constraint matrix (with columns representing scalar variables and rows representing scalar constraints).

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

  • lowerTriangle (bool) – Whether to return only the lower triangular part of the expression.

  • upperTriangle (bool) – Whether to return only the upper triangular part of the expression.

  • indexFunction – Instead of adding the local variable index to the value returned by varOffsetMap, use the return value of this function, that takes as argument the variable and its local index, as the “column index”, which need not be an integer. When this parameter is passed, the parameter varOffsetMap is ignored.

Returns

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

transpose()[source]

Return the matrix transpose.

Deprecated since version 2.0: Use T instead.

classmethod zero(shape=1, 1)[source]

Return a constant zero expression of given shape.

property H

Conjugate (or Hermitian) transpose.

property T

Matrix transpose.

property T0

Expression with the first 2 \times 2 subsystem transposed.

Only available for a 2^k \times 2^k matrix with all subsystems of shape 2 \times 2. Use partial_transpose otherwise.

property T1

Expression with the second 2 \times 2 subsystem transposed.

Only available for a 2^k \times 2^k matrix with all subsystems of shape 2 \times 2. Use partial_transpose otherwise.

property T2

Expression with the third 2 \times 2 subsystem transposed.

Only available for a 2^k \times 2^k matrix with all subsystems of shape 2 \times 2. Use partial_transpose otherwise.

property T3

Expression with the fourth 2 \times 2 subsystem transposed.

Only available for a 2^k \times 2^k matrix with all subsystems of shape 2 \times 2. Use partial_transpose otherwise.

property Tl

Expression with the last 2 \times 2 subsystem transposed.

Only available for a 2^k \times 2^k matrix with all subsystems of shape 2 \times 2. Use partial_transpose otherwise.

property Tx

Auto-detect few subsystems of same shape and transpose the last.

Deprecated since version 2.0: Use partial_transpose instead.

property complex

Whether the expression can be complex-valued.

property conj

Complex conjugate.

property constant

Whether the expression involves no variables.

property cst

Constant part of the affine expression.

property diag

Diagonal matrix with the expression on the main diagonal.

Vectorization is performed in column-major order.

property hermitian

Whether the expression is a hermitian (or symmetric) matrix.

A tolerance is used to compensate for small numeric errors that can occur when creating hermtian expressions by means of matrix multiplication, see RELATIVE_HERMITIANNESS_TOLERANCE.

If PICOS still rejects your expression as not hermitian (or as not symmetric), you can use hermitianized to correct larger numeric errors or the effects of noisy data.

property hermitianized

The expression projected onto the subspace of hermitian matrices.

For a square (complex) affine expression A, this is \frac{1}{2}(A + A^H).

If the expression is not complex, then this is the projection onto the subspace of symmetric matrices.

property imag

Imaginary part of a complex affine expression.

property is0

Whether this is a constant scalar, vector or matrix of all zeros.

property is1

Whether this is a constant scalar or vector of all ones.

property isI

Whether this is a constant identity matrix.

property isreal

Whether the expression is always real-valued.

property lin

Linear part of the affine expression.

property maindiag

The main diagonal of the expression as a column vector.

property real

Real part of a complex affine expression.

property scalar

Whether this is a scalar affine expression.

property square

Whether the expression is a square matrix.

property sum

Sum over all scalar elements of the expression.

property tr

Trace of a square expression.

property tr0

Expression with the first 2 \times 2 subsystem traced out.

Only available for a 2^k \times 2^k matrix with all subsystems of shape 2 \times 2. Use partial_trace otherwise.

property tr1

Expression with the second 2 \times 2 subsystem traced out.

Only available for a 2^k \times 2^k matrix with all subsystems of shape 2 \times 2. Use partial_trace otherwise.

property tr2

Expression with the third 2 \times 2 subsystem traced out.

Only available for a 2^k \times 2^k matrix with all subsystems of shape 2 \times 2. Use partial_trace otherwise.

property tr3

Expression with the fourth 2 \times 2 subsystem traced out.

Only available for a 2^k \times 2^k matrix with all subsystems of shape 2 \times 2. Use partial_trace otherwise.

property trilvec

Column-major vectorization of the lower triangular part.

Returns

A column vector of all elements A_{ij} that satisfy i \geq j.

Note

If you want a row-major vectorization instead, write A.T.triuvec instead of A.trilvec.

Example

>>> from picos import Constant
>>> A = Constant("A", [[1, 2], [3, 4], [5, 6]])
>>> print(A)
[ 1.00e+00  2.00e+00]
[ 3.00e+00  4.00e+00]
[ 5.00e+00  6.00e+00]
>>> print(A.trilvec)
[ 1.00e+00]
[ 3.00e+00]
[ 5.00e+00]
[ 4.00e+00]
[ 6.00e+00]
property triuvec

Column-major vectorization of the upper triangular part.

Returns

A column vector of all elements A_{ij} that satisfy i \leq j.

Note

If you want a row-major vectorization instead, write A.T.trilvec instead of A.triuvec.

Example

>>> from picos import Constant
>>> A = Constant("A", [[1, 2, 3], [4, 5, 6]])
>>> print(A)
[ 1.00e+00  2.00e+00  3.00e+00]
[ 4.00e+00  5.00e+00  6.00e+00]
>>> print(A.triuvec)
[ 1.00e+00]
[ 2.00e+00]
[ 5.00e+00]
[ 3.00e+00]
[ 6.00e+00]
property trl

Expression with the last 2 \times 2 subsystem traced out.

Only available for a 2^k \times 2^k matrix with all subsystems of shape 2 \times 2. Use partial_trace otherwise.

property vec

Column-major vectorization of the expression as a column vector.

Note

Given an expression A, A.vec and A[:] produce the same result (up to its string description) but A.vec is faster and its result is cached.

Example

>>> from picos import Constant
>>> A = Constant("A", [[1, 2], [3, 4]])
>>> A.vec.equals(A[:])
True
>>> A[:] is A[:]
False
>>> A.vec is A.vec
True

ComplexVariable

class picos.expressions.ComplexVariable(name, shape=1, 1)[source]

Bases: picos.expressions.variables.BaseVariable, picos.expressions.exp_affine.ComplexAffineExpression

A complex-valued variable.

Passed to solvers as a real variable vector with 2mn entries.

__init__(name, shape=1, 1)[source]

Create a ComplexVariable.

Parameters
  • name (str) – The variable’s name, used for both string description and identification.

  • shape (int or tuple or list) – The shape of a vector or matrix variable.

DetRootN

class picos.expressions.DetRootN(x)[source]

Bases: picos.expressions.expression.Expression

The n-th root of the determinant of an n\times n matrix.

Definition

For an n \times n positive semidefinite hermitian matrix X, this is

\sqrt[n]{\det X}.

Warning

When you pose a lower bound on the n-th root of a determinant of the matrix X, then PICOS enforces positive semidefiniteness X \succeq 0 through an auxiliary constraint during solution search.

__init__(x)[source]

Construct a DetRootN.

Parameters

x (ComplexAffineExpression) – The matrix concerned. Must be hermitian by definition.

property n

Diagonal length of x.

property x

The matrix concerned.

Entropy

class picos.expressions.Entropy(x, y=None)[source]

Bases: picos.expressions.expression.Expression

Entropy or negative relative entropy of an affine expression.

Negative relative entropy is also known as the perspective of the logarithm.

Definition

Let x be an n-dimensional real affine expression.

  1. If no additional expression y is given, this is the entropy

    -\sum_{i = 1}^n \operatorname{vec}(x)_i
\log(\operatorname{vec}(x)_i).

  2. If an additional affine expression y of same shape as x is given, this is the negative relative entropy (or logarithmic perspective)

    -\sum_{i = 1}^n \operatorname{vec}(x)_i
\log\left(
    \frac{\operatorname{vec}(x)_i}{\operatorname{vec}(y)_i}
\right)
&= -\sum_{i = 1}^n \operatorname{vec}(x)_i
\left[
    \log(\operatorname{vec}(x)_i) - \log(\operatorname{vec}(y)_i)
\right] \\
&= \sum_{i = 1}^n \operatorname{vec}(x)_i
\left[
    \log(\operatorname{vec}(y)_i) - \log(\operatorname{vec}(x)_i
\right] \\
&= \sum_{i = 1}^n \operatorname{vec}(x)_i
\log\left(
    \frac{\operatorname{vec}(y)_i}{\operatorname{vec}(x)_i}
\right).

Warning

When you pose a lower bound on this expression, then PICOS enforces x \geq 0 through an auxiliary constraint during solution search. When an additional expression y is given, PICOS enforces y \geq 0 as well.

__init__(x, y=None)[source]

Construct an Entropy.

Parameters
  • x (AffineExpression) – The affine expression x.

  • y (AffineExpression) – An additional affine expression y. If necessary, PICOS will attempt to reshape or broadcast it to the shape of x.

property n

Length of x.

property x

The expression x.

property y

The additional expression y, or None.

ExponentialCone

class picos.expressions.ExponentialCone[source]

Bases: picos.expressions.set.Set

The exponential cone.

Represents the convex cone \operatorname{cl}\{(x,y,z): y \exp(\frac{z}{y}) \leq x, x,y > 0\}.

__init__()[source]

Construct an exponential cone.

Expression

class picos.expressions.Expression(typeStr, symbStr)[source]

Bases: abc.ABC

Abstract base class for mathematical expressions, including variables.

For variables, this is the secondary base class, with BaseVariable being the primary one.

__init__(typeStr, symbStr)[source]

Perform basic initialization for Expression instances.

Parameters
  • typeStr (str) – Short string denoting the expression type.

  • symbStr (str) – Algebraic string description of the expression.

is_valued()[source]

Whether the expression is valued.

Deprecated since version 2.0: Use valued instead.

classmethod make_type(*args, **kwargs)[source]

Create a detailed expression type from subtype parameters.

replace_variables(new_variables)[source]

Return a copy of the expression concerning different variables.

New variables must have the same shape and vectorization format as the variables that they replace. This means in particular that RealVariable, IntegerVariable and BinaryVariable of same shape are interchangeable.

If the variables to be replaced do not appear in the expression, then the expression is not copied but returned as is.

Parameters

new_variables (tuple or list or dict) – Either a map from variables or variable names to new variables or an iterable of new variables to replace existing variables of same name with.

set_value(value)[source]

Set the value of an expression, usually a variable.

Deprecated since version 2.0: Use value instead.

property concave

Whether the expression is concave.

property convex

Whether the expression is convex.

property refined

A refined version of the expression.

The refined expression can be an instance of a different Expression subclass than the original expression, if that type is better suited for the mathematical object in question.

The refined expression is automatically used instead of the original one whenever a constraint is created, and in some other places.

The idea behind refined expressions is that operations that produce new expressions can be executed quickly without checking for exceptionnel cases. For instance, the sum of two ComplexAffineExpression instances could have the complex part eliminated so that storing the result as an AffineExpression would be prefered, but checking for this case on every addition would be too slow. Refinement is used sparingly to detect such cases at times where it makes the most sense.

property shape

Return the algebraic shape of the expression.

property size

The same as shape.

property string

Symbolic string representation of the expression.

Use this over Python’s str if you want to output the symbolic representation even when the expression is valued.

property subtype

The subtype part of the expression’s detailed type.

Returns a hashable object that, together with the Python class part of the expression’s type, is sufficient to predict the constraint outcome (constraint class and subtype) of any comparison operation with any other expression.

By convention the object returned is a namedtuple instance.

property type

The expression’s detailed type for constraint prediction.

The returned value is suffcient to predict the detailed type of any constraint that can be created by comparing with another expression.

Since constraints are created from refined expressions only, the Python class part of the detailed type may differ from the type of the expression whose type is queried.

property value

Value of the expression.

It is defined (not None) if the expression is constant or if all variables involved in the expression are valued. Variables can be valued directly by writing to their value attribute, or they can be valued by PICOS when an optimization solution is found.

Some expressions can also be valued directly if PICOS can find a minimal norm variable assignment that makes the expression have the desired value. In particular, this works with affine expressions whose linear part has an under- or well-determined coefficient matrix.

Example

>>> from picos import RealVariable
>>> x = RealVariable("x", (1,3))
>>> y = RealVariable("y", (1,3))
>>> e = x - 2*y + 3
>>> print("e:", e)
e: x - 2·y + [3]
>>> e.value = [4, 5, 6]
>>> print("e: ", e, "\nx: ", x, "\ny: ", y, sep = "")
e: [ 4.00e+00  5.00e+00  6.00e+00]
x: [ 2.00e-01  4.00e-01  6.00e-01]
y: [-4.00e-01 -8.00e-01 -1.20e+00]

Unlike value_as_matrix, scalars are returned as scalar types.

property value_as_matrix

Value of the expression, as a CVXOPT matrix type.

Refer to value for when it is defined (not None).

Unlike value, scalars are returned in the form of 1x1 matrices.

property valued

Whether the expression is valued.

Note

Querying this attribute is not faster than immediately querying value and checking whether it is None. Use it only if you do not need to know the value, but only whether it is available.

Example

>>> from picos import RealVariable
>>> x = RealVariable("x", 3)
>>> x.valued
False
>>> x.value
>>> print((x|1))
∑(x)
>>> x.value = [1, 2, 3]
>>> (x|1).valued
True
>>> print((x|1))
6.0
property variables

Return the set of variables that are involved in the expression.

ExpressionType

class picos.expressions.ExpressionType(theClass, subtype)[source]

Bases: picos.containers.DetailedType

The detailed type of an expression for predicting constraint outcomes.

This is suffcient to predict the detailed type of any constraint that can be created by comparing with another expression.

The prediction is done by using the relevant operator on instances of this class, as opposed to the expressions themselves. Note that operators used to create new expressions as opposed to constraints are not handled.

GeometricMean

class picos.expressions.GeometricMean(x)[source]

Bases: picos.expressions.expression.Expression

Geometric mean of an affine expression.

Definition

For an n-dimensional affine expression x with x \geq 0, the geometric mean is given as

\left(\prod_{i = 1}^n x_i \right)^{\frac{1}{n}}.

Warning

When you pose a lower bound on a geometric mean, then PICOS enforces x \geq 0 through an auxiliary constraint during solution search.

__init__(x)[source]

Construct a GeometricMean.

Parameters

x (AffineExpression) – The affine expression to form the geometric mean of.

property x

The expression under the mean.

HermitianVariable

class picos.expressions.HermitianVariable(name, shape)[source]

Bases: picos.expressions.variables.BaseVariable, picos.expressions.exp_affine.ComplexAffineExpression

A hermitian matrix variable.

Stored internally and passed to solvers as the horizontal concatenation of a real symmetric vectorization with \frac{n(n+1)}{2} entries and a real skew-symmetric vectorization with \frac{n(n-1)}{2} entries, resulting in a real vector with only n^2 entries total.

__init__(name, shape)[source]

Create a HermitianVariable.

Parameters
  • name (str) – The variable’s name, used for both string description and identification.

  • shape (int or tuple or list) – The shape of the matrix.

IntegerVariable

class picos.expressions.IntegerVariable(name, shape=1, 1, lower=None, upper=None)[source]

Bases: picos.expressions.variables.BaseVariable, picos.expressions.exp_affine.AffineExpression

An integer-valued variable.

__init__(name, shape=1, 1, lower=None, upper=None)[source]

Create an IntegerVariable.

Parameters
  • name (str) – The variable’s name, used for both string description and identification.

  • shape (int or tuple or list) – The shape of a vector or matrix variable.

  • lower – Constant lower bound on the variable. May contain float("-inf") to denote unbounded elements.

  • upper – Constant upper bound on the variable. May contain float("inf") to denote unbounded elements.

LogSumExp

class picos.expressions.LogSumExp(x)[source]

Bases: picos.expressions.expression.Expression

Logarithm of the sum of elementwise exponentials of an expression.

Definition

For an n-dimensional real affine expression x, this is the logarithm of the sum of elementwise exponentials

\log\sum_{i = 1}^n \exp(\operatorname{vec}(x)_i).

__init__(x)[source]

Construct a LogSumExp.

Parameters

x (AffineExpression) – The affine expression x.

property exp

The elementwise sum of exponentials of x.

property n

Length of x.

property x

The expression x.

Logarithm

class picos.expressions.Logarithm(x)[source]

Bases: picos.expressions.expression.Expression

Logarithm of a scalar affine expression.

Definition

For a real scalar affine expression x, this is \log(x).

Warning

When you pose a lower bound on a logarithm \log(x), then PICOS enforces x \geq 0 through an auxiliary constraint during solution search.

__init__(x)[source]

Construct a Logarithm.

Parameters

x (AffineExpression) – The scalar affine expression x.

property exp

The exponential of the logarithm, equal to x.

property x

The expression x.

LowerTriangularVariable

class picos.expressions.LowerTriangularVariable(name, shape=1, 1, lower=None, upper=None)[source]

Bases: picos.expressions.variables.BaseVariable, picos.expressions.exp_affine.AffineExpression

A lower triangular matrix variable.

Stored internally and passed to solvers as a lower triangular vectorization with only \frac{n(n+1)}{2} entries.

__init__(name, shape=1, 1, lower=None, upper=None)[source]

Create a LowerTriangularVariable.

Parameters
  • name (str) – The variable’s name, used for both string description and identification.

  • shape (int or tuple or list) – The shape of the matrix.

  • lower – Constant lower bound on the variable. May contain float("-inf") to denote unbounded elements.

  • upper – Constant upper bound on the variable. May contain float("inf") to denote unbounded elements.

NegativeEntropy

class picos.expressions.NegativeEntropy(x, y=None)[source]

Bases: picos.expressions.expression.Expression

Negative or relative entropy of an affine expression.

Relative entropy is also known as the Kullback-Leibler divergence.

Definition

Let x be an n-dimensional real affine expression.

  1. If no additional expression y is given, this is the negative entropy

    \sum_{i = 1}^n \operatorname{vec}(x)_i
\log(\operatorname{vec}(x)_i).

  2. If an additional affine expression y of same shape as x is given, this is the relative entropy (or Kullback-Leibler divergence)

    \sum_{i = 1}^n \operatorname{vec}(x)_i
\log\left(
    \frac{\operatorname{vec}(x)_i}{\operatorname{vec}(y)_i}
\right)
= \sum_{i = 1}^n \operatorname{vec}(x)_i
\left[
    \log(\operatorname{vec}(x)_i) - \log(\operatorname{vec}(y)_i)
\right].

Warning

When you pose an upper bound on this expression, then PICOS enforces x \geq 0 through an auxiliary constraint during solution search. When an additional expression y is given, PICOS enforces y \geq 0 as well.

__init__(x, y=None)[source]

Construct a NegativeEntropy.

Parameters
  • x (AffineExpression) – The affine expression x.

  • y (AffineExpression) – An additional affine expression y. If necessary, PICOS will attempt to reshape or broadcast it to the shape of x.

property n

Length of x.

property x

The expression x.

property y

The additional expression y, or None.

Norm

class picos.expressions.Norm(x, p=2, q=None, denominator_limit=1000)[source]

Bases: picos.expressions.expression.Expression

Entrywise p-norm or L_{p,q}-norm of an expression.

This class can represent the absolute value, the modulus, a vector p-norm and an entrywise matrix L_{p,q}-norm of a (complex) affine expression. In addition to these convex norms, it can represent the concave generalized vector p-norm with 0 < p \leq 1.

Not all of these norms are available on the complex field; see the definitions below to learn more.

Definition

If q is not given (None), then it is set equal to p.

  1. If the normed expression is a real scalar x, then this is the absolute value

    |x| = \begin{cases}
   x, &\text{if }x \geq 0,\\
   -x, &\text{otherwise.}
\end{cases}

    The parameters p and q are ignored in this case.

  2. If the normed expression is a complex scalar z, then this is the modulus

    |z| = \sqrt{\operatorname{Re}(z)^2 + \operatorname{Im}(z)^2}.

    The parameters p and q are ignored in this case.

  3. If the normed expression is a real vector x and p = q, then this is the (generalized) vector p-norm

    \lVert x \rVert_p = \left(\sum_{i=1}^n |x_i|^p\right)^{\frac{1}{p}}

    for p \in \mathbb{Q} \cup \{\infty\} with p > 0 and |x_i| the absolute value of the i-th entry of x.

    Note that for p < 1 the expression is not convex and thus not a proper norm. However, it is concave over the nonnegative orthant and posing a lower bound on such a generalized norm yields a convex constraint for x \geq 0.

    Warning

    When you pose a lower bound on a concave generalized norm (p < 1), then PICOS enforces x \geq 0 through an auxiliary constraint during solution search.

    Special cases:

    • For p = 1, this is the Manhattan or Taxicab norm \lVert x \rVert_{\text{sum}}.

    • For p = 2, this is the Euclidean norm \lVert x \rVert = \lVert x \rVert_2.

    • For p = \infty, this is the Maximum, Chebyshev, or Infinity norm \lVert x \rVert_{\text{max}}.

  4. If the normed expression is a real vector x and p \neq q, then it is treated as a matrix with a single row or a single column, depending on the shape associated with x. See case (5).

  5. If the normed expression is a complex vector z and p = q, then the definition is the same as in case (3) but with x = z, |x_i| the modulus of the i-th entry of x, and p \geq 1.

  6. If the normed expression is a real m \times n matrix X, then this is the L_{p,q}-norm

    \lVert X \rVert_{p,q} =
\left(\sum_{j = 1}^n \left(\sum_{i = 1}^m
    |X_{ij}|^p
\right)^{\frac{q}{p}} \right)^{\frac{1}{q}}

    for p, q \in \mathbb{Q} \cup \{\infty\} with p,q \geq 1.

    If p = q, then this is equal to the (generalized) vector p-norm of the the vectorized matrix, that is \lVert X \rVert_{p,p} = \lVert \operatorname{vec}(X) \rVert_p. In this case, the requirement p \geq 1 is relaxed to p > 0 and X may be a complex matrix. See case (3).

    Special cases:

    • For p = q = 2, this is the Frobenius norm \lVert X \rVert = \lVert X \rVert_F.

    • For p = 1, q = \infty, this is the maximum absolute column sum

      \lVert X \rVert_{1,\infty} =
\max_{j=1 \ldots n} \sum_{i=1}^m |X_{ij}|.

      This equals the operator norm induced by the vector 1-norm. You can obtain the maximum absolute row sum (the operator norm induced by the vector \infty-norm) by first transposing X.

  7. Complex matrix norms are not supported.

Note

You can write \infty in Python as float("inf").

__init__(x, p=2, q=None, denominator_limit=1000)[source]

Construct a Norm.

Parameters
  • x (ComplexAffineExpression) – The affine expression to take the norm of.

  • p (float) – The value for p, which is cast to a limited precision fraction.

  • q (float) – The value for q, which is cast to a limited precision fraction. The default of None means equal to p.

  • denominator_limit (int) – The largest allowed denominator when casting p and q to a fraction. Higher values can yield a greater precision at reduced performance.

property p

The parameter p.

This is a limited precision version of the paramter used when the norm was constructed.

property pden

The limited precision fraction denominator of p.

property pnum

The limited precision fraction numerator of p.

property q

The parameter q.

This is a limited precision version of the paramter used when the norm was constructed.

property qden

The limited precision fraction denominator of q.

property qnum

The limited precision fraction numerator of q.

property x

Real expression whose norm equals that of the original expression.

NuclearNorm

class picos.expressions.NuclearNorm(x)[source]

Bases: picos.expressions.expression.Expression

The nuclear norm of a matrix.

This class can represent the nuclear norm of a matrix-affine expression (real- or complex valued). The nuclear norm is convex, so we can form expressions of the form NuclearNorm(X) <= t which are typically reformulated as LMIs that can be handled by SDP solvers.

Definition

If the normed expression is a matrix X, then its nuclear norm is

\|X\|_* =  \operatorname{trace}\ (X^*X)^{1/2}
        = \sum_{i=1}^{\min(n,m)} \sigma_i(X)

where the \sigma_i(X) denote the singular values of a X, and X^* denotes the adjoint matrix of X (i.e., the transposed matrix X^T if X is real-valued).

Special cases:

  • If X is scalar, then \|X\|_* reduces to the the absolute value (or modulus) |X|.

  • If X is scalar, then \|X\|_* coincides with the Euclidean norm of X.

__init__(x)[source]

Construct a NuclearNorm.

Parameters

x (ComplexAffineExpression) – The affine expression to take the norm of.

property x

Real expression whose norm equals that of the original expression.

PowerTrace

class picos.expressions.PowerTrace(x, p, m=None, denominator_limit=1000)[source]

Bases: picos.expressions.expression.Expression

The trace of the p-th power of a hermitian matrix.

Definition

Let p \in \mathbb{Q}.

  1. If the base expressions is a real scalar x and no additional constant m is given, then this is the power x^p.

  2. If the base expressions is a real scalar x, p \in [0, 1], and a positive scalar constant m is given, then this is the scaled power m x^p.

  3. If the base expression is a hermitian matrix X and no additional constant M is given, then this is the trace of power \operatorname{tr}(X^p).

  4. If the base expression is a hermitian matrix X, p \in [0, 1], and a hermitian positive semidefinite constant matrix M of same shape as X is given, then this is the trace of a scaled power \operatorname{tr}(M X^p).

No other case is supported. In particular, if p \not\in [0, 1], then m/M must be undefined (None).

Warning

  1. For a constraint of the form x^p \leq t with p < 1 and p \neq 0, PICOS enforces x \geq 0 during solution search.

  2. For a constraint of the form \operatorname{tr}(X^p) \leq t or \operatorname{tr}(M X^p) \leq t with p < 1 and p \neq 0, PICOS enforces X \succeq 0 during solution search.

  3. For a constraint of the form \operatorname{tr}(X^p) \leq t or \operatorname{tr}(M X^p) \leq t with p > 1, PICOS enforces t \geq 0 during solution search.

__init__(x, p, m=None, denominator_limit=1000)[source]

Construct a PowerTrace.

Parameters
  • x (AffineExpression) – The scalar or symmetric matrix to form a power of.

  • p (float) – The value for p, which is cast to a limited precision fraction.

  • m (AffineExpression or anything recognized by load_data) – An additional positive semidefinite constant to multiply the power with.

  • denominator_limit (int) – The largest allowed denominator when casting p to a fraction. Higher values can yield a greater precision at reduced performance.

property den

The limited precision fraction denominator of p.

property m

An additional factor to multiply the power with.

property n

Diagonal length of x.

property num

The limited precision fraction numerator of p.

property p

The parameter p.

This is a limited precision version of the paramter used when the expression was constructed.

property x

The matrix concerned.

QuadraticExpression

class picos.expressions.QuadraticExpression(string, quadraticPart={}, affinePart=<1×1 Real Constant: 0>, scalarFactors=None, copyDecomposition=None)[source]

Bases: picos.expressions.expression.Expression

A scalar quadratic expression of the form x^TQx + a^Tx + b.

__init__(string, quadraticPart={}, affinePart=<1×1 Real Constant: 0>, scalarFactors=None, copyDecomposition=None)[source]

Initialize a scalar quadratic expression.

This constructor is meant for internal use. As a user, you will most likely want to build expressions starting from variables or a Constant.

Parameters
  • string (str) – A symbolic string description.

  • quadraticPart – A dict mapping PICOS variable pairs to CVXOPT matrices. Each entry (x, y) \mapsto A_{xy} represents a quadratic form \operatorname{vec_x}(x)^T A_{xy} \operatorname{vec_y}(y) where \operatorname{vec_x} and \operatorname{vec_y} refer to the isometric real vectorizations that are used by PICOS internally to store the variables x and y, respectively. The quadratic part Q of the expression is then given as Q = \sum_{x, y} A_{xy}.

  • affinePart (AffineExpression) – The affine part a^Tx + b of the expression.

  • scalarFactors – A pair (u, v) with both u and v scalar real affine expressions representing a known x^TQx + a^Tx + b = uv factorization of the expression.

  • copyDecomposition (QuadraticExpression) – Another quadratic expression with equal quadratic part whose quadratic part decomposition shall be copied.

property A

An affine-augmented quadratic coefficient matrix, condensed.

For a quadratic expression x^TQx + a^Tx + b, this is A = \begin{bmatrix}Q&\frac{a}{2}\\\frac{a^T}{2}&b\end{bmatrix} but with zero rows and columns removed.

The vector y is a condensed version of x that refers to this matrix, so that q.y.T*q.A*q.y equals the expression q.

Raises

ValueError – When the expression is zero.

property L

The L of an LL^T Cholesky decomposition of Q.

Returns

A CVXOPT lower triangular sparse matrix.

Raises
  • ValueError – When the quadratic part is zero.

  • ArithmeticError – When the expression is not convex, that is when the matrix Q is not numerically positive semidefinite.

property M

The M of an MM^T Cholesky decomposition of A.

Returns

A CVXOPT lower triangular sparse matrix.

Raises
  • ValueError – When the expression is zero.

  • ArithmeticError – When the expression can not be written as a squared norm, that is when the extended matrix A is not numerically positive semidefinite.

property Q

The coefficient matrix Q of the expression, condensed.

This equals the Q of the quadratic expression x^TQx + a^Tx + b but with zero rows and columns removed.

The vector x is a condensed version of x that refers to this matrix, so that q.x.T*q.Q*q.x equals the quadratic part x^TQx of the expression q.

Raises

ValueError – When the quadratic part is zero.

property aff

Affine part a^Tx + b of the quadratic expression.

property cst

Constant part b of the quadratic expression.

property fullroot

Affine expression whose squared norm equals the expression.

For a convex quadratic expression q, this is equal to the vector q.M.T*q.y with zero rows removed.

Construction

For a quadratic expression x^TQx + a^Tx + b with A = \begin{bmatrix}Q&\frac{a}{2}\\\frac{a^T}{2}&b\end{bmatrix} positive semidefinite, let A = MM^T be a Cholesky decomposition. Let further y = \begin{bmatrix}x^T & 1\end{bmatrix}^T. Then,

x^TQx + a^Tx + b
&= y^TAy \\
&= y^TMM^Ty \\
&= (M^Ty)^TM^Ty \\
&= \langle M^Ty, M^Ty \rangle \\
&= \lVert M^Ty \rVert^2.

Note that removing zero rows from M^Ty does not affect the norm.

Raises
  • ValueError – When the expression is zero.

  • ArithmeticError – When the expression is not convex, that is when the quadratic part is not numerically positive semidefinite.

property is0

Whether the quadratic expression is zero.

property is_squared_norm

Whether the expression can be written as a squared norm.

If this is True, then the there is a coefficient vector c such that

\lVert c^T \begin{bmatrix} x \\ 1 \end{bmatrix} \rVert^2
= x^TQx + a^Tx + b.

If the expression is also nonzero, then fullroot is c^T \begin{bmatrix} x^T & 1 \end{bmatrix}^T with zero entries removed.

property lin

Linear part a^Tx of the quadratic expression.

property num_quad_terms

The number of terms in the simplified quadratic form.

property quad

Quadratic part x^TQx of the quadratic expression.

property quadratic_forms

The quadratic forms as sparse matrices.

property quadroot

Affine expression whose squared norm equals x^TQx.

For a convex quadratic expression q, this is equal to the vector q.L.T*q.x with zero rows removed.

Construction

Let x^TQx be the quadratic part of the expression with Q positive semidefinite and Q = LL^T a Cholesky decomposition. Then,

x^TQx
&= x^TLL^Tx \\
&= (L^Tx)^TL^Tx \\
&= \langle L^Tx, L^Tx \rangle \\
&= \lVert L^Tx \rVert^2.

Note that removing zero rows from L^Tx does not affect the norm.

Raises
  • ValueError – When the quadratic part is zero.

  • ArithmeticError – When the expression is not convex, that is when the quadratic part is not numerically positive semidefinite.

property rank

The length of the vector quadroot.

Up to numerical considerations, this is the rank of the (convex) quadratic coefficient matrix Q of the expression.

Raises

ArithmeticError – When the expression is not convex, that is when the quadratic part is not numerically positive semidefinite.

property scalar_factors

Decomposition into scalar real affine expressions.

If the expression is known to be equal to ab for scalar real affine expressions a and b, returns the pair (a, b). Otherwise, returns the empty tuple ().

Note that if a = b, then also a is b in the returned tuple.

property x

The stacked variable vector x of the expression, condensed.

This equals the x of the quadratic expression x^TQx + a^Tx + b but entries corresponding to zero rows and columns in Q are removed, so that q.x.T*q.Q*q.x equals the x^TQx part of the expression q.

Raises

ValueError – When the quadratic part is zero.

property y

See A.

Raises

ValueError – When the expression is zero.

RealVariable

class picos.expressions.RealVariable(name, shape=1, 1, lower=None, upper=None)[source]

Bases: picos.expressions.variables.BaseVariable, picos.expressions.exp_affine.AffineExpression

A real-valued variable.

__init__(name, shape=1, 1, lower=None, upper=None)[source]

Create a RealVariable.

Parameters
  • name (str) – The variable’s name, used for both string description and identification.

  • shape (int or tuple or list) – The shape of a vector or matrix variable.

  • lower – Constant lower bound on the variable. May contain float("-inf") to denote unbounded elements.

  • upper – Constant upper bound on the variable. May contain float("inf") to denote unbounded elements.

RotatedSecondOrderCone

class picos.expressions.RotatedSecondOrderCone(p=1)[source]

Bases: picos.expressions.set.Set

The (narrowed or widened) rotated second order cone.

For n \in \mathbb{Z}_{\geq 3} and p \in \mathbb{R}_{> 0}, represents the convex cone

\mathcal{R}_{p}^n = \left\{
    x \in \mathbb{R}^n
~\middle|~
    p x_1 x_2 \geq \sum_{i = 3}^n x_i^2 \land x_1, x_2 \geq 0
\right\}.

For p = 2, this is the standard rotated second order cone \mathcal{R}^n obtained by rotating the second order cone \mathcal{Q}^n by \frac{\pi}{4} in the (x_1, x_2) plane.

The default instance of this class has p = 1, which can be understood as a narrowed version of the standard cone. This is more convenient for defining the primal problem but it should be noted that \mathcal{R}_{1}^n is not self-dual, so working with p = 2 may seem more natural when the dual problem is of interest.

Dual cone

The dual cone is

\left(\mathcal{R}_{p}^n\right)^* = \left\{
    x \in \mathbb{R}^n
~\middle|~
    \frac{4}{p} x_1 x_2 \geq \sum_{i = 2}^n x_i^2 \land x_1, x_2 \geq 0
\right\}=\mathcal{R}_{4/p}^n.

The cone is thus self-dual for p = 2.

__init__(p=1)[source]

Construct a rotated second order cone.

Parameters

p (float) – The positive factor p in the definition.

property p

A narrowing (p < 2) or widening (p > 2) factor.

SecondOrderCone

class picos.expressions.SecondOrderCone[source]

Bases: picos.expressions.set.Set

The second order cone.

Also known as the quadratic, 2-norm, Lorentz, or ice cream cone.

For n \in \mathbb{Z}_{\geq 2}, represents the convex cone

\mathcal{Q}^n = \left\{
    x \in \mathbb{R}^n
~\middle|~
    x_1 \geq \sqrt{\sum_{i = 2}^n x_i^2}
\right\}.

Dual cone

The second order cone as defined above is self-dual.

__init__()[source]

Construct a second order cone.

Set

class picos.expressions.Set(typeStr, symbStr)[source]

Bases: abc.ABC

Abstract base class for mathematical set expressions.

__init__(typeStr, symbStr)[source]

Perform basic initialization for Set instances.

Parameters
  • typeStr (str) – Short string denoting the set type.

  • symbStr (str) – Algebraic string description of the set.

replace_variables(new_variables)[source]

See replace_variables.

property refined

The set itself, as sets do not support refinement.

This exists for compatibility with expressions.

property string

Symbolic string representation of the set.

property subtype

See picos.expressions.Expression.subtype.

property type

See picos.expressions.Expression.type.

property variables

Return a Python set of variables that are involved in the set.

SetType

class picos.expressions.SetType(theClass, subtype)[source]

Bases: picos.expressions.expression.ExpressionType

ExpressionType for sets.

Simplex

class picos.expressions.Simplex(radius=<1×1 Real Constant: 1>, truncated=False, symmetrized=False)[source]

Bases: picos.expressions.set.Set

A (truncated, symmetrized) real simplex.

Definition

Let r \in \mathbb{R}_{\geq 0} the specified radius and n \in \mathbb{Z}_{\geq 1} an arbitrary dimensionality.

  1. Without truncation and symmetrization, this is the nonnegative simplex

    \{x \in \mathbb{R}^n_{\geq 0} \mid \sum_{i = 1}^n x_i \leq r\}.

    For r = 1, this is the standard (unit) n-simplex.

  2. With truncation but without symmetrization, this is the nonnegative simplex intersected with the \infty-norm unit ball

    \{
    x \in \mathbb{R}^n_{\geq 0}
\mid
    \sum_{i = 1}^n x_i \leq r \land x \leq 1
\}.

    For r \leq 1, this equals case (1).

  3. With symmetrization but without truncation, this is the 1-norm ball of radius r

    \{x \in \mathbb{R}^n \mid \sum_{i = 1}^n |x_i| \leq r\}.

  4. With both symmetrization and truncation, this is the convex polytope

    \{
    x \in \mathbb{R}
\mid
    \sum_{i = 1}^n |x_i| \leq r \land 0 \leq x \leq 1
\}.

    For r \leq 1, this equals case (3).

__init__(radius=<1×1 Real Constant: 1>, truncated=False, symmetrized=False)[source]

Construct a Simplex.

Parameters

radius (float or AffineExpression) – The radius of the simplex.

property radius

The radius of the simplex.

property symmetrized

Wether the simplex is mirrored onto all orthants.

property truncated

Whether this is intersected with the unit \infty-ball.

SkewSymmetricVariable

class picos.expressions.SkewSymmetricVariable(name, shape=1, 1, lower=None, upper=None)[source]

Bases: picos.expressions.variables.BaseVariable, picos.expressions.exp_affine.AffineExpression

A skew-symmetric matrix variable.

Stored internally and passed to solvers as a skew-symmetric vectorization with only \frac{n(n-1)}{2} entries.

__init__(name, shape=1, 1, lower=None, upper=None)[source]

Create a SkewSymmetricVariable.

Parameters
  • name (str) – The variable’s name, used for both string description and identification.

  • shape (int or tuple or list) – The shape of the matrix.

  • lower – Constant lower bound on the variable. May contain float("-inf") to denote unbounded elements.

  • upper – Constant upper bound on the variable. May contain float("inf") to denote unbounded elements.

SpectralNorm

class picos.expressions.SpectralNorm(x)[source]

Bases: picos.expressions.expression.Expression

The spectral norm of a matrix.

This class can represent the spectral norm of a matrix-affine expression (real- or complex valued). The spectral norm is convex, so we can form expressions of the form SpectralNorm(X) <= t which are typically reformulated as LMIs that can be handled by SDP solvers.

Definition

If the normed expression is a matrix X, then its spectral norm is

\|X\|_2 = \max \{  \|Xu\|_2 : \|u\| \leq  1\}
        = \sqrt{\lambda_{\max}(XX^*)},

where \lambda_{\max}(\cdot) denotes the largest eigenvalue of a matrix, and X^* denotes the adjoint matrix of X (i.e., the transposed matrix X^T if X is real-valued).

Special cases:

  • If X is scalar, then \|X\|_2 reduces to the the absolute value (or modulus) |X|.

  • If X is scalar, then \|X\|_2 coincides with the Euclidean norm of X.

__init__(x)[source]

Construct a SpectralNorm.

Parameters

x (ComplexAffineExpression) – The affine expression to take the norm of.

property x

Real expression whose norm equals that of the original expression.

SumExponentials

class picos.expressions.SumExponentials(x, y=None)[source]

Bases: picos.expressions.expression.Expression

Sum of elementwise exponentials of an affine expression.

Definition

Let x be an n-dimensional real affine expression.

  1. If no additional expression y is given, this is the sum of elementwise exponentials

    \sum_{i = 1}^n \exp(\operatorname{vec}(x)_i).

  2. If an additional affine expression y of same shape as x is given, this is the sum of elementwise perspectives of exponentials

    \sum_{i = 1}^n \operatorname{vec}(y)_i \exp\left(
\frac{\operatorname{vec}(x)_i}{\operatorname{vec}(y)_i}\right).

Warning

When you pose an upper bound t on a sum of elementwise exponentials, then PICOS enforces t \geq 0 through an auxiliary constraint during solution search. When an additional expression y is given, PICOS enforces y \geq 0 as well.

__init__(x, y=None)[source]

Construct a SumExponentials.

Parameters
  • x (AffineExpression) – The affine expression x.

  • y (AffineExpression) – An additional affine expression y. If necessary, PICOS will attempt to reshape or broadcast it to the shape of x.

property log

The logarithm of the expression.

property n

Length of x.

property x

The expression x.

property y

The additional expression y, or None.

SumExtremes

class picos.expressions.SumExtremes(x, k, largest, eigenvalues=False)[source]

Bases: picos.expressions.expression.Expression

Sum of the k largest or smallest elements or eigenvalues.

Definition

Let k \in \mathbb{Z}_{\geq 1}.

  1. If x is an n-dimensional real vector or matrix and eigenvalues == False, then this is the sum of the k \leq n largest or smallest scalar elements of x, depending on the truth value of largest.

    Special cases:

    • If k = 1, this is either the largest element \max_{i = 1}^n \operatorname{vec}(x)_i or the smallest element \min_{i = 1}^n \operatorname{vec}(x)_i of x.

    • If k = n, this is the sum of all elements \langle x, 1 \rangle of x.

  2. If X is an n \times n hermitian matrix and eigenvalues == True, then this is the sum of the k \leq n largest or smallest eigenvalues of X, depending on the truth value of largest. Recall that the eigenvalues of a hermitian matrix are real.

    Special cases:

    • If k = 1, this is either the largest eigenvalue \lambda_{\max}(X) or the smallest eigenvalue \lambda_{\min}(X) of X.

    • If k = n, this equals the trace \operatorname{tr}(X).

If the given k exceeds the n of either case, then k is silently clipped to n.

__init__(x, k, largest, eigenvalues=False)[source]

Construct a SumExtremes.

Parameters
  • x (ComplexAffineExpression) – The affine expression to take a sum over.

  • k (int) – Number of summands.

  • largest (bool) – Whether to sum over the largest (eigen)values as opposed to the smallest.

  • eigenvalues (bool) – Whether to sum eigenvalues instead of elements.

property eigenvalues

Whether the sum concerns eigenvalues as opposed to elements.

property full

Whether the sum concerns all (eigen)values of the expression.

property k

Number of (eigen)values to sum.

property largest

Whether the sum concerns largest values as opposed to smallest.

property x

The expression under the sum.

SymmetricVariable

class picos.expressions.SymmetricVariable(name, shape=1, 1, lower=None, upper=None)[source]

Bases: picos.expressions.variables.BaseVariable, picos.expressions.exp_affine.AffineExpression

A symmetric matrix variable.

Stored internally and passed to solvers as a symmetric vectorization with only \frac{n(n+1)}{2} entries.

__init__(name, shape=1, 1, lower=None, upper=None)[source]

Create a SymmetricVariable.

Parameters
  • name (str) – The variable’s name, used for both string description and identification.

  • shape (int or tuple or list) – The shape of the matrix.

  • lower – Constant lower bound on the variable. May contain float("-inf") to denote unbounded elements.

  • upper – Constant upper bound on the variable. May contain float("inf") to denote unbounded elements.

UpperTriangularVariable

class picos.expressions.UpperTriangularVariable(name, shape=1, 1, lower=None, upper=None)[source]

Bases: picos.expressions.variables.BaseVariable, picos.expressions.exp_affine.AffineExpression

An upper triangular matrix variable.

Stored internally and passed to solvers as an upper triangular vectorization with only \frac{n(n+1)}{2} entries.

__init__(name, shape=1, 1, lower=None, upper=None)[source]

Create a UpperTriangularVariable.

Parameters
  • name (str) – The variable’s name, used for both string description and identification.

  • shape (int or tuple or list) – The shape of the matrix.

  • lower – Constant lower bound on the variable. May contain float("-inf") to denote unbounded elements.

  • upper – Constant upper bound on the variable. May contain float("inf") to denote unbounded elements.

Functions

Constant

picos.expressions.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>

ball

picos.expressions.ball(*args, **kwargs)

Legacy shorthand for Ball.

Deprecated since version 2.0: Use Ball instead.

detrootn

picos.expressions.detrootn(*args, **kwargs)

Legacy shorthand for DetRootN.

Deprecated since version 2.0: Use DetRootN instead.

diag

picos.expressions.diag(x, n=1)[source]

Form a diagonal matrix from the column-major vectorization of x.

If n \neq 1, then the vectorization is repeated n times.

diag_vect

picos.expressions.diag_vect(x)[source]

Extract the diagonal of x as a column vector.

Deprecated since version 2.0: Use maindiag instead.

exp

picos.expressions.exp(x)[source]

Denote the exponential.

expcone

picos.expressions.expcone(*args, **kwargs)

Shorthand for ExponentialCone.

flow_Constraint

picos.expressions.flow_Constraint(*args, **kwargs)[source]

Legacy shorthand for FlowConstraint.

Deprecated since version 2.0: Use FlowConstraint instead.

geomean

picos.expressions.geomean(*args, **kwargs)

Shorthand for GeometricMean.

kldiv

picos.expressions.kldiv(*args, **kwargs)

Shorthand for NegativeEntropy.

kron

picos.expressions.kron(x, y)[source]

Denote the kronecker product.

Note that with Python 3, you can just write x @ y.

kullback_leibler

picos.expressions.kullback_leibler(*args, **kwargs)

Legacy shorthand for NegativeEntropy.

Deprecated since version 2.0: Use kldiv instead.

lambda_max

picos.expressions.lambda_max(x)[source]

Wrapper for SumExtremes.

Sets k = 1, largest = True and eigenvalues = True.

Example

>>> from picos import SymmetricVariable, lambda_max
>>> X = SymmetricVariable("X", 5)
>>> lambda_max(X)
<Largest Eigenvalue: λ_max(X)>
>>> lambda_max(X) <= 2
<Largest Eigenvalue Constraint: λ_max(X) ≤ 2>

lambda_min

picos.expressions.lambda_min(x)[source]

Wrapper for SumExtremes.

Sets k = 1, largest = False and eigenvalues = True.

Example

>>> from picos import SymmetricVariable, lambda_min
>>> X = SymmetricVariable("X", 5)
>>> lambda_min(X)
<Smallest Eigenvalue: λ_min(X)>
>>> lambda_min(X) >= 2
<Smallest Eigenvalue Constraint: λ_min(X) ≥ 2>

log

picos.expressions.log(x)[source]

Denote the natural logarithm.

logsumexp

picos.expressions.logsumexp(*args, **kwargs)

Legacy shorthand for LogSumExp.

Deprecated since version 2.0: Use lse instead.

lse

picos.expressions.lse(*args, **kwargs)

Shorthand for LogSumExp.

maindiag

picos.expressions.maindiag(x)[source]

Extract the diagonal of x as a column vector.

max

picos.expressions.max(x)[source]

Wrapper for SumExtremes.

Sets k = 1, largest = True and eigenvalues = False.

Example

>>> from picos import RealVariable, max
>>> x = RealVariable("x", 5)
>>> max(x)
<Largest Element: max(x)>
>>> max(x) <= 2  # The same as x <= 2.
<Largest Element Constraint: max(x) ≤ 2>

min

picos.expressions.min(x)[source]

Wrapper for SumExtremes.

Sets k = 1, largest = False and eigenvalues = False.

Example

>>> from picos import RealVariable, min
>>> x = RealVariable("x", 5)
>>> min(x)
<Smallest Element: min(x)>
>>> min(x) >= 2  # The same as x >= 2.
<Smallest Element Constraint: min(x) ≥ 2>

new_param

picos.expressions.new_param(name, value)[source]

Create a constant or a list or dict or tuple thereof.

Deprecated since version 2.0: Use Constant instead.

norm

picos.expressions.norm(*args, **kwargs)

Legacy shorthand for Norm.

Deprecated since version 2.0: Use Norm instead.

partial_trace

picos.expressions.partial_trace(x, subsystems=0, dimensions=2, k=None, dim=None)[source]

See expressions.ComplexAffineExpression.partial_trace.

The parameters k and dim are for backwards compatibility.

partial_transpose

picos.expressions.partial_transpose(x, subsystems=0, dimensions=2, k=None, dim=None)[source]

See expressions.ComplexAffineExpression.partial_transpose.

The parameters k and dim are for backwards compatibility.

rsoc

picos.expressions.rsoc(*args, **kwargs)

Shorthand for RotatedSecondOrderCone.

simplex

picos.expressions.simplex(gamma)[source]

Create a standard simplex of radius \gamma.

Deprecated since version 2.0: Use Simplex instead.

soc

picos.expressions.soc(*args, **kwargs)

Shorthand for SecondOrderCone.

sum

picos.expressions.sum(lst, it=None, indices=None)[source]

Sum PICOS expressions and give the result a meaningful description.

This is a replacement for Python’s sum that produces sensible string representations when summing PICOS expressions.

Parameters
Example

>>> import builtins
>>> import picos
>>> x = picos.RealVariable("x", 5)
>>> e = [x[i]*x[i+1] for i in range(len(x) - 1)]
>>> builtins.sum(e)
<Quadratic Expression: x[0]·x[1] + x[1]·x[2] + x[2]·x[3] + x[3]·x[4]>
>>> picos.sum(e)
<Quadratic Expression: ∑(x[i]·x[i+1] : i ∈ [0…3])>
>>> picos.sum(x)  # The same as (x|1).
<1×1 Real Linear Expression: ∑(x)>

sum_k_largest

picos.expressions.sum_k_largest(x, k)[source]

Wrapper for SumExtremes.

Sets largest = True and eigenvalues = False.

Example

>>> from picos import RealVariable, sum_k_largest
>>> x = RealVariable("x", 5)
>>> sum_k_largest(x, 2)
<Sum of Largest Elements: sum_2_largest(x)>
>>> sum_k_largest(x, 2) <= 2
<Sum of Largest Elements Constraint: sum_2_largest(x) ≤ 2>

sum_k_largest_lambda

picos.expressions.sum_k_largest_lambda(x, k)[source]

Wrapper for SumExtremes.

Sets largest = True and eigenvalues = True.

Example

>>> from picos import SymmetricVariable, sum_k_largest_lambda
>>> X = SymmetricVariable("X", 5)
>>> sum_k_largest_lambda(X, 2)
<Sum of Largest Eigenvalues: sum_2_largest_λ(X)>
>>> sum_k_largest_lambda(X, 2) <= 2
<Sum of Largest Eigenvalues Constraint: sum_2_largest_λ(X) ≤ 2>

sum_k_smallest

picos.expressions.sum_k_smallest(x, k)[source]

Wrapper for SumExtremes.

Sets largest = False and eigenvalues = False.

Example

>>> from picos import RealVariable, sum_k_smallest
>>> x = RealVariable("x", 5)
>>> sum_k_smallest(x, 2)
<Sum of Smallest Elements: sum_2_smallest(x)>
>>> sum_k_smallest(x, 2) >= 2
<Sum of Smallest Elements Constraint: sum_2_smallest(x) ≥ 2>

sum_k_smallest_lambda

picos.expressions.sum_k_smallest_lambda(x, k)[source]

Wrapper for SumExtremes.

Sets largest = False and eigenvalues = True.

Example

>>> from picos import SymmetricVariable, sum_k_smallest_lambda
>>> X = SymmetricVariable("X", 5)
>>> sum_k_smallest_lambda(X, 2)
<Sum of Smallest Eigenvalues: sum_2_smallest_λ(X)>
>>> sum_k_smallest_lambda(X, 2) >= 2
<Sum of Smallest Eigenvalues Constraint: sum_2_smallest_λ(X) ≥ 2>

sumexp

picos.expressions.sumexp(*args, **kwargs)

Shorthand for SumExponentials.

trace

picos.expressions.trace(x)[source]

Denote the trace of a square matrix.

tracepow

picos.expressions.tracepow(exp, num=1, denom=1, coef=None)[source]

Legacy shorthand for PowerTrace.

Deprecated since version 2.0: Use PowerTrace instead.

truncated_simplex

picos.expressions.truncated_simplex(gamma, sym=False)[source]

Create a truncated simplex of radius \gamma.

Deprecated since version 2.0: Use Simplex instead.

Exceptions

NotValued

exception picos.expressions.NotValued[source]

Bases: RuntimeError

The operation cannot be performed due to a variable without a value.

Note that the value and value_as_matrix attributes do not raise this exception, but return None.

__init__()

Initialize self. See help(type(self)) for accurate signature.

__new__()

Create and return a new object. See help(type) for accurate signature.

Data

picos.expressions.CONTINUOUS_VARTYPES

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable’s items.

If the argument is a tuple, the return value is the same object.