Installing dpctl

License

dpctl is licensed under Apache* License 2.0 that can be found in the LICENSE file. All usage and contributions to the project are subject to the terms and conditions of this license.

See the user guide document for additional information.

Installation using conda

Binary builds of dpctl are available for the conda package manager ecosystem.

Released versions of the package can be installed from the Intel channel, as indicated by --channel option:

Getting latest released version of dpctl using conda
conda create --name dpctl_env --channel https://software.repos.intel.com/python/conda/ --channel conda-forge dpctl

Development builds of dpctl can be accessed from the dppy/label/dev channel:

Getting latest development version
conda create -n dpctl_nightly -c dppy/label/dev -c https://software.repos.intel.com/python/conda/ -c conda-forge dpctl

Note

If dpctl is not available for the Python version of interest, see Building from source.

Installation using pip

Binary wheels are published with Python Package Index (https://pypi.org/project/dpctl/).

Getting latest released version of dpctl using pip
python -m pip install dpctl

Binary wheels of dpctl and its dependencies are also published on Intel(R) channel. To install from this non-default package index, use

python -m pip install --index-url https://software.repos.intel.com/python/pypi dpctl

Note

As of April 2024, installation using pip on Linux* requires that host operating system had libstdc++.so library version 6.0.29 or later. Check the version you have by executing find /lib/x86_64-linux-gnu/ -name "libstdc++*"

Note

If dpctl is not available for the Python version of interest, see Building from source.

Installation via Intel(R) Distribution for Python

Intel(R) Distribution for Python* is distributed as a conda-based installer and includes dpctl along with its dependencies and sister projects dpnp and numba_dpex.

Once the installed environment is activated, dpctl should be ready to use.

System requirements

Since dpctl is compiled using the Intel(R) oneAPI DPC++ compiler, the compiler’s system requirements for runtime must be met.

In order for DPC++ runtime to recognize supported hardware appropriate drivers must be installed. Directions to install drivers for Intel GPU devices are available at https://dgpu-docs.intel.com/

Once dpctl is installed, use python -m dpctl --full-list to list recognized devices.

For dpctl to target Intel GPU devices, appropriate drivers should be installed systemwide. Please refer to GPU installation guide for detailed instructions on how to install required drivers on Linux.

Note

Instructions for setting up GPU drivers in Windows Subsystem for Linux (WSL) will be added in a future release of this document.

Building from source

There are several reasons to want to build dpctl from source:

  1. To use it with Python version for which binary artifacts are not available

  2. To be able to use DPC++ runtime libraries from local installation of DPC++ compiler and avoid installing them into Python environment

  3. To build for custom SYCL targets, such as nvptx64-nvidia-cuda or "amdgcn-amd-amdhsa".

Building locally for use with oneAPI DPC++ installation

Working with dpctl in this mode assumes that the DPC++ compiler is activated, and that Python environment has all build and runtime dependencies of dpctl installed.

One way to create such environment is as follows:

Creation of environment to build dpctl locally
conda create -n dev_dpctl -c conda-forge python=3.12 pip
conda activate dev_dpctl
pip install --no-cache-dir numpy cython scikit-build cmake ninja pytest

Using such environment and with DPC++ compiler activated, build the project using

python scripts/build_locally.py --verbose

Note

Coming back to use this local build of dpctl remember to activate DPC++.

Building for custom SYCL targets

Project dpctl is written using generic SYCL and supports building for multiple SYCL targets, subject to limitations of CodePlay plugins implementing SYCL programming model for classes of devices.

Building dpctl for these targets requires that these CodePlay plugins be installed into DPC++ installation layout of compatible version. The following plugins from CodePlay are supported:

dpctl can be built for CUDA devices as follows:

python scripts/build_locally.py --verbose --cmake-opts="-DDPCTL_TARGET_CUDA=ON"

And for AMD devices

python scripts/build_locally.py --verbose --cmake-opts="-DDPCTL_TARGET_HIP=gfx1030"

Note that the oneAPI for AMD GPUs plugin requires the architecture be specified and only one architecture can be specified at a time.

It is, however, possible to build for Intel devices, CUDA devices, and an AMD device architecture all at once:

python scripts/build_locally.py --verbose --cmake-opts="-DDPCTL_TARGET_CUDA=ON \
-DDPCTL_TARGET_HIP=gfx1030"

Running Examples and Tests

Running the Examples

After setting up dpctl, you can test 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 and pybind11 extensions with the DPC++ compiler that interoperate with dpctl.

Please refer to the README.md file in respective folders for instructions on how to build each example Python project and how to execute its test suite.

Running the Python Tests

You can execute Python test suite of dpctl with:

pytest --pyargs dpctl