picos.expressions¶
This module contains the expression types created by PICOS when you perform
algebraic operations on variables and parameters. You do not need to create
expressions directly; it is more convenient to use standard Python operators
(see the Cheat Sheet) and additional algebraic functions (see the
picos
and picos.tools
namespaces) on the basic affine expressions
created by add_variable
and
new_param
.
Members¶

class
picos.expressions.
AffinExp
(factors=None, constant=None, size=(1, 1), string='0', typeBaseStr='Affine Expression')¶ Bases:
picos.expressions.Expression
A class for defining vectorial (or matrix) affine expressions.
Overloaded operators
+
:sum (with an affine or quadratic expression) +=
:inplace sum (with an affine or quadratic expression) 
:unitary minus or substraction (of an affine or quadratic expression) or unitary *
:multiplication (by another affine expression or a scalar) ^
:hadamard product (elementwise multiplication with another affine expression, similarly as MATLAB operator .*
)/
:division (by a scalar) 
:scalar product (with another affine expression) [·]
:slice of an affine expression abs(·)
:Euclidean norm (Frobenius norm for matrices) **
:exponentiation (works with arbitrary powers for constant affine expressions, and any nonzero exponent otherwise). In the case of a nonconstant affine expression, the exponentiation returns a quadratic expression if the exponent is , or a TracePow_Exp
object for other exponents. A rational approximation of the exponent is used, and the power inequality is internally replaced by an equivalent set of second order cone inequalities.&
:horizontal concatenation (with another affine expression) //
:vertical concatenation (with another affine expression) <
:less or equal (than an affine or quadratic expression) >
:greater or equal (than an affine or quadratic expression) ==
:is equal (to another affine expression) <<
:less than inequality in the Loewner ordering (linear matrix inequality ); or, if the right hand side is a Set
, membership in this set.>>
:greater than inequality in the Loewner ordering (linear matrix inequality ) Warning
We recall here the implicit assumptions that are made when using relation operator overloads:
 The rotated second order cone constraint
abs(exp1)**2 < exp2 * exp3
implicitely assumes that the scalar expressionexp2
(and henceexp3
) is nonnegative.  Inequalities involving an exponentiation of the form
x**p
wherep
is not an even positive integer impose nonnegativity onx
.  The linear matrix inequality
exp1 >> exp2
only tells picos that the symmetric matrix whose lower triangular elements are those ofexp1exp2
is positive semidefinite. The matrixexp1exp2
is not constrained to be symmetric. Hence, you should manually add the constraintexp1exp2 == (exp1exp2).T
if it is not clear from the data that this matrix is symmetric.

Htranspose
()¶ Hermitian (or conjugate) transposition.

apply_function
(fun)¶

conjugate
()¶ Complex conjugate.

copy
()¶

del_imag
()¶

del_real
()¶

del_type
()¶

del_value
()¶

diag
(dim)¶

eval
(ind=None)¶

classmethod
fromMatrix
(matrix, size=None)¶

classmethod
fromScalar
(scalar)¶

get_imag
()¶

get_real
()¶

get_type
()¶

hadamard
(fact)¶ hadamard (elementwise) product

inplace_Htranspose
()¶

inplace_conjugate
()¶

inplace_partial_transpose
(dim_1=None, subsystems=None, dim_2=None)¶

inplace_transpose
()¶

is0
()¶ Returns: Whether this is a scalar, vector or matrix of all zeros.

is1
()¶ Returns: Whether this is a scalar or vector of all ones.

is_pure_antisym_var
()¶

is_pure_complex_var
()¶

is_real
()¶

is_valued
(ind=None)¶

isconstant
()¶ is the expression constant (no variable involved) ?

partial_trace
(k=1, dim=None)¶ Partial trace, see also
the partial_trace tool

partial_transpose
(dim_1=None, subsystems=None, dim_2=None)¶ Partial transposition.

same_as
(other)¶

set_imag
(value)¶

set_real
(value)¶

set_type
(value)¶

set_value
(value)¶

soft_copy
()¶

sparse_rows
(varOffsetMap, lowerTriangle=False, upperTriangle=False, indexFunction=None)¶ A sparse list representation of the expression, given a mapping of PICOS variables to column offsets (or alternatively given an index function).
Parameters:  varOffsetMap (dict) – Maps variables or variable start indices to column offsets.
 lowerTriangle (bool) – Whether to return only the lower triangular part of the expression.
 lowerTriangle – 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. Each entry of the list represents a row in the vectorization of the expression.

transpose
()¶ Matrix transposition.

classmethod
zero
(size=(1, 1))¶

H
¶ Hermitian (or conjugate) transposition.

T
¶ Matrix transposition.

Tx
¶ Partial transposition for an n²×n² matrix, assuming subblocks of size n×n. Refer to
partial_transpose
.

