Skip to content

Restrict the T attribute to two-dimensional arrays #245

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Sep 13, 2021
Merged

Restrict the T attribute to two-dimensional arrays #245

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
2b367de
Restrict the `T` attribute to two-dimensional arrays
kgryte Aug 30, 2021
b8ddaf3
Add API recommendation
kgryte Aug 30, 2021
f405d00
Fix function name
kgryte Aug 30, 2021
918e865
Merge branch 'main' into update-t-attribute
kgryte Sep 13, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 7 additions & 29 deletions spec/API_specification/array_object.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -183,7 +183,6 @@ an array object supporting the following reflected operators:
The results of applying reflected operators must match their non-reflected equivalents.

```{note}

All operators for which `array <op> scalar` is implemented must have an equivalent reflected operator implementation.
```

Expand Down Expand Up @@ -259,11 +258,17 @@ _TODO: need to more carefully consider this in order to accommodate, e.g., graph

Transpose of the array.

The array instance must be two-dimensional. If the array instance is not two-dimensional, an error should be raised.

```{note}
Limiting the transpose to two-dimensional arrays (matrices) deviates from the NumPy et al practice of reversing all axes for arrays having more than two-dimensions. This is intentional, as reversing all axes was found to be problematic (e.g., conflicting with the mathematical definition of a transpose which is limited to matrices; not operating on batches of matrices; et cetera). In order to reverse all axes, one is recommended to use the functional `permute` interface found in this specification.
```

#### Returns

- **out**: _&lt;array&gt;_

- array whose dimensions (axes) are permuted in reverse order relative to original array. The returned array must have the same data type as the original array.
- two-dimensional array whose first and last dimensions (axes) are permuted in reverse order relative to original array. The returned array must have the same data type as the original array.

* * *

Expand Down Expand Up @@ -297,7 +302,6 @@ For floating-point operands, let `self` equal `x`.
- an array containing the element-wise absolute value. The returned array must have the same data type as `self`.

```{note}

Element-wise results must equal the results returned by the equivalent element-wise function [`abs(x)`](elementwise_functions.md#absx-).
```

Expand Down Expand Up @@ -329,7 +333,6 @@ For floating-point operands, let `self` equal `x1` and `other` equal `x2`.
- In the remaining cases, when neither `infinity`, `+0`, `-0`, nor a `NaN` is involved, and the operands have the same mathematical sign or have different magnitudes, the sum must be computed and rounded to the nearest representable value according to IEEE 754-2019 and a supported round mode. If the magnitude is too large to represent, the operation overflows and the result is an `infinity` of appropriate mathematical sign.

```{note}

Floating-point addition is a commutative operation, but not always associative.
```

Expand All @@ -350,7 +353,6 @@ Floating-point addition is a commutative operation, but not always associative.
- an array containing the element-wise sums. The returned array must have a data type determined by {ref}`type-promotion`.

```{note}

Element-wise results must equal the results returned by the equivalent element-wise function [`add(x1, x2)`](elementwise_functions.md#addx1-x2-).
```

Expand All @@ -376,7 +378,6 @@ Evaluates `self_i & other_i` for each element of an array instance with the resp
- an array containing the element-wise results. The returned array must have a data type determined by {ref}`type-promotion`.

```{note}

Element-wise results must equal the results returned by the equivalent element-wise function [`bitwise_and(x1, x2)`](elementwise_functions.md#logical_andx1-x2-).
```

Expand Down Expand Up @@ -524,7 +525,6 @@ Computes the truth value of `self_i == other_i` for each element of an array ins
- an array containing the element-wise results. The returned array must have a data type of `bool`.

```{note}

Element-wise results must equal the results returned by the equivalent element-wise function [`equal(x1, x2)`](elementwise_functions.md#equalx1-x2-).
```

Expand Down Expand Up @@ -567,7 +567,6 @@ Evaluates `self_i // other_i` for each element of an array instance with the res
- an array containing the element-wise results. The returned array must have a data type determined by {ref}`type-promotion`.

