From d57a1f8ff1a7ac9478155b75da5072d1f8e0ece0 Mon Sep 17 00:00:00 2001 From: Athan Date: Mon, 20 Sep 2021 01:59:50 -0700 Subject: [PATCH] Rename (and move) `transpose` to `permute_dims` (#247) * Rename (and move) `transpose` to `permute` * Remove specification for `linalg.transpose` * Rename function to `permute_dims`, make `axes` argument required, and update reference --- spec/API_specification/array_object.md | 2 +- .../manipulation_functions.md | 21 +++++++++++++++++++ 2 files changed, 22 insertions(+), 1 deletion(-) 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 e1e0e98ea..1f140bcb0 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-dims)= +### permute_dims(x, /, axes) + +Permutes the axes (dimensions) of an array `x`. + +#### Parameters + +- **x**: _<array>_ + + - input array. + +- **axes**: _Tuple\[ int, ... ]_ + + - tuple containing a permutation of `(0, 1, ..., N-1)` where `N` is the number of axes (dimensions) of `x`. + +#### 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)