hide long namesshow long names
hide short namesshow short names
Integer type:  int32  int64  nag_int  show int32  show int32  show int64  show int64  show nag_int  show nag_int

PDF version (NAG web site, 64-bit version, 64-bit version)
Chapter Contents
Chapter Introduction
NAG Toolbox

NAG Toolbox: nag_quad_1d_fin_gonnet_vec (d01rg)

Purpose

nag_quad_1d_fin_gonnet_vec (d01rg) is a general purpose integrator which calculates an approximation to the integral of a function f(x)f(x) over a finite interval [a,b][a,b]:
b
I = f(x)dx.
a
I= ab f(x) dx .
The function is suitable as a general purpose integrator, and can be used when the integrand has singularities and infinities. In particular, the function can continue if the function f explicitly returns a quiet or signalling NaN or a signed infinity.

Syntax

[dinest, errest, nevals, user, ifail] = d01rg(a, b, f, epsabs, epsrel, 'user', user)
[dinest, errest, nevals, user, ifail] = nag_quad_1d_fin_gonnet_vec(a, b, f, epsabs, epsrel, 'user', user)

Description

nag_quad_1d_fin_gonnet_vec (d01rg) uses the algorithm described in Gonnet (2010). It is an adaptive algorithm, similar to the QUADPACK routine QAGS (see Piessens et al. (1983), see also nag_quad_1d_gen_vec_multi_rcomm (d01ra)) but includes significant differences regarding how the integrand is represented, how the integration error is estimated and how singularities and divergent integrals are treated. The local error estimation is described in Gonnet (2010).
nag_quad_1d_fin_gonnet_vec (d01rg) requires a function to evaluate the integrand at an array of different points and is therefore amenable to parallel execution (see Section [Parallelism and Performance]).

References

Gonnet P (2010) Increasing the reliability of adaptive quadrature using explicit interpolants ACM Trans. Math. software 37 26
Piessens R, de Doncker–Kapenga E, Überhuber C and Kahaner D (1983) QUADPACK, A Subroutine Package for Automatic Integration Springer–Verlag

Parameters

Compulsory Input Parameters

1:     a – double scalar
aa, the lower limit of integration.
2:     b – double scalar
bb, the upper limit of integration. It is not necessary that a < ba<b.
Note: if a = ba=b, the function will immediately return dinest = 0.0dinest=0.0, errest = 0.0errest=0.0 and nevals = 0nevals=0.
3:     f – function handle or string containing name of m-file
f must return the value of the integrand ff at a set of points.
[fv, iflag, user] = f(x, nx, iflag, user)

Input Parameters

1:     x(nx) – double array
The abscissae, xixi, for i = 1,2,,nxi=1,2,,nx, at which function values are required.
2:     nx – int64int32nag_int scalar
The number of abscissae at which a function value is required.
3:     iflag – int64int32nag_int scalar
iflag = 0iflag=0.
4:     user – Any MATLAB object
f is called from nag_quad_1d_fin_gonnet_vec (d01rg) with the object supplied to nag_quad_1d_fin_gonnet_vec (d01rg).

Output Parameters

1:     fv(nx) – double array
fv must contain the values of the integrand ff. fv(i) = f(xi)fvi=f(xi) for all i = 1,2,,nxi=1,2,,nx.
2:     iflag – int64int32nag_int scalar
Set iflag < 0iflag<0 to force an immediate exit with ifail = 1ifail=-1.
3:     user – Any MATLAB object
4:     epsabs – double scalar
The absolute accuracy required.
If epsabs is negative, |epsabs||epsabs| is used. See Section [Accuracy].
If epsabs = 0.0epsabs=0.0, only the relative error will be used.
5:     epsrel – double scalar
The relative accuracy required.
If epsrel is negative, |epsrel||epsrel| is used. See Section [Accuracy].
If epsrel = 0.0epsrel=0.0, only the absolute error will be used otherwise the actual value of epsrel used by nag_quad_1d_fin_gonnet_vec (d01rg) is max (machine precision,|epsrel|)max(machine precision,|epsrel|).
Constraint: at least one of epsabs and epsrel must be nonzero.

