Merge branch 'kokkos:main' into 120-API-core-stl_compat-pair

.gitignore

@@ -1,5 +1,6 @@
 # Python Virtual Environment
 /venv
+.venv/
 # PyCharm files
 /.idea
 # Rendered html files

docs/Makefile

@@ -1,5 +1,5 @@
 html:
-	sphinx-build -b html ./source/ ./generated_docs/
+	sphinx-build -b html ./source/ ./generated_docs/ -W --keep-going
 	python3 ./source/edit_button_handler.py
 
 clean:

docs/source/API/containers/DynRankView.rst

@@ -70,19 +70,11 @@ Description
       are specified, ``MemorySpace`` must come before ``MemoryTraits``.
 
 
-   .. rubric:: Public Enums
+   .. rubric:: Public Static Variables
 
-   .. cppkokkos:type:: rank
-
-      Rank of the view (i.e. the dimensionality).
-
-   .. cppkokkos:type:: rank_dynamic
-
-      Number of runtime determined dimensions.
-
-   .. cppkokkos:type:: reference_type_is_lvalue_reference
-
-      Whether the reference type is a C++ lvalue reference.
+   * ``rank``: Rank of the view (i.e. the dimensionality).
+   * ``rank_dynamic``: Number of runtime determined dimensions.
+   * ``reference_type_is_lvalue_reference``: Whether the reference type is a C++ lvalue reference.
 
 
    .. rubric:: Public Data Types Typedefs
@@ -247,7 +239,7 @@ Description
        * ``ptr``: pointer to a user provided memory allocation. Must provide storage of size ``DynRankView::required_allocation_size(n0,...,nR)``.
        * ``indices``: runtime dimensions of the view.
 
-   .. cppkokkos:function:: DynRankView(const std::string& name, const array_layout& layout)
+   .. cppkokkos:function:: DynRankView(const pointer_type& ptr, const array_layout& layout)
 
        Unmanaged data wrapper constructor.
 

docs/source/API/containers/Unordered-Map.rst

@@ -67,9 +67,10 @@ Description
 
       Insert the given key into the map with a default constructed value
 
-   .. cppkokkos:kokkosinlinefunction:: UnorderedMapInsertResult insert(Key key, Value value) const;
+   .. cppkokkos:kokkosinlinefunction:: UnorderedMapInsertResult insert(Key key, Value value, Insert op = NoOp) const;
 
-      Insert the given key/value pair into the map
+      Insert the given key/value pair into the map and optionally specify
+      the operator, op, used for combining values if key already exists
 
    .. cppkokkos:kokkosinlinefunction:: uint32_t find(Key key) const
 
@@ -116,8 +117,27 @@ Description
 
       Index where the key exists in the map as long as failed() == false
 
-Insertion
----------
+.. cppkokkos:struct:: template <class ValueTypeView, class ValuesIdxType> UnorderedMapInsertOpTypes
+
+   :tparam ValueTypeView: The UnorderedMap value array type.
+
+   :tparam ValuesIdxType: The index type for lookups in the value array.
+
+   .. rubric:: *Public* Insertion Operator Types
+
+   .. cppkokkos:struct:: NoOp
+
+        Insert the given key/value pair into the map
+
+   .. cppkokkos:struct:: AtomicAdd
+
+       Duplicate key insertions sum values together.
+
+
+.. _unordered_map_insert_op_types_noop:
+
+Insertion using default ``UnorderedMapInsertOpTypes::NoOp``
+-----------------------------------------------------------
 
 There are 3 potential states for every insertion which are reported by the ``UnorderedMapInsertResult``:
 
@@ -129,6 +149,40 @@ There are 3 potential states for every insertion which are reported by the ``Uno
   with a bounded search of the internal atomic bitset. A ``failed`` insertion requires the user to increase
   the capacity (``rehash``) and restart the algoritm.
 
+.. code-block:: cpp
+
+    // use the default NoOp insert operation
+    using map_op_type = Kokkos::UnorderedMapInsertOpTypes<value_view_type, size_type>;
+    using noop_type   = typename map_op_type::NoOp;
+    noop_type noop;
+    parallel_for(N, KOKKOS_LAMBDA (uint32_t i) {
+      map.insert(i, values(i), noop);
+    });
+    // OR;
+    parallel_for(N, KOKKOS_LAMBDA (uint32_t i) {
+      map.insert(i, values(i));
+    });
+  
+Insertion using ``UnorderedMapInsertOpTypes::AtomicAdd``
+--------------------------------------------------------
+
+The behavior from :ref:`unordered_map_insert_op_types_noop` holds true with the
+exception that the ``UnorderedMapInsertResult``:
+
+- ``existing`` implies that the key is already in the map and the existing value at key was summed
+  with the new value being inserted.
+
+.. code-block:: cpp
+
+    // use the AtomicAdd insert operation
+    using map_op_type     = Kokkos::UnorderedMapInsertOpTypes<value_view_type, size_type>;
+    using atomic_add_type = typename map_op_type::AtomicAdd;
+    atomic_add_type atomic_add;
+    parallel_for(N, KOKKOS_LAMBDA (uint32_t i) {
+      map.insert(i, values(i), atomic_add);
+    });
+
+
 Iteration
 ---------
 

