CUDA 13.2 samples update (#432)

- Added Python samples for CUDA Python 1.0 release - Renamed top-level `Samples` directory to `cpp` to accommodate Python samples.
2026-10-13 00:08:26 +08:00 · 2026-05-13 15:13:18 -07:00
parent a4526d5229
commit aeab82ff30
2072 changed files with 15077 additions and 1970 deletions
--- a/python/2_CoreConcepts/parallelHistogram/README.md
+++ b/python/2_CoreConcepts/parallelHistogram/README.md
@@ -0,0 +1,117 @@
+# Sample: Parallel Histogram with Atomics (Python)
+
+## Description
+
+Compute histograms on the GPU using atomic operations to handle concurrent updates from multiple threads. This sample demonstrates the modern **cuda.core API** for kernel compilation and launch, comparing two approaches:
+
+1. **Global Atomics** - All threads atomically update a single global histogram
+2. **Privatized Histograms** - Each block uses shared memory, then merges to global
+
+## What You'll Learn
+
+- Compiling CUDA C kernels with `cuda.core.Program`
+- Configuring kernel launches with `cuda.core.LaunchConfig`
+- Launching kernels with `cuda.core.launch()`
+- Using **atomic operations** (`atomicAdd`) for thread-safe updates
+- Optimizing with **shared memory privatization**
+- GPU timing with `cuda.core` Events
+
+## Key Concepts
+
+### Atomic Operations
+
+When multiple threads update the same histogram bin, a race condition occurs. Atomic operations ensure thread-safe updates:
+
+```cuda
+atomicAdd(&histogram[data[i]], 1);  // Thread-safe increment
+```
+
+### Global vs Privatized Atomics
+
+| Approach | Pros | Cons |
+|----------|------|------|
+| Global | Simple | High contention on popular bins |
+| Privatized | Significantly faster | Extra shared memory, synchronization |
+
+## Key APIs
+
+### From `cuda.core`:
+
+- `Device` - Device management and context
+- `Program` - Compile CUDA C source code
+- `ProgramOptions` - Set architecture, optimization flags
+- `LaunchConfig` - Configure grid and block dimensions
+- `launch()` - Launch compiled kernel
+- `Stream` - Async stream management
+- `EventOptions` - Configure events for GPU timing
+- `stream.record()` - Record events for timing
+
+### From `cupy`:
+
+- `cp.random.randint()` - Generate random data directly on GPU
+- `cp.zeros()` - Allocate zeroed GPU arrays
+
+### CUDA Atomic Functions (in kernel):
+
+- `atomicAdd()` - Thread-safe addition
+
+## Requirements
+
+### Hardware:
+- NVIDIA GPU with CUDA support
+
+### Software:
+- CUDA Toolkit 13.0 or newer
+- Python 3.10 or newer
+- See `requirements.txt` for Python packages
+
+## Installation
+
+```bash
+pip install -r requirements.txt
+```
+
+## How to Run
+
+```bash
+python parallelHistogram.py
+```
+
+## Expected Output
+
+```
+============================================================
+Parallel Histogram with Atomics (cuda.core)
+============================================================
+
+Device: <Your GPU>
+Compute Capability: ComputeCapability(major=X, minor=Y)
+
+Compiling CUDA kernels with cuda.core.Program...
+  Compiled for architecture: sm_XY
+
+Generating 10,000,000 random values on GPU...
+
+Verifying correctness...
+  Global atomics:     PASSED
+  Privatized atomics: PASSED
+
+Benchmarking (100 iterations)...
+  Global atomics:     X.XXX ms
+  Privatized atomics: X.XXX ms
+  Speedup:            XXx
+
+Test PASSED
+```
+
+## Files
+
+- `parallelHistogram.py` - Main sample using cuda.core
+- `README.md` - This file
+- `requirements.txt` - Dependencies
+
+## See Also
+
+- [cuda.core Documentation](https://nvidia.github.io/cuda-python/cuda-core/latest/)
+- [CUDA Atomic Functions](https://docs.nvidia.com/cuda/cuda-c-programming-guide/index.html#atomic-functions)
+- [CUDA Shared Memory](https://docs.nvidia.com/cuda/cuda-c-programming-guide/index.html#shared-memory)
--- a/python/2_CoreConcepts/parallelHistogram/parallelHistogram.py
+++ b/python/2_CoreConcepts/parallelHistogram/parallelHistogram.py
@@ -0,0 +1,237 @@
+# Copyright (c) 2025, NVIDIA CORPORATION. All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions
+# are met:
+#  * Redistributions of source code must retain the above copyright
+#    notice, this list of conditions and the following disclaimer.
+#  * Redistributions in binary form must reproduce the above copyright
+#    notice, this list of conditions and the following disclaimer in the
+#    documentation and/or other materials provided with the distribution.
+#  * Neither the name of NVIDIA CORPORATION nor the names of its
+#    contributors may be used to endorse or promote products derived
+#    from this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS ``AS IS'' AND ANY
+# EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+# PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR
+# CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+# EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+# PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+# PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
+# OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+"""
+Parallel Histogram with Atomics using cuda.core
+
+This sample demonstrates GPU histogram computation using atomic operations,
+showcasing the modern cuda.core API for:
+- Kernel compilation (Program, ProgramOptions)
+- Kernel launch configuration (LaunchConfig)
+- Stream management (Stream)
+- Event timing (EventOptions)
+
+Two histogram approaches are compared:
+1. Global Atomics - All threads atomically update global memory
+2. Privatized Histograms - Shared memory reduces global atomic contention
+"""
+
+import sys
+
+try:
+    import cupy as cp
+    import numpy as np
+    from cuda.core import (
+        Device,
+        EventOptions,
+        LaunchConfig,
+        Program,
+        ProgramOptions,
+        launch,
+    )
+except ImportError as e:
+    print(f"Error: Required package not found: {e}")
+    print("Please install: pip install -r requirements.txt")
+    sys.exit(1)
+
+
+NUM_BINS = 256
+
+# CUDA C source code for both histogram kernels
+HISTOGRAM_KERNELS = r"""
+// Global Atomics - simple but high contention on popular bins
+extern "C" __global__
+void histogram_global(const unsigned char* data, unsigned int* histogram, int n) {
+    int idx = blockIdx.x * blockDim.x + threadIdx.x;
+    int stride = blockDim.x * gridDim.x;
+
+    for (int i = idx; i < n; i += stride) {
+        atomicAdd(&histogram[data[i]], 1);
+    }
+}
+
+// Privatized - uses shared memory to reduce global atomic contention
+extern "C" __global__
+void histogram_privatized(const unsigned char* data, unsigned int* histogram, int n) {
+    __shared__ unsigned int local_hist[256];
+
+    int tid = threadIdx.x;
+    int idx = blockIdx.x * blockDim.x + threadIdx.x;
+    int stride = blockDim.x * gridDim.x;
+
+    // Initialize shared memory
+    for (int i = tid; i < 256; i += blockDim.x)
+        local_hist[i] = 0;
+    __syncthreads();
+
+    // Accumulate into shared memory (fast)
+    for (int i = idx; i < n; i += stride)
+        atomicAdd(&local_hist[data[i]], 1);
+    __syncthreads();
+
+    // Merge to global (fewer atomics)
+    for (int i = tid; i < 256; i += blockDim.x)
+        if (local_hist[i] > 0)
+            atomicAdd(&histogram[i], local_hist[i]);
+}
+"""
+
+
+def main():
+    print("=" * 60)
+    print("Parallel Histogram with Atomics (cuda.core)")
+    print("=" * 60)
+
+    # Initialize device using cuda.core
+    device = Device(0)
+    device.set_current()
+    print(f"\nDevice: {device.name}")
+    print(f"Compute Capability: {device.compute_capability}")
+
+    # Create stream using cuda.core
+    stream = device.create_stream()
+
+    # Make CuPy use the same stream for correct ordering (avoids null-stream sync)
+    cp.cuda.Stream.from_external(stream).use()
+
+    try:
+        _run_histogram(device, stream)
+    finally:
+        cp.cuda.Stream.null.use()  # Restore CuPy to default stream before closing
+        stream.close()
+
+
+def _run_histogram(device, stream):
+    """Run histogram computation and benchmarking."""
+    # Compile CUDA kernels using cuda.core.Program
+    print("\nCompiling CUDA kernels with cuda.core.Program...")
+    arch = f"sm_{device.arch}"
+    options = ProgramOptions(arch=arch)
+    program = Program(HISTOGRAM_KERNELS, code_type="c++", options=options)
+    object_code = program.compile("cubin")
+
+    kernel_global = object_code.get_kernel("histogram_global")
+    kernel_privatized = object_code.get_kernel("histogram_privatized")
+    print(f"  Compiled for architecture: {arch}")
+
+    # Generate test data directly on GPU (more efficient than CPU->GPU copy)
+    n = 10_000_000
+    print(f"\nGenerating {n:,} random values on GPU...")
+    data_gpu = cp.random.randint(0, 256, size=n, dtype=cp.uint8)
+    hist_gpu = cp.zeros(NUM_BINS, dtype=cp.uint32)
+
+    # Compute reference histogram on CPU for verification
+    data_cpu = cp.asnumpy(data_gpu)
+    hist_cpu, _ = np.histogram(data_cpu, bins=NUM_BINS, range=(0, 256))
+    hist_cpu = hist_cpu.astype(np.uint32)
+
+    # Configure kernel launch using cuda.core.LaunchConfig
+    block_size = 256
+    grid_size = min((n + block_size - 1) // block_size, 1024)
+    config = LaunchConfig(grid=(grid_size,), block=(block_size,))
+
+    print("\nVerifying correctness...")
+
+    # Ensure CuPy allocations complete before kernel launch on our stream
+    stream.sync()
+
+    # Launch global atomics kernel (hist_gpu is already zeros from cp.zeros)
+    launch(
+        stream, config, kernel_global, data_gpu.data.ptr, hist_gpu.data.ptr, np.int32(n)
+    )
+    stream.sync()
+
+    hist_global = cp.asnumpy(hist_gpu)
+    global_ok = np.array_equal(hist_cpu, hist_global)
+    print(f"  Global atomics:     {'PASSED' if global_ok else 'FAILED'}")
+
+    # Reset histogram and launch privatized kernel (fill on same stream)
+    hist_gpu.fill(0)
+    launch(
+        stream,
+        config,
+        kernel_privatized,
+        data_gpu.data.ptr,
+        hist_gpu.data.ptr,
+        np.int32(n),
+    )
+    stream.sync()
+
+    hist_privatized = cp.asnumpy(hist_gpu)
+    privatized_ok = np.array_equal(hist_cpu, hist_privatized)
+    print(f"  Privatized atomics: {'PASSED' if privatized_ok else 'FAILED'}")
+
+    if not (global_ok and privatized_ok):
+        sys.exit(1)
+
+    # Benchmark using cuda.core Events (explicit Event objects recorded on stream)
+    print("\nBenchmarking (100 iterations)...")
+    num_iterations = 100
+    event_opts = EventOptions(enable_timing=True)
+    start_event = device.create_event(options=event_opts)
+    end_event = device.create_event(options=event_opts)
+
+    # Benchmark global atomics
+    stream.record(start_event)
+    for _ in range(num_iterations):
+        hist_gpu.fill(0)
+        launch(
+            stream,
+            config,
+            kernel_global,
+            data_gpu.data.ptr,
+            hist_gpu.data.ptr,
+            np.int32(n),
+        )
+    stream.record(end_event)
+    end_event.sync()
+    time_global = (end_event - start_event) / num_iterations
+
+    # Benchmark privatized
+    stream.record(start_event)
+    for _ in range(num_iterations):
+        hist_gpu.fill(0)
+        launch(
+            stream,
+            config,
+            kernel_privatized,
+            data_gpu.data.ptr,
+            hist_gpu.data.ptr,
+            np.int32(n),
+        )
+    stream.record(end_event)
+    end_event.sync()
+    time_privatized = (end_event - start_event) / num_iterations
+
+    print(f"  Global atomics:     {time_global:.3f} ms")
+    print(f"  Privatized atomics: {time_privatized:.3f} ms")
+    print(f"  Speedup:            {time_global / time_privatized:.1f}x")
+
+    print("\nTest PASSED")
+
+
+if __name__ == "__main__":
+    main()
--- a/python/2_CoreConcepts/parallelHistogram/requirements.txt
+++ b/python/2_CoreConcepts/parallelHistogram/requirements.txt
@@ -0,0 +1,7 @@
+# Parallel Histogram with Atomics Sample Requirements
+# Requires Python 3.10+, CUDA Toolkit 13.0+
+
+cuda-python>=13.0.0
+cuda-core>=0.6.0
+numpy>=2.3.2
+cupy-cuda13x>=13.0.0