13.13 Random Interface

ORIGIN 'betaenv';
BODY 'private/randombody';
(*
 * COPYRIGHT
 *       Copyright (C) Mjolner Informatics, 1995-96
 *       All rights reserved.
 *)
--- lib: attributes ---

initgn: external
  (*
   * INIT-ialize current G-e-N-erator
   *      Reinitializes the state of the current generator
   * 
   * Arguments
   *      isdtyp -> The state to which the generator is to be set
   *        isdtyp = -1 => sets the seeds to their initial value
   *        isdtyp = 0 => sets the seeds to the first value of the
   *                       current block
   *        isdtyp = 1 => sets the seeds to the first value of the
   *                       next block
   * 
   * Method
   *      This is a transcription from Pascal to Fortran of routine
   * Init_Generator from the paper
   *      L'Ecuyer, P. and Cote, S. "Implementing a Random Number
   * Package with Splitting Facilities."  ACM Transactions on
   * Mathematical Software, 17:98-111 (1991)
   *)
  (# isdtyp: @integer
  enter (isdtyp)
  #);


gscgn: external
  (*
   * Get/Set GeNerator
   *      Gets or returns in G the number of the current generator
   * 
   * Arguments
   *      getset --> 0 Get 1 Set
   *      g <-- Number of the current random number generator (1..32)
   *)
  (# getset, g: @integer
  enter (getset, g)
  #);


setsd: external
  (*
   * SET S-ee-D of current generator
   *      Resets the initial seed of the current generator to ISEED1
   *      and ISEED2. The seeds of the other generators remain
   *      unchanged.
   * Arguments
   *      iseed1 -> First integer seed
   *      iseed2 -> Second integer seed
   * Method
   *      This is a transcription from Pascal to Fortran of routine
   * Set_Seed from the paper L'Ecuyer, P. and Cote, S. "Implementing a
   * Random Number Package with Splitting Facilities."  ACM
   * Transactions on Mathematical Software, 17:98-111 (1991)
   *)
  (#  iseed1, iseed2: @integer
  enter (iseed1, iseed2)
  #);


getsd: external
  (*
   * GET SeeD
   *      Returns the value of two integer seeds of the current
   *      generator
   * Arguments
   *      iseed1 <- First integer seed of generator G
   *      iseed2 <- Second integer seed of generator G
   * Method
   *      This is a transcription from Pascal to Fortran of routine
   * Get_State from the paper L'Ecuyer, P. and Cote, S. "Implementing
   * a Random Number Package with Splitting Facilities."  ACM
   * Transactions on Mathematical Software, 17:98-111 (1991)
   *)
  (# iseed1, iseed2: @integer
  enter (iseed1, iseed2)
  #);


setall: external
  (*
   * SET ALL random number generators
   *      Sets the initial seed of generator 1 to ISEED1 and
   * ISEED2. The initial seeds of the other generators are set
   * accordingly, and all generators states are set to these seeds.
   * 
   * Arguments
   *      iseed1 -> First of two integer seeds
   *      iseed2 -> Second of two integer seeds
   * 
   * Method
   *      This is a transcription from Pascal to Fortran of routine
   * Set_Initial_Seed from the paper L'Ecuyer, P. and Cote,
   * S. "Implementing a Random Number Package with Splitting
   * Facilities."  ACM Transactions on Mathematical Software,
   * 17:98-111 (1991)
   *)
  (# iseed1, iseed2: @integer
  enter (iseed1, iseed2)
  #);


setant: external
  (*
   * SET ANTithetic Sets whether the current generator produces
   *      antithetic values.  If X is the value normally returned from
   *      a uniform [0,1] random number generator then 1 - X is the
   *      antithetic value. If X is the value normally returned from a
   *      uniform [0,N] random number generator then N - 1 - X is the
   *      antithetic value. All generators are initialized to NOT
   *      generate antithetic values.
   * Arguments
   *      qvalue -> nonzero if generator G is to generating antithetic
   *                values, otherwise zero
   * Method
   *      This is a transcription from Pascal to Fortran of routine
   * Set_Antithetic from the paper L'Ecuyer, P. and Cote,
   * S. "Implementing a Random Number Package with Splitting
   * Facilities."  ACM Transactions on Mathematical Software,
   * 17:98-111 (1991)
   *)
  (# qvalue: @integer
  enter qvalue
  #);


advnst: external
  (*
   * ADV-a-N-ce ST-ate
   *      Advances the state of the current generator by 2^K values
   *      and resets the initial seed to that value.
   * Arguments
   *      k -> The generator is advanced by2^K values
   * Method: routine Advance_State from the paper L'Ecuyer, P. and
   *      Cote, S. "Implementing a Random Number Package with
   *      Splitting Facilities."  ACM Transactions on Mathematical
   *      Software, 17:98-111 (1991)
   *)
  (# k: @integer
  enter k
  #);

(*=================================================================*)
(*===== Integer random number generators ==========================*)
(*=================================================================*)

ignlgi: external
  (*
   * Integer GeNerate LarGe Integer
   *      Returns a random integer following a uniform distribution
   * over (1, 2147483562) using the current generator.
   * 
   * Method
   *      This is a transcription from Pascal to Fortran of routine
   * Random from the paper L'Ecuyer, P. and Cote, S. "Implementing a
   * Random Number Package with Splitting Facilities."  ACM
   * Transactions on Mathematical Software, 17:98-111 (1991)
   *)
  (# random: @integer
  exit random
  #);


ignuin: external
  (*
   * GeNerate Uniform INteger
   *      Generates an integer uniformly distributed between LOW and
   * HIGH.
   * 
   * Arguments
   *      low --> Low bound (inclusive) on integer value to be
   *              generated
   *      high --> High bound (inclusive) on integer value to be
   *               generated
   * 
   * Note
   *      If (HIGH-LOW) > 2,147,483,561 prints error message on * unit
   * and stops the program.
   *)
  (# low, high: @integer;
     random: @integer
  enter (low, high)
  exit random
  #);


ignbin: external
  (*
   * Integer GeNerate BINomial random deviate
   *      Generates a single random deviate from a binomial
   * distribution whose number of trials is N and whose probability of
   * an event in each trial is P.
   * 
   * Arguments
   *      n --> The number of trials in the binomial distribution from
   *            which a random deviate is to be generated.
   *      p --> The probability of an event in each trial of the
   *            binomial distribution from which a random deviate is
   *            to be generated.
   *      ignbin <-- A random deviate yielding the number of events
   *            from N independent trials, each of which has a
   *            probability of event P.
   * Method
   *      This is algorithm BTPE from: Kachitvichyanukul, V. and
   * Schmeiser, B.  W.  Binomial Random Variate Generation.
   * Communications of the ACM, 31, 2 (February, 1988) 216.
   *)
  (# n: @integer;
     p: @real;
     random: @integer
  enter (n, p)
  exit random
  #);


ignnbn: external
  (*
   * Integer GeNerate Negative BiNomial random deviate
   *      Generates a single random deviate from a negative binomial
   * distribution.
   * 
   * Arguments
   *      N --> The number of trials in the negative binomial
   *            distribution from which a random deviate is to be
   *            generated.
   *      P --> The probability of an event.
   * Method
   *      Algorithm from page 480 of Devroye, Luc, Non-Uniform Random
   * Variate Generation.  Springer-Verlag, New York, 1986.
   *)
  (# n: @integer;
     p: @real;
     random: @integer
  enter (n, p)
  exit random
  #);


ignpoi: external
  (*
   * GENerate POIsson random deviate
   *      Generates a single random deviate from a Poisson
   *      distribution with mean AV.
   * 
   * Arguments
   *      mu --> The mean of the Poisson distribution from which a
   *             random deviate is to be generated.
   * 
   * Method
   *      Renames KPOIS from TOMS as slightly modified by BWB to use
   * RANF instead of SUNIF.  For details see: Ahrens, J.H. and Dieter,
   * U.  Computer Generation of Poisson Deviates From Modified Normal
   * Distributions.  ACM Trans. Math. Software, 8, 2 (June
   * 1982),163-179
   *)
  (# mu: @real;
     random: @integer
  enter mu
  exit random
  #);

(*=================================================================*)
(*===== Real random number generators =============================*)
(*=================================================================*)

ranf: external
  (*
   * RANnom number generator as a Function
   *      Returns a random floating point number from a uniform
   * distribution over 0 - 1 (endpoints of this interval are not
   * returned) using the current generator
   * 
   * Method
   *      This is a transcription from Pascal to Fortran of routine
   * Uniform_01 from the paper L'Ecuyer, P. and Cote, S. "Implementing
   * a Random Number Package with Splitting Facilities."  ACM
   * Transactions on Mathematical Software, 17:98-111 (1991)
   *)
  (# random: @real
  exit random
  #);


genunf: external
  (*
   * GENerate UNiForm real
   *      Generates a real uniformly distributed between LOW and HIGH.
   * 
   * Arguments low --> Low bound (exclusive) on real value to be
   *      generated high --> High bound (exclusive) on real value to
   *      be generated
   *)
  (# low, high: @real;
     random: @real
  enter (low, high)
  exit random
  #);


genbet: external
  (*
   * GeNerate BETa random deviate
   *      Returns a single random deviate from the beta distribution
   * with parameters A and B.  The density of the beta is x^(a-1) *
   * (1-x)^(b-1) / B(a,b) for 0 < x < 1
   * 
   * Arguments
   *      aa --> First parameter of the beta distribution
   *      bb --> Second parameter of the beta distribution Method
   * 
   * Method: described in R. C. H. Cheng Generating Beta Variatew with
   *      Nonintegral Shape Parameters Communications of the ACM,
   *      21:317-322 (1978) (Algorithms BB and BC)
   *)
  (# aa, bb: @real;
     random: @real
  enter (aa,bb)
  exit random
  #);


genchi: external
  (*
   * GENerate random value of CHIsquare variable
   *      Generates random deviate from the distribution of a
   * chisquare with DF degrees of freedom random variable.
   * 
   * Arguments
   *      df --> Degrees of freedom of the chisquare (Must be
   * positive)
   * 
   * Method:
   *      Uses relation between chisquare and gamma.
   *)
  (# df: @real;
     random: @real
  enter df
  exit random
  #);


genexp: external
  (*
   * GENerate EXPonential random deviate
   *      Generates a single random deviate from an exponential
   * distribution with mean AV.
   * 
   * Arguments
   *      av --> The mean of the exponential distribution from which a
   *             random deviate is to be generated.  Method:
   * 
   * Renames SEXPO from TOMS as slightly modified by BWB to use
   * RANF instead of SUNIF. 
   * For details see: Ahrens, J.H. and Dieter,
   * U.  Computer Methods for Sampling From the Exponential and Normal
   * Distributions.  Comm.  ACM, 15,10 (Oct. 1972), 873 - 882.
   *)
  (# av: @real;
     random: @real
  enter av
  exit random
  #);


genf: external
  (*
   * GENerate random deviate from the F distribution
   *      Generates a random deviate from the F (variance ratio)
   * distribution with DFN degrees of freedom in the numerator and DFD
   * degrees of freedom in the denominator.
   * 
   * Arguments
   *      dfn --> Numerator degrees of freedom (Must be positive)
   *      dfd --> Denominator degrees of freedom (Must be positive)
   * 
   * Method
   *      Directly generates ratio of chisquare variates
   *)
  (# dfn, dfd: @real;
     random: @real
  enter (dfn, dfd)
  exit random
  #);


gengam: external
  (*  GENerates random deviates from GAMma distribution
   *      Generates random deviates from the gamma distribution whose
   * density is (A**R)/Gamma(R) * X**(R-1) * Exp(-A*X)
   * 
   * Arguments
   *      a --> Location parameter of Gamma distribution
   *      r --> Shape parameter of Gamma distribution
   * 
   * Method
   *      Renames SGAMMA from TOMS as slightly modified by BWB to use
   * RANF instead of SUNIF.  For details see: (Case R >= 1.0) Ahrens,
   * J.H. and Dieter, U.  Generating Gamma Variates by a Modified
   * Rejection Technique.  Comm. ACM, 25,1 (Jan. 1982), 47 - 54.
   * Algorithm GD (Case 0.0 <= R <= 1.0) Ahrens, J.H. and Dieter, U.
   * Computer Methods for Sampling from Gamma, Beta, Poisson and
   * Binomial Distributions.  Computing, 12 (1974), 223-246/ Adapted
   * algorithm GS.
   *)
  (# a, r: @real;
     random: @real
  enter (a, r)
  exit random
  #);


gennch: external
  (*  GENerate random value of Noncentral CHisquare variable
   *      Generates random deviate from the distribution of a
   * noncentral chisquare with DF degrees of freedom and noncentrality
   * parameter xnonc.
   * 
   * Arguments
   *      df --> Degrees of freedom of the chisquare (Must be > 1.0)
   *      xnonc --> Noncentrality parameter of the chisquare (Must be
   *                >= 0.0)
   * Method
   *      Uses fact that noncentral chisquare is the sum of a
   * chisquare deviate with DF-1 degrees of freedom plus the square of
   * a normal deviate with mean XNONC and standard deviation 1.
   *)
  (# df, xnonc: @real;
     random: @real
  enter (df, xnonc)
  exit random
  #);


gennf: external
  (*  GENerate random deviate from the Noncentral F distribution
   *      Generates a random deviate from the noncentral F (variance
   * ratio) distribution with DFN degrees of freedom in the numerator,
   * and DFD degrees of freedom in the denominator, and noncentrality
   * parameter XNONC.
   * 
   * Arguments
   *      dfn --> Numerator degrees of freedom (Must be >= 1.0)
   *      dfd --> Denominator degrees of freedom (Must be positive)
   *      xnonc --> Noncentrality parameter (Must be nonnegative)
   * 
   * Method
   *      Directly generates ratio of noncentral numerator chisquare
   * variate to central denominator chisquare variate.
   *)
  (# dfn, dfd, xnonc: @real;
     random: @real
  enter (dfn, dfd, xnonc)
  exit random
  #);


gennor: external
  (*
   * GENerate random deviate from a NORmal distribution
   *      Generates a single random deviate from a normal distribution
   * with mean, AV, and standard deviation, SD.
   * 
   * Arguments
   *      av --> Mean of the normal distribution.
   *      sd --> Standard deviation of the normal distribution.
   * 
   * Method
   *      Renames SNORM from TOMS as slightly modified by BWB to use
   * RANF instead of SUNIF.  For details see: Ahrens, J.H. and Dieter,
   * U.  Extensions of Forsythe's Method for Random Sampling from the
   * Normal Distribution.  Math. Comput., 27,124 (Oct. 1973), 927 -
   * 937.
   *)
  (# av, sd: @real;
     random: @real
  enter (av, sd)
  exit random
  #);


sexpo: external
  (*
   * Standard EXPonential distribution
   * 
   * Method
   *      For details see: Ahrens, J.H. and Dieter, U.  Computer
   * Methods For Sampling From The Exponential And Normal
   * Distributions.  COMM. ACM, 15,10 (Oct. 1972), 873 - 882.  All
   * statement numbers correspond to the steps of algorithm 'SA' in
   * the above paper (slightly modified implementation) Modified by
   * Barry W. Brown, Feb 3, 1988 to use RANF instead of SUNIF.  The
   * argument IR thus goes away.
   * 
   *      Q(N) = SUM(ALOG(2.0)**K/K!)  K=1,..,N , The highest N (here
   * 8) is determined by Q(N)=1.0 within standard precision
   *)
  (# random: @real
  exit random
  #);


sgamma: external
  (*
   * Standard GAMMA distribution
   * 
   *      Sample from the GAMMA-(A)-distribution coefficients Q(K)
   *         - for Q0 = SUM(Q(K)*A**(-K)) coefficients A(K)
   *         - for Q = Q0+(T*T/2)*SUM(A(K)*V**K) coefficients E(K)
   *         - for EXP(Q)-1 = SUM(E(K)*Q**K)
   * 
   * Arguments
   *      A ---> Parameter (mean) of the standard GAMMA distribution
   * Method
   *      CASE A >= 1.0 !
   *      For details see: Ahrens, J.H. and Dieter, U.  Generating
   * GAMMA variates by a modified rejection technique.  COMM. ACM,
   * 25,1 (Jan.  1982), 47 - 54.  Step numbers correspond to algorithm
   * 'GD' in the above paper (straightforward implementation) Modified
   * by Barry W. Brown, Feb 3, 1988 to use RANF instead of SUNIF.  The
   * argument IR thus goes away.
   *      CASE 0.0 < A < 1.0 !
   *      For details see: Ahrens, J.H. and Dieter, U.  Computer
   * Methods for Sampling from GAMMA, BETA, Poisson and Binomial
   * Distributions.  COMPUTING, 12 (1974), 223 - 246.  (adapted
   * implementation of algorithm 'GS' in the above paper)
   *)
  (# a: @real;
     random: @real
  enter a
  exit random
  #);


snorm: external
  (*
   * Standard NORmal distribution
   * 
   * Method
   *       For details see: Ahrens, J.H. and Dieter, U.  Extensions of
   * Forsythe's method for Random Sampling from the NORMAL
   * distribution.  MATH.  COMPUT., 27,124 (OCT. 1973), 927 - 937.
   * All statement numbers correspond to the steps of algorithm 'FL'
   * (M=5) in the above paper (slightly modified implementation)
   * Modified by Barry W. Brown, Feb 3, 1988 to use RANF instead of
   * SUNIF.  The argument IR thus goes away.
   *)
  (# random: @real
  exit random
  #)


13.13 Random Interface
© 1990-2002 Mjølner Informatics
[Modified: Tuesday May 7th 1996 at 13:51]