Quickstart¶
In this example, we capture a simple kernel that doubles the values in a view and then replay it in a separate program.
The capture program
and a replay program with result checking
are available in the repository's examples/ directory.
See Installation for the prerequisites and build instructions.
capture.cpp¶
#include <Kokkos_Core.hpp>
#include <krepe/extractor.hpp>
int main(int argc, char* argv[]) {
Kokkos::ScopeGuard kokkos_scope(argc, argv);
const int N = 1024;
Kokkos::View<int*> values("values", N);
Kokkos::parallel_for(
"init", N, KOKKOS_LAMBDA(int i) { values(i) = i; });
// Use KREPE's wrapper to capture this kernel's data and execution policy.
krepe::parallel_for(
"scale", N, KOKKOS_LAMBDA(int i) { values(i) *= 2; });
Kokkos::fence();
return 0;
}
replay.cpp¶
The replay uses the captured data and execution policy. The second argument
of krepe::parallel_for is ignored, so we can pass 0.
#include <Kokkos_Core.hpp>
#include <krepe/replayer.hpp>
int main(int argc, char* argv[]) {
krepe::ScopeGuard replay_scope(argc, argv);
Kokkos::ScopeGuard kokkos_scope(argc, argv);
Kokkos::View<int*> values;
// Replay with the captured inputs and policy (the 0 argument is ignored).
krepe::parallel_for(
"scale", 0, KOKKOS_LAMBDA(int i) { values(i) *= 2; });
Kokkos::fence();
return 0;
}
CMakeLists.txt¶
cmake_minimum_required(VERSION 3.26)
project(krepe_quickstart LANGUAGES CXX)
set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
set(CMAKE_CXX_EXTENSIONS OFF)
find_package(Kokkos 5.0 REQUIRED)
find_package(KREPE REQUIRED)
add_executable(capture_prog capture.cpp)
target_link_libraries(capture_prog PRIVATE KREPE::extractor Kokkos::kokkos)
add_executable(replay_prog replay.cpp)
target_link_libraries(replay_prog PRIVATE KREPE::replayer Kokkos::kokkos)
Build the example¶
cmake -S . -B build \
-DCMAKE_BUILD_TYPE=Release \
-DCMAKE_CXX_COMPILER=/path/to/compiler \
-DKokkos_ROOT=/path/to/kokkos/install \
-DKREPE_ROOT=/path/to/krepe/install
cmake --build build --parallel
Capture the kernel¶
Load the installed Kokkos tool and select the first invocation of the scale kernel:
./build/capture_prog \
--kokkos-tools-libs=/path/to/krepe/install/lib/libkrepe.so \
--kokkos-tools-args="--krepe-kernel-label=scale"
The first invocation is captured by default. To capture another one, add
--krepe-kernel-invocation=N to --kokkos-tools-args.
The tool creates a file named krepe_scale_<kernel_id>.h5 in the current
directory and reports its path.
Replay the kernel¶
Pass the generated dump to the replay program. Replace
krepe_scale_<kernel_id>.h5 with the dump path reported during capture:
# Load the captured data and execution policy from the dump.
./build/replay_prog \
--krepe-dump-file="krepe_scale_<kernel_id>.h5"
Verify all 1024 values (optional)
To check the results, uses krepe::compare_views to compare
all 1024 values with the output recorded during capture:
#include <Kokkos_Core.hpp>
#include <Kokkos_StdAlgorithms.hpp>
#include <krepe/replayer.hpp>
#include <iostream>
#include <tuple>
int main(int argc, char* argv[]) {
krepe::ScopeGuard replay_scope(argc, argv);
Kokkos::ScopeGuard kokkos_scope(argc, argv);
Kokkos::View<int*> values;
// Replay with the captured inputs and policy (the 0 argument is ignored).
krepe::parallel_for(
"scale", 0, KOKKOS_LAMBDA(int i) { values(i) *= 2; });
Kokkos::fence();
// Compare the replayed values with the captured output.
krepe::compare_views<int*>(
"values", std::make_tuple(1024), [](auto expected, auto actual) {
if (!Kokkos::Experimental::equal(Kokkos::DefaultExecutionSpace(),
expected, actual)) {
Kokkos::abort("Replay verification failed");
}
});
std::cout << "Replay verified: 1024 values match.\n";
return 0;
}