[v0.2.4] Graceful Error Handling for Missing GPU Components

[m96-chan]

Parent Issue

Part of #49 (Eliminate CUDA Toolkit dependency)

Goal

Provide clear, actionable error messages when GPU components are missing, guiding users to install the correct drivers (NOT the CUDA Toolkit).

Tasks

Error Detection

• Detect missing NVIDIA GPU driver (nvcuda.dll / libcuda.so)
• Detect missing or incompatible NVRTC
• Detect GPU driver version too old for required features
• Detect no NVIDIA GPU present

Error Messages

• Create user-friendly error messages (not stack traces)
• Include specific action items for each error type
• Provide links to driver download pages
• Never mention "CUDA Toolkit" in user-facing errors

CPU Fallback

• Gracefully fall back to CPU mode when GPU unavailable
• Log warning (not error) when falling back
• Ensure all APIs work in CPU mode (NumPy backend)

Error Message Examples

No GPU Driver

PyGPUkit Error: NVIDIA GPU driver not found.

To use GPU features, install the NVIDIA GPU driver:
  - Windows: https://www.nvidia.com/Download/index.aspx
  - Linux: apt install nvidia-driver-535 (or your distro's package)

PyGPUkit will run in CPU-only mode.

Driver Too Old

PyGPUkit Error: NVIDIA driver version 470.xx is too old.

PyGPUkit requires driver version 520.xx or newer.
Please update your GPU driver:
  - Windows: https://www.nvidia.com/Download/index.aspx
  - Linux: apt install nvidia-driver-535

No NVIDIA GPU

PyGPUkit: No NVIDIA GPU detected.

PyGPUkit will run in CPU-only mode using NumPy.
For GPU acceleration, an NVIDIA GPU is required.

Files to Modify

• src/pygpukit/__init__.py - initialization error handling
• src/pygpukit/core/device.py - device detection errors
• native/core/device.cpp - C++ error detection
• native/jit/compiler.cpp - NVRTC error handling

Acceptance Criteria

• All error messages are user-friendly (no raw exceptions)
• Error messages never mention "CUDA Toolkit"
• Each error includes actionable next steps
• CPU fallback works silently when GPU unavailable
• Unit tests for each error condition

Labels

enhancement v0.2.4 user-experience

[m96-chan]

Completed in PR #57

All tasks have been implemented:

Error Detection ✅

• Detect missing NVIDIA GPU driver (nvcuda.dll / libcuda.so)
• Detect missing or incompatible NVRTC
• Detect GPU driver version too old for required features
• Detect no NVIDIA GPU present

Error Messages ✅

• Create user-friendly error messages (not stack traces)
• Include specific action items for each error type
• Provide links to driver download pages
• Never mention "CUDA Toolkit" in user-facing errors

CPU Fallback ✅

• Gracefully fall back to CPU mode when GPU unavailable
• Log warning (not error) when falling back
• Ensure all APIs work in CPU mode (NumPy backend)

Example Error Messages

NVRTC not available:

NVRTC (NVIDIA Runtime Compiler) is not available.
JIT compilation of custom kernels requires NVRTC.

Pre-compiled GPU operations (matmul, add, mul) work without NVRTC.
To use custom JIT kernels, NVRTC can be obtained from:
  https://developer.nvidia.com/cuda-downloads

Check availability: pygpukit.is_nvrtc_available()

Key principle: Users only need GPU drivers for pre-compiled ops. NVRTC is optional for JIT.