Update documentation for oneDPL 2022.7.0 release.

_sources/api_for_sycl_kernels/random.rst

@@ -11,53 +11,79 @@ Random Number Engines
 ---------------------
 
 Random number engines use seed data as an entropy source to generate pseudo-random numbers. 
-|onedpl_short| provides several class templates for customized engines, they are defined in the header
-``<oneapi/dpl/random>``.
-
-============================== =========================================================================================================
-Engine                         Description
-============================== =========================================================================================================
-``linear_congruential_engine`` Implements a linear congruential algorithm
-``subtract_with_carry_engine`` Implements a subtract-with-carry algorithm
-``discard_block_engine``       Implements a discard block adaptor
-============================== =========================================================================================================
+|onedpl_short| provides several class templates for customizable engines, defined in the header
+``<oneapi/dpl/random>`` under the ``oneapi::dpl::`` namespace.
+
+=============================== ============================================
+Engine                          Description
+=============================== ============================================
+``linear_congruential_engine``  Implements a linear congruential algorithm
+``subtract_with_carry_engine``  Implements a subtract-with-carry algorithm
+``discard_block_engine``        Implements a discard block adaptor
+``experimental::philox_engine`` Implements a Philox algorithm
+=============================== ============================================
 
 Predefined Random Number Engines
 --------------------------------
 
