Package: simplerandom
Author:Craig McQueenContact:http://craig.mcqueen.id.au/Copyright:2010 Craig McQueenSimple pseudo-random number generators.IntroThesimplerandompackage is provided, which contains modules containing
classes for various simple pseudo-random number generators.One module provides Python iterators, which generate simple unsigned 32-bit
integers identical to their C counterparts.Another module provides random classes that are sub-classed from the classRandomin therandommodule of the standard Python library.Why use this package? These random number generators are very simple, which
has two main advantages:It is easy to port them to a different platform and/or language. It can be
useful to be able to implement the identical algorithm on multiple
platforms and/or languages.Small and simple generators can be more appropriate for small embedded
systems, with limited RAM and ROM.An equivalent C implementation (of the Pythonsimplerandom.iteratorsmodule) has been created. See:http://github.com/cmcqueen/simplerandomAlgorithmsMost algorithms were obtained from two newsgroup posts by George Marsaglia[1][2]. However, some modifications have been
made. From[3], it seems that the SHR3 algorithm defined in[1]is flawed and should not be used. It doesn’t actually have a
period of 2**32-1 as expected, but has 64 different cycles, some with very
short periods. The SHR3 in the 2003 post is very similar, but with two shift
values swapped. It has a period of 2**32-1 as expected.We still find KISS from[1]useful mainly because it uses 32-bit
calculations for MWC, which can be more suitable for small embedded systems.
So we define KISS that uses a MWC based on[1], but the Cong and
SHR3 from[2].From Pierre L’Ecuyer[4][6], the Combined LFSR
(Tausworthe) LFSR113 algorithm[5]and LFSR88 (aka Taus88) have been
implemented.References[1](1,2,3,4,5,6,7)Random Numbers for C: End, at last?George MarsagliaNewsgroup post, sci.stat.math and others, Thu, 21 Jan 1999[2](1,2,3,4,5,6,7)RNGsGeorge MarsagliaNewsgroup post, sci.math, 26 Feb 2003[3]KISS: A Bit Too SimpleGreg RoseQualcomm Inc.[4](1,2)Tables of Maximally-Equidistributed Combined LFSR GeneratorsPierre L’EcuyerMathematics of Computation, 68, 225 (1999), 261–269.[5](1,2)LFSR113 C double implementationPierre L’Ecuyer[6](1,2)Maximally Equidistributed Combined Tausworthe GeneratorsP. L’EcuyerMathematics of Computation, 65, 213 (1996), 203–213.Modules ProvidedModuleDescriptionsimplerandom.iteratorsIterator classes, which generate unsigned 32-bit integers.simplerandom.randomClasses that conform to standard Pythonrandom.RandomAPI.Random Number Generators ProvidedInsimplerandom.iterators, the following pseudo-random number generators are provided:GeneratorNotesMWC1Two 32-bit MWCs combined. From[1].MWC2Very similar toMWC1, but slightly modified to improve its statistical properties.CongFrom[2].SHR3From[2].MWC64A single 64-bit multiply-with-carry calculation. From[2].KISSCombination of MWC2, Cong and SHR3. Based on[1]but using Cong and SHR3 from[2], and the modified MWC.KISS2Combination of MWC64, Cong and SHR3. From[2].LFSR113Combined LFSR (Tausworthe) random number generator by L’Ecuyer. From[4][5].LFSR88Combined LFSR (Tausworthe) random number generator by L’Ecuyer. From[6].These generators are Python iterators, of infinite length (they never raiseStopIteration). They implement the__next__()function to generate the
next random integer. All the generators output 32-bit unsigned values, and
take one or more 32-bit seed values during initialisation/seeding.Insimplerandom.random, pseudo-random number generators are provided which
have the same names as those insimplerandom.iterators, but these
generators implement the standard Pythonrandom.RandomAPI. Each generator
uses the iterator of the same name insimplerandom.iteratorsto generate
the random bits used to produce the random floats. Thejumpahead()function
(in the style of the Python 2.x API) is implemented in all cases, even thoughjumpahead()has officially been removed from the Python 3.xrandomAPI.UsageIterators>>> import simplerandom.iterators as sri
>>> rng = sri.KISS(123958, 34987243, 3495825239, 2398172431)
>>> next(rng)
702862187
>>> next(rng)
13888114
>>> next(rng)
699722976Random class API>>> import simplerandom.random as srr
>>> rng = srr.KISS(258725234)
>>> rng.random()
0.0925917826051541
>>> rng.random()
0.02901686453730415
>>> rng.random()
0.9024972981686489Supported Python VersionsPython >= 3.10 are supported.Python versions < 3.10 might work, but have not been tested.Use of CythonCythonis used to make a fast implementation ofsimplerandom.iterators.
Cython creates a.cfile that can be compiled into a Python binary
extension module.Thesimplerandomsource distribution package includes a.cfile that
was created with Cython, so it is not necessary to have Cython installed to
installsimplerandom.The Cython.pyxfile is also included, if you want to modify the Cython
source code, in which case you do need to have Cython installed. But by
default,setup.pybuilds the extension from the.cfile (to ensure
that the build doesn’t fail due to particular Cython version issues). If you
wish to build using Cython from the included.pyxfile, you must setUSE_CYTHON=Trueinsetup.py.InstallationThe simplerandom package is installed usingdistutils.  If you have the tools
installed to build a Python extension module, run the following command:python setup.py installIf you cannot build the C extension, you may install just the pure Python
implementation, using the following command:python setup.py build_py install --skip-buildUnit TestingUnit testing of the iterators is insimplerandom.iterators.test. It
duplicates the tests of the C algorithms given in the original newsgroup post[1], as well as other unit tests.To run unit tests:python -m simplerandom.iterators.testA more thorough unit test suite is needed. A unit test suite forsimplerandom.randomis needed.LicenseThe code is released under the MIT license. See LICENSE.txt for details.