Skip to content
This repository was archived by the owner on Jan 12, 2026. It is now read-only.

Commit 209daf2

Browse files
Merge pull request #21 from IntelPython/doc_update
Minor updates in examples 5e4e5b2
1 parent ffd2ac1 commit 209daf2

10 files changed

Lines changed: 123 additions & 59 deletions
68.6 KB
Loading

‎main/_sources/examples.rst.txt‎

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -7,21 +7,27 @@ List of examples
77
.. literalinclude:: ../../examples/01-hello_dpnp.py
88
:language: python
99
:lines: 27-
10-
:caption: Your first NumPy code running on GPU
10+
:caption: **EXAMPLE 01:** Your first NumPy code running on GPU
1111
:name: examples_01_hello_dpnp
1212

1313
.. literalinclude:: ../../examples/02-dpnp_device.py
1414
:language: python
1515
:lines: 27-
16-
:caption: Select device type while creating array
16+
:caption: **EXAMPLE 02:** Select device type while creating array
1717
:name: examples_02_dpnp_device
1818

1919
.. literalinclude:: ../../examples/03-dpnp2numba-dpex.py
2020
:language: python
2121
:lines: 27-
22-
:caption: Compile dpnp code with numba-dpex
22+
:caption: **EXAMPLE 03:** Compile dpnp code with numba-dpex
2323
:name: examples_03_dpnp2numba_dpex
2424

25+
.. literalinclude:: ../../examples/04-dpctl_device_query.py
26+
:language: python
27+
:lines: 27-
28+
:caption: **EXAMPLE 04:** Get information about devices
29+
:name: examples_04_dpctl_device_query
30+
2531
Benchmarks
2632
**********
2733

‎main/_sources/prerequisites_and_installation.rst.txt‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,10 @@
11
.. _prerequisites_and_installation:
22
.. include:: ./ext_links.txt
33

4+
.. |copy| unicode:: U+000A9
5+
6+
.. |trade| unicode:: U+2122
7+
48
Prerequisites and installation
59
==============================
610

@@ -31,7 +35,8 @@ Extensions for Python manually.
3135
3. Data Parallel Extensions for Python
3236
***************************************
3337

34-
You can skip this step if you already installed Intel® Distribution for Python or Intel® AI Analytics Toolkit.
38+
You can skip this step if you already installed Intel |copy| Distribution for Python or Intel |copy| AI Analytics Toolkit.
39+
3540
The easiest way to install Data Parallel Extensions for Python is to install numba-dpex:
3641

3742
Conda: ``conda install numba-dpex``
@@ -40,3 +45,6 @@ Pip: ``pip install numba-dpex``
4045

4146
The above commands will install ``numba-dpex`` along with its dependencies, including ``dpnp``, ``dpctl``,
4247
and required compiler runtimes and drivers.
48+
49+
.. WARNING::
50+
Before installing with conda or pip it is strongly advised to update ``conda`` and ``pip`` to latest versions

‎main/_sources/programming_dpep.rst.txt‎

Lines changed: 14 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -39,12 +39,12 @@ to execute your `Numpy*`_ script on GPU usually requires changing just a few lin
3939
.. literalinclude:: ../../examples/01-hello_dpnp.py
4040
:language: python
4141
:lines: 27-
42-
:caption: Your first NumPy code running on GPU
42+
:caption: **EXAMPLE 01:** Your first NumPy code running on GPU
4343
:name: ex_01_hello_dpnp
4444

4545

