FUNCTION calculate_polynomial_2d, x, y, fx, fy, x0, y0, polyterms, polycoeffs, status, NO_PAR_CHECK = no_par_check
; Description: For the input parameters "x" and "y", the function first transforms "x" and "y"
; into the new variables "X" and "Y" defined by:
;
; X = fx*(x - x0)
; Y = fy*(y - y0)
;
; The function then calculates and returns the value of the polynomial function
; of "X" and "Y" defined by the polynomial terms "polyterms" and the corresponding
; polynomial coefficients "polycoeffs". The input parameters "x" and "y" may be
; scalars, vectors or arrays, and they must have the same number of elements.
;
; 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 first independent variable.
; y - FLOAT/DOUBLE SCALAR/VECTOR/ARRAY - The value of the second independent variable. This
; parameter must have the same number of elements as
; the input parameter "x".
; fx - FLOAT/DOUBLE - The scale factor for the first independent variable "x" as defined above.
; fy - FLOAT/DOUBLE - The scale factor for the second independent variable "y" as defined above.
; x0 - FLOAT/DOUBLE - The offset for the first independent variable "x" as defined above.
; y0 - FLOAT/DOUBLE - The offset for the second independent variable "y" as defined above.
; polyterms - INTEGER/LONG ARRAY - A 2 by "nterms" array of values where each pair of numbers
; represents the exponents of the first and second independent
; variables "x" and "y" for each polynomial term. All values
; in this array must be non-negative. Note that since IDL
; treats a 2 by 1 array as a two-element one-dimensional
; vector, this module accepts such a two-element one-dimensional
; vector to represent the case when "nterms" is equal to "1".
; 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:
;
; 08/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 "y" is of the correct number type and that it has the same number of elements as "x"
;Check that "fx", "fy", "x0" and "y0" are numbers of the correct type
;Check that "polyterms" is a number array of the correct number type, dimensions and size, 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 grid 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
;Transform the independent variable "y" into the new variable "Y" as defined above
;Set up the output value(s)
;For each power of "y" in the set of polynomial terms
;Define or update the current power of "y"
;If all of the polynomial coefficients for the polynomial terms corresponding to the current
;power of "y" are zero, then continue
;Determine the maximum power of "x" in the set of polynomial terms corresponding to the current
;power of "y" that have non-zero polynomial coefficients
;Calculate the values of the relevant polynomial terms
;Set "status" to "1" and return the value(s) of the polynomial function