-Predefined random number engines are instantiations of random number engines class templates. 
-The types below are defined in the header ``<oneapi/dpl/random>`` under the ``oneapi::dpl::`` namespace.
-
-===================================================================== =========================================================================================================
-Type                                                                  Description
-===================================================================== =========================================================================================================
-``minstd_rand0``                                                      ``oneapi::dpl::linear_congruential_engine<std::uint32_t, 16807, 0, 2147483647>``
-``minstd_rand``                                                       ``oneapi::dpl::linear_congruential_engine<std::uint32_t, 48271, 0, 2147483647>``
-``ranlux24_base``                                                     ``oneapi::dpl::subtract_with_carry_engine<std::uint32_t, 24, 10, 24>``
-``ranlux48_base``                                                     ``oneapi::dpl::subtract_with_carry_engine<std::uint64_t, 48, 5, 12>``
-``ranlux24``                                                          ``oneapi::dpl::discard_block_engine<ranlux24_base, 223, 23>``
-``ranlux48``                                                          ``oneapi::dpl::discard_block_engine<ranlux48_base, 389, 11>``
-===================================================================== =========================================================================================================
-
-The engines described below can efficiently generate vectors of random numbers. These types are
-defined in the header ``<oneapi/dpl/random>`` under the ``oneapi::dpl::`` namespace.
-
-===================================================================== =========================================================================================================
-Type                                                                  Description
-===================================================================== =========================================================================================================
-``template<std::int32_t N> minstd_rand0_vec<N>``                      ``oneapi::dpl::linear_congruential_engine<sycl::vec<std::uint32_t, N>, 16807, 0, 2147483647>``
-                                                                      minstd_rand0 for a vector generation case
-``template<std::int32_t N> minstd_rand_vec<N>``                       ``oneapi::dpl::linear_congruential_engine<sycl::vec<std::uint32_t, N>, 48271, 0, 2147483647>``
-                                                                      minstd_rand for a vector generation case
-``template<std::int32_t N> ranlux24_base_vec<N>``                     ``oneapi::dpl::subtract_with_carry_engine<sycl::vec<std::uint32_t, N>, 24, 10, 24>``
-                                                                      ranlux24_base for a vector generation case
-``template<std::int32_t N> ranlux48_base_vec<N>``                     ``oneapi::dpl::subtract_with_carry_engine<sycl::vec<std::uint64_t, N>, 48, 5, 12>``
-                                                                      ranlux48_base for a vector generation case
-``template<std::int32_t N> ranlux24_vec<N>``                          ``oneapi::dpl::discard_block_engine<ranlux24_base_vec<N>, 223, 23>``
-                                                                      ranlux24 for a vector generation case
-``template<std::int32_t N> ranlux48_vec<N>``                          ``oneapi::dpl::discard_block_engine<ranlux48_base_vec<N>, 389, 11>``
-                                                                      ranlux48 for vector generation case
-===================================================================== =========================================================================================================
+Predefined random number engines are instantiations of the random number engines class templates
+with selected engine parameters.
+
+The types below are defined in the header ``<oneapi/dpl/random>`` in the same namespaces as their
+respective class templates.
+
+================== =================================================================================
+Type               Description
+================== =================================================================================
+``minstd_rand0``   ``oneapi::dpl::linear_congruential_engine<std::uint32_t, 16807, 0, 2147483647>``
+``minstd_rand``    ``oneapi::dpl::linear_congruential_engine<std::uint32_t, 48271, 0, 2147483647>``
+``ranlux24_base``  ``oneapi::dpl::subtract_with_carry_engine<std::uint32_t, 24, 10, 24>``
+``ranlux48_base``  ``oneapi::dpl::subtract_with_carry_engine<std::uint64_t, 48, 5, 12>``
+``ranlux24``       ``oneapi::dpl::discard_block_engine<ranlux24_base, 223, 23>``
+``ranlux48``       ``oneapi::dpl::discard_block_engine<ranlux48_base, 389, 11>``
+``philox4x32``     ``oneapi::dpl::experimental::philox_engine<std::uint_fast32_t, 32, 4, 10, 0xCD9E8D57, 0x9E3779B9, 0xD2511F53, 0xBB67AE85>``
+``philox4x64``     ``oneapi::dpl::experimental::philox_engine<std::uint_fast64_t, 64, 4, 10, 0xCA5A826395121157, 0x9E3779B97F4A7C15, 0xD2E7470EE14C6C93, 0xBB67AE8584CAA73B>``
+================== =================================================================================
+
+The following predefined engines can efficiently generate vectors of random numbers.
+They differ from the scalar engines above by using ``sycl::vec<T, N>`` as the data type,
+while other engine parameters remain the same.
+
+================================================== ===============================================================================================
+Type                                               Description
+================================================== ===============================================================================================
+``template<std::int32_t N> minstd_rand0_vec<N>``   ``oneapi::dpl::linear_congruential_engine<sycl::vec<std::uint32_t, N>, 16807, 0, 2147483647>``
+
+                                                   ``minstd_rand0`` that generates a vector.
+-------------------------------------------------- -----------------------------------------------------------------------------------------------
+``template<std::int32_t N> minstd_rand_vec<N>``    ``oneapi::dpl::linear_congruential_engine<sycl::vec<std::uint32_t, N>, 48271, 0, 2147483647>``
+
+                                                   ``minstd_rand`` that generates a vector.
+-------------------------------------------------- -----------------------------------------------------------------------------------------------
+``template<std::int32_t N> ranlux24_base_vec<N>``  ``oneapi::dpl::subtract_with_carry_engine<sycl::vec<std::uint32_t, N>, 24, 10, 24>``
+
+                                                   ``ranlux24_base`` that generates a vector.
+-------------------------------------------------- -----------------------------------------------------------------------------------------------
+``template<std::int32_t N> ranlux48_base_vec<N>``  ``oneapi::dpl::subtract_with_carry_engine<sycl::vec<std::uint64_t, N>, 48, 5, 12>``
+
+                                                   ``ranlux48_base`` that generates a vector.
+-------------------------------------------------- -----------------------------------------------------------------------------------------------
+``template<std::int32_t N> ranlux24_vec<N>``       ``oneapi::dpl::discard_block_engine<ranlux24_base_vec<N>, 223, 23>``
+
+                                                   ``ranlux24`` that generates a vector.
+-------------------------------------------------- -----------------------------------------------------------------------------------------------
+``template<std::int32_t N> ranlux48_vec<N>``       ``oneapi::dpl::discard_block_engine<ranlux48_base_vec<N>, 389, 11>``
+
+                                                   ``ranlux48`` that generates a vector.
+-------------------------------------------------- -----------------------------------------------------------------------------------------------
+``template<std::int32_t N> philox4x32_vec<N>``     ``oneapi::dpl::experimental::philox_engine<sycl::vec<std::uint_fast32_t, N>, 32, 4, 10, 0xCD9E8D57, 0x9E3779B9, 0xD2511F53, 0xBB67AE85>``
+
+                                                   ``philox4x32`` that generates a vector.
+-------------------------------------------------- -----------------------------------------------------------------------------------------------
+``template<std::int32_t N> philox4x64_vec<N>``     ``oneapi::dpl::experimental::philox_engine<sycl::vec<std::uint_fast64_t, N>, 64, 4, 10, 0xCA5A826395121157, 0x9E3779B97F4A7C15, 0xD2E7470EE14C6C93, 0xBB67AE8584CAA73B>``
+
+                                                   ``philox4x64`` that generates a vector.
+================================================== ===============================================================================================
 
 Random Number Distributions
 ---------------------------
@@ -66,9 +92,9 @@ Random number distributions process the output of random number engines in such
 resulting output is distributed according to a defined statistical probability density function. They
 are defined in the header ``<oneapi/dpl/random>`` under the ``oneapi::dpl::`` namespace.
 
-============================== =========================================================================================================
+============================== ============================================================================
 Distribution                   Description
-============================== =========================================================================================================
+============================== ============================================================================
 ``uniform_int_distribution``   Produces integer values evenly distributed across a range
 ``uniform_real_distribution``  Produces real values evenly distributed across a range
 ``normal_distribution``        Produces real values according to the Normal (Gaussian) distribution
