Add a page with constants documented and set a proper reference on dpnp.DLDeviceType

Author: antonwolfy

doc/reference/constants.rst

@@ -0,0 +1,162 @@
+Constants
+=================================
+
+DPNP includes several constants:
+
+.. currentmodule:: dpnp
+
+.. autodata:: DLDeviceType
+
+.. data:: e
+
+    Euler's constant, base of natural logarithms, Napier's constant.
+
+    ``e = 2.71828182845904523536028747135266249775724709369995...``
+
+    .. rubric:: See Also
+
+    :func:`exp` : Exponential function
+
+    :func:`log` : Natural logarithm
+
+    .. rubric:: References
+
+    https://en.wikipedia.org/wiki/E_%28mathematical_constant%29
+
+
+.. data:: euler_gamma
+
+    ``γ = 0.5772156649015328606065120900824024310421...``
+
+    .. rubric:: References
+
+    https://en.wikipedia.org/wiki/Euler%27s_constant
+
+
+.. data:: inf
+
+    IEEE 754 floating point representation of (positive) infinity.
+
+    .. rubric:: Returns
+
+    y : float
+        A floating point representation of positive infinity.
+
+    .. rubric:: See Also
+
+    :func:`isinf` : Shows which elements are positive or negative infinity
+
+    :func:`isposinf` : Shows which elements are positive infinity
+
+    :func:`isneginf` : Shows which elements are negative infinity
+
+    :func:`isnan` : Shows which elements are Not a Number
+
+    :func:`isfinite` : Shows which elements are finite (not one of Not a Number,
+    positive infinity and negative infinity)
+
+    .. rubric:: Notes
+
+    DPNP uses the IEEE Standard for Binary Floating-Point for Arithmetic
+    (IEEE 754). This means that Not a Number is not equivalent to infinity.
+    Also that positive infinity is not equivalent to negative infinity. But
+    infinity is equivalent to positive infinity.
+
+    .. rubric:: Examples
+
+    .. code-block:: python
+
+        >>> import dpnp as np
+        >>> np.inf
+        inf
+        >>> np.array([1]) / 0.0
+        array([inf])
+
+
+.. data:: nan
+
+    IEEE 754 floating point representation of Not a Number (NaN).
+
+    .. rubric:: Returns
+
+    y : A floating point representation of Not a Number.
+
+    .. rubric:: See Also
+
+    :func:`isnan` : Shows which elements are Not a Number.
+
+    :func:`isfinite` : Shows which elements are finite (not one of Not a Number,
+    positive infinity and negative infinity)
+
+    .. rubric:: Notes
+
+    DPNP uses the IEEE Standard for Binary Floating-Point for Arithmetic
+    (IEEE 754). This means that Not a Number is not equivalent to infinity.
+
+    .. rubric:: Examples
+
+    .. code-block:: python
+
+        >>> import dpnp as np
+        >>> np.nan
+        nan
+        >>> np.log(np.array(-1))
+        array(nan)
+        >>> np.log(np.array([-1, 1, 2]))
+        array([       nan, 0.        , 0.69314718])
+
+
+.. data:: newaxis
+
+    A convenient alias for *None*, useful for indexing arrays.
+
+    .. rubric:: Examples
+
+    .. code-block:: python
+
+        >>> import dpnp as np
+        >>> np.newaxis is None
+        True
+        >>> x = np.arange(3)
+        >>> x
+        array([0, 1, 2])
+        >>> x[:, np.newaxis]
+        array([[0],
+            [1],
+            [2]])
+        >>> x[:, np.newaxis, np.newaxis]
+        array([[[0]],
+            [[1]],
+            [[2]]])
+        >>> x[:, np.newaxis] * x
+        array([[0, 0, 0],
+            [0, 1, 2],
+            [0, 2, 4]])
+
+        Outer product, same as ``outer(x, y)``:
+
+        >>> y = np.arange(3, 6)
+        >>> x[:, np.newaxis] * y
+        array([[ 0,  0,  0],
+            [ 3,  4,  5],
+            [ 6,  8, 10]])
+
+        ``x[np.newaxis, :]`` is equivalent to ``x[np.newaxis]`` and ``x[None]``:
+
+        >>> x[np.newaxis, :].shape
+        (1, 3)
+        >>> x[np.newaxis].shape
+        (1, 3)
+        >>> x[None].shape
+        (1, 3)
+        >>> x[:, np.newaxis].shape
+        (3, 1)
+
+
+.. data:: pi
+
+    ``pi = 3.1415926535897932384626433...``
+
+    .. rubric:: References
+
+    https://en.wikipedia.org/wiki/Pi

doc/reference/routines.rst

@@ -11,6 +11,7 @@ These functions cover a subset of
 .. toctree::
    :maxdepth: 2
 
+   constants
    array-creation
    array-manipulation
    bitwise

dpnp/dpnp_array.py

@@ -233,9 +233,9 @@ def __dlpack__(
         dl_device : {tuple, None}, optional:
             The device the returned DLPack capsule will be placed on. The
             device must be a 2-tuple matching the format of
-            ``__dlpack_device__`` method, an integer enumerator representing
-            the device type followed by an integer representing the index of
-            the device.
+            :meth:`dpnp.ndarray.__dlpack_device__`, an integer enumerator
+            representing the device type followed by an integer representing
+            the index of the device.
 
             Default: ``None``.
         copy : {bool, None}, optional:
@@ -278,9 +278,12 @@ def __dlpack_device__(self, /):
         allocated, or the non-partitioned parent device of the allocation
         device.
 
+        See :class:`dpnp.DLDeviceType` for a list of devices supported by the
+        DLPack protocol.
+
         Raises
         ------
-        DLPackCreationError:
+        DLPackCreationError
             when the ``device_id`` could not be determined.
 
         """

dpnp/dpnp_iface_arraycreation.py

@@ -2180,8 +2180,9 @@ def from_dlpack(x, /, *, device=None, copy=None):
     Parameters
     ----------
     x : object
-        A Python object representing an array that implements the ``__dlpack__``
-        and ``__dlpack_device__`` methods.
+        A Python object representing an array that implements the
+        :meth:`dpnp.ndarray.__dlpack__` and
+        :meth:`dpnp.ndarray.__dlpack_device__`.
     device : {None, string, tuple, device}, optional
         Device where the output array is to be placed. `device` keyword values
         can be:
@@ -2197,10 +2198,10 @@ def from_dlpack(x, /, *, device=None, copy=None):
           ``device.sycl_queue``. The `device` object is obtained via
           :attr:`dpctl.tensor.usm_ndarray.device`.
         * ``(device_type, device_id)`` : 2-tuple matching the format of the
-          output of the ``__dlpack_device__`` method: an integer enumerator
-          representing the device type followed by an integer representing
-          the index of the device. The only supported :class:`dpnp.DLDeviceType`
-          device types are ``"kDLCPU"`` and ``"kDLOneAPI"``.
+          output of the :meth:`dpnp.ndarray.__dlpack_device__`: an integer
+          enumerator representing the device type followed by an integer
+          representing the index of the device. The only supported
+          :class:`dpnp.DLDeviceType` are ``"kDLCPU"`` and ``"kDLOneAPI"``.
 
         Default: ``None``.
     copy : {bool, None}, optional