diff --git a/README.rst b/README.rst index 2dfbb8b1d2..018656ed2d 100644 --- a/README.rst +++ b/README.rst @@ -6,8 +6,8 @@ Distributed Ranges =================== -.. image:: https://github.com/intel-sandbox/libraries.runtimes.hpc.dds.distributed-ranges/actions/workflows/pr.yml/badge.svg - :target: https://github.com/intel-sandbox/libraries.runtimes.hpc.dds.distributed-ranges/actions/workflows/pr.yml +.. image:: https://github.com/oneapi-src/distributed-ranges/actions/workflows/pr.yml/badge.svg + :target: https://github.com/oneapi-src/distributed-ranges/actions/workflows/pr.yml .. image:: https://www.bestpractices.dev/projects/8975/badge :target: https://www.bestpractices.dev/projects/8975 @@ -17,60 +17,124 @@ C++ Ranges. About ----- -Distributed Ranges is a productivity library for distributed and partitioned memory based on C++ ranges. +Distributed Ranges is a C++ productivity library for distributed and partitioned memory based on C++ ranges. It offers a collection of data structures, views, and algorithms for building generic abstractions and provides interoperability with MPI, SHMEM, SYCL and OpenMP and portability on CPUs and GPUs. NUMA-aware allocators and distributed data structures facilitate development of C++ applications on heterogeneous nodes with multiple devices and achieve excellent performance and parallel scalability by exploiting local compute and data access. +Main strength of the library +============================ + +In this model one can: + +* create a `distributed data structure` that work with all our algorithms out of the box +* create an `algorithm` that works with all our distributed data structures out of the box + +Distributed Ranges is a `glue` that makes this possible. + + Documentation ------------- -- Usage: - - Introductory presentation: `Distributed Ranges, why you need it`_, 2024 - - Article: `Get Started with Distributed Ranges`_, 2023 - - Tutorial: `Sample repository showing Distributed Ranges usage`_ -- Design / Implementation: - - Conference paper: `Distributed Ranges, A Model for Distributed Data Structures, Algorithms, and Views`_, 2024 - - Talk: `CppCon 2023; Benjamin Brock; Distributed Ranges`_, 2023 - - Technical presentation: `Intel Innovation'23`_, 2023 - - `API specification`_ - - `Doxygen`_ +* Usage: -Contact us ----------- + * Introductory presentation: `Distributed Ranges, why you need it`_, 2024 + * Article: `Get Started with Distributed Ranges`_, 2023 + * Tutorial: `Distributed Ranges Tutorial`_ -We seek collaboration opportunities and welcome feedback on ways to extend the library, -according to developer needs. Contact us by writing a `new issue`_. +* Design / Implementation: + * Conference paper: `Distributed Ranges, A Model for Distributed Data Structures, Algorithms, and Views`_, 2024 + * Talk: `CppCon 2023; Benjamin Brock; Distributed Ranges`_, 2023 + * Technical presentation: `Intel Innovation'23`_, 2023 + * `API specification`_ -Examples --------- -See `Sample repository showing Distributed Ranges usage`_ for a few well explained examples. -Additionally you may build all tests of this repository to see and run much more examples. +Requirements +------------ + +* Linux +* cmake >=3.20 +* `OneAPI HPC Toolkit`_ installed + +Enable `OneAPI` by:: + + source ~/intel/oneapi/setvars.sh + +... or by:: + + source /opt/intel/oneapi/setvars.sh + +... or wherever you have ``oneapi/setvars.sh`` script installed in your system. + +Additional requirements for NVIDIA GPUs +======================================= + +* `CUDA`_ +* `OneAPI for NVIDIA GPUs`_ plugin + +When enabling OneAPI use ``--include-intel-llvm`` option, e.g. call:: + + source ~/intel/oneapi/setvars.sh --include-intel-llvm + +... instead of ``source ~/intel/oneapi/setvars.sh``. + + +Build and run +------------- + +Build for Intel GPU/CPU +======================= + +All tests and examples can be build by:: + + CXX=icpx cmake -B build + cmake --build build -- -j -Build and test with gcc for CPU:: - CXX=g++-12 cmake -B build - make -C build -j all test +Build for NVidia GPU +==================== -Build and test with ipcx for SYCL && CPU/GPU:: +.. note:: - CXX=icpx cmake -B build -DENABLE_SYCL=ON + Distributed Ranges library works in two models: + - Multi Process (based on SYCL and MPI) + - Single Process (based on pure SYCL) -See how example is run and the output:: + On NVIDIA GPU only `Multi Process` model is currently supported. - cd build - ctest -VV +To build multi-process tests call:: + + CXX=icpx cmake -B build -DENABLE_CUDA:BOOL=ON + cmake --build build --target mp-all-tests -- -j + + +Run tests +========= + +Run multi process tests:: + + ctest --test-dir build --output-on-failure -L MP -j 4 + +Run single process tests:: + + ctest --test-dir build --output-on-failure -L SP -j 4 + +Run all tests:: + + ctest --test-dir build --output-on-failure -L TESTLABEL -j 4 + + +Examples +-------- + +See `Distributed Ranges Tutorial`_ for a few well explained examples. Adding Distributed Ranges to your project ----------------------------------------- -See `Sample repository showing Distributed Ranges usage`_ -for a live example how to write CMakeLists.txt. Alternatively you may read details below. - If your project uses CMAKE, add the following to your ``CMakeLists.txt`` to download the library:: @@ -87,52 +151,49 @@ The above will define targets that can be included in your project:: target_link_libraries( MPI::MPI_CXX DR::mpi) -If your project does not use CMAKE, then you need to download the -library, and install it into a prefix:: - - git clone https://github.com/oneapi-src/distributed-ranges.git dr - cd dr - cmake -B build -DCMAKE_INSTALL_PREFIX= - make -C build install - cmake -B build-fmt -DCMAKE_INSTALL_PREFIX= build/_deps/cpp-format-src - make -C build-fmt install - -Use ``-I`` and ``-L`` to find headers and libs during compilation:: - - g++ -std=c=++20 -I /include -L /lib -L /opt/intel/oneapi/mpi/latest/lib/release -lfmt -lmpicxx -lmpi +See `Distributed Ranges Tutorial`_ +for a live example of a cmake project that imports and uses Distributed Ranges. Logging ------- -Add this to your main to enable logging:: +Add below code to your ``main`` function to enable logging. - std::ofstream logfile(fmt::format("dr.{}.log", comm_rank)); +If using `Single-Process` model:: + + std::ofstream logfile("dr.log"); dr::drlog.set_file(logfile); +If using `Multi-Process` model:: -Contributing ------------- + int my_mpi_rank; + MPI_Comm_rank(MPI_COMM_WORLD, &my_mpi_rank); + std::ofstream logfile(fmt::format("dr.{}.log", my_mpi_rank)); -See `CONTRIBUTING`_. +Example of adding custom log statement to your code:: + DRLOG("my debug message with varA:{} and varB:{}", a, b); -See also --------- -`Fuzz Testing`_ - Fuzz testing of distributed ranges APIs +Contact us +---------- -`Spec Editing`_ - Editing the API document +Contact us by writing a `new issue`_. -`Print Type`_ - Print types at compile time: +We seek collaboration opportunities and welcome feedback on ways to extend the library, +according to developer needs. -`Testing`_ - Test system maintenance -`Security`_ - Security policy +See also +-------- + +* `CONTRIBUTING`_ +* `Fuzz Testing`_ +* `Spec Editing`_ - Editing the API document +* `Print Type`_ - Print types at compile time: +* `Testing`_ - Test system maintenance +* `Security`_ - Security policy +* `Doxygen`_ .. _`Security`: SECURITY.md .. _`Testing`: doc/developer/testing @@ -142,10 +203,13 @@ See also .. _`CONTRIBUTING`: CONTRIBUTING.md .. _`Distributed Ranges, why you need it`: https://github.com/oneapi-src/distributed-ranges/blob/main/doc/presentations/Distributed%20Ranges%2C%20why%20you%20need%20it.pdf .. _`Get Started with Distributed Ranges`: https://www.intel.com/content/www/us/en/developer/articles/guide/get-started-with-distributed-ranges.html -.. _`Sample repository showing Distributed Ranges usage`: https://github.com/oneapi-src/distributed-ranges-tutorial +.. _`Distributed Ranges Tutorial`: https://github.com/oneapi-src/distributed-ranges-tutorial .. _`Distributed Ranges, A Model for Distributed Data Structures, Algorithms, and Views`: https://dl.acm.org/doi/10.1145/3650200.3656632 .. _`CppCon 2023; Benjamin Brock; Distributed Ranges`: https://www.youtube.com/watch?v=X_dlJcV21YI .. _`Intel Innovation'23`: https://github.com/oneapi-src/distributed-ranges/blob/main/doc/presentations/Distributed%20Ranges.pdf .. _`API specification`: https://oneapi-src.github.io/distributed-ranges/spec/ .. _`Doxygen`: https://oneapi-src.github.io/distributed-ranges/doxygen/ .. _`new issue`: issues/new +.. _`OneAPI HPC Toolkit`: https://www.intel.com/content/www/us/en/developer/tools/oneapi/hpc-toolkit-download.html +.. _`OneAPI for NVIDIA GPUs`: https://developer.codeplay.com/products/oneapi/nvidia/home/ +.. _`CUDA`: https://developer.nvidia.com/cuda-toolkit diff --git a/doc/spec/source/conf.py b/doc/spec/source/conf.py index 896427af37..f22f62f329 100644 --- a/doc/spec/source/conf.py +++ b/doc/spec/source/conf.py @@ -22,7 +22,7 @@ # -- Project information ----------------------------------------------------- project = "distributed-ranges" -copyright = "2022-2024, Intel" +copyright = "2022-2025, Intel" # -- General configuration --------------------------------------------------- @@ -52,10 +52,7 @@ # documentation. # html_theme_options = { - "repository_url": ( - "https://github.com/intel-sandbox/" - "personal.rscohn1.distributed-ranges" - ), + "repository_url": ("https://github.com/oneapi-src/distributed-ranges"), "path_to_docs": "doc/spec/source", "use_issues_button": True, "use_edit_page_button": True, diff --git a/doc/spec/source/index.rst b/doc/spec/source/index.rst index f580e54175..faa030cc2d 100644 --- a/doc/spec/source/index.rst +++ b/doc/spec/source/index.rst @@ -27,5 +27,4 @@ Indices and tables ================== * :ref:`genindex` -* :ref:`modindex` * :ref:`search` diff --git a/include/CMakeLists.txt b/include/CMakeLists.txt index 5176e13e8c..83b708857d 100644 --- a/include/CMakeLists.txt +++ b/include/CMakeLists.txt @@ -4,7 +4,7 @@ FetchContent_Declare( dpl - GIT_REPOSITORY https://github.com/oneapi-src/oneDPL.git + GIT_REPOSITORY https://github.com/uxlfoundation/oneDPL.git GIT_TAG main) FetchContent_MakeAvailable(dpl)