conj
¶ Complex conjugate.

constant
= None¶ Constant of the affine expression, stored as a
cvxopt sparse matrix
.

factors
= None¶ Dictionary storing the matrix of coefficients of the linear part of the affine expressions. The matrices of coefficients are always stored with respect to vectorized variables (for the case of matrix variables), and are indexed by instances of the class
Variable
.

imag
¶ imaginary part (for complex expressions)

real
¶ real part (for complex expressions)

size
¶ Size of the affine expression.

typeStr
¶

vtype
¶
 The rotated second order cone constraint

class
picos.expressions.
Ball
(p, radius)¶ Bases:
picos.expressions.Set
Represents a ball of a given norm.
** Overloaded operators **
>>
:membership of the right hand side in this set.

class
picos.expressions.
DetRootN_Exp
(exp)¶ Bases:
picos.expressions.Expression
A class storing the th root of the determinant of a positive semidefinite matrix.
Use the function
picos.detrootn
to create an instance of this class.Note that the matrix is forced to be positive semidefinite when a constraint of the form
t < pic.detrootn(X)
is added.Overloaded operator
>
:greater or equal than (a scalar affine expression) 
eval
(ind=None)¶

dim
= None¶ dimension of
exp

exp
= None¶ The affine expression to which the detrootn is applied


class
picos.expressions.
ExponentialCone
¶ Bases:
picos.expressions.Set
Represents the cone .
** Overloaded operators **
>>
:membership of the right hand side in this set.

class
picos.expressions.
Expression
(typeStr, symbStr)¶ Bases:
object
The parent class of all expressions, including variables.

del_value
()¶

eval
()¶

get_value
()¶

get_value_as_matrix
()¶

has_complex_coef
()¶

is_valued
()¶ Returns: Whether the expression is valued. Example
>>> import picos as pic >>> prob=pic.Problem() >>> x=prob.add_variable('x',2) >>> x.is_valued() False >>> print(abs(x)) ‖x‖ >>> x.value=[3,4] >>> abs(x).is_valued() True >>> print(abs(x)) 5.0

set_value
(value)¶

string
= None¶ A symbolic string representation of the expression. It is always used by __descr__, and it is equivalent to the value returned by __str__ when the expression is not fully valued.

typeStr
= None¶ A string describing the expression type.

value
¶ Value of the expression.
It is defined (not None) in the following three situations:
 The expression is constant.
 Every variable involved in the expression is valued (this can be done
by setting
value
on each of the variables).  The expression involves variables of a problem that has already been solved, so that their values are set to some optimum value.
Unlike
valueAsMatrix
, scalars are returned as scalar types.


class
picos.expressions.
GeneralFun
(fun, Exp, funstring)¶ Bases:
picos.expressions.Expression
A class storing a scalar function, applied to an affine expression.

eval
(ind=None)¶

Exp
= None¶ The affine expression to which the function is applied

fun
= None¶ The function
f
applied to the affine expression. This function must take in argument acvxopt sparse matrix
X
. Moreover, the callfx,grad,hess=f(X)
must return the function value infx
, the gradient in thecvxopt matrix
grad
, and the Hessian in thecvxopt sparse matrix
hess
.

funstring
= None¶ a string representation of the function name


class
picos.expressions.
GeoMeanExp
(exp)¶ Bases:
picos.expressions.Expression
A class storing the geometric mean of a multidimensional expression.
Overloaded operator
>
:greater or equal than (the rhs must be a scalar affine expression) 
eval
(ind=None)¶

exp
= None¶ The affine expression to which the geomean is applied


class
picos.expressions.
KullbackLeibler
(exp, exp2=None)¶ Bases:
picos.expressions.Expression
A KullbackLeibler divergence.
If an affine expression of size with elements is given, then
KullbackLeibler(x)
represents the (negative) entropy .If a second expression (of same dimension as ) is given, then
KullbackLeibler(x, y)
represents .Overloaded operators
+
:addition (with a scalar AffinExp
or anotherKullbackLeibler
)<
:less or equal (than a scalar AffinExp
)Note
Upperbounding a KullbackLeibler divergence adds the implicit constraints and .

eval
(ind=None)¶


class
picos.expressions.
LogSumExp
(exp)¶ Bases:
picos.expressions.Expression
The logarithm of a sum of exponentials.
If an affine expression of size with elements is given, then
LogSumExp(x)
represents the expression .Overloaded operators
<
:less or equal than 
eval
(ind=None)¶


class
picos.expressions.
Logarithm
(exp)¶ Bases:
picos.expressions.Expression
The logarithm of a nonconstant scalar affine expression.
Overloaded operators
Note
Lowerbounding adds the implicit constraint .

eval
(ind=None)¶


