Commit 0ecd5d5e authored by Guillaume Sagnol's avatar Guillaume Sagnol

doc OK v1.0.1?

parent 4ea4dddc
......@@ -61,4 +61,17 @@ v1.0.1.dev, 18.05.14
* Complex Semidefinite Programming.
* Flow constraints in graphs
* Improved implementation of *expression slicing* (__getitem__)
\ No newline at end of file
v 1.0.1, 27.08.14:
Release fixing the missing functionnalities of the previous *.dev* version:
* Improved support for complex SDP (access to dual information and correction of a few
bugs, in particular sum of complex affine expression now work correctly)
* Flow constraints in graphs, including multicommodity flows.
* Additional ``coef`` argument in the function tracepow(), in order to represent
constraints of the form trace(M X^p) >= t.
* Improved implementation of retrieve_matrix(), which was taking a very long time to
process large parameters.
* Improved implementation of the retrieval of optimal primal variables with CPLEX.
With the previous versions there was an important overhead at the end of the
solving process to get the optimal values, this is now working much faster.
* Nicer documentation.
\ No newline at end of file
......@@ -44,9 +44,7 @@
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-nav-search">
<a href="#" class="fa fa-home"> Home <img src="_static/picos_big_trans.gif" height="50px" width="200px"/> </a>
<a href="#" class="fa fa-home"> picos</a>
<div role="search">
<form id ="rtd-search-form" class="wy-form" action="search.html" method="get">
......@@ -98,7 +96,6 @@
</ul>
</div>
&nbsp;
</nav>
......@@ -152,8 +149,9 @@ on every function of PICOS.</p>
<dd><ul class="first last simple">
<li>Support for Semidefinite Programming over the complex domain, see <a class="reference internal" href="complex.html#complex"><em>here</em></a>.</li>
<li>Flow constraints in graphs, cf. <a class="reference internal" href="tuto.html#flowcons"><em>this section</em></a>.</li>
<li>Improved implementation of several functionalities, in particular the slicing of affine expressions (<code class="docutils literal"><span class="pre">__getitem__</span></code>), the processing of large matrix parameters, and the access to primal optimal variables with CPLEX.</li>
<li>Improved readibility of the documentation.</li>
<li>Additional <tt class="docutils literal"><span class="pre">coef</span></tt> argument in the function <a class="reference internal" href="tools.html#picos.tools.tracepow" title="picos.tools.tracepow"><tt class="xref py py-func docutils literal"><span class="pre">picos.tracepow()</span></tt></a>, in order to represent constraints of the form <img class="math" src="_images/math/fa733d2db9d89ff82b3b53a61fc195c7de5b5625.png" alt="\operatorname{trace}(M X^p) \geq t"/>.</li>
<li>Improved implementation of several functionalities, in particular the slicing of affine expressions (<tt class="docutils literal"><span class="pre">__getitem__</span></tt>), the processing of large matrix parameters, and the access to primal optimal variables with CPLEX.</li>
<li>Nicer documentation.</li>
</ul>
</dd>
</dl>
......
......@@ -13,10 +13,10 @@ Change History
Release fixing the missing functionnalities of the previous *.dev* version:
* Improved support for complex SDP (access to dual information and correction of a few bugs, in particular sum of complex affine expression now work correctly)
* Flow constraints in graphs, including multicommodity flows, cf. :ref:`this section <flowcons>`.
* Improved implementation of :func:`_retrieve_matrix() <picos.tools._retrieve_matrix>`, which
was taking a very long time to process large parameters.
* Additional ``coef`` argument in the function :func:`picos.tracepow() <picos.tools.tracepow>`, in order to represent constraints of the form :math:`\operatorname{trace}(M X^p) \geq t`.
* Improved implementation of :func:`_retrieve_matrix() <picos.tools._retrieve_matrix>`, which was taking a very long time to process large parameters.
* Improved implementation of the retrieval of optimal primal variables with CPLEX. With the previous versions there was an important overhead at the end of the solving process to get the optimal values, this is now working much faster.
* Improved readibility of the documentation.
* Nicer documentation.
* 18 May 14: **Picos** :ref:`1.0.1.dev <download>` **Released** |br|
......
......@@ -31,8 +31,9 @@ on every function of PICOS.
Major Release with following changes:
* Support for Semidefinite Programming over the complex domain, see :ref:`here <complex>`.
* Flow constraints in graphs, cf. :ref:`this section <flowcons>`.
* Additional ``coef`` argument in the function :func:`picos.tracepow() <picos.tools.tracepow>`, in order to represent constraints of the form :math:`\operatorname{trace}(M X^p) \geq t`.
* Improved implementation of several functionalities, in particular the slicing of affine expressions (``__getitem__``), the processing of large matrix parameters, and the access to primal optimal variables with CPLEX.
* Improved readibility of the documentation.
* Nicer documentation.
* 18 May 14: **Picos** :ref:`1.0.1.dev <download>` **Released** |br|
Preliminary release of the 1.0.1 (still a few bugs for complex SDPs).
......
......@@ -344,6 +344,8 @@ Author and contributors
their comments, ideas, questions, ... (in no particular order):
* `Dan Stahlke <http://www.stahlke.org/>`_
* `Marco Dalai <http://www.ing.unibs.it/~marco.dalai/>`_
* `Matteo Seminaroti <http://www.cwi.nl/people/2683/>`_
......
......@@ -1263,4 +1263,6 @@ References
4. "`On the semidefinite representations of real functions applied to symmetric
matrices <http://opus4.kobv.de/opus4-zib/frontdoor/index/index/docId/1751>`_", G. Sagnol,
Submitted, ZIB Report 12-50, 2012.
\ No newline at end of file
*Linear Algebra and its Applications*,
439(10), p. *2829-2843*, 2013.
\ No newline at end of file
......@@ -808,11 +808,20 @@ creates the constraint
is used, the base :math:`x` is forced to be nonnegative (resp. the base :math:`X` is
forced to be positive semidefinite) by picos.
When the exponent is :math:`0<p<1`,
it is also possible to represent constraints of the form
:math:`\operatorname{trace}(M X^p) \geq t`
with SDPs, where :math:`M\succeq 0`, see :ref:`[2] <tuto_refs>`.
>>> pic.tracepow(X, 0.6666, coef = A[0].T*A[0]) >= t
# trace of pth power ineq : trace[ A[0].T*A[0] *(X)**2/3]>t#
As for geometric means, inequalities involving real powers are
stored in a temporary object of the class :class:`TracePow_Constraint <picos.TracePow_Constraint>`,
which contains a field ``Ptmp`` , a Problem instance with all the SOC or SDP constraints
used to represent the original inequality.
Inequalities involving generalized p-norm
-----------------------------------------
......@@ -1218,4 +1227,8 @@ References
M.S. Lobo, L. Vandenberghe, S. Boyd and H. Lebret,
*Linear Algebra and its Applications*,
284, p. *193-228*, 1998.
2. "`On the semidefinite representations of real functions applied to symmetric
matrices <http://opus4.kobv.de/opus4-zib/frontdoor/index/index/docId/1751>`_", G. Sagnol,
*Linear Algebra and its Applications*,
439(10), p. *2829-2843*, 2013.
......@@ -383,11 +383,12 @@ class TracePow_Constraint(_Convex_Constraint):
""" A temporary object used to pass (trace of) pth power inequalities
This class derives from :class:`Constraint <picos.Constraint>`
"""
def __init__(self,exprhs,explhs,alpha,beta,Ptmp,constring):
def __init__(self,exprhs,explhs,alpha,beta,M,Ptmp,constring):
self.explhs = explhs
self.exprhs = exprhs
self.numerator=alpha
self.denominator=beta
self.M=M
p = float(alpha)/float(beta)
if explhs.size[0]>1:
_Convex_Constraint.__init__(self,Ptmp,constring,'trace of pth power ineq')
......@@ -398,7 +399,7 @@ class TracePow_Constraint(_Convex_Constraint):
def slack_var(self):
p = float(self.numerator) / self.denominator
slk = self.exprhs.value-tracepow(self.explhs,self.numerator,self.denominator).value
slk = self.exprhs.value-tracepow(self.explhs,self.numerator,self.denominator,self.M).value
if p>0 and p<1:
return -slk
else:
......
......@@ -2048,6 +2048,10 @@ class TracePow_Exp(_ConvexExp):
(resp. over the set of positive semidefinite matrices ``exp``), and PICOS implicitely forces
the constraint ``exp >0`` (resp. ``exp >> 0``) to hold.
Also, when a coef matrix :math:`M` is specified (for constraints of the
form :math:`\operatorname{trace}(M X^p) \geq t`),
the matrix :math:`M` must be positive semidefinite and :math:`p` must be in :math:`(0,1]`.
**Overloaded operator**
:``<``: less **or equal** than (the rhs must be a scalar affine expression, AND
......@@ -2058,16 +2062,21 @@ class TracePow_Exp(_ConvexExp):
"""
def __init__(self,exp,alpha,beta=1):
def __init__(self,exp,alpha,beta=1,M=None):
pstr = str(alpha)
if beta>1:
pstr+='/'+str(beta)
p=float(alpha)/float(beta)
if exp.size==(1,1):
_ConvexExp.__init__(self,'( '+exp.string+')**'+pstr,'pth power expression')
if M is None:
if exp.size==(1,1):
_ConvexExp.__init__(self,'( '+exp.string+')**'+pstr,'pth power expression')
else:
_ConvexExp.__init__(self,'trace( '+exp.string+')**'+pstr,'trace of pth power expression')
else:
_ConvexExp.__init__(self,'trace( '+exp.string+')**'+pstr,'trace of pth power expression')
if exp.size==(1,1):
_ConvexExp.__init__(self, M.string+' *( '+exp.string+')**'+pstr,'pth power expression')
else:
_ConvexExp.__init__(self,'trace[ '+M.string+' *('+exp.string+')**'+pstr+']','trace of pth power expression')
if exp.size[0] != exp.size[1]:
raise ValueError('Matrix must be square')
......@@ -2083,14 +2092,32 @@ class TracePow_Exp(_ConvexExp):
self.dim = exp.size[0]
"""dimension of ``exp``"""
self.M = None#
"""the coef matrix"""
if M is not None:#we assume without checking that M is positive semidefinite
if p<=0 or p>1:
raise ValueError('when a coef matrix M is given, p must be between 0 and 1')
if not M.is_valued():
raise ValueError('coef matrix M must be valued')
if not M.size == exp.size:
raise ValueError('coef matrix M must have the same size as exp')
self.M=M
def eval(self,ind=None):
val=self.exp.eval(ind)
Mval = self.M.eval(ind)
if not isinstance(val,cvx.base.matrix):
val = cvx.matrix(val)
ev = np.linalg.eigvalsh(np.matrix(val))
p = float(self.numerator)/float(self.denominator)
return sum([vi**p for vi in ev])
if self.M is None:
ev = np.linalg.eigvalsh(np.matrix(val))
return sum([vi**p for vi in ev])
else:
U,S,V = np.linalg.svd(val)
Xp = cvx.matrix(U)*cvx.spdiag([s**p for s in S])*cvx.matrix(V)
return np.trace(Mval*Xp)
value = property(eval,Expression.set_value,Expression.del_simple_var_value)
......@@ -2186,7 +2213,7 @@ class TracePow_Exp(_ConvexExp):
Ptmp.add_constraint( (idt|v[0]) < exp )
return TracePow_Constraint(exp,self.exp,self.numerator,self.denominator,Ptmp,self.string + '<' + exp.string)
return TracePow_Constraint(exp,self.exp,self.numerator,self.denominator,None,Ptmp,self.string + '<' + exp.string)
else:#constant
......@@ -2199,7 +2226,10 @@ class TracePow_Exp(_ConvexExp):
if (p > 1) or (p < 0):
raise Exception('>= operator can be used only when the function is concave (0<p<=1)')
if p == 1:
return self.exp > exp
if self.M is None:
return self.exp > exp
else:
return (self.M | self.exp) > exp
if isinstance(exp,AffinExp):
if exp.size <> (1,1):
......@@ -2250,12 +2280,19 @@ class TracePow_Exp(_ConvexExp):
v.append(v0)
lis = newlis
if self.dim == 1:
Ptmp.add_constraint( exp**2 < lis[0] * lis[1])
if self.M is None:
Ptmp.add_constraint( exp**2 < lis[0] * lis[1])
else:
Ptmp.add_constraint( v[0]**2 < lis[0] * lis[1])
Ptmp.add_constraint( (self.M * v[0]) > exp )
else:
Ptmp.add_constraint( ((lis[0] & v[0])//(v[0] & lis[1])) >> 0)
Ptmp.add_constraint( (idt|v[0]) > exp )
if self.M is None:
Ptmp.add_constraint( (idt|v[0]) > exp )
else:
Ptmp.add_constraint( (self.M|v[0]) > exp )
return TracePow_Constraint(exp,self.exp,self.numerator,self.denominator,Ptmp,self.string + '>' + exp.string)
return TracePow_Constraint(exp,self.exp,self.numerator,self.denominator,self.M,Ptmp,self.string + '>' + exp.string)
else:#constant
term,termString=_retrieve_matrix(exp,(1,1))
......
......@@ -234,10 +234,15 @@ def norm(exp,num=2,denom=1):
frac = Fraction(p).limit_denominator(1000)
return NormP_Exp(exp,frac.numerator,frac.denominator)
def tracepow(exp,num=1,denom=1):
"""returns a :class:`TracePow_Exp <picos.TracePow_Exp>` object representing the trace of the pth-power of the symmetric matrix ``exp``.
def tracepow(exp,num=1,denom=1,coef=None):
"""Returns a :class:`TracePow_Exp <picos.TracePow_Exp>` object representing the trace of the pth-power of the symmetric matrix ``exp``, where ``exp`` is an :class:`AffinExp <picos.AffinExp>` which we denote by :math:`X`.
This can be used to enter constraints of the form :math:`\operatorname{trace} X^p \leq t` with :math:`p\geq1` or :math:`p < 0`, or :math:`\operatorname{trace} X^p \geq t` with :math:`0 \leq p \leq 1`.
Note that :math:`X` 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 (:math:`M`) of the same size as ``exp``, in order to represent the expression :math:`\operatorname{trace} (M X^p)`.
The constraint :math:`\operatorname{trace} (M X^p)\geq t` can be reformulated with SDP constraints if :math:`M` is positive
semidefinite and :math:`0<p<1`.
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.
......@@ -257,12 +262,20 @@ def tracepow(exp,num=1,denom=1):
>>> 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#
"""
#TODO coef
from .expression import AffinExp
from .expression import TracePow_Exp
if not isinstance(exp,AffinExp):
mat,name=_retrieve_matrix(exp)
exp = AffinExp({},constant=mat[:],size=mat.size,string=name)
if not(coef is None) and not isinstance(coef,AffinExp):
M,Mstr=_retrieve_matrix(coef)
coef = AffinExp({},constant=M[:],size=M.size,string=Mstr)
if num == denom:
return exp
p = float(num)/float(denom)
......@@ -270,7 +283,7 @@ def tracepow(exp,num=1,denom=1):
raise Exception('undefined for p=0')
from fractions import Fraction
frac = Fraction(p).limit_denominator(1000)
return TracePow_Exp(exp,frac.numerator,frac.denominator)
return TracePow_Exp(exp,frac.numerator,frac.denominator,coef)
def detrootn(exp):
"""returns a :class:`DetRootN_Exp <picos.DetRootN_Exp>` object representing the determinant of the
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment