Revision of help pages for poly function after commit 19f65129f614e293dd5663e8f6e0ef0...
[scilab.git] / scilab / modules / polynomials / help / en_US / poly.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <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="poly">
3     <refnamediv>
4         <refname>poly</refname>
5         <refpurpose>polynomial definition</refpurpose>
6     </refnamediv>
7     <refsynopsisdiv>
8         <title>Calling Sequence</title>
9         <synopsis>p = poly(a, vname, ["flag"])</synopsis>
10     </refsynopsisdiv>
11     <refsection>
12         <title>Arguments</title>
13         <variablelist>
14             <varlistentry>
15                 <term>a</term>
16                 <listitem>
17                     <para>a matrix or real number</para>
18                 </listitem>
19             </varlistentry>
20             <varlistentry>
21                 <term>vname</term>
22                 <listitem>
23                     <para>a string, the symbolic variable name. The string must be 4 characters max.
24                     </para>
25                 </listitem>
26             </varlistentry>
27             <varlistentry>
28                 <term>"flag"</term>
29                 <listitem>
30                     <para>
31                         string (<literal>"roots"</literal>, <literal>"coeff"</literal>),
32                         default value is <literal>"roots"</literal>.
33                     </para>
34                     <para>
35                         Shortcuts can be also used: <literal>"r"</literal> for <literal>"roots"</literal> and <literal>"c"</literal> for <literal>"coeff"</literal>.
36                     </para>
37                 </listitem>
38             </varlistentry>
39         </variablelist>
40     </refsection>
41     <refsection>
42         <title>Description</title>
43         <variablelist>
44             <varlistentry>
45                 <term>
46                     If <literal>a</literal> is a matrix,
47                 </term>
48                 <listitem>
49                     <para>
50                         <varname>p</varname> is the characteristic
51                         polynomial i.e. <code>determinant(x*eye()-a)</code>, <literal>x</literal> being
52                         the symbolic variable.
53                     </para>
54                 </listitem>
55             </varlistentry>
56             <varlistentry>
57                 <term>If <literal>v</literal> is a vector,</term>
58                 <listitem>
59                     <itemizedlist>
60                         <listitem>
61                             <para>
62                                 <code>poly(v,"x",["roots"])</code>  is the polynomial
63                                 with <literal>roots</literal> the entries of <varname>v</varname> and
64                                 <literal>"x"</literal> as formal variable. (In this case,
65                                 <function>roots</function> and   <function>poly</function> are inverse functions).
66                                 <note>
67                                     Note that Infinite roots gives zero  highest degree coefficients.
68                                 </note>
69                             </para>
70                         </listitem>
71                         <listitem>
72                             <para>
73                                 <code>poly(v,"x","coeff")</code> creates the
74                                 polynomial with symbol <literal>"x"</literal> and with coefficients
75                                 the entries of <varname>v</varname> (<code>v(1)</code> is the constant term
76                                 of the polynomial). (Here <function>poly</function> and <function>coeff</function> are
77                                 inverse functions).
78                             </para>
79                         </listitem>
80                     </itemizedlist>
81                 </listitem>
82             </varlistentry>
83         </variablelist>
84         <para>
85             <code>s=poly(0,"s")</code> is the seed for defining
86             polynomials with symbol <literal>"s"</literal>.
87         </para>
88     </refsection>
89     <refsection>
90         <title>Examples</title>
91         <programlisting role="example"><![CDATA[
92 s=poly(0,"s");
93 p=1+s+2*s^2
94 A=rand(2,2);
95 poly(A,"x")
96 //rational fractions
97 h=(1+2*%s)/poly(1:4,'s','c')
98  ]]></programlisting>
99     </refsection>
100     <refsection role="see also">
101         <title>See Also</title>
102         <simplelist type="inline">
103             <member>
104                 <link linkend="coeff">coeff</link>
105             </member>
106             <member>
107                 <link linkend="roots">roots</link>
108             </member>
109             <member>
110                 <link linkend="varn">varn</link>
111             </member>
112             <member>
113                 <link linkend="horner">horner</link>
114             </member>
115             <member>
116                 <link linkend="derivat">derivat</link>
117             </member>
118             <member>
119                 <link linkend="matrices">matrices</link>
120             </member>
121             <member>
122                 <link linkend="rational">rational</link>
123             </member>
124         </simplelist>
125     </refsection>
126 </refentry>