.. _oneapi-mkl-rng-device-poisson:

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


Generates Poisson distributed random values.


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

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

The ``oneapi::mkl::rng::device::poisson`` class object is used in the ``oneapi::mkl::rng::device::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


API
***


Syntax
------

.. code-block:: cpp


   template<typename IntType, typename Method>
   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);
   };


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

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


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

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

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

       ``std::int32_t``

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

       ``oneapi::mkl::rng::device::poisson_method::devroye``

.. note::
   The Poisson ``oneapi::mkl::rng::device::poisson_method::devroye`` method uses the following underlying methods depending on the lambda parameter:

   - table-lookup method for small lambdas (:math:`\lambda <` 60)
   - Devroye's method [Devroye] for medium lambdas (60 :math:`\leq \lambda <` 1000)
   - Gaussian approximation for huge lambdas (:math:`\lambda \geq`  1000)


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

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

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