naginterfaces.library.fit.dim1_​spline_​deriv_​vector

naginterfaces.library.fit.dim1_spline_deriv_vector(start, lamda, c, deriv, xord, x, ixloc, iwrk=None)

dim1_spline_deriv_vector evaluates a cubic spline and up to its first three derivatives from its B-spline representation at a vector of points. dim1_spline_deriv_vector can be used to compute the values and derivatives of cubic spline fits and interpolants produced by reference to interp.dim1_spline, dim1_spline_knots() and dim1_spline_auto().

For full information please refer to the NAG Library document for e02bf

https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/e02/e02bff.html

Parameters

startint

Indicates the completion state of the first phase of the algorithm.

$start=0$

The enclosing interval numbers ${\text{ixloc}}_j$ for the abscissae $x_j$ contained in $x$ have not been determined, and you wish to use the sorted mode of vectorization.

$start=1$

The enclosing interval numbers ${\text{ixloc}}_j$ 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=2$

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 dim1_spline_deriv_vector).

$start=10$

The enclosing interval numbers ${\text{ixloc}}_j$ for the abscissae $x_j$ contained in $x$ have not been determined, and you wish to use the unsorted mode of vectorization.

$start=11$

The enclosing interval numbers ${\text{ixloc}}_j$ for the abscissae $x_j$ contained in $x$ have been supplied in $ixloc$, and you wish to use the unsorted mode of vectorization.

Additional: $start=0$ or $10$ should be used unless you are sure that the knot set is unchanged between calls.

lamdafloat, array-like, shape $\left(\text{ncap7}\right)$

$lamda[\text{j}-1]$ must be set to the value of the $\text{j}$th member of the complete set of knots, ${\lambda }_{\text{j}}$, for $\text{j}=1,2,\dots ,\overline{n}+7$.

cfloat, array-like, shape $\left(\text{ncap7}\right)$

The coefficient $c_{\text{i}}$ of the B-spline $N_{\text{i}}\left(x\right)$, for $\text{i}=1,2,\dots ,\overline{n}+3$. The remaining elements of the array are not referenced.

derivint

Determines the maximum order of derivatives required, $D_{ord}$.

