# NAG CPP Interfacenagcpp::interp::dim1_spline (e01ba)

## 1Purpose

dim1_spline determines a cubic spline interpolant to a given set of data.

## 2Specification

```#include "e01/nagcpp_e01ba.hpp"
```
```template <typename X, typename Y, typename LAMDA, typename C>

void function dim1_spline(const X &x, const Y &y, LAMDA &&lamda, C &&c, OptionalE01BA opt)```
```template <typename X, typename Y, typename LAMDA, typename C>

void function dim1_spline(const X &x, const Y &y, LAMDA &&lamda, C &&c)```

## 3Description

dim1_spline determines a cubic spline $s\left(x\right)$, defined in the range ${x}_{1}\le x\le {x}_{m}$, which interpolates (passes exactly through) the set of data points $\left({x}_{\mathit{i}},{y}_{\mathit{i}}\right)$, for $\mathit{i}=1,2,\dots ,m$, where $m\ge 4$ and ${x}_{1}<{x}_{2}<\cdots <{x}_{m}$. Unlike some other spline interpolation algorithms, derivative end conditions are not imposed. The spline interpolant chosen has $m-4$ interior knots ${\lambda }_{5},{\lambda }_{6},\dots ,{\lambda }_{m}$, which are set to the values of ${x}_{3},{x}_{4},\dots ,{x}_{m-2}$ respectively. This spline is represented in its B-spline form (see Cox (1975)):
 $s(x)=∑i=1mciNi(x),$
where ${N}_{i}\left(x\right)$ denotes the normalized B-spline of degree $3$, defined upon the knots ${\lambda }_{i},{\lambda }_{i+1},\dots ,{\lambda }_{i+4}$, and ${c}_{i}$ denotes its coefficient, whose value is to be determined by the function.
The use of B-splines requires eight additional knots ${\lambda }_{1}$, ${\lambda }_{2}$, ${\lambda }_{3}$, ${\lambda }_{4}$, ${\lambda }_{m+1}$, ${\lambda }_{m+2}$, ${\lambda }_{m+3}$ and ${\lambda }_{m+4}$ to be specified; dim1_spline sets the first four of these to ${x}_{1}$ and the last four to ${x}_{m}$.
The algorithm for determining the coefficients is as described in Cox (1975) except that $QR$ factorization is used instead of $LU$ decomposition. The implementation of the algorithm involves setting up appropriate information for the related function e02baf (no CPP interface) followed by a call of that function. (See e02baf (no CPP interface) for further details.)
Values of the spline interpolant, or of its derivatives or definite integral, can subsequently be computed as detailed in Section 9.

## 4References

Cox M G (1975) An algorithm for spline interpolation J. Inst. Math. Appl. 15 95–108
Cox M G (1977) A survey of numerical methods for data and function approximation The State of the Art in Numerical Analysis (ed D A H Jacobs) 627–668 Academic Press

## 5Arguments

1: $\mathbf{x}\left({\mathbf{m}}\right)$double array Input
On entry: ${\mathbf{x}}\left(\mathit{i}-1\right)$ must be set to ${x}_{\mathit{i}}$, the $\mathit{i}$th data value of the independent variable $x$, for $\mathit{i}=1,2,\dots ,m$.
Constraint: ${\mathbf{x}}\left(\mathit{i}-1\right)<{\mathbf{x}}\left(\mathit{i}\right)$, for $\mathit{i}=1,2,\dots ,{\mathbf{m}}-1$.
2: $\mathbf{y}\left({\mathbf{m}}\right)$double array Input
On entry: ${\mathbf{y}}\left(\mathit{i}-1\right)$ must be set to ${y}_{\mathit{i}}$, the $\mathit{i}$th data value of the dependent variable $y$, for $\mathit{i}=1,2,\dots ,m$.
3: $\mathbf{lamda}\left({\mathbf{m}}+4\right)$double array Output
On exit: the value of ${\lambda }_{\mathit{i}}$, the $\mathit{i}$th knot, for $\mathit{i}=1,2,\dots ,m+4$.
4: $\mathbf{c}\left({\mathbf{m}}+4\right)$double array Output
On exit: the coefficient ${c}_{\mathit{i}}$ of the B-spline ${N}_{\mathit{i}}\left(x\right)$, for $\mathit{i}=1,2,\dots ,m$. The remaining elements of the array are not used.
5: $\mathbf{opt}$OptionalE01BA Input/Output
Optional parameter container, derived from Optional.

1: $\mathbf{m}$
$m$, the number of data points.
2: $\mathbf{lck}$
The dimension of the arrays lamda and c.

## 6Exceptions and Warnings

