Docs for pull request 2019

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

pulls/2019/_modules/dpctl/tensor/_indexing_functions.html

@@ -823,8 +823,8 @@ <h1>Source code for dpctl.tensor._indexing_functions</h1><div class="highlight">
         <span class="p">)</span>
 
 
-<div class="viewcode-block" id="take"><a class="viewcode-back" href="../../../api_reference/dpctl/generated/dpctl.tensor.take.html#dpctl.tensor.take">[docs]</a><span class="k">def</span><span class="w"> </span><span class="nf">take</span><span class="p">(</span><span class="n">x</span><span class="p">,</span> <span class="n">indices</span><span class="p">,</span> <span class="o">/</span><span class="p">,</span> <span class="o">*</span><span class="p">,</span> <span class="n">axis</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">mode</span><span class="o">=</span><span class="s2">&quot;wrap&quot;</span><span class="p">):</span>
-<span class="w">    </span><span class="sd">&quot;&quot;&quot;take(x, indices, axis=None, mode=&quot;wrap&quot;)</span>
+<div class="viewcode-block" id="take"><a class="viewcode-back" href="../../../api_reference/dpctl/generated/dpctl.tensor.take.html#dpctl.tensor.take">[docs]</a><span class="k">def</span><span class="w"> </span><span class="nf">take</span><span class="p">(</span><span class="n">x</span><span class="p">,</span> <span class="n">indices</span><span class="p">,</span> <span class="o">/</span><span class="p">,</span> <span class="o">*</span><span class="p">,</span> <span class="n">axis</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">out</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">mode</span><span class="o">=</span><span class="s2">&quot;wrap&quot;</span><span class="p">):</span>
+<span class="w">    </span><span class="sd">&quot;&quot;&quot;take(x, indices, axis=None, out=None, mode=&quot;wrap&quot;)</span>
 
 <span class="sd">    Takes elements from an array along a given axis at given indices.</span>
 
@@ -837,6 +837,9 @@ <h1>Source code for dpctl.tensor._indexing_functions</h1><div class="highlight">
 <span class="sd">            The axis along which the values will be selected.</span>
 <span class="sd">            If ``x`` is one-dimensional, this argument is optional.</span>
 <span class="sd">            Default: ``None``.</span>
+<span class="sd">        out (Optional[usm_ndarray]):</span>
+<span class="sd">            Output array to populate. Array must have the correct</span>
+<span class="sd">            shape and the expected data type.</span>
 <span class="sd">        mode (str, optional):</span>
 <span class="sd">            How out-of-bounds indices will be handled. Possible values</span>
 <span class="sd">            are:</span>
@@ -904,18 +907,53 @@ <h1>Source code for dpctl.tensor._indexing_functions</h1><div class="highlight">
             <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="s2">&quot;`axis` must be 0 for an array of dimension 0.&quot;</span><span class="p">)</span>
         <span class="n">res_shape</span> <span class="o">=</span> <span class="n">indices</span><span class="o">.</span><span class="n">shape</span>
 