docs/source/API/core/Utilities.rst

@@ -7,6 +7,7 @@ Utilities
    ./utilities/abort
    ./utilities/all
    ./utilities/complex
+   ./utilities/printf
    ./utilities/timer
    ./utilities/device_id
    ./utilities/num_threads

docs/source/API/core/initialize_finalize/InitArguments.rst

@@ -0,0 +1,62 @@
+InitArguments
+=============
+
+.. role:: cppkokkos(code)
+   :language: cppkokkos
+
+.. _KokkosInitialize: initialize.html
+.. |KokkosInitialize| replace:: ``Kokkos::initialize``
+
+.. _KokkosInitializationSetting: InitializationSettings.html
+.. |KokkosInitializationSetting| replace:: ``Kokkos::InitializationSettings``
+
+Defined in ``<Kokkos_Core.hpp>`` header.
+
+.. warning:: Deprecated since 3.7, **use** ``Kokkos::InitializationSettings`` **instead**
+
+Interface
+---------
+
+.. cppkokkos:struct:: InitArguments
+
+   .. cppkokkos:member:: int num_threads
+
+   .. cppkokkos:member:: int num_numa
+
+   .. cppkokkos:member:: int device_id
+
+   .. cppkokkos:member:: int ndevices
+
+   .. cppkokkos:member:: int skip_device
+
+   .. cppkokkos:member:: bool disable_warnings
+
+   .. cppkokkos:function:: InitArguments()
+
+``InitArguments`` is a struct that can be used to programmatically define the arguments passed to |KokkosInitialize|_. It was deprecated in version 3.7 in favor of |KokkosInitializationSetting|_.
+
+One of the main reasons for replacing it was that user-specified data members cannot be distinguished from defaulted ones.
+
+Example
+~~~~~~~
+
+.. code-block:: cpp
+
+   #include <Kokkos_Core.hpp>
+
+   int main() {
+     Kokkos::InitArguments arguments;
+     arguments.num_threads = 2;
+     arguments.device_id = 1;
+     arguments.disable_warnings = true;
+     Kokkos::initialize(arguments);
+     // ...
+     Kokkos::finalize();
+   }
+
+
+See also
+~~~~~~~~
+
+* |KokkosInitializationSetting|_
+* |KokkosInitialize|_

docs/source/API/core/parallel-dispatch/parallel_for.rst

@@ -74,7 +74,7 @@ More Detailed Examples are provided in the ExecutionPolicy documentation.
 
         int N = atoi(argv[1]);
 
