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.

Data¶

CONTINUOUS_VARTYPES

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}$ .

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).$
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.

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.

If no additional expression $y$ is given, this is the entropy

$-\sum_{i = 1}^n \operatorname{vec}(x)_i \log(\operatorname{vec}(x)_i).$
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.

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).$
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$ .

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.
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.
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}}$ .
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).
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$ .
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$ .
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}$ .

If the base expressions is a real scalar $x$ and no additional constant $m$ is given, then this is the power $x^p$ .
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$ .
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)$ .
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

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

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.
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).
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\}.$
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.

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

$\sum_{i = 1}^n \exp(\operatorname{vec}(x)_i).$
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}$ .

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$ .
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

lst (list or tuple or ComplexAffineExpression) – A list of ComplexAffineExpression, or a single affine expression whose elements shall be summed.
it – DEPRECATED
indices – DEPRECATED

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.