DOCSEARCHbyAlgolia
Submit Docs

kokkos/mdspan

repository·stable·Indexed 19 days ago

https://github.com/kokkos/mdspan

A header-only implementation of the C++ mdspan proposal (P0009) for non-owning multi-dimensional array references. It provides backports for C++14 and C++17, conforms to the C++23 draft standard (July 2022), and includes extensions for device-side compatibility such as CUDA.

Tokens
850
Snippets
1
Records
5
Agent score
18%

What's inside kokkos-mdspan

  1. Enable CUDA compatibility and non-standard extensions

    stable
    To support device code (e.g., for CUDA), the library provides macros to enable __device__ marking on functions. Additionally, you can invoke non-standard extension methods by passing Kokkos::mdspan_non_standard as the first argument to the relevant calls.

  2. Understand mdspan behavior across C++ standards

    stable

    The implementation is fully conforming to the C++23 draft standard (July 2022). When using older standards, there are specific behavioral differences:

    C++20

    • Implements operator() instead of operator[] (unless configured otherwise via macros).

    C++17

    • mdspan has a default constructor even when it should not (e.g., all static extents and default constructible mapping/accessor).
    • Missing conditional explicit markup: certain constructors are implicit, such as implicit conversion from dynamic extent to static extent.
    • Constraints on stride() for layout_left, layout_right, and layout_stride mappings requiring extents_type::rank() > 0 are not implemented.

    C++14

    • Deduction guides are not available.
    • submdspan (P2630) is not available (an earlier variant is available up to release 0.5).
    • Benchmarks are not available because they depend on submdspan.

  3. Build the tests and benchmarks

    stable

    While the library is header-only for usage, you must use CMake to build and run the included test suites or benchmarks. Below are the recommended CMake configurations for different environments.

    ### clang-15 / cmake 3.23
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
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
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"

  4. Use mdspan in your projects

    stable
    The mdspan implementation is header-only. You do not need to build or install it to use it in your own code; simply include the headers in your project. The library uses feature test macros to detect available compiler features automatically.

  5. Configure mdspan operator availability

    stable

    In C++20 mode, the implementation defaults to providing operator() instead of operator[]. You can manually control which operators are available by defining the following macros, regardless of whether the compiler detects multi-dimensional subscript support:

    • MDSPAN_USE_BRACKET_OPERATOR=[0,1]
    • MDSPAN_USE_PAREN_OPERATOR=[0,1]