Integer type:  int32  int64  nag_int  show int32  show int32  show int64  show int64  show nag_int  show nag_int

Chapter Contents
Chapter Introduction
NAG Toolbox

## Purpose

nag_quad_1d_fin_gonnet_vec (d01rg) is a general purpose integrator which calculates an approximation to the integral of a function $f\left(x\right)$ over a finite interval $\left[a,b\right]$:
 $I= ∫ab fx 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.

## 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:     $\mathrm{a}$ – double scalar
$a$, the lower limit of integration.
2:     $\mathrm{b}$ – double scalar
$b$, the upper limit of integration. It is not necessary that $a.
Note: if ${\mathbf{a}}={\mathbf{b}}$, the function will immediately return ${\mathbf{dinest}}=0.0$, ${\mathbf{errest}}=0.0$ and ${\mathbf{nevals}}=0$.
3:     $\mathrm{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:     $\mathrm{x}\left({\mathbf{nx}}\right)$ – double array
The abscissae, ${x}_{i}$, for $\mathit{i}=1,2,\dots ,{\mathbf{nx}}$, at which function values are required.
2:     $\mathrm{nx}$int64int32nag_int scalar
The number of abscissae at which a function value is required.
3:     $\mathrm{iflag}$int64int32nag_int scalar
${\mathbf{iflag}}=0$.
4:     $\mathrm{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:     $\mathrm{fv}\left({\mathbf{nx}}\right)$ – double array
fv must contain the values of the integrand $f$. ${\mathbf{fv}}\left(i\right)=f\left({x}_{i}\right)$ for all $i=1,2,\dots ,{\mathbf{nx}}$.
2:     $\mathrm{iflag}$int64int32nag_int scalar
Set ${\mathbf{iflag}}<0$ to force an immediate exit with ${\mathbf{ifail}}=-{\mathbf{1}}$.
3:     $\mathrm{user}$ – Any MATLAB object
4:     $\mathrm{epsabs}$ – double scalar
The absolute accuracy required.
If epsabs is negative, $\left|{\mathbf{epsabs}}\right|$ is used. See Accuracy.
If ${\mathbf{epsabs}}=0.0$, only the relative error will be used.
5:     $\mathrm{epsrel}$ – double scalar
The relative accuracy required.
If epsrel is negative, $\left|{\mathbf{epsrel}}\right|$ is used. See Accuracy.
If ${\mathbf{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 .
Constraint: at least one of epsabs and epsrel must be nonzero.

### Optional Input Parameters

1:     $\mathrm{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:     $\mathrm{dinest}$ – double scalar
The estimate of the definite integral f.
2:     $\mathrm{errest}$ – double scalar
The error estimate of the definite integral f.
3:     $\mathrm{nevals}$int64int32nag_int scalar
The total number of points at which the integrand, $f$, has been evaluated.
4:     $\mathrm{user}$ – Any MATLAB object
5:     $\mathrm{ifail}$int64int32nag_int scalar
${\mathbf{ifail}}={\mathbf{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  ${\mathbf{ifail}}=1$
The requested accuracy was not achieved. Consider using larger values of epsabs and epsrel.
W  ${\mathbf{ifail}}=2$
The integral is probably divergent or slowly convergent.
${\mathbf{ifail}}=14$
Both ${\mathbf{epsabs}}=0.0$ and ${\mathbf{epsrel}}=0.0$.
W  ${\mathbf{ifail}}=-1$
Exit requested from f with .
${\mathbf{ifail}}=-99$
${\mathbf{ifail}}=-399$
Your licence key may have expired or may not have been installed correctly.
${\mathbf{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 ≤ tol ,$
where
 $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
 $I-dinest ≤ errest ≤ tol .$

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
 $∫ -1 1 sinx x ln101 - x .$
```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
```