<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) 2008 - INRIA
 * 
 * This file must be used under the terms of the CeCILL.
 * This source file is licensed as described in the file COPYING, which
 * you should have received as part of this distribution.  The terms
 * are also available at    
 * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
 *
 -->
<refentry version="5.0-subset Scilab" xml:id="semidef" xml:lang="en"
          xmlns="http://docbook.org/ns/docbook"
          xmlns:xlink="http://www.w3.org/1999/xlink"
          xmlns:svg="http://www.w3.org/2000/svg"
          xmlns:ns4="http://www.w3.org/1999/xhtml"
          xmlns:mml="http://www.w3.org/1998/Math/MathML"
          xmlns:db="http://docbook.org/ns/docbook">
  <info>
    <pubdate>$LastChangedDate: 2008-03-26 09:50:39 +0100 (mer, 26 mar 2008)
    $</pubdate>
  </info>

  <refnamediv>
    <refname>semidef</refname>

    <refpurpose>semidefinite programming</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <title>Calling Sequence</title>

    <synopsis>[x,Z,ul,info]=semidef(x0,Z0,F,blck_szs,c,options)</synopsis>
  </refsynopsisdiv>

  <refsection>
    <title>Parameters</title>

    <variablelist>
      <varlistentry>
        <term>x0</term>

        <listitem>
          <para>m x 1 real column vector (must be strictly primal feasible,
          see below)</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>Z0</term>

        <listitem>
          <para>L x 1 real vector (compressed form of a strictly feasible dual
          matrix, see below)</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>F</term>

        <listitem>
          <para>L x (m+1) real matrix</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>blck_szs</term>

        <listitem>
          <para>p x 2 integer matrix (sizes of the blocks) defining the
          dimensions of the (square) diagonal blocks
          <literal>size(Fi(j)=blck_szs(j) j=1,...,m+1</literal>.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>c</term>

        <listitem>
          <para>m x 1 real vector</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>options</term>

        <listitem>
          <para>row vector with five entries
          <literal>[nu,abstol,reltol,0,maxiters]</literal></para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>ul</term>

        <listitem>
          <para>row vector with two entries</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsection>

  <refsection>
    <title>Description</title>

    <para><literal>[x,Z,ul,info]=semidef(x0,Z0,F,blck_szs,c,options)</literal>
    solves semidefinite program:</para>

    <informalequation>
      <mediaobject>
        <imageobject>
          <imagedata align="center" fileref="../mml/semidef_equation_1.mml" />
        </imageobject>
      </mediaobject>
    </informalequation>

    <para>and its dual:</para>

    <informalequation>
      <mediaobject>
        <imageobject>
          <imagedata align="center" fileref="../mml/semidef_equation_2.mml" />
        </imageobject>
      </mediaobject>
    </informalequation>

    <para>exploiting block structure in the matrices
    <literal>F_i</literal>.</para>

    <para>It interfaces L. Vandenberghe and S. Boyd sp.c program.</para>

    <para>The <literal>Fi's</literal> matrices are stored columnwise in
    <literal>F</literal> in compressed format: if <literal>F_i^j</literal>,
    i=0,..,m, j=1,...,L denote the jth (symmetric) diagonal block of
    <literal>F_i</literal>, then</para>

    <informalequation>
      <mediaobject>
        <imageobject>
          <imagedata align="center" fileref="../mml/semidef_equation_3.mml" />
        </imageobject>
      </mediaobject>
    </informalequation>

    <para>where <literal>pack(M)</literal>, for symmetric
    <literal>M</literal>, is the vector
    <literal>[M(1,1);M(1,2);...;M(1,n);M(2,2);M(2,3);...;M(2,n);...;M(n,n)]</literal>
    (obtained by scanning columnwise the lower triangular part of
    <literal>M</literal>).</para>

    <para><literal>blck_szs</literal> gives the size of block
    <literal>j</literal>, ie,
    <literal>size(F_i^j)=blck_szs(j)</literal>.</para>

    <para>Z is a block diagonal matrix with L blocks <literal>Z^0, ...,
    Z^{L-1}</literal>. <literal>Z^j</literal> has size <literal>blck_szs[j]
    times blck_szs[j]</literal>. Every block is stored using packed storage of
    the lower triangular part.</para>

    <para>The 2 vector <literal>ul</literal> contains the primal objective
    value <literal>c'*x</literal> and the dual objective value
    <literal>-trace(F_0*Z</literal>).</para>

    <para>The entries of <literal>options</literal> are respectively:
    <literal>nu</literal> = a real parameter which ntrols the rate of
    convergence. <literal>abstol</literal> = absolute tolerance.
    <literal>reltol</literal> = relative tolerance (has a special meaning when
    negative). <literal>tv</literal> target value, only referenced if
    <literal>reltol &lt; 0</literal>. <literal>iters</literal> = on entry:
    maximum number of iterations &gt;= 0, on exit: the number of iterations
    taken. Notice that the absolute tolerance cannot be lower than 1.0e-8,
    that is, the absolute tolerance used in the algorithm is the maximum of
    the user-defined tolerance and the constant tolerance 1.0e-8.</para>

    <para><literal>info</literal> returns 1 if maxiters exceeded, 2 if
    absolute accuracy is reached, 3 if relative accuracy is reached, 4 if
    target value is reached, 5 if target value is not achievable; negative
    values indicate errors.</para>

    <para>Convergence criterion:</para>

    <programlisting role = ""><![CDATA[ 
(1) maxiters is exceeded
(2) duality gap is less than abstol
(3) primal and dual objective are both positive and
    duality gap is less than (reltol * dual objective)
    or primal and dual objective are both negative and
    duality gap is less than (reltol * minus the primal objective)
(4) reltol is negative and
    primal objective is less than tv or dual objective is greater
    than tv
 ]]></programlisting>
  </refsection>

  <refsection>
    <title>Examples</title>

    <programlisting role="example"><![CDATA[ 
F0=[2,1,0,0;
    1,2,0,0;
    0,0,3,1
    0,0,1,3];

F1=[1,2,0,0;
    2,1,0,0;
    0,0,1,3;
    0,0,3,1]

F2=[2,2,0,0;
    2,2,0,0;
    0,0,3,4;
    0,0,4,4];

blck_szs=[2,2];

F01=F0(1:2,1:2);F02=F0(3:4,3:4);
F11=F1(1:2,1:2);F12=F1(3:4,3:4);
F21=F2(1:2,1:2);F22=F2(3:4,3:4);

x0=[0;0]
Z0=2*F0;
Z01=Z0(1:2,1:2);Z02=Z0(3:4,3:4);
FF=[[F01(:);F02(:)],[F11(:);F12(:)],[F21(:);F22(:)]]
ZZ0=[[Z01(:);Z02(:)]];

c=[trace(F1*Z0);trace(F2*Z0)];
options=[10,1.d-10,1.d-10,0,50];

[x,Z,ul,info]=semidef(x0,pack(ZZ0),pack(FF),blck_szs,c,options)

w=vec2list(unpack(Z,blck_szs),[blck_szs;blck_szs]);Z=sysdiag(w(1),w(2))

c'*x+trace(F0*Z)
spec(F0+F1*x(1)+F2*x(2))
trace(F1*Z)-c(1)
trace(F2*Z)-c(2)
 ]]></programlisting>
  </refsection>

  <refsection>
    <title>References</title>

    <para>L. Vandenberghe and S. Boyd, " Semidefinite Programming,"
    Informations Systems Laboratory, Stanford University, 1994.</para>

    <para>Ju. E. Nesterov and M. J. Todd, "Self-Scaled Cones and
    Interior-Point Methods in Nonlinear Programming," Working Paper, CORE,
    Catholic University of Louvain, Louvain-la-Neuve, Belgium, April
    1994.</para>

    <para>SP: Software for Semidefinite Programming, <ulink
    url="http://www.ee.ucla.edu/~vandenbe/sp.html">http://www.ee.ucla.edu/~vandenbe/sp.html</ulink></para>
  </refsection>
</refentry>