# RandomGen¶

This package contains replacements for the NumPy `RandomState`

object that allows the core random number generator be be changed.

Warning

There are many changes between v1.16.x and v1.17.x. These reflect API decision taken in conjunction with NumPy in preparation of the core of `randomgen`

being used as the preferred random number generator in NumPy. These all issue `DeprecationWarning`

except for `BasicRNG.generator`

which raises `NotImplementedError`

. The C-API has also changed to reflect the preferred naming the underlying Pseudo-RNGs, which are now known as bit generators (or `BitGenerator`

).

The main changes are

Rename

`RandomGenerator`

to`Generator`

.Rename

`randint()`

to`integers()`

.Rename

`random_integers()`

to`integers()`

.Rename

`random_sample()`

to`random()`

.Change

`jump`

which operated in-place to`jumped`

which returns a new`BitGenerator`

.Rename Basic RNG to bit generator, which impacts the API in multiple places where names like

`brng`

and`basic_rng`

have been replaced by`bitgen`

or`bit_generator`

.

v1.16.x will be updated until the end of 2019 if you want to avoid these changes.

## Quick Start¶

Like `numpy.random`

, RandomGen can be used at the module level. This uses the default `Generator`

which uses normals provided by `Xoroshiro128`

.

```
# As replacement for numpy.random
import randomgen.generator as random
random.standard_normal()
```

`Generator`

can also be used as a replacement for `RandomState`

, although the random values are generated by `Xoroshiro128`

. It also isn’t possible to directly seed a `Generator`

.

```
# As replacement for RandomState()
from randomgen import Generator
rg = Generator()
rg.standard_normal()
```

Seeds can be passed to any of the bit generators. Here `MT19937`

is used and the `Generator`

is accessed via the property `generator`

.

```
from randomgen import MT19937
rg = MT19937(12345).generator
rg.standard_normal()
```

## Introduction¶

RandomGen takes a different approach to producing random numbers from the `numpy.random.RandomState`

object used in NumPy. Random number generation is separated into two components, a bit generator and a random generator.

The bit generator has a limited set of responsibilities – it manages the underlying RNG state and provides functions to produce random doubles and random unsigned 32- and 64-bit values. The bit generator also handles all seeding since this varies when using alternative bit generators.

The random generator (`Generator`

) takes the bit generator-provided functions and transforms them into more useful distributions, e.g., simulated normal random values. This structure allows alternative bit generators to be used without code duplication.

The `Generator`

is the user-facing object that is nearly identical to `RandomState`

. The canonical method to initialize a generator passes a bit generator – `MT19937`

, the underlying RNG in NumPy – as the sole argument. Note that the bit generator must be instantized.

```
from randomgen import Generator, MT19937
rg = Generator(MT19937())
rg.random()
```

Seed information is directly passed to the bit generator.

```
rg = Generator(MT19937(12345))
rg.random()
```

A shorthand method is also available which uses the `generator()`

property from a bit generator to access an embedded random generator.

```
rg = MT19937(12345).generator
rg.random()
```

### What’s New or Different¶

Warning

The Box-Muller method used to produce NumPy’s normals is no longer available in `Generator`

. It is not possible to reproduce the random values using `Generator`

for the normal distribution or any other distribution that relies on the normal such as the gamma or student’s t. If you require backward compatibility, a legacy generator, `RandomState`

, has been created which can fully reproduce the sequence produced by NumPy.

The normal, exponential and gamma generators use 256-step Ziggurat methods which are 2-10 times faster than NumPy’s Box-Muller or inverse CDF implementations.

Optional

`dtype`

argument that accepts`np.float32`

or`np.float64`

to produce either single or double prevision uniform random variables for select distributionsOptional

`out`

argument that allows existing arrays to be filled for select distributionsSimulate from the complex normal distribution (

`complex_normal()`

)`random_entropy()`

provides access to the system source of randomness that is used in cryptographic applications (e.g.,`/dev/urandom`

on Unix).All bit generators functions to produce doubles, uint64s and uint32s via CTypes (

`ctypes()`

) and CFFI (`cffi()`

). This allows these bit generators to be used in numba.The bit generators can be used in downstream projects via Cython.

Support for Lemire’s method [Lemire] of generating uniform integers on an arbitrary interval by setting

`use_masked=True`

in (`integers()`

).

See What’s New or Different for a complete list of improvements and differences.

### Parallel Generation¶

The included generators can be used in parallel, distributed applications in one of two ways:

## Supported Generators¶

The main innovation is the inclusion of a number of alternative pseudo-random number generators, ‘in addition’ to the standard PRNG in NumPy. The included PRNGs are:

MT19937 - The standard NumPy generator. Produces identical results to NumPy using the same seed/state. Adds a jump function that advances the generator as-if 2**128 draws have been made (

`jumped()`

). See NumPy’s documentation.dSFMT - SSE2 enabled versions of the MT19937 generator. Theoretically the same, but with a different state and so it is not possible to produce a sequence identical to MT19937. Supports

`jump`

and so can be used in parallel applications. See the dSFMT authors’ page.XoroShiro128+ - Improved version of XorShift128+ with better performance and statistical quality. Like the XorShift generators, it can be jumped to produce multiple streams in parallel applications. See

`jumped()`

for details. More information about this PRNG is available at the xorshift, xoroshiro and xoshiro authors’ page.XorShift1024*φ - Fast fast generator based on the XSadd generator. Supports

`jump`

and so can be used in parallel applications. See the documentation for`jumped()`

for details. More information about these PRNGs is available at the xorshift, xoroshiro and xoshiro authors’ page.Xorshiro256** and Xorshiro512** - The most recently introduced XOR, shift, and rotate generator. Supports

`jump`

and so can be used in parallel applications. See the documentation for`jumped()`

for details. More information about these PRNGs is available at the xorshift, xoroshiro and xoshiro authors’ page.PCG-64 - Fast generator that support many parallel streams and can be advanced by an arbitrary amount. See the documentation for

`advance()`

. PCG-64 has a period of \(2^{128}\). See the PCG author’s page for more details about this class of PRNG.ThreeFry and Philox - counter-based generators capable of being advanced an arbitrary number of steps or generating independent streams. See the Random123 page for more details about this class of PRNG.

## Random Generator¶

## Bit Generators¶

Warning

These for formerly called Basic Random Number Generators. They have been renamed Bit Generators for compatibility with the version that will ship with NumPy.