Skip to content

Commit e2f83bc

Browse files
vlad-perevezentsevvlad-perevezentsev
committed
Add dpnp.tensor API reference documentation
1 parent a44d2ec commit e2f83bc

23 files changed

Lines changed: 697 additions & 0 deletions

‎doc/_templates/autosummary/cython_class.rst‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
{{ fullname | escape | underline}}
2+
3+
.. currentmodule:: {{ module }}
4+
5+
.. autoclass:: {{ name }}
6+
{% block methods %}
7+
8+
{% if methods %}
9+
.. rubric:: {{ _('Methods') }}
10+
11+
.. autosummary::
12+
:toctree: generated
13+
{% for item in methods if item != "__init__" %}
14+
~{{ name }}.{{ item }}
15+
{%- endfor %}
16+
{% endif %}
17+
{% endblock %}
18+
19+
{% block attributes %}
20+
{% if attributes %}
21+
.. rubric:: {{ _('Attributes') }}
22+
23+
.. autosummary::
24+
:toctree: generated
25+
{% for item in attributes %}
26+
~{{ name }}.{{ item }}
27+
{%- endfor %}
28+
{% endif %}
29+
{% endblock %}

‎doc/_templates/autosummary/elementwise.rst‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
{{ fullname | escape | underline}}
2+
3+
.. currentmodule:: {{ module }}
4+
5+
{% if objtype == "data" %}
6+
.. auto{{ objtype }}:: {{ objname }}
7+
:no-value:
8+
{% endif %}
9+
10+
{% if objtype == "function" %}
11+
.. auto{{ objtype }}:: {{ objname }}
12+
{% endif %}

‎doc/_templates/autosummary/usm_ndarray.rst‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
{{ fullname | escape | underline}}
2+
3+
.. currentmodule:: {{ module }}
4+
5+
6+
7+
.. autoclass:: {{ name }}
8+
9+
{% block methods %}
10+
11+
{% if methods %}
12+
.. rubric:: {{ _('Methods') }}
13+
14+
.. autosummary::
15+
:toctree: generated
16+
{% for item in methods if item != "__init__" %}
17+
~{{ name }}.{{ item }}
18+
{%- endfor %}
19+
{% endif %}
20+
{% endblock %}
21+
22+
{% block attributes %}
23+
{% if attributes %}
24+
.. rubric:: {{ _('Attributes') }}
25+
26+
.. autosummary::
27+
:toctree: generated
28+
{% for item in attributes %}
29+
~{{ name }}.{{ item }}
30+
{%- endfor %}
31+
32+
.. rubric:: {{ _('Special attributes') }}
33+
34+
.. autosummary::
35+
:toctree: generated
36+
37+
~{{name}}.__dlpack_device__
38+
~{{name}}.__dlpack__
39+
~{{name}}.__sycl_usm_array_interface__
40+
~{{name}}._pointer
41+
~{{name}}._element_offset
42+
~{{name}}._byte_bounds
43+
44+
{% endif %}
45+
{% endblock %}

‎doc/reference/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ API reference of the Data Parallel Extension for NumPy*
1313
.. toctree::
1414
:maxdepth: 2
1515

16+
tensor
1617
ndarray
1718
ufunc
1819
routines

‎doc/reference/tensor.accumulation_functions.rst‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
.. _dpnp_tensor_accumulation_functions:
2+
3+
Accumulation functions
4+
======================
5+
6+
Accumulation functions compute cumulative results along a given axis of the input array.
7+
8+
.. currentmodule:: dpnp.tensor
9+
10+
.. autosummary::
11+
:toctree: generated
12+
13+
cumulative_logsumexp
14+
cumulative_prod
15+
cumulative_sum

