Latest docs.

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

master/api_reference/dpctl/generated/dpctl.tensor.from_dlpack.html

@@ -821,60 +821,96 @@ <h1>dpctl.tensor.from_dlpack<a class="headerlink" href="#dpctl-tensor-from-dlpac
 <dl class="py function">
 <dt class="sig sig-object py" id="dpctl.tensor.from_dlpack">
 <span class="sig-prename descclassname"><span class="pre">dpctl.tensor.</span></span><span class="sig-name descname"><span class="pre">from_dlpack</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="o"><span class="pre">/</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">*</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">device</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">copy</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#dpctl.tensor.from_dlpack" title="Permalink to this definition">¶</a></dt>
-<dd><p>Constructs <a class="reference internal" href="dpctl.tensor.usm_ndarray.html#dpctl.tensor.usm_ndarray" title="dpctl.tensor.usm_ndarray"><code class="xref py py-class docutils literal notranslate"><span class="pre">dpctl.tensor.usm_ndarray</span></code></a> instance from a Python
-object <code class="docutils literal notranslate"><span class="pre">x</span></code> that implements <code class="docutils literal notranslate"><span class="pre">__dlpack__</span></code> protocol.</p>
+<dd><p>Constructs <a class="reference internal" href="dpctl.tensor.usm_ndarray.html#dpctl.tensor.usm_ndarray" title="dpctl.tensor.usm_ndarray"><code class="xref py py-class docutils literal notranslate"><span class="pre">dpctl.tensor.usm_ndarray</span></code></a> or <a class="reference external" href="https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray" title="(in NumPy v2.1)"><code class="xref py py-class docutils literal notranslate"><span class="pre">numpy.ndarray</span></code></a> instance
+from a Python object <code class="docutils literal notranslate"><span class="pre">x</span></code> that implements <code class="docutils literal notranslate"><span class="pre">__dlpack__</span></code> protocol.</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>x</strong> (<a class="reference external" href="https://docs.python.org/3/library/functions.html#object" title="(in Python v3.13)"><em>object</em></a>) – A Python object representing an array that supports
 <code class="docutils literal notranslate"><span class="pre">__dlpack__</span></code> protocol.</p></li>
-<li><p><strong>device</strong> (Optional[str, <a class="reference internal" href="dpctl.SyclDevice.html#dpctl.SyclDevice" title="dpctl.SyclDevice"><code class="xref py py-class docutils literal notranslate"><span class="pre">dpctl.SyclDevice</span></code></a>, <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>, <a class="reference internal" href="../tensor.utility_functions.html#dpctl.tensor.Device" title="dpctl.tensor.Device"><code class="xref py py-class docutils literal notranslate"><span class="pre">dpctl.tensor.Device</span></code></a>, tuple([<a class="reference external" href="https://docs.python.org/3/library/enum.html#enum.IntEnum" title="(in Python v3.13)"><code class="xref py py-class docutils literal notranslate"><span class="pre">enum.IntEnum</span></code></a>, int])])) – Array API concept of a device where the output array is to be placed.
-<code class="docutils literal notranslate"><span class="pre">device</span></code> can be <code class="docutils literal notranslate"><span class="pre">None</span></code>, a oneAPI filter selector
-string, an instance of <a class="reference internal" href="dpctl.SyclDevice.html#dpctl.SyclDevice" title="dpctl.SyclDevice"><code class="xref py py-class docutils literal notranslate"><span class="pre">dpctl.SyclDevice</span></code></a> corresponding to
-a non-partitioned SYCL device, an instance of
-<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>, a <a class="reference internal" href="../tensor.utility_functions.html#dpctl.tensor.Device" title="dpctl.tensor.Device"><code class="xref py py-class docutils literal notranslate"><span class="pre">dpctl.tensor.Device</span></code></a> object
-returned by <a class="reference internal" href="generated/dpctl.tensor.usm_ndarray.device.html#dpctl.tensor.usm_ndarray.device" title="dpctl.tensor.usm_ndarray.device"><code class="xref py py-attr docutils literal notranslate"><span class="pre">dpctl.tensor.usm_ndarray.device</span></code></a>, or a
-2-tuple matching the format of the output of the <code class="docutils literal notranslate"><span class="pre">__dlpack_device__</span></code>
-method, an integer enumerator representing the device type followed by
-an integer representing the index of the device. The only supported
-<a class="reference internal" href="../tensor.constants.html#dpctl.tensor.DLDeviceType" title="dpctl.tensor.DLDeviceType"><code class="xref py py-class docutils literal notranslate"><span class="pre">dpctl.tensor.DLDeviceType</span></code></a> types are “kDLCPU” and
-“kDLOneAPI”.
-Default: <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p></li>
-<li><p><strong>copy</strong> (<a class="reference external" href="https://docs.python.org/3/library/functions.html#bool" title="(in Python v3.13)"><em>bool</em></a><em>, </em><em>optional</em>) – <p>Boolean indicating whether or not to copy the input.</p>
+<li><p><strong>device</strong> (Optional[str, <a class="reference internal" href="dpctl.SyclDevice.html#dpctl.SyclDevice" title="dpctl.SyclDevice"><code class="xref py py-class docutils literal notranslate"><span class="pre">dpctl.SyclDevice</span></code></a>, <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>, <a class="reference internal" href="../tensor.utility_functions.html#dpctl.tensor.Device" title="dpctl.tensor.Device"><code class="xref py py-class docutils literal notranslate"><span class="pre">dpctl.tensor.Device</span></code></a>, tuple([<a class="reference external" href="https://docs.python.org/3/library/enum.html#enum.IntEnum" title="(in Python v3.13)"><code class="xref py py-class docutils literal notranslate"><span class="pre">enum.IntEnum</span></code></a>, int])])) – <p>Device where the output array is to be placed. <code class="docutils literal notranslate"><span class="pre">device</span></code> keyword values can be:</p>
 <ul>
 <li><dl class="simple">
