.. module:: cupy.random

Random Sampling (``cupy.random``)
=================================

.. https://docs.scipy.org/doc/numpy-1.16.1/reference/routines.random.html
.. https://docs.scipy.org/doc/numpy/reference/random/legacy.html

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

* CuPy provides `Legacy Random Generation <https://docs.scipy.org/doc/numpy/reference/random/legacy.html>`_ API (see also: `NumPy 1.16 Reference <https://docs.scipy.org/doc/numpy-1.16.1/reference/routines.random.html>`_).
  The new random generator API (:class:`numpy.random.Generator` class) introduced in NumPy 1.17 has not been implemented yet.
* 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.
* 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.


Simple random data
------------------

.. autosummary::
   :toctree: generated/
   :nosignatures:

   cupy.random.rand
   cupy.random.randn
   cupy.random.randint
   cupy.random.random_integers
   cupy.random.random_sample
   cupy.random.random
   cupy.random.ranf
   cupy.random.sample
   cupy.random.choice
   cupy.random.bytes


Permutations
------------

.. autosummary::
   :toctree: generated/
   :nosignatures:

   cupy.random.shuffle
   cupy.random.permutation


Distributions
-------------

.. autosummary::
   :toctree: generated/
   :nosignatures:

   cupy.random.beta
   cupy.random.binomial
   cupy.random.chisquare
   cupy.random.dirichlet
   cupy.random.exponential
   cupy.random.f
   cupy.random.gamma
   cupy.random.geometric
   cupy.random.gumbel
   cupy.random.hypergeometric
   cupy.random.laplace
   cupy.random.logistic
   cupy.random.lognormal
   cupy.random.logseries
   cupy.random.multinomial
   cupy.random.multivariate_normal
   cupy.random.negative_binomial
   cupy.random.noncentral_chisquare
   cupy.random.noncentral_f
   cupy.random.normal
   cupy.random.pareto
   cupy.random.poisson
   cupy.random.power
   cupy.random.rayleigh
   cupy.random.standard_cauchy
   cupy.random.standard_exponential
   cupy.random.standard_gamma
   cupy.random.standard_normal
   cupy.random.standard_t
   cupy.random.triangular
   cupy.random.uniform
   cupy.random.vonmises
   cupy.random.wald
   cupy.random.weibull
   cupy.random.zipf


Random generator
----------------

.. autosummary::
   :toctree: generated/
   :nosignatures:

   cupy.random.RandomState
   cupy.random.seed
   cupy.random.get_random_state
   cupy.random.set_random_state

.. note::

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