```{note}

Element-wise results must equal the results returned by the equivalent element-wise function [`floor_divide(x1, x2)`](elementwise_functions.md#floor_dividex1-x2-).
```

Expand All @@ -593,7 +592,6 @@ Computes the truth value of `self_i >= other_i` for each element of an array ins
- an array containing the element-wise results. The returned array must have a data type of `bool`.

```{note}

Element-wise results must equal the results returned by the equivalent element-wise function [`greater_equal(x1, x2)`](elementwise_functions.md#greater_equalx1-x2-).
```

Expand Down Expand Up @@ -640,7 +638,6 @@ Computes the truth value of `self_i > other_i` for each element of an array inst
- an array containing the element-wise results. The returned array must have a data type of `bool`.

```{note}

Element-wise results must equal the results returned by the equivalent element-wise function [`greater(x1, x2)`](elementwise_functions.md#greaterx1-x2-).
```

Expand Down Expand Up @@ -679,7 +676,6 @@ Evaluates `~self_i` for each element of an array instance.
- an array containing the element-wise results. The returned array must have the same data type as `self`.

```{note}

Element-wise results must equal the results returned by the equivalent element-wise function [`bitwise_invert(x)`](elementwise_functions.md#bitwise_invertx-).
```

Expand All @@ -705,7 +701,6 @@ Computes the truth value of `self_i <= other_i` for each element of an array ins
- an array containing the element-wise results. The returned array must have a data type of `bool`.

```{note}

Element-wise results must equal the results returned by the equivalent element-wise function [`less_equal(x1, x2)`](elementwise_functions.md#less_equalx1-x2-).
```

Expand Down Expand Up @@ -736,7 +731,6 @@ Evaluates `self_i << other_i` for each element of an array instance with the res
- an array containing the element-wise results. The returned array must have the same data type as `self`.

```{note}

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-).
```

Expand All @@ -762,7 +756,6 @@ Computes the truth value of `self_i < other_i` for each element of an array inst
- an array containing the element-wise results. The returned array must have a data type of `bool`.

```{note}

Element-wise results must equal the results returned by the equivalent element-wise function [`less(x1, x2)`](elementwise_functions.md#lessx1-x2-).
```

Expand All @@ -772,7 +765,6 @@ Element-wise results must equal the results returned by the equivalent element-w
Computes the matrix product.

```{note}

The `matmul` function must implement the same semantics as the built-in `@` operator (see [PEP 465](https://www.python.org/dev/peps/pep-0465)).
```

Expand Down Expand Up @@ -801,7 +793,6 @@ The `matmul` function must implement the same semantics as the built-in `@` oper
The returned array must have a data type determined by {ref}`type-promotion`.

```{note}

Results must equal the results returned by the equivalent function [`matmul(x1, x2)`](linear_algebra_functions.md#matmulx1-x2-).
```

Expand Down Expand Up @@ -833,7 +824,6 @@ Evaluates `self_i % other_i` for each element of an array instance with the resp
- an array containing the element-wise results. Each element-wise result must have the same sign as the respective element `other_i`. The returned array must have a floating-point data type determined by {ref}`type-promotion`.

```{note}

Element-wise results must equal the results returned by the equivalent element-wise function [`remainder(x1, x2)`](elementwise_functions.md#remainderx1-x2-).
```

Expand All @@ -857,7 +847,6 @@ For floating-point operands, let `self` equal `x1` and `other` equal `x2`.
- In the remaining cases, where neither `infinity` nor `NaN` is involved, the product must be computed and rounded to the nearest representable value according to IEEE 754-2019 and a supported rounding mode. If the magnitude is too large to represent, the result is an `infinity` of appropriate mathematical sign. If the magnitude is too small to represent, the result is a zero of appropriate mathematical sign.

```{note}

Floating-point multiplication is not always associative due to finite precision.
```

