From 8798c60b664524c8edec9e9bf5b716a3cce6c17d Mon Sep 17 00:00:00 2001 From: Nikita Grigorian Date: Thu, 19 Mar 2026 18:36:48 -0700 Subject: [PATCH 01/16] add documentation for patching utilities and interfaces --- docs/source/index.rst | 3 +- docs/source/reference/api.rst | 6 ++ docs/source/reference/interfaces.rst | 110 +++++++++++++++++++++++++++ docs/source/reference/patching.rst | 27 +++++++ 4 files changed, 145 insertions(+), 1 deletion(-) create mode 100644 docs/source/reference/interfaces.rst create mode 100644 docs/source/reference/patching.rst diff --git a/docs/source/index.rst b/docs/source/index.rst index f7f7e5c..b8eafaf 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -39,7 +39,8 @@ Intel(R) oneAPI Math Kernel Library .. grid-item-card:: Reference Guide - The reference guide contains a detailed description of class :class:`mkl_random.RandomState` and its methods. + The reference guide contains a detailed description of class :class:`mkl_random.MKLRandomState`, + the :ref:`interfaces ` submodule, and :ref:`NumPy patching ` utilities. +++ diff --git a/docs/source/reference/api.rst b/docs/source/reference/api.rst index cf2f084..1ea02ca 100644 --- a/docs/source/reference/api.rst +++ b/docs/source/reference/api.rst @@ -5,3 +5,9 @@ Class RandomState .. autoclass:: mkl_random.RandomState :members: + +Class MKLRandomState +==================== + +.. autoclass:: mkl_random.MKLRandomState + :members: diff --git a/docs/source/reference/interfaces.rst b/docs/source/reference/interfaces.rst new file mode 100644 index 0000000..1b63cd9 --- /dev/null +++ b/docs/source/reference/interfaces.rst @@ -0,0 +1,110 @@ +.. _interfaces: + +:mod:`mkl_random.interfaces` +==================================================== + +:mod:`mkl_random.interfaces` provides drop-in replacements for supported random number generation +modules using :mod:`mkl_random` implementations. Currently, only a NumPy interface is provided, +but more may be added in the future. + + +.. _numpy_random_interface: + +NumPy interface --- :mod:`mkl_random.interfaces.numpy_random` +------------------------------------------------------------- + +:mod:`mkl_random.interfaces.numpy_random` is a drop-in replacement for the legacy portion of +:mod:`numpy.random`. + +.. note:: + While the API is the same, :mod:`mkl_random.interfaces.numpy_random` is **not** seed-compatible + with :mod:`numpy.random`. Given the same seed, the two modules will produce different sequences. + The output of `get_state` and accepted input to `set_state` may also differ. It is not + recommended to provide the output of `get_state` from one module to `set_state` of the other. + There also may be differences in some edge cases, such as behavior of functions when given specific inputs. + + +RandomState class +^^^^^^^^^^^^^^^^^ + +.. autoclass:: mkl_random.interfaces.numpy_random.RandomState + :members: + :undoc-members: + + +Functions +^^^^^^^^^^^^^^^^^^^^^^ + +**Seeding and state functions:** + +.. autosummary:: + + mkl_random.interfaces.numpy_random.seed + mkl_random.interfaces.numpy_random.get_state + mkl_random.interfaces.numpy_random.set_state + +**Simple random data:** + +Similar to NumPy, the methods of :class:`RandomState` are exported as functions in the module. +Their usage is discouraged, as they are implemented from a global instance of :class:`RandomState`, +which means results may change across calls. + +.. autosummary:: + + mkl_random.interfaces.numpy_random.rand + mkl_random.interfaces.numpy_random.randn + mkl_random.interfaces.numpy_random.randint + mkl_random.interfaces.numpy_random.random_integers + mkl_random.interfaces.numpy_random.random_sample + mkl_random.interfaces.numpy_random.random + mkl_random.interfaces.numpy_random.ranf + mkl_random.interfaces.numpy_random.choice + mkl_random.interfaces.numpy_random.bytes + mkl_random.interfaces.numpy_random.sample + +**Permutations:** + +.. autosummary:: + + mkl_random.interfaces.numpy_random.shuffle + mkl_random.interfaces.numpy_random.permutation + +**Distributions:** + +.. autosummary:: + + mkl_random.interfaces.numpy_random.beta + mkl_random.interfaces.numpy_random.binomial + mkl_random.interfaces.numpy_random.chisquare + mkl_random.interfaces.numpy_random.dirichlet + mkl_random.interfaces.numpy_random.exponential + mkl_random.interfaces.numpy_random.f + mkl_random.interfaces.numpy_random.gamma + mkl_random.interfaces.numpy_random.geometric + mkl_random.interfaces.numpy_random.gumbel + mkl_random.interfaces.numpy_random.hypergeometric + mkl_random.interfaces.numpy_random.laplace + mkl_random.interfaces.numpy_random.logistic + mkl_random.interfaces.numpy_random.lognormal + mkl_random.interfaces.numpy_random.logseries + mkl_random.interfaces.numpy_random.multinomial + mkl_random.interfaces.numpy_random.multivariate_normal + mkl_random.interfaces.numpy_random.negative_binomial + mkl_random.interfaces.numpy_random.noncentral_chisquare + mkl_random.interfaces.numpy_random.noncentral_f + mkl_random.interfaces.numpy_random.normal + mkl_random.interfaces.numpy_random.pareto + mkl_random.interfaces.numpy_random.poisson + mkl_random.interfaces.numpy_random.power + mkl_random.interfaces.numpy_random.rayleigh + mkl_random.interfaces.numpy_random.standard_cauchy + mkl_random.interfaces.numpy_random.standard_exponential + mkl_random.interfaces.numpy_random.standard_gamma + mkl_random.interfaces.numpy_random.standard_normal + mkl_random.interfaces.numpy_random.standard_t + mkl_random.interfaces.numpy_random.triangular + mkl_random.interfaces.numpy_random.uniform + mkl_random.interfaces.numpy_random.vonmises + mkl_random.interfaces.numpy_random.wald + mkl_random.interfaces.numpy_random.weibull + mkl_random.interfaces.numpy_random.zipf diff --git a/docs/source/reference/patching.rst b/docs/source/reference/patching.rst new file mode 100644 index 0000000..a14342a --- /dev/null +++ b/docs/source/reference/patching.rst @@ -0,0 +1,27 @@ +.. _patching: + +Patching :mod:`numpy.random` +============================ + +:mod:`mkl_random` can temporarily replace functions and classes in :mod:`numpy.random` with +:mod:`mkl_random`implementations from the :ref:`numpy interface `. + + +Functions +--------- + +.. autofunction:: mkl_random.patch_numpy_random + +.. autofunction:: mkl_random.restore_numpy_random + +.. autofunction:: mkl_random.is_patched + + +Context manager +--------------- + +.. autoclass:: mkl_random.mkl_random + :members: + +:class:`mkl_random.mkl_random` is both a context manager and a decorator, making it possible to +scope the patch to a block of code or a function. From 94567169d11253c5fdbe25a847b1420e72675a0a Mon Sep 17 00:00:00 2001 From: Nikita Grigorian Date: Thu, 19 Mar 2026 18:36:54 -0700 Subject: [PATCH 02/16] show inherited members in MKLRandomState and RandomState --- docs/source/reference/api.rst | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/docs/source/reference/api.rst b/docs/source/reference/api.rst index 1ea02ca..4bb2af0 100644 --- a/docs/source/reference/api.rst +++ b/docs/source/reference/api.rst @@ -1,13 +1,15 @@ .. _fullapi: -Class RandomState -================= - -.. autoclass:: mkl_random.RandomState - :members: - Class MKLRandomState ==================== .. autoclass:: mkl_random.MKLRandomState :members: + :inherited-members: + +Class RandomState +================= + +.. autoclass:: mkl_random.RandomState + :members: + :inherited-members: From 3fca0b6f77f0d08ea607eef0c3a9195e91dd000f Mon Sep 17 00:00:00 2001 From: Nikita Grigorian Date: Thu, 19 Mar 2026 18:43:40 -0700 Subject: [PATCH 03/16] add sections to index.rst about interfaces and patching --- docs/source/reference/index.rst | 23 ++++++++++++++++++++--- 1 file changed, 20 insertions(+), 3 deletions(-) diff --git a/docs/source/reference/index.rst b/docs/source/reference/index.rst index fffc0c1..37a96fd 100644 --- a/docs/source/reference/index.rst +++ b/docs/source/reference/index.rst @@ -1,10 +1,10 @@ -:mod:`mkl_random` APIs +:mod:`mkl_random` Overview ====================== -The class :doc:`mkl_random.RandomState <./api>` exposes sampling from probability distributions while supporting +The class :doc:`mkl_random.MKLRandomState <./api>` exposes sampling from probability distributions while supporting different streams of randomness, also known as basic random number generators. -The basic random number generator is chosen by specifying :code:`brng` keyword argument to the constructor of :code:`mkl.RandomState` class. +The basic random number generator is chosen by specifying :code:`brng` keyword argument to the constructor of :code:`mkl.MKLRandomState` class. The list of supported basic random number generators is as follows (also see `oneMKL Engines `_): @@ -22,10 +22,27 @@ The list of supported basic random number generators is as follows (also see `on .. _oneMKLBRNG: https://spec.oneapi.io/versions/1.0-rev-2/elements/oneMKL/source/domains/rng/engines-basic-random-number-generators.html + +Drop-in interfaces +------------------ + +The :mod:`mkl_random.interfaces` submodule provides drop-in replacements for standard random modules: + +* :ref:`mkl_random.interfaces.numpy_random ` - a drop-in replacement for the legacy :mod:`numpy.random` module + + +Patching +-------- + +:mod:`mkl_random` can :ref:`patch numpy.random ` so that existing code calling :mod:`numpy.random` +functions can use :mod:`mkl_random` implementations. + .. toctree:: :hidden: api + interfaces + patching mt19937 sfmt19937 r250 From f06e30deeaf2ebc9a900280e78cffced10e99872 Mon Sep 17 00:00:00 2001 From: Nikita Grigorian Date: Thu, 2 Apr 2026 14:55:44 -0700 Subject: [PATCH 04/16] address review comments --- docs/source/how_to.rst | 86 ++++++++++++++++++++++++++-- docs/source/reference/index.rst | 5 +- docs/source/reference/interfaces.rst | 8 +-- docs/source/reference/patching.rst | 6 +- docs/source/tutorials.rst | 20 +++++-- 5 files changed, 105 insertions(+), 20 deletions(-) diff --git a/docs/source/how_to.rst b/docs/source/how_to.rst index 985d574..8a29eb1 100644 --- a/docs/source/how_to.rst +++ b/docs/source/how_to.rst @@ -4,7 +4,7 @@ How-to Guides How to save and resume long computation --------------------------------------- -:class:`RandomState` is pickleable. Pickling allows to save and restore +:class:`MKLRandomState` is pickleable. Pickling allows to save and restore the internal state of the pseudo-random number generators. .. code-block:: python @@ -14,7 +14,7 @@ the internal state of the pseudo-random number generators. import mkl_random import pickle - rs = mkl_random.RandomState(seed=777, brng="r250") + rs = mkl_random.MKLRandomState(seed=777, brng="r250") draw = rs.standard_normal(size=1357913) # pickle random state @@ -45,7 +45,7 @@ from such family, initialized equally, produce streams of randomness statistical indistinguishable from independent. .. py:method:: skipahead(nskips) - :canonical: mkl_random.RandomState.skipahead + :canonical: mkl_random.MKLRandomState.skipahead Advance the state of the generator using skip-ahead method, or raise :code:`ValueError` exception if not supported. @@ -63,7 +63,7 @@ indistinguishable from independent. independence breaks down. .. py:method:: leapfrog(k, nstreams) - :canonical: mkl_random.RandomState.leapfrog + :canonical: mkl_random.MKLRandomState.leapfrog Initialize the state of the generator using leap-frog method, or raise :code:`ValueError` exception if not supported. @@ -85,3 +85,81 @@ indistinguishable from independent. randomness stasistically indistunguishable from independent. To use such families in parallel computation, assign difference family generators to different parallel workers and sample those assigned generators in each parallel worker. Please refer to "examples/" folder in the `GitHub repo `_ for more details. + + +Using :mod:`mkl_random` as a drop-in replacement for `numpy.random `_ +----------------------------------------------------------------- + +The :mod:`mkl_random.interfaces.numpy_random` module is aligned to the legacy +portion of the `numpy.random `_ legacy API. +You can import it in place of `numpy.random `_ +without changing the rest of your code: + +.. code-block:: python + :caption: Drop-in replacement for numpy.random + + from mkl_random.interfaces import numpy_random as rng + + rng.seed(1234) + x = rng.standard_normal(size=100) + y = rng.uniform(0, 1, size=100) + +See :ref:`interfaces` for a full list of available functions. + +.. note:: + While the API is the same, :mod:`mkl_random.interfaces.numpy_random` is **not** seed-compatible + with `numpy.random `_. Given the same seed, + the two modules will produce different sequences. There also may be differences in some edge cases, such as + behavior of functions when given specific inputs. + + +How to patch `numpy.random `_ with :mod:`mkl_random` +------------------------------------------------------------- + +Existing code that calls `numpy.random `_ +directly can be patched to use :mod:`mkl_random.interfaces.numpy_random` at runtime. + +The recommended approach is to use the :class:`mkl_random.mkl_random` context manager: + +.. code-block:: python + :caption: Temporarily patch numpy.random using context manager + + import numpy as np + import mkl_random + + with mkl_random.mkl_random(): + x = np.random.standard_normal(100) # uses mkl_random + y = np.random.uniform(0, 1, size=100) # uses mkl_random + +:mod:`mkl_random` also exposes the explicit patching functions: + +.. code-block:: python + :caption: Patch numpy.random for the duration of a script + + import mkl_random + mkl_random.patch_numpy_random() # subsequent numpy.random calls use mkl_random + + import numpy as np + data = np.random.normal(0, 1, size=100) + +.. note:: + The patching functions are provided for users' convenience, but they are not recommended + for new code. It is instead recommended to use :mod:`mkl_random` directly for new code. + For existing code where patching may be desirable, it is also suggested to prefer the + context manager, as it scopes the patch to blocks and thus, prevents user error of + forgetting to restore the original state, calling the patch multiple times, or + creating undefined behavior when patching in a multi-threaded program. + +You can also use :class:`mkl_random.mkl_random` as a decorator: + +.. code-block:: python + :caption: Patch numpy.random as a decorator + + import numpy as np + import mkl_random + + @mkl_random.mkl_random() + def get_data(): + return np.random.standard_normal(100) + +See :ref:`patching` for details. diff --git a/docs/source/reference/index.rst b/docs/source/reference/index.rst index 37a96fd..e90524f 100644 --- a/docs/source/reference/index.rst +++ b/docs/source/reference/index.rst @@ -28,14 +28,13 @@ Drop-in interfaces The :mod:`mkl_random.interfaces` submodule provides drop-in replacements for standard random modules: -* :ref:`mkl_random.interfaces.numpy_random ` - a drop-in replacement for the legacy :mod:`numpy.random` module +* :ref:`mkl_random.interfaces.numpy_random ` - a drop-in replacement for the legacy `numpy.random `_ module Patching -------- -:mod:`mkl_random` can :ref:`patch numpy.random ` so that existing code calling :mod:`numpy.random` -functions can use :mod:`mkl_random` implementations. +:mod:`mkl_random` can :ref:`patch numpy.random ` so that existing code calling `numpy.random `_ functions can use :mod:`mkl_random` implementations. .. toctree:: :hidden: diff --git a/docs/source/reference/interfaces.rst b/docs/source/reference/interfaces.rst index 1b63cd9..adc17ce 100644 --- a/docs/source/reference/interfaces.rst +++ b/docs/source/reference/interfaces.rst @@ -14,13 +14,13 @@ NumPy interface --- :mod:`mkl_random.interfaces.numpy_random` ------------------------------------------------------------- :mod:`mkl_random.interfaces.numpy_random` is a drop-in replacement for the legacy portion of -:mod:`numpy.random`. +`numpy.random `_. .. note:: While the API is the same, :mod:`mkl_random.interfaces.numpy_random` is **not** seed-compatible - with :mod:`numpy.random`. Given the same seed, the two modules will produce different sequences. - The output of `get_state` and accepted input to `set_state` may also differ. It is not - recommended to provide the output of `get_state` from one module to `set_state` of the other. + with `numpy.random `_. Given the same seed, the two modules + will produce different sequences. The output of :func:`get_state` and accepted input to :func:`set_state` may also differ. + It is not recommended to provide the output of :func:`get_state` from one module to :func:`set_state` of the other. There also may be differences in some edge cases, such as behavior of functions when given specific inputs. diff --git a/docs/source/reference/patching.rst b/docs/source/reference/patching.rst index a14342a..79aff22 100644 --- a/docs/source/reference/patching.rst +++ b/docs/source/reference/patching.rst @@ -1,10 +1,10 @@ .. _patching: -Patching :mod:`numpy.random` +Patching `numpy.random `_ ============================ -:mod:`mkl_random` can temporarily replace functions and classes in :mod:`numpy.random` with -:mod:`mkl_random`implementations from the :ref:`numpy interface `. +:mod:`mkl_random` can temporarily replace functions and classes in `numpy.random `_ with +:mod:`mkl_random` implementations from the :ref:`numpy interface `. Functions diff --git a/docs/source/tutorials.rst b/docs/source/tutorials.rst index 40d3d21..f399f8e 100644 --- a/docs/source/tutorials.rst +++ b/docs/source/tutorials.rst @@ -39,8 +39,9 @@ The :mod:`mkl_random` is also distributed as part of `Intel® Distribution for P First steps ----------- -The :mod:`mkl_random` package has followed the design of :class:`numpy.random` package to -make :mod:`mkl_random` easy to use for those already familiar with the :mod:`numpy.random` module. +The :mod:`mkl_random` package has followed the design of `numpy.random `_ +package to make :mod:`mkl_random` easy to use for those already familiar with the +`numpy.random `_ module. .. note:: Since the first release of :mod:`mkl_random`, NumPy introduced new classes :class:`numpy.random.Generator` and @@ -48,14 +49,21 @@ make :mod:`mkl_random` easy to use for those already familiar with the :mod:`num compatibility. :mod:`mkl_random`, at present, does not provide classes mirroring :class:`Generator` or :class:`BitGenerators`. -The state of pseudo-random number generator is stored in :class:`mkl_random.RandomState` class, +.. tip:: + If you want a drop-in replacement for the `numpy.random `_ legacy interface, + see :ref:`interfaces`. While it is recommended users rewrite code to use :mod:`mkl_random` or :mod:`mkl_random.interfaces.numpy_random` + directly, :mod:`mkl_random` provides tools to patch `numpy.random `_ so that + existing code transparently uses the MKL-backed implementations in `numpy.random `_. + See :ref:`patching` for details. + +The state of pseudo-random number generator is stored in :class:`mkl_random.MKLRandomState` class, so using :mod:`mkl_random` begins with creating an instance of this class: .. code-block:: python :caption: Construct random number generator import mkl_random - rs = mkl_random.RandomState(seed=1234) + rs = mkl_random.MKLRandomState(seed=1234) Sampling from difference probability distribution is done by calling the class methods on the constructed instance: @@ -75,7 +83,7 @@ Here is an example of estimating value of :math:`\pi` by using Monte-Carlo metho import numpy as np import mkl_random - rs = mkl_random.RandomState(seed=1234) + rs = mkl_random.MKLRandomState(seed=1234) sample_size = 10**8 batch_size = 10**6 @@ -110,7 +118,7 @@ distributions of interest. `True random generator `_ relies on laws of physics to provide those, leveraging dedicated hardware providing a source of entropy. -`Psuedo-random generator `_ is an algorithm that outputs a sequence that emulates true randomness. +`Pseudo-random generator `_ is an algorithm that outputs a sequence that emulates true randomness. The quality of emulation is tested statistically through a battery of test, e.g. `Diehard tests `_. These tests check if various statistical tests can separate the pseudo-random sequence from a true random one. From 85b3c4d6cd20105ae2cf94603badb6271ec85e47 Mon Sep 17 00:00:00 2001 From: Nikita Grigorian Date: Mon, 6 Apr 2026 14:24:47 -0700 Subject: [PATCH 05/16] use ..autofunction over autosummary for exported methods in interfaces namespace --- docs/source/reference/interfaces.rst | 108 +++++++++++++-------------- 1 file changed, 50 insertions(+), 58 deletions(-) diff --git a/docs/source/reference/interfaces.rst b/docs/source/reference/interfaces.rst index adc17ce..fbec3ca 100644 --- a/docs/source/reference/interfaces.rst +++ b/docs/source/reference/interfaces.rst @@ -37,11 +37,9 @@ Functions **Seeding and state functions:** -.. autosummary:: - - mkl_random.interfaces.numpy_random.seed - mkl_random.interfaces.numpy_random.get_state - mkl_random.interfaces.numpy_random.set_state +.. autofunction:: mkl_random.interfaces.numpy_random.seed +.. autofunction:: mkl_random.interfaces.numpy_random.get_state +.. autofunction:: mkl_random.interfaces.numpy_random.set_state **Simple random data:** @@ -49,62 +47,56 @@ Similar to NumPy, the methods of :class:`RandomState` are exported as functions Their usage is discouraged, as they are implemented from a global instance of :class:`RandomState`, which means results may change across calls. -.. autosummary:: - - mkl_random.interfaces.numpy_random.rand - mkl_random.interfaces.numpy_random.randn - mkl_random.interfaces.numpy_random.randint - mkl_random.interfaces.numpy_random.random_integers - mkl_random.interfaces.numpy_random.random_sample - mkl_random.interfaces.numpy_random.random - mkl_random.interfaces.numpy_random.ranf - mkl_random.interfaces.numpy_random.choice - mkl_random.interfaces.numpy_random.bytes - mkl_random.interfaces.numpy_random.sample +.. autofunction:: mkl_random.interfaces.numpy_random.rand +.. autofunction:: mkl_random.interfaces.numpy_random.randn +.. autofunction:: mkl_random.interfaces.numpy_random.randint +.. autofunction:: mkl_random.interfaces.numpy_random.random_integers +.. autofunction:: mkl_random.interfaces.numpy_random.random_sample +.. autofunction:: mkl_random.interfaces.numpy_random.random +.. autofunction:: mkl_random.interfaces.numpy_random.ranf +.. autofunction:: mkl_random.interfaces.numpy_random.choice +.. autofunction:: mkl_random.interfaces.numpy_random.bytes +.. autofunction:: mkl_random.interfaces.numpy_random.sample **Permutations:** -.. autosummary:: - - mkl_random.interfaces.numpy_random.shuffle - mkl_random.interfaces.numpy_random.permutation +.. autofunction:: mkl_random.interfaces.numpy_random.shuffle +.. autofunction:: mkl_random.interfaces.numpy_random.permutation **Distributions:** -.. autosummary:: - - mkl_random.interfaces.numpy_random.beta - mkl_random.interfaces.numpy_random.binomial - mkl_random.interfaces.numpy_random.chisquare - mkl_random.interfaces.numpy_random.dirichlet - mkl_random.interfaces.numpy_random.exponential - mkl_random.interfaces.numpy_random.f - mkl_random.interfaces.numpy_random.gamma - mkl_random.interfaces.numpy_random.geometric - mkl_random.interfaces.numpy_random.gumbel - mkl_random.interfaces.numpy_random.hypergeometric - mkl_random.interfaces.numpy_random.laplace - mkl_random.interfaces.numpy_random.logistic - mkl_random.interfaces.numpy_random.lognormal - mkl_random.interfaces.numpy_random.logseries - mkl_random.interfaces.numpy_random.multinomial - mkl_random.interfaces.numpy_random.multivariate_normal - mkl_random.interfaces.numpy_random.negative_binomial - mkl_random.interfaces.numpy_random.noncentral_chisquare - mkl_random.interfaces.numpy_random.noncentral_f - mkl_random.interfaces.numpy_random.normal - mkl_random.interfaces.numpy_random.pareto - mkl_random.interfaces.numpy_random.poisson - mkl_random.interfaces.numpy_random.power - mkl_random.interfaces.numpy_random.rayleigh - mkl_random.interfaces.numpy_random.standard_cauchy - mkl_random.interfaces.numpy_random.standard_exponential - mkl_random.interfaces.numpy_random.standard_gamma - mkl_random.interfaces.numpy_random.standard_normal - mkl_random.interfaces.numpy_random.standard_t - mkl_random.interfaces.numpy_random.triangular - mkl_random.interfaces.numpy_random.uniform - mkl_random.interfaces.numpy_random.vonmises - mkl_random.interfaces.numpy_random.wald - mkl_random.interfaces.numpy_random.weibull - mkl_random.interfaces.numpy_random.zipf +.. autofunction:: mkl_random.interfaces.numpy_random.beta +.. autofunction:: mkl_random.interfaces.numpy_random.binomial +.. autofunction:: mkl_random.interfaces.numpy_random.chisquare +.. autofunction:: mkl_random.interfaces.numpy_random.dirichlet +.. autofunction:: mkl_random.interfaces.numpy_random.exponential +.. autofunction:: mkl_random.interfaces.numpy_random.f +.. autofunction:: mkl_random.interfaces.numpy_random.gamma +.. autofunction:: mkl_random.interfaces.numpy_random.geometric +.. autofunction:: mkl_random.interfaces.numpy_random.gumbel +.. autofunction:: mkl_random.interfaces.numpy_random.hypergeometric +.. autofunction:: mkl_random.interfaces.numpy_random.laplace +.. autofunction:: mkl_random.interfaces.numpy_random.logistic +.. autofunction:: mkl_random.interfaces.numpy_random.lognormal +.. autofunction:: mkl_random.interfaces.numpy_random.logseries +.. autofunction:: mkl_random.interfaces.numpy_random.multinomial +.. autofunction:: mkl_random.interfaces.numpy_random.multivariate_normal +.. autofunction:: mkl_random.interfaces.numpy_random.negative_binomial +.. autofunction:: mkl_random.interfaces.numpy_random.noncentral_chisquare +.. autofunction:: mkl_random.interfaces.numpy_random.noncentral_f +.. autofunction:: mkl_random.interfaces.numpy_random.normal +.. autofunction:: mkl_random.interfaces.numpy_random.pareto +.. autofunction:: mkl_random.interfaces.numpy_random.poisson +.. autofunction:: mkl_random.interfaces.numpy_random.power +.. autofunction:: mkl_random.interfaces.numpy_random.rayleigh +.. autofunction:: mkl_random.interfaces.numpy_random.standard_cauchy +.. autofunction:: mkl_random.interfaces.numpy_random.standard_exponential +.. autofunction:: mkl_random.interfaces.numpy_random.standard_gamma +.. autofunction:: mkl_random.interfaces.numpy_random.standard_normal +.. autofunction:: mkl_random.interfaces.numpy_random.standard_t +.. autofunction:: mkl_random.interfaces.numpy_random.triangular +.. autofunction:: mkl_random.interfaces.numpy_random.uniform +.. autofunction:: mkl_random.interfaces.numpy_random.vonmises +.. autofunction:: mkl_random.interfaces.numpy_random.wald +.. autofunction:: mkl_random.interfaces.numpy_random.weibull +.. autofunction:: mkl_random.interfaces.numpy_random.zipf From ac526c1614977eb067dafba1a38af2d0a563bf80 Mon Sep 17 00:00:00 2001 From: Nikita Grigorian Date: Mon, 6 Apr 2026 14:45:49 -0700 Subject: [PATCH 06/16] fix indentation in numpy_random.get_state --- mkl_random/interfaces/_numpy_random.py | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/mkl_random/interfaces/_numpy_random.py b/mkl_random/interfaces/_numpy_random.py index 30fe308..dcfa7c1 100644 --- a/mkl_random/interfaces/_numpy_random.py +++ b/mkl_random/interfaces/_numpy_random.py @@ -92,16 +92,16 @@ def get_state(self, legacy=True): 2. a bytes object holding content of Intel MKL's stream for the generator. - If `legacy` is False, a dictionary containing the state information is - returned instead, with the following keys: - 1. `bit_generator`: a string specifying the basic psedo-random - number generation algorithm. It should always be `MT19937` for - this class. - 2. `state`: a dictionary guaranteed to contain the key - `mkl_stream`, whose value is a bytes object holding content of - Intel MKL's stream for the generator. - - Compare with `numpy.random.get_state`. + If `legacy` is False, a dictionary containing the state information + is returned instead, with the following keys: + 1. `bit_generator`: a string specifying the basic psedo-random + number generation algorithm. It should always be `MT19937` + for this class. + 2. `state`: a dictionary guaranteed to contain the key + `mkl_stream`, whose value is a bytes object holding content of + Intel MKL's stream for the generator. + + Compare with `numpy.random.get_state`. *Compatibility Notice* As this class uses MKL in the backend, the state format is NOT From 5aabff24f1b1e5a8cb413743391ebb759b8588ad Mon Sep 17 00:00:00 2001 From: Nikita Grigorian Date: Mon, 6 Apr 2026 15:04:54 -0700 Subject: [PATCH 07/16] change compatibility notice formatting --- mkl_random/interfaces/_numpy_random.py | 45 +++++++++++++++----------- 1 file changed, 26 insertions(+), 19 deletions(-) diff --git a/mkl_random/interfaces/_numpy_random.py b/mkl_random/interfaces/_numpy_random.py index dcfa7c1..611e95e 100644 --- a/mkl_random/interfaces/_numpy_random.py +++ b/mkl_random/interfaces/_numpy_random.py @@ -42,14 +42,17 @@ class RandomState( For full documentation refer to `numpy.random.RandomState`. - *Compatibility Notice* - While this class shares some similarities with the original `RandomState`, - it has been rewritten to use MKL's vector statistics functionality, that - provides efficient implementation of the MT19937. - As consequences: - this version is NOT seed-compatible with the original `RandomState`. - the result of `get_state` is NOT compatible with the original - `RandomState` + .. note:: + *Compatibility Notice* + + While this class shares some similarities with the original + `RandomState`, it has been rewritten to use MKL's vector statistics + functionality, that provides efficient implementation of the MT19937. + As consequences: + this version is NOT seed-compatible with the original + `RandomState`. + the result of `get_state` is NOT compatible with the original + `RandomState` References ----- @@ -103,14 +106,16 @@ def get_state(self, legacy=True): Compare with `numpy.random.get_state`. - *Compatibility Notice* - As this class uses MKL in the backend, the state format is NOT - compatible with the original `numpy.random.set_state`. The returned - state represents the MKL stream state as a bytes object, which CANNOT - be interpreted by NumPy's `RandomState`. + .. note:: + *Compatibility Notice* - The `legacy` argument is included for compatibility with the original - `RandomState`. + As this class uses MKL in the backend, the state format is NOT + compatible with the original `numpy.random.set_state`. The returned + state represents the MKL stream state as a bytes object, which + CANNOT be interpreted by NumPy's `RandomState`. + + The `legacy` argument is included for compatibility with the + original `RandomState`. """ return super().get_state(legacy=legacy) @@ -122,10 +127,12 @@ def set_state(self, state): For full documentation refer to `numpy.random.set_state`. - *Compatibility Notice* - As this class uses MKL in the backend, the state of the generator is - NOT deterministic with states returned from the original - `numpy.random.get_state`. + .. note:: + *Compatibility Notice* + + As this class uses MKL in the backend, the state of the generator + is NOT deterministic with states returned from the original + `numpy.random.get_state`. """ return super().set_state(state=state) From 98eedcc8f14b8af7ea51822445b061281a6983f5 Mon Sep 17 00:00:00 2001 From: Nikita Grigorian Date: Mon, 6 Apr 2026 15:10:00 -0700 Subject: [PATCH 08/16] update compatibility notice in MKLRandomState --- mkl_random/mklrand.pyx | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/mkl_random/mklrand.pyx b/mkl_random/mklrand.pyx index 633f853..15b41bb 100644 --- a/mkl_random/mklrand.pyx +++ b/mkl_random/mklrand.pyx @@ -6677,13 +6677,16 @@ cdef class MKLRandomState(_MKLRandomState): array filled with generated values is returned. If `size` is a tuple, then an array with that shape is filled and returned. - *Compatibility Notice* - While this class shares some similarities with the original `RandomState`, - it has been rewritten to use MKL's vector statistics functionality, that - provides efficient implementation of the MT19937 and many other basic - psuedo-random number generation algorithms as well as efficient sampling - from other common statistical distributions. As a consequence this version - is NOT seed-compatible with the original `RandomState`. + .. note:: + *Compatibility Notice* + + While this class shares some similarities with the original + `RandomState`, it has been rewritten to use MKL's vector statistics + functionality, that provides efficient implementation of the MT19937 + and many other basic psuedo-random number generation algorithms as well + as efficient sampling from other common statistical distributions. As a + consequence this version is NOT seed-compatible with the original + `RandomState`. Parameters ---------- From c157fd65cfa9cdb81507ba7657af33d8d4ed2fb5 Mon Sep 17 00:00:00 2001 From: Nikita Grigorian Date: Mon, 6 Apr 2026 15:57:02 -0700 Subject: [PATCH 09/16] add linter flag removal to conf.py docstring rendering --- docs/source/conf.py | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/source/conf.py b/docs/source/conf.py index dacc474..e2f9920 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -38,3 +38,15 @@ html_theme = "furo" html_static_path = ["_static"] + +# remove linter flags from rendered docstrings + + +def remove_linter_flags(app, what, name, obj, options, lines): + for index, line in enumerate(lines): + if "# noqa" in line or "# no-cython-lint" in line: + lines[index] = line.split("#")[0].rstrip() + + +def setup(app): + app.connect("autodoc-process-docstring", remove_linter_flags) From cc9274c82e1e7069cf3cc7d9ab8758b1408852fa Mon Sep 17 00:00:00 2001 From: Nikita Grigorian Date: Mon, 6 Apr 2026 16:02:47 -0700 Subject: [PATCH 10/16] disable blanket-noqa check in conf.py --- .pre-commit-config.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index aa67a5d..c00a0fe 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -26,6 +26,7 @@ repos: rev: v1.10.0 hooks: - id: python-check-blanket-noqa + exclude: ^docs/source/conf\.py$ - id: python-check-blanket-type-ignore - id: python-check-mock-methods - id: python-no-eval From dfc9210602655aa475f7a490a1a685563fc91a06 Mon Sep 17 00:00:00 2001 From: Nikita Grigorian Date: Mon, 6 Apr 2026 16:09:45 -0700 Subject: [PATCH 11/16] simplfiy reference guide card description --- docs/source/index.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/index.rst b/docs/source/index.rst index b8eafaf..209fdd7 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -39,8 +39,8 @@ Intel(R) oneAPI Math Kernel Library .. grid-item-card:: Reference Guide - The reference guide contains a detailed description of class :class:`mkl_random.MKLRandomState`, - the :ref:`interfaces ` submodule, and :ref:`NumPy patching ` utilities. + The reference guide contains the detailed documentation of the :mod:`mkl_random` API and its + submodules. +++ From 8e84bf9c63c5286d6f709a0df952225f09168f6e Mon Sep 17 00:00:00 2001 From: Nikita Grigorian Date: Fri, 10 Apr 2026 18:37:34 -0700 Subject: [PATCH 12/16] add current_module to properly link to functions in interfaces docs --- docs/source/reference/interfaces.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/source/reference/interfaces.rst b/docs/source/reference/interfaces.rst index fbec3ca..fe54079 100644 --- a/docs/source/reference/interfaces.rst +++ b/docs/source/reference/interfaces.rst @@ -16,6 +16,8 @@ NumPy interface --- :mod:`mkl_random.interfaces.numpy_random` :mod:`mkl_random.interfaces.numpy_random` is a drop-in replacement for the legacy portion of `numpy.random `_. +.. currentmodule:: mkl_random.interfaces.numpy_random + .. note:: While the API is the same, :mod:`mkl_random.interfaces.numpy_random` is **not** seed-compatible with `numpy.random `_. Given the same seed, the two modules From 0524b2668a8cc4b3b5a39eabc6e1626ee2baa94b Mon Sep 17 00:00:00 2001 From: Nikita Grigorian Date: Fri, 10 Apr 2026 18:40:28 -0700 Subject: [PATCH 13/16] do not attempt to list in RandomState docstring --- mkl_random/interfaces/_numpy_random.py | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/mkl_random/interfaces/_numpy_random.py b/mkl_random/interfaces/_numpy_random.py index 611e95e..ee6edef 100644 --- a/mkl_random/interfaces/_numpy_random.py +++ b/mkl_random/interfaces/_numpy_random.py @@ -45,14 +45,12 @@ class RandomState( .. note:: *Compatibility Notice* - While this class shares some similarities with the original - `RandomState`, it has been rewritten to use MKL's vector statistics - functionality, that provides efficient implementation of the MT19937. - As consequences: - this version is NOT seed-compatible with the original - `RandomState`. - the result of `get_state` is NOT compatible with the original - `RandomState` + While this class shares its API with the original `RandomState`, it has + been rewritten to use MKL's vector statistics functionality, that + provides efficient implementation of the MT19937. + As a consequence, this version is NOT seed-compatible with the original + `RandomState` and the result of `get_state` is NOT compatible with the + original `RandomState` References ----- From 42f9b707edccbf4090a0aed4fb3b9130cb977ff9 Mon Sep 17 00:00:00 2001 From: Nikita Grigorian Date: Fri, 10 Apr 2026 18:47:58 -0700 Subject: [PATCH 14/16] fix indentation in get_state --- mkl_random/interfaces/_numpy_random.py | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/mkl_random/interfaces/_numpy_random.py b/mkl_random/interfaces/_numpy_random.py index ee6edef..ef51c17 100644 --- a/mkl_random/interfaces/_numpy_random.py +++ b/mkl_random/interfaces/_numpy_random.py @@ -95,12 +95,13 @@ def get_state(self, legacy=True): If `legacy` is False, a dictionary containing the state information is returned instead, with the following keys: - 1. `bit_generator`: a string specifying the basic psedo-random - number generation algorithm. It should always be `MT19937` - for this class. - 2. `state`: a dictionary guaranteed to contain the key - `mkl_stream`, whose value is a bytes object holding content of - Intel MKL's stream for the generator. + + 1. `bit_generator`: a string specifying the basic psedo-random + number generation algorithm. It should always be `MT19937` + for this class. + 2. `state`: a dictionary guaranteed to contain the key + `mkl_stream`, whose value is a bytes object holding content of + Intel MKL's stream for the generator. Compare with `numpy.random.get_state`. From f98e9d5bc55a5ed895a6bb63844c5c35e882de9e Mon Sep 17 00:00:00 2001 From: Nikita Grigorian Date: Fri, 10 Apr 2026 18:59:38 -0700 Subject: [PATCH 15/16] remove uses of .. note:: in docs for now --- mkl_random/interfaces/_numpy_random.py | 42 ++++++++++++-------------- mkl_random/mklrand.pyx | 23 ++++++-------- 2 files changed, 29 insertions(+), 36 deletions(-) diff --git a/mkl_random/interfaces/_numpy_random.py b/mkl_random/interfaces/_numpy_random.py index ef51c17..a695702 100644 --- a/mkl_random/interfaces/_numpy_random.py +++ b/mkl_random/interfaces/_numpy_random.py @@ -42,15 +42,14 @@ class RandomState( For full documentation refer to `numpy.random.RandomState`. - .. note:: - *Compatibility Notice* - - While this class shares its API with the original `RandomState`, it has - been rewritten to use MKL's vector statistics functionality, that - provides efficient implementation of the MT19937. - As a consequence, this version is NOT seed-compatible with the original - `RandomState` and the result of `get_state` is NOT compatible with the - original `RandomState` + Notes + ----- + While this class shares its API with the original `RandomState`, it has + been rewritten to use MKL's vector statistics functionality, that + provides efficient implementation of the MT19937. + As a consequence, this version is NOT seed-compatible with the original + `RandomState` and the result of `get_state` is NOT compatible with the + original `RandomState` References ----- @@ -88,7 +87,7 @@ def get_state(self, legacy=True): out : {tuple(str, bytes), dict} The returned tuple has the following items: - 1. a string specifying the basic psedo-random number generation + 1. a string specifying the basic pseudo-random number generation algorithm. It should always be `MT19937` for this class. 2. a bytes object holding content of Intel MKL's stream for the generator. @@ -96,23 +95,21 @@ def get_state(self, legacy=True): If `legacy` is False, a dictionary containing the state information is returned instead, with the following keys: - 1. `bit_generator`: a string specifying the basic psedo-random + 1. `bit_generator`: a string specifying the basic pseudo-random number generation algorithm. It should always be `MT19937` for this class. 2. `state`: a dictionary guaranteed to contain the key - `mkl_stream`, whose value is a bytes object holding content of - Intel MKL's stream for the generator. + `mkl_stream`, whose value is a bytes object holding content of + Intel MKL's stream for the generator. Compare with `numpy.random.get_state`. - .. note:: - *Compatibility Notice* - + Notes + ----- As this class uses MKL in the backend, the state format is NOT compatible with the original `numpy.random.set_state`. The returned state represents the MKL stream state as a bytes object, which CANNOT be interpreted by NumPy's `RandomState`. - The `legacy` argument is included for compatibility with the original `RandomState`. """ @@ -126,12 +123,11 @@ def set_state(self, state): For full documentation refer to `numpy.random.set_state`. - .. note:: - *Compatibility Notice* - - As this class uses MKL in the backend, the state of the generator - is NOT deterministic with states returned from the original - `numpy.random.get_state`. + Notes + ----- + As this class uses MKL in the backend, the state of the generator + is NOT deterministic with states returned from the original + `numpy.random.get_state`. """ return super().set_state(state=state) diff --git a/mkl_random/mklrand.pyx b/mkl_random/mklrand.pyx index 15b41bb..c1ebb05 100644 --- a/mkl_random/mklrand.pyx +++ b/mkl_random/mklrand.pyx @@ -1655,7 +1655,7 @@ cdef class _MKLRandomState: out : {tuple(str, bytes), dict} The returned tuple has the following items: - 1. a string specifying the basic psedo-random number generation + 1. a string specifying the basic pseudo-random number generation algorithm. 2. a bytes object holding content of Intel MKL's stream for the given BRNG. @@ -1711,7 +1711,7 @@ cdef class _MKLRandomState: state : {tuple(str, bytes), dict} The `state` tuple has the following items: - 1. a string specifying the basic psedo-random number generation + 1. a string specifying the basic pseudo-random number generation algorithm. 2. a bytes object holding content of Intel MKL's stream for the given BRNG. @@ -6677,17 +6677,6 @@ cdef class MKLRandomState(_MKLRandomState): array filled with generated values is returned. If `size` is a tuple, then an array with that shape is filled and returned. - .. note:: - *Compatibility Notice* - - While this class shares some similarities with the original - `RandomState`, it has been rewritten to use MKL's vector statistics - functionality, that provides efficient implementation of the MT19937 - and many other basic psuedo-random number generation algorithms as well - as efficient sampling from other common statistical distributions. As a - consequence this version is NOT seed-compatible with the original - `RandomState`. - Parameters ---------- seed : {None, int, array_like}, optional @@ -6711,6 +6700,14 @@ cdef class MKLRandomState(_MKLRandomState): NumPy-aware, has the advantage that it provides a much larger number of probability distributions to choose from. + While this class shares some similarities with the original + `RandomState`, it has been rewritten to use MKL's vector statistics + functionality, that provides efficient implementation of the MT19937 + and many other basic psuedo-random number generation algorithms as well + as efficient sampling from other common statistical distributions. As a + consequence this version is NOT seed-compatible with the original + `RandomState`. + References ----- MKL Documentation: https://www.intel.com/content/www/us/en/developer/tools/oneapi/onemkl.html # no-cython-lint From 0c4d814a832c426e4bc2335efdb3a427c14007c9 Mon Sep 17 00:00:00 2001 From: Nikita Grigorian Date: Fri, 10 Apr 2026 19:23:59 -0700 Subject: [PATCH 16/16] fix get_state docstrings --- mkl_random/interfaces/_numpy_random.py | 14 +++++++------- mkl_random/mklrand.pyx | 4 ++-- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/mkl_random/interfaces/_numpy_random.py b/mkl_random/interfaces/_numpy_random.py index a695702..63e8e3c 100644 --- a/mkl_random/interfaces/_numpy_random.py +++ b/mkl_random/interfaces/_numpy_random.py @@ -84,7 +84,7 @@ def get_state(self, legacy=True): Returns ------- - out : {tuple(str, bytes), dict} + out : tuple[str, bytes] or dict The returned tuple has the following items: 1. a string specifying the basic pseudo-random number generation @@ -95,12 +95,12 @@ def get_state(self, legacy=True): If `legacy` is False, a dictionary containing the state information is returned instead, with the following keys: - 1. `bit_generator`: a string specifying the basic pseudo-random - number generation algorithm. It should always be `MT19937` - for this class. - 2. `state`: a dictionary guaranteed to contain the key - `mkl_stream`, whose value is a bytes object holding content of - Intel MKL's stream for the generator. + * "bit_generator" - a string specifying the basic pseudo-random + number generation algorithm. It should always be `MT19937` + for this class. + * "state" - a dictionary guaranteed to contain the key + "mkl_stream", whose value is a bytes object holding content of + Intel MKL's stream for the generator. Compare with `numpy.random.get_state`. diff --git a/mkl_random/mklrand.pyx b/mkl_random/mklrand.pyx index c1ebb05..e538ac1 100644 --- a/mkl_random/mklrand.pyx +++ b/mkl_random/mklrand.pyx @@ -1652,7 +1652,7 @@ cdef class _MKLRandomState: Returns ------- - out : {tuple(str, bytes), dict} + out : tuple[str, bytes] or dict The returned tuple has the following items: 1. a string specifying the basic pseudo-random number generation @@ -1708,7 +1708,7 @@ cdef class _MKLRandomState: Parameters ---------- - state : {tuple(str, bytes), dict} + state : tuple[str, bytes] or dict The `state` tuple has the following items: 1. a string specifying the basic pseudo-random number generation