Functions
AMA_Options.h File Reference
#include <cnspla.h>
#include <stdio.h>
#include <stdlib.h>

Go to the source code of this file.

Functions

long int AMA_Options (AMA_OPTIONS **options)
 Allocate and Initialize AMA_OPTIONS Structure More...
 
long int AMA_OptionsFree (AMA_OPTIONS **options)
 Free AMA_OPTIONS Structure More...
 
long int AMA_OptionsSetBounds (AMA_OPTIONS *options, double lwrbnd, double uprbnd)
 Set Spline Bounds More...
 
long int AMA_OptionsSetCoefficients (AMA_OPTIONS *options, double alpha)
 Set Spline Coefficient's Initial Value More...
 
long int AMA_OptionsSetContinuity (AMA_OPTIONS *options, long int kindex, enum AMA_Continuity continuity)
 Set Continuity Condition More...
 
long int AMA_OptionsSetDefaults (AMA_OPTIONS *options)
 Set AMA_OPTIONS Defaults More...
 
long int AMA_OptionsSetErrorFlag (AMA_OPTIONS *options, enum AMA_ErrorFlag errorFlag)
 Set Error Message Flag More...
 
long int AMA_OptionsSetErrorFp (AMA_OPTIONS *options, FILE *errorFp)
 Set Error Message File More...
 
long int AMA_OptionsSetExtrapolation (AMA_OPTIONS *options, enum AMA_Boolean extrapolation)
 Enable/Disable Extrapolation More...
 
long int AMA_OptionsSetIterationLimit (AMA_OPTIONS *options, long int itrlim)
 
long int AMA_OptionsSetInputCheck (AMA_OPTIONS *options, enum AMA_Boolean inputCheck)
 Enable/Disable Input Error Checking More...
 
long int AMA_OptionsSetMinimumNorm (AMA_OPTIONS *options, enum AMA_Boolean minorm)
 Enable/Disable Minimum Norm Optimimzation More...
 
long int AMA_OptionsSetMltvBoundaryConditions (AMA_OPTIONS *options, long int nind, long int *degree, long int **numcnd, enum AMA_BoundaryConditions **bndcnd, long int **ordlft, long int **ordrgh, AMA_SPLINE **bndlft, AMA_SPLINE **bndrgh)
 Set boundary conditions for multivariate approximation and interpolation functions More...
 
long int AMA_OptionsSetMonotonicity (AMA_OPTIONS *options, long int kindex, enum AMA_Monotonicity monotonicity)
 Enable/Disable Monotonicity Constraints More...
 
long int AMA_OptionsSetOutputFlag (AMA_OPTIONS *options, long int outputFlag)
 Set Output Level Flag More...
 
long int AMA_OptionsSetOutputFp (AMA_OPTIONS *options, FILE *outputFp)
 Set Output File More...
 
long int AMA_OptionsSetPenaltyTerm (AMA_OPTIONS *options, long int kindex, long int lindex, enum AMA_Boolean pnltrm)
 Set Penalty Term More...
 
long int AMA_OptionsSetUnvBoundaryConditions (AMA_OPTIONS *options, long int degree, long int *numcnd, enum AMA_BoundaryConditions *bndcnd, long int *ordlft, long int *ordrgh, double *bndlft, double *bndrgh)
 Set boundary conditions for univariate approximation and interpolation functions More...
 
long int AMA_OptionsWrite (AMA_OPTIONS *options)
 Write AMA_OPTIONS Structure More...
 
long int AMA_OptionsCheck (AMA_OPTIONS *options, const char *function)
 Check AMA_OPTIONS. More...
 
void AMA_OptionsInitialize (AMA_OPTIONS *options)
 Initialize AMA_OPTIONS Structure More...
 

Function Documentation

long int AMA_Options ( AMA_OPTIONS **  options)

Allocate and Initialize AMA_OPTIONS Structure

This function allocates and initializes an AMA_OPTIONS structure and it must be called prior to invoking any of the other AMA Spline Library Functions. It does the following:

Parameters
options[in] Pointer to AMA_OPTIONS pointer to allocate and initialize. Must satisfy options $\ne$ NULL.
Returns
Success/Error Code.
Note
This function writes error/warning messages to stderr.
The function AMA_OptionsFree() should be invoked after usage of all other AMA Spline Library Functions is completed.

