Device

A device is an abstract representation of an XPU. The dpctl.SyclDevice class represents a device and is a wrapper over the sycl::device SYCL runtime class.

Creating Devices

The dpctl.SyclDevice class includes the default constructor to create a default device. This device is selected by the SYCL runtime. You can also use explicit filter selector strings to create a device.

Note

Refer to Device Selection for more information.

Listing Devices

dpctl provides the dpctl.get_devices() utility function to list the available devices on a user’s system. The list of devices returned depends on the available hardware, installed drivers, environment variables influencing SYCL runtime, such as SYCL_DEVICE_FILTER or SYCL_DEVICE_ALLOWLIST.

Listing Available Devices

import dpctl


    """Programmatically get a list of the available devices.

    The list can be filtered based on backend or device_type.
    """
    print("Get a list of all devices:\n")

    for d in dpctl.get_devices():
        d.print_device_info()
    print("=======================================\n")

    print("Get the list of only OpenCL devices:\n")

    for d in dpctl.get_devices(backend="opencl"):
        d.print_device_info()

    print("=======================================\n")

    print("Get all OpenCL CPU devices:\n")

    for d in dpctl.get_devices(backend="opencl", device_type="cpu"):
        d.print_device_info()

    print("=======================================\n")

A possible output for the Listing Available Devices example:

INFO: Executing example list_devices
Get a list of all devices:

    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

    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

=======================================

Get the list of only OpenCL devices:

    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

    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

=======================================

Get all OpenCL CPU devices:

    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: ===========================

The Listing Available Devices example demonstrates the usage of dpctl.get_devices().

You can filter the list based on the dpctl.backend and dpctl.device_type.

The 0-based ordinal position of a device in the output of dpctl.get_devices() corresponds to the device id value in the filter selector string corresponding to the device. For example, "opencl:cpu:0" refers to the first device in the list returned by dpctl.get_devices(backend="opencl", device_type="cpu"). If such a list is empty, device construction call dpctl.SyclDevice("opencl:gpu:0") raises a ValueError.

Note

Unless the system configuration changes, the list of devices returned by dpctl.get_devices() and the relative ordering of devices in the list is stable for every call to the function, even across different runs of an application.

Device Aspects and Information Descriptors

A device can have various aspects and information descriptors that describe its hardware characteristics:

• Aspects are boolean characteristics of the device

• information descriptors are non-boolean characteristics that provide more verbose information about the device

• dpctl.SyclDevice exposes various Python properties that describe a device’s aspects and information descriptors.

For example, the property has_aspect_fp16 returns a boolean expression indicating if:

• a particular device has the "fp16" aspect

• supports the IEEE-754 half-precision floating point type

The name property is an information descriptor that returns a string with the name of the device.

Listing Available Device Aspects and Information Descriptors

import dpctl
import inspect

def get_properties(cls, prop_name):
    "Get the name of properties of a class known to have `prop_name`"
    known_property_t = type(getattr(cls, prop_name))
    return [n for n, o in inspect.getmembers(cls) if isinstance(o, known_property_t)]

print(len(get_properties(dpctl.SyclDevice, "name")))
# Output: 52

The Listing Available Device Aspects and Information Descriptors example demonstrates a programmatic way to list all the aspects and information descriptor properties in dpctl.SyclDevice.

Sub-devices

You can partition a device into sub-devices.

A sub-device represents a subset of the computational units within a device that are grouped based on some hardware criteria. For example, you can partition a two-socket CPU into two sub-devices, where each sub-device represents a separate NUMA domain. Depending on the hardware characteristics and the capabilities of the SYCL runtime, a sub-device may be partitioned further.

For devices that support partitioning, you can use dpctl.SyclDevice.create_sub_devices() to create a list of sub-devices. The requested partitioning scheme is indicated with the usage of the required partition keyword.

Several types of partitioning schemes are available:

• Count partitioning

  The partitioning scheme is specified as a list of positive integers indicating a partitioning with each sub-device having the requested number of parallel compute units or as a single positive integer indicating equal-counts partition.

• Affinity partitioning

  The partitioning scheme is specified as a string indicating an affinity domain used to create sub-devices that share a common resource, such as certain hardware cache levels.

Note

Use partition="next_partitionable" to partition along the next level of architectural hierarchy.

The following example shows an affinity-based partitioning of a CPU device into sub-devices based on the available NUMA domains:

Partitioning a CPU device

import dpctl
def subdivide_by_affinity(affinity="numa"):
    """
    Create sub-devices partitioning by affinity.
    """
    cpu_d = dpctl.SyclDevice("cpu")
    try:
        sub_devs = cpu_d.create_sub_devices(partition=affinity)
        print(
            "{0} sub-devices were created with respective "
            "#EUs being {1}".format(
                len(sub_devs), [d.max_compute_units for d in sub_devs]
            )
        )
    except Exception:
        print("Device partitioning by affinity was not successful.")

A possible output for the Partitioning a CPU device example:

INFO: Executing example subdivide_by_affinity
Device partitioning by affinity was not successful.
INFO: ===========================