Merge pull request #252 from vzhurba01/cython_test_instructions

Update out-of-date (sub)package REAME files and overhaul bindings Cython test instructions

Author: vzhurba01

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

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

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"

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

cuda_bindings/tests_cython/test_ccuda.pyx renamed to 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

cuda_bindings/tests_cython/test_ccudart.pyx renamed to 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

cuda_bindings/tests_cython/test_cython.py renamed to cuda_bindings/tests/cython/test_cython.py

@@ -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():

cuda_bindings/tests_cython/test_interoperability_cython.pyx renamed to cuda_bindings/tests/cython/test_interoperability_cython.pyx

@@ -0,0 +1,2 @@
+[pytest]
+norecursedirs = cython