Docs for pull request 1872

Author: github-actions[doc-deploy-bot]

pulls/1872/_modules/dpctl/_sycl_timer.html

@@ -896,8 +896,7 @@ <h1>Source code for dpctl._sycl_timer</h1><div class="highlight"><pre>
 
 <div class="viewcode-block" id="SyclTimer"><a class="viewcode-back" href="../../api_reference/dpctl/generated/dpctl.SyclTimer.html#dpctl.SyclTimer">[docs]</a><span class="k">class</span> <span class="nc">SyclTimer</span><span class="p">:</span>
 <span class="w">    </span><span class="sd">&quot;&quot;&quot;</span>
-<span class="sd">    Context to measure device time and host wall-time of execution</span>
-<span class="sd">    of commands submitted to :class:`dpctl.SyclQueue`.</span>
+<span class="sd">    Context to time execution of tasks submitted to :class:`dpctl.SyclQueue`.</span>
 
 <span class="sd">    :Example:</span>
 <span class="sd">        .. code-block:: python</span>
@@ -911,13 +910,18 @@ <h1>Source code for dpctl._sycl_timer</h1><div class="highlight"><pre>
 <span class="sd">            milliseconds_sc = 1e3</span>
 <span class="sd">            timer = dpctl.SyclTimer(time_scale = milliseconds_sc)</span>
 
+<span class="sd">            untimed_code_block_1</span>
 <span class="sd">            # use the timer</span>
 <span class="sd">            with timer(queue=q):</span>
-<span class="sd">                code_block1</span>
+<span class="sd">                timed_code_block1</span>
+
+<span class="sd">            untimed_code_block_2</span>
 
 <span class="sd">            # use the timer</span>
 <span class="sd">            with timer(queue=q):</span>
-<span class="sd">                code_block2</span>
+<span class="sd">                timed_code_block2</span>
+
+<span class="sd">            untimed_code_block_3</span>
 
 <span class="sd">            # retrieve elapsed times in milliseconds</span>
 <span class="sd">            wall_dt, device_dt = timer.dt</span>
@@ -928,16 +932,41 @@ <h1>Source code for dpctl._sycl_timer</h1><div class="highlight"><pre>
 <span class="sd">        associated with these submissions to perform the timing. Thus</span>
 <span class="sd">        :class:`dpctl.SyclTimer` requires the queue with ``&quot;enable_profiling&quot;``</span>
 <span class="sd">        property. In order to be able to collect the profiling information,</span>
-<span class="sd">        the ``dt`` property ensures that both submitted barriers complete their</span>
-<span class="sd">        execution and thus effectively synchronizes the queue.</span>
+<span class="sd">        the ``dt`` property ensures that both tasks submitted by the timer</span>
+<span class="sd">        complete their execution and thus effectively synchronizes the queue.</span>
+
+<span class="sd">        Execution of the above example results in the following task graph,</span>
+<span class="sd">        where each group of tasks is ordered after the one preceding it,</span>
+<span class="sd">        ``[tasks_of_untimed_block1]``, ``[timer_fence_start_task]``,</span>
+<span class="sd">        ``[tasks_of_timed_block1]``, ``[timer_fence_finish_task]``,</span>
+<span class="sd">        ``[tasks_of_untimed_block2]``, ``[timer_fence_start_task]``,</span>
+<span class="sd">        ``[tasks_of_timed_block2]``, ``[timer_fence_finish_task]``,</span>
+<span class="sd">        ``[tasks_of_untimed_block3]``.</span>
 
-<span class="sd">        `device_timer` keyword argument controls the type of tasks submitted.</span>
-<span class="sd">        With `device_timer=&quot;queue_barrier&quot;`, queue barrier tasks are used. With</span>
-<span class="sd">        `device_timer=&quot;order_manager&quot;`, a single empty body task is inserted</span>
-<span class="sd">        instead relying on order manager (used by `dpctl.tensor` operations) to</span>
+<span class="sd">        ``device_timer`` keyword argument controls the type of tasks submitted.</span>
+<span class="sd">        With ``&quot;queue_barrier&quot;`` value, queue barrier tasks are used. With</span>
+<span class="sd">        ``&quot;order_manager&quot;`` value, a single empty body task is inserted</span>
+<span class="sd">        and order manager (used by all `dpctl.tensor` operations) is used to</span>
 <span class="sd">        order these tasks so that they fence operations performed within</span>
 <span class="sd">        timer&#39;s context.</span>
 
