nag_fit_1dspline_deriv_vector (e02bfc) (PDF version)
e02 Chapter Contents
e02 Chapter Introduction
NAG Library Manual

NAG Library Function Document

nag_fit_1dspline_deriv_vector (e02bfc)

 Contents

    1  Purpose
    7  Accuracy

1  Purpose

nag_fit_1dspline_deriv_vector (e02bfc) evaluates a cubic spline and up to its first three derivatives from its B-spline representation at a vector of points. nag_fit_1dspline_deriv_vector (e02bfc) can be used to compute the values and derivatives of cubic spline fits and interpolants produced by reference to nag_1d_spline_interpolant (e01bac), nag_1d_spline_fit_knots (e02bac) and nag_1d_spline_fit (e02bec).

2  Specification

#include <nag.h>
#include <nage02.h>
void  nag_fit_1dspline_deriv_vector (Nag_SplineVectorSort start, Nag_Spline *spline, Nag_DerivType deriv, Nag_Boolean xord, const double x[], Integer ixloc[], Integer nx, double s[], Integer pds, Integer iwrk[], Integer liwrk, NagError *fail)

3  Description

nag_fit_1dspline_deriv_vector (e02bfc) evaluates the cubic spline sx and optionally derivatives up to order 3 for a vector of points xj, for j=1,2,,nx. It is assumed that sx is represented in terms of its B-spline coefficients ci, for i=1,2,,n-+3, and (augmented) ordered knot set λi, for i=1,2,,n-+7, (see nag_1d_spline_fit_knots (e02bac) and nag_1d_spline_fit (e02bec)), i.e.,
sx = i=1q ci Nix .  
Here q=n-+3, n- is the number of intervals of the spline and Nix denotes the normalized B-spline of degree 3 (order 4) defined upon the knots λi,λi+1,,λi+4. The knots λ5,λ6,,λn-+3 are the interior knots. The remaining knots, λ1, λ2, λ3, λ4 and λn-+4, λn-+5, λn-+6, λn+7- are the exterior knots. The knots λ4 and λn-+4 are the boundaries of the spline.
Only abscissae satisfying,
λ4 xj λn-+4 ,  
will be evaluated. At a simple knot λi (i.e., one satisfying λi-1<λi<λi+1), the third derivative of the spline is, in general, discontinuous. At a multiple knot (i.e., two or more knots with the same value), lower derivatives, and even the spline itself, may be discontinuous. Specifically, at a point x=u where (exactly) r knots coincide (such a point is termed a knot of multiplicity r), the values of the derivatives of order 4-j, for j=1,2,,r, are, in general, discontinuous. (Here 1r4; r>4 is not meaningful.) The maximum order of the derivatives to be evaluated Dord, and the left- or right-handedness of the computation when an abscissa corresponds exactly to an interior knot, are determined by the value of deriv.
Each abscissa (point at which the spline is to be evaluated) xj contained in x has an associated enclosing interval number, ixlocj either supplied or returned in ixloc (see argument start). A simple call to nag_fit_1dspline_deriv_vector (e02bfc) would set start=Nag_SplineVectorSort_Sorted and the contents of ixloc need never be set nor referenced, and the following description on modes of operation can be ignored. However, where efficiency is an important consideration, the following description will help to choose the appropriate mode of operation.
The interval numbers are used to determine which B-splines must be evaluated for a given abscissa, and are defined as
ixlocj = 0 xj < λ1 4 λ4 = xj k λk < xj < λk+1 k λ4 < λk = xj left derivatives k xj = λk+1 < λ n-+4 right derivatives or no derivatives n-+4 λn-+4 = xj >n-+7 xj > λn-+7 (1)
The algorithm has two modes of vectorization, termed here sorted and unsorted, which are selectable by the argument start.
Furthermore, if the supplied abscissae are sufficiently ordered, as indicated by the argument xord, the algorithm will take advantage of significantly faster methods for the determination of both the interval numbers and the subsequent spline evaluations.
The sorted mode has two phases, a sorting phase and an evaluation phase. This mode is recommended if there are many abscissae to evaluate relative to the number of intervals of the spline, or the abscissae are distributed relatively densely over a subsection of the spline. In the first phase, ixlocj is determined for each xj and a permutation is calculated to sort the xj by interval number. The first phase may be either partially or completely by-passed using the argument start if the enclosing segments and/or the subsequent ordering are already known a priori, for example if multiple spline coefficients splinec are to be evaluated over the same set of knots splinelamda.
In the second phase of the sorted mode, spline approximations are evaluated by segment, so that non-abscissa dependent calculations over a segment may be reused in the evaluation for all abscissae belonging to a specific segment. For example, all third derivatives of all abscissae in the same segment will be identical.
In the unsorted mode of vectorization, no a priori segment sorting is performed, and if the abscissae are not sufficiently ordered, the evaluation at an abscissa will be independent of evaluations at other abscissae; also non-abscissa dependent calculations over a segment will be repeated for each abscissa in a segment. This may be quicker if the number of abscissa is small in comparison to the number of knots in the spline, and they are distributed sparsely throughout the domain of the spline. This is effectively a direct vectorization of nag_1d_spline_evaluate (e02bbc) and nag_1d_spline_deriv (e02bcc), although if the enclosing interval numbers ixlocj are known, these may again be provided.
If the abscissae are sufficiently ordered, then once the first abscissa in a segment is known, an efficient algorithm will be used to determine the location of the final abscissa in this segment. The spline will subsequently be evaluated in a vectorized manner for all the abscissae indexed between the first and last of the current segment.
If no derivatives are required, the spline evaluation is calculated by taking convex combinations due to de Boor (1972). Otherwise, the calculation of sx and its derivatives is based upon,
(i) evaluating the nonzero B-splines of orders 1, 2, 3 and 4 by recurrence (see Cox (1972) and Cox (1978)),
(ii) computing all derivatives of the B-splines of order 4 by applying a second recurrence to these computed B-spline values (see de Boor (1972)),
(iii) multiplying the fourth-order B-spline values and their derivative by the appropriate B-spline coefficients, and summing, to yield the values of sx and its derivatives.
The method of convex combinations is significantly faster than the recurrence based method. If higher derivatives of order 2 or 3 are not required, as much computation as possible is avoided.

