.. _oneapi-mkl-rng-beta:

oneapi::mkl::rng::beta
======================


Generates beta distributed random values.


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

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

The ``oneapi::mkl::rng::beta`` class object is used in the ``oneapi::mkl::rng::generate`` function to provide random numbers with beta distribution that has shape parameters p and ``q``, displacement ``a``, and scale parameter (``b``, ``β``), where ``p``, ``q``, ``a``, and :math:`\beta \in R ; p > 0, q > 0, \beta > 0`.


The probability density function is given by:

.. math::

   f_{p, q, a, \beta} (x) =
   \begin{cases}
      \frac{1}{B(p, q) \beta^{p+q-1}} (x-a)^{p-1} (\beta + a - x)^{q-1}, & a \leq x < a + \beta \\
      0, & x < a, x \geq a + \beta
   \end{cases},
   - \infty < x < \infty


where ``B``\ (``p``, ``q``) is the complete beta function.


The cumulative distribution function is as follows:


.. math::

   f_{p, q, a, \beta} (x) =
   \begin{cases}
      0, & x < a \\
      \int_a^x
      \frac{1}{B(p, q) \beta^{p+q-1}}
      (y-a)^{p-1} (\beta + a - y)^{q-1}dy, & a \leq x < a + \beta \\
      1, & x \geq a + \beta
   \end{cases},
   - \infty < x < \infty


.. 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 RealType = float,
     typename Method = beta_method::by_default>
     class beta {
     public:
     using method_type = Method; using result_type = RealType;
     beta(): beta((RealType)1.0, (RealType)1.0, (RealType)(0.0),
     (RealType)(1.0)){} explicit beta(RealType p, RealType q, RealType a,
     RealType b);
     explicit beta(const param_type& pt);
     RealType p() const;
     RealType q() const;
     RealType a() const;
     RealType b() 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 RealType = float``
     - Type of the produced values. The specific values are as follows:

       ``float``

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

       ``oneapi::mkl::rng::beta_method::cja``

       ``oneapi::mkl::rng::beta_method::cja_accurate``

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


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

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

   * - Name
     - Type
     - Description
   * - p
     - ``RealType (float, double)``
     -  Shape ``p``
   * - q
     - ``RealType (float, double)``
     -  Shape ``q``
   * - a
     - ``RealType (float, double)``
     - Displacement ``a``.
   * - b
     - \ ``RealType (float, double)``
     - Scalefactor ``b``.