Classes | Typedefs | Enumerations | Functions
AMA.h File Reference
#include <cnspla.h>
#include <stdio.h>
#include <stdlib.h>
#include <AMA_Options.h>
#include <AMA_Unv.h>
#include <AMA_Mltv.h>
#include <AMA_Spline.h>
#include <AMA_Visit.h>

Go to the source code of this file.

Classes

struct  ama_options
 This structure is used to maintain the AMA Spline Library environment. More...
 
struct  ama_spline
 This structure is used to define a tensor product spline $s({\bf X}):{\rm R}^n\rightarrow{\rm R}^m$. More...
 

Macros

Success/Error Code

The following macros are used to define error codes returned by AMA Spline Library Functions.

See Success/Error Code for additional details.

#define AMA_NO_ERROR   0
 No errors occured during function execution. More...
 
#define AMA_WARNING_ERROR   1
 A warning error occured in one or more functions. More...
 
#define AMA_PROCESS_ERROR   2
 A process error occured in one or more functions. More...
 
#define AMA_INPUT_ERROR   3
 An invalid value of an input parameter defined by the user is passed to a function. More...
 
#define AMA_FATAL_ERROR   4
 An invalid value of an input parameter defined within an AMA Function is passed to another AMA Function. More...
 
#define AMA_ALLOCATE_ERROR   5
 A memory allocation error occured in a function. More...
 
#define AMA_EXTRAPOLATION   100
 Spline evaluation point requires extrapolation. More...
 
Mxnind

The following macros defines the maximum number of independent variables.

#define AMA_MXNIND   6
 Maximum number of independent variables. More...
 

Typedefs

typedef struct ama_options AMA_OPTIONS
 
typedef CNSPLA_SPLINE AMA_SPLINE
 

Enumerations

enum  AMA_Boolean { AMA_Boolean_False, AMA_Boolean_True }
 This enumeration provides a boolean capability. More...
 
enum  AMA_BoundaryConditions { AMA_BoundaryConditions_Default, AMA_BoundaryConditions_Natural, AMA_BoundaryConditions_Spline }
 This enumeration specifies the boundary conditions imposed by the following AMA Functions: More...
 
enum  AMA_Continuity { AMA_Continuity_Full, AMA_Continuity_Reduced }
 This enumeration specifies the spline continuity condition imposed by the following AMA Functions: More...
 
enum  AMA_Monotonicity {
  AMA_Monotonicity_Disabled, AMA_Monotonicity_Disabled_Positive, AMA_Monotonicity_Disabled_Negative, AMA_Monotonicity_Disabled_Zero,
  AMA_Monotonicity_Enabled
}
 This enumeration specifies the monotonicity constraints imposed by the following AMA Functions: More...
 
enum  AMA_ErrorFlag { AMA_ErrorFlag_Disabled, AMA_ErrorFlag_Enabled }
 This enumeration specifies if error messages are written to AMA_OPTIONS::errorFp. More...
 

Functions

long int AMA_LamdaInterp (AMA_OPTIONS *options, long int n, double *x, long int degree, long int *mlamda, double **lamda)
 Define Approximation and Interpolation Knot Vector More...
 
long int AMA_LamdaMonoInterp (AMA_OPTIONS *options, long int n, double *x, long int degree, enum AMA_Continuity continuity, long int *mlamda, double **lamda)
 Define Monotonic Spline Interpolation Knot Vector. More...
 

Macro Definition Documentation

#define AMA_ALLOCATE_ERROR   5

A memory allocation error occured in a function.

Execution is terminated and a traceback message is reported.

#define AMA_EXTRAPOLATION   100

Spline evaluation point requires extrapolation.

#define AMA_FATAL_ERROR   4

An invalid value of an input parameter defined within an AMA Function is passed to another AMA Function.

Execution is terminated and a traceback message is reported.

#define AMA_INPUT_ERROR   3

An invalid value of an input parameter defined by the user is passed to a function.