4646
In this example ``np.asarray()`` creates an array on the default `SYCL*`_ device, which is ``"gpu"`` on systems
47-
with integrated or discrete GPU (it is ``"cpu"`` on systems that do not have GPU).
47+
with integrated or discrete GPU (it is ``"host"`` on systems that do not have GPU).
4848
The queue associated with this array is now carried with ``x``, and ``np.sum(x)`` will derive it from ``x``,
4949
and respective pre-compiled kernel implementing ``np.sum()`` will be submitted to that queue.
5050
The result ``y`` will be allocated on the device 0-dimensional array associated with that queue too.
@@ -57,7 +57,7 @@ In the following example we create the array ``x`` on the GPU device, and perfor
5757
.. literalinclude:: ../../examples/02-dpnp_device.py
5858
:language: python
5959
:lines: 27-
60-
:caption: Select device type while creating array
60+
:caption: **EXAMPLE 02:** Select device type while creating array
6161
:name: ex_02_dpnp_device
6262

6363

@@ -73,7 +73,7 @@ It takes just a few lines to modify your CPU `Numba*`_ script to run on GPU.
7373
.. literalinclude:: ../../examples/03-dpnp2numba-dpex.py
7474
:language: python
7575
:lines: 27-
76-
:caption: Compile dpnp code with numba-dpex
76+
:caption: **EXAMPLE 03:** Compile dpnp code with numba-dpex
7777
:name: ex_03_dpnp2numba_dpex
7878

7979
In this example we implement a custom function ``sum_it()`` that takes an array input. We compile it with
@@ -104,6 +104,12 @@ there are some situations when you will need to use dpctl advanced capabilities:
104104
Another frequent usage is the creation additional queues for the purpose of profiling or choosing an out-of-order
105105
execution of offload kernels.
106106

107+
.. literalinclude:: ../../examples/04-dpctl_device_query.py
108+
:language: python
109+
:lines: 27-
110+
:caption: **EXAMPLE 04:** Get information about devices
111+
:name: ex_04_dpctl_device_query
112+
107113
2. **Cross-platform development using Python Array API standard.** If you’re a Python developer
108114
programming Numpy-like codes and targeting different hardware vendors and different tensor implementations,
109115
then going with `Python* Array API Standard`_ is a good choice for writing a portable Numpy-like code.
@@ -208,8 +214,10 @@ The next command generates the roof-line graph as a html file in the output dire
208214
209215
> advisor --report=roofline --gpu --project-dir=<output_dir> --report-output=<output_dir>/roofline_gpu.html
210216
211-
.. todo::
212-
Insert high-resolution image illustrating Advisor html report
217+
.. image:: ./_images/advisor_roofline_gen9.png
218+
:width: 800px
219+
:align: center
220+
:alt: Advisor roofline analysis example on Gen9 integrated GPU
213221

214222
The above figure shows an example roof-line graph generated using Intel Advisor.
215223
The X-axis in the graph represents arithmetic intensity and the Y-axis represents performance in GFLOPS.

‎main/examples.html‎

Lines changed: 35 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -79,19 +79,22 @@ <h3>Navigation</h3>
7979
<span class="target" id="examples"></span><section id="list-of-examples">
8080
<h1>List of examples<a class="headerlink" href="#list-of-examples" title="Permalink to this heading"></a></h1>
8181
<div class="literal-block-wrapper docutils container" id="examples-01-hello-dpnp">
82-
<div class="code-block-caption"><span class="caption-text">Your first NumPy code running on GPU</span><a class="headerlink" href="#examples-01-hello-dpnp" title="Permalink to this code"></a></div>
82+
<div class="code-block-caption"><span class="caption-text"><strong>EXAMPLE 01:</strong> Your first NumPy code running on GPU</span><a class="headerlink" href="#examples-01-hello-dpnp" title="Permalink to this code"></a></div>
8383
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">dpnp</span> <span class="k">as</span> <span class="nn">np</span>
8484

8585
<span class="n">x</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">asarray</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">])</span>
86+
<span class="nb">print</span><span class="p">(</span><span class="s2">&quot;Array x allocated on the device:&quot;</span><span class="p">,</span> <span class="n">x</span><span class="o">.</span><span class="n">device</span><span class="p">)</span>
87+
8688
<span class="n">y</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">sum</span><span class="p">(</span><span class="n">x</span><span class="p">)</span>
8789

