picos.expressions¶
Mathematical expression types.
Outline¶
Classes¶
A multidimensional real affine expression. 

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

Primary base class for all variable types. 

A valued variable. 

A multidimensional complex affine expression. 

A complexvalued variable. 

The th root of the determinant of an matrix. 

Entropy or negative relative entropy of an affine expression. 

The exponential cone. 

Abstract base class for mathematical expressions, including variables. 

The detailed type of an expression for predicting constraint outcomes. 

Geometric mean of an affine expression. 

A hermitian matrix variable. 

An integervalued variable. 

Logarithm of the sum of elementwise exponentials of an expression. 

Logarithm of a scalar affine expression. 

A lower triangular matrix variable. 

Negative or relative entropy of an affine expression. 

Entrywise norm or norm of an expression. 

The nuclear norm of a matrix. 

The trace of the th power of a hermitian matrix. 

A scalar quadratic expression of the form . 

A realvalued variable. 

The (narrowed or widened) rotated second order cone. 

The second order cone. 

Abstract base class for mathematical set expressions. 



A (truncated, symmetrized) real simplex. 

A skewsymmetric matrix variable. 

The spectral norm of a matrix. 

Sum of elementwise exponentials of an affine expression. 

Sum of the largest or smallest elements or eigenvalues. 

A symmetric matrix variable. 

An upper triangular matrix variable. 
Functions¶
Create a constant PICOS expression. 

Legacy shorthand for 

Legacy shorthand for 

Form a diagonal matrix from the columnmajor vectorization of . 

Extract the diagonal of as a column vector. 

Denote the exponential. 

Shorthand for 

Legacy shorthand for 

Shorthand for 

Shorthand for 

Denote the kronecker product. 

Legacy shorthand for 

Wrapper for 

Wrapper for 

Denote the natural logarithm. 

Legacy shorthand for 

Shorthand for 

Extract the diagonal of as a column vector. 

Wrapper for 

Wrapper for 

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

Legacy shorthand for 

Shorthand for 

Create a standard simplex of radius . 

Shorthand for 

Sum PICOS expressions and give the result a meaningful description. 

Wrapper for 

Wrapper for 

Wrapper for 

Wrapper for 

Shorthand for 

Denote the trace of a square matrix. 

Legacy shorthand for 

Create a truncated simplex of radius . 
Data¶
Submodules¶
Implements functions that create or modify algebraic expressions. 

Functions to load and work with raw numeric data. 

Implements affine expression types. 

Implements 

Implements 

Implements 

Implements 

Implements 

Implements 

Implements 

Implements 

Implements 

Implements 

Backend for expression type implementations. 

Backend for mathematical set type implementations. 

Implements 

Implements 

Implements 

Implements 

Implements 

Implements all mathematical variable types. 

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.

property
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 according to a (generalized) norm.
 Definition
In the following, refers to the vector norm or to the entrywise matrix norm, depending on the argument. See
Norm
for definitions.Let .
For , this is the convex set
for any
For a generalized norm with , this is the convex set
for any
Note that may not be complex if due to the implicit constraint in this case, which is not meaningful on the complex field.
Note further that 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 norm ball of given radius.
 Parameters
radius (float or AffineExpression) – The ball’s radius.
p (float) – The value for , which is cast to a limited precision fraction.
denominator_limit (int) – The largest allowed denominator when casting to a fraction. Higher values can yield a greater precision at reduced performance.

property
p
¶ The value defining the norm used.
This is a limited precision version of the paramter used when the ball was constructed.

property
r
¶ The ball’s radius .
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
orAffineExpression
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

static

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

classmethod
make_var_type
(*args, **kwargs)[source]¶ Create a detailed variable type from subtype parameters.
See also
var_type
.

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")
andfloat("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
name
¶ The name of the variable.

property
num_bounds
¶ Number of scalar bounds associated with the variable.

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.

class
BinaryVariable¶

class
picos.expressions.
BinaryVariable
(name, shape=1, 1)[source]¶ Bases:
picos.expressions.variables.BaseVariable
,picos.expressions.exp_affine.AffineExpression
A valued 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 aConstant
. Parameters
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]

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 columnmajor order.
 Parameters
n (int) – Number of times to duplicate the vectorization.

dupvec
(n)[source]¶ Return a (repeated) columnmajor 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 anAffineExpression
.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,
 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 for matrices with shapes given in
