.. _oneapi-mkl-rng-device-engine_descriptor:

oneapi::mkl::rng::device::engine_descriptor
===========================================


Host side helper to provide an abstraction over ``sycl::buffer`` to initialize and store engines’ states between DPC++ kernels.


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

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

``engine_descriptor`` provides an abstraction over ``sycl::buffer`` to initialize and store engines’ states between SYCL kernels.

.. note::
   The constructor of the engine descriptor submits a parallel_for task to a given queue to initialize engines’ states:
   Each engine is initialized as ``Engine {seed, id * offset}`` for scalar offset case, where id is a value from 0 to range.size().


API
***


Syntax
------

.. code-block:: cpp


   template<Engine>
     class engine_descriptor {
     public:
     engine_descriptor(sycl::queue& queue, sycl::range<1> range, std::uint64_t seed, std::uint64_t offset);
     template<typename InitEngineFunc>
     engine_descriptor(sycl::queue& queue, sycl::range<1> range, InitEngineFunc func);
     engine_accessor<Engine> get_access(sycl::handler& cgh);
   };


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

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


Template Parameters
-------------------


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

   * -  Type
     -  Description
   * -  ``Engine``
     -  Specify an engine which state is hold by engine descriptor.




Constructors Input Parameters
-----------------------------

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

   * - Name
     - Type
     - Description

   * - queue
     -  ``sycl::queue&``
     - ``sycl::queue`` object. Task is submitted to this queue to inlize engines’ states directly on the device which is associated wiueue.

   * - range
     - ``sycl::range<1>``
     - Describes number of engines which are hold by this en_descriptor object.

   * - seed
     - ``std::uint64_t``
       ``std::initializer_list<std::uint64_t>``
     -  Initial conditions of the engine state.

   * - offset
     - ``std::uint64_t``
       ``std::initializer_list<std::uint64_t>``

     - Number of skipped elements, for ``initializer_list`` offset is
       calculated as ``num_to_skip`` [0]+ ``num_to_skip``
       [1]*2\ :sup:`64` + ``num_to_skip`` [2]* 2\ :sup:`128` + … + ``num_to_skip`` [``n``-1]*2\ :sup:`64` \*(``n``-1).

   * - func
     - InitEngineFunc
     - Functor which would be used to initialize engines. This functor should take ``sycl::item<1>`` as an argument and return object of type ``Engine``.