Merge branch 'main' into add-fft-extension

Author: steff456

.circleci/config.yml

@@ -0,0 +1,31 @@
+version: 2
+
+# Aliases to reuse
+_defaults: &defaults
+  docker:
+    # CircleCI maintains a library of pre-built images
+    # documented at https://circleci.com/docs/2.0/circleci-images/
+    - image: circleci/python:3.7.0
+  working_directory: ~/repo
+
+jobs:
+  build_page:
+    <<: *defaults
+    steps:
+      - checkout
+      - attach_workspace:
+          at: ~/
+      - run:
+          name: build docs
+          no_output_timeout: 25m
+          command: |
+            sudo pip install -r requirements.txt
+            sphinx-build -b html -WT --keep-going spec build/latest -d doctrees
+      - store_artifacts:
+          path: build/latest
+
+workflows:
+  version: 2
+  default:
+    jobs:
+      - build_page

.github/workflows/preview.yml

@@ -0,0 +1,17 @@
+on: [status]
+jobs:
+  circleci_artifacts_redirector_job:
+    runs-on: ubuntu-latest
+    name: Run CircleCI artifacts redirector
+    steps:
+      - name: GitHub Action step
+        id: step1
+        uses: larsoner/circleci-artifacts-redirector-action@master
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+          artifact-path: 0/build/latest/index.html
+          circleci-jobs: build_page
+          job-title: Check the rendered docs here!
+      - name: Array API preview
+        run: |
+          curl --fail ${{ steps.step1.outputs.url }} | grep $GITHUB_SHA

spec/API_specification/array_object.md

@@ -737,7 +737,7 @@ Evaluates `self_i << other_i` for each element of an array instance with the res
 
 ```{note}
 
-Element-wise results must equal the results returned by the equivalent element-wise function [`less_equal(x1, x2)`](elementwise_functions.md#bitwise_left_shiftx1-x2-).
+Element-wise results must equal the results returned by the equivalent element-wise function [`bitwise_left_shift(x1, x2)`](elementwise_functions.md#bitwise_left_shiftx1-x2-).
 ```
 
 (method-__lt__)=
@@ -1062,7 +1062,30 @@ Element-wise results must equal the results returned by the equivalent element-w
 (method-__setitem__)=
 ### \_\_setitem\_\_(self, key, value, /)
 
-_TODO: dependent on the indexing specification._
+Sets `self[key]` to `value`.
+
+#### Parameters
+
+-   **self**: _&lt;array;&gt;_
+
+    -   array instance.
+
+-   **key**: _Union\[ int, slice, ellipsis, Tuple\[ Union\[ int, slice, ellipsis ], ... ], &lt;array&gt; ]_
+
+    -   index key.
+
+-   **value**: _Union\[ int, float, bool, &lt;array&gt; ]_
+
+    -   value(s) to set. Must be compatible with `self[key]` (see {ref}`broadcasting`).
+
+```{note}
+
+Setting array values must not affect the data type of `self`.
+
+When `value` is a Python scalar (i.e., `int`, `float`, `bool`), behavior must follow specification guidance on mixing arrays with Python scalars (see {ref}`type-promotion`).
+
+When `value` is an `array` of a different data type than `self`, how values are cast to the data type of `self` is implementation defined.
+```
 
 (method-__sub__)=
 ### \_\_sub\_\_(self, other, /)

spec/API_specification/data_type_functions.md

@@ -95,6 +95,8 @@ Machine limits for floating-point data types.
             -   largest representable number.
         -   **min**: _float_
             -   smallest representable number.
+        -   **smallest_normal**: _float_
+            -   smallest positive floating-point number with full precision.
 
 (function-iinfo)=
 ### iinfo(type, /)

spec/API_specification/data_types.md

@@ -6,13 +6,6 @@
 
 A conforming implementation of the array API standard must provide and support the following data types.
 
-A conforming implementation of the array API standard must define a default floating-point data type (either `float32` or `float64`), as well as a default integer data type (`int32` or `int64`). These default data types must be the same across platforms. The default integer data type may vary depending on whether Python is 32-bit or 64-bit.
-
-```{note}
-The default floating-point and array index integer data types should be clearly defined in a conforming library's documentation.
-```
-
-
 ## bool
 
 Boolean (`True` or `False`).
