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..4bb2af0 100644 --- a/docs/source/reference/api.rst +++ b/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: 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 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.