Add dpnp.tensor documentation

doc/_templates/autosummary/cython_class.rst

@@ -0,0 +1,29 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ name }}
+   {% block methods %}
+
+   {% if methods %}
+   .. rubric:: {{ _('Methods') }}
+
+   .. autosummary::
+      :toctree: generated
+   {% for item in methods if item != "__init__" %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: {{ _('Attributes') }}
+
+   .. autosummary::
+      :toctree: generated
+   {% for item in attributes %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}

doc/_templates/autosummary/elementwise.rst

@@ -0,0 +1,12 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+{% if objtype == "data" %}
+.. auto{{ objtype }}:: {{ objname }}
+    :no-value:
+{% endif %}
+
+{% if objtype == "function" %}
+.. auto{{ objtype }}:: {{ objname }}
+{% endif %}

doc/_templates/autosummary/usm_ndarray.rst

@@ -0,0 +1,45 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+
+
+.. autoclass:: {{ name }}
+
+   {% block methods %}
+
+   {% if methods %}
+   .. rubric:: {{ _('Methods') }}
+
+   .. autosummary::
+      :toctree: generated
+   {% for item in methods if item != "__init__" %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: {{ _('Attributes') }}
+
+   .. autosummary::
+      :toctree: generated
+   {% for item in attributes %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+
+   .. rubric:: {{ _('Special attributes') }}
+
+   .. autosummary::
+      :toctree: generated
+
+      ~{{name}}.__dlpack_device__
+      ~{{name}}.__dlpack__
+      ~{{name}}.__sycl_usm_array_interface__
+      ~{{name}}._pointer
+      ~{{name}}._element_offset
+      ~{{name}}._byte_bounds
+
+   {% endif %}
+   {% endblock %}

doc/index.rst

@@ -12,6 +12,7 @@ Data Parallel Extension for NumPy*
 
    overview
    quick_start_guide
+   user_guides/index
    reference/index
 
 .. toctree::

doc/reference/index.rst

@@ -13,6 +13,7 @@ API reference of the Data Parallel Extension for NumPy*
 .. toctree::
    :maxdepth: 2
 
+   tensor
    ndarray
    ufunc
    routines

doc/reference/tensor.accumulation_functions.rst

@@ -0,0 +1,15 @@
+.. _dpnp_tensor_accumulation_functions:
+
+Accumulation functions
+======================
+
+Accumulation functions compute cumulative results along a given axis of the input array.
+
+.. currentmodule:: dpnp.tensor
+
+.. autosummary::
+    :toctree: generated
+
+    cumulative_logsumexp
+    cumulative_prod
+    cumulative_sum

doc/reference/tensor.constants.rst

@@ -0,0 +1,35 @@
+.. _dpnp_tensor_constants:
+
+Constants
+=========
+
+The following constants are defined in :py:mod:`dpnp.tensor`:
+
+.. currentmodule:: dpnp.tensor
+
+.. autodata:: DLDeviceType
+
+.. data:: e
+
+   ``float``:
+        IEEE 754 floating-point representation of Euler's constant.
+
+.. data:: inf
+
+   ``float``:
+        IEEE 754 floating-point representation of (positive) infinity.
+
+.. data:: nan
+
+   ``float``:
+        IEEE 754 floating-point representation of Not a Number (NaN).
+
+.. data:: newaxis
+
+   ``NoneType``:
+        Alias for ``None`` which is useful for indexing.
+
+.. data:: pi
+
+   ``float``:
+        IEEE 754 floating-point representation of the mathematical constant π.

doc/reference/tensor.creation_functions.rst

@@ -0,0 +1,31 @@
+.. _dpnp_tensor_creation_functions:
+
+Array creation functions
+========================
+
+The following functions in :py:mod:`dpnp.tensor` can be used
+to create new arrays:
+
+.. currentmodule:: dpnp.tensor
+
+.. autosummary::
+    :toctree: generated
+
+    arange
+    asarray
+    empty
+    empty_like
+    eye
+    from_dlpack
+    full
+    full_like
+    linspace
+    meshgrid
+    ones
+    ones_like
+    tril
+    triu
+    zeros
+    zeros_like
+    from_numpy
+    copy

doc/reference/tensor.data_type_functions.rst

@@ -0,0 +1,21 @@
+.. _dpnp_tensor_data_type_functions:
+
+Data type functions
+===================
+
+The package :py:mod:`dpnp.tensor` contains the following data type functions conforming
+to `Python Array API specification <array_api_data_type_fns_>`_:
+
+.. _array_api_data_type_fns: https://data-apis.org/array-api/latest/API_specification/data_type_functions.html
+
+.. currentmodule:: dpnp.tensor
+
+.. autosummary::
+    :toctree: generated
+
+    astype
+    can_cast
+    finfo
+    iinfo
+    isdtype
+    result_type

doc/reference/tensor.data_types.rst

@@ -0,0 +1,127 @@
+.. _dpnp_tensor_data_types:
+
+.. currentmodule:: dpnp.tensor
+
+Data types
+==========
+
+:py:mod:`dpnp.tensor` supports the following data types:
+
++----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Data Type      | Description                                                                                                                                                                             |
++================+=========================================================================================================================================================================================+
+| ``bool``       | Boolean (``True`` or ``False``)                                                                                                                                                         |
++----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``int8``       | An 8-bit signed integer type capable of representing :math:`v` subject to :math:`-2^7 \le v < 2^7`                                                                                      |
++----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``int16``      | A 16-bit signed integer type capable of representing :math:`v` subject to :math:`-2^{15} \le v < 2^{15}`                                                                                |
++----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``int32``      | A 32-bit signed integer type capable of representing :math:`v` subject to :math:`-2^{31} \le v < 2^{31}`                                                                                |
++----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``int64``      | A 64-bit signed integer type capable of representing :math:`v` subject to :math:`-2^{63} \le v < 2^{63}`                                                                                |
++----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``uint8``      | An 8-bit unsigned integer type capable of representing :math:`v` subject to :math:`0 \le v < 2^8`                                                                                       |
++----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``uint16``     | A 16-bit unsigned integer type capable of representing :math:`v` subject to :math:`0 \le v < 2^{16}`                                                                                    |
++----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``uint32``     | A 32-bit unsigned integer type capable of representing :math:`v` subject to :math:`0 \le v < 2^{32}`                                                                                    |
++----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``uint64``     | A 64-bit unsigned integer type capable of representing :math:`v` subject to :math:`0 \le v < 2^{64}`                                                                                    |
++----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``float16``    | An IEEE-754 half-precision (16-bit) binary floating-point number (see `IEEE 754-2019`_)                                                                                                 |
++----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``float32``    | An IEEE-754 single-precision (32-bit) binary floating-point number (see `IEEE 754-2019`_)                                                                                               |
++----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``float64``    | An IEEE-754 double-precision (64-bit) binary floating-point number (see `IEEE 754-2019`_)                                                                                               |
++----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``complex64``  | Single-precision (64-bit) complex floating-point number whose real and imaginary components are IEEE 754 single-precision (32-bit) binary floating-point numbers (see `IEEE 754-2019`_) |
++----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``complex128`` | Double-precision (128-bit) complex floating-point number whose real and imaginary components are IEEE 754 double-precision (64-bit) binary floating-point numbers (see `IEEE 754-2019`_)|
++----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+
+.. _IEEE 754-2019: https://doi.org/10.1109%2FIEEESTD.2019.8766229
+
+Data type support by array object :py:class:`usm_ndarray` depends on capabilities of :class:`dpctl.SyclDevice` where array is allocated.
+
+Half-precision floating-point type ``float16`` is supported only for devices whose attribute :attr:`dpctl.SyclDevice.has_aspect_fp16` evaluates to ``True``.
+
+Double-precision floating-point type ``float64`` and double-precision complex floating-point type ``complex128`` are supported only for devices whose attribute :attr:`dpctl.SyclDevice.has_aspect_fp64`
+evaluates to ``True``.
+
+If prerequisites are not met, requests to create an instance of an array object for these types will raise an exception.
+
+Data type objects are instances of :py:class:`dtype` object, and support equality comparison by implementing
+special method :meth:`__eq__`.
+
+.. py:class:: dtype
+
+    Same as :py:class:`numpy.dtype`
+
+    .. py:method:: __eq__
+
+        Check if data-type instances are equal.
+
+
+Default integral data type
+--------------------------
+
+The default integral data type is :attr:`int64` for all supported devices.
+
+Default indexing data type
+--------------------------
+
+The default indexing data type is :attr:`int64` for all supported devices.
+
+Default real floating-point data type
+-------------------------------------
+
+The default real floating-point type depends on the capabilities of device where array is allocated.
+If the device support double precision floating-point types, the default real floating-point type
+is :attr:`float64`, otherwise :attr:`float32`.
+
+Make sure to select an appropriately capable device for an application that requires use of double
+precision floating-point type.
+
+Default complex floating-point data type
+----------------------------------------
+
+Like for the default real floating-point type, the default complex floating-point type depends on
+capabilities of device. If the device support double precision real floating-point types, the default
+complex floating-point type is :attr:`complex128`, otherwise :attr:`complex64`.
+
+
+Querying default data types programmatically
+--------------------------------------------
+
+The data type can be discovered programmatically using Array API :ref:`inspection functions <dpnp_tensor_inspection>`:
+
+.. code-block:: python
+
+    import dpctl
+    from dpnp import tensor
+
+    device = dpctl.select_default_device()
+    # get default data types for default-selected device
+    default_types = tensor.__array_namespace_info__().default_dtypes(device)
+    int_dt = default_types["integral"]
+    ind_dt = default_types["indexing"]
+    rfp_dt = default_types["real floating"]
+    cfp_dt = default_types["complex floating"]
+
+
+Type promotion rules
+--------------------
+
+Type promotion rules govern the behavior of an array library when a function does not have
+a dedicated implementation for the data type(s) of the input array(s).
+
+In such a case, input arrays may be cast to data types for which a dedicated implementation
+exists. For example, when :data:`sin` is applied to array of integral values.
+
+Type promotion rules used in :py:mod:`dpnp.tensor` are consistent with the
+Python Array API specification's `type promotion rules <https://data-apis.org/array-api/latest/API_specification/type_promotion.html>`_
+for devices that support double precision floating-point type.
+
+
+For devices that do not support double precision floating-point type, the type promotion rule is
+truncated by removing nodes corresponding to unsupported data types and edges that lead to them.