User Callable Function - Documented 110914

long int AMA_OptionsCheck ( AMA_OPTIONS *  options,
const char *  function 
)

Check AMA_OPTIONS.

This function does the following:

Parameters
options[in] Pointer to AMA_OPTIONS whose input members are checked. Must be initialized with AMA_Options() prior to calling AMA_OptionsCheck().
function[in] Name of function invoking AMA_OptionsCheck().
Returns
Success/Error Code.
Note
If options is not properly initialize, then this function writes the following error message to stderr. 
INPUT_ERROR: Function function: Called out of sequence - Must call AMA_Options first.

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

long int AMA_OptionsFree ( AMA_OPTIONS **  options)

Free AMA_OPTIONS Structure

This function frees an AMA_OPTIONS structure and it should be called after usage of all other AMA Spline Library Functions is completed. It does the following:

  • Frees AMA_OPTIONS internal members, see AMA_OptionsFreeInternal().
  • Frees AMA_OPTIONS pointer.
Parameters
options[in] Pointer to AMA_OPTIONS pointer to free. Must be initialized with AMA_Options() prior to calling AMA_OptionsFree().
Returns
Success/Error Code.
Note
Failure to invoke this function causes memory leaks.

User Callable Function - Documented 110814

void AMA_OptionsInitialize ( AMA_OPTIONS *  options)

Initialize AMA_OPTIONS Structure

This function initializes an AMA_OPTIONS structure. It does the following:

Parameters
options[in] Pointer to AMA_OPTIONS to initialize.

All AMA_OPTIONS pointers are initialized to NULL. Initial values for other members are listed below.

AMA_OPTIONS Input Members Defined

AMA_OPTIONS Output Members Defined

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

long int AMA_OptionsSetBounds ( AMA_OPTIONS *  options,
double  lwrbnd,
double  uprbnd 
)

Set Spline Bounds

This function sets the lower bound $\alpha_l$ and the upper bound $\alpha_u$ for a univariate spline

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

or for 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}). \]

The univariate and multivariate splines computed by AMA Spline Library approximation and interpolation functions are subject to the bounds

\[ \alpha_l \le s(x) \le \alpha_u \]

and

\[ \alpha_l \le s({\bf X}) \le \alpha_u, \]

respectively. The default lower bound is $\alpha_l = -\alpha_\infty$ and the default upper bound is $\alpha_u = \alpha_\infty$, where $\alpha_\infty$ equals AMA_SplineInfbnd(). Therefore, by default, a spline is unbounded but finite bounds can be set with this function. For a given set of dependent variable data $z_\ell$, for $\ell=1,\ldots,N$, the bounds must satisfy the conditions $\alpha_l \le \min_\ell\lbrace{z_\ell\rbrace}$ and $\alpha_u \ge \max_\ell\lbrace{z_\ell\rbrace}$. These conditions are checked by the AMA Spline Library approximation and interpolation functions prior to computing their respective spline approximation or interpolant.

The lower and upper bound can be set for the following functions:

Univariate Data Functions

Multivariate Data Functions

Parameters
options[in] Pointer to AMA_OPTIONS. Must be initialized with AMA_Options() prior to calling AMA_OptionsSetBounds().
lwrbnd[in] The lower bound $\alpha_l$. Must satisfy $-\alpha_\infty \le \alpha_l \le \min_\ell\lbrace{z_\ell\rbrace}$ and $\alpha_l\le \alpha_u$.
uprbnd[in] The upper bound $\alpha_u$. Must satisfy $\max_\ell\lbrace{z_\ell\rbrace}\le \alpha_u \le \alpha_\infty$ and $\alpha_u\ge \alpha_l$.
Returns
Success/Error Code.

User Callable Function - Documented 101815

long int AMA_OptionsSetCoefficients ( AMA_OPTIONS *  options,
double  alpha 
)

Set Spline Coefficient's Initial Value

This function sets the value $\alpha_o$ used to initialize the spline coefficients $\alpha_j$, for $j=1,\ldots,m$, of a univariate spline

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

or the spline coefficients $\alpha_{j_1,\ldots,j_n}$, for $j_k=1,\ldots,m_k$ and $1\le k\le n$, of 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}). \]

