Merge branch 'master' into zip-iterator

alpaka-group · Jan 18, 2022 · 996aa55 · 996aa55
2 parents 6cc43fa + 91028b1
commit 996aa55
Show file tree

Hide file tree

Showing 30 changed files with 7,014 additions and 276 deletions.
diff --git a/.gitignore b/.gitignore
@@ -25,3 +25,5 @@
 # igonre build and install folder
 /build*
 /install*
+
+.vscode
diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
@@ -1,8 +1,8 @@
 ################################################################################
 # VIKUNJA_CXX                             : {g++, clang++}
-#   [g++]                                 : {5, 6, 7, 8, 9} <list>
+#   [g++]                                 : {7, 8, 9, 10, 11} <list>
 #   [clang++]                             : {4.0, 5.0, 6.0, 7, 8, 9, 10} <list>
-# ALPAKA_CXX_STANDARD                     . {14, 17, 20}, optional
+# ALPAKA_CXX_STANDARD                     . {17, 20}, optional
 # VIKUNJA_BOOST_VERSIONS                  : {1.65.1, 1.66.0, 1.67.0, 1.68.0, 1.69.0, 1.70.0, 1.71.0, 1.72.0, 1.73.0} <list>
 # VIKUNJA_BUILD_TYPE                      : {Debug, Release}
 # VIKUNJA_CMAKE_ARGS                      : <string>
@@ -38,13 +38,6 @@ pull-request-validation:
 variables:
   VIKUNJA_ALPAKA_VERSIONS: "0.6.0 0.6.1 0.7.0 0.8.0"
 
-cuda102:
-  image: registry.gitlab.com/hzdr/crp/alpaka-group-container/alpaka-ci-cuda102-gcc:1.4
-  variables:
-    VIKUNJA_CXX: "g++-7"
-    VIKUNJA_BOOST_VERSIONS: "1.65.1 1.66.0 1.67.0 1.68.0 1.69.0 1.70.0 1.71.0 1.72.0 1.73.0"
-  extends: .base_cuda
-
 cuda112:
   image: registry.gitlab.com/hzdr/crp/alpaka-group-container/alpaka-ci-cuda112-gcc:1.4
   variables:
@@ -54,7 +47,7 @@ cuda112:
 
 gcc:
   variables:
-    VIKUNJA_CXX: "g++-5 g++-6 g++-7 g++-8 g++-9"
+    VIKUNJA_CXX: "g++-7 g++-8 g++-9 g++-10 g++-11"
     VIKUNJA_BOOST_VERSIONS: "1.65.1 1.75.0"
   extends: .base_gcc
 

diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -13,24 +13,23 @@ project(vikunja
   HOMEPAGE_URL "https://github.com/alpaka-group/vikunja"
   LANGUAGES    CXX)
 
-set(ALPAKA_CXX_STANDARD "14" CACHE STRING "C++ standard version")
+set(ALPAKA_CXX_STANDARD "17" CACHE STRING "C++ standard version")
 
 include(CMakeDependentOption)
 include(FetchContent)
 
 option(VIKUNJA_BUILD_EXAMPLES "Build the examples" OFF)
-option(VIKUNJA_BUILD_DOXYGEN "Build the doxygen documentation" OFF)
 option(VIKUNJA_ENABLE_EXTRA_WARNINGS "Enable extra warnings" OFF)
 option(BUILD_TESTING "Build the testing tree." OFF)
-cmake_dependent_option(VIKUNJA_SYSTEM_CATCH2 "Use your local installation of Catch2 v3" ON BUILD_TESTING OFF)
+cmake_dependent_option(VIKUNJA_SYSTEM_CATCH2 "Use your local installation of Catch2" ON BUILD_TESTING OFF)
 cmake_dependent_option(VIKUNJA_ENABLE_CXX_TEST "Builds test that checks if the C++ standard is set correctly" OFF BUILD_TESTING OFF)
 
 # activate support for host/device lambdas in cuda
 # needs to be set before alpaka is included
 if(ALPAKA_ACC_GPU_CUDA_ENABLE)
   # DEPRECATED: used until alpaka 0.6.x
   set(ALPAKA_CUDA_NVCC_EXPT_EXTENDED_LAMBDA ON)
