#include <AMA.h>

Functions
long int	AMA_MltvMonoInterp (AMA_OPTIONS options, long int nind, long int n, double x, double z, long int degree, AMA_SPLINE *spline)
	Monotonic Interpolation of Multivariate Data More...

Function Documentation

long int AMA_MltvMonoInterp	(	AMA_OPTIONS *	options,
		long int	nind,
		long int	n,
		double **	x,
		double *	z,
		long int *	degree,
		AMA_SPLINE **	spline
	)

Monotonic Interpolation of Multivariate Data

This function employs cnspla to compute a spline interpolant of independent variable data ${\bf X}\in{\rm R}^n$ and dependent variable data ${\bf Z}\in{\rm R}^1$ . For a given set of independent variable data ${\bf X}_\ell=(x_{1,\ell},\cdots,x_{n,\ell})$ and dependent variable data $z_\ell$ , for $\ell=1,\ldots,N$ , this function computes the spline

$s({\bf X}) = \sum_{j_n=1}^{m_n}\cdots\sum_{j_1=1}^{m_1}\alpha_{j_1,\ldots,j_n}B_{d_1,j_1}(x_1|{\bf\Lambda}_1)\cdots B_{d_n,j_n}(x_n|{\bf\Lambda_n})$

that minimizes

$F^{(2)}(s({\bf X})) = \sum_{k=1}^n\left[\int_R\left(\partial^2 s({\bf X})\over\partial^2 x_k\right)^2dR + 2.0\sum_{l=k+1}^n\int_R\left(\partial^2 s({\bf X})\over\partial x_k \partial x_l\right)^2dR\right]$

subject to the interpolation constraints

$s({\bf X}_\ell) = z_\ell$

for $\ell=1,\ldots,N$ . The integration region $R = [x^L_1,x^U_1] \times [x^L_2,x^U_2] \times\cdots\times [x^L_n,x^U_n]$ where $x^L_k=\min_\ell\lbrace{x_{k,\ell}\rbrace}$ and $x^U_k=\max_\ell\lbrace{x_{k,\ell}\rbrace}$ , for $1\le k\le n$ . This function also imposes constraints on the first order partials ${\partial s({\bf X})\over \partial x_k}$ for all $1\le k\le n$ . These constraints are known as the local monotonicity constraints and they are defined by AMA_MltvConreg().

In the above definition of $s({\bf X})$ the $\alpha_{j_1,\ldots,j_n}$ , for $j_k=1,\ldots,m_k$ and $1\le k\le n$ , are the coefficients of the tensor product B-splines

$\Phi_{j_1,\ldots,j_n}({\bf X}) = B_{d_1,j_1}(x_1|{\bf\Lambda}_1)\cdots B_{d_n,j_n}(x_n|{\bf\Lambda}_n)$

where $B_{d_k,j_k}(x_k|{\bf\Lambda}_k)$ are the $m_k$ univariate B-splines of degree $1 \le d_k\le 5$ defined by the knot vector ${\bf\Lambda}_k\in{\rm R}^{M_k}$ . The knot vectors ${\bf\Lambda}_k$ are

${\bf\Lambda}_k = ( \lambda_{k,1},\cdots,\lambda_{k,d_k+1}, \lambda_{k,d_k+2}, \cdots, \lambda_{k,m_k}, \lambda_{k,m_k+1},\cdots,\lambda_{k,m_k+d_k+1} )^T$

and they depend on the independent variable data, the degree $d_k$ and the continuity of the spline at the interior data points. They are based on the rectilinear grid $(x^g_{1,1},x^g_{1,2},\cdots,x^g_{1,n^g_1-1},x^g_{1,n^g_1})\times\cdots\times(x^g_{n,1},x^g_{n,2},\cdots,x^g_{n,n^g_n-1},x^g_{n,n^g_n})$ upon which the independent variable data lies and they are defined by AMA_LamdaMonoInterp(). That is, the knot vector ${\bf\Lambda}_k$ is defined by AMA_LamdaMonoInterp() based on the points $(x^g_{k,1},x^g_{k,2},\cdots,x^g_{k,n^g_k-1},x^g_{k,n^g_k})$ .

Additionally, the spline $s({\bf X})$ is subject to the bounds

$\alpha_l \le s({\bf X}) \le \alpha_u$

where $\alpha_l=-\alpha_\infty$ , $\alpha_u=\alpha_\infty$ and $\alpha_\infty$ equals AMA_SplineInfbnd(). By default the spline is unbounded but finite bounds can be set with AMA_OptionsSetBounds(). If the bounds specified with AMA_OptionsSetBounds() can not be satisfied in conjunction with the aforementioned approximation and local monotonicity constraints, then AMA_MltvMonoApprox() imposes the bounds

$\tilde\alpha_l \le s({\bf X}) \le \tilde\alpha_u$

where $\tilde\alpha_l = \alpha_l - \alpha^s_l$ and $\tilde\alpha_u = \alpha_u + \alpha^s_u$ . The values of $\alpha^s_l$ and $\alpha^s_u$ are defined by minimizing

$f(\alpha^s_l,\alpha^s_u) = ( \alpha^s_l )^2 + ( \alpha^s_u )^2$

subject to the constraints