If $deriv<0$ left derivatives are calculated, otherwise right derivatives are calculated. For abscissae satisfying $x_j={\lambda }_4$ or $x_j={\lambda }_{\overline{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=0$

No derivatives required.

$deriv=\pm 1$

Only $s\left(x\right)$ and its first derivative are required.

$deriv=\pm 2$

Only $s\left(x\right)$ and its first and second derivatives are required.

$deriv=\pm 3$

$s\left(x\right)$ and its first, second and third derivatives are required.

Note: if $\left|deriv\right|$ is greater than $3$ only the derivatives up to and including $3$ will be returned.

xordint

Indicates whether $x$ is supplied in a sufficiently ordered manner. If $x$ is sufficiently ordered dim1_spline_deriv_vector will complete faster.

$xord\ne 0$

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, and the intervals are arranged in ascending order. For example, $x_j<x_{\text{j}+1}$, for $\text{j}=1,2,\dots ,\text{nx}-1$.

$xord=0$

The abscissae in $x$ are not sufficiently ordered.

xfloat, array-like, shape $\left(\text{nx}\right)$

The abscissae $x_{\text{j}}$, for $\text{j}=1,2,\dots ,n_x$. If $start=0$ or $10$ then evaluations will only be performed for these $x_j$ satisfying ${\lambda }_4\le x_j\le {\lambda }_{\overline{n}+4}$. Otherwise evaluation will be performed unless the corresponding element of $ixloc$ contains an invalid interval number. Please note that if the $ixloc\left[j\right]$ is a valid interval number then no check is made that $x\left[j\right]$ actually lies in that interval.

ixlocint, array-like, shape $\left(\text{nx}\right)$

If $start=1$, $2$ or $11$, if you wish $x_j$ to be evaluated, $ixloc[j-1]$ must be the enclosing interval number ${\text{ixloc}}_j$ of the abscissae $x_j$ (see [equation]). If you do not wish $x_j$ to be evaluated, you may set the interval number to be either less than $4$ or greater than $\overline{n}+4$.

Otherwise, $ixloc$ need not be set.

iwrkNone or int, array-like, shape $\left(\text{liwrk}\right)$, optional

If $start=2$, $iwrk$ must be unchanged from a previous call to dim1_spline_deriv_vector with $start=0$ or $1$.

Otherwise, $iwrk$ need not be set.

Returns

ixlocint, ndarray, shape $\left(\text{nx}\right)$

If $start=1$, $2$ or $11$, $ixloc$ is unchanged on exit.

Otherwise, $ixloc[\text{j}-1]$, contains the enclosing interval number ${\text{ixloc}}_{\text{j}}$, for the abscissa supplied in $x[\text{j}-1]$, for $\text{j}=1,2,\dots ,n_x$.

Evaluations will only be performed for abscissae $x_j$ satisfying ${\lambda }_4\le x_j\le {\lambda }_{\overline{n}+4}$.

If evaluation is not performed $ixloc[j-1]$ is set to $0$ if $x_j<{\lambda }_4$ or $\overline{n}+7$ if $x_j>{\lambda }_{\overline{n}+4}$.

sfloat, ndarray, shape $(\text{nx},min(\left|deriv\right|,3)+1)$

If $x_j$ is valid, $s[\text{j}-1,\text{d}-1]$ will contain the ($\text{d}-1$)th derivative of $s\left(x\right)$, for $\text{j}=1,2,\dots ,n_x$, for $\text{d}=1,2,\dots ,D_{ord}+1$. In particular, $s[j-1,0]$ will contain the approximation of $s\left(x_j\right)$ for all legal values in $x$.

iwrkNone or int, ndarray, shape $\left(\text{liwrk}\right)$

If $start=10$ or $11$, $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 $x_j$ between the intervals derived from $lamda$.

Raises

NagValueError

(errno $2$)

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⟩$.

(errno $11$)

On entry, $start=⟨value⟩$.

Constraint: $start=0$, $1$, $2$, $10$ or $11$.

(errno $12$)

On entry, $start=2$ and $\text{nx}$ is not consistent with the previous call to dim1_spline_deriv_vector.

On entry, $\text{nx}=⟨value⟩$.

Constraint: $\text{nx}=⟨value⟩$.

(errno $21$)

On entry, $\text{ncap7}=⟨value⟩$.

Constraint: $\text{ncap7}\ge 8$.

(errno $31$)

On entry, $lamda\left[3\right]=⟨value⟩$, $\text{ncap7}=⟨value⟩$ and $lamda[\text{ncap7}-4]=⟨value⟩$.

Constraint: $lamda\left[3\right]<lamda[\text{ncap7}-4]$.

(errno $91$)

On entry, $\text{nx}=⟨value⟩$.

Constraint: $\text{nx}\ge 1$.

(errno $131$)

On entry, $\text{liwrk}=⟨value⟩$.

Constraint: $\text{liwrk}\ge 3\times \text{nx}+3=⟨value⟩$.

Warns

NagAlgorithmicWarning

(errno $1$)

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⟩$.

Notes

dim1_spline_deriv_vector evaluates the cubic spline $s\left(x\right)$ and optionally derivatives up to order $3$ for a vector of points $x_{\text{j}}$, for $\text{j}=1,2,\dots ,n_x$. It is assumed that $s\left(x\right)$ is represented in terms of its B-spline coefficients $c_{\text{i}}$, for $\text{i}=1,2,\dots ,\overline{n}+3$, and (augmented) ordered knot set ${\lambda }_{\text{i}}$, for $\text{i}=1,2,\dots ,\overline{n}+7$, (see dim1_spline_knots() and dim1_spline_auto()), i.e.,

$$s\left(x\right)=\sum _{i=1}^q{c}_i{N}_i\left(x\right)\text{.}$$

Here $q=\overline{n}+3$, $\overline{n}$ is the number of intervals of the spline and $N_i\left(x\right)$ denotes the normalized B-spline of degree $3$ (order $4$) defined upon the knots ${\lambda }_i,{\lambda }_{i+1},\dots ,{\lambda }_{i+4}$. The knots ${\lambda }_5,{\lambda }_6,\dots ,{\lambda }_{\overline{n}+3}$ are the interior knots. The remaining knots, ${\lambda }_1$, ${\lambda }_2$, ${\lambda }_3$, ${\lambda }_4$ and ${\lambda }_{\overline{n}+4}$, ${\lambda }_{\overline{n}+5}$, ${\lambda }_{\overline{n}+6}$, ${\lambda }_{\overline{n+7}}$ are the exterior knots. The knots ${\lambda }_4$ and ${\lambda }_{\overline{n}+4}$ are the boundaries of the spline.

Only abscissae satisfying,

$${\lambda }_4\le x_j\le {\lambda }_{\overline{n}+4}\text{,}$$

will be evaluated. At a simple knot ${\lambda }_i$ (i.e., one satisfying ${\lambda }_{i-1}<{\lambda }_i<{\lambda }_{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-\text{j}$, for $\text{j}=1,2,\dots ,r$, are, in general, discontinuous. (Here $1\le r\le 4$; $r>4$ is not meaningful.) The maximum order of the derivatives to be evaluated $D_{ord}$, 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) $x_j$ contained in $x$ has an associated enclosing interval number, ${\text{ixloc}}_j$ either supplied or returned in $ixloc$ (see argument $start$). A simple call to dim1_spline_deriv_vector would set $start=0$ 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

$$\begin{array}{c}{\text{ixloc}}_j=\left(\begin{array}{ccc}\le 0& x_j<{\lambda }_1& \\ 4& {\lambda }_4=x_j& \\ k& {\lambda }_k<x_j<{\lambda }_{k+1}& \\ k& {\lambda }_4<{\lambda }_k=x_j& \text{left derivatives}\\ k& x_j={\lambda }_{k+1}<{\lambda }_{\overline{n}+4}& \text{right derivatives or no derivatives}\\ \overline{n}+4& {\lambda }_{\overline{n}+4}=x_j& \\ >\overline{n}+7& x_j>{\lambda }_{\overline{n}+7}& \end{array}\right)\end{array}$$

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, ${\text{ixloc}}_j$ is determined for each $x_j$ and a permutation is calculated to sort the $x_j$ 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 $c$ are to be evaluated over the same set of knots $lamda$.

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 dim1_spline_eval() and dim1_spline_deriv(), although if the enclosing interval numbers ${\text{ixloc}}_j$ 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 $s\left(x\right)$ and its derivatives is based upon,

1. evaluating the nonzero B-splines of orders $1$, $2$, $3$ and $4$ by recurrence (see Cox (1972) and Cox (1978)),

2. 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)),

3. multiplying the fourth-order B-spline values and their derivative by the appropriate B-spline coefficients, and summing, to yield the values of $s\left(x\right)$ 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.

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