Fix the XML declarations
[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>