Commit 623bec77 authored by Christoph Conrads's avatar Christoph Conrads

README: briefly explain contents of repository

parent 00197987
# Ranlux Tools
# RANLUX Tools
This git repository contains programs helping with the creation of Ranlux
pseudo-random number generators.
ranlux pseudo-random number generators (PRNGs) are a family of high-quality
PRNGs. This git repository contains programs searching for valid ranlux
parameters. The code is licensed under the [Mozilla Public License
2.0](https://www.mozilla.org/en-US/MPL/2.0/).
A ranlux PRNG works as follows:
* It draws `p` random values from an add-with-carry (AWC) PRNG or a
subtract-with-borrow (SWB) PRNG.
* It returns `r <= p` values and discards the rest.
* Repeat.
Ranlux PRNGs have four parameters and all of them are positive integers:
* Base `b >= 2`, long lag `r`, and short lag `s` with `r > s`.
* Block size `p >= r`.
Valid parameter choices must fulfill certain number theoretical criteria and the
search for such parameters is automated by the scripts in this repository.
AWC and SWB PRNGs were introduced in a paper by Marsaglia and Zaman:
> G. Marsaglia, A. Zaman: "A New Class of Random Number Generators." In: The
> Annals of Applied Probability, Vol. 1, Issue 3, pp. 462-480. 1991.
AWC and SWB PRNGs have solid theoretical foundations but in practice it is
necessary to discard values and this was discussed by Lüscher:
> M. Lüscher: "A Portable High-Quality Random Number Generator for Lattice Field
> Theory Simulations." In: Computer Physics Communications, Vol. 79, Issue 1,
> pp. 100-110. 1994. arXiv:hep-lat/9309020
The Bash script `find-awc-swb-prngs.sh` will call the various scripts in this
repository to find AWC/SWB parameters and a block size. The output has to be
read as follows:
* `awc` denotes with an add-with-carry PRNG with base `b`, long lag `r`, and
short lag `s`.
* `cawc` is a complementary AWC generator.
* `swb` is a subtract-with-borrow PRNG with base `b`, long lag `r`, and short
lag `s`. Its recurrence is `x_n = x_{n-r} - x_{n-s} - c`, where `c` is the
carry bit.
* `swc` is a subtract-with-borrow PRNG with recurrence `x_n = x_{n-s} - x_{n-r}
- c` (note the different order of the terms). This generator is also an SWB
but seeing that the C++11 standard library calls the class implementing this
generator `subtract_with_carry`, we decided to use the acronym `swc`.
* `t` is the time parameter from Lüscher's chaotic dynamical system discussion
of AWC and SWBs PRNGs.
To compute the block size `p`, we suggest to use the smallest prime number
larger than `t * r`, e.g., for the popular 24-bit ranlux, we have `b=2^24`,
`r=24`, `s=10`, and `t = 16`. It holds that `t * p = 16 * 24 = 384` so `p =
389`. Note that in practice, prime values larger than `t*p / 4` are often
sufficient to pass all empirical random number generator tests.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment