Docs for pull request 2099

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

pulls/2099/_sources/beginners_guides/installation.rst.txt

@@ -159,6 +159,13 @@ The following plugins from CodePlay are supported:
 .. _codeplay_nv_plugin: https://developer.codeplay.com/products/oneapi/nvidia/
 .. _codeplay_amd_plugin: https://developer.codeplay.com/products/oneapi/amd/
 
+Builds for CUDA and AMD devices internally use SYCL alias targets that are passed to the compiler.
+A full list of available SYCL alias targets is available in the
+`DPC++ Compiler User Manual <https://intel.github.io/llvm/UsersManual.html>`_.
+
+CUDA build
+~~~~~~~~~~
+
 ``dpctl`` can be built for CUDA devices using the ``DPCTL_TARGET_CUDA`` CMake option,
 which accepts a specific compute architecture string:
 
@@ -173,19 +180,20 @@ set ``DPCTL_TARGET_CUDA`` to a value such as ``ON``, ``TRUE``, ``YES``, ``Y``, o
 
     python scripts/build_locally.py --verbose --cmake-opts="-DDPCTL_TARGET_CUDA=ON"
 
-Note that kernels are built for ``sm_50`` by default, allowing them to work on a wider
-range of architectures, but limiting the usage of more recent CUDA features.
+Note that kernels are built for the default architecture (``sm_50``), allowing them to work on a
+wider range of architectures, but limiting the usage of more recent CUDA features.
 
 For reference, compute architecture strings like ``sm_80`` correspond to specific
 CUDA Compute Capabilities (e.g., Compute Capability 8.0 corresponds to ``sm_80``).
 A complete mapping between NVIDIA GPU models and their respective
 Compute Capabilities can be found in the official
 `CUDA GPU Compute Capability <https://developer.nvidia.com/cuda-gpus>`_ documentation.
 
-A full list of available SYCL alias targets is available in the
-`DPC++ Compiler User Manual <https://intel.github.io/llvm/UsersManual.html>`_.
+AMD build
+~~~~~~~~~
 
-To build for AMD devices, use:
+``dpctl`` can be built for AMD devices using the ``DPCTL_TARGET_HIP`` CMake option,
+which requires specifying a compute architecture string:
 
 .. code-block:: bash
 
@@ -207,8 +215,13 @@ For example:
 .. code-block:: bash
     python scripts/build_locally.py --verbose --cmake-opts="-DDPCTL_TARGET_HIP=gfx1030"
 
-It is, however, possible to build for Intel devices, CUDA devices, and an AMD device
-architecture all at once:
+Multi-target build
+~~~~~~~~~~~~~~~~~~
+
+The default ``dpctl`` build from the source enables support of Intel devices only.
+Extending the build with a custom SYCL target additionally enables support of CUDA or AMD
+device in ``dpctl``. Besides, the support can be also extended to enable both CUDA and AMD
+devices at the same time:
 
 .. code-block:: bash
 

pulls/2099/api_reference/dpctl/generated/dpctl.tensor.asarray.html

@@ -810,7 +810,7 @@ <h1>dpctl.tensor.asarray<a class="headerlink" href="#dpctl-tensor-asarray" title
 <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>,
 an object representing SYCL USM allocation and implementing
 <code class="docutils literal notranslate"><span class="pre">__sycl_usm_array_interface__</span></code> protocol, an instance
-of <a class="reference external" href="https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray" title="(in NumPy v2.2)"><code class="xref py py-class docutils literal notranslate"><span class="pre">numpy.ndarray</span></code></a>, an object supporting Python buffer
+of <a class="reference external" href="https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray" title="(in NumPy v2.3)"><code class="xref py py-class docutils literal notranslate"><span class="pre">numpy.ndarray</span></code></a>, an object supporting Python buffer
 protocol, a Python scalar, or a (possibly nested) sequence of
 Python scalars.</p></li>
 <li><p><strong>dtype</strong> (<em>data type</em><em>, </em><em>optional</em>) – output array data type. If <code class="docutils literal notranslate"><span class="pre">dtype</span></code> is

pulls/2099/api_reference/dpctl/generated/dpctl.tensor.astype.html

@@ -814,7 +814,7 @@ <h1>dpctl.tensor.astype<a class="headerlink" href="#dpctl-tensor-astype" title="
 <li><p><strong>order</strong> (<em>{&quot;C&quot;</em><em>, </em><em>&quot;F&quot;</em><em>, </em><em>&quot;A&quot;</em><em>, </em><em>&quot;K&quot;}</em><em>, </em><em>optional</em>) – Controls memory layout of the resulting array if a copy
 is returned.</p></li>
 <li><p><strong>casting</strong> (<em>{'no'</em><em>, </em><em>'equiv'</em><em>, </em><em>'safe'</em><em>, </em><em>'same_kind'</em><em>, </em><em>'unsafe'}</em><em>, </em><em>optional</em>) – Controls what kind of data casting may occur. Please see
-<a class="reference external" href="https://numpy.org/doc/stable/reference/generated/numpy.ndarray.astype.html#numpy.ndarray.astype" title="(in NumPy v2.2)"><code class="xref py py-meth docutils literal notranslate"><span class="pre">numpy.ndarray.astype()</span></code></a> for description of casting modes.</p></li>
+<a class="reference external" href="https://numpy.org/doc/stable/reference/generated/numpy.ndarray.astype.html#numpy.ndarray.astype" title="(in NumPy v2.3)"><code class="xref py py-meth docutils literal notranslate"><span class="pre">numpy.ndarray.astype()</span></code></a> for description of casting modes.</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>) – By default, <cite>astype</cite> always returns a newly allocated array.
 If this keyword is set to <cite>False</cite>, a view of the input array
 may be returned when possible.</p></li>

pulls/2099/api_reference/dpctl/generated/dpctl.tensor.empty.html

@@ -809,7 +809,7 @@ <h1>dpctl.tensor.empty<a class="headerlink" href="#dpctl-tensor-empty" title="Pe
 <dd class="field-odd"><ul class="simple">
 <li><p><strong>shape</strong> (<em>Tuple</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><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>) – Dimensions of the array to be created.</p></li>
 <li><p><strong>dtype</strong> (<em>optional</em>) – data type of the array. Can be typestring,
-a <a class="reference external" href="https://numpy.org/doc/stable/reference/generated/numpy.dtype.html#numpy.dtype" title="(in NumPy v2.2)"><code class="xref py py-class docutils literal notranslate"><span class="pre">numpy.dtype</span></code></a> object, <a class="reference external" href="https://numpy.org/doc/stable/reference/index.html#module-numpy" title="(in NumPy v2.2)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">numpy</span></code></a> char string,
+a <a class="reference external" href="https://numpy.org/doc/stable/reference/generated/numpy.dtype.html#numpy.dtype" title="(in NumPy v2.3)"><code class="xref py py-class docutils literal notranslate"><span class="pre">numpy.dtype</span></code></a> object, <a class="reference external" href="https://numpy.org/doc/stable/reference/index.html#module-numpy" title="(in NumPy v2.3)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">numpy</span></code></a> char string,
 or a NumPy scalar type. The <code class="docutils literal notranslate"><span class="pre">None</span></code> value creates an
 array of floating point data type. Default: <code class="docutils literal notranslate"><span class="pre">None</span></code></p></li>
 <li><p><strong>order</strong> (<code class="docutils literal notranslate"><span class="pre">&quot;C&quot;</span></code>, or <code class="docutils literal notranslate"><span class="pre">F&quot;</span></code>) – memory layout for the array. Default: <code class="docutils literal notranslate"><span class="pre">&quot;C&quot;</span></code></p></li>

pulls/2099/api_reference/dpctl/generated/dpctl.tensor.empty_like.html

@@ -809,7 +809,7 @@ <h1>dpctl.tensor.empty_like<a class="headerlink" href="#dpctl-tensor-empty-like"
 <dd class="field-odd"><ul class="simple">
 <li><p><strong>x</strong> (<a class="reference internal" href="dpctl.tensor.usm_ndarray.html#dpctl.tensor.usm_ndarray" title="dpctl.tensor.usm_ndarray"><em>usm_ndarray</em></a>) – Input array from which to derive the output array shape.</p></li>
 <li><p><strong>dtype</strong> (<em>optional</em>) – data type of the array. Can be a typestring,
-a <a class="reference external" href="https://numpy.org/doc/stable/reference/generated/numpy.dtype.html#numpy.dtype" title="(in NumPy v2.2)"><code class="xref py py-class docutils literal notranslate"><span class="pre">numpy.dtype</span></code></a> object, NumPy char string,
+a <a class="reference external" href="https://numpy.org/doc/stable/reference/generated/numpy.dtype.html#numpy.dtype" title="(in NumPy v2.3)"><code class="xref py py-class docutils literal notranslate"><span class="pre">numpy.dtype</span></code></a> object, NumPy char string,
 or a NumPy scalar type. Default: <code class="docutils literal notranslate"><span class="pre">None</span></code></p></li>
 <li><p><strong>order</strong> (<em>&quot;C&quot;</em><em>, </em><em>&quot;F&quot;</em><em>, </em><em>&quot;A&quot;</em><em>, or </em><em>&quot;K&quot;</em>) – memory layout for the array. Default: <code class="docutils literal notranslate"><span class="pre">&quot;K&quot;</span></code></p></li>
 <li><p><strong>device</strong> (<em>optional</em>) – array API concept of device where the output array

pulls/2099/api_reference/dpctl/generated/dpctl.tensor.eye.html

