Add cross-reference fallback for dpnp.tensor to dpctl 0.21.1 docs (#2848)

This PR proposes to replace `dpctl.tensor` with `dpnp.tensor` across the
error messages.
Add a Sphinx handler to redirect dpnp.tensor.* cross-references to dpctl
0.21.1 docs
and `tensor.rst` page linking to the dpctl API reference

Author: vlad-perevezentsev

doc/conf.py

@@ -6,6 +6,7 @@
 # http://www.sphinx-doc.org/en/master/config
 
 from datetime import datetime
+from urllib.parse import urljoin
 
 from sphinx.ext.autodoc import FunctionDocumenter
 from sphinx.ext.napoleon import NumpyDocstring, docstring
@@ -231,6 +232,9 @@ def _can_document_member(member, *args, **kwargs):
 
 autosummary_generate = True
 
+_DPCTL_021_BASE = "https://intelpython.github.io/dpctl/0.21.1/"
+_DPCTL_021_INV = urljoin(_DPCTL_021_BASE, "objects.inv")
+
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3/", None),
     "numpy": ("https://numpy.org/doc/stable/", None),
@@ -302,3 +306,65 @@ def _parse_returns_section_patched(self, section: str) -> list[str]:
 
 
 NumpyDocstring._parse_returns_section = _parse_returns_section_patched
+
+
+# TODO: Remove once dpnp.tensor docs are generated in dpnp
+def _load_dpctl_tensor_inventory(app):
+    """Load dpctl 0.21.1 inventory for dpnp.tensor fallback only."""
+    from sphinx.ext.intersphinx import fetch_inventory
+    from sphinx.util import logging
+
+    logger = logging.getLogger(__name__)
+
+    try:
+        inv = fetch_inventory(app, _DPCTL_021_BASE, _DPCTL_021_INV)
+    except Exception as exc:
+        logger.warning(
+            "Failed to load dpctl 0.21.1 inventory from %s: %s",
+            _DPCTL_021_INV,
+            exc,
+        )
+        inv = {}
+
+    app.builder.env._dpctl_tensor_021_inventory = inv
+
+
+# TODO: Remove once dpnp.tensor docs are generated in dpnp
+def _resolve_dpnp_tensor_refs(app, env, node, contnode):
+    """Resolve dpnp.tensor.* references to dpctl 0.21.1 documentation.
+
+    This temporary workaround is needed because dpnp.tensor documentation
+    is not generated yet, while the corresponding API is still documented
+    in dpctl 0.21.1.
+    """
+    from docutils import nodes as docutils_nodes
+
+    target = node.get("reftarget", "")
+    if not target.startswith("dpnp.tensor"):
+        return None
+
+    dpctl_target = target.replace("dpnp.tensor", "dpctl.tensor", 1)
+    dpctl_tensor_inv = getattr(env, "_dpctl_tensor_021_inventory", {})
+
+    for _objtype, objects in dpctl_tensor_inv.items():
+        if dpctl_target not in objects:
+            continue
+
+        item = objects[dpctl_target]
+        location = item.uri
+        if location.endswith("$"):
+            location = location[:-1] + dpctl_target
+
+        refuri = urljoin(_DPCTL_021_BASE, location)
+        newnode = docutils_nodes.reference(
+            "", "", internal=False, refuri=refuri
+        )
+        newnode += contnode.deepcopy()
+        return newnode
+
+    return None
+
+
+def setup(app):
+    app.connect("builder-inited", _load_dpctl_tensor_inventory, priority=400)
+    app.connect("missing-reference", _resolve_dpnp_tensor_refs, priority=400)

doc/index.rst

@@ -13,6 +13,7 @@ Data Parallel Extension for NumPy*
    overview
    quick_start_guide
    reference/index
+   tensor
 
 .. toctree::
    :maxdepth: 1

doc/reference/exceptions.rst

@@ -20,7 +20,7 @@ Exceptions
 .. exception:: DLPackCreationError
 
    Given when constructing DLPack capsule from either :class:`dpnp.ndarray` or
-   :class:`dpctl.tensor.usm_ndarray` based on a USM allocation
+   :class:`dpnp.tensor.usm_ndarray` based on a USM allocation
    on a partitioned SYCL device.
 
    .. rubric:: Examples

doc/tensor.rst

@@ -0,0 +1,70 @@
+.. _tensor:
+
+Tensor (``dpnp.tensor``)
+========================
+
+``dpnp.tensor`` provides a reference implementation of the
+`Python Array API <https://data-apis.org/array-api/latest/>`_ specification.
+The implementation uses data-parallel algorithms suitable for execution on
+accelerators, such as GPUs.
+
+It also provides the underlying Array API-compliant implementation
+used by ``dpnp``.
+
+``dpnp.tensor`` is written using C++ and
+`SYCL <https://registry.khronos.org/SYCL/specs/sycl-2020/html/sycl-2020.html>`_
+and oneAPI extensions implemented in
+`Intel(R) oneAPI DPC++ compiler <https://www.intel.com/content/www/us/en/developer/tools/oneapi/dpc-compiler.html>`_.
+
+Design and Motivation
+---------------------
+
+The tensor implementation was originally developed as a standalone project and
+later integrated into the `dpctl <https://intelpython.github.io/dpctl/latest/index.html>`_
+library as ``dpctl.tensor``. It has since been migrated into ``dpnp``,
+making ``dpnp`` the primary owner and development location of the tensor implementation.
+
+This change simplifies maintenance, reduces cross-project
+dependencies, and enables independent development and release cycles.
+
+Relationship to ``dpnp.ndarray``
+--------------------------------
+
+:class:`dpnp.ndarray` is a high-level array object built on top of
+``dpnp.tensor.usm_ndarray``, storing array data in Unified Shared Memory
+(USM) allocated on a SYCL device. Most users interact with
+:class:`dpnp.ndarray` directly; ``dpnp.tensor.usm_ndarray`` may appear in error
+messages or type signatures when working with device placement or
+interoperability.
+
+Relationship to ``dpctl``
+-------------------------
+
+The migration of ``dpctl.tensor`` into ``dpnp.tensor`` does not replace
+`dpctl <https://intelpython.github.io/dpctl/latest/index.html>`_ itself.
+``dpctl`` remains responsible for device and queue management
+(:class:`dpctl.SyclDevice`, :class:`dpctl.SyclQueue`) as well as USM memory
+allocation. ``dpnp`` builds on top of these capabilities.
+
+Example
+-------
+
+.. code-block:: python
+
+    import dpnp
+    import dpnp.tensor as dpt
+
+    # Create a tensor array on the default device
+    x = dpt.asarray([1.0, 2.0, 3.0])
+
+    # dpnp.ndarray wraps the underlying usm_ndarray
+    a = dpnp.asarray([1.0, 2.0, 3.0])
+    assert isinstance(a.get_array(), dpt.usm_ndarray)
+
+.. note::
+
+   The ``dpnp.tensor`` API documentation will be added in a future release.
+
+   The current implementation remains compatible with the original
+   ``dpctl.tensor`` API. For the complete API reference, see the
+   `dpctl 0.21.1 tensor documentation <https://intelpython.github.io/dpctl/0.21.1/api_reference/dpctl/tensor.html>`_.

dpnp/dpnp_algo/dpnp_arraycreation.py

@@ -45,7 +45,7 @@
 
 
 def _as_usm_ndarray(a, usm_type, sycl_queue):
-    """Converts input object to `dpctl.tensor.usm_ndarray`"""
+    """Converts input object to `dpnp.tensor.usm_ndarray`"""
 
     if isinstance(a, dpnp_array):
         a = a.get_array()

dpnp/dpnp_algo/dpnp_elementwise_common.py

@@ -119,7 +119,7 @@ class DPNPUnaryFunc(UnaryElementwiseFunc):
             sycl_dev - The :class:`dpctl.SyclDevice` where the function
                 evaluation is carried out.
         The function is invoked when the argument of the unary function
-        requires casting, e.g. the argument of `dpctl.tensor.log` is an
+        requires casting, e.g. the argument of `dpnp.tensor.log` is an
         array with integral data type.
 
     """
@@ -137,7 +137,7 @@ def __init__(
         def _call_func(src, dst, sycl_queue, depends=None):
             """
             A callback to register in UnaryElementwiseFunc class of
-            dpctl.tensor
+            dpnp.tensor
             """
 
             if depends is None:
@@ -588,7 +588,7 @@ class DPNPBinaryFunc(BinaryElementwiseFunc):
                 evaluation is carried out.
         The function is only called when both arguments of the binary
         function require casting, e.g. both arguments of
-        `dpctl.tensor.logaddexp` are arrays with integral data type.
+        `dpnp.tensor.logaddexp` are arrays with integral data type.
     weak_type_resolver : {None, callable}, optional
         Function to influence type promotion behavior for Python scalar types
         of this binary function. The function takes 3 arguments:
@@ -615,7 +615,7 @@ def __init__(
         def _call_func(src1, src2, dst, sycl_queue, depends=None):
             """
             A callback to register in UnaryElementwiseFunc class of
-            dpctl.tensor
+            dpnp.tensor
             """
 
             if depends is None:

dpnp/dpnp_array.py

@@ -72,7 +72,7 @@ class dpnp_array:
     An array object represents a multidimensional tensor of numeric elements
     stored in a USM allocation on a SYCL device.
 
-    This is a wrapper around :class:`dpctl.tensor.usm_ndarray` that provides
+    This is a wrapper around :class:`dpnp.tensor.usm_ndarray` that provides
     methods to be compliant with original NumPy.
 
     """
@@ -609,12 +609,12 @@ def __usm_ndarray__(self):
         """
         Property to support ``__usm_ndarray__`` protocol.
 
-        It assumes to return :class:`dpctl.tensor.usm_ndarray` instance
+        It assumes to return :class:`dpnp.tensor.usm_ndarray` instance
         corresponding to the content of the object.
 
         This property is intended to speed-up conversion from
-        :class:`dpnp.ndarray` to :class:`dpctl.tensor.usm_ndarray` passed into
-        :func:`dpctl.tensor.asarray` function. The input object that implements
+        :class:`dpnp.ndarray` to :class:`dpnp.tensor.usm_ndarray` passed into
+        :func:`dpnp.tensor.asarray` function. The input object that implements
         ``__usm_ndarray__`` protocol is recognized as owner of USM allocation
         that is managed by a smart pointer, and asynchronous deallocation
         will not involve GIL.
@@ -631,13 +631,13 @@ def __xor__(self, other, /):
     def _create_from_usm_ndarray(usm_ary: dpt.usm_ndarray):
         """
         Return :class:`dpnp.ndarray` instance from USM allocation providing
-        by an instance of :class:`dpctl.tensor.usm_ndarray`.
+        by an instance of :class:`dpnp.tensor.usm_ndarray`.
 
         """
 
         if not isinstance(usm_ary, dpt.usm_ndarray):
             raise TypeError(
-                f"Expected dpctl.tensor.usm_ndarray, got {type(usm_ary)}"
+                f"Expected dpnp.tensor.usm_ndarray, got {type(usm_ary)}"
             )
         res = dpnp_array.__new__(dpnp_array)
         res._array_obj = usm_ary
@@ -956,7 +956,7 @@ def astype(
             `device` can be ``None``, a oneAPI filter selector string,
             an instance of :class:`dpctl.SyclDevice` corresponding to
             a non-partitioned SYCL device, an instance of
-            :class:`dpctl.SyclQueue`, or a :class:`dpctl.tensor.Device` object
+            :class:`dpctl.SyclQueue`, or a :class:`dpnp.tensor.Device` object
             returned by :attr:`dpnp.ndarray.device`.
             If the value is ``None``, returned array is created on the same
             device as that array.
@@ -1067,7 +1067,7 @@ def copy(
             `device` can be ``None``, a oneAPI filter selector string,
             an instance of :class:`dpctl.SyclDevice` corresponding to
             a non-partitioned SYCL device, an instance of
-            :class:`dpctl.SyclQueue`, or a :class:`dpctl.tensor.Device` object
+            :class:`dpctl.SyclQueue`, or a :class:`dpnp.tensor.Device` object
             returned by :attr:`dpnp.ndarray.device`.
 
             Default: ``None``.
@@ -1162,7 +1162,7 @@ def data(self):
     @property
     def device(self):
         """
-        Return :class:`dpctl.tensor.Device` object representing residence of
+        Return :class:`dpnp.tensor.Device` object representing residence of
         the array data.
 
         The ``Device`` object represents Array API notion of the device, and
@@ -1329,7 +1329,7 @@ def flatten(self, /, order="C"):
         return self.reshape(-1, order=order, copy=True)
 
     def get_array(self):
-        """Get :class:`dpctl.tensor.usm_ndarray` object."""
+        """Get :class:`dpnp.tensor.usm_ndarray` object."""
         return self._array_obj
 
     # 'getfield',
@@ -2182,7 +2182,7 @@ def to_device(self, device, /, *, stream=None):
             `device` can be ``None``, a oneAPI filter selector string,
             an instance of :class:`dpctl.SyclDevice` corresponding to
             a non-partitioned SYCL device, an instance of
-            :class:`dpctl.SyclQueue`, or a :class:`dpctl.tensor.Device` object
+            :class:`dpctl.SyclQueue`, or a :class:`dpnp.tensor.Device` object
             returned by :attr:`dpnp.ndarray.device`.
         stream : {SyclQueue, None}, optional
             Execution queue to synchronize with. If ``None``, synchronization

dpnp/dpnp_container.py

@@ -64,7 +64,7 @@ def arange(
     usm_type="device",
     sycl_queue=None,
 ):
-    """Validate input parameters before passing them into `dpctl.tensor` module"""
+    """Validate input parameters before passing them into `dpnp.tensor` module"""
     dpt.validate_usm_type(usm_type, allow_none=False)
     sycl_queue_normalized = dpnp.get_normalized_queue_device(
         sycl_queue=sycl_queue, device=device
@@ -151,7 +151,7 @@ def empty(
     usm_type="device",
     sycl_queue=None,
 ):
-    """Validate input parameters before passing them into `dpctl.tensor` module"""
+    """Validate input parameters before passing them into `dpnp.tensor` module"""
     dpt.validate_usm_type(usm_type, allow_none=False)
     sycl_queue_normalized = dpnp.get_normalized_queue_device(
         sycl_queue=sycl_queue, device=device
@@ -182,7 +182,7 @@ def eye(
     usm_type="device",
     sycl_queue=None,
 ):
-    """Validate input parameters before passing them into `dpctl.tensor` module"""
+    """Validate input parameters before passing them into `dpnp.tensor` module"""
     dpt.validate_usm_type(usm_type, allow_none=False)
     sycl_queue_normalized = dpnp.get_normalized_queue_device(
         sycl_queue=sycl_queue, device=device
@@ -213,7 +213,7 @@ def full(
     usm_type=None,
     sycl_queue=None,
 ):
-    """Validate input parameters before passing them into `dpctl.tensor` module"""
+    """Validate input parameters before passing them into `dpnp.tensor` module"""
     dpt.validate_usm_type(usm_type, allow_none=True)
 
     sycl_queue_normalized = dpnp.get_normalized_queue_device(
@@ -246,7 +246,7 @@ def ones(
     usm_type="device",
     sycl_queue=None,
 ):
-    """Validate input parameters before passing them into `dpctl.tensor` module"""
+    """Validate input parameters before passing them into `dpnp.tensor` module"""
     dpt.validate_usm_type(usm_type, allow_none=False)
     sycl_queue_normalized = dpnp.get_normalized_queue_device(
         sycl_queue=sycl_queue, device=device
@@ -286,7 +286,7 @@ def zeros(
     usm_type="device",
     sycl_queue=None,
 ):
-    """Validate input parameters before passing them into `dpctl.tensor` module"""
+    """Validate input parameters before passing them into `dpnp.tensor` module"""
     dpt.validate_usm_type(usm_type, allow_none=False)
     sycl_queue_normalized = dpnp.get_normalized_queue_device(
         sycl_queue=sycl_queue, device=device