fix typos in benchmark related documentation

- improve CMake for benchmarks
- Thanks to Hannes

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

CMakeLists.txt

@@ -24,7 +24,7 @@ option(BUILD_TESTING "Build the testing tree." 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)
 cmake_dependent_option(VIKUNJA_ENABLE_BENCHMARKS "Enable benchmarks" OFF BUILD_TESTING OFF)
-cmake_dependent_option(VIKUNJA_ENABLE_CUDA_THRUST_BENCHMARKS "Enable benchmarks" OFF VIKUNJA_ENABLE_BENCHMARKS OFF)
+cmake_dependent_option(VIKUNJA_ENABLE_CUDA_THRUST_BENCHMARKS "Enable benchmarks using CUDA Thrust" OFF "VIKUNJA_ENABLE_BENCHMARKS;ALPAKA_ACC_GPU_CUDA_ENABLE" OFF)
 
 # activate support for host/device lambdas in cuda
 # needs to be set before alpaka is included

docs/source/advanced/cmake.rst

@@ -30,29 +30,29 @@ Testing
 **VIKUNJA_SYSTEM_CATCH2** (OFF)
     .. code-block::
 
-        Only works if BUILD_TESTING is ON.
+        Requires BUILD_TESTING to be ON.
         Use your local installation of Catch2.
         Otherwise, it will be automatically downloaded and installed in the local build folder.
 
 **VIKUNJA_ENABLE_CXX_TEST** (OFF)
     .. code-block::
 
-        Only works if BUILD_TESTING is ON.
+        Requires BUILD_TESTING to be 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.
+        supported by your C++ compiler.
 
 **VIKUNJA_ENABLE_BENCHMARKS** (OFF)
     .. code-block::
 
-        Only works if BUILD_TESTING is ON.
-        Enable the benchmarks. The benchmarks are built automatically and can be executed via ctest.
+        Requires BUILD_TESTING to be ON.
+        Enables the benchmarks. The benchmarks are built automatically and can be executed via CTest.
 
 **VIKUNJA_ENABLE_CUDA_THRUST_BENCHMARKS** (OFF)
     .. code-block::
 
-        Only works if VIKUNJA_ENABLE_BENCHMARKS and ALPAKA_ACC_GPU_CUDA_ENABLE are ON.
-        Enable thrust benchmarks for comparison.
+        Requires VIKUNJA_ENABLE_BENCHMARKS and ALPAKA_ACC_GPU_CUDA_ENABLE to be ON.
+        Enables Thrust benchmarks for comparison.
 
 alpaka
 ++++++

docs/source/development/test.rst

@@ -1,12 +1,12 @@
 Testing and Benchmarking
 ========================
 
-Vikunja offers different types of tests. The source code is tested via unit and integration tests with `Cacht2 <https://github.com/catchorg/Catch2/tree/v2.x>`_. The CMake code is tested with integration tests and custom scripts.
+Vikunja offers different types of tests. The source code is tested via unit and integration tests with `Catch2 <https://github.com/catchorg/Catch2/tree/v2.x>`_. The CMake code is tested with integration tests and custom scripts.
 
 Source Code Tests
 -----------------
 
-Before you start writing source code tests, you should read the `Catch2 documentation <https://github.com/catchorg/Catch2/blob/v2.x/docs/tutorial.md#top>`_. Tests written with Catch2 are standalone application. Therefore, they have their own source code files and ``CMakeLists.txt`` files located in the ``test/unit`` and ``test/integ`` folders. If you set the CMake argument ``-DBUILD_TESTING=ON``, the executable files of the tests will be built automatically. All test cases are registered via the CMake function ``add_test``. Therefore, you can automatically run all tests in the build folder with the ``ctest`` command:
+Before you start writing source code tests, you should read the `Catch2 documentation <https://github.com/catchorg/Catch2/blob/v2.x/docs/tutorial.md#top>`_. Tests written with Catch2 are standalone executables. They have their own source code files and ``CMakeLists.txt`` files located in the ``test/unit`` and ``test/integ`` folders. If you set the CMake argument ``-DBUILD_TESTING=ON``, the tests will be built automatically. All test executables are registered via the CMake function ``add_test``. Therefore, you can automatically run all tests from the build folder with the ``ctest`` command:
 
 .. code-block:: bash
 