+<span class="sd">        Timing offloading operations that do not use the order manager with</span>
+<span class="sd">        the timer that uses ``&quot;order_manager&quot;`` as ``device_timer`` value</span>
+<span class="sd">        will be misleading becaused the tasks submitted by the timer will not</span>
+<span class="sd">        be ordered with respect to tasks we intend to time.</span>
+
+<span class="sd">        Note, that host timer effectively measures the time of task</span>
+<span class="sd">        submissions. To measure host timer wall-time that includes execution</span>
+<span class="sd">        of submitted tasks, make sure to include synchronization point in</span>
+<span class="sd">        the timed block.</span>
+
+<span class="sd">        :Example:</span>
+<span class="sd">            .. code-block:: python</span>
+
+<span class="sd">            with timer(q):</span>
+<span class="sd">                timed_block</span>
+<span class="sd">                q.wait()</span>
+
 <span class="sd">    Args:</span>
 <span class="sd">        host_timer (callable, optional):</span>
 <span class="sd">            A callable such that host_timer() returns current</span>
@@ -946,7 +975,7 @@ <h1>Source code for dpctl._sycl_timer</h1><div class="highlight"><pre>
 <span class="sd">        device_timer (Literal[&quot;queue_barrier&quot;, &quot;order_manager&quot;], optional):</span>
 <span class="sd">            Device timing method. Default: &quot;queue_barrier&quot;.</span>
 <span class="sd">        time_scale (Union[int, float], optional):</span>
-<span class="sd">            Ratio of the unit of time of interest and one second.</span>
+<span class="sd">            Ratio of one second and the unit of time-scale of interest.</span>
 <span class="sd">            Default: ``1``.</span>
 <span class="sd">    &quot;&quot;&quot;</span>
 

pulls/1872/api_reference/dpctl/generated/dpctl.SyclTimer.html

@@ -821,8 +821,7 @@ <h1>dpctl.SyclTimer<a class="headerlink" href="#dpctl-sycltimer" title="Permalin
 <dl class="py class">
 <dt class="sig sig-object py" id="dpctl.SyclTimer">
 <em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">dpctl.</span></span><span class="sig-name descname"><span class="pre">SyclTimer</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">host_timer=&lt;built-in</span> <span class="pre">function</span> <span class="pre">perf_counter&gt;</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">device_timer=None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">time_scale=1</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../../../_modules/dpctl/_sycl_timer.html#SyclTimer"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#dpctl.SyclTimer" title="Permalink to this definition">¶</a></dt>
-<dd><p>Context to measure device time and host wall-time of execution
-of commands submitted to <a class="reference internal" href="dpctl.SyclQueue.html#dpctl.SyclQueue" title="dpctl.SyclQueue"><code class="xref py py-class docutils literal notranslate"><span class="pre">dpctl.SyclQueue</span></code></a>.</p>
+<dd><p>Context to time execution of tasks submitted to <a class="reference internal" href="dpctl.SyclQueue.html#dpctl.SyclQueue" title="dpctl.SyclQueue"><code class="xref py py-class docutils literal notranslate"><span class="pre">dpctl.SyclQueue</span></code></a>.</p>
 <dl class="field-list">
 <dt class="field-odd">Example<span class="colon">:</span></dt>
 <dd class="field-odd"><div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">dpctl</span>
@@ -834,13 +833,18 @@ <h1>dpctl.SyclTimer<a class="headerlink" href="#dpctl-sycltimer" title="Permalin
 <span class="n">milliseconds_sc</span> <span class="o">=</span> <span class="mf">1e3</span>
 <span class="n">timer</span> <span class="o">=</span> <span class="n">dpctl</span><span class="o">.</span><span class="n">SyclTimer</span><span class="p">(</span><span class="n">time_scale</span> <span class="o">=</span> <span class="n">milliseconds_sc</span><span class="p">)</span>
 
+<span class="n">untimed_code_block_1</span>
 <span class="c1"># use the timer</span>
 <span class="k">with</span> <span class="n">timer</span><span class="p">(</span><span class="n">queue</span><span class="o">=</span><span class="n">q</span><span class="p">):</span>
-    <span class="n">code_block1</span>
+    <span class="n">timed_code_block1</span>
+
+<span class="n">untimed_code_block_2</span>
 
 <span class="c1"># use the timer</span>
 <span class="k">with</span> <span class="n">timer</span><span class="p">(</span><span class="n">queue</span><span class="o">=</span><span class="n">q</span><span class="p">):</span>
