Rename (and move) transpose to permute_dims

[kgryte]

This PR:

• renames (and moves) the current transpose API to permute_dims (which is consistent with the *_dims naming convention (e.g., expand_dims)), as discussed in gh-228.
• makes the axes argument a required argument (as discussed in the consortium meeting held 2021-09-16).
• removes default behavior of reversing all axes (as discussed in the consortium meeting held 2021-09-16).

Background

The current behavior of transpose where all axes are reversed, even for arrays having more than two dimensions, is considered problematic due to its conflicting with the mathematical definition and not operating on batches of matrices.

By renaming the transpose function to permute_dims and moving the API to the set of manipulation functions, we both (1) provide a functional API which allows consumers to achieve equivalent functionality possible today (see gh-245), thus providing a migration path, and (2) avoid conflicting definitions.

This PR further helps pave the way for a dedicated matrix_transpose API for operating on stacks of matrices.

[rgommers]

LGTM

[asmeurer]

This is a new function, right (not in any of the existing APIs under this name)? Is there any reason to keep the default argument for axes?

[kgryte]

@asmeurer It is a new function insofar as it has a different name, but still retains the same default behavior as transpose. Otherwise, what other default do you propose?

[asmeurer]

I would propose making axes a required argument. I don't feel strongly about it, but reversing seems like an odd default. Unless there are legitimate use-cases for reversing (I was never clear that there were).

[kgryte]

Updated the PR such that the function name is permute_dims, the axes argument is required, and the default behavior is no longer to reverse all axes. This was discussed and approved during the most recent consortium meeting held on 2021-09-16. As such, will go ahead and merge...