NAG Library Function Document

nag_2d_spline_fit_grid (e02dcc)

1  Purpose

2  Specification

3  Description

4  References

5  Arguments

1:     start – Nag_StartInput

On entry: start must be set to $\mathbf{start}=\mathrm{Nag\_Cold}$ or $\mathrm{Nag\_Warm}$.

$\mathbf{start}=\mathrm{Nag\_Cold}$, (cold start)

The function will build up the knot set starting with no interior knots. No values need be assigned to $\mathbf{spline}\mathbf{\to }\mathbf{nx}$ and $\mathbf{spline}\mathbf{\to }\mathbf{ny}$ and memory will be internally allocated to $\mathbf{spline}\mathbf{\to }\mathbf{lamda}$, $\mathbf{spline}\mathbf{\to }\mathbf{mu}$, $\mathbf{spline}\mathbf{\to }\mathbf{c}$, $\mathbf{warmstartinf}\mathbf{\to }\mathbf{nag\_w}$ and $\mathbf{warmstartinf}\mathbf{\to }\mathbf{nag\_iw}$.

$\mathbf{start}=\mathrm{Nag\_Warm}$ (warm start)

The function will restart the knot-placing strategy using the knots found in a previous call of the function. In this case, all arguments except s must be unchanged from that previous call. This warm start can save much time in searching for a satisfactory value of $S$.

Constraint: $\mathbf{start}=\mathrm{Nag\_Cold}$ or $\mathrm{Nag\_Warm}$.

2:     mx – IntegerInput

On entry: $m_x$, the number of grid points along the $x$ axis.

Constraint: $\mathbf{mx}\ge 4$.

3:     x[mx] – const doubleInput

On entry: $\mathbf{x}\left[\mathit{q}-1\right]$ must be set to $x_{\mathit{q}}$, the $x$ coordinate of the $\mathit{q}$th grid point along the $x$ axis, for $\mathit{q}=1,2,\dots ,m_x$.

Constraint: $x_1<x_2<\cdots <x_{m_x}$.

4:     my – IntegerInput

On entry: $m_y$, the number of grid points along the $y$ axis.

Constraint: $\mathbf{my}\ge 4$.

5:     y[my] – const doubleInput

On entry: $\mathbf{y}\left[\mathit{r}-1\right]$ must be set to $y_{\mathit{r}}$, the $y$ coordinate of the $\mathit{r}$th grid point along the $y$ axis, for $\mathit{r}=1,2,\dots ,m_y$.

Constraint: $y_1<y_2<\cdots <y_{m_y}$.

6:     f[$\mathbf{mx}\times \mathbf{my}$] – const doubleInput

On entry: $\mathbf{f}\left[m_y\times \left(\mathit{q}-1\right)+\mathit{r}-1\right]$ must contain the data value $f_{\mathit{q},\mathit{r}}$, for $\mathit{q}=1,2,\dots ,m_x$ and $\mathit{r}=1,2,\dots ,m_y$.

7:     s – doubleInput

On entry: the smoothing factor, $S$.

If $S=0.0$, the function returns an interpolating spline.

If $S$ is smaller than machine precision, it is assumed equal to zero.

For advice on the choice of $S$, see Section 3 and Section 9.2.

Constraint: $\mathbf{s}\ge 0.0$.

8:     nxest – IntegerInput

9:     nyest – IntegerInput

On entry: an upper bound for the number of knots $n_x$ and $n_y$ required in the $x$ and $y$ directions respectively.

In most practical situations, $\mathbf{nxest}=m_x/2$ and $\mathbf{nyest}=m_y/2$ is sufficient. nxest and nyest never need to be larger than $m_x+4$ and $m_y+4$ respectively, the numbers of knots needed for interpolation ($S=0.0$). See also Section 9.4.

Constraint: $\mathbf{nxest}\ge 8$ and $\mathbf{nyest}\ge 8$.

10:   fp – double *Output

On exit: the sum of squared residuals, $\theta$, of the computed spline approximation. If $\mathbf{fp}=0.0$, this is an interpolating spline. fp should equal $S$ within a relative tolerance of 0.001 unless $\mathbf{spline}\mathbf{\to }\mathbf{nx}=\mathbf{spline}\mathbf{\to }\mathbf{ny}=8$, when the spline has no interior knots and so is simply a bicubic polynomial. For knots to be inserted, $S$ must be set to a value below the value of fp produced in this case.

11:   warmstartinf – Nag_Comm *

Pointer to structure of type Nag_Comm with the following members:

nag_w – double *Input

On entry: if the warm start option is used, the values $\mathbf{nag\_w}\left[0\right]$,$\dots$,$\mathbf{nag\_w}\left[3\right]$ must be left unchanged from the previous call.

nag_iw – Integer *Input

On entry: if the warm start option is used, the values $\mathbf{nag\_iw}\left[0\right]$,$\dots$,$\mathbf{nag\_iw}\left[2\right]$ must be left unchanged from the previous call.

Note that when the information contained in the pointers $\mathbf{nag\_w}$ and $\mathbf{nag\_iw}$ is no longer of use, or before a new call to nag_2d_spline_fit_grid (e02dcc) with the same warmstartinf, you should free this storage using the NAG macros NAG_FREE. This storage will have been allocated only if this function returns with $\mathbf{fail}\mathbf{.}\mathbf{code}=\mathrm{NE\_NOERROR}$, NE_SPLINE_COEFF_CONV, or NE_NUM_KNOTS_2D_GT_RECT.

12:   spline – Nag_2dSpline *

Pointer to structure of type Nag_2dSpline with the following members:

nx – IntegerInput/Output

On entry: if the warm start option is used, the value of $\mathbf{nx}$ must be left unchanged from the previous call.

On exit: the total number of knots, $n_x$, of the computed spline with respect to the $x$ variable.

lamda – double *Input/Output

On entry: a pointer to which if $\mathbf{start}=\mathrm{Nag\_Cold}$, memory of size nxest is internally allocated. If the warm start option is used, the values $\mathbf{lamda}\left[0\right],\mathbf{lamda}\left[1\right],\dots ,\mathbf{lamda}\left[\mathbf{nx}-1\right]$ must be left unchanged from the previous call.

On exit: $\mathbf{lamda}$ contains the complete set of knots ${\lambda }_i$ associated with the $x$ variable, i.e., the interior knots $\mathbf{lamda}\left[4\right],\mathbf{lamda}\left[5\right],\dots ,\mathbf{lamda}\left[\mathbf{nx}-5\right]$ as well as the additional knots $\mathbf{lamda}\left[0\right]=\mathbf{lamda}\left[1\right]=\mathbf{lamda}\left[2\right]=\mathbf{lamda}\left[3\right]=\mathbf{x}\left[0\right]$ and $\mathbf{lamda}\left[\mathbf{nx}-4\right]=\mathbf{lamda}\left[\mathbf{nx}-3\right]=\mathbf{lamda}\left[\mathbf{nx}-2\right]=\mathbf{lamda}\left[\mathbf{nx}-1\right]=\mathbf{x}\left[\mathbf{mx}-1\right]$ needed for the B-spline representation.

ny – IntegerInput/Output

On entry: if the warm start option is used, the value of $\mathbf{ny}$ must be left unchanged from the previous call.

On exit: the total number of knots, $n_y$, of the computed spline with respect to the $y$ variable.

mu – double *Input/Output

On entry: a pointer to which if $\mathbf{start}=\mathrm{Nag\_Cold}$, memory of size nyest is internally allocated. If the warm start option is used, the values $\mathbf{mu}\left[0\right],\mathbf{mu}\left[1\right],\dots ,\mathbf{mu}\left[\mathbf{ny}-1\right]$ must be left unchanged from the previous call.

On exit: $\mathbf{mu}$ contains the complete set of knots ${\mu }_i$ associated with the $y$ variable, i.e., the interior knots $\mathbf{mu}\left[4\right]$, $\mathbf{mu}\left[5\right]$, $\dots$, $\mathbf{mu}\left[\mathbf{ny}-5\right]$ as well as the additional knots $\mathbf{mu}\left[0\right]=\mathbf{mu}\left[1\right]=\mathbf{mu}\left[2\right]=\mathbf{mu}\left[3\right]=\mathbf{y}\left[0\right]$ and $\mathbf{mu}\left[\mathbf{ny}-4\right]=\mathbf{mu}\left[\mathbf{ny}-3\right]=\mathbf{mu}\left[\mathbf{ny}-2\right]=\mathbf{mu}\left[\mathbf{ny}-1\right]=\mathbf{y}\left[\mathbf{my}-1\right]$ needed for the B-spline representation.

c – double *Output

On exit: a pointer to which if $\mathbf{start}=\mathrm{Nag\_Cold}$, memory of size $\left(\mathbf{nxest}-4\right)\times \left(\mathbf{nyest}-4\right)$ is internally allocated. $\mathbf{c}\left[\left(n_y-4\right)\times \left(i-1\right)+j-1\right]$ is the coefficient $c_{ij}$ defined in Section 3.