@@ -60,8 +53,9 @@ IEEE 754 double-precision (64-bit) binary floating-point number (see IEEE 754-20
 
 :::{admonition} Future extension
 :class: hint
-It is expected that in the next version of this standard, `complex64` and `complex128`
-dtypes will be added, with these casting rules (will be added to {ref}`type-promotion`):
+`complex64` and `complex128` dtypes are expected to be included in the next
+version of this standard and to have the following casting rules (will be added
+to {ref}`type-promotion`):
 
 ![Type promotion diagram for complex dtypes in next version](/_static/images/dtype_promotion_complex.png)
 
@@ -78,13 +72,33 @@ Implementations may provide other ways to specify data types (e.g.,
 A conforming implementation of the array API standard may provide and support additional data types beyond those described in this specification.
 ```
 
+(data-type-defaults)=
+## Default Data Types
+
+A conforming implementation of the array API standard must define a default floating-point data type (either `float32` or `float64`) and a default integer data type (`int32` or `int64`).
+
+The default data types must be the same across platforms.
+
+The default integer data type may vary depending on whether Python is 32-bit or 64-bit.
+
+```{note}
+The default floating-point and integer data types should be clearly defined in a conforming library's documentation.
+```
+
 (data-type-categories)=
 ## Data Type Categories
 
-For the purposes of this specification, the following data type categories are defined.
-Libraries do not need to organize dtypes according to these categories. These
-are only for organizing the functions in this specification itself. Future versions of
-the specification will include additional categories for complex data types.
+For the purpose of organizing functions within this specification, the following data type categories are defined.
+
+```{note}
+Conforming libraries are not required to organize dtypes according to these categories. These
+categories are only intended for use within this specification.
+```
+
+```{note}
+Future versions of the specification will include additional categories for
+complex data types.
+```
 
 ### Numeric Data Types
 

spec/API_specification/elementwise_functions.md

@@ -352,7 +352,7 @@ Shifts the bits of each element `x1_i` of the input array `x1` to the left by ap
 
 -   **out**: _<array>_
 
-    -   an array containing the element-wise results. The returned array must have the same data type as `x1`.
+    -   an array containing the element-wise results. The returned array must have a data type determined by {ref}`type-promotion`.
 
 (function-bitwise_invert)=
 ### bitwise_invert(x, /)
@@ -397,6 +397,11 @@ Computes the bitwise OR of the underlying binary representation of each element
 
 Shifts the bits of each element `x1_i` of the input array `x1` to the right according to the respective element `x2_i` of the input array `x2`.
 
+```{note}
+
+This operation must be an arithmetic shift (i.e., sign-propagating) and thus equivalent to floor division by a power of two.
+```
+
 #### Parameters
 
 -   **x1**: _<array>_
@@ -411,7 +416,7 @@ Shifts the bits of each element `x1_i` of the input array `x1` to the right acco
 
 -   **out**: _<array>_
 
-    -   an array containing the element-wise results. The returned array must have the same data type as `x1`.
+    -   an array containing the element-wise results. The returned array must have a data type determined by {ref}`type-promotion`.
 
 (function-bitwise_xor)=
 ### bitwise_xor(x1, x2, /)
@@ -939,8 +944,9 @@ each element `x1_i` of the input array `x1` with the respective element `x2_i` o
 
 For floating-point operands,
 
-- If either `x1_i` or `x2_i` is `NaN`, the result is `NaN`.
-- If either `x1_i` or `x2_i` is `+infinity`, the result is `+infinity`.
+-   If either `x1_i` or `x2_i` is `NaN`, the result is `NaN`.
+-   If `x1_i` is `+infinity` and `x2_i` is not `NaN`, the result is `+infinity`.
+-   If `x1_i` is not `NaN` and `x2_i` is `+infinity`, the result is `+infinity`.
 
 #### Parameters
 

spec/API_specification/indexing.md

@@ -160,6 +160,12 @@ _Rationale: this is consistent with bounds-checking for single-axis indexing. An
 
 ## Boolean Array Indexing
 
+:::{admonition} Data-dependent output shape
+:class: important
+
+For common boolean array use cases (e.g., using a dynamically-sized boolean array mask to filter the values of another array), the shape of the output array is data-dependent; hence, array libraries which build computation graphs (e.g., JAX, Dask, etc.) may find boolean array indexing difficult to implement. Accordingly, such libraries may choose to omit boolean array indexing. See {ref}`data-dependent-output-shapes` section for more details.
+:::
+
 An array must support indexing where the **sole index** is an `M`-dimensional boolean array `B` with shape `S1 = (s1, ..., sM)` according to the following rules. Let `A` be an `N`-dimensional array with shape `S2 = (s1, ..., sM, ..., sN)`.
 
 -   If `N >= M`, then `A[B]` must replace the first `M` dimensions of `A` with a single dimension having a size equal to the number of `True` elements in `B`. The values in the resulting array must be in row-major (C-style order); this is equivalent to `A[nonzero(B)]`.

spec/API_specification/searching_functions.md

@@ -69,6 +69,12 @@ Returns the indices of the minimum values along a specified axis. When the minim
 (function-nonzero)=
 ### nonzero(x, /)
 
+:::{admonition} Data-dependent output shape
+:class: important
+
+The shape of the output array for this function depends on the data values in the input array; hence, array libraries which build computation graphs (e.g., JAX, Dask, etc.) may find this function difficult to implement without knowing array values. Accordingly, such libraries may choose to omit this function. See {ref}`data-dependent-output-shapes` section for more details.
+:::
+
 Returns the indices of the array elements which are non-zero.
 
 #### Parameters

spec/API_specification/set_functions.md

@@ -15,6 +15,12 @@ A conforming implementation of the array API standard must provide and support t
 (function-unique)=
 ### unique(x, /, *, return_counts=False, return_index=False, return_inverse=False)
 
+:::{admonition} Data-dependent output shape
+:class: important
+
+The shapes of one or more of output arrays for this function depend on the data values in the input array; hence, array libraries which build computation graphs (e.g., JAX, Dask, etc.) may find this function difficult to implement without knowing array values. Accordingly, such libraries may choose to omit this function. See {ref}`data-dependent-output-shapes` section for more details.
+:::
+
 Returns the unique elements of an input array `x`.
 
 #### Parameters
@@ -59,6 +65,4 @@ Returns the unique elements of an input array `x`.
 
         -   **counts**: _<array>_
 
-            -   an array containing the number of times each unique element occurs in `x`.
-
-                _TODO: should this be `int64`? This probably makes sense for most hardware; however, may be undesirable for older hardware and/or embedded systems._
+            -   an array containing the number of times each unique element occurs in `x`. The returned array must have the default integer data type.

spec/API_specification/type_promotion.md

@@ -70,6 +70,7 @@ where
 | **i1** | i2 | i4 | i8 |
 | **i2** | i2 | i4 | i8 |
 | **i4** | i4 | i4 | i8 |
+| **i8** | i8 | i8 | i8 |
 
 ### Floating-point type promotion table
 
@@ -108,6 +109,7 @@ a compatible type and value to the array dtype:
 - Python `bool` for a `bool` array dtype,
 - a Python `int` within the [bounds](data-types) of the given dtype for integer array dtypes,
 - a Python `int` or `float` for floating-point array dtypes
+
 The expected behavior is then equivalent to:
 
 1. Convert the scalar to a 0-D array with the same dtype as that of the array

spec/design_topics/data_dependent_output_shapes.md

@@ -0,0 +1,15 @@
+(data-dependent-output-shapes)=
+
+# Data-dependent output shapes
+
+Array libraries which build computation graphs commonly employ static analysis that relies upon known shapes. For example, JAX requires known array sizes when compiling code, in order to perform static memory allocation. Functions and operations which are value-dependent present difficulties for such libraries, as array sizes cannot be inferred ahead of time without also knowing the contents of the respective arrays.
+
+While value-dependent functions and operations are not impossible to implement for array libraries which build computation graphs, this specification does not want to impose an undue burden on such libraries and permits omission of value-dependent operations. All other array libraries are expected, however, to implement the value-dependent operations included in this specification in order to be array specification compliant.
+
+Value-dependent operations are demarcated in this specification using an admonition similar to the following:
+
+:::{admonition} Data-dependent output shape
+:class: important
+
+The shape of the output array for this function/operation depends on the data values in the input array; hence, array libraries which build computation graphs (e.g., JAX, Dask, etc.) may find this function/operation difficult to implement without knowing array values. Accordingly, such libraries may choose to omit this function. See {ref}`data-dependent-output-shapes` section for more details.
+:::

spec/design_topics/data_interchange.md

@@ -12,20 +12,28 @@ The interchange mechanism must offer the following:
 
 1. Data access via a protocol that describes the memory layout of the array
    in an implementation-independent manner.
+
    _Rationale: any number of libraries must be able to exchange data, and no
    particular package must be needed to do so._
+
 2. Support for all dtypes in this API standard (see {ref}`data-types`).
+
 3. Device support. It must be possible to determine on what device the array
    that is to be converted lives.
+
    _Rationale: there are CPU-only, GPU-only, and multi-device array types;
    it's best to support these with a single protocol (with separate
    per-device protocols it's hard to figure out unambiguous rules for which
    protocol gets used, and the situation will get more complex over time
    as TPU's and other accelerators become more widely available)._
+
 4. Zero-copy semantics where possible, making a copy only if needed (e.g.
    when data is not contiguous in memory).
+
    _Rationale: performance._
+
 5. A Python-side and a C-side interface, the latter with a stable C ABI.
+
    _Rationale: all prominent existing array libraries are implemented in
    C/C++, and are released independently from each other. Hence a stable C
    ABI is required for packages to work well together._

spec/design_topics/index.rst

@@ -6,6 +6,7 @@ Design topics & constraints
    :maxdepth: 1
 
    copies_views_and_mutation
+   data_dependent_output_shapes
    data_interchange
    device_support
    static_typing