.. _oneapi-mkl-rng-poisson:

oneapi::mkl::rng::poisson
=========================

Generates Poisson distributed random values.


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

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

The ``oneapi::mkl::rng::poisson`` class object is used in the ``oneapi::mkl::rng::generate`` function to provide Poisson distributed random numbers with distribution parameter λ, where ``λ∈R; λ > 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


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

   * - Product and Performance Information
   * - Performance varies by use, configuration and other factors. Learn more at `https://www.intel.com/PerformanceIndex <https://www.intel.com/PerformanceIndex>`__. Notice revision #20201201


API
***


Syntax
------

.. code-block:: cpp

   template<typename IntType = std::int32_t, typename Method = poisson_method::by_default>
   class poisson {
   public:
   using method_type = Method;
   using result_type = IntType;
   poisson(): poisson(0.5){} explicit poisson(double lambda);
   explicit poisson(const param_type& pt);
   double lambda() 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: 0

   * - ``typename IntType = std::int32_t``
     - Type of the produced values. The specific values are as follows:

       ``std::int32_t``

       ``std::uint32_t``

   * - ``typename Method =  oneapi::mkl::rng::poisson_method:: by_default``
     - Generation method. The specific values are as follows:

       ``oneapi::mkl::rng::poisson_method::ptpe``

       ``oneapi::mkl::rng::poisson_method::gaussian_icdf_based``

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


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

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

   * -     Name
     -     Type
     -     Description
   * -     lambda
     -     ``double``
     -     Distribution parameter λ.