.. _new-or-different:

.. currentmodule:: numpy.random

What's new or different
-----------------------

NumPy 1.17.0 introduced `Generator` as an improved replacement for
the :ref:`legacy <legacy>` `RandomState`. Here is a quick comparison of the two
implementations.

======================= ================== =============
Feature                 Older Equivalent   Notes
----------------------- ------------------ -------------
`Generator`             `RandomState`      `Generator` requires a stream
                                           source, called a `BitGenerator`
                                           A number of these are provided.
                                           `RandomState` uses the Mersenne
                                           Twister `MT19937` by default,
                                           but can also be instantiated
                                           with any BitGenerator.
----------------------- ------------------ -------------
`~.Generator.random`    `random_sample`,   Access the values in a
                        `rand`             BitGenerator, convert them to
                                           ``float64`` in the interval
                                           ``[0.0., 1.0)``. In addition
                                           to the ``size`` kwarg, now
                                           supports ``dtype='d'`` or
                                           ``dtype='f'``, and an ``out``
                                           kwarg to fill a user-supplied
                                           array.

                                           Many other distributions are also
                                           supported.
----------------------- ------------------ -------------
`~.Generator.integers`  `randint`,         Use the ``endpoint`` kwarg to
                        `random_integers`  adjust the inclusion or exclusion
                                           of the ``high`` interval endpoint.
======================= ================== =============

* The normal, exponential and gamma generators use 256-step Ziggurat
  methods which are 2-10 times faster than NumPy's default implementation in
  `~.Generator.standard_normal`, `~.Generator.standard_exponential` or
  `~.Generator.standard_gamma`. Because of the change in algorithms, it is not
  possible to reproduce the exact random values using `Generator` for these
  distributions or any distribution method that relies on them.

.. ipython:: python

  import numpy.random
  rng = np.random.default_rng()
  %timeit -n 1 rng.standard_normal(100000)
  %timeit -n 1 numpy.random.standard_normal(100000)

.. ipython:: python

  %timeit -n 1 rng.standard_exponential(100000)
  %timeit -n 1 numpy.random.standard_exponential(100000)

.. ipython:: python

  %timeit -n 1 rng.standard_gamma(3.0, 100000)
  %timeit -n 1 numpy.random.standard_gamma(3.0, 100000)


* `~.Generator.integers` is now the canonical way to generate integer
  random numbers from a discrete uniform distribution. This replaces both
  `randint` and the deprecated `random_integers`.
* The `rand` and `randn` methods are only available through the legacy
  `~.RandomState`.
* `Generator.random` is now the canonical way to generate floating-point
  random numbers, which replaces `RandomState.random_sample`,
  `sample`, and `ranf`, all of which were aliases. This is consistent with
  Python's `random.random`.
* All bit generators can produce doubles, uint64s and
  uint32s via CTypes (`~PCG64.ctypes`) and CFFI (`~PCG64.cffi`).
  This allows these bit generators to be used in numba.
* The bit generators can be used in downstream projects via
  Cython.
* All bit generators use `SeedSequence` to :ref:`convert seed integers to
  initialized states <seeding_and_entropy>`.
* Optional ``dtype`` argument that accepts ``np.float32`` or ``np.float64``
  to produce either single or double precision uniform random variables for
  select distributions. `~.Generator.integers` accepts a ``dtype`` argument
  with any signed or unsigned integer dtype.

  * Uniforms (`~.Generator.random` and `~.Generator.integers`)
  * Normals (`~.Generator.standard_normal`)
  * Standard Gammas (`~.Generator.standard_gamma`)
  * Standard Exponentials (`~.Generator.standard_exponential`)

.. ipython:: python

  rng = np.random.default_rng()
  rng.random(3, dtype=np.float64)
  rng.random(3, dtype=np.float32)
  rng.integers(0, 256, size=3, dtype=np.uint8)

* Optional ``out`` argument that allows existing arrays to be filled for
  select distributions

  * Uniforms (`~.Generator.random`)
  * Normals (`~.Generator.standard_normal`)
  * Standard Gammas (`~.Generator.standard_gamma`)
  * Standard Exponentials (`~.Generator.standard_exponential`)

  This allows multithreading to fill large arrays in chunks using suitable
  BitGenerators in parallel.

.. ipython:: python

  rng = np.random.default_rng()
  existing = np.zeros(4)
  rng.random(out=existing[:2])
  print(existing)

* Optional ``axis`` argument for methods like `~.Generator.choice`,
  `~.Generator.permutation` and `~.Generator.shuffle` that controls which
  axis an operation is performed over for multi-dimensional arrays.

.. ipython:: python

  rng = np.random.default_rng()
  a = np.arange(12).reshape((3, 4))
  a
  rng.choice(a, axis=1, size=5)
  rng.shuffle(a, axis=1)        # Shuffle in-place
  a

* Added a method to sample from the complex normal distribution
  (`~.Generator.complex_normal`)