-<dt>If <code class="docutils literal notranslate"><span class="pre">copy</span></code> is <code class="docutils literal notranslate"><span class="pre">True</span></code>, the input will always be</dt><dd><p>copied.</p>
+<dt><code class="docutils literal notranslate"><span class="pre">None</span></code></dt><dd><p>The data remains on the same device.</p>
+</dd>
+</dl>
+</li>
+<li><dl class="simple">
+<dt>oneAPI filter selector string</dt><dd><p>SYCL device selected by <a class="reference internal" href="../filter_selector_string.html#filter-selector-string"><span class="std std-ref">filter selector string</span></a>.</p>
 </dd>
 </dl>
 </li>
 <li><dl class="simple">
-<dt>If <code class="docutils literal notranslate"><span class="pre">False</span></code>, a <code class="docutils literal notranslate"><span class="pre">BufferError</span></code> will be raised if a</dt><dd><p>copy is deemed necessary.</p>
+<dt><a class="reference internal" href="dpctl.SyclDevice.html#dpctl.SyclDevice" title="dpctl.SyclDevice"><code class="xref py py-class docutils literal notranslate"><span class="pre">dpctl.SyclDevice</span></code></a></dt><dd><p>explicit SYCL device that must correspond to
+a non-partitioned SYCL device.</p>
 </dd>
 </dl>
 </li>
 <li><dl class="simple">
