.. _oneapi-mkl-rng-multinomial:

oneapi::mkl::rng::multinomial
=============================


Generates multinomially distributed random numbers.


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

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

The ``oneapi::mkl::rng::multinomial`` class object is used in the ``oneapi::mkl::rng::generate`` function to provide multinomially distributed random numbers with ``ntrial`` independent trials and ``k`` possible mutually exclusive outcomes, with corresponding probabilities ``pi``, where ``pi∈R; 0 ≤pi≤ 1, m∈N, k∈N``.


The probability distribution is given by:

.. math::

   P (X_1 = x_1, \ldots, X_k = x_k) =
   \frac
      {m!}
      {\prod_{i=1}^k x_i!}
   \prod_{i=1}^k {p_i}^{x_i},
   0 \leq x_i \leq m,
   \sum_{i=1}^k x_i = m


.. 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 = multinomial_method::by_default>
   class multinomial {
   public:
   using method_type = Method;
   using result_type = IntType;
   explicit multinomial(double ntrial, std::vector<double> p);
   explicit multinomial(const param_type& pt);
   std::int32_t ntrial() const;
   std::vector<double> p() const;
   param_type param() const;
   void param(const param_type& pt);
   };


Devices supported: Host, CPU, and GPU

.. note::
   This distribution only supports input parameters (on GPU) which follow the condition :math:`(k \geq ntrial * 16 \land ntrial \leq 16)`, where ``k`` is the probability vector length.


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::multinomial_method:: by_default``
     -     Generation method. The specific values are as follows:

           ``oneapi::mkl::rng::multinomial_method::poisson_icdf_based``

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


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

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

   * - Name
     - Type
     - Description
   * - ntrial
     - ``std::int32_t``
     - Number of independent trials ``m``.
   * - p
     - ``std::vector<double>``
     - Probability vector of possible outcomes (``k``    length).