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)
+=:in-place 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 2, 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 \preceq); or, if the right hand side is a Set, membership in this set.
>>:greater than inequality in the Loewner ordering (linear matrix inequality \succeq )

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 expression exp2 (and hence exp3) is nonnegative.
  • Inequalities involving an exponentiation of the form x**p where p is not an even positive integer impose nonnegativity on x.
  • The linear matrix inequality exp1 >> exp2 only tells picos that the symmetric matrix whose lower triangular elements are those of exp1-exp2 is positive semidefinite. The matrix exp1-exp2 is not constrained to be symmetric. Hence, you should manually add the constraint exp1-exp2 == (exp1-exp2).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
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 n-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 X 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 det-root-n is applied

class picos.expressions.ExponentialCone

Bases: picos.expressions.Set

Represents the cone \operatorname{closure}\{(x,y,z): y \exp(z/y) \leq x, x,y > 0\}.

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

valueAsMatrix

Value of the expression.

Refer to value for when it is available.

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

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 a cvxopt sparse matrix X. Moreover, the call fx,grad,hess=f(X) must return the function value f(X) in fx, the gradient \nabla f(X) in the cvxopt matrix grad, and the Hessian \nabla^2 f(X) in the cvxopt 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 Kullback-Leibler divergence.

If an affine expression x of size N with elements x_1, x_2, \ldots, x_N is given, then KullbackLeibler(x) represents the (negative) entropy \sum_{i=1}^N x_i \log(x_i).

If a second expression y (of same dimension as x) is given, then KullbackLeibler(x, y) represents \sum_{i=1}^N x_i \log{x_i/y_i}.

Overloaded operators

+:addition (with a scalar AffinExp or another KullbackLeibler)
<:less or equal (than a scalar AffinExp)

Note

Upper-bounding a Kullback-Leibler divergence adds the implicit constraints x > 0 and y > 0.

eval(ind=None)
class picos.expressions.LogSumExp(exp)

Bases: picos.expressions.Expression

The logarithm of a sum of exponentials.

If an affine expression x of size N with elements x_1, x_2, \ldots, x_N is given, then LogSumExp(x) represents the expression \log \sum_{i=1}^N e^{x_i}.

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

+:addition (with a scalar AffinExp)
*:multiplication (with the expression under the logarithm)
>:greater or equal (than a scalar AffinExp)

Note

Lower-bounding \log(x) adds the implicit constraint x \geq 0.

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 2)
<: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 p-norm 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 L_{p,q} norm of a matrix.

Generalized norms are also defined for p < 1, by using the usual formula \operatorname{norm}(\mathbf{x},p) :=
\Big(\sum_i x_i^p\Big)^{1/p}. Note that this function is concave (for p<1) over the set of vectors with nonnegative coordinates. When a constraint of the form \operatorname{norm}(\mathbf{x},p) > t with p \leq 1 is entered, PICOS implicitely forces \mathbf{x} 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 p-norm 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‖², and
  • LR=(aff1,aff2) when the expression is equal to aff1*aff2.
aff = None

The affine part of the quadratic expression.

quad = None

Dictionary of quadratic forms, stored as matrices representing bilinear forms with respect to two vectorized variables, and indexed by tuples of instances of the class Variable.

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 x of size N with elements x_1, x_2, \ldots, x_N is given, then SumExponential(x) represents the expression \sum_{i=1}^N e^{x_i}.

If a second affine expression y (of same dimension as x) is given, then SumExponential(x, y) represents \sum_{i=1}^N y_i e^{x_i/y_i}.

Overloaded operators

+:addition (with a scalar AffinExp or another SumExponential)
*:multiplication (with a scalar AffinExp)
/:division (by a scalar AffinExp)
<:less or equal (than a scalar AffinExp or another SumExponential)

Note

Upper-bounding with a nonconstant scalar t adds the implicit constraint t > 0. Upper-bounding a sum of perspectives of exponentials (that is in the case of y \neq 1 given) independently adds the implicit constraint y > 0.

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 k largest elements of an AffinExp, or the sum of its k largest eigenvalues (for a square matrix expression).

Use the function picos.sum_k_largest or picos.sum_k_largest_lambda to create an instance of this class.

Note that the matrix X 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() or picos.sum_k_smallest_lambda() to create an instance of this class.

Note that the matrix X 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 p-th power of a scalar, or more generally the trace of the p-th power of a symmetric matrix, for some rational p.

The exponent p 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 0 \leq p \leq 1 and convex for both p \leq 0 and :math:p geq 1 for a non-negative (positive semidefinite) base. If the expression is concave, then an additional positive semdidefinite coefficient matrix M may be given so that the expression describes \operatorname{trace}(M X^p).

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 p-norm 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 infinity-norm (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)}
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.

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 i-th element of the variable var. None means +/- infinite. if var.bnd[i] is not defined, then var[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])