NAG Toolbox: nag_fit_1dspline_deriv_vector (e02bf)

Purpose

Syntax

Description

References

Parameters

Compulsory Input Parameters

1:     $\mathrm{start}$ – int64int32nag_int scalar

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

$\mathbf{start}=0$

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

$\mathbf{start}=1$

The enclosing interval numbers ${\mathit{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.

$\mathbf{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 nag_fit_1dspline_deriv_vector (e02bf)).

$\mathbf{start}=10$

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

$\mathbf{start}=11$

The enclosing interval numbers ${\mathit{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.

Constraint: $\mathbf{start}=0$, $1$, $2$, $10$ or $11$.

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

2:     $\mathrm{lamda}\left(\mathbf{ncap7}\right)$ – double array

$\mathbf{lamda}\left(\mathit{j}\right)$ must be set to the value of the $\mathit{j}$th member of the complete set of knots, ${\lambda }_{\mathit{j}}$, for $\mathit{j}=1,2,\dots ,\stackrel{-}{n}+7$.

Constraint: the $\mathbf{lamda}\left(j\right)$ must be in nondecreasing order with
$\mathbf{lamda}\left(\mathbf{ncap7}-3\right)>\mathbf{lamda}\left(4\right)$.

3:     $\mathrm{c}\left(\mathbf{ncap7}\right)$ – double array

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

4:     $\mathrm{deriv}$ – int64int32nag_int scalar

The order of derivatives required.

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

$\mathbf{deriv}=0$

No derivatives required.

$\mathbf{deriv}=\pm 1$

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

$\mathbf{deriv}=\pm 2$

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

$\mathbf{deriv}=\pm 3$

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

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

5:     $\mathrm{xord}$ – int64int32nag_int scalar

Indicates whether x is supplied in a sufficiently ordered manner. If x is sufficiently ordered nag_fit_1dspline_deriv_vector (e02bf) will complete faster.

$\mathbf{xord}=1$

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_{\mathit{j}+1}$, for $\mathit{j}=1,2,\dots ,\mathbf{nx}-1$.

$\mathbf{xord}\ne 1$

The abscissae in x are not sufficiently ordered.

6:     $\mathrm{x}\left(\mathbf{nx}\right)$ – double array

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

Constraint: at least one abscissa must fall between $\mathbf{lamda}\left(4\right)$ and $\mathbf{lamda}\left(\mathbf{ncap7}-3\right)$.

7:     $\mathrm{ixloc}\left(\mathbf{nx}\right)$ – int64int32nag_int array

If $\mathbf{start}=1$, $2$ or $11$, if you wish $x_j$ to be evaluated, $\mathbf{ixloc}\left(j\right)$ must be the enclosing interval number ${\mathit{ixloc}}_j$ of the abscissae $x_j$ (see (1)). 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 $\stackrel{-}{n}+4$.

Otherwise, ixloc need not be set.

Constraint: if $\mathbf{start}=1$, $2$ or $11$, at least one element of ixloc must be between $4$ and $\mathbf{ncap7}-3$.

8:     $\mathrm{iwrk}\left(\mathbf{liwrk}\right)$ – int64int32nag_int array

If $\mathbf{start}=2$, iwrk must be unchanged from a previous call to nag_fit_1dspline_deriv_vector (e02bf) with $\mathbf{start}=0$ or $1$.

Otherwise, iwrk need not be set.

Optional Input Parameters

1:     $\mathrm{ncap7}$ – int64int32nag_int scalar

Default: the dimension of the arrays lamda, c. (An error is raised if these dimensions are not equal.)

$\stackrel{-}{n}+7$, where $\stackrel{-}{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 ${\lambda }_4$ to ${\lambda }_{\stackrel{-}{n}+4}$ over which the spline is defined). Note that if nag_fit_1dspline_auto (e02be) was used to generate the knots and spline coefficients then ncap7 should contain the same value as returned in n by nag_fit_1dspline_auto (e02be).

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

2:     $\mathrm{nx}$ – int64int32nag_int scalar

Default: the dimension of the array x and the dimension of the array ixloc. (An error is raised if these dimensions are not equal.)

$n_x$, the total number of abscissae contained in x, including any that will not be evaluated.

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

3:     $\mathrm{liwrk}$ – int64int32nag_int scalar

Default: the dimension of the array iwrk.

The dimension of the array iwrk.

Constraint: if $\mathbf{start}=0$, $1$ or $2$, $\mathbf{liwrk}\ge 3+3\times \mathbf{nx}$.

Output Parameters

1:     $\mathrm{s}\left(\mathit{lds},:\right)$ – double array

The first dimension of the array s will be $\mathbf{nx}$, regardless of the acceptability of the elements of x.

The second dimension of the array s will be $\min \left(\left|\mathbf{deriv}\right|,3\right)+1$.

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

2:     $\mathrm{ixloc}\left(\mathbf{nx}\right)$ – int64int32nag_int array

If $\mathbf{start}=1$, $2$ or $11$, ixloc is unchanged on exit.

Otherwise, $\mathbf{ixloc}\left(\mathit{j}\right)$, contains the enclosing interval number ${\mathit{ixloc}}_{\mathit{j}}$, for the abscissa supplied in $\mathbf{x}\left(\mathit{j}\right)$, for $\mathit{j}=1,2,\dots ,n_x$. Evaluations will only be performed for abscissae $x_j$ satisfying ${\lambda }_4\le x_j\le {\lambda }_{\stackrel{-}{n}+4}$. If evaluation is not performed $\mathbf{ixloc}\left(j\right)$ is set to $0$ if $x_j<{\lambda }_4$ or $\stackrel{-}{n}+7$ if $x_j>{\lambda }_{\stackrel{-}{n}+4}$.

3:     $\mathrm{iwrk}\left(\mathbf{liwrk}\right)$ – int64int32nag_int array

If $\mathbf{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.

4:     $\mathrm{ifail}$ – int64int32nag_int scalar

$\mathbf{ifail}=\mathbf{0}$ unless the function detects an error (see Error Indicators and Warnings).

Error Indicators and Warnings

   $\mathbf{ifail}=1$

On entry, at least one element of x has an enclosing interval number in ixloc outside the set allowed by the provided spline.

   $\mathbf{ifail}=2$

On entry, all elements of x had enclosing interval numbers in ixloc outside the domain allowed by the provided spline.

   $\mathbf{ifail}=11$

Constraint: $\mathbf{start}=0$, $1$, $2$, $10$ or $11$.

   $\mathbf{ifail}=12$

   $\mathbf{ifail}=21$

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

   $\mathbf{ifail}=31$

Constraint: $\mathbf{lamda}\left(4\right)<\mathbf{lamda}\left(\mathbf{ncap7}-3\right)$.

   $\mathbf{ifail}=91$

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

   $\mathbf{ifail}=111$

ldsnx is too small.

   $\mathbf{ifail}=131$

liwrknx is too small.

   $\mathbf{ifail}=-99$

An unexpected error has been triggered by this routine. Please contact NAG.

   $\mathbf{ifail}=-399$

Your licence key may have expired or may not have been installed correctly.

   $\mathbf{ifail}=-999$

Dynamic memory allocation failed.

Accuracy

Further Comments

Example

Open in the MATLAB editor: e02bf_example

function e02bf_example


fprintf('e02bf example results\n\n');

% Data to fit
npts = 15;
x(1:8)    = [ 0;    0.5;   1;     1.5;  2;    2.5;   3;    4];
y(1:8)    = [-1.1; -0.372; 0.431; 1.69; 2.11; 3.1;   4.23; 4.35];
x(9:npts) = [4.5;   5;     5.5;   6;    7;    7.5;   8];
y(9:npts) = [4.81;  4.61;  4.79;  5.23; 6.35; 7.19;  7.97];

% Input parameters for fit
w(1:npts) = 1;
w(3)      = 1.5;
cstart    = 'c';
sfac      = 0.001;
nest      = int64(npts + 4);
lamda     = zeros(nest, 1);
wrk       = zeros(4*npts + 16*nest + 41, 1);
iwrk1     = zeros(nest, 1, 'int64');

% Determine the spline approximation
[n, lamda, c, fp, wrk, iwrk1, ifail] = ...
    e02be(...
          cstart, x, y, w, sfac, nest, lamda, wrk, iwrk1);

% Interpolation points
nip   = 20;
xe    = [6.5178; 7.2463; 1.0159; 7.3070; 5.0589; 0.7803; 2.2280; 4.3751; ...
         7.6601; 7.7191; 1.2609; 7.7647; 7.6573; 3.8830; 6.4022; 1.1351; ...
         3.3741; 7.3259; 6.3377; 7.6759];
xe = sort(xe);
% Input parameters for interpolation
ixloc = zeros(nip, 1, 'int64');
iwrk2 = zeros(3+3*nip, 1, 'int64');
xord  = int64(0);
start = int64(0);
deriv = int64(3);

% Evaluate the spline and derivatives
[s, ixloc, iwrk2, ifail] = e02bf(...
        start, lamda, c, deriv, xord, xe, ixloc, iwrk2);

% Output the results
fprintf('%8s%7s%10s%10s%10s%10s\n',...
        'x','ixloc','s(x)','ds/dx','d2s/dx2','d3s/dx3');
sd2 = min(abs(deriv),3) + 1;
for r = 1:nip
  if ixloc(r) >= 4 && ixloc(r) <= n
    fprintf('%8.4f%7d%10.4f%10.4f%10.4f%10.4f\n', ...
            xe(r), ixloc(r), s(r, 1:sd2));
  else
    fprintf('%8.4f%7d\n', x(r), ixloc(r));
  end
end

e02bf example results

       x  ixloc      s(x)     ds/dx   d2s/dx2   d3s/dx3
  0.7803      4    0.0067    1.6216    2.5007    7.5980
  1.0159      5    0.4747    2.4179    3.8175  -22.1715
  1.1351      5    0.7838    2.7154    1.1746  -22.1715
  1.2609      5    1.1273    2.6878   -1.6146  -22.1715
  2.2280      7    2.4751    1.9559    3.0615   -6.6690
  3.3741      9    4.4165   -0.1181   -2.0644   10.2964
  3.8830      9    4.3152    0.1646    3.1754   10.2964
  4.3751     10    4.7199    0.8519   -3.0718  -19.8662
  5.0589     12    4.6105   -0.1036    2.9075   -4.4467
  6.3377     14    5.5563    0.9931    0.3321    1.3065
  6.4022     14    5.6211    1.0172    0.4163    1.3065
  6.5178     14    5.7418    1.0741    0.5674    1.3065
  7.2463     15    6.7486    1.7074    0.4905   -2.8697
  7.3070     15    6.8531    1.7319    0.3163   -2.8697
  7.3259     15    6.8859    1.7374    0.2621   -2.8697
  7.6573     15    7.4586    1.6667   -0.6889   -2.8697
  7.6601     15    7.4633    1.6647   -0.6970   -2.8697
  7.6759     15    7.4895    1.6534   -0.7423   -2.8697
  7.7191     15    7.5602    1.6186   -0.8663   -2.8697
  7.7647     15    7.6330    1.5761   -0.9971   -2.8697