Quick Start Guide¶

Table of contents

Installing from oneAPI
Install Wheel package from Pypi
Building from source
- Building using oneAPI dpcpp
- Building using custom dpcpp
Using dpctl
Running examples and tests
- Running the examples
- Running the Python tests
Building the C API shared library

Installing from oneAPI¶

Dpctl is available as part of the oneAPI Intel Distribution of Python (IDP). Please follow oneAPI installation guide to install oneAPI. In this guide it is assumed oneAPI is installed in the standard location and the environment variable ONEAPI_ROOT points to the following installation root directory:

Windows: C:\Program Files (x86)\Intel\oneAPI\

Linux: /opt/intel/oneapi

Once oneAPI is installed, dpctl is ready to be used by setting up the IDP that is available inside oneAPI. IDP can be set up as follows:

On Linux

source ${ONEAPI_ROOT}/intelpython/latest/env/vars.sh
python -c "import dpctl; dpctl.lsplatform()"

On Windows

call "%ONEAPI_ROOT%\intelpython\latest\env\vars.bat"
python -c "import dpctl; dpctl.lsplatform()"

Note

The dpctl.lsplatform() function is new in dpctl 0.7 and will be available in oneAPI 2021.3. If you are following the guide on an older oneAPI installation, use dpctl.dump(). If no GPU platforms are shown, make source your system has a GPU and has the necessary GPU drivers. You can install GPU drivers by following the GPU driver installation guide.

Install Wheel package from Pypi¶

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 available only in Anaconda Cloud. That is why install command requires additional Intel Pypi channel from Anaconda Cloud.

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%

Building from source¶

To build dpctl from source, we need dpcpp and GPU drivers (and optionally CPU OpenCL drivers). It is preferable to use the dpcpp compiler packaged as part of oneAPI. However, it is possible to use a custom build of dpcpp and use that to build dpctl, especially if you want to enable CUDA support.

Building using oneAPI dpcpp¶

As before, oneAPI and graphics drivers should be installed on the system prior to proceeding further.

Activate oneAPI as follows

On Linux

source ${ONEAPI_ROOT}/setvars.sh

On Windows

call "%ONEAPI_ROOT%\setvars.bat"

Build and install using conda-build

The conda-recipe included with the sources can be used to build the dpctl package. The advantage of this approach is that all dependencies are pulled in from oneAPI’s intelpython conda channel that was installed as part of oneAPI.

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"

After building the conda package you may install it by executing:

conda install dpctl

Note

You could face issues with conda-build version 3.20. Use conda-build 3.18 instead.

Build and Install with setuptools

To build using Python setuptools, the following packages should be installed:

cython

numpy

cmake

ninja (only on Windows)

gtest (optional to run C API tests)

pytest (optional to run Python API tests)

Once the prerequisites are installed, building using setuptools involves The usual steps

to build and install

python setup.py install

, and to develop.

python setup.py develop

Building using custom dpcpp¶

Todo

Instructions coming soon.

Using dpctl¶

Dpctl requires a DPC++ runtime. When dpctl is installed via conda then it uses the DPC++ runtime from dpcpp_cpp_rt package that is part of IDP. When using setuptools make sure a compatible version of DPC++ runtime is available on the system. The easiest way to setup a DPC++ runtime will be by activating oneAPI.

Running examples and tests¶

Running the examples¶

After setting up dpctl you can try out the Python examples as follows:

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

The dpctl repository also provides a set of examples of building Cython extensions with DPC++ compiler, that interoperate with dpctl. These examples are located under examples/cython. Each example in the 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 the Cython extension examples.

Running the Python tests¶

The dpctl Python test suite can be executed as follows:

pytest --pyargs dpctl

Building the C API shared library¶

The dpctl C API is a shared library called libDPCTLSyclInterface and is built together when build the Python package. However, it is possible to only build the C API as a standalone library. To do so, you will need cmake, ninja or make, and optionally gtest 1.10 if you wish to run the C API test suite.

For example, on Linux the following script can be used to build the C oneAPI library.

#!/bin/bash
set +xe
rm -rf build
mkdir build
pushd build

INSTALL_PREFIX=`pwd`/../install
rm -rf ${INSTALL_PREFIX}
export ONEAPI_ROOT=/opt/intel/oneapi
DPCPP_ROOT=${ONEAPI_ROOT}/compiler/latest/linux

cmake                                                       \
    -DCMAKE_BUILD_TYPE=Release                              \
    -DCMAKE_INSTALL_PREFIX=${INSTALL_PREFIX}                \
    -DCMAKE_PREFIX_PATH=${INSTALL_PREFIX}                   \
    -DDPCPP_INSTALL_DIR=${DPCPP_ROOT}                       \
    -DCMAKE_C_COMPILER:PATH=${DPCPP_ROOT}/bin/clang         \
    -DCMAKE_CXX_COMPILER:PATH=${DPCPP_ROOT}/bin/dpcpp       \
    -DDPCTL_ENABLE_LO_PROGRAM_CREATION=ON                   \
    -DDPCTL_BUILD_CAPI_TESTS=ON                             \
    ..

make V=1 -n -j 4 && make check && make install