.. _oneapi-mkl-rng-generate:

oneapi::mkl::rng::generate
==========================

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

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

Entry point to obtain random numbers from a given engine with proper statistics of a given distribution.


API
***


Syntax
------

**Buffer API**

.. code-block:: cpp


   template<typename Distr, typename Engine>
     void generate (const Distr& distr,
     Engine& engine,
     std::int64_t n,
     sycl::buffer<typename Distr::result_type, 1>& r)


**USM API**

.. code-block:: cpp

   template<typename Distr, typename Engine>
     sycl::event generate (const Distr& distr,
     Engine& engine,
     std::int64_t n,
     typename Distr::result_type* r,
     const std::vector<sycl::event> & dependencies)


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

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


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

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

   * - Name
     - Type
     - Description
   * - distr
     - const Distr&
     - Distribution object. See :ref:`distributions` for details.
   * - engine
     - Engine&
     - Engine object. See :ref:`Engines<engines-basic-random-number-generators>` for details.
   * - n
     - ``std::int64_t``
     - Number of random values to be generated.


**Optional Input Parameter for USM API**


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

   * - Name
     - Type
     - Description
   * - dependencies
     - const ``std::vector <sycl::event>`` &
     - List of events to wait for before starting computation, if any.


Output Parameters
-----------------

**Buffer API**

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

   * - Name
     - Type
     - Description
   * - r
     - ``sycl::buffer<typename Distr::result_type``, 1>
     - ``sycl::buffer`` ``r`` to the output vector.


**USM API**

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

   * - Name
     - Type
     - Description
   * - r
     - typename ``Distr::result_type``
     - Pointer ``r`` to the output vector.
   * - event
     - ``sycl::event``
     - Function return event after submitting task in ``sycl::queue`` from the engine.


``oneapi::mkl::rng::generate`` submits a kernel into a queue that is held by the engine and fills ``sycl::buffer``/typename ``Distr::result_type`` \* vector with ``n`` random numbers.