kokkos-execution

kokkos-execution

kokkos-execution is a header-only library that customizes std::execution for Kokkos. It uses stdexec, the reference implementation of std::execution.

kokkos-execution lets you express your operations as sender pipelines, and lower them transparently to either of these two Kokkos programming models:

1. execution space
2. graph

A thorough comparison of these programming models can be found here.

The full documentation is available here.

Overview

kokkos-execution provides the following execution contexts:

1. Kokkos::Execution::ExecutionSpaceContext
2. Kokkos::Execution::GraphContext

Many standard algorithms (such as then, bulk, continues_on, when_all) are customized for each of these contexts, together with the custom algorithms Kokkos::Execution::parallel_for Kokkos::Execution::parallel_reduce.

The algorithms are customized to avoid unnecessary synchronization points.

All of the following Kokkos backends are supported and exercised in CI:

Kokkos backend	Supported
Serial	:white_check_mark:
Threads	:exclamation:
OpenMP	:white_check_mark:
HPX	:white_check_mark:
Cuda	:white_check_mark:
HIP	:white_check_mark:
SYCL	:white_check_mark:

:exclamation: The Kokkos::Threads backend requires that parallel regions be launched from the thread that initialized Kokkos. Many tests are thus disabled.

How operation dependencies are expressed?

When using Kokkos::Execution::ExecutionSpaceContext, dependencies are expressed either through execution space ordering or using events.

When using Kokkos::Execution::GraphContext, dependencies are expressed through the underlying Kokkos graph edges.

Testing

Tests do not rely solely on value correctness. Through the kokkos-tools hooks, they also assert that the expected sequence of Kokkos actions (such as parallel region launch or fence) actually took place. Such trace-based assertions are made practical by kokkos-utils, which provides the matcher machinery used to express and check the expected sequences.

Tests can be found in this directory.

Building

The library is developed against the latest version of stdexec, bundled as a submodule. The versions of Kokkos and other dependencies are recorded here.

Our CI relies on Docker images, ready to be used for testing kokkos-execution off the self:

docker pull ghcr.io/uliegecsm/kokkos-execution/kokkos-execution:gnu-15-OpenMP-Release

Once the container is running, do:

git clone --recurse-submodules https://github.com/uliegecsm/kokkos-execution.git
cd kokkos-execution
cmake -S . --preset=gnu-OpenMP
cmake --build --preset=gnu-OpenMP
ctest --preset=gnu-OpenMP

Example

A sequence of operations can be written as a sender pipeline and easily lowered to either an execution space instance or a graph:

auto ops = Kokkos::Execution::parallel_for("label for A", 17, Functor_A{...})
         | stdexec::bulk(stdexec::par, N_B, Functor_B{...})
         | Kokkos::Execution::parallel_for("label for C", Kokkos::range_slice<size_t, size_t>{3, 42}, Functor_C{...});
 
// Lower onto an execution space instance.
const Kokkos::Execution::ExecutionSpaceContext<Exec> ectx{exec};
stdexec::sync_wait(stdexec::schedule(ectx.get_scheduler()) | ops);
 
// Lower onto a graph.
const Kokkos::Execution::GraphContext<Exec> gctx{exec};
stdexec::sync_wait(stdexec::schedule(gctx.get_scheduler()) | ops);

More examples are available here.

Contributing

See our contribution guidelines.