Skip to content

Commit 06d3b6d

Browse files
oleksandr-pavlykoleksandr-pavlyk
committed
Add initial version of documentation
1 parent 0ac1d09 commit 06d3b6d

File tree

20 files changed

+698
-0
lines changed

20 files changed

+698
-0
lines changed

‎docs/Makefile‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line, and also
5+
# from the environment for the first two.
6+
SPHINXOPTS ?=
7+
SPHINXBUILD ?= sphinx-build
8+
SOURCEDIR = source
9+
BUILDDIR = build
10+
11+
# Put it first so that "make" without argument is like "make help".
12+
help:
13+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
14+
15+
.PHONY: help Makefile
16+
17+
# Catch-all target: route all unknown targets to Sphinx using the new
18+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
19+
%: Makefile
20+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎docs/make.bat‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
@ECHO OFF
2+
3+
pushd %~dp0
4+
5+
REM Command file for Sphinx documentation
6+
7+
if "%SPHINXBUILD%" == "" (
8+
set SPHINXBUILD=sphinx-build
9+
)
10+
set SOURCEDIR=source
11+
set BUILDDIR=build
12+
13+
%SPHINXBUILD% >NUL 2>NUL
14+
if errorlevel 9009 (
15+
echo.
16+
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
17+
echo.installed, then set the SPHINXBUILD environment variable to point
18+
echo.to the full path of the 'sphinx-build' executable. Alternatively you
19+
echo.may add the Sphinx directory to PATH.
20+
echo.
21+
echo.If you don't have Sphinx installed, grab it from
22+
echo.https://www.sphinx-doc.org/
23+
exit /b 1
24+
)
25+
26+
if "%1" == "" goto help
27+
28+
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
29+
goto end
30+
31+
:help
32+
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
33+
34+
:end
35+
popd

‎docs/source/conf.py‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# Configuration file for the Sphinx documentation builder.
2+
#
3+
# For the full list of built-in configuration values, see the documentation:
4+
# https://www.sphinx-doc.org/en/master/usage/configuration.html
5+
6+
# -- Project information -----------------------------------------------------
7+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
8+
9+
project = 'mkl_random'
10+
copyright = '2017-2024, Intel Corp.'
11+
author = 'Intel Corp.'
12+
release = '1.2.5'
13+
14+
# -- General configuration ---------------------------------------------------
15+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
16+
17+
extensions = [
18+
"sphinx.ext.autodoc",
19+
"sphinx.ext.autosummary",
20+
"sphinx.ext.coverage",
21+
"sphinx.ext.extlinks",
22+
"sphinx.ext.intersphinx",
23+
"sphinx.ext.githubpages",
24+
"sphinx.ext.napoleon",
25+
"sphinx.ext.todo",
26+
"sphinx.ext.viewcode",
27+
"sphinxcontrib.programoutput",
28+
# "sphinxcontrib.googleanalytics",
29+
'sphinx_design',
30+
]
31+
32+
templates_path = ['_templates']
33+
exclude_patterns = []
34+
35+
36+
37+
# -- Options for HTML output -------------------------------------------------
38+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
39+
40+
html_theme = 'furo'
41+
html_static_path = ['_static']

‎docs/source/how_to.rst‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
How-to Guides
2+
=============
3+
4+
To be written.

