dpctl Functions

Queue Management Functions

dpctl.device_context(arg)

Yields a SYCL queue corresponding to the input queue object, device object, or device filter selector 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.

You can register context factory in the list of factories. This context manager uses context factories to create and activate nested contexts.

Parameters:

arg – A dpctl.SyclQueue object, or a dpctl.SyclDevice object, or a filter selector string.

Yields:

dpctl.SyclQueue –

A SYCL queue corresponding to the specified: input device, queue, or filter string.

Raises:

SyclQueueCreationError – If the SYCL queue creation failed.

Example:

The following example sets current queue targeting specific device indicated with filter selector string in the scope of with block:

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

The following example registers nested context factory:

import dctl

def factory(sycl_queue):
    ...
    return context

dpctl.nested_context_factories.append(factory)

Other Functions

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.

Device Selection Functions

dpctl.select_device_with_aspects(required_aspects, excluded_aspects=None)[source]

Selects the root dpctl.SyclDevice that has the highest default selector score among devices that have all aspects in the required_aspects list, and do not have any aspects in excluded_aspects list.

The list of SYCL device aspects can be found in SYCL 2020 specs:

https://www.khronos.org/registry/SYCL/specs/sycl-2020/html/sycl-2020.html#sec:device-aspects

Example:

import dpctl
# select a GPU that supports double precision
dpctl.select_device_with_aspects(['fp64', 'gpu'])
# select non-custom device with USM shared allocations
dpctl.select_device_with_aspects(
    ['usm_shared_allocations'], excluded_aspects=['custom'])