.. _oneapi-mkl-rng-device-lognormal:

oneapi::mkl::rng::device::lognormal
===================================


Generates lognormally distributed random numbers.


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

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

The ``oneapi::mkl::rng::device::lognormal`` class object is used in the ``oneapi::mkl::rng::device::generate`` function to provide random numbers with average of distribution (``m``, ``a``) and standard deviation (``s``, ``σ``) of subject normal distribution, displacement (``displ``, ``b``), and scalefactor (``scale``, ``β``), where ``a, σ, b, β ∈ R ; σ > 0 , β > 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}


API
***


Syntax
------

.. code-block:: cpp


   template<typename RealType, typename Method>
   class lognormal { public:
   using method_type = Method; using result_type = RealType;
   lognormal(): lognormal((RealType)0.0, (RealType)1.0, (RealType) 0.0,
   (RealType)1.0){} explicit lognormal(RealType m, RealType s, RealType displ =
   (RealType)0.0, RealType scale = (RealType)1.0);

   explicit lognormal(const param_type& pt);
   RealType m() const;
   RealType s() const;
   RealType displ() const;
   RealType scale() const;
   param_type param() const;
   void param(const param_type& pt);
   };


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

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


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

.. list-table::
   :header-rows: 0

   * -  ``typename RealType``
     -  Type of the produced values. The specific values are as follows:

        ``float``

        ``double``
   * -  ``typename Method``
     -  Generation method. The specific values are as follows:


        ``oneapi::mkl::rng::device::lognormal_method::box_muller2``


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

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

   * - Name
     - Type
     - Description
   * - m
     - ``RealType (float, double)``
     - Average ``a`` of the subject normal distribution.
   * - s
     - ``RealType (float, double)``
     - Standard deviation ``σ`` of the subject normal distribution.
   * - displ
     - ``RealType (float, double)``
     - Displacement ``displ``.
   * - scale
     - ``RealType (float, double)``
     - Scalefactor ``scale``.