The initial spline coefficient value can be set for the following functions:

Univariate Data Functions

Multivariate Data Functions

Parameters
options[in] Pointer to AMA_OPTIONS. Must be initialized with AMA_Options() prior to calling AMA_OptionsSetCoefficients().
alpha[in] The initial value $\alpha_o$ of the spline coefficients.
Returns
Success/Error Code.

User Callable Function - Documented 101515

long int AMA_OptionsSetContinuity ( AMA_OPTIONS *  options,
long int  kindex,
enum AMA_Continuity  continuity 
)

Set Continuity Condition

This function sets the continuity condition for a univariate spline

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

or for 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}). \]

It can be used to set the continuity condition in any independent variable $x_k$, for $1\le k\le n$. The continuity condition can be set for the following functions:

Univariate Data Functions

Multivariate Data Functions

See AMA_Continuity for additional information about the continuity condition.

Parameters
options[in] Pointer to AMA_OPTIONS. Must be initialized with AMA_Options() prior to calling AMA_OptionsSetContinuity().
kindex[in] The independent variable index $k$ for which the continuity condition is set. Must satisfy $1\le$ kindex $\le$ AMA_MXNIND.
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$.
Returns
Success/Error Code.

User Callable Function - Documented 101515

long int AMA_OptionsSetDefaults ( AMA_OPTIONS *  options)

Set AMA_OPTIONS Defaults

This function sets the members of an AMA_OPTIONS structure to their default values. It does the following:

  • Frees AMA_OPTIONS internal members, see AMA_OptionsFreeInternal().
  • Initializes AMA_OPTIONS structure, see AMA_OptionsInitialize().
  • Allocates AMA_OPTIONS internal members, see AMA_OptionsAllocateInternal().
Parameters
options[in] Pointer to AMA_OPTIONS whose members are set to their default values. Must be initialized with AMA_Options() prior to calling AMA_OptionsSetDefaults().
Returns
Success/Error Code.

AMA_OPTIONS Input Members Defined

AMA_OPTIONS Output Members Defined

User Callable Function - Documented 022115

long int AMA_OptionsSetErrorFlag ( AMA_OPTIONS *  options,
enum AMA_ErrorFlag  errorFlag 
)

Set Error Message Flag

This function sets the AMA Spline Library's error message flag which enables/disables error messages reported by AMA Spline Library Functions.

Parameters
options[in] Pointer to AMA_OPTIONS. Must be initialized with AMA_Options() prior to calling AMA_OptionsSetErrorFlag().
errorFlag[in] Error message flag. It has one of the following two values:
Returns
Success/Error Code.
Note
Error messages reported by AMA Spline Library Functions can be redirected to a file, see AMA_OptionsSetErrorFp().
The error message flag is stored in AMA_OPTIONS::errorFlag.

User Callable Function - Documented 110914

long int AMA_OptionsSetErrorFp ( AMA_OPTIONS *  options,
FILE *  errorFp 
)

Set Error Message File

This function sets the AMA Spline Library's error message file pointer to which AMA Spline Library Functions' error messages are written.

Parameters
options[in] Pointer to AMA_OPTIONS. Must be initialized with AMA_Options() prior to calling AMA_OptionsSetErrorFp().
errorFp[in] Pointer to file to which error messages are written. Must satisfy errorFp $\ne$ NULL.
Returns
Success/Error Code.
Note
Error messages are written to errorFp only if the AMA Spline Library's error message flag is enabled, see AMA_OptionsSetErrorFlag().
The error message file pointer is stored in AMA_OPTIONS::errorFp.

User Callable Function - Documented 110914

long int AMA_OptionsSetExtrapolation ( AMA_OPTIONS *  options,
enum AMA_Boolean  extrapolation 
)

Enable/Disable Extrapolation

This function enables/disables extrapolation when evaluating a 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}). \]

The extrapolation option is employed by the following functions:

Parameters
options[in] Pointer to AMA_OPTIONS. Must be initialized with AMA_Options() prior to calling AMA_OptionsSetExtrapolation().
extrapolation[in] Extrapolation flag. It has one of the following two values:
  • If extrapolation equals AMA_Boolean_True, then extrapolation is performed when ${\bf X}$ lies outside the spline's domain.
  • If extrapolation equals AMA_Boolean_False, then extrapolation is not performed when ${\bf X}$ lies outside the spline's domain.