class
picos.expressions.
Norm
(exp)¶ Bases:
picos.expressions.Expression
Euclidean (or Frobenius) norm of an Affine Expression.
Overloaded operators
**
:exponentiation (with an exponent of ) <
:less or equal (than a scalar affine expression) 
eval
(ind=None)¶

exp
= None¶ The affine expression of which we take the norm.


class
picos.expressions.
NormP_Exp
(exp, numerator, denominator=1, num2=None, den2=1)¶ Bases:
picos.expressions.Expression
A class storing the entrywise pnorm of a multidimensional expression.
Use the function
picos.norm()
to create an instance of this class. This class can also be used to store the norm of a matrix.Generalized norms are also defined for , by using the usual formula . Note that this function is concave (for ) over the set of vectors with nonnegative coordinates. When a constraint of the form with is entered, PICOS implicitely forces to be a nonnegative vector.
Overloaded operator
<
:less or equal than (a scalar affine expression, p >= 1) >
:greater or equal than (a scalar affine expression, p <= 1) 
eval
(ind=None)¶

den2
= None¶ denominator of q

denominator
= None¶ denominator of p

exp
= None¶ The affine expression to which the pnorm is applied

num2
= None¶ numerator of q

numerator
= None¶ numerator of p


class
picos.expressions.
QuadExp
(quad, aff, string, LR=None)¶ Bases:
picos.expressions.Expression
Quadratic expression.
Overloaded operators
+
:addition (with an affine or a quadratic expression) 
:unitary minus or substraction (of an affine or a quadratic expression) *
:multiplication (by a scalar or a constant affine expression) <
:less or equal than (a quadratic or affine expression) >
:greater or equal than (a quadratic or affine expression). 
copy
()¶

eval
(ind=None)¶

nnz
()¶

LR
= None¶ Stores a factorization of the quadratic expression, if the expression was entered in a factorized form. We have:
LR=None
when no factorization is known,LR=(aff,None)
when the expression is equal to‖aff‖²
, andLR=(aff1,aff2)
when the expression is equal toaff1*aff2
.

aff
= None¶ The affine part of the quadratic expression.


class
picos.expressions.
Set
(typeStr, symbStr=None)¶ Bases:
object
Parent class for set expressions.

string
¶


class
picos.expressions.
SumExponential
(exp, exp2=None)¶ Bases:
picos.expressions.Expression
A sum of (perspectives of) exponentials.
If an affine expression of size with elements is given, then
SumExponential(x)
represents the expression .If a second affine expression (of same dimension as ) is given, then
SumExponential(x, y)
represents .Overloaded operators
+
:addition (with a scalar AffinExp
or anotherSumExponential
)*
:multiplication (with a scalar AffinExp
)/
:division (by a scalar AffinExp
)<
:less or equal (than a scalar AffinExp
or anotherSumExponential
)Note
Upperbounding with a nonconstant scalar adds the implicit constraint . Upperbounding a sum of perspectives of exponentials (that is in the case of given) independently adds the implicit constraint .

eval
(ind=None)¶


class
picos.expressions.
Sum_k_Largest_Exp
(exp, k, eigenvals=False)¶ Bases:
picos.expressions.Expression
A class storing the sum of the largest elements of an
AffinExp
, or the sum of its largest eigenvalues (for a square matrix expression).Use the function
picos.sum_k_largest
orpicos.sum_k_largest_lambda
to create an instance of this class.Note that the matrix is assumed to be symmetric when a constraint of the form
pic.sum_k_largest_lambda(X,k) < t
is added.Overloaded operator
<
:smaller or equal than (a scalar affine expression) 
eval
(ind=None)¶

eigenvalues
= None¶ whether this is a sum of k largest eigenvalues (for symmetric matrices)

exp
= None¶ The affine expression to which the sum_k_largest is applied

k
= None¶ The number of elements to sum


class
picos.expressions.
Sum_k_Smallest_Exp
(exp, k, eigenvals=False)¶ Bases:
picos.expressions.Expression
A class storing the sum of the k smallest elements of an
AffinExp
, or the sum of its k smallest eigenvalues (for a square matrix expression).Use the function
picos.sum_k_smallest()
orpicos.sum_k_smallest_lambda()
to create an instance of this class.Note that the matrix is assumed to be symmetric when a constraint of the form
pic.sum_k_smallest_lambda(X,k) > t
is added.Overloaded operator
>
:greater or equal than (a scalar affine expression) 
eval
(ind=None)¶

eigenvalues
= None¶ whether this is a sum of k smallest eigenvalues (for symmetric matrices)

exp
= None¶ The affine expression to which sum_k_smallest is applied

k
= None¶ The number of elements to sum


