License Header change: Removed the LICENSE_END before beta
[scilab.git] / scilab / modules / cacsd / help / en_US / contr.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  * Copyright (C) 2012 - 2016 - Scilab Enterprises
7  *
8  * This file is hereby licensed under the terms of the GNU GPL v2.0,
9  * pursuant to article 5.3.4 of the CeCILL v.2.1.
10  * This file was originally licensed under the terms of the CeCILL v2.1,
11  * and continues to be available under such terms.
12  * For more information, see the COPYING file which you should have received
13  * along with this program.
14  *
15  -->
16 <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="contr">
17     <refnamediv>
18         <refname>contr</refname>
19         <refpurpose>controllability, controllable subspace, staircase</refpurpose>
20     </refnamediv>
21     <refsynopsisdiv>
22         <title>Calling Sequence</title>
23         <synopsis>n=contr(A,B [,tol])
24             [n,U]=contr(A,B [,tol])
25             [n,U,ind,V,Ac,Bc]=contr(A,B,[,tol])
26         </synopsis>
27     </refsynopsisdiv>
28     <refsection>
29         <title>Arguments</title>
30         <variablelist>
31             <varlistentry>
32                 <term>A, B</term>
33                 <listitem>
34                     <para>real matrices</para>
35                 </listitem>
36             </varlistentry>
37             <varlistentry>
38                 <term>tol</term>
39                 <listitem>
40                     <para>tolerance parameter</para>
41                 </listitem>
42             </varlistentry>
43             <varlistentry>
44                 <term>n</term>
45                 <listitem>
46                     <para> dimension of controllable subspace.</para>
47                 </listitem>
48             </varlistentry>
49             <varlistentry>
50                 <term>U</term>
51                 <listitem>
52                     <para>
53                         orthogonal change of basis which puts <literal>(A,B)</literal> in canonical form.
54                     </para>
55                 </listitem>
56             </varlistentry>
57             <varlistentry>
58                 <term>V</term>
59                 <listitem>
60                     <para>orthogonal matrix, change of basis in the control space.</para>
61                 </listitem>
62             </varlistentry>
63             <varlistentry>
64                 <term>Ac</term>
65                 <listitem>
66                     <para>
67                         block Hessenberg matrix <literal>Ac=U'*A*U</literal>
68                     </para>
69                 </listitem>
70             </varlistentry>
71             <varlistentry>
72                 <term>Bc</term>
73                 <listitem>
74                     <para>
75                         is <literal>U'*B*V</literal>.
76                     </para>
77                 </listitem>
78             </varlistentry>
79             <varlistentry>
80                 <term>ind</term>
81                 <listitem>
82                     <para>
83                         p integer vector associated with controllability indices  (dimensions of subspaces <literal>B, B+A*B,...=ind(1),ind(1)+ind(2),...</literal>)
84                     </para>
85                 </listitem>
86             </varlistentry>
87         </variablelist>
88     </refsection>
89     <refsection>
90         <title>Description</title>
91         <para>
92             <literal>[n,[U]]=contr(A,B,[tol])</literal> gives the controllable form of an <literal>(A,B)</literal> 
93             pair.(<literal>dx/dt = A x + B u</literal> or <literal>x(n+1) = A x(n) +b u(n)</literal>).
94             The <literal>n</literal> first columns of <literal>U</literal> make a basis for the controllable
95             subspace.
96         </para>
97         <para>
98             If <literal>V=U(:,1:n)</literal>, then <literal>V'*A*V</literal> and  <literal>V'*B</literal> give the controllable part
99             of the <literal>(A,B)</literal> pair.
100         </para>
101         <para>
102             The pair <literal>(Bc, Ac)</literal> is in staircase controllable form.
103         </para>
104         <programlisting role=""><![CDATA[ 
105                    |B |sI-A      *  . . .  *      *       |
106                    | 1|    11       .      .      .       |
107                    |  |  A    sI-A    .    .      .       |
108                    |  |   21      22    .  .      .       |
109                    |  |        .     .     *      *       |
110 [U'BV|sI - U'AU] = |0 |     0    .     .                  |
111                    |  |            A     sI-A     *       |
112                    |  |             p,p-1    pp           |
113                    |  |                                   |
114                    |0 |         0          0   sI-A       |
115                    |  |                            p+1,p+1|
116  ]]></programlisting>
117     </refsection>
118     <refsection>
119         <title>Reference</title>
120         <para>
121             Slicot library (see ab01od in SCI/modules/cacsd/src/slicot).
122         </para>
123     </refsection>
124     <refsection>
125         <title>Examples</title>
126         <programlisting role="example"><![CDATA[ 
127 W=ssrand(2,3,5,list('co',3));  //cont. subspace has dim 3.
128 A=W("A");B=W("B");
129 [n,U]=contr(A,B);n
130 A1=U'*A*U;
131 spec(A1(n+1:$,n+1:$))  //uncontrollable modes
132 spec(A+B*rand(3,5))    
133  ]]></programlisting>
134     </refsection>
135     <refsection role="see also">
136         <title>See Also</title>
137         <simplelist type="inline">
138             <member>
139                 <link linkend="canon">canon</link>
140             </member>
141             <member>
142                 <link linkend="cont_mat">cont_mat</link>
143             </member>
144             <member>
145                 <link linkend="unobs">unobs</link>
146             </member>
147             <member>
148                 <link linkend="stabil">stabil</link>
149             </member>
150             <member>
151                 <link linkend="st_ility">st_ility</link>
152             </member>
153         </simplelist>
154     </refsection>
155 </refentry>