@@ -17,7 +17,7 @@ Before you start writing source code tests, you should read the `Catch2 document
 
 For more CMake arguments for the tests, see the :ref:`CMake section <cmake-test>`.
 
-If you only want to run a single test, you can run the test executable directly. All test executables are located in the ``<build_folder>/tests``. It is also possible to run the executable with the ``--help`` flag to show additional options. For example, the ``-s`` flag displays additional information created with the Catch2 function ``INFO()``.
+If you only want to run a single test, you can run the test executable directly. All test executables are located in ``<build_folder>/tests``. It is also possible to run the executable with the ``--help`` flag to show additional options. For example, the ``-s`` flag displays additional information created with the Catch2 function ``INFO()``.
 
 .. code-block:: bash
 
@@ -29,27 +29,31 @@ If you only want to run a single test, you can run the test executable directly.
     # run test with extra output
     test/integ/reduce/test_reduce -s
 
+.. tip::
+
+    Each test is a CMake target that you can build separately. A test target always starts with ``test_``. To get all available test CMake targets, run ``cmake --build . -t help | grep 'test_'`` in the build folder. You can build a specific test with ``cmake --build . -t test_IndividualTestCase``.
+
 CMake Tests
 -----------
 
-The CMake integration tests check whether vikunja can be used correctly in another project via the CMake functions ``find_package()``) or ``add_subdirectory``. The CI contains test jobs for creating projects that use the vikunja library. The job names start with ``integration``. All associated files for the tests are in ``script/integration_test``.
+The CMake integration tests check whether vikunja can be used correctly in another project via the CMake functions ``find_package()`` or ``add_subdirectory``. The CI contains test jobs which create dummy projects that use the vikunja library. The job names start with ``integration``. All associated files for the tests are in ``script/integration_test``.
 
 CXX Test
 ++++++++
 
-There is a special Catch2 test that tests the vikunja CMake to see if the C++ standard is set correctly. The name of the test is ``test_cxx``. The test compares the C++ standard set by the compiler with an expected standard passed as an argument. By default, ``ctest`` automatically passes the expected C++ standard depending on the CMake variable ``ALPAKA_CXX_STANDARD``. If you run the test manually, you must pass it yourself:
+There is a special Catch2 test that tests vikunja's build system to see if the C++ standard is set correctly. The name of the test is ``test_cxx``. It compares the C++ standard set by the compiler with an expected standard passed as an argument. By default, ``ctest`` automatically passes the expected C++ standard depending on the CMake variable ``ALPAKA_CXX_STANDARD``. If you run the test manually, you must pass it yourself:
 
 .. code-block:: bash
 
-    # expected, that the code was compiled with C++ 17
+    # expects, that the code was compiled with C++ 17
     test/unit/cxx/test_cxx --cxx 17
 
 
 Benchmarks
 ----------
 
-Vikunja uses `Catch2 benchmark <https://github.com/catchorg/Catch2/blob/v2.x/docs/benchmarks.md#top>`_ to automatically run benchmarks. By default, the benchmarks are not enabled. To enable the benchmarks, the CMake arguments ``-DBUILD_TESTING=ON -DVIKUNJA_ENABLE_BENCHMARKS=ON`` must be set. The benchmarks are created automatically and can be run with ``ctest``. As with the tests, you can run a particular benchmark directly from the executable file, e.g. ``test/benchmarks/transform/bench_vikunja_transform``. All benchmark executables are located in ``<build_folder>/test/benchmarks``.
+Vikunja uses `Catch2 benchmark <https://github.com/catchorg/Catch2/blob/v2.x/docs/benchmarks.md#top>`_ to automatically run benchmarks. By default, benchmarks are not enabled. To enable them, the CMake arguments ``-DBUILD_TESTING=ON -DVIKUNJA_ENABLE_BENCHMARKS=ON`` must be set. The benchmarks are created automatically and can be run with ``ctest``. As with the tests, you can run a particular benchmark directly from the executable file, e.g. ``test/benchmarks/transform/bench_vikunja_transform``. All benchmark executables are located in ``<build_folder>/test/benchmarks``.
 
 .. tip::
 
-    If you run ``bechmark_exe --help``, you get benchmark specific options.
+    If you run ``<benchmark_exe> --help``, you get benchmark specific options.

test/CMakeLists.txt

@@ -33,6 +33,9 @@ target_link_libraries(vikunjaTestSetup
   PUBLIC
   Catch2::Catch2
   )
+if(VIKUNJA_ENABLE_BENCHMARKS)
+  target_compile_definitions(vikunjaTestSetup PRIVATE CATCH_CONFIG_ENABLE_BENCHMARKING)
+endif()
 add_library(vikunja::testSetup ALIAS vikunjaTestSetup)
 
 list(APPEND _VIKUNJA_TEST_OPTIONS "--use-colour yes")

test/benchmarks/CMakeLists.txt

