diff --git a/README.md b/README.md index 0072e062ca..d2b5241b2f 100644 --- a/README.md +++ b/README.md @@ -1,76 +1,39 @@ # CUDA-Python -CUDA Python is a standard set of low-level interfaces, providing full coverage of and access to the CUDA host APIs from Python. Checkout the [Overview](https://nvidia.github.io/cuda-python/overview.html) for the workflow and performance results. +CUDA Python is the home for accessing NVIDIA’s CUDA platform from Python. It consists of multiple components: -## Installing +* [cuda.core](https://nvidia.github.io/cuda-python/cuda-core/latest): Pythonic access to CUDA Runtime and other core functionalities +* [cuda.bindings](https://nvidia.github.io/cuda-python/cuda-bindings/latest): Low-level Python bindings to CUDA C APIs +* [cuda.cooperative](https://nvidia.github.io/cccl/cuda_cooperative/): Pythonic exposure of CUB cooperative algorithms +* [cuda.parallel](https://nvidia.github.io/cccl/cuda_parallel/): Pythonic exposure of Thrust parallel algorithms -CUDA Python can be installed from: +For access to NVIDIA Math Libraries, please refer to [nvmath-python](https://docs.nvidia.com/cuda/nvmath-python/latest). -* PYPI -* Conda (nvidia channel) -* Source builds +CUDA Python is currently undergoing an overhaul to improve existing and bring up new components. All of the previously available functionalities from the cuda-python package will continue to be available, please refer to the [cuda.bindings](https://nvidia.github.io/cuda-python/cuda-bindings/latest) documentation for installation guide and further detail. -There're differences in each of these options that are described further in [Installation](https://nvidia.github.io/cuda-python/install.html) documentation. Each package will guarantee minor version compatibility. +## CUDA-Python as a metapackage -## Runtime Dependencies +CUDA-Python is structured to become a metapackage that contains a collection of subpackages. Each subpackage is versioned independently, allowing installation of each component as needed. -CUDA Python is supported on all platforms that CUDA is supported. Specific dependencies are as follows: +### Subpackage: `cuda.core` -* Driver: Linux (450.80.02 or later) Windows (456.38 or later) -* CUDA Toolkit 12.0 to 12.6 +The `cuda.core` package offers idiomatic, pythonic access to CUDA Runtime and other functionalities. -Only the NVRTC redistributable component is required from the CUDA Toolkit. [CUDA Toolkit Documentation](https://docs.nvidia.com/cuda/index.html) Installation Guides can be used for guidance. Note that the NVRTC component in the Toolkit can be obtained via PYPI, Conda or Local Installer. +The goals are to -### Supported Python Versions +1. Provide **idiomatic (“pythonic”)** access to CUDA Driver/Runtime +2. Focus on **developer productivity** by ensuring end-to-end CUDA development can be performed quickly and entirely in Python +3. **Avoid homegrown** Python abstractions for CUDA for new Python GPU libraries starting from scratch +4. **Ease** developer **burden of maintaining** and catching up with latest CUDA features +5. **Flatten the learning curve** for current and future generations of CUDA developers -CUDA Python follows [NEP 29](https://numpy.org/neps/nep-0029-deprecation_policy.html) for supported Python version guarantee. +### Subpackage: `cuda.bindings` -Before dropping support, an issue will be raised to look for feedback. +The `cuda.bindings` package is a standard set of low-level interfaces, providing full coverage of and access to the CUDA host APIs from Python. -Source builds work for multiple Python versions, however pre-build PyPI and Conda packages are only provided for a subset: +The list of available interfaces are: -* Python 3.9 to 3.12 - -## Testing - -### Requirements - -Latest dependencies can be found in [requirements.txt](https://github.com/NVIDIA/cuda-python/blob/main/requirements.txt). - -### Unit-tests - -You can run the included tests with: - -``` -python -m pytest tests/ -``` - -### Benchmark - -You can run benchmark only tests with: - -``` -python -m pytest --benchmark-only benchmarks/ -``` - -### Samples - -You can run the included tests with: - -``` -python -m pytest examples/ -``` - -## Examples - -CUDA Samples rewriten using CUDA Python are found in `examples`. - -Custom extra included examples: - -- `examples/extra/jit_program_test.py`: Demonstrates the use of the API to compile and - launch a kernel on the device. Includes device memory allocation / - deallocation, transfers between host and device, creation and usage of - streams, and context management. -- `examples/extra/numba_emm_plugin.py`: Implements a Numba External Memory Management - plugin, showing that this CUDA Python Driver API can coexist with other - wrappers of the driver API. +* CUDA Driver +* CUDA Runtime +* NVRTC +* nvJitLink diff --git a/cuda_bindings/README.md b/cuda_bindings/README.md index a47346b2fe..85852068b2 100644 --- a/cuda_bindings/README.md +++ b/cuda_bindings/README.md @@ -1,6 +1,6 @@ -# CUDA-Python +# `cuda.bindings`: Low-level CUDA interfaces -CUDA Python is a standard set of low-level interfaces, providing full coverage of and access to the CUDA host APIs from Python. Checkout the [Overview](https://nvidia.github.io/cuda-python/overview.html) for the workflow and performance results. +CUDA Python is a standard set of low-level interfaces, providing full coverage of and access to the CUDA host APIs from Python. Checkout the [Overview](https://nvidia.github.io/cuda-python/cuda-bindings/latest/overview.html) for the workflow and performance results. ## Installing @@ -10,7 +10,7 @@ CUDA Python can be installed from: * Conda (nvidia channel) * Source builds -There're differences in each of these options that are described further in [Installation](https://nvidia.github.io/cuda-python/install.html) documentation. Each package will guarantee minor version compatibility. +Differences between these options are described in [Installation](https://nvidia.github.io/cuda-python/cuda-bindings/latest/install.html) documentation. Each package guarantees minor version compatibility. ## Runtime Dependencies @@ -33,53 +33,56 @@ Source builds work for multiple Python versions, however pre-build PyPI and Cond ## Testing -### Requirements +Latest dependencies can be found in [requirements.txt](https://github.com/NVIDIA/cuda-python/blob/main/cuda_bindings/requirements.txt). -Latest dependencies can be found in [requirements.txt](https://github.com/NVIDIA/cuda-python/blob/main/requirements.txt). +Multiple testing options are available: -### Unit-tests +* Cython Unit Tests +* Python Unit Tests +* Samples +* Benchmark -To run unit-tests against local builds: -``` -python -m pytest tests/ -``` -To run unit-tests against installed builds: -``` -pytest tests/ -``` +### Python Unit Tests -### Benchmark +Responsible for validating different binding usage patterns. Unit test `test_kernelParams.py` is particularly special since it demonstrates various approaches in setting up kernel launch parameters. -To run unit-tests against local builds: -``` -python -m pytest --benchmark-only benchmark/ -``` -To run unit-tests against installed builds: -``` -pytest --benchmark-only benchmark/ -``` +To run these tests: +* `python -m pytest tests/` against local builds +* `pytest tests/` against installed packages -### Samples +### Cython Unit Tests + +Cython tests are located in `tests/cython` and need to be built. Furthermore they need CUDA Toolkit headers matching the major-minor of CUDA Python. To build them: -To run unit-tests against local builds: -``` -python -m pytest benchmark/ -``` -To run unit-tests against installed builds: -``` -pytest benchmark/ -``` +1. Setup environment variable `CUDA_HOME` with the path to the CUDA Toolkit installation. +2. Run `build_tests` script located in `test/cython` appropriate to your platform. This will both cythonize the tests and build them. -## Examples +To run these tests: +* `python -m pytest tests/cython/` against local builds +* `pytest tests/cython/` against installed packages + +### Samples -CUDA Samples rewriten using CUDA Python are found in `examples`. +Various [CUDA Samples](https://github.com/NVIDIA/cuda-samples/tree/master) that were rewritten using CUDA Python are located in `examples`. -Custom extra included examples: +In addition, extra examples are included: -- `examples/extra/jit_program_test.py`: Demonstrates the use of the API to compile and +* `examples/extra/jit_program_test.py`: Demonstrates the use of the API to compile and launch a kernel on the device. Includes device memory allocation / deallocation, transfers between host and device, creation and usage of streams, and context management. -- `examples/extra/numba_emm_plugin.py`: Implements a Numba External Memory Management +* `examples/extra/numba_emm_plugin.py`: Implements a Numba External Memory Management plugin, showing that this CUDA Python Driver API can coexist with other wrappers of the driver API. + +To run these samples: +* `python -m pytest tests/cython/` against local builds +* `pytest tests/cython/` against installed packages + +### Benchmark (WIP) + +Benchmarks were used for performance analysis during initial release of CUDA Python. Today they need to be updated the 12.x toolkit and are work in progress. + +The intended way to run these benchmarks was: +* `python -m pytest --benchmark-only benchmark/` against local builds +* `pytest --benchmark-only benchmark/` against installed packages diff --git a/cuda_bindings/tests/cython/build_tests.bat b/cuda_bindings/tests/cython/build_tests.bat new file mode 100644 index 0000000000..258bd81343 --- /dev/null +++ b/cuda_bindings/tests/cython/build_tests.bat @@ -0,0 +1 @@ +cmd /V /C "set CL=%CL% /I%CUDA_HOME%\\include && cythonize -3 -i test_*.pyx" diff --git a/cuda_bindings/tests/cython/build_tests.sh b/cuda_bindings/tests/cython/build_tests.sh new file mode 100755 index 0000000000..d18a6aaa05 --- /dev/null +++ b/cuda_bindings/tests/cython/build_tests.sh @@ -0,0 +1,4 @@ +#!/bin/bash + +cd "$(dirname "$0")" +CPLUS_INCLUDE_PATH=$CUDA_HOME/include:$CPLUS_INCLUDE_PATH cythonize -3 -i test_*.pyx diff --git a/cuda_bindings/tests_cython/test_ccuda.pyx b/cuda_bindings/tests/cython/test_ccuda.pyx similarity index 98% rename from cuda_bindings/tests_cython/test_ccuda.pyx rename to cuda_bindings/tests/cython/test_ccuda.pyx index 0d90ba9098..a2ade6056f 100644 --- a/cuda_bindings/tests_cython/test_ccuda.pyx +++ b/cuda_bindings/tests/cython/test_ccuda.pyx @@ -5,6 +5,8 @@ # this software. Any use, reproduction, disclosure, or distribution of # this software and related documentation outside the terms of the EULA # is strictly prohibited. + +# distutils: language=c++ from libc.string cimport ( memset, memcmp diff --git a/cuda_bindings/tests_cython/test_ccudart.pyx b/cuda_bindings/tests/cython/test_ccudart.pyx similarity index 99% rename from cuda_bindings/tests_cython/test_ccudart.pyx rename to cuda_bindings/tests/cython/test_ccudart.pyx index b228661c8d..aaa2f5d7a1 100644 --- a/cuda_bindings/tests_cython/test_ccudart.pyx +++ b/cuda_bindings/tests/cython/test_ccudart.pyx @@ -5,6 +5,8 @@ # this software. Any use, reproduction, disclosure, or distribution of # this software and related documentation outside the terms of the EULA # is strictly prohibited. + +# distutils: language=c++ from libc.string cimport ( memset, memcmp diff --git a/cuda_bindings/tests_cython/test_cython.py b/cuda_bindings/tests/cython/test_cython.py similarity index 100% rename from cuda_bindings/tests_cython/test_cython.py rename to cuda_bindings/tests/cython/test_cython.py diff --git a/cuda_bindings/tests_cython/test_interoperability_cython.pyx b/cuda_bindings/tests/cython/test_interoperability_cython.pyx similarity index 99% rename from cuda_bindings/tests_cython/test_interoperability_cython.pyx rename to cuda_bindings/tests/cython/test_interoperability_cython.pyx index 5c58e8eae3..89e36a4c65 100644 --- a/cuda_bindings/tests_cython/test_interoperability_cython.pyx +++ b/cuda_bindings/tests/cython/test_interoperability_cython.pyx @@ -6,16 +6,17 @@ # this software and related documentation outside the terms of the EULA # is strictly prohibited. -# TODO: update to new module once the old ones are removed, we use the -# tests to cover backward compatibility. -import pytest +# distutils: language=c++ +from libc.stdlib cimport calloc, free import cuda.cuda as cuda import cuda.cudart as cudart import numpy as np +import pytest +# TODO: update to new module once the old ones are removed, we use the +# tests to cover backward compatibility. cimport cuda.ccuda as ccuda cimport cuda.ccudart as ccudart -from libc.stdlib cimport calloc, free def supportsMemoryPool(): diff --git a/cuda_bindings/tests/pytest.ini b/cuda_bindings/tests/pytest.ini new file mode 100644 index 0000000000..76f66832c6 --- /dev/null +++ b/cuda_bindings/tests/pytest.ini @@ -0,0 +1,2 @@ +[pytest] +norecursedirs = cython