NAME:
  smplprb
 PURPOSE:   (one line only)
  Sample a probability function to facilitate drawing random numbers from it.
 DESCRIPTION:
  This program is intended to take a probability function, and return
    an array that if plotted as a histogram will look like the probability
    function.  The array that is produced is meant to be used to draw
    random numbers that will be characterized by the probility function.
 CATEGORY:
  Mathematical
 CALLING SEQUENCE:
  xval=SMPLPRB(func,x1,x2,n)
 INPUTS:
  func   -String. Function name. ex: 'sqrt' or 'alog'
              Any positive definite function can be used and must take
               one and only one argument.
  x1     - Min of x range.
  x2     - Max of x range. 
 OPTIONAL INPUT PARAMETERS:
  n      - Size of output array.  Determines sampling size.
           DEFAULT=10000.  As this number is increased the resolution of
           the sampled probability function is improved.  Successful usage
           of this routine will depend on tuning this value.
 KEYWORD INPUT PARAMETERS:
 PLOT    - Flag, if set will cause a plots to be generated to show
             a histogram derived from xval with the function overplotted.
 DEBUG   - Flag, if set will print some internal debugging information.
 RANDOMIZE - Flag, if set will force the returned array to be in random
               order.  The default is to turn them in an order sorted by
               increasing function value.
 OUTPUTS:
  returns an array of n x-values between x1 and x2.  Each discrete value of
     X appears in the output array as many times as is needed to represent
     the probability of that value.  This is a relative number since
     increasing N will increase the number of times that every value of X
     will appear.
 KEYWORD OUTPUT PARAMETERS:
 COMMON BLOCKS:
 SIDE EFFECTS:
 RESTRICTIONS:
  Can only take probability functions, i.e. the function cannot be
  less than zero.
 PROCEDURE:
 MODIFICATION HISTORY:
  2004/07/13, Written by Maureen Teyssier, REU Lowell Observatory
  2004/07/15, MWB, incorporated into library.
  2013/08/14, MWB, slight algorithmic improvements, on average the results
                     are nearly the same but the sampling is slightly more
                     robust and cleaner now.  Also added the DEBUG and
                     RANDOMIZE keyword.
  2016/08/18, MWB, changed plots to black on white and fixed a minor
                     edge effect that would cause the routine to crash.