Add element-wise function specifications, incl. type casting and broadcasting rules

spec/API_specification/broadcasting.md

@@ -0,0 +1,112 @@
+.. _broadcasting:
+
+# Broadcasting
+
+> Array API specification for broadcasting semantics.
+
+## Overview
+
+**Broadcasting** refers to the automatic (implicit) expansion of array dimensions to be of equal sizes without copying array data for the purpose of making arrays with different shapes have compatible shapes for element-wise operations.
+
+Broadcasting facilitates user ergonomics by encouraging users to avoid unnecessary copying of array data and can **potentially** enable more memory-efficient element-wise operations through vectorization, reduced memory consumption, and cache locality.
+
+## Algorithm
+
+Given an element-wise operation involving two compatible arrays, an array having a singleton dimension (i.e., a dimension whose size is one) is broadcast (i.e., virtually repeated) across an array having a corresponding non-singleton dimension.
+
+If two arrays are of unequal rank, the array having a lower rank is promoted to a higher rank by (virtually) prepending singleton dimensions until the number of dimensions matches that of the array having a higher rank.
+
+The results of the element-wise operation must be stored in an array having a shape determined by the following algorithm.
+
+1.  Let `A` and `B` both be arrays.
+
+1.  Let `shape1` be a tuple describing the shape of array `A`.
+
+1.  Let `shape2` be a tuple describing the shape of array `B`.
+
+1.  Let `N1` be the number of dimensions of array `A` (i.e., the result of `len(shape1)`).
+
+1.  Let `N2` be the number of dimensions of array `B` (i.e., the result of `len(shape2)`).
+
+1.  Let `N` be the maximum value of `N1` and `N2` (i.e., the result of `max(N1, N2)`).
+
+1.  Let `shape` be a temporary list of length `N` for storing the shape of the result array.
+
+1.  Let `i` be `N-1`.
+
+1.  Repeat, while `i >= 0`
+
+	1.  If `N1-N+i >= 0`, let `d1` be the size of dimension `n` for array `A` (i.e., the result of `shape1[i]`); else, let `d1` be `1`.
+
+	1.  If `N2-N+i >= 0`, let `d2` be the size of dimension `n` for array `B` (i.e., the result of `shape2[i]`); else, let `d2` be `1`.
+
+	1.  If `d1 == 1`, then
+
+		-   set the `i`th element of `shape` to `d2`.
+
+	1.  Else, if `d2 == 1`, then
+
+		-   set the `i`th element of `shape` to `d1`.
+
+	1.  Else, if `d1 == d2`, then
+
+		-   set the `i`th element of `shape` to `d1`.
+
+	1.  Else, throw an exception.
+
+	1.  Set `i` to `i-1`.
+
+1.  Let `tuple(shape)` be the shape of the result array.
+
+### Examples
+
+The following examples demonstrate the application of the broadcasting algorithm for two compatible arrays.
+
+```text
+A      (4d array):  8 x 1 x 6 x 1
+B      (3d array):      7 x 1 x 5
+---------------------------------
+Result (4d array):  8 x 7 x 6 x 5
+
+A      (2d array):  5 x 4
+B      (1d array):      1
+-------------------------
+Result (2d array):  5 x 4
+
+A      (2d array):  5 x 4
+B      (1d array):      4
+-------------------------
+Result (2d array):  5 x 4
+
+A      (3d array):  15 x 3 x 5
+B      (3d array):  15 x 1 x 5
+------------------------------
+Result (3d array):  15 x 3 x 5
+
+A      (3d array):  15 x 3 x 5
+B      (2d array):       3 x 5
+------------------------------
+Result (3d array):  15 x 3 x 5
+
+A      (3d array):  15 x 3 x 5
+B      (2d array):       3 x 1
+------------------------------
+Result (3d array):  15 x 3 x 5
+```
+
+The following examples demonstrate array shapes which do **not** broadcast.
+
+```text
+A      (1d array):  3
+B      (1d array):  4           # dimension does not match
+
+A      (2d array):      2 x 1
+B      (3d array):  8 x 4 x 3   # second dimension does not match
+
+A      (3d array):  15 x 3 x 5
+B      (2d array):  15 x 3      # singleton dimensions can only be prepended, not appended
+```
+
+## In-place Semantics
+
+As implied by the broadcasting algorithm, in-place element-wise operations must not change the shape of the in-place array as a result of broadcasting.

spec/API_specification/data_types.md

@@ -0,0 +1,53 @@
+.. _data-types:
+
+# Data Types
+
+> Array API specification for supported data types.
+
+A conforming implementation of the array API standard must provide and support the following data types.
+
+A conforming implementation of the array API standard may provide and support additional data types beyond those described in this specification.
+
+## bool
+
+Boolean (`True` or `False`) stored as a byte.
+
+## int8
+
+An 8-bit signed integer whose values exist on the interval `[-128, +127]`.
+
+## int16
+
+A 16-bit signed integer whose values exist on the interval `[−32,767, +32,767]`.
+
+## int32
+
+A 32-bit signed integer whose values exist on the interval `[−2,147,483,647, +2,147,483,647]`.
+
+## int64
+
+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]`.
+
+## uint8
+
+An 8-bit unsigned integer whose values exist on the interval `[0, +255]`.
+
+## uint16
+
+A 16-bit unsigned integer whose values exist on the interval `[0, +65,535]`.
+
+## uint32
+
+A 32-bit unsigned integer whose values exist on the interval `[0, +4,294,967,295]`.
+
+## uint64
+
+A 64-bit unsigned integer whose values exist on the interval `[0, +18,446,744,073,709,551,615]`.
+
+## float32
+
+IEEE 754 single-precision (32-bit) binary floating-point number (see IEEE 754-2019).
+
+## float64
+
+IEEE 754 double-precision (64-bit) binary floating-point number (see IEEE 754-2019).

spec/API_specification/index.rst

@@ -7,4 +7,9 @@ API specification
 
    array_object
    indexing
+   data_types
+   type_promotion
    casting
+   broadcasting
+   out_keyword
+   elementwise_functions

spec/API_specification/out_keyword.md

@@ -0,0 +1,13 @@
+.. _out-keyword:
+
+# out
+
+> Array API specification for the `out` keyword argument.
+
+A conforming implementation of the array API standard must adhere to the following conventions.
+
+-   Functions and methods which support providing one or more output arrays must do so via a single `out` keyword argument whose default value is `None`.
+-   If a function or method returns a single output array, the `out` keyword argument must be either `None` or an array.
+-   If a function or method returns multiple output arrays, the `out` keyword argument must be a tuple with one entry (either `None` or an array) per output. Providing a single output array when a function or method returns multiple output arrays is **not** permitted.
+-   If `out` is not provided or is `None`, an uninitialized return array must be created for each output for which an output array has not been provided.
+-   Functions and methods which support the `out` keyword argument are **not** permitted to change the shape of provided output arrays.

spec/API_specification/type_promotion.md

@@ -0,0 +1,70 @@
+.. _type-promotion:
+
+# Type Promotion Rules
+
+> Array API specification for type promotion rules.
+
+A conforming implementation of the array API standard must implement the following type promotion rules governing the common result type for two **array** operands during an arithmetic operation.
+
+A conforming implementation of the array API standard may support additional type promotion rules beyond those described in this specification.
+
+## Rules
+
+<!-- Note: please keep table columns aligned -->
+
+-   signed integer type promotion table:
+
+    |        | i1 | i2 | i4 | i8 |
+    | ------ | -- | -- | -- | -- |
+    | **i1** | i1 | i2 | i4 | i8 |
+    | **i2** | i2 | i2 | i4 | i8 |
+    | **i4** | i4 | i4 | i4 | i8 |
+    | **i8** | i8 | i8 | i8 | i8 |
+
+    where
+
+    -   **i1**: 8-bit signed integer
+    -   **i2**: 16-bit signed integer
+    -   **i4**: 32-bit signed integer
+    -   **i8**: 64-bit signed integer
+
+-   unsigned integer type promotion table:
+
+    |        | u1 | u2 | u4 | u8 |
+    | ------ | -- | -- | -- | -- |
+    | **u1** | u1 | u2 | u4 | u8 |
+    | **u2** | u2 | u2 | u4 | u8 |
+    | **u4** | u4 | u4 | u4 | u8 |
+    | **u8** | u8 | u8 | u8 | u8 |
+
+    where
+
+    -   **u1**: 8-bit unsigned integer
+    -   **u2**: 16-bit unsigned integer
+    -   **u4**: 32-bit unsigned integer
+    -   **u8**: 64-bit unsigned integer
+
+-   mixed unsigned and signed integer type promotion table:
+
+    |        | u1 | u2 | u4 |
+    | ------ | -- | -- | -- |
+    | **i1** | i2 | i4 | i8 |
+    | **i2** | i2 | i4 | i8 |
+    | **i4** | i4 | i4 | i8 |
+
+-   floating-point type promotion table:
+
+    |        | f4 | f8 |
+    | ------ | -- | -- |
+    | **f4** | f4 | f8 |
+    | **f8** | f8 | f8 |
+
+    where
+
+    -   **f4**: single-precision (32-bit) floating-point number
+    -   **f8**: double-precision (64-bit) floating-point number
+
+## Notes
+
+-   Type promotion rules **strictly** apply when determining the common result type for two **array** operands during an arithmetic operation, regardless of array dimension. Accordingly, zero-dimensional arrays are subject to the same type promotion rules as dimensional arrays.
+-   Non-array ("scalar") operands are **not** permitted to participate in type promotion.

spec/purpose_and_scope.md

@@ -24,18 +24,60 @@
 
 ## How to read this document
 
-
+For guidance on how to read and understand the type annotations included in this specification, consult the Python [documentation](https://docs.python.org/3/library/typing.html).
 
 
 ## How to adopt this API
 
 
+* * *
+
+## Conformance
+
+A conforming implementation of the array API standard must provide and support all the functions, arguments, data types, syntax, and semantics described in this specification.
+
+A conforming implementation of the array API standard may provide additional values, objects, properties, data types, and functions beyond those described in this specification.
+
+* * *
+
+## Terms and Definitions
+
+For the purposes of this specification, the following terms and definitions apply.
+
+<!-- NOTE: please keep terms in alphabetical order -->
+
+### array
+
+a (usually fixed-size) multidimensional container of items of the same type and size.
+
+### broadcast
+
+automatic (implicit) expansion of array dimensions to be of equal sizes without copying array data for the purpose of making arrays with different shapes have compatible shapes for element-wise operations.
+
+### compatible
+
+two arrays whose dimensions are compatible (i.e., where the size of each dimension in one array is either equal to one or to the size of the corresponding dimension in a second array).
+
+### element-wise
+
+an operation performed element-by-element, in which individual array elements are considered in isolation and independently of other elements within the same array.
+
+### rank
+
+number of array dimensions (not to be confused with the number of linearly independent columns of a matrix).
+
+### shape
 
+a tuple of `N` non-negative integers that specify the sizes of each dimension and where `N` corresponds to the number of dimensions.
 
-## Definitions
+### singleton dimension
 
+a dimension whose size is one.
 
+* * *
 
+## Normative References
 
-## References
+The following referenced documents are indispensable for the application of this specification.
 
+-   __IEEE 754-2019: IEEE Standard for Floating-Point Arithmetic.__ Institute of Electrical and Electronic Engineers, New York (2019).