NAG C Library Function Document

nag_1d_spline_interpolant (e01bac)

1
Purpose

nag_1d_spline_interpolant (e01bac) determines a cubic spline interpolant to a given set of data.

2
Specification

#include <nag.h>
#include <nage01.h>
void  nag_1d_spline_interpolant (Integer m, const double x[], const double y[], Nag_Spline *spline, NagError *fail)

3
Description

nag_1d_spline_interpolant (e01bac) determines a cubic spline s x , defined in the range x 1 x x m , which interpolates (passes exactly through) the set of data points x i , y i , for i=1,2,,m, where m4  and x 1 < x 2 < < x m . Unlike some other spline interpolation algorithms, derivative end conditions are not imposed. The spline interpolant chosen has m-4  interior knots λ 5 , λ 6 , , λ m , which are set to the values of x 3 , x 4 , , x m-2  respectively. This spline is represented in its B-spline form (see Cox (1975)):
s x = i=1 m c i N i x  
where N i x  denotes the normalized B-spline of degree 3, defined upon the knots λ i , λ i+1 , , λ 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 λ 1 , λ 2 , λ 3 , λ 4 , λ m+1 , λ m+2 , λ m+3  and λ m+4  to be specified; the function 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 nag_1d_spline_fit_knots (e02bac) followed by a call of that function. (For further details of nag_1d_spline_fit_knots (e02bac), see the function document.)
Values of the spline interpolant, or of its derivatives or definite integral, can subsequently be computed as detailed in Section 9.

4
References

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

5
Arguments

1:     m IntegerInput
On entry: m , the number of data points.
Constraint: m4 .
2:     x[m] const doubleInput
On entry: x[i-1]  must be set to x i , the i th data value of the independent variable x , for i=1,2,,m.
Constraint: x[i] < x[i+1] , for i=0,1,,m-2.
3:     y[m] const doubleInput
On entry: y[i-1]  must be set to y i , the i th data value of the dependent variable y , for i=1,2,,m.
4:     spline Nag_Spline *
Pointer to structure of type Nag_Spline with the following members:
nIntegerOutput
On exit: the size of the storage internally allocated to lamda. This is set to m+4 .
lamdadouble *Output
On exit: the pointer to which storage of size n is internally allocated. lamda[i-1]  contains the i th knot, for i=1,2,,m+4.
cdouble *Output
On exit: the pointer to which storage of size n-4  is internally allocated. c[i-1]  contains the coefficient c i  of the B-spline N i x , for i=1,2,,m.
Note that when the information contained in the pointers lamda and c is no longer of use, or before a new call to nag_1d_spline_interpolant (e01bac) with the same spline, you should free this storage using the NAG macro NAG_FREE. This storage will not have been allocated if this function returns with fail.code  NE_NOERROR.
5:     fail NagError *Input/Output
The NAG error argument (see Section 3.7 in How to Use the NAG Library and its Documentation).

6
Error Indicators and Warnings

NE_ALLOC_FAIL
Dynamic memory allocation failed.
NE_INT_ARG_LT
On entry, m=value.
Constraint: m4.
NE_NOT_STRICTLY_INCREASING
The sequence x is not strictly increasing: x[value] = value, x[value] = value.

7
Accuracy

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

8
Parallelism and Performance

nag_1d_spline_interpolant (e01bac) is not threaded in any implementation.

9
Further Comments

The time taken by nag_1d_spline_interpolant (e01bac) 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 x  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 m5 , the first and last arcs span the intervals x 1  to x 3  and x m-2  to x m  respectively. Additionally if m6 , the i th arc, for i=2,3,,m - 4, spans the interval x i+1  to x i+2 .
After the call
e01bac(m, x, y, &spline, &fail)
the following operations may be carried out on the interpolant s x .
The value of s x  at x = xval  can be provided in the variable sval by calling the function
e02bbc(xval, &sval, &spline, &fail)
The values of s x  and its first three derivatives at x = xval  can be provided in the array sdif of dimension 4, by the call
e02bcc(derivs, xval, sdif, &spline, &fail)
Here derivs must specify whether the left- or right-hand value of the third derivative is required (see nag_1d_spline_deriv (e02bcc) for details). The value of the integral of s x  over the range x 1  to x m  can be provided in the variable sint by
e02bdc(&spline, &sint, &fail)

10
Example

The following example program sets up data from 7 values of the exponential function in the interval 0 to 1. nag_1d_spline_interpolant (e01bac) is then called to compute a spline interpolant to these data.
The spline is evaluated by nag_1d_spline_evaluate (e02bbc), 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.

10.1
Program Text

Program Text (e01bace.c)

10.2
Program Data

None.

10.3
Program Results

Program Results (e01bace.r)