From 0ef009d2a0c29bb5384e33c5a5dff7138f89dec6 Mon Sep 17 00:00:00 2001 From: Christian Trott Date: Thu, 15 Oct 2026 15:19:12 -0600 Subject: [PATCH 1/2] Update README Signed-off-by: Christian Trott --- README.md | 101 +++++++++++++++++++++++++++++------------------------- 1 file changed, 55 insertions(+), 46 deletions(-) diff --git a/README.md b/README.md index 8442d8bf2..c4c15be1d 100644 --- a/README.md +++ b/README.md @@ -1,64 +1,37 @@ 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 proposal as follows: ### C++20 - implements `operator()` not `operator[]` @@ -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 +- `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). From a1199675b9c5211ed638c7bc4b055392b8ad11db Mon Sep 17 00:00:00 2001 From: Christian Trott Date: Thu, 15 Oct 2026 16:56:54 -0600 Subject: [PATCH 2/2] Apply batched suggestions from code review Co-authored-by: Mark Hoemmen --- README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index c4c15be1d..02c6419e5 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ Reference `mdspan` implementation ========================================== -This is the Kokkos Project's implementation of the ISO C++ `mdspan` feature with extensions for High Performance Computing (HPC) use-cases. +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. **Kokkos MDSpan is part of the [Kokkos C++ Performance Portability Programming Ecosystem](https://kokkos.org).** @@ -31,14 +31,14 @@ Caveats ------- 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 proposal as follows: +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. @@ -70,7 +70,7 @@ mdspan specific options: - `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 +- `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