NAG CL Interface
e02bfc (dim1_spline_deriv_vector)
1
Purpose
e02bfc evaluates a cubic spline and up to its first three derivatives from its B-spline representation at a vector of points.
e02bfc can be used to compute the values and derivatives of cubic spline fits and interpolants produced by reference to
e01bac,
e02bac and
e02bec.
2
Specification
void |
e02bfc (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) |
|
The function may be called by the names: e02bfc, nag_fit_dim1_spline_deriv_vector or nag_fit_1dspline_deriv_vector.
3
Description
e02bfc evaluates the cubic spline
and optionally derivatives up to order
for a vector of points
, for
. It is assumed that
is represented in terms of its B-spline coefficients
, for
, and (augmented) ordered knot set
, for
,
(see
e02bac and
e02bec),
i.e.,
Here , is the number of intervals of the spline and denotes the normalized B-spline of degree (order ) defined upon the knots . The knots are the interior knots. The remaining knots, , , , and , , , are the exterior knots. The knots and are the boundaries of the spline.
Only abscissae satisfying,
will be evaluated. At a simple knot
(i.e., one satisfying
), 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
where (exactly)
knots coincide (such a point is termed a knot of multiplicity
), the values of the derivatives of order
, for
, are, in general, discontinuous. (Here
;
is not meaningful.) The maximum order of the derivatives to be evaluated
, 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)
contained in
x has an associated enclosing interval number,
either supplied or returned in
ixloc (see argument
start). A simple call to
e02bfc would set
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
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,
is determined for each
and a permutation is calculated to sort the
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
are to be evaluated over the same set of knots
.
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
e02bbc and
e02bcc, although if the enclosing interval numbers
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
and its derivatives is based upon,
-
(i)evaluating the nonzero B-splines of orders , , and by recurrence (see Cox (1972) and Cox (1978)),
-
(ii)computing all derivatives of the B-splines of order 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 and its derivatives.
The method of convex combinations is significantly faster than the recurrence based method. If higher derivatives of order or 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:
– Nag_SplineVectorSort
Input
-
On entry: indicates the completion state of the first phase of the algorithm.
- The enclosing interval numbers for the abscissae contained in x have not been determined, and you wish to use the sorted mode of vectorization.
- The enclosing interval numbers 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.
- 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 e02bfc).
- The enclosing interval numbers for the abscissae contained in x have not been determined, and you wish to use the unsorted mode of vectorization.
- The enclosing interval numbers for the abscissae contained in x have been supplied in ixloc, and you wish to use the unsorted mode of vectorization.
Constraint:
, , , or .
Additional: or should be used unless you are sure that the knot set is unchanged between calls.
-
2:
– Nag_Spline *
-
Pointer to structure of type Nag_Spline with the following members:
- n – IntegerInput
-
On entry: , where 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 to over which the spline is defined).
Constraint:
.
- lamda – double *Input
-
On entry: a pointer to which memory of size must be allocated.
must be set to the value of the th member of the complete set of knots, , for .
Constraint:
the must be in nondecreasing order with .
- c – double *Input
-
On entry: a pointer to which memory of size must be allocated. holds the coefficient
of the B-spline , for .
Under normal usage, the call to function
e02bfc will follow at least one call to
e01bac,
e02bac or
e02bec). In that case, the structure spline will have been set up correctly for input to
e02bfc. If multiple sets of B-spline co-efficients are required for the same set of knots
and the same set of abscissae
, multiple calls to
e02bfc may be made with
pointing to different coefficient sets, with
start set appropriately for efficiency.
-
3:
– Nag_DerivType
Input
-
On entry: determines the maximum order of derivatives required,
, as well as the computational behaviour when absicssae correspond exactly to interior knots.
For abscissae satisfying
or
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.
- No derivatives required. . Only right-handed computation will be used at interior knots.
- or
- Only and its first derivative are required. .
- or
- Only and its first and second derivatives are required. .
- or
- and its first, second and third derivatives are required. .
Constraint:
, , , , , or .
Additional: if left-handed computation of the spline
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
will only have an effect if at least
interior knots are identical.
-
4:
– Nag_Boolean
Input
-
On entry: indicates whether
x is supplied in a sufficiently ordered manner. If
x is sufficiently ordered
e02bfc will complete faster.
- 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, , for .
- The abscissae in x are not sufficiently ordered.
-
5:
– const double
Input
-
On entry: the abscissae
, for
. If
or
then evaluations will only be performed for these
satisfying
. Otherwise evaluation will be performed unless the corresponding element of
ixloc contains an invalid interval number. Please note that if the
is a valid interval number then no check is made that
actually lies in that interval.
Constraint:
at least one abscissa must fall between and .
-
6:
– Integer
Input/Output
-
On entry: if
,
or
, if you wish
to be evaluated,
must be the enclosing interval number
of the abscissae
(see
(1)). If you do not wish
to be evaluated, you may set the interval number to be either less than
or greater than
.
Otherwise,
ixloc need not be set.
On exit: if
,
or
,
ixloc is unchanged on exit.
Otherwise,
, contains the enclosing interval number , for the abscissa supplied in , for . Evaluations will only be performed for abscissae satisfying . If evaluation is not performed is set to if or if .
Constraint:
if
,
or
, at least one element of
ixloc must be between
and
.
-
7:
– Integer
Input
-
On entry:
, the total number of abscissae contained in
x, including any that will not be evaluated.
Constraint:
.
-
8:
– double
Output
-
Note: the dimension,
dim, of the array
s
must be at least
, see
deriv for the definition of
.
On exit: if
is valid,
will contain the (
)th derivative of
, for
and
. In particular,
will contain the approximation of
for all legal values in
x.
-
9:
– Integer
Input
-
On entry: the stride separating row elements in the two-dimensional data stored in the array
s.
Constraint:
, regardless of the acceptability of the elements of
x.
-
10:
– Integer
Input/Output
-
On entry: if
,
iwrk must be unchanged from a previous call to
e02bfc with
or
.
Otherwise,
iwrk need not be set.
Furthermore,
iwrk may be
NULL if
or
.
On exit: if
or
,
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
between the intervals derived from
.
-
11:
– Integer
Input
-
On entry: the dimension of the array
iwrk.
Constraint:
if , or , .
-
12:
– NagError *
Input/Output
-
The NAG error argument (see
Section 7 in the Introduction to the NAG Library CL Interface).
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.
entries of
x were indexed below the lower bound
.
entries of
x were indexed above the upper bound
.
- NE_ALLOC_FAIL
-
Dynamic memory allocation failed.
See
Section 3.1.2 in the Introduction to the NAG Library CL Interface for further information.
- NE_BAD_PARAM
-
On entry, argument had an illegal value.
- NE_INT
-
On entry, .
Constraint: .
On entry, .
Constraint: .
- NE_INT_2
-
On entry, .
Constraint: .
On entry, .
Constraint: .
- NE_INT_CHANGED
-
On entry,
and
nx is not consistent with the previous call to
e02bfc.
On entry,
.
Constraint:
.
- 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.
See
Section 7.5 in the Introduction to the NAG Library CL Interface for further information.
- NE_NO_LICENCE
-
Your licence key may have expired or may not have been installed correctly.
See
Section 8 in the Introduction to the NAG Library CL Interface for further information.
- NE_SPLINE_RANGE_INVALID
-
On entry, , and .
Constraint: .
- 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.
entries of
x were indexed below the lower bound
.
entries of
x were indexed above the upper bound
.
7
Accuracy
The computed value of
has negligible error in most practical situations. Specifically, this value has an absolute error bounded in modulus by
, where
is the largest in modulus of
,
,
and
, and
is an integer such that
. If
,
,
and
are all of the same sign, then the computed value of
has relative error bounded by
. For full details see
Cox (1978).
No complete error analysis is available for the computation of the derivatives of . 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
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.
If using the sorted mode of vectorization, the time required for the first phase to determine the enclosing intervals is approximately proportional to
. The time required to then generate the required permutations and interval information is
if
x is ordered sufficiently, or at worst
if
x is not ordered. The time required by the second phase is then proportional to
.
If using the unsorted mode of vectorization, the time required is proportional to if the enclosing interval numbers are not provided, or 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
in
Section 5, since to do this would result in a computation time with a linear dependency upon
instead of
. All the conditions are tested in
e02bac and
e02bec, however.
10
Example
This example fits a spline through a set of data points using
e02bec and then evaluates the spline at a set of supplied abscissae.
10.1
Program Text
10.2
Program Data
10.3
Program Results