This module is an attempt to move away from the legacy numpy RandomState and use the best practices described in the numpy random documentation and in NEP 19.

Although the bottomline of the numpy documentation is not to have a global state, never seed an existing generator, and create the desired generator at the beginning of the program and then just pass the object around, we deemed changing constructors (or the signature of the relevant class methods) for all the classes that need to throw random number too intrusive. Instead, we created this module that has a global Generator object.

The basic usage of the module is as follows

from hexsample import rng

rng.initialize()
z = rng.generator.normal()

and any attempt to do something with the rng.generator object will raise a RuntimeError if the module is not properly initialized. The initialization function :meth:`initialize() <hexsample.rng.initialize>` is the place where the particular algorithm for the random number generation, as well as the seed, can be set. This should be normally called once at the beginning of the program, and then the global rng.generator object will be available from everywhere in the package.

The default undelrying bit generator object that we use is the SFC64 Small Fast Chaotic PRNG, that is known to be very fast and have good statistical properties.

.. automodule:: hexsample.rng