# NAG FL Interfaced01gaf (dim1_​data)

## ▸▿ Contents

Settings help

FL Name Style:

FL Specification Language:

## 1Purpose

d01gaf integrates a function which is specified numerically at four or more points, over the whole of its specified range, using third-order finite difference formulae with error estimates, according to a method due to Gill and Miller (1972).

## 2Specification

Fortran Interface
 Subroutine d01gaf ( x, y, n, ans, er,
 Integer, Intent (In) :: n Integer, Intent (Inout) :: ifail Real (Kind=nag_wp), Intent (In) :: x(n), y(n) Real (Kind=nag_wp), Intent (Out) :: ans, er
C Header Interface
#include <nag.h>
 void d01gaf_ (const double x[], const double y[], const Integer *n, double *ans, double *er, Integer *ifail)
The routine may be called by the names d01gaf or nagf_quad_dim1_data.

## 3Description

d01gaf evaluates the definite integral
 $I = ∫ x1 xn y(x) dx ,$
where the function $y$ is specified at the $n$-points ${x}_{1},{x}_{2},\dots ,{x}_{n}$, which should be all distinct, and in either ascending or descending order. The integral between successive points is calculated by a four-point finite difference formula centred on the interval concerned, except in the case of the first and last intervals, where four-point forward and backward difference formulae respectively are employed. If $n$ is less than $4$, the routine fails. An approximation to the truncation error is integrated and added to the result. It is also returned separately to give an estimate of the uncertainty in the result. The method is due to Gill and Miller (1972).
Gill P E and Miller G F (1972) An algorithm for the integration of unequally spaced data Comput. J. 15 80–83

## 5Arguments

1: $\mathbf{x}\left({\mathbf{n}}\right)$Real (Kind=nag_wp) array Input
On entry: the values of the independent variable, i.e., the ${x}_{1},{x}_{2},\dots ,{x}_{n}$.
Constraint: either ${\mathbf{x}}\left(1\right)<{\mathbf{x}}\left(2\right)<\cdots <{\mathbf{x}}\left({\mathbf{n}}\right)$ or ${\mathbf{x}}\left(1\right)>{\mathbf{x}}\left(2\right)>\cdots >{\mathbf{x}}\left({\mathbf{n}}\right)$.
2: $\mathbf{y}\left({\mathbf{n}}\right)$Real (Kind=nag_wp) array Input
On entry: the values of the dependent variable ${y}_{\mathit{i}}$ at the points ${x}_{\mathit{i}}$, for $\mathit{i}=1,2,\dots ,n$.
3: $\mathbf{n}$Integer Input
On entry: $n$, the number of points.
Constraint: ${\mathbf{n}}\ge 4$.
4: $\mathbf{ans}$Real (Kind=nag_wp) Output
On exit: the estimated value of the integral.
5: $\mathbf{er}$Real (Kind=nag_wp) Output
On exit: an estimate of the uncertainty in ans.
6: $\mathbf{ifail}$Integer Input/Output
On entry: ifail must be set to $0$, $-1$ or $1$ to set behaviour on detection of an error; these values have no effect when no error is detected.
A value of $0$ causes the printing of an error message and program execution will be halted; otherwise program execution continues. A value of $-1$ means that an error message is printed while a value of $1$ means that it is not.
If halting is not appropriate, the value $-1$ or $1$ is recommended. If message printing is undesirable, then the value $1$ is recommended. Otherwise, the value $0$ is recommended. When the value $-\mathbf{1}$ or $\mathbf{1}$ is used it is essential to test the value of ifail on exit.
On exit: ${\mathbf{ifail}}={\mathbf{0}}$ unless the routine detects an error or a warning has been flagged (see Section 6).

## 6Error Indicators and Warnings

If on entry ${\mathbf{ifail}}=0$ or $-1$, explanatory error messages are output on the current error message unit (as defined by x04aaf).
Errors or warnings detected by the routine:
Note: no error is reported arising from the relative magnitudes of ans and er on return, due to the difficulty when the true answer is zero.
${\mathbf{ifail}}=1$
On entry, ${\mathbf{n}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{n}}\ge 4$.
${\mathbf{ifail}}=2$
On entry, ${\mathbf{x}}\left(1\right)=⟨\mathit{\text{value}}⟩$ and ${\mathbf{x}}\left(2\right)=⟨\mathit{\text{value}}⟩$, ${\mathbf{x}}\left(I-1\right)=⟨\mathit{\text{value}}⟩$, ${\mathbf{x}}\left(I\right)=⟨\mathit{\text{value}}⟩$ and $I=⟨\mathit{\text{value}}⟩$.
Constraint: either ${\mathbf{x}}\left(1\right)<{\mathbf{x}}\left(2\right)<\cdots <{\mathbf{x}}\left({\mathbf{n}}\right)$ or ${\mathbf{x}}\left(1\right)>{\mathbf{x}}\left(2\right)>\cdots >{\mathbf{x}}\left({\mathbf{n}}\right)$.
${\mathbf{ifail}}=3$
On entry, $I=⟨\mathit{\text{value}}⟩$, ${\mathbf{x}}\left(I\right)=⟨\mathit{\text{value}}⟩$ and ${\mathbf{x}}\left(I-1\right)=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{x}}\left(I\right)\ne {\mathbf{x}}\left(I-1\right)$.
${\mathbf{ifail}}=-99$
An unexpected error has been triggered by this routine. Please contact NAG.
See Section 7 in the Introduction to the NAG Library FL Interface for further information.
${\mathbf{ifail}}=-399$
Your licence key may have expired or may not have been installed correctly.
See Section 8 in the Introduction to the NAG Library FL Interface for further information.
${\mathbf{ifail}}=-999$
Dynamic memory allocation failed.
See Section 9 in the Introduction to the NAG Library FL Interface for further information.

## 7Accuracy

No accuracy level is specified by you before calling d01gaf but on return the absolute value of er is an approximation to, but not necessarily a bound for, $|I-{\mathbf{ans}}|$. If on exit ${\mathbf{ifail}}>{\mathbf{0}}$, both ans and er are returned as zero.

## 8Parallelism and Performance

d01gaf is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

## 9Further Comments

The time taken by d01gaf depends on the number of points supplied, $n$.
In their paper, Gill and Miller (1972) do not add the quantity er to ans before return. However, extensive tests have shown that a dramatic reduction in the error often results from such addition. In other cases, it does not make an improvement, but these tend to be cases of low accuracy in which the modified answer is not significantly inferior to the unmodified one. You have the option of recovering the Gill–Miller answer by subtracting er from ans on return from the routine.

## 10Example

This example evaluates the integral
 $∫01 4 1+x2 dx = π$
reading in the function values at $21$ unequally spaced points.

### 10.1Program Text

Program Text (d01gafe.f90)

### 10.2Program Data

Program Data (d01gafe.d)

### 10.3Program Results

Program Results (d01gafe.r)