.. currentmodule:: dpnp.random Random sampling (:mod:`dpnp.random`) ==================================== .. hint:: `NumPy API Reference: Random sampling `_ DPNP draws random numbers on the SYCL device, with the counter-based Philox4x32x10 generator of the oneMKL device RNG API. It provides the :class:`Generator` API of NumPy, recommended for new code. The legacy :class:`RandomState` API and the module-level functions still use the host-side oneMKL RNG. .. code-block:: python import dpnp rng = dpnp.random.default_rng(seed=42) x = rng.standard_normal((3, 4)) # on the default device y = rng.integers(0, 10, size=5, usm_type="shared") rng = dpnp.random.default_rng(42, device="cpu") A generator draws all its samples on one SYCL queue, chosen with the ``device`` or ``sycl_queue`` keyword when it is created. All samples are :class:`dpnp.ndarray`, zero-dimensional when ``size`` is ``None``. Differences from NumPy ---------------------- * The streams differ from NumPy's. For a given seed, output size and data type, the raw bits and the uniform floats are the same on every device. The other distributions use transcendental functions, which may round differently on another device: their samples agree to a few ULP, or differ when a rejection sampler then takes another candidate. The discrete distributions also depend on the device's support of double precision, as noted below. * The values depend on the output size: a draw is not a prefix of a larger one, and two draws of ``n`` values differ from one draw of ``2 * n``. Code splitting its draws into chunks gets other values. * The floating-point distributions take a ``dtype`` keyword, as in CuPy, which defaults to the default floating-point type of the device, so on a device without double precision the same seed gives other values by default. * All methods take a ``usm_type`` keyword. With ``usm_type=None``, the default, the samples take the USM type of the array parameters, or ``"device"`` when there are none. * Parameters on the host (Python scalars, lists and NumPy arrays) are checked as in NumPy. Parameters in :class:`dpnp.ndarray` are not, since that would wait for the device. Invalid ones give undefined values, such as NaN or the smallest ``int64``, but the kernels handle them safely: they never loop without end or access memory out of bounds. Floating-point arrays given for integer parameters are converted as by :meth:`dpnp.ndarray.astype`, whose result for NaN and out-of-range values is undefined. * The discrete distributions return ``int64`` values. They compute in double precision on devices supporting it, and in single precision otherwise. There, the streams differ from the ones of devices with double precision, and some samples are only multiples of a power of two: the ones above ``2**24`` of ``geometric``, ``logseries`` and ``zipf``, and the ones of ``poisson`` and ``binomial`` with a standard deviation above about ``2**22``. * ``zipf`` follows the Zipf distribution truncated to the largest ``int64``. NumPy's rejection test rounds to accepting every sample above ``2**53``, which makes its tail too heavy for ``a`` close to 1. * ``hypergeometric`` requires ``ngood`` and ``nbad`` below ``10**9``. * :meth:`Generator.shuffle` only accepts a :class:`dpnp.ndarray`, as in CuPy. * Generators and bit generators cannot be pickled or copied, and the bit generators have no ``advance`` or ``jumped`` method. Random Generator ---------------- .. autosummary:: :toctree: generated/ :nosignatures: default_rng Generator Accessing the bit generator and spawning ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. autosummary:: :toctree: generated/ :nosignatures: Generator.bit_generator Generator.spawn Simple random data ^^^^^^^^^^^^^^^^^^ .. autosummary:: :toctree: generated/ :nosignatures: Generator.integers Generator.random Generator.choice Generator.bytes Permutations ^^^^^^^^^^^^ .. autosummary:: :toctree: generated/ :nosignatures: Generator.shuffle Generator.permutation Generator.permuted Distributions ^^^^^^^^^^^^^ .. autosummary:: :toctree: generated/ :nosignatures: Generator.beta Generator.binomial Generator.chisquare Generator.dirichlet Generator.exponential Generator.f Generator.gamma Generator.geometric Generator.gumbel Generator.hypergeometric Generator.laplace Generator.logistic Generator.lognormal Generator.logseries Generator.multinomial Generator.multivariate_hypergeometric Generator.multivariate_normal Generator.negative_binomial Generator.noncentral_chisquare Generator.noncentral_f Generator.normal Generator.pareto Generator.poisson Generator.power Generator.rayleigh Generator.standard_cauchy Generator.standard_exponential Generator.standard_gamma Generator.standard_normal Generator.standard_t Generator.triangular Generator.uniform Generator.vonmises Generator.wald Generator.weibull Generator.zipf Bit generators -------------- .. autosummary:: :toctree: generated/ :nosignatures: BitGenerator BitGenerator.random_raw BitGenerator.spawn BitGenerator.state Philox4x3210 SeedSequence Legacy random generation ------------------------ .. hint:: `NumPy API Reference: Legacy random generation `_ Simple random data ^^^^^^^^^^^^^^^^^^ .. autosummary:: :toctree: generated/ :nosignatures: rand randn randint random_integers random_sample random ranf sample choice bytes Permutations ^^^^^^^^^^^^ .. autosummary:: :toctree: generated/ :nosignatures: shuffle permutation Distributions ^^^^^^^^^^^^^ .. autosummary:: :toctree: generated/ :nosignatures: beta binomial chisquare dirichlet exponential f gamma geometric gumbel hypergeometric laplace logistic lognormal logseries multinomial multivariate_normal negative_binomial noncentral_chisquare noncentral_f normal pareto poisson power rayleigh standard_cauchy standard_exponential standard_gamma standard_normal standard_t triangular uniform vonmises wald weibull zipf Random generator ^^^^^^^^^^^^^^^^ .. autosummary:: :toctree: generated/ :nosignatures: RandomState seed get_random_state set_random_state