path: root/doc/source/reference/random/index.rst

.. currentmodule:: numpy.random

numpy.random
============

<<<<<<< HEAD
A `~RandomGenerator` can
be initialized with a number of different Random Number Generators (RNG)s, and
exposes many different probability distributions.

=======
Numpy's random number routines produce psuedo random numbers using
combinations of a `BitGenerator` to create sequences and a `Generator`
to use those sequences to sample from different statistical distributions:

* BitGenerators: Objects that generate random numbers. These are typically
  unsigned integer words filled with sequences of either 32 or 64 random bits.
* Generators: Objects that transform sequences of random bits from a
  BitGenerator into sequences of numbers that follow a specific probability
  distribution (such as uniform, Normal or Binomial) within a specified
  interval.

Since Numpy version 1.17.0 the Generator can be initialized with a
number of different BitGenerators. It exposes many different probability
distributions. See `NEP 19 <https://www.numpy.org/neps/
nep-0019-rng-policy.html>`_ for context on the updated random Numpy number
routines. The legacy `RandomState` random number routines are still
available, but limited to a single BitGenerator.

For convenience and backward compatibility, a single `RandomState`
instance's methods are imported into the numpy.random namespace, see
:ref:`legacy` for the complete list.
>>>>>>> d7650d9f2... DOC: use more BitGenerator instead of other termonology

Quick Start
-----------

<<<<<<< HEAD
By default, `RandomGenerator` uses normals provided by
`xoroshiro128.Xoroshiro128` which will be faster than the legacy methods in
`mtrand.RandomState`
=======
By default, `Generator` uses normals provided by `xoroshiro128.Xoroshiro128`
which will be faster than the legacy methods in `RandomState`
>>>>>>> d7650d9f2... DOC: use more BitGenerator instead of other termonology

.. code-block:: python

  # Uses the old numpy.random.RandomState
  from numpy import random
  random.standard_normal()

<<<<<<< HEAD
`RandomGenerator` can be used as a direct replacement for
`~RandomState`, although the random values are generated by
`~xoroshiro128.Xoroshiro128`. The `RandomGenerator` holds an instance of a RNG.
It is accessable as ``gen.brng``.
=======
`Generator` can be used as a direct replacement for `RandomState`,
although the random values are generated by `~xoroshiro128.Xoroshiro128`. The
`Generator` holds an instance of a BitGenerator. It is accessable as
``gen.bit_generator``.
>>>>>>> d7650d9f2... DOC: use more BitGenerator instead of other termonology

.. code-block:: python

  # As replacement for RandomState()
  from numpy.random import RandomGenerator
  rg = RandomGenerator()
  rg.standard_normal()
  rg.bit_generator


Seeds can be passed to any of the basic RNGs. Here `mt19937.MT19937` is used
and the ``RandomGenerator`` is accessed via the attribute `mt19937.MT19937.
generator`.

.. code-block:: python

  from numpy.random import MT19937
  rg = MT19937(12345).generator
  rg.standard_normal()


Introduction
------------
RandomGen takes a different approach to producing random numbers from the
<<<<<<< HEAD
:class:`numpy.random.RandomState` object.  Random number generation is
separated into two components, a basic RNG and a random generator.
=======
`RandomState` object.  Random number generation is separated into two
components, a bit generator and a random generator.
>>>>>>> d7650d9f2... DOC: use more BitGenerator instead of other termonology

The basic RNG 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 basic random generator also handles
all seeding since this varies when using alternative basic RNGs.

<<<<<<< HEAD
The `random generator <~RandomGenerator>` takes the
basic RNG-provided functions and transforms them into more useful
=======
The `random generator <Generator>` takes the
bit generator-provided stream and transforms them into more useful
>>>>>>> d7650d9f2... DOC: use more BitGenerator instead of other termonology
distributions, e.g., simulated normal random values. This structure allows
alternative basic RNGs to be used without code duplication.

<<<<<<< HEAD
The ``RandomGenerator`` is the user-facing object
that is nearly identical to :class:`~.RandomState`. The canonical
method to initialize a generator passes a basic RNG -- `~mt19937.MT19937`, the
underlying RNG in NumPy  -- as the sole argument. Note that the basic RNG must
be instantized.

.. code-block:: python

  from numpy.random import RandomGenerator, MT19937
  rg = RandomGenerator(MT19937())
  rg.random_sample()

Seed information is directly passed to the basic RNG.
=======
The `Generator` is the user-facing object that is nearly identical to
`RandomState`. The canonical method to initialize a generator passes a
`~mt19937.MT19937` bit generator, the underlying bit generator in Python -- as
the sole argument. Note that the bit generator must be instantiated.
>>>>>>> d7650d9f2... DOC: use more BitGenerator instead of other termonology

