dpctl Python API

Data Parallel Control (dpctl) is a Python abstraction layer over SYCL.

Dpctl implements a subset of SYCL’s API providing wrappers for the SYCL runtime classes described in Section 4.6 of the SYCL 2020 spec. Note that the SYCL device_selector class is not implemented, instead there are device selection helper functions that can be used to simulate the same behavior. Dpctl implements the ONEPI::filter_selector extension that is included in Intel’s DPC++ SYCL compiler.

The module also includes a global SYCL queue manager. The queue manager provides convenience functions to create a global instance of a dpctl.SyclQueue, to create a nested stack of queue objects, and to create a queue object for use only within a specific scope.

Sub-modules

dpctl.memory

USM allocators and deallocators and classes that implement Python’s buffer protocol.

dpctl.program

Experimental wrappers for SYCL 1.2 program and kernel classes. The module is going to be refactored in the future to support SYCL 2020’s kernel_bundle feature and the wrapper for the program class is going to be removed.

dpctl.tensor

Implementation of different types of tensor classes that use USM memory.

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.

Device Selection Functions

dpctl.get_devices(backend=backend_type.all, device_type=device_type_t.all)

Returns a list of dpctl.SyclDevice instances selected based on the given dpctl.device_type and dpctl.backend_type values.

The function is analogous to sycl::devices::get_devices(), but with an additional functionality that allows filtering SYCL devices based on backend in addition to only device_type.

Parameters

  • backend (optional) – Defaults to dpctl.backend_type.all. A dpctl.backend_type enum value or a string that specifies a SYCL backend. Currently, accepted values are: “cuda”, “opencl”, “level_zero”, or “all”.

  • device_type (optional) – Defaults to dpctl.device_type.all. A dpctl.device_type enum value or a string that specifies a SYCL device type. Currently, accepted values are: “gpu”, “cpu”, “accelerator”, “host_device”, or “all”.

Returns

A list of available dpctl.SyclDevice instances that satisfy the provided dpctl.backend_type and dpctl.device_type values.

Return type

list

dpctl.select_accelerator_device()

A wrapper for SYCL’s accelerator_selector class.

Returns

A Python object wrapping the SYCL device returned by the SYCL accelerator_selector.

Return type

dpctl.SyclDevice

Raises

ValueError – If the SYCL accelerator_selector is unable to select a device.

dpctl.select_cpu_device()

A wrapper for SYCL’s cpu_selector class.

Returns

A Python object wrapping the SYCL device returned by the SYCL cpu_selector.

Return type

dpctl.SyclDevice

Raises

ValueError – If the SYCL cpu_selector is unable to select a device.

dpctl.select_default_device()

A wrapper for SYCL’s default_selector class.

Returns

A Python object wrapping the SYCL device returned by the SYCL default_selector.

Return type

dpctl.SyclDevice

Raises

ValueError – If the SYCL default_selector is unable to select a device.

dpctl.select_gpu_device()

A wrapper for SYCL’s gpu_selector class.

Returns

A Python object wrapping the SYCL device returned by the SYCL gpu_selector.

Return type

dpctl.SyclDevice

Raises

ValueError – If the SYCL gpu_selector is unable to select a device.

dpctl.select_host_device()

A wrapper for SYCL’s host_selector class.

Returns

A Python object wrapping the SYCL device returned by the SYCL host_selector.

Return type

dpctl.SyclDevice

Raises

ValueError – If the SYCL host_selector is unable to select a device.

dpctl.get_num_devices(backend=backend_type.all, device_type=device_type_t.all)

A helper function to return the number of SYCL devices of a given dpctl.device_type and dpctl.backend_type.

Parameters

  • backend (optional) – Defaults to dpctl.backend_type.all. A dpctl.backend_type enum value or a string that specifies a SYCL backend. Currently, accepted values are: “cuda”, “opencl”, “level_zero”, or “all”.

  • device_type (optional) – Defaults to dpctl.device_type.all. A dpctl.device_type enum value or a string that specifies a SYCL device type. Currently, accepted values are: “gpu”, “cpu”, “accelerator”, “host_device”, or “all”.

Returns

The number of available SYCL devices that satisfy the provided dpctl.backend_type and dpctl.device_type values.

Return type

int

dpctl.has_cpu_devices()

A helper function to check if there are any SYCL CPU devices available.

Returns

True if sycl::device_type::cpu devices are present, False otherwise.

Return type

bool

dpctl.has_gpu_devices()

A helper function to check if there are any SYCL GPU devices available.

Returns

True if sycl::device_type::gpu devices are present, False otherwise.

Return type

bool

dpctl.has_accelerator_devices()

A helper function to check if there are any SYCL Accelerator devices available.

Returns

True if sycl::device_type::accelerator devices are present, False otherwise.

Return type

bool

dpctl.has_host_device()

A helper function to check if there are any SYCL Host devices available.

Returns

True if sycl::device_type::host devices are present, False otherwise.

Return type

bool

Queue Management Functions

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

arg – An instance of dpctl.SyclQueue or a filter selector string to be used to construct a dpctl.SyclQueue. The queue is stored in the dpctl queue manager as the default queue.

Raises

SyclQueueCreationError – If a SYCL queue could not be created.

Other Helper Functions

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 optionally extra metadata about each platform.

The level of information printed out by the function can be controlled by the optional vebosity setting.

  • Verbosity level 0: Prints out the list of platforms and their names.

  • Verbosity level 1: Prints out the name, version, vendor, backend, number of devices for each platform.

  • Verbosity level 2: At the highest level of verbosity everything in the previous levels along with the name, version, and filter string for each device is printed.

At verbosity level 2 (highest level) the following output is generated.

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
Parameters

verbosity (optional) – Defaults to 0. The verbosity controls how much information is printed by the function. 0 is the lowest level set by default and 2 is the highest level to print the most verbose output.