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

@c Copyright (C) 1996, 1997 John W. Eaton
@c This is part of the Octave manual.
@c For copying conditions, see the file gpl.texi.

@node Quadrature
@chapter Quadrature

@menu
* Functions of One Variable::   
* Orthogonal Collocation::      
@end menu

@node Functions of One Variable
@section Functions of One Variable

@anchor{doc-quad}
@deftypefn {Loadable Function} {[@var{v}, @var{ier}, @var{nfun}, @var{err}] =} quad (@var{f}, @var{a}, @var{b}, @var{tol}, @var{sing})
Integrate a nonlinear function of one variable using Quadpack.
The first argument is the name of the  function, the function handle or
the inline function to call to compute the value of the integrand.  It
must have the form

@example
y = f (x)
@end example

@noindent
where @var{y} and @var{x} are scalars.

The second and third arguments are limits of integration.  Either or
both may be infinite.

The optional argument @var{tol} is a vector that specifies the desired
accuracy of the result.  The first element of the vector is the desired
absolute tolerance, and the second element is the desired relative
tolerance.  To choose a relative test only, set the absolute
tolerance to zero.  To choose an absolute test only, set the relative
tolerance to zero. 

The optional argument @var{sing} is a vector of values at which the
integrand is known to be singular.

The result of the integration is returned in @var{v} and @var{ier}
contains an integer error code (0 indicates a successful integration).
The value of @var{nfun} indicates how many function evaluations were
required, and @var{err} contains an estimate of the error in the
solution.

You can use the function @code{quad_options} to set optional
parameters for @code{quad}.
@end deftypefn


@anchor{doc-quad_options}
@deftypefn {Loadable Function} {} quad_options (@var{opt}, @var{val})
When called with two arguments, this function
allows you set options parameters for the function @code{quad}.
Given one argument, @code{quad_options} returns the value of the
corresponding option.  If no arguments are supplied, the names of all
the available options and their current values are displayed.

Options include

@table @code
@item "absolute tolerance"
Absolute tolerance; may be zero for pure relative error test.
@item "relative tolerance"
Nonnegative relative tolerance.  If the absolute tolerance is zero,
the relative tolerance must be greater than or equal to 
@code{max (50*eps, 0.5e-28)}.
@end table
@end deftypefn


Here is an example of using @code{quad} to integrate the function
@iftex
@tex
$$
 f(x) = x \sin (1/x) \sqrt {|1 - x|}
$$
from $x = 0$ to $x = 3$.
@end tex
@end iftex
@ifinfo

@example
  @var{f}(@var{x}) = @var{x} * sin (1/@var{x}) * sqrt (abs (1 - @var{x}))
@end example

@noindent
from @var{x} = 0 to @var{x} = 3.
@end ifinfo

This is a fairly difficult integration (plot the function over the range
of integration to see why).

The first step is to define the function:

@example
@group
function y = f (x)
  y = x .* sin (1 ./ x) .* sqrt (abs (1 - x));
endfunction
@end group
@end example

