tools.py¶

picos.tools.
eval_dict
(dict_of_variables)¶ if
dict_of_variables
is a dictionary mapping variable names (strings) tovariables
, this function returns the dictionarynames > variable values
.

picos.tools.
svec
(mat, ignore_sym=False)¶ returns the svec representation of the cvx matrix
mat
. (see Dattorro, ch.2.2.2.1)If
ignore_sym = False
(default), the function raises an Exception ifmat
is not symmetric. Otherwise, elements in the lower triangle ofmat
are simply ignored.

picos.tools.
ltrim1
(vec, uptri=True, offdiag_fact=1.0)¶ If
vec
is a vector or an affine expression of size n(n+1)/2, ltrim1(vec) returns a (n,n) matrix with the elements of vec in the lower triangle. Ifuptri == False
, the upper triangle is 0, otherwise the upper triangle is the symmetric of the lower one.

picos.tools.
lowtri
(exp)¶ if
exp
is a square affine expression of size (n,n),lowtri(exp)
returns the (n(n+1)/2)vector of the lower triangular elements ofexp
.Example
>>> import picos as pic >>> import cvxopt as cvx >>> prob=pic.Problem() >>> X=prob.add_variable('X',(4,4),'symmetric') >>> pic.tools.lowtri(X) # (10 x 1)affine expression: lowtri(X) # >>> X0 = cvx.matrix(range(16),(4,4)) >>> X.value = X0 * X0.T >>> print(X) #doctest: +NORMALIZE_WHITESPACE [ 2.24e+02 2.48e+02 2.72e+02 2.96e+02] [ 2.48e+02 2.76e+02 3.04e+02 3.32e+02] [ 2.72e+02 3.04e+02 3.36e+02 3.68e+02] [ 2.96e+02 3.32e+02 3.68e+02 4.04e+02] >>> print(pic.tools.lowtri(X)) #doctest: +NORMALIZE_WHITESPACE [ 2.24e+02] [ 2.48e+02] [ 2.72e+02] [ 2.96e+02] [ 2.76e+02] [ 3.04e+02] [ 3.32e+02] [ 3.36e+02] [ 3.68e+02] [ 4.04e+02]

picos.tools.
sum
(lst, it=None, indices=None)¶ sum of a list of affine expressions. This fonction can be used with python list comprehensions (see the example below).
Parameters:  lst – list of
AffinExp
.  it (None or str or list.) – Description of the letters which should
be used to replace the dummy indices.
The function tries to find a template
for the string representations of the
affine expressions in the list.
If several indices change in the
list, their letters should be given as a
list of strings, in their order of appearance in
the resulting string. For example, if three indices
change in the summands, and you want them to be
named
'i'
,'j'
and'k'
, setit = ['i','j','k']
. You can also group two indices which always appear together, e.g. if'i'
always appear next to'j'
you could setit = [('ij',2),'k']
. Here, the number 2 indicates that'ij'
replaces 2 indices. Ifit
is set toNone
, or if the function is not able to find a template, the string of the first summand will be used for the string representation of the sum.  indices (str.) – a string to denote the set where the indices belong to.
Example:
>>> import picos as pic >>> prob=pic.Problem() >>> x={} >>> names=['foo','bar','baz'] >>> for n in names: ... x[n]=prob.add_variable( 'x[{0}]'.format(n),(3,5) ) >>> for n in names: ... print("{}: {}".format(n, x[n])) #doctest: +NORMALIZE_WHITESPACE foo: # variable x[foo]:(3 x 5),continuous # bar: # variable x[bar]:(3 x 5),continuous # baz: # variable x[baz]:(3 x 5),continuous # >>> pic.sum([x[n] for n in names],'n','names') # (3 x 5)affine expression: Σ_{n in names} x[n] # >>> pic.sum([(i+1) * x[n] for i,n in enumerate(names)],['i','n'],'[3] x names') #two indices # (3 x 5)affine expression: Σ_{i,n in [3] x names} i*x[n] # >>> IJ = [(1,2),(2,4),(0,1),(1,3)] >>> pic.sum([x['foo'][ij] for ij in IJ],[('ij',2)],'IJ') #double index # (1 x 1)affine expression: Σ_{ij in IJ} x[foo][ij] #
 lst – list of

picos.tools.
diag
(exp, dim=1)¶ if
exp
is an affine expression of size (n,m),diag(exp,dim)
returns a diagonal matrix of sizedim*n*m
dim*n*m
, withdim
copies of the vectorized expressionexp[:]
on the diagonal.In particular:
 when