dimensions
, then this returns with , ifi in subsystems
(with read as ), and , 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 refers to the last subsystem.
dimensions (int or tuple or list) – Either an integer so that the subsystems are assumed to be all of shape , or a sequence of subsystem shapes where an integer within the sequence is read as . 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 nonsquare 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 for matrices with shapes given in
dimensions
, then this returns with , ifi in subsystems
(with read as ), and , 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 refers to the last subsystem.
dimensions (int or tuple or list) – Either an integer so that the subsystems are assumed to be all of shape , or a sequence of subsystem shapes where an integer within the sequence is read as . 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]

reshaped
(shape)[source]¶ Return the expression reshaped in columnmajor 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
orbroadcasted
.Unlike with
reshaped
andbroadcasted
, the target shape may not contain a wildcard character.If the wildcardfree target shape has the same number of elements as the current shape, then this is the same as
reshaped
, otherwise it is the same asbroadcasted
.

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.

property
H
¶ Conjugate (or Hermitian) transpose.

property
T
¶ Matrix transpose.

property
T0
¶ Expression with the first subsystem transposed.
Only available for a matrix with all subsystems of shape . Use
partial_transpose
otherwise.

property
T1
¶ Expression with the second subsystem transposed.
Only available for a matrix with all subsystems of shape . Use
partial_transpose
otherwise.

property
T2
¶ Expression with the third subsystem transposed.
Only available for a matrix with all subsystems of shape . Use
partial_transpose
otherwise.

property
T3
¶ Expression with the fourth subsystem transposed.
Only available for a matrix with all subsystems of shape . Use
partial_transpose
otherwise.

property
Tl
¶ Expression with the last subsystem transposed.
Only available for a matrix with all subsystems of shape . Use
partial_transpose
otherwise.

property
Tx
¶ Autodetect 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 complexvalued.

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 columnmajor 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 , this is .
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 realvalued.

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 subsystem traced out.
Only available for a matrix with all subsystems of shape . Use
partial_trace
otherwise.

property
tr1
¶ Expression with the second subsystem traced out.
Only available for a matrix with all subsystems of shape . Use
partial_trace
otherwise.

property
tr2
¶ Expression with the third subsystem traced out.
Only available for a matrix with all subsystems of shape . Use
partial_trace
otherwise.

property
tr3
¶ Expression with the fourth subsystem traced out.
Only available for a matrix with all subsystems of shape . Use
partial_trace
otherwise.

property
trilvec
¶ Columnmajor vectorization of the lower triangular part.
 Returns
A column vector of all elements that satisfy .
Note
If you want a rowmajor vectorization instead, write
A.T.triuvec
instead ofA.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
¶ Columnmajor vectorization of the upper triangular part.
 Returns
A column vector of all elements that satisfy .
Note
If you want a rowmajor vectorization instead, write
A.T.trilvec
instead ofA.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 subsystem traced out.
Only available for a matrix with all subsystems of shape . Use
partial_trace
otherwise.

property
vec
¶ Columnmajor vectorization of the expression as a column vector.
Note
Given an expression
A
,A.vec
andA[:]
produce the same result (up to its string description) butA.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 complexvalued variable.
Passed to solvers as a real variable vector with entries.
DetRootN¶

class
picos.expressions.
DetRootN
(x)[source]¶ Bases:
picos.expressions.expression.Expression
The th root of the determinant of an matrix.
 Definition
For an positive semidefinite hermitian matrix , this is
Warning
When you pose a lower bound on the th root of a determinant of the matrix , then PICOS enforces positive semidefiniteness 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
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 be an dimensional real affine expression.
If no additional expression is given, this is the entropy
If an additional affine expression of same shape as is given, this is the negative relative entropy (or logarithmic perspective)
Warning
When you pose a lower bound on this expression, then PICOS enforces through an auxiliary constraint during solution search. When an additional expression is given, PICOS enforces as well.

__init__
(x, y=None)[source]¶ Construct an
Entropy
. Parameters
x (AffineExpression) – The affine expression .
y (AffineExpression) – An additional affine expression . If necessary, PICOS will attempt to reshape or broadcast it to the shape of .

property
x
¶ The expression .
ExponentialCone¶

