You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This is large a reorganization to improve the readability of this page,
by replacing many subheadings with tables, by removing duplication
in notes, and by reorganizing content.
Furthermore, the description on how dtype objects are used is extended:
- add more ways in which dtype objects are used
- explain that `dtype=` keywords determine output dtype and not
internal/intermediate calculation dtype of arrays
- cross-link type promotion rules
| complex64 | Single-precision (64-bit) complex floating-point number whose real and imaginary components must be 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 must be IEEE 754 double-precision (64-bit) binary floating-point numbers (see IEEE 754-2019). |
Data type objects must have the following methods (no attributes are required):
9
43
10
-
bool
11
-
----
12
-
13
-
Boolean (``True`` or ``False``).
14
-
15
-
int8
16
-
----
17
-
18
-
An 8-bit signed integer whose values exist on the interval ``[-128, +127]``.
19
-
20
-
int16
21
-
-----
22
-
23
-
A 16-bit signed integer whose values exist on the interval ``[−32,767, +32,767]``.
24
-
25
-
int32
26
-
-----
27
-
28
-
A 32-bit signed integer whose values exist on the interval ``[−2,147,483,647, +2,147,483,647]``.
29
-
30
-
int64
31
-
-----
32
-
33
-
A 64-bit signed integer whose values exist on the interval ``[−9,223,372,036,854,775,807, +9,223,372,036,854,775,807]``.
34
-
35
-
uint8
36
-
-----
37
-
38
-
An 8-bit unsigned integer whose values exist on the interval ``[0, +255]``.
39
-
40
-
uint16
41
-
------
42
-
43
-
A 16-bit unsigned integer whose values exist on the interval ``[0, +65,535]``.
44
-
45
-
uint32
46
-
------
47
-
48
-
A 32-bit unsigned integer whose values exist on the interval ``[0, +4,294,967,295]``.
49
-
50
-
uint64
51
-
------
52
-
53
-
A 64-bit unsigned integer whose values exist on the interval ``[0, +18,446,744,073,709,551,615]``.
54
-
55
-
float32
56
-
-------
57
-
58
-
IEEE 754 single-precision (32-bit) binary floating-point number (see IEEE 754-2019).
59
-
60
-
float64
61
-
-------
44
+
..
45
+
NOTE: please keep the functions in alphabetical order
62
46
63
-
IEEE 754 double-precision (64-bit) binary floating-point number (see IEEE 754-2019).
47
+
.. currentmodule:: array_api.data_types
64
48
65
-
complex64
66
-
---------
49
+
.. autosummary::
50
+
:toctree: generated
51
+
:template: method.rst
67
52
68
-
Single-precision (64-bit) complex floating-point number whose real and imaginary components must be IEEE 754 single-precision (32-bit) binary floating-point numbers (see IEEE 754-2019).
53
+
__eq__
69
54
70
-
complex128
71
-
----------
72
55
73
-
Double-precision (128-bit) complex floating-point number whose real and imaginary components must be IEEE 754 double-precision (64-bit) binary floating-point numbers (see IEEE 754-2019).
56
+
.. note::
57
+
A conforming implementation of the array API standard may provide and
58
+
support additional data types beyond those described in this specification.
59
+
It may also support additional methods and attributes on dtype objects.
74
60
75
61
.. note::
76
62
IEEE 754-2019 requires support for subnormal (a.k.a., denormal) numbers, which are useful for supporting gradual underflow. However, hardware support for subnormal numbers is not universal, and many platforms (e.g., accelerators) and compilers support toggling denormals-are-zero (DAZ) and/or flush-to-zero (FTZ) behavior to increase performance and to guard against timing attacks.
77
63
78
64
Accordingly, subnormal behavior is left unspecified and, thus, implementation-defined. Conforming implementations may vary in their support for subnormal numbers.
79
65
80
-
.. note::
81
-
A conforming implementation of the array API standard may provide and support additional data types beyond those described in this specification.
82
-
83
-
.. _data-type-objects:
84
66
85
-
Data Type Objects
86
-
-----------------
67
+
Use of data type objects
68
+
------------------------
87
69
88
-
Data types ("dtypes") are objects which are used as ``dtype`` specifiers in functions and methods (e.g., ``zeros((2, 3), dtype=float32)``).
70
+
Data type objects are used as ``dtype`` specifiers in functions and methods
71
+
(e.g., ``zeros((2, 3), dtype=float32)``), accessible as ``.dtype`` attribute on
72
+
arrays, and used in various casting and introspection functions (e.g.,
73
+
``isdtype(x.dtype, 'integral')``).
89
74
90
-
.. note::
91
-
A conforming implementation may add additional methods or attributes to data type objects beyond those described in this specification.
75
+
``dtype`` keywords in functions specify the dtype of arrays returned from
76
+
functions or methods. ``dtype`` keywords are not required to affect the data
77
+
type used for intermediate calculations or results (e.g., implementors are free
78
+
to use a higher-precision dtype when accumulating values for reductions, as
79
+
long as the returned array has the specified dtype).
92
80
93
81
.. note::
94
82
Implementations may provide other ways to specify data types (e.g., ``zeros((2, 3), dtype='f4')``) which are not described in this specification; however, in order to ensure portability, array library consumers are recommended to use data type objects as provided by specification conforming array libraries.
95
83
96
-
A conforming implementation of the array API standard must provide and support data type objects having the following attributes and methods.
97
-
98
-
Methods
99
-
~~~~~~~
100
-
101
-
..
102
-
NOTE: please keep the functions in alphabetical order
103
-
104
-
.. currentmodule:: array_api.data_types
105
-
106
-
.. autosummary::
107
-
:toctree: generated
108
-
:template: method.rst
109
-
110
-
__eq__
84
+
When arrays with different dtypes or different dtype objects are used together,
85
+
what happens is described in :ref:`type-promotion`.
111
86
112
87
113
88
.. _data-type-defaults:
@@ -138,48 +113,32 @@ the library should clearly warn about this in its documentation.
138
113
.. note::
139
114
The default data types should be clearly defined in a conforming library's documentation.
140
115
116
+
141
117
.. _data-type-categories:
142
118
143
119
Data Type Categories
144
120
--------------------
145
121
146
122
For the purpose of organizing functions within this specification, the following data type categories are defined.
147
123
148
-
.. note::
149
-
Conforming libraries are not required to organize data types according to these categories. These categories are only intended for use within this specification.
``float32``, ``float64``, ``complex64``, and ``complex128``.
171
142
172
-
Real-valued Floating-point Data Types
173
-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
174
-
175
-
``float32`` and ``float64``.
176
-
177
-
Complex Floating-point Data Types
178
-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
179
-
180
-
``complex64`` and ``complex128``.
181
-
182
-
Boolean Data Types
183
-
~~~~~~~~~~~~~~~~~~
184
-
185
-
``bool``.
143
+
.. note::
144
+
Conforming libraries are not required to organize data types according to these categories. These categories are only intended for use within this specification.
0 commit comments