CHANGES.txt

@@ -55,4 +55,23 @@ v1.0.0, 19.07.13
        that stores which solvers are already aware of a constraint / variable. There is also an
        attribute ``obj_passed`` of the class Problem that lists the solver instances
        where the objective function has already been passed. The option ``onlyChangeObjective`` has been
-       deprecated.
\ No newline at end of file
+       deprecated.
+       
+v1.0.1.dev, 18.05.14
+     * Complex Semidefinite Programming.
+     * Flow constraints in graphs
+     * Improved implementation of *expression slicing* (__getitem__)
+     
+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

doc/Makefile

@@ -6,6 +6,13 @@ SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
 PAPER         =
 BUILDDIR      = _build
+RSYNC         = rsync
+LASTDIR       = full_html/last
+
+# User-friendly check for sphinx-build
+ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
+$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
+endif
 
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
@@ -29,22 +36,28 @@ help:
 	@echo "  epub       to make an epub"
 	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
 	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
+	@echo "  latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
 	@echo "  text       to make text files"
 	@echo "  man        to make manual pages"
 	@echo "  texinfo    to make Texinfo files"
 	@echo "  info       to make Texinfo files and run them through makeinfo"
 	@echo "  gettext    to make PO message catalogs"
 	@echo "  changes    to make an overview of all changed/added/deprecated items"
+	@echo "  xml        to make Docutils-native XML files"
+	@echo "  pseudoxml  to make pseudoxml-XML files for display purposes"
 	@echo "  linkcheck  to check all external links for integrity"
 	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
 
 clean:
-	-rm -rf $(BUILDDIR)/*
+	rm -rf $(BUILDDIR)/*
 
 html:
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+	@echo "Sync-ing with the /last directory"
+	$(RSYNC) -uzvr $(BUILDDIR)/html/* $(LASTDIR)
+	@echo "Done. The last build is in $(LASTDIR)"
 
 dirhtml:
 	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
@@ -77,17 +90,17 @@ qthelp:
 	@echo
 	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
 	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
-	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/pyMathProg.qhcp"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/picos.qhcp"
 	@echo "To view the help file:"
-	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/pyMathProg.qhc"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/picos.qhc"
 
 devhelp:
 	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
 	@echo
 	@echo "Build finished."
 	@echo "To view the help file:"
-	@echo "# mkdir -p $$HOME/.local/share/devhelp/pyMathProg"
-	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/pyMathProg"
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/picos"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/picos"
 	@echo "# devhelp"
 
 epub:
@@ -108,6 +121,12 @@ latexpdf:
 	$(MAKE) -C $(BUILDDIR)/latex all-pdf
 	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
 
+latexpdfja:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through platex and dvipdfmx..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
 text:
 	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
 	@echo
@@ -151,3 +170,13 @@ doctest:
 	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
 	@echo "Testing of doctests in the sources finished, look at the " \
 	      "results in $(BUILDDIR)/doctest/output.txt."
+
+xml:
+	$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
+	@echo
+	@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
+
+pseudoxml:
+	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
+	@echo
+	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."

doc/RELEASE_CHECK

+
+lancer python ../../add_warning_notlast.py from directory /doc/full_html/x.x.x (former_version)
+lancer script add_google_script directly from /doc
+Changer CHANGE file
+Creer dist file (python setup.py sdist) -> check that the doc is in the dist file ???
+
+[OBSOLETE: move to /www, and change root-index with 3 <meta tags> and $sed -i 's/href="/href="v013\//g' index.html]
+rsync to /www
+
+Register on pypi (python setup.py register, username guillaume.sagnol)
+sed -i 's/Picos 0\.1\.0/Picos 0\.1\.1/g' picos/*.py
+et change version num dans conf.py and setup.py and __init__.py
+make new directory in the full_html directory and update the symolic link "last"
\ No newline at end of file

doc/TODO

+website: ask Paul how to make redirections ?
+dualize does not work on cplxsdp
+solve re3 with solveviadual (pb matrice pas symmetrique -> but OK with A+A.H/2: check)
+problem de rang avec cvxopt: remove constraints redondantes ?
+
+
+add new contributors (Marco Dalai, Peter Wittek ?)
+trace (AM^p)
+robust -- uncertainty sets
+read solution partially
+fix some variables as constant
+
+
+
+
 
 solve_via_dual avec cvxopt -- something special to do (finir primalize())
-probleme qd solve problems 2 times in a row (test_cutting_plane.py avec mosek6, but only at zib (?))
+probleme qd solve problems 2 times in a row sequentially (test_cutting_plane.py avec mosek6, but only at zib (?))
 problem avec duals de gurobi pour probleme dsocp de test_picos.py (faire testSOCP5 ?). Bug gurobi -> min example ?
 write_to_file --> scaled vars [mettre ds nom variable ?]
 file reader
@@ -29,7 +44,7 @@ generaliser les inplace operators (avoid seelfcopy as much as possible)
 lancer script add_google_script
 Changer CHANGE file
 Creer dist file (python setup.py sdist)
-move to /www and change root-index with 3 <meta tags> and $sed -i 's/href="/href="v013\//g' index.html
+move to /www, and change root-index with 3 <meta tags> and $sed -i 's/href="/href="v013\//g' index.html
 Register on pypi (python setup.py register, username guillaume.sagnol)
 sed -i 's/Picos 0\.1\.0/Picos 0\.1\.1/g' picos/*.py
-et change version num dans conf.py and setup.py 
+et change version num dans conf.py and setup.py and __init__.py

doc/add_google_script.py

-files = ['index.html','api.html',
-         'examples.html','constraint.html','expression.html',
-         'intro.html','tools.html','problem.html',
-         'download.html','graphs.html','tuto.html','optdes.html']
 import os
+files = os.popen('ls full_html/last/*.html').readlines()
+files = [f[:-1] for f in files if f[:6] not in ('search','py-mod','genind')]
 
 for f in files:
-        fi=open('_build/html/'+f,'r')
-        fitmp=open('_build/html/'+f+'tmp','w')
+        fi=open(f,'r')
+        fitmp=open(f+'tmp','w')
         line = fi.readline()
         while '</head>' not in line:
                 fitmp.write(line)
@@ -43,5 +41,5 @@ for f in files:
                 
         fi.close()
         fitmp.close()
-        os.system('mv _build/html/'+f+'tmp _build/html/'+f)
+        os.system('mv '+f+'tmp '+f)
         

doc/add_warning_notlast.py

+newlines =['<body>',
+           '<div class="admonition warning">',
+           '<p class="first admonition-title">Warning</p>',
+           '<p class="last">You are consulting the doc of a former version of PICOS.',
+           'The latest version is <a href="../index.html">HERE</a>. </p>',
+           '</div>'
+           ]
+
+import os
+files = os.popen('ls *.html').readlines()
+files = [f[:-1] for f in files if f[:6] not in ('search','py-mod','genind')]
+
+for f in files:
+        fi=open(f,'r')
+        fitmp=open(f+'tmp','w')
+        line = fi.readline()
+        while '<body>' not in line:
+                fitmp.write(line)
+                line = fi.readline()
+
+        for ln in newlines:
+                fitmp.write(ln)
+                
+        line = fi.readline()
+        while line:
+                fitmp.write(line)
+                line = fi.readline()
+                
+        fi.close()
+        fitmp.close()
+        os.system('mv '+f+'tmp '+f)
+        

doc/changes.rst

+.. |br| raw:: html
+
+   <br />
+
+.. _changes:
+
+==============
+Change History
+==============
+
+ * 27 Aug. 14: **Picos** :ref:`1.0.1 <download>` **Released** |br|
+   
+   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>`.
+     * 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. 
+     * Nicer documentation.
+     
+* 18 May 14: **Picos** :ref:`1.0.1.dev <download>` **Released** |br|
+   
+   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>`.
+     * Improved implementation of ``__getitem__`` for affine expressions. The slicing of affine expressions
+       was slowing down (a lot!) the processing of the optimization problem.
+
+ * 19 Jul. 13: **Picos** :ref:`1.0.0 <download>` **Released** |br|
+   
+   Major Release with following changes:
+     * Semidefinite Programming Interface for MOSEK 7.0 !!!
+     * New options ``handleBarVars`` and ``handleConeVars`` to customize how SOCP and SDPs are passed to MOSEK
+       (When these options are set to ``True`` , PICOS tries to minimize the number of variables of the
+       MOSEK instance, see the doc in :func:`set_all_options_to_default() <picos.Problem.set_all_options_to_default>`).
+     * The function :func:`dualize() <picos.Problem.dualize>` returns the Lagrangian dual of a Problem.
+     * The option ``solve_via_dual`` (documented in
+       :func:`set_all_options_to_default() <picos.Problem.set_all_options_to_default>` ) allows the user to pass
+       the dual of a problem to a solver, instead of the primal problem itself. This can yield important speed-up for
+       certain problems.
+     * In addition to the geometric mean function :func:`picos.geomean() <picos.tools.geomean>` , it is now possible
+       to pass rational powers of affine expressions (through an overload of the ``**`` operator), trace of
+       matrix powers with :func:`picos.tracepow() <picos.tools.tracepow>` , (generalized) p-norms
+       with :func:`picos.norm() <picos.tools.norm>`, and nth root of a determinant with
+       :func:`picos.detrootn() <picos.tools.detrootn>`. These functions automatically reformulate the entered inequalities as a set of equivalent SOCP or SDP constraints.
+     * It is now possible to specify variable bounds directly (rather than adding constraints of the type ``x >= 0`` ).
+       This can be done with the Keywords ``lower`` and ``upper`` of the function
+       :func:`add_variable() <picos.Problem.add_variable>` ,
+       or by the methods :func:`set_lower() <picos.Variable.set_lower>` ,
+       :func:`set_upper() <picos.Variable.set_upper>` ,
+       :func:`set_sparse_lower() <picos.Variable.set_sparse_lower>` , and
+       :func:`set_sparse_upper() <picos.Variable.set_sparse_upper>` of the class :class:`Variable <picos.Variable>`.
+     * It is now more efficient to update a Problem and resolve it. This is done thanks to the attribute ``passed``
+       of the classes :class:`Constraint <picos.Constraint>` and :class:`Variable <picos.Variable>` ,
+       that stores which solvers are already aware of a constraint / variable. There is also an
+       attribute ``obj_passed`` of the class :class:`Problem <picos.Problem>` , that lists the solver instances
+       where the objective function has already been passed. The option ``onlyChangeObjective`` has been
+       deprecated.
+       
+     
+ * 17 Apr. 13: **Picos** :ref:`0.1.3 <download>` **Released** |br|
+   
+   Major changes:
+     * Function :func:`picos.geomean() <picos.tools.geomean>` implemented, to handle inequalities involving
+       a geometric mean and reformulate them automatically as a set of SOCP constraints.
+     * Some options were added for the function :func:`solve() <picos.Problem.solve>` ,
+       to tell CPLEX to stop the computation as soon as a given value for the
+       upper bound (or lower bound) is reached (see the options ``uboundlimit`` and ``lboundlimit``
+       documented in :func:`set_all_options_to_default() <picos.Problem.set_all_options_to_default>`).
+     * The time used by the solver is now stored in the dictionary
+       returned by :func:`solve() <picos.Problem.solve>`.
+     * The option ``boundMonitor`` of the function :func:`solve() <picos.Problem.solve>`
+       gives access to the values of the lower and upper bounds over time with cplex.
+       (this option is documented in :func:`set_all_options_to_default() <picos.Problem.set_all_options_to_default>`).
+     * The weak inequalities operators ``<=`` and ``>=`` can now be used (but strict inequalities are
+       still interpreted as weak inequalities !).
+     * Minor bugs corrected (access to the duals of fixed variables with CPLEX,
+       evaluation of constant affine expressions with a zero coefficient appearing
+       in the dict of linear terms, number of constraints is now updated in
+       :func:`remove_constraint() <picos.Problem.remove_constraint>`).
+
+ * 10 Jan. 13: **Picos** :ref:`0.1.2 <download>` **Released** |br|
+   
+   Bug-fix release, correcting:
+     * The :func:`write_to_file() <picos.Problem.write_to_file>`
+       function for sparse SDPA files. The function was writing the
+       coefficients of the lower triangular part of the constraint matrices
+       instead of the upper triangle.
+     * An ``IndexError`` occuring with the function
+       :func:`remove_constraint() <picos.Problem.remove_constraint>`.
+   
+   Thanks to Warren Schudy for pointing out these bugs of the previous release !
+
+ * 08 Dec. 12: **Picos** :ref:`0.1.1 <download>` **Released** |br|
+   
+   Major changes:
+     * Picos now interfaces GUROBI !
+     * You can specify an initial solution to *warm-start* mixed integer optimizers.
+       (see the option ``hotstart`` documented in
+       :func:`set_all_options_to_default() <picos.Problem.set_all_options_to_default>`)
+     * Minor bugs with quadratic expressions corrected
+     * It's possible to return a reference to a constraint added
+       with add_constraint()
\ No newline at end of file

doc/complex.rst

+.. _complex:
+
+********************************
+Complex Semidefinite Programming
+********************************
+
+Since the version 1.0.1, it is possible to
+do complex semidefinite programming with Picos.
+This extension of semidefinite programming to
+the complex domain was introduced by Goemans and Williamson :ref:`[1] <complex_refs>`
+as relaxtions of combinatorial optimization problems, and
+has applications
+e.g. in Quantum Information Theory :ref:`[2] <complex_refs>`, or 
+for the phase recovery problem in signal processing :ref:`[3] <complex_refs>`.
+
+To handle complex SDPs in Picos, we have introduced two new variable types: ``'complex'``
+and ``'hermitian'``. A complex variable can be created as follows:
+
+   >>> import picos as pic
+   >>> import cvxopt as cvx
+   >>> P = pic.Problem()
+   >>> Z = P.add_variable('Z',(3,2),'complex')
+   
+it automatically creates two variables called ``Z_RE`` and ``Z_IM`` which contains the
+real and imaginary part of ``Z``, and that be accessed by using the ``real`` and ``imag`` properties:
+
+   >>> Z.real
+   # variable Z_RE:(3 x 2),continuous #
+   >>> Z.imag
+   # variable Z_IM:(3 x 2),continuous #
+   >>> Z.vtype
+   'complex'
+
+The python variable ``Z`` contains an affine expression equal to ``Z_RE + 1j * Z_IM``,
+and that can be used to easily define a complex SDP.
+
+The variable type ``'hermitian'`` can be used to create a complex variable that is forced to be Hermitian.
+The following properties can now be used with every affine expression: ``conj`` (complex conjugate),
+``real`` (real part, i.e. ``exp.real`` returns ``0.5 * (exp+exp.conj)`` ),
+``imag`` (imaginary part, i.e. ``exp.imag`` returns ``-0.5 * 1j * (exp-exp.conj)`` ),
+anf ``H`` (Hermitian transposition, i.e. ``exp.H`` returns ``exp.conj.T`` ).
+
+   >>> X = P.add_variable('X',(3,3),'hermitian')
+   >>> X >> 0
+   # (3x3)-LMI constraint X ≽ |0| #
+   
+
+
+
+Fidelity in Quantum Information Theory
+======================================
+
+The material of this section is inspired from a lecture of John Watrous :ref:`[4] <complex_refs>`.
+
+The Fidelity between two (Hermitian) positive semidefinite operators :math:`P` and :math:`Q`
+is defined as:
+
+.. math::
+        F(P,Q) = \Vert P^{1/2} Q^{1/2} \Vert_{tr} = \max_U  \left|\operatorname{trace} \big(P^{1/2} U Q^{1/2}\big) \right|,
+
+where the trace norm :math:`\Vert \cdot \Vert_{tr}` is the  sum of the singular values,
+and the maximization goes over the set of all unitary matrices :math:`U`.
+This quantity can be expressed as the optimal value of the following complex-valued SDP:
+
+.. math::
+        :nowrap:
+        
+        \begin{center}
+        \begin{eqnarray*}
+        &\underset{Z \in \mathbb{C}^{n \times n}}
+                        {\mbox{maximize}}
+                        & \frac{1}{2}\operatorname{trace}(Z + Z^*)\\
+        &\mbox{subject to} & 
+        \left(\begin{array}{cc}
+        P & Z \\
+        Z^* & Q
+        \end{array}\right) \succeq 0
+        \end{eqnarray*}
+        \end{center}
+
+        
+This Problem can be solved as follows in PICOS
+
+.. testcode::
+        
+        #generate two (arbitrary) positive hermitian operators
+        P = cvx.matrix([ [1-1j , 2+2j  , 1    ],
+                         [3j   , -2j   , -1-1j],
+                         [1+2j, -0.5+1j, 1.5  ]
+                        ])
+        P = P * P.H
+        
+        Q = cvx.matrix([ [-1-2j , 2j   , 1.5   ],
+                         [1+2j  ,-2j   , 2.-3j ],
+                         [1+2j  ,-1+1j , 1+4j  ]
+                        ])
+        Q = Q * Q.H
+
+        n=P.size[0]
+        P = pic.new_param('P',P)
+        Q = pic.new_param('Q',Q)
+        
+        #create the problem in picos
+        
+        F = pic.Problem()
+        Z = F.add_variable('Z',(n,n),'complex')
+        
+        F.set_objective('max','I'|0.5*(Z+Z.H))       #('I' | Z.real) works as well
+        F.add_constraint(((P & Z) // (Z.H & Q))>>0 )
+        
+        print F
+        
+        F.solve(verbose = 0)
+        
+        print 'fidelity: F(P,Q) = {0:.4f}'.format(F.obj_value())
+        
+        print 'optimal matrix Z:'
+        print Z
+        
+        #verify that we get the same value with numpy
+        import numpy as np
+        PP = np.matrix(P.value)
+        QQ = np.matrix(Q.value)
+        
+        S,U = np.linalg.eig(PP)
+        sqP = U * np.diag([s**0.5 for s in S]) * U.H #square root of P
+        S,U = np.linalg.eig(QQ)
+        sqQ = U * np.diag([s**0.5 for s in S]) * U.H #square root of P
+        
+        fidelity = sum(np.linalg.svd(sqP * sqQ)[1])  #trace-norm of P**0.5 *  Q**0.5 
+        
+        print 'fidelity computed by trace-norm: F(P,Q) = {0:.4f}'.format(fidelity)
+
+.. testoutput::
+        :options: +NORMALIZE_WHITESPACE
+        
+        ---------------------
+        optimization problem  (SDP):
+        18 variables, 0 affine constraints, 21 vars in 1 SD cones
+
+        Z_RE        : (3, 3), continuous
+        Z_IM        : (3, 3), continuous
+
+                maximize trace( 0.5*( Z + Z.H ) )
+        such that
+        [P,Z;Z.H,Q] ≽ |0|
+        ---------------------
+        fidelity: F(P,Q) = 37.4742
+        optimal matrix Z:
+        [ 1.51e+01+j2.21e+00 -7.17e+00-j1.22e+00  2.52e+00+j6.87e-01]
+        [-4.88e+00+j4.06e+00  1.00e+01-j1.57e-01  8.33e+00+j1.13e+01]
+        [-4.32e-01+j2.98e-01  3.84e+00-j3.28e+00  1.24e+01-j2.05e+00]
+
+        fidelity computed by trace-norm: F(P,Q) = 37.4742
+
+
+Phase Recovery in Signal Processing
+===================================
+
+The material from this section is inspired from :ref:`[3] <complex_refs>`.
+
+The goal of the phase recovery problem is to reconstruct the complex phase of a vector,
+when we are only given the magnitude of some linear measurements.
+This problem can be formulated as a nonconvex optimization problem,
+and the authors of :ref:`[3] <complex_refs>` have proposed a complex SDP relaxation
+similar to the well known *Max-Cut* SDP:
+Given a linear operator :math:`A` and a vector :math:`b` of measured amplitudes,
+define the positive semidefinite hermitian matrix :math:`M = \operatorname{diag}(b) (I - AA^\dagger) \operatorname{diag}(b)`,
+the *Phase-cut* Problem is:
+
+.. math::
+        :nowrap:
+        
+        \begin{center}
+        \begin{eqnarray*}
+        &\underset{U \in \mathbb{H}_n}
+                        {\mbox{minimize}}
+                        & \langle U , M \rangle \\
+        &\mbox{subject to} & \operatorname{diag}(U) = 1\\
+        &                  & U \succeq 0
+        \end{eqnarray*}
+        \end{center}
+
+Here the variable :math:`U` must be hermitian (:math:`U \in \mathbb{H}_n` ),
+and we have a solution to the phase recovery problem if :math:`U = uu^*` has rank one.
+Otherwise, the leading singular vector of :math:`U` is used as an approximation.
+
+This problem can be implemented as follows using Picos:
+
+.. testcode::
+        
+        # We generate an arbitrary matrix M
+        
+        import cvxopt as cvx
+        import picos as pic
+        
+        n    = 5
+        rank = 4  #we take a singular M for the sake of generality 
+        
+        M = cvx.normal (n,rank) +1j*cvx.normal (n,rank) 
+        M = M * M.H
+        M = pic.new_param('M',M)
+        
+        P = pic.Problem()
+        U = P.add_variable('U',(n,n),'hermitian')
+        P.add_list_of_constraints([U[i,i]==1 for i in range(n)],'i')
+        P.add_constraint(U >> 0)
+        
+        P.set_objective('min', U | M)
+        
+        print P
+        
+        #solve the problem
+        P.solve(verbose=0)
+        
+        #optimal complex variable
+        print
+        print 'optimal variable: U='
+        print U
+        print
+        
+        #Do we have a matrix of rank one ?
+        S, V = np.linalg.eig(U.value)
+        print 'rank of U = ', len([s for s in S if abs(s)>1e-6])
+
+.. testoutput::
+        :options: +SKIP
+        
+        ---------------------
+        optimization problem  (SDP):
+        36 variables, 8 affine constraints, 36 vars in 1 SD cones
+
+        U       : (8, 8), hermitian
+
+                minimize 〈 U | M 〉
+        such that
+        U[i,i] = 1.0 for all i
+        U ≽ |0|
+        ---------------------
+
+        optimal variable: U=
+        [ 1.00e+00+j8.97e-10  9.11e-01-j1.27e-01  1.46e-01+j9.38e-01 -7.30e-01+j6.32e-01 -5.52e-01-j8.09e-01]
+        [ 9.11e-01+j1.27e-01  1.00e+00+j1.32e-09  1.05e-01+j9.56e-01 -8.04e-01+j5.66e-01 -4.73e-01-j8.40e-01]
+        [ 1.46e-01-j9.38e-01  1.05e-01-j9.56e-01  1.00e+00+j1.19e-09  4.96e-01+j8.58e-01 -9.00e-01+j4.19e-01]
+        [-7.30e-01-j6.32e-01 -8.04e-01-j5.66e-01  4.96e-01-j8.58e-01  1.00e+00+j9.45e-10 -9.85e-02+j9.91e-01]
+        [-5.52e-01+j8.09e-01 -4.73e-01+j8.40e-01 -9.00e-01-j4.19e-01 -9.85e-02-j9.91e-01  1.00e+00+j9.16e-10]
+
+
+        rank of U =  2
+
+        
+.. _complex_refs:
+
+           
+References
+==========
+
+        1. "Approximation algorithms for MAX-3-CUT and other problems via complex semidefinite programming",
+           M.X. Goemans and D. Williamson. In Proceedings of the thirty-third annual
+           *ACM symposium on Theory of computing*, pp. 443-452. ACM, 2001.
+
+        2. "Semidefinite programs for completely bounded norms",
+           J. Watrous, arXiv preprint 0901.4709, 2009.
+        
+        3. "Phase recovery, maxcut and complex semidefinite programming",
+           I. Waldspurger, A. d'Aspremont, and S. Mallat. *Mathematical Programming*, pp. 1-35, 2012.
+        
+        4. "Semidefinite Programs for fidelity and optimal measurements", J. Watrous,
+           in the script of a `course on Theory of Quantum Information <https://cs.uwaterloo.ca/~watrous/CS766/LectureNotes/08.pdf>`_ 

doc/conf.py

@@ -30,7 +30,7 @@ sys.setdefaultencoding("UTF-8")
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = ['sphinx.ext.autodoc',
-	      'sphinx.ext.intersphinx',
+	      #'sphinx.ext.intersphinx', #COMMENT TO BUILD FASTER, BUT UNCOMMENT FOR THE FINAL RELEASE !
 	      'sphinx.ext.todo',
 	      'sphinx.ext.doctest',
 	      'sphinx.ext.pngmath',
@@ -61,6 +61,7 @@ source_suffix = '.rst'
 master_doc = 'index'
 
 # General information about the project.
+projectname = u'picos_tututu'
 project = u'picos'
 copyright = u'2012, Guillaume Sagnol'
 
@@ -71,7 +72,7 @@ copyright = u'2012, Guillaume Sagnol'
 # The short X.Y version.
 version = '1.0'
 # The full version, including alpha/beta/rc tags.
-release = '1.0.0'
+release = '1.0.1'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -112,12 +113,22 @@ pygments_style = 'sphinx'
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'default'
+#html_theme = 'default'
+#html_theme_options = {'stickysidebar':True}
+
+#read the doc theme
+import sphinx_rtd_theme
+html_theme = "sphinx_rtd_theme"
+html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+html_theme_options = {'sticky_navigation':True}
+
+#readibility theme
+#import sphinxtheme
+#readability_path = os.path.dirname(os.path.abspath(sphinxtheme.__file__))
+#relative_path = os.path.relpath(readability_path, os.path.abspath('.'))
+#html_theme = 'readability'
+#html_theme_path = [relative_path]
 
-# Theme options are theme-specific and customize the look and feel of a theme
-# further.  For a list of options available for each theme, see the
-# documentation.
-#html_theme_options = {}
 
 # Add any paths that contain custom themes here, relative to this directory.
 #html_theme_path = []
@@ -130,9 +141,8 @@ html_theme = 'default'
 #html_short_title = None
 html_short_title = 'PICOS'
 
-# The name of an image file (relative to this directory) to place at the top
-# of the sidebar.
-#html_logo = None
+# The name of an image file (relative to this directory) stored in the _static directory
+html_logo = 'picos_big_trans.gif'
 
 # The name of an image file (within the static path) to use as favicon of the
 # docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
@@ -153,8 +163,9 @@ html_static_path = ['_static']
 #html_use_smartypants = True
 
 # Custom sidebar templates, maps document names to template names.
-#html_sidebars = {}
-html_sidebars = {'**': ['globaltoc.html','localtoc2.html','relations.html',  'sourcelink.html', 'download.html', 'searchbox.html']}
+html_sidebars = {}
+#html_sidebars = {'**': ['globaltoc.html','localtoc2.html']}
+#html_sidebars = {'**': ['globaltoc.html','localtoc2.html','relations.html',  'sourcelink.html', 'download.html', 'searchbox.html']}
 
 # Additional templates that should be rendered to pages, maps page names to
 # template names.
@@ -212,7 +223,7 @@ latex_documents = [
 
 # The name of an image file (relative to this directory) to place at the top of
 # the title page.
-#latex_logo = None
+latex_logo = './picos.png'
 
 # For "manual" documents, if this is true, then toplevel headings are parts,
 # not chapters.
@@ -275,8 +286,13 @@ def setup(app):
 #copying files
 import os
 print 'copying pyplots files...'
-os.system('cp -v pyplots/*.py _build/html/pyplots/')
+#os.system('cp -v pyplots/*.py _build/html/pyplots/')
+os.system('rsync -uzvr pyplots/*.py _build/html/pyplots/')
 print 'done.'
 print 'copying dist files...'
-os.system('cp -v ../dist/* _build/html/dist')
-print 'done.'
\ No newline at end of file
+#os.system('cp -v ../dist/* _build/html/dist')
+os.system('rsync -uzvr ../dist/* _build/html/dist')
+print 'done.'
+#print 'copy in /last'
+#os.system('rsync -uzvr _build/html/* full_html/last')
+#print 'done.'

doc/constraint.rst

@@ -18,7 +18,10 @@ Constraint
 .. autoclass:: picos.TracePow_Constraint
     :members:
     :inherited-members: slack
+
+.. autoclass:: picos.Flow_Constraint
+    :members:
     
 .. autoclass:: picos.DetRootN_Constraint
     :members:
-    :inherited-members: slack
\ No newline at end of file
+    :inherited-members: slack

doc/download.rst

@@ -6,14 +6,19 @@ Download
 
 The latest version of PICOS can be downloaded here:
 
-        `picos-1.0.0 <dist/PICOS-1.0.0.tar.gz>`_
+        `picos-1.0.1 <dist/PICOS-1.0.1.tar.gz>`_
 
 Installation instructions are explained
 :ref:`here <requirements>`.
 
 
+
 **Older versions**
 
+  `picos-1.0.1.dev <dist/PICOS-1.0.1.dev.tar.gz>`_
+
+  `picos-1.0.0 <dist/PICOS-1.0.0.tar.gz>`_
+
   `picos-0.1.3 <dist/PICOS-0.1.3.tar.gz>`_
 
   `picos-0.1.2 <dist/PICOS-0.1.2.tar.gz>`_

doc/examples.rst

@@ -9,4 +9,5 @@ Examples
 
    optdes.rst
    graphs.rst
+   complex.rst
 

doc/full_html/0.1.2/.buildinfo

+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: beb97d53a22f7e7a57996db44bfe9314
+tags: fbb0d17656682115ca4d033fb2f83ba1

doc/full_html/0.1.2/.directory

+[Dolphin]
+AdditionalInfoV2=Details_Size,Details_Date,CustomizedDetails
+ShowPreview=true
+Sorting=1
+Timestamp=2012,12,8,23,56,18
+Version=2
+ViewMode=1
+
+[Settings]
+ShowDotFiles=true