4  References

Cox M G (1972) The numerical evaluation of B-splines J. Inst. Math. Appl. 10 134–149
Cox M G (1978) The numerical evaluation of a spline from its B-spline representation J. Inst. Math. Appl. 21 135–143
de Boor C (1972) On calculating with B-splines J. Approx. Theory 6 50–62

5  Arguments

1:     start Nag_SplineVectorSortInput
On entry: indicates the completion state of the first phase of the algorithm.
start=Nag_SplineVectorSort_Sorted
The enclosing interval numbers ixlocj for the abscissae xj contained in x have not been determined, and you wish to use the sorted mode of vectorization.
start=Nag_SplineVectorSort_Sorted_Indexed
The enclosing interval numbers ixlocj have been determined and are provided in ixloc, however the required permutation and interval related information has not been determined and you wish to use the sorted mode of vectorization.
start=Nag_SplineVectorSort_Sorted_Indexed_Perm
You wish to use the sorted mode of vectorization, and the entire first phase has been completed, with the enclosing interval numbers supplied in ixloc, and the required permutation and interval related information provided in iwrk (from a previous call to nag_fit_1dspline_deriv_vector (e02bfc)).
start=Nag_SplineVectorSort_Unsorted
The enclosing interval numbers ixlocj for the abscissae xj contained in x have not been determined, and you wish to use the unsorted mode of vectorization.
start=Nag_SplineVectorSort_Unsorted_Indexed
The enclosing interval numbers ixlocj for the abscissae xj contained in x have been supplied in ixloc, and you wish to use the unsorted mode of vectorization.
Constraint: start=Nag_SplineVectorSort_Sorted, Nag_SplineVectorSort_Sorted_Indexed, Nag_SplineVectorSort_Sorted_Indexed_Perm, Nag_SplineVectorSort_Unsorted or Nag_SplineVectorSort_Unsorted_Indexed.
Additional: start=Nag_SplineVectorSort_Sorted or Nag_SplineVectorSort_Unsorted should be used unless you are sure that the knot set is unchanged between calls.
2:     spline Nag_Spline *
Pointer to structure of type Nag_Spline with the following members:
nIntegerInput
On entry: n - + 7 , where n -  is the number of intervals of the spline (which is one greater than the number of interior knots, i.e., the knots strictly within the range λ 4  to λ n - + 4  over which the spline is defined).
Constraint: splinen8 .
lamdadouble *Input
On entry: a pointer to which memory of size splinen must be allocated. splinelamda[k-1]  must be set to the value of the k th member of the complete set of knots, λ k , for k=1,2,, n - + 7.
Constraint: the λ k  must be in nondecreasing order with splinelamda[splinen-4] > splinelamda[3] .
cdouble *Input
On entry: a pointer to which memory of size splinen-4  must be allocated. splinec holds the coefficient c i  of the B-spline N i x , for i=1,2,, n - + 3.
Under normal usage, the call to function nag_fit_1dspline_deriv_vector (e02bfc) will follow at least one call to nag_1d_spline_interpolant (e01bac), nag_1d_spline_fit_knots (e02bac) or nag_1d_spline_fit (e02bec)). In that case, the structure spline will have been set up correctly for input to nag_fit_1dspline_deriv_vector (e02bfc). If multiple sets of B-spline co-efficients are required for the same set of knots λ and the same set of abscissae x, multiple calls to nag_fit_1dspline_deriv_vector (e02bfc) may be made with splinec pointing to different coefficient sets, with start set appropriately for efficiency.
3:     deriv Nag_DerivTypeInput
On entry: determines the maximum order of derivatives required, Dord, as well as the computational behaviour when absicssae correspond exactly to interior knots.
For abscissae satisfying xj=λ4 or xj=λn-+4 only right-handed or left-handed computation will be used respectively. For abscissae which do not coincide exactly with a knot, the handedness of the computation is immaterial.
deriv=Nag_NoDerivs
No derivatives required. Dord=0. Only right-handed computation will be used at interior knots.
deriv=Nag_LeftDerivs_1 or Nag_RightDerivs_1
Only sx and its first derivative are required. Dord=1.
deriv=Nag_LeftDerivs_2 or Nag_RightDerivs_2
Only sx and its first and second derivatives are required. Dord=2.
deriv=Nag_LeftDerivs_3 or Nag_RightDerivs_3
sx and its first, second and third derivatives are required. Dord=3.
Constraint: deriv=Nag_NoDerivs, Nag_LeftDerivs_1, Nag_RightDerivs_1, Nag_LeftDerivs_2, Nag_RightDerivs_2, Nag_LeftDerivs_3 or Nag_RightDerivs_3.
Additional: if left-handed computation of the spline s is required, a value of deriv must be chosen which computes at least the first derivative in a left-handed manner. As mentioned in Section 3, the handedness of the computation of s will only have an effect if at least 4 interior knots are identical.
4:     xord Nag_BooleanInput
On entry: indicates whether x is supplied in a sufficiently ordered manner. If x is sufficiently ordered nag_fit_1dspline_deriv_vector (e02bfc) will complete faster.
xord=Nag_TRUE
The abscissae in x are ordered at least by ascending interval, in that any two abscissae contained in the same interval are only separated by abscissae in the same interval. For example, xj<xj+1, for j=1,2,,nx-1.
xord=Nag_FALSE
The abscissae in x are not sufficiently ordered.
5:     x[nx] const doubleInput
On entry: the abscissae xj, for j=1,2,,nx. If start=Nag_SplineVectorSort_Sorted or Nag_SplineVectorSort_Unsorted then evaluations will only be performed for these xj satisfying λ4xjλn-+4. Otherwise evaluation will be performed unless the corresponding element of ixloc contains an invalid interval number. Please note that if the ixloc[j] is a valid interval number then no check is made that x[j] actually lies in that interval.
Constraint: at least one abscissa must fall between splinelamda3 and splinelamdasplinen-4.
6:     ixloc[nx] IntegerInput/Output
On entry: if start=Nag_SplineVectorSort_Sorted_Indexed, Nag_SplineVectorSort_Sorted_Indexed_Perm or Nag_SplineVectorSort_Unsorted_Indexed, if you wish xj to be evaluated, ixloc[j-1] must be the enclosing interval number ixlocj of the abscissae xj (see (1)). If you do not wish xj to be evaluated, you may set the interval number to be either less than 4 or greater than n-+4.
Otherwise, ixloc need not be set.
On exit: if start=Nag_SplineVectorSort_Sorted_Indexed, Nag_SplineVectorSort_Sorted_Indexed_Perm or Nag_SplineVectorSort_Unsorted_Indexed, ixloc is unchanged on exit.
Otherwise, ixloc[j-1], contains the enclosing interval number ixlocj, for the abscissa supplied in x[j-1], for j=1,2,,nx. Evaluations will only be performed for abscissae xj satisfying λ4xjλn-+4. If evaluation is not performed ixloc[j-1] is set to 0 if xj<λ4 or n-+7 if xj>λn-+4.
Constraint: if start=Nag_SplineVectorSort_Sorted_Indexed, Nag_SplineVectorSort_Sorted_Indexed_Perm or Nag_SplineVectorSort_Unsorted_Indexed, at least one element of ixloc must be between 4 and splinen-3.
7:     nx IntegerInput
On entry: nx, the total number of abscissae contained in x, including any that will not be evaluated.
Constraint: nx1.
8:     s[dim] doubleOutput
Note: the dimension, dim, of the array s must be at least pds×( Dord +1 ), see deriv for the definition of Dord.
On exit: if xj is valid, Sj,d will contain the (d-1)th derivative of sx, for d=1,2,,Dord+1 and j=1,2,,nx. In particular, Sj,1 will contain the approximation of sxj for all legal values in x.
9:     pds IntegerInput
On entry: the stride separating row elements in the two-dimensional data stored in the array s.
Constraint: pdsnx, regardless of the acceptability of the elements of x.
10:   iwrk[liwrk] IntegerInput/Output
On entry: if start=Nag_SplineVectorSort_Sorted_Indexed_Perm, iwrk must be unchanged from a previous call to nag_fit_1dspline_deriv_vector (e02bfc) with start=Nag_SplineVectorSort_Sorted or Nag_SplineVectorSort_Sorted_Indexed.
Otherwise, iwrk need not be set. Furthermore, iwrk may be NULL if start=Nag_SplineVectorSort_Unsorted or Nag_SplineVectorSort_Unsorted_Indexed.
On exit: if start=Nag_SplineVectorSort_Unsorted or Nag_SplineVectorSort_Unsorted_Indexed, iwrk is unchanged on exit.
Otherwise, iwrk contains the required permutation of elements of x, if any, and information related to the division of the abscissae xj between the intervals derived from splinelamda.
11:   liwrk IntegerInput
On entry: the dimension of the array iwrk.
Constraint: if start=Nag_SplineVectorSort_Sorted, Nag_SplineVectorSort_Sorted_Indexed or Nag_SplineVectorSort_Sorted_Indexed_Perm, liwrk3+3×nx.
12:   fail NagError *Input/Output
The NAG error argument (see Section 2.7 in How to Use the NAG Library and its Documentation).

