Adding Mxx*FirstLoc reducers

docs/source/API/alphabetical.rst

@@ -150,6 +150,8 @@ Core
 +--------------------------------------------------------------------------------------+---------------------------+------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+
 | `Max <core/builtinreducers/Max.html>`_                                               | `Core <core-index.html>`_ | `Built-in Reducers <core/builtin_reducers.html>`_                      | Reducer for Maximum reduction                                                                                                           |
 +--------------------------------------------------------------------------------------+---------------------------+------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+
+| `MaxFirstLoc <core/builtinreducers/MaxFirstLoc.html>`_                               | `Core <core-index.html>`_ | `Built-in Reducers <core/builtin_reducers.html>`_                      | Reducer for Reduction providing maximum and its smallest index position                                                                 |
++--------------------------------------------------------------------------------------+---------------------------+------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+
 | `MaxLoc <core/builtinreducers/MaxLoc.html>`_                                         | `Core <core-index.html>`_ | `Built-in Reducers <core/builtin_reducers.html>`_                      | Reducer for Reduction providing maximum and an associated index                                                                         |
 +--------------------------------------------------------------------------------------+---------------------------+------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+
 | `(U)MDRangePolicy <core/policies/MDRangePolicy.html>`_                               | `Core <core-index.html>`_ | `Execution Policies <core/Execution-Policies.html>`_                   | Policy to iterate over a multidimensional index range.                                                                                  |
@@ -158,10 +160,14 @@ Core
 +--------------------------------------------------------------------------------------+---------------------------+------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+
 | `Min <core/builtinreducers/Min.html>`_                                               | `Core <core-index.html>`_ | `Built-in Reducers <core/builtin_reducers.html>`_                      | Reducer for Minimum reduction                                                                                                           |
 +--------------------------------------------------------------------------------------+---------------------------+------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+
+| `MinFirstLoc <core/builtinreducers/MinFirstLoc.html>`_                               | `Core <core-index.html>`_ | `Built-in Reducers <core/builtin_reducers.html>`_                      | Reducer for Reduction providing minimum and its smallest index position                                                                 |
++--------------------------------------------------------------------------------------+---------------------------+------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+
 | `MinLoc <core/builtinreducers/MinLoc.html>`_                                         | `Core <core-index.html>`_ | `Built-in Reducers <core/builtin_reducers.html>`_                      | Reducer for Reduction providing minimum and an associated index                                                                         |
 +--------------------------------------------------------------------------------------+---------------------------+------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+
 | `MinMax <core/builtinreducers/MinMax.html>`_                                         | `Core <core-index.html>`_ | `Built-in Reducers <core/builtin_reducers.html>`_                      | Reducer for Reduction providing both minimum and maximum                                                                                |
 +--------------------------------------------------------------------------------------+---------------------------+------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+
+| `MinMaxFirstLastLoc <core/builtinreducers/MinMaxFirstLastLoc.html>`_                 | `Core <core-index.html>`_ | `Built-in Reducers <core/builtin_reducers.html>`_                      | Reducer for Reduction providing both minimum at its smallest index & maximum at its largest index                                       |
++--------------------------------------------------------------------------------------+---------------------------+------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+
 | `MinMaxLoc <core/builtinreducers/MinMaxLoc.html>`_                                   | `Core <core-index.html>`_ | `Built-in Reducers <core/builtin_reducers.html>`_                      | Reducer for Reduction providing both minimum and maximum and associated indices                                                         |
 +--------------------------------------------------------------------------------------+---------------------------+------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+
 | `OpenMP <core/execution_spaces.html#kokkos-openmp>`_                                 | `Core <core-index.html>`_ | `Spaces <core/Spaces.html>`_                                           | Execution space using non-target OpenMP parallel execution mechanisms.                                                                  |

docs/source/API/core/builtin_reducers.rst