exp
is scalar,diag(exp,n)
returns a diagonal matrix of size , with all diagonal elements equal toexp
.  when
exp
is a vector of size ,diag(exp)
returns the diagonal matrix of size with the vectorexp
on the diagonal
Example
>>> import picos as pic >>> prob=pic.Problem() >>> x=prob.add_variable('x',1) >>> y=prob.add_variable('y',1) >>> pic.tools.diag(xy,4) # (4 x 4)affine expression: Diag(x y) # >>> pic.tools.diag(x//y) # (2 x 2)affine expression: Diag([x;y]) #
 when

picos.tools.
new_param
(name, value)¶ Declare a parameter for the problem, that will be stored as a
cvxopt sparse matrix
. It is possible to give a list or a dictionary of parameters. The function returns a constantAffinExp
(or alist
or adict
ofAffinExp
) representing this parameter.Note
Declaring parameters is optional, since the expression can as well be given by using normal variables. (see Example below). However, if you use this function to declare your parameters, the names of the parameters will be displayed when you print an
Expression
or aConstraint
Parameters:  name (str.) – The name given to this parameter.
 value – The value (resp
list
of values,dict
of values) of the parameter. The type of value (resp. the elements of thelist
value, the values of thedict
value) should be understandable by the function_retrieve_matrix()
.
Returns: A constant affine expression (
AffinExp
) (resp. alist
ofAffinExp
of the same length as value, adict
ofAffinExp
indexed by the keys of value)Example:
>>> import cvxopt as cvx >>> prob=pic.Problem() >>> x=prob.add_variable('x',3) >>> B={'foo':17.4,'matrix':cvx.matrix([[1,2],[3,4],[5,6]]),'ones':'1(4,1)'} >>> B['matrix']*x+B['foo'] # (2 x 1)affine expression: [ 2 x 3 MAT ]*x + 17.4 # >>> #(in the string above, 17.4 represents the 2dim vector [17.4,17.4]) >>> B=pic.new_param('B',B) >>> #now that B is a param, we have a nicer display: >>> B['matrix']*x+B['foo'] # (2 x 1)affine expression: B[matrix]*x + B[foo] #

picos.tools.
available_solvers
()¶ Lists all available solvers

picos.tools.
offset_in_lil
(lil, offset, lower)¶ substract the
offset
from all elements of the (recursive) list of listslil
which are larger thanlower
.

picos.tools.
import_cbf
(filename)¶ Imports the data from a CBF file, and creates a
Problem
object.The created problem contains one (multidimmensional) variable for each cone specified in the section
VAR
of the .cbf file, and one (multidimmensional) constraint for each cone specified in the sectionsCON
andPSDCON
.Semidefinite variables defined in the section
PSDVAR
of the .cbf file are represented by a matrix picos variableX
withX.vtype='symmetric'
.This function returns a tuple
(P,x,X,data)
, where:P
is the imported picosProblem
object.x
is a list ofVariable
objects, representing the (multidimmensional) scalar variables.X
is a list ofVariable
objects, representing the symmetric semidefinite positive variables.data
is a dictionary containing picos parameters (AffinExp
objects) used to define the problem. Indexing is with respect to the blocks of variables as defined in thes sectionsVAR
andCON
of the .cbf file.

picos.tools.
diag_vect
(exp)¶ Returns the vector with the diagonal elements of the matrix expression
exp
Example
>>> import picos as pic >>> prob=pic.Problem() >>> X=prob.add_variable('X',(3,3)) >>> pic.tools.diag_vect(X) # (3 x 1)affine expression: diag(X) #

exception
picos.tools.
QuadAsSocpError
(msg)¶ Exception raised when the problem can not be solved in the current form, because quad constraints are not handled. User should try to convert the quads as socp.

exception
picos.tools.
NotAppropriateSolverError
(msg)¶ Exception raised when trying to solve a problem with a solver which cannot handle it

exception
picos.tools.
NonConvexError
(msg)¶ Exception raised when nonconvex quadratic constraints are passed to a solver which cannot handle them.

exception
picos.tools.
DualizationError
(msg)¶ Exception raised when a nonstandard conic problem is being dualized.

picos.tools.
geomean
(exp)¶ returns a
GeoMeanExp
object representing the geometric mean of the entries ofexp[:]
. This can be used to enter inequalities of the formt <= geomean(x)
. Note that geometric mean inequalities are internally reformulated as a set of SOC inequalities.Example:
>>> import picos as pic >>> prob = pic.Problem() >>> x = prob.add_variable('x',1) >>> y = prob.add_variable('y',3) >>> # the following line adds the constraint x <= (y0*y1*y2)**(1./3) in the problem: >>> prob.add_constraint(x<pic.geomean(y))

