dpctl.SyclDevice

class dpctl.SyclDevice(arg=None)

A Python wrapper for the sycl::device C++ 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(),
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()

Parameters:

arg (optional) – The argument can be a selector string or None. Defaults to None.

Raises:

MemoryError – If the constructor could not allocate necessary temporary memory.
SyclDeviceCreationError – If the dpctl.SyclDevice object creation failed.
TypeError – If the list of dpctl.SyclDevice objects was empty, or the input capsule contained a null pointer or could not be renamed.

Attributes:

`backend`	Returns the backend_type enum value for this device
`default_selector_score`	Integer score assigned to this device by DPC++ runtime's default scoring function.
`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 root device, returns a fully specified filter selector string `"backend:device_type:relative_id"` selecting the device.
`global_mem_cache_line_size`	Global device memory cache line size.
`global_mem_cache_size`	Global device memory cache size.
`global_mem_cache_type`	Global device cache memory type.
`global_mem_size`	Returns the size of global memory on this device in bytes.
`has_aspect_accelerator`	Returns True if this device is an accelerator device, False otherwise.
`has_aspect_atomic64`	Returns true if the device supports a basic set of atomic operations, False otherwise.
`has_aspect_cpu`	Returns True if this device is a CPU device, False otherwise.
`has_aspect_custom`	Returns True if this device is a custom device, False otherwise.
`has_aspect_fp16`	Returns True if the device supports half-precision floating point operations, False otherwise.
`has_aspect_fp64`	Returns True if the device supports 64-bit precision floating point operations, False otherwise.
`has_aspect_gpu`	Returns True if this device is a GPU device, False otherwise.
`has_aspect_host_debuggable`	Returns True if kernels running on this device can be debugged using standard debuggers that are normally available on the host system, False otherwise
`has_aspect_image`	Returns True if the device supports images, False otherwise (refer Sec 4.7.3 of SYCL 2020 spec).
`has_aspect_online_compiler`	Returns True if this device supports online compilation of device code, False otherwise.
`has_aspect_online_linker`	Returns True if this device supports online linking of device code, False otherwise.
`has_aspect_queue_profiling`	Returns True if this device supports queue profiling, False otherwise.
`has_aspect_usm_atomic_host_allocations`	Returns True if this device supports USM-host allocations and the host and this device may concurrently access and atomically modify host allocations, False otherwise.
`has_aspect_usm_atomic_shared_allocations`	Returns True if this device supports USM-shared allocations and the host and other devices in the same context as this device may concurrently access and atomically modify shared allocations, False otherwise
`has_aspect_usm_device_allocations`	Returns True if this device supports explicit USM allocations, False otherwise (refer Section 4.8 of SYCL 2020 specs).
`has_aspect_usm_host_allocations`	Returns True if this device can access USM-host memory, False otherwise (refer Section 4.8 of SYCL 2020 specs).
`has_aspect_usm_shared_allocations`	Returns True if this device supports USM-shared memory allocated on the same device, False otherwise.
`has_aspect_usm_system_allocations`	Returns True if system allocator may be used instead of SYCL USM allocation mechanism for USM-shared allocations on this device, False otherwise.
`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.
`local_mem_size`	Returns the size of local memory on this device in bytes.
`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_work_item_sizes1d`	Returns the maximum number of work-items that are permitted in each dimension of the work-group of the nd_range<1>.
`max_work_item_sizes2d`	Returns the maximum number of work-items that are permitted in each dimension of the work-group of the nd_range<2>.
`max_work_item_sizes3d`	Returns the maximum number of work-items that are permitted in each dimension of the work-group of the nd_range<3>.
`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
`native_vector_width_char`	Returns the native ISA vector width size for built-in scalar types that can be put into vectors.
`native_vector_width_double`	Returns the native ISA vector width size for built-in scalar types that can be put into vectors.
`native_vector_width_float`	Returns the native ISA vector width size for built-in scalar types that can be put into vectors.
`native_vector_width_half`	Returns the native ISA vector width size for built-in scalar types that can be put into vectors.
`native_vector_width_int`	Returns the native ISA vector width size for built-in scalar types that can be put into vectors.
`native_vector_width_long`	Returns the native ISA vector width size for built-in scalar types that can be put into vectors.
`native_vector_width_short`	Returns the native ISA vector width size for built-in scalar types that can be put into vectors.
`parent_device`	Parent device for a sub-device, or None for a root device.
`partition_max_sub_devices`	The maximum number of sub-devices this `dpctl.SyclDevice` instance can be partitioned into.
`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.
`profiling_timer_resolution`	Profiling timer resolution.
`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.
`sub_group_sizes`	Returns list of supported sub-group sizes for this device.
`sycl_platform`	Returns the platform associated with this device.
`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 partition 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.

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: Integer score assigned to this device by DPC++ runtime’s default scoring function. Score of -1 denotes that this device was rejected and may not be properly programmed by the DPC++ runtime.

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:: ValueError – 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 root 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-device.

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.global_mem_cache_line_size

