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 can be installed through the conda/mamba package managers, from either the conda-forge channel, or from Intel’s channel.

Warning

Packages from the Intel channel are meant to be used together with dependencies from the conda-forge channel, and might not work correctly when used in an environment where packages from the anaconda default channel have been installed. It is advisable to use the miniforge installer for conda/mamba, as it comes with conda-forge as the only default channel.

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

Development builds of dpctl can be installed 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 --override-channels 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:

Builds for CUDA and AMD devices internally use SYCL alias targets that are passed to the compiler. A full list of available SYCL alias targets is available in the DPC++ Compiler User Manual.

CUDA build

dpctl can be built for CUDA devices using the --target-cuda argument.

To target a specific architecture (e.g., sm_80):

python scripts/build_locally.py --verbose --target-cuda=sm_80

To use the default architecture (sm_50), omit the value:

python scripts/build_locally.py --verbose --target-cuda

Alternatively, you can use the DPCTL_TARGET_CUDA CMake option:

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

To use the default architecture (sm_50) with CMake options, set DPCTL_TARGET_CUDA to a value such as ON, TRUE, YES, Y, or 1:

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

Note that kernels are built for the default architecture (sm_50), allowing them to work on a wider range of architectures, but limiting the usage of more recent CUDA features.

For reference, compute architecture strings like sm_80 correspond to specific CUDA Compute Capabilities (e.g., Compute Capability 8.0 corresponds to sm_80). A complete mapping between NVIDIA GPU models and their respective Compute Capabilities can be found in the official CUDA GPU Compute Capability documentation.

AMD build

dpctl can be built for AMD devices using the --target-hip argument.

python scripts/build_locally.py --verbose --target-hip=<arch>

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

To determine the architecture code (<arch>) for your AMD GPU, run:

This will print names like gfx90a, gfx1030, etc. You can then use one of them as the argument to --target-hip.

For example:

Alternatively, you can use the DPCTL_TARGET_HIP CMake option:

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

Multi-target build

The default dpctl build from the source enables support of Intel devices only. Extending the build with a custom SYCL target additionally enables support of CUDA or AMD device in dpctl. Besides, the support can be also extended to enable both CUDA and AMD devices at the same time:

python scripts/build_locally.py --verbose --target-cuda --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