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

# NAG Toolbox: nag_interp_1d_monotonic (e01be)

## Purpose

nag_interp_1d_monotonic (e01be) computes a monotonicity-preserving piecewise cubic Hermite interpolant to a set of data points.

## Syntax

[d, ifail] = e01be(x, f, 'n', n)
[d, ifail] = nag_interp_1d_monotonic(x, f, 'n', n)

## Description

nag_interp_1d_monotonic (e01be) estimates first derivatives at the set of data points $\left({x}_{\mathit{r}},{f}_{\mathit{r}}\right)$, for $\mathit{r}=1,2,\dots ,n$, which determine a piecewise cubic Hermite interpolant to the data, that preserves monotonicity over ranges where the data points are monotonic. If the data points are only piecewise monotonic, the interpolant will have an extremum at each point where monotonicity switches direction. The estimates of the derivatives are computed by a formula due to Brodlie, which is described in Fritsch and Butland (1984), with suitable changes at the boundary points.
The function is derived from function PCHIM in Fritsch (1982).
Values of the computed interpolant, and of its first derivative and definite integral, can subsequently be computed by calling nag_interp_1d_monotonic_eval (e01bf), nag_interp_1d_monotonic_deriv (e01bg) and nag_interp_1d_monotonic_intg (e01bh), as described in Further Comments.

## References

Fritsch F N (1982) PCHIP final specifications Report UCID-30194 Lawrence Livermore National Laboratory
Fritsch F N and Butland J (1984) A method for constructing local monotone piecewise cubic interpolants SIAM J. Sci. Statist. Comput. 5 300–304

## Parameters

### Compulsory Input Parameters

1:     $\mathrm{x}\left({\mathbf{n}}\right)$ – double array
${\mathbf{x}}\left(\mathit{r}\right)$ must be set to ${x}_{\mathit{r}}$, the $\mathit{r}$th value of the independent variable (abscissa), for $\mathit{r}=1,2,\dots ,n$.
Constraint: ${\mathbf{x}}\left(r\right)<{\mathbf{x}}\left(r+1\right)$.
2:     $\mathrm{f}\left({\mathbf{n}}\right)$ – double array
${\mathbf{f}}\left(\mathit{r}\right)$ must be set to ${f}_{\mathit{r}}$, the $\mathit{r}$th value of the dependent variable (ordinate), for $\mathit{r}=1,2,\dots ,n$.

### Optional Input Parameters

1:     $\mathrm{n}$int64int32nag_int scalar
Default: the dimension of the arrays x, f. (An error is raised if these dimensions are not equal.)
$n$, the number of data points.
Constraint: ${\mathbf{n}}\ge 2$.

### Output Parameters

1:     $\mathrm{d}\left({\mathbf{n}}\right)$ – double array
Estimates of derivatives at the data points. ${\mathbf{d}}\left(r\right)$ contains the derivative at ${\mathbf{x}}\left(r\right)$.
2:     $\mathrm{ifail}$int64int32nag_int scalar
${\mathbf{ifail}}={\mathbf{0}}$ unless the function detects an error (see Error Indicators and Warnings).

## Error Indicators and Warnings

Errors or warnings detected by the function:
${\mathbf{ifail}}=1$
 On entry, ${\mathbf{n}}<2$.
${\mathbf{ifail}}=2$
The values of ${\mathbf{x}}\left(\mathit{r}\right)$, for $\mathit{r}=1,2,\dots ,{\mathbf{n}}$, are not in strictly increasing order.
${\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

The computational errors in the array d should be negligible in most practical situations.

The time taken by nag_interp_1d_monotonic (e01be) is approximately proportional to $n$.
The values of the computed interpolant at the points ${\mathbf{px}}\left(\mathit{i}\right)$, for $\mathit{i}=1,2,\dots ,{\mathbf{m}}$, may be obtained in the double array pf, of length at least m, by the call:
```[pf, ifail] = e01bf(x, f, d, px);
```
where n, x and f are the input arguments to nag_interp_1d_monotonic (e01be) and d is the output argument from nag_interp_1d_monotonic (e01be).
The values of the computed interpolant at the points ${\mathbf{px}}\left(\mathit{i}\right)$, for $\mathit{i}=1,2,\dots ,{\mathbf{m}}$, together with its first derivatives, may be obtained in the double arrays pf and pd, both of length at least m, by the call:
```[pf, pd, ifail] = e01bg(x, f, d, px);
```
where n, x, f and d are as described above.
The value of the definite integral of the interpolant over the interval a to b can be obtained in the double variable pint by the call:
```[pint, ifail] = e01bh(x, f, d, a, b);
```
where n, x, f and d are as described above.

## Example

This example reads in a set of data points, calls nag_interp_1d_monotonic (e01be) to compute a piecewise monotonic interpolant, and then calls nag_interp_1d_monotonic_eval (e01bf) to evaluate the interpolant at equally spaced points.
```function e01be_example

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

x = [7.99 8.09    8.19    8.7     9.2     10      12      15      20];
f = [0 2.7643e-05 0.04375 0.16918 0.46943 0.94374 0.99864 0.99992 0.99999];

[d, ifail] = e01be(x, f);

m = 11;
dx = (x(end)-x(1))/(m-1);
px = [x(1):dx:x(end)];

[pf, ifail] = e01bf(x, f, d, px);

fprintf('\n                Interpolated\n     Abscissa          Value\n');
fprintf('%13.4f  %13.4f\n', [px' pf]')

```
```e01be example results

Interpolated
Abscissa          Value
7.9900         0.0000
9.1910         0.4640
10.3920         0.9645
11.5930         0.9965
12.7940         0.9992
13.9950         0.9998
15.1960         0.9999
16.3970         1.0000
17.5980         1.0000
18.7990         1.0000
20.0000         1.0000
```