Note the use of the `dot' forms of the operators.  This is not necessary
for the call to @code{quad}, but it makes it much easier to generate a
set of points for plotting (because it makes it possible to call the
function with a vector argument to produce a vector result).

Then we simply call quad:

@example
@group
[v, ier, nfun, err] = quad ("f", 0, 3)
     @result{} 1.9819
     @result{} 1
     @result{} 5061
     @result{} 1.1522e-07
@end group
@end example

Although @code{quad} returns a nonzero value for @var{ier}, the result
is reasonably accurate (to see why, examine what happens to the result
if you move the lower bound to 0.1, then 0.01, then 0.001, etc.).

@anchor{doc-quadl}
@deftypefn {Function File} {@var{q} =} quadl (@var{f}, @var{a}, @var{b})
@deftypefnx {Function File} {@var{q} =} quadl (@var{f}, @var{a}, @var{b}, @var{tol})
@deftypefnx {Function File} {@var{q} =} quadl (@var{f}, @var{a}, @var{b}, @var{tol}, @var{trace})
@deftypefnx {Function File} {@var{q} =} quadl (@var{f}, @var{a}, @var{b}, @var{tol}, @var{trace}, @var{p1}, @var{p2}, @dots{})

Numerically evaluate integral using adaptive Lobatto rule.
@code{quadl (@var{f}, @var{a}, @var{b})} approximates the integral of
@code{@var{f}(@var{x})} to machine precision. @var{f} is either a
function handle, inline function or string containing the name of
the function to evaluate. The function @var{f} must return a vector
of output values if given a vector of input values.

If defined, @var{tol} defines the relative tolerance to which to
which to integrate @code{@var{f}(@var{x})}. While if @var{trace} is
defined, displays the left end point of the current interval, the 
interval length, and the partial integral.

Additional arguments @var{p1}, etc, are passed directly to @var{f}.
To use default values for @var{tol} and @var{trace}, one may pass
empty matrices.

Reference: W. Gander and W. Gautschi, 'Adaptive Quadrature - 
Revisited', BIT Vol. 40, No. 1, March 2000, pp. 84--101.
@url{http://www.inf.ethz.ch/personal/gander/}

@end deftypefn


@anchor{doc-trapz}
@deftypefn {Function File} {@var{z} =} trapz (@var{y})
@deftypefnx {Function File} {@var{z} =} trapz (@var{x}, @var{y})
@deftypefnx {Function File} {@var{z} =} trapz (@dots{}, @var{dim})

Numerical intergration using trapezodial method. @code{trapz
(@var{y})} computes the integral of the @var{y} along the first
non singleton dimension. If the argument @var{x} is omitted a 
equally spaced vector is assumed. @code{trapz (@var{x}, @var{y})} 
evaluates the integral with respect to @var{x}.
 
@seealso{cumtrapz}
@end deftypefn


@anchor{doc-cumtrapz}
@deftypefn {Function File} {@var{z} =} cumtrapz (@var{y})
@deftypefnx {Function File} {@var{z} =} cumtrapz (@var{x}, @var{y})
@deftypefnx {Function File} {@var{z} =} cumtrapz (@dots{}, @var{dim})

Cumulative numerical intergration using trapezodial method.
@code{trapz (@var{y})} computes the cummulative integral of the 
@var{y} along the first non singleton dimension. If the argument 
@var{x} is omitted a equally spaced vector is assumed. @code{trapz 
(@var{x}, @var{y})} evaluates the cummulative integral with respect 
to @var{x}.
 
@seealso{trapz,cumsum}
@end deftypefn


@node Orthogonal Collocation
@section Orthogonal Collocation

@anchor{doc-colloc}
@deftypefn {Loadable Function} {[@var{r}, @var{amat}, @var{bmat}, @var{q}] =} colloc (@var{n}, "left", "right")
Compute derivative and integral weight matrices for orthogonal
collocation using the subroutines given in J. Villadsen and
M. L. Michelsen, @cite{Solution of Differential Equation Models by
Polynomial Approximation}.
@end deftypefn


Here is an example of using @code{colloc} to generate weight matrices
for solving the second order differential equation
@iftex
@tex
$u^\prime - \alpha u^{\prime\prime} = 0$ with the boundary conditions
$u(0) = 0$ and $u(1) = 1$.
@end tex
@end iftex
@ifinfo
@var{u}' - @var{alpha} * @var{u}'' = 0 with the boundary conditions
@var{u}(0) = 0 and @var{u}(1) = 1.
@end ifinfo

First, we can generate the weight matrices for @var{n} points (including
the endpoints of the interval), and incorporate the boundary conditions
in the right hand side (for a specific value of
@iftex
@tex
$\alpha$).
@end tex
@end iftex
@ifinfo
@var{alpha}).
@end ifinfo

@example
@group
n = 7;
alpha = 0.1;
[r, a, b] = colloc (n-2, "left", "right");
at = a(2:n-1,2:n-1);
bt = b(2:n-1,2:n-1);
rhs = alpha * b(2:n-1,n) - a(2:n-1,n);
@end group
@end example

Then the solution at the roots @var{r} is

@example
u = [ 0; (at - alpha * bt) \ rhs; 1]
     @result{} [ 0.00; 0.004; 0.01 0.00; 0.12; 0.62; 1.00 ]
@end example
