From 0df625b06efd134848f8f981d14cf685368bd6dc Mon Sep 17 00:00:00 2001 From: Nikita Grigorian Date: Thu, 19 Mar 2026 18:36:48 -0700 Subject: [PATCH 1/3] 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 b56e5f5a770f070397aedb743e08eeb1783d002b Mon Sep 17 00:00:00 2001 From: Nikita Grigorian Date: Thu, 19 Mar 2026 18:36:54 -0700 Subject: [PATCH 2/3] 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 fe7b7a2d2f2de3d0cd1115dbbd12a754a8293e02 Mon Sep 17 00:00:00 2001 From: Nikita Grigorian Date: Thu, 19 Mar 2026 18:43:40 -0700 Subject: [PATCH 3/3] 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