Execution is terminated and a traceback message is not reported.

#define AMA_MXNIND   6

Maximum number of independent variables.

#define AMA_NO_ERROR   0

No errors occured during function execution.

#define AMA_PROCESS_ERROR   2

A process error occured in one or more functions.

Execution is continued and a traceback message is not reported.

#define AMA_WARNING_ERROR   1

A warning error occured in one or more functions.

Execution is continued and a traceback message is not reported.

Typedef Documentation

typedef struct ama_options AMA_OPTIONS
typedef CNSPLA_SPLINE AMA_SPLINE

Enumeration Type Documentation

This enumeration provides a boolean capability.

Documented 010914

Enumerator
AMA_Boolean_False 
AMA_Boolean_True 

This enumeration specifies the boundary conditions imposed by the following AMA Functions:

Univariate Data Functions

Multivariate Data Functions

The first five functions compute an univariate spline

\[ s(x) = \sum_{j=1}^{m}\alpha_jB_{d,j}(x|{\bf\Lambda}) \]

based the independent variable data $x_\ell$, for $\ell=1,\ldots,N$. By default the five univariate approximation and interpolation functions do not imposed boundary conditions, with the exception of AMA_UnvInterp(), which imposes natural boundary conditions. However, boundary conditions can be imposed with AMA_OptionsSetUnvBoundaryConditions(). See AMA_UnvBoundaryConditions() for additional information about the boundary conditions associated with the different values of AMA_BoundaryConditions.

The latter ten functions compute a multivariate 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}) \]

based on the independent variable data ${\bf X}_\ell=(x_{1,\ell},\cdots,x_{n,\ell})$, for $\ell=1,\ldots,N$. With the exception of AMA_MltvInterp() and AMA_MltvGrdInterp(), which impose natural boundary conditions, these functions do not impose any boundary conditions. However, boundary conditions can be imposed with AMA_OptionsSetMltvBoundaryConditions(). See AMA_MltvBoundaryConditions() for additional information about the boundary conditions associated with the different values of AMA_BoundaryConditions.

Documented 102515

Enumerator
AMA_BoundaryConditions_Default 

Impose the default boundary conditions.

AMA_BoundaryConditions_Natural 

Impose the natural boundary conditions.

AMA_BoundaryConditions_Spline 

Impose user specified boundary conditions.

This enumeration specifies the spline continuity condition imposed by the following AMA Functions:

Univariate Data Functions

Multivariate Data Functions

The first two functions compute an univariate spline

\[ s(x) = \sum_{j=1}^{m}\alpha_jB_{d,j}(x|{\bf\Lambda}) \]

based the independent variable data $x_\ell$, for $\ell=1,\ldots,N$. The knot vector ${\bf\Lambda}$ is defined by AMA_LamdaMonoInterp() and it includes knots which lie at the interior data points $x_\ell$, for $2\le \ell\le N-1$, at which the spline can satisfy either the full or reduced continuity condition. The following table summarizes the continuity of the spline $s(x)$ at interior data points for linear through quintic splines.

The following table summarizes the continuity of $s(x_\ell)$, for $\ell=2,\ldots,N-1$, and the number of coefficients, $m$, for a spline that satisfies the full and reduced continuity conditions.

Degree Full Continuity $m$ Reduced Continuity $m$
Linear $s^{(p)}(x_\ell)$ is continuous for $p=0$ $N$ $s^{(p)}(x_\ell)$ is continuous for $p=0$ $N$
Quadratic $s^{(p)}(x_\ell)$ is continuous for $0\le p\le 1$ $2N$ $s^{(p)}(x_\ell)$ is continuous for $p=0$ $2N-1$
Cubic $s^{(p)}(x_\ell)$ is continuous for $0\le p\le 2$ $3N$ $s^{(p)}(x_\ell)$ is continuous for $0\le p\le 1$ $2N$
Quartic $s^{(p)}(x_\ell)$ is continuous for $0\le p\le 3$ $4N$ $s^{(p)}(x_\ell)$ is continuous for $0\le p\le 2$ $3N$
Quintic $s^{(p)}(x_\ell)$ is continuous for $0\le p\le 4$ $5N$ $s^{(p)}(x_\ell)$ is continuous for $0\le p\le 3$ $4N$