-    <span class="n">code_block2</span>
+    <span class="n">timed_code_block2</span>
+
+<span class="n">untimed_code_block_3</span>
 
 <span class="c1"># retrieve elapsed times in milliseconds</span>
 <span class="n">wall_dt</span><span class="p">,</span> <span class="n">device_dt</span> <span class="o">=</span> <span class="n">timer</span><span class="o">.</span><span class="n">dt</span>
@@ -855,14 +859,41 @@ <h1>dpctl.SyclTimer<a class="headerlink" href="#dpctl-sycltimer" title="Permalin
 associated with these submissions to perform the timing. Thus
 <a class="reference internal" href="#dpctl.SyclTimer" title="dpctl.SyclTimer"><code class="xref py py-class docutils literal notranslate"><span class="pre">dpctl.SyclTimer</span></code></a> requires the queue with <code class="docutils literal notranslate"><span class="pre">&quot;enable_profiling&quot;</span></code>
 property. In order to be able to collect the profiling information,
-the <code class="docutils literal notranslate"><span class="pre">dt</span></code> property ensures that both submitted barriers complete their
-execution and thus effectively synchronizes the queue.</p>
-<p><cite>device_timer</cite> keyword argument controls the type of tasks submitted.
-With <cite>device_timer=”queue_barrier”</cite>, queue barrier tasks are used. With
-<cite>device_timer=”order_manager”</cite>, a single empty body task is inserted
-instead relying on order manager (used by <cite>dpctl.tensor</cite> operations) to
+the <code class="docutils literal notranslate"><span class="pre">dt</span></code> property ensures that both tasks submitted by the timer
+complete their execution and thus effectively synchronizes the queue.</p>
+<p>Execution of the above example results in the following task graph,
+where each group of tasks is ordered after the one preceding it,
+<code class="docutils literal notranslate"><span class="pre">[tasks_of_untimed_block1]</span></code>, <code class="docutils literal notranslate"><span class="pre">[timer_fence_start_task]</span></code>,
+<code class="docutils literal notranslate"><span class="pre">[tasks_of_timed_block1]</span></code>, <code class="docutils literal notranslate"><span class="pre">[timer_fence_finish_task]</span></code>,
+<code class="docutils literal notranslate"><span class="pre">[tasks_of_untimed_block2]</span></code>, <code class="docutils literal notranslate"><span class="pre">[timer_fence_start_task]</span></code>,
+<code class="docutils literal notranslate"><span class="pre">[tasks_of_timed_block2]</span></code>, <code class="docutils literal notranslate"><span class="pre">[timer_fence_finish_task]</span></code>,
+<code class="docutils literal notranslate"><span class="pre">[tasks_of_untimed_block3]</span></code>.</p>
+<p><code class="docutils literal notranslate"><span class="pre">device_timer</span></code> keyword argument controls the type of tasks submitted.
+With <code class="docutils literal notranslate"><span class="pre">&quot;queue_barrier&quot;</span></code> value, queue barrier tasks are used. With
+<code class="docutils literal notranslate"><span class="pre">&quot;order_manager&quot;</span></code> value, a single empty body task is inserted
+and order manager (used by all <cite>dpctl.tensor</cite> operations) is used to
 order these tasks so that they fence operations performed within
 timer’s context.</p>
+<p>Timing offloading operations that do not use the order manager with
+the timer that uses <code class="docutils literal notranslate"><span class="pre">&quot;order_manager&quot;</span></code> as <code class="docutils literal notranslate"><span class="pre">device_timer</span></code> value
+will be misleading becaused the tasks submitted by the timer will not
+be ordered with respect to tasks we intend to time.</p>
+<p>Note, that host timer effectively measures the time of task
+submissions. To measure host timer wall-time that includes execution
+of submitted tasks, make sure to include synchronization point in
+the timed block.</p>
+<dl class="field-list">
+<dt class="field-odd">Example<span class="colon">:</span></dt>
+<dd class="field-odd"><div class="highlight-python notranslate"><div class="highlight"><pre><span></span>
+</pre></div>
+</div>
+<dl class="simple">
+<dt>with timer(q):</dt><dd><p>timed_block
+q.wait()</p>
+</dd>
+</dl>
+</dd>
+</dl>
 </div>
 <dl class="field-list simple">
 <dt class="field-odd">Parameters<span class="colon">:</span></dt>
