Polynomial Chapter

[Søren Hauberg]

Hi,
  Attached is some text/sectioning for the polynomial chapter of the 
manual. To be honest I didn't really have a lot to say on polynomial 
manipulations, so it's not that good what I've written. But I guess it's 
better than nothing :-)
  I couldn't really figure out what to do with the following functions
    * poly
    * polyout
    * polyreduce
so I threw them into a section called "Miscellaneous Functions", and 
didn't write anything about them. This is just an awful thing to do... 
but I couldn't really think of anything better :-(

Søren

P.S. The patch also removes a check from 'compan' that doesn't appear to 
be needed.

2007-08-28  Søren Hauberg  <address@hidden>

        * doc/interpreter/poly.txi: Sectioning and documentation.
        * doc/interpreter/octave.texi: Adapt to changes in poly.txi.
        * scripts/polynomial/polygcd.m: Better layout of example.
        * scripts/polynomial/compan.m: Remove unnecessary check.
        * scripts/polynomial/roots.m: Added example to help text.
        * scripts/polynomial/polyderiv.m: Change 'polyder' to
          'polyderiv' in help text.
        * scripts/polynomial/poly.m: Added example to help text.

Index: doc/interpreter/poly.txi
===================================================================
RCS file: /cvs/octave/doc/interpreter/poly.txi,v
retrieving revision 1.7
diff -u -r1.7 poly.txi
--- doc/interpreter/poly.txi    18 Jul 2007 17:03:11 -0000      1.7
+++ doc/interpreter/poly.txi    28 Aug 2007 21:19:27 -0000
@@ -6,26 +6,13 @@
 @chapter Polynomial Manipulations
 
 In Octave, a polynomial is represented by its coefficients (arranged
-in descending order).  For example, a vector
address@hidden
address@hidden iftex
address@hidden
- $c$
address@hidden ifinfo
-of length
address@hidden
address@hidden
- $N+1$
address@hidden tex
address@hidden
- @var{N+1}
address@hidden ifinfo
- corresponds to the following polynomial of order
+in descending order).  For example, a vector @var{c} of length
address@hidden corresponds to the following polynomial of order
 @iftex
 @tex
  $N$
 $$
- p (x) = c_1 x^N + ... + c_N x + c_{N+1}.
+ p (x) = c_1 x^N + \ldots + c_N x + c_{N+1}.
 $$
 @end tex
 @end iftex
@@ -37,40 +24,134 @@
 @end example
 @end ifinfo
 
address@hidden
+* Evaluating Polynomials::
+* Finding Roots::
+* Products of Polynomials::
+* Derivatives and Integrals::
+* Polynomial Interpolation::
+* Miscellaneous Functions::
address@hidden menu
+
address@hidden Evaluating Polynomials
address@hidden Evaluating Polynomials
+
+The value of a polynomial represented by the vector @var{c} can be evaluated
+at the point @var{x} very easily, as the following example shows.
+
address@hidden
+N = length(c)-1;
+val = dot( x.^(N:-1:0), c );
address@hidden example
+
address@hidden
+While the above example shows how easy it is to compute the value of a
+polynomial, it isn't the most stable algorithm.  With larger polynomials
+you should use more elegant algorithms, such as Horner's Method, which
+is exactly what the Octave function @code{polyval} does.
+
+In the case where @var{x} is a square matrix, the polynomial given by
address@hidden is still well-defined.  As when @var{x} is a scalar the obvious
+implementation is easily expressed in Octave, but also in this case
+more elegant algorithms perform better.  The @code{polyvalm} function
+provides such an algorithm.
+
address@hidden(polyval)
+
address@hidden(polyvalm)
+
address@hidden Finding Roots
address@hidden Finding Roots
+
+Octave can find the roots of a given polynomial.  This is done by computing
+the companion matrix of the polynomial (see the @code{compan} function
+for a definition), and then finding its eigenvalues.
+
address@hidden(roots)
+
 @DOCSTRING(compan)
 
address@hidden Products of Polynomials
address@hidden Products of Polynomials
+
 @DOCSTRING(conv)
 
 @DOCSTRING(deconv)
 
 @DOCSTRING(conv2)
 
address@hidden(poly)
address@hidden(polygcd)
+
address@hidden(residue)
+
address@hidden Derivatives and Integrals
address@hidden Derivatives and Integrals
+
+Octave comes with functions for computing the derivative and the integral
+of a polynomial.  The functions @code{polyderiv} and @code{polyinteg}
+both return new polynomials describing the result.  As an example we'll
+compute the definite integral of @math{p(x) = x^2 + 1} from 0 to 3.
+
address@hidden
+c = [1, 0, 1];
+integral = polyinteg(c);
+area = polyval(integral, 3) - polyval(integral, 0)
address@hidden 12
address@hidden example
 
 @DOCSTRING(polyderiv)
 
 @DOCSTRING(polyder)
 
