Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

update README #257

Draft
wants to merge 1 commit into
base: stable
Choose a base branch
from
Draft

update README #257

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 30 additions & 13 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,4 @@
Reference `mdspan` implementation
==========================================
# 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 :-)

Expand All @@ -13,24 +12,45 @@ 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`
--------------
## 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.

Features in Addition To C++ Standard
------------------------------------
### Including `mdspan` in your code

`mdspan` is a header-only library, and can be included in one of three ways: as a CMake target via `find_package(mdspan <options...>)`, as an include directory, or as a single include file. You can obtain the latest generated single header file from [here](https://github.com/kokkos/mdspan/blob/single-header/mdspan.hpp). This is always kept up to date with the `stable` branch via an automated script.

There are two "modes" of including the `mdspan` headers. The primary way, which we recommend, is via the headers `<mdspan/mdspan.hpp>` and `<mdspan/mdarray.hpp>`. These will define all the mdspan constructs in namespace `Kokkos` for elements that are part of the C++23 standard, and `Kokkos::Experimental` for elements that are being proposed for the C++26 standard.

The second way, is to include the "std-mode" headers. These are `<experimental/mdspan>` and `<experimental/mdarray>`. When included in this way, all elements in the C++23 standard are defined in the `std` namespace, and elements that are proposed for C++26 are in the `std::experimental`. This mode can be useful when writing code for compilers and standard libraries that don't yet support `mdspan`. Note that while we have some compile-time tests for this mode, in general, this mode is **not** portable because adding entities to the `std` namespace is not supported by any compiler. This means that our "std-mode" support can break at any time, and is why we recommend the primary method above.

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

`mdspan` requires CMake 3.14 or higher, and can build with no dependencies. If you want to build the tests with various backends, such as Cuda or Sycl, these will have to be installed first. Configuring is done in the usual way with CMake. The possible CMake options are documented below:

| Option | Description | Default |
| -------------------------- | ------------------------------------------------------------------------------ | -------- |
| `MDSPAN_ENABLE_TESTS` | Enable tests | `OFF` |
| `MDSPAN_ENABLE_EXAMPLES` | Enable examples | `OFF` |
| `MDSPAN_ENABLE_BENCHMARKS` | Enable Benchmarks | `OFF` |
| `MDSPAN_ENABLE_COMP_BENCH` | Enable compilation benchmarks | `OFF` |
| `MDSPAN_ENABLE_CUDA` | Enable Cuda tests/benchmarks/examples if tests/benchmarks/examples are enabled | `OFF` |
| `MDSPAN_ENABLE_SYCL` | Enable SYCL tests/benchmarks/examples if tests/benchmarks/examples are enabled | `OFF` |
| `MDSPAN_ENABLE_HIP` | Enable HIP tests/benchmarks/examples if tests/benchmarks/examples are enabled | `OFF` |
| `MDSPAN_ENABLE_OPENMP` | Enable OpenMP benchmarks if benchmarks are enabled | `ON` |
| `MDSPAN_USE_SYSTEM_GTEST` | Use system-installed GoogleTest library for tests | `OFF` |
| `MDSPAN_CXX_STANDARD` | Override the default CXX_STANDARD to compile with | `DETECT` |
| `MDSPAN_ENABLE_CONCEPTS` | Try to enable concepts support by giving extra flags | `ON` |

### Running tests

#### Configurations
Expand All @@ -47,13 +67,11 @@ This implementation is header-only, with compiler features detected using featur
- 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
-------
## 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:
Expand All @@ -75,8 +93,7 @@ When not in C++23 mode the implementation deviates from the proposal as follows:



Acknowledgements
================
# Acknowledgements

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.