.. _oneapi-mkl-rng-geometric:

oneapi::mkl::rng::geometric
===========================


Generates geometrically distributed random values.


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

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

The ``oneapi::mkl::rng::geometric`` class object is used in the ``oneapi::mkl::rng::generate`` function to provide geometrically distributed random numbers with probability ``p`` of a single trial success, where ``p∈R; 0 <  p <  1.``

A geometrically distributed variate represents the number of
independent Bernoulli trials preceding the first success. The probability of a single Bernoulli trial success is ``p``.

The probability distribution is given by:

``P``\ (``X`` = ``k``) = ``p``\ ·(1 - ``p``)\ :sup:`k`, ``k``\ ∈
{0,1,2, ... }.

The cumulative distribution function is as follows:

.. math::

   F_p(x) =
   \begin{cases}
      0, & x < 0 \\
      1 - (1-p)^{\lfloor x + 1 \rfloor}, & x \geq 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 = geometric_method::by_default>
   class geometric {
   public:
   using method_type = Method;
   using result_type = IntType;
   geometric(): geometric(0.5){} explicit geometric(float p);
   explicit geometric(const param_type& pt);
   float p() 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 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:: geometric_method:: by_default``
     - Generation method. The specific values are as follows:

       ``oneapi::mkl::rng::geometric_method::icdf``

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


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

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

   * - Name
     - Type
     - Description
   * - p
     - ``float``
     - Success probability ``p`` of a trial.