(* source: h:\modula\defs\UnifRNG.DEF     v1.0a             revised: 88.07.18
   author: G.Greene, AGCS D/429 (NS/TS), 312/681-7783       created: 88.07.18

   function:
    This is the definition for a module which exports generators of
    uniformly-distributed pseudo-random variates.  The primary procedure--
    invoked, directly or indirectly, by all other random number generators--
    provides reals in the half-open interval [0,1).  A specialized variant of
    this generates values in the interval (0, 1), for applications wherein
    zero values are not acceptable.  There are also discrete-uniform, general
    continuous rectangular, and Pareto random number generators.  Procedures
    are provided for reading and setting the random number seed value.

   history:
    88.07.18  1.0a  initial release
*)


DEFINITION MODULE UnifRNG;


(*  Return as the function value a Real value which is uniformly distributed
    in the interval [0,1).
*)

PROCEDURE  UniformVariate ( ): LONGREAL;




(*  Since there is a chance, albeit minute, that the standard uniform random-
    number generator will return a zero value, and since a zero value will
    result in an error when used in some applications (particularly other
    random variate generators), we provide this function that is guaranteed
    not to yield a zero value.
*)

PROCEDURE  NonzeroUniformVariate ( ): LONGREAL;



(*  Return as the function value a discrete uniform variate in the range
    specified by the parameters.  The parameters are supposed to be the low
    and high ends of the range of possible values, respectively, but the
    range limits can be presented in either order.  (Reversing the order
    results in an inverting of the returned values, but the distribution
    will still be in the proper range, and no less random.)  The maximum
    number of discrete values that can be generated is MaxInt (32767), thus
    the value abs ( HighValue - LowValue + 1 ) must not exceed MaxInt
    (for example, parameters ( -20000, 20000 ) would not be acceptable).
*)

PROCEDURE  DiscreteVariate (
                    (*in*)  LowValue,
                    (*in*)  HighValue: INTEGER ): INTEGER;

(*                                                                        [2]
 source: h:\modula\defs\UnifRNG.DEF     v1.0a             revised: 88.07.18 *)


(*  Return as the function value a general continuous rectangular variate in
    the range specified by the parameters.  The parameters are supposed to be
    the low and high ends of the range of possible values, respectively, but
    the range limits can be presented in either order.  (Reversing the order
    results in an inverting of the returned values, but the distribution will
    be no less random.)  Resulting values are confined to the interval
    [ LowValue, HighValue ) for the case of parameters in normal order, and
    to ( HighValue, LowValue ] for inverted parameters.  This can be used to
    get special cases:  for uniform variates in the interval ( 0, 1 ] invoke
    this procedure as RectangularVariate ( 1.0, 0.0 ).
*)

PROCEDURE  RectangularVariate (
                       (*in*)  LowValue,
                       (*in*)  HighValue: REAL ): LONGREAL;



(*  Return as the function value a Pareto variate with strictly positive
    shape parameter specified by the function parameter.  A negative actual
    parameter is taken as its absolute value;  a zero actual parameter is
    taken as 1.
*)

PROCEDURE  ParetoVariate (
                  (*in*)  Shape: REAL ): LONGREAL;



(*  Set the initial value to use for generating random variates.
*)

PROCEDURE  SetSeedValue (
                 (*in*)  ValueToSet: LONGCARD );



(*  Get the initial value to use for generating random variates.
    This value can be saved to continue a sequence, and later restored using
    the SetSeedValue procedure, above.
*)

PROCEDURE  GetSeedValue (
           (*out*)  VAR  CurrentSeed: LONGCARD );

END UnifRNG.