@@ -21,14 +21,20 @@ Reducer objects used in conjunction with `parallel_reduce <parallel-dispatch/par
      - Logical 'Or' reduction
    * - `Max <builtinreducers/Max.html>`__
      - Maximum reduction
+   * - `MaxFirstLoc <builtinreducers/MaxFirstLoc.html>`__
+     - Reduction providing maximum and its smallest associated index
    * - `MaxLoc <builtinreducers/MaxLoc.html>`__
      - Reduction providing maximum and an associated index
    * - `Min <builtinreducers/Min.html>`__
      - Minimum reduction
+   * - `MinFirstLoc <builtinreducers/MinFirstLoc.html>`__
+     - Reduction providing minimum and its smallest associated index
    * - `MinLoc <builtinreducers/MinLoc.html>`__
      - Reduction providing minimum and an associated index
    * - `MinMax <builtinreducers/MinMax.html>`__
      - Reduction providing both minimum and maximum
+   * - `MinMaxFirstLastLoc <builtinreducers/MinMaxFirstLastLoc.html>`__
+     - Reduction providing both minimum at its smallest index & maximum at its largest index
    * - `MinMaxLoc <builtinreducers/MinMaxLoc.html>`__
      - Reduction providing both minimum and maximum and associated indices
    * - `Prod <builtinreducers/Prod.html>`__
@@ -48,10 +54,13 @@ Reducer objects used in conjunction with `parallel_reduce <parallel-dispatch/par
    ./builtinreducers/LAnd
    ./builtinreducers/LOr
    ./builtinreducers/Max
+   ./builtinreducers/MaxFirstLoc
    ./builtinreducers/MaxLoc
    ./builtinreducers/Min
+   ./builtinreducers/MinFirstLoc
    ./builtinreducers/MinLoc
    ./builtinreducers/MinMax
+   ./builtinreducers/MinMaxFirstLastLoc
    ./builtinreducers/MinMaxLoc
    ./builtinreducers/Prod
    ./builtinreducers/Sum

docs/source/API/core/builtinreducers/MaxFirstLoc.rst

@@ -0,0 +1,113 @@
+``MaxFirstLoc``
+===============
+
+.. role:: cpp(code)
+    :language: cpp
+
+Specific implementation of `ReducerConcept <ReducerConcept.html>`_ storing the maximum value.
+If there are equivalent values, stores the smallest index.
+
+Header File: ``<Kokkos_Core.hpp>``
+
+Usage
+-----
+
+.. code-block:: cpp
+
+   MaxFirstLoc<T, I, S>::value_type result;
+   parallel_reduce(N, Functor, MaxFirstLoc<T, I, S>(result));
+
+Synopsis
+--------
+
+.. code-block:: cpp
+
+   template<typename Scalar, typename Index, typename Space = HostSpace>
+   struct MaxFirstLoc{
+       using reducer = MaxFirstLoc;
+       using value_type = ValLocScalar<std::remove_cv_t<Scalar>, std::remove_cv_t<Index>>;
+       using result_view_type = View<value_type, Space>;
+
+       MaxFirstLoc(value_type& value_);
+       MaxFirstLoc(const result_view_type& value_);
+
+       void join(value_type& dest, const value_type& src) const;
+       void init(value_type& val) const;
+       value_type& reference() const;
+       result_view_type view() const;
+       bool references_scalar() const;
+   };
+
+   template<typename T, typename I, typename... Ps>
+   MaxFirstLoc(View<ValLocScalar<T, I>, Ps...> const&)
+   -> MaxFirstLoc<T, I, View<ValLocScalar<T, I>, Ps...>::memory_space>;
+
+Interface
+---------
+
+.. cpp:class:: template<class Scalar, class Index, class Space> MaxFirstLoc
+
+   .. rubric:: Public Types:
+
+   .. cpp:type:: reducer
+
+      The self type.
+
+   .. cpp:type:: value_type
+
+      The reduction scalar type (specialization of `ValLocScalar <ValLocScalar.html>`_).
+
+   .. cpp:type:: result_view_type
+
+      A ``View`` referencing the reduction result.
+
+   .. rubric:: Constructors:
+
+   .. cpp:function:: MaxFirstLoc(value_type& value_);
+
+      Constructs a reducer which references a local variable as its result location.
+
+   .. cpp:function:: MaxFirstLoc(const result_view_type& value_);
+
+      Constructs a reducer which references a specific view as its result location.
+
+   .. rubric:: Public Member Functions:
+
+   .. cpp:function:: void join(value_type& dest, const value_type& src) const;
+
+      If ``dest.val == src.val && src.loc < dest.loc`` then ``dest.loc = src.loc``;
+      otherwise if ``dest.val < src.val`` then ``dest.val = src.val`` & ``dest.loc = src.loc``.
+
+   .. cpp:function:: void init(value_type& val) const;
+
+      Initialize ``val.val`` using the ``reduction_identity<Scalar>::max()`` method. The default implementation sets ``val=<TYPE>_MIN``.
+      Initialize ``val.loc`` using the ``reduction_identity<Index>::min()`` method. The default implementation sets ``val=<TYPE>_MAX``.
+
+   .. cpp:function:: value_type& reference() const;
+
+      :return: A reference to the result provided in class constructor.
+
+   .. cpp:function:: result_view_type view() const;
+
+      :return: A ``View`` of the result place provided in class constructor.
+
+   .. cpp:function:: bool references_scalar() const;
+
+      :return: ``true`` if the reducer was constructed with a scalar; ``false`` if the reducer was constructed with a ``View``.
+
+   .. rubric:: Explicit Deduction Guides (CTAD):
+
+   .. cpp:function:: template<typename T, typename I, typename... Ps> MaxFirstLoc(View<ValLocScalar<T, I>, Ps...> const&) -> MaxFirstLoc<T, I, View<ValLocScalar<T, I>, Ps...>::memory_space>;
+
+Additional Information
+^^^^^^^^^^^^^^^^^^^^^^
+
+* ``MaxFirstLoc<T, I, S>::value_type`` is specialization of ``ValLocScalar`` on non-``const`` ``T`` and non-``const`` ``I``.
+
+* ``MaxFirstLoc<T, I, S>::result_view_type`` is ``View<T, S, MemoryTraits<Unmanaged>>``. Note that the ``S`` (memory space) must be the same as the space where the result resides.
+
+* Requires: ``Scalar`` has ``operator=`` and ``operator>`` defined. ``reduction_identity<Scalar>::max()`` is a valid expression.
+
+* Requires: ``Index`` has ``operator=`` defined. ``reduction_identity<Index>::min()`` is a valid expression.
+
+* In order to use ``MaxFirstLoc`` with a custom type of either ``Scalar`` or ``Index``, a template specialization of ``reduction_identity<CustomType>`` must be defined. See `Built-In Reducers with Custom Scalar Types <../../../ProgrammingGuide/Custom-Reductions-Built-In-Reducers-with-Custom-Scalar-Types.html>`_ for details.

