• Stars
    star
    295
  • Rank 140,902 (Top 3 %)
  • Language
    C++
  • License
    Other
  • Created over 5 years ago
  • Updated over 1 year ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Reference implementation of mdspan targeting C++23

Reference mdspan implementation

The ISO-C++ proposal 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 :-)

Try it out on Godbolt{: .btn }

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<index_type> alias.

Using mdspan

A tutorial-style introduction to the basic usage of mdspan is provided on the project wiki. More advanced tutorials to come.

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

Building and Installation

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.

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

TODO write this

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:

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.

C++17

  • 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.

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
  • benchmarks are not available (they need submdspan)

Acknowledgements

This work was undertaken as part of the Kokkos project 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.

More Repositories

1

kokkos

Kokkos C++ Performance Portability Programming Ecosystem: The Programming Model - Parallel Execution and Memory Abstraction
C++
1,977
star
2

kokkos-kernels

Kokkos C++ Performance Portability Programming Ecosystem: Math Kernels - Provides BLAS, Sparse BLAS and Graph Kernels
C++
294
star
3

kokkos-tutorials

Tutorials for the Kokkos C++ Performance Portability Programming EcoSystem
C++
240
star
4

stdBLAS

Reference Implementation for stdBLAS
C++
124
star
5

kokkos-tools

Kokkos C++ Performance Portability Programming EcoSystem: Profiling and Debugging Tools
C++
71
star
6

pykokkos

Provides Kokkos performance portable parallel programming in Python.
Python
65
star
7

kokkos-remote-spaces

Kokkos Remote Spaces implements distributed Kokkos Views and related APIs for distributed parallel programming.
C++
42
star
8

array_ref

Polymorphic multidimensional array view
C++
35
star
9

pykokkos-base

Python bindings for data interoperability with Kokkos (View, DynRankView)
C++
24
star
10

kokkos-fortran-interop

The Kokkos Fortran Interop repository contains tools and interfaces which help interactions between Fortran portions of an applications and C++ portions using Kokkos.
Fortran
24
star
11

kokkos-fft

A shared-memory FFT for the Kokkos ecosystem
C++
21
star
12

simd-math

Library for length agnostic SIMD intrinsic support and the corresponding math operations
C++
20
star
13

kokkos-comm

Experimental MPI Wrapper for Kokkos
C++
15
star
14

mdarray

C++
10
star
15

kokkos-miniapps

Mini-applications that exclusively use the Kokkos programming model
C++
10
star
16

ISO-CPP-Papers

HTML
8
star
17

nvcc_wrapper

Wrapper shell script for NVIDIA nvcc to better conform to host compiler command line arguments
Shell
7
star
18

hpcbind

Binding utilities used for MPI, OpenMP and GPUs
Shell
6
star
19

kokkos-resilience

Resilience Extensions for Kokkos
C++
4
star
20

kokkos-core-wiki

3
star
21

kokkos-benchmark-results

3
star
22

kokkos.github.io

Documentation Repo
HTML
1
star
23

kokkos-openmptarget-examples

This is a repository for sharing OpenMP 5 target usage examples and reproducers
C++
1
star