Add documentation to LinAlgError exception (#2613)

The PR adds missing docstrings to `dpnp.linalg.LinAlgError` exception.

Author: antonwolfy

CHANGELOG.md

@@ -8,6 +8,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+* Added the docstrings to `dpnp.linalg.LinAlgError` exception [#2613](https://github.com/IntelPython/dpnp/pull/2613)
+
 ### Changed
 
 * Silenced `pybind11` CMake message due to using compatibility mode for Python [#2614](https://github.com/IntelPython/dpnp/pull/2614)

doc/reference/linalg.rst

@@ -107,4 +107,20 @@ Exceptions
    :toctree: generated/
    :nosignatures:
 
-   dpnp.linalg.linAlgError
+   dpnp.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) {dpnp.ndarray, usm_ndarray}``. 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.

dpnp/backend/extensions/lapack/lapack_py.cpp

@@ -83,9 +83,10 @@ PYBIND11_MODULE(_lapack_impl, m)
         .value("C", oneapi::mkl::transpose::C)
         .export_values(); // Optional, allows access like `Transpose.N`
 
-    // Register a LinAlgError exception in the current submodule
-    py::register_exception<lapack_ext::LinAlgError>(m, "LinAlgError",
-                                                    PyExc_ValueError);
+    // Register a LinAlgError exception with local scope, meaning this is a
+    // module-private exception (only used in that module)
+    py::register_local_exception<lapack_ext::LinAlgError>(m, "LinAlgError",
+                                                          PyExc_ValueError);
 
     init_dispatch_vectors();
     init_dispatch_tables();

dpnp/linalg/dpnp_iface_linalg.py

@@ -104,8 +104,27 @@
     "vector_norm",
 ]
 
-# Need to set the module explicitly, since exposed by LAPACK pybind11 extension
+# Need to set the module explicitly, because it's initially exposed by LAPACK
+# pybind11 extension and to add the docstrings
 LinAlgError.__module__ = "dpnp.linalg"
+LinAlgError.__doc__ = """
+Generic Python-exception-derived object raised by LinAlg functions.
+
+For full documentation refer to :obj:`numpy.linalg.LinAlgError`.
+
+General purpose exception class, derived from Python's ``ValueError`` class,
+programmatically raised in LinAlg functions when a Linear Algebra-related
+condition would prevent further correct execution of the function.
+
+Examples
+--------
+>>> import dpnp as np
+>>> np.linalg.inv(np.zeros((2, 2)))
+Traceback (most recent call last):
+...
+dpnp.linalg.LinAlgError: The input coefficient matrix is singular.
+
+"""
 
 
 # pylint:disable=missing-class-docstring