mirror of
https://github.com/NVIDIA/nvbench.git
synced 2026-07-08 08:07:20 +00:00
e0198df47f
Document that published `cuda-bench` wheels are multi-CUDA wheels containing both CUDA 12.x and CUDA 13.x native extensions, with runtime selection driven by the installed cuda.bindings major version. Clarify that the cu12/cu13 extras select compatible cuda-bindings dependency families rather than different cuda-bench wheels. Update source-build instructions to use CUDAARCHS=all-major, avoid editable installs while the versioned extension layout is unsupported there, and note that local builds only produce the extension for the Toolkit found by CMake. closes #391
108 lines
3.2 KiB
Markdown
108 lines
3.2 KiB
Markdown
# CUDA Kernel Benchmarking Package
|
|
|
|
This package provides a Python API to the CUDA Kernel Benchmarking
|
|
Library `NVBench`.
|
|
|
|
## Installation
|
|
|
|
Install from PyPI:
|
|
|
|
```bash
|
|
python -m pip install cuda-bench
|
|
```
|
|
|
|
Use an optional dependency if you want `pip` to install a compatible
|
|
`cuda-bindings` package as well:
|
|
|
|
```bash
|
|
python -m pip install "cuda-bench[cu12]" # Install cuda-bindings 12.x
|
|
python -m pip install "cuda-bench[cu13]" # Install cuda-bindings 13.x
|
|
```
|
|
|
|
The published Linux wheel is compatible with both CUDA 12.x and CUDA 13.x
|
|
Python environments. It contains two native extensions: one built with a CUDA
|
|
12.x Toolkit and installed under `cuda.bench.cu12`, and one built with a CUDA
|
|
13.x Toolkit and installed under `cuda.bench.cu13`. At runtime, `cuda-bench`
|
|
queries the installed `cuda.bindings` package to determine the CUDA major
|
|
version and loads the matching native extension.
|
|
|
|
The `cu12` and `cu13` extras do not select different `cuda-bench` wheels. They
|
|
only select the compatible `cuda-bindings` dependency family. If your
|
|
environment already provides an appropriate `cuda-bindings` 12.x or 13.x
|
|
package, installing plain `cuda-bench` is sufficient.
|
|
|
|
A local CUDA Toolkit is not required when installing a published wheel, but the
|
|
NVIDIA driver must support the CUDA runtime used by the installed
|
|
`cuda.bindings` package. Use the same CUDA major version for other CUDA Python
|
|
binary packages in the environment, for example `cupy-cuda12x` with
|
|
`cuda-bench[cu12]` or `cupy-cuda13x` with `cuda-bench[cu13]`.
|
|
|
|
## Building from source
|
|
|
|
### Ensure recent version of CMake
|
|
|
|
Since `nvbench` requires CMake >=3.30.4, either install a recent CMake or
|
|
create a conda environment with CMake and Ninja:
|
|
|
|
```bash
|
|
conda create -n build_env --yes cmake ninja
|
|
conda activate build_env
|
|
```
|
|
|
|
### Ensure CUDA compiler
|
|
|
|
Building `cuda-bench` from source requires a CUDA Toolkit with `nvcc`. Ensure
|
|
that the appropriate environment variables are set. For example, on Linux,
|
|
assuming the CUDA Toolkit is installed system-wide:
|
|
|
|
```bash
|
|
export CUDACXX=/usr/local/cuda/bin/nvcc
|
|
export CUDAARCHS=all-major
|
|
```
|
|
|
|
Unlike the published wheel, a local source build only builds the native
|
|
extension for the CUDA Toolkit found by CMake. The CUDA major version selected
|
|
in the install command below must match that Toolkit.
|
|
|
|
### Build Python project
|
|
|
|
Now switch to the Python package directory and install `cuda-bench` from source:
|
|
|
|
```bash
|
|
cd nvbench/python
|
|
python -m pip install ".[cu12]" # If CUDACXX points to a CUDA 12.x toolkit
|
|
python -m pip install ".[cu13]" # If CUDACXX points to a CUDA 13.x toolkit
|
|
```
|
|
|
|
Editable installs (`python -m pip install -e .`) are currently not supported.
|
|
They do not install the versioned CUDA extension layout used by `cuda-bench`.
|
|
Re-run the non-editable install command after making source changes.
|
|
|
|
### 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
|
|
```
|