picos.tools.
norm
(exp, num=2, denom=1)¶ returns a
NormP_Exp
object representing the (generalized) pnorm of the entries ofexp[:]
. This can be used to enter constraints of the form with . 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 assumes that is a nonnegative vector.This function can also be used to represent the Lp,q norm of a matrix (for ): , that is, the pnorm of the vector formed with the qnorms of the rows of .
The exponent of the norm must be specified either by a couple numerator (2d argument) / denominator (3d arguments), or directly by a float
p
given as second argument. In the latter case a rational approximation ofp
will be used. It is also possible to pass'inf'
as second argument for the infinitynorm (aka maxnorm).For the case of norms,
p
andq
must be specified by a tuple of floats in the second argument (rational approximations will be used), and the third argument will be ignored.Example:
>>> import picos as pic >>> P = pic.Problem() >>> x = P.add_variable('x',1) >>> y = P.add_variable('y',3) >>> pic.norm(y,7,3) < x # pnorm ineq : norm_7/3( y)<x# >>> pic.norm(y,0.4) > x # generalized pnorm ineq : norm_2/5( y)>x# >>> X = P.add_variable('X',(3,2)) >>> pic.norm(X,(1,2)) < 1 # pqnorm ineq : norm_1,2( X)<1.0# >>> pic.norm(X,('inf',1)) < 1 # pqnorm ineq : norm_inf,1( X)<1.0#

picos.tools.
tracepow
(exp, num=1, denom=1, coef=None)¶ Returns a
TracePow_Exp
object representing the trace of the pthpower of the symmetric matrixexp
, whereexp
is anAffinExp
which we denote by . This can be used to enter constraints of the form with or , or with . Note that is forced to be positive semidefinite when a constraint of this form is entered in PICOS.It is also possible to specify a
coef
matrix () of the same size asexp
, in order to represent the expression . The constraint can be reformulated with SDP constraints if is positive semidefinite and .Trace of power inequalities are internally reformulated as a set of Linear Matrix Inequalities (SDP), or second order cone inequalities if
exp
is a scalar.The exponent of the norm must be specified either by a couple numerator (2d argument) / denominator (3d arguments), or directly by a float
p
given as second argument. In the latter case a rational approximation ofp
will be used.Example:
>>> import picos as pic >>> prob = pic.Problem() >>> X = prob.add_variable('X',(3,3),'symmetric') >>> t = prob.add_variable('t',1) >>> pic.tracepow(X,7,3) < t # trace of pth power ineq : trace( X)**7/3<t# >>> pic.tracepow(X,0.6) > t # trace of pth power ineq : trace( X)**3/5>t#
>>> A = cvx.normal(3,3);A=A*A.T #A random semidefinite positive matrix >>> A = pic.new_param('A',A) >>> pic.tracepow(X,0.25,coef=A) > t # trace of pth power ineq : trace[ A *(X)**1/4]>t#

picos.tools.
trace
(exp)¶ trace of a square AffinExp

picos.tools.
partial_transpose
(exp, dims_1=None, subsystems=None, dims_2=None)¶ Partial transpose of an Affine Expression, with respect to given subsystems. If
X
is a matrixAffinExp
that can be written as for some matrices of respective sizesdims_1[0] x dims_2[0]
, … ,dims_1[n1] x dims_2[n1]
, this function returns the matrix , where ifi in subsystems
, and otherwise.The optional parameters
dims_1
anddims_2
are tuples specifying the dimension of each subsystem . The argumentsubsystems
must be atuple
(or anint
) with the index of all subsystems to be transposed.The default value
dims_1=None
automatically computes the size of the subblocks, assuming thatexp
is a square matrix, for the smallest appropriate value of , that isdims_1=(n,)*k
.If
dims_2
is not specified, it is assumed that the subsystems are square, i.e.,dims_2=dims_1
. Ifsubsystems
is not specified, the default assumes that only the last system must be transposed, i.e.,subsystems = (len(dims_1)1,)
Example:
>>> import picos as pic >>> import cvxopt as cvx >>> P = pic.Problem() >>> X = P.add_variable('X',(4,4)) >>> X.value = cvx.matrix(range(16),(4,4)) >>> print(X) #doctest: +NORMALIZE_WHITESPACE [ 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] >>> print(X.Tx) #standard partial transpose (with respect to the 2x2 blocks and 2d subsystem) #doctest: +NORMALIZE_WHITESPACE [ 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] >>> print(pic.partial_transpose(X,(2,2),0)) #(now with respect to the first subsystem) #doctest: +NORMALIZE_WHITESPACE [ 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]

