*rndm.txt*	Pseudo-Random Number Generator		Sep 13, 2013

Author:  Charles E. Campbell  <cec@NgrOyphSon.gPsfAc.nMasa.gov>
	  (remove NOSPAM from Campbell's email first)
Copyright: (c) 2004-2013 by Charles E. Campbell	*rndm-copyright*
           The VIM LICENSE applies to Rndm.vim and Rndm.txt
           (see |copyright|) except use "Rndm" instead of "Vim"
	   No warranty, express or implied.  Use At-Your-Own-Risk.

==============================================================================
1. Contents						*Rndm* *Rndm-contents*

	1. Contents......................: |Rndm-contents|
	2. Rndm Manual...................: |Rndm-manual|
	3. History.......................: |Rndm-history|

==============================================================================

2. Rndm Manual			*Rndmman* *Rndmmanual* *Rndm-manual*

	To Enable: put <Rndm.vim> into your .vim/plugin

 /=============+============================================================\
 || Commands   |      Explanation                                          ||
 ++------------+-----------------------------------------------------------++
 || RndmInit() |  RndmInit(m1,m2,m3)                                       ||
 || RndmInit() |  RndmInit()                                               ||
 ||            +-----------------------------------------------------------++
 ||            | RndmInit takes three integers between [0-100,000,000)     ||
 ||            | to initialize the pseudo-random number generator          ||
 ||            |                                                           ||
 ||            | If no arguments are given, then RmdmInit() will attempt   ||
 ||            | to read the $HOME/.seed file which should contain three   ||
 ||            | numbers, also [0,100 000 000).  With this format, the     ||
 ||            | script should call RndmSave() when done.                  ||
 ||            |                                                           ||
 ++============+===========================================================++
 || RndmSave() | This function saves the current values of the three       ||
 ||            | pseudo-random number generator seeds in $HOME/.seed       ||
 ||            | Use call RndmInit() (no arguments) to initialize the      ||
 ||            | generator with these seeds.                               ||
 ||            |                                                           ||
 ++============+===========================================================++
 || Rndm()     |  Rndm()                                                   ||
 ||            +-----------------------------------------------------------++
 ||            | Generates a pseudo-random variable on [0 - 100,000,000)   ||
 ||            |                                                           ||
 ++============+===========================================================++
 || Urndm()    |  Urndm(a,b)                                               ||
 ||            +-----------------------------------------------------------++
 ||            | Generates a uniformly distributed pseudo-random variable  ||
 ||            | on the interval [a,b]                                     ||
 ||            |                                                           ||
 ++============+===========================================================++
 || Dice()     |  Dice(qty,sides)                                          ||
 ||            +-----------------------------------------------------------++
 ||            | Assumes one is rolling a quantity "qty" of dice, each     ||
 ||            | having "sides" sides.                                     ||
 ||            | Example: dice(5,4) returns a variate based on rolling     ||
 ||            |          5 4-sided dice and summing the results           ||
 ||            |                                                           ||
 \==========================================================================/

The pseudo-random number generator used herein was developed at MIT.

I used D. Knuth's ent program (http://www.fourmilab.ch/random/) and generated
one million (1,000,000) values using a C program variant: >
	rv= Rndm()/3906.25   (which divides one million into 256 equal regions)
and converted each value into bytes.  The report from Knuth's ent program:

    Entropy = 7.999825 bits per byte.

    Optimum compression would reduce the size
    of this 1000000 byte file by 0 percent.

    Chi square distribution for 1000000 samples is 242.41, and randomly
    would exceed this value 70.44 percent of the times.

    Arithmetic mean value of data bytes is 127.5553 (127.5 = random).
    Monte Carlo value for Pi is 3.135732543 (error 0.19 percent).
    Serial correlation coefficient is 0.001313 (totally uncorrelated = 0.0).

These values are quite good (a true random source, for example, had a
chi square distribution value of 249.51, for example -- from Knuth's page).

However, the results for the low-order byte aren't good: >
	rv=Rndm()%8     (which essentially looks at just the low order byte)
The report from Knuth's ent program:

    Entropy = 2.999996 bits per byte.

    Optimum compression would reduce the size
    of this 1000000 byte file by 62 percent.

    Chi square distribution for 1000000 samples is 31000155.62, and randomly
    would exceed this value less than 0.01 percent of the times.

    Arithmetic mean value of data bytes is 3.4987 (127.5 = random).
    Monte Carlo value for Pi is 4.000000000 (error 27.32 percent).
    Serial correlation coefficient is 0.000782 (totally uncorrelated = 0.0).

The Urndm() function, which generates pseudo-random variates from [a,b],
preferentially uses the high order bits, and so has good near-random behavior.

==============================================================================
3. History							*Rndm-history*

   4 May 23, 2005 : * cpo use standardized while loading
     Feb 16, 2007   * RndmInit() (no arguments) now reads $HOME/.seed
     Feb 16, 2007   * wrote RndmSave()
   3 May 28, 2004 : * now supports initial "extra randomization" by using the
                      localtime() clock.

==============================================================================
vim:tw=78:ts=8:ft=help