← Back to branch summary

~ubuntu-branches/ubuntu/raring/scilab/raring-proposed

« back to all changes in this revision

Viewing changes to modules/polynomials/help/en_US/roots.xml

  • Committer: Package Import Robot
  • Author(s): Sylvestre Ledru
  • Date: 2012-08-30 14:42:38 UTC
  • mfrom: (1.4.7)
  • Revision ID: package-import@ubuntu.com-20120830144238-c1y2og7dbm7m9nig
Tags: 5.4.0-beta-3-1~exp1
* New upstream release
* Update the scirenderer dep
* Get ride of libjhdf5-java dependency

Show diffs side-by-side

added added

removed removed

Lines of Context:
modules/polynomials/help/en_US/roots.xml
12
12
 *
13
13
 -->
14
14
<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" version="5.0-subset Scilab" xml:id="roots" xml:lang="en">
15
 
  <refnamediv>
16
 
    <refname>roots</refname>
17
 
    <refpurpose>roots of polynomials</refpurpose>
18
 
  </refnamediv>
19
 
  <refsynopsisdiv>
20
 
    <title>Calling Sequence</title>
21
 
    <synopsis>
22
 
      x=roots(p)
23
 
      x=roots(p,algo)
24
 
    </synopsis>
25
 
  </refsynopsisdiv>
26
 
  <refsection>
27
 
    <title>Arguments</title>
28
 
    <variablelist>
29
 
      <varlistentry>
30
 
        <term>p</term>
31
 
        <listitem>
32
 
          <para>
33
 
            a polynomial with real or complex coefficients, or 
34
 
            a m-by-1 or 1-by-m matrix of doubles, the polynomial coefficients in decreasing degree order.
35
 
          </para>
36
 
        </listitem>
37
 
      </varlistentry>
38
 
      <varlistentry>
39
 
        <term>algo</term>
40
 
        <listitem>
41
 
          <para>
42
 
            a string, the algorithm to be used (default algo="f").
43
 
            If algo="e", then the eigenvalues of the companion matrix are returned.
44
 
            If algo="f", then the Jenkins-Traub method is used (if the polynomial is real and 
45
 
            has degree lower than 100).
46
 
            If algo="f" and the polynomial is complex, then an error is generated.
47
 
            If algo="f" and the polynomial has degree greater than 100, then an error is generated.
48
 
          </para>
49
 
        </listitem>
50
 
      </varlistentry>
51
 
    </variablelist>
52
 
  </refsection>
53
 
  <refsection>
54
 
    <title>Description</title>
55
 
    <para>
56
 
      This function returns in the complex vector
57
 
      <literal>x</literal> the roots of the polynomial <literal>p</literal>. 
58
 
    </para>
59
 
    <para>
60
 
      The "e" option corresponds to method based on the eigenvalues of the 
61
 
      companion matrix. 
62
 
    </para>
63
 
    <para>
64
 
      The "f" option corresponds to the fast RPOLY algorithm, based on
65
 
      Jenkins-Traub method. 
66
 
    </para>
67
 
    <para>
68
 
      For real polynomials of degree &lt;=100, users may consider the "f" option, 
69
 
      which might be faster in some cases. 
70
 
      On the other hand, some specific polynomials are known to be able to 
71
 
      make this option to fail.
72
 
    </para>
73
 
  </refsection>
74
 
  <refsection>
75
 
    <title>Examples</title>
76
 
    <para>
77
 
      In the following examples, we compute roots of polynomials.
78
 
    </para>
