Skip to content

Commit e18b716

Browse files
author
Diptorup Deb
committed
Add a quick-start guide.
1 parent d9b1fda commit e18b716

File tree

4 files changed

+270
-0
lines changed

4 files changed

+270
-0
lines changed

‎docs/conf.in

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,7 @@ extensions = [
3535
"sphinx.ext.napoleon",
3636
]
3737

38+
todo_include_todos = True
3839
use_doxyrest = "@DPCTL_ENABLE_DOXYREST@"
3940

4041
if use_doxyrest == "ON":

‎docs/docfiles/user_guides/QuickStart.rst

Lines changed: 257 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,257 @@
1+
.. _quick_start_guide:
2+
3+
#################
4+
Quick Start Guide
5+
#################
6+
7+
8+
.. contents:: Table of contents
9+
:local:
10+
:backlinks: none
11+
:depth: 3
12+
13+
Installing from oneAPI
14+
----------------------
15+
16+
Dpctl is available as part of the oneAPI Intel Distribution of Python (IDP).
17+
Please follow `oneAPI installation guide`_ to install oneAPI. In this guide it
18+
is assumed oneAPI is installed in the standard location and the environment
19+
variable ``ONEAPI_ROOT`` points to the following installation root directory:
20+
21+
- Windows: ``C:\Program Files (x86)\Intel\oneAPI\``
22+
- Linux: ``/opt/intel/oneapi``
23+
24+
Once oneAPI is installed, dpctl is ready to be used by setting up the IDP that
25+
is available inside oneAPI. IDP can be set up as follows:
26+
27+
On Linux
28+
29+
.. code-block:: bash
30+
31+
source ${ONEAPI_ROOT}/intelpython/latest/env/vars.sh
32+
python -c "import dpctl; dpctl.lsplatform()"
33+
34+
On Windows
35+
36+
.. code-block:: bat
37+
38+
call "%ONEAPI_ROOT%\intelpython\latest\env\vars.bat"
39+
python -c "import dpctl; dpctl.lsplatform()"
40+
41+
42+
.. note::
43+
44+
The ``dpctl.lsplatform()`` function is new in dpctl 0.7 and will be
45+
available in oneAPI 2021.3. If you are following the guide on an older
46+
oneAPI installation, use ``dpctl.dump()``. If no GPU platforms are shown,
47+
make source your system has a GPU and has the necessary GPU drivers. You can
48+
install GPU drivers by following the `GPU driver installation guide`_.
49+
50+
Install Wheel package from Pypi
51+
-------------------------------
52+
53+
1. Install dpctl
54+
55+
.. code-block:: bash
56+
57+
python -m pip install --index-url https://pypi.anaconda.org/intel/simple -extra-index-url https://pypi.org/simple dpctl
58+
59+
.. note::
60+
61+
Dpctl wheel package is placed on Pypi, but some of its dependencies
62+
(like Intel numpy) are available only in Anaconda Cloud. That is why install
63+
command requires additional Intel Pypi channel from Anaconda Cloud.
64+
65+
2. Set path to Performance Libraries in case of using ``venv`` or system Python.
66+
67+
68+
On Linux
69+
70+
.. code-block:: bash
71+
72+
export LD_LIBRARY_PATH=<path_to_your_env>/lib
73+
74+
On Windows
75+
76+
.. code-block:: bat
77+
78+
set PATH=<path_to_your_env>\bin;<path_to_your_env>\Library\bin;%PATH%
79+
80+
Building from source
81+
--------------------
82+
83+
To build dpctl from source, we need dpcpp and GPU drivers (and optionally CPU
84+
OpenCL drivers). It is preferable to use the dpcpp compiler packaged as part of
85+
oneAPI. However, it is possible to use a custom build of dpcpp and use that to
86+
build dpctl, especially if you want to enable CUDA support.
87+
88+
Building using oneAPI dpcpp
89+
~~~~~~~~~~~~~~~~~~~~~~~~~~~
90+
91+
As before, oneAPI and graphics drivers should be installed on the system prior
92+
to proceeding further.
93+
94+
**Activate oneAPI as follows**
95+
96+
On Linux
97+
98+
.. code-block:: bash
99+
100+
source ${ONEAPI_ROOT}/setvars.sh
101+
102+
On Windows
103+
104+
.. code-block:: bat
105+
106+
call "%ONEAPI_ROOT%\setvars.bat"
107+
108+
**Build and install using conda-build**
109+
110+
The conda-recipe included with the sources can be used to build the dpctl
111+
package. The advantage of this approach is that all dependencies are pulled in
112+
from oneAPI's intelpython conda channel that was installed as part of oneAPI.
113+
114+
.. code-block:: bash
115+
116+
export ONEAPI_ROOT=/opt/intel/oneapi
117+
conda build conda-recipe -c ${ONEAPI_ROOT}/conda_channel
118+
119+
On Windows to cope with `long file names <https://github.com/IntelPython/dpctl/issues/15>`_,
120+
use ``croot`` with short folder path:
121+
122+
.. code-block:: bat
123+
124+
set "ONEAPI_ROOT=C:\Program Files (x86)\Intel\oneAPI\"
125+
conda build --croot=C:/tmp conda-recipe -c "%ONEAPI_ROOT%\conda_channel"
126+
127+
After building the conda package you may install it by executing:
128+
129+
.. code-block:: bash
130+
131+
conda install dpctl
132+
133+
.. note::
134+
135+
You could face issues with conda-build version 3.20. Use conda-build
136+
3.18 instead.
137+
138+
**Build and Install with setuptools**
139+
140+
To build using Python ``setuptools``, the following packages should be
141+
installed:
142+
143+
- ``cython``
144+
- ``numpy``
145+
- ``cmake``
146+
- ``ninja`` (only on Windows)
147+
- ``gtest`` (optional to run C API tests)
148+
- ``pytest`` (optional to run Python API tests)
149+
150+
Once the prerequisites are installed, building using ``setuptools`` involves The
151+
usual steps
152+
153+
to build and install
154+
155+
.. code-block:: bash
156+
157+
python setup.py install
158+
159+
, and to develop.
160+
161+
.. code-block:: bash
162+
163+
python setup.py develop
164+
165+
Building using custom dpcpp
166+
~~~~~~~~~~~~~~~~~~~~~~~~~~~
167+
168+
.. todo::
169+
170+
Instructions coming soon.
171+
172+
Using dpctl
173+
-----------
174+
175+
Dpctl requires a DPC++ runtime. When dpctl is installed via conda then it uses
176+
the DPC++ runtime from ``dpcpp_cpp_rt`` package that is part of IDP. When using
177+
``setuptools`` make sure a compatible version of DPC++ runtime is available on
178+
the system. The easiest way to setup a DPC++ runtime will be by activating
179+
oneAPI.
180+
181+
Running examples and tests
182+
--------------------------
183+
184+
Running the examples
185+
~~~~~~~~~~~~~~~~~~~~
186+
187+
After setting up dpctl you can try out the Python examples as follows:
188+
189+
.. code-block:: bash
190+
191+
for script in `ls examples/python/`
192+
do
193+
echo "executing ${script}"
194+
python examples/python/${script}
195+
done
196+
197+
The dpctl repository also provides a set of examples of building Cython
198+
extensions with DPC++ compiler, that interoperate with dpctl. These examples are
199+
located under *examples/cython*. Each example in the folder can be built using
200+
``CC=clang CXX=dpcpp python setup.py build_ext --inplace``. Please refer to
201+
``run.py`` script in respective folders to execute the Cython extension
202+
examples.
203+
204+
Running the Python tests
205+
~~~~~~~~~~~~~~~~~~~~~~~~
206+
207+
The dpctl Python test suite can be executed as follows:
208+
209+
.. code-block:: bash
210+
211+
pytest --pyargs dpctl
212+
213+
214+
Building the C API shared library
215+
---------------------------------
216+
217+
The dpctl C API is a shared library called libDPCTLSyclInterface and is built
218+
together when build the Python package. However, it is possible to only build
219+
the C API as a standalone library. To do so, you will need ``cmake``,
220+
``ninja`` or ``make``, and optionally ``gtest 1.10`` if you wish to run the
221+
C API test suite.
222+
223+
For example, on Linux the following script can be used to build the C oneAPI
224+
library.
225+
226+
.. code-block:: bash
227+
228+
#!/bin/bash
229+
set +xe
230+
rm -rf build
231+
mkdir build
232+
pushd build
233+
234+
INSTALL_PREFIX=`pwd`/../install
235+
rm -rf ${INSTALL_PREFIX}
236+
export ONEAPI_ROOT=/opt/intel/oneapi
237+
DPCPP_ROOT=${ONEAPI_ROOT}/compiler/latest/linux
238+
239+
cmake \
240+
-DCMAKE_BUILD_TYPE=Release \
241+
-DCMAKE_INSTALL_PREFIX=${INSTALL_PREFIX} \
242+
-DCMAKE_PREFIX_PATH=${INSTALL_PREFIX} \
243+
-DDPCPP_INSTALL_DIR=${DPCPP_ROOT} \
244+
-DCMAKE_C_COMPILER:PATH=${DPCPP_ROOT}/bin/clang \
245+
-DCMAKE_CXX_COMPILER:PATH=${DPCPP_ROOT}/bin/dpcpp \
246+
-DDPCTL_ENABLE_LO_PROGRAM_CREATION=ON \
247+
-DDPCTL_BUILD_CAPI_TESTS=ON \
248+
..
249+
250+
make V=1 -n -j 4 && make check && make install
251+
252+
253+
254+
255+
256+
.. _oneAPI installation guide: https://software.intel.com/content/www/us/en/develop/articles/installation-guide-for-intel-oneapi-toolkits.html
257+
.. _GPU driver installation guide : https://dgpu-docs.intel.com/installation-guides/index.html

‎docs/index_doxyrest.rst.in

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,11 @@
11
.. include:: ./docfiles/intro.rst
22

3+
.. toctree::
4+
:maxdepth: 1
5+
:caption: User Guides
6+
7+
docfiles/user_guides/QuickStart
8+
39
.. toctree::
410
:maxdepth: 1
511
:caption: API Documentation

‎docs/index_no_doxyrest.rst.in

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,11 @@
11
.. include:: ./docfiles/intro.rst
22

3+
.. toctree::
4+
:maxdepth: 1
5+
:caption: User Guides
6+
7+
docfiles/user_guides/QuickStart
8+
39
.. toctree::
410
:maxdepth: 1
511
:caption: API Documentation

0 commit comments

Comments
 (0)