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