dpctl.SyclDevice¶

class dpctl.SyclDevice(arg=None)¶

Python equivalent for cl::sycl::device class.

There are two ways of creating a SyclDevice instance:

by directly passing in a filter string to the class constructor. The filter string needs to conform to the DPC++ filter selector SYCL extension.
Example
import dpctl

# Create a SyclDevice with an explicit filter string,
# in this case the first level_zero gpu device.
level_zero_gpu = dpctl.SyclDevice("level_zero:gpu:0"):
level_zero_gpu.print_device_info()
by calling one of the device selector helper functions:

dpctl.select_accelerator_device(), dpctl.select_cpu_device(), dpctl.select_default_device(), dpctl.select_gpu_device(), dpctl.select_host_device().
Example
import dpctl

# Create a SyclDevice of type GPU based on whatever is returned
# by the SYCL `gpu_selector` device selector class.
gpu = dpctl.select_gpu_device():
gpu.print_device_info()

Attributes:

`backend`	Returns the backend_type enum value for this device
`default_selector_score`
`device_type`	Returns the type of the device as a device_type enum.
`driver_version`	Returns a backend-defined driver version as a string.
`filter_string`	For a parent device, returns a fully specified filter selector string``backend:device_type:relative_id`` selecting the device.
`has_aspect_accelerator`
`has_aspect_cpu`
`has_aspect_custom`
`has_aspect_fp16`
`has_aspect_fp64`
`has_aspect_gpu`
`has_aspect_host`
`has_aspect_image`
`has_aspect_int64_base_atomics`
`has_aspect_int64_extended_atomics`
`has_aspect_online_compiler`
`has_aspect_online_linker`
`has_aspect_queue_profiling`
`has_aspect_usm_device_allocations`
`has_aspect_usm_host_allocations`
`has_aspect_usm_restricted_shared_allocations`
`has_aspect_usm_shared_allocations`
`has_aspect_usm_system_allocator`
`image_2d_max_height`	Returns the maximum height of a 2D image or 1D image in pixels.
`image_2d_max_width`	Returns the maximum width of a 2D image or 1D image in pixels.
`image_3d_max_depth`	Returns the maximum depth of a 3D image in pixels.
`image_3d_max_height`	Returns the maximum height of a 3D image in pixels.
`image_3d_max_width`	Returns the maximum width of a 3D image in pixels.
`is_accelerator`	Returns True if the SyclDevice instance is a SYCL accelerator device.
`is_cpu`	Returns True if the SyclDevice instance is a SYCL CPU device.
`is_gpu`	Returns True if the SyclDevice instance is a SYCL GPU device.
`is_host`	Returns True if the SyclDevice instance is a SYCL host device.
`max_compute_units`	Returns the number of parallel compute units available to the device.
`max_num_sub_groups`	Returns the maximum number of sub-groups in a work-group for any kernel executed on the device.
`max_read_image_args`	Returns the maximum number of simultaneous image objects that can be read from by a kernel.
`max_work_group_size`	Returns the maximum number of work-items that are permitted in a work-group executing a kernel on a single compute unit.
`max_work_item_dims`	Returns the maximum dimensions that specify the global and local work-item IDs used by the data parallel execution model.
`max_work_item_sizes`	Returns the maximum number of work-items that are permitted in each dimension of the work-group of the nd_range.
`max_write_image_args`	Returns the maximum number of simultaneous image objects that can be written to by a kernel.
`name`	Returns the name of the device as a string
`parent_device`	Parent device for a sub-device, or None for a root device.
`preferred_vector_width_char`	Returns the preferred native vector width size for built-in scalar types that can be put into vectors.
`preferred_vector_width_double`	Returns the preferred native vector width size for built-in scalar types that can be put into vectors.
`preferred_vector_width_float`	Returns the preferred native vector width size for built-in scalar types that can be put into vectors.
`preferred_vector_width_half`	Returns the preferred native vector width size for built-in scalar types that can be put into vectors.
`preferred_vector_width_int`	Returns the preferred native vector width size for built-in scalar types that can be put into vectors.
`preferred_vector_width_long`	Returns the preferred native vector width size for built-in scalar types that can be put into vectors.
`preferred_vector_width_short`	Returns the preferred native vector width size for built-in scalar types that can be put into vectors.
`sub_group_independent_forward_progress`	Returns true if the device supports independent forward progress of sub-groups with respect to other sub-groups in the same work-group.
`vendor`	Returns the device vendor name as a string.

Public methods:

`addressof_ref`	Returns the address of the `DPCTLSyclDeviceRef` pointer as a `size_t`.
`create_sub_devices`([partition])	Creates a list of sub-devices by partitioning a root device based on the provided partion specifier.
`get_filter_string`([include_backend, …])	For a parent device, returns a filter selector string that includes backend or device type based on the value of the given keyword arguments.
`print_device_info`	Print information about the SYCL device.

Detail¶

Attributes¶

SyclDevice.backend¶

Returns the backend_type enum value for this device

Returns: The backend for the device.
Return type: backend_type

SyclDevice.default_selector_score¶

SyclDevice.device_type¶

Returns the type of the device as a device_type enum.

Returns: The type of device encoded as a device_type enum.
Return type: device_type
Raises: A ValueError is raised if the device type is not recognized. –

SyclDevice.driver_version¶

Returns a backend-defined driver version as a string.

Returns: The driver version of the device as a string.
Return type: str

SyclDevice.filter_string¶

For a parent device, returns a fully specified filter selector string``backend:device_type:relative_id`` selecting the device.

Returns

A Python string representing a filter selector string.

Return type

str

Raises

TypeError – If the device is a sub-devices.

Example

import dpctl

# Create a SyclDevice with an explicit filter string,
# in this case the first level_zero gpu device.
level_zero_gpu = dpctl.SyclDevice("level_zero:gpu:0")
# filter_string property should be "level_zero:gpu:0"
dev = dpctl.SyclDevice(level_zero_gpu.filter_string)
assert level_zero_gpu == dev

SyclDevice.has_aspect_accelerator¶

SyclDevice.has_aspect_cpu¶

SyclDevice.has_aspect_custom¶

SyclDevice.has_aspect_fp16¶

SyclDevice.has_aspect_fp64¶

SyclDevice.has_aspect_gpu¶

SyclDevice.has_aspect_host¶

SyclDevice.has_aspect_image¶

SyclDevice.has_aspect_int64_base_atomics¶

SyclDevice.has_aspect_int64_extended_atomics¶

SyclDevice.has_aspect_online_compiler¶

SyclDevice.has_aspect_online_linker¶

SyclDevice.has_aspect_queue_profiling¶

SyclDevice.has_aspect_usm_device_allocations¶

SyclDevice.has_aspect_usm_host_allocations¶

SyclDevice.has_aspect_usm_restricted_shared_allocations¶

SyclDevice.has_aspect_usm_shared_allocations¶

SyclDevice.has_aspect_usm_system_allocator¶

SyclDevice.image_2d_max_height¶: Returns the maximum height of a 2D image or 1D image in pixels. The minimum value is 8192 if the SYCL device has aspect::image.

SyclDevice.image_2d_max_width¶: Returns the maximum width of a 2D image or 1D image in pixels. The minimum value is 8192 if the SYCL device has aspect::image.

SyclDevice.image_3d_max_depth¶: Returns the maximum depth of a 3D image in pixels. The minimum value is 2048 if the SYCL device has aspect::image.

SyclDevice.image_3d_max_height¶: Returns the maximum height of a 3D image in pixels. The minimum value is 2048 if the SYCL device has aspect::image.

SyclDevice.image_3d_max_width¶: Returns the maximum width of a 3D image in pixels. The minimum value is 2048 if the SYCL device has aspect::image.

SyclDevice.is_accelerator¶

Returns True if the SyclDevice instance is a SYCL accelerator device.

Returns: True if the SyclDevice is a SYCL accelerator device, else False.
Return type: bool

SyclDevice.is_cpu¶

Returns True if the SyclDevice instance is a SYCL CPU device.

Returns: True if the SyclDevice is a SYCL CPU device, else False.
Return type: bool

SyclDevice.is_gpu¶

Returns True if the SyclDevice instance is a SYCL GPU device.

Returns: True if the SyclDevice is a SYCL GPU device, else False.
Return type: bool

SyclDevice.is_host¶

Returns True if the SyclDevice instance is a SYCL host device.

Returns: True if the SyclDevice is a SYCL host device, else False.
Return type: bool

SyclDevice.max_compute_units¶: Returns the number of parallel compute units available to the device. The minimum value is 1.

SyclDevice.max_num_sub_groups¶

Returns the maximum number of sub-groups in a work-group for any kernel executed on the device. The minimum value is 1.

Returns: The maximum number of sub-groups support per work-group by the device.
Return type: int

SyclDevice.max_read_image_args¶: Returns the maximum number of simultaneous image objects that can be read from by a kernel. The minimum value is 128 if the SYCL device has aspect::image.

SyclDevice.max_work_group_size¶: Returns the maximum number of work-items that are permitted in a work-group executing a kernel on a single compute unit. The minimum value is 1.

