1e8f8b54b700e63ac93d0c28572aaf3d79916853
[scilab.git] / scilab / modules / linear_algebra / help / en_US / pencil / kroneck.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  * 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="kroneck">
17     <refnamediv>
18         <refname>kroneck</refname>
19         <refpurpose>Kronecker form of matrix pencil</refpurpose>
20     </refnamediv>
21     <refsynopsisdiv>
22         <title>Syntax</title>
23         <synopsis>[Q,Z,Qd,Zd,numbeps,numbeta]=kroneck(F)
24             [Q,Z,Qd,Zd,numbeps,numbeta]=kroneck(E,A)
25         </synopsis>
26     </refsynopsisdiv>
27     <refsection>
28         <title>Arguments</title>
29         <variablelist>
30             <varlistentry>
31                 <term>F</term>
32                 <listitem>
33                     <para>
34                         real matrix pencil <literal>F=s*E-A</literal>
35                     </para>
36                 </listitem>
37             </varlistentry>
38             <varlistentry>
39                 <term>E,A</term>
40                 <listitem>
41                     <para>two real matrices of same dimensions</para>
42                 </listitem>
43             </varlistentry>
44             <varlistentry>
45                 <term>Q,Z</term>
46                 <listitem>
47                     <para>two square orthogonal matrices</para>
48                 </listitem>
49             </varlistentry>
50             <varlistentry>
51                 <term>Qd,Zd</term>
52                 <listitem>
53                     <para>two vectors of integers</para>
54                 </listitem>
55             </varlistentry>
56             <varlistentry>
57                 <term>numbeps,numeta</term>
58                 <listitem>
59                     <para>two vectors of integers</para>
60                 </listitem>
61             </varlistentry>
62         </variablelist>
63     </refsection>
64     <refsection>
65         <title>Description</title>
66         <para>
67             Kronecker form of matrix pencil: <literal>kroneck</literal> computes two
68             orthogonal matrices <literal>Q, Z</literal> which put the pencil <literal>F=s*E -A</literal> into
69             upper-triangular form:
70         </para>
71         <programlisting role=""><![CDATA[ 
72            | sE(eps)-A(eps) |        X       |      X     |      X        |
73            |----------------|----------------|------------|---------------|
74            |        O       | sE(inf)-A(inf) |      X     |      X        |
75 Q(sE-A)Z = |---------------------------------|----------------------------|
76            |                |                |            |               |
77            |        0       |       0        | sE(f)-A(f) |      X        |
78            |--------------------------------------------------------------|
79            |                |                |            |               |
80            |        0       |       0        |      0     | sE(eta)-A(eta)|
81  ]]></programlisting>
82         <para>
83             The dimensions of the four blocks are given by:
84         </para>
85         <para>
86             <literal>eps=Qd(1) x Zd(1)</literal>, <literal>inf=Qd(2) x Zd(2)</literal>,
87             <literal>f = Qd(3) x Zd(3)</literal>, <literal>eta=Qd(4)xZd(4)</literal>
88         </para>
89         <para>
90             The <literal>inf</literal> block contains the infinite modes of
91             the pencil.
92         </para>
93         <para>
94             The <literal>f</literal> block contains the finite modes of
95             the pencil
96         </para>
97         <para>
98             The structure of epsilon and eta blocks are given by:
99         </para>
100         <para>
101             <literal>numbeps(1)</literal> = <literal>#</literal> of eps blocks of size 0 x 1
102         </para>
103         <para>
104             <literal>numbeps(2)</literal> = <literal>#</literal> of eps blocks of size 1 x 2
105         </para>
106         <para>
107             <literal>numbeps(3)</literal> = <literal>#</literal> of eps blocks of size 2 x 3     etc...
108         </para>
109         <para>
110             <literal>numbeta(1)</literal> = <literal>#</literal> of eta blocks of size 1 x 0
111         </para>
112         <para>
113             <literal>numbeta(2)</literal> = <literal>#</literal> of eta blocks of size 2 x 1
114         </para>
115         <para>
116             <literal>numbeta(3)</literal> = <literal>#</literal> of eta blocks of size 3 x 2     etc...
117         </para>
118         <para>
119             The code is taken from T. Beelen (Slicot-WGS group).
120         </para>
121     </refsection>
122     <refsection>
123         <title>Examples</title>
124         <programlisting role="example"><![CDATA[ 
125 F=randpencil([1,1,2],[2,3],[-1,3,1],[0,3]);
126 Q=rand(17,17);Z=rand(18,18);F=Q*F*Z;
127 //random pencil with eps1=1,eps2=1,eps3=1; 2 J-blocks @ infty 
128 //with dimensions 2 and 3
129 //3 finite eigenvalues at -1,3,1 and eta1=0,eta2=3
130 [Q,Z,Qd,Zd,numbeps,numbeta]=kroneck(F);
131 [Qd(1),Zd(1)]    //eps. part is sum(epsi) x (sum(epsi) + number of epsi) 
132 [Qd(2),Zd(2)]    //infinity part
133 [Qd(3),Zd(3)]    //finite part
134 [Qd(4),Zd(4)]    //eta part is (sum(etai) + number(eta1)) x sum(etai)
135 numbeps
136 numbeta
137  ]]></programlisting>
138     </refsection>
139     <refsection role="see also">
140         <title>See Also</title>
141         <simplelist type="inline">
142             <member>
143                 <link linkend="gschur">gschur</link>
144             </member>
145             <member>
146                 <link linkend="gspec">gspec</link>
147             </member>
148             <member>
149                 <link linkend="systmat">systmat</link>
150             </member>
151             <member>
152                 <link linkend="pencan">pencan</link>
153             </member>
154             <member>
155                 <link linkend="randpencil">randpencil</link>
156             </member>
157             <member>
158                 <link linkend="trzeros">trzeros</link>
159             </member>
160         </simplelist>
161     </refsection>
162 </refentry>