Bug Fix #14415 - Corrected some spellings error in help pages
[scilab.git] / scilab / modules / polynomials / help / en_US / factors.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) 2006-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="factors">
17     <refnamediv>
18         <refname>factors</refname>
19         <refpurpose>numeric real factorization</refpurpose>
20     </refnamediv>
21     <refsynopsisdiv>
22         <title>Syntax</title>
23         <synopsis>[lnum,g]=factors(pol [,'flag'])
24             [lnum,lden,g]=factors(rat [,'flag'])
25             rat=factors(rat,'flag')
26         </synopsis>
27     </refsynopsisdiv>
28     <refsection>
29         <title>Arguments</title>
30         <variablelist>
31             <varlistentry>
32                 <term>pol</term>
33                 <listitem>
34                     <para>real polynomial</para>
35                 </listitem>
36             </varlistentry>
37             <varlistentry>
38                 <term>rat</term>
39                 <listitem>
40                     <para>
41                         real rational polynomial (<literal>rat=pol1/pol2</literal>)
42                     </para>
43                 </listitem>
44             </varlistentry>
45             <varlistentry>
46                 <term>lnum</term>
47                 <listitem>
48                     <para>list of polynomials (of degrees 1 or 2)</para>
49                 </listitem>
50             </varlistentry>
51             <varlistentry>
52                 <term>lden</term>
53                 <listitem>
54                     <para>list of polynomials (of degrees 1 or 2)</para>
55                 </listitem>
56             </varlistentry>
57             <varlistentry>
58                 <term>g</term>
59                 <listitem>
60                     <para>real number</para>
61                 </listitem>
62             </varlistentry>
63             <varlistentry>
64                 <term>flag</term>
65                 <listitem>
66                     <para>
67                         character string <literal>'c'</literal> or <literal>'d'</literal>
68                     </para>
69                 </listitem>
70             </varlistentry>
71         </variablelist>
72     </refsection>
73     <refsection>
74         <title>Description</title>
75         <para>
76             returns the factors of polynomial <literal>pol</literal> in the list <literal>lnum</literal>
77             and the "gain" g.
78         </para>
79         <para>
80             One has pol= g times product of entries of the list <literal>lnum</literal>
81             (if <literal>flag</literal> is not given). If <literal>flag='c'</literal> is given, then
82             one has <literal>|pol(i omega)|</literal> = <literal>|g*prod(lnum_j(i omega)|</literal>.
83             If <literal>flag='d'</literal> is given, then
84             one has <literal>|pol(exp(i omega))|</literal> = <literal>|g*prod(lnum_i(exp(i omega))|</literal>.
85             If argument of <literal>factors</literal> is a 1x1 rational <literal>rat=pol1/pol2</literal>,
86             the factors of the numerator <literal>pol1</literal> and the denominator <literal>pol2</literal>
87             are returned in the lists <literal>lnum</literal> and <literal>lden</literal> respectively.
88         </para>
89         <para>
90             The "gain" is returned as <literal>g</literal>,i.e. one has:
91             rat= g times (product entries in lnum) / (product entries in lden).
92         </para>
93         <para>
94             If <literal>flag</literal> is <literal>'c'</literal> (resp. <literal>'d'</literal>), the roots of <literal>pol</literal>
95             are reflected wrt the imaginary axis (resp. the unit circle), i.e.
96             the factors in <literal>lnum</literal> are stable polynomials.
97         </para>
98         <para>
99             Same thing if <literal>factors</literal> is invoked with a rational arguments:
100             the entries in <literal>lnum</literal> and <literal>lden</literal> are stable polynomials if
101             <literal>flag</literal> is given. <literal>R2=factors(R1,'c')</literal> or <literal>R2=factors(R1,'d')</literal>
102             with <literal>R1</literal> a rational function or SISO <literal>syslin</literal> list then the
103             output <literal>R2</literal> is a transfer with stable numerator and denominator and
104             with same magnitude as <literal>R1</literal> along the imaginary axis (<literal>'c'</literal>)
105             or unit circle (<literal>'d'</literal>).
106         </para>
107     </refsection>
108     <refsection>
109         <title>Examples</title>
110         <programlisting role="example"><![CDATA[
111 n=poly([0.2,2,5],'z');
112 d=poly([0.1,0.3,7],'z');
113 R=syslin('d',n,d);
114 R1=factors(R,'d')
115 roots(R1('num'))
116 roots(R1('den'))
117 w=exp(2*%i*%pi*[0:0.1:1]);
118 norm(abs(horner(R1,w))-abs(horner(R,w)))
119  ]]></programlisting>
120     </refsection>
121     <refsection role="see also">
122         <title>See Also</title>
123         <simplelist type="inline">
124             <member>
125                 <link linkend="simp">simp</link>
126             </member>
127         </simplelist>
128     </refsection>
129 </refentry>