6  Error Indicators and Warnings

NE_ABSCI_OUTSIDE_KNOT_INTVL
On entry, all elements of x had enclosing interval numbers in ixloc outside the domain allowed by the provided spline.
value entries of x were indexed below the lower bound value.
value entries of x were indexed above the upper bound value.
NE_ALLOC_FAIL
Dynamic memory allocation failed.
See Section 2.3.1.2 in How to Use the NAG Library and its Documentation for further information.
NE_BAD_PARAM
On entry, argument value had an illegal value.
NE_INT
On entry, nx=value.
Constraint: nx1.
On entry, splinen=value.
Constraint: splinen8.
NE_INT_2
On entry, liwrk=value.
Constraint: liwrk3×nx+3=value.
On entry, pds=value.
Constraint: pdsnx=value.
NE_INT_CHANGED
On entry, start=Nag_SplineVectorSort_Sorted_Indexed_Perm and nx is not consistent with the previous call to nag_fit_1dspline_deriv_vector (e02bfc).
On entry, nx=value.
Constraint: nx=value.
NE_INTERNAL_ERROR
An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact NAG for assistance.
An unexpected error has been triggered by this function. Please contact NAG.
See Section 2.7.6 in How to Use the NAG Library and its Documentation for further information.
NE_NO_LICENCE
Your licence key may have expired or may not have been installed correctly.
See Section 2.7.5 in How to Use the NAG Library and its Documentation for further information.
NE_SPLINE_RANGE_INVALID
On entry, splinelamda[3]=value, splinen=value and splinelamda[splinen-4]=value.
Constraint: splinelamda[3]<splinelamda[splinen-4].
NW_SOME_SOLUTIONS
On entry, at least one element of x has an enclosing interval number in ixloc outside the set allowed by the provided spline. The spline has been evaluated for all x with enclosing interval numbers inside the allowable set.
value entries of x were indexed below the lower bound value.
value entries of x were indexed above the upper bound value.

