.. _tensor:

Tensor (``dpnp.tensor``)
========================

:mod:`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``.

:mod:`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
:class:`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; :class:`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 :mod:`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)

.. seealso::

   :ref:`dpnp.tensor API Reference <dpnp_tensor_pyapi>`