-  # used with alpaka 0.7.0 and below
+  # used with alpaka 0.7.0 and later
   set(ALPAKA_CUDA_EXPT_EXTENDED_LAMBDA ON)
 endif()
 
@@ -50,14 +49,17 @@ if(NOT TARGET alpaka::alpaka)
   endif()
 endif()
 
+# Override poperty, as alpaka <= 0.8.0 supports C++ 14 and vikunja does not.
+set_property(CACHE ALPAKA_CXX_STANDARD PROPERTY STRINGS "17;20")
+
 add_library(${PROJECT_NAME} INTERFACE)
 target_include_directories(${PROJECT_NAME}
   INTERFACE
   $<BUILD_INTERFACE:${PROJECT_SOURCE_DIR}/include>
   $<INSTALL_INTERFACE:include>)
 add_library(${PROJECT_NAME}::${PROJECT_NAME} ALIAS ${PROJECT_NAME})
 
-#The target vikunja::internalvikunja is for internal use only, such as the tests or examples.
+# The target vikunja::internalvikunja is for internal use only, such as the tests or examples.
 # For external projects that use vikunja, the target vikunja::vikunja should be used.
 
 # The internal target links alpaka to make it easier to use vikunja, but the target cannot be
@@ -125,16 +127,6 @@ if(${CMAKE_PROJECT_NAME} STREQUAL ${PROJECT_NAME})
     DESTINATION "${CMAKE_INSTALL_LIBDIR}/cmake/${PROJECT_NAME}")
   install(DIRECTORY ${PROJECT_SOURCE_DIR}/include/ DESTINATION include)
 
-  #########################################
-  ############# Documentation #############
-  #########################################
-
-  # Use doxygen for api doc when available.
-  if(VIKUNJA_BUILD_DOXYGEN)
-    find_package(Doxygen REQUIRED)
-    doxygen_add_docs(doc include/)
-  endif()
-
   #########################################
   ################ Testing ################
   #########################################

