71346edb5a12c51fa86a3e9b9d4e0f5776e803a3
[scilab.git] / scilab / modules / linear_algebra / help / en_US / eigen / gschur.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  * 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" scilab:needs-examples="no" xml:id="gschur">
14     <refnamediv>
15         <refname>gschur</refname>
16         <refpurpose>
17             generalized Schur form. <emphasis role="bold">This function is obsolete.</emphasis>
18         </refpurpose>
19     </refnamediv>
20     <refsynopsisdiv>
21         <title>Calling Sequence</title>
22         <synopsis>[As,Es]=gschur(A,E)
23             [As,Es,Q,Z]=gschur(A,E)
24             [As,Es,Z,dim] = gschur(A,E,flag)
25             [As,Es,Z,dim]= gschur(A,E,extern)
26         </synopsis>
27     </refsynopsisdiv>
28     <refsection>
29         <title>Description</title>
30         <para>
31             This function is obsolete and is now included in the <literal>schur</literal>
32             function. In most cases the <literal>gschur</literal> function will still work as
33             before, but it will be removed in the future release. 
34         </para>
35         <para>
36             The first three syntaxes can be replaced by
37         </para>
38         <programlisting role=""><![CDATA[ 
39 [As,Es]=schur(A,E)
40 [As,Es,Q,Z]=schur(A,E);Q=Q' //NOTE THE TRANPOSITION HERE
41 [As,Es,Z,dim] = schur(A,E,flag) 
42  ]]></programlisting>
43         <para>
44             The last syntax requires little more adaptations:
45         </para>
46         <variablelist>
47             <varlistentry>
48                 <term>if</term>
49                 <listitem>
50                     <para>extern is a scilab function  the new calling sequence
51                         should be <literal>[As,Es,Z,dim]= schur(A,E,Nextern)</literal> with
52                         Nextern defined as follow:
53                     </para>
54                     <programlisting role=""><![CDATA[ 
55 function t=Nextern(R)
56 if R(2)==0 then
57   t=extern([1,R(1),R(3)])==1
58 else
59   c=(R(1)+%i*R(2))/R(3)
60   t=extern([2,real(c+c'),real(c*c')])==1
61 end
62 endfunction
63  ]]></programlisting>
64                 </listitem>
65             </varlistentry>
66             <varlistentry>
67                 <term>if</term>
68                 <listitem>
69                     <para>extern is the name of an external function coded in Fortran or C
70                         the new calling sequence should be <literal>[As,Es,Z,dim]=    schur(A,E,'nextern')</literal> with nextern defined as follow:
71                     </para>
72                 </listitem>
73             </varlistentry>
74         </variablelist>
75         <programlisting role=""><![CDATA[ 
76 logical function nextern(ar,ai,beta)
77 double precision ar,ai,beta
78 integer r,extern
79 if (ai.eq.0.0d0) then
80   r=extern(1,ar,beta,0.0d0,0.0d0)
81 else
82   r=extern(2,0.0d0,0.0d0,2.0d0*ar,ar*ar+ai*ai)
83 endif
84 nextern=r.eq.1
85 end
86  ]]></programlisting>
87     </refsection>
88     <refsection role="see also">
89         <title>See Also</title>
90         <simplelist type="inline">
91             <member>
92                 <link linkend="external">external</link>
93             </member>
94             <member>
95                 <link linkend="schur">schur</link>
96             </member>
97         </simplelist>
98     </refsection>
99 </refentry>