Skip to content

AGENTS.md

Latest commit

 

History

History
62 lines (50 loc) · 2.44 KB

AGENTS.md

File metadata and controls

62 lines (50 loc) · 2.44 KB

This file describes cuda_core, the high-level Pythonic CUDA subpackage in the cuda-python monorepo.

Scope and principles

  • Role: provide higher-level CUDA abstractions (Device, Stream, Program, Linker, memory resources, graphs) on top of cuda.bindings.
  • API intent: keep interfaces Pythonic while preserving explicit CUDA behavior and error visibility.
  • Compatibility: changes should remain compatible with supported cuda.bindings major versions (12.x and 13.x).

Package architecture

  • Main package: cuda/core/ contains most Cython modules (*.pyx, *.pxd) implementing runtime behaviors and public objects.
  • Subsystems:
    • memory/resource stack: cuda/core/_memory/
    • system-level APIs: cuda/core/system/
    • compile/link path: _program.pyx, _linker.pyx, _module.pyx
    • execution path: _launcher.pyx, _launch_config.pyx, _stream.pyx
  • C++ helpers: module-specific C++ implementations live under cuda/core/_cpp/.
  • Build backend: build_hooks.py handles Cython extension setup and build dependency wiring.

Build and version coupling

  • build_hooks.py determines CUDA major version from CUDA_CORE_BUILD_MAJOR or CUDA headers (CUDA_HOME/CUDA_PATH) and uses it for build decisions.
  • Source builds require CUDA headers available through CUDA_HOME or CUDA_PATH.
  • cuda_core expects cuda.bindings to be present and version-compatible.

Testing expectations

  • Primary tests: pytest tests/
  • Examples: validate affected examples in examples/ when changing user workflows or public APIs.
  • Orchestrated run: from repo root, scripts/run_tests.sh core.

Runtime/build environment notes

  • Runtime env vars commonly relevant:
    • CUDA_PYTHON_CUDA_PER_THREAD_DEFAULT_STREAM
    • CUDA_PYTHON_DISABLE_MAJOR_VERSION_WARNING
  • Build env vars commonly relevant:
    • CUDA_HOME / CUDA_PATH
    • CUDA_CORE_BUILD_MAJOR
    • CUDA_PYTHON_PARALLEL_LEVEL
    • CUDA_PYTHON_COVERAGE

Editing guidance

  • Keep user-facing behaviors coherent with docs and examples, especially around stream semantics, memory ownership, and compile/link flows.
  • Reuse existing shared utilities in cuda/core/_utils/ before adding new helpers.
  • When changing Cython signatures or cimports, verify related .pxd and call-site consistency.
  • Prefer explicit error propagation over silent fallback paths.
  • If you change public behavior, update tests and docs under docs/source/.