FUNCTION calculate_polynomial_1d, x, fx, x0, polyterms, polycoeffs, status, NO_PAR_CHECK = no_par_check
; Description: For an input parameter "x", the function first transforms "x" into a new
; variable "X" defined by:
;
; X = fx*(x - x0)
;
; The function then calculates and returns the value of the polynomial function
; of "X" defined by the polynomial terms "polyterms" and the corresponding
; polynomial coefficients "polycoeffs". The input parameter "x" may be a scalar,
; vector or array.
;
; N.B: For reasons of efficiency and numerical accuracy, the method implemented in
; this module for calculating the values of the polynomial terms uses only
; multiplications and additions, avoiding the use of the exponentiation
; operation "^".
;
; Input Parameters:
;
; x - FLOAT/DOUBLE SCALAR/VECTOR/ARRAY - The value of the independent variable.
; fx - FLOAT/DOUBLE - The scale factor for the independent variable as defined above.
; x0 - FLOAT/DOUBLE - The offset for the independent variable as defined above.
; polyterms - INTEGER/LONG VECTOR - A one-dimensional vector of length "nterms" that contains
; the exponents of the independent variable for each
; polynomial term. All values in this vector must be
; non-negative.
; polycoeffs - FLOAT/DOUBLE VECTOR - A one-dimensional vector of length "nterms" that contains
; the set of polynomial coefficients corresponding to the
; polynomial terms defined by "polyterms".
; status - ANY - A variable which will be used to contain the output status of the function
; on returning (see output parameters below).
;
; Output Parameters:
;
; status - INTEGER - If the function successfully calculated the polynomial function value(s),
; then "status" is returned with a value of "1", otherwise it is returned
; with a value of "0".
;
; Return Value:
;
; The return value is a SCALAR/VECTOR/ARRAY (the same as the input parameter "x") of DOUBLE
; type that takes the value of the requested polynomial function.
;
; Keywords:
;
; If the keyword NO_PAR_CHECK is set (as "/NO_PAR_CHECK"), then the function will not perform
; parameter checking on the input parameters, reducing function overheads.
;
; Author: Dan Bramich (dan.bramich@hotmail.co.uk)
;
; History:
;
; 07/12/2010 - Module created (dmb).
;Set the default output parameter values
;Perform parameter checking if not instructed otherwise
;Check that "x" is of the correct number type
;Check that "fx" and "x0" are numbers of the correct type
;Check that "polyterms" is a one-dimensional vector of the correct number type, and that it has no
;negative elements
;Check that "polycoeffs" is a one-dimensional vector of the correct number type with the correct
;number of elements
;Determine the polynomial coefficients corresponding to a vector of polynomial terms that contains
;all of the input polynomial terms
;If the only polynomial term is a constant term
;Set the value(s) of the polynomial function to the value of the constant term
;Set "status" to "1" and return the value(s) of the polynomial function
;Transform the independent variable "x" into the new variable "X" as defined above
;Calculate the value(s) of the polynomial function
;Set "status" to "1"
;Return the value(s) of the polynomial function