From eb348142ffa0dabaa2b6cb63e77b820965d121a9 Mon Sep 17 00:00:00 2001 From: Ivan Martianov Date: Tue, 5 Sep 2023 21:31:04 +0100 Subject: [PATCH] [oneMKL][RNG][Spec] Added oneMKL RNG Device APIs (#493) --- ...istributions-template-parameter-method.rst | 52 ++++ .../rng/device_api/device-distributions.rst | 92 +++++++ .../domains/rng/device_api/device-engines.rst | 42 +++ .../rng/device_api/device-rng-bernoulli.rst | 185 +++++++++++++ .../rng/device_api/device-rng-bits.rst | 61 +++++ .../rng/device_api/device-rng-exponential.rst | 207 +++++++++++++++ .../rng/device_api/device-rng-gaussian.rst | 213 +++++++++++++++ .../device-rng-generate-routines.rst | 18 ++ .../rng/device_api/device-rng-generate.rst | 52 ++++ .../rng/device_api/device-rng-lognormal.rst | 242 ++++++++++++++++++ .../rng/device_api/device-rng-mcg31m1.rst | 121 +++++++++ .../rng/device_api/device-rng-mcg59.rst | 117 +++++++++ .../rng/device_api/device-rng-mrg32k3a.rst | 213 +++++++++++++++ .../device_api/device-rng-philox4x32x10.rst | 192 ++++++++++++++ .../rng/device_api/device-rng-poisson.rst | 182 +++++++++++++ .../rng/device_api/device-rng-skip-ahead.rst | 79 ++++++ .../device_api/device-rng-uniform-bits.rst | 64 +++++ .../device-rng-uniform-continuous.rst | 208 +++++++++++++++ .../device-rng-uniform-discrete.rst | 177 +++++++++++++ .../rng/device_api/device-rng-usage-model.rst | 77 ++++++ .../rng/device_api/device-routines.rst | 62 +++++ .../device_api/device-service-routines.rst | 27 ++ ...mplate-parameter-mkl-rng-method-values.rst | 0 .../rng/{ => host_api}/distributions.rst | 12 +- ...engines-basic-random-number-generators.rst | 6 +- .../rng/{ => host_api}/generate-routine.rst | 6 +- .../rng/{ => host_api}/mkl-rng-ars5.rst | 0 .../rng/{ => host_api}/mkl-rng-bernoulli.rst | 0 .../rng/{ => host_api}/mkl-rng-beta.rst | 0 .../rng/{ => host_api}/mkl-rng-binomial.rst | 0 .../rng/{ => host_api}/mkl-rng-bits.rst | 0 .../rng/{ => host_api}/mkl-rng-cauchy.rst | 0 .../rng/{ => host_api}/mkl-rng-chi_square.rst | 0 .../{ => host_api}/mkl-rng-default_engine.rst | 0 .../{ => host_api}/mkl-rng-exponential.rst | 0 .../rng/{ => host_api}/mkl-rng-gamma.rst | 0 .../rng/{ => host_api}/mkl-rng-gaussian.rst | 0 .../{ => host_api}/mkl-rng-gaussian_mv.rst | 0 .../rng/{ => host_api}/mkl-rng-generate.rst | 0 .../rng/{ => host_api}/mkl-rng-geometric.rst | 0 .../rng/{ => host_api}/mkl-rng-gumbel.rst | 0 .../{ => host_api}/mkl-rng-hypergeometric.rst | 0 .../rng/{ => host_api}/mkl-rng-laplace.rst | 0 .../rng/{ => host_api}/mkl-rng-leapfrog.rst | 2 +- .../rng/{ => host_api}/mkl-rng-lognormal.rst | 0 .../rng/{ => host_api}/mkl-rng-mcg31m1.rst | 0 .../rng/{ => host_api}/mkl-rng-mcg59.rst | 0 .../rng/{ => host_api}/mkl-rng-mrg32k3a.rst | 6 +- .../rng/{ => host_api}/mkl-rng-mt19937.rst | 0 .../rng/{ => host_api}/mkl-rng-mt2203.rst | 0 .../{ => host_api}/mkl-rng-multinomial.rst | 0 .../{ => host_api}/mkl-rng-negbinomial.rst | 0 .../{ => host_api}/mkl-rng-niederreiter.rst | 0 .../mkl-rng-nondeterministic.rst | 0 .../{ => host_api}/mkl-rng-philox4x32x10.rst | 0 .../rng/{ => host_api}/mkl-rng-poisson.rst | 0 .../rng/{ => host_api}/mkl-rng-poisson_v.rst | 0 .../rng/{ => host_api}/mkl-rng-r250.rst | 0 .../rng/{ => host_api}/mkl-rng-rayleigh.rst | 0 .../rng/{ => host_api}/mkl-rng-sfmt19937.rst | 0 .../rng/{ => host_api}/mkl-rng-skip_ahead.rst | 4 +- .../rng/{ => host_api}/mkl-rng-sobol.rst | 0 .../mkl-rng-uniform-continuous.rst | 0 .../mkl-rng-uniform-discrete.rst | 0 .../{ => host_api}/mkl-rng-uniform_bits.rst | 0 .../rng/{ => host_api}/mkl-rng-weibull.rst | 0 .../{ => host_api}/mkl-rng-wichmann_hill.rst | 0 .../rng/host_api/onemkl-rng-usage-model.rst | 68 +++++ .../rng/host_api/rng-host-routines.rst | 48 ++++ .../rng/{ => host_api}/service-routines.rst | 6 +- .../domains/rng/onemkl-rng-overview.rst | 39 +-- .../domains/rng/onemkl-rng-usage-model.rst | 111 -------- 72 files changed, 2829 insertions(+), 162 deletions(-) create mode 100644 source/elements/oneMKL/source/domains/rng/device_api/device-distributions-template-parameter-method.rst create mode 100644 source/elements/oneMKL/source/domains/rng/device_api/device-distributions.rst create mode 100644 source/elements/oneMKL/source/domains/rng/device_api/device-engines.rst create mode 100644 source/elements/oneMKL/source/domains/rng/device_api/device-rng-bernoulli.rst create mode 100644 source/elements/oneMKL/source/domains/rng/device_api/device-rng-bits.rst create mode 100644 source/elements/oneMKL/source/domains/rng/device_api/device-rng-exponential.rst create mode 100644 source/elements/oneMKL/source/domains/rng/device_api/device-rng-gaussian.rst create mode 100644 source/elements/oneMKL/source/domains/rng/device_api/device-rng-generate-routines.rst create mode 100644 source/elements/oneMKL/source/domains/rng/device_api/device-rng-generate.rst create mode 100644 source/elements/oneMKL/source/domains/rng/device_api/device-rng-lognormal.rst create mode 100644 source/elements/oneMKL/source/domains/rng/device_api/device-rng-mcg31m1.rst create mode 100644 source/elements/oneMKL/source/domains/rng/device_api/device-rng-mcg59.rst create mode 100644 source/elements/oneMKL/source/domains/rng/device_api/device-rng-mrg32k3a.rst create mode 100644 source/elements/oneMKL/source/domains/rng/device_api/device-rng-philox4x32x10.rst create mode 100644 source/elements/oneMKL/source/domains/rng/device_api/device-rng-poisson.rst create mode 100644 source/elements/oneMKL/source/domains/rng/device_api/device-rng-skip-ahead.rst create mode 100644 source/elements/oneMKL/source/domains/rng/device_api/device-rng-uniform-bits.rst create mode 100644 source/elements/oneMKL/source/domains/rng/device_api/device-rng-uniform-continuous.rst create mode 100644 source/elements/oneMKL/source/domains/rng/device_api/device-rng-uniform-discrete.rst create mode 100644 source/elements/oneMKL/source/domains/rng/device_api/device-rng-usage-model.rst create mode 100644 source/elements/oneMKL/source/domains/rng/device_api/device-routines.rst create mode 100644 source/elements/oneMKL/source/domains/rng/device_api/device-service-routines.rst rename source/elements/oneMKL/source/domains/rng/{ => host_api}/distributions-template-parameter-mkl-rng-method-values.rst (100%) rename source/elements/oneMKL/source/domains/rng/{ => host_api}/distributions.rst (97%) rename source/elements/oneMKL/source/domains/rng/{ => host_api}/engines-basic-random-number-generators.rst (97%) rename source/elements/oneMKL/source/domains/rng/{ => host_api}/generate-routine.rst (76%) rename source/elements/oneMKL/source/domains/rng/{ => host_api}/mkl-rng-ars5.rst (100%) rename source/elements/oneMKL/source/domains/rng/{ => host_api}/mkl-rng-bernoulli.rst (100%) rename source/elements/oneMKL/source/domains/rng/{ => host_api}/mkl-rng-beta.rst (100%) rename source/elements/oneMKL/source/domains/rng/{ => host_api}/mkl-rng-binomial.rst (100%) rename source/elements/oneMKL/source/domains/rng/{ => host_api}/mkl-rng-bits.rst (100%) rename source/elements/oneMKL/source/domains/rng/{ => host_api}/mkl-rng-cauchy.rst (100%) rename source/elements/oneMKL/source/domains/rng/{ => host_api}/mkl-rng-chi_square.rst (100%) rename source/elements/oneMKL/source/domains/rng/{ => host_api}/mkl-rng-default_engine.rst (100%) rename source/elements/oneMKL/source/domains/rng/{ => host_api}/mkl-rng-exponential.rst (100%) rename source/elements/oneMKL/source/domains/rng/{ => host_api}/mkl-rng-gamma.rst (100%) rename source/elements/oneMKL/source/domains/rng/{ => host_api}/mkl-rng-gaussian.rst (100%) rename source/elements/oneMKL/source/domains/rng/{ => host_api}/mkl-rng-gaussian_mv.rst (100%) rename source/elements/oneMKL/source/domains/rng/{ => host_api}/mkl-rng-generate.rst (100%) rename source/elements/oneMKL/source/domains/rng/{ => host_api}/mkl-rng-geometric.rst (100%) rename source/elements/oneMKL/source/domains/rng/{ => host_api}/mkl-rng-gumbel.rst (100%) rename source/elements/oneMKL/source/domains/rng/{ => host_api}/mkl-rng-hypergeometric.rst (100%) rename source/elements/oneMKL/source/domains/rng/{ => host_api}/mkl-rng-laplace.rst (100%) rename source/elements/oneMKL/source/domains/rng/{ => host_api}/mkl-rng-leapfrog.rst (97%) rename source/elements/oneMKL/source/domains/rng/{ => host_api}/mkl-rng-lognormal.rst (100%) rename source/elements/oneMKL/source/domains/rng/{ => host_api}/mkl-rng-mcg31m1.rst (100%) rename source/elements/oneMKL/source/domains/rng/{ => host_api}/mkl-rng-mcg59.rst (100%) rename source/elements/oneMKL/source/domains/rng/{ => host_api}/mkl-rng-mrg32k3a.rst (96%) rename source/elements/oneMKL/source/domains/rng/{ => host_api}/mkl-rng-mt19937.rst (100%) rename source/elements/oneMKL/source/domains/rng/{ => host_api}/mkl-rng-mt2203.rst (100%) rename source/elements/oneMKL/source/domains/rng/{ => host_api}/mkl-rng-multinomial.rst (100%) rename source/elements/oneMKL/source/domains/rng/{ => host_api}/mkl-rng-negbinomial.rst (100%) rename source/elements/oneMKL/source/domains/rng/{ => host_api}/mkl-rng-niederreiter.rst (100%) rename source/elements/oneMKL/source/domains/rng/{ => host_api}/mkl-rng-nondeterministic.rst (100%) rename source/elements/oneMKL/source/domains/rng/{ => host_api}/mkl-rng-philox4x32x10.rst (100%) rename source/elements/oneMKL/source/domains/rng/{ => host_api}/mkl-rng-poisson.rst (100%) rename source/elements/oneMKL/source/domains/rng/{ => host_api}/mkl-rng-poisson_v.rst (100%) rename source/elements/oneMKL/source/domains/rng/{ => host_api}/mkl-rng-r250.rst (100%) rename source/elements/oneMKL/source/domains/rng/{ => host_api}/mkl-rng-rayleigh.rst (100%) rename source/elements/oneMKL/source/domains/rng/{ => host_api}/mkl-rng-sfmt19937.rst (100%) rename source/elements/oneMKL/source/domains/rng/{ => host_api}/mkl-rng-skip_ahead.rst (96%) rename source/elements/oneMKL/source/domains/rng/{ => host_api}/mkl-rng-sobol.rst (100%) rename source/elements/oneMKL/source/domains/rng/{ => host_api}/mkl-rng-uniform-continuous.rst (100%) rename source/elements/oneMKL/source/domains/rng/{ => host_api}/mkl-rng-uniform-discrete.rst (100%) rename source/elements/oneMKL/source/domains/rng/{ => host_api}/mkl-rng-uniform_bits.rst (100%) rename source/elements/oneMKL/source/domains/rng/{ => host_api}/mkl-rng-weibull.rst (100%) rename source/elements/oneMKL/source/domains/rng/{ => host_api}/mkl-rng-wichmann_hill.rst (100%) create mode 100644 source/elements/oneMKL/source/domains/rng/host_api/onemkl-rng-usage-model.rst create mode 100644 source/elements/oneMKL/source/domains/rng/host_api/rng-host-routines.rst rename source/elements/oneMKL/source/domains/rng/{ => host_api}/service-routines.rst (86%) delete mode 100644 source/elements/oneMKL/source/domains/rng/onemkl-rng-usage-model.rst diff --git a/source/elements/oneMKL/source/domains/rng/device_api/device-distributions-template-parameter-method.rst b/source/elements/oneMKL/source/domains/rng/device_api/device-distributions-template-parameter-method.rst new file mode 100644 index 0000000000..20f93b2992 --- /dev/null +++ b/source/elements/oneMKL/source/domains/rng/device_api/device-distributions-template-parameter-method.rst @@ -0,0 +1,52 @@ +.. SPDX-FileCopyrightText: 2023 Intel Corporation +.. +.. SPDX-License-Identifier: CC-BY-4.0 + +.. _onemkl_device_rng_distributions_method: + +Distributions Template Parameter Method +======================================= + +.. tabularcolumns:: |\Y{0.4}|\Y{0.2}|\Y{0.4}| + +.. list-table:: + :header-rows: 1 + :class: longtable + + * - Method Type + - Distributions + - Math Description + + * - ``uniform_method::standard`` + ``uniform_method::accurate`` + - ``uniform`` + - Standard method. ``uniform_method::accurate`` checks for additional ``float`` and ``double`` data types. + For ``integer`` data types, it uses ``double`` as a ``BRNG`` data type (``float`` ``BRNG`` data type is used in + ``uniform_method::standard`` method on GPU). + * - ``gaussian_method::box_muller2`` + - ``gaussian`` + - Generates normally distributed random numbers `x1` and `x2` through the pair of uniformly distributed numbers `u1` and `u2` according to + the formulas: :math:`x_1 = \sqrt{-2 \ln u_1} \sin {2 \pi u_2}`\ :math:`x_2 = \sqrt{-2 \ln u_1} \cos {2 \pi u_2}`\ + * - ``exponential_method::icdf`` + ``exponential_method::icdf_accurate`` + - ``exponential`` + - Inverse cumulative distribution function (ICDF) method. + * - ``lognormal_method::box_muller2`` + - ``lognormal`` + - Normally distributed random numbers `x1` and `x2` are produced through the pair of uniformly distributed numbers `u1` and `u2` according to the formulas: + :math:`x_1 = -2 \ln u_1 \sin {2 \pi u_2}`\ \ :math:`x_2 = -2 \ln u_1 \cos {2 \pi u_2}`\ + + Then `x1` and `x2` are converted to lognormal distribution. + * - ``bernoulli_method::icdf`` + - ``bernoulli`` + - Inverse cumulative distribution function (ICDF) method. + * - ``poisson_method::devroye`` + - ``poisson`` + - Acceptance/rejection method for :math:`\lambda \geq 27` with decomposition into four regions: + + * Two parallelograms + * Triangle + * Left exponential tail + * Right exponential tail + +`NOTE:` Methods provided for exposition purposes. diff --git a/source/elements/oneMKL/source/domains/rng/device_api/device-distributions.rst b/source/elements/oneMKL/source/domains/rng/device_api/device-distributions.rst new file mode 100644 index 0000000000..836d02f2ff --- /dev/null +++ b/source/elements/oneMKL/source/domains/rng/device_api/device-distributions.rst @@ -0,0 +1,92 @@ +.. SPDX-FileCopyrightText: 2023 Intel Corporation +.. +.. SPDX-License-Identifier: CC-BY-4.0 + +.. _onemkl_device_rng_distributions: + +Device Distributions +==================== + +oneMKL RNG routines are used to generate random numbers with different types of distributions. Each function group is +introduced below by the type of underlying distribution and contains a short description of its functionality, as well +as specifications of the call sequence and the explanation of input and output parameters. The Device Continuous +Distribution Generators table and Device Discrete Distribution Generators table mention random number generator routines +with data types and output distributions, and sets correspondence between data types of the generator routines and the +basic random number generators. + +**Device Continuous Distribution Generators** + +.. list-table:: + :header-rows: 1 + + * - Type of Distribution + - Data Types + - BRNG Data Type + - Description + * - :ref:`onemkl_device_rng_uniform_continuous` + - float, double + - float, double + - Uniform continuous distribution on the interval [``a,b``) + * - :ref:`onemkl_device_rng_gaussian` + - float, double + - float, double + - Normal (Gaussian) distribution + * - :ref:`onemkl_device_rng_exponential` + - float, double + - float, double + - Exponential distribution + * - :ref:`onemkl_device_rng_lognormal` + - float, double + - float, double + - Lognormal distribution + + +**Device Discrete Distribution Generators** + +.. list-table:: + :header-rows: 1 + + * - Type of Distribution + - Data Types + - BRNG Data Type + - Description + * - :ref:`onemkl_device_rng_uniform_discrete` + - integer + - float + - Uniform discrete distribution on the interval [``a,b``) + * - :ref:`onemkl_device_rng_bits` + - integer + - integer + - Bits of underlying BRNG integer sequence + * - :ref:`onemkl_device_rng_uniform_bits` + - integer + - integer + - Uniformly distributed bits in 32/64-bit chunks + * - :ref:`onemkl_device_rng_poisson` + - integer + - integer + - Poisson distribution + * - :ref:`onemkl_device_rng_bernoulli` + - integer + - integer + - Bernoulli distribution + +`NOTE:` In case of ``integer`` check desired distribution for supported data types. + +**Parent topic:** :ref:`onemkl_device_rng_routines` + +.. toctree:: + :maxdepth: 1 + :hidden: + + device-distributions-template-parameter-method.rst + device-rng-uniform-continuous.rst + device-rng-gaussian.rst + device-rng-lognormal.rst + device-rng-exponential.rst + device-rng-uniform-discrete.rst + device-rng-bits.rst + device-rng-uniform-bits.rst + device-rng-poisson.rst + device-rng-bernoulli.rst + diff --git a/source/elements/oneMKL/source/domains/rng/device_api/device-engines.rst b/source/elements/oneMKL/source/domains/rng/device_api/device-engines.rst new file mode 100644 index 0000000000..794f089f5e --- /dev/null +++ b/source/elements/oneMKL/source/domains/rng/device_api/device-engines.rst @@ -0,0 +1,42 @@ +.. SPDX-FileCopyrightText: 2023 Intel Corporation +.. +.. SPDX-License-Identifier: CC-BY-4.0 + +.. _onemkl_device_rng_engines: + +Device Engines (Basic Random Number Generators) +=============================================== + +oneMKL RNG provides following device pseudorandom number generators: + +.. tabularcolumns:: |\Y{0.4}|\Y{0.6}| + +.. list-table:: + :header-rows: 1 + :class: longtable + + * - Routine + - Description + + * - :ref:`onemkl_device_rng_mrg32k3a` + - The combined multiple recursive pseudorandom number generator ``MRG32k3a`` [:ref:`L'Ecuyer99 `] + + * - :ref:`onemkl_device_rng_philox4x32x10` + - Philox4x32-10 counter-based pseudorandom number generator with a period of :math:`2^{128}` ``PHILOX4X32X10`` [:ref:`Salmon11 `] + + * - :ref:`onemkl_device_rng_mcg31m1` + - The 31-bit multiplicative congruential pseudorandom number generator MCG(:math:`1132489760, 2^{32}-1`) :ref:`[L'Ecuyer99a] `. + + * - :ref:`onemkl_device_rng_mcg59` + - The 59-bit multiplicative congruential pseudorandom number generator MCG(:math:`13^{13}, 2^{59}`) from NAG Numerical Libraries :ref:`[NAG] `. + +**Parent topic:** :ref:`onemkl_device_rng_routines` + +.. toctree:: + :maxdepth: 1 + :hidden: + + device-rng-mrg32k3a.rst + device-rng-philox4x32x10.rst + device-rng-mcg31m1.rst + device-rng-mcg59.rst \ No newline at end of file diff --git a/source/elements/oneMKL/source/domains/rng/device_api/device-rng-bernoulli.rst b/source/elements/oneMKL/source/domains/rng/device_api/device-rng-bernoulli.rst new file mode 100644 index 0000000000..4bff82aaf7 --- /dev/null +++ b/source/elements/oneMKL/source/domains/rng/device_api/device-rng-bernoulli.rst @@ -0,0 +1,185 @@ +.. SPDX-FileCopyrightText: 2023 Intel Corporation +.. +.. SPDX-License-Identifier: CC-BY-4.0 + +.. _onemkl_device_rng_bernoulli: + +bernoulli +========= + +Generates Bernoulli distributed random values. + +.. rubric:: Description + +The ``bernoulli`` class object is used in the ``generate`` and function +to provide Bernoulli distributed random numbers with probability ``p`` of a single trial success, +where :math:`p \in R; 0 \leq p \leq 1`. + +The probability distribution is given by: + +.. math:: + + P(X = 1) = p + +.. math:: + + P(X = 0) = 1 - p + +The cumulative distribution function is as follows: + +.. math:: + + F_p(x) = + \begin{cases} + 0, & x < 0 \\ + 1 - p, & 0 \leq x < 1, x \in R \\ + 1, & x \geq 1 + \end{cases} + + +class bernoulli +--------------- + +.. rubric:: Syntax + +.. code-block:: cpp + + namespace oneapi::mkl::rng::device { + template + class bernoulli { + public: + using method_type = Method; + using result_type = IntType; + + bernoulli(); + explicit bernoulli(float p); + + float p() const; + }; + } + + +.. container:: section + + .. rubric:: Template parameters + + .. container:: section + + typename IntType + Type of the produced values. Supported types: + * ``std::int32_t`` + * ``std::uint32_t`` + + .. container:: section + + typename Method = oneapi::mkl::rng::bernoulli_method::by_default + Transformation method, which will be used for generation. Supported types: + + * ``oneapi::mkl::rng::bernoulli_method::by_default`` + * ``oneapi::mkl::rng::bernoulli_method::icdf`` + + See description of the methods in :ref:`Distributions methods template parameter`. + +.. container:: section + + .. rubric:: Class Members + + .. list-table:: + :header-rows: 1 + + * - Routine + - Description + * - `bernoulli()`_ + - Default constructor + * - `explicit bernoulli(float p)`_ + - Constructor with parameters + * - `float p() const`_ + - Method to obtain probability `p` + +.. container:: section + + .. rubric:: Member types + + .. container:: section + + .. code-block:: cpp + + bernoulli::method_type = Method + + .. container:: section + + .. rubric:: Description + + The type which defines transformation method for generation. + + .. container:: section + + .. code-block:: cpp + + bernoulli::result_type = IntType + + .. container:: section + + .. rubric:: Description + + The type which defines type of generated random numbers. + +.. container:: section + + .. rubric:: Constructors + + .. container:: section + + .. _`bernoulli()`: + + .. code-block:: cpp + + bernoulli::bernoulli() + + .. container:: section + + .. rubric:: Description + + Default constructor for distribution, parameters set as `p` = 0.5f. + + .. container:: section + + .. _`explicit bernoulli(float p)`: + + .. code-block:: cpp + + explicit bernoulli::bernoulli(float p) + + .. container:: section + + .. rubric:: Description + + Constructor with parameters. `p` is a probability. + + .. container:: section + + .. rubric:: Throws + + oneapi::mkl::invalid_argument + Exception is thrown when `p > 1`, or `p < 0` + +.. container:: section + + .. rubric:: Characteristics + + .. container:: section + + .. _`float p() const`: + + .. code-block:: cpp + + float bernoulli::p() const + + .. container:: section + + .. rubric:: Return Value + + Returns the distribution parameter `p` - probability. + +**Parent topic:** :ref:`onemkl_device_rng_distributions` + diff --git a/source/elements/oneMKL/source/domains/rng/device_api/device-rng-bits.rst b/source/elements/oneMKL/source/domains/rng/device_api/device-rng-bits.rst new file mode 100644 index 0000000000..bee0775dd8 --- /dev/null +++ b/source/elements/oneMKL/source/domains/rng/device_api/device-rng-bits.rst @@ -0,0 +1,61 @@ +.. SPDX-FileCopyrightText: 2023 Intel Corporation +.. +.. SPDX-License-Identifier: CC-BY-4.0 + +.. _onemkl_device_rng_bits: + +bits +==== + +Generates bits of underlying engine (BRNG) integer sequence. + +.. rubric:: Description + +The ``bits`` class object is used in ``generate`` and function to provide integer +random values. Each integer can be treated as a vector of several bits. In pseudorandom generators +this randomness can be violated. See :ref:`VS Notes` for details. + + +class bits +---------- + +.. rubric:: Syntax + +.. code-block:: cpp + + namespace oneapi::mkl::rng::device { + template + class bits { + using result_type = UIntType; + }; + } + + +.. container:: section + + .. rubric:: Template parameters + + .. container:: section + + typename UIntType + Type of the produced values. Supported types: + * ``std::uint32_t`` for philox4x32x10, mrg32k3a and mcg31m1 engines. + * ``std::uint64_t`` for mcg59. + +.. container:: section + + .. rubric:: Member types + + .. container:: section + + .. code-block:: cpp + + bits::result_type = UIntType + + .. container:: section + + .. rubric:: Description + + The type which defines type of generated random numbers. + +**Parent topic:** :ref:`onemkl_device_rng_distributions` diff --git a/source/elements/oneMKL/source/domains/rng/device_api/device-rng-exponential.rst b/source/elements/oneMKL/source/domains/rng/device_api/device-rng-exponential.rst new file mode 100644 index 0000000000..2d3fda860e --- /dev/null +++ b/source/elements/oneMKL/source/domains/rng/device_api/device-rng-exponential.rst @@ -0,0 +1,207 @@ +.. SPDX-FileCopyrightText: 2023 Intel Corporation +.. +.. SPDX-License-Identifier: CC-BY-4.0 + +.. _onemkl_device_rng_exponential: + +exponential +=========== + + +Generates exponentially distributed random numbers. + +.. rubric:: Description + +The ``exponential`` class object is used in the ``generate`` function to provide +random numbers with exponential distribution that has displacement :math:`a` and scalefactor :math:`\beta`, +where :math:`a, \beta \in R ; \beta > 0`. + + +The probability density function is given by: + +.. math:: + + f_{a, \beta}(x) = + \begin{cases} + \frac{1}{\beta} \exp (-\frac{(x-a)}{\beta}), & x \geq a \\ + 0, & x < a + \end{cases}, + - \infty < x < + \infty + +The cumulative distribution function is as follows: + +.. math:: + + F_{a, \beta}(x) = + \begin{cases} + 1 - \exp (-\frac{(x-a)}{\beta}), & x \geq a \\ + 0, & x < a + \end{cases}, + - \infty < x < + \infty + + +class exponential +----------------- + +.. rubric:: Syntax + +.. code-block:: cpp + + namespace oneapi::mkl::rng::device { + template + class exponential { + public: + using method_type = Method; + using result_type = RealType; + + exponential(); + explicit exponential(RealType a, RealType beta); + + RealType a() const; + RealType beta() const; + }; + } + + +.. container:: section + + .. rubric:: Template parameters + + .. container:: section + + typename RealType + Type of the produced values. Supported types: + + * ``float`` + * ``double`` + + .. container:: section + + typename Method = oneapi::mkl::rng::exponential_method::by_default + Generation method. The specific values are as follows: + + * ``oneapi::mkl::rng::device::exponential_method::by_default`` + * ``oneapi::mkl::rng::device::exponential_method::icdf`` + * ``oneapi::mkl::rng::device::exponential_method::icdf_accurate`` + + See description of the methods in :ref:`Distributions methods template parameter`. + + +.. container:: section + + .. rubric:: Class Members + + .. list-table:: + :header-rows: 1 + + * - Routine + - Description + * - `exponential()`_ + - Default constructor + * - `explicit exponential(RealType a, RealType beta)`_ + - Constructor with parameters + * - `RealType a() const`_ + - Method to obtain displacement value + * - `RealType beta() const`_ + - Method to obtain scalefactor + +.. container:: section + + .. rubric:: Member types + + .. container:: section + + .. code-block:: cpp + + lognormal::method_type = Method + + .. container:: section + + .. rubric:: Description + + The type which defines transformation method for generation. + + .. container:: section + + .. code-block:: cpp + + lognormal::result_type = RealType + + .. container:: section + + .. rubric:: Description + + The type which defines type of generated random numbers. + +.. container:: section + + .. rubric:: Constructors + + .. container:: section + + .. _`exponential()`: + + .. code-block:: cpp + + exponential::exponential() + + .. container:: section + + .. rubric:: Description + + Default constructor for distribution, parameters set as `a` = 0.0, `beta` = 1.0. + + .. container:: section + + .. _`explicit exponential(RealType a, RealType beta)`: + + .. code-block:: cpp + + explicit exponential::exponential(RealType a, RealType beta) + + .. container:: section + + .. rubric:: Description + + Constructor with parameters. `a` is a displacement, `beta` is a scalefactor. + + .. container:: section + + .. rubric:: Throws + + oneapi::mkl::invalid_argument + Exception is thrown when :math:`beta \leq 0` + +.. container:: section + + .. rubric:: Characteristics + + .. container:: section + + .. _`RealType a() const`: + + .. code-block:: cpp + + RealType exponential::a() const + + .. container:: section + + .. rubric:: Return Value + + Returns the distribution parameter `a` - displacement. + + .. container:: section + + .. _`RealType beta() const`: + + .. code-block:: cpp + + RealType exponential::beta() const + + .. container:: section + + .. rubric:: Return Value + + Returns the distribution parameter `beta` - scalefactor value. + +**Parent topic:** :ref:`onemkl_device_rng_distributions` diff --git a/source/elements/oneMKL/source/domains/rng/device_api/device-rng-gaussian.rst b/source/elements/oneMKL/source/domains/rng/device_api/device-rng-gaussian.rst new file mode 100644 index 0000000000..f809fce6b4 --- /dev/null +++ b/source/elements/oneMKL/source/domains/rng/device_api/device-rng-gaussian.rst @@ -0,0 +1,213 @@ +.. SPDX-FileCopyrightText: 2023 Intel Corporation +.. +.. SPDX-License-Identifier: CC-BY-4.0 + +.. _onemkl_device_rng_gaussian: + +gaussian +======== + +Generates normally distributed random numbers. + +.. rubric:: Description + +The ``gaussian`` class object is used in the ``generate`` and function to provide +random numbers with normal (Gaussian) distribution with mean (``a``) and standard deviation +(``stddev``, :math:`\sigma` ), where :math:`a, \sigma \in \mathbb{R}; \sigma > 0` + +The probability density function is given by: + +.. math:: + + f_{a, \sigma} (x) = + \frac{1}{\sigma \sqrt{2 \pi}} + \exp + \left( + - \frac{(y-a)^2}{2\sigma^2} + \right) dy, + - \infty < x < + \infty + +The cumulative distribution function is as follows: + +.. math:: + + F_{a, \sigma} (x) = + \int_{-\infty}^{x} + \frac{1}{\sigma \sqrt{2 \pi}} + \exp + \left( + - \frac{(y-a)^2}{2\sigma^2} + \right) dy, + - \infty < x < + \infty + + +The cumulative distribution function :math:`F_{a, \sigma}(x)` can be expressed +in terms of standard normal distribution :math:`\phi(x)` as + +.. math:: + + F_{a,\sigma}(x) = \phi((x - a)/\sigma) + + +class gaussian +-------------- + +.. rubric:: Syntax + +.. code-block:: cpp + + namespace oneapi::mkl::rng::device { + template + class gaussian { + public: + using method_type = Method; + using result_type = RealType; + + gaussian(); + explicit gaussian(RealType mean, RealType stddev); + + RealType mean() const; + RealType stddev() const; + }; + } + +.. container:: section + + .. rubric:: Template parameters + + .. container:: section + + typename RealType + Type of the produced values. Supported types: + + * ``float`` + * ``double`` + + .. container:: section + + typename Method + Generation method. The specific values are as follows: + + * ``oneapi::mkl::rng::device::gaussian_method::by_default`` + * ``oneapi::mkl::rng::device::gaussian_method::box_muller2`` + + See description of the methods in :ref:`Distributions methods template parameter` + +.. container:: section + + .. rubric:: Class Members + + .. list-table:: + :header-rows: 1 + + * - Routine + - Description + * - `gaussian()`_ + - Default constructor + * - `explicit gaussian(RealType mean, RealType stddev)`_ + - Constructor with parameters + * - `RealType mean() const`_ + - Method to obtain left bound `a` + * - `RealType stddev() const`_ + - Method to obtain right bound `b` + +.. container:: section + + .. rubric:: Member types + + .. container:: section + + .. code-block:: cpp + + gaussian::method_type = Method + + .. container:: section + + .. rubric:: Description + + The type which defines transformation method for generation. + + .. container:: section + + .. code-block:: cpp + + gaussian::result_type = RealType + + .. container:: section + + .. rubric:: Description + + The type which defines type of generated random numbers. + +.. container:: section + + .. rubric:: Constructors + + .. container:: section + + .. _`gaussian()`: + + .. code-block:: cpp + + gaussian::gaussian() + + .. container:: section + + .. rubric:: Description + + Default constructor for distribution, parameters set as `mean` = 0.0, `stddev` = 1.0. + + .. container:: section + + .. _`explicit gaussian(RealType mean, RealType stddev)`: + + .. code-block:: cpp + + explicit gaussian::gaussian(RealType a, RealType b) + + .. container:: section + + .. rubric:: Description + + Constructor with parameters. `mean` is a mean value, `stddev` is a standard deviation value. + + .. container:: section + + .. rubric:: Throws + + oneapi::mkl::invalid_argument + Exception is thrown when `stddev` :math:`\leq 0` + +.. container:: section + + .. rubric:: Characteristics + + .. container:: section + + .. _`RealType mean() const`: + + .. code-block:: cpp + + RealType gaussian::mean() const + + .. container:: section + + .. rubric:: Return Value + + Returns the distribution parameter `mean` - mean value. + + .. container:: section + + .. _`RealType stddev() const`: + + .. code-block:: cpp + + RealType gaussian::stddev() const + + .. container:: section + + .. rubric:: Return Value + + Returns the distribution parameter `stddev` - standard deviation value. + +**Parent topic:** :ref:`onemkl_device_rng_distributions` diff --git a/source/elements/oneMKL/source/domains/rng/device_api/device-rng-generate-routines.rst b/source/elements/oneMKL/source/domains/rng/device_api/device-rng-generate-routines.rst new file mode 100644 index 0000000000..8b60e7429e --- /dev/null +++ b/source/elements/oneMKL/source/domains/rng/device_api/device-rng-generate-routines.rst @@ -0,0 +1,18 @@ +.. SPDX-FileCopyrightText: 2023 Intel Corporation +.. +.. SPDX-License-Identifier: CC-BY-4.0 + +.. _onemkl_device_rng_generate_routines: + +Device Generate Routines +======================== + + +Use the :ref:`onemkl_device_rng_generate` routine to obtain random numbers from a given engine with proper +statistics of a given distribution. + +.. toctree:: + :maxdepth: 1 + :hidden: + + device-rng-generate.rst \ No newline at end of file diff --git a/source/elements/oneMKL/source/domains/rng/device_api/device-rng-generate.rst b/source/elements/oneMKL/source/domains/rng/device_api/device-rng-generate.rst new file mode 100644 index 0000000000..02e62390c2 --- /dev/null +++ b/source/elements/oneMKL/source/domains/rng/device_api/device-rng-generate.rst @@ -0,0 +1,52 @@ +.. SPDX-FileCopyrightText: 2023 Intel Corporation +.. +.. SPDX-License-Identifier: CC-BY-4.0 + +.. _onemkl_device_rng_generate: + +generate +======== + +.. rubric:: Description + +Entry point to obtain random numbers from a given engine with proper statistics of a given distribution. + +.. rubric:: Syntax + +.. code-block:: cpp + + namespace oneapi::mkl::rng::device { + template + auto generate(Distr& distr, Engine& engine) -> + typename std::conditional>::type + } + +.. container:: section + + .. rubric:: Template Parameters + + Distr + Type of distribution which is used for random number generation. + + Engine + Type of engine which is used for random number generation. + +.. container:: section + + .. rubric:: Input Parameters + + distr + Distribution object. See :ref:`onemkl_device_rng_distributions` for details. + + engine + Engine object. See :ref:`onemkl_device_rng_engines` for details. + +.. container:: section + + .. rubric:: Return Value + + Returns `Distr::result_type` if `Engine::vec_size == 1` or `sycl::vec` + with generated random numbers. + +**Parent topic:** :ref:`onemkl_device_rng_generate_routines` diff --git a/source/elements/oneMKL/source/domains/rng/device_api/device-rng-lognormal.rst b/source/elements/oneMKL/source/domains/rng/device_api/device-rng-lognormal.rst new file mode 100644 index 0000000000..d9e065a5af --- /dev/null +++ b/source/elements/oneMKL/source/domains/rng/device_api/device-rng-lognormal.rst @@ -0,0 +1,242 @@ +.. SPDX-FileCopyrightText: 2023 Intel Corporation +.. +.. SPDX-License-Identifier: CC-BY-4.0 + +.. _onemkl_device_rng_lognormal: + +lognormal +========= + + +Generates lognormally distributed random numbers. + +.. rubric:: Description + +The ``lognormal`` class object is used in the ``generate`` and function to provide +random numbers with average of distribution (``m``, ``a``) and standard deviation (``s``, :math:`\sigma`) of +subject normal distribution, displacement (``displ``, ``b``), and scalefactor (``scale``, :math:`\beta`), where +:math:`a, \sigma, b, \beta \in \mathbb{R}; \sigma > 0, \beta > 0`. + +The probability density function is given by: + +.. math:: + + f_{a, \sigma, b, \beta} (x) = + \begin{cases} + \frac{1}{\sigma (x - b) \sqrt {2\pi}} + \exp \left( + -\frac{\ln( \frac{x - b}{\beta}) - a)^2}{2\sigma^2} + \right), & x > b \\ + 0, & x \leq b + \end{cases} + + +The cumulative distribution function is as follows: + +.. math:: + + F_{a, \sigma, b, \beta} (x) = + \begin{cases} + \Phi \left(\frac{\ln( \frac{x - b}{\beta}) - a}{\sigma}\right), & x > b \\ + 0, & x \leq b + \end{cases} + + +class lognormal +--------------- + +.. rubric:: Syntax + +.. code-block:: cpp + + namespace oneapi::mkl::rng::device { + template + class lognormal { + public: + using method_type = Method; + using result_type = RealType; + + lognormal(); + explicit lognormal(RealType m, RealType s, RealType displ = (RealType)0.0, RealType scale = (RealType)1.0); + + RealType m() const; + RealType s() const; + RealType displ() const; + RealType scale() const; + }; + } + +.. container:: section + + .. rubric:: Template parameters + + .. container:: section + + typename RealType + Type of the produced values. Supported types: + + * ``float`` + * ``double`` + + .. container:: section + + typename Method = oneapi::mkl::rng::lognormal_method::by_default + Transformation method, which will be used for generation. Supported types: + + * ``oneapi::mkl::rng::device::lognormal_method::by_default`` + * ``oneapi::mkl::rng::device::lognormal_method::box_muller2`` + + See description of the methods in :ref:`Distributions methods template parameter`. + + +.. container:: section + + .. rubric:: Class Members + + .. list-table:: + :header-rows: 1 + + * - Routine + - Description + * - `lognormal()`_ + - Default constructor + * - `explicit lognormal(RealType m, RealType s, RealType displ = (RealType)0.0, RealType scale = (RealType)1.0)`_ + - Constructor with parameters + * - `RealType m() const`_ + - Method to obtain mean value + * - `RealType s() const`_ + - Method to obtain standard deviation value + * - `RealType displ() const`_ + - Method to obtain displacement value + * - `RealType scale() const`_ + - Method to obtain scalefactor value + + +.. container:: section + + .. rubric:: Member types + + .. container:: section + + .. code-block:: cpp + + lognormal::method_type = Method + + .. container:: section + + .. rubric:: Description + + The type which defines transformation method for generation. + + .. container:: section + + .. code-block:: cpp + + lognormal::result_type = RealType + + .. container:: section + + .. rubric:: Description + + The type which defines type of generated random numbers. + +.. container:: section + + .. rubric:: Constructors + + .. container:: section + + .. _`lognormal()`: + + .. code-block:: cpp + + lognormal::lognormal() + + .. container:: section + + .. rubric:: Description + + Default constructor for distribution, parameters set as `m` = 0.0, `s` = 1.0, `displ` = 0.0, `scale` = 1.0. + + .. container:: section + + .. _`explicit lognormal(RealType m, RealType s, RealType displ = (RealType)0.0, RealType scale = (RealType)1.0)`: + + .. code-block:: cpp + + explicit lognormal::lognormal(RealType m, RealType s, RealType displ = (RealType)0.0, RealType scale = (RealType)1.0) + + .. container:: section + + .. rubric:: Description + + Constructor with parameters. `m` is a mean value, `s` is a standard deviation value, `displ` is a displacement value, `scale` is a scalefactor value. + + .. container:: section + + .. rubric:: Throws + + oneapi::mkl::invalid_argument + Exception is thrown when :math:`s \leq 0`, or :math:`scale \leq 0` + +.. container:: section + + .. rubric:: Characteristics + + .. container:: section + + .. _`RealType m() const`: + + .. code-block:: cpp + + RealType lognormal::m() const + + .. container:: section + + .. rubric:: Return Value + + Returns the distribution parameter `m` - mean value. + + .. container:: section + + .. _`RealType s() const`: + + .. code-block:: cpp + + RealType lognormal::s() const + + .. container:: section + + .. rubric:: Return Value + + Returns the distribution parameter `s` - standard deviation value. + + .. container:: section + + .. _`RealType displ() const`: + + .. code-block:: cpp + + RealType lognormal::displ() const + + .. container:: section + + .. rubric:: Return Value + + Returns the distribution parameter `displ` - displacement value. + + .. container:: section + + .. _`RealType scale() const`: + + .. code-block:: cpp + + RealType lognormal::scale() const + + .. container:: section + + .. rubric:: Return Value + + Returns the distribution parameter `scale` - scalefactor value. + +**Parent topic:** :ref:`onemkl_device_rng_distributions` diff --git a/source/elements/oneMKL/source/domains/rng/device_api/device-rng-mcg31m1.rst b/source/elements/oneMKL/source/domains/rng/device_api/device-rng-mcg31m1.rst new file mode 100644 index 0000000000..54bfdbe34a --- /dev/null +++ b/source/elements/oneMKL/source/domains/rng/device_api/device-rng-mcg31m1.rst @@ -0,0 +1,121 @@ +.. SPDX-FileCopyrightText: 2023 Intel Corporation +.. +.. SPDX-License-Identifier: CC-BY-4.0 + +.. _onemkl_device_rng_mcg31m1: + +mcg31m1 +======= + +The 31-bit multiplicative congruential pseudorandom number generator MCG(:math:`1132489760, 2^{32}-1`) :ref:`[L'Ecuyer99a] `. + +.. rubric:: Description + +The mcg31m1 engine is a 31-bit multiplicative congruential generator :ref:`[L'Ecuyer99] `. +The mcg31m1 generator belongs to linear congruential generators with the period length of approximately :math:`2^{31}`. +Such generators are still used as default random number generators in various software systems, mainly due to the +simplicity of the portable versions implementation, speed, and compatibility with the earlier systems versions. +However, their period length does not meet the requirements for modern basic generators. Still, the mcg31m1 generator +possesses good statistic properties and you may successfully use it to generate random numbers of different +distributions for small samplings. + +.. container:: section + + .. rubric:: Generation algorithm + + :math:`x_n=ax_{n-1}(mod \ m)` + + :math:`u_n = x_n / m` + + :math:`a = 1132489760, m=2^{31} - 1` + +class mcg31m1 +------------- + +.. rubric:: Syntax + +.. code-block:: cpp + + namespace oneapi::mkl::rng::device { + template + class mcg31m1 { + public: + static constexpr std::uint32_t default_seed = 1; + static constexpr std::int32_t vec_size = VecSize; + + mcg31m1(); + mcg31m1(std::uint32_t seed, std::uint64_t offset = 0); + mcg31m1(std::initializer_list seed, std::uint64_t offset = 0); + }; + } + +.. container:: section + + .. rubric:: Class Template Parameters + + VecSize + Describes the size of vector which will be produced by generate function by this engine. VecSize values + may be 1, 2, 3, 4, 8, 16 as ``sycl::vec`` class size. By default VecSize = 1, for this case, a single + random number is returned by the ``generate`` function. + +.. container:: section + + .. rubric:: Class Members + + .. list-table:: + :header-rows: 1 + + * - Routine + - Description + * - `mcg31m1()`_ + - Default constructor + * - `mcg31m1(std::uint32_t seed, std::uint64_t offset = 0)`_ + - Constructor for common seed initialization of the engine and common number of skipped elements + * - `mcg31m1(std::initializer_list seed, std::uint64_t offset = 0)`_ + - Constructor for extended seed initialization of the engine and common number of skipped elements + +.. container:: section + + .. rubric:: Constructors + + .. _`mcg31m1()`: + + .. code-block:: cpp + + mcg31m1::mcg31m1() + + .. _`mcg31m1(std::uint32_t seed, std::uint64_t offset = 0)`: + + .. code-block:: cpp + + mcg31m1::mcg31m1(std::uint32_t seed, std::uint64_t offset = 0) + + .. container:: section + + .. rubric:: Input Parameters + + seed + The initial conditions of the generator state, assume :math:`x_0 = seed \ mod \ 0x7FFFFFFF`, + if :math:`x_0 = 0`, assume :math:`x_0 = 1`. + + offset + Number of skipped elements. + + .. _`mcg31m1(std::initializer_list seed, std::uint64_t offset = 0)`: + + .. code-block:: cpp + + mcg31m1::mcg31m1(std::initializer_list seed, std::uint64_t offset = 0) + + .. container:: section + + .. rubric:: Input Parameters + + seed + The initial conditions of the generator state, assume :math:`x_0 = seed \ mod \ 0x7FFFFFFF`, + if :math:`x_0 = 0`, assume :math:`x_0 = 1`. + + offset + Number of skipped elements. + +**Parent topic:** :ref:`onemkl_device_rng_engines` diff --git a/source/elements/oneMKL/source/domains/rng/device_api/device-rng-mcg59.rst b/source/elements/oneMKL/source/domains/rng/device_api/device-rng-mcg59.rst new file mode 100644 index 0000000000..33dbd2e3dc --- /dev/null +++ b/source/elements/oneMKL/source/domains/rng/device_api/device-rng-mcg59.rst @@ -0,0 +1,117 @@ +.. SPDX-FileCopyrightText: 2023 Intel Corporation +.. +.. SPDX-License-Identifier: CC-BY-4.0 + +.. _onemkl_device_rng_mcg59: + +mcg59 +===== + +The 59-bit multiplicative congruential pseudorandom number generator MCG(:math:`13^{13}, 2^{59}`) +from NAG Numerical Libraries. + +.. rubric:: Description + +The mcg59 engine is a 59-bit multiplicative congruential generator from NAG Numerical Libraries :ref:`NAG `. +The mcg59 generator belongs to linear congruential generators with the period length of approximately :math:`2^{57}`. + +.. container:: section + + .. rubric:: Generation algorithm + + :math:`x_n=ax_{n-1}(mod \ m)` + + :math:`u_n = x_n / m` + + :math:`a = 13^{13}, m=2^{59}` + +class mcg59 +----------- + +.. rubric:: Syntax + +.. code-block:: cpp + + namespace oneapi::mkl::rng::device { + template + class mcg59 { + public: + static constexpr std::uint32_t default_seed = 1; + static constexpr std::int32_t vec_size = VecSize; + + mcg59(); + mcg59(std::uint32_t seed, std::uint64_t offset = 0); + mcg59(std::initializer_list seed, std::uint64_t offset = 0); + }; + } + +.. container:: section + + .. rubric:: Class Template Parameters + + VecSize + Describes the size of vector which will be produced by generate function by this engine. VecSize values + may be 1, 2, 3, 4, 8, 16 as ``sycl::vec`` class size. By default VecSize = 1, for this case, a single + random number is returned by the ``generate`` function. + +.. container:: section + + .. rubric:: Class Members + + .. list-table:: + :header-rows: 1 + + * - Routine + - Description + * - `mcg59()`_ + - Default constructor + * - `mcg59(std::uint32_t seed, std::uint64_t offset = 0)`_ + - Constructor for common seed initialization of the engine and common number of skipped elements + * - `mcg59(std::initializer_list seed, std::uint64_t offset = 0)`_ + - Constructor for extended seed initialization of the engine and common number of skipped elements + +.. container:: section + + .. rubric:: Constructors + + .. _`mcg59()`: + + .. code-block:: cpp + + mcg59::mcg59() + + .. _`mcg59(std::uint32_t seed, std::uint64_t offset = 0)`: + + .. code-block:: cpp + + mcg59::mcg59(std::uint32_t seed, std::uint64_t offset = 0) + + .. container:: section + + .. rubric:: Input Parameters + + seed + The initial conditions of the generator state, assume :math:`x_0 = seed \ mod \ 2^{59}`, + if :math:`x_0 = 0`, assume :math:`x_0 = 1`. + + offset + Number of skipped elements. + + .. _`mcg59(std::initializer_list seed, std::uint64_t offset = 0)`: + + .. code-block:: cpp + + mcg59::mcg59(std::initializer_list seed, std::uint64_t offset = 0) + + .. container:: section + + .. rubric:: Input Parameters + + seed + The initial conditions of the generator state, assume :math:`x_0 = seed \ mod \ 2^{59}`, + if :math:`x_0 = 0`, assume :math:`x_0 = 1`. + + offset + Number of skipped elements. + +**Parent topic:** :ref:`onemkl_device_rng_engines` diff --git a/source/elements/oneMKL/source/domains/rng/device_api/device-rng-mrg32k3a.rst b/source/elements/oneMKL/source/domains/rng/device_api/device-rng-mrg32k3a.rst new file mode 100644 index 0000000000..ffd3125198 --- /dev/null +++ b/source/elements/oneMKL/source/domains/rng/device_api/device-rng-mrg32k3a.rst @@ -0,0 +1,213 @@ +.. SPDX-FileCopyrightText: 2023 Intel Corporation +.. +.. SPDX-License-Identifier: CC-BY-4.0 + +.. _onemkl_device_rng_mrg32k3a: + +mrg32k3a +======== + +The combined multiple recursive pseudorandom number generator MRG32k3a. + +.. rubric:: Description + +MRG32k3a engine is a 32-bit combined multiple recursive generator with two components of order 3 +[:ref:`L'Ecuyer99a`]. MRG32k3a combined generator meets the requirements for +modern RNGs, such as good multidimensional uniformity, or a long period (:math:`p \approx 2^{191}`). + + +.. container:: section + + .. rubric:: Generation algorithm + + + :math:`x_n=a_{11} x_{n-1} + a_{12} x_{n-2} + a_{13} x_{n-3}(mod \ m_{1})` + + :math:`y_n = a_{21} y_{n-1} + a_{22} y_{n-2} + a_{23} (mod \ m_2)` + + :math:`z_n = x_n - y_n (mod \ m_{1})` + + :math:`u_n = z_n / m_1` + + :math:`a_{11} = 0, a_{12} = 1403580, a_{13} = -810728, m_1 = 2^{32} - 209` + + :math:`a_{21} = 527612, a_{22} = 0, a_{23} = -1370589, m_2 = 2^{32} - 22853` + + +class mrg32k3a +-------------- + +.. rubric:: Syntax + +.. code-block:: cpp + + namespace oneapi::mkl::rng::device { + template + class mrg32k3a { + public: + static constexpr std::uint32_t default_seed = 1; + static constexpr std::int32_t vec_size = VecSize; + + mrg32k3a(); + mrg32k3a(std::uint32_t seed, std::uint64_t offset = 0); + mrg32k3a(std::initializer_list seed, std::uint64_t offset = 0); + mrg32k3a(std::uint32_t seed, std::initializer_list offset); + mrg32k3a(std::initializer_list seed, std::initializer_list offset); + }; + } + + +.. container:: section + + .. rubric:: Class Template Parameters + + VecSize + Describes the size of vector which will be produced by generate function by this engine. VecSize values + may be 1, 2, 3, 4, 8, 16 as ``sycl::vec`` class size. By default VecSize = 1, for this case, a single + random number is returned by the ``generate`` function. + +.. container:: section + + .. rubric:: Class Members + + .. list-table:: + :header-rows: 1 + + * - Routine + - Description + * - `mrg32k3a()`_ + - Default constructor + * - `mrg32k3a(std::uint32_t seed, std::uint64_t offset = 0)`_ + - Constructor for common seed initialization of the engine and common number of skipped elements + * - `mrg32k3a(std::initializer_list seed, std::uint64_t offset = 0)`_ + - Constructor for extended seed initialization of the engine and common number of skipped elements + * - `mrg32k3a(std::uint32_t seed, std::initializer_list offset)`_ + - Constructor for common seed initialization of the engine and extended number of skipped elements + * - `mrg32k3a(std::initializer_list seed, std::initializer_list offset)`_ + - Constructor for extended seed initialization of the engine and extended number of skipped elements + +.. container:: section + + .. rubric:: Constructors + + .. _`mrg32k3a()`: + + .. code-block:: cpp + + mrg32k3a::mrg32k3a() + + .. _`mrg32k3a(std::uint32_t seed, std::uint64_t offset = 0)`: + + .. code-block:: cpp + + mrg32k3a::mrg32k3a(std::uint32_t seed, std::uint64_t offset = 0) + + .. container:: section + + .. rubric:: Input Parameters + + seed + The initial conditions of the generator state, assume + if :math:`n = 0: x_{-3} = x_{-2} = x_{-1} = y_{-3} = y_{-2} = y_{-1} = 1` + + if :math:`n = 1: x_{-3} = seed[0] \ mod \ m_1, x_{-2} = x_{-1} = y_{-3} = y_{-2} = y_{-1} = 1` + + if :math:`n = 2: x_{-3} = seed[0] \ mod \ m_1, x_{-2} = seed[1] \ mod \ m_1, x_{-1} = y_{-3} = y_{-2} = y_{-1} = 1` + + if :math:`n = 3: x_{-3} = seed[0] \ mod \ m_1, x_{-2} = seed[1] \ mod \ m_1, x_{-1} = seed[2] \ mod \ m_1` + + :math:`y_{-3} = y_{-2} = y_{-1} = 1` + + if :math:`n = 4: x_{-3} = seed[0] \ mod \ m_1, x_{-2} = seed[1] \ mod \ m_1, x_{-1} = seed[2] \ mod \ m_1` + + :math:`y_{-3} = seed[3] \ mod \ m_2, y_{-2} = y_{-1} = 1` + + if :math:`n = 5: x_{-3} = seed[0] \ mod \ m_1, x_{-2} = seed[1] \ mod \ m_1, x_{-1} = seed[2] \ mod \ m_1` + + :math:`y_{-3} = seed[3] \ mod \ m_2, y_{-2} = seed[4] \ mod \ m_2, y_{-1} = 1` + + if :math:`n \geqslant 6: x_{-3} = seed[0] \ mod \ m_1, x_{-2} = seed[1] \ mod \ m_1, x_{-1} = seed[2] \ mod \ m_1` + + :math:`y_{-3} = seed[3] \ mod \ m_2, y_{-2} = seed[4] \ mod \ m_2, y_{-1} = seed[5] \ mod \ m_2` + + if the values prove to be :math:`x_{-3} = x_{-2} = x_{-1} = 0`, assume :math:`x_{-3} = 1` + + if the values prove to be :math:`y_{-3} = y_{-2} = y_{-1} = 0`, assume :math:`y_{-3} = 1`. + + offset + Number of skipped elements. + + .. _`mrg32k3a(std::initializer_list seed, std::uint64_t offset = 0)`: + + .. code-block:: cpp + + mrg32k3a::mrg32k3a(std::initializer_list seed, std::uint64_t offset = 0) + + .. container:: section + + .. rubric:: Input Parameters + + seed + Initial conditions of the engine state. + + offset + Number of skipped elements. + + .. _`mrg32k3a(std::uint32_t seed, std::initializer_list offset)`: + + .. code-block:: cpp + + mrg32k3a::mrg32k3a(std::uint32_t seed, std::initializer_list offset) + + .. container:: section + + .. rubric:: Input Parameters + + seed + The initial conditions of the generator state, assume + if :math:`n = 0: x_{-3} = x_{-2} = x_{-1} = y_{-3} = y_{-2} = y_{-1} = 1` + + if :math:`n = 1: x_{-3} = seed[0] \ mod \ m_1, x_{-2} = x_{-1} = y_{-3} = y_{-2} = y_{-1} = 1` + + if :math:`n = 2: x_{-3} = seed[0] \ mod \ m_1, x_{-2} = seed[1] \ mod \ m_1, x_{-1} = y_{-3} = y_{-2} = y_{-1} = 1` + + if :math:`n = 3: x_{-3} = seed[0] \ mod \ m_1, x_{-2} = seed[1] \ mod \ m_1, x_{-1} = seed[2] \ mod \ m_1` + + :math:`y_{-3} = y_{-2} = y_{-1} = 1` + + if :math:`n = 4: x_{-3} = seed[0] \ mod \ m_1, x_{-2} = seed[1] \ mod \ m_1, x_{-1} = seed[2] \ mod \ m_1` + + :math:`y_{-3} = seed[3] \ mod \ m_2, y_{-2} = y_{-1} = 1` + + if :math:`n = 5: x_{-3} = seed[0] \ mod \ m_1, x_{-2} = seed[1] \ mod \ m_1, x_{-1} = seed[2] \ mod \ m_1` + + :math:`y_{-3} = seed[3] \ mod \ m_2, y_{-2} = seed[4] \ mod \ m_2, y_{-1} = 1` + + if :math:`n \geqslant 6: x_{-3} = seed[0] \ mod \ m_1, x_{-2} = seed[1] \ mod \ m_1, x_{-1} = seed[2] \ mod \ m_1` + + :math:`y_{-3} = seed[3] \ mod \ m_2, y_{-2} = seed[4] \ mod \ m_2, y_{-1} = seed[5] \ mod \ m_2` + + if the values prove to be :math:`x_{-3} = x_{-2} = x_{-1} = 0`, assume :math:`x_{-3} = 1` + + if the values prove to be :math:`y_{-3} = y_{-2} = y_{-1} = 0`, assume :math:`y_{-3} = 1`. + + offset + Number of skipped elements. Offset is calculated as: ``num_to_skip`` [0]+ ``num_to_skip`` [1]*2\ :sup:`64` + ``num_to_skip`` [2]\* 2\ :sup:`128` + … + ``num_to_skip`` [``n``-1]\*2\ :sup:`64` \*(``n``-1). + + .. _`mrg32k3a(std::initializer_list seed, std::initializer_list offset)`: + + .. code-block:: cpp + + mrg32k3a::mrg32k3a(std::initializer_list seed, std::initializer_list offset) + + .. container:: section + + .. rubric:: Input Parameters + + seed + Initial conditions of the engine state. + + offset + Number of skipped elements. Offset is calculated as: ``num_to_skip`` [0]+ ``num_to_skip`` [1]*2\ :sup:`64` + ``num_to_skip`` [2]\* 2\ :sup:`128` + … + ``num_to_skip`` [``n``-1]\*2\ :sup:`64` \*(``n``-1). + +**Parent topic:** :ref:`onemkl_device_rng_engines` diff --git a/source/elements/oneMKL/source/domains/rng/device_api/device-rng-philox4x32x10.rst b/source/elements/oneMKL/source/domains/rng/device_api/device-rng-philox4x32x10.rst new file mode 100644 index 0000000000..d5f51b8068 --- /dev/null +++ b/source/elements/oneMKL/source/domains/rng/device_api/device-rng-philox4x32x10.rst @@ -0,0 +1,192 @@ +.. SPDX-FileCopyrightText: 2023 Intel Corporation +.. +.. SPDX-License-Identifier: CC-BY-4.0 + +.. _onemkl_device_rng_philox4x32x10: + +philox4x32x10 +============= + +A Philox4x32-10 counter-based pseudorandom number generator [:ref:`Salmon11`]. + +.. rubric:: Description + +The Philox4x32x10 engine is a keyed family of generator of counter-based BRNG. The state consists of 128-bit integer counter :math:`c` and two 32-bits keys :math:`k_0` and :math:`k_1`. + +.. container:: section + + .. rubric:: Generation algorithm + + The generator has 32-bit integer output obtained in the following way [:ref:`Salmon11 `]: + + 1. :math:`c_n=c_{n-1} + 1` + 2. :math:`\omega_n = f(c_n)`, where :math:`f` is a function that takes 128-bit argument and returns a 128-bit number. The returned number is obtained as follows: + 2.1. The argument :math:`c` is interpreted as four 32-bit numbers :math:`c = \overline{L_1 R_1 L_0 R_0}`, where :math:`\overline{A B C D} = A \cdot 2^{96} + B \cdot 2^{64} + C \cdot 2^{32} + D`, put :math:`k_0^0 =k_0, k_1^0=k_1`. + + 2.2. The following recurrence is calculated: + + :math:`L_1^{i+1} =mullo(R_1^i, 0xD2511F53)` + + :math:`R_1^{i+1} =mulhi(R_0^i, 0xCD9E8D57) \oplus k_0^i \oplus L_0^i` + + :math:`L_0^{i+1} =mullo(R_0^i, 0xCD9E8D57)` + + :math:`R_0^{i+1} =mulhi(R_1^i, 0xD2511F53) \oplus k_1^i \oplus L_1^i` + + :math:`k_0^{i+1} =k_0^i + 0xBB67AE85` + + :math:`k_1^{i+1} =k_1^i + 0x9E3779B9`, where :math:`mulhi(a, b)` and :math:`mullo(a, b)` are high and low parts of the :math:`a \cdot b` product respectively. + + 2.3. Put :math:`f(c) = \overline{L_1^N R_1^N L_0^N R_0^N}`, where :math:`N = 10` + + 3. Integer output: :math:`r_{4n + k} = \omega_n(k)`, where :math:`\omega_n(k)` is the k-th 32-bit integer in quadruple :math:`\omega_n, k = 0, 1, 2, 3` + 4. Real output: :math:`u_n=(int)r_n / 2^{32} + 1/2` + + + +class philox4x32x10 +------------------- + +.. rubric:: Syntax + +.. code-block:: cpp + + namespace oneapi::mkl::rng::device { + template + class philox4x32x10 { + public: + static constexpr std::uint64_t default_seed = 1; + static constexpr std::int32_t vec_size = VecSize; + + philox4x32x10(); + philox4x32x10(std::uint64_t seed, std::uint64_t offset = 0); + philox4x32x10(std::initializer_list seed, std::uint64_t offset = 0); + philox4x32x10(std::uint64_t seed, std::initializer_list offset); + philox4x32x10(std::initializer_list seed, std::initializer_list offset); + }; + } + +.. container:: section + + .. rubric:: Class Template Parameters + + VecSize + Describes the size of vector which will be produced by generate function by this engine. VecSize values + may be 1, 2, 3, 4, 8, 16 as ``sycl::vec`` class size. By default VecSize = 1, for this case, a single + random number is returned by the ``generate`` function. + +.. container:: section + + .. rubric:: Class Members + + .. list-table:: + :header-rows: 1 + + * - Routine + - Description + * - `philox4x32x10()`_ + - Default constructor + * - `philox4x32x10(std::uint32_t seed, std::uint64_t offset = 0)`_ + - Constructor for common seed initialization of the engine and common number of skipped elements + * - `philox4x32x10(std::initializer_list seed, std::uint64_t offset = 0)`_ + - Constructor for extended seed initialization of the engine and common number of skipped elements + * - `philox4x32x10(std::uint32_t seed, std::initializer_list offset)`_ + - Constructor for common seed initialization of the engine and extended number of skipped elements + * - `philox4x32x10(std::initializer_list seed, std::initializer_list offset)`_ + - Constructor for extended seed initialization of the engine and extended number of skipped elements + +.. container:: section + + .. rubric:: Constructors + + .. _`philox4x32x10()`: + + .. code-block:: cpp + + philox4x32x10::philox4x32x10() + + .. _`philox4x32x10(std::uint32_t seed, std::uint64_t offset = 0)`: + + .. code-block:: cpp + + philox4x32x10::philox4x32x10(std::uint32_t seed, std::uint64_t offset = 0) + + .. container:: section + + .. rubric:: Input Parameters + + seed + The initial conditions of the generator state, assume :math:`k = seed, c = 0`, + where :math:`k` is a 64-bit key, :math:`c` is a 128-bit counter. + + offset + Number of skipped elements. + + .. _`philox4x32x10(std::initializer_list seed, std::uint64_t offset = 0)`: + + .. code-block:: cpp + + philox4x32x10::philox4x32x10(std::initializer_list seed, std::uint64_t offset = 0) + + .. container:: section + + .. rubric:: Input Parameters + + seed + The initial conditions of the generator state, assume + if :math:`n = 0: k = 0, c = 0` + + if :math:`n = 1: k = seed[0], c = 0` + + if :math:`n = 2: k = seed[0], c = seed[1]` + + if :math:`n = 3: k = seed[0], c = seed[1] + seed[2] \cdot 2^{64}` + + for :math:`n > 3` following arguments are ignored. + + offset + Number of skipped elements. + + .. _`philox4x32x10(std::uint32_t seed, std::initializer_list offset)`: + + .. code-block:: cpp + + philox4x32x10::philox4x32x10(std::uint32_t seed, std::initializer_list offset) + + .. container:: section + + .. rubric:: Input Parameters + + seed + The initial conditions of the generator state, assume :math:`k = seed, c = 0`, + where :math:`k` is a 64-bit key, :math:`c` is a 128-bit counter. + + offset + Number of skipped elements. Offset is calculated as: ``num_to_skip`` [0]+ ``num_to_skip`` [1]*2\ :sup:`64` + ``num_to_skip`` [2]\* 2\ :sup:`128` + … + ``num_to_skip`` [``n``-1]\*2\ :sup:`64` \*(``n``-1). + + .. _`philox4x32x10(std::initializer_list seed, std::initializer_list offset)`: + + .. code-block:: cpp + + philox4x32x10::philox4x32x10(std::initializer_list seed, std::initializer_list offset) + + .. container:: section + + .. rubric:: Input Parameters + + seed + The initial conditions of the generator state, assume + if :math:`n = 0: k = 0, c = 0` + + if :math:`n = 1: k = seed[0], c = 0` + + if :math:`n = 2: k = seed[0], c = seed[1]` + + if :math:`n = 3: k = seed[0], c = seed[1] + seed[2] \cdot 2^{64}` + + for :math:`n > 3` following arguments are ignored. + + offset + Number of skipped elements. Offset is calculated as: ``num_to_skip`` [0]+ ``num_to_skip`` [1]*2\ :sup:`64` + ``num_to_skip`` [2]\* 2\ :sup:`128` + … + ``num_to_skip`` [``n``-1]\*2\ :sup:`64` \*(``n``-1). + +**Parent topic:** :ref:`onemkl_device_rng_engines` diff --git a/source/elements/oneMKL/source/domains/rng/device_api/device-rng-poisson.rst b/source/elements/oneMKL/source/domains/rng/device_api/device-rng-poisson.rst new file mode 100644 index 0000000000..c2270cba27 --- /dev/null +++ b/source/elements/oneMKL/source/domains/rng/device_api/device-rng-poisson.rst @@ -0,0 +1,182 @@ +.. SPDX-FileCopyrightText: 2023 Intel Corporation +.. +.. SPDX-License-Identifier: CC-BY-4.0 + +.. _onemkl_device_rng_poisson: + +poisson +======= + +Generates Poisson distributed random values. + +.. rubric:: Description + +The ``poisson`` class object is used in the ``generate`` and function +to provide Poisson distributed random numbers with distribution parameter λ, where :math:`\lambda \in R; \lambda > 0`. + + +The probability distribution is given by: + +.. math:: + + P(X = k) = \frac{\lambda^k e^{-\lambda}}{k!} + +:math:`k \in \{0, 1, 2, \ldots \}`. + +The cumulative distribution function is as follows: + +.. math:: + + F_{\lambda}(x) = + \begin{cases} + \sum_{k=0}^{\lfloor x \rfloor} \frac{\lambda^k e^{-\lambda}}{k!}, & x \geq 0 \\ + 0, & x < 0 + \end{cases}, + x \in R + + +class poisson +------------- + +.. rubric:: Syntax + +.. code-block:: cpp + + namespace oneapi::mkl::rng::device { + template + class poisson { + public: + using method_type = Method; + using result_type = IntType; + + poisson(); + explicit poisson(double lambda); + + double lambda() const; + }; + } + + +.. container:: section + + .. rubric:: Template parameters + + .. container:: section + + typename IntType + Type of the produced values. Supported types: + * ``std::int32_t`` + * ``std::uint32_t`` + + .. container:: section + + typename Method = oneapi::mkl::rng::poisson_method::by_default + Transformation method, which will be used for generation. Supported types: + + * ``oneapi::mkl::rng::device::poisson_method::by_default`` + * ``oneapi::mkl::rng::device::poisson_method::devroye`` + + See description of the methods in :ref:`Distributions methods template parameter`. + +.. container:: section + + .. rubric:: Class Members + + .. list-table:: + :header-rows: 1 + + * - Routine + - Description + * - `poisson()`_ + - Default constructor + * - `explicit poisson(double lambda)`_ + - Constructor with parameters + * - `double lambda() const`_ + - Method to obtain distribution parameter + +.. container:: section + + .. rubric:: Member types + + .. container:: section + + .. code-block:: cpp + + poisson::method_type = Method + + .. container:: section + + .. rubric:: Description + + The type which defines transformation method for generation. + + .. container:: section + + .. code-block:: cpp + + poisson::result_type = IntType + + .. container:: section + + .. rubric:: Description + + The type which defines type of generated random numbers. + +.. container:: section + + .. rubric:: Constructors + + .. container:: section + + .. _`poisson()`: + + .. code-block:: cpp + + poisson::poisson() + + .. container:: section + + .. rubric:: Description + + Default constructor for distribution, parameters set as `lambda` = 0.5. + + .. container:: section + + .. _`explicit poisson(double lambda)`: + + .. code-block:: cpp + + explicit poisson::poisson(double lambda) + + .. container:: section + + .. rubric:: Description + + Constructor with parameters. `lambda` is a distribution parameter. + + .. container:: section + + .. rubric:: Throws + + oneapi::mkl::invalid_argument + Exception is thrown when :math:`lambda \leq 0` + +.. container:: section + + .. rubric:: Characteristics + + .. container:: section + + .. _`double lambda() const`: + + .. code-block:: cpp + + double poisson::lambda() const + + .. container:: section + + .. rubric:: Return Value + + Returns the distribution parameter `lambda`. + +**Parent topic:** :ref:`onemkl_device_rng_distributions` diff --git a/source/elements/oneMKL/source/domains/rng/device_api/device-rng-skip-ahead.rst b/source/elements/oneMKL/source/domains/rng/device_api/device-rng-skip-ahead.rst new file mode 100644 index 0000000000..173b3f782c --- /dev/null +++ b/source/elements/oneMKL/source/domains/rng/device_api/device-rng-skip-ahead.rst @@ -0,0 +1,79 @@ +.. SPDX-FileCopyrightText: 2023 Intel Corporation +.. +.. SPDX-License-Identifier: CC-BY-4.0 + +.. _onemkl_device_rng_skip_ahead: + +skip_ahead +========== + +.. rubric:: Description + +Proceed state of engine by the skip-ahead method. + +The ``skip_ahead`` function supports the following interfaces to apply the skip-ahead method: + +- Common interface +- Interface with a partitioned number of skipped elements + + +skip_ahead +---------- + +.. rubric:: Common Interface + + +.. code-block:: cpp + + namespace oneapi::mkl::rng::device { + template + void skip_ahead (Engine& engine, std::uint64_t num_to_skip) + } + +.. container:: section + + .. rubric:: Template Parameters + + Engine + Object of engine class, which supports the block-splitting method. + +.. container:: section + + .. rubric:: Input Parameters + + engine + Engine which state would be skipped. + + num_to_skip + Number of skipped elements. + + +.. rubric:: Interface with a partitioned number of skipped elements + +.. code-block:: cpp + + namespace oneapi::mkl::rng::device { + template + void skip_ahead (Engine& engine, std::initializer_list num_to_skip) + } + +.. container:: section + + .. rubric:: Template Parameters + + Engine + Object of engine class, which supports the block-splitting method. + +.. container:: section + + .. rubric:: Input Parameters + + engine + Engine which state would be skipped. + + num_to_skip + Partitioned number of skipped elements. The total number of skipped elements + would be: :math:`num\_to\_skip[0] + num\_to\_skip[1] \cdot 2^{64} + ... + + num\_to\_skip[1] \cdot 2^{64 (n - 1)}`, where `n` is a number of elements in `num_to_skip` list. + +**Parent topic:** :ref:`onemkl_device_rng_service_routines` diff --git a/source/elements/oneMKL/source/domains/rng/device_api/device-rng-uniform-bits.rst b/source/elements/oneMKL/source/domains/rng/device_api/device-rng-uniform-bits.rst new file mode 100644 index 0000000000..56bc8cf7d2 --- /dev/null +++ b/source/elements/oneMKL/source/domains/rng/device_api/device-rng-uniform-bits.rst @@ -0,0 +1,64 @@ +.. SPDX-FileCopyrightText: 2023 Intel Corporation +.. +.. SPDX-License-Identifier: CC-BY-4.0 + +.. _onemkl_device_rng_uniform_bits: + +uniform_bits +============ + +Generates uniformly distributed bits in 32/64-bit chunks. + +.. rubric:: Description + +The ``uniform_bits`` class object is used in ``generate`` and function to generate uniformly distributed bits +in 32/64-bit chunks. It is designed to ensure each bit in the 32/64-bit chunk is uniformly distributed. This distribution +is supported for philox4x32x10 and mcg59 engines. When generating 64-bit chunks, twice as much engine offset needs to +be provided. + +``UIntType`` denotes the chunk size and can be ``std::uint32_t``, ``std::uint64_t``. See :ref:`VS Notes` for details. + + +class uniform_bits +------------------ + +.. rubric:: Syntax + +.. code-block:: cpp + + namespace oneapi::mkl::rng::device { + template + class uniform_bits { + using result_type = UIntType; + }; + } + + +.. container:: section + + .. rubric:: Template parameters + + .. container:: section + + typename UIntType + Type of the produced values. Supported types: + * ``std::uint32_t`` + * ``std::uint64_t`` + +.. container:: section + + .. rubric:: Member types + + .. container:: section + + .. code-block:: cpp + + uniform_bits::result_type = UIntType + + .. container:: section + + .. rubric:: Description + + The type which defines type of generated random numbers. + +**Parent topic:** :ref:`onemkl_device_rng_distributions` diff --git a/source/elements/oneMKL/source/domains/rng/device_api/device-rng-uniform-continuous.rst b/source/elements/oneMKL/source/domains/rng/device_api/device-rng-uniform-continuous.rst new file mode 100644 index 0000000000..ef218522cf --- /dev/null +++ b/source/elements/oneMKL/source/domains/rng/device_api/device-rng-uniform-continuous.rst @@ -0,0 +1,208 @@ +.. SPDX-FileCopyrightText: 2023 Intel Corporation +.. +.. SPDX-License-Identifier: CC-BY-4.0 + +.. _onemkl_device_rng_uniform_continuous: + +uniform (Continuous) +==================== + + +Generates random numbers with uniform distribution. + +.. rubric:: Description + +The class object is used in ``generate`` function to provide random numbers uniformly +distributed over the interval [``a``, ``b``), where ``a``, ``b`` are the left and right bounds of the interval, +respectively, and :math:`a, b \in R ; a < b` +``a``, ``b∈R`` ; ``a`` < ``b``. + + +The probability density function is given by: + +.. math:: + + f_{a, b}(x) = + \begin{cases} + \frac{1}{b-a}, & x \in [a, b)\\ + 1, & x \notin [a, b) \end{cases}, -\infty < x < +\infty + +The cumulative distribution function is as follows: + + +.. math:: + + F_{a, b}(x) = + \begin{cases} + 0, & x < a \\ + \frac{x-a}{b-a}, & a \leq x < b \\ + 1, & x \geq b + \end{cases}, + -\infty < x < +\infty + + +class uniform +------------- + +.. rubric:: Syntax + +.. code-block:: cpp + + namespace oneapi::mkl::rng::device { + template + class uniform { + public: + using method_type = Method; + using result_type = Type; + + uniform(); + explicit uniform(Type a, Type b); + + Type a() const; + Type b() const; + }; + } + + +.. container:: section + + .. rubric:: Template parameters + + .. container:: section + + typename RealType + Type of the produced values. Supported types: + + * ``float`` + * ``double`` + + .. container:: section + + typename Method + Generation method. The specific values are as follows: + + * ``oneapi::mkl::rng::device::uniform_method::by_default`` + * ``oneapi::mkl::rng::device::uniform_method::standard`` + * ``oneapi::mkl::rng::device::uniform_method::accurate`` + + See description of the methods in :ref:`Distributions methods template parameter` + + +.. container:: section + + .. rubric:: Class Members + + .. list-table:: + :header-rows: 1 + + * - Routine + - Description + * - `uniform()`_ + - Default constructor + * - `explicit uniform(RealType a, RealType b)`_ + - Constructor with parameters + * - `RealType a() const`_ + - Method to obtain left bound `a` + * - `RealType b() const`_ + - Method to obtain right bound `b` + +.. container:: section + + .. rubric:: Member types + + .. container:: section + + .. code-block:: cpp + + uniform::method_type = Method + + .. container:: section + + .. rubric:: Description + + The type which defines transformation method for generation. + + .. container:: section + + .. code-block:: cpp + + uniform::result_type = RealType + + .. container:: section + + .. rubric:: Description + + The type which defines type of generated random numbers. + +.. container:: section + + .. rubric:: Constructors + + .. container:: section + + .. _`uniform()`: + + .. code-block:: cpp + + uniform::uniform() + + .. container:: section + + .. rubric:: Description + + Default constructor for distribution, parameters set as `a` = 0.0, `b` = 1.0. + + .. container:: section + + .. _`explicit uniform(RealType a, RealType b)`: + + .. code-block:: cpp + + explicit uniform::uniform(RealType a, RealType b) + + .. container:: section + + .. rubric:: Description + + Constructor with parameters. `a` is a left bound, `b` is a right bound, assume :math:`a < b`. + + .. container:: section + + .. rubric:: Throws + + oneapi::mkl::invalid_argument + Exception is thrown when :math:`a \ge b` + +.. container:: section + + .. rubric:: Characteristics + + .. container:: section + + .. _`RealType a() const`: + + .. code-block:: cpp + + RealType uniform::a() const + + .. container:: section + + .. rubric:: Return Value + + Returns the distribution parameter `a` - left bound. + + .. container:: section + + .. _`RealType b() const`: + + .. code-block:: cpp + + RealType uniform::b() const + + .. container:: section + + .. rubric:: Return Value + + Returns the distribution parameter `b` - right bound. + +**Parent topic:** :ref:`onemkl_device_rng_distributions` diff --git a/source/elements/oneMKL/source/domains/rng/device_api/device-rng-uniform-discrete.rst b/source/elements/oneMKL/source/domains/rng/device_api/device-rng-uniform-discrete.rst new file mode 100644 index 0000000000..aa55315a8e --- /dev/null +++ b/source/elements/oneMKL/source/domains/rng/device_api/device-rng-uniform-discrete.rst @@ -0,0 +1,177 @@ +.. SPDX-FileCopyrightText: 2023 Intel Corporation +.. +.. SPDX-License-Identifier: CC-BY-4.0 + +.. _onemkl_device_rng_uniform_discrete: + +uniform (Discrete) +================== + + +Generates random numbers uniformly distributed over the interval ``[a, b)``. + +.. rubric:: Description + +The ``uniform`` class object is used in ``generate`` and function +to provide random numbers uniformly distributed over the interval ``[a, b)``, where ``a, b`` are the left and right +bounds of the interval respectively, and :math:`a, b \in Z ; a < b`. + + +The probability distribution is given by: + +.. math:: + + P(X = k) = \frac{1}{b-a}, + k \in \{a, a + 1, \ldots, b-1\} + +The cumulative distribution function is as follows: + +.. math:: + + F_{a, b}(x) = + \begin{cases} + 0, & x < a \\ + \frac{x-a + 1}{b-a}, & a \leq x < b \\ + 1, & x \geq b + \end{cases}, + x \in R + + +class uniform +------------- + +.. rubric:: Syntax + +.. code-block:: cpp + + namespace oneapi::mkl::rng::device { + template + class uniform { + public: + using method_type = Method; + using result_type = Type; + + uniform(); + explicit uniform(Type a, Type b); + + Type a() const; + Type b() const; + }; + } + + +.. container:: section + + .. rubric:: Template parameters + + .. container:: section + + typename Type + Type of the produced values. Supported types: + + * ``std::int32_t`` + * ``std::uint32_t`` + + .. container:: section + + typename Method = oneapi::mkl::rng::uniform_method::by_default + Transformation method, which will be used for generation. Supported types: + + * ``oneapi::mkl::rng::device::uniform_method::by_default`` + * ``oneapi::mkl::rng::device::uniform_method::standard`` + * ``oneapi::mkl::rng::device::uniform_method::accurate`` + + See description of the methods in :ref:`Distributions methods template parameter`. + + +.. container:: section + + .. rubric:: Class Members + + .. list-table:: + :header-rows: 1 + + * - Routine + - Description + * - `uniform()`_ + - Default constructor + * - `explicit uniform(Type a, Type b)`_ + - Constructor with parameters + * - `Type a() const`_ + - Method to obtain left bound `a` + * - `Type b() const`_ + - Method to obtain right bound `b` + +.. container:: section + + .. rubric:: Constructors + + .. container:: section + + .. _`uniform()`: + + .. code-block:: cpp + + uniform::uniform() + + .. container:: section + + .. rubric:: Description + + Default constructor for distribution, parameters set as `a` = 0, `b` = (1 << 23) with ``uniform_method::standard`` + or std::numeric_limits::max() with ``uniform_method::accurate``. + + .. container:: section + + .. _`explicit uniform(Type a, Type b)`: + + .. code-block:: cpp + + explicit uniform::uniform(Type a, Type b) + + .. container:: section + + .. rubric:: Description + + Constructor with parameters. `a` is a left bound, `b` is a right bound, assume :math:`a < b`. + + .. container:: section + + .. rubric:: Throws + + oneapi::mkl::invalid_argument + Exception is thrown when :math:`a \ge b` + +.. container:: section + + .. rubric:: Characteristics + + .. container:: section + + .. _`Type a() const`: + + .. code-block:: cpp + + uniform::a() const + + .. container:: section + + .. rubric:: Return Value + + Returns the distribution parameter `a` - left bound. + + .. container:: section + + .. _`Type b() const`: + + .. code-block:: cpp + + uniform::b() const + + .. container:: section + + .. rubric:: Return Value + + Returns the distribution parameter `b` - right bound. + +**Parent topic:** :ref:`onemkl_device_rng_distributions` diff --git a/source/elements/oneMKL/source/domains/rng/device_api/device-rng-usage-model.rst b/source/elements/oneMKL/source/domains/rng/device_api/device-rng-usage-model.rst new file mode 100644 index 0000000000..15c65c6631 --- /dev/null +++ b/source/elements/oneMKL/source/domains/rng/device_api/device-rng-usage-model.rst @@ -0,0 +1,77 @@ +.. SPDX-FileCopyrightText: 2023 Intel Corporation +.. +.. SPDX-License-Identifier: CC-BY-4.0 + +.. _onemkl_device_rng_usage_model: + +oneMKL RNG Device Usage Model +============================= + +.. contents:: + :local: + :depth: 1 + +A typical usage model for device routines is the same as described in +:ref:`onemkl_rng_usage_model`: + + +#. Create and initialize the object for basic random number generator. + +#. Create and initialize the object for distribution generator. + +#. Call the generate routine to get random numbers with appropriate statistical distribution. + + +Example of Scalar Random Numbers Generation +------------------------------------------- + +.. code-block:: cpp + + #include "oneapi/mkl/rng/device.hpp" + + int main() { + sycl::queue q; + // Prepare a memory for random numbers + // Submit a kernel to generate on device + q.submit([&](sycl::handler& cgh) { + // ... + cgh.parallel_for(n, [=](size_t idx) { + // Create an engine object + oneapi::mkl::rng::device::philox4x32x10<> engine(seed, idx); + // Create a distribution object + oneapi::mkl::rng::device::uniform distr; + // Call generate function to obtain scalar random number + float res = oneapi::mkl::rng::device::generate(distr, engine); + // ... + }); + }); + // ... + } + +Example of Vector Random Numbers Generation +------------------------------------------- + +.. code-block:: cpp + + #include "oneapi/mkl/rng/device.hpp" + + int main() { + sycl::queue q; + // Prepare an array for random numbers + // Submit a kernel to generate on device + q.submit([&](sycl::handler& cgh) { + // ... + cgh.parallel_for((n / vec_size), [=](size_t idx) { + // Create an engine object + oneapi::mkl::rng::device::philox4x32x10 engine(seed, idx * vec_size); + // Create a distribution object + oneapi::mkl::rng::device::uniform distr; + // Call generate function to obtain random numbers + sycl::vec res = oneapi::mkl::rng::device::generate(distr, engine); + // ... + }); + }); + // ... + } + +**Parent topic:** :ref:`onemkl_device_rng_routines` diff --git a/source/elements/oneMKL/source/domains/rng/device_api/device-routines.rst b/source/elements/oneMKL/source/domains/rng/device_api/device-routines.rst new file mode 100644 index 0000000000..16e7d7664e --- /dev/null +++ b/source/elements/oneMKL/source/domains/rng/device_api/device-routines.rst @@ -0,0 +1,62 @@ +.. SPDX-FileCopyrightText: 2023 Intel Corporation +.. +.. SPDX-License-Identifier: CC-BY-4.0 + +.. _onemkl_device_rng_routines: + +Random Number Generators Device Routines +======================================== + +The main purpose of Device routines is to make them callable from your SYCL kernels; however, there are no limitations to be called from the Host. For example: + +.. code-block:: + + sycl::queue queue; + + queue.submit([&](sycl::handler& cgh) { + cgh.parallel_for(range,[=](...) { + oneapi::mkl::rng::device::routine(...); // calling routine from user's kernel code + }); + }); + + oneapi::mkl::rng::device::routine(...); // calling routine from host + +.. rubric:: Structure + +RNG domain contains two classes types: + + - Engines (basic random number generators) classes, which holds + the state of generator and is a source of independent and identically distributed random variables. + Refer to :ref:`onemkl_rng_engines_basic_random_number_generators` + for a detailed description. + - Distribution classes templates (transformation classes) for different types of statistical + distributions, for example, uniform, normal (Gaussian), binomial, + etc. These classes contain all of the distribution’s parameters + (including generation method). Refer to :ref:`onemkl_device_rng_distributions` for + a detailed description of the distributions. + +The RNG domain also contains two types of free functions: + + - Generation routines. The current routines are used to obtain random + numbers from a given engine with proper statistics defined by a + given distribution. Refer to the :ref:`onemkl_device_rng_generate_routines` + section for a detailed description. + - Service routines. The routines are used to modify the engine state. Refer to :ref:`onemkl_device_rng_service_routines` for a + description of these routines. + + +Engine classes work with both generation and service routines. Distribution classes are used in +generation routines only. Refer to the :ref:`onemkl_device_rng_usage_model` +section for the description of typical RNG scenario. + +.. toctree:: + :hidden: + + device-rng-usage-model.rst + device-rng-generate-routines.rst + device-engines.rst + device-distributions.rst + device-service-routines.rst + ../bibliography.rst + +**Parent topic:** :ref:`onemkl_rng` diff --git a/source/elements/oneMKL/source/domains/rng/device_api/device-service-routines.rst b/source/elements/oneMKL/source/domains/rng/device_api/device-service-routines.rst new file mode 100644 index 0000000000..cf04188904 --- /dev/null +++ b/source/elements/oneMKL/source/domains/rng/device_api/device-service-routines.rst @@ -0,0 +1,27 @@ +.. SPDX-FileCopyrightText: 2023 Intel Corporation +.. +.. SPDX-License-Identifier: CC-BY-4.0 + +.. _onemkl_device_rng_service_routines: + +Device Service Routines +======================= + +.. tabularcolumns:: |\Y{0.4}|\Y{0.6}| + +.. list-table:: + :header-rows: 1 + + * - Routine + - Description + + * - :ref:`onemkl_device_rng_skip_ahead` + - Proceed state of engine by the skip-ahead method to skip a given number of elements from the original sequence. + +.. toctree:: + :maxdepth: 1 + :hidden: + + device-rng-skip-ahead.rst + +**Parent topic:** :ref:`onemkl_device_rng_routines` \ No newline at end of file diff --git a/source/elements/oneMKL/source/domains/rng/distributions-template-parameter-mkl-rng-method-values.rst b/source/elements/oneMKL/source/domains/rng/host_api/distributions-template-parameter-mkl-rng-method-values.rst similarity index 100% rename from source/elements/oneMKL/source/domains/rng/distributions-template-parameter-mkl-rng-method-values.rst rename to source/elements/oneMKL/source/domains/rng/host_api/distributions-template-parameter-mkl-rng-method-values.rst diff --git a/source/elements/oneMKL/source/domains/rng/distributions.rst b/source/elements/oneMKL/source/domains/rng/host_api/distributions.rst similarity index 97% rename from source/elements/oneMKL/source/domains/rng/distributions.rst rename to source/elements/oneMKL/source/domains/rng/host_api/distributions.rst index d8f0003577..8308f0783b 100644 --- a/source/elements/oneMKL/source/domains/rng/distributions.rst +++ b/source/elements/oneMKL/source/domains/rng/host_api/distributions.rst @@ -4,8 +4,8 @@ .. _onemkl_rng_distributions: -Distributions -============= +Host Distributions +================== .. container:: @@ -23,8 +23,7 @@ Distributions generator routines and the basic random number generators. - _`Table Continuous Distribution Generators` - + _`Table Continuous Distribution Generators` .. container:: tablenoborder @@ -62,7 +61,8 @@ Distributions - Normal Multivariate (Gaussian Multivariate) distribution - _`Table Discrete Distribution Generators` + _`Table Discrete Distribution Generators` + .. container:: tablenoborder @@ -142,7 +142,7 @@ Distributions * - \ :ref:`onemkl_rng_beta`\ - `oneapi::mkl::rng::beta_method::cja_accurate`   - **Parent topic:** :ref:`onemkl_rng` + **Parent topic:** :ref:`onemkl_rng_manual_offload_routines` diff --git a/source/elements/oneMKL/source/domains/rng/engines-basic-random-number-generators.rst b/source/elements/oneMKL/source/domains/rng/host_api/engines-basic-random-number-generators.rst similarity index 97% rename from source/elements/oneMKL/source/domains/rng/engines-basic-random-number-generators.rst rename to source/elements/oneMKL/source/domains/rng/host_api/engines-basic-random-number-generators.rst index 30c74467f1..5b4b6a2ce6 100644 --- a/source/elements/oneMKL/source/domains/rng/engines-basic-random-number-generators.rst +++ b/source/elements/oneMKL/source/domains/rng/host_api/engines-basic-random-number-generators.rst @@ -4,8 +4,8 @@ .. _onemkl_rng_engines_basic_random_number_generators: -Engines (Basic Random Number Generators) -======================================== +Host Engines (Basic Random Number Generators) +============================================= .. container:: @@ -72,7 +72,7 @@ Engines (Basic Random Number Generators) [:ref:`Coddington94 `]. - **Parent topic:** :ref:`onemkl_rng` + **Parent topic:** :ref:`onemkl_rng_manual_offload_routines` .. container:: diff --git a/source/elements/oneMKL/source/domains/rng/generate-routine.rst b/source/elements/oneMKL/source/domains/rng/host_api/generate-routine.rst similarity index 76% rename from source/elements/oneMKL/source/domains/rng/generate-routine.rst rename to source/elements/oneMKL/source/domains/rng/host_api/generate-routine.rst index cf61652199..8c43e955c7 100644 --- a/source/elements/oneMKL/source/domains/rng/generate-routine.rst +++ b/source/elements/oneMKL/source/domains/rng/host_api/generate-routine.rst @@ -4,8 +4,8 @@ .. _onemkl_rng_generate_routine: -Generate Routine -================ +Host Generate Routine +===================== .. container:: @@ -14,7 +14,7 @@ Generate Routine Entry point to obtain random numbers from a given engine with proper statistics of a given distribution. - **Parent topic:** :ref:`onemkl_rng` + **Parent topic:** :ref:`onemkl_rng_manual_offload_routines` .. toctree:: :hidden: diff --git a/source/elements/oneMKL/source/domains/rng/mkl-rng-ars5.rst b/source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-ars5.rst similarity index 100% rename from source/elements/oneMKL/source/domains/rng/mkl-rng-ars5.rst rename to source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-ars5.rst diff --git a/source/elements/oneMKL/source/domains/rng/mkl-rng-bernoulli.rst b/source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-bernoulli.rst similarity index 100% rename from source/elements/oneMKL/source/domains/rng/mkl-rng-bernoulli.rst rename to source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-bernoulli.rst diff --git a/source/elements/oneMKL/source/domains/rng/mkl-rng-beta.rst b/source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-beta.rst similarity index 100% rename from source/elements/oneMKL/source/domains/rng/mkl-rng-beta.rst rename to source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-beta.rst diff --git a/source/elements/oneMKL/source/domains/rng/mkl-rng-binomial.rst b/source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-binomial.rst similarity index 100% rename from source/elements/oneMKL/source/domains/rng/mkl-rng-binomial.rst rename to source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-binomial.rst diff --git a/source/elements/oneMKL/source/domains/rng/mkl-rng-bits.rst b/source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-bits.rst similarity index 100% rename from source/elements/oneMKL/source/domains/rng/mkl-rng-bits.rst rename to source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-bits.rst diff --git a/source/elements/oneMKL/source/domains/rng/mkl-rng-cauchy.rst b/source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-cauchy.rst similarity index 100% rename from source/elements/oneMKL/source/domains/rng/mkl-rng-cauchy.rst rename to source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-cauchy.rst diff --git a/source/elements/oneMKL/source/domains/rng/mkl-rng-chi_square.rst b/source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-chi_square.rst similarity index 100% rename from source/elements/oneMKL/source/domains/rng/mkl-rng-chi_square.rst rename to source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-chi_square.rst diff --git a/source/elements/oneMKL/source/domains/rng/mkl-rng-default_engine.rst b/source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-default_engine.rst similarity index 100% rename from source/elements/oneMKL/source/domains/rng/mkl-rng-default_engine.rst rename to source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-default_engine.rst diff --git a/source/elements/oneMKL/source/domains/rng/mkl-rng-exponential.rst b/source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-exponential.rst similarity index 100% rename from source/elements/oneMKL/source/domains/rng/mkl-rng-exponential.rst rename to source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-exponential.rst diff --git a/source/elements/oneMKL/source/domains/rng/mkl-rng-gamma.rst b/source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-gamma.rst similarity index 100% rename from source/elements/oneMKL/source/domains/rng/mkl-rng-gamma.rst rename to source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-gamma.rst diff --git a/source/elements/oneMKL/source/domains/rng/mkl-rng-gaussian.rst b/source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-gaussian.rst similarity index 100% rename from source/elements/oneMKL/source/domains/rng/mkl-rng-gaussian.rst rename to source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-gaussian.rst diff --git a/source/elements/oneMKL/source/domains/rng/mkl-rng-gaussian_mv.rst b/source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-gaussian_mv.rst similarity index 100% rename from source/elements/oneMKL/source/domains/rng/mkl-rng-gaussian_mv.rst rename to source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-gaussian_mv.rst diff --git a/source/elements/oneMKL/source/domains/rng/mkl-rng-generate.rst b/source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-generate.rst similarity index 100% rename from source/elements/oneMKL/source/domains/rng/mkl-rng-generate.rst rename to source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-generate.rst diff --git a/source/elements/oneMKL/source/domains/rng/mkl-rng-geometric.rst b/source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-geometric.rst similarity index 100% rename from source/elements/oneMKL/source/domains/rng/mkl-rng-geometric.rst rename to source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-geometric.rst diff --git a/source/elements/oneMKL/source/domains/rng/mkl-rng-gumbel.rst b/source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-gumbel.rst similarity index 100% rename from source/elements/oneMKL/source/domains/rng/mkl-rng-gumbel.rst rename to source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-gumbel.rst diff --git a/source/elements/oneMKL/source/domains/rng/mkl-rng-hypergeometric.rst b/source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-hypergeometric.rst similarity index 100% rename from source/elements/oneMKL/source/domains/rng/mkl-rng-hypergeometric.rst rename to source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-hypergeometric.rst diff --git a/source/elements/oneMKL/source/domains/rng/mkl-rng-laplace.rst b/source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-laplace.rst similarity index 100% rename from source/elements/oneMKL/source/domains/rng/mkl-rng-laplace.rst rename to source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-laplace.rst diff --git a/source/elements/oneMKL/source/domains/rng/mkl-rng-leapfrog.rst b/source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-leapfrog.rst similarity index 97% rename from source/elements/oneMKL/source/domains/rng/mkl-rng-leapfrog.rst rename to source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-leapfrog.rst index 5f824399c6..b767ec0b66 100644 --- a/source/elements/oneMKL/source/domains/rng/mkl-rng-leapfrog.rst +++ b/source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-leapfrog.rst @@ -76,4 +76,4 @@ leapfrog **Parent topic:** :ref:`onemkl_rng_service_routines` -.. |image0| image:: ../equations/rng-leapfrog.png +.. |image0| image:: ../../equations/rng-leapfrog.png diff --git a/source/elements/oneMKL/source/domains/rng/mkl-rng-lognormal.rst b/source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-lognormal.rst similarity index 100% rename from source/elements/oneMKL/source/domains/rng/mkl-rng-lognormal.rst rename to source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-lognormal.rst diff --git a/source/elements/oneMKL/source/domains/rng/mkl-rng-mcg31m1.rst b/source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-mcg31m1.rst similarity index 100% rename from source/elements/oneMKL/source/domains/rng/mkl-rng-mcg31m1.rst rename to source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-mcg31m1.rst diff --git a/source/elements/oneMKL/source/domains/rng/mkl-rng-mcg59.rst b/source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-mcg59.rst similarity index 100% rename from source/elements/oneMKL/source/domains/rng/mkl-rng-mcg59.rst rename to source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-mcg59.rst diff --git a/source/elements/oneMKL/source/domains/rng/mkl-rng-mrg32k3a.rst b/source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-mrg32k3a.rst similarity index 96% rename from source/elements/oneMKL/source/domains/rng/mkl-rng-mrg32k3a.rst rename to source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-mrg32k3a.rst index a0cbec284d..e72ff80b03 100644 --- a/source/elements/oneMKL/source/domains/rng/mkl-rng-mrg32k3a.rst +++ b/source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-mrg32k3a.rst @@ -72,7 +72,7 @@ class mrg32k3a * - Routine - Description - * - `sycl::queue queue, std::uint32_t seed = default_seed`_ + * - `mrg32k3a(sycl::queue queue, std::uint32_t seed = default_seed)`_ - Constructor for common seed initialization of the engine * - `mrg32k3a(sycl::queue queue, std::initializer_list seed)`_ - Constructor for extended seed initialization of the engine @@ -89,11 +89,11 @@ class mrg32k3a .. rubric:: Constructors - .. _`sycl::queue queue, std::uint32_t seed = default_seed`: + .. _`mrg32k3a(sycl::queue queue, std::uint32_t seed = default_seed)`: .. code-block:: cpp - mrg32k3a::sycl::queue queue, std::uint32_t seed = default_seed + mrg32k3a::mrg32k3a(sycl::queue queue, std::uint32_t seed = default_seed) .. container:: section diff --git a/source/elements/oneMKL/source/domains/rng/mkl-rng-mt19937.rst b/source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-mt19937.rst similarity index 100% rename from source/elements/oneMKL/source/domains/rng/mkl-rng-mt19937.rst rename to source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-mt19937.rst diff --git a/source/elements/oneMKL/source/domains/rng/mkl-rng-mt2203.rst b/source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-mt2203.rst similarity index 100% rename from source/elements/oneMKL/source/domains/rng/mkl-rng-mt2203.rst rename to source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-mt2203.rst diff --git a/source/elements/oneMKL/source/domains/rng/mkl-rng-multinomial.rst b/source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-multinomial.rst similarity index 100% rename from source/elements/oneMKL/source/domains/rng/mkl-rng-multinomial.rst rename to source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-multinomial.rst diff --git a/source/elements/oneMKL/source/domains/rng/mkl-rng-negbinomial.rst b/source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-negbinomial.rst similarity index 100% rename from source/elements/oneMKL/source/domains/rng/mkl-rng-negbinomial.rst rename to source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-negbinomial.rst diff --git a/source/elements/oneMKL/source/domains/rng/mkl-rng-niederreiter.rst b/source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-niederreiter.rst similarity index 100% rename from source/elements/oneMKL/source/domains/rng/mkl-rng-niederreiter.rst rename to source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-niederreiter.rst diff --git a/source/elements/oneMKL/source/domains/rng/mkl-rng-nondeterministic.rst b/source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-nondeterministic.rst similarity index 100% rename from source/elements/oneMKL/source/domains/rng/mkl-rng-nondeterministic.rst rename to source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-nondeterministic.rst diff --git a/source/elements/oneMKL/source/domains/rng/mkl-rng-philox4x32x10.rst b/source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-philox4x32x10.rst similarity index 100% rename from source/elements/oneMKL/source/domains/rng/mkl-rng-philox4x32x10.rst rename to source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-philox4x32x10.rst diff --git a/source/elements/oneMKL/source/domains/rng/mkl-rng-poisson.rst b/source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-poisson.rst similarity index 100% rename from source/elements/oneMKL/source/domains/rng/mkl-rng-poisson.rst rename to source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-poisson.rst diff --git a/source/elements/oneMKL/source/domains/rng/mkl-rng-poisson_v.rst b/source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-poisson_v.rst similarity index 100% rename from source/elements/oneMKL/source/domains/rng/mkl-rng-poisson_v.rst rename to source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-poisson_v.rst diff --git a/source/elements/oneMKL/source/domains/rng/mkl-rng-r250.rst b/source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-r250.rst similarity index 100% rename from source/elements/oneMKL/source/domains/rng/mkl-rng-r250.rst rename to source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-r250.rst diff --git a/source/elements/oneMKL/source/domains/rng/mkl-rng-rayleigh.rst b/source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-rayleigh.rst similarity index 100% rename from source/elements/oneMKL/source/domains/rng/mkl-rng-rayleigh.rst rename to source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-rayleigh.rst diff --git a/source/elements/oneMKL/source/domains/rng/mkl-rng-sfmt19937.rst b/source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-sfmt19937.rst similarity index 100% rename from source/elements/oneMKL/source/domains/rng/mkl-rng-sfmt19937.rst rename to source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-sfmt19937.rst diff --git a/source/elements/oneMKL/source/domains/rng/mkl-rng-skip_ahead.rst b/source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-skip_ahead.rst similarity index 96% rename from source/elements/oneMKL/source/domains/rng/mkl-rng-skip_ahead.rst rename to source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-skip_ahead.rst index 553ff483d6..f975421867 100644 --- a/source/elements/oneMKL/source/domains/rng/mkl-rng-skip_ahead.rst +++ b/source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-skip_ahead.rst @@ -108,7 +108,7 @@ skip_ahead (Interface with a partitioned number of skipped elements) oneapi::mkl::rng::mrg32k3a engine_1(queue, seed); // To skip 2^64 elements in the random stream number of skipped elements should be - /represented as num_to_skip = 2^64 = 0 + 1 * 2^64 + // represented as num_to_skip = 2^64 = 0 + 1 * 2^64 std::initializer_list num_to_skip = {0, 1}; // Creating the 2nd engine based on 1st. Skipping by 2^64 @@ -118,4 +118,4 @@ skip_ahead (Interface with a partitioned number of skipped elements) **Parent topic:** :ref:`onemkl_rng_service_routines` -.. |image0| image:: ../equations/rng-skip-ahead.png +.. |image0| image:: ../../equations/rng-skip-ahead.png diff --git a/source/elements/oneMKL/source/domains/rng/mkl-rng-sobol.rst b/source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-sobol.rst similarity index 100% rename from source/elements/oneMKL/source/domains/rng/mkl-rng-sobol.rst rename to source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-sobol.rst diff --git a/source/elements/oneMKL/source/domains/rng/mkl-rng-uniform-continuous.rst b/source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-uniform-continuous.rst similarity index 100% rename from source/elements/oneMKL/source/domains/rng/mkl-rng-uniform-continuous.rst rename to source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-uniform-continuous.rst diff --git a/source/elements/oneMKL/source/domains/rng/mkl-rng-uniform-discrete.rst b/source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-uniform-discrete.rst similarity index 100% rename from source/elements/oneMKL/source/domains/rng/mkl-rng-uniform-discrete.rst rename to source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-uniform-discrete.rst diff --git a/source/elements/oneMKL/source/domains/rng/mkl-rng-uniform_bits.rst b/source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-uniform_bits.rst similarity index 100% rename from source/elements/oneMKL/source/domains/rng/mkl-rng-uniform_bits.rst rename to source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-uniform_bits.rst diff --git a/source/elements/oneMKL/source/domains/rng/mkl-rng-weibull.rst b/source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-weibull.rst similarity index 100% rename from source/elements/oneMKL/source/domains/rng/mkl-rng-weibull.rst rename to source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-weibull.rst diff --git a/source/elements/oneMKL/source/domains/rng/mkl-rng-wichmann_hill.rst b/source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-wichmann_hill.rst similarity index 100% rename from source/elements/oneMKL/source/domains/rng/mkl-rng-wichmann_hill.rst rename to source/elements/oneMKL/source/domains/rng/host_api/mkl-rng-wichmann_hill.rst diff --git a/source/elements/oneMKL/source/domains/rng/host_api/onemkl-rng-usage-model.rst b/source/elements/oneMKL/source/domains/rng/host_api/onemkl-rng-usage-model.rst new file mode 100644 index 0000000000..ad62a589e9 --- /dev/null +++ b/source/elements/oneMKL/source/domains/rng/host_api/onemkl-rng-usage-model.rst @@ -0,0 +1,68 @@ +.. SPDX-FileCopyrightText: 2019-2020 Intel Corporation +.. +.. SPDX-License-Identifier: CC-BY-4.0 + +.. _onemkl_rng_usage_model: + +oneMKL RNG Host Usage Model +=========================== + + +.. rubric:: Description + +A typical algorithm for random number generators is as follows: + +1. Create and initialize the object for basic random number generator. + + - Use the `skip_ahead` or `leapfrog` function if it is required (used in parallel with random number generation for Host and CPU devices). + +2. Create and initialize the object for distribution generator. + +3. Call the generate routine to get random numbers with appropriate statistical distribution. + +The following example demonstrates random numbers generation with PHILOX4X32X10 basic generator (engine). + +Buffer-based example +-------------------- + +.. code-block:: cpp + + #include "oneapi/mkl/rng.hpp" + + int main() { + sycl::queue q; + + // Create the random number generator object + oneapi::mkl::rng::philox4x32x10 engine(q, seed); + // Create the distribution object + oneapi::mkl::rng::gaussian distr(5.0, 2.0); + // Fill the SYCL buffer with random numbers + oneapi::mkl::rng::generate(distr, engine, n, sycl_buffer); + + // ... + } + + +USM-based example +----------------- + +.. code-block:: cpp + + #include "oneapi/mkl/rng.hpp" + + int main() { + sycl::queue q; + + // Create the random number generator object + oneapi::mkl::rng::philox4x32x10 engine(q, seed); + // Create the distribution object + oneapi::mkl::rng::gaussian distr(5.0, 2.0); + // Fill the USM memory under the pointer with random numbers + auto event = oneapi::mkl::rng::generate(distr, engine, n, usm_ptr); + // ... + // wait until generation is finalized + event.wait(); + // ... + } + +**Parent topic:** :ref:`onemkl_rng_manual_offload_routines` diff --git a/source/elements/oneMKL/source/domains/rng/host_api/rng-host-routines.rst b/source/elements/oneMKL/source/domains/rng/host_api/rng-host-routines.rst new file mode 100644 index 0000000000..0531602019 --- /dev/null +++ b/source/elements/oneMKL/source/domains/rng/host_api/rng-host-routines.rst @@ -0,0 +1,48 @@ +.. SPDX-FileCopyrightText: 2019-2020 Intel Corporation +.. +.. SPDX-License-Identifier: CC-BY-4.0 + +.. _onemkl_rng_manual_offload_routines: + +Random Number Generators Host Routines +====================================== + +.. rubric:: Structure + +RNG domain contains two classes types: + + - Engines (basic random number generators) classes, which holds + the state of generator and is a source of independent and identically distributed random variables. + Refer to :ref:`onemkl_rng_engines_basic_random_number_generators` + for a detailed description. + - Distribution classes templates (transformation classes) for different types of statistical + distributions, for example, uniform, normal (Gaussian), binomial, + etc. These classes contain all of the distribution’s parameters + (including generation method). Refer to :ref:`onemkl_rng_distributions` for + a detailed description of the distributions. + +The RNG domain also contains two types of free functions: + + - Generation routines. The current routines are used to obtain random + numbers from a given engine with proper statistics defined by a + given distribution. Refer to the :ref:`onemkl_rng_generate_routine` + section for a detailed description. + - Service routines. The routines are used to modify the engine state. Refer to :ref:`onemkl_rng_service_routines` for a + description of these routines. + + +Engine classes work with both generation and service routines. Distribution classes are used in +generation routines only. Refer to the :ref:`onemkl_rng_usage_model` +section for the description of typical RNG scenario. + +.. toctree:: + :hidden: + + onemkl-rng-usage-model.rst + generate-routine.rst + engines-basic-random-number-generators.rst + service-routines.rst + distributions.rst + ../bibliography.rst + +**Parent topic:** :ref:`onemkl_rng` \ No newline at end of file diff --git a/source/elements/oneMKL/source/domains/rng/service-routines.rst b/source/elements/oneMKL/source/domains/rng/host_api/service-routines.rst similarity index 86% rename from source/elements/oneMKL/source/domains/rng/service-routines.rst rename to source/elements/oneMKL/source/domains/rng/host_api/service-routines.rst index 78d412f3e4..08c0c072d1 100644 --- a/source/elements/oneMKL/source/domains/rng/service-routines.rst +++ b/source/elements/oneMKL/source/domains/rng/host_api/service-routines.rst @@ -4,8 +4,8 @@ .. _onemkl_rng_service_routines: -Service Routines -================ +Host Service Routines +===================== .. container:: @@ -26,7 +26,7 @@ Service Routines - **Parent topic:** :ref:`onemkl_rng` + **Parent topic:** :ref:`onemkl_rng_manual_offload_routines` .. toctree:: :hidden: diff --git a/source/elements/oneMKL/source/domains/rng/onemkl-rng-overview.rst b/source/elements/oneMKL/source/domains/rng/onemkl-rng-overview.rst index 7fbcd4bb8a..ddf440a33c 100755 --- a/source/elements/oneMKL/source/domains/rng/onemkl-rng-overview.rst +++ b/source/elements/oneMKL/source/domains/rng/onemkl-rng-overview.rst @@ -35,42 +35,21 @@ In computational statistics, random variate generation is usually made in two st in order to generate (or imitate) random variates and random vectors from arbitrary distributions. -.. rubric:: Structure -RNG domain contains two classes types: +.. rubric:: Execution Models - - Engines (basic random number generators) classes, which holds - the state of generator and is a source of i.i.d. random. Refer to - :ref:`onemkl_rng_engines_basic_random_number_generators` - for a detailed description. - - Distribution classes templates (transformation classes) for different types of statistical - distributions, for example, uniform, normal (Gaussian), binomial, - etc. These classes contain all of the distribution’s parameters - (including generation method). Refer to :ref:`onemkl_rng_distributions` for - a detailed description of the distributions. +RNG domain supports two execution models: -The RNG domain also contains two types of free functions: + #. :ref:`Host API`, which is aligned with the rest of oneMKL domains + :ref:`oneMKL domains`. + #. :ref:`Device API`, which is specific for RNG domain. These APIs + are designed to be callable from the User's kernels as well as Host code. - - Generation routines. The current routines are used to obtain random - numbers from a given engine with proper statistics defined by a - given distribution. Refer to the :ref:`onemkl_rng_generate_routine` - section for a detailed description. - - Service routines. The routines are used to modify the engine state. Refer to :ref:`onemkl_rng_service_routines` for a - description of these routines. - - -Engine classes work with both generation and service routines. Distribution classes are used in -generation routines only. Refer to the :ref:`onemkl_rng_usage_model` -section for the description of typical RNG scenario. .. toctree:: :hidden: - onemkl-rng-usage-model.rst - generate-routine.rst - engines-basic-random-number-generators.rst - service-routines.rst - distributions.rst - bibliography.rst + host_api/rng-host-routines.rst + device_api/device-routines.rst -**Parent topic:** :ref:`onemkl_rng` \ No newline at end of file +**Parent topic:** :ref:`onemkl_rng` diff --git a/source/elements/oneMKL/source/domains/rng/onemkl-rng-usage-model.rst b/source/elements/oneMKL/source/domains/rng/onemkl-rng-usage-model.rst deleted file mode 100644 index 72a38a00b0..0000000000 --- a/source/elements/oneMKL/source/domains/rng/onemkl-rng-usage-model.rst +++ /dev/null @@ -1,111 +0,0 @@ -.. SPDX-FileCopyrightText: 2019-2020 Intel Corporation -.. -.. SPDX-License-Identifier: CC-BY-4.0 - -.. _onemkl_rng_usage_model: - -oneMKL RNG Usage Model -====================== - - -.. rubric:: Description - -A typical algorithm for random number generators is as follows: - -1. Create and initialize the object for basic random number generator. - - - Use the `skip_ahead` or `leapfrog` function if it is required (used in parallel with random number generation for Host and CPU devices). - -2. Create and initialize the object for distribution generator. - -3. Call the generate routine to get random numbers with appropriate statistical distribution. - -The following example demonstrates generation of random numbers that -is output of basic generator (engine) PHILOX4X32X10. The seed is -equal to 777. The generator is used to generate 10,000 normally -distributed random numbers with parameters ``a`` = 5 and ``sigma``\ = -2. The purpose of the example is to calculate the sample mean for -normal distribution with the given parameters. - -Buffer-based example --------------------- - -.. code-block:: cpp - - #include - #include - - #include "CL/sycl.hpp" - #include "oneapi/mkl/rng.hpp" - - int main() { - sycl::queue queue; - const size_t n = 10000; - const std::uint64_t seed = 777; - std::vector r(n); - - oneapi::mkl::rng::philox4x32x10 engine(queue, seed); // basic random number generator object - oneapi::mkl::rng::gaussian distr(5.0, 2.0); // distribution object - - { - //create buffer for random numbers - sycl::buffer r_buf(r.data(), r.size()); - oneapi::mkl::rng::generate(distr, engine, n, r_buf); // perform generation - } - - double s = 0.0; - for(int i = 0; i < n; i++) { - s += r[i]; - } - s /= n; - - std::cout << "Average = " << s << std::endl; - return 0; - } - - -USM-based example ------------------ - -.. code-block:: cpp - - #include - #include - - #include "CL/sycl.hpp" - #include "oneapi/mkl/rng.hpp" - - int main() { - sycl::queue queue; - const size_t n = 10000; - const std::uint64_t seed = 777; - - // create USM allocator - sycl::usm_allocator allocator(queue.get_context(), queue.get_device()); - - // create vector with USM allocator - std::vector r(n, allocator); - - oneapi::mkl::rng::philox4x32x10 engine(queue, seed); // basic random number generator object - oneapi::mkl::rng::gaussian distr(5.0, 2.0); // distribution object - - auto event = oneapi::mkl::rng::generate(distr, engine, n, r.data()); // perform generation - // sycl::event object is returned by generate function for synchronization - event.wait(); // synchronization can be also done by queue.wait() - - double s = 0.0; - for(int i = 0; i < n; i++) { - s += r[i]; - } - s /= n; - - std::cout << "Average = " << s << std::endl; - return 0; - } - - -.. rubric:: USM usage - -You can also use USM with raw pointers by using the sycl::malloc_shared/malloc_device functions. - -**Parent topic:** :ref:`onemkl_rng`