class
picos.expressions.
TracePow_Exp
(exp, numerator, denominator=1, M=None)¶ Bases:
picos.expressions.Expression
The th power of a scalar, or more generally the trace of the th power of a symmetric matrix, for some rational .
The exponent is given in the form of a numerator/denominator pair.
You can use the shorthand function
picos.tracepow()
and the overloaded exponentiation operator**
to create an instance of this class.Note that this expression is concave for and convex for both and :math:p geq 1 for a nonnegative (positive semidefinite) base. If the expression is concave, then an additional positive semdidefinite coefficient matrix may be given so that the expression describes .
Warning
The symmetry of the base matrix and the positive semidefiniteness of the optional coefficient matrix are not checked or enforced by PICOS.
Overloaded operator
<
:less or equal than (a scalar affine expression, for a convex power) >
:greater or equal than (a scalar affine expression, for a concave power) 
eval
(ind=None)¶

M
= None¶ the coef matrix

denominator
= None¶ denominator of p

dim
= None¶ dimension of
exp

exp
= None¶ The affine expression to which the pnorm is applied

numerator
= None¶ numerator of p


class
picos.expressions.
TruncatedSimplex
(radius=1, truncated=False, nonneg=True)¶ Bases:
picos.expressions.Set
Represents a simplex, that can be intersected with the ball of radius 1 for the infinitynorm (truncation), and that can be symmetrized with respect to the origin.
** Overloaded operators **
>>
:membership of the right hand side in this set.

class
picos.expressions.
Variable
(parent_problem, name, size, Id, startIndex, vtype='continuous', lower=None, upper=None)¶ Bases:
picos.expressions.AffinExp
This class stores a variable.

bound_constraint
()¶ Returns the variable bounds in the form of a PICOS multidimensional
affine constraint
.

del_value
(index=None)¶

eval
(ind=None)¶

set_lower
(lo)¶ sets a lower bound to the variable (lo may be scalar or a matrix of the same size as the variable
self
). Entries smaller than INFINITY = 1e16 are ignored

set_sparse_lower
(indices, bnds)¶ sets the lower bound bnds[i] to the index indices[i] of the variable.
For a symmetric matrix variable, bounds on elements in the upper triangle are ignored.
Parameters:  indices (
list
) – list of indices, given as integers (column major order) or tuples (i,j).  bnds – list of lower bounds.
Warning
This function does not modify the existing bounds on elements other than those specified in
indices
.Example:
>>> import picos as pic >>> P = pic.Problem() >>> X = P.add_variable('X',(3,2),lower = 0) >>> X.set_sparse_upper([0,(0,1),1],[1,2,0]) >>> X.bnd #doctest: +NORMALIZE_WHITESPACE {0: (0.0, 1.0), 1: (0.0, 0.0), 2: (0.0, None), 3: (0.0, 2.0), 4: (0.0, None), 5: (0.0, None)}
 indices (

set_sparse_upper
(indices, bnds)¶ sets the upper bound bnds[i] to the index indices[i] of the variable.
For a symmetric matrix variable, bounds on elements in the upper triangle are ignored.
Parameters:  indices (
list
) – list of indices, given as integers (column major order) or tuples (i,j).  bnds – list of upper bounds.
Warning
This function does not modify the existing bounds on elements other than those specified in
indices
. indices (

set_upper
(up)¶ sets an upper bound to the variable (up may be scalar or a matrix of the same size as the variable
self
). Entries larger than INFINITY = 1e16 are ignored

set_value
(value, index=None)¶

Id
= None¶ An integer index (obsolete)

bnd
¶ var.bnd[i]
returns a tuple(lo,up)
of lower and upper bounds for the ith element of the variablevar
. None means +/ infinite. ifvar.bnd[i]
is not defined, thenvar[i]
is unbounded.

dim
¶ The algebraic dimension of the variable.

endIndex
¶ end position in the global vector of all variables

name
= None¶ The name of the variable (str)

origin
= None¶ The metaconstraint that created this variable, if any.

parent_problem
= None¶ The Problem instance to which this variable belongs

semiDef
= None¶ Conditionally evaluates to True if this is a symmetric variable subject to X >> 0. Counts the number of constraints stating this.

startIndex
¶ starting position in the global vector of all variables

typeStr
¶

vtype
¶ one of the following strings:
 ‘continuous’ (continuous variable)
 ‘binary’ (binary 0/1 variable)
 ‘integer’ (integer variable)
 ‘symmetric’ (symmetric matrix variable)
 ‘antisym’ (antisymmetric matrix variable)
 ‘complex’ (complex matrix variable)
 ‘hermitian’ (complex hermitian matrix variable)
 ‘semicont’ (semicontinuous variable
 [can take the value 0 or any other admissible value])
 ‘semiint’ (semi integer variable
 [can take the value 0 or any other integer admissible value])
