PRO calculate_integer_sequence_of_powers_of_1dvec, x, power_first, power_step, npowers, xpowers, status
; Description: This module calculates the elements of the vector "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 two-dimensional array of numbers representing the different powers of the vector
; "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 VECTOR - A one-dimensional vector 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 two-dimensional array of size "npowers" by "n1" elements where "n1"
; is the number of elements in "x". This array contains the versions
; of the vector "x" raised to the different integer powers in the
; requested sequence. The vector "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 jth individual element of "x" is
; stored as "xpowers[*,j]" 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 one-dimensional vector 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 vector
;"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"