-        Kokkos::parallel_for("Loop1", N, KOKKOS_LAMBDA (const int& i) {
+        Kokkos::parallel_for("Loop1", N, KOKKOS_LAMBDA (const int i) {
             printf("Greeting from iteration %i\n",i);
         });
 

docs/source/API/core/parallel-dispatch/parallel_reduce.rst

@@ -11,12 +11,12 @@ Usage
 
 .. code-block:: cpp
 
-    Kokkos::parallel_reduce( name, policy, functor, reducer... );
-    Kokkos::parallel_reduce( name, policy, functor, result...);
-    Kokkos::parallel_reduce( name, policy, functor);
-    Kokkos::parallel_reduce( policy, functor, reducer...);
-    Kokkos::parallel_reduce( policy, functor, result...);
-    Kokkos::parallel_reduce( policy, functor);
+    Kokkos::parallel_reduce(name, policy, functor, reducer...);
+    Kokkos::parallel_reduce(name, policy, functor, result...);
+    Kokkos::parallel_reduce(name, policy, functor);
+    Kokkos::parallel_reduce(policy, functor, reducer...);
+    Kokkos::parallel_reduce(policy, functor, result...);
+    Kokkos::parallel_reduce(policy, functor);
 
 Dispatches parallel work defined by ``functor`` according to the *ExecutionPolicy* and performs a reduction of the contributions provided by workers as defined by the execution policy. The optional label name is used by profiling and debugging tools. The reduction type is either a ``sum``, is defined by the ``reducer`` or is deduced from an optional ``join`` operator on the functor. The reduction result is stored in ``result``, or through the ``reducer`` handle. It is also provided to the ``functor.final()`` function if such a function exists. Multiple ``reducers`` can be used in a single ``parallel_reduce`` and thus, it is possible to compute the ``min`` and the ``max`` values in a single ``parallel_reduce``.
 
@@ -79,7 +79,7 @@ Parameters:
   - `TeamThreadRange <../policies/TeamThreadRange.html>`_: defines a 1D iteration range to be executed by a thread-team. Only valid inside a parallel region executed through a ``TeamPolicy`` or a ``TaskTeam``.
   - `ThreadVectorRange <../policies/ThreadVectorRange.html>`_: defines a 1D iteration range to be executed through vector parallelization dividing the threads within a team.  Only valid inside a parallel region executed through a ``TeamPolicy`` or a ``TaskTeam``.
 * FunctorType: A valid functor with (at minimum) an ``operator()`` with a matching signature for the ``ExecPolicy`` combined with the reduced type.
-* ReducerArgument: Either a class fullfilling the "Reducer" concept or a ``Kokkos::View``
+* ReducerArgument: Either a class fulfilling the "Reducer" concept or a ``Kokkos::View``.
 * ReducerArgumentNonConst: A scalar type or an array type; see below for functor requirements.
 
 Requirements:
@@ -106,7 +106,7 @@ Requirements:
     + ReducerValueType must match the array signature.
     + the functor must define FunctorType::value_type the same as ReducerValueType.
     + the functor must declare a public member variable ``int value_count`` which is the length of the array.
-    + the functor must implement the function ``void init( ReducerValueType dst [] ) const``.
+    + the functor must implement the function ``void init( ReducerValueType dst[] ) const``.
     + the functor must implement the function ``void join( ReducerValueType dst[], ReducerValueType src[] ) const``.
     + If the functor implements the ``final`` function, the argument must also match those of init and join.
 
@@ -125,74 +125,74 @@ Further examples are provided in the `Custom Reductions <../../../ProgrammingGui
 
 .. code-block:: cpp
 
-    #include<Kokkos_Core.hpp>
-    #include<cstdio>
+    #include <Kokkos_Core.hpp>
+    #include <cstdio>
 
     int main(int argc, char* argv[]) {
-        Kokkos::initialize(argc,argv);
+        Kokkos::initialize(argc, argv);
 
         int N = atoi(argv[1]);
         double result;
-        Kokkos::parallel_reduce("Loop1", N, KOKKOS_LAMBDA (const int& i, double& lsum ) {
+        Kokkos::parallel_reduce("Loop1", N, KOKKOS_LAMBDA (const int& i, double& lsum) {
             lsum += 1.0*i;
-        },result);
+        }, result);
 
-        printf("Result: %i %lf\n",N,result);
+        printf("Result: %i %lf\n", N, result);
         Kokkos::finalize();
     }
 
 .. code-block:: cpp
 
-    #include<Kokkos_Core.hpp>
-    #include<cstdio>
+    #include <Kokkos_Core.hpp>
+    #include <cstdio>
 
     int main(int argc, char* argv[]) {
-        Kokkos::initialize(argc,argv);
+        Kokkos::initialize(argc, argv);
 
         int N = atoi(argv[1]);
         double sum, min;
-        Kokkos::parallel_reduce("Loop1", N, KOKKOS_LAMBDA (const int& i, double& lsum, double& lmin ) {
+        Kokkos::parallel_reduce("Loop1", N, KOKKOS_LAMBDA (const int& i, double& lsum, double& lmin) {
             lsum += 1.0*i;
             lmin = lmin < 1.0*i ? lmin : 1.0*i;
-        },sum,Min<double>(min));
+        }, sum, Kokkos::Min<double>(min));
 
-        printf("Result: %i %lf %lf\n",N,sum,min);
+        printf("Result: %i %lf %lf\n", N, sum, min);
         Kokkos::finalize();
     }
 
 .. code-block:: cpp
 
-    #include<Kokkos_Core.hpp>
-    #include<cstdio>
+    #include <Kokkos_Core.hpp>
+    #include <cstdio>
 
     struct TagMax {};
     struct TagMin {};
 
     struct Foo {
         KOKKOS_INLINE_FUNCTION
         void operator() (const TagMax, const Kokkos::TeamPolicy<>::member_type& team, double& lmax) const {
-            if( team.league_rank % 17 + team.team_rank % 13 > lmax )
-                lmax = team.league_rank % 17 + team.team_rank % 13;
+            if (team.league_rank() % 17 + team.team_rank() % 13 > lmax)
+                lmax = team.league_rank() % 17 + team.team_rank() % 13;
         }
         KOKKOS_INLINE_FUNCTION
-        void operator() (const TagMin, const Kokkos::TeamPolicy<>::member_type& team, double& lmin ) const {
-            if( team.league_rank % 17 + team.team_rank % 13 < lmin )
-                lmin = team.league_rank % 17 + team.team_rank % 13;
+        void operator() (const TagMin, const Kokkos::TeamPolicy<>::member_type& team, double& lmin) const {
+            if (team.league_rank() % 17 + team.team_rank() % 13 < lmin)
+                lmin = team.league_rank() % 17 + team.team_rank() % 13;
         }
     };
 
     int main(int argc, char* argv[]) {
-        Kokkos::initialize(argc,argv);
+        Kokkos::initialize(argc, argv);
 
         int N = atoi(argv[1]);
 
         Foo foo;
-        double max,min;
+        double max, min;
         Kokkos::parallel_reduce(Kokkos::TeamPolicy<TagMax>(N,Kokkos::AUTO), foo, Kokkos::Max<double>(max));
         Kokkos::parallel_reduce("Loop2", Kokkos::TeamPolicy<TagMin>(N,Kokkos::AUTO), foo, Kokkos::Min<double>(min));
         Kokkos::fence();
 
-        printf("Result: %lf %lf\n",min,max);
+        printf("Result: %lf %lf\n", min, max);
 
         Kokkos::finalize();
     }