Expand All @@ -878,7 +867,6 @@ Floating-point multiplication is not always associative due to finite precision.
- an array containing the element-wise products. The returned array must have a data type determined by {ref}`type-promotion`.

```{note}

Element-wise results must equal the results returned by the equivalent element-wise function [`multiply(x1, x2)`](elementwise_functions.md#multiplyx1-x2-).
```

Expand All @@ -904,7 +892,6 @@ Computes the truth value of `self_i != other_i` for each element of an array ins
- an array containing the element-wise results. The returned array must have a data type of `bool` (i.e., must be a boolean array).

```{note}

Element-wise results must equal the results returned by the equivalent element-wise function [`not_equal(x1, x2)`](elementwise_functions.md#not_equalx1-x2-).
```

Expand All @@ -926,7 +913,6 @@ Evaluates `-self_i` for each element of an array instance.
- an array containing the evaluated result for each element in `self`. The returned array must have a data type determined by {ref}`type-promotion`.

```{note}

Element-wise results must equal the results returned by the equivalent element-wise function [`negative(x)`](elementwise_functions.md#negativex-).
```

Expand All @@ -952,7 +938,6 @@ Evaluates `self_i | other_i` for each element of an array instance with the resp
- an array containing the element-wise results. The returned array must have a data type determined by {ref}`type-promotion`.

```{note}

Element-wise results must equal the results returned by the equivalent element-wise function [`bitwise_or(x1, x2)`](elementwise_functions.md#bitwise_orx1-x2-).
```

Expand All @@ -974,7 +959,6 @@ Evaluates `+self_i` for each element of an array instance.
- an array containing the evaluated result for each element. The returned array must have the same data type as `self`.

```{note}

Element-wise results must equal the results returned by the equivalent element-wise function [`positive(x)`](elementwise_functions.md#positivex-).
```

Expand Down Expand Up @@ -1029,7 +1013,6 @@ For floating-point operands, let `self` equal `x1` and `other` equal `x2`.
- an array containing the element-wise results. The returned array must have a data type determined by {ref}`type-promotion`.

```{note}

Element-wise results must equal the results returned by the equivalent element-wise function [`pow(x1, x2)`](elementwise_functions.md#powx1-x2-).
```

Expand All @@ -1055,7 +1038,6 @@ Evaluates `self_i >> other_i` for each element of an array instance with the res
- an array containing the element-wise results. The returned array must have the same data type as `self`.

```{note}

Element-wise results must equal the results returned by the equivalent element-wise function [`bitwise_right_shift(x1, x2)`](elementwise_functions.md#bitwise_right_shiftx1-x2-).
```

Expand All @@ -1079,7 +1061,6 @@ Sets `self[key]` to `value`.
- 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`).
Expand Down Expand Up @@ -1109,7 +1090,6 @@ Calculates the difference for each element of an array instance with the respect
- an array containing the element-wise differences. The returned array must have a data type determined by {ref}`type-promotion`.

```{note}

Element-wise results must equal the results returned by the equivalent element-wise function [`subtract(x1, x2)`](elementwise_functions.md#subtractx1-x2-).
```

Expand Down Expand Up @@ -1162,7 +1142,6 @@ For floating-point operands, let `self` equal `x1` and `other` equal `x2`.
- an array containing the element-wise results. The returned array must have a data type determined by {ref}`type-promotion`.

```{note}

Element-wise results must equal the results returned by the equivalent element-wise function [`divide(x1, x2)`](elementwise_functions.md#dividex1-x2-).
```

Expand All @@ -1188,6 +1167,5 @@ Evaluates `self_i ^ other_i` for each element of an array instance with the resp
- an array containing the element-wise results. The returned array must have a data type determined by {ref}`type-promotion`.

```{note}

Element-wise results must equal the results returned by the equivalent element-wise function [`bitwise_xor(x1, x2)`](elementwise_functions.md#bitwise_xorx1-x2-).
```