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
- Spline Approximation Options Functions
- Spline Evaluation 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.

- AMA_Options() -
**Allocate and Initialize AMA_OPTIONS Structure** - AMA_OptionsFree() -
**Free AMA_OPTIONS Structure** - AMA_OptionsSetDefaults() -
**Set AMA_OPTIONS Defaults** - AMA_OptionsSetErrorFlag() -
**Set Error Message Flag** - AMA_OptionsSetErrorFp() -
**Set Error Message File** - AMA_OptionsSetOutputFlag() -
**Set Output Level Flag** - AMA_OptionsSetOutputFp() -
**Set Output File** - AMA_OptionsWrite() -
**Write AMA_OPTIONS Structure**

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

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 splines are continuous in their first -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.

- AMA_OptionsSetBounds() -
**Set Spline Bounds** - AMA_OptionsSetCoefficients() -
**Set Spline Coefficient's Initial Value** - AMA_OptionsSetContinuity() -
**Set Continuity Condition** - AMA_OptionsSetMinimumNorm() -
**Enable/Disable Minimum Norm Optimization** - AMA_OptionsSetMonotonicity() -
**Enable/Disable Monotonicity Constraints** - AMA_OptionsSetPenaltyTerm() -
**Set Penalty Term**

**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.

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 (the angle of attack with respect to time, ) 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

where is the altitude, the Mach, the velocity, the airplane's weight, the airplane's mass, the gravitational constant and the radius of the earth. The function represents the airplane's thrust as a function of Mach and altitude and is based on the data given in the following table.

Altitude (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

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

Default Penalty Term | Cross Partial Removed from Penalty Term |
---|---|

The surface in **Figure** Interpolation of Thrust Data is oriented such that the data point for which resides at the upper left hand corner of the surface and the missing data for and 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 and propagates through the surface over the region , eventually damping out near the 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 . 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.

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.

- AMA_OptionsSetExtrapolation() -
**Enable/Disable Extrapolation** - AMA_OptionsSetInputCheck() -
**Enable/Disable Input Error Checking**

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