Review and standardize all example code before cuda.core 1.0.0 release

[rparolin]

Motivation

Our example code is the first thing users reach for. The current examples were written at different times by different authors and have accumulated inconsistencies in structure, style, naming, and resource management. We need to review every example across both cuda.core and cuda.bindings to ensure they present a polished, consistent experience for 1.0.0.

Each sub-issue below is a self-contained work item — claim one by assigning yourself to it.

Scope

cuda.core examples (11 files in cuda_core/examples/):

• vector_add.py
• saxpy.py
• pytorch_example.py
• memory_ops.py
• show_device_properties.py
• jit_lto_fractal.py
• cuda_graphs.py
• simple_multi_gpu_example.py
• thread_block_cluster.py
• strided_memory_view_gpu.py
• strided_memory_view_cpu.py

cuda.bindings examples (13+ files in cuda_bindings/examples/):

• 0_Introduction/vectorAddDrv_test.py
• 0_Introduction/clock_nvrtc_test.py
• 0_Introduction/simpleCubemapTexture_test.py
• 0_Introduction/simpleP2P_test.py
• 0_Introduction/simpleZeroCopy_test.py
• 0_Introduction/systemWideAtomics_test.py
• 0_Introduction/vectorAddMMAP_test.py
• 2_Concepts_and_Techniques/streamOrderedAllocation_test.py
• 3_CUDA_Features/globalToShmemAsyncCopy_test.py
• 3_CUDA_Features/simpleCudaGraphs_test.py
• 4_CUDA_Libraries/conjugateGradientMultiBlockCG_test.py
• extra/jit_program_test.py
• extra/numba_emm_plugin.py
• common/common.py (shared utility)

Known inconsistencies to evaluate

The following cross-cutting concerns have been identified. Each should be discussed by the team and resolved consistently across all examples.

1. File headers and copyright years

• Copyright years are split: 7 files use 2024-2025, 4 files use 2025 only.
• The team should decide on one approach (e.g., always 2024-2025, or year-of-creation to present).

2. Description block style

• Some files use a single-line description: "This demo illustrates how to..."
• Others use numbered bullet-point lists describing multiple concepts.
• Some include usage instructions (## Usage: with pip/python commands), others don't.

3. Import ordering

• At least 5 different import ordering patterns exist across the 11 cuda.core examples alone.
• Variations: some start with sys, some have no stdlib imports, some use try/except for optional deps inline.
• No consistent grouping (stdlib → third-party → cuda).

4. if __name__ == "__main__" guard

• Only 4 of 11 cuda.core examples use a __main__ guard (show_device_properties.py, jit_lto_fractal.py, strided_memory_view_gpu.py, strided_memory_view_cpu.py).
• The other 7 run all code at module level.

5. Resource cleanup

• Most examples do NOT close streams or buffers explicitly.
• Only saxpy.py and memory_ops.py demonstrate explicit close() calls.
• strided_memory_view_gpu.py uses a finally block for cleanup, others don't.
• No examples use context managers for resource management.

6. Naming conventions

• Stream variables: s vs stream vs stream0/stream1.
• Kernel variables: ker vs add_kernel vs gpu_ker.
• Device variables: dev vs dev0/dev1 vs inline Device().
• Config objects are mostly config, but multi-config uses config0/config1.

7. Error handling and early-exit patterns

• Some files use sys.exit(0) for unsupported configurations; others silently skip.
• NumPy version checking uses two different APIs (np.__version__ < "2.1.0" vs np.lib.NumpyVersion()).
• Validation is a mix of assert statements and print + sys.exit.

8. Output and success messages

• Completion messages vary: "done!", "done" (no exclamation), "Example completed successfully!", "All tests passed successfully!", "Memory management example completed!", or no message at all.
• Some examples print intermediate progress, others are silent until the end.
• Some use sys.stderr for warnings/info, others use stdout.

9. External dependencies

• CuPy is required by 7 of 11 cuda.core files — is this the right default, or should more examples be dependency-light?
• Only show_device_properties.py has zero external dependencies.
• Optional dependency handling (try/except) is inconsistent.

10. Documentation coverage

• Neither cuda_core/examples/ nor cuda_bindings/examples/ has a README.
• Some examples are referenced in docs (getting-started.rst), others are not.
• Consider whether each example should be linked from the documentation.

Sub-issues

Each sub-issue below is a self-contained work item that can be claimed and driven independently. Assign yourself to a sub-issue to own it. Each sub-issue should result in one or more PRs that update all affected example files across both packages.

• Examples: Standardize file structure conventions #1674 — Standardize file structure conventions
• Examples: Standardize naming conventions #1675 — Standardize naming conventions
• Examples: Standardize resource cleanup #1676 — Standardize resource cleanup
• Examples: Standardize imports and dependency policy #1677 — Standardize imports and dependency policy
• Examples: Standardize error handling and output #1678 — Standardize error handling and output
• Examples: Standardize file headers and copyright years #1679 — Standardize file headers and copyright years
• Examples: Audit example coverage in documentation #1680 — Audit example coverage in documentation

How to contribute

1. Claim a sub-issue: Assign yourself to one of the sub-issues above.
2. Propose a convention: Comment on your sub-issue with a proposed standard for team review.
3. Apply across all files: Once the convention is agreed upon, update all affected examples in both cuda_core/examples/ and cuda_bindings/examples/.
4. Submit a PR referencing this issue and the sub-issue number.
5. Check off the file-level boxes in the Scope section above as files are updated.