From 20b3f28a28452983945d55573536ede5ca5fd079 Mon Sep 17 00:00:00 2001 From: Anton Volkov Date: Wed, 8 Oct 2025 15:42:40 +0200 Subject: [PATCH 01/15] Add a page to list exceptions and warnings --- doc/reference/exceptions.rst | 14 ++++++++++++++ doc/reference/routines.rst | 1 + 2 files changed, 15 insertions(+) create mode 100644 doc/reference/exceptions.rst diff --git a/doc/reference/exceptions.rst b/doc/reference/exceptions.rst new file mode 100644 index 000000000000..935ccd93dec3 --- /dev/null +++ b/doc/reference/exceptions.rst @@ -0,0 +1,14 @@ +.. _routines.exceptions: + +Exceptions and Warnings +======================= + +General exceptions used by DPNP. Note that some exceptions may be module +specific, such as linear algebra errors. + +.. currentmodule:: dpnp.exceptions + +Exceptions +---------- + +.. autodata:: DLPackCreationError diff --git a/doc/reference/routines.rst b/doc/reference/routines.rst index 1cfca82a15de..e38eb159fd32 100644 --- a/doc/reference/routines.rst +++ b/doc/reference/routines.rst @@ -15,6 +15,7 @@ These functions cover a subset of array-manipulation bitwise dtype + exceptions fft functional indexing From 6b657f7b5106e925a100dc9434e0a3510a31e0de Mon Sep 17 00:00:00 2001 From: Anton Volkov Date: Wed, 8 Oct 2025 15:43:06 +0200 Subject: [PATCH 02/15] Add dpnp.exceptions submodule --- dpnp/__init__.py | 3 ++- dpnp/exceptions/__init__.py | 5 +++++ 2 files changed, 7 insertions(+), 1 deletion(-) create mode 100644 dpnp/exceptions/__init__.py diff --git a/dpnp/__init__.py b/dpnp/__init__.py index c00e5eed9dc1..df9cfeadbee6 100644 --- a/dpnp/__init__.py +++ b/dpnp/__init__.py @@ -73,6 +73,7 @@ from .dpnp_iface_utils import * from .dpnp_iface_utils import __all__ as _ifaceutils__all__ from ._version import get_versions +from . import exceptions as exceptions from . import linalg as linalg from . import scipy as scipy @@ -80,7 +81,7 @@ __all__ += _ifaceutils__all__ # add submodules -__all__ += ["linalg", "scipy"] +__all__ += ["exceptions", "linalg", "scipy"] __version__ = get_versions()["version"] diff --git a/dpnp/exceptions/__init__.py b/dpnp/exceptions/__init__.py new file mode 100644 index 000000000000..0d4f6a0d701c --- /dev/null +++ b/dpnp/exceptions/__init__.py @@ -0,0 +1,5 @@ +from dpctl.tensor._dlpack import DLPackCreationError + +__all__ = [ + "DLPackCreationError", +] From 702b33958c8d288ae89a7790674f551f2ae31fd5 Mon Sep 17 00:00:00 2001 From: Anton Volkov Date: Wed, 8 Oct 2025 15:44:05 +0200 Subject: [PATCH 03/15] Add DLPackCreationError exception to docstring of dpnp.from_dlpack --- dpnp/dpnp_iface_arraycreation.py | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/dpnp/dpnp_iface_arraycreation.py b/dpnp/dpnp_iface_arraycreation.py index ca65fbfffd97..8ceed6c51978 100644 --- a/dpnp/dpnp_iface_arraycreation.py +++ b/dpnp/dpnp_iface_arraycreation.py @@ -2234,9 +2234,12 @@ def from_dlpack(x, /, *, device=None, copy=None): Raises ------ TypeError - if `obj` does not implement ``__dlpack__`` method + if `x` does not implement ``__dlpack__`` method ValueError if data of the input object resides on an unsupported device + DLPackCreationError + when `x` is allocated on a partitioned SYCL device, or with + a non-default context Notes ----- From f9c7ee98ee7186572e1dbae7d77e7f4b25ed765e Mon Sep 17 00:00:00 2001 From: Anton Volkov Date: Wed, 8 Oct 2025 16:35:02 +0200 Subject: [PATCH 04/15] Add detailed description to DLPackCreationError exception --- doc/reference/exceptions.rst | 25 ++++++++++++++++++++++++- 1 file changed, 24 insertions(+), 1 deletion(-) diff --git a/doc/reference/exceptions.rst b/doc/reference/exceptions.rst index 935ccd93dec3..404f7fe62056 100644 --- a/doc/reference/exceptions.rst +++ b/doc/reference/exceptions.rst @@ -11,4 +11,27 @@ specific, such as linear algebra errors. Exceptions ---------- -.. autodata:: DLPackCreationError +.. data:: AxisError + + Given when an axis is invalid. + +.. data:: DLPackCreationError + + Given when constructing DLPack capsule from either :class:`dpnp.ndarray` or + :class:`dpctl.tensor.usm_ndarray` based on a USM allocation + on a partitioned SYCL device. + + .. rubric:: Examples + + .. code-block:: python + + >>> import dpnp as np + >>> import dpctl + >>> dev = dpctl.SyclDevice('cpu') + >>> sdevs = dev.create_sub_devices(partition=[1, 1]) + >>> q = dpctl.SyclQueue(sdevs[0]) + >>> x = np.ones(10, sycl_queue=q) + >>> np.from_dlpack(x) + Traceback (most recent call last): + ... + DLPackCreationError: to_dlpack_capsule: DLPack can only export arrays based on USM allocations bound to a default platform SYCL context From 640236f6e6f914a5a2f28597b49579f5f37aaa59 Mon Sep 17 00:00:00 2001 From: Anton Volkov Date: Wed, 8 Oct 2025 16:35:24 +0200 Subject: [PATCH 05/15] Add AxisError exception to dpnp.exceptions submodule --- dpnp/exceptions/__init__.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/dpnp/exceptions/__init__.py b/dpnp/exceptions/__init__.py index 0d4f6a0d701c..e8861b23aa78 100644 --- a/dpnp/exceptions/__init__.py +++ b/dpnp/exceptions/__init__.py @@ -1,5 +1,7 @@ from dpctl.tensor._dlpack import DLPackCreationError +from numpy.exceptions import AxisError __all__ = [ + "AxisError", "DLPackCreationError", ] From 54338863963a895c0606d9a5e4b943580e3fff24 Mon Sep 17 00:00:00 2001 From: Anton Volkov Date: Thu, 9 Oct 2025 11:33:13 +0200 Subject: [PATCH 06/15] Add dpnp.exception to setup.py --- setup.py | 1 + 1 file changed, 1 insertion(+) diff --git a/setup.py b/setup.py index 53f6f80674d8..cc21221299c4 100644 --- a/setup.py +++ b/setup.py @@ -36,6 +36,7 @@ "dpnp", "dpnp.dpnp_algo", "dpnp.dpnp_utils", + "dpnp.exceptions", "dpnp.fft", "dpnp.linalg", "dpnp.memory", From 5602d811c89a4781b9e2beb9d4ea837e79e70509 Mon Sep 17 00:00:00 2001 From: Anton Volkov Date: Thu, 9 Oct 2025 11:37:32 +0200 Subject: [PATCH 07/15] Add SyclDeviceCreationError to the dpnp.exceptions module and documentation page --- doc/reference/exceptions.rst | 2 ++ dpnp/exceptions/__init__.py | 2 ++ 2 files changed, 4 insertions(+) diff --git a/doc/reference/exceptions.rst b/doc/reference/exceptions.rst index 404f7fe62056..85043b28e4f5 100644 --- a/doc/reference/exceptions.rst +++ b/doc/reference/exceptions.rst @@ -35,3 +35,5 @@ Exceptions Traceback (most recent call last): ... DLPackCreationError: to_dlpack_capsule: DLPack can only export arrays based on USM allocations bound to a default platform SYCL context + +.. autodata:: SyclDeviceCreationError diff --git a/dpnp/exceptions/__init__.py b/dpnp/exceptions/__init__.py index e8861b23aa78..2edc28175ada 100644 --- a/dpnp/exceptions/__init__.py +++ b/dpnp/exceptions/__init__.py @@ -1,7 +1,9 @@ +from dpctl import SyclDeviceCreationError from dpctl.tensor._dlpack import DLPackCreationError from numpy.exceptions import AxisError __all__ = [ "AxisError", "DLPackCreationError", + "SyclDeviceCreationError", ] From 5fa26b0e615c547f7f093f814cb85641d9cbf7e2 Mon Sep 17 00:00:00 2001 From: Anton Volkov Date: Thu, 9 Oct 2025 12:21:48 +0200 Subject: [PATCH 08/15] Expose more dpctl exceptions: SyclContextCreationError, SyclQueueCreationError, USMAllocationError, ExecutionPlacementError --- doc/reference/exceptions.rst | 30 +++++++++++++++++++++++++++++- dpnp/exceptions/__init__.py | 12 +++++++++++- 2 files changed, 40 insertions(+), 2 deletions(-) diff --git a/doc/reference/exceptions.rst b/doc/reference/exceptions.rst index 85043b28e4f5..8d647e6d3918 100644 --- a/doc/reference/exceptions.rst +++ b/doc/reference/exceptions.rst @@ -36,4 +36,32 @@ Exceptions ... DLPackCreationError: to_dlpack_capsule: DLPack can only export arrays based on USM allocations bound to a default platform SYCL context -.. autodata:: SyclDeviceCreationError +.. data:: ExecutionPlacementError + + Given when execution placement target can not be unambiguously determined + from input arrays. Make sure that input arrays are associated with the same + :class:`dpctl.SyclQueue`, or migrate data to the same + :class:`dpctl.SyclQueue` using :meth:`dpnp.ndarray.to_device` method. + +.. data:: SyclContextCreationError + + Given when :class:`dpctl.SyclContext` instance could not created. + +.. data:: SyclDeviceCreationError + + Given when :class:`dpctl.SyclDevice` instance could not created. + +.. data:: SyclQueueCreationError + + Given when :class:`dpctl.SyclQueue` instance could not created. + The creation can fail if the filter string is invalid, or the backend or + device type values are not supported. + +.. data:: USMAllocationError + + Given when Unified Shared Memory (USM) allocation call returns a null + pointer, signaling a failure to perform the allocation. + Some common reasons for allocation failure are: + + * insufficient free memory to perform the allocation request + * allocation size exceeds the maximum supported by targeted backend diff --git a/dpnp/exceptions/__init__.py b/dpnp/exceptions/__init__.py index 2edc28175ada..30e23ffabc30 100644 --- a/dpnp/exceptions/__init__.py +++ b/dpnp/exceptions/__init__.py @@ -1,9 +1,19 @@ -from dpctl import SyclDeviceCreationError +from dpctl import ( + SyclContextCreationError, + SyclDeviceCreationError, + SyclQueueCreationError, +) +from dpctl.memory import USMAllocationError from dpctl.tensor._dlpack import DLPackCreationError +from dpctl.utils import ExecutionPlacementError from numpy.exceptions import AxisError __all__ = [ "AxisError", "DLPackCreationError", + "ExecutionPlacementError", "SyclDeviceCreationError", + "SyclContextCreationError", + "SyclQueueCreationError", + "USMAllocationError", ] From efd2876a7aa5da75e32de4f4ce4ca365e61c955c Mon Sep 17 00:00:00 2001 From: Anton Volkov Date: Thu, 9 Oct 2025 13:03:26 +0200 Subject: [PATCH 09/15] Add PR to the changelog --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index a2ee5771a5b9..5dfcdfbed0d2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,7 @@ This release changes the license from `BSD-2-Clause` to `BSD-3-Clause`. ### Added * Added the docstrings to `dpnp.linalg.LinAlgError` exception [#2613](https://github.com/IntelPython/dpnp/pull/2613) +* Added `dpnp.exceptions` submodule to aggregate the generic exceptions used by dpnp [#2616](https://github.com/IntelPython/dpnp/pull/2616) ### Changed From 5a07e2e5b540d4db9f2887a1b141cc06c21c59be Mon Sep 17 00:00:00 2001 From: Anton Volkov Date: Fri, 10 Oct 2025 11:37:51 +0200 Subject: [PATCH 10/15] Add license header to new file --- dpnp/exceptions/__init__.py | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/dpnp/exceptions/__init__.py b/dpnp/exceptions/__init__.py index 30e23ffabc30..dff67e64ca25 100644 --- a/dpnp/exceptions/__init__.py +++ b/dpnp/exceptions/__init__.py @@ -1,3 +1,32 @@ +# -*- coding: utf-8 -*- +# ***************************************************************************** +# Copyright (c) 2025, Intel Corporation +# All rights reserved. +# +# Redistribution and use in source and binary forms, with or without +# modification, are permitted provided that the following conditions are met: +# - Redistributions of source code must retain the above copyright notice, +# this list of conditions and the following disclaimer. +# - Redistributions in binary form must reproduce the above copyright notice, +# this list of conditions and the following disclaimer in the documentation +# and/or other materials provided with the distribution. +# - Neither the name of the copyright holder nor the names of its contributors +# may be used to endorse or promote products derived from this software +# without specific prior written permission. +# +# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE +# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF +# THE POSSIBILITY OF SUCH DAMAGE. +# ***************************************************************************** + from dpctl import ( SyclContextCreationError, SyclDeviceCreationError, From 4cd44811d76fd5b57011a2c9494745dfed42f882 Mon Sep 17 00:00:00 2001 From: Anton <100830759+antonwolfy@users.noreply.github.com> Date: Mon, 13 Oct 2025 11:33:53 +0200 Subject: [PATCH 11/15] Apply suggestions from code review Co-authored-by: vlad-perevezentsev --- doc/reference/exceptions.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/reference/exceptions.rst b/doc/reference/exceptions.rst index 8d647e6d3918..0628fadeff03 100644 --- a/doc/reference/exceptions.rst +++ b/doc/reference/exceptions.rst @@ -45,15 +45,15 @@ Exceptions .. data:: SyclContextCreationError - Given when :class:`dpctl.SyclContext` instance could not created. + Given when :class:`dpctl.SyclContext` instance could not be created. .. data:: SyclDeviceCreationError - Given when :class:`dpctl.SyclDevice` instance could not created. + Given when :class:`dpctl.SyclDevice` instance could not be created. .. data:: SyclQueueCreationError - Given when :class:`dpctl.SyclQueue` instance could not created. + Given when :class:`dpctl.SyclQueue` instance could not be created. The creation can fail if the filter string is invalid, or the backend or device type values are not supported. From cc9d274ca91f30018f4962c9a02c30e959065254 Mon Sep 17 00:00:00 2001 From: Anton Volkov Date: Tue, 14 Oct 2025 13:02:04 +0200 Subject: [PATCH 12/15] Use exception:: directive to document exceptions instead of data:: --- doc/reference/exceptions.rst | 82 +++++++++++++++++++----------------- 1 file changed, 43 insertions(+), 39 deletions(-) diff --git a/doc/reference/exceptions.rst b/doc/reference/exceptions.rst index 0628fadeff03..2d9f530fbe96 100644 --- a/doc/reference/exceptions.rst +++ b/doc/reference/exceptions.rst @@ -1,67 +1,71 @@ .. _routines.exceptions: +.. py:module:: dpnp.exceptions + Exceptions and Warnings ======================= General exceptions used by DPNP. Note that some exceptions may be module specific, such as linear algebra errors. -.. currentmodule:: dpnp.exceptions - Exceptions ---------- -.. data:: AxisError +.. exception:: AxisError + + Given when an axis is invalid. + +.. exception:: DLPackCreationError - Given when an axis is invalid. + Given when constructing DLPack capsule from either :class:`dpnp.ndarray` or + :class:`dpctl.tensor.usm_ndarray` based on a USM allocation + on a partitioned SYCL device. -.. data:: DLPackCreationError + .. rubric:: Examples - Given when constructing DLPack capsule from either :class:`dpnp.ndarray` or - :class:`dpctl.tensor.usm_ndarray` based on a USM allocation - on a partitioned SYCL device. + .. code-block:: python - .. rubric:: Examples + >>> import dpnp as np + >>> import dpctl + >>> dev = dpctl.SyclDevice('cpu') + >>> sdevs = dev.create_sub_devices(partition=[1, 1]) + >>> q = dpctl.SyclQueue(sdevs[0]) + >>> x = np.ones(10, sycl_queue=q) + >>> np.from_dlpack(x) + Traceback (most recent call last): + ... + DLPackCreationError: to_dlpack_capsule: DLPack can only export arrays based on USM allocations bound to a default platform SYCL context - .. code-block:: python +.. exception:: ExecutionPlacementError - >>> import dpnp as np - >>> import dpctl - >>> dev = dpctl.SyclDevice('cpu') - >>> sdevs = dev.create_sub_devices(partition=[1, 1]) - >>> q = dpctl.SyclQueue(sdevs[0]) - >>> x = np.ones(10, sycl_queue=q) - >>> np.from_dlpack(x) - Traceback (most recent call last): - ... - DLPackCreationError: to_dlpack_capsule: DLPack can only export arrays based on USM allocations bound to a default platform SYCL context + Given when execution placement target can not be unambiguously determined + from input arrays. Make sure that input arrays are associated with the same + :class:`dpctl.SyclQueue`, or migrate data to the same + :class:`dpctl.SyclQueue` using :meth:`dpnp.ndarray.to_device` method. -.. data:: ExecutionPlacementError +.. exception:: SyclContextCreationError - Given when execution placement target can not be unambiguously determined - from input arrays. Make sure that input arrays are associated with the same - :class:`dpctl.SyclQueue`, or migrate data to the same - :class:`dpctl.SyclQueue` using :meth:`dpnp.ndarray.to_device` method. + Given when :class:`dpctl.SyclContext` instance could not be created. -.. data:: SyclContextCreationError +.. exception:: SyclDeviceCreationError - Given when :class:`dpctl.SyclContext` instance could not be created. + Given when :class:`dpctl.SyclDevice` instance could not be created. -.. data:: SyclDeviceCreationError +.. exception:: SyclQueueCreationError - Given when :class:`dpctl.SyclDevice` instance could not be created. + Given when :class:`dpctl.SyclQueue` instance could not be created. + The creation can fail if the filter string is invalid, or the backend or + device type values are not supported. -.. data:: SyclQueueCreationError +.. exception:: USMAllocationError - Given when :class:`dpctl.SyclQueue` instance could not be created. - The creation can fail if the filter string is invalid, or the backend or - device type values are not supported. + Given when Unified Shared Memory (USM) allocation call returns a null + pointer, signaling a failure to perform the allocation. + Some common reasons for allocation failure are: -.. data:: USMAllocationError + * insufficient free memory to perform the allocation request + * allocation size exceeds the maximum supported by targeted backend - Given when Unified Shared Memory (USM) allocation call returns a null - pointer, signaling a failure to perform the allocation. - Some common reasons for allocation failure are: - * insufficient free memory to perform the allocation request - * allocation size exceeds the maximum supported by targeted backend +.. automodule:: dpnp.exceptions + :no-index: From eebc331476b18021ef0cbb29f3f7665ea68b497b Mon Sep 17 00:00:00 2001 From: Anton Volkov Date: Tue, 14 Oct 2025 13:03:03 +0200 Subject: [PATCH 13/15] Add files produced by the doc build to the git ignore list --- .gitignore | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/.gitignore b/.gitignore index c263dae47818..33d07d623ff8 100644 --- a/.gitignore +++ b/.gitignore @@ -7,6 +7,11 @@ dpnp.egg-info # Byte-compiled / optimized / DLL files __pycache__/ +# Doc build and generated files +doc/_build +doc/reference/generated/ +doc/reference/*.inc + # Code project files .vscode From 4e1ba3649d2e8ed0f100dc015ec9a98097499d49 Mon Sep 17 00:00:00 2001 From: Anton <100830759+antonwolfy@users.noreply.github.com> Date: Tue, 14 Oct 2025 14:41:30 +0200 Subject: [PATCH 14/15] Apply suggestions from code review Co-authored-by: vlad-perevezentsev --- dpnp/dpnp_iface_arraycreation.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/dpnp/dpnp_iface_arraycreation.py b/dpnp/dpnp_iface_arraycreation.py index 8ceed6c51978..d768a2f69a6f 100644 --- a/dpnp/dpnp_iface_arraycreation.py +++ b/dpnp/dpnp_iface_arraycreation.py @@ -2234,12 +2234,12 @@ def from_dlpack(x, /, *, device=None, copy=None): Raises ------ TypeError - if `x` does not implement ``__dlpack__`` method + If `x` does not implement ``__dlpack__`` method. ValueError - if data of the input object resides on an unsupported device + If data of the input object resides on an unsupported device. DLPackCreationError - when `x` is allocated on a partitioned SYCL device, or with - a non-default context + When `x` is allocated on a partitioned SYCL device, or with + a non-default context. Notes ----- From 6c487cd496da04c8ed887c4f9b171bcd57ca7f56 Mon Sep 17 00:00:00 2001 From: Anton <100830759+antonwolfy@users.noreply.github.com> Date: Tue, 14 Oct 2025 15:20:46 +0200 Subject: [PATCH 15/15] Update .gitignore Co-authored-by: vlad-perevezentsev --- .gitignore | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.gitignore b/.gitignore index 33d07d623ff8..0188b5019d0e 100644 --- a/.gitignore +++ b/.gitignore @@ -8,7 +8,7 @@ dpnp.egg-info __pycache__/ # Doc build and generated files -doc/_build +doc/_build/ doc/reference/generated/ doc/reference/*.inc