DOC: Better explanations about GPGPU driver installations #2464

david-cortes-intel · 2025-05-05T12:55:59Z

Description

This PR adds a better explanation of how to install the GPGPU drivers that are required for GPU mode.

PR should start as a draft, then move to ready for review state after CI is passed and all applicable checkboxes are closed.
This approach ensures that reviewers don't spend extra time asking for regular requirements.

You can remove a checkbox as not applicable only if it doesn't relate to this PR in any way.
For example, PR with docs update doesn't require checkboxes for performance while PR with any change in actual code should have checkboxes and justify how this code change is expected to affect performance (or justification should be self-evident).

Checklist to comply with before moving PR from draft:

PR completeness and readability

I have reviewed my changes thoroughly before submitting this pull request.
I have updated the documentation to reflect the changes or created a separate PR with update and provided its number in the description, if necessary.
Git commit message contains an appropriate signed-off-by string (see CONTRIBUTING.md for details).
I have added a respective label(s) to PR if I have a permission for that.
I have resolved any merge conflicts that might occur with the base branch.

Testing

I have run it locally and tested the changes extensively.
All CI jobs are green or I have provided justification why they aren't.

Performance

Not applicable.

codecov · 2025-05-05T14:15:40Z

Codecov Report

All modified and coverable lines are covered by tests ✅

Flag	Coverage Δ
azure	`79.76% <ø> (?)`
github	`73.58% <ø> (ø)`

Flags with carried forward coverage won't be shown. Click here to find out more.

see 37 files with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

doc/sources/oneapi-gpu.rst

Co-authored-by: Ian Faust <icfaust@gmail.com>

KateBlueSky · 2025-05-09T18:02:33Z

doc/sources/index.rst

@@ -29,7 +29,7 @@ The software acceleration is achieved with vector instructions, AI hardware-spec
 Use |sklearnex|, to:

 * Speed up training and inference by up to 100x with equivalent mathematical accuracy
-* Benefit from performance improvements across different x86-64 CPUs and Intel(R) GPUs
+* Benefit from performance improvements across different x86-64 CPUs and Intel(R) GPUs (including iGPUs)


Hi David for this would it be better just to say Intel(R) GPUs?

I would say reading "Intel(R) GPUs" to me at least doesn't immediately bring up the thought that it should work on the iGPUs that one might already have in a laptop.

My idea here is to make it explicit that the library still works on the kind of products that users might already have without knowing, and which might not have been even considered as a potential entry point for trying out the functionalities in the library.

i guess the question is - one is set of supported platforms for binary releases and second more broad in terms what overall support - this includes ARM, RISC and potentially some of the cases on non-intel gpus. there is questions of migration to oneMath for broader enabling but even without it some things can work

That's a good point, but this line right here is from the landing page of the docs with the short summary about what the library is for.

I don't think it'd make much sense to add points about ARM/RISC-V support in that specific section right now, because it requires building both oneDAL and sklearnex from source, with non-default arguments and dependencies in the case of oneDAL.

I agree with Kate here

KateBlueSky · 2025-05-09T18:04:32Z

doc/sources/oneapi-gpu.rst

@@ -19,19 +19,22 @@
 oneAPI and GPU support in |sklearnex|
 ##############################################################

-|sklearnex| can execute computations on different devices (CPUs, GPUs) through the SYCL framework in oneAPI.
+|sklearnex| can execute computations on different devices (CPUs and GPUs, including integrated GPUs from laptops and desktops) through the SYCL framework in oneAPI.


