Skip to content

Commit f055e36

Browse files
author
Diptorup Deb
committed
Add a quickstart guide.
1 parent 3cd1585 commit f055e36

File tree

8 files changed

+291
-32
lines changed

8 files changed

+291
-32
lines changed

‎docs/docfiles/dpctl.dptensor_api.rst

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
.. _dpctl.dptensor_api:
22

3-
#########################
4-
dpctl dptensor Python API
5-
#########################
3+
##############
4+
dpctl.dptensor
5+
##############
66

77
.. automodule:: dpctl.dptensor
88
:members:

‎docs/docfiles/dpctl.memory_api.rst

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
.. _dpctl.memory_api:
22

3-
#######################
4-
dpctl Memory Python API
5-
#######################
3+
############
4+
dpctl.memory
5+
############
66

77
.. automodule:: dpctl.memory
88

‎docs/docfiles/dpctl.program_api.rst

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
.. _dpctl.program_api:
22

3-
########################
4-
dpctl Program Python API
5-
########################
3+
#############
4+
dpctl.program
5+
#############
66

77
.. automodule:: dpctl.program
88

‎docs/docfiles/dpctl_pyapi.rst

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,16 @@ dpctl Python API
66

77
.. automodule:: dpctl
88

9+
Sub-modules
10+
-----------
11+
12+
.. toctree::
13+
:maxdepth: 1
14+
15+
dpctl.dptensor_api
16+
dpctl.memory_api
17+
dpctl.program_api
18+
919
Classes
1020
-------
1121

‎docs/docfiles/intro.rst

Lines changed: 4 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -4,27 +4,8 @@ Welcome to Data-parallel Control (dpctl)'s documentation!
44
Data-parallel control (dpctl) is a library that exposes SYCL and DPCPP to
55
languages other than C++. Currently, dpctl provides SYCL bindings for C and
66
Python making it possible to access SYCL runtime objects and methods from these
7-
languages. The SYCL functionality covered by dpctl includes the core SYCL
8-
runtime classes described in Section 4.6 of the
9-
`SYCL 2020 spec <https://www.khronos.org/registry/SYCL/specs/sycl-2020/html/sycl-2020.html#_sycl_runtime_classes>`_
10-
and USM memory management. dpctl also has experimental support for SYCL's
7+
languages. The SYCL functionality covered by dpctl includes the core SYCL
8+
runtime classes described in Section 4.6 of the
9+
`SYCL 2020 spec <https://www.khronos.org/registry/SYCL/specs/sycl-2020/html/sycl-2020.html#_sycl_runtime_classes>`_
10+
and USM memory management. dpctl also has experimental support for SYCL's
1111
``kernel`` and ``program`` classes.
12-
13-
Core Features
14-
-------------
15-
16-
.. todo::
17-
18-
Coming soon.
19-
20-
User Guidies
21-
------------
22-
23-
.. todo::
24-
25-
Device Management.
26-
27-
.. todo::
28-
29-
USM Memory Management
30-

‎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+
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: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,11 @@
55

66
.. include:: ./docfiles/intro.rst
77

8+
.. toctree::
9+
:maxdepth: 1
10+
:caption: User Guides
11+
12+
docfiles/user_guides/QuickStart
813
.. toctree::
914
:maxdepth: 1
1015
:caption: API Documentation

‎docs/index_no_doxyrest.rst.in

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,12 @@
55

66
.. include:: ./docfiles/intro.rst
77

8+
.. toctree::
9+
:maxdepth: 1
10+
:caption: User Guides
11+
12+
docfiles/user_guides/QuickStart
13+
814
.. toctree::
915
:maxdepth: 1
1016
:caption: API Documentation

0 commit comments

Comments
 (0)