PRO calculate_integer_sequence_of_powers_of_scalar, x, power_first, power_step, npowers, xpowers, status
; Description: This module calculates the scalar number "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:
;
; x^1, x^3, x^5, x^7, x^9
;
; The vector of numbers representing the different powers of "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 be non-zero. This module
; checks that all powers 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 "x"
; by starting with the smallest absolute power of "x" and then applying the
; relevant constant factor between each power in the sequence. 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 - A scalar number for which the sequence of integer powers is to be calculated.
; 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 VECTOR - A one-dimensional vector of length "npowers" containing the requested
; sequence of integer powers of "x".
; status - INTEGER - If the module successfully creates the vector 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:
;
; 21/10/2010 - Module created (dmb).
;Set the default output parameter values
;Check that "x" is a scalar number 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 if "x" is zero, then there are no negative powers in the sequence of integer powers
;If "npowers" is equal to "1"
;Calculate the single integer power of "x"
;Set "status" to "1" and finish
;If "power_step" is equal to "0"
;Calculate the first integer power of "x" and replicate this value "npowers" times
;Set "status" to "1" and finish
;Generate the sequence of integer powers
;Calculate the sequence of integer powers of "x"
;Set "status" to "1"