Merge pull request #12 from uliegecsm/concepts-view

concepts(core): additional concepts for the `Kokkos::View`

CMakeLists.txt

@@ -60,6 +60,8 @@ target_sources(
         include/kokkos-utils/concepts/MemorySpace.hpp
         include/kokkos-utils/concepts/Space.hpp
         include/kokkos-utils/concepts/View.hpp
+
+        include/kokkos-utils/impl/type_traits.hpp
 )
 
 target_include_directories(

docs/CMakeLists.txt

@@ -1,4 +1,4 @@
-#--- Find Doxygen.
+#---- Find Doxygen.
 string(JSON Doxygen_REQUIRED_VERSION GET "${VERSION_JSON}" dependencies doxygen value)
 
 find_package(
@@ -7,16 +7,28 @@ find_package(
     REQUIRED
 )
 
+#---- Fetch Kokkos tag file. Note that the Kokkos project does not generate a tag file, but Trilinos does.
+set(KOKKOS_TAG_FILE     "${CMAKE_CURRENT_BINARY_DIR}/Kokkos.tag")
+set(KOKKOS_TAG_FILE_URL "https://docs.trilinos.org/dev/packages/common/tag_files/kokkos.tag")
+message(STATUS "Fetching Kokkos tag file with ${KOKKOS_TAG_FILE_URL} and storing it to ${KOKKOS_TAG_FILE}.")
+file(DOWNLOAD ${KOKKOS_TAG_FILE_URL} ${KOKKOS_TAG_FILE} STATUS fetch_kokkos_tag_file_status)
+list(GET fetch_kokkos_tag_file_status 0 fetch_kokkos_tag_file_status_return_code)
+if(NOT fetch_kokkos_tag_file_status_return_code EQUAL 0)
+    message(FATAL_ERROR "An error occurred while fetching tag file for package Kokkos with ${KOKKOS_TAG_FILE_URL} (${fetch_kokkos_tag_file_status}).")
+endif()
+
 #---- Our 'homepage' is the README file.
 set(HOMEPAGE_MD ${CMAKE_SOURCE_DIR}/README.md)
 
 #---- Doxygen settings.
 set(DOXYGEN_USE_MDFILE_AS_MAINPAGE ${HOMEPAGE_MD})
 set(DOXYGEN_TIMESTAMP YES)
+set(DOXYGEN_EXTRACT_ALL YES)
 set(DOXYGEN_WARN_AS_ERROR YES)
 set(DOXYGEN_SOURCE_BROWSER YES)
 set(DOXYGEN_WARN_IF_UNDOCUMENTED NO)
 set(DOXYGEN_GENERATE_TAGFILE "${CMAKE_CURRENT_BINARY_DIR}/html/${CMAKE_PROJECT_NAME}.tag")
+set(DOXYGEN_TAGFILES "${KOKKOS_TAG_FILE}")
 
 #---- Extract files for documentation.
 get_target_property(KokkosUtils_TARGET_FILES_FOR_DOC KokkosUtils INTERFACE_SOURCES)
@@ -38,4 +50,5 @@ doxygen_add_docs(
 
     # Files NOT added to the global property KokkosUtils_FILES_FOR_DOC
     ${CMAKE_SOURCE_DIR}/docs/tests.dox
+    ${CMAKE_SOURCE_DIR}/tests/main.cpp
 )

include/kokkos-utils/atomics/InsertOp.hpp

@@ -11,7 +11,7 @@ namespace Kokkos::utils::atomics
 /**
  * @brief Insert an element in a view at a specific index using @c Kokkos::atomic_min.
  *
- * To be used with *e.g.* @c Kokkos::UnorderedMap::insert.
+ * To be used with *e.g.* @ref Kokkos::UnorderedMap::insert.
  */
 struct InsertMin
 {

include/kokkos-utils/concepts/DualView.hpp

@@ -6,7 +6,7 @@
 namespace Kokkos::utils::concepts
 {
 
-//! Concept to specify that a type is a @c Kokkos::DualView.
+//! Specify that a type is a @c Kokkos::DualView.
 template <typename T>
 concept DualView = Kokkos::is_dual_view_v<T>;
 

include/kokkos-utils/concepts/ExecutionSpace.hpp

@@ -6,7 +6,7 @@
 namespace Kokkos::utils::concepts
 {
 
-//! Concept to specify that a type is a @c Kokkos execution space.
+//! Specify that a type is a @ref Kokkos execution space.
 template <typename T>
 concept ExecutionSpace = Kokkos::is_execution_space_v<T>;
 

include/kokkos-utils/concepts/MemorySpace.hpp

@@ -6,7 +6,7 @@
 namespace Kokkos::utils::concepts
 {
 
-//! Concept to specify that a type is a @c Kokkos memory space.
+//! Specify that a type is a @ref Kokkos memory space.
 template <typename T>
 concept MemorySpace = Kokkos::is_memory_space_v<T>;
 

include/kokkos-utils/concepts/Space.hpp

@@ -6,7 +6,7 @@
 namespace Kokkos::utils::concepts
 {
 
-//! Concept to specify that a type is a @c Kokkos space.
+//! Specify that a type is a @ref Kokkos space.
 template <typename T>
 concept Space = Kokkos::is_space<T>::value;
 

include/kokkos-utils/concepts/View.hpp

@@ -1,15 +1,35 @@
 #ifndef KOKKOS_UTILS_CONCEPTS_VIEW_HPP
 #define KOKKOS_UTILS_CONCEPTS_VIEW_HPP
 
+#include <concepts>
+
 #include "Kokkos_View.hpp"
 
+#include "kokkos-utils/impl/type_traits.hpp"
+
 namespace Kokkos::utils::concepts
 {
 
-//! Concept to specify that a type is a @c Kokkos::View.
+//! Specify that a type is a @ref Kokkos::View.
 template <typename T>
 concept View = Kokkos::is_view_v<T>;
 
+//! Specify that a type is a @ref Kokkos::View of given rank @p Rank.
+template <typename T, std::size_t Rank>
+concept ViewOfRank = View<T> && T::rank == Rank;
+
+//! Specify that a type is a modifiable @ref Kokkos::View.
+template <typename T>
+concept ModifiableView = View<T> && ! std::is_const_v<typename T::value_type>;
+
+//! Specify that a type is a @ref Kokkos::View with value type @p ValueType.
+template <typename T, typename ValueType>
+concept ViewOf = View<T> && std::same_as<typename T::value_type, ValueType>;
+
+//! Specify that a type is a @ref Kokkos::View, whose value type is an instance of a given class template @p U.
+template <typename T, template <typename...> class U>
+concept ViewOfInstanceOf = View<T> && impl::InstanceOf<typename T::value_type, U>;
+
 } // namespace Kokkos::utils::concepts
 
 #endif // KOKKOS_UTILS_CONCEPTS_VIEW_HPP

include/kokkos-utils/impl/type_traits.hpp

@@ -0,0 +1,34 @@
+#ifndef KOKKOS_UTILS_IMPL_TYPE_TRAITS_HPP
+#define KOKKOS_UTILS_IMPL_TYPE_TRAITS_HPP
+
+#include <type_traits>
+
+/**
+ * @brief This namespace provides extensions to the @c type_traits standard header.
+ *
+ * References:
+ *      * https://en.cppreference.com/w/cpp/header/type_traits
+ */
+namespace Kokkos::utils::impl
+{
+
+/**
+ * @name Check if a type is an instantiation of a given class template.
+ *
+ * References:
+ *      * https://indii.org/blog/is-type-instantiation-of-template/
+ */
+///@{
+template <class T, template <typename...> class U>
+inline constexpr bool is_instance_of_v = std::false_type{};
+
+template <template <typename...> class U, typename... Vs>
+inline constexpr bool is_instance_of_v<U<Vs...>, U> = std::true_type{};
+
+template <typename T, template <typename...> class U>
+concept InstanceOf = is_instance_of_v<T, U>;
+///@}
+
+} // namespace Kokkos::utils::impl
+
+#endif // KOKKOS_UTILS_IMPL_TYPE_TRAITS_HPP

tests/CMakeLists.txt

@@ -82,3 +82,6 @@ add_subdirectory(atomics)
 
 ### TESTS : concepts ###
 add_subdirectory(concepts)
+
+### TESTS : impl ###
+add_subdirectory(impl)

tests/concepts/test_DualView.cpp

@@ -21,22 +21,25 @@ namespace Kokkos::utils::tests::concepts
 //! @test Check that @ref Kokkos::utils::concepts::DualView works as expected.
 TEST(concepts, DualView)
 {
+    using Kokkos::utils::concepts::DualView;
+    using Kokkos::utils::concepts::View;
+
     using dual_view_1d_t = Kokkos::DualView<int[5]   , execution_space>;
     using      view_1d_t = Kokkos::    View<int[5]   , execution_space>;
     using dual_view_2d_t = Kokkos::DualView<int[5][5], execution_space>;
     using      view_2d_t = Kokkos::    View<int[5][5], execution_space>;
 
     //! A @c Kokkos::DualView fulfills the concept.
-    static_assert(Kokkos::utils::concepts::DualView<dual_view_1d_t>);
-    static_assert(Kokkos::utils::concepts::DualView<dual_view_2d_t>);
+    static_assert(DualView<dual_view_1d_t>);
+    static_assert(DualView<dual_view_2d_t>);
 
-    //! A @c Kokkos::View does not fulfill the concept.
-    static_assert(! Kokkos::utils::concepts::DualView<view_1d_t>);
-    static_assert(! Kokkos::utils::concepts::DualView<view_2d_t>);
+    //! A @ref Kokkos::View does not fulfill the concept.
+    static_assert(! DualView<view_1d_t>);
+    static_assert(! DualView<view_2d_t>);
 
     //! A @c Kokkos::DualView does not fulfill the @ref Kokkos::utils::concepts::View concept.
-    static_assert(! Kokkos::utils::concepts::View<dual_view_1d_t>);
-    static_assert(! Kokkos::utils::concepts::View<dual_view_2d_t>);
+    static_assert(! View<dual_view_1d_t>);
+    static_assert(! View<dual_view_2d_t>);
 }
 
 } // namespace Kokkos::utils::tests::concepts

tests/concepts/test_ExecutionSpace.cpp

@@ -11,9 +11,9 @@ using execution_space = Kokkos::DefaultExecutionSpace;
  *
  * @addtogroup unittests
  *
- * **Concepts related to @c Kokkos execution space**
+ * **Concepts related to @ref Kokkos execution space**
  *
- * This group of tests check the behavior of our concepts related to @c Kokkos execution space.
+ * This group of tests check the behavior of our concepts related to @ref Kokkos execution space.
  */
 
 namespace Kokkos::utils::tests::concepts
@@ -22,9 +22,11 @@ namespace Kokkos::utils::tests::concepts
 //! @test Check that @ref Kokkos::utils::concepts::ExecutionSpace works as expected.
 TEST(concepts, ExecutionSpace)
 {
-    static_assert(  Kokkos::utils::concepts::ExecutionSpace<typename execution_space::execution_space>);
-    static_assert(! Kokkos::utils::concepts::ExecutionSpace<typename execution_space::memory_space>);
-    static_assert(! Kokkos::utils::concepts::ExecutionSpace<Kokkos::Device<typename execution_space::execution_space, typename execution_space::memory_space>>);
+    using Kokkos::utils::concepts::ExecutionSpace;
+
+    static_assert(  ExecutionSpace<typename execution_space::execution_space>);
+    static_assert(! ExecutionSpace<typename execution_space::memory_space>);
+    static_assert(! ExecutionSpace<Kokkos::Device<typename execution_space::execution_space, typename execution_space::memory_space>>);
 }
 
 } // namespace Kokkos::utils::tests::concepts

tests/concepts/test_MemorySpace.cpp

@@ -11,9 +11,9 @@ using execution_space = Kokkos::DefaultExecutionSpace;
  *
  * @addtogroup unittests
  *
- * **Concepts related to @c Kokkos memory space**
+ * **Concepts related to @ref Kokkos memory space**
  *
- * This group of tests check the behavior of our concepts related to @c Kokkos memory space.
+ * This group of tests check the behavior of our concepts related to @ref Kokkos memory space.
  */
 
 namespace Kokkos::utils::tests::concepts
@@ -22,9 +22,11 @@ namespace Kokkos::utils::tests::concepts
 //! @test Check that @ref Kokkos::utils::concepts::MemorySpace works as expected.
 TEST(concepts, MemorySpace)
 {
-    static_assert(! Kokkos::utils::concepts::MemorySpace<typename execution_space::execution_space>);
-    static_assert(  Kokkos::utils::concepts::MemorySpace<typename execution_space::memory_space>);
-    static_assert(! Kokkos::utils::concepts::MemorySpace<Kokkos::Device<typename execution_space::execution_space, typename execution_space::memory_space>>);
+    using Kokkos::utils::concepts::MemorySpace;
+
+    static_assert(! MemorySpace<typename execution_space::execution_space>);
+    static_assert(  MemorySpace<typename execution_space::memory_space>);
+    static_assert(! MemorySpace<Kokkos::Device<typename execution_space::execution_space, typename execution_space::memory_space>>);
 }
 
 } // namespace Kokkos::utils::tests::concepts

tests/concepts/test_Space.cpp

@@ -11,9 +11,9 @@ using execution_space = Kokkos::DefaultExecutionSpace;
  *
  * @addtogroup unittests
  *
- * **Concepts related to @c Kokkos space**
+ * **Concepts related to @ref Kokkos space**
  *
- * This group of tests check the behavior of our concepts related to @c Kokkos space.
+ * This group of tests check the behavior of our concepts related to @ref Kokkos space.
  */
 
 namespace Kokkos::utils::tests::concepts
@@ -22,9 +22,11 @@ namespace Kokkos::utils::tests::concepts
 //! @test Check that @ref Kokkos::utils::concepts::Space works as expected.
 TEST(concepts, Space)
 {
-    static_assert(Kokkos::utils::concepts::Space<typename execution_space::execution_space>);
-    static_assert(Kokkos::utils::concepts::Space<typename execution_space::memory_space>);
-    static_assert(Kokkos::utils::concepts::Space<Kokkos::Device<typename execution_space::execution_space, typename execution_space::memory_space>>);
+    using Kokkos::utils::concepts::Space;
+
+    static_assert(Space<typename execution_space::execution_space>);
+    static_assert(Space<typename execution_space::memory_space>);
+    static_assert(Space<Kokkos::Device<typename execution_space::execution_space, typename execution_space::memory_space>>);
 }
 
 } // namespace Kokkos::utils::tests::concepts

tests/concepts/test_View.cpp

@@ -1,5 +1,9 @@
+#include <tuple>
+
 #include "gtest/gtest.h"
 
+#include "Kokkos_Core.hpp"
+
 #include "kokkos-utils/concepts/View.hpp"
 
 using execution_space = Kokkos::DefaultExecutionSpace;
@@ -9,9 +13,9 @@ using execution_space = Kokkos::DefaultExecutionSpace;
  *
  * @addtogroup unittests
  *
- * **Concepts related to @c Kokkos::View**
+ * **Concepts related to @ref Kokkos::View**
  *
- * This group of tests check the behavior of our concepts related to @c Kokkos::View.
+ * This group of tests check the behavior of our concepts related to @ref Kokkos::View.
  */
 
 namespace Kokkos::utils::tests::concepts
@@ -27,4 +31,60 @@ TEST(concepts, View)
     static_assert(Kokkos::utils::concepts::View<view_2d_t>);
 }
 
+//! @test Check @ref Kokkos::utils::concepts::ViewOfInstanceOf.
+TEST(concepts, ViewOfInstanceOf)
+{
+    using Kokkos::utils::concepts::ViewOfInstanceOf;
+
+    static_assert(  ViewOfInstanceOf<Kokkos::View<std::tuple<int> , execution_space>, std::tuple>);
+    static_assert(  ViewOfInstanceOf<Kokkos::View<std::tuple<int>*, execution_space>, std::tuple>);
+    static_assert(! ViewOfInstanceOf<Kokkos::View<std::tuple<int>*, execution_space>, Kokkos::IndexType>);
+}
+
+//! @test Check @ref Kokkos::utils::concepts::ViewOf.
+TEST(concepts, ViewOf)
+{
+    using Kokkos::utils::concepts::ViewOf;
+
+    static_assert(  ViewOf<Kokkos::View<double       , execution_space>, double>);
+    static_assert(  ViewOf<Kokkos::View<double[5]    , execution_space>, double>);
+    static_assert(  ViewOf<Kokkos::View<double*      , execution_space>, double>);
+    static_assert(  ViewOf<Kokkos::View<double**     , execution_space>, double>);
+    static_assert(  ViewOf<Kokkos::View<const double*, execution_space>, const double>);
+    static_assert(! ViewOf<Kokkos::View<const double*, execution_space>, double>);
+    static_assert(! ViewOf<Kokkos::View<int          , execution_space>, double>);
+    static_assert(! ViewOf<             double                         , double>);
+}
+
+//! @test Check the behavior of @ref Kokkos::utils::concepts::ViewOfRank.
+TEST(concepts, ViewOfRank)
+{
+    using Kokkos::utils::concepts::ViewOfRank;
+
+    using int_0d_view_t = Kokkos::View<int  , execution_space>;
+    using int_1d_view_t = Kokkos::View<int* , execution_space>;
+    using int_2d_view_t = Kokkos::View<int**, execution_space>;
+
+    static_assert(  ViewOfRank<int_0d_view_t, 0>);
+    static_assert(! ViewOfRank<int_0d_view_t, 1>);
+
+    static_assert(  ViewOfRank<int_1d_view_t, 1>);
+    static_assert(! ViewOfRank<int_1d_view_t, 2>);
+
+    static_assert(! ViewOfRank<int_2d_view_t, 1>);
+    static_assert(  ViewOfRank<int_2d_view_t, 2>);
+}
+
+//! @test Check the behavior of @ref Kokkos::utils::concepts::ModifiableView.
+TEST(concepts, ModifiableView)
+{
+    using Kokkos::utils::concepts::ModifiableView;
+
+    using       double_view_t = Kokkos::View<      double*, execution_space>;
+    using const_double_view_t = Kokkos::View<const double*, execution_space>;
+
+    static_assert(  ModifiableView<      double_view_t>);
+    static_assert(! ModifiableView<const_double_view_t>);
+}
+
 } // namespace Kokkos::utils::tests::concepts

tests/impl/CMakeLists.txt

@@ -0,0 +1,4 @@
+### TEST : type_traits ###
+add_one_test(
+    TEST_NAME type_traits
+)