From f56d10703c5b861a7b3b68ec557e7f1dbe2ae7ab Mon Sep 17 00:00:00 2001 From: Floris-Jan Willemsen Date: Fri, 13 Nov 2026 10:16:06 -0500 Subject: [PATCH 1/4] Pending fix of #423 --- kernel_tuner/backends/julia.py | 74 ++++++++--- kernel_tuner/backends/julia_helper.py | 119 ++++++++++++++++-- .../backends/julia_helper_ext_cuda.jl | 4 +- kernel_tuner/observers/julia_nvml.jl | 7 +- kernel_tuner/observers/julia_nvml.py | 14 +-- noxfile.py | 23 +++- test/test_julia_helper.py | 86 +++++++++++++ test/test_julia_nvml_observer.py | 2 +- 8 files changed, 283 insertions(+), 46 deletions(-) create mode 100644 test/test_julia_helper.py diff --git a/kernel_tuner/backends/julia.py b/kernel_tuner/backends/julia.py index ada365aa..e4e24416 100644 --- a/kernel_tuner/backends/julia.py +++ b/kernel_tuner/backends/julia.py @@ -1,10 +1,12 @@ -"""Kernel Tuner backend for running Julia CUDA.jl kernels via JuliaCall. +"""Kernel Tuner backend for running Julia GPU kernels (KernelAbstractions.jl) via JuliaCall. This backend allows Julia kernels to be compiled, launched, and observed from Python using Kernel Tuner. Requirements: pip install juliacall - and in Julia: ] add CUDA / ROCBackend / oneAPI / Metal (will be automatically installed if not present) + and in Julia: ] add CUDACore NVML / AMDGPU / oneAPI / Metal (will be automatically installed if not present) + When installing CUDACore, a compatible local CUDA toolkit is used if available instead of downloading one, + see `KERNEL_TUNER_JULIA_LOCAL_CUDA_TOOLKIT` in julia_helper.py. Notes: - The kernel string should contain a valid Julia GPU kernel function definition. @@ -56,7 +58,7 @@ def give_interrupts_to_python(jl): from kernel_tuner.observers.julia import JuliaRuntimeObserver from kernel_tuner.util import SkippableFailure -from .julia_helper import backend_map, detect_julia_gpu_backends +from .julia_helper import CUDA_TOOLKIT_JLLS, backend_map, detect_julia_gpu_backends, local_cuda_toolkit_preferences jl = None @@ -180,7 +182,7 @@ def __init__(self, device=0, iterations=7, compiler_options=None, observers=None const kt_julia_backend = {self.backend_mod_instname}() const GPUArrayType = {self.GPUArrayType} include("{str(Path(__file__).parent / "julia_helper.jl")}") - include("{str(Path(__file__).parent / str("julia_helper_ext_" + self.backend_mod_name.lower() + ".jl"))}") + include("{str(Path(__file__).parent / f"julia_helper_ext_{self.helper_ext}.jl")}") end """ ) @@ -201,11 +203,20 @@ def initialize_backend(self, device, backend_name): if backend_name not in backend_map: raise ValueError(f"Unknown backend: {backend_name}") info = backend_map[backend_name] + self.backend_name = backend_name + self.helper_ext = info["helper_ext"] backend_pkg = info["pkg"] if backend_pkg is not None: # Ensure the package is installed - self.check_package_and_install(backend_pkg, allow_install=backend_name != "INTEL") # avoid Intel false positives + packages = [backend_pkg] + info.get("extra_pkgs", []) + preferences = None + if backend_name == "CUDA" and not self.package_available(backend_pkg): + # CUDA.jl downloads a CUDA toolkit on installation, prefer a compatible local toolkit instead + preferences = local_cuda_toolkit_preferences() + self.check_package_and_install( + packages, allow_install=backend_name != "INTEL", preferences=preferences + ) # avoid Intel false positives # # Set debug level if needed # if backend_name == "cuda": @@ -220,6 +231,8 @@ def initialize_backend(self, device, backend_name): jl.seval("using KernelAbstractions") if backend_pkg is not None: jl.seval(f"using {info['module']}") + for extra_pkg in info.get("extra_pkgs", []): + jl.seval(f"import {extra_pkg}") backend_mod = getattr(jl.Main, self.backend_mod_name) self.backend_mod = backend_mod jl.seval(f"tmp_arr = {info['GPUArrayType']}(Float32.(zeros(2)))") @@ -229,7 +242,7 @@ def initialize_backend(self, device, backend_name): # Select device try: - if int(device) == 0 and backend_pkg != "CUDA": + if int(device) == 0 and backend_name != "CUDA": # Julia uses 1-based indexing, but the CUDA backend uses 0-based so we skip that device = 1 jl.seval(info["device_select"](int(device))) @@ -456,7 +469,7 @@ def stop_event(self): def kernel_finished(self): """Returns True if the kernel has finished, False otherwise.""" - if self.backend_mod_name == "CUDA": + if self.backend_name == "CUDA": if self._end_event is not None: return bool(self.backend_mod.isdone(self._end_event)) return True @@ -539,24 +552,45 @@ def copy_texture_memory_args(self, texmem_args): # Helper functions # ------------------------- - def check_package_and_install(self, package, allow_install=True): - """Checks if the Julia package is available, and installs it if not.""" + @staticmethod + def package_available(package): + """Checks if the Julia package can be imported.""" try: jl.seval(f"import {package}") + return True except Exception: - if not allow_install: - warn(f"{package} not found in your Julia environment. Run `using Pkg; Pkg.add(\"{package}\")` to install it.") - return - try: - warn(f"{package} not found, attempting to install it directly.") - import juliapkg + return False + + def check_package_and_install(self, packages, allow_install=True, preferences=None): + """Checks if the Julia package(s) are available, and installs the missing ones if not. + + ``preferences`` optionally maps package names to Julia preferences that are set before installing, e.g. to + configure the CUDA toolkit JLLs. Packages that only appear in ``preferences`` are added as dependencies. + """ + packages = [packages] if isinstance(packages, str) else list(packages) + missing = [package for package in packages if not self.package_available(package)] + if not missing: + return + add_command = "using Pkg; Pkg.add([" + ", ".join(f'\"{package}\"' for package in missing) + "])" + if not allow_install: + warn(f"{', '.join(missing)} not found in your Julia environment. Run `{add_command}` to install it.") + return + try: + warn(f"{', '.join(missing)} not found, attempting to install it directly.") + import juliapkg + + for package in missing: juliapkg.add(package) - juliapkg.resolve() + for package, package_preferences in (preferences or {}).items(): + # the preferences must be in place before installation, as CUDA.jl selects the toolkit at that point + juliapkg.add(package, CUDA_TOOLKIT_JLLS.get(package), preferences=package_preferences) + juliapkg.resolve() + for package in missing: jl.seval(f"import {package}") - except Exception as e: - raise ImportError( - f'{package} not found in your Julia environment. Run `using Pkg; Pkg.add(\"{package}\")` to install it.' - ) from e + except Exception as e: + raise ImportError( + f"{', '.join(missing)} not found in your Julia environment. Run `{add_command}` to install it." + ) from e def setup_streams(self, backend_name: str): """Set up stream and event attributes for observers.""" diff --git a/kernel_tuner/backends/julia_helper.py b/kernel_tuner/backends/julia_helper.py index 4af916c4..12e79324 100644 --- a/kernel_tuner/backends/julia_helper.py +++ b/kernel_tuner/backends/julia_helper.py @@ -3,7 +3,10 @@ We might want to consider moving this to a utility module or Julia package as it can be useful. """ +import os +import shutil import subprocess +from glob import glob from json import JSONDecodeError from json import loads as json_loads from re import search as regex_search @@ -12,14 +15,18 @@ # Map name → Julia module and device-selection calls backend_map = { "CUDA": { - "pkg": "CUDA", - "module": "CUDA", + # CUDACore is the core of CUDA.jl (>= 6) without the CUDA libraries (cuBLAS, cuFFT, cuSOLVER etc.), which the + # backend does not need. NVML is a separate, small package, used to query the device UUID. + "pkg": "CUDACore", + "extra_pkgs": ["NVML"], + "module": "CUDACore", "module_backend": "CUDABackend", - "device_select": lambda d: f"CUDA.device!({d})", - "name": "CUDA.name(CUDA.device())", - "max_threads": "CUDA.attribute(CUDA.device(), CUDA.DEVICE_ATTRIBUTE_MAX_THREADS_PER_BLOCK)", - "capability": "CUDA.capability(CUDA.device())", - "uuid": lambda d: f"NVML.uuid(CUDA.NVML.Device({d}))", + "helper_ext": "cuda", + "device_select": lambda d: f"CUDACore.device!({d})", + "name": "CUDACore.name(CUDACore.device())", + "max_threads": "CUDACore.attribute(CUDACore.device(), CUDACore.DEVICE_ATTRIBUTE_MAX_THREADS_PER_BLOCK)", + "capability": "CUDACore.capability(CUDACore.device())", + "uuid": lambda d: f"NVML.uuid(NVML.Device({d}))", "pci_bus_id": None, "GPUArrayType": "CuArray", "supported_float_types": ["Float16", "BFloat16", "Float32", "Float64"], @@ -27,6 +34,7 @@ "AMD": { "pkg": "AMDGPU", "module": "AMDGPU", + "helper_ext": "amdgpu", "module_backend": "ROCBackend", "device_select": lambda d: f"AMDGPU.device!(AMDGPU.devices()[{d}])", "name": "AMDGPU.HIP.name(AMDGPU.HIP.device())", @@ -40,6 +48,7 @@ "INTEL": { "pkg": "oneAPI", "module": "oneAPI", + "helper_ext": "oneapi", "module_backend": "oneAPIBackend", "device_select": lambda d: f"device!(devices(first(drivers()))[{d}])", "name": "oneAPI.name(oneAPI.device())", @@ -53,6 +62,7 @@ "METAL": { "pkg": "Metal", "module": "Metal", + "helper_ext": "metal", "module_backend": "MetalBackend", "device_select": lambda d: "Metal.device!(Metal.device())", # only single device support in Metal.jl "name": "Metal.device().name", @@ -66,6 +76,7 @@ "CPU": { "pkg": None, "module": "CPU", + "helper_ext": None, "module_backend": "CPU", "device_select": lambda d: "nothing", "name": "CPU", @@ -146,3 +157,97 @@ def julia_backend_available_intel(): return True except (FileNotFoundError, subprocess.CalledProcessError): return False + + +# UUIDs of the JLLs that provide the CUDA toolkit to CUDA.jl, these hold the preferences for using a local toolkit +CUDA_TOOLKIT_JLLS = { + "CUDA_Runtime_jll": "76a88914-d11a-5bdc-97e0-2f5a05c973a2", + "CUDA_Compiler_jll": "d1e2174e-dfdc-576e-b43e-73b79eb1aca8", +} +# environment variable to control the use of a local CUDA toolkit when the Julia backend installs CUDACore.jl +LOCAL_CUDA_TOOLKIT_ENV = "KERNEL_TUNER_JULIA_LOCAL_CUDA_TOOLKIT" +MIN_LOCAL_CUDA_TOOLKIT_VERSION = (12, 0) + + +def _cuda_version_from_output(command, pattern): + """Run a command and parse a (major, minor) CUDA version from its output, None if this fails.""" + try: + output = subprocess.check_output(command, stderr=subprocess.STDOUT, text=True, timeout=30) + except (FileNotFoundError, PermissionError, subprocess.CalledProcessError, subprocess.TimeoutExpired): + return None + match = regex_search(pattern, output) + return (int(match.group(1)), int(match.group(2))) if match else None + + +def cuda_driver_version(): + """Return the highest CUDA version supported by the NVIDIA driver as (major, minor), None if unknown.""" + return _cuda_version_from_output(["nvidia-smi"], r"CUDA Version:\s*(\d+)\.(\d+)") + + +def _toolkit_candidate_dirs(): + """Directories that may hold a CUDA toolkit, in the order that CUDA.jl (CUDA_Runtime_Discovery) searches them.""" + # if set, the environment variables override the discovery + env_dirs = [os.environ[var] for var in ("CUDA_PATH", "CUDA_HOME", "CUDA_ROOT") if os.path.isdir(os.environ.get(var, ""))] + if env_dirs: + return list(dict.fromkeys(env_dirs)) + dirs = [] + ptxas = shutil.which("ptxas") + if ptxas is not None: + dirs.append(os.path.dirname(os.path.dirname(os.path.realpath(ptxas)))) + for base in ("/usr/local/cuda", "/opt/cuda"): + dirs.extend(sorted(glob(f"{base}-*"), reverse=True)) + dirs.append(base) + return [d for d in dict.fromkeys(dirs) if os.path.isdir(d)] + + +def _toolkit_is_complete(toolkit_dir): + """Check that the toolkit has the components CUDA.jl needs: the compiler, runtime library and libdevice.""" + has_cudart = any( + glob(os.path.join(toolkit_dir, pattern)) + for pattern in ("lib64/libcudart.so*", "lib/libcudart.so*", "targets/*/lib/libcudart.so*", "bin/cudart64_*.dll") + ) + has_libdevice = bool(glob(os.path.join(toolkit_dir, "nvvm", "libdevice", "libdevice*.bc"))) + return has_cudart and has_libdevice + + +def find_local_cuda_toolkit(): + """Find a local CUDA toolkit that CUDA.jl can use with the installed driver. + + Returns a tuple of the toolkit directory and its (major, minor) version, or None if no compatible toolkit is found. + """ + driver_version = cuda_driver_version() + if driver_version is None: + return None + for toolkit_dir in _toolkit_candidate_dirs(): + ptxas = os.path.join(toolkit_dir, "bin", "ptxas.exe" if os.name == "nt" else "ptxas") + if not os.path.isfile(ptxas) or not _toolkit_is_complete(toolkit_dir): + continue + version = _cuda_version_from_output([ptxas, "--version"], r"release (\d+)\.(\d+)") + # like CUDA.jl, rely on minor version compatibility: the toolkit major version may not exceed the driver's + if version is not None and MIN_LOCAL_CUDA_TOOLKIT_VERSION <= version and version[0] <= driver_version[0]: + return toolkit_dir, version + return None + + +def local_cuda_toolkit_preferences(): + """Return the juliapkg preferences that make CUDA.jl use a local CUDA toolkit instead of downloading one. + + Controlled by the environment variable ``KERNEL_TUNER_JULIA_LOCAL_CUDA_TOOLKIT``: "auto" (default) uses a compatible + local toolkit if one is found, "yes" always uses the local toolkit, "no" lets CUDA.jl download the toolkit. + Returns None if the toolkit should be downloaded. + """ + setting = os.environ.get(LOCAL_CUDA_TOOLKIT_ENV, "auto").strip().lower() + if setting in ("no", "false", "0", "off"): + return None + if setting not in ("yes", "true", "1", "on"): + if setting != "auto": + warn(f"Unknown value '{setting}' for {LOCAL_CUDA_TOOLKIT_ENV}, expected 'auto', 'yes' or 'no'. Using 'auto'.") + toolkit = find_local_cuda_toolkit() + if toolkit is None: + return None + toolkit_dir, (major, minor) = toolkit + warn( + f"Using the local CUDA {major}.{minor} toolkit at {toolkit_dir} for CUDA.jl instead of downloading one. " + f"Set {LOCAL_CUDA_TOOLKIT_ENV}=no before the first use of the Julia backend to download it instead." + ) + return {name: {"local": "true"} for name in CUDA_TOOLKIT_JLLS} diff --git a/kernel_tuner/backends/julia_helper_ext_cuda.jl b/kernel_tuner/backends/julia_helper_ext_cuda.jl index 61798f83..213b0a64 100644 --- a/kernel_tuner/backends/julia_helper_ext_cuda.jl +++ b/kernel_tuner/backends/julia_helper_ext_cuda.jl @@ -1,4 +1,4 @@ -# Extension of the julia_helper.jl file for the CUDA backend. You can assume `using CUDA` has ran. +# Extension of the julia_helper.jl file for the CUDA backend. You can assume `using CUDACore` has ran. # GPU timing events, recorded on the stream that the kernel is launched on create_timing_events(::CUDABackend) = (CuEvent(), CuEvent()) -record_timing_event(evt::CuEvent) = CUDA.record(evt, CUDA.stream()) +record_timing_event(evt::CuEvent) = CUDACore.record(evt, CUDACore.stream()) diff --git a/kernel_tuner/observers/julia_nvml.jl b/kernel_tuner/observers/julia_nvml.jl index 46f8594e..8360e5dd 100644 --- a/kernel_tuner/observers/julia_nvml.jl +++ b/kernel_tuner/observers/julia_nvml.jl @@ -1,9 +1,10 @@ -# NVML functionality for the JuliaNVMLObserver, using the NVML wrapper of CUDA.jl. +# NVML functionality for the JuliaNVMLObserver, using NVML.jl (the NVML wrapper of CUDA.jl). # Functions raise `NVML.NVMLError` on failure; `error_code` lets Python tell e.g. "not supported" from "no permission". # Units follow NVML: power in milliwatt, energy in millijoule, clocks in MHz, temperature in degrees Celsius. module KernelTunerNVML -using CUDA: CUDA, NVML +import CUDACore +import NVML # NVML return code of an exception, or -1 if it is not an NVML error error_code(err) = err isa NVML.NVMLError ? Int(err.code) : -1 @@ -13,7 +14,7 @@ error_code(err) = err isa NVML.NVMLError ? Int(err.code) : -1 # the device (not a MIG instance, as power and clocks are controlled per device) that runs the given CUDA device, # found by UUID, as CUDA and NVML can number the devices differently (e.g. with CUDA_VISIBLE_DEVICES) -device_of(cuda_device::CUDA.CuDevice) = NVML.Device(CUDA.parent_uuid(cuda_device)) +device_of(cuda_device::CUDACore.CuDevice) = NVML.Device(CUDACore.parent_uuid(cuda_device)) device_by_index(index::Integer) = NVML.Device(index) diff --git a/kernel_tuner/observers/julia_nvml.py b/kernel_tuner/observers/julia_nvml.py index 24f161d6..191e514b 100644 --- a/kernel_tuner/observers/julia_nvml.py +++ b/kernel_tuner/observers/julia_nvml.py @@ -1,4 +1,4 @@ -"""NVML observer for the Julia backend, using the NVML wrapper of CUDA.jl instead of pynvml. +"""NVML observer for the Julia backend, using NVML.jl (the NVML wrapper of CUDA.jl) instead of pynvml. The observables and tunable parameters are the same as those of the :class:`~kernel_tuner.observers.nvml.NVMLObserver`. The NVML calls are made from the Julia process that runs the kernels, so pynvml is not needed. See ``julia_nvml.jl`` @@ -52,7 +52,7 @@ def __init__(self): try: jl.include(str(Path(__file__).parent / "julia_nvml.jl")) except JuliaError as e: - raise ImportError(f"Could not load NVML through CUDA.jl, is CUDA.jl installed? {e}") from e + raise ImportError(f"Could not load NVML.jl, are CUDACore.jl and NVML.jl installed? {e}") from e self._module = jl.KernelTunerNVML def __getattr__(self, name): @@ -84,10 +84,10 @@ def julia_nvml_library(): class JuliaNVML: - """Class that gathers the NVML functionality for one device, through CUDA.jl. + """Class that gathers the NVML functionality for one device, through NVML.jl. Has the same interface as :class:`kernel_tuner.observers.nvml.nvml`. The device is selected by exactly one of - ``cuda_device`` (a ``CUDA.CuDevice`` from Julia), ``device_id`` (the NVML index, as reported by nvidia-smi), + ``cuda_device`` (a ``CUDACore.CuDevice`` from Julia), ``device_id`` (the NVML index, as reported by nvidia-smi), ``device_uuid``, or ``device_pci_bus``. """ @@ -100,7 +100,7 @@ def __init__( use_locked_clocks=False, cuda_device=None, ): - """Create object to control device using NVML through CUDA.jl.""" + """Create object to control device using NVML through NVML.jl.""" # set these first, as __del__ uses them and this __init__ may raise an exception midway self.pwr_limit_default = None self.modified_clocks = False @@ -347,7 +347,7 @@ def gr_voltage(self): class JuliaNVMLObserver(NVMLObserver): - """Observer for the Julia backend that uses NVML through CUDA.jl to monitor power, energy, clock frequencies, voltages and temperature. + """Observer for the Julia backend that uses NVML through NVML.jl to monitor power, energy, clock frequencies, voltages and temperature. Takes the same arguments and supports the same observables and tunable parameters (``nvml_pwr_limit``, ``nvml_gr_clock``, and ``nvml_mem_clock``) as the :class:`~kernel_tuner.observers.nvml.NVMLObserver`, see there. @@ -370,7 +370,7 @@ def read_power(self): return self._last_power def register_device(self, dev): - cuda_device = getattr(dev, "backend_device", None) if getattr(dev, "backend_mod_name", None) == "CUDA" else None + cuda_device = getattr(dev, "backend_device", None) if getattr(dev, "backend_name", None) == "CUDA" else None env = getattr(dev, "env", dict()) uuid = env.get("uuid") pci_bus = env.get("pci_bus_id") diff --git a/noxfile.py b/noxfile.py index 3b6cd5b5..971ed699 100644 --- a/noxfile.py +++ b/noxfile.py @@ -17,7 +17,12 @@ # TODO this should be changed to something more robust REPO_ROOT = Path(__file__).parent.joinpath(Path("kernel_tuner/backends")).resolve() sys.path.append(str(REPO_ROOT)) -from julia_helper import backend_map, detect_julia_gpu_backends # noqa: E402, F401 +from julia_helper import ( # noqa: E402, F401 + CUDA_TOOLKIT_JLLS, + backend_map, + detect_julia_gpu_backends, + local_cuda_toolkit_preferences, +) # set the test parameters verbose = False @@ -367,12 +372,18 @@ def tests(session: Session) -> None: session.env["PYTHON_JULIAPKG_PROJECT"] = julia_project_path env_vars["PYTHON_JULIAPKG_PROJECT"] = julia_project_path # install any additional dependencies used by the tests, as `check_package_and_install` won't work from Nox + gpu_backends_string = "" if julia_use_gpu: - gpu_backends_string = "".join( - f'juliapkg.add("{backend_map[backend]["pkg"]}"); ' if backend_map[backend]["pkg"] else "" for backend in detect_julia_gpu_backends() - ) - else: - gpu_backends_string = "" + for backend in detect_julia_gpu_backends(): + if backend_map[backend]["pkg"] is None: + continue + for pkg in [backend_map[backend]["pkg"]] + backend_map[backend].get("extra_pkgs", []): + gpu_backends_string += f'juliapkg.add("{pkg}"); ' + if backend == "CUDA": + # use a compatible local CUDA toolkit instead of letting CUDA.jl download one, if available + for jll, preferences in (local_cuda_toolkit_preferences() or {}).items(): + gpu_backends_string += f'juliapkg.add("{jll}", "{CUDA_TOOLKIT_JLLS[jll]}", preferences={preferences!r}); ' + session.run( "python", "-c", f"{preamble}; juliapkg.resolve(); juliapkg.add('KernelAbstractions'); {gpu_backends_string} juliapkg.resolve();", diff --git a/test/test_julia_helper.py b/test/test_julia_helper.py new file mode 100644 index 00000000..4509de24 --- /dev/null +++ b/test/test_julia_helper.py @@ -0,0 +1,86 @@ +"""Tests for the detection of a local CUDA toolkit for the Julia backend, these do not need Julia or a GPU.""" + +import os +import stat + +import pytest + +from kernel_tuner.backends import julia_helper + + +def make_toolkit(base, version="12.4", complete=True): + """Create a fake CUDA toolkit directory with a ptxas that reports the given version.""" + bin_dir = base / "bin" + bin_dir.mkdir(parents=True) + ptxas = bin_dir / "ptxas" + ptxas.write_text(f"#!/bin/sh\necho 'Cuda compilation tools, release {version}, V{version}.0'\n") + ptxas.chmod(ptxas.stat().st_mode | stat.S_IEXEC) + if complete: + (base / "lib64").mkdir() + (base / "lib64" / "libcudart.so.12").write_text("") + (base / "nvvm" / "libdevice").mkdir(parents=True) + (base / "nvvm" / "libdevice" / "libdevice.10.bc").write_text("") + return base + + +@pytest.fixture +def toolkit_env(monkeypatch, tmp_path): + """Isolate the toolkit discovery from the system, with a driver that supports CUDA 12.8.""" + for var in ("CUDA_PATH", "CUDA_HOME", "CUDA_ROOT", julia_helper.LOCAL_CUDA_TOOLKIT_ENV): + monkeypatch.delenv(var, raising=False) + monkeypatch.setattr(julia_helper.shutil, "which", lambda name: None) + monkeypatch.setattr(julia_helper.os.path, "isdir", lambda path: str(path).startswith(str(tmp_path))) + monkeypatch.setattr(julia_helper, "cuda_driver_version", lambda: (12, 8)) + return tmp_path + + +skip_on_windows = pytest.mark.skipif(os.name == "nt", reason="fake ptxas is a shell script") + + +@skip_on_windows +def test_find_local_cuda_toolkit_from_env(toolkit_env, monkeypatch): + """A toolkit given by the environment variables is found.""" + toolkit = make_toolkit(toolkit_env / "cuda") + monkeypatch.setenv("CUDA_HOME", str(toolkit)) + assert julia_helper.find_local_cuda_toolkit() == (str(toolkit), (12, 4)) + + +@skip_on_windows +def test_find_local_cuda_toolkit_incompatible(toolkit_env, monkeypatch): + """Toolkits that CUDA.jl can not use with the driver are rejected.""" + # newer major version than the driver supports + monkeypatch.setenv("CUDA_HOME", str(make_toolkit(toolkit_env / "cuda13", version="13.0"))) + assert julia_helper.find_local_cuda_toolkit() is None + # too old + monkeypatch.setenv("CUDA_HOME", str(make_toolkit(toolkit_env / "cuda11", version="11.8"))) + assert julia_helper.find_local_cuda_toolkit() is None + # incomplete, e.g. only the compiler + monkeypatch.setenv("CUDA_HOME", str(make_toolkit(toolkit_env / "partial", complete=False))) + assert julia_helper.find_local_cuda_toolkit() is None + + +@skip_on_windows +def test_find_local_cuda_toolkit_no_driver(toolkit_env, monkeypatch): + """Without an NVIDIA driver, no toolkit is used.""" + monkeypatch.setenv("CUDA_HOME", str(make_toolkit(toolkit_env / "cuda"))) + monkeypatch.setattr(julia_helper, "cuda_driver_version", lambda: None) + assert julia_helper.find_local_cuda_toolkit() is None + + +@skip_on_windows +def test_local_cuda_toolkit_preferences(toolkit_env, monkeypatch): + """The preferences follow the detection and the environment variable.""" + local = {name: {"local": "true"} for name in julia_helper.CUDA_TOOLKIT_JLLS} + # no local toolkit: download + assert julia_helper.local_cuda_toolkit_preferences() is None + # local toolkit found + monkeypatch.setenv("CUDA_HOME", str(make_toolkit(toolkit_env / "cuda"))) + with pytest.warns(UserWarning, match="local CUDA 12.4 toolkit"): + assert julia_helper.local_cuda_toolkit_preferences() == local + # opt-out + monkeypatch.setenv(julia_helper.LOCAL_CUDA_TOOLKIT_ENV, "no") + assert julia_helper.local_cuda_toolkit_preferences() is None + # forced, even without a detected toolkit + monkeypatch.delenv("CUDA_HOME") + monkeypatch.setenv(julia_helper.LOCAL_CUDA_TOOLKIT_ENV, "yes") + assert julia_helper.local_cuda_toolkit_preferences() == local diff --git a/test/test_julia_nvml_observer.py b/test/test_julia_nvml_observer.py index 4e85f2ca..e4d82ab2 100644 --- a/test/test_julia_nvml_observer.py +++ b/test/test_julia_nvml_observer.py @@ -180,7 +180,7 @@ def test_tune_kernel_with_julia_nvml_observer(): from juliacall import Main as jl # the observer measures the GPU that the Julia backend runs on - assert observer.nvml.uuid == "GPU-" + str(jl.seval("CUDA.uuid(CUDA.device())")) + assert observer.nvml.uuid == "GPU-" + str(jl.seval("CUDACore.uuid(CUDACore.device())")) for r in results: for observable in observables: assert r[observable] > 0, f"{observable} not positive in {r}" From 1e59e5ee5299483660bfbd830878ece5fab550ea Mon Sep 17 00:00:00 2001 From: Floris-Jan Willemsen Date: Fri, 13 Nov 2026 11:00:43 -0500 Subject: [PATCH 2/4] Already instealled CUDA.jl is reused as is --- kernel_tuner/backends/julia.py | 31 ++++++++++++++----- kernel_tuner/backends/julia_helper.py | 2 ++ .../backends/julia_helper_ext_cuda.jl | 3 +- kernel_tuner/backends/julia_load_cuda.jl | 20 ++++++++++++ kernel_tuner/observers/julia_nvml.jl | 3 +- kernel_tuner/observers/julia_nvml.py | 2 +- 6 files changed, 49 insertions(+), 12 deletions(-) create mode 100644 kernel_tuner/backends/julia_load_cuda.jl diff --git a/kernel_tuner/backends/julia.py b/kernel_tuner/backends/julia.py index e4e24416..99347859 100644 --- a/kernel_tuner/backends/julia.py +++ b/kernel_tuner/backends/julia.py @@ -5,6 +5,7 @@ Requirements: pip install juliacall and in Julia: ] add CUDACore NVML / AMDGPU / oneAPI / Metal (will be automatically installed if not present) + An installed CUDA.jl is used as is, as it contains CUDACore and NVML. When installing CUDACore, a compatible local CUDA toolkit is used if available instead of downloading one, see `KERNEL_TUNER_JULIA_LOCAL_CUDA_TOOLKIT` in julia_helper.py. @@ -178,7 +179,7 @@ def __init__(self, device=0, iterations=7, compiler_options=None, observers=None f""" global dest_tmp, src_tmp # for memcpy_htod module KernelTunerHelper - using {self.backend_mod_name} + using {self.backend_using} const kt_julia_backend = {self.backend_mod_instname}() const GPUArrayType = {self.GPUArrayType} include("{str(Path(__file__).parent / "julia_helper.jl")}") @@ -211,9 +212,13 @@ def initialize_backend(self, device, backend_name): # Ensure the package is installed packages = [backend_pkg] + info.get("extra_pkgs", []) preferences = None - if backend_name == "CUDA" and not self.package_available(backend_pkg): - # CUDA.jl downloads a CUDA toolkit on installation, prefer a compatible local toolkit instead - preferences = local_cuda_toolkit_preferences() + if backend_name == "CUDA": + if self.package_installed("CUDA"): + # CUDA.jl contains CUDACore and NVML, use it as is (see julia_load_cuda.jl) + packages = [] + elif not self.package_installed(backend_pkg): + # CUDA.jl downloads a CUDA toolkit on installation, prefer a compatible local toolkit instead + preferences = local_cuda_toolkit_preferences() self.check_package_and_install( packages, allow_install=backend_name != "INTEL", preferences=preferences ) # avoid Intel false positives @@ -229,10 +234,15 @@ def initialize_backend(self, device, backend_name): # KernelAbstractions is a dependency of the backend packages, but must be a direct dependency to be loaded self.check_package_and_install("KernelAbstractions") jl.seval("using KernelAbstractions") + self.backend_using = info["module"] if backend_pkg is not None: - jl.seval(f"using {info['module']}") - for extra_pkg in info.get("extra_pkgs", []): - jl.seval(f"import {extra_pkg}") + if info.get("loader") is not None: + # the loader binds the module in Main, so other modules defined in Main use it relatively + jl.include(str(Path(__file__).parent / info["loader"])) + jl.seval(f"using .{info['module']}") + self.backend_using = f"..{info['module']}" + else: + jl.seval(f"using {info['module']}") backend_mod = getattr(jl.Main, self.backend_mod_name) self.backend_mod = backend_mod jl.seval(f"tmp_arr = {info['GPUArrayType']}(Float32.(zeros(2)))") @@ -391,7 +401,7 @@ def compile(self, kernel_instance): else: module_code = f""" module KernelTunerUserKernel - using {self.backend_mod_name} + using {self.backend_using} {kernel_code} end """ @@ -552,6 +562,11 @@ def copy_texture_memory_args(self, texmem_args): # Helper functions # ------------------------- + @staticmethod + def package_installed(package): + """Checks if the Julia package is a direct dependency of the environment, without loading it.""" + return bool(jl.seval(f'Base.find_package("{package}") !== nothing')) + @staticmethod def package_available(package): """Checks if the Julia package can be imported.""" diff --git a/kernel_tuner/backends/julia_helper.py b/kernel_tuner/backends/julia_helper.py index 12e79324..d9e214d6 100644 --- a/kernel_tuner/backends/julia_helper.py +++ b/kernel_tuner/backends/julia_helper.py @@ -17,8 +17,10 @@ "CUDA": { # CUDACore is the core of CUDA.jl (>= 6) without the CUDA libraries (cuBLAS, cuFFT, cuSOLVER etc.), which the # backend does not need. NVML is a separate, small package, used to query the device UUID. + # An installed CUDA.jl is used instead, as it contains both, see julia_load_cuda.jl. "pkg": "CUDACore", "extra_pkgs": ["NVML"], + "loader": "julia_load_cuda.jl", "module": "CUDACore", "module_backend": "CUDABackend", "helper_ext": "cuda", diff --git a/kernel_tuner/backends/julia_helper_ext_cuda.jl b/kernel_tuner/backends/julia_helper_ext_cuda.jl index 213b0a64..7862049b 100644 --- a/kernel_tuner/backends/julia_helper_ext_cuda.jl +++ b/kernel_tuner/backends/julia_helper_ext_cuda.jl @@ -1,4 +1,5 @@ # Extension of the julia_helper.jl file for the CUDA backend. You can assume `using CUDACore` has ran. +# Only use exported names unqualified, as CUDACore may be provided by CUDA.jl (see julia_load_cuda.jl). # GPU timing events, recorded on the stream that the kernel is launched on create_timing_events(::CUDABackend) = (CuEvent(), CuEvent()) -record_timing_event(evt::CuEvent) = CUDACore.record(evt, CUDACore.stream()) +record_timing_event(evt::CuEvent) = record(evt, stream()) diff --git a/kernel_tuner/backends/julia_load_cuda.jl b/kernel_tuner/backends/julia_load_cuda.jl new file mode 100644 index 00000000..2443dad3 --- /dev/null +++ b/kernel_tuner/backends/julia_load_cuda.jl @@ -0,0 +1,20 @@ +# Makes `CUDACore` and `NVML` available in the module that includes this file. +# These come from the CUDACore.jl and NVML.jl packages if they are installed (direct dependencies of the environment), +# otherwise from CUDA.jl: since v6, CUDA.jl contains CUDACore and NVML, before v6 CUDA.jl itself was the core package. +# This way an existing CUDA.jl installation is used as is, without installing or downloading anything. +if !isdefined(@__MODULE__, :CUDACore) + if Base.find_package("CUDACore") !== nothing + import CUDACore + else + import CUDA + const CUDACore = isdefined(CUDA, :CUDACore) ? CUDA.CUDACore : CUDA + end +end +if !isdefined(@__MODULE__, :NVML) + if Base.find_package("NVML") !== nothing + import NVML + else + import CUDA + const NVML = CUDA.NVML + end +end diff --git a/kernel_tuner/observers/julia_nvml.jl b/kernel_tuner/observers/julia_nvml.jl index 8360e5dd..137c9fb7 100644 --- a/kernel_tuner/observers/julia_nvml.jl +++ b/kernel_tuner/observers/julia_nvml.jl @@ -3,8 +3,7 @@ # Units follow NVML: power in milliwatt, energy in millijoule, clocks in MHz, temperature in degrees Celsius. module KernelTunerNVML -import CUDACore -import NVML +include(joinpath(@__DIR__, "..", "backends", "julia_load_cuda.jl")) # defines CUDACore and NVML # NVML return code of an exception, or -1 if it is not an NVML error error_code(err) = err isa NVML.NVMLError ? Int(err.code) : -1 diff --git a/kernel_tuner/observers/julia_nvml.py b/kernel_tuner/observers/julia_nvml.py index 191e514b..af9b48f7 100644 --- a/kernel_tuner/observers/julia_nvml.py +++ b/kernel_tuner/observers/julia_nvml.py @@ -52,7 +52,7 @@ def __init__(self): try: jl.include(str(Path(__file__).parent / "julia_nvml.jl")) except JuliaError as e: - raise ImportError(f"Could not load NVML.jl, are CUDACore.jl and NVML.jl installed? {e}") from e + raise ImportError(f"Could not load NVML.jl, is CUDA.jl (or CUDACore.jl and NVML.jl) installed? {e}") from e self._module = jl.KernelTunerNVML def __getattr__(self, name): From fc6511ba5f56f6113c2c35b10c82a4efeee48029 Mon Sep 17 00:00:00 2001 From: Floris-Jan Willemsen Date: Fri, 13 Nov 2026 13:11:29 -0500 Subject: [PATCH 3/4] Improved Intel and oneAPI detection --- kernel_tuner/backends/julia.py | 16 ++++- kernel_tuner/backends/julia_helper.py | 41 +++++++++---- test/test_julia_helper.py | 86 --------------------------- 3 files changed, 43 insertions(+), 100 deletions(-) delete mode 100644 test/test_julia_helper.py diff --git a/kernel_tuner/backends/julia.py b/kernel_tuner/backends/julia.py index 99347859..540a5653 100644 --- a/kernel_tuner/backends/julia.py +++ b/kernel_tuner/backends/julia.py @@ -219,9 +219,14 @@ def initialize_backend(self, device, backend_name): elif not self.package_installed(backend_pkg): # CUDA.jl downloads a CUDA toolkit on installation, prefer a compatible local toolkit instead preferences = local_cuda_toolkit_preferences() - self.check_package_and_install( + installed = self.check_package_and_install( packages, allow_install=backend_name != "INTEL", preferences=preferences ) # avoid Intel false positives + if not installed: + if self.backend_requested: + raise ImportError(f"Julia backend {backend_name} requested, but {backend_pkg} is not installed.") + warn(f"Julia backend {backend_name} detected, but {backend_pkg} is not installed. Using the CPU backend.") + return self.initialize_backend(device, "CPU") # # Set debug level if needed # if backend_name == "cuda": @@ -579,17 +584,19 @@ def package_available(package): def check_package_and_install(self, packages, allow_install=True, preferences=None): """Checks if the Julia package(s) are available, and installs the missing ones if not. + Returns True if the packages are available, False if they are missing and installation is not allowed. + ``preferences`` optionally maps package names to Julia preferences that are set before installing, e.g. to configure the CUDA toolkit JLLs. Packages that only appear in ``preferences`` are added as dependencies. """ packages = [packages] if isinstance(packages, str) else list(packages) missing = [package for package in packages if not self.package_available(package)] if not missing: - return + return True add_command = "using Pkg; Pkg.add([" + ", ".join(f'\"{package}\"' for package in missing) + "])" if not allow_install: warn(f"{', '.join(missing)} not found in your Julia environment. Run `{add_command}` to install it.") - return + return False try: warn(f"{', '.join(missing)} not found, attempting to install it directly.") import juliapkg @@ -602,6 +609,7 @@ def check_package_and_install(self, packages, allow_install=True, preferences=No juliapkg.resolve() for package in missing: jl.seval(f"import {package}") + return True except Exception as e: raise ImportError( f"{', '.join(missing)} not found in your Julia environment. Run `{add_command}` to install it." @@ -654,7 +662,9 @@ def process_compiler_options(self, compiler_options=None): def verify_backends_with_options(self, compiler_options=None): """Verify that the requested backend is available.""" + self.backend_requested = False if compiler_options is not None and len(compiler_options) == 1: + self.backend_requested = True if compiler_options[0].upper() not in self.available_backends: raise ValueError( f"Requested Julia backend '{compiler_options[0]}' not available. " diff --git a/kernel_tuner/backends/julia_helper.py b/kernel_tuner/backends/julia_helper.py index d9e214d6..f6ea70fb 100644 --- a/kernel_tuner/backends/julia_helper.py +++ b/kernel_tuner/backends/julia_helper.py @@ -6,6 +6,7 @@ import os import shutil import subprocess +import sys from glob import glob from json import JSONDecodeError from json import loads as json_loads @@ -148,17 +149,31 @@ def julia_backend_available_metal(): def julia_backend_available_intel(): - """Check if Intel backend is available. May give false positives if other backends are present.""" - try: - subprocess.check_output("intel-smi") - return True - except (FileNotFoundError, subprocess.CalledProcessError): + """Check if Intel backend is available, i.e. an Intel GPU is present (oneAPI.jl only supports Linux).""" + INTEL_PCI_VENDOR_ID = "0x8086" + PCI_CLASS_DISPLAY = "0x03" + + if not sys.platform.startswith("linux"): + return False + for tool in ("xpu-smi", "intel-smi"): try: - # not a perfect check but should work in most cases - subprocess.check_output("ls /dev/dri/by-path/".split()) + subprocess.check_output(tool, stderr=subprocess.DEVNULL) return True - except (FileNotFoundError, subprocess.CalledProcessError): - return False + except (FileNotFoundError, PermissionError, subprocess.CalledProcessError): + pass + # a /dev/dri device alone is not enough, as e.g. NVIDIA, AMD and virtual GPUs (as on CI runners) also have one, + # so check the PCI vendor and class of the DRM devices for an Intel display controller + for device in glob("/sys/class/drm/card*/device"): + try: + with open(os.path.join(device, "vendor")) as vendor_file: + vendor = vendor_file.read().strip().lower() + with open(os.path.join(device, "class")) as class_file: + device_class = class_file.read().strip().lower() + except OSError: + continue + if vendor == INTEL_PCI_VENDOR_ID and device_class.startswith(PCI_CLASS_DISPLAY): + return True + return False # UUIDs of the JLLs that provide the CUDA toolkit to CUDA.jl, these hold the preferences for using a local toolkit @@ -189,7 +204,9 @@ def cuda_driver_version(): def _toolkit_candidate_dirs(): """Directories that may hold a CUDA toolkit, in the order that CUDA.jl (CUDA_Runtime_Discovery) searches them.""" # if set, the environment variables override the discovery - env_dirs = [os.environ[var] for var in ("CUDA_PATH", "CUDA_HOME", "CUDA_ROOT") if os.path.isdir(os.environ.get(var, ""))] + env_dirs = [ + os.environ[var] for var in ("CUDA_PATH", "CUDA_HOME", "CUDA_ROOT") if os.path.isdir(os.environ.get(var, "")) + ] if env_dirs: return list(dict.fromkeys(env_dirs)) dirs = [] @@ -243,7 +260,9 @@ def local_cuda_toolkit_preferences(): return None if setting not in ("yes", "true", "1", "on"): if setting != "auto": - warn(f"Unknown value '{setting}' for {LOCAL_CUDA_TOOLKIT_ENV}, expected 'auto', 'yes' or 'no'. Using 'auto'.") + warn( + f"Unknown value '{setting}' for {LOCAL_CUDA_TOOLKIT_ENV}, expected 'auto', 'yes' or 'no'. Using 'auto'." + ) toolkit = find_local_cuda_toolkit() if toolkit is None: return None diff --git a/test/test_julia_helper.py b/test/test_julia_helper.py deleted file mode 100644 index 4509de24..00000000 --- a/test/test_julia_helper.py +++ /dev/null @@ -1,86 +0,0 @@ -"""Tests for the detection of a local CUDA toolkit for the Julia backend, these do not need Julia or a GPU.""" - -import os -import stat - -import pytest - -from kernel_tuner.backends import julia_helper - - -def make_toolkit(base, version="12.4", complete=True): - """Create a fake CUDA toolkit directory with a ptxas that reports the given version.""" - bin_dir = base / "bin" - bin_dir.mkdir(parents=True) - ptxas = bin_dir / "ptxas" - ptxas.write_text(f"#!/bin/sh\necho 'Cuda compilation tools, release {version}, V{version}.0'\n") - ptxas.chmod(ptxas.stat().st_mode | stat.S_IEXEC) - if complete: - (base / "lib64").mkdir() - (base / "lib64" / "libcudart.so.12").write_text("") - (base / "nvvm" / "libdevice").mkdir(parents=True) - (base / "nvvm" / "libdevice" / "libdevice.10.bc").write_text("") - return base - - -@pytest.fixture -def toolkit_env(monkeypatch, tmp_path): - """Isolate the toolkit discovery from the system, with a driver that supports CUDA 12.8.""" - for var in ("CUDA_PATH", "CUDA_HOME", "CUDA_ROOT", julia_helper.LOCAL_CUDA_TOOLKIT_ENV): - monkeypatch.delenv(var, raising=False) - monkeypatch.setattr(julia_helper.shutil, "which", lambda name: None) - monkeypatch.setattr(julia_helper.os.path, "isdir", lambda path: str(path).startswith(str(tmp_path))) - monkeypatch.setattr(julia_helper, "cuda_driver_version", lambda: (12, 8)) - return tmp_path - - -skip_on_windows = pytest.mark.skipif(os.name == "nt", reason="fake ptxas is a shell script") - - -@skip_on_windows -def test_find_local_cuda_toolkit_from_env(toolkit_env, monkeypatch): - """A toolkit given by the environment variables is found.""" - toolkit = make_toolkit(toolkit_env / "cuda") - monkeypatch.setenv("CUDA_HOME", str(toolkit)) - assert julia_helper.find_local_cuda_toolkit() == (str(toolkit), (12, 4)) - - -@skip_on_windows -def test_find_local_cuda_toolkit_incompatible(toolkit_env, monkeypatch): - """Toolkits that CUDA.jl can not use with the driver are rejected.""" - # newer major version than the driver supports - monkeypatch.setenv("CUDA_HOME", str(make_toolkit(toolkit_env / "cuda13", version="13.0"))) - assert julia_helper.find_local_cuda_toolkit() is None - # too old - monkeypatch.setenv("CUDA_HOME", str(make_toolkit(toolkit_env / "cuda11", version="11.8"))) - assert julia_helper.find_local_cuda_toolkit() is None - # incomplete, e.g. only the compiler - monkeypatch.setenv("CUDA_HOME", str(make_toolkit(toolkit_env / "partial", complete=False))) - assert julia_helper.find_local_cuda_toolkit() is None - - -@skip_on_windows -def test_find_local_cuda_toolkit_no_driver(toolkit_env, monkeypatch): - """Without an NVIDIA driver, no toolkit is used.""" - monkeypatch.setenv("CUDA_HOME", str(make_toolkit(toolkit_env / "cuda"))) - monkeypatch.setattr(julia_helper, "cuda_driver_version", lambda: None) - assert julia_helper.find_local_cuda_toolkit() is None - - -@skip_on_windows -def test_local_cuda_toolkit_preferences(toolkit_env, monkeypatch): - """The preferences follow the detection and the environment variable.""" - local = {name: {"local": "true"} for name in julia_helper.CUDA_TOOLKIT_JLLS} - # no local toolkit: download - assert julia_helper.local_cuda_toolkit_preferences() is None - # local toolkit found - monkeypatch.setenv("CUDA_HOME", str(make_toolkit(toolkit_env / "cuda"))) - with pytest.warns(UserWarning, match="local CUDA 12.4 toolkit"): - assert julia_helper.local_cuda_toolkit_preferences() == local - # opt-out - monkeypatch.setenv(julia_helper.LOCAL_CUDA_TOOLKIT_ENV, "no") - assert julia_helper.local_cuda_toolkit_preferences() is None - # forced, even without a detected toolkit - monkeypatch.delenv("CUDA_HOME") - monkeypatch.setenv(julia_helper.LOCAL_CUDA_TOOLKIT_ENV, "yes") - assert julia_helper.local_cuda_toolkit_preferences() == local From 688b4d5667397a5b0e6b58009e7c5082ff8c3e2c Mon Sep 17 00:00:00 2001 From: Floris-Jan Willemsen Date: Fri, 13 Nov 2026 13:37:53 -0500 Subject: [PATCH 4/4] Updated changelog --- CHANGELOG.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 49b6b146..c7a05c4d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,10 +3,13 @@ All notable changes to this project will be documented in this file. This project adheres to [Semantic Versioning](http://semver.org/). ## Unreleased + +## [1.6.0] - 2026-11-13 - Extended Julia functionality: - Implemented Julia observers for Metal, Nvidia and AMD energy measurements. - Improved timing stability. - Include the new tests of #407, additional new and updated tests. + - Fixed issue #423. - Improved performance and data handling. - Improved NVML and AMD observers. - Improved signal handling.