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 (str, 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.

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

`backend`	Returns the `backend_type` enum value for this device
`default_selector_score`	Integral score assigned to this device by DPC++ runtime's default selector's 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.15.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 this instance is a SYCL accelerator device.
`is_cpu`	Returns `True` if this instance is a SYCL CPU device.
`is_gpu`	Returns `True` if this instance is a SYCL GPU device.
`local_mem_size`	Returns the size of local memory on this device in bytes.
`max_clock_frequency`	Maximal clock frequency in MHz.
`max_compute_units`	Returns the number of parallel compute units available to the device.
`max_mem_alloc_size`	Maximum size of memory object than can be allocated.
`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 `sycl::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 `sycl::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 `sycl::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.