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, another dpctl.SyclDevice, 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 argument is not a dpctl.SyclDevice or string.

Methods

`addressof_ref`()	Returns the address of the `DPCTLSyclDeviceRef` pointer as a `size_t`.
`can_access_peer`(peer[, value])	Returns `True` if this device (`self`) can enable peer access to USM device memory on `peer`, `False` otherwise.
`can_compile`(language)	Check whether it is possible to create an executable kernel_bundle for this device from the given source language.
`component_devices`()	Returns a tuple of component devices contained in this SYCL device.
`create_sub_devices`([partition])	Creates a tuple of sub-devices by partitioning a root device based on the provided partition specifier.
`disable_peer_access`(peer)	Disables peer access to `peer` from this device (`self`).
`enable_peer_access`(peer)	Enables this device (`self`) to access USM device allocations located on `peer`.
`get_device_id`()	For an unpartitioned device, returns the canonical index of this device in the list of devices visible to dpctl.
`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.
`get_unpartitioned_parent_device`()	Returns the unpartitioned parent device of this device.
`print_device_info`()	Print information about the SYCL device.

Attributes

`address_bits`	Returns the address space size of the device.
`atomic_fence_order_capabilities`	Returns a tuple of `dpctl.memory_order` enum members describing atomic fence order capabilities of the device.
`atomic_fence_scope_capabilities`	Returns a tuple of `dpctl.memory_scope` enum members describing atomic fence scope capabilities of the device.
`atomic_memory_order_capabilities`	Returns a tuple of `dpctl.memory_order` enum members describing atomic memory order capabilities of the device.
`atomic_memory_scope_capabilities`	Returns a tuple of `dpctl.memory_scope` enum members describing atomic memory scope capabilities of the device.
`backend`	Returns the `backend_type` enum value for this device
`backend_version`	Returns a backend version string.
`composite_device`	The composite device for a component device, or `None` for a non-component 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.
`double_fp_config`	Returns a tuple of `dpctl.fp_config` enum members describing double-precision floating-point capabilities of the device.
`driver_version`	Returns a backend-defined driver version as a string.
`error_correction_support`	Returns `True` if the device implements error correction for all accesses to compute device memories (global, local, etc.).
`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.
`half_fp_config`	Returns a tuple of `dpctl.fp_config` enum members describing half-precision floating-point capabilities of the device.
`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_emulated`	Returns `True` if this device is somehow emulated, `False` otherwise.
`has_aspect_ext_oneapi_ipc_memory`	Returns `True` if this device supports inter-process communication (IPC) memory handles, `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_is_component`	Returns `True` if this device is a component device, `False` otherwise.
`has_aspect_is_composite`	Returns `True` if this device is a composite device, `False` otherwise.
`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.
`image_max_buffer_size`	Returns the max number of pixels for a 1D image created from a buffer.
`is_accelerator`	Returns `True` if this instance is a SYCL accelerator device.
`is_available`	Returns `True` if the device is available.
`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.
`local_mem_type`	Returns the type of local memory supported by the device.
`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_parameter_size`	Returns the maximum size in bytes of all arguments that can be passed to a kernel.
`max_read_image_args`	Returns the maximum number of simultaneous image objects that can be read from by a kernel.
`max_samplers`	Returns the maximum number of samplers that can be used in 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.
`mem_base_addr_align`	Returns the minimum value to which memory allocations on this device are aligned in bits.
`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_affinity_domains`	Returns a tuple of strings describing supported partition affinity domains of the device.
`partition_max_sub_devices`	The maximum number of sub-devices this `dpctl.SyclDevice` instance can be partitioned into.
`partition_properties`	Returns a tuple of `dpctl.partition_property` enum members describing supported partition properties of the device.
`partition_type_affinity_domain`	Returns the partition affinity domain used to partition the parent device if this is a sub-device partitioned by affinity domain, or `"not_applicable"` otherwise.
`partition_type_property`	Returns the partition property of this device if it is a sub-device, or `partition_property.no_partition` if it is not a sub-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.
`profiling_timer_resolution`	Profiling timer resolution.
`single_fp_config`	Returns a tuple of `dpctl.fp_config` enum members describing single-precision floating-point capabilities of the device.
`sub_group_sizes`	Returns tuple 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.
`vendor_id`	Returns the vendor identifier of the device.
`version`	Returns a backend-defined device version string.