$\begin{array}{ccc} \alpha^s_l &\ge &0.0, \cr \alpha^s_u &\ge &0.0, \cr \alpha_l - \alpha^s_l &\le &s({\bf X}), \cr \alpha_u + \alpha^s_u &\ge &s({\bf X}) \cr \end{array}$

and the aforementioned approximation and local monotonicity constraints. If either $\alpha^s_l > 0.0$ or $\alpha^s_u > 0.0$ , then AMA_MltvMonoApprox() reports AMA_WARNING_ERROR messages which specify the bounds $\tilde\alpha_l$ and $\tilde\alpha_u$ imposed on the spline. Additionally, it sets AMA_OPTIONS::lwrbnd $=\alpha^s_l$ and AMA_OPTIONS::uprbnd $=\alpha^s_u$ .

This function computes a spline which satisfies either the full or reduced continuity condition at the interior grid points, as well as, the interpolation and local monotonicity constraints. The following table summarizes the continuity of $s({\bf X})$ with respect to $x_k$ at the interior grid points $x^g_{k,l_k}$ , for $l_k=2,\ldots,N^g_k-1$ , and the number of coefficients, $m_k$ , for a spline that satisfies either the full or reduced continuity condition. In the table the term

$s^{(p)}(x^g_{k,l_k}) = {\partial^p s(x_1,\cdots,x^g_{k,l_k},\cdots,x_n)\over \partial x^p_k}$

is the $p$ -th order partial of $s({\bf X})$ with respect to $x_k$ evaluated at $x^g_{k,l_k}$ and defined over the region $[x^L_1,x^U_1]\times\cdots\times[x^L_{k-1},x^U_{k-1}]\times[x^L_{k+1},x^U_{k+1}]\times\cdots\times[x^L_n,x^U_n]$ .

Degree	Full Continuity	Reduced Continuity
Linear	$s^{(p)}(x^g_{k,l_k})$ is continuous for	$s^{(p)}(x^g_{k,l_k})$ is continuous for
Quadratic	$s^{(p)}(x^g_{k,l_k})$ is continuous for $0\le p\le 1$	$s^{(p)}(x^g_{k,l_k})$ is continuous for
Cubic	$s^{(p)}(x^g_{k,l_k})$ is continuous for $0\le p\le 2$	$s^{(p)}(x^g_{k,l_k})$ is continuous for $0\le p\le 1$
Quartic	$s^{(p)}(x^g_{k,l_k})$ is continuous for $0\le p\le 3$	$s^{(p)}(x^g_{k,l_k})$ is continuous for $0\le p\le 2$
Quintic	$s^{(p)}(x^g_{k,l_k})$ is continuous for $0\le p\le 4$	$s^{(p)}(x^g_{k,l_k})$ is continuous for $0\le p\le 3$

This function does the following:

Checks the input parameters for validity, see AMA_MltvInputCheck().
Defines the spline $s({\bf X})$ based on the knot vectors ${\bf\Lambda}_k$ , for $1\le k\le n$ .
Defines CNSPLA_CONPNT constraints to represent the interpolation constraints, see AMA_MltvConpnt().
Defines CNSPLA_PNLTRM condition to represent the function $F^{(2)}(s({\bf X}))$ , see AMA_MltvPnltrm().
Defines CNSPLA_CONREG constraints to represent the local monotonicity constraints, see AMA_MltvConreg().
Invokes cnspla to compute a spline which minimizes $F^{(2)}(s({\bf X}))$ subject to the interpolation and local monotonicity constraints.
Stores interpolant into spline.

Note: By default the spline coefficients are initialized to zero but a different initial value for the spline coefficients can be set with AMA_OptionsSetCoefficients().; By default the spline is unbounded but finite bounds can be set with AMA_OptionsSetBounds().; By default the spline satisfies the full continuity condition in all of its independent variables but the reduced continuity condition can be requested with AMA_OptionsSetContinuity().; By default the cross partial terms are included in the penalty term but they can be excluded with AMA_OptionsSetPenaltyTerm().; Because this function defines knot vectors based on the rectilinear grid upon which the independent variable data lies, it should only be used when the independent variable data either defines a gridded data with holes distribution, defines a gridded data distribution or consists of a small randomly distributed data set. See Multivariate Data Functions for a description of these data distributions.

Parameter Note: In the parameter definitions given below the limits on $k$ are $1\le k\le n$ and k = $k-1$ .

Parameters

options	[in] Pointer to AMA_OPTIONS. Must be initialized with AMA_Options() prior to calling AMA_MltvMonoInterp().
nind	[in] The number of independent variables . Must satisfy $2\le$ nind $\le$ AMA_MXNIND.
n	[in] The number of data points . Must satisfy n $\ge 2$ .
x	[in] Array of size nind containing arrays of size n where x[k] contains the independent variable data $x_{k,\ell}$ , for $\ell=1,\ldots,N$ .
z	[in] Array of size n containing the dependent variable data $z_\ell$ , for $\ell=1,\ldots,N$ .
degree	[in] Array of size nind containing the degree where degree[k] . Must satisfy $1\le$ degree[k] $\le 5$ .
spline	[out] Pointer to AMA_SPLINE pointer containing the monotonic spline interpolant. Must satisfy spline $\ne$ NULL.

Returns: Success/Error Code.

User Callable Function - Documented 022416

Functions

Function Documentation