.. _oneapi-mkl-rng-gaussian:

oneapi::mkl::rng::gaussian
==========================


Generates normally distributed random numbers.


.. contents::
    :local:
    :depth: 1

Description
***********

The class object is used in ``oneapi::mkl::rng::generate`` function to provide random numbers with normal (Gaussian) distribution with mean (``a``) and standard deviation (``stddev, σ``), where ``a``, ``σ ∈ R`` ; ``σ`` > 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:`Fa,\sigma (x)` can be expressed in terms of standard normal distribution :math:`\phi(x)` as :math:`Fa, \sigma ( \,x) \, = \phi( \, ( \, x-a) \, / \sigma ) \,`


API
***


Syntax
------

.. code-block:: cpp

   template<typename RealType = float, typename Method = gaussian_method::by_default>
   class gaussian {
   public:
   using method_type = Method;
   using result_type = RealType;
   gaussian(): gaussian(static_cast<RealType>(0.0), static_cast<RealType>(1.0));
   explicit gaussian(RealType mean, RealType stddev);
   explicit gaussian(const param_type& pt);
   RealType mean() const;
   RealType stddev() const;
   param_type param() const;
   void param(const param_type& pt);
   };


Devices supported: Host, CPU, and GPU.


Include Files
-------------

- ``oneapi/mkl/rng.hpp``


Template Parameters
-------------------

.. list-table::
   :header-rows: 1

   * - Name
     - Description
   * - ``typename RealType = float``
     - Type of the produced values. The specific values are as follows: ``float``  ``double``
   * - ``typename Method = ``oneapi::mkl::rng::gaussian_method::by_default``
     - Generation method. The specific values are as follows: ``oneapi::mkl::rng::gaussian_method::box_muller`` ``oneapi::mkl::rng::gaussian_method::box_muller2`` ``oneapi::mkl::rng::gaussian_method::icdf``

       See brief descriptions of the methods in :ref:`distributions-template-parameter-method`.


Input Parameters
----------------

.. list-table::
   :header-rows: 1

   * - Name
     - Type
     - Description
   * - mean
     - ``RealType (float, double)``
     - Mean value ``a``.
   * - stddev
     - ``RealType (float, double)``
     - Standard deviation ``σ``.