@@ -816,7 +816,7 @@ <h1>dpctl.tensor.eye<a class="headerlink" href="#dpctl-tensor-eye" title="Permal
 Raises <a class="reference external" href="https://docs.python.org/3/library/exceptions.html#TypeError" title="(in Python v3.13)"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> if <code class="docutils literal notranslate"><span class="pre">k</span></code> is not an integer.
 Default: <code class="docutils literal notranslate"><span class="pre">0</span></code></p></li>
 <li><p><strong>dtype</strong> (<em>optional</em>) – data type of the array. Can be typestring,
-a <a class="reference external" href="https://numpy.org/doc/stable/reference/generated/numpy.dtype.html#numpy.dtype" title="(in NumPy v2.2)"><code class="xref py py-class docutils literal notranslate"><span class="pre">numpy.dtype</span></code></a> object, <a class="reference external" href="https://numpy.org/doc/stable/reference/index.html#module-numpy" title="(in NumPy v2.2)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">numpy</span></code></a> char string, or
+a <a class="reference external" href="https://numpy.org/doc/stable/reference/generated/numpy.dtype.html#numpy.dtype" title="(in NumPy v2.3)"><code class="xref py py-class docutils literal notranslate"><span class="pre">numpy.dtype</span></code></a> object, <a class="reference external" href="https://numpy.org/doc/stable/reference/index.html#module-numpy" title="(in NumPy v2.3)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">numpy</span></code></a> char string, or
 a NumPy scalar type. Default: <code class="docutils literal notranslate"><span class="pre">None</span></code></p></li>
 <li><p><strong>order</strong> (<em>&quot;C&quot;</em><em> or </em><em>&quot;F&quot;</em>) – memory layout for the array. Default: <code class="docutils literal notranslate"><span class="pre">&quot;C&quot;</span></code></p></li>
 <li><p><strong>device</strong> (<em>optional</em>) – array API concept of device where the output array

pulls/2099/api_reference/dpctl/generated/dpctl.tensor.from_dlpack.html

@@ -802,7 +802,7 @@ <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> or <a class="reference external" href="https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray" title="(in NumPy v2.2)"><code class="xref py py-class docutils literal notranslate"><span class="pre">numpy.ndarray</span></code></a>
+<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.3)"><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>
@@ -877,7 +877,7 @@ <h1>dpctl.tensor.from_dlpack<a class="headerlink" href="#dpctl-tensor-from-dlpac
 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.2)"><code class="xref py py-class docutils literal notranslate"><span class="pre">numpy.ndarray</span></code></a>,
+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.3)"><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>
@@ -892,7 +892,7 @@ <h1>dpctl.tensor.from_dlpack<a class="headerlink" href="#dpctl-tensor-from-dlpac
 </p>
 </dd>
 <dt class="field-odd">Return type<span class="colon">:</span></dt>
-<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.2)">numpy.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.3)">numpy.ndarray</a>]</p>
 </dd>
 <dt class="field-even">Raises<span class="colon">:</span></dt>
 <dd class="field-even"><ul class="simple">

pulls/2099/api_reference/dpctl/generated/dpctl.tensor.from_numpy.html

@@ -803,11 +803,11 @@ <h1>dpctl.tensor.from_numpy<a class="headerlink" href="#dpctl-tensor-from-numpy"
 <dt class="sig sig-object py" id="dpctl.tensor.from_numpy">
 <span class="sig-prename descclassname"><span class="pre">dpctl.tensor.</span></span><span class="sig-name descname"><span class="pre">from_numpy</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">arg</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">usm_type</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'device'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">sycl_queue</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="reference internal" href="../../../_modules/dpctl/tensor/_copy_utils.html#from_numpy"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#dpctl.tensor.from_numpy" title="Permalink to this definition">¶</a></dt>
 <dd><p>Creates <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> from instance of
-<a class="reference external" href="https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray" title="(in NumPy v2.2)"><code class="xref py py-class docutils literal notranslate"><span class="pre">numpy.ndarray</span></code></a>.</p>
+<a class="reference external" href="https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray" title="(in NumPy v2.3)"><code class="xref py py-class docutils literal notranslate"><span class="pre">numpy.ndarray</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>arg</strong> – Input convertible to <a class="reference external" href="https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray" title="(in NumPy v2.2)"><code class="xref py py-class docutils literal notranslate"><span class="pre">numpy.ndarray</span></code></a></p></li>
+<li><p><strong>arg</strong> – Input convertible to <a class="reference external" href="https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray" title="(in NumPy v2.3)"><code class="xref py py-class docutils literal notranslate"><span class="pre">numpy.ndarray</span></code></a></p></li>
 <li><p><strong>device</strong> (<a class="reference external" href="https://docs.python.org/3/library/functions.html#object" title="(in Python v3.13)"><em>object</em></a>) – array API specification of device where the
 output array is created. Device can be specified by
 a filter selector string, an instance of