PRO define_geometric_bins, value1, value2, factor, nbins, bin_limits, first_bin_size, status
; Description: This module defines the bin limits "bin_limits" for "nbins" bins with sizes that follow a
; geometric sequence between the values "value1" and "value2".
;
; Input Parameters:
;
; value1 - INTEGER/LONG/FLOAT/DOUBLE - The value of the first limit for the range for which bins are
; to be defined. This limit is usually the lower limit for the
; range.
; value2 - INTEGER/LONG/FLOAT/DOUBLE - The value of the second limit for the range for which bins are
; to be defined. This limit is usually the upper limit for the
; range. The value of "value2" must not be equal to the value of
; "value1".
; factor - FLOAT/DOUBLE - The factor relating the size of consecutive bins in ascending order such that
; the (i+1)th bin is a factor "factor" times larger than the ith bin. The value
; of this parameter must be positive.
; nbins - INTEGER/LONG - The number of bins to be defined in the range between "value1" and "value2".
; This parameter must be positive.
;
; Output Parameters:
;
; bin_limits - DOUBLE VECTOR - A one-dimensional vector of size "nbins + 1" with consecutive pairs
; of values representing the lower and upper limits of each bin. For
; instance, the ith bin, with i running from "0" to "nbins - 1", will
; correspond to the range of values between bin_limits[i] and
; bin_limits[i+1], where bin_limits[i] < bin_limits[i+1], regardless
; of whether "value1" is greater than or less than "value2". The size
; of each bin is such that the (i+1)th bin is a factor "factor" times
; larger than the ith bin.
; first_bin_size - DOUBLE - The size of the first bin.
; status - INTEGER - If the module successfully defined a set of bin limits, 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:
;
; 09/12/2009 - Module created (dmb).
;Set the default output parameter values
;Check that "value1" and "value2" are numbers of the correct type, and check that they have sensible
;values
;Check that "factor" is a positive number of the correct type
;Check that "nbins" is a positive number of the correct type
;Create the vector of values defining the bin limits
;Set "status" to "1"