Functions
AMA_Unv.c File Reference
#include <AMA.h>

Functions

long int AMA_UnvBoundaryConditions (AMA_OPTIONS *options, enum AMA_Boolean interp, CNSPLA_SPLFUN *splfun)
 Define boundary conditions for univariate approximation and interpolation functions. More...
 
long int AMA_UnvData (AMA_OPTIONS *options, const char *datfile, long int *degree, long int *n, double **x, double **z, double **epsilon, double **wht, double *theta, long int *mlamda, double **lamda)
 Read data and approximation options for AMA Spline Library Univariate Data Functions. More...
 
long int AMA_UnvDataFree (AMA_OPTIONS *options, double **x, double **z, double **epsilon, double **wht, double **lamda)
 Free Univariate Data Functions data arrays. More...
 
long int AMA_UnvInputCheck (AMA_OPTIONS *options, long int n, double *x, double *z, double *wht, double *epsilon, long int degree, long int mlamda, double *lamda, enum AMA_Boolean lstsqr)
 Perform input check for univariate data approximation functions. More...
 
long int AMA_UnvPnltrm (AMA_OPTIONS *options, double theta, long int porder, CNSPLA_SPLFUN *splfun)
 Define penalty term on an univariate spline. More...
 
long int AMA_UnvConpnt (AMA_OPTIONS *options, long int n, double *x, double *z, double *epsilon, CNSPLA_SPLFUN *splfun)
 Define approximation or interpolation constraints on an univariate spline. More...
 
long int AMA_UnvConreg (AMA_OPTIONS *options, long int n, double *x, double *z, double *epsilon, long int degree, CNSPLA_SPLFUN *splfun)
 Define local monotonicity constraints on an univariate spline. More...
 

Function Documentation

long int AMA_UnvBoundaryConditions ( AMA_OPTIONS options,
enum AMA_Boolean  interp,
CNSPLA_SPLFUN *  splfun 
)

Define boundary conditions for univariate approximation and interpolation functions.

Parameters
options[in] Pointer to AMA_OPTIONS. Should be initialized with AMA_Options() prior to calling AMA_UnvBoundaryConditions().
interp[in] Interpolation function flag. It has one of the following two values:
splfun[in] Pointer to CNSPLA_SPLFUN containing the spline $s(x)$ upon which the penalty term is imposed. Should satisfy splfun $\ne$ NULL.
Returns
Success/Error Code.

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

long int AMA_UnvConpnt ( AMA_OPTIONS options,
long int  n,
double *  x,
double *  z,
double *  epsilon,
CNSPLA_SPLFUN *  splfun 
)

Define approximation or interpolation constraints on an univariate spline.

For a given set of data $(x_\ell,z_\ell)$ and approximation tolerances $\epsilon_\ell$, for $\ell=1,\ldots,N$, this function defines either the approximation constraints

\[ z_\ell - \epsilon_\ell \le s(x_\ell) \le z_\ell + \epsilon_\ell \]

or the interpolation constraints

\[ s(x_\ell) = z_\ell, \]

for $\ell=1,\ldots,N$, on a univariate spline

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

Parameters
options[in] Pointer to AMA_OPTIONS. Should be initialized with AMA_Options() prior to calling AMA_UnvConpnt().
n[in] The number of data points $N$. Should satisfy n $\ge 2$.
x[in] Array of size n containing the independent variable data $x_\ell$, for $\ell=1,\ldots,N$. Should be in strictly ascending order.
z[in] Array of size n containing the dependent variable data $z_\ell$, for $\ell=1,\ldots,N$.
epsilon[in] Array of size n containing the approximation tolerances $\epsilon_\ell$, for $\ell=1,\ldots,N$. Should satisfy $\epsilon_\ell\ge 0.0$ for all $\ell=1,\ldots,N$. If epsilon = NULL, then the interpolation constraints are defined. Otherwise, the approximation constraints are defined.
splfun[in] Pointer to CNSPLA_SPLFUN containing spline $s(x)$ upon which approximation or interpolation constraints are imposed. Should satisfy splfun $\ne$ NULL.
Returns
Success/Error Code.

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

long int AMA_UnvConreg ( AMA_OPTIONS options,
long int  n,
double *  x,
double *  z,
double *  epsilon,
long int  degree,
CNSPLA_SPLFUN *  splfun 
)

