From a04e5792c1efaabd3bd752ccfcbd88eea64a0e4f Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 30 Aug 2021 11:00:51 -0700 Subject: [PATCH 1/3] Rename (and move) `transpose` to `permute` --- .../linear_algebra_functions.md | 21 ------------------- .../manipulation_functions.md | 21 +++++++++++++++++++ 2 files changed, 21 insertions(+), 21 deletions(-) diff --git a/spec/API_specification/linear_algebra_functions.md b/spec/API_specification/linear_algebra_functions.md index 3724c2c24..a96e79a30 100644 --- a/spec/API_specification/linear_algebra_functions.md +++ b/spec/API_specification/linear_algebra_functions.md @@ -93,27 +93,6 @@ Returns a tensor contraction of `x1` and `x2` over specific axes. - an array containing the tensor contraction whose shape consists of the non-contracted axes (dimensions) of the first array `x1`, followed by the non-contracted axes (dimensions) of the second array `x2`. The returned array must have a data type determined by {ref}`type-promotion`. -(function-transpose)= -### transpose(x, /, *, axes=None) - -Transposes (or permutes the axes (dimensions)) of an array `x`. - -#### Parameters - -- **x**: _<array>_ - - - input array. - -- **axes**: _Optional\[ Tuple\[ int, ... ] ]_ - - - tuple containing a permutation of `(0, 1, ..., N-1)` where `N` is the number of axes (dimensions) of `x`. If `None`, the axes (dimensions) must be permuted in reverse order (i.e., equivalent to setting `axes=(N-1, ..., 1, 0)`). Default: `None`. - -#### Returns - -- **out**: _<array>_ - - - an array containing the transpose. The returned array must have the same data type as `x`. - (function-vecdot)= ### vecdot(x1, x2, /, *, axis=None) diff --git a/spec/API_specification/manipulation_functions.md b/spec/API_specification/manipulation_functions.md index e1e0e98ea..0988b7679 100644 --- a/spec/API_specification/manipulation_functions.md +++ b/spec/API_specification/manipulation_functions.md @@ -80,6 +80,27 @@ Reverses the order of elements in an array along the given axis. The shape of th - an output array having the same data type and shape as `x` and whose elements, relative to `x`, are reordered. +(function-permute)= +### permute(x, /, *, axes=None) + +Permutes the axes (dimensions) of an array `x`. + +#### Parameters + +- **x**: _<array>_ + + - input array. + +- **axes**: _Optional\[ Tuple\[ int, ... ] ]_ + + - tuple containing a permutation of `(0, 1, ..., N-1)` where `N` is the number of axes (dimensions) of `x`. If `None`, the axes (dimensions) must be permuted in reverse order (i.e., equivalent to setting `axes=(N-1, ..., 1, 0)`). Default: `None`. + +#### Returns + +- **out**: _<array>_ + + - an array containing the axes permutation. The returned array must have the same data type as `x`. + (function-reshape)= ### reshape(x, /, shape) From ed96f7da6d57b26d8342067a194ab52b22862536 Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 30 Aug 2021 11:10:40 -0700 Subject: [PATCH 2/3] Remove specification for `linalg.transpose` --- spec/extensions/linear_algebra_functions.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/spec/extensions/linear_algebra_functions.md b/spec/extensions/linear_algebra_functions.md index 2e4302539..715ae2a52 100644 --- a/spec/extensions/linear_algebra_functions.md +++ b/spec/extensions/linear_algebra_functions.md @@ -562,11 +562,6 @@ Returns the sum along the specified diagonals of a matrix (or a stack of matrice The returned array must have the same data type as `x`. -(function-linalg-transpose)= -### linalg.transpose(x, /, *, axes=None) - -Alias for {ref}`function-transpose`. - (function-linalg-vecdot)= ### linalg.vecdot(x1, x2, /, *, axis=None) From d9be95d83ab1afce741fd430376db26d7232386a Mon Sep 17 00:00:00 2001 From: Athan Reines Date: Mon, 20 Sep 2021 01:52:09 -0700 Subject: [PATCH 3/3] Rename function to `permute_dims`, make `axes` argument required, and update reference --- spec/API_specification/array_object.md | 2 +- spec/API_specification/manipulation_functions.md | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/spec/API_specification/array_object.md b/spec/API_specification/array_object.md index 0b0ca24f1..9569f0168 100644 --- a/spec/API_specification/array_object.md +++ b/spec/API_specification/array_object.md @@ -274,7 +274,7 @@ 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. +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_dims` interface found in this specification. ``` #### Returns diff --git a/spec/API_specification/manipulation_functions.md b/spec/API_specification/manipulation_functions.md index 0988b7679..1f140bcb0 100644 --- a/spec/API_specification/manipulation_functions.md +++ b/spec/API_specification/manipulation_functions.md @@ -80,8 +80,8 @@ Reverses the order of elements in an array along the given axis. The shape of th - an output array having the same data type and shape as `x` and whose elements, relative to `x`, are reordered. -(function-permute)= -### permute(x, /, *, axes=None) +(function-permute-dims)= +### permute_dims(x, /, axes) Permutes the axes (dimensions) of an array `x`. @@ -91,9 +91,9 @@ Permutes the axes (dimensions) of an array `x`. - input array. -- **axes**: _Optional\[ Tuple\[ int, ... ] ]_ +- **axes**: _Tuple\[ int, ... ]_ - - tuple containing a permutation of `(0, 1, ..., N-1)` where `N` is the number of axes (dimensions) of `x`. If `None`, the axes (dimensions) must be permuted in reverse order (i.e., equivalent to setting `axes=(N-1, ..., 1, 0)`). Default: `None`. + - tuple containing a permutation of `(0, 1, ..., N-1)` where `N` is the number of axes (dimensions) of `x`. #### Returns