diff --git a/README.md b/README.md index 8442d8bf..02c6419e 100644 --- a/README.md +++ b/README.md @@ -1,71 +1,44 @@ Reference `mdspan` implementation ========================================== -The ISO-C++ proposal [P0009](https://wg21.link/p0009) will add support for non-owning multi-dimensional array references to the C++ standard library. This repository aims to provide a production-quality implementation of the proposal as written (with a few caveats, see below) in preparation for the addition of `mdspan` to the standard. Please feel free to use this, file bugs when it breaks, and let us know how it works for you :-) +This is the Kokkos Project's implementation of the ISO C++ `mdspan` feature with extensions for High Performance Computing (HPC) use cases. +The implementation underpins the primary data structures of the Kokkos Project and is used in production environments. -[Try it out on Godbolt](https://godbolt.org/z/Mxa7cej1a){: .btn } +**Kokkos MDSpan is part of the [Kokkos C++ Performance Portability Programming Ecosystem](https://kokkos.org).** -During the final leg of the ISO C++ committee review process a number of breaking changes were proposed and accepted (issue #136). These are now merged into the stable branch. - -Note: There is a tag mdspan-0.3.0 which reflects the status of P0009 before R17 - i.e. it does not have the integral type template parameter for `extents`. -Note: There is a tag mdspan-0.4.0 which reflects the status of P0009 before - -* renaming `pointer`, `data`, `is_contiguous` and `is_always_contiguous`; and before -* renaming `size_type` to `index_type` and introducing a new `size_type = make_unsigned_t` alias. - -Using `mdspan` --------------- - -A [tutorial-style introduction](https://github.com/kokkos/mdspan/wiki/A-Gentle-Introduction-to-mdspan) to the basic usage of `mdspan` is provided on the project wiki. More advanced tutorials to come. +Kokkos is a [Linux Foundation](https://linuxfoundation.org) project and a *Core* stage member of the LF's +[High Performance Software Foundation](https://hpsf.io). Features in Addition To C++ Standard ------------------------------------ -- C++17 backport (e.g., concepts not required) -- C++14 backport (e.g., fold expressions not required) - - Compile times of this backport will be substantially slower than the C++17 version -- Macros to enable, e.g., `__device__` marking of all functions for CUDA compatibility +* Backport to C++14/17/20/23 + * Not all features are supported in C++14 +* Macros to enable, e.g., `__device__` marking of all functions for CUDA compatibility * Non-standard extensions for device code compatibility - * These extension methods can be invoked by passing `Kokkos::mdspan_non_standard` as the first argument. -Building and Installation -------------------------- +Obtaining Kokkos MDSpan +----------------------- -This implementation is header-only, with compiler features detected using feature test macros, so you can just use it directly with no building or installation. If you would like to run the included tests or benchmarks, you'll need CMake. +The latest release of Kokkos's mdspan can be obtained from the [GitHub releases page](https://github.com/kokkos/mdspan/releases/latest). -### Running tests - -#### Configurations - -- clang-15 / cmake 3.23 - - Warning free with `-Wall -Wextra -pedantic` for C++23/20. In C++17 pedantic will give a few warnings, in C++14 Wextra will also give some. - - `cmake -DMDSPAN_ENABLE_TESTS=ON -DMDSPAN_ENABLE_BENCHMARKS=ON -DCMAKE_CXX_FLAGS="-Werror -Wall -Wextra -pedantic" -DCMAKE_CXX_STANDARD=23 -DMDSPAN_CXX_STANDARD=23 -DCMAKE_CXX_COMPILER=clang++` -- gcc-11 / cmake 3.23 - - Warning free with `-Wall -Wextra -pedantic` for C++23/20. In C++17 and C++14 pedantic will give a warning (note only with `CMAKE_CXX_EXTENSION=OFF`). - - `cmake -DMDSPAN_ENABLE_TESTS=ON -DMDSPAN_ENABLE_BENCHMARKS=ON -DCMAKE_CXX_FLAGS="-Werror -Wall -Wextra -pedantic" -DCMAKE_CXX_STANDARD=17 -DMDSPAN_CXX_STANDARD=17 -DCMAKE_CXX_COMPILER=g++ -DCMAKE_CXX_EXTENSIONS=OFF` -- CUDA 11.x / gcc 9.1 / cmake 3.23 - - has a few warnings in C++17 mostly in `mdarray` due to the use of `vector` as container for the tests. - - Note with CUDA 11.7 and GCC 11.1 as host compiler we observe some issues around CTAD, some of the layout tests won't compile - - CUDA 11.7 with GCC 9.1 works however - - `cmake -DMDSPAN_ENABLE_TESTS=ON -DMDSPAN_ENABLE_CUDA=ON -DMDSPAN_ENABLE_BENCHMARKS=ON -DCMAKE_CXX_STANDARD=17 -DCMAKE_CUDA_ARCHITECTURES=70 -DMDSPAN_CXX_STANDARD=17 -DCMAKE_CUDA_FLAGS="--expt-relaxed-constexpr --extended-lambda"` - - -### Running benchmarks +Support +------- -TODO write this +For questions find us on Slack: https://kokkos.org/community/chat/#slack or open a GitHub issue. Caveats ------- -This implementation is fully conforming with the version of `mdspan` voted into the C++23 draft standard in July 2022. -When not in C++23 mode the implementation deviates from the proposal as follows: +This implementation is fully conforming with the version of `mdspan` voted into the C++26 draft standard. +When not at least in C++23 mode the implementation deviates from the C++26 draft standard as follows: ### C++20 - implements `operator()` not `operator[]` - - note you can control which operator is available with defining `MDSPAN_USE_BRACKET_OPERATOR=[0,1]` and `MDSPAN_USE_PAREN_OPERATOR=[0,1]` irrespective of whether multi dimensional subscript support is detected. + - you can control which operator is available by defining `MDSPAN_USE_BRACKET_OPERATOR=[0,1]` and `MDSPAN_USE_PAREN_OPERATOR=[0,1]` irrespective of whether language support for multidimensional `operator[]` is detected. ### C++17 -- mdspan has a default constructor even in cases where it shouldn't (i.e. all static extents, and default constructible mapping/accessor) +- mdspan has a default constructor even in cases where it shouldn't (i.e., all static extents, and default constructible mapping/accessor) - the conditional explicit markup is missing, making certain constructors implicit - most notably you can implicitly convert from dynamic extent to static extent, which you can't in C++20 mode - there is a constraint on `layout_left::mapping::stride()`, `layout_right::mapping::stride()` and `layout_stride::mapping::stride()` that `extents_type::rank() > 0` is `true`, which is not implemented in C++17 or C++14. @@ -73,12 +46,48 @@ When not in C++23 mode the implementation deviates from the proposal as follows: ### C++14 - deduction guides don't exist - submdspan (P2630) is not available - an earlier variant of submdspan is available up to release 0.5 in C++14 mode +- `layout_left_padded` and `layout_right_padded` are not available. - benchmarks are not available (they need submdspan) +Building and Installation +------------------------- + +This project is a CMake project. + +``` +cmake -B builddir [] +cmake --build builddir +cmake --install builddir [--prefix ] +``` + +mdspan specific options: + +- `MDSPAN_ENABLE_TESTS`: Enable tests. Default: Off +- `MDSPAN_ENABLE_EXAMPLES`: Build examples. Default: Off +- `MDSPAN_ENABLE_BENCHMARKS`: Enable benchmarks. Default: Off +- `MDSPAN_ENABLE_COMP_BENCH`: Enable compilation benchmarks. Default: Off +- `MDSPAN_ENABLE_CUDA`: Enable Cuda tests/benchmarks/examples if tests/benchmarks/examples are enabled. Default: Off +- `MDSPAN_ENABLE_SYCL`: Enable SYCL tests/benchmarks/examples if tests/benchmarks/examples are enabled. Default: Off +- `MDSPAN_ENABLE_HIP`: Enable HIP tests/benchmarks/examples if tests/benchmarks/examples are enabled. Default: Off +- `MDSPAN_ENABLE_OPENMP`: Enable OpenMP benchmarks if benchmarks are enabled. Default: On if and only if OpenMP is detected +- `MDSPAN_CXX_STANDARD`: Set the C++ standard for compiling tests/benchmarks/examples. Default: Auto-Detect +- `MDSPAN_USE_SYSTEM_GTEST`: Use system-installed GoogleTest library for tests. Default: Off +- `MDSPAN_USE_SYSTEM_BENCHMARK`: Use system-installed Google Benchmark library for benchmarks. Default: On + +Note: if you only install mdspan, the CUDA/SYCL/HIP/OPENMP options have no real effect. +MDSpan is installed in a *headers only* fashion, and discovers use of CUDA, HIP, SYCL and OpenMP from compiler macros. +Thus a single install of MDSpan can be used for all such downstream use cases. + +Contributing +------------ + +Please see [this page](https://kokkos.org/kokkos-core-wiki/contributing.html) for details on how to contribute. + +License +------- -Acknowledgements -================ +[![License](https://img.shields.io/badge/License-Apache--2.0_WITH_LLVM--exception-blue)](https://spdx.org/licenses/LLVM-exception.html) -This work was undertaken as part of the [Kokkos project](https://github.com/kokkos/kokkos) at Sandia National Laboratories. Sandia National Laboratories is a multimission laboratory managed and operated by National Technology & Engineering Solutions of Sandia, LLC, a wholly owned subsidary of Honeywell International Inc., for the U. S. Department of Energy's National Nuclear Security Administration under contract DE-NA0003525. +The full license statement used in all headers is available [here](https://kokkos.org/kokkos-core-wiki/license.html).