Define local monotonicity constraints on an univariate spline.

For a given set of data $(x_\ell,z_\ell)$ and approximation tolerances $\epsilon_\ell$, for $\ell=1,\ldots,N$, this function defines the local monotonicity constraints on an univariate spline

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

If $\max_\ell\lbrace{\epsilon_\ell\rbrace}=0.0$, then this function imposes the constraints

\[ s'(x) \cases { \ge 0.0 {\rm \hspace{5pt}for\hspace{5pt}all\hspace{5pt}} x\in[x_\ell,x_{\ell+1}], & if $z_\ell < z_{\ell+1}$; \cr \le 0.0 {\rm \hspace{5pt}for\hspace{5pt}all\hspace{5pt}} x\in[x_\ell,x_{\ell+1}], & if $z_\ell > z_{\ell+1}$; \cr = 0.0 {\rm \hspace{5pt}for\hspace{5pt}all\hspace{5pt}} x\in[x_\ell,x_{\ell+1}], & otherwise; \cr } \]

for $\ell=1,\ldots,N-1$. Alternatively, if there exists a $1\le \ell\le N$ for which $\epsilon_\ell\ne 0.0$, then the local monotonicity constraints

\[ s'(x) \cases { \ge 0.0 {\rm \hspace{5pt}for\hspace{5pt}all\hspace{5pt}} x\in[x_\ell,x_{\ell+1}], & if $z_\ell + \epsilon_\ell < z_{\ell+1} - \epsilon_{\ell+1}$; \cr \le 0.0 {\rm \hspace{5pt}for\hspace{5pt}all\hspace{5pt}} x\in[x_\ell,x_{\ell+1}], & if $z_\ell - \epsilon_\ell > z_{\ell+1} + \epsilon_{\ell+1}$; \cr } \]

for $\ell=1,\ldots,N-1$ are imposed. If for some $1\le \ell\le N-1$ the above conditions are not met, then the intervals $[z_\ell - \epsilon_\ell,z_\ell + \epsilon_\ell]$ and $[z_{\ell+1} - \epsilon_{\ell+1},z_{\ell+1} + \epsilon_{\ell+1}]$ intersect and the constraint $s'(x)=0$ can be imposed over the interval $[x_\ell,x_{\ell+1}]$. However, it is possible for the intervals $[z_q - \epsilon_q, z_q + \epsilon_q]$ and $[z_{q+1} - \epsilon_{q+1}, z_{q+1} + \epsilon_{q+1}]$ to intersect, for each $\ell\le q\le \ell+r$ and $r\ge 1$; without an intersection existing between all the intervals. In this case the equality constraint is inconsistent with the approximation constraints

\[ z_q - \epsilon_q \le s(x_q) \le z_q + \epsilon_q, \]

for $\ell\le q\le \ell+r+1$; and, therefore, can not be imposed over the interval $[x_l,x_{l+r+1}]$. Hence, instead of imposing an equality constraint this function minimizes $\vert\vert s'(x) \vert\vert_\infty$ over all intervals $[x_\ell,x_{\ell+1}]$ for which the intervals $[z_\ell - \epsilon_\ell,z_\ell + \epsilon_\ell]$ and $[z_{\ell+1} - \epsilon_{\ell+1},z_{\ell+1} + \epsilon_{\ell+1}]$ intersect.

Parameters
options[in] Pointer to AMA_OPTIONS. Should be initialized with AMA_Options() prior to calling AMA_UnvConreg().
n[in] The number of data points $N$. Should satisfy n $\ge 2$.
x[in] Array of size n containing the independent variable data $x_\ell$, for $\ell=1,\ldots,N$. Should be in strictly ascending order.
z[in] Array of size n containing the dependent variable data $z_\ell$, for $\ell=1,\ldots,N$.
epsilon[in] Array of size n containing the approximation tolerances $\epsilon_\ell$, for $\ell=1,\ldots,N$. Should satisfy $\epsilon_\ell \ge 0.0$ for all $\ell=1,\ldots,N$. If epsilon = NULL, then this function uses $\epsilon_\ell = 0.0$ for all $\ell=1,\ldots,N$.
degree[in] The degree $d$. Should satisfy $1\le$ degree $\le 5$.
splfun[in] Pointer to CNSPLA_SPLFUN containing spline $s(x)$ upon which monotonicity constraints are imposed. Should satisfy splfun $\ne$ NULL.
Returns
Success/Error Code.

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

long int AMA_UnvData ( AMA_OPTIONS options,
const char *  datfile,
long int *  degree,
long int *  n,
double **  x,
double **  z,
double **  epsilon,
double **  wht,
double *  theta,
long int *  mlamda,
double **  lamda 
)

Read data and approximation options for AMA Spline Library Univariate Data Functions.

This function reads data and approximation options for AMA Spline Library functions which compute spline approximations of independent variable data ${\bf X}\in{\rm R}^1$ and dependent variable data ${\bf Z}\in{\rm R}^1$.

The argument datfile should reference a readable file which consists of a data section and several, optional, approximation options sections. The Data section must preceed the approximation options sections and has the following structure:

\[ \begin{array}{llll} {\bf Data} & & & \cr {\bf N:}N &{\bf Degree:}d & & \cr {\bf X} &{\bf Z} &{\bf Epsilon} &{\bf Wht} \cr x_1 &z_1 &\epsilon_1 &w_1 \cr x_2 &z_2 &\epsilon_2 &w_2 \cr \vdots &\vdots &\vdots &\vdots \cr x_N &z_N &\epsilon_N &w_N \cr {\bf End\_Data} & & & \cr \end{array} \]

where the Epsilon and Wht columns are optional. The data must satisfy the following conditions:

  • $1\le d \le 5$;
  • $N\ge 2$;
  • the independent variable data $x_\ell$, for $\ell=1,\cdots,N$, must be in increasing order;
  • the approximation tolerances must satisfy $\epsilon_\ell\ge 0.0$, for $\ell=1,\cdots,N$;
  • the weights must satisfy $w_\ell\ge 0.0$, for $\ell=1,\cdots,N$.

Following the Data section may be one or more of the Bounds, Least_Squares or Monotonicity sections. If an approximation options section is not defined, then this function sets the options to their default values. See Table Approximation Options Defaults for a list of Univariate Data Functions approximation options default values.

The Bounds section specifies the lower and upper bounds employed by AMA_UnvLstsqr(). It has the following structure:

\[ \begin{array}{ll} {\bf Bounds} & \cr {\bf Lwrbnd:}\alpha_l &{\bf Uprbnd:}\alpha_u \cr {\bf End\_Bounds} & \cr \end{array} \]

and its options must satisfy the following conditions:

The lower bound is read as a string lwrstr and based on the value of lwrstr the value of $\alpha_l$ is set as follows:

  • If lwrstr equals infbnd, then $\alpha_l = -\alpha_\infty$ where $\alpha_\infty$ = AMA_SplineInfbnd(); or,
  • If lwrstr equals zmin , then $\alpha_l = \min_\ell\lbrace{z_\ell\rbrace}$.
  • Otherwise, $\alpha_l =$ atof(lwrstr).

Similarly, the upper bound is read as a string uprstr and based on the value of uprstr the value of $\alpha_u$ is set as follows:

  • If uprstr equals infbnd, then $\alpha_u = \alpha_\infty$ where $\alpha_\infty$ = AMA_SplineInfbnd(); or,
  • If uprstr equals zmax , then $\alpha_u = \max_\ell\lbrace{z_\ell\rbrace}$.
  • Otherwise, $\alpha_u =$ atof(uprstr).

The Least_Squares section specifies the approximation options and knots employed by AMA_UnvLstsqr(). It has the following structure:

\[ \begin{array}{lll} {\bf Least\_Squares} & & \cr {\bf Mlamda:}m &{\bf Theta:}\theta &{\bf Minorm:\rm minorm} \cr \lambda^o_1 & & \cr \lambda^o_2 & & \cr \vdots & & \cr \lambda^o_m & & \cr {\bf End\_Least\_Squares} & & \cr \end{array} \]

and its options must satisfy the following conditions:

  • $0.0\le\theta < 1.0$;
  • ${\rm minorm}$ must be Enabled or Disabled;
  • $m\ge 2$;
  • the knots $\lambda^o_i$, for $i=1,\cdots,m$, must be in increasing order;
  • $\lambda^o_1 \le x_1$ and $\lambda^o_{m} \ge x_N$.

The Monotonicity section specifies the monotonicity constraints and continuity conditions employed by AMA_UnvMonoApprox() and AMA_UnvMonoInterp(). It has the the following structure:

\[ \begin{array}{llll} {\bf Monotonicity} & & & \cr {\bf Monpos:\rm monpos} &{\bf Monneg:\rm monneg} &{\bf Monzer:\rm monzer} &{\bf Concnd:\rm concnd} \cr {\bf End\_Monotonicity} & & & \cr \end{array} \]

and its options must satisfy the following conditions:

  • the positive monotonicity constraint flag ${\rm monpos}$, negative monotonicity constraint flag ${\rm monneg}$ and zero monotonicity constraint flag ${\rm monzer}$ must be Enabled or Disabled;
  • the continuity condition ${\rm concnd}$ must be Full or Reduced.

The bold keywords are case sensitive and the string values for the approximation options are case insensitive.

This function performs the following tasks:

Parameters
options[in] Pointer to AMA_OPTIONS initialized with AMA_Options(). Must be initialized with AMA_Options() prior to calling AMA_UnvData().
datfile[in] The data file name. Must satisfy datfile $\ne$ NULL.
degree[out] The degree $d$. Must satisfy degree $\ne$ NULL.
n[out] The number of data points $N$. Must satisfy n $\ne$ NULL.
x[out] Array of size n containing the independent variable data $x_\ell$, for $\ell=1,\ldots,N$. Must satisfy x $\ne$ NULL.
z[out] Array of size n containing the dependent variable data $z_\ell$, for $\ell=1,\ldots,N$. Must satisfy z $\ne$ NULL.
epsilon[out] Array of size n containing the approximation tolerances $\epsilon_\ell$, for $\ell=1,\ldots,N$. Must satisfy epsilon $\ne$ NULL.
wht[out] Array of size n containing the weights $w_\ell$, for $\ell=1,\ldots,N$. Must satisfy wht $\ne$ NULL.
theta[out] The penalty term weight $\theta$. Must satisfy theta $\ne$ NULL.
mlamda[out] The number of knots $m$. Must satisfy mlamda $\ne$ NULL.
lamda[out] Array of size mlamda containing the knots $\lambda^o_i$, for $i=1,\ldots,m$. 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_UnvDataFree ( AMA_OPTIONS options,
double **  x,
double **  z,
double **  epsilon,
double **  wht,
double **  lamda 
)

Free Univariate Data Functions data arrays.

This function frees the arrays allocated by AMA_UnvData().

Parameters
options[in] Pointer to AMA_OPTIONS. Must be initialized with AMA_Options() prior to calling AMA_UnvDataFree().
x[out] Pointer to array containing the independent variable data.
z[out] Pointer to array containing the dependent variable data.
epsilon[out] Pointer to array containing the approximation tolerances.
wht[out] Pointer to array containing the weights.
lamda[out] Pointer to array containing the knots.
Returns
Success/Error Code.

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

long int AMA_UnvInputCheck ( AMA_OPTIONS options,
long int  n,
double *  x,
double *  z,
double *  wht,
double *  epsilon,
long int  degree,
long int  mlamda,
double *  lamda,
enum AMA_Boolean  lstsqr 
)

Perform input check for univariate data approximation functions.

This function checks the input parameters for the Univariate Data Functions which compute the spline

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

of degree $d$ which is based on the knot vector ${\bf\Lambda}$. Along with the degree the Univariate Data Functions require the independent variable data $x_\ell$, for $\ell=1,\ldots,N$, and either the weights $w_\ell$ or the approximation tolerances $\epsilon_\ell$, for $\ell=1,\ldots,N$. Also, for least squares approximation functions the knot vector ${\bf\Lambda}\in{\rm R}^M$ is required. This function insures the following conditions are satisfied:

  • $N\ge 2$;
  • $1\le d\le 5$;
  • $x_\ell$, for $1\le\ell\le N$, is in ascending order and if lstsqr equals AMA_Boolean_False, then it is in strictly ascending order;
  • $w_\ell\ge 0.0$ for all $1\le\ell\le N$ and $w_\ell >0.0$ for at least one $1\le\ell\le N$;
  • $\epsilon_\ell\ge 0.0$ for all $1\le\ell\le N$;
  • $M\ge 2$.

Also, if lstsqr equals AMA_Boolean_True and the knot vector ${\bf\Lambda}$ is represented by its distinct knot vector

\[ {\bf\rm K}^{{\bf\Lambda}} = ( \kappa_1, \kappa_2, \cdots, \kappa_{m^d-1}, \kappa_{m^d} )^T \]

and its knot multiplicity vector

\[ {\bf\rm H}^{{\bf\Lambda}} = ( \eta_1, \eta_2, \cdots, \eta_{m^d-1}, \eta_{m^d} )^T, \]

then this function insures either the conditions

  • $\kappa_i < \kappa_{i+1}$, for $1\le i\le m^d - 1$;
  • $\eta_i \le d + 1$, for $2\le i\le m^d-1$;
  • $\eta_1 = \eta_{m^d} = d+1$;

or

  • $\kappa_i < \kappa_{i+1}$, for $1\le i\le m^d - 1$;
  • $\eta_i \le d + 1$, for $2\le i\le m^d-1$;
  • $\eta_1 = \eta_{m^d} = 1$;

are satisfied. It also insures the first and last distinct knots satisfy the conditions $\kappa_1\le x_1$ and $\kappa_{m^d}\ge x_N$, respectively.

Parameters
options[in] Pointer to AMA_OPTIONS. Must be initialized with AMA_Options() prior to calling AMA_UnvInputCheck().
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 satisfy x $\ne$ NULL and be in ascending order.
z[in] Array of size n containing the dependent variable data $z_\ell$, for $\ell=1,\ldots,N$. Must satisfy z $\ne$ NULL.
wht[in] Array of size n containing the weights $w_\ell$, for $\ell=1,\ldots,N$. If wht $\ne$ NULL, then must satisfy $w_\ell\ge 0.0$ for all $\ell=1,\ldots,N$.
epsilon[in] Array of size n containing the approximation tolerances $\epsilon_\ell$, for $\ell=1,\ldots,N$. If epsilon $\ne$ NULL, then must satisfy $\epsilon_\ell\ge 0.0$ for all $\ell=1,\ldots,N$.
degree[in] The degree $d$. Must satisfy $1\le$ degree $\le 5$.
mlamda[in] The number of knots $M$. If lstsqr AMA_Boolean_True, then must satisfy mlamda $\ge 2$.
lamda[in] Array of size mlamda containing the knot vector ${\bf\Lambda}$. If lstsqr AMA_Boolean_True, then must be a valid knot vector.
lstsqr[in] The least squares approximation flag. If it equals AMA_Boolean_True, then this function is being called by a least squares approximation function.
Returns
Success/Error Code.

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

long int AMA_UnvPnltrm ( AMA_OPTIONS options,
double  theta,
long int  porder,
CNSPLA_SPLFUN *  splfun 
)

Define penalty term on an univariate spline.

This function defines a penalty term $\theta F^{(p)}(s(x)$ for $p=0$ or $p=2$ on an univariate spline

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

of degree $d$ where ${\bf\Lambda}$ is

\[ {\bf\Lambda} = ( \lambda_1,\cdots,\lambda_{d+1}, \lambda_{d+2}, \cdots, \lambda_m, \lambda_{m+1},\cdots,\lambda_{m+d+1} )^T. \]

The penalty term is

\[ F^{(p)}(s(x)) = \int_{\lambda_1}^{\lambda_{m+d+1}}\left( s^{(p)}(x) \right)^2dx. \]

Parameters
options[in] Pointer to AMA_OPTIONS. Should be initialized with AMA_Options() prior to calling AMA_UnvPnltrm().
theta[in] The penalty term weight $\theta$. Should satisfy $0.0\le$ theta $\le 1.0$.
porder[in] The penalty term order $p$. Should satisfy porder $=0$ or porder $=2$.
splfun[in] Pointer to CNSPLA_SPLFUN containing the spline $s(x)$ upon which the penalty term is imposed. Should satisfy splfun $\ne$ NULL.
Returns
Success/Error Code.

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