[srimanachanta]

Summary

Add cuda.core.CUDAOutOfMemoryError(CUDAError, MemoryError). CUDA_ERROR_OUT_OF_MEMORY and cudaErrorMemoryAllocation now raise it instead of a plain CUDAError.

Motivation

Allocating too much from a DeviceMemoryResource raises CUDAError, which derives only from Exception:

>>> mr.allocate(1 << 46, stream=dev.default_stream)
CUDAError: CUDA_ERROR_OUT_OF_MEMORY: ...
>>> type(e).__mro__
(CUDAError, Exception, BaseException, object)

Other libraries raise a MemoryError subclass: CuPy's OutOfMemoryError, PyTorch's torch.cuda.OutOfMemoryError, and NumPy's MemoryError. Code that recovers from running out of memory by asking for less catches MemoryError. A downstream CUDA extension library defines its own CudaOutOfMemory for this reason (common.hpp, registered as a MemoryError in bindings.cpp), and its sweep halves the chunk on except MemoryError (simulation.py). That retry does not see out-of-memory errors from cuda.core.

Change

• _check_driver_error and _check_runtime_error pick CUDAOutOfMemoryError for the two out-of-memory codes. Every driver and runtime failure in cuda.core, including the C++ handle layer through HANDLE_RETURN(get_last_error()), goes through these two functions.
• Message, explanation and notes are unchanged. Code that catches CUDAError is unaffected.
• Exported from cuda.core, added to api.rst, the error handling page and the 1.3.0 release notes.

NVRTC's NVRTC_ERROR_OUT_OF_MEMORY still raises NVRTCError. I left it out to keep the change to driver and runtime errors.

Tests

• Driver and runtime OOM codes raise CUDAOutOfMemoryError, which is both a CUDAError and a MemoryError.
• No other driver or runtime code raises a MemoryError.
• End to end: a 64 TiB request from a DeviceMemoryResource raises MemoryError, and the pool stays usable.
• test_cuda_utils.py, test_error_handling.py, test_api_docs_consistency.py and test_memory.py pass locally (RTX 5070 Ti, driver 615, CUDA 13.4).

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[coderabbitai]

📝 Summary

Summary by CodeRabbit

• New Features
  • CUDA out-of-memory failures now raise CUDAOutOfMemoryError, which can be caught as either a CUDAError or a standard MemoryError.
  • The new exception is available from the top-level cuda.core namespace. Other CUDA errors continue to raise CUDAError.
• Documentation
  • Updated the error-handling guide, API reference, and release notes with details about the new exception.

The change adds and exports CUDAOutOfMemoryError. Driver and runtime out-of-memory errors now raise this class, which inherits from CUDAError and MemoryError. Tests and documentation cover the new exception.

Changes: CUDA out-of-memory exception

Layer / File(s)	Summary
Exception classification and public API cuda_core/cuda/core/_utils/cuda_utils.pyi, cuda_core/cuda/core/_utils/cuda_utils.pyx, cuda_core/cuda/core/__init__.py, cuda_core/tests/test_cuda_utils.py, cuda_core/tests/test_memory.py, cuda_core/docs/source/api.rst, cuda_core/docs/source/error_handling.rst, cuda_core/docs/source/release/1.3.0-notes.rst	Adds and exports CUDAOutOfMemoryError, maps driver and runtime out-of-memory codes to it, and tests its inheritance, error messages, and memory allocation behavior. The documentation describes the exception and its error conditions.

Suggested labels: cuda.core, feature

Suggested reviewers: andy-jost

Priority: Normal

Change: Feature

Merge Risk: Low · up to b7b0f

Readers may try an invalid import. Narrow the documentation claim; this does not otherwise block merging.

Finishing Touches: 💡 1

🛠️ Fix failing CI checks: 💡

• Commit to this branch
• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

---

Review info

Run configuration

• Source mode: Auto
• Repository: NVIDIA/cuda-python
• Branch: main
• File: .coderabbit.yaml
• Commit: 590a8bf
• Layers: Repository YAML
• Review profile: CHILL
• Plan: Enterprise
• Run ID: deb66916-c5af-44de-827c-e6ebbf1830a5

Commits

Reviewing files that changed from the base of the PR and between 590a8bf and b7b0f23.

Files selected for processing: 8

• cuda_core/cuda/core/__init__.py
• cuda_core/cuda/core/_utils/cuda_utils.pyi
• cuda_core/cuda/core/_utils/cuda_utils.pyx
• cuda_core/docs/source/api.rst
• cuda_core/docs/source/error_handling.rst
• cuda_core/docs/source/release/1.3.0-notes.rst
• cuda_core/tests/test_cuda_utils.py
• cuda_core/tests/test_memory.py

Included review availability: This review used your included allowance. Your plan provides up to 12 included reviews per hour; 8 remain after this review.

[coderabbitai]

Minor · Functional Correctness · Quick win

suggestion: Limit the importability claim to these exception classes. The sentence says all cuda.core classes are available at the top level. Classes such as Graph instead live in cuda.core.graph, so a reader following this claim can use an invalid import. Replace “All cuda.core classes” with “These exception classes.” (raw.githubusercontent.com)