Re-indent XML Files
[scilab.git] / scilab / modules / optimization / help / en_US / lmisolver.xml
1 <?xml version="1.0" encoding="ISO-8859-1"?>
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 xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" version="5.0-subset Scilab" xml:lang="en" xml:id="lmisolver">
14   <info>
15     <pubdate>$LastChangedDate$</pubdate>
16   </info>
17   <refnamediv>
18     <refname>lmisolver</refname>
19     <refpurpose> linear matrix inequation solver</refpurpose>
20   </refnamediv>
21   <refsynopsisdiv>
22     <title>Calling Sequence</title>
23     <synopsis>[XLISTF[,OPT]] = lmisolver(XLIST0,evalfunc [,options])</synopsis>
24   </refsynopsisdiv>
25   <refsection>
26     <title>Parameters</title>
27     <variablelist>
28       <varlistentry>
29         <term>XLIST0</term>
30         <listitem>
31           <para>a list of containing initial guess (e.g. <literal>XLIST0=list(X1,X2,..,Xn)</literal>)</para>
32         </listitem>
33       </varlistentry>
34       <varlistentry>
35         <term>evalfunc</term>
36         <listitem>
37           <para>a Scilab function ("external" function with specific
38     syntax)</para>
39           <para>
40     The syntax the function <literal>evalfunc</literal> must be as follows:
41   </para>
42           <para><literal>[LME,LMI,OBJ]=evalfunct(X)</literal> where <literal>X</literal> is a list of matrices, <literal>LME, LMI</literal> are lists and <literal>OBJ</literal> a real scalar.
43   </para>
44         </listitem>
45       </varlistentry>
46       <varlistentry>
47         <term>XLISTF</term>
48         <listitem>
49           <para>a list of matrices (e.g. <literal>XLIST0=list(X1,X2,..,Xn)</literal>)</para>
50         </listitem>
51       </varlistentry>
52       <varlistentry>
53         <term>options</term>
54         <listitem>
55           <para>optional parameter. If given, <literal>options</literal> is  a real row vector with 5 components <literal>[Mbound,abstol,nu,maxiters,reltol]</literal></para>
56         </listitem>
57       </varlistentry>
58     </variablelist>
59   </refsection>
60   <refsection>
61     <title>Description</title>
62     <para><literal>lmisolver</literal> solves the following problem:</para>
63     <para>
64     minimize <literal>f(X1,X2,...,Xn)</literal> a linear function of Xi's</para>
65     <para>
66     under the linear constraints:
67     <literal>Gi(X1,X2,...,Xn)=0</literal> for i=1,...,p and LMI (linear matrix
68     inequalities) constraints:</para>
69     <para><literal>Hj(X1,X2,...,Xn) &gt; 0</literal> for j=1,...,q</para>
70     <para>
71     The functions f, G, H are coded in the Scilab function <literal>evalfunc</literal>
72     and the set of matrices Xi's in the list X (i.e.
73     <literal>X=list(X1,...,Xn)</literal>).</para>
74     <para>
75     The function <literal>evalfun</literal> must return in the list <literal>LME</literal> the matrices
76     <literal>G1(X),...,Gp(X)</literal> (i.e. <literal>LME(i)=Gi(X1,...,Xn),</literal> i=1,...,p).
77     <literal>evalfun</literal> must return in the list <literal>LMI</literal> the matrices
78     <literal>H1(X0),...,Hq(X)</literal> (i.e. <literal>LMI(j)=Hj(X1,...,Xn)</literal>, j=1,...,q). 
79     <literal>evalfun</literal> must return in <literal>OBJ</literal> the value of <literal>f(X)</literal>
80     (i.e. <literal>OBJ=f(X1,...,Xn)</literal>).</para>
81     <para><literal>lmisolver</literal>  returns in <literal>XLISTF</literal>, a list of real matrices,
82     i. e. <literal>XLIST=list(X1,X2,..,Xn)</literal> where the Xi's solve the LMI
83     problem:</para>
84     <para>
85     Defining <literal>Y,Z</literal> and <literal>cost</literal> by:</para>
86     <para><literal>[Y,Z,cost]=evalfunc(XLIST)</literal>, <literal>Y</literal> is a list of zero matrices, 
87     <literal>Y=list(Y1,...,Yp)</literal>, <literal>Y1=0, Y2=0, ..., Yp=0</literal>.</para>
88     <para><literal> Z</literal> is a list of square symmetric matrices, 
89     <literal> Z=list(Z1,...,Zq) </literal>, which are semi positive definite
90     <literal> Z1&gt;0, Z2&gt;0, ..., Zq&gt;0</literal> (i.e. <literal>spec(Z(j))</literal> &gt; 0),</para>
91     <para><literal>cost</literal> is minimized.</para>
92     <para><literal>lmisolver</literal> can also solve LMI problems in which the <literal>Xi's</literal> 
93     are not matrices but lists of matrices. More details are given in the 
94     documentation of LMITOOL.</para>
95   </refsection>
96   <refsection>
97     <title>Examples</title>
98     <programlisting role="example"><![CDATA[
99
100 //Find diagonal matrix X (i.e. X=diag(diag(X), p=1) such that
101 //A1'*X+X*A1+Q1 < 0, A2'*X+X*A2+Q2 < 0 (q=2) and trace(X) is maximized 
102 n=2;A1=rand(n,n);A2=rand(n,n);
103 Xs=diag(1:n);Q1=-(A1'*Xs+Xs*A1+0.1*eye());
104 Q2=-(A2'*Xs+Xs*A2+0.2*eye());
105 deff('[LME,LMI,OBJ]=evalf(Xlist)','X=Xlist(1),LME=X-diag(diag(X));...
106 LMI=list(-(A1''*X+X*A1+Q1),-(A2''*X+X*A2+Q2)),OBJ= -sum(diag(X))  ');
107 X=lmisolver(list(zeros(A1)),evalf);X=X(1)
108 [Y,Z,c]=evalf(X)
109  
110   ]]></programlisting>
111   </refsection>
112   <refsection>
113     <title>See Also</title>
114     <simplelist type="inline">
115       <member>
116         <link linkend="lmitool">lmitool</link>
117       </member>
118     </simplelist>
119   </refsection>
120 </refentry>