PRO calculate_integer_sequence_of_powers_of_2darr, x, power_first, power_step, npowers, xpowers, status
; Description: This module calculates the elements of the two-dimensional array "x" raised to
; different integer powers. The integer powers that are used form a sequence generated
; from the parameters defining the first integer power "power_first" in the sequence,
; the integer step size "power_step" between consecutive powers, and the total number of
; integer powers "npowers" to be calculated. For example, setting "power_first" to "1",
; "power_step" to "2", and "npowers" to "5", would generate the following sequence of
; numbers for each element of "x":
;
; x^1, x^3, x^5, x^7, x^9
;
; The three-dimensional array of numbers representing the different powers of the
; two-dimensional array "x" is returned via the parameter "xpowers".
;
; N.B: (i) Negative powers of zero are undefined. Hence, if the sequence 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.
;
; (ii) I have attempted to optimise the calculation of the integer powers of
; the elements of "x" by starting with the smallest absolute power of the
; elements of "x" and then applying the relevant factors between each power
; in the sequence, which is a constant factor for each element of "x".
; However, in IDL, this theoretical optimisation actually tends to slow down
; the routine, and therefore I have implemented the brute-force approach.
;
; Input Parameters:
;
; x - FLOAT/DOUBLE ARRAY - A two-dimensional array for which the sequence of integer powers is to
; be calculated for each element.
; power_first - INTEGER/LONG - The first integer power in the sequence of powers to be applied to
; "x".
; power_step - INTEGER/LONG - The integer step size between consecutive integer powers in the
; sequence of powers to be applied to "x".
; npowers - INTEGER/LONG - The total number of integer powers of "x" to be calculated. This
; parameter must be positive.
;
; 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 sequence. The array
; "x^m[i]", where "m[i]" is the ith power in the sequence of integer
; powers, is stored as "xpowers[i,*,*]" in this array. The sequence 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:
;
; 23/10/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_first" and "power_step" are numbers of the correct number type
;Check that "npowers" is a positive number of the correct number type
;Check that there are no zero elements of "x" that will be raised to a negative power in the
;sequence
;If "npowers" is equal to "1"
;Calculate the single integer power of the elements of "x"
;Set "status" to "1" and finish
;If "power_first" is equal to "0" and "power_step" is equal to "0"
;Prepare the array of integer powers of "x"
;Set "status" to "1" and finish
;Prepare the array of integer powers of "x"
;If "power_step" is equal to "0"
;Calculate the first integer power of the elements of "x" and replicate this array
;"npowers" times
;Set "status" to "1" and finish
;Generate the sequence of integer powers
;For each integer power, calculate the power of the elements of "x"
;Set "status" to "1"