add documentation for patching utilities and interfaces

Author: ndgrigorian

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

@@ -5,3 +5,9 @@ Class RandomState
 
 .. autoclass:: mkl_random.RandomState
     :members:
+
+Class MKLRandomState
+====================
+
+.. autoclass:: mkl_random.MKLRandomState
+    :members:

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.