Device Selection

Device selection refers to programmatically selecting a single device from the set of devices available on the system.

Selecting a Specific Type of Device

If you need to select a specific type of device, such as a GPU, use one of the helper functions included inside dpctl` directly. Dpctl includes helper functions for selecting:

host
cpu
gpu
accelerator
default device

These functions are analogous to SYCL built-in sycl::device_selector classes. The scoring and selection of a specific device when multiple devices of the same type are available on a system are deferred to the underlying SYCL runtime.

The example Selecting a GPU Device shows the usage of the dpctl.select_gpu_device() device selection function. In case when multiple GPU devices are available, only one is returned based on the underlying scoring logic inside of the SYCL runtime. If the selection function is unable to select a device, a ValueError is raised.

Selecting a GPU Device

import dpctl

def create_gpu_device():
    """
    Create a GPU device.

    Device created can be influenced by environment variable
    SYCL_DEVICE_FILTER, which determines SYCL devices seen by the
    SYCL runtime.
    """
    try:
        d1 = dpctl.SyclDevice("gpu")
        d2 = dpctl.select_gpu_device()
        assert d1 == d2
        d1.print_device_info()
    except dpctl.SyclDeviceCreationError:
        print("A GPU device is not available on the system")

A possible output for the Selecting a GPU Device example:

INFO: Executing example create_gpu_device
A GPU device is not available on the system
INFO: ===========================

Selecting a Device Using a Filter String

Along with using the default device selection functions, a more explicit way of device selection involves the usage of filter strings. Refer to oneAPI filter selection extension to learn more.

The Selecting a GPU Device example also demonstrates the usage of a filter string to create a GPU device directly. Using a filter string allows much more fine-grained control for selecting a device.

The following Device Creation With Filter Strings example demonstrates the usage of the device selection using filter strings.

Device Creation With Filter Strings

import dpctl

def select_using_filter():
    """
    Demonstrate the usage of a filter string to create a SyclDevice.

    """
    try:
        d1 = dpctl.SyclDevice("cpu")
        d1.print_device_info()
    except dpctl.SyclDeviceCreationError:
        print("A CPU type device is not available on the system")

    try:
        d1 = dpctl.SyclDevice("opencl:cpu:0")
        d1.print_device_info()
    except dpctl.SyclDeviceCreationError:
        print("An OpenCL CPU driver needs to be installed on the system")

    d1 = dpctl.SyclDevice("0")
    d1.print_device_info()

    try:
        d1 = dpctl.SyclDevice("gpu")
        d1.print_device_info()
    except dpctl.SyclDeviceCreationError:
        print("A GPU type device is not available on the system")


if __name__ == "__main__":
    import _runner as runner

    runner.run_examples("Filter selection examples for dpctl.", globals())

A possible output for the Device Creation With Filter Strings example:

INFO: Executing example select_using_filter
    Name            AMD EPYC 7763 64-Core Processor                
    Driver version  2023.16.12.0.12_195853.xmain-hotfix
    Vendor          Intel(R) Corporation
    Filter string   opencl:cpu:0

    Name            AMD EPYC 7763 64-Core Processor                
    Driver version  2023.16.12.0.12_195853.xmain-hotfix
    Vendor          Intel(R) Corporation
    Filter string   opencl:cpu:0

    Name            Intel(R) FPGA Emulation Device
    Driver version  2023.16.12.0.12_195853.xmain-hotfix
    Vendor          Intel(R) Corporation
    Filter string   opencl:accelerator:0

A GPU type device is not available on the system
INFO: ===========================

It is also possible to pass a list of devices using a filter string. The Selecting a GPU Device if Available example demonstrates this use case. The filter string gpu,cpu implies that a GPU should be selected if available, otherwise a CPU device should be selected.

Selecting a GPU Device if Available

import dpctl

def create_gpu_device_if_present():
    """
    Select from union of two selections using default_selector.
    If a GPU device is available, it will be selected, if not,
    a CPU device will be selected, if available, otherwise an error
    will be raised.

    Device created can be influenced by environment variable
    SYCL_DEVICE_FILTER, which determines SYCL devices seen by the
    SYCL runtime.
    """
    d = dpctl.SyclDevice("gpu,cpu")
    print("Selected " + ("GPU" if d.is_gpu else "CPU") + " device")

A possible output for the Selecting a GPU Device if Available example:

INFO: Executing example create_gpu_device_if_present
Selected CPU device
INFO: ===========================

A filter string is a three-tuple that may specify the backend, device type, and device number as a colon (:) separated string.

String	Usage	Values
backend	Specifies the type of device driver.	`host`, `opencl`, `level-zero`, `cuda`
device type	Specifies the type of device.	`host`, `gpu`, `cpu`, `accelerator`
device number	Specifies the ordinality of the device in the listing of devices as determined by the SYCL* runtime.	Numeric value

The backend, device type, and device number value are optional but provide at least one of them. That is, opencl:gpu:0, gpu:0, gpu, 0, and opencl:0 are all valid filter strings.

The device listing including the device number value remains stable for a given system unless the driver configuration is changed or the SYCL runtime setting is changed using the SYCL_DEVICE_FILTER environment variable. Refer to oneAPI filter selection extension for more information.

Advanced Device Selection

Real-world applications may require more precise control over device selection. Dpctl helps you to accomplish more advanced device selection.

Custom Device Selection

import dpctl

def custom_select_device():
    """
    Programmatically select among available devices.

    Device created can be influenced by environment variable
    SYCL_DEVICE_FILTER, which determines SYCL devices seen by the
    SYCL runtime.
    """
    # select devices that support half-precision computation
    devs = [d for d in dpctl.get_devices() if d.has_aspect_fp16]
    # choose the device with highest default_selector score
    max_score = 0
    selected_dev = None
    for d in devs:
        if d.default_selector_score > max_score:
            max_score = d.default_selector_score
            selected_dev = d
    if selected_dev:
        selected_dev.print_device_info()
    else:
        print("No device with half-precision support is available.")
    return selected_dev

The Custom Device Selection example shows a way of selecting a device based on a specific hardware property. The process is the following:

The dpctl.get_devices() returns a list of all root devices on the system.

2. Out of that list the devices that support half-precision floating-point arithmetic are selected. 3. A “score” computed using the SYCL8 runtime’s default device scoring logic that is stored in dpctl.SyclDevice.default_selector_score is used to select a single device.

Refer to the dpctl.SyclDevice documentation for a list of hardware properties that may be used for device selection.

Note

A root device implies an unpartitioned device. A root device can be partitioned into two or more sub-devices based on various criteria. For example, a CPU device with multiple NUMA domains may be partitioned into multiple sub-devices, each representing a sub-device.

A convenience function dpctl.select_device_with_aspects() is available, which makes it easy to select a device based on a set of specific aspects. The Device Selection Using Aspects example selects a device that supports double precision arithmetic and SYCL USM shared memory allocation.

Device Selection Using Aspects

import dpctl

def create_device_with_aspects():
    """
    Programmatically select a device based on specific set of aspects.

    Demonstrate the usage of :func:`dpctl.select_device_with_aspects()`.
    """
    dev = dpctl.select_device_with_aspects(
        required_aspects=["fp64", "usm_shared_allocations"]
    )
    dev.print_device_info()

A possible output for the Device Selection Using Aspects example:

INFO: Executing example create_device_with_aspects
    Name            AMD EPYC 7763 64-Core Processor                
    Driver version  2023.16.12.0.12_195853.xmain-hotfix
    Vendor          Intel(R) Corporation
    Filter string   opencl:cpu:0

INFO: ===========================