Global device memory cache line size.

Returns:: Cache size in bytes
Return type:: int

SyclDevice.global_mem_cache_size

Global device memory cache size.

Returns:: Cache size in bytes
Return type:: int

SyclDevice.global_mem_cache_type

Global device cache memory type.

Returns:: type of cache memory
Return type:: global_mem_cache_type
Raises:: RuntimeError – If an unrecognized memory type is reported by runtime.

SyclDevice.global_mem_size: Returns the size of global memory on this device in bytes.

SyclDevice.has_aspect_accelerator

Returns True if this device is an accelerator device, False otherwise.

SYCL considers an accelerator to be a device that usually uses a peripheral interconnect for communication.

Returns:: Indicates if the device is an accelerator.
Return type:: bool

SyclDevice.has_aspect_atomic64

Returns true if the device supports a basic set of atomic operations, False otherwise.

Indicates that the device supports the following atomic operations on 64-bit values:

atomic::load

atomic::store

atomic::fetch_add

atomic::fetch_sub

atomic::exchange

atomic::compare_exchange_strong

atomic::compare_exchange_weak

Returns:: Indicates that the device supports a basic set of atomic operations on 64-bit values.
Return type:: bool

SyclDevice.has_aspect_cpu

Returns True if this device is a CPU device, False otherwise.

Returns:: Indicates if the device is a cpu.
Return type:: bool

SyclDevice.has_aspect_custom

Returns True if this device is a custom device, False otherwise.

A custom device can be a dedicated accelerator that can use the SYCL API, but programmable kernels cannot be dispatched to the device, only fixed functionality is available. Refer SYCL spec for more details.

Returns:: Indicates if the device is a custom SYCL device.
Return type:: bool

SyclDevice.has_aspect_fp16

Returns True if the device supports half-precision floating point operations, False otherwise.

Returns:: Indicates that the device supports half precision floating point operations.
Return type:: bool

SyclDevice.has_aspect_fp64

Returns True if the device supports 64-bit precision floating point operations, False otherwise.

Returns:: Indicates that the device supports 64-bit precision floating point operations.
Return type:: bool

SyclDevice.has_aspect_gpu

Returns True if this device is a GPU device, False otherwise.

Returns:: Indicates if the device is a gpu.
Return type:: bool

SyclDevice.has_aspect_host_debuggable: Returns True if kernels running on this device can be debugged using standard debuggers that are normally available on the host system, False otherwise

SyclDevice.has_aspect_image

Returns True if the device supports images, False otherwise (refer Sec 4.7.3 of SYCL 2020 spec).

Returns:: Indicates that the device supports images
Return type:: bool

SyclDevice.has_aspect_online_compiler

Returns True if this device supports online compilation of device code, False otherwise.

Returns:: Indicates that the device supports online compilation of device code.
Return type:: bool

SyclDevice.has_aspect_online_linker

Returns True if this device supports online linking of device code, False otherwise.

Returns:: Indicates that the device supports online linking of device code.
Return type:: bool

SyclDevice.has_aspect_queue_profiling

Returns True if this device supports queue profiling, False otherwise.

Returns:: Indicates that the device supports queue profiling.
Return type:: bool

SyclDevice.has_aspect_usm_atomic_host_allocations

Returns True if this device supports USM-host allocations and the host and this device may concurrently access and atomically modify host allocations, False otherwise.

Returns:: Indicates if the device supports USM atomic host allocations.
Return type:: bool

SyclDevice.has_aspect_usm_atomic_shared_allocations: Returns True if this device supports USM-shared allocations and the host and other devices in the same context as this device may concurrently access and atomically modify shared allocations, False otherwise

SyclDevice.has_aspect_usm_device_allocations