The latter four functions compute a multivariate 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}) \]

based on the independent variable data ${\bf X}_\ell=(x_{1,\ell},\cdots,x_{n,\ell})$, for $\ell=1,\ldots,N$. If the rectilinear grid upon which the data lies is $(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})$, then the knot vectors are defined by AMA_LamdaMonoInterp() and they include knots which lie at the interior grid points $x^g_{k,l_k}$, for $l_k=2,\ldots,n^g_k-1$, at which the spline can satisfy either the full or reduced continuity condition.

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 $m_k$ Reduced Continuity $m_k$
Linear $ s^{(p)}(x^g_{k,l_k})$ is continuous for $p=0$ $N^g_k$ $s^{(p)}(x^g_{k,l_k})$ is continuous for $p=0$ $N^g_k$
Quadratic $s^{(p)}(x^g_{k,l_k})$ is continuous for $0\le p\le 1$ $2N^g_k$ $s^{(p)}(x^g_{k,l_k})$ is continuous for $p=0$ $2N^g_k-1$
Cubic $s^{(p)}(x^g_{k,l_k})$ is continuous for $0\le p\le 2$ $3N^g_k$ $s^{(p)}(x^g_{k,l_k})$ is continuous for $0\le p\le 1$ $2N^g_k$
Quartic $s^{(p)}(x^g_{k,l_k})$ is continuous for $0\le p\le 3$ $4N^g_k$ $s^{(p)}(x^g_{k,l_k})$ is continuous for $0\le p\le 2$ $3N^g_k$
Quintic $s^{(p)}(x^g_{k,l_k})$ is continuous for $0\le p\le 4$ $5N^g_k$ $s^{(p)}(x^g_{k,l_k})$ is continuous for $0\le p\le 3$ $4N^g_k$

By default the splines produced by the aforementioned functions satisfy the full continuity condition but the reduced continuity condition can be requested with AMA_OptionsSetContinuity().

Documented 102515

Enumerator
AMA_Continuity_Full 

The spline satisfies the full continuity condition.

AMA_Continuity_Reduced 

The spline satisfies the reduced continuity condition.

This enumeration specifies if error messages are written to AMA_OPTIONS::errorFp.

Documented 101913

Enumerator
AMA_ErrorFlag_Disabled 

Error messages are not written to AMA_OPTIONS::errorFp.

AMA_ErrorFlag_Enabled 

Error messages are written to AMA_OPTIONS::errorFp.

This enumeration specifies the monotonicity constraints imposed by the following AMA Functions:

Univariate Data Functions

Multivariate Data Functions

The first two functions compute an univariate spline

\[ s(x) = \sum_{j=1}^{m}\alpha_jB_{d,j}(x|{\bf\Lambda}) \]

based the independent variable data $x_\ell$, for $\ell=1,\ldots,N$. They impose positive derivative $s'(x)\ge 0.0$ constraints in intervals of increasing data, negative derivative $s'(x)\le 0.0$ constraints in intervals of decreasing data, and zero derivative $s'(x)= 0.0$ constraints in intervals of equal data. See AMA_UnvConreg() for additional details about the monotonicity constraints imposed by these two univariate functions. By default the monotonicity constraints are enabled but they can be disabled with AMA_OptionsSetMonotonicity().

The latter four functions compute a multivariate 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}) \]

