Home > freetb4matlab > general > quadgk.m

quadgk

PURPOSE ^

% Numerically evaluate integral using adaptive Gauss-Konrod quadrature.

SYNOPSIS ^

function [q, err] = quadgk (f, a, b, varargin)

DESCRIPTION ^

% -*- texinfo -*-
% @deftypefn {Function File} {} quadgk (@var{f}, @var{a}, @var{b}, @var{abstol}, @var{trace})
% @deftypefnx {Function File} {} quadgk (@var{f}, @var{a}, @var{b}, @var{prop}, @var{val}, @dots{})
% @deftypefnx {Function File} {[@var{q}, @var{err}] =} quadgk (@dots{})
% Numerically evaluate integral using adaptive Gauss-Konrod quadrature.
% The formulation is based on a proposal by L.F. Shampine,
% @cite{'Vectorized adaptive quadrature in @sc{matlab}', Journal of
% Computational and Applied Mathematics, pp131-140, Vol 211, Issue 2,
% Feb 2008} where all function evaluations at an iteration are
% calculated with a single call to @var{f}.  Therefore the function
% @var{f} must be of the form @code{@var{f} (@var{x})} and accept
% vector values of @var{x} and return a vector of the same length
% representing the function evaluations at the given values of @var{x}.
% The function @var{f} can be defined in terms of a function handle,
% inline function or string.
%
% The bounds of the quadrature @code{[@var{a}, @var{b}]} can be finite
% or infinite and contain weak end singularities.  Variable
% transformation will be used to treat infinite intervals and weaken
% the singularities.  For example
%
% @example
% quadgk(@@(x) 1 ./ (sqrt (x) .* (x + 1)), 0, Inf)
% @end example
%
% @noindent
% Note that the formulation of the integrand uses the
% element-by-element operator @code{./} and all user functions to
% @code{quadgk} should do the same.
%
% The absolute tolerance can be passed as a fourth argument in a manner
% compatible with @code{quadv}.  Equally the user can request that
% information on the convergence can be printed is the fifth argument
% is logically true.
%
% Alternatively, certain properties of @code{quadgk} can be passed as
% pairs @code{@var{prop}, @var{val}}.  Valid properties are
%
% @table @code
% @item AbsTol
% Defines the absolute error tolerance for the quadrature.  The default
% absolute tolerance is 1e-10.
%
% @item RelTol
% Defines the relative error tolerance for the quadrature.  The default
% relative tolerance is 1e-5.
%
% @item MaxIntervalCount
% @code{quadgk} initially subdivides the interval on which to perform
% the quadrature into 10 intervals.  Sub-intervals that have an
% unacceptable error are sub-divided and re-evaluated.  If the number of
% sub-intervals exceeds at any point 650 sub-intervals then a poor
% convergence is signaled and the current estimate of the integral is
% returned.  The property 'MaxIntervalCount' can be used to alter the
% number of sub-intervals that can exist before exiting.
%
% @item WayPoints
% If there exists discontinuities in the first derivative of the
% function to integrate, then these can be flagged with the
% @code{'WayPoints'} property.  This forces the ends of a sub-interval
% to fall on the breakpoints of the function and can result in
% significantly improved estimated of the error in the integral, faster
% computation or both.  For example,
%
% @example
% quadgk (@@(x) abs (1 - x .^ 2), 0, 2, 'Waypoints', 1)
% @end example
%
% @noindent
% signals the breakpoint in the integrand at @code{@var{x} = 1}.
%
% @item Trace
% If logically true, then @code{quadgk} prints information on the
% convergence of the quadrature at each iteration.
%@end table
%
% If any of @var{a}, @var{b} or @var{waypoints} is complex, then the
% quadrature is treated as a contour integral along a piecewise
% continuous path defined by the above.  In this case the integral is
% assumed to have no edge singularities.  For example
%
% @example
% @group
% quadgk (@@(z) log (z), 1+1i, 1+1i, 'WayPoints',
%         [1-1i, -1,-1i, -1+1i])
% @end group
% @end example
%
% @noindent
% integrates @code{log (z)} along the square defined by @code{[1+1i,
%  1-1i, -1-1i, -1+1i]}
%
% If two output arguments are requested, then @var{err} returns the
% approximate bounds on the error in the integral @code{abs (@var{q} -
% @var{i})}, where @var{i} is the exact value of the integral.
%
% @seealso{triplequad, dblquad, quad, quadl, quadv, trapz}
% @end deftypefn

CROSS-REFERENCE INFORMATION ^

This function calls: This function is called by:
Generated on Sat 16-May-2009 00:04:49 by m2html © 2003