Intel Variant Provider Plugin

A variant provider plugin for the Wheel Variant upcoming proposed standard that enables automatic detection and selection of Intel GPU-optimized Python packages. This plugin is part of the WheelNext initiative to "Re-invent the Wheel" and Python package distribution for scientific and hardware-accelerated computing.

Compatibility with package managers

Important

This plugin implements support for the specification which is a work in progress and is not intended for production use. It is provided as-is, without guarantees or warranties, and may change, disappear, or stop working at any time.

There is no backward compatibility guarantees for the components implementing the proposed specification. Be careful selecting component versions. Below we outline tested combinations of components which are known to work.

At the moment packaging of the wheel variants and queries of the plugins list and their metadata is supported by the variantlib library. Intel Variant Provider Plugin is currently validated with the following version of variantlib:

• https://github.com/wheelnext/variantlib/commit/75bea8ef4886d5fd4d5282ee5ba6b45f48badd70

Package manager which supports proposed specification is needed to install variant wheels. The patched version of pip can be found here:

• https://github.com/wheelnext/pep_xxx_wheel_variants/tree/e44bf06c26872be158949f93fecb0c8ee762653e/pep_xxx_wheel_variants

The patched version of uv can be found here:

• astral-sh/uv#12203

Note that current efforts are focused on uv. Patches for pip are supported with the best efforts. Run the following to install compatible version of uv:

• On Linux:

curl -LsSf https://astral.sh/uv/install.sh | INSTALLER_DOWNLOAD_URL=https://wheelnext.astral.sh/v0.0.3 sh

• On Windows:

powershell -c { $env:INSTALLER_DOWNLOAD_URL = 'https://wheelnext.astral.sh/v0.0.3'; irm https://astral.sh/uv/install.ps1 | iex }

Provided Properties

intel::gt_gmdid

Values: 30.0.0, 30.0.4, ...

Specifies the GPU architecture (compute capability) the wheel is built for. Each value is a human readable form of Intel's GT (Graphics Technology) GMDID (Graphics Media Descriptor ID). In Intel documentation and driver APIs these values are also referenced as device IP (Intellectual Property) versions.

Detection

Detection is backed by Level Zero C++ API which is being utilized by the provider plugin loading the system installed Level Zero library via ctypes.CDLL() and querying the required information via designated Level Zero API. Note that the Level Zero library is a driver loader library. Actual hardware detection is done by the platform driver (user space library) identified and loaded by the Level Zero library.

OS	Level Zero loading details
Linux	libze_loader.so.1 is loaded with ctypes.CDLL() using default search algorithm. The ZE_extension_device_ip_version API is used to query for the GT GMDID values
Windows	ze_loader.dll is loaded with ctypes.CDLL() from $WINDIR\System32 with $WINDIR=C:\Windows being default

After Level Zero loading, the ZE_extension_device_ip_version API is used to query for the GT GMDID values.

Environment variables

INTEL_VARIANT_PROVIDER_FORCE_GT_GMDID allows to override GPU architecture detection performed by plugin. DISCLAIMER: this is debug and test purpose variable as it can lead to a non-functional installation.

WheelNext package index

WheelNext initiative supports aggregated index of the packages which are enabled with variant providers.

• Release index:

  • https://wheelnext.github.io/variants-index/

• Test index:

  • https://wheelnext.github.io/variants-index-test/

The WheelNext version of uv is configured to works with the release index from above.

Configuring Your Project

Add variant configuration to your pyproject.toml:

[variant.default-priorities]
namespace = ["intel"]

[variant.providers.intel]
requires = ["intel_variant_provider"]
enable-if = "platform_system == 'Linux' or platform_system == 'Windows'"
plugin-api = "intel_variant_provider.plugin:IntelVariantPlugin"

Intel GT GMDID Values

GT GMDID is an identifier assigned to differentiate architectures of compute platforms of Intel GPU devices. Few different Intel GPU devices (with the different device IDs) might be built on the same compute platform architecture.

Programmatically GT GMDID can be queried for each Intel GPU device using Level Zero ZE_extension_device_ip_version API. The returned Device IP Version value is the integer representation of GT GMDID on Intel platforms.

Intel offline compiler (ocloc) generates code for one or few target compute platforms passed in -device <device_type> argument. Each <device type> in the list can be set as GT GMDID or as respective platform acronym name internally mapped to the GT GMDID of the platform. To query GT GMDID for the specific acronym, ocloc ids command can be used. For example:

$ ocloc ids bmg
Matched ids:
20.1.0

$ ocloc ids xe3
Matched ids:
30.0.0
30.0.4
30.1.0
30.1.1

For Python package to target specific Intel architectures using XPU variant provider plugin, it's required to build package variants for these architectures and set intel::gt_gmdid::<gt_gmdid> properties accordingly. For the above example of bmg and xe3 that would be:

# for bmg variant:
intel::gt_gmdid::20.1.0

# for xe3 variant:
intel::gt_gmdid::30.0.0
intel::gt_gmdid::30.0.4
intel::gt_gmdid::30.1.0
intel::gt_gmdid::30.1.1

License

This project is licensed under the Apache 2 License - see the LICENSE file for details.