Value-View Interface

RELEASE_NOTES.md

@@ -5,6 +5,15 @@ Version v2025.01.0 -- Release date 2025-01-31
 Notable changes include:
 
   * New features / API changes:
+    * Value-View Interface for wrapping complex classes in a GPU compatible Interface.
+      * Enabled w/ `SPHERAL_ENABLE_VVI=On`.
+      * Example executables demonstrating :
+        * Basic class w/ ManagedVector member.
+        * CRTP pattern.
+        * `Spheral::Field` like structure w/ an abstract inferface base class.
+      * VVI Implmenetation of `Spheral::QuadraticInterpolator`.
+    * CTest unit tests for `QuadraticInterpolator` and `Field`.
+    * CTest runs during GitlabCI build stage.
     * MPI variables are now wrapped as
       ```
       SPHERAL_OP_SUM, SPHERAL_OP_MAX, SPHERAL_OP_MIN

cmake/CMakeDefinitions.cmake

@@ -16,6 +16,15 @@ else()
   add_definitions("-DDEBUG=0")
 endif()
 
+if (SPHERAL_ENABLE_VVI)
+  message("-- Value-View Interface Pattern (VVI) : Enabled")
+  message("------ WARNING ------")
+  message("-- VVI is an experimental implementation necessary for the GPU port. Use with caution!")
+  message("---------------------")
+else()
+  message("-- Semantic Class Interface Pattern (VVI) : Disabled")
+endif()
+
 # The DBC flag
 if (DBC_MODE STREQUAL "All")
   message("-- DBC (design by contract) set to All")

cmake/SetupSpheral.cmake

@@ -11,6 +11,11 @@ if (NOT SPHERAL_CMAKE_MODULE_PATH)
 endif()
 list(APPEND CMAKE_MODULE_PATH "${SPHERAL_CMAKE_MODULE_PATH}")
 
+#-------------------------------------------------------------------------------
+# Add Spheral CMake Macros for tests and executables
+#-------------------------------------------------------------------------------
+include(SpheralMacros)
+
 #-------------------------------------------------------------------------------
 # Set Compiler Flags / Options
 #-------------------------------------------------------------------------------
@@ -85,6 +90,19 @@ if(ENABLE_CUDA)
   #set(CMAKE_CUDA_FLAGS  "${CMAKE_CUDA_FLAGS} -arch=${CUDA_ARCH} --expt-relaxed-constexpr --extended-lambda -Xcudafe --display_error_number")
   set(CMAKE_CUDA_STANDARD 17)
   list(APPEND SPHERAL_CXX_DEPENDS cuda)
+  set(SPHERAL_ENABLE_CUDA On)
+  set(SPHERAL_ENABLE_VVI On)
+endif()
+message("Enable Value-View Interface Pattern (VVI) : ${SPHERAL_ENABLE_VVI}")
+
+if(ENABLE_HIP)
+  list(APPEND SPHERAL_CXX_DEPENDS blt::hip)
+  list(APPEND SPHERAL_CXX_DEPENDS blt::hip_runtime)
+endif()
+
+if(ENABLE_HIP)
+  list(APPEND SPHERAL_CXX_DEPENDS blt::hip)
+  list(APPEND SPHERAL_CXX_DEPENDS blt::hip_runtime)
 endif()
 
 if(ENABLE_HIP)
@@ -145,6 +163,10 @@ set_property(GLOBAL PROPERTY SPHERAL_CXX_DEPENDS "${SPHERAL_CXX_DEPENDS}")
 #-------------------------------------------------------------------------------
 # Prepare to build the src
 #-------------------------------------------------------------------------------
+configure_file(${SPHERAL_ROOT_DIR}/src/config.hh.in
+  ${PROJECT_BINARY_DIR}/src/config.hh)
+include_directories(${PROJECT_BINARY_DIR}/src)
+
 add_subdirectory(${SPHERAL_ROOT_DIR}/src)
 
 #-------------------------------------------------------------------------------
@@ -158,6 +180,8 @@ endif()
 # Build C++ tests and install tests to install directory
 #-------------------------------------------------------------------------------
 if (ENABLE_TESTS)
+  add_subdirectory(${SPHERAL_ROOT_DIR}/tests)
+
   spheral_install_python_tests(${SPHERAL_ROOT_DIR}/tests/ ${SPHERAL_TEST_INSTALL_PREFIX})
   # Always install performance.py in the top of the testing script
   install(FILES ${SPHERAL_ROOT_DIR}/tests/performance.py

cmake/SpheralMacros.cmake

@@ -0,0 +1,91 @@
+macro(spheral_add_executable)
+  set(options )
+  set(singleValueArgs NAME TEST REPRODUCER BENCHMARK)
+  set(multiValueArgs SOURCES DEPENDS_ON)
+
+  cmake_parse_arguments(arg
+    "${options}" "${singleValueArgs}" "${multiValueArgs}" ${ARGN})
+
+  if (ENABLE_OPENMP)
+    list (APPEND arg_DEPENDS_ON openmp)
+  endif ()
+
+  if (ENABLE_CUDA)
+    list (APPEND arg_DEPENDS_ON cuda)
+  endif ()
+
+  if (ENABLE_HIP)
+    list (APPEND arg_DEPENDS_ON blt::hip)
+    list (APPEND arg_DEPENDS_ON blt::hip_runtime)
+  endif ()
+
+  if (${arg_TEST})
+    set (_output_dir ${CMAKE_BINARY_DIR}/test)
+  elseif (${arg_REPRODUCER})
+    set (_output_dir ${CMAKE_BINARY_DIR}/reproducers)
+  elseif (${arg_BENCHMARK})
+    set (_output_dir ${CMAKE_BINARY_DIR}/benchmark)
+  else ()
+    set (_output_dir ${CMAKE_BINARY_DIR}/bin)
+  endif()
+
+  blt_add_executable(
+    NAME ${arg_NAME}
+    SOURCES ${arg_SOURCES}
+    DEPENDS_ON ${arg_DEPENDS_ON}
+    OUTPUT_DIR ${_output_dir}
+    )
+
+  target_include_directories(${arg_NAME} SYSTEM PRIVATE ${SPHERAL_EXTERN_INCLUDES})
+  target_include_directories(${arg_NAME} SYSTEM PRIVATE ${SPHERAL_ROOT_DIR}/src)
+  target_include_directories(${arg_NAME} SYSTEM PRIVATE ${PROJECT_BINARY_DIR}/src)
+
+endmacro(spheral_add_executable)
+
+macro(spheral_add_test)
+  set(options DEBUG_LINKER)
+  set(singleValueArgs NAME)
+  set(multiValueArgs SOURCES DEPENDS_ON)
+
+  cmake_parse_arguments(arg
+    "${options}" "${singleValueArgs}" "${multiValueArgs}" ${ARGN})
+
+  set(original_test_name ${arg_NAME})
+  set(original_src ${arg_SOURCES})
+  set(original_deps ${arg_DEPENDS_ON})
+
+  if (ENABLE_DEV_BUILD)
+    message("Skipping ${original_test_name} : NOT compatible with ENABLE_DEV_BUILD.")
+  else()
+    get_property(SPHERAL_BLT_DEPENDS GLOBAL PROPERTY SPHERAL_BLT_DEPENDS)
+
+    blt_add_library(
+      NAME ${original_test_name}_lib
+      SOURCES ${TEST_LIB_SOURCE}
+      SOURCES ${SPHERAL_ROOT_DIR}/src/spheralCXX.cc
+      DEPENDS_ON ${SPHERAL_BLT_DEPENDS} ${original_deps}
+      SHARED False
+      )
+
+    target_link_options(${original_test_name}_lib PRIVATE "-Wl,--unresolved-symbols=ignore-in-object-files")
+
+    spheral_add_executable(
+      NAME ${original_test_name}.exe
+      SOURCES ${original_src}
+      DEPENDS_ON gtest ${CMAKE_THREAD_LIBS_INIT} ${original_test_name}_lib
+      TEST On)
+
+    blt_add_test(
+      NAME ${original_test_name}
+      COMMAND ${TEST_DRIVER} ${original_test_name}.exe)
+
+    target_include_directories(${original_test_name}.exe SYSTEM PRIVATE ${SPHERAL_ROOT_DIR}/tests/cpp/include)
+
+    if (${arg_DEBUG_LINKER})
+      target_link_options(${original_test_name}.exe PUBLIC "-Wl,--warn-unresolved-symbols")
+    else()
+      target_link_options(${original_test_name}.exe PUBLIC "-Wl,--unresolved-symbols=ignore-all")
+    endif()
+  endif()
+
+endmacro(spheral_add_test)

docs/build_guide/include/appendecies/cmake_config.rst.inc

@@ -88,6 +88,9 @@ In this section we list the CMake variables that can be tweaked for a Spheral bu
 ``ENABLE_DEV_BUILD`` (On, **Off**)
   Builds separate internal C++ libraries for faster code development.
 
+``SPHERAL_ENABLE_VVI`` (On, *Off*)
+  Builds Spheral with the experimental Value-View Interface for GPU porting capabilities.
+
 ``<TPL-Name-Here>_DIR``
   Directory of previously built TPL.