Optional Input Parameters

1:     user – Any MATLAB object
user is not used by nag_quad_1d_fin_gonnet_vec (d01rg), but is passed to f. Note that for large objects it may be more efficient to use a global variable which is accessible from the m-files than to use user.

Input Parameters Omitted from the MATLAB Interface

iuser ruser

Output Parameters

1:     dinest – double scalar
The estimate of the definite integral f.
2:     errest – double scalar
The error estimate of the definite integral f.
3:     nevals – int64int32nag_int scalar
The total number of points at which the integrand, ff, has been evaluated.
4:     user – Any MATLAB object
5:     ifail – int64int32nag_int scalar
ifail = 0ifail=0 unless the function detects an error (see [Error Indicators and Warnings]).

Error Indicators and Warnings

Note: nag_quad_1d_fin_gonnet_vec (d01rg) may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the function:

Cases prefixed with W are classified as warnings and do not generate an error of type NAG:error_n. See nag_issue_warnings.

W ifail = 1ifail=1
The requested accuracy was not achieved. Consider using larger values of epsabs and epsrel.
W ifail = 2ifail=2
The integral is probably divergent or slowly convergent.
  ifail = 14ifail=14
Both epsabs = 0.0epsabs=0.0 and epsrel = 0.0epsrel=0.0.
W ifail = 1ifail=-1
Exit requested from f with .
  ifail = 999ifail=-999
Dynamic memory allocation failed.

Accuracy

nag_quad_1d_fin_gonnet_vec (d01rg) cannot guarantee, but in practice usually achieves, the following accuracy:
|Idinest| tol ,
|I-dinest| tol ,
where
tol = max {|epsabs|,|epsrel| × |I|} ,
tol = max{ |epsabs| , |epsrel| × |I| } ,
and epsabs and epsrel are user-specified absolute and relative error tolerances. Moreover, it returns the quantity errest which, in normal circumstances, satisfies
|Idinest| errest tol .
|I-dinest| errest tol .

Further Comments

The time taken by nag_quad_1d_fin_gonnet_vec (d01rg) depends on the integrand and the accuracy required.
nag_quad_1d_fin_gonnet_vec (d01rg) is suitable for evaluating integrals that have singularities within the requested interval.
In particular, nag_quad_1d_fin_gonnet_vec (d01rg) accepts non-finite values on return from the user-supplied function f, and will adapt the integration rule accordingly to eliminate such points. Non-finite values include NaNs and infinities.

Example

function nag_quad_1d_fin_gonnet_vec_example
a = -1;
b =  1;
epsabs = 0;
epsrel = 0.0001;
[dinest, errest, nevals, user, ifail] = ...
    nag_quad_1d_fin_gonnet_vec(a, b, @f, epsabs, epsrel)

function [fv, iflag, user] = f(x, nx, iflag, user)
  fv = sin(x)./x.*log(10*(1-x));
 

dinest =

    3.8116


errest =

   3.3918e-04


nevals =

                  593


user =

     0


ifail =

                    0


function d01rg_example
a = -1;
b =  1;
epsabs = 0;
epsrel = 0.0001;
[dinest, errest, nevals, user, ifail] = d01rg(a, b, @f, epsabs, epsrel)

function [fv, iflag, user] = f(x, nx, iflag, user)
  fv = sin(x)./x.*log(10*(1-x));
 

dinest =

    3.8116


errest =

   3.3918e-04


nevals =

                  593


user =

     0


ifail =

                    0



PDF version (NAG web site, 64-bit version, 64-bit version)
Chapter Contents
Chapter Introduction
NAG Toolbox

© The Numerical Algorithms Group Ltd, Oxford, UK. 2009–2013