Apply suggestions from code review

Co-authored-by: Jan Stephan <[email protected]>

CMakeLists.txt

@@ -21,7 +21,7 @@ include(FetchContent)
 option(VIKUNJA_BUILD_EXAMPLES "Build the examples" 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

README.md

@@ -9,9 +9,9 @@
 
 ![vikunja](docs/source/logo/vikunja_logo.png)
 
-Vikunja is a performance portable algorithms 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 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`. 
+Vikunja uses [alpaka](https://github.com/alpaka-group/alpaka) to implement platform-independent primitives such as `reduce` or `transform`. 
 
 # Installation
 ## Install Alpaka
@@ -26,7 +26,7 @@ cmake ..
 cmake --install .
 ```
 
-For more information, see the [alpaka github](https://github.com/alpaka-group/alpaka) repository. It is recommenced to use the latest release version. Vikunja supports `alpaka` `0.6` up to `0.8`.
+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
 
@@ -38,7 +38,7 @@ cmake ..
 cmake --install .
 ```
 
-# Build and Run tests
+# Build and Run Tests
 
 ```bash
 cd vikunja/build

docs/source/advanced/cmake.rst

@@ -3,52 +3,54 @@
 CMake Arguments
 ===============
 
+The value in the brackets after the argument type indicates the default value.
+
 Common
 ++++++
 
-VIKUNJA_BUILD_EXAMPLES
+**VIKUNJA_BUILD_EXAMPLES** (OFF)
     .. code-block::
 
         Build the examples.
 
-VIKUNJA_ENABLE_EXTRA_WARNINGS
+**VIKUNJA_ENABLE_EXTRA_WARNINGS** (OFF)
     .. code-block::
 
         Set some additional compiler warning flags.
 
 Testing
 +++++++
 
-BUILD_TESTING
+**BUILD_TESTING** (OFF)
     .. code-block::
 
         Build the testing tree.
 
-VIKUNJA_SYSTEM_CATCH2
+**VIKUNJA_SYSTEM_CATCH2** (OFF)
     .. code-block::
 
         Only works if BUILD_TESTING is ON.
-        Use your local installation of Catch2 v3.
+        Use your local installation of Catch2.
         Otherwise, it will be automatically downloaded and installed in the local build folder.
 
-VIKUNJA_ENABLE_CXX_TEST
+**VIKUNJA_ENABLE_CXX_TEST** (OFF)
     .. code-block::
 
         Only works if BUILD_TESTING is ON.
         Special test that checks if ALPAKA_CXX_STANDARD works correctly.
         The implementation is very compiler specific, so it is possible that the test is not supported by your used C++ compiler.
 
-Alpaka
+alpaka
 ++++++
 
-The following cmake variables are provided by alpaka. This section contains only the most important variables. To see all variables, see `here <https://alpaka.readthedocs.io/en/latest/advanced/cmake.html>`_.
+The following CMake variables are provided by alpaka. This section contains only the variables most important for vikunja. To see all variables refer to the `alpaka documentation <https://alpaka.readthedocs.io/en/latest/advanced/cmake.html>`_.
 
-ALPAKA_CXX_STANDARD
+**ALPAKA_CXX_STANDARD** (17)
     .. code-block::
 
        Set the C++ standard version.
 
-ALPAKA_ACC_<ACC>_ENABLE
+**ALPAKA_ACC_<ACC>_ENABLE** (OFF)
     .. code-block::
 
         Enable one or more accelerator backends. The following accelerators are available:
@@ -62,14 +64,15 @@ ALPAKA_ACC_<ACC>_ENABLE
         - ALPAKA_ACC_GPU_CUDA_ENABLE
         - ALPAKA_ACC_GPU_HIP_ENABLE
 
-        Important: Not all accelerator backends are tested, see CI tests.
+        Important: Not all alpaka accelerator backends are tested together with vikunja, 
+        see CI tests.
 
-ALPAKA_CUDA_NVCC_EXPT_EXTENDED_LAMBDA
+**ALPAKA_CUDA_NVCC_EXPT_EXTENDED_LAMBDA** (ON)
     .. code-block::
 
         Enable lambda support in Alpaka 0.6.x and below for the CUDA accelerator.
 
-ALPAKA_CUDA_EXPT_EXTENDED_LAMBDA
+**ALPAKA_CUDA_EXPT_EXTENDED_LAMBDA** (ON)
     .. code-block::
 
         Enable lambda support in Alpaka 0.7.x and later for the CUDA accelerator.

docs/source/basic/algorithm.rst

@@ -1,4 +1,4 @@
-Algorithm
+Algorithms
 =========
 
 This page provides an overview of all algorithms implemented in vikunja.

docs/source/basic/installation.rst

@@ -1,7 +1,7 @@
 Installation
 ============
 
-Vikunja builds and installs itself using `CMake <https://cmake.org/>`_. Before you can install and use vikunja, you have to install the only dependency `alpaka <https://github.com/alpaka-group/alpaka>`_. Vikunja supports alpaka from version 0.6 until 0.8. It is recommend to use the latest alpaka version. Alpaka itself has also a single dependency, boost. Read the `alpaka documentation <https://github.com/alpaka-group/alpaka#dependencies>`_ to determine the supported boost version.
+Vikunja builds and installs itself using `CMake <https://cmake.org/>`_. Before you can install and use vikunja, you have to install `alpaka <https://github.com/alpaka-group/alpaka>`_ and its dependencies. Vikunja supports alpaka from version 0.6 to 0.8. It is recommended to use the latest alpaka version. Alpaka itself has also a single non-optional dependency, Boost, as well as optional dependencies for the various back-ends. Read the `alpaka documentation <https://github.com/alpaka-group/alpaka#dependencies>`_ to determine the dependencies for your platform.
 
 **Install alpaka:**
 
@@ -52,7 +52,7 @@ Enable and run an example:
 Use vikunja in a CMake project via ``find_package``
 ---------------------------------------------------
 
-Once vikunja and alpaka are successfully installed, you can use them in your project via the cmake function ``find_packge``.
+Once vikunja and alpaka are successfully installed, you can use them in your project via the CMake function ``find_package``.
 
 .. code-block:: cmake
 
@@ -64,7 +64,7 @@ Once vikunja and alpaka are successfully installed, you can use them in your pro
    alpaka_add_executable(${CMAKE_PROJECT_NAME} main.cpp)
    target_link_libraries(${CMAKE_PROJECT_NAME} PRIVATE vikunja::vikunja)
 
-At the cmake configuration time of your project, you need to enable at least on alpaka accelerator to execute a vikunja function on a processor. The accelerators are enabled via the cmake argument ``-DALPAKA_ACC_<...>_ENABLE=ON``. All existing accelerators can be found `here <https://alpaka.readthedocs.io/en/latest/advanced/cmake.html>`_.
+During configuration you need to enable at least one alpaka accelerator to execute a vikunja function on a processor. The accelerators are enabled by the CMake argument ``-DALPAKA_ACC_<...>_ENABLE=ON``. All existing accelerators can be found `here <https://alpaka.readthedocs.io/en/latest/advanced/cmake.html>`_.
 
 .. code-block:: bash
 
@@ -74,12 +74,12 @@ At the cmake configuration time of your project, you need to enable at least on
    cmake .. -DALPAKA_ACC_CPU_B_SEQ_T_SEQ_ENABLE=ON -DALPAKA_ACC_GPU_CUDA_ENABLE=ON
    cmake --build .
 
-By default ``find_package(vikunja)`` runs ``find_package(alpaka)``, if the ``alpaka::alpaka`` target is not already defined.
+By default ``find_package(vikunja)`` runs ``find_package(alpaka)`` if the ``alpaka::alpaka`` target is not already defined.
 
 Use vikunja in a CMake project via ``add_subdirectory``
 -------------------------------------------------------
 
-Vikunja also provides cmake integration via ``add_subdirectory``. The `add_subdirectory <https://cmake.org/cmake/help/latest/command/add_subdirectory.html>`_ approach does not require vikunja or alpaka to be installed and allows for easy deployment of a custom vikunja version together with your project.
+Vikunja also provides CMake integration via ``add_subdirectory``. The `add_subdirectory <https://cmake.org/cmake/help/latest/command/add_subdirectory.html>`_ approach does not require vikunja or alpaka to be installed and allows for easy deployment of a custom vikunja version together with your project.
 
 .. code-block:: cmake
 

docs/source/basic/operators.rst

@@ -93,13 +93,13 @@ The functor object must fullfil the requirements of ``std::is_trivially_copyable
     }
 
 .. warning:: 
-    Global functions are not allowed as functor objects for the vikunja ``algorithm`` due to a limitation of the Nvidia CUDA accelerator.
+    Global functions are not allowed as functor objects for the vikunja ``algorithm`` due to a limitation of the CUDA accelerator.
 
 
 Operator Types
 ++++++++++++++
 
-Depending on the ``algorithm``, the ``operator`` requires a different number of input arguments. Currently, the vikunja ``algorithm`` requires a unary (one data input) or binary (two data inputs) ``operator``. A vikunja-specific property of the ``operator`` is that they can have an additional ``acc`` argument, which is required for some alpaka-specific functions.
+Depending on the ``algorithm``, the ``operator`` requires a different number of input arguments. Currently, the vikunja ``algorithm`` requires a unary (one data input) or binary (two data inputs) ``operator``. A vikunja-specific property of the ``operator`` is that they can have an additional ``acc`` argument, which is required for any device-specific functions (such as math functions).
 
 .. code-block:: c++
 

docs/source/conf.py

@@ -63,12 +63,12 @@
 else:
     rel_sphinx_build_folder_path = '../build'
 
-# path where doxygen generate html files
+# path where doxygen places the generated html files
 doxygen_build_dir = '../build/doxygen/html'
-# build folder of sphinx -> conntet is online available
+# build folder of sphinx -> content is online available
 doxygen_dst = os.path.join(rel_sphinx_build_folder_path, 'html/doxygen')
 
-# create build folder, if not already exists
+# create build folder if it does not exist
 if not os.path.exists(doxygen_build_dir):
     os.makedirs(doxygen_build_dir)
 
@@ -78,4 +78,4 @@
 
 if os.path.exists(doxygen_dst):
     shutil.rmtree(doxygen_dst)
-shutil.copytree(src=doxygen_build_dir, dst=doxygen_dst)
+shutil.copytree(src=doxygen_build_dir, dst=doxygen_dst)

docs/source/development/ci.rst

@@ -8,4 +8,4 @@ For automatic testing we use ``GitLab CI``. ``GitLab CI`` allows us to run runti
 
    Relationship between GitHub.com, GitLab.com and HZDR gitlab-ci runners
 
-To change how the tests are built and executed, modify the code in the `vikunja repository <https://github.com/alpaka-group/vikunja>`_. If the container environment with the dependencies needs to be changed, please open an issue or contribute to `alpaka-group-container repository <https://gitlab.com/hzdr/crp/alpaka-group-container/container_registry>`_.
+To change how the tests are built and executed modify the code in the `vikunja repository <https://github.com/alpaka-group/vikunja>`_. If the container environment with the dependencies needs to be changed please open an issue or contribute to `alpaka-group-container repository <https://gitlab.com/hzdr/crp/alpaka-group-container/container_registry>`_.

docs/source/development/docs.rst

@@ -1,7 +1,7 @@
 Documentation
 =============
 
-Vikunja uses two tools to create documentation: `Sphinx Doc <https://www.sphinx-doc.org/en/master/>`_ and `Doxygen <https://www.doxygen.nl/index.html>`_. Sphinx is used to write this general documentation and Doxygen enables the documentation of the API.
+Vikunja uses two tools to create documentation: `Sphinx Doc <https://www.sphinx-doc.org/en/master/>`_ and `Doxygen <https://www.doxygen.nl/index.html>`_. Sphinx is used to write this general documentation and Doxygen generates the API documentation.
 
 Building
 ++++++++

docs/source/index.rst

@@ -12,15 +12,15 @@
      :alt: vikunja logo
 
 
-Vikunja is a performance portable algorithms 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 is a performance portable algorithms 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``.
 
 
 vikunja - How to Read This Document
 ===================================
 
-Generally, **follow the manual pages in-order** to get started. Individual chapters are based on the information of the chapters before. The documentation is separated in three sections. The ``basic`` section explains all concepts of vikunja. In the ``advanced`` you will get more details of certain functionalities. If you want to provide to the project, you should have a look in the ``development`` section.
+Generally, **follow the manual pages in-order** to get started. Individual chapters are based on the information of the chapters before. The documentation is separated in three sections. The ``basic`` section explains all concepts of vikunja. In the ``advanced`` you will get more details of certain functionalities. If you want to contribute to the project, you should have a look in the ``development`` section.
 
 .. toctree::
    :maxdepth: 1

docs/source/logo/README.md

@@ -1 +1 @@
-The Logo was created with Inkscape. The text uses the font `UnDinaru` and the colors `005aa0ff` (blue - RGBA) and `f0781eff` (orange).
+The logo was created with Inkscape. The text uses the font `UnDinaru` and the colors `005aa0ff` (blue - RGBA) and `f0781eff` (orange).

example/reduce/src/reduce-main.cpp

@@ -17,8 +17,8 @@
 int main()
 {
     // Define the accelerator.
-    // The accelerates decides on which processor type the vikunja algorithm will be executed.
-    // The accelerators must be enabled in the CMake build to be available.
+    // 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
@@ -34,35 +34,36 @@ int main()
 
     // 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));
+    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 queued so that they are executed in the correct order.
+    // 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.
+    // 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 = uint64_t;
+    using Data = std::uint64_t;
 
-    // The extends stores the problem size.
+    // The extent stores the problem size.
     using Vec = alpaka::Vec<Dim, Idx>;
     Vec extent(Vec::all(static_cast<Idx>(1)));
     extent[0] = static_cast<Idx>(6400);
 
 
-    // Allocates memory for the device.
+    // 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);
-    // Allocates memory for the host.
+    // Allocate memory for the host.
     auto hostMem(alpaka::allocBuf<Data, Idx>(devHost, extent));
     Data* hostNativePtr = alpaka::getPtrNative(hostMem);
 
@@ -81,7 +82,7 @@ int main()
     Idx reduceResult = vikunja::reduce::deviceReduce<Acc>(
         devAcc, // The device that executes the algorithm.
         devHost, // The host is necessary to allocate memory for the result.
-        queueAcc, // Queue in which the algorithm enqueues.
+        queueAcc, // Queue in which the algorithm is enqueued.
         extent.prod(), // Problem size
         deviceNativePtr, // Input memory
         sum // Operator
@@ -95,7 +96,7 @@ int main()
     Idx transformReduceResult = vikunja::reduce::deviceTransformReduce<Acc>(
         devAcc, // The device that executes the algorithm.
         devHost, // The host is necessary to allocate memory for the result.
-        queueAcc, // Queue in which the algorithm enqueues.
+        queueAcc, // Queue in which the algorithm is enqueued.
         extent.prod(), // Problem size
         deviceNativePtr, // Input memory
         doubleNum, // transformation operator
@@ -114,7 +115,7 @@ int main()
     {
         std::cout << "Reduce was not successful!\n"
                   << "expected result: " << expectedReduceResult << "\n"
-                  << "real result: " << reduceResult << std::endl;
+                  << "actual result: " << reduceResult << std::endl;
     }
 
     // Verify the transform-reduction result.
@@ -128,7 +129,7 @@ int main()
     {
         std::cout << "TransformReduce was not successful!\n"
                   << "expected result: " << expectedTransformReduceResult << "\n"
-                  << "real result: " << transformReduceResult << std::endl;
+                  << "actual result: " << transformReduceResult << std::endl;
     }
 
     return 0;

example/transform/src/transform-main.cpp

@@ -16,7 +16,7 @@
 int main()
 {
     // Define the accelerator.
-    // The accelerates decides on which processor type the vikunja algorithm will be executed.
+    // The accelerator decides on which processor type the vikunja algorithm will be executed.
     // The accelerators must be enabled in the CMake build to be available.
     //
     // It is possible to choose from a set of accelerators:
@@ -38,7 +38,7 @@ int main()
     // 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 queued so that they are executed in the correct order.
+    // All algorithms must be enqueued so that they are executed in the correct order.
     using QueueAcc = alpaka::Queue<Acc, alpaka::Blocking>;
     QueueAcc queueAcc(devAcc);
 
@@ -51,17 +51,17 @@ int main()
     // Type of the user data.
     using Data = uint64_t;
 
-    // The extends stores the problem size.
+    // The extent stores the problem size.
     using Vec = alpaka::Vec<Dim, Idx>;
     Vec extent(Vec::all(static_cast<Idx>(1)));
     extent[0] = static_cast<Idx>(6400);
 
 
-    // Allocates memory for the device.
+    // 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);
-    // Allocates memory for the host.
+    // Allocate memory for the host.
     auto hostMem(alpaka::allocBuf<Data, Idx>(devHost, extent));
     Data* hostNativePtr = alpaka::getPtrNative(hostMem);
 
@@ -80,7 +80,7 @@ int main()
 
     vikunja::transform::deviceTransform<Acc>(
         devAcc, // The device that executes the algorithm.
-        queueAcc, // Queue in which the algorithm enqueues.
+        queueAcc, // Queue in which the algorithm is enqueued.
         extent[Dim::value - 1u], // Problem size
         deviceNativePtr, // Input memory
         deviceNativePtr, // Output memory
@@ -101,7 +101,9 @@ int main()
     }
     else
     {
-        std::cout << "Transform was not successful!\n";
+        std::cout << "Transform was not successful!\n"
+                  << "expected result: " << expectedResult << "\n"
+                  << "actual result: " << resultSum << std::endl;
     }
 
     return 0;