Errors or warnings detected by the function:
All errors and warnings have an associated numeric error code field, errorid, stored either as a member of the thrown exception object (see errorid), or as a member of opt.ifail, depending on how errors and warnings are being handled (see Error Handling for more details).
Raises: ErrorException
$\mathbf{errorid}=1$
On entry, ${\mathbf{lck}}=⟨\mathit{value}⟩$ and ${\mathbf{m}}=⟨\mathit{value}⟩$.
Constraint: ${\mathbf{lck}}\ge {\mathbf{m}}+4$.
$\mathbf{errorid}=1$
On entry, ${\mathbf{m}}=⟨\mathit{value}⟩$.
Constraint: ${\mathbf{m}}\ge 4$.
$\mathbf{errorid}=2$
On entry, $I=⟨\mathit{value}⟩$, ${\mathbf{x}}\left[I-1\right]=⟨\mathit{value}⟩$
and ${\mathbf{x}}\left[I-2\right]=⟨\mathit{value}⟩$.
Constraint: ${\mathbf{x}}\left[I-1\right]>{\mathbf{x}}\left[I-2\right]$.
$\mathbf{errorid}=10601$
On entry, argument $⟨\mathit{\text{value}}⟩$ must be a vector of size $⟨\mathit{\text{value}}⟩$ array.
Supplied argument has $⟨\mathit{\text{value}}⟩$ dimensions.
$\mathbf{errorid}=10601$
On entry, argument $⟨\mathit{\text{value}}⟩$ must be a vector of size $⟨\mathit{\text{value}}⟩$ array.
Supplied argument was a vector of size $⟨\mathit{\text{value}}⟩$.
$\mathbf{errorid}=10601$
On entry, argument $⟨\mathit{\text{value}}⟩$ must be a vector of size $⟨\mathit{\text{value}}⟩$ array.
The size for the supplied array could not be ascertained.
$\mathbf{errorid}=10602$
On entry, the raw data component of $⟨\mathit{\text{value}}⟩$ is null.
$\mathbf{errorid}=10603$
On entry, unable to ascertain a value for $⟨\mathit{\text{value}}⟩$.
$\mathbf{errorid}=-99$
An unexpected error has been triggered by this routine.
$\mathbf{errorid}=-399$
Your licence key may have expired or may not have been installed correctly.
$\mathbf{errorid}=-999$
Dynamic memory allocation failed.

## 7Accuracy

The rounding errors incurred are such that the computed spline is an exact interpolant for a slightly perturbed set of ordinates ${y}_{i}+\delta {y}_{i}$. The ratio of the root-mean-square value of the $\delta {y}_{i}$ to that of the ${y}_{i}$ is no greater than a small multiple of the relative machine precision.

## 8Parallelism and Performance

Please see the description for the underlying computational routine in this section of the FL Interface documentation.

The time taken by dim1_spline is approximately proportional to $m$.
All the ${x}_{i}$ are used as knot positions except ${x}_{2}$ and ${x}_{m-1}$. This choice of knots (see Cox (1977)) means that $s\left(x\right)$ is composed of $m-3$ cubic arcs as follows. If $m=4$, there is just a single arc space spanning the whole interval ${x}_{1}$ to ${x}_{4}$. If $m\ge 5$, the first and last arcs span the intervals ${x}_{1}$ to ${x}_{3}$ and ${x}_{m-2}$ to ${x}_{m}$ respectively. Additionally if $m\ge 6$, the $\mathit{i}$th arc, for $\mathit{i}=2,3,\dots ,m-4$, spans the interval ${x}_{\mathit{i}+1}$ to ${x}_{\mathit{i}+2}$.
After calling dim1_spline the following operations may be carried out on the interpolant $s\left(x\right)$.
The value of $s\left(x\right)$ at $x={\mathbf{x}}$ can be provided in the real variable s by calling dim1_​spline_​eval.
The values of $s\left(x\right)$ and its first three derivatives at $x={\mathbf{x}}$ can be provided in the real array s of dimension $4$, by calling dim1_​spline_​deriv.
In the call to dim1_​spline_​deriv, left must specify whether the left- or right-hand value of the third derivative is required (see e02bcf (no CPP interface) for details).
The value of the integral of $s\left(x\right)$ over the range ${x}_{1}$ to ${x}_{m}$ can be provided in the real variable dint by calling dim1_​spline_​integ.

## 10Example

This example sets up data from $7$ values of the exponential function in the interval $0$ to $1$. dim1_spline is then called to compute a spline interpolant to these data.
The spline is evaluated by dim1_​spline_​eval, at the data points and at points halfway between each adjacent pair of data points, and the spline values and the values of ${e}^{x}$ are printed out.
 Source File Data Results ex_e01ba.cpp None ex_e01ba.r