address@hidden(polyinteg)
+
address@hidden Polynomial Interpolation
address@hidden Polynomial Interpolation
+
+Octave comes with good support for various kinds of interpolation,
+most of which are described in @ref{Interpolation}.  One simple alternative
+to the functions described in the aforementioned chapter, is to fit
+a single polynomial to some given data points.  To avoid a highly
+fluctuating polynomial, one most often wants to fit a low-order polynomial
+to data.  This usually means that it is necessary to fit the polynomial
+in a least-squares sense, which is what the @code{polyfit} function does.
+
 @DOCSTRING(polyfit)
 
address@hidden(polygcd)
+In situations where a single polynomial isn't good enough, a solution
+is to use several polynomials pieced together.  The function @code{mkpp}
+creates a piece-wise polynomial, @code{ppval} evaluates the function 
+created by @code{mkpp}, and @code{unmkpp} returns detailed information
+about the function.
+
+The following example shows how to combine two linear functions and a
+quadratic into one function.  Each of these functions are expressed
+on adjoined intervals.
 
address@hidden(polyinteg)
address@hidden
+x = [-2, -1, 1, 2];
+p = [ 0,  1, 0;
+      1, -2, 1;
+      0, -1, 1 ];
+pp = mkpp(x, p);
+xi = linspace(-2, 2, 50);
+yi = ppval(pp, xi);
+plot(xi, yi);
address@hidden example
 
address@hidden(polyreduce)
address@hidden(ppval)
 
address@hidden(polyval)
address@hidden(mkpp)
 
address@hidden(polyvalm)
address@hidden(unmkpp)
 
address@hidden(residue)
address@hidden Miscellaneous Functions
address@hidden Miscellaneous Functions
 
address@hidden(roots)
address@hidden(poly)
 
 @DOCSTRING(polyout)
 
address@hidden(ppval)
address@hidden(polyreduce)
 
address@hidden(mkpp)
 
address@hidden(unmkpp)
Index: doc/interpreter/octave.texi
===================================================================
RCS file: /cvs/octave/doc/interpreter/octave.texi,v
retrieving revision 1.64
diff -u -r1.64 octave.texi
--- doc/interpreter/octave.texi 25 Aug 2007 00:35:33 -0000      1.64
+++ doc/interpreter/octave.texi 28 Aug 2007 21:19:27 -0000
@@ -445,6 +445,15 @@
 
 * Set Operations::
 
+Polynomial Manipulations
+
+* Evaluating Polynomials::
+* Finding Roots::
+* Products of Polynomials::
+* Derivatives and Integrals::
+* Polynomial Interpolation::
+* Miscellaneous Functions::
+
 Interpolation
 
 * One-dimensional Interpolation::
Index: scripts/polynomial/polygcd.m
===================================================================
RCS file: /cvs/octave/scripts/polynomial/polygcd.m,v
retrieving revision 1.7
diff -u -r1.7 polygcd.m
--- scripts/polynomial/polygcd.m        10 Oct 2006 16:10:28 -0000      1.7
+++ scripts/polynomial/polygcd.m        28 Aug 2007 21:19:27 -0000
@@ -31,7 +31,9 @@
 ## Example
 ## @example
 ## polygcd (poly(1:8), poly(3:12)) - poly(3:8)
-##          deconv (poly(1:8), polygcd (poly(1:8), poly(3:12))) - poly(1:2)
+## @result{} [ 0, 0, 0, 0, 0, 0, 0 ]
+## deconv (poly(1:8), polygcd (poly(1:8), poly(3:12))) - poly(1:2)
+## @result{} [ 0, 0, 0 ]
 ## @end example
 ## @seealso{poly, polyinteg, polyderiv, polyreduce, roots, conv, deconv,
 ## residue, filter, polyval, and polyvalm}
Index: scripts/polynomial/compan.m
===================================================================
RCS file: /cvs/octave/scripts/polynomial/compan.m,v
retrieving revision 1.21
diff -u -r1.21 compan.m
--- scripts/polynomial/compan.m 10 Oct 2006 16:10:28 -0000      1.21
+++ scripts/polynomial/compan.m 28 Aug 2007 21:19:27 -0000
@@ -35,7 +35,7 @@
 ## $$
 ## @end tex
 ## @end iftex
-## @ifinfo
+## @ifnottex
 ##
 ## @smallexample
 ##      _                                                        _
@@ -47,7 +47,7 @@
 ##     |       .            .           .    .             .      |
 ##     |_      0            0      ...       1             0     _|
 ## @end smallexample
-## @end ifinfo
+## @end ifnottex
 ##
 ## The eigenvalues of the companion matrix are equal to the roots of the
 ## polynomial.
@@ -69,12 +69,6 @@
     error ("compan: expecting a vector argument");
   endif
 
