diff --git a/CHANGELOG.md b/CHANGELOG.md index f1cbd15b0a0..0bab2d17db6 100644 --- a/CHANGELOG.md +++ b/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) diff --git a/doc/reference/linalg.rst b/doc/reference/linalg.rst index 142c6052db8..e397ba20c42 100644 --- a/doc/reference/linalg.rst +++ b/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. diff --git a/dpnp/backend/extensions/lapack/lapack_py.cpp b/dpnp/backend/extensions/lapack/lapack_py.cpp index 5e072bfeac8..1a237bed0ec 100644 --- a/dpnp/backend/extensions/lapack/lapack_py.cpp +++ b/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(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(m, "LinAlgError", + PyExc_ValueError); init_dispatch_vectors(); init_dispatch_tables(); diff --git a/dpnp/linalg/dpnp_iface_linalg.py b/dpnp/linalg/dpnp_iface_linalg.py index ec48ccf381f..b729c68c4b8 100644 --- a/dpnp/linalg/dpnp_iface_linalg.py +++ b/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