.. module:: cupy.random

Random sampling (:mod:`cupy.random`)
====================================

Differences between :mod:`cupy.random` and :mod:`numpy.random`:

* Most functions under :mod:`cupy.random` support the ``dtype`` option, which do not exist in the corresponding NumPy APIs.
  This option enables generation of float32 values directly without any space overhead.
* :func:`cupy.random.default_rng` uses XORWOW bit generator by default.
* Random states cannot be serialized. See the description below for details.
* CuPy does not guarantee that the same number generator is used across major versions.
  This means that numbers generated by :mod:`cupy.random` by new major version may not be the same as the previous one, even if the same seed and distribution are used.

.. currentmodule:: cupy.random

New Random Generator API
------------------------

.. Hint:: `NumPy API Reference: Random sampling (numpy.random) <https://numpy.org/doc/stable/reference/random/>`_

Random Generator
~~~~~~~~~~~~~~~~

.. Hint:: `NumPy API Reference: Random Generator <https://numpy.org/doc/stable/reference/random/generator.html>`_

.. autosummary::
   :toctree: generated/

   default_rng
   Generator

Bit Generators
~~~~~~~~~~~~~~

.. Hint:: `NumPy API Reference: Bit Generators <https://numpy.org/doc/stable/reference/random/bit_generators/index.html>`_

.. autosummary::
   :toctree: generated/

   BitGenerator

CuPy provides the following bit generator implementations:

.. autosummary::
   :toctree: generated/

   XORWOW
   MRG32k3a
   Philox4x3210

Legacy Random Generation
------------------------

.. Hint::
   * `NumPy API Reference: Legacy Random Generation <https://numpy.org/doc/stable/reference/random/legacy.html>`_
   * `NumPy 1.16 Reference <https://numpy.org/doc/1.16/reference/routines.random.html>`_

.. autosummary::
   :toctree: generated/

   RandomState

Functions in :mod:`cupy.random`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. autosummary::
   :toctree: generated/

   beta
   binomial
   bytes
   chisquare
   choice
   dirichlet
   exponential
   f
   gamma
   geometric
   gumbel
   hypergeometric
   laplace
   logistic
   lognormal
   logseries
   multinomial
   multivariate_normal
   negative_binomial
   noncentral_chisquare
   noncentral_f
   normal
   pareto
   permutation
   poisson
   power
   rand
   randint
   randn
   random
   random_integers
   random_sample
   ranf
   rayleigh
   sample
   seed
   shuffle
   standard_cauchy
   standard_exponential
   standard_gamma
   standard_normal
   standard_t
   triangular
   uniform
   vonmises
   wald
   weibull
   zipf

CuPy does not provide ``cupy.random.get_state`` nor ``cupy.random.set_state`` at this time.
Use the following CuPy-specific APIs instead.
Note that these functions use :class:`cupy.random.RandomState` instance to represent the internal state, which cannot be serialized.

.. autosummary::
   :toctree: generated/

   get_random_state
   set_random_state