Docs for pull request 1893

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

pulls/1893/_modules/dpctl/_sycl_timer.html

@@ -820,9 +820,8 @@
 <h1>dpctl.SyclTimer<a class="headerlink" href="#dpctl-sycltimer" title="Permalink to this heading">¶</a></h1>
 <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">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>
+<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 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>
@@ -831,16 +830,21 @@ <h1>dpctl.SyclTimer<a class="headerlink" href="#dpctl-sycltimer" title="Permalin
 <span class="n">q</span> <span class="o">=</span> <span class="n">dpctl</span><span class="o">.</span><span class="n">SyclQueue</span><span class="p">(</span><span class="nb">property</span><span class="o">=</span><span class="s2">&quot;enable_profiling&quot;</span><span class="p">)</span>
 
 <span class="c1"># create the timer</span>
-<span class="n">milliseconds_sc</span> <span class="o">=</span> <span class="mf">1e-3</span>
+<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>
@@ -850,21 +854,55 @@ <h1>dpctl.SyclTimer<a class="headerlink" href="#dpctl-sycltimer" title="Permalin
 </dl>
 <div class="admonition note">
 <p class="admonition-title">Note</p>
-<p>The timer submits barriers to the queue at the entrance and the
+<p>The timer submits tasks to the queue at the entrance and the
 exit of the context and uses profiling information from events
 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>
+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>
 <dd class="field-odd"><ul class="simple">
 <li><p><strong>host_timer</strong> (<em>callable</em><em>, </em><em>optional</em>) – A callable such that host_timer() returns current
 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>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>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 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>
@@ -873,7 +911,7 @@ <h1>dpctl.SyclTimer<a class="headerlink" href="#dpctl-sycltimer" title="Permalin
 <div class="table-wrapper autosummary longtable docutils container">
 <table class="autosummary longtable docutils align-default">
 <tbody>
-<tr class="row-odd"><td><p><a class="reference internal" href="generated/dpctl.SyclTimer.__init__.html#dpctl.SyclTimer.__init__" title="dpctl.SyclTimer.__init__"><code class="xref py py-obj docutils literal notranslate"><span class="pre">__init__</span></code></a>([host_timer, time_scale])</p></td>
+<tr class="row-odd"><td><p><a class="reference internal" href="generated/dpctl.SyclTimer.__init__.html#dpctl.SyclTimer.__init__" title="dpctl.SyclTimer.__init__"><code class="xref py py-obj docutils literal notranslate"><span class="pre">__init__</span></code></a>([host_timer, device_timer, time_scale])</p></td>
 <td><p>Create new instance of <a class="reference internal" href="#dpctl.SyclTimer" title="dpctl.SyclTimer"><code class="xref py py-class docutils literal notranslate"><span class="pre">SyclTimer</span></code></a>.</p></td>
 </tr>
 </tbody>

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

@@ -820,14 +820,15 @@
 <h1>dpctl.SyclTimer.__init__<a class="headerlink" href="#dpctl-sycltimer-init" title="Permalink to this heading">¶</a></h1>
 <dl class="py method">
 <dt class="sig sig-object py" id="dpctl.SyclTimer.__init__">
-<span class="sig-prename descclassname"><span class="pre">SyclTimer.</span></span><span class="sig-name descname"><span class="pre">__init__</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">time_scale=1</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../../../../_modules/dpctl/_sycl_timer.html#SyclTimer.__init__"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#dpctl.SyclTimer.__init__" title="Permalink to this definition">¶</a></dt>
+<span class="sig-prename descclassname"><span class="pre">SyclTimer.</span></span><span class="sig-name descname"><span class="pre">__init__</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.__init__"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#dpctl.SyclTimer.__init__" title="Permalink to this definition">¶</a></dt>
 <dd><p>Create new instance of <a class="reference internal" href="../dpctl.SyclTimer.html#dpctl.SyclTimer" title="dpctl.SyclTimer"><code class="xref py py-class docutils literal notranslate"><span class="pre">SyclTimer</span></code></a>.</p>
 <dl class="field-list simple">
 <dt class="field-odd">Parameters<span class="colon">:</span></dt>
 <dd class="field-odd"><ul class="simple">
 <li><p><strong>host_timer</strong> (<em>callable</em><em>, </em><em>optional</em>) – A function that takes no arguments and returns a value
 measuring time.
 Default: <code class="xref py py-meth docutils literal notranslate"><span class="pre">timeit.default_timer()</span></code>.</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>) – Scaling factor applied to durations measured by
 the host_timer. Default: <code class="docutils literal notranslate"><span class="pre">1</span></code>.</p></li>
 </ul>

pulls/1893/api_reference/dpctl/generated/generated/dpctl.SyclTimer.__init__.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>