based on the independent variable data ${\bf X}_\ell=(x_{1,\ell},\cdots,x_{n,\ell})$, for $\ell=1,\ldots,N$. They impose positive partial derivative ${\partial s({\bf X})\over \partial x_k}\ge 0.0$ constraints in intervals of increasing data, negative partial derivative ${\partial s({\bf X})\over \partial x_k}\le 0.0$ constraints in intervals of decreasing data, and partial derivative equal to zero ${\partial s({\bf X})\over \partial x_k} = 0.0$ constraints in intervals of equal data. The constraints can be imposed in $x_k$, for $1\le k\le n$. See AMA_MltvConreg() for additional details about the monotonicity constraints imposed by these four multivariate functions. By default the monotonicity constraints are imposed in all independent variables but they can be disabled with AMA_OptionsSetMonotonicity().

Documented 102515

Enumerator
AMA_Monotonicity_Disabled 

Monotonicity constraints are not imposed.

AMA_Monotonicity_Disabled_Positive 

Positive derivative constraints are not imposed.

AMA_Monotonicity_Disabled_Negative 

Negative derivative constraints are not imposed.

AMA_Monotonicity_Disabled_Zero 

Derivative equal to zero constraints are not imposed.

AMA_Monotonicity_Enabled 

Monotonicity constraints are imposed.

Function Documentation

long int AMA_LamdaInterp ( AMA_OPTIONS options,
long int  n,
double *  x,
long int  degree,
long int *  mlamda,
double **  lamda 
)

Define Approximation and Interpolation Knot Vector

For given independent variable data $x_\ell$, for $\ell=1,\ldots,N$, this function computes a knot vector ${\bf\Lambda}$ which insures a spline has sufficient coefficients to satisfy the approximation or interpolation constraints imposed by the univariate and multivariate data approximation and interpolation functions.

The knot vector ${\bf\Lambda}$ depends on the degree, $d$, of the spline approximation. If the degree is even, then the knot vector ${\bf\Lambda}\in{\rm R}^M$, where $M=N+2d+1$, is defined such that its distinct knots are

\[ {\bf\rm K}^{\bf\Lambda} = (x_1,0.5(x_1+x_2),x_2,\cdots,x_{N-1},0.5(x_{N-1}+x_N),x_N)^T. \]

If the degree is odd, then the knot vector ${\bf\Lambda}\in{\rm R}^M$, where $M=N+2d$, is defined such that its distinct knots are

\[ {\bf\rm K}^{\bf\Lambda} = (x_1,x_2,\cdots,x_{N-1},x_N)^T. \]

Regardless of the degree its corresponding knot multiplicity vector is

\[ {\bf\rm H}^{\bf\Lambda} = (d+1,1,\cdots,1,d+1)^T. \]

Parameters
options[in] Pointer to AMA_OPTIONS. Must be initialized with AMA_Options() prior to calling AMA_LamdaInterp().
n[in] The number of data points $N$. Must satisfy n $\ge 2$.
x[in] Array of size n containing the independent variable data $x_\ell$, for $\ell=1,\ldots,N$. Must be in strictly ascending order.
degree[in] The degree $d$. Must satisfy $1\le$ degree $\le 5$.
mlamda[out] The number of knots $M$. Must satisfy mlamda $\ne$ NULL.
lamda[out] Pointer to an array of size mlamda containing the knot vector ${\bf\Lambda}$. Must satisfy lamda $\ne$ NULL.
Returns
Success/Error Code.

User Support Function - Documented 110415 - !!!THIS IS NOT A USER CALLABLE FUNCTION - DOCUMENT IS INCLUDED FOR COMPLETENESS!!!

long int AMA_LamdaMonoInterp ( AMA_OPTIONS options,
long int  n,
double *  x,
long int  degree,
enum AMA_Continuity  continuity,
long int *  mlamda,
double **  lamda 
)

Define Monotonic Spline Interpolation Knot Vector.

For given independent variable data $x_\ell$, for $\ell=1,\ldots,N$, this function computes a knot vector ${\bf\Lambda}$ which insures a spline has sufficient coefficients to satisfy either the full continuity condition or the reduced continuity condition at the interior data points and also the approximation and local monotinicity constraints. The knot vector provides sufficient conditions to insure a feasible solution for the constraints independent of the variation of the dependent variable data. It depends on the spline's degree, $d$, and the continuity of the spline at the interior data points $x_\ell$, for $\ell=2,\ldots,N-1$.

