The `transpose` function is problematic

There are multiple problems, both related to adoption due to conflicting definitions, and because NumPy’s transpose does something no one really wants (namely, swap all axes).

The current array API transpose may not be correct:

• https://data-apis.org/array-api/latest/API_specification/linear_algebra_functions.html#transpose-x-axes-none says “swap all axes”
• https://github.com/data-apis/array-api/issues/147 claims the intent is to only swap the last two axes, to be consistent with all other linalg functions.

PyTorch names the numpy.transpose equivalent permute, and PyTorch’s transpose is np.swapaxes. Relevant issues PyTorch issues:

• https://github.com/pytorch/pytorch/issues/50275
• https://github.com/pytorch/pytorch/issues/51280

Relevant NumPy issues:

• https://github.com/numpy/numpy/issues/9530
• https://github.com/numpy/numpy/issues/7495
• https://github.com/numpy/numpy/issues/13797 (note that there’s np.linalg.linalg.transpose which is private but does have the desired behavior)

There’s multiple ways of dealing with this problem:

1. Accept the status quo
2. Remove transpose completely, and use permute or some other function name with the behavior we want by default (do the right thing for batches of 2-D matrices)
3. Add both, by adding a matrix_transpose function and a corresponding .mT (or .MT) attribute

I searched the JAX and TensorFlow issue trackers as well and, somewhat surprisingly, didn’t find an issue about this topic.

[shoyer]

I think separating the functionality of np.transpose() into two separate functions/methods would make sense. As you note, there are two distinct use cases:

1. Swap the last two dimensions
2. Permute axes

The only real relation is that (1) can be implemented via (2).

From my perspective, the functionality (1) would be the best fit for the name “transpose”, and (2) could use some other name, like “permute axes”.

[rgommers]

permute_dims seems quite reasonable too. If we consistently name keywords axis/axes, using _dims for function names and ndim for attribute is at least some kind of consistency.