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.

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

a

, the lower limit of integration.

2: $b$ – double scalar

b

, the upper limit of integration. It is not necessary that

a < b

Note: if

a = b

, the function will immediately return

dinest = 0.0

errest = 0.0

and

nevals = 0

3: $f$ – function handle or string containing name of m-file

f must return the value of the integrand

f

at a set of points.

[fv, iflag, user] = f(x, nx, iflag, user)

Input Parameters

1: $x (nx)$ – double array: The abscissae, $x_{i}$ , for $i = 1, 2, \dots, 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 = 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 $f$ . $fv (i) = f (x_{i})$ for all $i = 1, 2, \dots, nx$ .
2: $iflag$ – int64int32nag_int scalar: Set $iflag < 0$ to force an immediate exit with $ifail = - 1$ .
3: $user$ – Any MATLAB object

4: $epsabs$ – double scalar

The absolute accuracy required.

If epsabs is negative,

|epsabs|

is used. See Accuracy.

epsabs = 0.0

, only the relative error will be used.

5: $epsrel$ – double scalar

The relative accuracy required.

If epsrel is negative,

|epsrel|

is used. See Accuracy.

epsrel = 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|)

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.

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, $f$ , has been evaluated.
4: $user$ – Any MATLAB object
5: $ifail$ – int64int32nag_int scalar: $ifail = 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 = 1$: The requested accuracy was not achieved. Consider using larger values of epsabs and epsrel.

W $ifail = 2$: The integral is probably divergent or slowly convergent.

$ifail = 14$: Both $epsabs = 0.0$ and $epsrel = 0.0$ .

W $ifail = - 1$: Exit requested from f with .

$ifail = - 99$: An unexpected error has been triggered by this routine. Please contact NAG.

$ifail = - 399$: Your licence key may have expired or may not have been installed correctly.

$ifail = - 999$: Dynamic memory allocation failed.

Accuracy

nag_quad_1d_fin_gonnet_vec (d01rg) cannot guarantee, but in practice usually achieves, the following accuracy:

|I - dinest| \leq tol,

where

tol = \max \{|epsabs|, |epsrel| \times |I|\},

and epsabs and epsrel are user-specified absolute and relative error tolerances. Moreover, it returns the quantity errest which, in normal circumstances, satisfies

|I - dinest| \leq errest \leq 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

This example computes

\int_{- 1}^{1} \frac{\sin (x)}{x} \ln (10 (1 - x)) .

Open in the MATLAB editor: d01rg_example

function d01rg_example


fprintf('d01rg example results\n\n');

a = -1;
b =  1;
epsabs = 0;
epsrel = 0.0001;

[dinest, errest, nevals, user, ifail] = ...
  d01rg( ...
	 a, b, @f, epsabs, epsrel);

formr = '%-6s - %-30s = %8.5f\n';
formd = '%-6s - %-30s = %8d\n';
fprintf(formr, 'a', 'lower limit of integration', a);
fprintf(formr, 'b', 'upper limit of integration', b);
fprintf(formr, 'epsabs', 'absolute accuracy requested', epsabs);
fprintf(formr, 'epsabs', 'relative accuracy requested', epsrel);
fprintf('\n');
fprintf(formr, 'result', 'approximation to the integral', dinest);
fprintf(formr, 'abserr', 'estimate of the absolute error', errest);
fprintf(formd, 'nevals', 'number of function eblauations', nevals);




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

d01rg example results

a      - lower limit of integration     = -1.00000
b      - upper limit of integration     =  1.00000
epsabs - absolute accuracy requested    =  0.00000
epsabs - relative accuracy requested    =  0.00010

result - approximation to the integral  =  3.81155
abserr - estimate of the absolute error =  0.00034
nevals - number of function eblauations =      593

PDF version (NAG web site, 64-bit version, 64-bit version)

Chapter Contents

Chapter Introduction

NAG Toolbox