dpctl 0.11.0

A lightweight Python wrapper for a subset of SYCL.

About dpctl

dpctl (data parallel control) is a lightweight Python package exposing a subset of the Intel(R) oneAPI DPC++ runtime classes that is distributed as part of Intel(R) Distribution for Python* and is included in Intel(R) oneAPI Base ToolKit. dpctl lets Python users query SYCL platforms, discover and represent SYCL devices, and construct SYCL queues to control data-parallel code execution on Intel(R) XPUs from Python.

dpctl features classes representing SYCL unified shared memory allocations as well as higher-level objects such as dpctl.tensor.usm_ndarray on top of USM allocations.

dpctl assists authors of Python native extensions written in C, Cython, or pybind11 to use its dpctl.SyclQueue object to indicate the offload target as well as objects in dpctl.memory and dpctl.tensor submodules to represent USM allocations that are accessible from within data-parallel code executed on the target queue.

dpctl.tensor submodule provides an array container representing an array in a strided layout on top of a USM allocation. The submodule provides an array-API conforming oneAPI DPC++ powered library to manipulate the array container.

Requirements

• Install Conda
• Install Intel oneAPI
  • Set environment variable ONEAPI_ROOT
    • Windows: C:\Program Files (x86)\Intel\oneAPI\
    • Linux: /opt/intel/oneapi
• Install OpenCL HD graphics drivers

Build and Install Conda Package

1. Create and activate conda build environment

conda create -n build-env conda-build
conda activate build-env

2. Set environment variable ONEAPI_ROOT and build conda package

export ONEAPI_ROOT=/opt/intel/oneapi
conda build conda-recipe -c ${ONEAPI_ROOT}/conda_channel

On Windows to cope with long file names use croot with short folder path:

set "ONEAPI_ROOT=C:\Program Files (x86)\Intel\oneAPI\"
conda build --croot=C:/tmp conda-recipe -c "%ONEAPI_ROOT%\conda_channel"

:warning: You could face issues with conda-build=3.20: Use conda-build=3.18!

3. Install conda package

conda install dpctl

Build and Install with setuptools

dpctl relies on DPC++ runtime. With Intel oneAPI installed you should activate it. setup.py requires environment variable ONEAPI_ROOT and following packages installed:

• cython
• numpy
• cmake - for building C API
• ninja - only on Windows

You need DPC++ to build dpctl. If you want to build using the DPC++ in a oneAPI distribution, activate DPC++ compiler as follows:

export ONEAPI_ROOT=/opt/intel/oneapi
source ${ONEAPI_ROOT}/compiler/latest/env/vars.sh

For install:

python setup.py install

For development:

python setup.py develop

It is also possible to build dpctl using DPC++ toolchain instead of oneAPI DPC++. Instead of activating the oneAPI environment, indicate the toolchain installation prefix with --sycl-compiler-prefix option, e.g.

python setup.py develop --sycl-compiler-prefix=${DPCPP_ROOT}/llvm/build

Please use python setup.py develop --help for more details.

Install Wheel Package from Pypi

1. Install dpctl

python -m pip install --index-url https://pypi.anaconda.org/intel/simple --extra-index-url https://pypi.org/simple dpctl

Note: dpctl wheel package is placed on Pypi, but some of its dependencies (like Intel numpy) are in Anaconda Cloud. That is why install command requires additional intel Pypi channel from Anaconda Cloud.

2. Set path to Performance Libraries in case of using venv or system Python: On Linux:

export LD_LIBRARY_PATH=<path_to_your_env>/lib

On Windows:

set PATH=<path_to_your_env>\bin;<path_to_your_env>\Library\bin;%PATH%

Using dpctl

dpctl relies on DPC++ runtime. With Intel oneAPI installed you could activate it.

On Windows:

call "%ONEAPI_ROOT%\compiler\latest\env\vars.bat"

On Linux:

source ${ONEAPI_ROOT}/compiler/latest/env/vars.sh

When dpctl is installed via conda package then it uses DPC++ runtime from dpcpp_cpp_rt package and it is not necessary to activate oneAPI DPC++ compiler environment.

dpcpp_cpp_rt package is provided by oneAPI conda_channel.

Examples

See examples in folder examples.

Run python examples:

for script in `ls examples/python/`; do echo "executing ${script}"; python examples/python/${script}; done

Examples of building Cython extensions with DPC++ compiler, that interoperate with dpctl can be found in folder cython.

Each example in cython folder can be built using CC=clang CXX=dpcpp python setup.py build_ext --inplace. Please refer to run.py script in respective folders to execute extensions.

Tests

See tests in folder dpctl/tests.

Run tests:

pytest --pyargs dpctl