‎doc/reference/tensor.constants.rst‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
.. _dpnp_tensor_constants:
2+
3+
Constants
4+
=========
5+
6+
The following constants are defined in :py:mod:`dpnp.tensor`:
7+
8+
.. currentmodule:: dpnp.tensor
9+
10+
.. autodata:: DLDeviceType
11+
12+
.. data:: e
13+
14+
``float``:
15+
IEEE 754 floating-point representation of Euler's constant.
16+
17+
.. data:: inf
18+
19+
``float``:
20+
IEEE 754 floating-point representation of (positive) infinity.
21+
22+
.. data:: nan
23+
24+
``float``:
25+
IEEE 754 floating-point representation of Not a Number (NaN).
26+
27+
.. data:: newaxis
28+
29+
``NoneType``:
30+
Alias for ``None`` which is useful for indexing.
31+
32+
.. data:: pi
33+
34+
``float``:
35+
IEEE 754 floating-point representation of the mathematical constant π.

‎doc/reference/tensor.creation_functions.rst‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
.. _dpnp_tensor_creation_functions:
2+
3+
Array creation functions
4+
========================
5+
6+
The following functions in :py:mod:`dpnp.tensor` can be used
7+
to create new arrays:
8+
9+
.. currentmodule:: dpnp.tensor
10+
11+
.. autosummary::
12+
:toctree: generated
13+
14+
arange
15+
asarray
16+
empty
17+
empty_like
18+
eye
19+
from_dlpack
20+
full
21+
full_like
22+
linspace
23+
meshgrid
24+
ones
25+
ones_like
26+
tril
27+
triu
28+
zeros
29+
zeros_like
30+
from_numpy
31+
copy

‎doc/reference/tensor.data_type_functions.rst‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
.. _dpnp_tensor_data_type_functions:
2+
3+
Data type functions
4+
===================
5+
6+
The package :py:mod:`dpnp.tensor` contains the following data type functions conforming
7+
to `Python Array API specification <array_api_data_type_fns_>`_:
8+
9+
.. _array_api_data_type_fns: https://data-apis.org/array-api/latest/API_specification/data_type_functions.html
10+
11+
.. currentmodule:: dpnp.tensor
12+
13+
.. autosummary::
14+
:toctree: generated
15+
16+
astype
17+
can_cast
18+
finfo
19+
iinfo
20+
isdtype
21+
result_type