.. code-block:: python

  rg = RandomGenerator(MT19937(12345))
  rg.random_sample()

A shorthand method is also available which uses the `~mt19937.MT19937.
generator` property from a basic RNG to access an embedded random generator.

.. code-block:: python

  rg = MT19937(12345).generator
  rg.random_sample()

What's New or Different
~~~~~~~~~~~~~~~~~~~~~~~
.. warning::

  The Box-Muller method used to produce NumPy's normals is no longer available
<<<<<<< HEAD
  in `~.RandomGenerator`.  It is not possible to reproduce the exact random
  values using ``RandomGenerator`` for the normal distribution or any other
=======
  in `Generator`.  It is not possible to reproduce the exact random
  values using Generator for the normal distribution or any other
>>>>>>> d7650d9f2... DOC: use more BitGenerator instead of other termonology
  distribution that relies on the normal such as the `numpy.random.gamma` or
  `numpy.random.standard_t`. If you require bitwise backward compatible
  streams, use `RandomState`.

* The Generator's normal, exponential and gamma functions 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 distributions
* Optional ``out`` argument that allows existing arrays to be filled for
  select distributions
* `~entropy.random_entropy` provides access to the system
  source of randomness that is used in cryptographic applications (e.g.,
  ``/dev/urandom`` on Unix).
<<<<<<< HEAD
* All basic random generators functions can produce doubles, uint64s and
  uint32s via CTypes (`~xoroshiro128.Xoroshiro128.ctypes`)
  and CFFI (:meth:`~xoroshiro128.Xoroshiro128.cffi`).
  This allows these basic RNGs to be used in numba.
* The basic random number generators can be used in downstream projects via
  :ref:`Cython <randomgen_cython>`.
* Support for Lemire’s method [Lemire]_ of generating uniform integers on an
  arbitrary interval by setting ``use_masked=True`` in
  `~RandomGenerator.randint`.
=======
* All BitGenerators can produce doubles, uint64s and uint32s via CTypes
  (`~xoroshiro128.Xoroshiro128.ctypes`) and CFFI
  (:meth:`~xoroshiro128.Xoroshiro128.cffi`). This allows the bit generators to
  be used in numba.
* The bit generators can be used in downstream projects via
  :ref:`Cython <randomgen_cython>`.
* `~.Generator.integers` is now the canonical way to generate integer
  random numbers from a discrete uniform distribution. The ``rand`` and
  ``randn`` methods are only availabe through the legacy `~.RandomState`.
  The ``endpoint`` keyword can be used to specify open or closed intervals.
  This replaces both ``randint`` and the deprecated ``random_integers``.
* `~.Generator.random` is now the canonical way to generate floating-point
  random numbers, which replaces `random_sample`, `sample`, and `ranf`. This
  is consistent with Python's `random.random`.

>>>>>>> d7650d9f2... DOC: use more BitGenerator instead of other termonology

See :ref:`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:

* :ref:`independent-streams`
* :ref:`jump-and-advance`

Supported BitGenerators
-----------------------
The included BitGenerators are:

* MT19937 - The standard Python BitGenerator. Produces identical results to
  Python using the same seed/state. Adds a `~mt19937.MT19937.jumped` function
  that returns a new generator with state as-if ``2**128`` draws have been made.
* 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
  `~xoroshiro128.Xoroshiro128.jump` 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
  `~xorshift1024.Xorshift1024.jumped` for details. More
  information about these bit generators 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
  `~xoshiro256.Xoshirt256.jumped` for details. More information about these bit
  generators is available at the `xorshift, xoroshiro and xoshiro authors'
  page`_.
* 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.

.. _`dSFMT authors' page`: http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/SFMT/
.. _`xorshift, xoroshiro and xoshiro authors' page`:  http://xoroshiro.di.unimi.it/
.. _`PCG author's page`: http://www.pcg-random.org/
.. _`Random123`: https://www.deshawresearch.com/resources_random123.html

Generator
---------
.. toctree::
   :maxdepth: 1

   generator
   legacy mtrand <legacy>

BitGenerators
-------------

.. toctree::
   :maxdepth: 1

   BitGenerators <bit_generators/index>

New Features
------------
.. toctree::
   :maxdepth: 2

   Parallel Applications <parallel>
   Multithreaded Generation <multithreading>
   new-or-different
   Comparing Performance <performance>
   extending
   Reading System Entropy <entropy>
   references

Changes
~~~~~~~

This package was developed independently of NumPy and was integrated in version
1.17.0. The original repo is at https://github.com/bashtage/randomgen.

.. toctree::
   :maxdepth: 2

   Change Log <change-log>