Deprecate and provide alternatives for things in cuda.core.system (NVIDIA#1374)

* Deprecate and provide alternatives for things in `cuda.core.system`

In preparation for the new `cuda.core.system` package.

* Add release notes

* Remove AssertionError

Author: mdboom

cuda_core/cuda/core/experimental/_device.pyx

@@ -1024,6 +1024,20 @@ class Device:
                     raise CUDAError("Internal error (current device is not equal to Device.device_id)")
         return driver.CUcontext(<uintptr_t>ctx)
 
+    @classmethod
+    def get_all_devices(cls):
+        """
+        Query the available device instances.
+
+        Returns
+        -------
+        tuple of Device
+            A tuple containing instances of available devices.
+        """
+        from cuda.core.experimental import system
+        total = system.get_num_devices()
+        return tuple(cls(device_id) for device_id in range(total))
+
     @property
     def device_id(self) -> int:
         """Return device ordinal."""

cuda_core/cuda/core/experimental/_system.py

@@ -2,6 +2,8 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
+import warnings
+
 from cuda.core.experimental._device import Device
 from cuda.core.experimental._utils.cuda_utils import driver, handle_return, runtime
 
@@ -23,8 +25,7 @@ def __init__(self):
             return
         self._initialized = True
 
-    @property
-    def driver_version(self) -> tuple[int, int]:
+    def get_driver_version(self) -> tuple[int, int]:
         """
         Query the CUDA driver version.
 
@@ -39,7 +40,27 @@ def driver_version(self) -> tuple[int, int]:
         return (major, minor)
 
     @property
-    def num_devices(self) -> int:
+    def driver_version(self) -> tuple[int, int]:
+        """
+        Query the CUDA driver version.
+
+        Returns
+        -------
+        tuple of int
+            A 2-tuple of (major, minor) version numbers.
+
+        .. deprecated:: 0.5.0
+          `cuda.core.system.driver_version` will be removed in 0.6.0.
+          Use `cuda.core.system.get_driver_version()` instead.
+        """
+        warnings.warn(
+            "cuda.core.system.driver_version is deprecated. Use cuda.core.system.get_driver_version() instead.",
+            DeprecationWarning,
+            stacklevel=1,
+        )
+        return self.get_driver_version()
+
+    def get_num_devices(self) -> int:
         """
         Query the number of available GPUs.
 
@@ -50,6 +71,27 @@ def num_devices(self) -> int:
         """
         return handle_return(runtime.cudaGetDeviceCount())
 
+    @property
+    def num_devices(self) -> int:
+        """
+        Query the number of available GPUs.
+
+        Returns
+        -------
+        int
+            The number of available GPU devices.
+
+        .. deprecated:: 0.5.0
+          `cuda.core.system.num_devices` will be removed in 0.6.0.
+          Use `cuda.core.system.get_num_devices()` instead.
+        """
+        warnings.warn(
+            "cuda.core.system.num_devices is deprecated. Use cuda.core.system.get_num_devices() instead.",
+            DeprecationWarning,
+            stacklevel=1,
+        )
+        return self.get_num_devices()
+
     @property
     def devices(self) -> tuple:
         """
@@ -59,6 +101,14 @@ def devices(self) -> tuple:
         -------
         tuple of Device
             A tuple containing instances of available devices.
+
+        .. deprecated:: 0.5.0
+          `cuda.core.system.devices` will be removed in 0.6.0.
+          Use `cuda.core.Device.get_all_devices()` instead.
         """
-        total = self.num_devices
-        return tuple(Device(device_id) for device_id in range(total))
+        warnings.warn(
+            "cuda.core.system.devices is deprecated. Use cuda.core.Device.get_all_devices() instead.",
+            DeprecationWarning,
+            stacklevel=1,
+        )
+        return Device.get_all_devices()

cuda_core/docs/source/api.rst

@@ -60,9 +60,8 @@ CUDA compilation toolchain
 CUDA system information
 -----------------------
 
-.. autoproperty:: cuda.core.experimental._system.System.driver_version
-.. autoproperty:: cuda.core.experimental._system.System.num_devices
-.. autoproperty:: cuda.core.experimental._system.System.devices
+.. automethod:: cuda.core.experimental._system.System.get_driver_version
+.. automethod:: cuda.core.experimental._system.System.get_num_devices
 
 
 .. module:: cuda.core.experimental.utils

cuda_core/docs/source/release/0.5.x-notes.rst

@@ -16,7 +16,14 @@ None.
 Breaking Changes
 ----------------
 
-None.
+The following APIs have been deprecated and will be removed in 0.6.0:
+
+- ``cuda.core.experimental.system.driver_version`` has been replaced with
+  ``cuda.core.experimental.system.get_driver_version()``.
+- ``cuda.core.experimental.system.num_devices`` has been replaced with
+  ``cuda.core.experimental.system.get_num_devices()``.
+- ``cuda.core.experimental.system.devices`` has been replaced with
+  ``cuda.core.experimental.Device.get_all_devices()``.
 
 New features
 ------------

cuda_core/examples/show_device_properties.py

@@ -215,7 +215,7 @@ def print_device_properties(properties):
 
 # Print info about all CUDA devices in the system
 def show_device_properties():
-    ndev = system.num_devices
+    ndev = system.get_num_devices()
     print(f"Number of GPUs: {ndev}")
 
     for device_id in range(ndev):

cuda_core/examples/simple_multi_gpu_example.py

@@ -14,7 +14,7 @@
 import cupy as cp
 from cuda.core.experimental import Device, LaunchConfig, Program, launch, system
 
-if system.num_devices < 2:
+if system.get_num_devices() < 2:
     print("this example requires at least 2 GPUs", file=sys.stderr)
     sys.exit(0)
 

cuda_core/tests/conftest.py

@@ -124,7 +124,7 @@ def mempool_device():
 
 
 def _mempool_device_impl(num):
-    num_devices = len(cuda.core.experimental.system.devices)
+    num_devices = len(cuda.core.experimental.Device.get_all_devices())
     if num_devices < num:
         pytest.skip(f"Test requires at least {num} GPUs")
 

cuda_core/tests/test_device.py

@@ -48,7 +48,7 @@ def test_device_alloc(deinit_cuda):
 
 
 def test_device_id(deinit_cuda):
-    for device in cuda.core.experimental.system.devices:
+    for device in Device.get_all_devices():
         device.set_current()
         assert device.device_id == handle_return(runtime.cudaGetDevice())
 

cuda_core/tests/test_memory_peer_access.py

@@ -72,7 +72,7 @@ def check(expected):
     with pytest.raises(ValueError, match=r"device_id must be \>\= 0"):
         dmr.peer_accessible_by = [-1]  # device ID out of bounds
 
-    num_devices = len(cuda.core.experimental.system.devices)
+    num_devices = len(cuda.core.experimental.Device.get_all_devices())
 
     with pytest.raises(ValueError, match=r"device_id must be within \[0, \d+\)"):
         dmr.peer_accessible_by = [num_devices]  # device ID out of bounds

cuda_core/tests/test_module.py

@@ -7,7 +7,7 @@
 
 import cuda.core.experimental
 import pytest
-from cuda.core.experimental import Device, ObjectCode, Program, ProgramOptions, system
+from cuda.core.experimental import Device, ObjectCode, Program, ProgramOptions
 from cuda.core.experimental._utils.cuda_utils import CUDAError, driver, get_binding_version, handle_return
 
 try:
@@ -135,7 +135,7 @@ def test_read_only_kernel_attributes(get_saxpy_kernel_cubin, attr, expected_type
     assert value is not None
 
     # get the value for each device on the system, using either the device object or ordinal
-    for device in system.devices:
+    for device in Device.get_all_devices():
         value = method(device)
         value = method(device.device_id)
     assert isinstance(value, expected_type), f"Expected {attr} to be of type {expected_type}, but got {type(value)}"