@c DO NOT EDIT!  Generated automatically by munge-texi.

@c Copyright (C) 1996-2011 John W. Eaton
@c
@c This file is part of Octave.
@c
@c Octave is free software; you can redistribute it and/or modify it
@c under the terms of the GNU General Public License as published by the
@c Free Software Foundation; either version 3 of the License, or (at
@c your option) any later version.
@c 
@c Octave is distributed in the hope that it will be useful, but WITHOUT
@c ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
@c FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
@c for more details.
@c 
@c You should have received a copy of the GNU General Public License
@c along with Octave; see the file COPYING.  If not, see
@c <http://www.gnu.org/licenses/>.

@node Polynomial Manipulations
@chapter Polynomial Manipulations

In Octave, a polynomial is represented by its coefficients (arranged
in descending order).  For example, a vector @var{c} of length
@math{N+1} corresponds to the following polynomial of order
@tex
 $N$
$$
 p (x) = c_1 x^N + \ldots + c_N x + c_{N+1}.
$$
@end tex
@ifnottex
 @var{N}

@example
p(x) = @var{c}(1) x^@var{N} + @dots{} + @var{c}(@var{N}) x + @var{c}(@var{N}+1).
@end example

@end ifnottex

@menu
* Evaluating Polynomials::
* Finding Roots::
* Products of Polynomials::
* Derivatives / Integrals / Transforms::
* Polynomial Interpolation::
* Miscellaneous Functions::
@end menu

@node Evaluating Polynomials
@section 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:

@example
@group
N = length(c)-1;
val = dot( x.^(N:-1:0), c );
@end group
@end example

@noindent
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
@var{c} 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.

