/* README 3.2 7/20/93 */

This ftp directory contains the file mrandom-3.0.tar.Z, a new
distribution of the public-domain mrandom package in 4.3bsd Unix
tar'red, compressed format.  It also contains a tech report describing
the design of Mrandom, in file umd.cs.tr93-2.Z.tar.

Mrandom is a package of routines intended to help anyone writing
machine-independent C-language programs that call pseudorandom number
generators (RNGs).  We provide a standard interface to nine different
RNGs, making it easy to write efficient programs in which the choice
of RNG algorithm is deferred until runtime.  We also provide a set of
commonly-used "RNG utility functions" (e.g. to generate integers
uniformly distributed in a restricted range), as well as a small suite
of RNG tests.

To date, we have only tested the mrandom package on SparcStations and
DECstations.  However, we believe that it will run correctly, without
modification, on any IEEE-compliant, ANSI C, 32-bit computational
platform which can link to the 4.3bsd Unix RNGs "random", "rand", and
"nrand48".  Please send bug reports and comments to Clark Thomborson,
cthombor@ua.d.umn.edu.

You can use the ftp commands 
	ftp> binary
	ftp> get mrandom-3.0.tar.Z
	ftp> bye
to retrieve this file.  Move it into a suitable directory on your home
system, then unpack it with the 4.3bsd Unix sequence
	your-home-machine% zcat mrandom-3.0.tar.Z | tar xvf -
If all goes well, you will have created a new subdirectory, named
mrandom-3.0, containing the complete software distribution for version
3.0 of mrandom.

To unpack and print the tech report, you'll need a PostScript printer
and some patience for the cut-and-paste.  Unpack with "tar xvf *.tar",
then make the .ps files with "uncompress *.Z".  Alternatively, you can
order hardcopy from the CS Department, 320 HH, U Minnesota, Duluth MN
55812.  There will be a charge to defray shipping and handling: please
write Colleen Dennie <cdennie@ua.d.umn.edu> for details.

The rest of this file briefly outlines the changes in the Mrandom
programmer's interface since the last version.  See the User's Manual,
included in the distribution in several formats (files
mrandom-3.0/doc/mrandom.tex, mrandom.txt, mrandom.ps.Z), for detailed
information about these changes, for general information about this
package, and for compilation instructions.


init_rng()
	Old version:
	int init_rng(rng, alg, seed1, seed2, count1, count2)
	RNGdata *rng;
	long alg;
	long seed1, seed2;
	long count1, count2;

	New version:
	RNGdata *init_rng(alg, mrandom_alg, seed, count1, count2, bufsize)
	long alg;
	long mrandom_alg;
	long *seed;
	long count1, count2;
	long bufsize;

restart_rng()
	Old version:
	int restart_rng(rng, filename)
	RNGdata *rng;
	char *filename;

	New version:
	RNGdata *restart_rng(filename)
	char *filename;

kill_rng()
	There is now a kill_rng() routine:
	int kill_rng(rng)
	RNGdata *rng;

xrandomrv()
	xrandomrv() has been replaced by a family of routines for
providing unbuffered generates from an RNG:
	double dxrandomrv(rng, n, v)
	RNGdata *rng;
	long n;
	double v[];

	float fxrandomrv(rng, n, v)
	RNGdata *rng;
	long n;
	float v[];

	long lxrandomrv(rng, n, v)
	RNGdata *rng;
	long n;
	long v[];

	int bxrandomrv(rng, n, v)
	RNGdata *rng;
	long n;
	int v[];

	double bxrandomrv_f(rng, n, v)
	RNGdata *rng;
	long n;
	int v[];

Buffered generating routines
	A family of routines has been added for providing buffered
output of generates from an RNG:
	double drandomrv(rng, n, v)
	RNGdata *rng;
	long n;
	double v[];

	float frandomrv(rng, n, v)
	RNGdata *rng;
	long n;
	float v[];

	long lrandomrv(rng, n, v)
	RNGdata *rng;
	long n;
	long v[];

	int brandomrv(rng, n, v)
	RNGdata *rng;
	long n;
	int v[];

	double brandomrv_f(rng, n, v)
	RNGdata *rng;
	long n;
	int v[];

flush_rng()
	A routine has been added for flushing the RNG's buffers:
	int flush_rng(rng)
	RNGdata *rng;

mrandomrv()
	The interface to mrandomrv() has remained unchanged:
	long mrandomrv(rng, m, n, v)
	RNGdata *rng;
	long m, n, v[];

	However, mrandomrv() is now capable of using one of two
different algorithms for producing restricted-range integer generates.

save_rng() and restart_rng()
	The interface to save_rng() has remained unchanged.  However,
some files saved with the old save_rng() (e.g. files containing state
tables for nrand48) are not compatible with the new version.  The
interface to restart_rng() is now the following:
	RNGdata *restart_rng(filename)
	char *filename;

seed_rng()
	There is now a seed_rng() routine:
	void seed_rng(rng, seed)
	RNGdata *rng;
	long *seed;

check_rng()
	checkrandom() is now called check_rng() and has the following
interface:
	int check_rng(rng)
	RNGdata *rng;

describe_rng()
	The string created and returned by describe_rng() now has the
following format:

	RNG state identifier is (alg, mralg; seed1, seed2; count1,
count2; bufsize, split)

mralg_rng(), split_rng(), and range_rng()
	Three routines for examining and modifying the parameters of
RNG's have been added:
	int mralg_rng(rng, new_value)
	RNGdata *rng;
	long new_value;

	int split_rng(rng, new_value)
	RNGdata *rng;
	long new_value;

	double range_rng(rng)
	RNGdata *rng;