Options Functions

This page describes functions for initializing and maintaining the AMA Spline Library environment.

The first input parameter for all AMA Spline Library functions is a pointer to an AMA_OPTIONS structure. This structure must be initialized with AMA_Options() prior to calling any other AMA Spline Library function. If it is not initialized before calling an AMA Spline Library function, then the function reports an AMA Initialization Error. An AMA_OPTIONS structure consists of various flags which control the AMA Spline Library computational environment. These flags are separated into three categories: the first category consists of general flags which control error messages and function output; the second category consists of approximation flags which set algorithm options for the univariate and multivariate approximation and interpolation functions; and the third category consists of spline evaluation flags which control input error checking and extrapolation for the spline evaluation functions. AMA Spline Library functions for setting these three categories of flags are presented in the following sections.

General Options Functions

This section contains a list of AMA Spline Library functions which define the AMA_OPTIONS parameter required by all AMA Spline Library Functions. The function AMA_Options() must be called prior to invoking any of the other AMA Spline Library Functions. The function AMA_OptionsFree() should be called after usage of all other AMA Spline Library Functions is completed. The functions AMA_OptionsSetErrorFlag() and AMA_OptionsSetErrorFp() provide the ability to disable or redirect AMA Spline Library Functions error/warning messages, respectively. The functions AMA_OptionsSetOutputFlag() and AMA_OptionsSetOutputFp() provide the ability to disable or redirect AMA Spline Library Functions output, respectively. The functions AMA_OptionsSetDefaults() and AMA_OptionsWrite() are provided for convenience.

An example of using these functions is given in exampleAMA_Options.c.

Spline Approximation Options Functions

This section contains a list of AMA Spline Library functions for setting the AMA_OPTIONS approximation flags which define default algorithm options that influence the nature of the spline approximations produced by the univariate and multivariate approximation and interpolation functions presented on pages Univariate Data Functions, Multivariate Random Data Functions and Multivariate Gridded Data Functions. Based on the default values for the approximation flags all the approximation and interpolation functions initialize the spline coefficients to zero and do not imposed bounds, the univariate and multivariate least squares approximation functions do not perform a minimum norm optimization, the univariate and multivariate monotonic approximation and interpolation functions impose full continuity(degree $d$ splines are continuous in their first $d-1$-th derivatives) at the knots in each independent variable, the multivariate monotonic approximation and interpolation functions imposed monotonicity constraints in each independent variable, and, the penalty term for all multivariate functions is imposed on second order partials in each independent variable and on second order cross partials. The default values of the approximation flags can be overridden with the following functions.

Table Approximation Options Defaults specifies default values for the approximation options for the AMA Spline Library approximation and interpolation functions. A value of NA indicates the option does not apply to the function and setting the option with its corresponding Spline Approximation Option Function does not alter the spline approximation or interpolant produced by the function. Any approximation options set prior to invoking an approximation or interpolation function are first employed by the function and then reset to their default values.

Approximation Options Defaults
Function Option
Bounds Coefficients Continuity Minimum Norm Monotonicity Penalty Term
AMA_UnvLstsqr() Unbounded $\alpha_o = 0.0$ NA Disabled NA NA
AMA_UnvApprox() NA $\alpha_o = 0.0$ NA NA NA NA
AMA_UnvInterp() NA $\alpha_o = 0.0$ NA NA NA NA
AMA_UnvMonoApprox() NA $\alpha_o = 0.0$ AMA_Continuity_Full NA AMA_Monotonicity_Enabled NA
AMA_UnvMonoInterp() NA $\alpha_o = 0.0$ AMA_Continuity_Full NA AMA_Monotonicity_Enabled NA
AMA_MltvLstsqr() Unbounded $\alpha_o = 0.0$ NA Disabled NA Cross Partials Included
AMA_MltvApprox() Unbounded $\alpha_o = 0.0$ NA NA NA Cross Partials Included
AMA_MltvInterp() Unbounded $\alpha_o = 0.0$ NA NA NA Cross Partials Included
AMA_MltvMonoApprox() Unbounded $\alpha_o = 0.0$ AMA_Continuity_Full NA AMA_Monotonicity_Enabled Cross Partials Included
AMA_MltvMonoInterp() Unbounded $\alpha_o = 0.0$ AMA_Continuity_Full NA AMA_Monotonicity_Enabled Cross Partials Included
AMA_MltvGrdLstsqr() Unbounded $\alpha_o = 0.0$ NA Disabled NA NA
AMA_MltvGrdApprox() NA $\alpha_o = 0.0$ NA NA NA NA
AMA_MltvGrdInterp() NA $\alpha_o = 0.0$ NA NA NA NA
AMA_MltvGrdMonoApprox() NA $\alpha_o = 0.0$ AMA_Continuity_Full NA AMA_Monotonicity_Enabled NA
AMA_MltvGrdMonoInterp() NA $\alpha_o = 0.0$ AMA_Continuity_Full NA AMA_Monotonicity_Enabled NA

An example of reducing the continuity of a spline approximation at the knots with AMA_OptionsSetContinuity() is given in Section AMA_UnvMonoInterp() - Monotonic Interpolation of Univariate Data. The result of enabling the minimum norm optimization with AMA_OptionsSetMinimumNorm() is illustrated in Section AMA_MltvLstsqr() - Least Squares Approximation of Multivariate Data. The effect of monotonicity constraints is shown in numerous examples presented on pages Univariate Data Functions and Multivariate Data Functions And, in what follows, the influence of the second order cross partials of the penalty term on an approximation is discussed.