7  Accuracy

The computed value of sx has negligible error in most practical situations. Specifically, this value has an absolute error bounded in modulus by 18×cmax×machine precision, where cmax is the largest in modulus of cj, cj+1, cj+2 and cj+3, and j is an integer such that λj+3<xλj+4. If cj, cj+1, cj+2 and cj+3 are all of the same sign, then the computed value of sx has relative error bounded by 20×machine precision. For full details see Cox (1978).
No complete error analysis is available for the computation of the derivatives of sx. However, for most practical purposes the absolute errors in the computed derivatives should be small. Note that this is in comparison to the derivatives of the spline, which may or may not be comparable to the derivatives of the function that has been approximated by the spline.

8  Parallelism and Performance

nag_fit_1dspline_deriv_vector (e02bfc) 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 function. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9  Further Comments

If using the sorted mode of vectorization, the time required for the first phase to determine the enclosing intervals is approximately proportional to Onx logn-. The time required to then generate the required permutations and interval information is Onx if x is ordered sufficiently, or at worst O nx minnx,n- log minnx,n-  if x is not ordered. The time required by the second phase is then proportional to Onx.
If using the unsorted mode of vectorization, the time required is proportional to O nx logn-  if the enclosing interval numbers are not provided, or Onx  if they are provided. However, the repeated calculation of various quantities will typically make this slower than the sorted mode when the ratio of abscissae to knots is high, or the abscissae are densely distributed over a relatively small subset of the intervals of the spline.
Note: the function does not test all the conditions on the knots given in the description of splinelamda in Section 5, since to do this would result in a computation time with a linear dependency upon n- instead of logn-. All the conditions are tested in nag_1d_spline_fit_knots (e02bac) and nag_1d_spline_fit (e02bec), however.

10  Example

This example fits a spline through a set of data points using nag_1d_spline_fit (e02bec) and then evaluates the spline at a set of supplied abscissae.

10.1  Program Text

Program Text (e02bfce.c)

10.2  Program Data

Program Data (e02bfce.d)

10.3  Program Results

Program Results (e02bfce.r)


nag_fit_1dspline_deriv_vector (e02bfc) (PDF version)
e02 Chapter Contents
e02 Chapter Introduction
NAG Library Manual

© The Numerical Algorithms Group Ltd, Oxford, UK. 2016