.. _mt2203_brng:

MT2203 brng
===========

Each generator from the set of `6024 Mersenne Twister pseudorandom number generators <philoxrng_>`_ can be 
initialized with either an integral seed, a list of integral seeds, or automatically.

An individual member of the set can be addressed by using a tuple to specify the generator 
:code:`brng=("MT2203", set_id)` where :math:`0 \leq \text{set_id} < 6024`.

.. code-block:: python
    :caption: Construction for MT2203 basic psuedo-random number generator with scalar seed

        import mkl_random
        seed = 777
        # initialize representative generator from the set
        rs0 = mkl_random.RandomState(seed, brng="MT2203")

        # initialize 0-th member of the set
        rs0 = mkl_random.RandomState(seed, brng=("MT2203", 0))

        # initialize 5-th member of the set
        rs5 = mkl_random.RandomState(seed, brng=("MT2203", 5))

        sample = rs5.uniform(0, 1, size=1_000_000)

.. code-block:: python
    :caption: Construction for MT2203 basic psuedo-random number generator with vector seed

        import mkl_random
        rs = mkl_random.RandomState([1234, 567, 89, 0], brng=("MT2203", 6023))

        # Use random state instance to generate 1000 random numbers from
        # Gamma(3, 1) distibution
        gsample = rs_vec.gamma(3, 1, size=1000)

When seed is not specified, the generator is initialized using system clock, e.g.:

.. code-block:: python
    :caption: Construction for MT2203 basic psuedo-random number generator with automatic seed

        import mkl_random
        rs_def = mkl_random.RandomState(brng="MT2203")

        # Use random state instance to generate 1000 random numbers
        # from discrete uniform distribution [1, 6]
        isample = rs_def.randint(1, 6 + 1, size=1000)

Different members of the set of generators initialized with the same seed are designed to generate
statistically independent streams of randomness. This property makes MT2203 generator suitable for 
parallelizing stochastic algorithms. Please refer to "examples/" folder in the `GitHub repo
<https://github.com/IntelPython/mkl_random>`_.

.. _philoxrng: https://spec.oneapi.io/versions/1.0-rev-2/elements/oneMKL/source/domains/rng/mkl-rng-philox4x32x10.html