@@ -871,7 +902,7 @@ <h1>dpctl.SyclTimer<a class="headerlink" href="#dpctl-sycltimer" title="Permalin
 host time in seconds.
 Default: <a class="reference external" href="https://docs.python.org/3/library/timeit.html#timeit.default_timer" title="(in Python v3.13)"><code class="xref py py-func docutils literal notranslate"><span class="pre">timeit.default_timer()</span></code></a>.</p></li>
 <li><p><strong>device_timer</strong> (<em>Literal</em><em>[</em><em>&quot;queue_barrier&quot;</em><em>, </em><em>&quot;order_manager&quot;</em><em>]</em><em>, </em><em>optional</em>) – Device timing method. Default: “queue_barrier”.</p></li>
-<li><p><strong>time_scale</strong> (<em>Union</em><em>[</em><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.13)"><em>int</em></a><em>, </em><a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.13)"><em>float</em></a><em>]</em><em>, </em><em>optional</em>) – Ratio of the unit of time of interest and one second.
+<li><p><strong>time_scale</strong> (<em>Union</em><em>[</em><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.13)"><em>int</em></a><em>, </em><a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.13)"><em>float</em></a><em>]</em><em>, </em><em>optional</em>) – Ratio of one second and the unit of time-scale of interest.
 Default: <code class="docutils literal notranslate"><span class="pre">1</span></code>.</p></li>
 </ul>
 </dd>

pulls/1872/api_reference/dpctl/index.html

@@ -861,7 +861,7 @@
 <td><p>Python class representing <code class="docutils literal notranslate"><span class="pre">sycl::platform</span></code> class.</p></td>
 </tr>
 <tr class="row-even"><td><p><a class="reference internal" href="generated/dpctl.SyclTimer.html#dpctl.SyclTimer" title="dpctl.SyclTimer"><code class="xref py py-obj docutils literal notranslate"><span class="pre">SyclTimer</span></code></a></p></td>
-<td><p>Context to measure device time and host wall-time of execution of commands submitted to <a class="reference internal" href="generated/dpctl.SyclQueue.html#dpctl.SyclQueue" title="dpctl.SyclQueue"><code class="xref py py-class docutils literal notranslate"><span class="pre">dpctl.SyclQueue</span></code></a>.</p></td>
+<td><p>Context to time execution of tasks submitted to <a class="reference internal" href="generated/dpctl.SyclQueue.html#dpctl.SyclQueue" title="dpctl.SyclQueue"><code class="xref py py-class docutils literal notranslate"><span class="pre">dpctl.SyclQueue</span></code></a>.</p></td>
 </tr>
 </tbody>
 </table>

pulls/1872/beginners_guides/installation.html

@@ -881,7 +881,7 @@ <h2>Installation using pip<a class="headerlink" href="#installation-using-pip" t
 <section id="installation-via-intel-r-distribution-for-python">
 <h2>Installation via Intel(R) Distribution for Python<a class="headerlink" href="#installation-via-intel-r-distribution-for-python" title="Permalink to this heading">¶</a></h2>
 <p><a class="reference external" href="https://www.intel.com/content/www/us/en/developer/tools/oneapi/distribution-for-python.html">Intel(R) Distribution for Python*</a> is distributed as a conda-based installer
-and includes <a class="reference internal" href="../api_reference/dpctl/index.html#module-dpctl" title="dpctl"><code class="xref py py-mod docutils literal notranslate"><span class="pre">dpctl</span></code></a> along with its dependencies and sister projects <a class="reference external" href="https://intelpython.github.io/dpnp/overview.html#module-dpnp" title="(in Data Parallel Extension for NumPy v0.17.0dev1+21.g078d9a33a18)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">dpnp</span></code></a>
+and includes <a class="reference internal" href="../api_reference/dpctl/index.html#module-dpctl" title="dpctl"><code class="xref py py-mod docutils literal notranslate"><span class="pre">dpctl</span></code></a> along with its dependencies and sister projects <a class="reference external" href="https://intelpython.github.io/dpnp/overview.html#module-dpnp" title="(in Data Parallel Extension for NumPy v0.17.0dev2)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">dpnp</span></code></a>
 and <a class="reference external" href="https://intelpython.github.io/numba-dpex/latest/index.html#module-numba_dpex" title="(in numba-dpex)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">numba_dpex</span></code></a>.</p>
 <p>Once the installed environment is activated, <code class="docutils literal notranslate"><span class="pre">dpctl</span></code> should be ready to use.</p>
 </section>