PRO calculate_integer_powers_of_2darr, x, power_vec, xpowers, status
; Description: This module calculates the elements of the two-dimensional array "x" raised to a set
; of integer powers defined by "power_vec". The three-dimensional array of numbers
; representing the different powers of the two-dimensional array "x" is returned via
; the parameter "xpowers".
;
; N.B: Negative powers of zero are undefined. Hence, if the set of integer powers
; includes any negative powers, then "x" must have no zero elements. This module
; checks that all powers of the elements of "x" are properly defined, and will
; fail by returning a "status" of "0" if this is not the case.
;
; Input Parameters:
;
; x - FLOAT/DOUBLE ARRAY - A two-dimensional array for which the set of integer powers is to be
; calculated for each element.
; power_vec - INTEGER/LONG VECTOR - A one-dimensional vector of length "npowers" containing the
; set of integer powers to which the elements of "x" are to be
; raised.
;
; Output Parameters:
;
; xpowers - DOUBLE ARRAY - A three-dimensional array of size "npowers" by "n1" by "n2" elements
; where "n1" and "n2" are the sizes of the first and second dimensions
; of "x". This array contains the versions of the array "x" raised to
; the different integer powers in the requested set. The array "x^m[i]",
; where "m[i]" is the ith power in the set of integer powers, is stored
; as "xpowers[i,*,*]" in this array. The set of powers of the (j,k)th
; individual element of "x" is stored as "xpowers[*,j,k]" in this array.
; status - INTEGER - If the module successfully creates the array of integer powers of "x", then
; "status" is returned with a value of "1", otherwise it is returned with a
; value of "0".
;
; Author: Dan Bramich (dan.bramich@hotmail.co.uk)
;
; History:
;
; 05/12/2010 - Module created (dmb).
;Set the default output parameter values
;Check that "x" is a two-dimensional array of the correct number type
;Check that "power_vec" is a one-dimensional vector of the correct number type
;Check that there are no zero elements of "x" that will be raised to a negative power
;Determine the unique set of integer powers
;Prepare the array of integer powers of "x"
;For each unique integer power
;Extract the current unique integer power
;Determine the set of like integer powers
;If the current unique integer power is "0"
;Store the current unique integer power of the elements of "x"
;If the current unique integer power is "1"
;Store the current unique integer power of the elements of "x"
;If the current unique integer power is "-1"
;Calculate and store the current unique integer power of the elements of "x"
;If the current unique integer power is not "0", "1", or "-1"
;Calculate and store the current unique integer power of the elements of "x"
;Set "status" to "1"