If the spline is linear, $d=1$, then independent of the continuity condition the spline's value $s(x)$ is continuous at the interior data points and the knot vector ${\bf\Lambda}\in{\rm R}^{N+2}$ is defined such that its distinct knot and knot multiplicity vectors are

\[ {\bf\rm K}^{\bf\Lambda} = (x_1,x_2,\cdots,x_{N-1},x_N) \]

and

\[ {\bf\rm H}^{\bf\Lambda} = (2,1,\cdots,1,2). \]

The number of spline coefficients is $m=N$. If $2\le d\le 5$, then the knot vector ${\bf\Lambda}$ depends on whether the spline satisfies either a full continuity condition or a reduced continuity condition.

If a full continuity condition is requested, then the spline's value $s(x)$ and its derivatives $s^{(p)}(x)$, for $p=1,\ldots,d-1$, are continuous at $x_\ell$, for $\ell=2,\ldots,N-1$. In this case the knot vector ${\bf\Lambda}\in{\rm R}^{d(N+1)+1}$ is defined such that its distinct knots are

\[ \lambda_{(l-1)d+j} = \left({d-j+1 \over d}\right)x_\ell + \left({j-1 \over d}\right)x_{\ell+1} \]

for $\ell=1,\ldots,N-1$ and $j=1,\ldots,d$; and $\lambda_{d(N-1)+1} = x_N$. For example, if the spline is quadratic, $d=2$, then the distinct knot vector is

\[ {\bf\rm K}^{\bf\Lambda} = (x_1,0.5(x_1+x_2),x_2,\cdots,x_{N-1},0.5(x_{N-1}+x_N),x_N)^T \]

and; if if the spline is cubic, $d=3$, then the distinct knot vector is

\[ {\bf\rm K}^{\bf\Lambda} = (x_1,(2/3)x_1+(1/3)x_2,(1/3)x_1+(2/3)x_2,x_2,\cdots,x_{N-1},(2/3)x_{N-1}+(1/3)x_N,(1/3)x_{N-1}+(2/3)x_N,x_N)^T. \]

Regardless of the degree its corresponding knot multiplicity vector is

\[ {\bf\rm H}^{\bf\Lambda} = (d+1,1,\cdots,1,d+1)^T \]

and the number of spline coefficients is $m=dN$. This distribution of knots insures the spline has sufficient coefficients to satisfy the full continuity condition at the interior data and to satisfy both the approximation and local monotinicity constraints independent of the variation of the dependent variable data $z_\ell$, for $l=1,\ldots,N$.

If a reduced continuity condition is requested, then the knot vector depends on the spline's degree. If the spline is quadratic, $d=2$, or cubic, $d=3$, then the knot vector ${\bf\Lambda}\in{\rm R}^{2(N+d-1)}$ is defined such that its distinct knot and knot multiplicity vectors are

\[ {\bf\rm K}^{\bf\Lambda} = (x_1,x_2,\cdots,x_{N-1},x_N) \]

and

\[ {\bf\rm H}^{\bf\Lambda} = (d+1,2,\cdots,2,d+1). \]

The number of spline coefficients is $m=2N+d-3$.

If $4\le d\le 5$, then for each interval $[x_\ell,x_{\ell+1}]$, for $\ell=1,\ldots,N-1$, this function defines the knots

\[ \lambda_{\ell,j} = \left({d-j-2 \over d-2}\right)x_\ell + \left({j \over d-2}\right)x_{\ell+1} \]

for $j=1,\ldots,d-3$, of multiplicity one and knots of multiplicity two at the interior data points $x_\ell$, for $\ell=2,\ldots,N-1$, along with knots of multiplicity $d+1$ at the endpoints $x_1$ and $x_N$. That is, if the spline is quartic, $d=4$, then ${\bf\Lambda}\in{\rm R}^{3N+5}$ and its distinct knot and knot multiplicity vectors are