‎doc/reference/tensor.data_types.rst‎

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
.. _dpnp_tensor_data_types:
2+
3+
.. currentmodule:: dpnp.tensor
4+
5+
Data types
6+
==========
7+
8+
:py:mod:`dpnp.tensor` supports the following data types:
9+
10+
+----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
11+
| Data Type | Description |
12+
+================+=========================================================================================================================================================================================+
13+
| ``bool`` | Boolean (``True`` or ``False``) |
14+
+----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
15+
| ``int8`` | An 8-bit signed integer type capable of representing :math:`v` subject to :math:`-2^7 \le v < 2^7` |
16+
+----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
17+
| ``int16`` | A 16-bit signed integer type capable of representing :math:`v` subject to :math:`-2^{15} \le v < 2^{15}` |
18+
+----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
19+
| ``int32`` | A 32-bit signed integer type capable of representing :math:`v` subject to :math:`-2^{31} \le v < 2^{31}` |
20+
+----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
21+
| ``int64`` | A 64-bit signed integer type capable of representing :math:`v` subject to :math:`-2^{63} \le v < 2^{63}` |
22+
+----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
23+
| ``uint8`` | An 8-bit unsigned integer type capable of representing :math:`v` subject to :math:`0 \le v < 2^8` |
24+
+----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
25+
| ``uint16`` | A 16-bit unsigned integer type capable of representing :math:`v` subject to :math:`0 \le v < 2^{16}` |
26+
+----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
27+
| ``uint32`` | A 32-bit unsigned integer type capable of representing :math:`v` subject to :math:`0 \le v < 2^{32}` |
28+
+----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
29+
| ``uint64`` | A 64-bit unsigned integer type capable of representing :math:`v` subject to :math:`0 \le v < 2^{64}` |
30+
+----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
31+
| ``float16`` | An IEEE-754 half-precision (16-bit) binary floating-point number (see `IEEE 754-2019`_) |
32+
+----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
33+
| ``float32`` | An IEEE-754 single-precision (32-bit) binary floating-point number (see `IEEE 754-2019`_) |
34+
+----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
35+
| ``float64`` | An IEEE-754 double-precision (64-bit) binary floating-point number (see `IEEE 754-2019`_) |
36+
+----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
37+
| ``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`_) |
38+
+----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
39+
| ``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`_)|
40+
+----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
41+
42+
.. _IEEE 754-2019: https://doi.org/10.1109%2FIEEESTD.2019.8766229
43+
44+
Data type support by array object :py:class:`usm_ndarray` depends on capabilities of :class:`dpctl.SyclDevice` where array is allocated.
45+
46+
Half-precision floating-point type ``float16`` is supported only for devices whose attribute :attr:`dpctl.SyclDevice.has_aspect_fp16` evaluates to ``True``.
47+
48+
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`
49+
evaluates to ``True``.
50+
51+
If prerequisites are not met, requests to create an instance of an array object for these types will raise an exception.
52+
53+
Data type objects are instances of :py:class:`dtype` object, and support equality comparison by implementing
54+
special method :meth:`__eq__`.
55+
56+
.. py:class:: dtype
57+
58+
Same as :py:class:`numpy.dtype`
59+
60+
.. py:method:: __eq__
61+
62+
Check if data-type instances are equal.
63+
64+
65+
Default integral data type
66+
--------------------------
67+
68+
The default integral data type is :attr:`int64` for all supported devices.
69+
70+
Default indexing data type
71+
--------------------------
72+
73+
The default indexing data type is :attr:`int64` for all supported devices.
74+
75+
Default real floating-point data type
76+
-------------------------------------
77+
78+
The default real floating-point type depends on the capabilities of device where array is allocated.
79+
If the device support double precision floating-point types, the default real floating-point type
80+
is :attr:`float64`, otherwise :attr:`float32`.
81+
82+
Make sure to select an appropriately capable device for an application that requires use of double
83+
precision floating-point type.
84+
85+
Default complex floating-point data type
86+
----------------------------------------
87+
88+
Like for the default real floating-point type, the default complex floating-point type depends on
89+
capabilities of device. If the device support double precision real floating-point types, the default
90+
complex floating-point type is :attr:`complex128`, otherwise :attr:`complex64`.
91+
92+
93+
Querying default data types programmatically
94+
--------------------------------------------
95+
96+
The data type can be discovered programmatically using Array API :ref:`inspection functions <dpnp_tensor_inspection>`:
97+
98+
.. code-block:: python
99+
100+
import dpctl
101+
from dpnp import tensor
102+
103+
device = dpctl.select_default_device()
104+
# get default data types for default-selected device
105+
default_types = tensor.__array_namespace_info__().default_dtypes(device)
106+
int_dt = default_types["integral"]
107+
ind_dt = default_types["indexing"]
108+
rfp_dt = default_types["real floating"]
109+
cfp_dt = default_types["complex floating"]
110+
111+
112+
Type promotion rules
113+
--------------------
114+
115+
Type promotion rules govern the behavior of an array library when a function does not have
116+
a dedicated implementation for the data type(s) of the input array(s).
117+
118+
In such a case, input arrays may be cast to data types for which a dedicated implementation
119+
exists. For example, when :data:`sin` is applied to array of integral values.
120+
121+
Type promotion rules used in :py:mod:`dpnp.tensor` are consistent with the
122+
Python Array API specification's `type promotion rules <https://data-apis.org/array-api/latest/API_specification/type_promotion.html>`_
123+
for devices that support double precision floating-point type.
124+
125+
126+
For devices that do not support double precision floating-point type, the type promotion rule is
127+
truncated by removing nodes corresponding to unsupported data types and edges that lead to them.

0 commit comments

Comments
 (0)