Same here maybe just say ((CPUs and GPUs) instead of (CPUs and GPUs, including integrated GPUs from laptops and desktops)

KateBlueSky · 2025-05-09T18:09:08Z

doc/sources/oneapi-gpu.rst

+GPGPU Drivers
+~~~~~~~~~~~~~
+
+On Windows, GPGPU drivers are bundled as part of the regular drivers for iGPUs and dGPUs, which can be downloaded from `this link <https://www.intel.com/content/www/us/en/download/785597/intel-arc-iris-xe-graphics-windows.html>`__.


Maybe instead of GPGPU you should GPU. Since all Intel GPUs are currently generalized gpus. Or maybe just reword this so it's.. "One Windows, gpu drivers for Intel® Arc™ & Iris® Xe Graphics can be downloaded here.."

I think that wouldn't be very obvious to people who are not familiar with the product suite already. Before joining Intel, I wouldn't have known that laptop iGPUs were called "Iris Xe", for example.

KateBlueSky · 2025-05-09T18:10:38Z

doc/sources/oneapi-gpu.rst

+For datacenters, see further instructions `here <https://www.intel.com/content/www/us/en/developer/articles/system-requirements/oneapi-dpcpp/2025.html#inpage-nav-2-1-1>`__.
+
+
+On Linux, some distributions - namely Ubuntu Desktop 25.04 and higher, and Fedora Workstation 42 and higher - come with the GPGPU drivers for iGPUs and dGPUs preinstalled, while others require installing them separately.


samething maybe just say gpu instead of GPGPU

KateBlueSky · 2025-05-09T18:12:33Z

doc/sources/oneapi-gpu.rst

+
+    sudo apt-get install intel-opencl-icd
+
+For Arch Linux, and for other distributions in general, see the `GPGPU article in the Arch wiki <https://wiki.archlinux.org/title/GPGPU>`__.


Also for this you might just want point the reader to the installation page for the Intel GPU driver install page. https://dgpu-docs.intel.com/driver/installation.html

Problems with that page are that: (a) it doesn't explain how to install the drivers in most of the supported platforms; (b) the drivers and processes it lists are mostly for datacenter GPUs.

KateBlueSky · 2025-05-09T18:13:10Z

doc/sources/quick-start.rst

@@ -319,7 +319,7 @@ Software Requirements
   .. tab:: GPU

      - A Linux* or Windows* version supported by DPC++ and oneMKL
-      - Intel® GPGPU drivers
+      - Intel® GPGPU drivers (see :ref:`oneapi_gpu`)


Here just say GPU instead of GPGPU.

They are actually different if I'm getting it correctly. The regular GPU drivers that come with MESA don't work for GPGPU.

It's also how the DCP++ page describes them:

KateBlueSky · 2025-05-09T18:14:44Z

Hi @david-cortes-intel I left a couple of comments other that lgtm

napetrov · 2025-05-12T15:03:12Z

doc/sources/oneapi-gpu.rst


-While not strictly required, package |dpctl| is recommended for a better experience on GPUs.
+While not strictly required, package |dpctl| is recommended for a better experience on GPUs - for example, it can provide GPU-allocated arrays so that ``target_offload`` wouldn't need to move the data from CPU to GPU.


As an option you can use "compute follows data" name to describe it as well.

napetrov · 2025-05-12T15:03:31Z

doc/sources/oneapi-gpu.rst


 Prerequisites
 -------------

 For execution on GPUs, DPC++ runtime and GPGPU drivers are required.

+DPC++


Might worth to replace it to SYCL

But it does require the software called "DPC++ runtime":
https://anaconda.org/conda-forge/dpcpp-cpp-rt

ethanglaser

Not much feedback here but generally agree with Kate's comments

ethanglaser · 2025-05-15T18:17:19Z

doc/sources/index.rst

@@ -29,7 +29,7 @@ The software acceleration is achieved with vector instructions, AI hardware-spec
 Use |sklearnex|, to:

 * Speed up training and inference by up to 100x with equivalent mathematical accuracy
-* Benefit from performance improvements across different x86-64 CPUs and Intel(R) GPUs
+* Benefit from performance improvements across different x86-64 CPUs and Intel(R) GPUs (including iGPUs)


I agree with Kate here

ethanglaser · 2025-05-15T18:17:29Z

doc/sources/oneapi-gpu.rst

@@ -19,19 +19,22 @@
 oneAPI and GPU support in |sklearnex|
 ##############################################################

-|sklearnex| can execute computations on different devices (CPUs, GPUs) through the SYCL framework in oneAPI.
+|sklearnex| can execute computations on different devices (CPUs and GPUs, including integrated GPUs from laptops and desktops) through the SYCL framework in oneAPI.


david-cortes-intel · 2025-05-22T14:20:28Z

@ethanglaser @KateBlueSky Some comments:

When it comes to consumer-grade GPUs, there is a separation between the regular GPU drivers and what is required to execute GPGPU code with SYCL. On linux at least, the consumer-grade GPU drivers come from the MESA packages, while executing SYCL code requires other packages like 'intel-compute-runtime', 'intel-graphics-compiler', etc. (which are specified neither as 'depends' nor 'recommends' for regular drivers), in addition to the DPC++ runtime. These do not appear to be explicitly called "GPGPU drivers", but that's how DPC++ at least refers to them.
There isn't any Intel webpage explaining how to install drivers for all GPGPU-capable devices in all the platforms that are supported. Some oneAPI products link to the generic support page for products (like https://www.intel.com/content/www/us/en/download/747008/intel-arc-graphics-driver-ubuntu.html?wapkw=intel%20arc%20a770), which does not have any instruction for installing required GPGPU software on linux; while others link to the page for DC-grade devices (https://dgpu-docs.intel.com/driver/installation.html) which does not explain how to install the GPGPU software for iGPUs or ARC cards, and does not explain how to install what they offer in most of the platforms that are supported, such as newer versions of Ubuntu or Fedora.
We currently have quite a bad structuring of the docs, with some things being spread throughout different pages (like system requirements, GPU instructions, installation instructions, etc.). As it currently is, this PR tries to add visibility about consumer-grade GPU support in this library, which will only be noticeable when added to the GPU docs. Ideally, details like which kinds of devices are supported should be put in the same page as the instructions for running on GPUs, but that would be a much deeper scope of changes for docs.

doc/sources/oneapi-gpu.rst

ethanglaser · 2025-06-27T05:35:56Z

doc/sources/oneapi-gpu.rst

+
+    sudo apt-get install intel-opencl-icd
+
+.. tip:: For Debian Trixie (13), the Intel Compute Runtime is not available from the Stable repository, but can be installed by enabling the Sid (Unstable) repository.


Are stable and unstable actual names/proper nouns here or should they be lowercase?

They aren't, but that kind of usage is common throughout docs:
https://wiki.debian.org/SourcesList

ethanglaser

Looks good to me now, just a few minor tweaks that would slightly improve readability

Co-authored-by: ethanglaser <42726565+ethanglaser@users.noreply.github.com>

more details about GPGPU drivers

043e750

david-cortes-intel added the documentation label May 5, 2025

david-cortes-intel requested review from maria-Petrova, napetrov, Alexsandruss and icfaust as code owners May 5, 2025 12:56

advertise iGPU compat more visibly

7d18320

icfaust reviewed May 5, 2025

View reviewed changes

doc/sources/oneapi-gpu.rst Outdated Show resolved Hide resolved

doc/sources/oneapi-gpu.rst Outdated Show resolved Hide resolved

david-cortes-intel and others added 3 commits May 5, 2025 16:57

Update doc/sources/oneapi-gpu.rst

64e3b95

Co-authored-by: Ian Faust <icfaust@gmail.com>

Update doc/sources/oneapi-gpu.rst

9184739

Co-authored-by: Ian Faust <icfaust@gmail.com>

add link to arch wiki and more details

21c3129

david-cortes-intel requested review from ahuber21, Vika-F and avolkov-intel May 8, 2025 12:51

KateBlueSky reviewed May 9, 2025

View reviewed changes

napetrov reviewed May 12, 2025

View reviewed changes

reword compute-follows-data idea

41119fe

ethanglaser reviewed May 15, 2025

View reviewed changes

david-cortes-intel added 3 commits June 4, 2025 07:31

Merge branch 'main' into update_gpu_docs

d9c52f7

Merge branch 'main' into update_gpu_docs

e1cbdd0

reword 'gpgpu drivers' -> 'compute runtime'

e30f412

david-cortes-intel requested review from syakov-intel and yuejiaointel as code owners June 23, 2025 16:20

david-cortes-intel requested review from ethanglaser and KateBlueSky June 26, 2025 10:00

ethanglaser reviewed Jun 27, 2025

View reviewed changes

doc/sources/oneapi-gpu.rst Outdated Show resolved Hide resolved

ethanglaser reviewed Jun 27, 2025

View reviewed changes

ethanglaser approved these changes Jun 27, 2025

View reviewed changes

Update doc/sources/oneapi-gpu.rst

70b091a

Co-authored-by: ethanglaser <42726565+ethanglaser@users.noreply.github.com>

david-cortes-intel merged commit 2fdba34 into uxlfoundation:main Jun 27, 2025
5 checks passed

		For datacenters, see further instructions `here <https://www.intel.com/content/www/us/en/developer/articles/system-requirements/oneapi-dpcpp/2025.html#inpage-nav-2-1-1>`__.


		On Linux, some distributions - namely Ubuntu Desktop 25.04 and higher, and Fedora Workstation 42 and higher - come with the GPGPU drivers for iGPUs and dGPUs preinstalled, while others require installing them separately.


		sudo apt-get install intel-opencl-icd

		For Arch Linux, and for other distributions in general, see the `GPGPU article in the Arch wiki <https://wiki.archlinux.org/title/GPGPU>`__.


		While not strictly required, package \|dpctl\| is recommended for a better experience on GPUs.
		While not strictly required, package \|dpctl\| is recommended for a better experience on GPUs - for example, it can provide GPU-allocated arrays so that ``target_offload`` wouldn't need to move the data from CPU to GPU.


		sudo apt-get install intel-opencl-icd

		.. tip:: For Debian Trixie (13), the Intel Compute Runtime is not available from the Stable repository, but can be installed by enabling the Sid (Unstable) repository.

DOC: Better explanations about GPGPU driver installations #2464

DOC: Better explanations about GPGPU driver installations #2464

Uh oh!

Conversation

david-cortes-intel commented May 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Uh oh!

codecov bot commented May 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

david-cortes-intel May 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

KateBlueSky commented May 9, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ethanglaser left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

david-cortes-intel commented May 22, 2025

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ethanglaser left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

david-cortes-intel commented May 5, 2025 •

edited

Loading

codecov bot commented May 5, 2025 •

edited

Loading

david-cortes-intel May 12, 2025 •

edited

Loading

ethanglaser left a comment •

edited

Loading

ethanglaser left a comment •

edited

Loading