@@ -13,14 +13,6 @@ target_compile_definitions(vikunjaBenchSetup INTERFACE CATCH_CONFIG_ENABLE_BENCH
 target_include_directories(vikunjaBenchSetup INTERFACE include)
 add_library(vikunja::benchSetup ALIAS vikunjaBenchSetup)
 
-target_compile_definitions(vikunjaTestSetup PRIVATE CATCH_CONFIG_ENABLE_BENCHMARKING)
-
-if(VIKUNJA_ENABLE_CUDA_THRUST_BENCHMARKS)
-    if(NOT ALPAKA_ACC_GPU_CUDA_ENABLE)
-        message(FATAL_ERROR "VIKUNJA_ENABLE_CUDA_THRUST_BENCHMARKS requires the ALPAKA_ACC_GPU_CUDA_ENABLE backend to be enabled.")
-    endif()
-endif()
-
 add_subdirectory("helper/")
 add_subdirectory("transform/")
 add_subdirectory("reduce/")

test/benchmarks/include/vikunja/bench/memory.hpp

@@ -22,16 +22,16 @@ namespace vikunja::bench
         TData const m_increment;
 
     public:
-        //! Functor for iota implementation with generic data type.
+        //! Iota functor for generic data types.
         //!
         //! \tparam TData Type of each element
-        //! \param begin Value of the first element.
+        //! \param init Value of the first element.
         //! \param increment Distance between two elements.
-        IotaFunctor(TData const begin, TData const increment) : m_begin(begin), m_increment(increment)
+        IotaFunctor(TData const init, TData const increment) : m_begin(init), m_increment(increment)
         {
         }
 
-        //! Writes the result of `begin + index * increment` to each element of the output vector.
+        //! Writes the result of `init + index * increment` to each element of the output vector.
         //!
         //! \tparam TAcc The accelerator environment to be executed on.
         //! \tparam TElem The element type.
@@ -64,17 +64,17 @@ namespace vikunja::bench
     };
 
 
-    //! Allocates memory and initialises each value with `begin + index * increment`,
+    //! Allocates memory and initializes each value with `init + index * increment`,
     //! where index is the position in the output vector. The allocation is done with `setup.devAcc`.
     //!
     //! \tparam TData Data type of the memory buffer.
     //! \tparam TSetup Fully specialized type of `vikunja::test::TestAlpakaSetup`.
     //! \tparam Type of the extent.
     //! \tparam TBuf Type of the alpaka memory buffer.
-    //! \param setup Instance of `vikunja::test::TestAlpakaSetup`. The `setup.devAcc` and `setup.queueDev` is used
+    //! \param setup Instance of `vikunja::test::TestAlpakaSetup`. `setup.devAcc` and `setup.queueDev` are used
     //! for allocation and initialization of the the memory.
     //! \param extent Size of the memory buffer. Needs to be 1 dimensional.
-    //! \param begin Value of the first element. Depending of TData, it can be negative.
+    //! \param init Value of the first element. Depending on TData, it can be negative.
     //! \param increment Distance between two elements of the vector. If the value is negative, the value of an
     //! element is greater than its previous element.
     template<
@@ -85,7 +85,7 @@ namespace vikunja::bench
     TBuf allocate_mem_iota(
         TSetup& setup,
         TExtent const& extent,
-        TData const begin = TData{0},
+        TData const init = TData{0},
         TData const increment = TData{1})
     {
         // TODO: test also 2 and 3 dimensional memory
@@ -105,7 +105,7 @@ namespace vikunja::bench
                 false,
                 alpaka::GridBlockExtentSubDivRestrictions::Unrestricted));
 
-        IotaFunctor iotaFunctor(begin, increment);
+        IotaFunctor iotaFunctor(init, increment);
 
         alpaka::exec<typename TSetup::Acc>(
             setup.queueAcc,
@@ -124,10 +124,10 @@ namespace vikunja::bench
         TData const m_constant;
 
     public:
-        //! Functor to write constant value in each element of a vector.
+        //! Functor to write a constant value into each element of a vector.
         //!
         //! \tparam TData Type of each element
-        //! \param begin Value of all elements.
+        //! \param constant Value to which all elements are set.
         ConstantInitFunctor(TData const constant) : m_constant(constant)
         {
         }
@@ -164,17 +164,17 @@ namespace vikunja::bench
         }
     };
 
-    //! Allocates memory and initialises each value with a constant value.
+    //! Allocates memory and initializes each value with a constant value.
     //! The allocation is done with `setup.devAcc`.
     //!
     //! \tparam TData Data type of the memory buffer.
     //! \tparam TSetup Fully specialized type of `vikunja::test::TestAlpakaSetup`.
     //! \tparam Type of the extent.
     //! \tparam TBuf Type of the alpaka memory buffer.
-    //! \param setup Instance of `vikunja::test::TestAlpakaSetup`. The `setup.devAcc` and `setup.queueDev` is used
+    //! \param setup Instance of `vikunja::test::TestAlpakaSetup`. `setup.devAcc` and `setup.queueDev` are used
     //! for allocation and initialization of the the memory.
     //! \param extent Size of the memory buffer. Needs to be 1 dimensional.
-    //! \param begin Value of the constant.
+    //! \param constant Value of the constant.
     template<
         typename TData,
         typename TSetup,

test/benchmarks/reduce/bench_vikunja_reduce.cpp

@@ -91,7 +91,7 @@ TEMPLATE_TEST_CASE("bechmark reduce", "[benchmark][reduce][vikunja]", int, float
     }
     else if constexpr(std::is_same_v<Data, float>)
     {
-        // removed 1'270'000 because of rounding errors.
+        // removed 1'270'000 because of precision errors.
         reduce_benchmark<Data, Idx>(GENERATE(100, 100'000, 2'000'000));
     }
     else if constexpr(std::is_same_v<Data, double>)