SyclDevice.max_work_item_dims¶

Returns the maximum dimensions that specify the global and local work-item IDs used by the data parallel execution model.

The cb value is 3 if this SYCL device is not of device type info::device_type::custom.

SyclDevice.max_work_item_sizes¶: Returns the maximum number of work-items that are permitted in each dimension of the work-group of the nd_range. The minimum value is (1; 1; 1) for devices that are not of device type info::device_type::custom.

SyclDevice.max_write_image_args¶: Returns the maximum number of simultaneous image objects that can be written to by a kernel. The minimum value is 8 if the SYCL device has aspect::image.

SyclDevice.name¶

Returns the name of the device as a string

Returns: The name of the device as a string.
Return type: str

SyclDevice.parent_device¶

Parent device for a sub-device, or None for a root device.

Returns: A parent dpctl.SyclDevice instance if the device is a sub-device, None otherwise.
Return type: dpctl.SyclDevice

SyclDevice.preferred_vector_width_char¶: Returns the preferred native vector width size for built-in scalar types that can be put into vectors.

SyclDevice.preferred_vector_width_double¶: Returns the preferred native vector width size for built-in scalar types that can be put into vectors.

SyclDevice.preferred_vector_width_float¶: Returns the preferred native vector width size for built-in scalar types that can be put into vectors.

SyclDevice.preferred_vector_width_half¶: Returns the preferred native vector width size for built-in scalar types that can be put into vectors.

SyclDevice.preferred_vector_width_int¶: Returns the preferred native vector width size for built-in scalar types that can be put into vectors.

SyclDevice.preferred_vector_width_long¶: Returns the preferred native vector width size for built-in scalar types that can be put into vectors.

SyclDevice.preferred_vector_width_short¶: Returns the preferred native vector width size for built-in scalar types that can be put into vectors.

SyclDevice.sub_group_independent_forward_progress¶: Returns true if the device supports independent forward progress of sub-groups with respect to other sub-groups in the same work-group.

SyclDevice.vendor¶

Returns the device vendor name as a string.

Returns: The vendor name for the device as a string.
Return type: str

Public methods¶

dpctl.SyclDevice.addressof_ref()¶

Returns the address of the DPCTLSyclDeviceRef pointer as a size_t.

Returns: The address of the DPCTLSyclDeviceRef object used to create this dpctl.SyclDevice cast to a size_t.
Return type: int

dpctl.SyclDevice.create_sub_devices(partition=parition_spec)¶

Creates a list of sub-devices by partitioning a root device based on the provided partion specifier.

A partition specifier must be provided using a “partition” keyword argument. Possible values for the specifier are: an int, a string specifying the affinity domain, or a collection of ints.

Example

import dpctl

cpu_d = dpctl.SyclDevice("cpu")
cpu_count = cpu_d.max_compute_units
sub_devs = cpu_d.create_sub_devices(partition=cpu_count // 2)
for d in sub_devs:
    d.print_device_info()

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

Parameters

partition –

Specification to partition the device as follows:

Specifying an int (count). The returned list contains as many sub-devices as can be created such that each sub-device contains count compute units. If the device’s total number of compute units is not evenly divided by count, then the remaining compute units are not included in any of the sub-devices.
Specifying an affinity domain as a string. The supported values are: numa, L4_cache, L3_cache, L2_cache, L1_cache, next_partitionable.
Specifying a collection of int values. For each non-zero value M in the collection, a sub-device with M compute units is created.

Returns

List of dpctl.SyclDevice objects

Return type

list

Raises

TypeError – If the “partition” keyword arg is not specified or the affinity domain string is not legal or is not one of the three supported options.

dpctl.SyclDevice.get_filter_string(include_backend=True, include_device_type=True)¶

For a parent device, returns a filter selector string that includes backend or device type based on the value of the given keyword arguments.

Parameters

include_backend (optional) – Defaults to True. A boolean flag indicating if the backend should be included in the filter string.
include_device_type (optional) – Defaults to True. A boolean flag indicating if the device type should be included in the filter string.

Returns

A Python string representing a filter selector string.

Return type

str

Raises

TypeError – If the device is a sub-device.
ValueError – If no match for the device was found in the vector returned by sycl::device::get_devices()

Example

import dpctl

# Create a GPU SyclDevice
gpu_dev = dpctl.SyclDevice("gpu:0")
# filter string should be "gpu:0"
fs = gpu_dev.get_filter_string(use_backend=False)
dev = dpctl.SyclDevice(fs)
assert gpu _dev == dev

dpctl.SyclDevice.print_device_info()¶: Print information about the SYCL device.