-    <span class="n">res</span> <span class="o">=</span> <span class="n">dpt</span><span class="o">.</span><span class="n">empty</span><span class="p">(</span>
-        <span class="n">res_shape</span><span class="p">,</span> <span class="n">dtype</span><span class="o">=</span><span class="n">x</span><span class="o">.</span><span class="n">dtype</span><span class="p">,</span> <span class="n">usm_type</span><span class="o">=</span><span class="n">res_usm_type</span><span class="p">,</span> <span class="n">sycl_queue</span><span class="o">=</span><span class="n">exec_q</span>
-    <span class="p">)</span>
+    <span class="n">dt</span> <span class="o">=</span> <span class="n">x</span><span class="o">.</span><span class="n">dtype</span>
+
+    <span class="n">orig_out</span> <span class="o">=</span> <span class="n">out</span>
+    <span class="k">if</span> <span class="n">out</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span><span class="p">:</span>
+        <span class="k">if</span> <span class="ow">not</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">out</span><span class="p">,</span> <span class="n">dpt</span><span class="o">.</span><span class="n">usm_ndarray</span><span class="p">):</span>
+            <span class="k">raise</span> <span class="ne">TypeError</span><span class="p">(</span>
+                <span class="sa">f</span><span class="s2">&quot;output array must be of usm_ndarray type, got </span><span class="si">{</span><span class="nb">type</span><span class="p">(</span><span class="n">out</span><span class="p">)</span><span class="si">}</span><span class="s2">&quot;</span>
+            <span class="p">)</span>
+        <span class="k">if</span> <span class="ow">not</span> <span class="n">out</span><span class="o">.</span><span class="n">flags</span><span class="o">.</span><span class="n">writable</span><span class="p">:</span>
+            <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="s2">&quot;provided `out` array is read-only&quot;</span><span class="p">)</span>
+
+        <span class="k">if</span> <span class="n">out</span><span class="o">.</span><span class="n">shape</span> <span class="o">!=</span> <span class="n">res_shape</span><span class="p">:</span>
+            <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span>
+                <span class="s2">&quot;The shape of input and output arrays are inconsistent. &quot;</span>
+                <span class="sa">f</span><span class="s2">&quot;Expected output shape is </span><span class="si">{</span><span class="n">res_shape</span><span class="si">}</span><span class="s2">, got </span><span class="si">{</span><span class="n">out</span><span class="o">.</span><span class="n">shape</span><span class="si">}</span><span class="s2">&quot;</span>
+            <span class="p">)</span>
+        <span class="k">if</span> <span class="n">dt</span> <span class="o">!=</span> <span class="n">out</span><span class="o">.</span><span class="n">dtype</span><span class="p">:</span>
+            <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span>
+                <span class="sa">f</span><span class="s2">&quot;Output array of type </span><span class="si">{</span><span class="n">dt</span><span class="si">}</span><span class="s2"> is needed, got </span><span class="si">{</span><span class="n">out</span><span class="o">.</span><span class="n">dtype</span><span class="si">}</span><span class="s2">&quot;</span>
+            <span class="p">)</span>
+        <span class="k">if</span> <span class="n">dpctl</span><span class="o">.</span><span class="n">utils</span><span class="o">.</span><span class="n">get_execution_queue</span><span class="p">((</span><span class="n">exec_q</span><span class="p">,</span> <span class="n">out</span><span class="o">.</span><span class="n">sycl_queue</span><span class="p">))</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
+            <span class="k">raise</span> <span class="n">dpctl</span><span class="o">.</span><span class="n">utils</span><span class="o">.</span><span class="n">ExecutionPlacementError</span><span class="p">(</span>
+                <span class="s2">&quot;Input and output allocation queues are not compatible&quot;</span>
+            <span class="p">)</span>
+        <span class="k">if</span> <span class="n">ti</span><span class="o">.</span><span class="n">_array_overlap</span><span class="p">(</span><span class="n">x</span><span class="p">,</span> <span class="n">out</span><span class="p">):</span>
+            <span class="n">out</span> <span class="o">=</span> <span class="n">dpt</span><span class="o">.</span><span class="n">empty_like</span><span class="p">(</span><span class="n">out</span><span class="p">)</span>
+    <span class="k">else</span><span class="p">:</span>
+        <span class="n">out</span> <span class="o">=</span> <span class="n">dpt</span><span class="o">.</span><span class="n">empty</span><span class="p">(</span>
+            <span class="n">res_shape</span><span class="p">,</span> <span class="n">dtype</span><span class="o">=</span><span class="n">dt</span><span class="p">,</span> <span class="n">usm_type</span><span class="o">=</span><span class="n">res_usm_type</span><span class="p">,</span> <span class="n">sycl_queue</span><span class="o">=</span><span class="n">exec_q</span>
+        <span class="p">)</span>
 
     <span class="n">_manager</span> <span class="o">=</span> <span class="n">dpctl</span><span class="o">.</span><span class="n">utils</span><span class="o">.</span><span class="n">SequentialOrderManager</span><span class="p">[</span><span class="n">exec_q</span><span class="p">]</span>
     <span class="n">deps_ev</span> <span class="o">=</span> <span class="n">_manager</span><span class="o">.</span><span class="n">submitted_events</span>
     <span class="n">hev</span><span class="p">,</span> <span class="n">take_ev</span> <span class="o">=</span> <span class="n">ti</span><span class="o">.</span><span class="n">_take</span><span class="p">(</span>
-        <span class="n">x</span><span class="p">,</span> <span class="p">(</span><span class="n">indices</span><span class="p">,),</span> <span class="n">res</span><span class="p">,</span> <span class="n">axis</span><span class="p">,</span> <span class="n">mode</span><span class="p">,</span> <span class="n">sycl_queue</span><span class="o">=</span><span class="n">exec_q</span><span class="p">,</span> <span class="n">depends</span><span class="o">=</span><span class="n">deps_ev</span>
+        <span class="n">x</span><span class="p">,</span> <span class="p">(</span><span class="n">indices</span><span class="p">,),</span> <span class="n">out</span><span class="p">,</span> <span class="n">axis</span><span class="p">,</span> <span class="n">mode</span><span class="p">,</span> <span class="n">sycl_queue</span><span class="o">=</span><span class="n">exec_q</span><span class="p">,</span> <span class="n">depends</span><span class="o">=</span><span class="n">deps_ev</span>
     <span class="p">)</span>
     <span class="n">_manager</span><span class="o">.</span><span class="n">add_event_pair</span><span class="p">(</span><span class="n">hev</span><span class="p">,</span> <span class="n">take_ev</span><span class="p">)</span>
 