-<dt>If <code class="docutils literal notranslate"><span class="pre">None</span></code>, a copy will be made only if deemed</dt><dd><p>necessary, otherwise, the existing memory buffer will
-be reused.</p>
+<dt><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></dt><dd><p>implies SYCL device targeted by the SYCL queue.</p>
+</dd>
+</dl>
+</li>
+<li><dl class="simple">
+<dt><a class="reference internal" href="../tensor.utility_functions.html#dpctl.tensor.Device" title="dpctl.tensor.Device"><code class="xref py py-class docutils literal notranslate"><span class="pre">dpctl.tensor.Device</span></code></a></dt><dd><p>implies SYCL device <cite>device.sycl_queue</cite>. The <cite>Device</cite> object
+is obtained via <a class="reference internal" href="generated/dpctl.tensor.usm_ndarray.device.html#dpctl.tensor.usm_ndarray.device" title="dpctl.tensor.usm_ndarray.device"><code class="xref py py-attr docutils literal notranslate"><span class="pre">dpctl.tensor.usm_ndarray.device</span></code></a>.</p>
+</dd>
+</dl>
+</li>
+<li><dl class="simple">
+<dt><code class="docutils literal notranslate"><span class="pre">(device_type,</span> <span class="pre">device_id)</span></code></dt><dd><p>2-tuple matching the format of the output of the <code class="docutils literal notranslate"><span class="pre">__dlpack_device__</span></code>
+method: an integer enumerator representing the device type followed by
+an integer representing the index of the device.
+The only supported <a class="reference internal" href="../tensor.constants.html#dpctl.tensor.DLDeviceType" title="dpctl.tensor.DLDeviceType"><code class="xref py py-class docutils literal notranslate"><span class="pre">dpctl.tensor.DLDeviceType</span></code></a> device types
+are <code class="docutils literal notranslate"><span class="pre">&quot;kDLCPU&quot;</span></code> and <code class="docutils literal notranslate"><span class="pre">&quot;kDLOneAPI&quot;</span></code>.</p>
 </dd>
 </dl>
 </li>
 </ul>
 <p>Default: <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>
 </p></li>
+<li><p><strong>copy</strong> (<a class="reference external" href="https://docs.python.org/3/library/functions.html#bool" title="(in Python v3.13)"><em>bool</em></a><em>, </em><em>optional</em>) – <p>Boolean indicating whether or not to copy the input.</p>
+<ul>
+<li><p>If <code class="docutils literal notranslate"><span class="pre">copy</span></code> is <code class="docutils literal notranslate"><span class="pre">True</span></code>, the input will always be
+copied.</p></li>
+<li><p>If <code class="docutils literal notranslate"><span class="pre">False</span></code>, a <code class="docutils literal notranslate"><span class="pre">BufferError</span></code> will be raised if a
+copy is deemed necessary.</p></li>
+<li><p>If <code class="docutils literal notranslate"><span class="pre">None</span></code>, a copy will be made only if deemed
+necessary, otherwise, the existing memory buffer will
+be reused.</p></li>
+</ul>
+<p>Default: <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>
+</p></li>
 </ul>
 </dd>
 <dt class="field-even">Returns<span class="colon">:</span></dt>
-<dd class="field-even"><p>An array containing the data in <code class="docutils literal notranslate"><span class="pre">x</span></code>. When <code class="docutils literal notranslate"><span class="pre">copy</span></code> is
+<dd class="field-even"><p><p>An array containing the data in <code class="docutils literal notranslate"><span class="pre">x</span></code>. When <code class="docutils literal notranslate"><span class="pre">copy</span></code> is
 <code class="docutils literal notranslate"><span class="pre">None</span></code> or <code class="docutils literal notranslate"><span class="pre">False</span></code>, this may be a view into the original
 memory.</p>
+<p>The type of the returned object
+depends on where the data backing up input object <code class="docutils literal notranslate"><span class="pre">x</span></code> resides.
+If it resides in a USM allocation on a SYCL device, the
+type <a class="reference internal" href="dpctl.tensor.usm_ndarray.html#dpctl.tensor.usm_ndarray" title="dpctl.tensor.usm_ndarray"><code class="xref py py-class docutils literal notranslate"><span class="pre">dpctl.tensor.usm_ndarray</span></code></a> is returned, otherwise if it resides
+on <code class="docutils literal notranslate"><span class="pre">&quot;kDLCPU&quot;</span></code> device the type is <a class="reference external" href="https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray" title="(in NumPy v2.1)"><code class="xref py py-class docutils literal notranslate"><span class="pre">numpy.ndarray</span></code></a>, and otherwise
+an exception is raised.</p>
+<div class="admonition note">
+<p class="admonition-title">Note</p>
+<p>If the return type is <a class="reference internal" href="dpctl.tensor.usm_ndarray.html#dpctl.tensor.usm_ndarray" title="dpctl.tensor.usm_ndarray"><code class="xref py py-class docutils literal notranslate"><span class="pre">dpctl.tensor.usm_ndarray</span></code></a>, the associated
+SYCL queue is derived from the <code class="docutils literal notranslate"><span class="pre">device</span></code> keyword. When <code class="docutils literal notranslate"><span class="pre">device</span></code>
+keyword value has type <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>, the explicit queue
+instance is used, when <code class="docutils literal notranslate"><span class="pre">device</span></code> keyword value has type <a class="reference internal" href="../tensor.utility_functions.html#dpctl.tensor.Device" title="dpctl.tensor.Device"><code class="xref py py-class docutils literal notranslate"><span class="pre">dpctl.tensor.Device</span></code></a>,
+the <code class="docutils literal notranslate"><span class="pre">device.sycl_queue</span></code> is used. In all other cases, the cached
+SYCL queue corresponding to the implied SYCL device is used.</p>
+</div>
+</p>
 </dd>
 <dt class="field-odd">Return type<span class="colon">:</span></dt>
