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

Author: antonwolfy

doc/reference/constants.rst

@@ -0,0 +1,161 @@
+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
+
+.. try_examples::
+
+    >>> 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
+
+.. try_examples::
+
+    >>> 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
+
+.. try_examples::
+
+    >>> 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

@@ -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.
 
         """