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_eval (e01bf)

## Purpose

nag_interp_1d_monotonic_eval (e01bf) evaluates a piecewise cubic Hermite interpolant at a set of points.

## Syntax

[pf, ifail] = e01bf(x, f, d, px, 'n', n, 'm', m)
[pf, ifail] = nag_interp_1d_monotonic_eval(x, f, d, px, 'n', n, 'm', m)

## Description

nag_interp_1d_monotonic_eval (e01bf) evaluates a piecewise cubic Hermite interpolant, as computed by nag_interp_1d_monotonic (e01be), at the points ${\mathbf{px}}\left(\mathit{i}\right)$, for $\mathit{i}=1,2,\dots ,m$. If any point lies outside the interval from ${\mathbf{x}}\left(1\right)$ to ${\mathbf{x}}\left({\mathbf{n}}\right)$, a value is extrapolated from the nearest extreme cubic, and a warning is returned.
The function is derived from function PCHFE in Fritsch (1982).

## References

Fritsch F N (1982) PCHIP final specifications Report UCID-30194 Lawrence Livermore National Laboratory

## Parameters

### Compulsory Input Parameters

1:     $\mathrm{x}\left({\mathbf{n}}\right)$ – double array
2:     $\mathrm{f}\left({\mathbf{n}}\right)$ – double array
3:     $\mathrm{d}\left({\mathbf{n}}\right)$ – double array
n, x, f and d must be unchanged from the previous call of nag_interp_1d_monotonic (e01be).
4:     $\mathrm{px}\left({\mathbf{m}}\right)$ – double array
The $m$ values of $x$ at which the interpolant is to be evaluated.

### Optional Input Parameters

1:     $\mathrm{n}$int64int32nag_int scalar
Default: the dimension of the arrays x, f, d. (An error is raised if these dimensions are not equal.)
n, x, f and d must be unchanged from the previous call of nag_interp_1d_monotonic (e01be).
2:     $\mathrm{m}$int64int32nag_int scalar
Default: the dimension of the array px.
$m$, the number of points at which the interpolant is to be evaluated.
Constraint: ${\mathbf{m}}\ge 1$.

### Output Parameters

1:     $\mathrm{pf}\left({\mathbf{m}}\right)$ – double array
${\mathbf{pf}}\left(\mathit{i}\right)$ contains the value of the interpolant evaluated at the point ${\mathbf{px}}\left(\mathit{i}\right)$, for $\mathit{i}=1,2,\dots ,m$.
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:

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

${\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}}=3$
 On entry, ${\mathbf{m}}<1$.
W  ${\mathbf{ifail}}=4$
At least one of the points ${\mathbf{px}}\left(\mathit{i}\right)$, for $\mathit{i}=1,2,\dots ,{\mathbf{m}}$, lies outside the interval [${\mathbf{x}}\left(1\right),{\mathbf{x}}\left({\mathbf{n}}\right)$], and extrapolation was performed at all such points. Values computed at such points may be very unreliable.
${\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 pf should be negligible in most practical situations.

The time taken by nag_interp_1d_monotonic_eval (e01bf) is approximately proportional to the number of evaluation points, $m$. The evaluation will be most efficient if the elements of px are in nondecreasing order (or, more generally, if they are grouped in increasing order of the intervals $\left[{\mathbf{x}}\left(r-1\right),{\mathbf{x}}\left(r\right)\right]$). A single call of nag_interp_1d_monotonic_eval (e01bf) with $m>1$ is more efficient than several calls with $m=1$.

## Example

This example reads in values of n, x, f and d, and then calls nag_interp_1d_monotonic_eval (e01bf) to evaluate the interpolant at equally spaced points.
```function e01bf_example

fprintf('e01bf 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];

% Theses are as returned by e01be(x,f)
d = [0;
0.00055251;
0.33587;
0.34944;
0.59696;
0.060326;
0.000898335;
2.93954e-05;
0];

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]')

```
```e01bf 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
```