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