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