diff --git a/.gitignore b/.gitignore index c263dae47818..0188b5019d0e 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 diff --git a/CHANGELOG.md b/CHANGELOG.md index 3e5bc60b80db..e2ecf1684beb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,6 +12,7 @@ This release changes the license from `BSD-2-Clause` to `BSD-3-Clause`. * Added the docstrings to `dpnp.linalg.LinAlgError` exception [#2613](https://github.com/IntelPython/dpnp/pull/2613) * Added implementation of `dpnp.linalg.lu_solve` for batch inputs (SciPy-compatible) [#2619](https://github.com/IntelPython/dpnp/pull/2619) +* Added `dpnp.exceptions` submodule to aggregate the generic exceptions used by dpnp [#2616](https://github.com/IntelPython/dpnp/pull/2616) ### Changed diff --git a/doc/reference/exceptions.rst b/doc/reference/exceptions.rst new file mode 100644 index 000000000000..2d9f530fbe96 --- /dev/null +++ b/doc/reference/exceptions.rst @@ -0,0 +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. + +Exceptions +---------- + +.. exception:: AxisError + + Given when an axis is invalid. + +.. exception:: 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 + +.. exception:: 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. + +.. exception:: SyclContextCreationError + + Given when :class:`dpctl.SyclContext` instance could not be created. + +.. exception:: SyclDeviceCreationError + + Given when :class:`dpctl.SyclDevice` instance could not be created. + +.. exception:: SyclQueueCreationError + + 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. + +.. exception:: 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 + + +.. automodule:: dpnp.exceptions + :no-index: 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 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/dpnp_iface_arraycreation.py b/dpnp/dpnp_iface_arraycreation.py index ca65fbfffd97..d768a2f69a6f 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 + 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 ----- diff --git a/dpnp/exceptions/__init__.py b/dpnp/exceptions/__init__.py new file mode 100644 index 000000000000..dff67e64ca25 --- /dev/null +++ b/dpnp/exceptions/__init__.py @@ -0,0 +1,48 @@ +# -*- 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, + 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", +] 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",