From 00d1d336d031e7d8a4359651703c2563dc6f3b68 Mon Sep 17 00:00:00 2001 From: Anton Volkov Date: Tue, 7 Oct 2025 16:26:27 +0200 Subject: [PATCH 1/6] Fix type in LinAlgError exception name on the rst page --- doc/reference/linalg.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/reference/linalg.rst b/doc/reference/linalg.rst index 142c6052db8..3cef4948983 100644 --- a/doc/reference/linalg.rst +++ b/doc/reference/linalg.rst @@ -107,4 +107,4 @@ Exceptions :toctree: generated/ :nosignatures: - dpnp.linalg.linAlgError + dpnp.linalg.LinAlgError From aa7e1cc93f248af021883f7b3757fe96947d8d28 Mon Sep 17 00:00:00 2001 From: Anton Volkov Date: Tue, 7 Oct 2025 16:48:52 +0200 Subject: [PATCH 2/6] Add doctrings to the LinAlgError exception --- dpnp/linalg/dpnp_iface_linalg.py | 23 ++++++++++++++++++++++- 1 file changed, 22 insertions(+), 1 deletion(-) diff --git a/dpnp/linalg/dpnp_iface_linalg.py b/dpnp/linalg/dpnp_iface_linalg.py index ec48ccf381f..23b721ce82b 100644 --- a/dpnp/linalg/dpnp_iface_linalg.py +++ b/dpnp/linalg/dpnp_iface_linalg.py @@ -104,8 +104,29 @@ "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. + +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. + +Parameters +---------- +None + +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 From ef1ce030b1bdfddaa013041dc418da10690810f8 Mon Sep 17 00:00:00 2001 From: Anton Volkov Date: Tue, 7 Oct 2025 16:51:04 +0200 Subject: [PATCH 3/6] Register the exception with py::register_local_exception() --- dpnp/backend/extensions/lapack/lapack_py.cpp | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) 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(); From 31a3a7f65b4d113f62aa3de085951b04becc9d64 Mon Sep 17 00:00:00 2001 From: Anton Volkov Date: Tue, 7 Oct 2025 16:57:32 +0200 Subject: [PATCH 4/6] Add a note how stacked array is handled in liear algebra --- doc/reference/linalg.rst | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/doc/reference/linalg.rst b/doc/reference/linalg.rst index 3cef4948983..e397ba20c42 100644 --- a/doc/reference/linalg.rst +++ b/doc/reference/linalg.rst @@ -108,3 +108,19 @@ Exceptions :nosignatures: 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. From d04aee096349b63dbd12b135b847cc770e3ddb0f Mon Sep 17 00:00:00 2001 From: Anton Volkov Date: Tue, 7 Oct 2025 17:55:41 +0200 Subject: [PATCH 5/6] Add a link to numpy doc --- dpnp/linalg/dpnp_iface_linalg.py | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/dpnp/linalg/dpnp_iface_linalg.py b/dpnp/linalg/dpnp_iface_linalg.py index 23b721ce82b..b729c68c4b8 100644 --- a/dpnp/linalg/dpnp_iface_linalg.py +++ b/dpnp/linalg/dpnp_iface_linalg.py @@ -110,14 +110,12 @@ 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. -Parameters ----------- -None - Examples -------- >>> import dpnp as np From 07abc6c36bbd227ffe4da436d595d2dcdde5fac9 Mon Sep 17 00:00:00 2001 From: Anton Volkov Date: Wed, 8 Oct 2025 11:11:29 +0200 Subject: [PATCH 6/6] Add the PR to changelog --- CHANGELOG.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4a0b98a42ef..d2c83c2d939 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 ### Deprecated