Class Generator

dask/array/random.py:30–389

Container for the BitGenerators. ``Generator`` exposes a number of methods for generating random numbers drawn from a variety of probability distributions and serves as a replacement for ``RandomState``. The main difference between the two is that ``Generator`` relies on an add

class Generator:
    """
    Container for the BitGenerators.

    ``Generator`` exposes a number of methods for generating random
    numbers drawn from a variety of probability distributions and serves
    as a replacement for ``RandomState``. The main difference between the
    two is that ``Generator`` relies on an additional ``BitGenerator`` to
    manage state and generate the random bits, which are then transformed
    into random values from useful distributions. The default ``BitGenerator``
    used by ``Generator`` is ``PCG64``. The ``BitGenerator`` can be changed
    by passing an instantiated ``BitGenerator`` to ``Generator``.

    The function :func:`dask.array.random.default_rng` is the recommended way
    to instantiate a ``Generator``.

    .. warning::

       No Compatibility Guarantee.

       ``Generator`` does not provide a version compatibility guarantee. In
       particular, as better algorithms evolve the bit stream may change.

    Parameters
    ----------
    bit_generator : BitGenerator
        BitGenerator to use as the core generator.

    Notes
    -----
    In addition to the distribution-specific arguments, each ``Generator``
    method takes a keyword argument `size` that defaults to ``None``. If
    `size` is ``None``, then a single value is generated and returned. If
    `size` is an integer, then a 1-D array filled with generated values is
    returned. If `size` is a tuple, then an array with that shape is
    filled and returned.

    The Python stdlib module `random` contains pseudo-random number generator
    with a number of methods that are similar to the ones available in
    ``Generator``. It uses Mersenne Twister, and this bit generator can
    be accessed using ``MT19937``. ``Generator``, besides being
    Dask-aware, has the advantage that it provides a much larger number
    of probability distributions to choose from.

    All ``Generator`` methods are identical to ``np.random.Generator`` except
    that they also take a `chunks=` keyword argument.

    ``Generator`` does not guarantee parity in the generated numbers
    with any third party library. In particular, numbers generated by
    `Dask` and `NumPy` will differ even if they use the same seed.

    Examples
    --------
    >>> from numpy.random import PCG64
    >>> from dask.array.random import Generator
    >>> rng = Generator(PCG64())
    >>> rng.standard_normal().compute() # doctest: +SKIP
    array(0.44595957)  # random