@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, Differential Equations, Nonlinear Equations, Top
@chapter Quadrature

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

@node Functions of One Variable, Orthogonal Collocation, Quadrature, Quadrature
@section Functions of One Variable

@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 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.
@end deftypefn

@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.
@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.).

@node Orthogonal Collocation,  , Functions of One Variable, Quadrature
@section Orthogonal Collocation

@deftypefn {Loadable Function} {[@var{r}, @var{A}, @var{B}, @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