Add specification for computing the matrix transpose (#248)

Author: kgryte

spec/API_specification/linear_algebra_functions.md

@@ -60,6 +60,23 @@ The `matmul` function must implement the same semantics as the built-in `@` oper
 -   if `x1` is a one-dimensional array having shape `(N)`, `x2` is a one-dimensional array having shape `(M)`, and `N != M`.
 -   if `x1` is an array having shape `(..., M, K)`, `x2` is an array having shape `(..., L, N)`, and `K != L`.
 
+(function-matrix-transpose)=
+### matrix_transpose(x, /)
+
+Transposes a matrix (or a stack of matrices) `x`.
+
+#### Parameters
+
+-   **x**: _<array>_
+
+    -   input array having shape `(..., M, N)` and whose innermost two dimensions form `MxN` matrices.
+
+#### Returns
+
+-   **out**: _<array>_
+
+    -   an array containing the transpose for each matrix and having shape `(..., N, M)`. The returned array must have the same data type as `x`.
+
 (function-tensordot)=
 ### tensordot(x1, x2, /, *, axes=2)
 
@@ -93,27 +110,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)
 

spec/extensions/linear_algebra_functions.md

@@ -357,6 +357,11 @@ Computes the rank (i.e., number of non-zero singular values) of a matrix (or a s
 
     -   an array containing the ranks. The returned array must have a floating-point data type determined by {ref}`type-promotion` and must have shape `(...)` (i.e., must have a shape equal to `shape(x)[:-2]`).
 
+(function-linalg-matrix-transpose)=
+### linalg.matrix_transpose(x, /)
+
+Alias for {ref}`function-matrix-transpose`.
+
 (function-linalg-outer)=
 ### linalg.outer(x1, x2, /)
 
@@ -562,11 +567,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)