Initial import of cuda.core.system (#1393)

* First pass at cuda.core.system

* Fix fallback to non-working NVML

* Precommit fixes

* Move exceptions related to NVML to their own module.

* Update version check

* Add verbose logging for doc build

* Try to get doc failure info

* Try to get more info

* No implicit init, and fix docs build

* Use cimport where possible

* Move some tests

* Improve docs

* Fix cyclical imports

* Remove more cimports

* Fix exposure of unpack_bitmask

* Fix tests that use cuda.core.system

* Move system.utils to device_utils.pxi

* Document the diff between cuda.core.Device and cuda.core.system.Device

* Redo the "get_version" APIs

* Address comments in PR

* Fix typo

* Fix array conversion

* Remove 'experimental' from the docstring

* Windows fix

* Remove initialize from docs

Author: mdboom

cuda_core/cuda/core/__init__.py

@@ -28,7 +28,7 @@
 finally:
     del bindings, importlib, subdir, cuda_major, cuda_minor
 
-from cuda.core import utils  # noqa: E402
+from cuda.core import system, utils  # noqa: E402
 from cuda.core._device import Device  # noqa: E402
 from cuda.core._event import Event, EventOptions  # noqa: E402
 from cuda.core._graph import (  # noqa: E402
@@ -62,8 +62,3 @@
 from cuda.core._module import Kernel, ObjectCode  # noqa: E402
 from cuda.core._program import Program, ProgramOptions  # noqa: E402
 from cuda.core._stream import Stream, StreamOptions  # noqa: E402
-from cuda.core._system import System  # noqa: E402
-
-system = System()
-__import__("sys").modules[__spec__.name + ".system"] = system
-del System

cuda_core/cuda/core/_system.py

@@ -38,7 +38,7 @@ def _warn_deprecated():
 _warn_deprecated()
 
 
-from cuda.core import utils  # noqa: E402
+from cuda.core import system, utils  # noqa: E402
 
 # Make utils accessible as a submodule for backward compatibility
 __import__("sys").modules[__spec__.name + ".utils"] = utils
@@ -73,8 +73,3 @@ def _warn_deprecated():
 from cuda.core._module import Kernel, ObjectCode  # noqa: E402
 from cuda.core._program import Program, ProgramOptions  # noqa: E402
 from cuda.core._stream import Stream, StreamOptions  # noqa: E402
-from cuda.core._system import System  # noqa: E402
-
-system = System()
-__import__("sys").modules[__spec__.name + ".system"] = system
-del System

cuda_core/cuda/core/experimental/__init__.py

@@ -0,0 +1,38 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+# ruff: noqa: F403, F405
+
+
+# NOTE: We must maintain that it is always possible to import this module
+# without CUDA being installed, and without CUDA being initialized or any
+# contexts created, so that a user can use NVML to explore things about their
+# system without loading CUDA.
+
+
+__all__ = [
+    "get_driver_version",
+    "get_driver_version_full",
+    "get_num_devices",
+    "get_process_name",
+    "CUDA_BINDINGS_NVML_IS_COMPATIBLE",
+]
+
+
+from ._system import *
+
+if CUDA_BINDINGS_NVML_IS_COMPATIBLE:
+    from ._device import Device, DeviceArchitecture
+    from .exceptions import *
+    from .exceptions import __all__ as _exceptions_all
+
+    __all__.extend(
+        [
+            "get_nvml_version",
+            "Device",
+            "DeviceArchitecture",
+        ]
+    )
+
+    __all__.extend(_exceptions_all)