Returns
Success/Error Code.
long int AMA_OptionsSetInputCheck ( AMA_OPTIONS *  options,
enum AMA_Boolean  inputCheck 
)

Enable/Disable Input Error Checking

This function enables/disables input error checking when evaluating a 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}). \]

The input error checking option is employed by the following functions:

Disabling input error checking reduces the execution time of these functions.

Parameters
options[in] Pointer to AMA_OPTIONS. Must be initialized with AMA_Options() prior to calling AMA_OptionsSetInputCheck().
inputCheck[in] Input error checking flag. It has one of the following two values:
Returns
Success/Error Code.

User Callable Function - Documented 090115

long int AMA_OptionsSetIterationLimit ( AMA_OPTIONS *  options,
long int  itrlim 
)
long int AMA_OptionsSetMinimumNorm ( AMA_OPTIONS *  options,
enum AMA_Boolean  minorm 
)

Enable/Disable Minimum Norm Optimimzation

This function enables/disables the minimum norm optimization for a univariate spline

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

or for 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}). \]

The minimum norm optimization can be enabled/disabled for the following functions:

Univariate Data Functions

Multivariate Data Functions

Parameters
options[in] Pointer to AMA_OPTIONS. Must be initialized with AMA_Options() prior to calling AMA_OptionsSetMinimumNorm().
minorm[in] Minimum norm optimization flag. It has one of two values:
  • If minorm equals AMA_Boolean_True, then minimum norm optimization is performed.
  • If minorm equals AMA_Boolean_False, then minimum norm optimization is not performed.
Returns
Success/Error Code.

User Callable Function - Documented 101515

long int AMA_OptionsSetMltvBoundaryConditions ( AMA_OPTIONS *  options,
long int  nind,
long int *  degree,
long int **  numcnd,
enum AMA_BoundaryConditions **  bndcnd,
long int **  ordlft,
long int **  ordrgh,
AMA_SPLINE **  bndlft,
AMA_SPLINE **  bndrgh 
)

Set boundary conditions for multivariate approximation and interpolation functions

User Callable Function - Documented nnnnnn

long int AMA_OptionsSetMonotonicity ( AMA_OPTIONS *  options,
long int  kindex,
enum AMA_Monotonicity  monotonicity 
)

Enable/Disable Monotonicity Constraints

This function enables/disables the monotonicity constraints for a univariate spline

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

or for 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}). \]

It can be used to enable/disable the monotonicity constraints in any independent variable $x_k$, for $1\le k\le n$. Montonicity constraints can be enabled/disabled for the following functions:

Univariate Data Functions

Multivariate Data Functions

See AMA_Monotonicity for additional information about the monotonicity constraints.

Parameters
options[in] Pointer to AMA_OPTIONS. Must be initialized with AMA_Options() prior to calling AMA_OptionsSetMonotonicity().
kindex[in] The independent variable index $k$ in which the monotonicity constraints are imposed. Must satisfy $1\le$ kindex $\le$ AMA_MXNIND.
monotonicity[in] Monotonicity constraint flag. It has one of the following two values:
Returns
Success/Error Code.

User Callable Function - Documented 102515

long int AMA_OptionsSetOutputFlag ( AMA_OPTIONS *  options,
long int  outputFlag 
)

Set Output Level Flag

This function sets the AMA Spline Library's output level flag which specifies the amount of output produced by AMA Spline Library Functions and cnspla.

Parameters
options[in] Pointer to AMA_OPTIONS. Must be initialized with AMA_Options() prior to calling AMA_OptionsSetOutputFlag().
outputFlag[in] Output level flag. Must satisfy $0\le$ outputFlag $\le 5$.
Returns
Success/Error Code.
Note
Output produced by AMA Spline Library Functions and cnspla can be redirected to a file, see AMA_OptionsSetOutputFp().
The output level flag is stored in AMA_OPTIONS::outputFlag.

User Callable Function - Documented 110914

long int AMA_OptionsSetOutputFp ( AMA_OPTIONS *  options,
FILE *  outputFp 
)

Set Output File

This function sets the AMA Spline Library's output file pointer to which AMA Spline Library Functions' and cnspla output is written.