The program exampleAMA_OptionsPenaltyTerm.c illustrates usage of the function AMA_OptionsSetPenaltyTerm(). It employs the multivariate functions AMA_MltvApprox() and AMA_MltvInterp() to compute approximations required to solve a minimum time to climb problem. The original minimum time to climb problem was presented by Byson et al. The basic problem is to choose the optimal control function $\alpha(t)$ (the angle of attack with respect to time, $t$) such that an airplane flies from a point on the runway to a specified final altitude as quickly as possible. In its simplest form the planar motion of the the aircraft is described by the ordinary differential equations

\begin{eqnarray*} \dot h &=& v\sin\gamma, \cr \dot v &=& {1\over m}\left[T(M,h)\cos\alpha-D\right] - {\mu\over (R_e-h)^2}\sin\gamma, \cr \dot\gamma &=& {1\over mv}\left[T(M,h)\sin\alpha-L\right] + \cos\gamma\left[{v \over (R_e+h)} - {\mu\over v(R_e+h)^2}\right], \cr \dot w &=& {-T(M,h)\over I_{sp}}, \cr \end{eqnarray*}

where $h$ is the altitude, $M$ the Mach, $v$ the velocity, $w$ the airplane's weight, $m$ the airplane's mass, $\mu$ the gravitational constant and $R_e$ the radius of the earth. The function $T(M,h)$ represents the airplane's thrust as a function of Mach and altitude and is based on the data given in the following table.

Thrust $T(M,h)$ (thousands of lb)
$M$ Altitude $h$ (thousands of ft)
0.0 5.0 10.0 15.0 20.0 25.0 30.0 40.0 50.0 70.0
0.0 24.2
0.2 28.0 24.6 21.1 18.1 15.2 12.8 10.7
0.4 28.3 25.2 21.9 18.7 15.9 13.4 11.2 7.3 4.4
0.6 30.8 27.2 23.8 20.5 17.3 14.7 12.3 8.1 4.9
0.8 34.5 30.3 26.6 23.2 19.8 16.8 14.1 9.4 5.6 1.1
1.0 37.9 34.3 30.4 26.8 23.3 19.8 16.8 11.2 6.8 1.4
1.2 36.1 38.0 34.9 31.3 27.3 23.6 20.1 13.4 8.3 1.7
1.4 36.6 38.5 36.1 31.6 28.1 24.2 16.2 10.0 2.2
1.6 38.7 35.7 32.0 28.1 19.3 11.9 2.9
1.8 34.6 31.1 21.7 13.3 3.1

In order to solve the minimum time to climb problem with a derivative based optimization technique a continuous representation of the thrust data must be defined. In what follows the function AMA_MltvInterp() is used to compute a cubic spline interpolant of the thrust data. Graphical illustrations of the spline interpolant are shown in Figure Interpolation of Thrust Data. The figure consists of two panels each of which show the data, represented as red spheres, and its spline interpolant, represented as a gray surface. The left hand panel contains the interpolant associated with the default penalty term

\[ F^{(2)}(s({\bf X})) = \int_R\left(\partial^2 s({\bf X})\over\partial^2 x_1\right)^2dR + 2.0\int_R\left(\partial^2 s({\bf X})\over\partial x_1 \partial x_2\right)^2dR + \int_R\left(\partial^2 s({\bf X})\over\partial^2 x_2\right)^2dR. \]

For the interpolant in the right hand panel AMA_OptionsSetPenaltyTerm() is used to remove the integral of the cross partial term from the penalty term so AMA_MltvInterp() minimizes the penalty term

\[ F^{(2)}(s({\bf X})) = \int_R\left(\partial^2 s({\bf X})\over\partial^2 x_1\right)^2dR + \int_R\left(\partial^2 s({\bf X})\over\partial^2 x_2\right)^2dR. \]

Interpolation of Thrust Data
Default Penalty Term Cross Partial Removed from Penalty Term

The surface in Figure Interpolation of Thrust Data is oriented such that the $(M,h)=(0.0,0.0)$ data point for which $T(M,h)=24.2$ resides at the upper left hand corner of the surface and the missing data for $M=0.0$ and $h\in[5.0,70.0]$ is along the left hand boundary curve of the surface. It is in this region of missing data that the influence of the cross partial term is most evident. When the default penalty term is employed the convex down behavior of the surface based on the data at $h=0.0$ and $M\in[0.0,0.4]$ propagates through the surface over the region $(M,h)\in[0.0,0.4]\times[0.0,30.0]$, eventually damping out near the $(M,h)=(0.0,70.0)$ corner of the surface. When the cross partial term is removed from the penalty term the convex down behavior damps out immediately and is not evident in the region $(M,h)\in[0.0,0.4]\times[10.0,30.0]$. Hence, exclusion of the cross partial term results in a significantly different surface in the missing data regions. Which surface is "correct" may be based merely on preference. Alternatively, it may be the surface which produces the "best" solution to the minimum time to climb problem.

Spline Evaluation Options Functions

This section contains a list of AMA Spline Library functions for setting the AMA_OPTIONS spline evaluation flags. These flags control error checking of the spline evaluation functions' input parameters and whether the functions perform extrapolation. If extrapolation is not enabled and the point of evaluation lies outside a spline's domain, then the spline evaluation functions report an input error. Otherwise, they report a warning error and extrapolate the spline in order to evaluate the spline at the point. An example of using these functions is given in exampleAMA_SplineValue() of exampleAMA_Spline.c.