docs/source/API/core/builtinreducers/MaxLoc.rst

@@ -83,6 +83,10 @@ Interface
 
       Store maximum with index of ``src`` and ``dest`` into ``dest``: ``dest = (src.val > dest.val) ? src :dest;``.
 
+   .. note:: It is unspecified which index is stored if there are duplicate equivalent maximum values.  To ensure the smallest index, use MaxFirstLoc_ instead of ``MaxLoc``.
+
+   .. _MaxFirstLoc: ../builtinreducers/MaxFirstLoc.html
+
    .. cpp:function:: KOKKOS_INLINE_FUNCTION void init(value_type& val) const;
 
       Initialize ``val.val`` using the ``Kokkos::reduction_identity<Scalar>::max()`` method. The default implementation sets ``val=<TYPE>_MIN``.

docs/source/API/core/builtinreducers/MinFirstLoc.rst

@@ -0,0 +1,113 @@
+``MinFirstLoc``
+===============
+
+.. role:: cpp(code)
+    :language: cpp
+
+Specific implementation of `ReducerConcept <ReducerConcept.html>`_ storing the minimum value.
+If there are equivalent values, stores the smallest index.
+
+Header File: ``<Kokkos_Core.hpp>``
+
+Usage
+-----
+
+.. code-block:: cpp
+
+   MinFirstLoc<T, I, S>::value_type result;
+   parallel_reduce(N, Functor, MinFirstLoc<T, I, S>(result));
+
+Synopsis
+--------
+
+.. code-block:: cpp
+
+   template<typename Scalar, typename Index, typename Space = HostSpace>
+   struct MinFirstLoc{
+       using reducer = MinFirstLoc;
+       using value_type = ValLocScalar<std::remove_cv_t<Scalar>, std::remove_cv_t<Index>>;
+       using result_view_type = View<value_type, Space>;
+
+       MinFirstLoc(value_type& value_);
+       MinFirstLoc(const result_view_type& value_);
+
+       void join(value_type& dest, const value_type& src) const;
+       void init(value_type& val) const;
+       value_type& reference() const;
+       result_view_type view() const;
+       bool references_scalar() const;
+   };
+
+   template<typename T, typename I, typename... Ps>
+   MinFirstLoc(View<ValLocScalar<T, I>, Ps...> const&)
+   -> MinFirstLoc<T, I, View<ValLocScalar<T, I>, Ps...>::memory_space>;
+
+Interface
+---------
+
+.. cpp:class:: template<class Scalar, class Index, class Space> MinFirstLoc
+
+   .. rubric:: Public Types:
+
+   .. cpp:type:: reducer
+
+      The self type.
+
+   .. cpp:type:: value_type
+
+      The reduction scalar type (specialization of `ValLocScalar <ValLocScalar.html>`_).
+
+   .. cpp:type:: result_view_type
+
+      A ``View`` referencing the reduction result.
+
+   .. rubric:: Constructors:
+
+   .. cpp:function:: MinFirstLoc(value_type& value_);
+
+      Constructs a reducer which references a local variable as its result location.
+
+   .. cpp:function:: MinFirstLoc(const result_view_type& value_);
+
+      Constructs a reducer which references a specific view as its result location.
+
+   .. rubric:: Public Member Functions:
+
+   .. cpp:function:: void join(value_type& dest, const value_type& src) const;
+
+      If ``src.val == dest.val`` && ``src.loc < dest.loc`` then ``dest.loc = src.loc``;
+      otherwise if ``src.val < dest.val`` then ``dest.val = src.val`` && ``dest.loc = src.loc``.
+
+   .. cpp:function:: void init(value_type& val) const;
+
+      Initialize ``val.val`` using the ``reduction_identity<Scalar>::min()`` method. The default implementation sets ``val=<TYPE>_MAX``.
+      Initialize ``val.loc`` using the ``reduction_identity<Index>::min()`` method. The default implementation sets ``val=<TYPE>_MAX``.
+
+   .. cpp:function:: value_type& reference() const;
+
+      :return: A reference to the result provided in class constructor.
+
+   .. cpp:function:: result_view_type view() const;
+
+      :return: A ``View`` of the result place provided in class constructor.
+
+   .. cpp:function:: bool references_scalar() const;
+
+      :return: ``true`` if the reducer was constructed with a scalar; ``false`` if the reducer was constructed with a ``View``.
+
+   .. rubric:: Explicit Deduction Guides (CTAD):
+
+   .. cpp:function:: template<typename T, typename I, typename... Ps> MinFirstLoc(View<ValLocScalar<T, I>, Ps...> const&) -> MinFirstLoc<T, I, View<ValLocScalar<T, I>, Ps...>::memory_space>;
+
+Additional Information
+^^^^^^^^^^^^^^^^^^^^^^
+
+* ``MinFirstLoc<T, I, S>::value_type`` is specialization of ``ValLocScalar`` on non-``const`` ``T`` and non-``const`` ``I``.
+
+* ``MinFirstLoc<T, I, S>::result_view_type`` is ``View<T,S,MemoryTraits<Unmanaged>>``. Note that the ``S`` (memory space) must be the same as the space where the result resides.
+
+* Requires: ``Scalar`` has ``operator=`` and ``operator>`` defined. ``reduction_identity<Scalar>::max()`` is a valid expression.
+
+* Requires: ``Index`` has ``operator=`` defined. ``reduction_identity<Index>::min()`` is a valid expression.
+
+* In order to use ``MinFirstLoc`` with a custom type of either ``Scalar`` or ``Index``, a template specialization of ``reduction_identity<CustomType>`` must be defined. See `Built-In Reducers with Custom Scalar Types <../../../ProgrammingGuide/Custom-Reductions-Built-In-Reducers-with-Custom-Scalar-Types.html>`_ for details.

docs/source/API/core/builtinreducers/MinLoc.rst

@@ -83,6 +83,10 @@ Interface
 
       Store minimum with index of ``src`` and ``dest`` into ``dest``:  ``dest = (src.val < dest.val) ? src :dest;``.
 
+   .. note:: It is unspecified which index is stored if there are duplicate equivalent minimum values.  To ensure the smallest index, use MinFirstLoc_ instead of ``MinLoc``.
+
+   .. _MinFirstLoc: ../builtinreducers/MinFirstLoc.html
+
    .. cpp:function:: KOKKOS_INLINE_FUNCTION void init(value_type& val) const;
 
       Initialize ``val.val`` using the ``Kokkos::reduction_identity<Scalar>::min()`` method. The default implementation sets ``val=<TYPE>_MAX``.