88-
<span class="nb">print</span><span class="p">(</span><span class="n">y</span><span class="o">.</span><span class="n">shape</span><span class="p">)</span> <span class="c1"># Must be 0-dimensional array</span>
89-
<span class="nb">print</span><span class="p">(</span><span class="n">y</span><span class="p">)</span> <span class="c1"># Expect 6</span>
90+
<span class="nb">print</span><span class="p">(</span><span class="s2">&quot;Result y is located on the device:&quot;</span><span class="p">,</span> <span class="n">y</span><span class="o">.</span><span class="n">device</span><span class="p">)</span> <span class="c1"># The same device as x</span>
91+
<span class="nb">print</span><span class="p">(</span><span class="s2">&quot;Shape of y is:&quot;</span><span class="p">,</span> <span class="n">y</span><span class="o">.</span><span class="n">shape</span><span class="p">)</span> <span class="c1"># 0-dimensional array</span>
92+
<span class="nb">print</span><span class="p">(</span><span class="s2">&quot;y=&quot;</span><span class="p">,</span> <span class="n">y</span><span class="p">)</span> <span class="c1"># Expect 6</span>
9093
</pre></div>
9194
</div>
9295
</div>
9396
<div class="literal-block-wrapper docutils container" id="examples-02-dpnp-device">
94-
<div class="code-block-caption"><span class="caption-text">Select device type while creating array</span><a class="headerlink" href="#examples-02-dpnp-device" title="Permalink to this code"></a></div>
97+
<div class="code-block-caption"><span class="caption-text"><strong>EXAMPLE 02:</strong> Select device type while creating array</span><a class="headerlink" href="#examples-02-dpnp-device" title="Permalink to this code"></a></div>
9598
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">dpnp</span> <span class="k">as</span> <span class="nn">np</span>
9699

97100
<span class="n">x</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">empty</span><span class="p">(</span><span class="mi">3</span><span class="p">)</span>
@@ -100,31 +103,50 @@ <h1>List of examples<a class="headerlink" href="#list-of-examples" title="Permal
100103
<span class="k">except</span><span class="p">:</span>
101104
<span class="nb">print</span><span class="p">(</span><span class="s2">&quot;GPU device is not available&quot;</span><span class="p">)</span>
102105

106+
<span class="nb">print</span><span class="p">(</span><span class="s2">&quot;Array x allocated on the device:&quot;</span><span class="p">,</span> <span class="n">x</span><span class="o">.</span><span class="n">device</span><span class="p">)</span>
107+
103108
<span class="n">y</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">sum</span><span class="p">(</span><span class="n">x</span><span class="p">)</span>
104-
<span class="nb">print</span><span class="p">(</span><span class="n">y</span><span class="p">)</span> <span class="c1"># Expect 6</span>
109+
110+
<span class="nb">print</span><span class="p">(</span><span class="s2">&quot;Result y is located on the device:&quot;</span><span class="p">,</span> <span class="n">y</span><span class="o">.</span><span class="n">device</span><span class="p">)</span> <span class="c1"># The same device as x</span>
111+
<span class="nb">print</span><span class="p">(</span><span class="s2">&quot;Shape of y is:&quot;</span><span class="p">,</span> <span class="n">y</span><span class="o">.</span><span class="n">shape</span><span class="p">)</span> <span class="c1"># 0-dimensional array</span>
112+
<span class="nb">print</span><span class="p">(</span><span class="s2">&quot;y=&quot;</span><span class="p">,</span> <span class="n">y</span><span class="p">)</span> <span class="c1"># Expect 6</span>
105113
</pre></div>
106114
</div>
107115
</div>
108116
<div class="literal-block-wrapper docutils container" id="examples-03-dpnp2numba-dpex">
109-
<div class="code-block-caption"><span class="caption-text">Compile dpnp code with numba-dpex</span><a class="headerlink" href="#examples-03-dpnp2numba-dpex" title="Permalink to this code"></a></div>
117+
<div class="code-block-caption"><span class="caption-text"><strong>EXAMPLE 03:</strong> Compile dpnp code with numba-dpex</span><a class="headerlink" href="#examples-03-dpnp2numba-dpex" title="Permalink to this code"></a></div>
110118
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">dpnp</span> <span class="k">as</span> <span class="nn">np</span>
111-
<span class="kn">from</span> <span class="nn">numba_dpex</span> <span class="kn">import</span> <span class="n">jit</span>
119+
<span class="kn">from</span> <span class="nn">numba_dpex</span> <span class="kn">import</span> <span class="n">njit</span>
112120