Note that when the information contained in the pointers $\mathbf{lamda}$, $\mathbf{mu}$ and $\mathbf{c}$ is no longer of use, or before a new call to nag_2d_spline_fit_grid (e02dcc) with the same spline, you should free this storage using the NAG macro NAG_FREE. This storage will have been allocated only if this function returns with $\mathbf{fail}\mathbf{.}\mathbf{code}=\mathrm{NE\_NOERROR}$, NE_SPLINE_COEFF_CONV, or NE_NUM_KNOTS_2D_GT_RECT.

13:   fail – NagError *Input/Output

The NAG error argument (see Section 3.6 in the Essential Introduction).

6  Error Indicators and Warnings

If the function fails with an error exit of NE_NUM_KNOTS_2D_GT_RECT or NE_SPLINE_COEFF_CONV, then a spline approximation is returned, but it fails to satisfy the fitting criterion (see (2) and (3)) – perhaps by only a small amount, however.

NE_ALLOC_FAIL

Dynamic memory allocation failed.

NE_BAD_PARAM

On entry, argument start had an illegal value.

NE_ENUMTYPE_WARM

$\mathbf{start}=\mathrm{Nag\_Warm}$ at the first call of this function. start must be set to$\mathbf{start}=\mathrm{Nag\_Cold}$ at the first call.

NE_INT_ARG_LT

On entry, $\mathbf{mx}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{mx}\ge 4$.

On entry, $\mathbf{my}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{my}\ge 4$.

On entry, $\mathbf{nxest}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{nxest}\ge 8$.

On entry, $\mathbf{nyest}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{nyest}\ge 8$.

NE_NOT_STRICTLY_INCREASING

The sequence x is not strictly increasing: $\mathbf{x}\left[⟨\mathit{\text{value}}⟩\right]=⟨\mathit{\text{value}}⟩$, $\mathbf{x}\left[⟨\mathit{\text{value}}⟩\right]=⟨\mathit{\text{value}}⟩$.
The sequence y is not strictly increasing: $\mathbf{y}\left[⟨\mathit{\text{value}}⟩\right]=⟨\mathit{\text{value}}⟩$, $\mathbf{y}\left[⟨\mathit{\text{value}}⟩\right]=⟨\mathit{\text{value}}⟩$.

NE_NUM_KNOTS_2D_GT_RECT

The number of knots required is greater than allowed by nxest or nyest, $\mathbf{nxest}=⟨\mathit{\text{value}}⟩$, $\mathbf{nyest}=⟨\mathit{\text{value}}⟩$. Possibly s is too small, especially if nxest, $\mathbf{nyest}>\mathbf{mx}$/2, my/2. $\mathbf{s}=⟨\mathit{\text{value}}⟩$, $\mathbf{mx}=⟨\mathit{\text{value}}⟩$, $\mathbf{my}=⟨\mathit{\text{value}}⟩$.

NE_REAL_ARG_LT

On entry, s must not be less than 0.0: $\mathbf{s}=⟨\mathit{\text{value}}⟩$.

NE_SF_D_K_CONS

On entry, $\mathbf{s}=⟨\mathit{\text{value}}⟩$, $\mathbf{nxest}=⟨\mathit{\text{value}}⟩$, $\mathbf{mx}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{nxest}\ge \mathbf{mx}+4$ when $\mathbf{s}=0.0$.

On entry, $\mathbf{s}=⟨\mathit{\text{value}}⟩$, $\mathbf{nyest}=⟨\mathit{\text{value}}⟩$, $\mathbf{my}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{nyest}\ge \mathbf{mx}+4$ when $\mathbf{s}=0.0$.

NE_SPLINE_COEFF_CONV

The iterative process has failed to converge. Possibly s is too small: $\mathbf{s}=⟨\mathit{\text{value}}⟩$.

7  Accuracy

8  Parallelism and Performance

9  Further Comments

9.1  Timing

9.2  Weighting of Data Points

9.3  Choice of s

9.4  Choice of nxest and nyest

9.5  Outline of Method Used

9.6  Evaluation of Computed Spline

e02dec(n, tx, ty, ff, &spline, &fail)

e02dfc(kx, ky, tx, ty, fg, &spline, &fail)

10  Example

10.1  Program Text

Program Text (e02dcce.c)

10.2  Program Data

Program Data (e02dcce.d)

10.3  Program Results

Program Results (e02dcce.r)