README 1.4 7/22/92

I wrote this code out of frustration with the bugs in the random
number generators supplied with 4.3bsd Unix.  All three have serious
defects: rand() is not very "random," random() is unable to correctly
save its state so that it can be restarted "where it left off,"
and nrand48() has poor long-range correlation properties.

Using this package, instead of direct calls to random() or some
other RNG code, offers the following advantages.

  1.  You can switch to another RNG, and re-run a portion of your
  experiment to check its validity, without changing any of your code
  other than a single parameter in your init_rng() call.  The RNGs
  available are the three 4.3bsd codes, Jon Bentley's "Truly Amazing RNG,"
  and the "Portable Combined (multiplicative) Generator" described in
  C.ACM a couple of years ago.  If another RNG is your favorite, you 
  should be able to modify my source code fairly easily -- please send
  me a note if you do so.

  2.  You can use my unbiased method for generating random integers
  in the range 0..m-1.  By contrast, the typical integer-generating
  codes "random()%m" or "(int) m * ((double) random()/MAXLONG)"
  have a slight bias for large m.

  3.  Floating point numbers, uniformly distributed in [0.0, 1.0),
  are available (as on most RNG interfaces).

  4.  As with most RNG interfaces, you can have many simultaneously-active
  RNGs with efficient state-switching calls.  (Unfortunately, I was unable
  to find an efficient work-around for 4.3bsd random()'s state-saving bug;
  you'll have to use one of the other generators if you want to use multiple
  RNG streams in a single program invocation.)

  5.  Time-efficient vectorized calls, returning multiple uniform variates,
  are available.

  6.  The package offers a shorthand notation for completely specifying the
  algorithm and current state of your RNG(s), in an 80-character human-readable
  ASCII string.  This is very useful in experimental documentation and
  replication.

  7.  A complete RNG state can be (serially) reconstructed from its shorthand
  notation, and

  8.  A file-I/O interface allows fast saves and restarts of complete
  RNG state vectors, without the time overhead of serial reconstruction.

Also included in this software release is a driver routine, "mrtest.c."
This routine implements some of the simpler tests of randomness, e.g.
equidistribution, pairwise (both short- and long-range) correlation,
and 3-tuple correlation.  These tests were chosen to illustrate the use
of the components of the mrandom() package, as well as to exhibit the
known defects of the 4.3bsd generators rand() and nrand48().

For technical details on the algorithms and statistical analyses used,
consult my submission to the SODA conference, soda.tex, also included
in this distribution.

To test the package, type ``make test''.  This will compile and
run a test script.

To install, type ``make install''.

Please send bug reports, comments, etc., to cthombor@ub.d.umn.edu

						Clark Thomborson
						22 July 1992

PS: I won't respond to email for the period 25 July -- 14 August 1992,
while I'm on the way to a year-long sabbatical visit at MIT.  After
August 14 or so, I'll arrange for my email to be forwarded. 

PPS: An earlier version of this package, lacking most of the features
described above, appeared under the name mrandom() in comp.sources.unix
25(23), December 1991.