79
 
    <programlisting role="example"><![CDATA[
 
15
    <refnamediv>
 
16
        <refname>roots</refname>
 
17
        <refpurpose>roots of polynomials</refpurpose>
 
18
    </refnamediv>
 
19
    <refsynopsisdiv>
 
20
        <title>Calling Sequence</title>
 
21
        <synopsis>
 
22
            x=roots(p)
 
23
            x=roots(p,algo)
 
24
        </synopsis>
 
25
    </refsynopsisdiv>
 
26
    <refsection>
 
27
        <title>Arguments</title>
 
28
        <variablelist>
 
29
            <varlistentry>
 
30
                <term>p</term>
 
31
                <listitem>
 
32
                    <para>
 
33
                        a polynomial with real or complex coefficients, or 
 
34
                        a m-by-1 or 1-by-m matrix of doubles, the polynomial coefficients in decreasing degree order.
 
35
                    </para>
 
36
                </listitem>
 
37
            </varlistentry>
 
38
            <varlistentry>
 
39
                <term>algo</term>
 
40
                <listitem>
 
41
                    <para>
 
42
                        a string, the algorithm to be used (default algo="f").
 
43
                        If algo="e", then the eigenvalues of the companion matrix are returned.
 
44
                        If algo="f", then the Jenkins-Traub method is used (if the polynomial is real and 
 
45
                        has degree lower than 100).
 
46
                        If algo="f" and the polynomial is complex, then an error is generated.
 
47
                        If algo="f" and the polynomial has degree greater than 100, then an error is generated.
 
48
                    </para>
 
49
                </listitem>
 
50
            </varlistentry>
 
51
        </variablelist>
 
52
    </refsection>
 
53
    <refsection>
 
54
        <title>Description</title>
 
55
        <para>
 
56
            This function returns in the complex vector
 
57
            <literal>x</literal> the roots of the polynomial <literal>p</literal>. 
 
58
        </para>
 
59
        <para>
 
60
            The "e" option corresponds to method based on the eigenvalues of the 
 
61
            companion matrix. 
 
62
        </para>
 
63
        <para>
 
64
            The "f" option corresponds to the fast RPOLY algorithm, based on
 
65
            Jenkins-Traub method. 
 
66
        </para>
 
67
        <para>
 
68
            For real polynomials of degree &lt;=100, users may consider the "f" option, 
 
69
            which might be faster in some cases. 
 
70
            On the other hand, some specific polynomials are known to be able to 
 
71
            make this option to fail.
 
72
        </para>
 
73
    </refsection>
 
74
    <refsection>
 
75
        <title>Examples</title>
 
76
        <para>
 
77
            In the following examples, we compute roots of polynomials.
 
78
        </para>
 
79
        <programlisting role="example"><![CDATA[
80
80
// Roots given a real polynomial
81
81
p = poly([1 2 3],"x")
82
82
roots(p)
92
92
roots(p)
93
93
spec(A)
94
94
 ]]></programlisting>
95
 
    <para>
96
 
      The polynomial representation can have a significant 
97
 
      impact on the roots. 
98
 
      In the following example, suggested by Wilkinson in the 60s and presented by Moler, 
99
 
      we consider a diagonal matrix with diagonal entries equal to 1, 2, ..., 20. 
100
 
      The eigenvalues are obviously equal to 1, 2, ..., 20. 
101
 
      If we compute the associated characteristic polynomial and compute its roots, 
102
 
      we can see that the eigenvalues are significantly different from the expected 
103
 
      ones. 
104
 
      This implies that just representing the coefficients as IEEE doubles changes the 
105
 
      roots. 
106
 
    </para>
107
 
    <programlisting role="example"><![CDATA[
 
95
        <para>
 
96
            The polynomial representation can have a significant 
 
97
            impact on the roots. 
 
98
            In the following example, suggested by Wilkinson in the 60s and presented by Moler, 
 
99
            we consider a diagonal matrix with diagonal entries equal to 1, 2, ..., 20. 
 
100
            The eigenvalues are obviously equal to 1, 2, ..., 20. 
 
101
            If we compute the associated characteristic polynomial and compute its roots, 
 
102
            we can see that the eigenvalues are significantly different from the expected 
 
103
            ones. 
 
104
            This implies that just representing the coefficients as IEEE doubles changes the 
 
105
            roots. 
 
106
        </para>
 
107
        <programlisting role="example"><![CDATA[
108
108
A = diag(1:20);
109
109
p = poly(A,'x')
110
110
roots(p)
111
111
 ]]></programlisting>
112
 
    <para>
113
 
      The "f" option produces an error if the polynomial is complex or 
114
 
      if the degree is greater than 100.
115
 
    </para>
116
 
    <programlisting role="example"><![CDATA[
 
112
        <para>
 
113
            The "f" option produces an error if the polynomial is complex or 
 
114
            if the degree is greater than 100.
 
115
        </para>
 
116
        <programlisting role="example"><![CDATA[
117
117
 // The following case produces an error.
118
118
 p = %i+%s;
119
119
 roots(p,"f")
121
121
 p = ones(101,1);
122
122
 roots(p,"f")
123
123
 ]]></programlisting>
124
 
  </refsection>
125
 
  <refsection role="see also">
126
 
    <title>See Also</title>
127
 
    <simplelist type="inline">
128
 
      <member>
129
 
        <link linkend="poly">poly</link>
130
 
      </member>
131
 
      <member>
132
 
        <link linkend="spec">spec</link>
133
 
      </member>
134
 
      <member>
135
 
        <link linkend="companion">companion</link>
136
 
      </member>
137
 
    </simplelist>
138
 
  </refsection>
139
 
  <refsection>
140
 
    <title>References</title>
141
 
    <para>
142
 
      The RPOLY algorithm is described in "Algorithm 493: Zeros of a Real
143
 
      Polynomial", ACM TOMS Volume 1, Issue 2 (June 1975), pp. 178-189
144
 
    </para>
145
 
    <para>Jenkins, M. A. and Traub, J. F. (1970), A Three-Stage Algorithm for 
146
 
      Real Polynomials Using Quadratic Iteration, SIAM J. Numer. Anal., 7(1970), 545-566.
147
 
    </para>
148
 
    <para>Jenkins, M. A. and Traub, J. F. (1970), Principles for Testing Polynomial Zerofinding Programs.
149
 
      ACM TOMS 1, 1 (March 1975), pp. 26-34
150
 
    </para>
151
 
  </refsection>
152
 
  <refsection>
153
 
    <title>Used Functions</title>
154
 
    <para>The rpoly.f source codes can be found in the directory
155
 
      SCI/modules/polynomials/src/fortran of a Scilab source distribution. In the case where the
156
 
      companion matrix is used, the eigenvalue computation is perfomed using
157
 
      DGEEV and ZGEEV LAPACK codes.
158
 
    </para>
159
 
  </refsection>
 
124
    </refsection>
 
125
    <refsection role="see also">
 
126
        <title>See Also</title>
 
127
        <simplelist type="inline">
 
128
            <member>
 
129
                <link linkend="poly">poly</link>
 
130
            </member>
 
131
            <member>
 
132
                <link linkend="spec">spec</link>
 
133
            </member>
 
134
            <member>
 
135
                <link linkend="companion">companion</link>
 
136
            </member>
 
137
        </simplelist>
 
138
    </refsection>
 
139
    <refsection>
 
140
        <title>References</title>
 
141
        <para>
 
142
            The RPOLY algorithm is described in "Algorithm 493: Zeros of a Real
 
143
            Polynomial", ACM TOMS Volume 1, Issue 2 (June 1975), pp. 178-189
 
144
        </para>
 
145
        <para>Jenkins, M. A. and Traub, J. F. (1970), A Three-Stage Algorithm for 
 
146
            Real Polynomials Using Quadratic Iteration, SIAM J. Numer. Anal., 7(1970), 545-566.
 
147
        </para>
 
148
        <para>Jenkins, M. A. and Traub, J. F. (1970), Principles for Testing Polynomial Zerofinding Programs.
 
149
            ACM TOMS 1, 1 (March 1975), pp. 26-34
 
150
        </para>
 
151
    </refsection>
 
152
    <refsection>
 
153
        <title>Used Functions</title>
 
154
        <para>The rpoly.f source codes can be found in the directory
 
155
            SCI/modules/polynomials/src/fortran of a Scilab source distribution. In the case where the
 
156
            companion matrix is used, the eigenvalue computation is perfomed using
 
157
            DGEEV and ZGEEV LAPACK codes.
 
158
        </para>
 
159
    </refsection>
160
160
</refentry>