             Dynamic Creator of Mersenne Twisters 2001/12/21			

1. Overview
  This is a C library for "Dynamic Creator", which dynamically
generates a parameter for a random number generator. Users
can specify (1) the word size w of generated random integers
(presently w=31,32 only) (2) the period (chosen from the
list of Mersenne primes below), and (3) id-number.

  When these specifications are given to a function in this 
library, it searches for a set of parameters (stored in
a struct type named mt_struct) of a recursion generating
a random number sequence conforming to the specification.
If we specify different id-numbers, then the set of yielded
random number sequences should be highly independent.

  Each random number generator is a Mersenne Twister with
specified size, which is very widely used and is proved to 
be a reliable source of pseudorandomness.

2. Compiling

  When you develop the tar file, you will find the following
three files and three directories.

  README 		This file
  README.jp		Japanese version of the above file
  VERSION		Version information
  lib			The library
  include 		The include file "dc.h" 
  example		Examples of C-codes

  To compile this library,  do "cd lib" and "make lib".
Then "libdcmt.a" will be created in the directory "lib",
and the compilation for the library is done.

  To use the library, include "dc.h" in the include directory
in your C-code source files, and link them with libdcmt.a 
when you compile the source.

3. The library functions

 void init_dc(uint32 seed)
     Initializes this library, i.e., initialize the internal 
   random number generator of this library. One needs to call
   this function once, before using any of get_mt_parameter(), 
   get_mt_parameter_id(), get_mt_parameters().
   The seed may be any integer between 0 and 2^32-1, so 
   2^32 possible choices.

     If this function is called with one same seed, then the 
   generated parameters are identical for any system, i.e., 
   it is reproducible.

 mt_struct *get_mt_parameter(int w, int p)
     Search for a set of parameters for random number generator.
   (We call such a parameter a "mt_struct parameter".) w is the
   number of bits in one word of generated random numbers 
   (w=31 or 32 only). p is the exponent of the period. The period
   should be 2^p-1, but p must be an Mersenne exponent, i.e., 
   2^p-1 should be a prime. The list of usable p are as follows.
     521   607  1279  2203
    2281  3217  4253  4423
    9689  9941 11213 19937
   21701 23209 44497

     This function returns a mt_struct parameter, when it 
   finds one, and returns NULL, when it failed to find.
   The function genrand_mt() below will generate a random
   number sequence of w-bit integers with period 2^p-1,
   when this mt_struct parameter is passed.

     Depending on the machine's speed, it may take one minute
   or more in finding one mt_struct parameter even if p=521.
   The average time in the search is rapidly increasing
   with respect to p. For large p, it is expected to be
   O(p^3).

 mt_struct *get_mt_parameter_id(int w, int p, int id)
     This is similar to the above get_mt_parameter().
   get_mt_parameter() admits only w and p, but this function
   takes one more parameter, called id, and generates a
   mt_struct parameter, in which id is embedded.
     id is an 16-bit integer. For different id's, the 
   generated random number sequences are highly independent.
   (Mathematically saying, the characteristic polynomials 
   of the recursion are coprime to each other.)

 mt_struct **get_mt_parameters(int w, int p, int max_id)
     This searches for a set of mt_struct parameters with
   id between 0 and max_id (0<=id<=max_id). Thus, it finds
   max_id+1 independent mt_struct parameters, and make them
   into an array, and return it. The maximum value of max_id
   is 2^16. 

 void sgenrand_mt(uint32 seed, mt_struct *mts)
     One mt_struct parameter has the information on the recursion 
   and the state vector. This function initializes this state vector
   in mts with the seed. Before using the random numbers on the
   mt_struct parameter mts, call this function once to initialize.
   The seed is any integer between 0 and 2^32-1, and each seed
   generates distinct sequences.

 uint32 genrand_mt(mt_struct *mts)
     This returns a random number, generated from mts, 
   by using the recursion specified in the mts, and the state vector
   inside mts. 

4. Examples

4.1 example1
  Move to the directory "example", and execute "make example1".
Then an executable file "example1" will be created.

  Execute "example1", and wait for one minute. Then
get_mt_parameter(32,521) will give a mt_struct parameter
for a random number generator of 32-bit integers with 
period 2^521-1. (If it could not find one, then print
"error".)

  This mt_struct parameter is stored in mts. Using this, 
by genrand_mt(mts), 100 random numbers will be generated
and printed.

4.2 example2
  Similarly to 4.1, in the directory example, execute
"make example2" and obtain an executable file "example2".
Execute "example2", and wait for five minutes. Then 
three mt_struct parameters of 32-bit and period 2^521-1.
Each has id 0,1,999. 

  Store these three mt_struct parameters in mts0, mts1, mts2.
Using these, genrand_mt() generates three highly independent
three random number sequnces. First tens of each sequence 
will be printed.

5. Caution.

  This library was developed on Solaris2.6 with gcc-2.8.1 and
FreeBSD4.2R. It is expected to work in most of 32-bit machines
with a C compiler. Though, the "make" command seems not to 
work in an older version of Sun O.S. Use your own C compiler
in that case.

  This library is still under development, and may contain
some serious bugs. Please keep this in your mind. Report 
the bugs to the authors, if you find any.

6. Comment and bug reports

  If you find any comments or bug, please kindly send an email 
to both of or one of 
	nisimura@sci.kj.yamagata-u.ac.jp
	matumoto@math.h.kyoto-u.ac.jp

  The home page
	http:/www.math.keio.ac.jp/matumoto/emt.html
contains newest information on our random number generators,
but will be rarely up-dated and frequently be down.   

7. References

  [1] Makoto Matsumoto and Takuji Nishimura,
      "Mersenne Twister: A 623-Dimensionally Equidistributed Uniform
      Pseudorandom Number Generator",
      ACM Transactions on Modeling and Computer Simulation, 
      Vol. 8, No. 1, 1998, pp 3--30.

  [2] Makoto Matsumoto and Takuji Nishimura,
      "Dynamic Creation of Pseudorandom Number Generators",
      Monte Carlo and Quasi-Monte Carlo Methods 1998, 
      Springer, 2000, pp 56--69.