Parameters
options[in] Pointer to AMA_OPTIONS. Must be initialized with AMA_Options() prior to calling AMA_OptionsSetOutputFp().
outputFp[in] Pointer to file to which AMA Spline Library Functions and cnspla output is written. Must satisfy outputFp $\ne$ NULL.
Returns
Success/Error Code.
Note
Output is written to outputFp only if AMA Spline Library's output level flag is greater than zero, see AMA_OptionsSetOutputFlag().
The output file pointer is stored in AMA_OPTIONS::outputFp.

User Callable Function - Documented 110814

long int AMA_OptionsSetPenaltyTerm ( AMA_OPTIONS *  options,
long int  kindex,
long int  lindex,
enum AMA_Boolean  pnltrm 
)

Set Penalty Term

This function sets the penalty term $F^{(2)}(s({\bf X}))$ for 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}) \]

computed by the Multivariate Random Data Functions. By default these functions utilize the penalty term

\[ 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]; \]

but this function can be used to include/exclude one or more of the cross partial terms

\[ 2.0\int_R\left(\partial^2 s({\bf X})\over\partial x_k \partial x_l\right)^2dR, \]

for $1\le k\le n$ and $k < l\le n$. The cross partial terms of $F^{(2)}(s({\bf X}))$ can be included/excluded for the following functions:

Multivariate Random Data Functions

Parameters
options[in] Pointer to AMA_OPTIONS. Must be initialized with AMA_Options() prior to calling AMA_OptionsSetPenaltyTerm().
kindex[in] The first index $k$ of the cross partial term to be included/excluded from the penalty term. Must satisfy $1\le$ kindex $\le$ AMA_MXNIND.
lindex[in] The second index $l$ of the cross partial term to be included/excluded from the penalty term. Must satisfy kindex $<$ lindex $\le$ AMA_MXNIND.
pnltrm[in] Penalty term flag. It has one of the following two values:
  • If pnltrm equals AMA_Boolean_True, then cross partial term is included in the penalty term.
  • If pnltrm equals AMA_Boolean_False, then cross partial term is excluded from the penalty term.
Returns
Success/Error Code.

User Callable Function - Documented 101515

long int AMA_OptionsSetUnvBoundaryConditions ( AMA_OPTIONS *  options,
long int  degree,
long int *  numcnd,
enum AMA_BoundaryConditions *  bndcnd,
long int *  ordlft,
long int *  ordrgh,
double *  bndlft,
double *  bndrgh 
)

Set boundary conditions for univariate approximation and interpolation functions

User Callable Function - Documented nnnnnn

long int AMA_OptionsWrite ( AMA_OPTIONS *  options)

Write AMA_OPTIONS Structure

This function does the following:

Parameters
options[in] Pointer to AMA_OPTIONS whose input members are written. Must be initialized with AMA_Options() prior to calling AMA_OptionsWrite().

Following is an example of the information written by this function when all AMA_OPTIONS members are set to their defaults.

========================================================================================================================================================
===                                              AMA Spline Library Options - Version:1.0.0-a Date:02/24/16                                          ===
========================================================================================================================================================


General Options

Member         Description           Value
====================================================
errorFlag      Error Message Flag    Enabled
errorFp        Error Message File    Standard Output
outputFlag     Output Level Flag     0
outputFp       Output File           Standard Output



                              Monotonicity                      
Variable  Continuity  Positive  Negative    Zero    Penalty Term
================================================================
x_1       Full        Enabled   Enabled   Enabled   1 1 1 1 1 1 
x_2       Full        Enabled   Enabled   Enabled     1 1 1 1 1 
x_3       Full        Enabled   Enabled   Enabled       1 1 1 1 
x_4       Full        Enabled   Enabled   Enabled         1 1 1 
x_5       Full        Enabled   Enabled   Enabled           1 1 
x_6       Full        Enabled   Enabled   Enabled             1 

Description                      Value
==========================================
Minimum Norm Optimization         Disabled
Initial Coefficients Value    0.000000e+00
Lower Bound                  -4.503600e+13
Upper Bound                   4.503600e+13

User Callable Function - Documented 022416

AMA Spline Library Document - Version:1.0.0-a Date:02/24/16 - Generated by   doxygen 1.8.5