Add documentation for patching utilities and interfaces

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 <interfaces>` submodule, and :ref:`NumPy patching <patching>` utilities.
 
         +++
 

docs/source/reference/api.rst

@@ -1,7 +1,15 @@
 .. _fullapi:
 
+Class MKLRandomState
+====================
+
+.. autoclass:: mkl_random.MKLRandomState
+    :members:
+    :inherited-members:
+
 Class RandomState
 =================
 
 .. autoclass:: mkl_random.RandomState
     :members:
+    :inherited-members:

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 <oneMKLBRNG_>`_):
 
@@ -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 <numpy_random_interface>` - a drop-in replacement for the legacy :mod:`numpy.random` module
+
+
+Patching
+--------
+
+:mod:`mkl_random` can :ref:`patch numpy.random <patching>` so that existing code calling :mod:`numpy.random`
+functions can use :mod:`mkl_random` implementations.
+
 .. toctree::
     :hidden:
 
     api
+    interfaces
+    patching
     mt19937
     sfmt19937
     r250

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

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 <numpy_random_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.