class
picos.expressions.
ExponentialCone
[source]¶ Bases:
picos.expressions.set.Set
The exponential cone.
Represents the convex 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.

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

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 anAffineExpression
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
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 whosetype
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 theirvalue
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 welldetermined 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.00e01 4.00e01 6.00e01] y: [4.00e01 8.00e01 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 (notNone
).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 isNone
. 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((x1)) ∑(x) >>> x.value = [1, 2, 3] >>> (x1).valued True >>> print((x1)) 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 dimensional affine expression with , the geometric mean is given as
Warning
When you pose a lower bound on a geometric mean, then PICOS enforces 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 entries and a real skewsymmetric vectorization with entries, resulting in a real vector with only entries total.
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 integervalued 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 dimensional real affine expression , this is the logarithm of the sum of elementwise exponentials

__init__
(x)[source]¶ Construct a
LogSumExp
. Parameters
x (AffineExpression) – The affine expression .

property
exp
¶ The elementwise sum of exponentials of .

property
x
¶ The expression .
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 , this is .
Warning
When you pose a lower bound on a logarithm , then PICOS enforces through an auxiliary constraint during solution search.

__init__
(x)[source]¶ Construct a
Logarithm
. Parameters
x (AffineExpression) – The scalar affine expression .

property
exp
¶ The exponential of the logarithm, equal to .

property
x
¶ The expression .
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 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.
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 KullbackLeibler divergence.
 Definition
Let be an dimensional real affine expression.
If no additional expression is given, this is the negative entropy
If an additional affine expression of same shape as is given, this is the relative entropy (or KullbackLeibler divergence)
Warning
When you pose an upper bound on this expression, then PICOS enforces through an auxiliary constraint during solution search. When an additional expression is given, PICOS enforces as well.

__init__
(x, y=None)[source]¶ Construct a
NegativeEntropy
. Parameters
x (AffineExpression) – The affine expression .
y (AffineExpression) – An additional affine expression . If necessary, PICOS will attempt to reshape or broadcast it to the shape of .

property
x
¶ The expression .
Norm¶

class
picos.expressions.
Norm
(x, p=2, q=None, denominator_limit=1000)[source]¶ Bases:
picos.expressions.expression.Expression
Entrywise norm or norm of an expression.
This class can represent the absolute value, the modulus, a vector norm and an entrywise matrix norm of a (complex) affine expression. In addition to these convex norms, it can represent the concave generalized vector norm with .
Not all of these norms are available on the complex field; see the definitions below to learn more.
 Definition
If is not given (
None
), then it is set equal to .If the normed expression is a real scalar , then this is the absolute value
The parameters and are ignored in this case.
If the normed expression is a complex scalar , then this is the modulus
The parameters and are ignored in this case.
If the normed expression is a real vector and , then this is the (generalized) vector norm
for with and the absolute value of the th entry of .
Note that for 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 .
Warning
When you pose a lower bound on a concave generalized norm (), then PICOS enforces through an auxiliary constraint during solution search.
Special cases:
For , this is the Manhattan or Taxicab norm .
For , this is the Euclidean norm .
For , this is the Maximum, Chebyshev, or Infinity norm .
If the normed expression is a real vector and , then it is treated as a matrix with a single row or a single column, depending on the shape associated with . See case (5).
If the normed expression is a complex vector and , then the definition is the same as in case (3) but with , the modulus of the th entry of , and .
If the normed expression is a real matrix , then this is the norm
for with .
If , then this is equal to the (generalized) vector norm of the the vectorized matrix, that is . In this case, the requirement is relaxed to and may be a complex matrix. See case (3).
Special cases:
For , this is the Frobenius norm .
For , , this is the maximum absolute column sum
This equals the operator norm induced by the vector norm. You can obtain the maximum absolute row sum (the operator norm induced by the vector norm) by first transposing .
Complex matrix norms are not supported.
Note
You can write 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 , which is cast to a limited precision fraction.
q (float) – The value for , which is cast to a limited precision fraction. The default of
None
means equal to .denominator_limit (int) – The largest allowed denominator when casting and to a fraction. Higher values can yield a greater precision at reduced performance.

property
p
¶ The parameter .
This is a limited precision version of the paramter used when the norm was constructed.

property
pden
¶ The limited precision fraction denominator of .

property
pnum
¶ The limited precision fraction numerator of .

property
q
¶ The parameter .
This is a limited precision version of the paramter used when the norm was constructed.

property
qden
¶ The limited precision fraction denominator of .

property
qnum
¶ The limited precision fraction numerator of .

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 matrixaffine 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 , then its nuclear norm is
where the denote the singular values of a , and denotes the adjoint matrix of (i.e., the transposed matrix if is realvalued).
Special cases:
If is scalar, then reduces to the the absolute value (or modulus) .
If is scalar, then coincides with the Euclidean norm of .

__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 th power of a hermitian matrix.
 Definition
Let .
If the base expressions is a real scalar and no additional constant is given, then this is the power .
If the base expressions is a real scalar , , and a positive scalar constant is given, then this is the scaled power .
If the base expression is a hermitian matrix and no additional constant is given, then this is the trace of power .
If the base expression is a hermitian matrix , , and a hermitian positive semidefinite constant matrix of same shape as is given, then this is the trace of a scaled power .
No other case is supported. In particular, if , then / must be undefined (
None
).Warning
For a constraint of the form with and , PICOS enforces during solution search.
For a constraint of the form or with and , PICOS enforces during solution search.
For a constraint of the form or with , PICOS enforces 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 , which is cast to a limited precision fraction.
m (
AffineExpression
or anything recognized byload_data
) – An additional positive semidefinite constant to multiply the power with.denominator_limit (int) – The largest allowed denominator when casting to a fraction. Higher values can yield a greater precision at reduced performance.

property
den
¶ The limited precision fraction denominator of .

property
m
¶ An additional factor to multiply the power with.

property
num
¶ The limited precision fraction numerator of .

property
p
¶ The parameter .
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 .

__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 aConstant
. Parameters
string (str) – A symbolic string description.
quadraticPart – A
dict
mapping PICOS variable pairs to CVXOPT matrices. Each entry represents a quadratic form where and refer to the isometric realvectorizations
that are used by PICOS internally to store the variables and , respectively. The quadratic part of the expression is then given as .affinePart (AffineExpression) – The affine part of the expression.
scalarFactors – A pair with both and scalar real affine expressions representing a known factorization of the expression.
copyDecomposition (QuadraticExpression) – Another quadratic expression with equal quadratic part whose quadratic part decomposition shall be copied.

property
A
¶ An affineaugmented quadratic coefficient matrix, condensed.
For a quadratic expression , this is but with zero rows and columns removed.
The vector
y
is a condensed version of that refers to this matrix, so thatq.y.T*q.A*q.y
equals the expressionq
. Raises
ValueError – When the expression is zero.

property
L
¶ The of an 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 of an 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 of the expression, condensed.
This equals the of the quadratic expression but with zero rows and columns removed.
The vector
x
is a condensed version of that refers to this matrix, so thatq.x.T*q.Q*q.x
equals the quadratic part of the expressionq
. Raises
ValueError – When the quadratic part is zero.

property
aff
¶ Affine part of the quadratic expression.

property
cst
¶ Constant part 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 vectorq.M.T*q.y
with zero rows removed. Construction
For a quadratic expression with positive semidefinite, let be a Cholesky decomposition. Let further . Then,
Note that removing zero rows from 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 such thatIf the expression is also nonzero, then
fullroot
is with zero entries removed.

property
lin
¶ Linear part of the quadratic expression.

property
num_quad_terms
¶ The number of terms in the simplified quadratic form.

property
quad
¶ Quadratic part of the quadratic expression.

property
quadratic_forms
¶ The quadratic forms as sparse matrices.

property
quadroot
¶ Affine expression whose squared norm equals .
For a convex quadratic expression
q
, this is equal to the vectorq.L.T*q.x
with zero rows removed. Construction
Let be the quadratic part of the expression with positive semidefinite and a Cholesky decomposition. Then,
Note that removing zero rows from 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 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 for scalar real affine expressions and , returns the pair
(a, b)
. Otherwise, returns the empty tuple()
.Note that if , then also
a is b
in the returned tuple.

property
x
¶ The stacked variable vector of the expression, condensed.
This equals the of the quadratic expression but entries corresponding to zero rows and columns in
Q
are removed, so thatq.x.T*q.Q*q.x
equals the part of the expressionq
. 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 realvalued 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 and , represents the convex cone
For , this is the standard rotated second order cone obtained by rotating the
second order cone
by in the plane.The default instance of this class has , 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 is not selfdual, so working with may seem more natural when the dual problem is of interest.
 Dual cone
The dual cone is
The cone is thus selfdual for .

__init__
(p=1)[source]¶ Construct a rotated second order cone.
 Parameters
p (float) – The positive factor in the definition.

property
p
¶ A narrowing () or widening () factor.
SecondOrderCone¶

class
picos.expressions.
SecondOrderCone
[source]¶ Bases:
picos.expressions.set.Set
The second order cone.
Also known as the quadratic, norm, Lorentz, or ice cream cone.
For , represents the convex cone
 Dual cone
The second order cone as defined above is selfdual.
Set¶

class
picos.expressions.
Set
(typeStr, symbStr)[source]¶ Bases:
abc.ABC
Abstract base class for mathematical set expressions.

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
¶

property
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 the specified radius and an arbitrary dimensionality.
Without truncation and symmetrization, this is the nonnegative simplex
For , this is the standard (unit) simplex.
With truncation but without symmetrization, this is the nonnegative simplex intersected with the norm unit ball
For , this equals case (1).
With symmetrization but without truncation, this is the norm ball of radius
With both symmetrization and truncation, this is the convex polytope
For , 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 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 skewsymmetric matrix variable.
Stored internally and passed to solvers as a skewsymmetric vectorization with only 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.
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 matrixaffine 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 , then its spectral norm is
where denotes the largest eigenvalue of a matrix, and denotes the adjoint matrix of (i.e., the transposed matrix if is realvalued).
Special cases:
If is scalar, then reduces to the the absolute value (or modulus) .
If is scalar, then coincides with the Euclidean norm of .

__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 be an dimensional real affine expression.
If no additional expression is given, this is the sum of elementwise exponentials
If an additional affine expression of same shape as is given, this is the sum of elementwise perspectives of exponentials
Warning
When you pose an upper bound on a sum of elementwise exponentials, then PICOS enforces through an auxiliary constraint during solution search. When an additional expression is given, PICOS enforces as well.

__init__
(x, y=None)[source]¶ Construct a
SumExponentials
. Parameters
x (AffineExpression) – The affine expression .
y (AffineExpression) – An additional affine expression . If necessary, PICOS will attempt to reshape or broadcast it to the shape of .

property
log
¶ The logarithm of the expression.

property
x
¶ The expression .
SumExtremes¶

class
picos.expressions.
SumExtremes
(x, k, largest, eigenvalues=False)[source]¶ Bases:
picos.expressions.expression.Expression
Sum of the largest or smallest elements or eigenvalues.
 Definition
Let .
If is an dimensional real vector or matrix and
eigenvalues == False
, then this is the sum of the largest or smallest scalar elements of , depending on the truth value oflargest
.Special cases:
If , this is either the largest element or the smallest element of .
If , this is the sum of all elements of .
If is an hermitian matrix and
eigenvalues == True
, then this is the sum of the largest or smallest eigenvalues of , depending on the truth value oflargest
. Recall that the eigenvalues of a hermitian matrix are real.Special cases:
If , this is either the largest eigenvalue or the smallest eigenvalue of .
If , this equals the trace .
If the given exceeds the of either case, then is silently clipped to .

__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 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.
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 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.
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
orAffineExpression
, depending on the value. Optionally, the value is broadcasted or reshaped according to the shape argument. Parameters
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¶
detrootn¶
diag¶
diag_vect¶
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¶
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
andeigenvalues = 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
andeigenvalues = 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>
logsumexp¶
max¶

picos.expressions.
max
(x)[source]¶ Wrapper for
SumExtremes
.Sets
k = 1
,largest = True
andeigenvalues = 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
andeigenvalues = 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¶
norm¶
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¶
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 (x1). <1×1 Real Linear Expression: ∑(x)>
sum_k_largest¶

picos.expressions.
sum_k_largest
(x, k)[source]¶ Wrapper for
SumExtremes
.Sets
largest = True
andeigenvalues = 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
andeigenvalues = 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
andeigenvalues = 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
andeigenvalues = 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
.
tracepow¶

picos.expressions.
tracepow
(exp, num=1, denom=1, coef=None)[source]¶ Legacy shorthand for
PowerTrace
.Deprecated since version 2.0: Use
PowerTrace
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
andvalue_as_matrix
attributes do not raise this exception, but returnNone
.
__init__
()¶ Initialize self. See help(type(self)) for accurate signature.

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