-    <span class="k">return</span> <span class="n">res</span></div>
+    <span class="k">if</span> <span class="ow">not</span> <span class="p">(</span><span class="n">orig_out</span> <span class="ow">is</span> <span class="kc">None</span> <span class="ow">or</span> <span class="n">out</span> <span class="ow">is</span> <span class="n">orig_out</span><span class="p">):</span>
+        <span class="c1"># Copy the out data from temporary buffer to original memory</span>
+        <span class="n">ht_e_cpy</span><span class="p">,</span> <span class="n">cpy_ev</span> <span class="o">=</span> <span class="n">ti</span><span class="o">.</span><span class="n">_copy_usm_ndarray_into_usm_ndarray</span><span class="p">(</span>
+            <span class="n">src</span><span class="o">=</span><span class="n">out</span><span class="p">,</span> <span class="n">dst</span><span class="o">=</span><span class="n">orig_out</span><span class="p">,</span> <span class="n">sycl_queue</span><span class="o">=</span><span class="n">exec_q</span><span class="p">,</span> <span class="n">depends</span><span class="o">=</span><span class="p">[</span><span class="n">take_ev</span><span class="p">]</span>
+        <span class="p">)</span>
+        <span class="n">_manager</span><span class="o">.</span><span class="n">add_event_pair</span><span class="p">(</span><span class="n">ht_e_cpy</span><span class="p">,</span> <span class="n">cpy_ev</span><span class="p">)</span>
+        <span class="n">out</span> <span class="o">=</span> <span class="n">orig_out</span>
+
+    <span class="k">return</span> <span class="n">out</span></div>
 
 
 <div class="viewcode-block" id="put"><a class="viewcode-back" href="../../../api_reference/dpctl/generated/dpctl.tensor.put.html#dpctl.tensor.put">[docs]</a><span class="k">def</span><span class="w"> </span><span class="nf">put</span><span class="p">(</span><span class="n">x</span><span class="p">,</span> <span class="n">indices</span><span class="p">,</span> <span class="n">vals</span><span class="p">,</span> <span class="o">/</span><span class="p">,</span> <span class="o">*</span><span class="p">,</span> <span class="n">axis</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">mode</span><span class="o">=</span><span class="s2">&quot;wrap&quot;</span><span class="p">):</span>

pulls/2019/_sources/api_reference/dpctl/constants.rst.txt

@@ -1,7 +1,7 @@
 .. _dpctl_constants:
 
 Constants
-========================
+=========
 
 The following constants are defined in :py:mod:`dpctl`:
 

pulls/2019/_sources/api_reference/dpctl/tensor.constants.rst.txt

@@ -1,7 +1,7 @@
 .. _dpctl_tensor_constants:
 
 Constants
-========================
+=========
 
 The following constants are defined in :py:mod:`dpctl.tensor`:
 

pulls/2019/api_reference/dpctl/generated/dpctl.tensor.take.html

@@ -791,7 +791,7 @@
 <h1>dpctl.tensor.take<a class="headerlink" href="#dpctl-tensor-take" title="Permalink to this heading">¶</a></h1>
 <dl class="py function">
 <dt class="sig sig-object py" id="dpctl.tensor.take">
-<span class="sig-prename descclassname"><span class="pre">dpctl.tensor.</span></span><span class="sig-name descname"><span class="pre">take</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">x</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">indices</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">axis</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">mode</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'wrap'</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../../../_modules/dpctl/tensor/_indexing_functions.html#take"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#dpctl.tensor.take" title="Permalink to this definition">¶</a></dt>
+<span class="sig-prename descclassname"><span class="pre">dpctl.tensor.</span></span><span class="sig-name descname"><span class="pre">take</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">x</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">indices</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">axis</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">out</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">mode</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'wrap'</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="../../../_modules/dpctl/tensor/_indexing_functions.html#take"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#dpctl.tensor.take" title="Permalink to this definition">¶</a></dt>
 <dd><p>Takes elements from an array along a given axis at given indices.</p>
 <dl class="field-list simple">
 <dt class="field-odd">Parameters<span class="colon">:</span></dt>
@@ -801,6 +801,8 @@ <h1>dpctl.tensor.take<a class="headerlink" href="#dpctl-tensor-take" title="Perm
 <li><p><strong>axis</strong> (<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><em>optional</em>) – The axis along which the values will be selected.
 If <code class="docutils literal notranslate"><span class="pre">x</span></code> is one-dimensional, this argument is optional.
 Default: <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p></li>
+<li><p><strong>out</strong> (<em>Optional</em><em>[</em><a class="reference internal" href="dpctl.tensor.usm_ndarray.html#dpctl.tensor.usm_ndarray" title="dpctl.tensor.usm_ndarray"><em>usm_ndarray</em></a><em>]</em>) – Output array to populate. Array must have the correct
+shape and the expected data type.</p></li>
 <li><p><strong>mode</strong> (<a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.13)"><em>str</em></a><em>, </em><em>optional</em>) – <p>How out-of-bounds indices will be handled. Possible values
 are:</p>
 <ul>

pulls/2019/api_reference/dpctl/tensor.indexing_functions.html

@@ -806,7 +806,7 @@
 <tr class="row-even"><td><p><a class="reference internal" href="generated/dpctl.tensor.put_along_axis.html#dpctl.tensor.put_along_axis" title="dpctl.tensor.put_along_axis"><code class="xref py py-obj docutils literal notranslate"><span class="pre">put_along_axis</span></code></a>(x, indices, vals, /, *[, ...])</p></td>
 <td><p>Puts elements into an array at the one-dimensional indices specified by <code class="docutils literal notranslate"><span class="pre">indices</span></code> along a provided <code class="docutils literal notranslate"><span class="pre">axis</span></code>.</p></td>
 </tr>
-<tr class="row-odd"><td><p><a class="reference internal" href="generated/dpctl.tensor.take.html#dpctl.tensor.take" title="dpctl.tensor.take"><code class="xref py py-obj docutils literal notranslate"><span class="pre">take</span></code></a>(x, indices[, axis, mode])</p></td>
+<tr class="row-odd"><td><p><a class="reference internal" href="generated/dpctl.tensor.take.html#dpctl.tensor.take" title="dpctl.tensor.take"><code class="xref py py-obj docutils literal notranslate"><span class="pre">take</span></code></a>(x, indices[, axis, out, mode])</p></td>
 <td><p>Takes elements from an array along a given axis at given indices.</p></td>
 </tr>
 <tr class="row-even"><td><p><a class="reference internal" href="generated/dpctl.tensor.take_along_axis.html#dpctl.tensor.take_along_axis" title="dpctl.tensor.take_along_axis"><code class="xref py py-obj docutils literal notranslate"><span class="pre">take_along_axis</span></code></a>(x, indices, /, *[, axis, mode])</p></td>