‎docs/source/index.rst‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
Random sampling powered by Intel(R) Math Kernel Library
2+
=======================================================
3+
4+
:mod:`mkl_random` is Python package exposing pseudo-random and non-deterministic random
5+
number generators with continuous and discrete distribution available in
6+
Intel(R) Math Kernel Library (MKL).
7+
8+
.. grid:: 2
9+
:gutter: 3
10+
11+
.. grid-item-card:: Beginner Guides
12+
13+
New to :mod:`mkl_random`? Check out the Tutorials.
14+
They are a hands-on introduction for beginners.
15+
16+
+++
17+
18+
.. button-ref:: tutorials
19+
:expand:
20+
:color: secondary
21+
:click-parent:
22+
23+
To the beginner guides
24+
25+
.. grid-item-card:: User Guides
26+
27+
The user guides are recipes for key tasks and common problems.
28+
29+
+++
30+
31+
.. button-ref:: how_to
32+
:expand:
33+
:color: secondary
34+
:click-parent:
35+
36+
To the user guides
37+
38+
.. grid-item-card:: Reference Guide
39+
40+
The reference guide contains a detailed description of class :class:`mkl_random.RandomState` and its methods.
41+
42+
+++
43+
44+
.. button-ref:: reference/index
45+
:expand:
46+
:color: secondary
47+
:click-parent:
48+
49+
To the reference guide
50+
51+
.. grid-item-card:: Contributor Guides
52+
53+
Want to add to the codebase?
54+
The contributing guidelines will guide you through the
55+
process of improving :mod:`mkl_random`.
56+
57+
+++
58+
59+
.. button-ref:: maintenance/index
60+
:expand:
61+
:color: secondary
62+
:click-parent:
63+
64+
To the contributor guides
65+
66+
67+
.. toctree::
68+
:hidden:
69+
70+
tutorials
71+
how_to
72+
reference/index
73+
maintenance/index

‎docs/source/maintenance/index.rst‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
Contributing
2+
============
3+
4+
:mod:`mkl_random` is an free and open source project.
5+
We welcome and appreciate your contributions.
6+
7+
To contribute, fork the repo https://github.com/IntelPython/mkl_random.git,
8+
clone it:
9+
10+
.. code-block::
11+
:caption: How to clone the repo
12+
13+
git clone https://github.com/<fork-org>/mkl_random.git
14+
15+

‎docs/source/reference/api.rst‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
.. _fullapi:
2+
3+
Class RandomState
4+
=================
5+
6+
.. autoclass:: mkl_random.RandomState
7+
:members:

‎docs/source/reference/ars5.rst‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
ARS5 brng
2+
=========
3+
4+
The ARS5 counter-based pseudorandom number generator based on AES encryption algorithm can be
5+
initialized with either an integral seed, a list of integral seeds, or automatically.
6+
7+
.. code-block:: python
8+
:caption: Construction for ARS5 basic random number generator with scalar seed
9+
10+
import mkl_random
11+
rs = mkl_random.RandomState(1234, brng="ars5")
12+
13+
# Use random state instance to generate 1000 random numbers from
14+
# Uniform(0, 1) distribution
15+
esample = rs.uniform(0, 1, size=1000)
16+
17+
.. code-block:: python
18+
:caption: Construction for ARS5 basic random number generator with vector seed
19+
20+
import mkl_random
21+
rs_vec = mkl_random.RandomState([1234, 567, 89, 0], brng="ars5")
22+
23+
# Use random state instance to generate 1000 random numbers from
24+
# Gamma(3, 1) distibution
25+
gsample = rs_vec.gamma(3, 1, size=1000)
26+
27+
When seed is not specified, the generator is initialized using system clock, e.g.:
28+
29+
.. code-block:: python
30+
:caption: Construction for ARS5 basic random number generator automatic seed
31+
32+
import mkl_random
33+
rs_def = mkl_random.RandomState(brng="ars5")
34+
35+
# Use random state instance to generate 1000 random numbers
36+
# from discrete uniform distribution [1, 6]
37+
isample = rs_def.randint(1, 6 + 1, size=1000)

