scilab/modules/optimization/help/en_US/lmisolver.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!--
   3  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
   4  * Copyright (C) 2008 - INRIA
   5  *
   6  * This file must be used under the terms of the CeCILL.
   7  * This source file is licensed as described in the file COPYING, which
   8  * you should have received as part of this distribution.  The terms
   9  * are also available at
  10  * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
  11  *
  12  -->
  13 <refentry version="5.0-subset Scilab" xml:id="lmisolver" xml:lang="en"
  14           xmlns="http://docbook.org/ns/docbook"
  15           xmlns:xlink="http://www.w3.org/1999/xlink"
  16           xmlns:svg="http://www.w3.org/2000/svg"
  17           xmlns:ns4="http://www.w3.org/1999/xhtml"
  18           xmlns:mml="http://www.w3.org/1998/Math/MathML"
  19           xmlns:db="http://docbook.org/ns/docbook">
  20   <info>
  21     <pubdate>$LastChangedDate$</pubdate>
  22   </info>
  23
  24   <refnamediv>
  25     <refname>lmisolver</refname>
  26
  27     <refpurpose>linear matrix inequation solver</refpurpose>
  28   </refnamediv>
  29
  30   <refsynopsisdiv>
  31     <title>Calling Sequence</title>
  32
  33     <synopsis>[XLISTF[,OPT]] = lmisolver(XLIST0,evalfunc [,options])</synopsis>
  34   </refsynopsisdiv>
  35
  36   <refsection>
  37     <title>Parameters</title>
  38
  39     <variablelist>
  40       <varlistentry>
  41         <term>XLIST0</term>
  42
  43         <listitem>
  44           <para>a list of containing initial guess (e.g.
  45           <literal>XLIST0=list(X1,X2,..,Xn)</literal>)</para>
  46         </listitem>
  47       </varlistentry>
  48
  49       <varlistentry>
  50         <term>evalfunc</term>
  51
  52         <listitem>
  53           <para>a Scilab function ("external" function with specific
  54           syntax)</para>
  55
  56           <para>The syntax the function <literal>evalfunc</literal> must be as
  57           follows:</para>
  58
  59           <para><literal>[LME,LMI,OBJ]=evalfunct(X)</literal> where
  60           <literal>X</literal> is a list of matrices, <literal>LME,
  61           LMI</literal> are lists and <literal>OBJ</literal> a real
  62           scalar.</para>
  63         </listitem>
  64       </varlistentry>
  65
  66       <varlistentry>
  67         <term>XLISTF</term>
  68
  69         <listitem>
  70           <para>a list of matrices (e.g.
  71           <literal>XLIST0=list(X1,X2,..,Xn)</literal>)</para>
  72         </listitem>
  73       </varlistentry>
  74
  75       <varlistentry>
  76         <term>options</term>
  77
  78         <listitem>
  79           <para>optional parameter. If given, <literal>options</literal> is a
  80           real row vector with 5 components
  81           <literal>[Mbound,abstol,nu,maxiters,reltol]</literal></para>
  82         </listitem>
  83       </varlistentry>
  84     </variablelist>
  85   </refsection>
  86
  87   <refsection>
  88     <title>Description</title>
  89
  90     <para><literal>lmisolver</literal> solves the following problem:</para>
  91
  92     <para>minimize <literal>f(X1,X2,...,Xn)</literal> a linear function of
  93     Xi's</para>
  94
  95     <para>under the linear constraints: <literal>Gi(X1,X2,...,Xn)=0</literal>
  96     for i=1,...,p and LMI (linear matrix inequalities) constraints:</para>
  97
  98     <para><literal>Hj(X1,X2,...,Xn) &gt; 0</literal> for j=1,...,q</para>
  99
 100     <para>The functions f, G, H are coded in the Scilab function
 101     <literal>evalfunc</literal> and the set of matrices Xi's in the list X
 102     (i.e. <literal>X=list(X1,...,Xn)</literal>).</para>
 103
 104     <para>The function <literal>evalfun</literal> must return in the list
 105     <literal>LME</literal> the matrices <literal>G1(X),...,Gp(X)</literal>
 106     (i.e. <literal>LME(i)=Gi(X1,...,Xn),</literal> i=1,...,p).
 107     <literal>evalfun</literal> must return in the list <literal>LMI</literal>
 108     the matrices <literal>H1(X0),...,Hq(X)</literal> (i.e.
 109     <literal>LMI(j)=Hj(X1,...,Xn)</literal>, j=1,...,q).
 110     <literal>evalfun</literal> must return in <literal>OBJ</literal> the value
 111     of <literal>f(X)</literal> (i.e.
 112     <literal>OBJ=f(X1,...,Xn)</literal>).</para>
 113
 114     <para><literal>lmisolver</literal> returns in <literal>XLISTF</literal>, a
 115     list of real matrices, i. e. <literal>XLIST=list(X1,X2,..,Xn)</literal>
 116     where the Xi's solve the LMI problem:</para>
 117
 118     <para>Defining <literal>Y,Z</literal> and <literal>cost</literal>
 119     by:</para>
 120
 121     <para><literal>[Y,Z,cost]=evalfunc(XLIST)</literal>, <literal>Y</literal>
 122     is a list of zero matrices, <literal>Y=list(Y1,...,Yp)</literal>,
 123     <literal>Y1=0, Y2=0, ..., Yp=0</literal>.</para>
 124
 125     <para><literal> Z</literal> is a list of square symmetric matrices,
 126     <literal> Z=list(Z1,...,Zq) </literal>, which are semi positive definite
 127     <literal> Z1&gt;0, Z2&gt;0, ..., Zq&gt;0</literal> (i.e.
 128     <literal>spec(Z(j))</literal> &gt; 0),</para>
 129
 130     <para><literal>cost</literal> is minimized.</para>
 131
 132     <para><literal>lmisolver</literal> can also solve LMI problems in which
 133     the <literal>Xi's</literal> are not matrices but lists of matrices. More
 134     details are given in the documentation of LMITOOL.</para>
 135   </refsection>
 136
 137   <refsection>
 138     <title>Examples</title>
 139
 140     <programlisting role="example"><![CDATA[
 141 //Find diagonal matrix X (i.e. X=diag(diag(X), p=1) such that
 142 //A1'*X+X*A1+Q1 < 0, A2'*X+X*A2+Q2 < 0 (q=2) and trace(X) is maximized
 143 n  = 2;
 144 A1 = rand(n,n);
 145 A2 = rand(n,n);
 146 Xs = diag(1:n);
 147 Q1 = -(A1'*Xs+Xs*A1+0.1*eye());
 148 Q2 = -(A2'*Xs+Xs*A2+0.2*eye());
 149
 150 deff('[LME,LMI,OBJ]=evalf(Xlist)','X   = Xlist(1); ...
 151                                    LME = X-diag(diag(X));...
 152                                    LMI = list(-(A1''*X+X*A1+Q1),-(A2''*X+X*A2+Q2)); ...
 153                                    OBJ = -sum(diag(X))  ');
 154
 155 X=lmisolver(list(zeros(A1)),evalf);
 156
 157 X=X(1)
 158 [Y,Z,c]=evalf(X)
 159  ]]></programlisting>
 160   </refsection>
 161
 162   <refsection>
 163     <title>See Also</title>
 164
 165     <simplelist type="inline">
 166       <member><link linkend="lmitool">lmitool</link></member>
 167     </simplelist>
 168   </refsection>
 169 </refentry>