-<dd class="field-odd"><p><a class="reference internal" href="dpctl.tensor.usm_ndarray.html#dpctl.tensor.usm_ndarray" title="dpctl.tensor.usm_ndarray">usm_ndarray</a></p>
+<dd class="field-odd"><p>Alternative[<a class="reference internal" href="dpctl.tensor.usm_ndarray.html#dpctl.tensor.usm_ndarray" title="dpctl.tensor.usm_ndarray">usm_ndarray</a>, <a class="reference external" href="https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray" title="(in NumPy v2.1)">numpy.ndarray</a>]</p>
 </dd>
 <dt class="field-even">Raises<span class="colon">:</span></dt>
 <dd class="field-even"><ul class="simple">
 <li><p><a class="reference external" href="https://docs.python.org/3/library/exceptions.html#TypeError" title="(in Python v3.13)"><strong>TypeError</strong></a> – if <code class="docutils literal notranslate"><span class="pre">x</span></code> does not implement <code class="docutils literal notranslate"><span class="pre">__dlpack__</span></code> method</p></li>
-<li><p><a class="reference external" href="https://docs.python.org/3/library/exceptions.html#ValueError" title="(in Python v3.13)"><strong>ValueError</strong></a> – if the input array resides on an unsupported device</p></li>
+<li><p><a class="reference external" href="https://docs.python.org/3/library/exceptions.html#ValueError" title="(in Python v3.13)"><strong>ValueError</strong></a> – if data of the input object resides on an unsupported device</p></li>
 </ul>
 </dd>
 </dl>
@@ -896,7 +932,9 @@ <h1>dpctl.tensor.from_dlpack<a class="headerlink" href="#dpctl-tensor-from-dlpac
         <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_array</span><span class="o">.</span><span class="n">__dlpack_device__</span><span class="p">()</span>
 
 <span class="n">C</span> <span class="o">=</span> <span class="n">Container</span><span class="p">(</span><span class="n">dpt</span><span class="o">.</span><span class="n">linspace</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">100</span><span class="p">,</span> <span class="n">num</span><span class="o">=</span><span class="mi">20</span><span class="p">,</span> <span class="n">dtype</span><span class="o">=</span><span class="s2">&quot;int16&quot;</span><span class="p">))</span>
+<span class="c1"># create usm_ndarray view</span>
 <span class="n">X</span> <span class="o">=</span> <span class="n">dpt</span><span class="o">.</span><span class="n">from_dlpack</span><span class="p">(</span><span class="n">C</span><span class="p">)</span>
+<span class="c1"># migrate content of the container to device of type kDLCPU</span>
 <span class="n">Y</span> <span class="o">=</span> <span class="n">dpt</span><span class="o">.</span><span class="n">from_dlpack</span><span class="p">(</span><span class="n">C</span><span class="p">,</span> <span class="n">device</span><span class="o">=</span><span class="p">(</span><span class="n">dpt</span><span class="o">.</span><span class="n">DLDeviceType</span><span class="o">.</span><span class="n">kDLCPU</span><span class="p">,</span> <span class="mi">0</span><span class="p">))</span>
 </pre></div>
 </div>