Merge pull request #1123 from IntelPython/tensor-docs-cleanup

Closes gh-1114 and gh-1116

Author: Diptorup Deb

dpctl/tensor/_copy_utils.py

@@ -128,11 +128,22 @@ def from_numpy(np_ary, device=None, usm_type="device", sycl_queue=None):
     `numpy.ndarray`.
 
     Args:
-        arg: An instance of `numpy.ndarray`
+        arg: An instance of input `numpy.ndarray`
         device: array API specification of device where the output array
-            is created.
-        sycl_queue: a :class:`dpctl.SyclQueue` used to create the output
-            array is created
+            is created
+        usm_type: The requested USM allocation type for the output array
+        sycl_queue: a :class:`dpctl.SyclQueue` instance that determines
+            output array allocation device as well as placement of data
+            movement operation. The `device` and `sycl_queue` arguments
+            are equivalent. Only one of them should be specified. If both
+            are provided, they must be consistent and result in using the
+            same execution queue.
+
+    The returned array has the same shape, and the same data type kind.
+    If the device does not support the data type of input array, a
+    closest support data type of the same kind may be returned, e.g.
+    input array of type `float16` may be upcast to `float32` if the
+    target device does not support 16-bit floating point type.
     """
     q = normalize_queue_device(sycl_queue=sycl_queue, device=device)
     return _copy_from_numpy(np_ary, usm_type=usm_type, sycl_queue=q)

dpctl/tensor/_ctors.py

@@ -39,14 +39,16 @@ def __new__(cls, *args, **kwargs):
         raise TypeError("No public constructor")
 
     @classmethod
-    def create_device(cls, dev):
-        """
+    def create_device(cls, dev=None):
+        """Device.create_device(dev=None)
+
         Creates instance of Device from argument.
 
         Args:
-            dev: None, :class:`.Device`, :class:`dpctl.SyclQueue`, or
-                 a :class:`dpctl.SyclDevice` corresponding to a root SYCL
-                 device.
+            dev:
+                Device specification, i.e. `None`, :class:`.Device`,
+                :class:`dpctl.SyclQueue`, or a :class:`dpctl.SyclDevice`
+                corresponding to a root SYCL device.
         Raises:
             ValueError: if an instance of :class:`dpctl.SycDevice` corresponding
                         to a sub-device was specified as the argument
@@ -135,14 +137,13 @@ def __hash__(self):
 
 
 def normalize_queue_device(sycl_queue=None, device=None):
-    """
-    normalize_queue_device(sycl_queue=None, device=None)
+    """normalize_queue_device(sycl_queue=None, device=None)
 
     Utility to process exclusive keyword arguments 'device'
     and 'sycl_queue' in functions of `dpctl.tensor`.
 
     Args:
-        sycl_queue(:class:`dpctl.SyclQueue`, optional):
+        sycl_queue (:class:`dpctl.SyclQueue`, optional):
             explicitly indicates where USM allocation is done
             and the population code (if any) is executed.
             Value `None` is interpreted as get the SYCL queue

dpctl/tensor/_device.py

@@ -469,13 +469,25 @@ cpdef usm_ndarray from_dlpack_capsule(object py_caps) except +:
 
 
 cpdef from_dlpack(array):
-    """
-    dpctl.tensor.from_dlpack(obj) -> dpctl.tensor.usm_ndarray
+    """ from_dlpack(obj)
 
     Constructs :class:`dpctl.tensor.usm_ndarray` instance from a Python
     object `obj` that implements `__dlpack__` protocol. The output
     array is always a zero-copy view of the input.
 
+    Args:
+        obj: A Python object representing an array that supports `__dlpack__`
+            protocol.
+
+    Returns:
+        out (usm_ndarray):
+            An array with a view into the tensor underlying the input `obj`.
+
+    Raises:
+        TypeError: if `obj` does not implement `__dlpack__` method.
+        ValueError: if zero copy view can not be constructed because
+            the input array resides on an unsupported device.
+
     See https://dmlc.github.io/dlpack/latest/ for more details.
 
     :Example:
@@ -498,13 +510,6 @@ cpdef from_dlpack(array):
             C = Container(dpt.linspace(0, 100, num=20, dtype="int16"))
             X = dpt.from_dlpack(C)
 
-    Args:
-        obj: A Python object representing an array that supports `__dlpack__`
-            protocol.
-    Raises:
-        TypeError: if `obj` does not implement `__dlpack__` method.
-        ValueError: if zero copy view can not be constructed because
-            the input array resides on an unsupported device.
     """
     if not hasattr(array, "__dlpack__"):
         raise TypeError(

dpctl/tensor/_dlpack.pyx

@@ -32,18 +32,20 @@ def take(x, indices, /, *, axis=None, mode="clip"):
     Takes elements from array along a given axis.
 
     Args:
-       x: usm_ndarray
+       x (usm_ndarray):
           The array that elements will be taken from.
-       indices: usm_ndarray
+       indices (usm_ndarray):
           One-dimensional array of indices.
        axis:
           The axis over which the values will be selected.
           If x is one-dimensional, this argument is optional.
+          Default: `None`.
        mode:
           How out-of-bounds indices will be handled.
-          "Clip" - clamps indices to (-n <= i < n), then wraps
+          "clip" - clamps indices to (-n <= i < n), then wraps
           negative indices.
-          "Wrap" - wraps both negative and positive indices.
+          "wrap" - wraps both negative and positive indices.
+          Default: `"clip"`.
 
     Returns:
        out: usm_ndarray
@@ -119,21 +121,23 @@ def put(x, indices, vals, /, *, axis=None, mode="clip"):
     along a given axis.
 
     Args:
-       x: usm_ndarray
+       x (usm_ndarray):
           The array the values will be put into.
-       indices: usm_ndarray
+       indices (usm_ndarray)
           One-dimensional array of indices.
        vals:
           Array of values to be put into `x`.
           Must be broadcastable to the shape of `indices`.
        axis:
           The axis over which the values will be placed.
           If x is one-dimensional, this argument is optional.
+          Default: `None`.
        mode:
           How out-of-bounds indices will be handled.
-          "Clip" - clamps indices to (-axis_size <= i < axis_size),
+          "clip" - clamps indices to (-axis_size <= i < axis_size),
           then wraps negative indices.
-          "Wrap" - wraps both negative and positive indices.
+          "wrap" - wraps both negative and positive indices.
+          Default: `"clip"`.
     """
     if not isinstance(x, dpt.usm_ndarray):
         raise TypeError(
@@ -219,14 +223,14 @@ def extract(condition, arr):
     ``dpctl.tensor.extract``.
 
     Args:
-       conditions: usm_ndarray
+       conditions (usm_ndarray):
             An array whose non-zero or True entries indicate the element
             of `arr` to extract.
-       arr: usm_ndarray
+       arr (usm_ndarray):
             Input array of the same size as `condition`.
 
     Returns:
-        usm_ndarray
+        out (usm_ndarray):
             Rank 1 array of values from `arr` where `condition` is True.
     """
     if not isinstance(condition, dpt.usm_ndarray):
@@ -259,11 +263,11 @@ def place(arr, mask, vals):
     equivalent to ``arr[condition] = vals``.
 
     Args:
-        arr: usm_ndarray
+        arr (usm_ndarray):
             Array to put data into.
-       mask: usm_ndarray
+        mask (usm_ndarray):
             Boolean mask array. Must have the same size as `arr`.
-       vals: usm_ndarray
+        vals (usm_ndarray, sequence):
             Values to put into `arr`. Only the first N elements are
             used, where N is the number of True values in `mask`. If
             `vals` is smaller than N, it will be repeated, and if
@@ -325,10 +329,10 @@ def nonzero(arr):
     row-major, C-style order.
 
     Args:
-        arr: usm_ndarray
+        arr (usm_ndarray):
             Input array, which has non-zero array rank.
     Returns:
-        Tuple[usm_ndarray]
+        out: Tuple[usm_ndarray, ...]
             Indices of non-zero array elements.
     """
     if not isinstance(arr, dpt.usm_ndarray):