@@ -79,7 +105,10 @@ Distribution                   Description
 ``lognormal_distribution``     Produces real values according to the Lognormal distribution
 ``extreme_value_distribution`` Produces real values according to the Extreme value (Gumbel) distribution
 ``cauchy_distribution``        Produces real values according to the Cauchy distribution
-============================== =========================================================================================================
+============================== ============================================================================
+
+.. note::
+  ``bernoulli_distribution``, ``geometric_distribution``, and ``uniform_int_distribution`` can only be used on devices with FP64 support as they rely on double precision in their implementation (use ``sycl::aspect::fp64`` to check if the device supports FP64).
 
 Usage Model of |onedpl_short| Random Number Generation Functionality
 --------------------------------------------------------------------

_sources/api_for_sycl_kernels/tested_standard_cpp_api.rst

@@ -463,9 +463,9 @@ C++ Standard API                      libstdc++  libc++     MSVC
 These tests were done for the following versions of the standard C++ library:
 
 ============================================= =============================================
-libstdc++(GNU)                                Provided with GCC*-7.5.0, GCC*-9.3.0
+libstdc++ (GNU)                               Provided with GCC*-7.5.0, GCC*-9.3.0
 --------------------------------------------- ---------------------------------------------
-libc++(LLVM)                                  Provided with Clang*-11.0
+libc++ (LLVM)                                 Provided with Clang*-11.0
 --------------------------------------------- ---------------------------------------------
 Microsoft Visual C++* (MSVC) Standard Library Provided with Microsoft Visual Studio* 2017;
                                               Microsoft Visual Studio 2019; and Microsoft 

_sources/api_for_sycl_kernels/utility_function_object_classes.rst

@@ -2,11 +2,11 @@ Utility Function Object Classes
 ##################################
 
 The definitions of the utility function objects are available through the
-``oneapi/dpl/functional`` header.  All function objects are implemented in the ``oneapi::dpl`` namespace.
+``<oneapi/dpl/functional>`` header.  All function objects are implemented in the ``oneapi::dpl`` namespace.
 
-* ``identity``: A C++11 implementation of the C++20 ``std::identity`` function object type, where the operator() returns the
-  argument unchanged.
-* ``minimum``: A function object type where the operator() applies ``std::less`` to its arguments, then returns the
-  lesser argument unchanged.
-* ``maximum``: A function object type where the operator() applies ``std::greater`` to its arguments, then returns the
-  greater argument unchanged.
+* ``identity``: A function object type where the operator() returns the argument unchanged.
+  It is an implementation of ``std::identity`` that can be used prior to C++20.
+* ``minimum``: A function object type where the operator() applies ``std::less`` to its arguments,
+  then returns the lesser argument unchanged.
+* ``maximum``: A function object type where the operator() applies ``std::greater`` to its arguments,
+  then returns the greater argument unchanged.

_sources/api_for_sycl_kernels_main.rst

@@ -1,5 +1,5 @@
-API for the SYCL* Kernels
-#########################
+API for SYCL* Kernels
+#####################
 
 |onedpl_long| (|onedpl_short|) includes the following APIs for SYCL* kernels:
 
@@ -13,9 +13,8 @@ API for the SYCL* Kernels
 .. toctree::
    :maxdepth: 2
    :titlesonly:
-   :glob:
    :hidden:
 
-   api_for_sycl_kernels/random
    api_for_sycl_kernels/tested_standard_cpp_api
-   api_for_sycl_kernels/utility_function_object_classes
+   api_for_sycl_kernels/random
+   api_for_sycl_kernels/utility_function_object_classes

_sources/cmake_support.rst

@@ -17,7 +17,10 @@ Requirements
 ============
 The minimal supported CMake version for |onedpl_short| is 3.11 on Linux and 3.20 on Windows.
 
-The supported `CMake Generator <https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html#ninja-generators>`_ for Linux is `Unix Makefiles <https://cmake.org/cmake/help/latest/generator/Unix%20Makefiles.html>`_ (default). In the Windows environment, the supported generator is `Ninja <https://cmake.org/cmake/help/latest/generator/Ninja.html>`_ as described in the `Intel® oneAPI DPC++/C++ Compiler Developer Guide and Reference <https://www.intel.com/content/www/us/en/docs/dpcpp-cpp-compiler/developer-guide-reference/current/use-cmake-with-the-compiler.html>`_ which may be specified via ``-GNinja``.
+The supported `CMake Generator <https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html#ninja-generators>`_
+for Linux is `Unix Makefiles <https://cmake.org/cmake/help/latest/generator/Unix%20Makefiles.html>`_ (default).
+In the Windows environment, the supported generator is `Ninja <https://cmake.org/cmake/help/latest/generator/Ninja.html>`_
+which may be specified via ``-GNinja`` as described in the |dpcpp_cmake_support|_.
 
 |onedpl_short| Backend Options
 ==============================