Skip to content

installation.rst

Latest commit

 

History

History
200 lines (128 loc) · 6.84 KB

installation.rst

File metadata and controls

200 lines (128 loc) · 6.84 KB

Installing dpctl

License

:py:mod:`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 :ref:`document <user_guide_dpctl_license>` for additional information.

Installation using conda

Binary builds of :py:mod:`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:

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:

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

Note

If :py:mod:`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/).

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 :py:mod:`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 :py:mod:`dpctl` along with its dependencies and sister projects :py:mod:`dpnp` and :py:mod:`numba_dpex`.

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

System requirements

Since :py:mod:`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 :py:mod:`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:

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 :py:mod:`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:

Build dpctl as follows:

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

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 :py:mod:`dpctl` repository also provides a set of examples of building Cython and pybind11 extensions with the DPC++ compiler that interoperate with :py:mod:`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 :py:mod:`dpctl` with:

pytest --pyargs dpctl