picos.tools.
partial_trace
(X, k=1, dim=None)¶ Partial trace of an Affine Expression, with respect to the
k
th subsystem for a tensor product of dimensionsdim
. IfX
is a matrixAffinExp
that can be written as for some matrices of respective sizesdim[0] x dim[0]
, … ,dim[n1] x dim[n1]
(dim
is a list of ints if all matrices are square), ordim[0][0] x dim[0][1]
, …,``dim[n1][0] x dim[n1][1]`` (dim
is a list of 2tuples if any of them except thek
th one is rectangular), this function returns the matrix .The default value
dim=None
automatically computes the size of the subblocks, assuming thatX
is a square matrix with blocks of size .Example:
>>> import picos as pic >>> import cvxopt as cvx >>> P = pic.Problem() >>> X = P.add_variable('X',(4,4)) >>> X.value = cvx.matrix(range(16),(4,4)) >>> print(X) #doctest: +NORMALIZE_WHITESPACE [ 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] >>> print(pic.partial_trace(X)) #partial trace with respect to second subsystem (k=1) #doctest: +NORMALIZE_WHITESPACE [ 5.00e+00 2.10e+01] [ 9.00e+00 2.50e+01] >>> print(pic.partial_trace(X,0)) #and now with respect to first subsystem (k=0) #doctest: +NORMALIZE_WHITESPACE [ 1.00e+01 1.80e+01] [ 1.20e+01 2.00e+01]

picos.tools.
detrootn
(exp)¶ returns a
DetRootN_Exp
object representing the determinant of the throot of the symmetric matrixexp
, where is the dimension of the matrix. This can be used to enter constraints of the form . Note that is forced to be positive semidefinite when a constraint of this form is entered in PICOS. Determinant inequalities are internally reformulated as a set of Linear Matrix Inequalities (SDP).Example:
>>> import picos as pic >>> prob = pic.Problem() >>> X = prob.add_variable('X',(3,3),'symmetric') >>> t = prob.add_variable('t',1) >>> t < pic.detrootn(X) # nth root of det ineq : det( X)**1/3>t#

picos.tools.
ball
(r, p=2)¶ returns a
Ball
object representing: a L_p Ball of radius
r
() if  the convex set .
Example
>>> import picos as pic >>> P = pic.Problem() >>> x = P.add_variable('x', 3) >>> x << pic.ball(2,3) #doctest: +NORMALIZE_WHITESPACE # pnorm ineq : norm_3( x)<2.0# >>> x << pic.ball(1,0.5) # generalized pnorm ineq : norm_1/2( x)>1.0#
 a L_p Ball of radius

picos.tools.
sum_k_largest
(exp, k)¶ returns a
Sum_k_Largest_Exp
object representing the sum of thek
largest elements of an affine expressionexp
. This can be used to enter constraints of the form . This kind of constraints is reformulated internally as a set of linear inequalities.Example:
>>> import picos as pic >>> prob = pic.Problem() >>> x = prob.add_variable('x',3) >>> t = prob.add_variable('t',1) >>> pic.sum_k_largest(x,2) < 1 # sum_k_largest constraint : sum_2_largest(x)<1.0# >>> pic.sum_k_largest(x,1) < t # (3x1)affine constraint: max(x)<=t #

picos.tools.
sum_k_largest_lambda
(exp, k)¶ returns a
Sum_k_Largest_Exp
object representing the sum of thek
largest eigenvalues of a square matrix affine expressionexp
. This can be used to enter constraints of the form . This kind of constraints is reformulated internally as a set of linear matrix inequalities (SDP). Note thatexp
is assumed to be symmetric (picos does not check).Example:
>>> import picos as pic >>> prob = pic.Problem() >>> X = prob.add_variable('X',(3,3),'symmetric') >>> t = prob.add_variable('t',1) >>> pic.sum_k_largest_lambda(X,3) < 1 #this is simply the trace of X # (1x1)affine constraint: 〈 I  X 〉 < 1.0 # >>> pic.sum_k_largest_lambda(X,2) < t # sum_k_largest constraint : sum_2_largest_lambda(X)<t#

