ENH: Add np.linalg.matrix_transpose

[asmeurer]

Unlike np.transpose(), matrix_transpose() only operates on the last 2 dimensions of an array, and raises an exception if it is 0- or 1-dimensional.

This is a function from the array API specification. See https://data-apis.org/array-api/latest/API_specification/generated/signatures.linear_algebra_functions.matrix_transpose.html

This was mentioned in this issue #13797

Some things left to do, which I would like some help with:

• matrix_transpose should also be added to the main np namespace. What is the correct way to do that? (the spec specifies it should be in both the main namespace and the linalg sub-namespace)
• I need to add it to the documentation (presumably under its main namespace name, which is why I will do this once I have the above item done)
• There is also an mT attribute that can be added to the array object, which is a shorthand for matrix_transpose. Should I add that in this PR? There was some discussion on the list about it, which is why I haven't done it yet.
• This replaces the internal np.linalg.linalg.transpose function. Should I re-include that function for backwards compatibility?
• Did I implement everything correctly here? I added the @array_function_dispatch to the function? Is there anything else I need to do?
• Is it OK that this function is implemented in pure Python? It is basically a wrapper around np.swapaxes(x, -1, -2) (with a shape check to give a better error message for ndim < 2)
• Is the error message and error type (ValueError) OK for ndim < 2?
• I also know I need to add a release note entry. I will do so once we sort out what will happen here for np.matrix_transpose and ndarry.mT.
• Is it OK to use a positional-only argument for this function? There shouldn't be a problem adding it for a new function, but we can also wait until we generally move all functions to positional-only.

[charris]

LGTM on first look, needs a release note.

Is there a particular reason for the name "matrix_transpose"? Something shorter would be nice, but the current name has the advantage of being unambiguous. What about a method, "mT"? I would be in favor of such an addition despite the hesitance to add new methods.

[asmeurer]

Is there a particular reason for the name "matrix_transpose"? Something shorter would be nice, but the current name has the advantage of being unambiguous.

That's the idea. Ideally just transpose and .T would do a matrix transpose, but currently they don't for stacked matrices. Changing that is a difficult proposition, hence the new, unambiguous function.

What about a method, "mT"?

A mT attribute (not method) is proposed, but it is a bit more controversial, so I will likely implement in a separate pull request.

[seberg]

LGTM, it sounds like nobody minded the addition. The only thing is whether we should coerce, since NumPy does that everywhere (this does not affect the internal usage in linalg).
If we don't coerce, the function has little to add over an attribute?

[seberg]

Suggested change

	@array_function_dispatch(_matrix_transpose_dispatcher)
	@array_function_dispatch(_matrix_transpose_dispatcher, module='numpy.linalg')

although I guess you want to copy it also into the main namespace, in which case we have to decide for one of the two modules.

[seberg]

Hmmm, this will effectively not work for many array-likes, which is fairly untypical for NumPy. Is that what we want? swapaxes itself checks for the attribute or coerces unfortunately.

[seberg]

If we implement .mT then this function should possibly just try obj.mT and otherwise coerce?

[seberg]

Could also check for may_share_memory() or a.base is a just for completeness sake.

[seberg]

To answer a few questions:

1. ValueError seems right, we have AxisError, but it subclasses ValueError and I doubt this normally runs into an other error currently.
2. I am OK with removing np.linalg.linalg.transpose, but be ready to re-add it if downstream complains (possibly with a deprecation warning).
3. If you plan to add .mT anyway, that might make things simpler here, since it should probably be used here.
4. I like using positional-only in such clear-cut cases, but don't care either way. I expect we could get away with transitioning most of these type of functions anyway.

[rgommers]

This was superseded by gh-25155 I think, we've got a matrix_transpose in the main namespace and in linalg. Can this be closed?