@c polyval scripts/polynomial/polyval.m
@anchor{doc-polyval}
@deftypefn  {Function File} {@var{y} =} polyval (@var{p}, @var{x})
@deftypefnx {Function File} {@var{y} =} polyval (@var{p}, @var{x}, [], @var{mu})
Evaluate the polynomial @var{p} at the specified values of @var{x}.  When
@var{mu} is present evaluate the polynomial for
(@var{x}-@var{mu}(1))/@var{mu}(2).
If @var{x} is a vector or matrix, the polynomial is evaluated for each of
the elements of @var{x}.
@deftypefnx {Function File} {[@var{y}, @var{dy}] =} polyval (@var{p}, @var{x}, @var{s})
@deftypefnx {Function File} {[@var{y}, @var{dy}] =} polyval (@var{p}, @var{x}, @var{s}, @var{mu})
In addition to evaluating the polynomial, the second output
represents the prediction interval, @var{y} +/- @var{dy}, which
contains at least 50% of the future predictions.  To calculate the
prediction interval, the structured variable @var{s}, originating
form `polyfit', must be present.
@seealso{@ref{doc-polyfit,,polyfit}, @ref{doc-polyvalm,,polyvalm}, @ref{doc-poly,,poly}, @ref{doc-roots,,roots}, @ref{doc-conv,,conv}, @ref{doc-deconv,,deconv}, @ref{doc-residue,,residue}, @ref{doc-filter,,filter}, @ref{doc-polyderiv,,polyderiv}, @ref{doc-polyint,,polyint}}
@end deftypefn


@c polyvalm scripts/polynomial/polyvalm.m
@anchor{doc-polyvalm}
@deftypefn {Function File} {} polyvalm (@var{c}, @var{x})
Evaluate a polynomial in the matrix sense.

@code{polyvalm (@var{c}, @var{x})} will evaluate the polynomial in the
matrix sense, i.e., matrix multiplication is used instead of element by
element multiplication as is used in polyval.

The argument @var{x} must be a square matrix.
@seealso{@ref{doc-polyval,,polyval}, @ref{doc-poly,,poly}, @ref{doc-roots,,roots}, @ref{doc-conv,,conv}, @ref{doc-deconv,,deconv}, @ref{doc-residue,,residue}, @ref{doc-filter,,filter}, @ref{doc-polyderiv,,polyderiv}, @ref{doc-polyint,,polyint}}
@end deftypefn


@node Finding Roots
@section 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.

@c roots scripts/polynomial/roots.m
@anchor{doc-roots}
@deftypefn {Function File} {} roots (@var{v})

For a vector @var{v} with @math{N} components, return
the roots of the polynomial
@tex
$$
v_1 z^{N-1} + \cdots + v_{N-1} z + v_N.
$$
@end tex
@ifnottex

@example
v(1) * z^(N-1) + @dots{} + v(N-1) * z + v(N)
@end example

@end ifnottex

As an example, the following code finds the roots of the quadratic
polynomial
@tex
$$ p(x) = x^2 - 5. $$
@end tex
@ifnottex

@example
p(x) = x^2 - 5.
@end example

@end ifnottex

@example
@group
c = [1, 0, -5];
roots(c)
@result{}  2.2361
@result{} -2.2361
@end group
@end example

Note that the true result is
@tex
$\pm \sqrt{5}$
@end tex
@ifnottex
@math{+/- sqrt(5)}
@end ifnottex
which is roughly
@tex
$\pm 2.2361$.
@end tex
@ifnottex
@math{+/- 2.2361}.
@end ifnottex
@seealso{@ref{doc-compan,,compan}}
@end deftypefn


@c compan scripts/polynomial/compan.m
@anchor{doc-compan}
@deftypefn {Function File} {} compan (@var{c})
Compute the companion matrix corresponding to polynomial coefficient
vector @var{c}.

The companion matrix is
@tex
$$
A = \left[\matrix{
 -c_2/c_1 & -c_3/c_1 & \cdots & -c_N/c_1 & -c_{N+1}/c_1\cr
     1    &     0    & \cdots &     0    &         0   \cr
     0    &     1    & \cdots &     0    &         0   \cr
  \vdots  &   \vdots & \ddots &  \vdots  &      \vdots \cr
     0    &     0    & \cdots &     1    &         0}\right].
$$
@end tex
@ifnottex
@c Set example in small font to prevent overfull line

@smallexample
@group
     _                                                        _
    |  -c(2)/c(1)   -c(3)/c(1)  @dots{}  -c(N)/c(1)  -c(N+1)/c(1)  |
    |       1            0      @dots{}       0             0      |
    |       0            1      @dots{}       0             0      |
A = |       .            .      .         .             .      |
    |       .            .       .        .             .      |
    |       .            .        .       .             .      |
    |_      0            0      @dots{}       1             0     _|
@end group
@end smallexample

@end ifnottex
The eigenvalues of the companion matrix are equal to the roots of the
polynomial.
@seealso{@ref{doc-poly,,poly}, @ref{doc-roots,,roots}, @ref{doc-residue,,residue}, @ref{doc-conv,,conv}, @ref{doc-deconv,,deconv}, @ref{doc-polyval,,polyval}, @ref{doc-polyderiv,,polyderiv}, @ref{doc-polyint,,polyint}}
@end deftypefn


@c mpoles scripts/polynomial/mpoles.m
@anchor{doc-mpoles}
@deftypefn  {Function File} {[@var{multp}, @var{indx}] =} mpoles (@var{p})
@deftypefnx {Function File} {[@var{multp}, @var{indx}] =} mpoles (@var{p}, @var{tol})
@deftypefnx {Function File} {[@var{multp}, @var{indx}] =} mpoles (@var{p}, @var{tol}, @var{reorder})
Identify unique poles in @var{p} and associates their multiplicity,
ordering them from largest to smallest.

If the relative difference of the poles is less than @var{tol}, then
they are considered to be multiples.  The default value for @var{tol}
is 0.001.

If the optional parameter @var{reorder} is zero, poles are not sorted.

The value @var{multp} is a vector specifying the multiplicity of the
poles.  @var{multp}(:) refers to multiplicity of @var{p}(@var{indx}(:)).

For example:

@example
@group
p = [2 3 1 1 2];
[m, n] = mpoles(p);
  @result{} m = [1; 1; 2; 1; 2]
  @result{} n = [2; 5; 1; 4; 3]
  @result{} p(n) = [3, 2, 2, 1, 1]
@end group
@end example

@seealso{@ref{doc-poly,,poly}, @ref{doc-roots,,roots}, @ref{doc-conv,,conv}, @ref{doc-deconv,,deconv}, @ref{doc-polyval,,polyval}, @ref{doc-polyderiv,,polyderiv}, @ref{doc-polyint,,polyint}, @ref{doc-residue,,residue}}
@end deftypefn


@node Products of Polynomials
@section Products of Polynomials

@c conv scripts/polynomial/conv.m
@anchor{doc-conv}
@deftypefn  {Function File} {} conv (@var{a}, @var{b})
@deftypefnx {Function File} {} conv (@var{a}, @var{b}, @var{shape})
Convolve two vectors.

@code{c = conv (@var{a}, @var{b})} returns a vector of length equal to
@code{length (@var{a}) + length (@var{b}) - 1}.
If @var{a} and @var{b} are the coefficient vectors of two polynomials, the
returned value is the coefficient vector of the product polynomial.

The optional @var{shape} argument may be

@table @asis
@item @var{shape} = "full"
Return the full convolution.  (default)

@item @var{shape} = "same"
Return the central part of the convolution with the same size as @var{a}.
@end table

@seealso{@ref{doc-deconv,,deconv}, @ref{doc-fftconv,,fftconv}, @ref{doc-conv2,,conv2}, @ref{doc-poly,,poly}}
@end deftypefn


@c convn src/DLD-FUNCTIONS/conv2.cc
@anchor{doc-convn}
@deftypefn {Loadable Function} {@var{C} =} convn (@var{A}, @var{B}, @var{shape})
Return the n-D convolution of @var{A} and @var{B} where the size
of @var{C} is given by

@table @asis
@item @var{shape} = "full"
Return the full convolution.

@item @var{shape} = "same"
Return central part of the convolution with the same size as @var{A}.

@item @var{shape} = "valid"
Return only the parts which do not include zero-padded edges.
@end table

By default @var{shape} is @samp{"full"}.
@seealso{@ref{doc-conv2,,conv2}, @ref{doc-conv,,conv}}
@end deftypefn


@c deconv scripts/polynomial/deconv.m
@anchor{doc-deconv}
@deftypefn {Function File} {} deconv (@var{y}, @var{a})
Deconvolve two vectors.

@code{[b, r] = deconv (y, a)} solves for @var{b} and @var{r} such that
@code{y = conv (a, b) + r}.

If @var{y} and @var{a} are polynomial coefficient vectors, @var{b} will
contain the coefficients of the polynomial quotient and @var{r} will be
a remainder polynomial of lowest order.
@seealso{@ref{doc-conv,,conv}, @ref{doc-poly,,poly}, @ref{doc-roots,,roots}, @ref{doc-residue,,residue}, @ref{doc-polyval,,polyval}, @ref{doc-polyderiv,,polyderiv}, @ref{doc-polyint,,polyint}}
@end deftypefn


@c conv2 src/DLD-FUNCTIONS/conv2.cc
@anchor{doc-conv2}
@deftypefn  {Loadable Function} {} conv2 (@var{A}, @var{B})
@deftypefnx {Loadable Function} {} conv2 (@var{v1}, @var{v2}, @var{m})
@deftypefnx {Loadable Function} {} conv2 (@dots{}, @var{shape})
Return the 2-D convolution of @var{A} and @var{B}.  The size of the result
is determined by the optional @var{shape} argument which takes the following
values

@table @asis
@item @var{shape} = "full"
Return the full convolution.  (default)

@item @var{shape} = "same"
Return the central part of the convolution with the same size as @var{A}.

@item @var{shape} = "valid"
Return only the parts which do not include zero-padded edges.
@end table

When the third argument is a matrix, return the convolution of the matrix
@var{m} by the vector @var{v1} in the column direction and by the vector
@var{v2} in the row direction
@seealso{@ref{doc-conv,,conv}, @ref{doc-convn,,convn}}
@end deftypefn


@c polygcd scripts/polynomial/polygcd.m
@anchor{doc-polygcd}
@deftypefn  {Function File} {@var{q} =} polygcd (@var{b}, @var{a})
@deftypefnx {Function File} {@var{q} =} polygcd (@var{b}, @var{a}, @var{tol})

Find the greatest common divisor of two polynomials.  This is equivalent
to the polynomial found by multiplying together all the common roots.
Together with deconv, you can reduce a ratio of two polynomials.
Tolerance defaults to @code{sqrt(eps)}.

Note that this is a numerically unstable algorithm, and should not be used
on large polynomials.

Example:

@example
@group
polygcd (poly(1:8), poly(3:12)) - poly(3:8)
@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 group
@end example
@seealso{@ref{doc-poly,,poly}, @ref{doc-polyint,,polyint}, @ref{doc-polyderiv,,polyderiv}, @ref{doc-polyreduce,,polyreduce}, @ref{doc-roots,,roots}, @ref{doc-conv,,conv}, @ref{doc-deconv,,deconv}, @ref{doc-residue,,residue}, @ref{doc-filter,,filter}, @ref{doc-polyval,,polyval}, @ref{doc-polyvalm,,polyvalm}}
@end deftypefn


@c residue scripts/polynomial/residue.m
@anchor{doc-residue}
@deftypefn {Function File} {[@var{r}, @var{p}, @var{k}, @var{e}] =} residue (@var{b}, @var{a})
@deftypefnx {Function File} {[@var{b}, @var{a}] =} residue (@var{r}, @var{p}, @var{k})
@deftypefnx {Function File} {[@var{b}, @var{a}] =} residue (@var{r}, @var{p}, @var{k}, @var{e})
The first calling form computes the partial fraction expansion for the
quotient of the polynomials, @var{b} and @var{a}.
@tex
$$
{B(s)\over A(s)} = \sum_{m=1}^M {r_m\over (s-p_m)^e_m}
  + \sum_{i=1}^N k_i s^{N-i}.
$$
@end tex
@ifnottex

@example
@group
 B(s)    M       r(m)         N
 ---- = SUM -------------  + SUM k(i)*s^(N-i)
 A(s)   m=1 (s-p(m))^e(m)    i=1
@end group
@end example

@end ifnottex
@noindent
where @math{M} is the number of poles (the length of the @var{r},
@var{p}, and @var{e}), the @var{k} vector is a polynomial of order @math{N-1}
representing the direct contribution, and the @var{e} vector specifies
the multiplicity of the m-th residue's pole.

For example,

@example
@group
b = [1, 1, 1];
a = [1, -5, 8, -4];
[r, p, k, e] = residue (b, a);
     @result{} r = [-2; 7; 3]
     @result{} p = [2; 2; 1]
     @result{} k = [](0x0)
     @result{} e = [1; 2; 1]
@end group
@end example

@noindent
which represents the following partial fraction expansion
@tex
$$
{s^2+s+1\over s^3-5s^2+8s-4} = {-2\over s-2} + {7\over (s-2)^2} + {3\over s-1}
$$
@end tex
@ifnottex

@example
@group
        s^2 + s + 1       -2        7        3
   ------------------- = ----- + ------- + -----
   s^3 - 5s^2 + 8s - 4   (s-2)   (s-2)^2   (s-1)
@end group
@end example

@end ifnottex

The second calling form performs the inverse operation and computes
the reconstituted quotient of polynomials, @var{b}(s)/@var{a}(s),
from the partial fraction expansion; represented by the residues,
poles, and a direct polynomial specified by @var{r}, @var{p} and
@var{k}, and the pole multiplicity @var{e}.

If the multiplicity, @var{e}, is not explicitly specified the multiplicity is
determined by the function @code{mpoles}.

For example:

@example
@group
r = [-2; 7; 3];
p = [2; 2; 1];
k = [1, 0];
[b, a] = residue (r, p, k);
     @result{} b = [1, -5, 9, -3, 1]
     @result{} a = [1, -5, 8, -4]

where mpoles is used to determine e = [1; 2; 1]

@end group
@end example

Alternatively the multiplicity may be defined explicitly, for example,

@example
@group
r = [7; 3; -2];
p = [2; 1; 2];
k = [1, 0];
e = [2; 1; 1];
[b, a] = residue (r, p, k, e);
     @result{} b = [1, -5, 9, -3, 1]
     @result{} a = [1, -5, 8, -4]
@end group
@end example

@noindent
which represents the following partial fraction expansion
@tex
$$
{-2\over s-2} + {7\over (s-2)^2} + {3\over s-1} + s = {s^4-5s^3+9s^2-3s+1\over s^3-5s^2+8s-4}
$$
@end tex
@ifnottex

@example
@group
    -2        7        3         s^4 - 5s^3 + 9s^2 - 3s + 1
   ----- + ------- + ----- + s = --------------------------
   (s-2)   (s-2)^2   (s-1)          s^3 - 5s^2 + 8s - 4
@end group
@end example

@end ifnottex
@seealso{@ref{doc-poly,,poly}, @ref{doc-roots,,roots}, @ref{doc-conv,,conv}, @ref{doc-deconv,,deconv}, @ref{doc-mpoles,,mpoles}, @ref{doc-polyval,,polyval}, @ref{doc-polyderiv,,polyderiv}, @ref{doc-polyint,,polyint}}
@end deftypefn


@node Derivatives / Integrals / Transforms
@section Derivatives / Integrals / Transforms

Octave comes with functions for computing the derivative and the integral
of a polynomial.  The functions @code{polyderiv} and @code{polyint}
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.

@example
@group
c = [1, 0, 1];
integral = polyint(c);
area = polyval(integral, 3) - polyval(integral, 0)
@result{} 12
@end group
@end example

@c polyderiv scripts/polynomial/polyderiv.m
@anchor{doc-polyderiv}
@deftypefn  {Function File} {} polyderiv (@var{p})
@deftypefnx {Function File} {[@var{k}] =} polyderiv (@var{a}, @var{b})
@deftypefnx {Function File} {[@var{q}, @var{d}] =} polyderiv (@var{b}, @var{a})
Return the coefficients of the derivative of the polynomial whose
coefficients are given by the vector @var{p}.  If a pair of polynomials
is given, return the derivative of the product @math{@var{a}*@var{b}}.
If two inputs and two outputs are given, return the derivative of the
polynomial quotient @math{@var{b}/@var{a}}.  The quotient numerator is
in @var{q} and the denominator in @var{d}.
@seealso{@ref{doc-poly,,poly}, @ref{doc-polyint,,polyint}, @ref{doc-polyreduce,,polyreduce}, @ref{doc-roots,,roots}, @ref{doc-conv,,conv}, @ref{doc-deconv,,deconv}, @ref{doc-residue,,residue}, @ref{doc-filter,,filter}, @ref{doc-polygcd,,polygcd}, @ref{doc-polyval,,polyval}, @ref{doc-polyvalm,,polyvalm}}
@end deftypefn


@c polyder scripts/polynomial/polyder.m
@anchor{doc-polyder}
@deftypefn  {Function File} {} polyderiv (@var{p})
@deftypefnx {Function File} {[@var{k}] =} polyderiv (@var{a}, @var{b})
@deftypefnx {Function File} {[@var{q}, @var{d}] =} polyderiv (@var{b}, @var{a})
An alias for @code{polyderiv}.
@seealso{@ref{doc-polyderiv,,polyderiv}}
@end deftypefn


@c polyint scripts/polynomial/polyint.m
@anchor{doc-polyint}
@deftypefn  {Function File} {} polyint (@var{p})
@deftypefnx {Function File} {} polyint (@var{p}, @var{k})
Return the coefficients of the integral of the polynomial whose
coefficients are represented by the vector @var{p}.  The variable
@var{k} is the constant of integration, which by default is set to zero.
@seealso{@ref{doc-poly,,poly}, @ref{doc-polyderiv,,polyderiv}, @ref{doc-polyreduce,,polyreduce}, @ref{doc-roots,,roots}, @ref{doc-conv,,conv}, @ref{doc-deconv,,deconv}, @ref{doc-residue,,residue}, @ref{doc-filter,,filter}, @ref{doc-polyval,,polyval}, @ref{doc-polyvalm,,polyvalm}}
@end deftypefn


@c polyaffine scripts/polynomial/polyaffine.m
@anchor{doc-polyaffine}
@deftypefn {Function File} {} polyaffine (@var{f}, @var{mu})
Return the coefficients of the polynomial vector @var{f} after an affine
transformation.  If @var{f} is the vector representing the polynomial f(x),
then @code{@var{g} = polyaffine (@var{f}, @var{mu})} is the vector
representing:

@example
g(x) = f((x-@var{mu}(1))/@var{mu}(2)).
@end example

@seealso{@ref{doc-polyval,,polyval}}
@end deftypefn


@node Polynomial Interpolation
@section 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 just is what the @code{polyfit} function does.

@c polyfit scripts/polynomial/polyfit.m
@anchor{doc-polyfit}
@deftypefn  {Function File} {@var{p} =} polyfit (@var{x}, @var{y}, @var{n})
@deftypefnx {Function File} {[@var{p}, @var{s}] =} polyfit (@var{x}, @var{y}, @var{n})
@deftypefnx {Function File} {[@var{p}, @var{s}, @var{mu}] =} polyfit (@var{x}, @var{y}, @var{n})
Return the coefficients of a polynomial @var{p}(@var{x}) of degree
@var{n} that minimizes the least-squares-error of the fit.

The polynomial coefficients are returned in a row vector.

The second output is a structure containing the following fields:

@table @samp
@item R
Triangular factor R from the QR@tie{}decomposition.

@item X
The Vandermonde matrix used to compute the polynomial coefficients.

@item df
The degrees of freedom.

@item normr
The norm of the residuals.

@item yf
The values of the polynomial for each value of @var{x}.
@end table

The second output may be used by @code{polyval} to calculate the
statistical error limits of the predicted values.

When the third output, @var{mu}, is present the
coefficients, @var{p}, are associated with a polynomial in
@var{xhat} = (@var{x}-@var{mu}(1))/@var{mu}(2).
Where @var{mu}(1) = mean (@var{x}), and @var{mu}(2) = std (@var{x}).
This linear transformation of @var{x} improves the numerical
stability of the fit.
@seealso{@ref{doc-polyval,,polyval}, @ref{doc-residue,,residue}}
@end deftypefn


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 piecewise 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 is expressed
on adjoined intervals.

@example
@group
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);
@end group
@end example

@c mkpp scripts/polynomial/mkpp.m
@anchor{doc-mkpp}
@deftypefn  {Function File} {@var{pp} =} mkpp (@var{x}, @var{p})
@deftypefnx {Function File} {@var{pp} =} mkpp (@var{x}, @var{p}, @var{d})

Construct a piecewise polynomial structure from sample points
@var{x} and coefficients @var{p}.  The i-th row of @var{p},
@code{@var{p} (@var{i},:)}, contains the coefficients for the polynomial
over the @var{i}-th interval, ordered from highest to
lowest.  There must be one row for each interval in @var{x}, so
@code{rows (@var{p}) == length (@var{x}) - 1}.

@var{p} may also be a multi-dimensional array, specifying a vector-valued
or array-valued polynomial.  The shape is determined by @var{d}.  If @var{d}
is
not given, the default is @code{size (p)(1:end-2)}.  If @var{d} is given, the
leading dimensions of @var{p} are reshaped to conform to @var{d}.

@seealso{@ref{doc-unmkpp,,unmkpp}, @ref{doc-ppval,,ppval}, @ref{doc-spline,,spline}}
@end deftypefn


@c unmkpp scripts/polynomial/unmkpp.m
@anchor{doc-unmkpp}
@deftypefn {Function File} {[@var{x}, @var{p}, @var{n}, @var{k}, @var{d}] =} unmkpp (@var{pp})

Extract the components of a piecewise polynomial structure @var{pp}.
These are as follows:

@table @asis
@item @var{x}
Sample points.

@item @var{p}
Polynomial coefficients for points in sample interval.  @code{@var{p}
(@var{i}, :)} contains the coefficients for the polynomial over
interval @var{i} ordered from highest to lowest.  If @code{@var{d} >
1}, @code{@var{p} (@var{r}, @var{i}, :)} contains the coefficients for
the r-th polynomial defined on interval @var{i}.

@item @var{n}
Number of polynomial pieces.

@item @var{k}
Order of the polynomial plus 1.

@item @var{d}
Number of polynomials defined for each interval.
@end table

@seealso{@ref{doc-mkpp,,mkpp}, @ref{doc-ppval,,ppval}, @ref{doc-spline,,spline}}
@end deftypefn


@c ppval scripts/polynomial/ppval.m
@anchor{doc-ppval}
@deftypefn {Function File} {@var{yi} =} ppval (@var{pp}, @var{xi})
Evaluate piecewise polynomial @var{pp} at the points @var{xi}.
If @var{pp} is scalar-valued, the result is an array of the same shape as
@var{xi}.
Otherwise, the size of the result is @code{[pp.d, length(@var{xi})]} if
@var{xi} is a vector, or @code{[pp.d, size(@var{xi})]} if it is a
multi-dimensional array.  If pp.orient is 1, the dimensions are permuted as
in interp1, to
@code{[pp.d, length(@var{xi})]} and @code{[pp.d, size(@var{xi})]}
respectively.
@seealso{@ref{doc-mkpp,,mkpp}, @ref{doc-unmkpp,,unmkpp}, @ref{doc-spline,,spline}}
@end deftypefn


@c ppder scripts/polynomial/ppder.m
@anchor{doc-ppder}
@deftypefn {Function File} {@var{ppd} =} ppder (@var{pp})
Compute the piecewise derivative of the piecewise polynomial struct @var{pp}.
@seealso{@ref{doc-mkpp,,mkpp}, @ref{doc-ppval,,ppval}, @ref{doc-ppint,,ppint}}
@end deftypefn


@c ppint scripts/polynomial/ppint.m
@anchor{doc-ppint}
@deftypefn  {Function File} {@var{ppi} =} ppint (@var{pp})
@deftypefnx {Function File} {@var{ppi} =} ppint (@var{pp}, @var{c})
Compute the integral of the piecewise polynomial struct @var{pp}.
@var{c}, if given, is the constant of integration.
@seealso{@ref{doc-mkpp,,mkpp}, @ref{doc-ppval,,ppval}, @ref{doc-ppder,,ppder}}
@end deftypefn


@c ppjumps scripts/polynomial/ppjumps.m
@anchor{doc-ppjumps}
@deftypefn {Function File} {@var{jumps} =} ppjumps (@var{pp})
Evaluate the boundary jumps of a piecewise polynomial.
If there are @math{n} intervals, and the dimensionality of @var{pp} is
@math{d}, the resulting array has dimensions @code{[d, n-1]}.
@seealso{@ref{doc-mkpp,,mkpp}}
@end deftypefn


@node Miscellaneous Functions
@section Miscellaneous Functions

@c poly scripts/polynomial/poly.m
@anchor{doc-poly}
@deftypefn  {Function File} {} poly (@var{A})
@deftypefnx {Function File} {} poly (@var{x})
If @var{A} is a square @math{N}-by-@math{N} 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}.  For example,
the following code finds the eigenvalues of @var{A} which are the roots of
@code{poly (@var{A})}.

@example
@group
roots(poly(eye(3)))
@result{} 1.00001 + 0.00001i
@result{} 1.00001 - 0.00001i
@result{} 0.99999 + 0.00000i
@end group
@end example

In fact, all three eigenvalues are exactly 1 which emphasizes that for
numerical performance the @code{eig} function should be used to compute
eigenvalues.

If @var{x} is a vector, @code{poly (@var{x})} is a vector of the coefficients
of the polynomial whose roots are the elements of @var{x}.  That is,
if @var{c} is a polynomial, then the elements of
@code{@var{d} = roots (poly (@var{c}))} are contained in @var{c}.
The vectors @var{c} and @var{d} are not identical, however, due to sorting
and numerical errors.
@seealso{@ref{doc-eig,,eig}, @ref{doc-roots,,roots}}
@end deftypefn


@c polyout scripts/polynomial/polyout.m
@anchor{doc-polyout}
@deftypefn  {Function File} {} polyout (@var{c})
@deftypefnx {Function File} {} polyout (@var{c}, @var{x})
@deftypefnx {Function File} {@var{str} =} polyout (@dots{})
Write formatted polynomial
@tex
$$ c(x) = c_1 x^n + \ldots + c_n x + c_{n+1} $$
@end tex
@ifnottex

@example
   c(x) = c(1) * x^n + @dots{} + c(n) x + c(n+1)
@end example

@end ifnottex
and return it as a string or write it to the screen (if
@var{nargout} is zero).
@var{x} defaults to the string @code{"s"}.
@seealso{@ref{doc-polyval,,polyval}, @ref{doc-polyvalm,,polyvalm}, @ref{doc-poly,,poly}, @ref{doc-roots,,roots}, @ref{doc-conv,,conv}, @ref{doc-deconv,,deconv}, @ref{doc-residue,,residue}, @ref{doc-filter,,filter}, @ref{doc-polyderiv,,polyderiv}, @ref{doc-polyint,,polyint}}
@end deftypefn


@c polyreduce scripts/polynomial/polyreduce.m
@anchor{doc-polyreduce}
@deftypefn {Function File} {} polyreduce (@var{c})
Reduce a polynomial coefficient vector to a minimum number of terms by
stripping off any leading zeros.
@seealso{@ref{doc-poly,,poly}, @ref{doc-roots,,roots}, @ref{doc-conv,,conv}, @ref{doc-deconv,,deconv}, @ref{doc-residue,,residue}, @ref{doc-filter,,filter}, @ref{doc-polyval,,polyval}, @ref{doc-polyvalm,,polyvalm}, @ref{doc-polyderiv,,polyderiv}, @ref{doc-polyint,,polyint}}
@end deftypefn





