dpctl Python API¶

Data Parallel Control (dpctl)

Dpctl’s Python API implements Python wrappers for a subset of DPC++/SYCL’s API. The Python API exposes wrappers for the SYCL runtime classes (expect device_selector) described in Section 4.6 of the SYCL 2020 spec (https://www.khronos.org/registry/SYCL/specs/sycl-2020/html/sycl-2020.html#_sycl_runtime_classes). Apart from the main SYCL runtime classes, dpctl includes a memory sub-module that exposes the SYCL USM allocators and deallocators.

Sub-modules¶

Classes¶

Enumerations¶

class dpctl.backend_type(value)[source]¶

An enumeration of supported SYCL backends.

Name of backend	Enum value
opencl	1
level_zero	2
cuda	3
host	4

class dpctl.device_type(value)[source]¶

An enumeration of supported SYCL device types.

Device type	Enum value
gpu	1
cpu	2
accelerator	3
host_device	4

Exceptions¶

exception dpctl.SyclKernelInvalidRangeError¶: A SyclKernelInvalidRangeError is raised when the provided range has less than one or more than three dimensions.

exception dpctl.SyclKernelSubmitError¶: A SyclKernelSubmitError exception is raised when the provided SyclKernel could not be submitted to the SyclQueue.

exception dpctl.SyclQueueCreationError¶: A SyclQueueCreationError exception is raised when a SyclQueue could not be created. SyclQueue creation can fail if the filter string is invalid, or the backend or device type values are not supported.

Functions¶

dpctl.get_devices()¶

dpctl.select_accelerator_device()¶

A wrapper for SYCL’s accelerator_selector device_selector class.

Returns

A new SyclDevice object containing the SYCL device returned by the accelerator_selector.

Raises

A ValueError is raised if the SYCL accelerator_selector is unable to –
select a device. –

dpctl.select_cpu_device()¶

A wrapper for SYCL’s cpu_selector device_selector class.

Returns

A new SyclDevice object containing the SYCL device returned by the cpu_selector.

Raises

A ValueError is raised if the SYCL cpu_seector is unable to select a –
device. –

dpctl.select_default_device()¶

A wrapper for SYCL’s default_selector device_selector class.

Returns

A new SyclDevice object containing the SYCL device returned by the default_selector.

Raises

A ValueError is raised if the SYCL default_seector is unable to –
select a device. –

dpctl.select_gpu_device()¶

A wrapper for SYCL’s gpu_selector device_selector class.

Returns

A new SyclDevice object containing the SYCL device returned by the gpu_selector.

Raises

A ValueError is raised if the SYCL gpu_seector is unable to select a –
device. –

dpctl.select_host_device()¶

A wrapper for SYCL’s host_selector device_selector class.

Returns

A new SyclDevice object containing the SYCL device returned by the host_selector.

Raises

A ValueError is raised if the SYCL host_seector is unable to select a –
device. –

dpctl.get_num_devices()¶

dpctl.has_cpu_devices()¶: Returns: True if sycl::device_type::cpu devices are present, False otherwise

dpctl.has_gpu_devices()¶: Returns: True if sycl::device_type::gpu devices are present, False otherwise

dpctl.has_accelerator_devices()¶: Returns: True if sycl::device_type::accelerator devices are present, False otherwise

dpctl.has_host_device()¶: Returns: True if sycl::device_type::host devices are present, False otherwise

dpctl.get_platforms()¶

Returns a list of all available SYCL platforms on the system.

Returns: A list of SYCL platforms on the system.
Return type: list

dpctl.lsplatform()¶

Prints out the list of available SYCL platforms and various information about each platform.

Currently, this function prints a list of all SYCL platforms that are available on the system and the list of devices for each platform.

Example

On a system with an OpenCL CPU driver, OpenCL GPU driver, Level Zero GPU driver, running the command.

$python -c "import dpctl; dpctl.lsplatform()"

returns

Platform 0::
    Name        Intel(R) OpenCL
    Version     OpenCL 2.1 LINUX
    Vendor      Intel(R) Corporation
    Profile     FULL_PROFILE
    Backend     opencl
    Devices     1
        Device 0::
        Name            Intel(R) Core(TM) i7-9700 CPU @ 3.00GHz
        Driver version  2020.11.11.0.13_160000
        Device type     cpu
Platform 1::
    Name        Intel(R) OpenCL HD Graphics
    Version     OpenCL 3.0
    Vendor      Intel(R) Corporation
    Profile     FULL_PROFILE
    Backend     opencl
    Devices     1
        Device 0::
        Name            Intel(R) Graphics Gen9 [0x3e98]
        Driver version  20.47.18513
        Device type     gpu
Platform 2::
    Name        Intel(R) Level-Zero
    Version     1.0
    Vendor      Intel(R) Corporation
    Profile     FULL_PROFILE
    Backend     level_zero
    Devices     1
        Device 0::
        Name            Intel(R) Graphics Gen9 [0x3e98]
        Driver version  1.0.18513
        Device type     gpu

dpctl.device_context()¶

Yields a SYCL queue corresponding to the input filter string.

This context manager “activates”, i.e., sets as the currently usable queue, the SYCL queue defined by the argument arg. The activated queue is yielded by the context manager and can also be accessed by any subsequent call to dpctl.get_current_queue() inside the context manager’s scope. The yielded queue is removed as the currently usable queue on exiting the context manager.

Parameters

queue_str (str) – A string corresponding to the DPC++ filter selector.

Yields

SyclQueue – A SYCL queue corresponding to the specified filter string.

Raises

SyclQueueCreationError – If the SYCL queue creation failed.

Example

To create a scope within which the Level Zero GPU number 0 is active, a programmer needs to do the following.

import dpctl
with dpctl.device_context("level0:gpu:0"):
    pass

dpctl.get_current_backend()¶

Returns the backend for the current queue as a backend_type enum.

Returns: The SYCL backend for the currently selected queue.
Return type: backend_type

dpctl.get_current_device_type()¶

Returns current device type as a device_type enum.

Returns: The SYCL device type for the currently selected queue. Possible values can be gpu, cpu, accelerator, or host.
Return type: device_type

dpctl.get_current_queue()¶

Returns the currently activate SYCL queue as a new SyclQueue object.

Returns: If there is a currently active SYCL queue that queue is returned wrapped in a SyclQueue object. The SyclQueue object owns a copy of the currently active SYCL queue as an opaque DPCTLSyclQueueRef pointer. The pointer is freed when the SyclQueue is garbage collected.
Return type: SyclQueue
Raises: SyclQueueCreationError – If no currently active SYCL queue found.

dpctl.get_num_activated_queues()¶

Returns the number of currently activated queues for this thread.

Whenever a program’s control enters a dpctl.device_context() scope, either a new SYCL queue is created or a previously created queue is retrieved from a cache and yielded. The queue yielded by the context manager is termed to be “activated”. If a program creates multiple nested dpctl.device_context() scopes then multiple queues can be activated at the same time, although only the latest activated queue is usable directly via calling dpctl.get_current_queue(). This function returns the number of currently activated queues.

Returns: The number of currently activated queues.
Return type: int

dpctl.is_in_device_context()¶

Checks if the control is inside a dpctl.device_context() scope.

Returns: True if the control is within a dpctl.device_context() scope, otherwise False.
Return type: bool

dpctl.set_global_queue()¶

Sets the global queue to the SYCL queue specified explicitly, or created from given arguments.

Parameters

SyclQueue instance to be used as a global queue. (A) –
Alternatively –
filter selector string (a) –
a SyclDevice (or) –
to be used to construct SyclQueue. (instance) –

Raises

SyclQueueCreationError – If a SYCL queue could not be created.