113121
<span class="nd">@njit</span><span class="p">(</span><span class="n">parallel</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">fastmath</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
114-
<span class="k">def</span> <span class="nf">sum_it</span><span class="p">(</span><span class="n">x</span><span class="p">):</span>
122+
<span class="k">def</span> <span class="nf">sum_it</span><span class="p">(</span><span class="n">x</span><span class="p">):</span> <span class="c1"># Device queue is inferred from x. The kernel is submitted to that queue</span>
115123
<span class="k">return</span> <span class="n">np</span><span class="o">.</span><span class="n">sum</span><span class="p">(</span><span class="n">x</span><span class="p">)</span>
116124

117-
118-
<span class="n">x</span> <span class="o">=</span> <span class="kc">None</span>
125+
<span class="n">x</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">empty</span><span class="p">(</span><span class="mi">3</span><span class="p">)</span>
119126
<span class="k">try</span><span class="p">:</span>
120127
<span class="n">x</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">asarray</span><span class="p">([</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">],</span> <span class="n">device</span><span class="o">=</span><span class="s2">&quot;gpu&quot;</span><span class="p">)</span>
121128
<span class="k">except</span><span class="p">:</span>
122129
<span class="nb">print</span><span class="p">(</span><span class="s2">&quot;GPU device is not available&quot;</span><span class="p">)</span>
123130

124-
<span class="n">y</span> <span class="o">=</span> <span class="n">sum_it</span><span class="p">(</span><span class="n">x</span><span class="p">)</span>
131+
<span class="nb">print</span><span class="p">(</span><span class="s2">&quot;Array x allocated on the device:&quot;</span><span class="p">,</span> <span class="n">x</span><span class="o">.</span><span class="n">device</span><span class="p">)</span>
125132

