DOC: document the behavior of generalized N-dim linear algebra functions

1 files changed, 18 insertions, 0 deletions

diff --git a/doc/source/reference/routines.linalg.rst b/doc/source/reference/routines.linalg.rst
index 173a6ad53..00620347a 100644
--- a/doc/source/reference/routines.linalg.rst
+++ b/doc/source/reference/routines.linalg.rst
@@ -67,3 +67,21 @@ Exceptions
    :toctree: generated/
 
    linalg.LinAlgError
+
+Linear algebra on several matrices at once
+------------------------------------------
+
+Several of the linear algebra routines listed above are able to
+compute results for several matrices at once, if they are stacked into
+the same array.
+
+This is indicated in the documentation via input parameter
+specifications such as ``a : (..., M, M) array_like``. This means that
+if for instance given an input array ``a.shape == (N, M, M)``, it is
+interpreted as a "stack" of N matrices, each of size M-by-M. Similar
+specification applies to return values, for instance the determinant
+has ``det : (...)`` and will in this case return an array of shape
+``det(a).shape == (N,)``. This generalizes to linear algebra
+operations on higher-dimensional arrays: the last 1 or 2 dimensions of
+a multidimensional array are interpreted as vectors or matrices, as
+appropriate for each operation.