diff --git a/README.md b/README.md
@@ -1,19 +1,32 @@
-# Primitives for Alpaka
-This contains a `reduce` and a `transform` primitive for Alpaka, both header-only.
-Directories:
-* `include/vikunja`: The actual code
-    - `mem/iterator`: Contains a base iterator class and a policy based iterator that can vary the memory access pattern: Either a linear or a grid-striding access is possible.
-    - `reduce`: Contains the `transform_reduce` and the `reduce` function (the latter is just a convenient wrapper around the former).
-        + `detail`: This contains the two possible reduce kernels.
-    - `transform`: Contains two `transform` variants with one and two input iterators.
-        + `detail`: This contains the transform kernel.
-    - `workdiv`: This contains various working divisions for the different backends.
+# Vikunja
+
+[![Build Status](https://gitlab.com/hzdr/crp/vikunja/badges/master/pipeline.svg)](https://gitlab.com/hzdr/crp/vikunja/-/commits/master/)
+[![Documentation Status](https://readthedocs.org/projects/vikunja/badge/?version=latest)](https://vikunja.readthedocs.io)
+[![Doxygen](https://img.shields.io/badge/API-Doxygen-blue.svg)](https://vikunja.readthedocs.io/en/latest/doxygen/index.html)
+[![Language](https://img.shields.io/badge/language-C%2B%2B17-orange.svg)](https://isocpp.org/)
+[![Platforms](https://img.shields.io/badge/platform-linux-lightgrey.svg)](https://github.com/alpaka-group/vikunja)
+[![License](https://img.shields.io/badge/license-MPL--2.0-blue.svg)](https://www.mozilla.org/en-US/MPL/2.0/)
+
+![vikunja](docs/source/logo/vikunja_logo.png)
+
+Vikunja is a performance portable algorithm library that defines functions operating on ranges of elements for a variety of purposes . It supports the execution on multi-core CPUs and various GPUs.
+
+Vikunja uses [alpaka](https://github.com/alpaka-group/alpaka) to implement platform-independent primitives such as `reduce` or `transform`. 
 
 # Installation
+## Install Alpaka
+
+Alpaka requires a [boost installation](https://github.com/alpaka-group/alpaka#dependencies).
 
-## Requirements
+```bash
+git clone --depth 1 --branch 0.8.0 https://github.com/alpaka-group/alpaka.git
+mkdir alpaka/build
+cd alpaka/build
+cmake ..
+cmake --install .
+```
 
-[Alpaka 0.6.0](https://github.com/alpaka-group/alpaka)
+For more information see the [alpaka GitHub](https://github.com/alpaka-group/alpaka) repository. It is recommended to use the latest release version. Vikunja supports `alpaka` from version `0.6` up to version `0.8`.
 
 ## Install Vikunja
 
@@ -25,54 +38,163 @@ cmake ..
 cmake --install .
 ```
 
-## Enable tests
+## Build and Run Tests
 
 ```bash
+cd vikunja/build
 cmake .. -DBUILD_TESTING=ON
+ctest
 ```
 
 ## Enable Examples
 
 ```bash
 cmake .. -Dvikunja_BUILD_EXAMPLES=ON
 ```
-Two small examples can be found in the folder `example/`.
-
-# Using Vikunja in a Project
-
-You need to import vikunja in the `CMakeLists.txt` of your Project to use it.
-
+Examples can be found in the folder `example/`.
+
+# Getting Started
+
+The following source code shows an application that uses vikunja to replace all values in a vector with their absolute values.
+
+```c++
+#include <vikunja/transform/transform.hpp>
+
+#include <alpaka/alpaka.hpp>
+
+#include <algorithm>
+#include <iostream>
+#include <random>
+
+
+int main()
+{
+    // Define the accelerator.
+    // The accelerator decides on which processor type the vikunja algorithm will be executed.
+    // The accelerators must be enabled during the CMake configuration to be available.
+    //
+    // It is possible to choose from a set of accelerators:
+    // - AccGpuCudaRt
+    // - AccGpuHipRt
+    // - AccCpuThreads
+    // - AccCpuFibers
+    // - AccCpuOmp2Threads
+    // - AccCpuOmp2Blocks
+    // - AccOmp5
+    // - AccCpuTbbBlocks
+    // - AccCpuSerial
+    using Acc = alpaka::AccCpuOmp2Blocks<alpaka::DimInt<1u>, int>;
+
+    // Create a device that executes the algorithm.
+    // For example, it can be a CPU or GPU Nr. 0 or 1 in a multi-GPU system.
+    auto const devAcc = alpaka::getDevByIdx<Acc>(0u);
+    // The host device is required if the devAcc does not use the same memory as the host.
+    // For example, if the host is a CPU and the device is a GPU.
+    auto const devHost(alpaka::getDevByIdx<alpaka::PltfCpu>(0u));
+
+    // All algorithms must be enqueued so that they are executed in the correct order.
+    using QueueAcc = alpaka::Queue<Acc, alpaka::Blocking>;
+    QueueAcc queueAcc(devAcc);
+
+    // Dimension of the problem. 1D in this case (inherited from the Accelerator).
+    using Dim = alpaka::Dim<Acc>;
+    // The index type needs to fit the problem size.
+    // A smaller index type can reduce the execution time.
+    // In this case the index type is inherited from the Accelerator: std::uint64_t.
+    using Idx = alpaka::Idx<Acc>;
+    // Type of the user data.
+    using Data = int;
+
+    // The extent stores the problem size.
+    using Vec = alpaka::Vec<Dim, Idx>;
+    Vec extent(Vec::all(static_cast<Idx>(10)));
+
+    // Allocate memory for the device.
+    auto deviceMem(alpaka::allocBuf<Data, Idx>(devAcc, extent));
+    // The memory is accessed via a pointer.
+    Data* deviceNativePtr = alpaka::getPtrNative(deviceMem);
+    // Allocate memory for the host.
+    auto hostMem(alpaka::allocBuf<Data, Idx>(devHost, extent));
+    Data* hostNativePtr = alpaka::getPtrNative(hostMem);
+
+    // Initialize the host memory with random values from -10 to 10.
+    std::uniform_int_distribution<Data> distribution(-10, 10);
+    std::default_random_engine generator;
+    std::generate(
+        hostNativePtr,
+        hostNativePtr + extent.prod(),
+        [&distribution, &generator]() { return distribution(generator); });
+
+    // Copy data to the device.
+    alpaka::memcpy(queueAcc, deviceMem, hostMem, extent);
+
+    // Use a lambda function to define the transformation function.
+    // Returns the absolute value of each input
+    auto abs = [] ALPAKA_FN_HOST_ACC(auto const& acc, Data const j) { return alpaka::math::abs(acc, j); };
+
+    vikunja::transform::deviceTransform<Acc>(
+        devAcc, // The device that executes the algorithm.
+        queueAcc, // Queue in which the algorithm is enqueued.
+        extent.prod(), // Problem size
+        deviceNativePtr, // Input memory
+        deviceNativePtr, // Operator
+        abs);
+
+    // Copy data to the host.
+    alpaka::memcpy(queueAcc, hostMem, deviceMem, extent);
+
+    for(Data i = 0; i < extent.prod(); ++i)
+    {
+        std::cout << hostNativePtr[i] << " ";
+    }
+    std::cout << std::endl;
+
+    return 0;
+}
 ```
-cmake_minimum_required(VERSION 3.15)
 
-set(_TARGET_NAME example)
-project(${_TARGET_NAME})
+CMakeLists.txt
+
+```cmake
+cmake_minimum_required(VERSION 3.18)
+project(vikunjaAbs)
 
-find_package(vikunja REQUIRED)
+add_subdirectory(vikunja REQUIRED)
 
-alpaka_add_executable(${_TARGET_NAME} main.cpp)
-target_link_libraries(${_TARGET_NAME}
-  PUBLIC
-  vikunja::vikunja
-)
+alpaka_add_executable(${CMAKE_PROJECT_NAME} main.cpp)
+target_link_libraries(${CMAKE_PROJECT_NAME} PRIVATE vikunja::vikunja)
 ```
 
-Vikunja supports `find_package(vikunja)` and `add_subdirectory(/path/to/vikunja)`. Alpaka is a dependency during the configure time of your project. If it is not installed in a default location, you can use the cmake argument `-Dalpaka_DIR=/path/to/alpakaInstall/lib/cmake/alpaka` or the environment variable `ALPAKA_ROOT=/path/to/alpakaInstall/` to find it.
+Build instructions:
+```bash
+# the source folder contains the main.cpp and the CMakeLists.txt
+cd <folder/with/source/code>
+mkdir build && cd build
+# configure build with OpenMP backend enabled
+cmake .. -DALPAKA_ACC_CPU_B_OMP2_T_SEQ_ENABLE=ON
+# compile application
+cmake --build .
+# run application
+./vikunjaAbs # output: 10 8 5 1 1 6 10 4 4 9
+```
 
 # Documentation
 
-An API documentation can be generated with [doxygen](https://www.doxygen.nl/index.html). Install doxygen and run
+- You can find the general documentation here: https://vikunja.readthedocs.io/en/latest/
+- You can find the API documentation here: https://vikunja.readthedocs.io/en/latest/doxygen/index.html
 
-```bash
-cmake .. -Dvikunja_BUILD_DOXYGEN=ON
-cmake --build . -t doc
-```
+# Authors
 
-The documentation can be found in `build/doc`.
+## Maintainers* and Core Developers
 
-# Format the code
+- Simeon Ehrig*
 
-The code is formatted with `clang-format-11`.
+## Former Members, Contributions and Thanks
 
-* Format a single file with: `clang-format -i --style=file <sourcefile>`
-* If you want to format the entire code base execute the following command from alpaka’s top-level directory: `find example include test -name '*.hpp' -o -name '*.cpp' | xargs clang-format -i --style=file`
+- Dr. Michael Bussmann
+- Hauke Mewes
+- René Widera
+- Bernhard Manfred Gruber
+- Jan Stephan
+- Dr. Jiří Vyskočil
+- Matthias Werner