‎docs/source/reference/index.rst‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
:mod:`mkl_random` APIs
2+
======================
3+
4+
The class :doc:`mkl_random.RandomState <./api>` exposes sampling from probability distributions while supporting
5+
different streams of randomness, also known as basic random number generators.
6+
7+
The basic random number generator is chosen by specifying :code:`brng` keyword argument to the constructor of :code:`mkl.RandomState` class.
8+
9+
The list of supported basic random number generators is as follows (also see `oneMKL Engines <oneMKLBRNG_>`_):
10+
11+
* :code:`'MT19937'` - the Mersenne Twister pseudo-random number generator (default), :doc:`example <mt19937>`
12+
* :code:`'SFMT19937'` - the SIMD-oriented Mersenne Twister pseudo-random number generator, :doc:`example <sfmt19937>`
13+
* :code:`'MT2203'` - the set of 6024 Mersenne Twister pseudorandom number generators, :doc:`example <mt2203>`
14+
* :code:`'R250'` - the 32-bit generalized feedback shift register pseudorandom number generator GFSR(250,103), :doc:`example <r250>`
15+
* :code:`'WH'` - the set of 273 Wichmann-Hill’s combined multiplicative congruential generators, :doc:`example <wichmann_hill>`
16+
* :code:`'MCG31'` - the 31-bit multiplicative congruential pseudorandom number generator, :doc:`example <mcg31>`
17+
* :code:`'MCG59'` - the 59-bit multiplicative congruential pseudorandom number generator, :doc:`example <mcg59>`
18+
* :code:`'MRG32K3A'` - the combined multiple recursive pseudorandom number generator MRG32k3a, :doc:`example <mrg32k3a>`
19+
* :code:`'PHILOX4X32X10'` - the Philox4x32x10 counter-based pseudorandom number generator, :doc:`example <philox4x32x10>`
20+
* :code:`'NONDETERM'` - the generator with non-deterministic source of randomness (for example, a hardware device), :doc:`example <nondeterministic>`
21+
* :code:`'ARS5'` - the ARS5 counter-based pseudorandom number generator based on AES encryption algorithm, :doc:`example <ars5>`
22+
23+
.. _oneMKLBRNG: https://spec.oneapi.io/versions/1.0-rev-2/elements/oneMKL/source/domains/rng/engines-basic-random-number-generators.html
24+
25+
.. toctree::
26+
:hidden:
27+
28+
api
29+
mt19937
30+
sfmt19937
31+
r250
32+
mt2203
33+
wichmann_hill
34+
mcg31
35+
mcg59
36+
mrg32k3a
37+
philox4x32x10
38+
nondeterministic
39+
ars5

‎docs/source/reference/mcg31.rst‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
MCG31 brng
2+
==========
3+
4+
The 31-bit multiplicative congruential pseudorandom number generator MCG(1132489760, 2**31 -1) can be
5+
initialized with either an integral seed, a list of integral seeds, or automatically.
6+
7+
.. code-block:: python
8+
:caption: Construction for MCG31 basic random number generator with scalar seed
9+
10+
import mkl_random
11+
rs = mkl_random.RandomState(1234, brng="MCG31")
12+
13+
# Use random state instance to generate 1000 random numbers from
14+
# Uniform(0, 1) distribution
15+
esample = rs.uniform(0, 1, size=1000)
16+
17+
.. code-block:: python
18+
:caption: Construction for MCG31 basic random number generator with vector seed
19+
20+
import mkl_random
21+
rs_vec = mkl_random.RandomState([1234, 567, 89, 0], brng="MCG31")
22+
23+
# Use random state instance to generate 1000 random numbers from
24+
# Gamma(3, 1) distibution
25+
gsample = rs_vec.gamma(3, 1, size=1000)
26+
27+
When seed is not specified, the generator is initialized using system clock, e.g.:
28+
29+
.. code-block:: python
30+
:caption: Construction for MCG31 basic random number generator automatic seed
31+
32+
import mkl_random
33+
rs_def = mkl_random.RandomState(brng="MCG31")
34+
35+
# Use random state instance to generate 1000 random numbers
36+
# from discrete uniform distribution [1, 6]
37+
isample = rs_def.randint(1, 6 + 1, size=1000)

0 commit comments

Comments
 (0)