\[ {\bf\rm K}^{\bf\Lambda} = (x_1,0.5(x_1+x_2),x_2,\cdots,x_{N-1},0.5(x_{N-1}+x_N),x_N) \]

and

\[ {\bf\rm H}^{\bf\Lambda} = (5,1,2,\cdots,2,1,5). \]

The number of spline coefficients is $m=3N$. However, if the spline is quintic, $d=5$, then ${\bf\Lambda}\in{\rm R}^{4N+6}$ and its distinct knot and knot multiplicity vectors are

\[ {\bf\rm K}^{\bf\Lambda} = (x_1,(2/3)x_1+(1/3)x_2,(1/3)x_1+(2/3)x_2,x_2,\cdots,x_{N-1},(2/3)x_{N-1}+(1/3)x_N,(1/3)x_{N-1}+(2/3)x_N,x_N) \]

and

\[ {\bf\rm H}^{\bf\Lambda} = (6,1,2,\cdots,2,1,6). \]

The number of spline coefficients is $m=4N$. The distribution of knots discussed above insures the spline has sufficient coefficients to satisfy the reduced continuity condition at the interior data and to satisfy both the approximation and local monotinicity constraints independent of the variation of the dependent variable data $z_\ell$, for $l=1,\ldots,N$.

The following table summarizes the continuity of $s(x_\ell)$, for $\ell=2,\ldots,N-1$, and the number of coefficients, $m$, for a spline that satisfies the full and reduced continuity conditions.

Degree Full Continuity $m$ Reduced Continuity $m$
Linear $s^{(p)}(x_\ell)$ is continuous for $p=0$ $N$ $s^{(p)}(x_\ell)$ is continuous for $p=0$ $N$
Quadratic $s^{(p)}(x_\ell)$ is continuous for $0\le p\le 1$ $2N$ $s^{(p)}(x_\ell)$ is continuous for $p=0$ $2N-1$
Cubic $s^{(p)}(x_\ell)$ is continuous for $0\le p\le 2$ $3N$ $s^{(p)}(x_\ell)$ is continuous for $0\le p\le 1$ $2N$
Quartic $s^{(p)}(x_\ell)$ is continuous for $0\le p\le 3$ $4N$ $s^{(p)}(x_\ell)$ is continuous for $0\le p\le 2$ $3N$
Quintic $s^{(p)}(x_\ell)$ is continuous for $0\le p\le 4$ $5N$ $s^{(p)}(x_\ell)$ is continuous for $0\le p\le 3$ $4N$
Parameters
options[in] Pointer to AMA_OPTIONS. Must be initialized with AMA_Options() prior to calling AMA_LamdaMonoInterp().
n[in] The number of data points $N$. Must satisfy n $\ge 2$.
x[in] Array of size n containing the independent variable data $x_\ell$, for $\ell=1,\ldots,N$. Must be in strictly ascending order.
degree[in] The degree $d$. Must satisfy $1\le$ degree $\le 5$.
continuity[in] Continuity condition flag. It has one of the following two values:
  • If continuity equals AMA_Continuity_Full, then spline approximation or interpolant satisfies the full continuity condition in $x_k$.
  • If continuity equals AMA_Continuity_Reduced, then spline approximation or interpolant satisfies the reduced continuity condition in $x_k$.
mlamda[out] The number of knots $M$. Must satisfy mlamda $\ne$ NULL.
lamda[out] Pointer to an array of size mlamda containing the knot vector ${\bf\Lambda}$. Must satisfy lamda $\ne$ NULL.
Returns
Success/Error Code.

User Support Function - Documented 110415 - !!!THIS IS NOT A USER CALLABLE FUNCTION - DOCUMENT IS INCLUDED FOR COMPLETENESS!!!