From 89119ef5de110bcbca23b48c14234875b0fc19e7 Mon Sep 17 00:00:00 2001 From: Vladislav Perevezentsev Date: Wed, 26 Aug 2026 04:26:22 -0700 Subject: [PATCH 01/10] Align distribution docstrings with NumPy --- mkl_random/mklrand.pyx | 154 +++++++++++++++++++++++++---------------- 1 file changed, 94 insertions(+), 60 deletions(-) diff --git a/mkl_random/mklrand.pyx b/mkl_random/mklrand.pyx index edbcd400..023526aa 100644 --- a/mkl_random/mklrand.pyx +++ b/mkl_random/mklrand.pyx @@ -2458,10 +2458,10 @@ cdef class _MKLRandomState: Parameters ---------- - low : float, optional + low : float or array_like of floats, optional Lower boundary of the output interval. All values generated will be greater than or equal to low. The default value is 0. - high : float + high : float or array_like of floats Upper boundary of the output interval. All values generated will be less than high. The default value is 1.0. size : int or tuple of ints, optional @@ -2827,10 +2827,11 @@ cdef class _MKLRandomState: Parameters ---------- - loc : float + loc : float or array_like of floats Mean ("centre") of the distribution. - scale : float + scale : float or array_like of floats Standard deviation (spread or "width") of the distribution. + Must be non-negative. size : int or tuple of ints, optional Output shape. If the given shape is, e.g., ``(m, n, k)``, then ``m * n * k`` samples are drawn. Default is None, in which case a @@ -2839,6 +2840,11 @@ cdef class _MKLRandomState: Sampling method used by Intel MKL. Can also be specified using tokens mkl_random.ICDF, mkl_random.BOXMULLER, mkl_random.BOXMULLER2 + Returns + ------- + out : ndarray or scalar + Drawn samples from the parameterized normal distribution. + See Also -------- scipy.stats.distributions.norm : probability density function, @@ -2996,9 +3002,9 @@ cdef class _MKLRandomState: Parameters ---------- - a : float + a : float or array_like of floats Alpha, non-negative. - b : float + b : float or array_like of floats Beta, non-negative. size : int or tuple of ints, optional Output shape. If the given shape is, e.g., ``(m, n, k)``, then @@ -3066,13 +3072,19 @@ cdef class _MKLRandomState: Parameters ---------- - scale : float + scale : float or array_like of floats The scale parameter, :math:`\\beta = 1/\\lambda`. + Must be non-negative. size : int or tuple of ints, optional Output shape. If the given shape is, e.g., ``(m, n, k)``, then ``m * n * k`` samples are drawn. Default is None, in which case a single value is returned. + Returns + ------- + out : ndarray or scalar + Drawn samples from the parameterized exponential distribution. + References ---------- .. [1] Peyton Z. Peebles Jr., "Probability, Random Variables and @@ -3199,7 +3211,7 @@ cdef class _MKLRandomState: Parameters ---------- - shape : float + shape : float or array_like of floats Parameter, should be > 0. size : int or tuple of ints, optional Output shape. If the given shape is, e.g., ``(m, n, k)``, then @@ -3297,10 +3309,12 @@ cdef class _MKLRandomState: Parameters ---------- - shape : scalar > 0 + shape : float or array_like of floats The shape of the gamma distribution. - scale : scalar > 0, optional - The scale of the gamma distribution. Default is equal to 1. + Must be non-negative. + scale : float or array_like of floats, optional + The scale of the gamma distribution. Must be non-negative. + Default is equal to 1. size : int or tuple of ints, optional Output shape. If the given shape is, e.g., ``(m, n, k)``, then ``m * n * k`` samples are drawn. Default is None, in which case a @@ -3409,9 +3423,9 @@ cdef class _MKLRandomState: Parameters ---------- - dfnum : float + dfnum : float or array_like of floats Degrees of freedom in numerator. Should be greater than zero. - dfden : float + dfden : float or array_like of floats Degrees of freedom in denominator. Should be greater than zero. size : int or tuple of ints, optional Output shape. If the given shape is, e.g., ``(m, n, k)``, then @@ -3516,11 +3530,11 @@ cdef class _MKLRandomState: Parameters ---------- - dfnum : int + dfnum : float or array_like of floats Parameter, should be > 1. - dfden : int + dfden : float or array_like of floats Parameter, should be > 1. - nonc : float + nonc : float or array_like of floats Parameter, should be >= 0. size : int or tuple of ints, optional Output shape. If the given shape is, e.g., ``(m, n, k)``, then @@ -3636,8 +3650,8 @@ cdef class _MKLRandomState: Parameters ---------- - df : int - Number of degrees of freedom. + df : float or array_like of floats + Number of degrees of freedom, must be > 0. size : int or tuple of ints, optional Output shape. If the given shape is, e.g., ``(m, n, k)``, then ``m * n * k`` samples are drawn. Default is None, in which case a @@ -3719,16 +3733,22 @@ cdef class _MKLRandomState: Parameters ---------- - df : int + df : float or array_like of floats Degrees of freedom, should be > 0 as of Numpy 1.10, should be > 1 for earlier versions. - nonc : float + nonc : float or array_like of floats Non-centrality, should be non-negative. size : int or tuple of ints, optional Output shape. If the given shape is, e.g., ``(m, n, k)``, then ``m * n * k`` samples are drawn. Default is None, in which case a single value is returned. + Returns + ------- + out : ndarray or scalar + Drawn samples from the parameterized noncentral + chi-square distribution. + Notes ----- The probability density function for the noncentral Chi-square @@ -3903,7 +3923,7 @@ cdef class _MKLRandomState: Parameters ---------- - df : int + df : float or array_like of floats Degrees of freedom, should be > 0. size : int or tuple of ints, optional Output shape. If the given shape is, e.g., ``(m, n, k)``, then @@ -4017,9 +4037,9 @@ cdef class _MKLRandomState: Parameters ---------- - mu : float + mu : float or array_like of floats Mode ("center") of the distribution. - kappa : float + kappa : float or array_like of floats Dispersion of the distribution, has to be >=0. size : int or tuple of ints, optional Output shape. If the given shape is, e.g., ``(m, n, k)``, then @@ -4135,13 +4155,18 @@ cdef class _MKLRandomState: Parameters ---------- - shape : float, > 0. - Shape of the distribution. + a : float or array_like of floats + Shape of the distribution. Must be positive. size : int or tuple of ints, optional Output shape. If the given shape is, e.g., ``(m, n, k)``, then ``m * n * k`` samples are drawn. Default is None, in which case a single value is returned. + Returns + ------- + out : ndarray or scalar + Drawn samples from the parameterized Pareto distribution. + See Also -------- scipy.stats.distributions.lomax.pdf : probability density function, @@ -4236,8 +4261,8 @@ cdef class _MKLRandomState: Parameters ---------- - a : float - Shape of the distribution. + a : float or array_like of floats + Shape parameter of the distribution. Must be nonnegative. size : int or tuple of ints, optional Output shape. If the given shape is, e.g., ``(m, n, k)``, then ``m * n * k`` samples are drawn. Default is None, in which case a @@ -4342,7 +4367,7 @@ cdef class _MKLRandomState: Parameters ---------- - a : float + a : float or array_like of floats parameter, > 0 size : int or tuple of ints, optional Output shape. If the given shape is, e.g., ``(m, n, k)``, then @@ -4461,10 +4486,12 @@ cdef class _MKLRandomState: Parameters ---------- - loc : float, optional + loc : float or array_like of floats, optional The position, :math:`\\mu`, of the distribution peak. - scale : float, optional + Default is 0. + scale : float or array_like of floats, optional :math:`\\lambda`, the exponential decay. + Default is 1. Must be non-negative. size : int or tuple of ints, optional Output shape. If the given shape is, e.g., ``(m, n, k)``, then ``m * n * k`` samples are drawn. Default is None, in which case a @@ -4566,10 +4593,11 @@ cdef class _MKLRandomState: Parameters ---------- - loc : float - The location of the mode of the distribution. - scale : float - The scale parameter of the distribution. + loc : float or array_like of floats, optional + The location of the mode of the distribution. Default is 0. + scale : float or array_like of floats, optional + The scale parameter of the distribution. Default is 1. + Must be non-negative. size : int or tuple of ints, optional Output shape. If the given shape is, e.g., ``(m, n, k)``, then ``m * n * k`` samples are drawn. Default is None, in which case a @@ -4705,10 +4733,11 @@ cdef class _MKLRandomState: Parameters ---------- - loc : float - - scale : float > 0. - + loc : float or array_like of floats, optional + Parameter of the distribution. Default is 0. + scale : float or array_like of floats, optional + Parameter of the distribution. Must be non-negative. + Default is 1. size : int or tuple of ints, optional Output shape. If the given shape is, e.g., ``(m, n, k)``, then ``m * n * k`` samples are drawn. Default is None, in which case a @@ -4813,10 +4842,11 @@ cdef class _MKLRandomState: Parameters ---------- - mean : float - Mean value of the underlying normal distribution - sigma : float, > 0. - Standard deviation of the underlying normal distribution + mean : float or array_like of floats, optional + Mean value of the underlying normal distribution. Default is 0. + sigma : float or array_like of floats, optional + Standard deviation of the underlying normal distribution. + Must be non-negative. Default is 1. size : int or tuple of ints, optional Output shape. If the given shape is, e.g., ``(m, n, k)``, then ``m * n * k`` samples are drawn. Default is None, in which case a @@ -4981,13 +5011,18 @@ cdef class _MKLRandomState: Parameters ---------- - scale : scalar + scale : float or array_like of floats, optional Scale, also equals the mode. Should be >= 0. size : int or tuple of ints, optional Output shape. If the given shape is, e.g., ``(m, n, k)``, then ``m * n * k`` samples are drawn. Default is None, in which case a single value is returned. + Returns + ------- + out : ndarray or scalar + Drawn samples from the parameterized Rayleigh distribution. + Notes ----- The probability density function for the Rayleigh distribution is @@ -5066,9 +5101,9 @@ cdef class _MKLRandomState: Parameters ---------- - mean : scalar + mean : float or array_like of floats Distribution mean, should be > 0. - scale : scalar + scale : float or array_like of floats Scale parameter, should be >= 0. size : int or tuple of ints, optional Output shape. If the given shape is, e.g., ``(m, n, k)``, then @@ -5159,12 +5194,12 @@ cdef class _MKLRandomState: Parameters ---------- - left : scalar + left : float or array_like of floats Lower limit. - mode : scalar + mode : float or array_like of floats The value where the peak of the distribution occurs. The value should fulfill the condition ``left <= mode <= right``. - right : scalar + right : float or array_like of floats Upper limit, should be larger than `left`. size : int or tuple of ints, optional Output shape. If the given shape is, e.g., ``(m, n, k)``, then @@ -5276,9 +5311,9 @@ cdef class _MKLRandomState: Parameters ---------- - n : float (but truncated to an integer) + n : int or array_like of ints parameter, >= 0. - p : float + p : float or array_like of floats parameter, >= 0 and <=1. size : int or tuple of ints, optional Output shape. If the given shape is, e.g., ``(m, n, k)``, then @@ -5405,9 +5440,9 @@ cdef class _MKLRandomState: Parameters ---------- - n : int + n : float or array_like of floats Parameter, > 0. - p : float + p : float or array_like of floats Parameter, >= 0 and <=1. size : int or tuple of ints, optional Output shape. If the given shape is, e.g., ``(m, n, k)``, then @@ -5515,7 +5550,7 @@ cdef class _MKLRandomState: Parameters ---------- - lam : float or sequence of float + lam : float or array_like of floats Expectation of interval, should be >= 0. A sequence of expectation intervals must be broadcastable over the requested size. size : int or tuple of ints, optional @@ -5647,8 +5682,8 @@ cdef class _MKLRandomState: Parameters ---------- - a : float > 1 - Distribution parameter. + a : float or array_like of floats + Distribution parameter. Must be greater than 1. size : int or tuple of ints, optional Output shape. If the given shape is, e.g., ``(m, n, k)``, then ``m * n * k`` samples are drawn. Default is None, in which case a @@ -5745,7 +5780,7 @@ cdef class _MKLRandomState: Parameters ---------- - p : float + p : float or array_like of floats The probability of success of an individual trial. size : int or tuple of ints, optional Output shape. If the given shape is, e.g., ``(m, n, k)``, then @@ -5969,10 +6004,9 @@ cdef class _MKLRandomState: Parameters ---------- - loc : float - - scale : float > 0. - + p : float or array_like of floats + Shape parameter for the distribution. Must be in the range + (0, 1). size : int or tuple of ints, optional Output shape. If the given shape is, e.g., ``(m, n, k)``, then ``m * n * k`` samples are drawn. Default is None, in which case a From 835107151ac77fca7087b655edf629fa3fa01942 Mon Sep 17 00:00:00 2001 From: Vladislav Perevezentsev Date: Wed, 26 Aug 2026 05:13:17 -0700 Subject: [PATCH 02/10] Render distribution methods under MKLRandomState in API reference --- docs/source/reference/api.rst | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/docs/source/reference/api.rst b/docs/source/reference/api.rst index cf2f0841..faf72625 100644 --- a/docs/source/reference/api.rst +++ b/docs/source/reference/api.rst @@ -1,7 +1,16 @@ .. _fullapi: -Class RandomState -================= +MKL-powered RandomState +======================= -.. autoclass:: mkl_random.RandomState +.. autoclass:: mkl_random.MKLRandomState :members: + :inherited-members: + +.. note:: + + ``mkl_random.RandomState`` is a deprecated alias of + :class:`mkl_random.MKLRandomState`, kept for backward compatibility with + legacy code. A NumPy-compatible drop-in replacement for + :class:`numpy.random.RandomState` is available in + :mod:`mkl_random.interfaces.numpy_random`. From 310392a0a59fd411e3ae663c09caf8af1b4a246d Mon Sep 17 00:00:00 2001 From: Vladislav Perevezentsev Date: Wed, 26 Aug 2026 07:09:25 -0700 Subject: [PATCH 03/10] Use numpydoc to render the API reference --- .github/workflows/build-docs.yml | 2 +- .gitignore | 3 + docs/source/_static/mkl_random-custom.css | 45 +++++++++++ docs/source/conf.py | 10 ++- docs/source/reference/api.rst | 98 ++++++++++++++++++++++- 5 files changed, 153 insertions(+), 5 deletions(-) create mode 100644 docs/source/_static/mkl_random-custom.css diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml index a1e8e0c2..6598b955 100644 --- a/.github/workflows/build-docs.yml +++ b/.github/workflows/build-docs.yml @@ -44,7 +44,7 @@ jobs: if: ${{ !github.event.pull_request || github.event.action != 'closed' }} shell: bash -l {0} run: | - pip install meson-python ninja cython cmake numpy sphinx sphinx_rtd_theme furo pydot graphviz sphinxcontrib-programoutput sphinxcontrib-googleanalytics sphinx_design + pip install meson-python ninja cython cmake numpy sphinx sphinx_rtd_theme furo pydot graphviz sphinxcontrib-programoutput sphinxcontrib-googleanalytics sphinx_design numpydoc - name: Checkout repo uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: diff --git a/.gitignore b/.gitignore index d16f217a..ab5d4ebd 100644 --- a/.gitignore +++ b/.gitignore @@ -3,5 +3,8 @@ build/ .mesonpy-* mkl_random.egg-info/ +# Sphinx autosummary generated stub pages +docs/source/reference/generated/ + # Byte-compiled / optimized / DLL files __pycache__/ diff --git a/docs/source/_static/mkl_random-custom.css b/docs/source/_static/mkl_random-custom.css new file mode 100644 index 00000000..602578f8 --- /dev/null +++ b/docs/source/_static/mkl_random-custom.css @@ -0,0 +1,45 @@ +/* mkl_random docs: small Furo overrides for a NumPy-like API look. */ + +/* Keep autosummary tables left-aligned (Furo centres wide ones). */ +.longtable.docutils { + margin-left: 0; + margin-right: auto; +} + +/* Restore body font size in notes (Furo shrinks admonitions). */ +div.admonition { + font-size: inherit !important; +} + +/* Emphasise section headings (Furo renders them small/uppercase, unbold). */ +dd p.rubric, +dl.field-list > dt, +.admonition > .admonition-title { + text-transform: none !important; + font-size: inherit !important; + font-weight: 700 !important; + background-color: var(--color-background-secondary); + padding: 4px 8px; +} + +/* Bold the signature name and parameter names (Furo only colours them). */ +dt.sig.sig-object, +dt.sig.sig-object * { + font-weight: 400 !important; +} +dt.sig.sig-object .sig-name, +dt.sig.sig-object .sig-name *, +dt.sig.sig-object .sig-param > .n, +dt.sig.sig-object .sig-param > .n * { + font-weight: 700 !important; +} + +/* Full grid, roomier padding, zebra rows (Furo borders are faint). */ +body table.docutils td, +body table.docutils th { + border: 1px solid var(--color-foreground-border) !important; + padding: 8px 12px; +} +body table.docutils tbody tr.row-odd { + background-color: var(--color-background-secondary) !important; +} diff --git a/docs/source/conf.py b/docs/source/conf.py index ac55bf4e..0badc7de 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -21,7 +21,7 @@ "sphinx.ext.extlinks", "sphinx.ext.intersphinx", "sphinx.ext.githubpages", - "sphinx.ext.napoleon", + "numpydoc", "sphinx.ext.todo", "sphinx.ext.viewcode", "sphinxcontrib.programoutput", @@ -32,9 +32,17 @@ templates_path = ["_templates"] exclude_patterns = [] +# Generate per-method stub pages for autosummary ":toctree:" tables. +autosummary_generate = True + +# Let api.rst list class members via autosummary +# (avoid numpydoc duplicating them). +numpydoc_show_class_members = False + # -- Options for HTML output ------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output html_theme = "furo" html_static_path = ["_static"] +html_css_files = ["mkl_random-custom.css"] diff --git a/docs/source/reference/api.rst b/docs/source/reference/api.rst index faf72625..225e4cd5 100644 --- a/docs/source/reference/api.rst +++ b/docs/source/reference/api.rst @@ -3,9 +3,9 @@ MKL-powered RandomState ======================= -.. autoclass:: mkl_random.MKLRandomState - :members: - :inherited-members: +.. currentmodule:: mkl_random + +.. autoclass:: MKLRandomState .. note:: @@ -14,3 +14,95 @@ MKL-powered RandomState legacy code. A NumPy-compatible drop-in replacement for :class:`numpy.random.RandomState` is available in :mod:`mkl_random.interfaces.numpy_random`. + +Seeding and state +----------------- + +.. autosummary:: + :toctree: generated/ + :nosignatures: + + ~MKLRandomState.seed + ~MKLRandomState.get_state + ~MKLRandomState.set_state + +Simple random data +------------------ + +.. autosummary:: + :toctree: generated/ + :nosignatures: + + ~MKLRandomState.rand + ~MKLRandomState.randn + ~MKLRandomState.randint + ~MKLRandomState.random_integers + ~MKLRandomState.random_sample + ~MKLRandomState.tomaxint + ~MKLRandomState.choice + ~MKLRandomState.bytes + +Permutations +------------ + +.. autosummary:: + :toctree: generated/ + :nosignatures: + + ~MKLRandomState.shuffle + ~MKLRandomState.permutation + +Distributions +------------- + +.. autosummary:: + :toctree: generated/ + :nosignatures: + + ~MKLRandomState.beta + ~MKLRandomState.binomial + ~MKLRandomState.chisquare + ~MKLRandomState.dirichlet + ~MKLRandomState.exponential + ~MKLRandomState.f + ~MKLRandomState.gamma + ~MKLRandomState.geometric + ~MKLRandomState.gumbel + ~MKLRandomState.hypergeometric + ~MKLRandomState.laplace + ~MKLRandomState.logistic + ~MKLRandomState.lognormal + ~MKLRandomState.logseries + ~MKLRandomState.multinomial + ~MKLRandomState.multivariate_normal + ~MKLRandomState.negative_binomial + ~MKLRandomState.noncentral_chisquare + ~MKLRandomState.noncentral_f + ~MKLRandomState.normal + ~MKLRandomState.pareto + ~MKLRandomState.poisson + ~MKLRandomState.power + ~MKLRandomState.rayleigh + ~MKLRandomState.standard_cauchy + ~MKLRandomState.standard_exponential + ~MKLRandomState.standard_gamma + ~MKLRandomState.standard_normal + ~MKLRandomState.standard_t + ~MKLRandomState.triangular + ~MKLRandomState.uniform + ~MKLRandomState.vonmises + ~MKLRandomState.wald + ~MKLRandomState.weibull + ~MKLRandomState.zipf + +MKL-specific methods +-------------------- + +.. autosummary:: + :toctree: generated/ + :nosignatures: + + ~MKLRandomState.leapfrog + ~MKLRandomState.skipahead + ~MKLRandomState.randint_untyped + ~MKLRandomState.multinormal_cholesky From 2d65eb8c8c5899930297bc7ae660a26c328bd70e Mon Sep 17 00:00:00 2001 From: Vladislav Perevezentsev Date: Wed, 26 Aug 2026 07:54:24 -0700 Subject: [PATCH 04/10] Fix distribution docstring rendering under numpydoc --- docs/source/conf.py | 6 +++ mkl_random/mklrand.pyx | 96 +++++++++++++++++++++--------------------- 2 files changed, 53 insertions(+), 49 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 0badc7de..7384ae1f 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -39,6 +39,12 @@ # (avoid numpydoc duplicating them). numpydoc_show_class_members = False +# Shared external link, referenced as `MKL Documentation`_ from docstrings. +rst_epilog = """ +.. _MKL Documentation: + https://www.intel.com/content/www/us/en/developer/tools/oneapi/onemkl.html +""" + # -- Options for HTML output ------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output diff --git a/mkl_random/mklrand.pyx b/mkl_random/mklrand.pyx index 023526aa..dde09ed1 100644 --- a/mkl_random/mklrand.pyx +++ b/mkl_random/mklrand.pyx @@ -1622,21 +1622,21 @@ cdef class _MKLRandomState: seed : int or array_like, optional Seed for `MKLRandomState`. Must be convertible to 32 bit unsigned integers. - brng : {'MT19937', 'SFMT19937', 'MT2203', 'R250', 'WH', 'MCG31', - 'MCG59', 'MRG32K3A', 'PHILOX4X32X10', 'NONDETERM', - 'ARS5', None}, optional - basic pseudo-random number generation algorithms, or - non-deterministic hardware-based generator, provided by Intel MKL. - Use `brng==None` to keep the `brng` specified during construction - of this class instance. + brng : str or None, optional + Name of the basic random number generation algorithm, or a + non-deterministic hardware-based generator, provided by Intel + MKL. One of 'MT19937', 'SFMT19937', 'MT2203', 'R250', 'WH', + 'MCG31', 'MCG59', 'MRG32K3A', 'PHILOX4X32X10', 'NONDETERM', + 'ARS5'. Use ``brng=None`` to keep the algorithm specified when + this instance was constructed. See Also -------- MKLRandomState References - -------- - MKL Documentation: https://www.intel.com/content/www/us/en/developer/tools/oneapi/onemkl.html # no-cython-lint + ---------- + `MKL Documentation`_ """ self._seed_impl(seed, brng) @@ -1656,13 +1656,13 @@ 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 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. + 2. a bytes object holding the content of Intel MKL's stream for + the given BRNG. See Also -------- @@ -1675,8 +1675,8 @@ cdef class _MKLRandomState: altered, the user should know exactly what he/she is doing. References - ----- - MKL Documentation: https://www.intel.com/content/www/us/en/developer/tools/oneapi/onemkl.html # no-cython-lint + ---------- + `MKL Documentation`_ """ cdef int state_buffer_size @@ -1712,13 +1712,13 @@ cdef class _MKLRandomState: Parameters ---------- - state : {tuple(str, bytes), dict} - The `state` tuple has the following items: + state : tuple(str, bytes) or 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. + 2. a bytes object holding the content of Intel MKL's stream for + the given BRNG. Returns ------- @@ -1742,7 +1742,7 @@ cdef class _MKLRandomState: References ---------- - MKL Documentation: https://www.intel.com/content/www/us/en/developer/tools/oneapi/onemkl.html # no-cython-lint + `MKL Documentation`_ """ cdef char *bytes_ptr @@ -2253,7 +2253,7 @@ cdef class _MKLRandomState: .. versionadded:: 1.7.0 Parameters - ----------- + ---------- a : 1-D array-like or int If an ndarray, a random sample is generated from its elements. If an int, the random sample is generated as if a was np.arange(n) @@ -2269,12 +2269,12 @@ cdef class _MKLRandomState: entries in a. Returns - -------- + ------- samples : 1-D ndarray, shape (size,) The generated random samples Raises - ------- + ------ ValueError If a is an int and less than zero, if a or p are not 1-dimensional, if a is an array-like of size 0, if p is not a vector of @@ -2283,11 +2283,11 @@ cdef class _MKLRandomState: size See Also - --------- + -------- randint, shuffle, permutation Examples - --------- + -------- Generate a uniform random sample from np.arange(5) of size 3: >>> mkl_random.choice(5, 3) @@ -2565,7 +2565,7 @@ cdef class _MKLRandomState: Parameters ---------- d0, d1, ..., dn : int, optional - The dimensions of the returned array, should all be positive. + The dimensions of the returned array, must be non-negative. If no argument is given a single Python float is returned. Returns @@ -2575,7 +2575,7 @@ cdef class _MKLRandomState: See Also -------- - random + random_sample Notes ----- @@ -2616,7 +2616,7 @@ cdef class _MKLRandomState: Parameters ---------- d0, d1, ..., dn : int, optional - The dimensions of the returned array, should be all positive. + The dimensions of the returned array, must be non-negative. If no argument is given a single Python float is returned. Returns @@ -2628,7 +2628,7 @@ cdef class _MKLRandomState: See Also -------- - random.standard_normal : Similar, but takes a tuple as its argument. + standard_normal : Similar, but takes a tuple as its argument. Notes ----- @@ -6131,10 +6131,9 @@ cdef class _MKLRandomState: ------- out : ndarray The drawn samples, of shape *size*, if that was provided. If not, - the shape is ``(N,)``. - - In other words, each entry ``out[i,j,...,:]`` is an N-dimensional - value drawn from the distribution. + the shape is ``(N,)``. In other words, each entry + ``out[i,j,...,:]`` is an N-dimensional value drawn from the + distribution. Notes ----- @@ -6298,10 +6297,9 @@ cdef class _MKLRandomState: ------- out : ndarray The drawn samples, of shape *size*, if that was provided. If not, - the shape is ``(N,)``. - - In other words, each entry ``out[i,j,...,:]`` is an N-dimensional - value drawn from the distribution. + the shape is ``(N,)``. In other words, each entry + ``out[i,j,...,:]`` is an N-dimensional value drawn from the + distribution. Examples -------- @@ -6732,11 +6730,12 @@ cdef class MKLRandomState(_MKLRandomState): If `seed` is ``None``, then `RandomState` will try to read data from ``/dev/urandom`` (or the Windows analogue) if available or seed from the clock otherwise. - brng : {'MT19937', 'SFMT19937', 'MT2203', 'R250', 'WH', 'MCG31', 'MCG59', - 'MRG32K3A', 'PHILOX4X32X10', 'NONDETERM', 'ARS5'}, optional - basic pseudo-random number generation algorithms, or non-deterministic - hardware-based generator, provided by Intel MKL. The default choice is - 'MT19937' - the Mersenne Twister generator. + brng : str, optional + Name of the basic random number generation algorithm, or a + non-deterministic hardware-based generator, provided by Intel MKL. + One of 'MT19937', 'SFMT19937', 'MT2203', 'R250', 'WH', 'MCG31', + 'MCG59', 'MRG32K3A', 'PHILOX4X32X10', 'NONDETERM', 'ARS5'. The + default is 'MT19937', the Mersenne Twister generator. Notes ----- @@ -6747,8 +6746,8 @@ cdef class MKLRandomState(_MKLRandomState): of probability distributions to choose from. References - ----- - MKL Documentation: https://www.intel.com/content/www/us/en/developer/tools/oneapi/onemkl.html # no-cython-lint + ---------- + `MKL Documentation`_ """ @@ -6937,10 +6936,9 @@ cdef class MKLRandomState(_MKLRandomState): ------- out : ndarray The drawn samples, of shape *size*, if that was provided. If not, - the shape is ``(N,)``. - - In other words, each entry ``out[i,j,...,:]`` is an N-dimensional - value drawn from the distribution. + the shape is ``(N,)``. In other words, each entry + ``out[i,j,...,:]`` is an N-dimensional value drawn from the + distribution. Notes ----- From 110bf7231e2878c9d07ac1354d353eaa8b3e1905 Mon Sep 17 00:00:00 2001 From: Vladislav Perevezentsev Date: Wed, 26 Aug 2026 11:17:51 -0700 Subject: [PATCH 05/10] Add gh-165 to changelog --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index eff67b71..4b10d069 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added ### Changed +* Documented `MKLRandomState` and its methods in the API reference, aligning the docstrings with NumPy [gh-165](https://github.com/IntelPython/mkl_random/pull/165) ### Fixed From 52ea3c9918222cd3078bfa6366f42713520bac3d Mon Sep 17 00:00:00 2001 From: Vladislav Perevezentsev Date: Thu, 27 Aug 2026 02:27:12 -0700 Subject: [PATCH 06/10] Temporary publish rendered docs to this PR --- .github/workflows/build-docs.yml | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml index 6598b955..88fb313a 100644 --- a/.github/workflows/build-docs.yml +++ b/.github/workflows/build-docs.yml @@ -68,6 +68,37 @@ jobs: with: name: ${{ env.PACKAGE_NAME }} rendered documentation path: ~/rendered_docs + # TEMPORARY: publish this PR's docs to gh-pages and comment the link. + # Remove after review. + - name: Publish pull-request docs + if: ${{ github.event.pull_request && github.event.action != 'closed' }} + env: + PR_NUM: ${{ github.event.number }} + shell: bash -l {0} + run: | + git remote add tokened_docs https://IntelPython:${{ secrets.GITHUB_TOKEN }}@github.com/IntelPython/mkl_random.git + git fetch tokened_docs + git checkout --track tokened_docs/gh-pages + [ -d "pull/${PR_NUM}" ] && git rm -rf "pull/${PR_NUM}" + mkdir -p "pull/${PR_NUM}" + cd "pull/${PR_NUM}" + mv ~/rendered_docs/* . + git add . + git config --global user.name 'github-actions[doc-deploy-bot]' + git config --global user.email 'github-actions[doc-deploy-bot]@users.noreply.github.com' + git commit -m "Docs for pull request ${PR_NUM}" + git push tokened_docs gh-pages + - name: Comment with URL to published pull-request docs + if: ${{ github.event.pull_request && github.event.action != 'closed' }} + env: + PR_NUM: ${{ github.event.number }} + uses: mshick/add-pr-comment@ec328af66588ab8f77cdeb2c264f14aba45bbf59 # v2 + with: + message-id: url_to_docs + allow-repeats: false + message: | + View rendered docs @ https://intelpython.github.io/mkl_random/pull/${{ env.PR_NUM }}/index.html + repo-token: ${{ secrets.GITHUB_TOKEN }} - name: Configure git if: ${{ !github.event.pull_request && github.event.action != 'closed'}} run: | From cb0fdec218ebbd834c1be5f78813dfa32ab67dc6 Mon Sep 17 00:00:00 2001 From: Vladislav Perevezentsev Date: Wed, 14 Oct 2026 06:25:58 -0700 Subject: [PATCH 07/10] Fix MKLRandomState docstrings that disagree with the code --- mkl_random/mklrand.pyx | 126 ++++++++++++++++++++++++++++------------- 1 file changed, 87 insertions(+), 39 deletions(-) diff --git a/mkl_random/mklrand.pyx b/mkl_random/mklrand.pyx index 6e6e1439..94de2e4c 100644 --- a/mkl_random/mklrand.pyx +++ b/mkl_random/mklrand.pyx @@ -1857,12 +1857,14 @@ cdef class _MKLRandomState: seed : int or array_like, optional Seed for `MKLRandomState`. Must be convertible to 32 bit unsigned integers. - brng : str or None, optional + brng : str or tuple of (str, int), optional Name of the basic random number generation algorithm, or a non-deterministic hardware-based generator, provided by Intel MKL. One of 'MT19937', 'SFMT19937', 'MT2203', 'R250', 'WH', 'MCG31', 'MCG59', 'MRG32K3A', 'PHILOX4X32X10', 'NONDETERM', - 'ARS5'. Use ``brng=None`` to keep the algorithm specified when + 'ARS5' (case-insensitive). For the 'MT2203' and 'WH' families, + a ``(name, set_id)`` pair selects a member of the family. Use + ``brng=None``, the default, to keep the algorithm specified when this instance was constructed. See Also @@ -2562,7 +2564,7 @@ cdef class _MKLRandomState: See Also -------- - random.random_integers : similar to `randint`, only for the closed + random_integers : similar to `randint`, only for the closed interval [`low`, `high`], and 1 is the lowest value if `high` is omitted. In particular, this other one is the one to use to generate uniformly distributed discrete non-integers. @@ -2686,16 +2688,16 @@ cdef class _MKLRandomState: Parameters ---------- - a : 1-D array-like or int + a : 1-D array_like or int If an ndarray, a random sample is generated from its elements. If an int, the random sample is generated as if a was np.arange(n) size : int or tuple of ints, optional Output shape. If the given shape is, e.g., ``(m, n, k)``, then ``m * n * k`` samples are drawn. Default is None, in which case a single value is returned. - replace : boolean, optional + replace : bool, optional Whether the sample is with or without replacement - p : 1-D array-like, optional + p : 1-D array_like, optional The probabilities associated with each entry in a. If not given the sample assumes a uniform distribution over all entries in a. @@ -3106,13 +3108,15 @@ cdef class _MKLRandomState: Parameters ---------- - low : int + low : int or array_like of ints Lowest (signed) integer to be drawn from the distribution (unless ``high=None``, in which case this parameter is the *highest* such - integer). - high : int, optional + integer). If an array is given, it must broadcast with `high` (and + with `size`, if provided). + high : int or array_like of ints, optional If provided, the largest (signed) integer to be drawn from the distribution (see above for behavior if ``high=None``). + If an array is given, it must broadcast with `low`. size : int or tuple of ints, optional Output shape. If the given shape is, e.g., ``(m, n, k)``, then ``m * n * k`` samples are drawn. Default is None, in which case a @@ -3126,7 +3130,7 @@ cdef class _MKLRandomState: See Also -------- - random.randint : Similar to `random_integers`, only for the half-open + randint : Similar to `random_integers`, only for the half-open interval [`low`, `high`), and 0 is the lowest value if `high` is omitted. @@ -3197,9 +3201,11 @@ cdef class _MKLRandomState: Output shape. If the given shape is, e.g., ``(m, n, k)``, then ``m * n * k`` samples are drawn. Default is None, in which case a single value is returned. - method : 'ICDF, 'BoxMuller', 'BoxMuller2', optional + method : {'ICDF', 'BoxMuller', 'BoxMuller2'}, optional Sampling method used by Intel MKL. Can also be specified using - tokens mkl_random.ICDF, mkl_random.BOXMULLER, mkl_random.BOXMULLER2 + the tokens ``mkl_random.mklrand.ICDF``, + ``mkl_random.mklrand.BOXMULLER``, + ``mkl_random.mklrand.BOXMULLER2``. Returns ------- @@ -3271,9 +3277,11 @@ cdef class _MKLRandomState: Output shape. If the given shape is, e.g., ``(m, n, k)``, then ``m * n * k`` samples are drawn. Default is None, in which case a single value is returned. - method : 'ICDF, 'BoxMuller', 'BoxMuller2', optional + method : {'ICDF', 'BoxMuller', 'BoxMuller2'}, optional Sampling method used by Intel MKL. Can also be specified using - tokens mkl_random.ICDF, mkl_random.BOXMULLER, mkl_random.BOXMULLER2 + the tokens ``mkl_random.mklrand.ICDF``, + ``mkl_random.mklrand.BOXMULLER``, + ``mkl_random.mklrand.BOXMULLER2``. Returns ------- @@ -5288,9 +5296,10 @@ cdef class _MKLRandomState: Output shape. If the given shape is, e.g., ``(m, n, k)``, then ``m * n * k`` samples are drawn. Default is None, in which case a single value is returned. - method : 'ICDF, 'BoxMuller', optional + method : {'ICDF', 'BoxMuller'}, optional Sampling method used by Intel MKL. Can also be specified using - tokens mkl_random.ICDF, mkl_random.BOXMULLER + the tokens ``mkl_random.mklrand.ICDF``, + ``mkl_random.mklrand.BOXMULLER``. Returns ------- @@ -5994,9 +6003,10 @@ cdef class _MKLRandomState: Output shape. If the given shape is, e.g., ``(m, n, k)``, then ``m * n * k`` samples are drawn. Default is None, in which case a single value is returned. - method : 'POISNORM, 'PTPE', optional + method : {'POISNORM', 'PTPE'}, optional Sampling method used by Intel MKL. Can also be specified using - tokens mkl_random.POISNORM, mkl_random.PTPE + the tokens ``mkl_random.mklrand.POISNORM``, + ``mkl_random.mklrand.PTPE``. Returns ------- @@ -6282,11 +6292,11 @@ cdef class _MKLRandomState: Parameters ---------- - ngood : int or array_like + ngood : int or array_like of ints Number of ways to make a good selection. Must be nonnegative. - nbad : int or array_like + nbad : int or array_like of ints Number of ways to make a bad selection. Must be nonnegative. - nsample : int or array_like + nsample : int or array_like of ints Number of items sampled. Must be at least 1 and at most ``ngood + nbad``. size : int or tuple of ints, optional @@ -6701,7 +6711,7 @@ cdef class _MKLRandomState: def multinomial(self, int n, object pvals, size=None): """ - multinomial(n, pvals, size=None, method='ICDF') + multinomial(n, pvals, size=None) Draw samples from a multinomial distribution. @@ -6726,9 +6736,6 @@ cdef class _MKLRandomState: Output shape. If the given shape is, e.g., ``(m, n, k)``, then ``m * n * k`` samples are drawn. Default is None, in which case a single value is returned. - method : 'ICDF, 'BoxMuller', 'BoxMuller2', optional - Sampling method used by Intel MKL. Can also be specified using - tokens mkl_random.ICDF, mkl_random.BOXMULLER, mkl_random.BOXMULLER2 Returns ------- @@ -6842,8 +6849,8 @@ cdef class _MKLRandomState: Parameters ---------- - alpha : array - Parameter of the distribution (k dimension for sample of + alpha : sequence of floats, length k + Parameter of the distribution (length k for sample of dimension k). size : int or tuple of ints, optional Output shape. If the given shape is, e.g., ``(m, n, k)``, then @@ -6852,8 +6859,8 @@ cdef class _MKLRandomState: Returns ------- - samples : ndarray, - The drawn samples, of shape (size, alpha.ndim). + samples : ndarray + The drawn samples, of shape ``(size, k)``. Notes ----- @@ -7169,24 +7176,26 @@ cdef class MKLRandomState(_MKLRandomState): 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 + pseudo-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 + seed : int or array_like, optional Random seed initializing the pseudo-random number generator. Can be an integer, an array (or other sequence) of integers of any length, or ``None`` (the default). - If `seed` is ``None``, then `RandomState` will try to read data from - ``/dev/urandom`` (or the Windows analogue) if available or seed from - the clock otherwise. - brng : str, optional + If `seed` is ``None``, then `MKLRandomState` will try to read data + from ``/dev/urandom`` (or the Windows analogue) if available or seed + from the clock otherwise. + brng : str or tuple of (str, int), optional Name of the basic random number generation algorithm, or a non-deterministic hardware-based generator, provided by Intel MKL. One of 'MT19937', 'SFMT19937', 'MT2203', 'R250', 'WH', 'MCG31', - 'MCG59', 'MRG32K3A', 'PHILOX4X32X10', 'NONDETERM', 'ARS5'. The + 'MCG59', 'MRG32K3A', 'PHILOX4X32X10', 'NONDETERM', 'ARS5' + (case-insensitive). For the 'MT2203' and 'WH' families, a + ``(name, set_id)`` pair selects a member of the family. The default is 'MT19937', the Mersenne Twister generator. Notes @@ -7214,6 +7223,26 @@ cdef class MKLRandomState(_MKLRandomState): Initializes the current state generator using leap-frog method, if supported for the basic random pseudo-random number generation algorithm. + + Parameters + ---------- + k : int + Index of the sub-stream to generate, should be + ``0 <= k < nstreams``. + nstreams : int + Number of sub-streams the original stream is split into, + should be positive. + + Raises + ------ + ValueError + If leap-frog is not supported for the current `brng`, or if + oneMKL rejects `k` and `nstreams`. + + See Also + -------- + skipahead + """ cdef int err, brng_id @@ -7236,6 +7265,23 @@ cdef class MKLRandomState(_MKLRandomState): Initializes the current state generator using skip-ahead method, if supported for the basic random pseudo-random number generation algorithm. + + Parameters + ---------- + nskips : int + Number of elements to skip in the stream, should be + non-negative. + + Raises + ------ + ValueError + If skip-ahead is not supported for the current `brng`, or if + oneMKL rejects `nskips`. + + See Also + -------- + leapfrog + """ cdef int err, brng_id @@ -7317,7 +7363,7 @@ cdef class MKLRandomState(_MKLRandomState): def multinormal_cholesky(self, mean, ch, size=None, method=ICDF): """ - multivariate_normal(mean, ch, size=None, method='ICDF') + multinormal_cholesky(mean, ch, size=None, method='ICDF') Draw random samples from a multivariate normal distribution. @@ -7341,9 +7387,11 @@ cdef class MKLRandomState(_MKLRandomState): generated, and packed in an `m`-by-`n`-by-`k` arrangement. Because each sample is `N`-dimensional, the output shape is ``(m,n,k,N)``. If no shape is specified, a single (`N`-D) sample is returned. - method : 'ICDF, 'BoxMuller', 'BoxMuller2', optional + method : {'ICDF', 'BoxMuller', 'BoxMuller2'}, optional Sampling method used by Intel MKL. Can also be specified using - tokens mkl_random.ICDF, mkl_random.BOXMULLER, mkl_random.BOXMULLER2 + the tokens ``mkl_random.mklrand.ICDF``, + ``mkl_random.mklrand.BOXMULLER``, + ``mkl_random.mklrand.BOXMULLER2``. Returns ------- From 6c447916ea64c8faa284345ac8dfa1b4c64127fa Mon Sep 17 00:00:00 2001 From: Vladislav Perevezentsev Date: Wed, 14 Oct 2026 06:43:57 -0700 Subject: [PATCH 08/10] Resolve Python, numpy and scipy cross-references in docstrings --- docs/source/conf.py | 7 +++++++ docs/source/tutorials.rst | 2 +- mkl_random/mklrand.pyx | 30 +++++++++++++++--------------- 3 files changed, 23 insertions(+), 16 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 7384ae1f..6f7cfb2c 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -39,6 +39,13 @@ # (avoid numpydoc duplicating them). numpydoc_show_class_members = False +# Resolve cross-references to Python, NumPy and SciPy in docstrings and guides. +intersphinx_mapping = { + "python": ("https://docs.python.org/3/", None), + "numpy": ("https://numpy.org/doc/stable/", None), + "scipy": ("https://docs.scipy.org/doc/scipy/", None), +} + # Shared external link, referenced as `MKL Documentation`_ from docstrings. rst_epilog = """ .. _MKL Documentation: diff --git a/docs/source/tutorials.rst b/docs/source/tutorials.rst index 40d3d21e..99508278 100644 --- a/docs/source/tutorials.rst +++ b/docs/source/tutorials.rst @@ -39,7 +39,7 @@ 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 +The :mod:`mkl_random` package has followed the design of :mod:`numpy.random` package to make :mod:`mkl_random` easy to use for those already familiar with the :mod:`numpy.random` module. .. note:: diff --git a/mkl_random/mklrand.pyx b/mkl_random/mklrand.pyx index 94de2e4c..ccc898e6 100644 --- a/mkl_random/mklrand.pyx +++ b/mkl_random/mklrand.pyx @@ -3290,7 +3290,7 @@ cdef class _MKLRandomState: See Also -------- - scipy.stats.distributions.norm : probability density function, + scipy.stats.norm : probability density function, distribution or cumulative density function, etc. Notes @@ -3668,7 +3668,7 @@ cdef class _MKLRandomState: See Also -------- - scipy.stats.distributions.gamma : probability density function, + scipy.stats.gamma : probability density function, distribution or cumulative density function, etc. Notes @@ -3770,7 +3770,7 @@ cdef class _MKLRandomState: See Also -------- - scipy.stats.distributions.gamma : probability density function, + scipy.stats.gamma : probability density function, distribution or cumulative density function, etc. Notes @@ -3882,7 +3882,7 @@ cdef class _MKLRandomState: See Also -------- - scipy.stats.distributions.f : probability density function, + scipy.stats.f : probability density function, distribution or cumulative density function, etc. Notes @@ -4496,7 +4496,7 @@ cdef class _MKLRandomState: See Also -------- - scipy.stats.distributions.vonmises : probability density function, + scipy.stats.vonmises : probability density function, distribution, or cumulative density function, etc. Notes @@ -4612,9 +4612,9 @@ cdef class _MKLRandomState: See Also -------- - scipy.stats.distributions.lomax.pdf : probability density function, + scipy.stats.lomax : probability density function, distribution or cumulative density function, etc. - scipy.stats.distributions.genpareto.pdf : probability density function, + scipy.stats.genpareto : probability density function, distribution or cumulative density function, etc. Notes @@ -4717,9 +4717,9 @@ cdef class _MKLRandomState: See Also -------- - scipy.stats.distributions.weibull_max - scipy.stats.distributions.weibull_min - scipy.stats.distributions.genextreme + scipy.stats.weibull_max + scipy.stats.weibull_min + scipy.stats.genextreme gumbel Notes @@ -5195,7 +5195,7 @@ cdef class _MKLRandomState: See Also -------- - scipy.stats.distributions.logistic : probability density function, + scipy.stats.logistic : probability density function, distribution or cumulative density function, etc. Notes @@ -5773,7 +5773,7 @@ cdef class _MKLRandomState: See Also -------- - scipy.stats.distributions.binom : probability density function, + scipy.stats.binom : probability density function, distribution or cumulative density function, etc. Notes @@ -6143,7 +6143,7 @@ cdef class _MKLRandomState: See Also -------- - scipy.stats.distributions.zipf : probability density function, + scipy.stats.zipf : probability density function, distribution, or cumulative density function, etc. Notes @@ -6311,7 +6311,7 @@ cdef class _MKLRandomState: See Also -------- - scipy.stats.distributions.hypergeom : probability density function, + scipy.stats.hypergeom : probability density function, distribution or cumulative density function, etc. Notes @@ -6466,7 +6466,7 @@ cdef class _MKLRandomState: See Also -------- - scipy.stats.distributions.logser : probability density function, + scipy.stats.logser : probability density function, distribution or cumulative density function, etc. Notes From 87147f6250713aa3eec09481f072e33d0c1ca4d5 Mon Sep 17 00:00:00 2001 From: Vladislav Perevezentsev Date: Wed, 14 Oct 2026 06:47:28 -0700 Subject: [PATCH 09/10] Describe RandomState as a deprecated subclass --- docs/source/conf.py | 3 +-- docs/source/reference/api.rst | 2 +- 2 files changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 6f7cfb2c..b376b3a9 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -39,9 +39,8 @@ # (avoid numpydoc duplicating them). numpydoc_show_class_members = False -# Resolve cross-references to Python, NumPy and SciPy in docstrings and guides. +# Resolve `numpy`/`scipy` cross-references in docstrings and guides. intersphinx_mapping = { - "python": ("https://docs.python.org/3/", None), "numpy": ("https://numpy.org/doc/stable/", None), "scipy": ("https://docs.scipy.org/doc/scipy/", None), } diff --git a/docs/source/reference/api.rst b/docs/source/reference/api.rst index 225e4cd5..2a8b3ae4 100644 --- a/docs/source/reference/api.rst +++ b/docs/source/reference/api.rst @@ -9,7 +9,7 @@ MKL-powered RandomState .. note:: - ``mkl_random.RandomState`` is a deprecated alias of + ``mkl_random.RandomState`` is a deprecated subclass of :class:`mkl_random.MKLRandomState`, kept for backward compatibility with legacy code. A NumPy-compatible drop-in replacement for :class:`numpy.random.RandomState` is available in From 8efaff4671b4e2baa30bcd718fb210f493e9577f Mon Sep 17 00:00:00 2001 From: Vladislav Perevezentsev Date: Fri, 16 Oct 2026 03:59:55 -0700 Subject: [PATCH 10/10] Require positive scale parameters and use the exported method tokens --- mkl_random/mklrand.pyx | 47 +++++++++++++++++++----------------------- 1 file changed, 21 insertions(+), 26 deletions(-) diff --git a/mkl_random/mklrand.pyx b/mkl_random/mklrand.pyx index f8915715..10417974 100644 --- a/mkl_random/mklrand.pyx +++ b/mkl_random/mklrand.pyx @@ -3236,9 +3236,8 @@ cdef class _MKLRandomState: single value is returned. method : {'ICDF', 'BoxMuller', 'BoxMuller2'}, optional Sampling method used by Intel MKL. Can also be specified using - the tokens ``mkl_random.mklrand.ICDF``, - ``mkl_random.mklrand.BOXMULLER``, - ``mkl_random.mklrand.BOXMULLER2``. + the tokens ``mkl_random.ICDF``, ``mkl_random.BOXMULLER``, + ``mkl_random.BOXMULLER2``. Returns ------- @@ -3305,16 +3304,15 @@ cdef class _MKLRandomState: Mean ("centre") of the distribution. scale : float or array_like of floats Standard deviation (spread or "width") of the distribution. - Must be non-negative. + Must be positive. size : int or tuple of ints, optional Output shape. If the given shape is, e.g., ``(m, n, k)``, then ``m * n * k`` samples are drawn. Default is None, in which case a single value is returned. method : {'ICDF', 'BoxMuller', 'BoxMuller2'}, optional Sampling method used by Intel MKL. Can also be specified using - the tokens ``mkl_random.mklrand.ICDF``, - ``mkl_random.mklrand.BOXMULLER``, - ``mkl_random.mklrand.BOXMULLER2``. + the tokens ``mkl_random.ICDF``, ``mkl_random.BOXMULLER``, + ``mkl_random.BOXMULLER2``. Returns ------- @@ -3479,9 +3477,9 @@ cdef class _MKLRandomState: Parameters ---------- a : float or array_like of floats - Alpha, non-negative. + Alpha, must be positive. b : float or array_like of floats - Beta, non-negative. + Beta, must be positive. size : int or tuple of ints, optional Output shape. If the given shape is, e.g., ``(m, n, k)``, then ``m * n * k`` samples are drawn. Default is None, in which case a @@ -3550,7 +3548,7 @@ cdef class _MKLRandomState: ---------- scale : float or array_like of floats The scale parameter, :math:`\\beta = 1/\\lambda`. - Must be non-negative. + Must be positive. size : int or tuple of ints, optional Output shape. If the given shape is, e.g., ``(m, n, k)``, then ``m * n * k`` samples are drawn. Default is None, in which case a @@ -3787,9 +3785,9 @@ cdef class _MKLRandomState: ---------- shape : float or array_like of floats The shape of the gamma distribution. - Must be non-negative. + Must be positive. scale : float or array_like of floats, optional - The scale of the gamma distribution. Must be non-negative. + The scale of the gamma distribution. Must be positive. Default is equal to 1. size : int or tuple of ints, optional Output shape. If the given shape is, e.g., ``(m, n, k)``, then @@ -4738,7 +4736,7 @@ cdef class _MKLRandomState: Parameters ---------- a : float or array_like of floats - Shape parameter of the distribution. Must be nonnegative. + Shape parameter of the distribution. Must be positive. size : int or tuple of ints, optional Output shape. If the given shape is, e.g., ``(m, n, k)``, then ``m * n * k`` samples are drawn. Default is None, in which case a @@ -4967,7 +4965,7 @@ cdef class _MKLRandomState: Default is 0. scale : float or array_like of floats, optional :math:`\\lambda`, the exponential decay. - Default is 1. Must be non-negative. + Default is 1. Must be positive. size : int or tuple of ints, optional Output shape. If the given shape is, e.g., ``(m, n, k)``, then ``m * n * k`` samples are drawn. Default is None, in which case a @@ -5074,7 +5072,7 @@ cdef class _MKLRandomState: The location of the mode of the distribution. Default is 0. scale : float or array_like of floats, optional The scale parameter of the distribution. Default is 1. - Must be non-negative. + Must be positive. size : int or tuple of ints, optional Output shape. If the given shape is, e.g., ``(m, n, k)``, then ``m * n * k`` samples are drawn. Default is None, in which case a @@ -5214,7 +5212,7 @@ cdef class _MKLRandomState: loc : float or array_like of floats, optional Parameter of the distribution. Default is 0. scale : float or array_like of floats, optional - Parameter of the distribution. Must be non-negative. + Parameter of the distribution. Must be positive. Default is 1. size : int or tuple of ints, optional Output shape. If the given shape is, e.g., ``(m, n, k)``, then @@ -5324,15 +5322,14 @@ cdef class _MKLRandomState: Mean value of the underlying normal distribution. Default is 0. sigma : float or array_like of floats, optional Standard deviation of the underlying normal distribution. - Must be non-negative. Default is 1. + Must be positive. Default is 1. size : int or tuple of ints, optional Output shape. If the given shape is, e.g., ``(m, n, k)``, then ``m * n * k`` samples are drawn. Default is None, in which case a single value is returned. method : {'ICDF', 'BoxMuller'}, optional Sampling method used by Intel MKL. Can also be specified using - the tokens ``mkl_random.mklrand.ICDF``, - ``mkl_random.mklrand.BOXMULLER``. + the tokens ``mkl_random.ICDF``, ``mkl_random.BOXMULLER``. Returns ------- @@ -5491,7 +5488,7 @@ cdef class _MKLRandomState: Parameters ---------- scale : float or array_like of floats, optional - Scale, also equals the mode. Should be >= 0. + Scale, also equals the mode. Must be positive. size : int or tuple of ints, optional Output shape. If the given shape is, e.g., ``(m, n, k)``, then ``m * n * k`` samples are drawn. Default is None, in which case a @@ -5583,7 +5580,7 @@ cdef class _MKLRandomState: mean : float or array_like of floats Distribution mean, should be > 0. scale : float or array_like of floats - Scale parameter, should be >= 0. + Scale parameter, must be positive. size : int or tuple of ints, optional Output shape. If the given shape is, e.g., ``(m, n, k)``, then ``m * n * k`` samples are drawn. Default is None, in which case a @@ -6038,8 +6035,7 @@ cdef class _MKLRandomState: single value is returned. method : {'POISNORM', 'PTPE'}, optional Sampling method used by Intel MKL. Can also be specified using - the tokens ``mkl_random.mklrand.POISNORM``, - ``mkl_random.mklrand.PTPE``. + the tokens ``mkl_random.POISNORM``, ``mkl_random.PTPE``. Returns ------- @@ -7422,9 +7418,8 @@ cdef class MKLRandomState(_MKLRandomState): If no shape is specified, a single (`N`-D) sample is returned. method : {'ICDF', 'BoxMuller', 'BoxMuller2'}, optional Sampling method used by Intel MKL. Can also be specified using - the tokens ``mkl_random.mklrand.ICDF``, - ``mkl_random.mklrand.BOXMULLER``, - ``mkl_random.mklrand.BOXMULLER2``. + the tokens ``mkl_random.ICDF``, ``mkl_random.BOXMULLER``, + ``mkl_random.BOXMULLER2``. Returns -------