picos.tools.
lambda_max
(exp)¶ largest eigenvalue of a square matrix expression (cf.
pic.sum_k_largest(exp,1)
)>>> import picos as pic >>> prob = pic.Problem() >>> x = prob.add_variable('X',(3,3),'symmetric') >>> pic.lambda_max(X) < 2 # (3x3)LMI constraint lambda_max(X)<=2.0 #

picos.tools.
sum_k_smallest
(exp, k)¶ returns a
Sum_k_Smallest_Exp
object representing the sum of thek
smallest elements of an affine expressionexp
. This can be used to enter constraints of the form . This kind of constraints is reformulated internally as a set of linear inequalities.Example:
>>> import picos as pic >>> prob = pic.Problem() >>> x = prob.add_variable('x',3) >>> t = prob.add_variable('t',1) >>> pic.sum_k_smallest(x,2) > t # sum_k_smallest constraint : sum_2_smallest(x)>t# >>> pic.sum_k_smallest(x,1) > 3 # (3x1)affine constraint: min(x)>=3.0 #

picos.tools.
sum_k_smallest_lambda
(exp, k)¶ returns a
Sum_k_Smallest_Exp
object representing the sum of thek
smallest eigenvalues of a square matrix affine expressionexp
. This can be used to enter constraints of the form . This kind of constraints is reformulated internally as a set of linear matrix inequalities (SDP). Note thatexp
is assumed to be symmetric (picos does not check).Example:
>>> import picos as pic >>> prob = pic.Problem() >>> X = prob.add_variable('X',(3,3),'symmetric') >>> t = prob.add_variable('t',1) >>> pic.sum_k_smallest_lambda(X,1) > 1 # (3x3)LMI constraint lambda_min(X)>=1.0 # >>> pic.sum_k_smallest_lambda(X,2) > t # sum_k_smallest constraint : sum_2_smallest_lambda(X)>t#

picos.tools.
lambda_min
(exp)¶ smallest eigenvalue of a square matrix expression (cf.
pic.sum_k_smallest(exp,1)
)>>> import picos as pic >>> prob = pic.Problem() >>> x = prob.add_variable('X',(3,3),'symmetric') >>> pic.lambda_min(X) > 1 # (3x3)LMI constraint lambda_min(X)>=1.0 #

picos.tools.
simplex
(gamma=1)¶ returns a
Truncated_Simplex
object representing the set .Example
>>> import picos as pic >>> P = pic.Problem() >>> x = P.add_variable('x', 3) >>> x << pic.simplex(1) # (4x1)affine constraint: x in standard simplex # >>> x << pic.simplex(2) # (4x1)affine constraint: x in simplex of radius 2 #

picos.tools.
truncated_simplex
(gamma=1, sym=False)¶ returns a
Truncated_Simplex
object representing object representing the set: if
sym=False
(default)  if
sym=True
.
Example
>>> import picos as pic >>> P = pic.Problem() >>> x = P.add_variable('x', 3) >>> x << pic.truncated_simplex(2) # (7x1)affine constraint: x in truncated simplex of radius 2 # >>> x << pic.truncated_simplex(2,sym=True) # symmetrized truncated simplex constraint : x_{infty;1} <= {1;2}#
 if

picos.tools.
kron
(A, B)¶ Kronecker product of 2 expression, at least one of which must be constant
Example:
>>> import picos as pic >>> import cvxopt as cvx >>> import numpy as np >>> P = pic.Problem() >>> X = P.add_variable('X',(4,3)) >>> X.value = cvx.matrix(range(12),(4,3)) >>> I = pic.new_param('I',np.eye(2)) >>> print(pic.kron(I,X)) #doctest: +NORMALIZE_WHITESPACE [ 0.00e+00 4.00e+00 8.00e+00 0.00e+00 0.00e+00 0.00e+00] [ 1.00e+00 5.00e+00 9.00e+00 0.00e+00 0.00e+00 0.00e+00] [ 2.00e+00 6.00e+00 1.00e+01 0.00e+00 0.00e+00 0.00e+00] [ 3.00e+00 7.00e+00 1.10e+01 0.00e+00 0.00e+00 0.00e+00] [ 0.00e+00 0.00e+00 0.00e+00 0.00e+00 4.00e+00 8.00e+00] [ 0.00e+00 0.00e+00 0.00e+00 1.00e+00 5.00e+00 9.00e+00] [ 0.00e+00 0.00e+00 0.00e+00 2.00e+00 6.00e+00 1.00e+01] [ 0.00e+00 0.00e+00 0.00e+00 3.00e+00 7.00e+00 1.10e+01]