From 742e578577c3a04f178a16ba64b42260b49690d1 Mon Sep 17 00:00:00 2001 From: Simeon Ehrig Date: Wed, 12 Jan 2022 13:37:18 +0100 Subject: [PATCH] Apply suggestions from code review Co-authored-by: Jan Stephan --- README.md | 8 +++---- docs/source/advanced/cmake.rst | 4 ++-- docs/source/basic/algorithm.rst | 2 +- docs/source/basic/installation.rst | 10 ++++----- docs/source/basic/operators.rst | 4 ++-- docs/source/conf.py | 8 +++---- docs/source/development/ci.rst | 2 +- docs/source/development/docs.rst | 2 +- docs/source/index.rst | 4 ++-- docs/source/logo/README.md | 2 +- example/reduce/src/reduce-main.cpp | 27 ++++++++++++------------ example/transform/src/transform-main.cpp | 12 +++++------ 12 files changed, 43 insertions(+), 42 deletions(-) diff --git a/README.md b/README.md index 694b96b..1db1a8e 100644 --- a/README.md +++ b/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 diff --git a/docs/source/advanced/cmake.rst b/docs/source/advanced/cmake.rst index 02451e0..5b620ba 100644 --- a/docs/source/advanced/cmake.rst +++ b/docs/source/advanced/cmake.rst @@ -38,10 +38,10 @@ VIKUNJA_ENABLE_CXX_TEST 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 `_. +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 `_. ALPAKA_CXX_STANDARD .. code-block:: diff --git a/docs/source/basic/algorithm.rst b/docs/source/basic/algorithm.rst index fcf46af..2054657 100644 --- a/docs/source/basic/algorithm.rst +++ b/docs/source/basic/algorithm.rst @@ -1,4 +1,4 @@ -Algorithm +Algorithms ========= This page provides an overview of all algorithms implemented in vikunja. diff --git a/docs/source/basic/installation.rst b/docs/source/basic/installation.rst index d0f9a02..4defddf 100644 --- a/docs/source/basic/installation.rst +++ b/docs/source/basic/installation.rst @@ -1,7 +1,7 @@ Installation ============ -Vikunja builds and installs itself using `CMake `_. Before you can install and use vikunja, you have to install the only dependency `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 `_ to determine the supported boost version. +Vikunja builds and installs itself using `CMake `_. Before you can install and use vikunja, you have to install `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 `_ 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 `_. +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 `_. .. 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 `_ 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 `_ 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 diff --git a/docs/source/basic/operators.rst b/docs/source/basic/operators.rst index 9079437..ec996cb 100644 --- a/docs/source/basic/operators.rst +++ b/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++ diff --git a/docs/source/conf.py b/docs/source/conf.py index 73c8415..bb03fff 100644 --- a/docs/source/conf.py +++ b/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) \ No newline at end of file +shutil.copytree(src=doxygen_build_dir, dst=doxygen_dst) diff --git a/docs/source/development/ci.rst b/docs/source/development/ci.rst index 763762d..7e44ea4 100644 --- a/docs/source/development/ci.rst +++ b/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 `_. If the container environment with the dependencies needs to be changed, please open an issue or contribute to `alpaka-group-container repository `_. +To change how the tests are built and executed modify the code in the `vikunja repository `_. If the container environment with the dependencies needs to be changed please open an issue or contribute to `alpaka-group-container repository `_. diff --git a/docs/source/development/docs.rst b/docs/source/development/docs.rst index 6ab165d..ee74af9 100644 --- a/docs/source/development/docs.rst +++ b/docs/source/development/docs.rst @@ -1,7 +1,7 @@ Documentation ============= -Vikunja uses two tools to create documentation: `Sphinx Doc `_ and `Doxygen `_. 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 `_ and `Doxygen `_. Sphinx is used to write this general documentation and Doxygen generates the API documentation. Building ++++++++ diff --git a/docs/source/index.rst b/docs/source/index.rst index 62954ee..f684598 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -12,7 +12,7 @@ :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 `_ to implement platform independent primitives such as ``reduce`` or ``transform``. @@ -20,7 +20,7 @@ Vikunja uses `alpaka `_ to implement pla 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 diff --git a/docs/source/logo/README.md b/docs/source/logo/README.md index 4504a63..6cd14a1 100644 --- a/docs/source/logo/README.md +++ b/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). diff --git a/example/reduce/src/reduce-main.cpp b/example/reduce/src/reduce-main.cpp index 581bc91..fe43cb7 100644 --- a/example/reduce/src/reduce-main.cpp +++ b/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(0u)); + auto const devAcc = alpaka::getDevByIdx(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(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; QueueAcc queueAcc(devAcc); - // Dimension of the problem. + // Dimension of the problem. 1D in this case (inherited from the Accelerator). using Dim = alpaka::Dim; // 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; // 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; Vec extent(Vec::all(static_cast(1))); extent[0] = static_cast(6400); - // Allocates memory for the device. + // Allocate memory for the device. auto deviceMem(alpaka::allocBuf(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(devHost, extent)); Data* hostNativePtr = alpaka::getPtrNative(hostMem); @@ -81,7 +82,7 @@ int main() Idx reduceResult = vikunja::reduce::deviceReduce( 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( 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; diff --git a/example/transform/src/transform-main.cpp b/example/transform/src/transform-main.cpp index a453a43..c77d4f0 100644 --- a/example/transform/src/transform-main.cpp +++ b/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(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; 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; Vec extent(Vec::all(static_cast(1))); extent[0] = static_cast(6400); - // Allocates memory for the device. + // Allocate memory for the device. auto deviceMem(alpaka::allocBuf(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(devHost, extent)); Data* hostNativePtr = alpaka::getPtrNative(hostMem); @@ -80,7 +80,7 @@ int main() vikunja::transform::deviceTransform( 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