-  ## Ensure that c is a row vector.
-
-  if (rows (c) > 1)
-    c = c.';
-  endif
-
   n = length (c);
 
   if (n == 1)
Index: scripts/polynomial/roots.m
===================================================================
RCS file: /cvs/octave/scripts/polynomial/roots.m,v
retrieving revision 1.23
diff -u -r1.23 roots.m
--- scripts/polynomial/roots.m  1 Mar 2007 15:39:30 -0000       1.23
+++ scripts/polynomial/roots.m  28 Aug 2007 21:19:27 -0000
@@ -29,12 +29,50 @@
 ## $$
 ## @end tex
 ## @end iftex
-## @ifinfo
+## @ifnottex
 ##
 ## @example
 ## v(1) * z^(N-1) + ... + v(N-1) * z + v(N)
 ## @end example
-## @end ifinfo
+## @end ifnottex
+##
+## As an example, the following code finds the roots of the quadratic
+## polynomial
+## @iftex
+## @tex
+## $$ p(x) = x^2 - 5. $$
+## @end tex
+## @end iftex
+## @ifnottex
+## @example
+## p(x) = x^2 - 5.
+## @end example
+## @end ifnottex
+## @example
+## c = [1, 0, -5];
+## roots(c)
+## @result{}  2.2361
+## @result{} -2.2361
+## @end example
+## Note that the true result is
+## @iftex
+## @tex
+## $\pm \sqrt{5}$
+## @end tex
+## @end iftex
+## @ifnottex
+## @math{+/- sqrt(5)}
+## @end ifnottex
+## which is roughly
+## @iftex
+## @tex
+## $\pm 2.2361$.
+## @end tex
+## @end iftex
+## @ifnottex
+## @math{+/- 2.2361}.
+## @end ifnottex
+## @seealso{compan}
 ## @end deftypefn
 
 ## Author: KH <address@hidden>
Index: scripts/polynomial/polyderiv.m
===================================================================
RCS file: /cvs/octave/scripts/polynomial/polyderiv.m,v
retrieving revision 1.24
diff -u -r1.24 polyderiv.m
--- scripts/polynomial/polyderiv.m      10 Oct 2006 16:10:28 -0000      1.24
+++ scripts/polynomial/polyderiv.m      28 Aug 2007 21:19:27 -0000
@@ -19,8 +19,8 @@
 
 ## -*- texinfo -*-
 ## @deftypefn {Function File} {} polyderiv (@var{c})
-## @deftypefnx {Function File} address@hidden =} polyder (@var{b}, @var{a})
-## @deftypefnx {Function File} address@hidden, @var{r}] =} polyder (@var{b}, 
@var{a})
+## @deftypefnx {Function File} address@hidden =} polyderiv (@var{b}, @var{a})
+## @deftypefnx {Function File} address@hidden, @var{r}] =} polyderiv (@var{b}, 
@var{a})
 ## Return the coefficients of the derivative of the polynomial whose
 ## coefficients are given by vector @var{c}.  If a pair of polynomials
 ## is given @var{b} and @var{a}, the derivative of the product is
Index: scripts/polynomial/poly.m
===================================================================
RCS file: /cvs/octave/scripts/polynomial/poly.m,v
retrieving revision 1.18
diff -u -r1.18 poly.m
--- scripts/polynomial/poly.m   10 Oct 2006 16:10:28 -0000      1.18
+++ scripts/polynomial/poly.m   28 Aug 2007 21:19:27 -0000
@@ -21,9 +21,24 @@
 ## @deftypefn {Function File} {} poly (@var{a})
 ## If @var{a} is a square @address@hidden matrix, @code{poly (@var{a})}
 ## is the row vector of the coefficients of @code{det (z * eye (N) - a)},
-## the characteristic polynomial of @var{a}.  If @var{x} is a vector,
-## @code{poly (@var{x})} is a vector of coefficients of the polynomial
-## whose roots are the elements of @var{x}.
+## the characteristic polynomial of @var{a}.  As an example we can use
+## this to find the eigenvalues of @var{a} as the roots of @code{poly 
(@var{a})}.
+## @example
+## roots(poly(eye(3)))
+## @result{} 1.00000 + 0.00000i
+## @result{} 1.00000 - 0.00000i
+## @result{} 1.00000 + 0.00000i
+## @end example
+## In real-life examples you should, however, use the @code{eig} function
+## for computing eigenvalues.
+##
+## If @var{x} is a vector, @code{poly (@var{x})} is a vector of coefficients
+## of the polynomial whose roots are the elements of @var{x}.  That is,
+## of @var{c} is a polynomial, then the elements of 
+## @address@hidden = roots (poly (@var{c}))} are contained in @var{c}.
+## The vectors @var{c} and @var{d} are, however, not equal due to sorting
+## and numerical errors.
+## @seealso{eig, roots}
 ## @end deftypefn
 
 ## Author: KH <address@hidden>