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

   1 <?xml version="1.0" encoding="ISO-8859-1" standalone="no"?>
   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 <!DOCTYPE MAN SYSTEM "../../../../modules/helptools/help.dtd">
  14 <MAN>
  15   <LANGUAGE>eng</LANGUAGE>
  16   <TITLE>lmisolver</TITLE>
  17   <TYPE>Scilab Function</TYPE>
  18   <DATE>$LastChangedDate$</DATE>
  19   <SHORT_DESCRIPTION name="lmisolver"> linear matrix inequation solver</SHORT_DESCRIPTION>
  20   <CALLING_SEQUENCE>
  21     <CALLING_SEQUENCE_ITEM>[XLISTF[,OPT]] = lmisolver(XLIST0,evalfunc [,options])  </CALLING_SEQUENCE_ITEM>
  22   </CALLING_SEQUENCE>
  23   <PARAM>
  24     <PARAM_INDENT>
  25       <PARAM_ITEM>
  26         <PARAM_NAME>XLIST0</PARAM_NAME>
  27         <PARAM_DESCRIPTION>
  28           <SP>: a list of containing initial guess (e.g. <VERB>XLIST0=list(X1,X2,..,Xn)</VERB>)</SP>
  29         </PARAM_DESCRIPTION>
  30       </PARAM_ITEM>
  31       <PARAM_ITEM>
  32         <PARAM_NAME>evalfunc</PARAM_NAME>
  33         <PARAM_DESCRIPTION>
  34           <SP>: a Scilab function (&quot;external&quot; function with specific
  35     syntax)</SP>
  36           <P>
  37     The syntax the function <VERB>evalfunc</VERB> must be as follows:
  38   </P>
  39           <P><VERB>[LME,LMI,OBJ]=evalfunct(X)</VERB> where <VERB>X</VERB> is a list of matrices, <VERB>LME, LMI</VERB> are lists and <VERB>OBJ</VERB> a real scalar.
  40   </P>
  41         </PARAM_DESCRIPTION>
  42       </PARAM_ITEM>
  43       <PARAM_ITEM>
  44         <PARAM_NAME>XLISTF</PARAM_NAME>
  45         <PARAM_DESCRIPTION>
  46           <SP>: a list of matrices (e.g. <VERB>XLIST0=list(X1,X2,..,Xn)</VERB>)</SP>
  47         </PARAM_DESCRIPTION>
  48       </PARAM_ITEM>
  49       <PARAM_ITEM>
  50         <PARAM_NAME>options</PARAM_NAME>
  51         <PARAM_DESCRIPTION>
  52           <SP>: optional parameter. If given, <VERB>options</VERB> is  a real row vector with 5 components <VERB>[Mbound,abstol,nu,maxiters,reltol]</VERB></SP>
  53         </PARAM_DESCRIPTION>
  54       </PARAM_ITEM>
  55     </PARAM_INDENT>
  56   </PARAM>
  57   <DESCRIPTION>
  58     <P><VERB>lmisolver</VERB> solves the following problem:</P>
  59     <P>
  60     minimize <VERB>f(X1,X2,...,Xn)</VERB> a linear function of Xi's</P>
  61     <P>
  62     under the linear constraints:
  63     <VERB>Gi(X1,X2,...,Xn)=0</VERB> for i=1,...,p and LMI (linear matrix
  64     inequalities) constraints:</P>
  65     <P><VERB>Hj(X1,X2,...,Xn) &gt; 0</VERB> for j=1,...,q</P>
  66     <P>
  67     The functions f, G, H are coded in the Scilab function <VERB>evalfunc</VERB>
  68     and the set of matrices Xi's in the list X (i.e.
  69     <VERB>X=list(X1,...,Xn)</VERB>).</P>
  70     <P>
  71     The function <VERB>evalfun</VERB> must return in the list <VERB>LME</VERB> the matrices
  72     <VERB>G1(X),...,Gp(X)</VERB> (i.e. <VERB>LME(i)=Gi(X1,...,Xn),</VERB> i=1,...,p).
  73     <VERB>evalfun</VERB> must return in the list <VERB>LMI</VERB> the matrices
  74     <VERB>H1(X0),...,Hq(X)</VERB> (i.e. <VERB>LMI(j)=Hj(X1,...,Xn)</VERB>, j=1,...,q).
  75     <VERB>evalfun</VERB> must return in <VERB>OBJ</VERB> the value of <VERB>f(X)</VERB>
  76     (i.e. <VERB>OBJ=f(X1,...,Xn)</VERB>).</P>
  77     <P><VERB>lmisolver</VERB>  returns in <VERB>XLISTF</VERB>, a list of real matrices,
  78     i. e. <VERB>XLIST=list(X1,X2,..,Xn)</VERB> where the Xi's solve the LMI
  79     problem:</P>
  80     <P>
  81     Defining <VERB>Y,Z</VERB> and <VERB>cost</VERB> by:</P>
  82     <P><VERB>[Y,Z,cost]=evalfunc(XLIST)</VERB>, <VERB>Y</VERB> is a list of zero matrices,
  83     <VERB>Y=list(Y1,...,Yp)</VERB>, <VERB>Y1=0, Y2=0, ..., Yp=0</VERB>.</P>
  84     <P><VERB> Z</VERB> is a list of square symmetric matrices,
  85     <VERB> Z=list(Z1,...,Zq) </VERB>, which are semi positive definite
  86     <VERB> Z1&gt;0, Z2&gt;0, ..., Zq&gt;0</VERB> (i.e. <VERB>spec(Z(j))</VERB> &gt; 0),</P>
  87     <P><VERB>cost</VERB> is minimized.</P>
  88     <P><VERB>lmisolver</VERB> can also solve LMI problems in which the <VERB>Xi's</VERB>
  89     are not matrices but lists of matrices. More details are given in the
  90     documentation of LMITOOL.</P>
  91   </DESCRIPTION>
  92   <EXAMPLE>
  93 <![CDATA[
  94 //Find diagonal matrix X (i.e. X=diag(diag(X), p=1) such that
  95 //A1'*X+X*A1+Q1 < 0, A2'*X+X*A2+Q2 < 0 (q=2) and trace(X) is maximized
  96 n=2;A1=rand(n,n);A2=rand(n,n);
  97 Xs=diag(1:n);Q1=-(A1'*Xs+Xs*A1+0.1*eye());
  98 Q2=-(A2'*Xs+Xs*A2+0.2*eye());
  99 deff('[LME,LMI,OBJ]=evalf(Xlist)','X=Xlist(1),LME=X-diag(diag(X));...
 100 LMI=list(-(A1''*X+X*A1+Q1),-(A2''*X+X*A2+Q2)),OBJ= -sum(diag(X))  ');
 101 X=lmisolver(list(zeros(A1)),evalf);X=X(1)
 102 [Y,Z,c]=evalf(X)
 103  ]]>
 104   </EXAMPLE>
 105   <SEE_ALSO>
 106     <SEE_ALSO_ITEM>
 107       <LINK>lmitool</LINK>
 108     </SEE_ALSO_ITEM>
 109   </SEE_ALSO>
 110 </MAN>