.. _oneapi-mkl-rng-skip_ahead:

oneapi::mkl::rng::skip_ahead
============================

Proceeds the state of the engine using the skip-ahead method. The ``oneapi::mkl::rng::skip_ahead`` function supports the following interfaces to apply the skip-ahead method:

-  Common interface
-  Interface with a partitioned number of skipped elements



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

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

The ``oneapi::mkl::rng::skip_ahead`` function skips a given number of elements in a random sequence provided by engine. This feature is particularly useful in distributing random numbers from original engine across different computational nodes. If the largest number of random numbers used by a computational node is num_to_skip, then the original random sequence may be split by ``oneapi::mkl::rng::skip_ahead`` into non-overlapping blocks of ``num_to_skip`` size so that each block corresponds to the respective computational node. The number of computational nodes is unlimited. This method is known as the block-splitting method or as the skip-ahead method (see the following figure).


**Block-Splitting Method**

.. figure:: /_figures/GUID-061AF9F8-B166-4154-9BF1-4E2C99F1CE1F-low.png
   :scale: 50%
   :align: center
   :alt: Block-Splitting Method

   Block-Splitting Method


The skip-ahead method is supported only for those basic generators that allow skipping elements by the skip-ahead method, which is more efficient than simply generating them by generator with subsequent manual skipping. See :ref:`VS Notes <bibliography>` for details.

Please note that for quasi-random basic generators the skip-ahead method works with components of quasi-random vectors rather than with whole quasi-random vectors. Therefore, to skip NS quasi-random vectors,
set the ``num_to_skip`` parameter equal to the ``num_to_skip`` \*dim, where ``dim`` is the dimension of the quasi-random vector.

When the number of skipped elements is greater than 2\ :sup:`63` the interface with the partitioned number of skipped elements is used.

Prior calls to the function represent the number of skipped elements with the list of size ``n`` as shown below:


``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)` ;


When the number of skipped elements is less than 2\ :sup:`63` both interfaces can be used.


The following code illustrates how to initialize three independent streams using the ``oneapi::mkl::rng::skip_ahead`` function:


Code for Block-Splitting Method
-------------------------------

.. literalinclude:: /_examples/rng_block_splitting.cpp
   :language: cpp
   :linenos:


Code for Block-Splitting Method with Partitioned Number of Elements
-------------------------------------------------------------------

.. literalinclude:: /_examples/rng_block_split_partitioned_elements.cpp
   :language: cpp
   :linenos:


API
***


Syntax
------

**Common Interface**

.. code-block:: cpp

   template<typename Engine>
     void skip_ahead (Engine& engine, std::uint64_t num_to_skip)

**Interface with Partitioned Number of Skipped Elements**


.. code-block:: cpp

   template<typename Engine>
     void skip_ahead (Engine& engine,   std::initializer_list<std::uint64_t> num_to_skip)


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

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


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

**Common Interface**


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

   * - Name
     - Type
     - Description
   * - engine
     - ``Engine``
     - Object of engine class, which supports the block-splitting method.
   * - num_to_skip
     - ``std::uint64_t``
     - Number of skipped elements.




**Interface with Partitioned Number of Skipped Elements**


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

   * - Name
     - Type
     - Description
   * - engine
     - ``Engine``
     - Object of engine class, which supports the block-splitting method.
   * - num_to_skip
     - ``std::initializer_list<std::uint64_t>``
     - Partitioned number of skipped elements.