126-
<span class="nb">print</span><span class="p">(</span><span class="n">y</span><span class="o">.</span><span class="n">shape</span><span class="p">)</span> <span class="c1"># Must be 0-dimensional array</span>
127-
<span class="nb">print</span><span class="p">(</span><span class="n">y</span><span class="p">)</span> <span class="c1"># Expect 6</span>
133+
<span class="n">y</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">sum</span><span class="p">(</span><span class="n">x</span><span class="p">)</span>
134+
135+
<span class="nb">print</span><span class="p">(</span><span class="s2">&quot;Result y is located on the device:&quot;</span><span class="p">,</span> <span class="n">y</span><span class="o">.</span><span class="n">device</span><span class="p">)</span> <span class="c1"># The same device as x</span>
136+
<span class="nb">print</span><span class="p">(</span><span class="s2">&quot;Shape of y is:&quot;</span><span class="p">,</span> <span class="n">y</span><span class="o">.</span><span class="n">shape</span><span class="p">)</span> <span class="c1"># 0-dimensional array</span>
137+
<span class="nb">print</span><span class="p">(</span><span class="s2">&quot;y=&quot;</span><span class="p">,</span> <span class="n">y</span><span class="p">)</span> <span class="c1"># Expect 6</span>
138+
</pre></div>
139+
</div>
140+
</div>
141+
<div class="literal-block-wrapper docutils container" id="examples-04-dpctl-device-query">
142+
<div class="code-block-caption"><span class="caption-text"><strong>EXAMPLE 04:</strong> Get information about devices</span><a class="headerlink" href="#examples-04-dpctl-device-query" title="Permalink to this code"></a></div>
143+
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">dpctl</span>
144+
145+
<span class="nb">print</span><span class="p">(</span><span class="s2">&quot;Platform:&quot;</span><span class="p">,</span> <span class="n">dpctl</span><span class="o">.</span><span class="n">lsplatform</span><span class="p">())</span> <span class="c1"># Print platform information</span>
146+
<span class="nb">print</span><span class="p">(</span><span class="s2">&quot;GPU devices:&quot;</span><span class="p">,</span> <span class="n">dpctl</span><span class="o">.</span><span class="n">get_devices</span><span class="p">(</span><span class="n">device_type</span><span class="o">=</span><span class="s2">&quot;gpu&quot;</span><span class="p">))</span> <span class="c1"># Get the list of all GPU devices</span>
147+
<span class="nb">print</span><span class="p">(</span><span class="s2">&quot;Number of GPU devices&quot;</span><span class="p">,</span> <span class="n">dpctl</span><span class="o">.</span><span class="n">get_num_devices</span><span class="p">(</span><span class="n">device_type</span><span class="o">=</span><span class="s2">&quot;gpu&quot;</span><span class="p">))</span> <span class="c1"># Get the number of GPU devices</span>
148+
<span class="nb">print</span><span class="p">(</span><span class="s2">&quot;Has CPU devices?&quot;</span><span class="p">,</span> <span class="n">dpctl</span><span class="o">.</span><span class="n">has_cpu_devices</span><span class="p">())</span> <span class="c1"># Check if there are CPU devices</span>
149+
<span class="nb">print</span><span class="p">(</span><span class="s2">&quot;Has host device?&quot;</span><span class="p">,</span> <span class="n">dpctl</span><span class="o">.</span><span class="n">has_host_device</span><span class="p">())</span> <span class="c1"># Check if there is the host device</span>
128150
</pre></div>
129151
</div>
130152
</div>

‎main/objects.inv‎

78 Bytes
Binary file not shown.

‎main/prerequisites_and_installation.html‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -101,12 +101,16 @@ <h2>2. Python interpreter<a class="headerlink" href="#python-interpreter" title=
101101
</section>
102102
<section id="data-parallel-extensions-for-python">
103103
<h2>3. Data Parallel Extensions for Python<a class="headerlink" href="#data-parallel-extensions-for-python" title="Permalink to this heading"></a></h2>
104-
<p>You can skip this step if you already installed Intel® Distribution for Python or Intel® AI Analytics Toolkit.
105-
The easiest way to install Data Parallel Extensions for Python is to install numba-dpex:</p>
104+
<p>You can skip this step if you already installed Intel © Distribution for Python or Intel © AI Analytics Toolkit.</p>
105+
<p>The easiest way to install Data Parallel Extensions for Python is to install numba-dpex:</p>
106106
<p>Conda: <code class="docutils literal notranslate"><span class="pre">conda</span> <span class="pre">install</span> <span class="pre">numba-dpex</span></code></p>
107107
<p>Pip: <code class="docutils literal notranslate"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">numba-dpex</span></code></p>
108108
<p>The above commands will install <code class="docutils literal notranslate"><span class="pre">numba-dpex</span></code> along with its dependencies, including <code class="docutils literal notranslate"><span class="pre">dpnp</span></code>, <code class="docutils literal notranslate"><span class="pre">dpctl</span></code>,
109109
and required compiler runtimes and drivers.</p>
110+
<div class="admonition warning">
111+
<p class="admonition-title">Warning</p>
112+
<p>Before installing with conda or pip it is strongly advised to update <code class="docutils literal notranslate"><span class="pre">conda</span></code> and <code class="docutils literal notranslate"><span class="pre">pip</span></code> to latest versions</p>
113+
</div>
110114
</section>
111115
</section>
112116

0 commit comments

Comments
 (0)