dpctl Python API¶

Data Parallel Control (dpCtl)

DpCtl provides a lightweight Python wrapper over a subset of DPC++/SYCL’s API. The goal of dpCtl is not (yet) to provide a abstraction for every SYCL function. DpCtl is intended to provide a common runtime to manage specific SYCL resources, such as devices and USM memory, for SYCL-based Python packages and extension modules.

The main features presently provided by dpCtl are:

A SYCL queue manager exposed directly inside the top-level dpctl module.
Python wrapper classes for the main SYCL runtime classes mentioned in Section 4.6 of SYCL provisional 2020 spec (https://bit.ly/3asQx07).

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.

exception dpctl.UnsupportedBackendError¶: An UnsupportedBackendError exception is raised when a backend value is other than backend_type.opencl or backend_type.level_zero is encountered. All other backends are currently not supported.

exception dpctl.UnsupportedDeviceError¶: An UnsupportedDeviceError exception is raised when a device type value other than device_type.cpu or device_type.gpu is encountered.

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 “backend:device type:device id” tuple. 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 spec that should be a three tuple specified as “backend:device-type:device-id”, defaults to “opencl:gpu:0”.

Yields

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

Raises

ValueError – If the filter string is malformed.
UnsupportedDeviceError – If the device type value is invalid.
UnsupportedBackendError – If the backend value is invalid.
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.dump()¶

Prints information about the SYCL environment.

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.dump()"

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.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_include()[source]¶

Return the directory that contains the dpCtl *.h header files.

Extension modules that need to be compiled against dpCtl should use this function to locate the appropriate include directory.

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.get_num_platforms()¶

Returns the number of available non-host SYCL platforms. WARNING: To be depracated in the near future.

Returns: The number of non-host SYCL backends.
Return type: int

dpctl.get_num_queues()¶

Returns the number of devices for the input backend and device type combination. WARNING: To be depracated in the near future.

Parameters

backend_ty (backend_type) – Enum value specifying a SYCL backend.
device_ty (device_type) – Enum value specifying a SYCL device type.

Returns

Number of devices for the input backend and device type combination.

Return type

int

Raises

UnsupportedDeviceError – If the device type value is invalid.
UnsupportedBackendError – If the backend value is invalid.

dpctl.has_cpu_queues()¶

Checks if the system has a CPU device for the specified SYCL backend type. WARNING: To be depracated in the near future.

Parameters: backend_ty (backend_type) – Enum value specifying a SYCL backend defaults to backend_type.opencl.
Returns: True if the backend has a CPU device else False.
Return type: bool
Raises: UnsupportedBackendError – If the backend value is invalid.

dpctl.has_gpu_queues()¶

Checks if the system has a GPU device for the specified SYCL backend type. WARNING: To be depracated in the near future.

Parameters: backend_ty (backend_type) – Enum value specifying a SYCL backend defaults to backend_type.opencl.
Returns: True if the backend has a GPU device else False.
Return type: bool
Raises: UnsupportedBackendError – If the backend value is invalid.

dpctl.has_sycl_platforms()¶

Checks if the system has any non-host SYCL platforms. WARNING: The behavior of the function may change in the future to include the host platform.

Returns: Returns True if there is at least one non-host SYCL, platform, otherwise returns False.
Return type: bool

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_default_queue()¶

Sets the global (default) queue to the SYCL queue specified using the backend, device type, and relative device id parameters. WARNING: To be depracated in the near future.

Parameters

backend_ty (backend_type) – Enum value specifying a SYCL backend.
device_ty (device_type) – Enum value specifying a SYCL device type.
device_id (int) – A relative device number. The relative device id is based on the ordering of the devices in the list returned by SYCL’s platform::get_platforms().get_devices() function.

Raises

SyclQueueCreationError – If a SYCL queue could not be created.
UnsupportedDeviceError – If the device type is invalid.
UnsupportedBackendError – If the backend type is invalid.