.. _oneapi-mkl-rng-bernoulli:

oneapi::mkl::rng::bernoulli
===========================


Generates Bernoulli distributed random values.


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

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

The ``oneapi::mkl::rng::bernoulli`` class object is used in the ``oneapi::mkl::rng::generate`` function to provide Bernoulli distributed random numbers with probability ``p`` of a single trial success, where :math:`p \epsilon R; 0 \leq p \leq 1`.


A variate is called Bernoulli distributed, if after a trial it is equal to 1 with probability of success ``p``, and to 0 with probability 1 - ``p``.


The probability distribution is given by:

P(X =1) = p

P(X=0) = 1-p


The cumulative distribution function is as follows:

.. math::

   F_p(x) =
   \begin{cases}
      0, & x < 0 \\
      1 - p, & 0 \leq x < 1, x \in R \\
      1, & x \geq 1
   \end{cases}


.. 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 = bernoulli_method::by_default>
    class bernoulli {
    public:
    using method_type = Method;
    using result_type = IntType;
    bernoulli(): bernoulli(0.5){} explicit bernoulli(float p);
    explicit bernoulli(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: 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::bernoulli_method::by_default``
     -     Generation method. The specific values are as follows:

           ``oneapi::mkl::rng::bernoulli_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.