Avoid multilines declarations
[scilab.git] / scilab / modules / cacsd / help / en_US / ricc.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) 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" xmlns:scilab="http://www.scilab.org" xml:lang="en" xml:id="ricc">
14     <refnamediv>
15         <refname>ricc</refname>
16         <refpurpose>Riccati equation</refpurpose>
17     </refnamediv>
18     <refsynopsisdiv>
19         <title>Calling Sequence</title>
20         <synopsis>[X,RCOND,FERR]=ricc(A,B,C,"cont""method")
21             [X,RCOND,FERR]=ricc(F,G,H,"disc","method")
22         </synopsis>
23     </refsynopsisdiv>
24     <refsection>
25         <title>Arguments</title>
26         <variablelist>
27             <varlistentry>
28                 <term>A,B,C</term>
29                 <listitem>
30                     <para>real matrices of appropriate dimensions</para>
31                 </listitem>
32             </varlistentry>
33             <varlistentry>
34                 <term>F,G,H</term>
35                 <listitem>
36                     <para>real matrices of appropriate dimensions</para>
37                 </listitem>
38             </varlistentry>
39             <varlistentry>
40                 <term>X</term>
41                 <listitem>
42                     <para>real matrix</para>
43                 </listitem>
44             </varlistentry>
45             <varlistentry>
46                 <term>"cont","disc"'  </term>
47                 <listitem>
48                     <para>imposed string (flag for continuous or discrete)</para>
49                 </listitem>
50             </varlistentry>
51             <varlistentry>
52                 <term>method</term>
53                 <listitem>
54                     <para>'schr' or 'sign' for continuous-time systems and 'schr' or 'invf' for discrete-tyme systems</para>
55                 </listitem>
56             </varlistentry>
57         </variablelist>
58     </refsection>
59     <refsection>
60         <title>Description</title>
61         <para>
62             Riccati solver.
63         </para>
64         <para>
65             Continuous time:
66         </para>
67         <programlisting role=""><![CDATA[ 
68 X=ricc(A,B,C,'cont')
69  ]]></programlisting>
70         <para>
71             gives a solution to the continuous time ARE
72         </para>
73         <programlisting role=""><![CDATA[ 
74 A'*X+X*A-X*B*X+C=0 .
75  ]]></programlisting>
76         <para>
77             <literal>B</literal> and <literal>C</literal> are assumed to be nonnegative definite.
78             <literal>(A,G)</literal> is assumed to be stabilizable with <literal>G*G'</literal> a full rank
79             factorization of <literal>B</literal>.
80         </para>
81         <para>
82             <literal>(A,H)</literal> is assumed to be detectable with <literal>H*H'</literal> a full rank
83             factorization of <literal>C</literal>.
84         </para>
85         <para>
86             Discrete time:
87         </para>
88         <programlisting role=""><![CDATA[ 
89 X=ricc(F,G,H,'disc')
90  ]]></programlisting>
91         <para>
92             gives a solution  to the discrete time ARE
93         </para>
94         <programlisting role=""><![CDATA[ 
95 X=F'*X*F-F'*X*G1*((G2+G1'*X*G1)^-1)*G1'*X*F+H
96  ]]></programlisting>
97         <para>
98             <literal>F</literal> is assumed invertible and   <literal>G = G1*inv(G2)*G1'</literal>.
99         </para>
100         <para>
101             One  assumes  <literal>(F,G1)</literal> stabilizable and <literal>(C,F)</literal> detectable
102             with <literal>C'*C</literal> full rank factorization of <literal>H</literal>. Use preferably
103             <literal>ric_desc</literal>.
104         </para>
105         <para>
106             C, D are symmetric .It is assumed that the matrices A, C and D are such that the corresponding matrix pencil has N eigenvalues with moduli less than one.
107         </para>
108         <para>
109             Error bound on the solution and a condition estimate are also provided.
110             It is assumed that the matrices A, C and D are such that the
111             corresponding Hamiltonian matrix has N eigenvalues with negative real parts.
112         </para>
113     </refsection>
114     <refsection>
115         <title>Examples</title>
116         <programlisting role="example"><![CDATA[ 
117 //Standard formulas to compute Riccati solutions
118 A=rand(3,3);
119 B=rand(3,2);
120 C=rand(3,3);
121 C=C*C';
122 R=rand(2,2);
123 R=R*R'+eye();
124 B=B*inv(R)*B';
125 X=ricc(A,B,C,'cont');
126 norm(A'*X+X*A-X*B*X+C,1)
127 H=[A -B;-C -A'];
128 [T,d]=schur(eye(H),H,'cont');
129 T=T(:,1:d);
130 X1=T(4:6,:)/T(1:3,:);
131 norm(X1-X,1)
132 [T,d]=schur(H,'cont');
133 T=T(:,1:d);
134 X2=T(4:6,:)/T(1:3,:);
135 norm(X2-X,1)
136 //       Discrete time case
137 F=A;
138 B=rand(3,2);
139 G1=B;
140 G2=R;
141 G=G1/G2*G1';
142 H=C;
143 X=ricc(F,G,H,'disc');
144 norm(F'*X*F-(F'*X*G1/(G2+G1'*X*G1))*(G1'*X*F)+H-X)
145 H1=[eye(3,3) G;zeros(3,3) F'];
146 H2=[F zeros(3,3);-H eye(3,3)];
147 [T,d]=schur(H2,H1,'disc');
148 T=T(:,1:d);
149 X1=T(4:6,:)/T(1:3,:);
150 norm(X1-X,1)
151 Fi=inv(F);
152 Hami=[Fi Fi*G;H*Fi F'+H*Fi*G];
153 [T,d]=schur(Hami,'d');
154 T=T(:,1:d);
155 Fit=inv(F');
156 Ham=[F+G*Fit*H -G*Fit;-Fit*H Fit];
157 [T,d]=schur(Ham,'d');
158 T=T(:,1:d);
159 X2=T(4:6,:)/T(1:3,:);
160 norm(X2-X,1)
161  ]]></programlisting>
162     </refsection>
163     <refsection role="see also">
164         <title>See Also</title>
165         <simplelist type="inline">
166             <member>
167                 <link linkend="riccati">riccati</link>
168             </member>
169             <member>
170                 <link linkend="ric_desc">ric_desc</link>
171             </member>
172             <member>
173                 <link linkend="schur">schur</link>
174             </member>
175         </simplelist>
176     </refsection>
177     <refsection>
178         <title>Used Functions</title>
179         <para>See SCI/modules/cacsd/src/slicot/riccpack.f</para>
180     </refsection>
181 </refentry>