Returns True if this device supports explicit USM allocations, False otherwise (refer Section 4.8 of SYCL 2020 specs).

Returns:: Indicates that the device supports explicit USM allocations.
Return type:: bool

SyclDevice.has_aspect_usm_host_allocations

Returns True if this device can access USM-host memory, False otherwise (refer Section 4.8 of SYCL 2020 specs).

Returns:: Indicates that the device can access USM memory allocated using sycl::malloc_host.
Return type:: bool

SyclDevice.has_aspect_usm_shared_allocations

Returns True if this device supports USM-shared memory allocated on the same device, False otherwise.

Returns:: Indicates that the device supports USM memory allocated using sycl::malloc_shared.
Return type:: bool

SyclDevice.has_aspect_usm_system_allocations

Returns True if system allocator may be used instead of SYCL USM allocation mechanism for USM-shared allocations on this device, False otherwise.

Returns:: Indicates that system allocator may be used instead of sycl::malloc_shared.
Return type:: bool

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.local_mem_size: Returns the size of local memory on this device in bytes.

SyclDevice.max_compute_units

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

Returns:: The number of compute units in the device.
Return type:: int

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.

Returns:: The maximum supported work group size.
Return type:: int

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.

Returns:: The maximum number of work items supported by the device.
Return type:: int

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 evaluate to False for has_aspect_custom.

Returns:: A tuple whose length depends on the number of workgrpup dimensions supported by the device.
Return type:: tuple[int, int, int]

Deprecated since version 0.14: The property is deprecated use max_work_item_sizes3d instead.

SyclDevice.max_work_item_sizes1d

Returns the maximum number of work-items that are permitted in each dimension of the work-group of the nd_range<1>. The minimum value is (1 ) for devices that evaluate to False for has_aspect_custom.

Returns:: A tuple with the maximum allowed value for a 1D range used to enqueue a kernel on the device.
Return type:: tuple[int,]

SyclDevice.max_work_item_sizes2d

Returns the maximum number of work-items that are permitted in each dimension of the work-group of the nd_range<2>. The minimum value is (1; 1) for devices that evaluate to False for has_aspect_custom.

Returns:: A tuple with the maximum allowed value for each dimension of a 2D range used to enqueue a kernel on the device.
Return type:: tuple[int, int]

SyclDevice.max_work_item_sizes3d

Returns the maximum number of work-items that are permitted in each dimension of the work-group of the nd_range<3>. The minimum value is (1; 1; 1) for devices that evaluate to False for has_aspect_custom.

Returns:: A tuple with the maximum allowed value for each dimension of a 3D range used to enqueue a kernel on the device.
Return type:: tuple[int, int, int]

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.native_vector_width_char: Returns the native ISA vector width size for built-in scalar types that can be put into vectors.

SyclDevice.native_vector_width_double: Returns the native ISA vector width size for built-in scalar types that can be put into vectors.

SyclDevice.native_vector_width_float: Returns the native ISA vector width size for built-in scalar types that can be put into vectors.

SyclDevice.native_vector_width_half: Returns the native ISA vector width size for built-in scalar types that can be put into vectors.

SyclDevice.native_vector_width_int: Returns the native ISA vector width size for built-in scalar types that can be put into vectors.

SyclDevice.native_vector_width_long: Returns the native ISA vector width size for built-in scalar types that can be put into vectors.

SyclDevice.native_vector_width_short: Returns the native ISA vector width size for built-in scalar types that can be put into vectors.

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.partition_max_sub_devices

The maximum number of sub-devices this dpctl.SyclDevice instance can be partitioned into. The value returned cannot exceed the value returned by dpctl.SyclDevice.max_compute_units.

Returns:

The maximum number of sub-devices that can be created when this: device is partitioned. Zero value indicates that device can not be partitioned.

Return type:

int

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.profiling_timer_resolution

Profiling timer resolution.

Returns:: The resolution of device timer in nanoseconds.
Return type:: int

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.

Returns:: Indicates if the device supports independent forward progress of sub-groups.
Return type:: bool

SyclDevice.sub_group_sizes

Returns list of supported sub-group sizes for this device.

Returns:: List of supported sub-group sizes.
Return type:: List[int]

SyclDevice.sycl_platform

Returns the platform associated with this device.

Returns:: The platform associated with this device.
Return type:: dpctl.SyclPlatform

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(self)

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 partition 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(self): Print information about the SYCL device.