Merge pull request #237 from oleksandr-pavlyk/add-pynvbench

Python package pynvbench introduced that exposes `cuda.bench` namespace. Repository provides a set of examples.

Author: oleksandr-pavlyk

python/.gitignore

@@ -0,0 +1,4 @@
+build
+nvbench_build
+nvbench_install
+__pycache__

python/CMakeLists.txt

@@ -0,0 +1,41 @@
+cmake_minimum_required(VERSION 3.30...4.0)
+
+# CUDA is transitive dependency of nvbench
+project(${SKBUILD_PROJECT_NAME} LANGUAGES CXX CUDA)
+
+find_package(Python REQUIRED COMPONENTS Development.Module)
+find_package(CUDAToolkit REQUIRED)
+
+# Get CMake package manager
+set(_cpm_download_location ${CMAKE_CURRENT_BINARY_DIR}/cmake/CPM.cmake)
+file(
+  DOWNLOAD
+  https://github.com/cpm-cmake/CPM.cmake/releases/download/v0.42.0/CPM.cmake
+  ${_cpm_download_location}
+  EXPECTED_HASH SHA256=2020b4fc42dba44817983e06342e682ecfc3d2f484a581f11cc5731fbe4dce8a
+)
+include(${_cpm_download_location})
+
+CPMAddPackage(
+   NAME nvbench
+   SOURCE_DIR ${CMAKE_CURRENT_SOURCE_DIR}/..
+   OPTIONS "NVBench_INSTALL_RULES ON"
+   FIND_PACKAGE_ARGS CONFIG REQUIRED
+)
+
+CPMAddPackage("gh:pybind/[email protected]")
+
+pybind11_add_module(_nvbench MODULE src/py_nvbench.cpp)
+target_link_libraries(_nvbench PUBLIC nvbench::nvbench)
+target_link_libraries(_nvbench PRIVATE CUDA::cudart_static)
+
+set_target_properties(_nvbench PROPERTIES INSTALL_RPATH "$ORIGIN")
+set_target_properties(_nvbench PROPERTIES INTERPROCEDURAL_OPTIMIZATION ON)
+set_target_properties(_nvbench PROPERTIES POSITION_INDEPENDENT_CODE ON)
+
+install(TARGETS _nvbench DESTINATION cuda/bench)
+
+# Determine target that nvbench::nvbench is an alias of,
+# necessary because ALIAS targets cannot be installed
+get_target_property(_aliased_target_name nvbench::nvbench ALIASED_TARGET)
+install(IMPORTED_RUNTIME_ARTIFACTS ${_aliased_target_name} DESTINATION cuda/bench)

python/README.md

@@ -0,0 +1,61 @@
+# CUDA Kernel Benchmarking Package
+
+This package provides Python API to CUDA Kernel Benchmarking Library `NVBench`.
+
+## Building
+
+### Ensure recent version of CMake
+
+Since `nvbench` requires a rather new version of CMake (>=3.30.4), either build CMake from sources, or create a conda environment with a recent version of CMake, using
+
+```
+conda create -n build_env --yes  cmake ninja
+conda activate build_env
+```
+
+### Ensure CUDA compiler
+
+Since building `NVBench` library requires CUDA compiler, ensure that appropriate environment variables
+are set. For example, assuming CUDA toolkit is installed system-wide, and assuming Ampere GPU architecture:
+
+```bash
+export CUDACXX=/usr/local/cuda/bin/nvcc
+export CUDAARCHS=86
+``
+
+### Build Python project
+
+Now switch to python folder, configure and install NVBench library, and install the package in editable mode:
+
+```bash
+cd nvbench/python
+pip install -e .
+```
+
+### Verify that package works
+
+```bash
+python test/run_1.py
+```
+
+### Run examples
+
+```bash
+# Example benchmarking numba.cuda kernel
+python examples/throughput.py
+```
+
+```bash
+# Example benchmarking kernels authored using cuda.core
+python examples/axes.py
+```
+
+```bash
+# Example benchmarking algorithms from cuda.cccl.parallel
+python examples/cccl_parallel_segmented_reduce.py
+```
+
+```bash
+# Example benchmarking CuPy function
+python examples/cupy_extract.py
+```

python/cuda/bench/__init__.py

@@ -0,0 +1,59 @@
+# Copyright 2025 NVIDIA Corporation
+#
+#  Licensed under the Apache License, Version 2.0 with the LLVM exception
+#  (the "License"); you may not use this file except in compliance with
+#  the License.
+#
+#  You may obtain a copy of the License at
+#
+#      http://llvm.org/foundation/relicensing/LICENSE.txt
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+import importlib.metadata
+import warnings
+
+from cuda.pathfinder import (  # type: ignore[import-not-found]
+    load_nvidia_dynamic_lib,
+)
+
+try:
+    __version__ = importlib.metadata.version("pynvbench")
+except Exception as e:
+    __version__ = "0.0.0dev"
+    warnings.warn(
+        "Could not retrieve version of pynvbench package dynamically from its metadata. "
+        f"Exception {e} was raised. "
+        f"Version is set to fall-back value '{__version__}' instead."
+    )
+
+for libname in ("cupti", "nvperf_target", "nvperf_host"):
+    load_nvidia_dynamic_lib(libname)
+
+from cuda.bench._nvbench import (  # noqa: E402
+    Benchmark as Benchmark,
+)
+from cuda.bench._nvbench import (  # noqa: E402
+    CudaStream as CudaStream,
+)
+from cuda.bench._nvbench import (  # noqa: E402
+    Launch as Launch,
+)
+from cuda.bench._nvbench import (  # noqa: E402
+    NVBenchRuntimeError as NVBenchRuntimeError,
+)
+from cuda.bench._nvbench import (  # noqa: E402
+    State as State,
+)
+from cuda.bench._nvbench import (  # noqa: E402
+    register as register,
+)
+from cuda.bench._nvbench import (  # noqa: E402
+    run_all_benchmarks as run_all_benchmarks,
+)
+
+del load_nvidia_dynamic_lib