Adds order="K" support to array-like functions

`empty_like`, `zeros_like`, `ones_like`, and `full_like` all gain this support

Slips in changes to typos in docstrings

Author: ndgrigorian

dpctl/tensor/_ctors.py

@@ -904,7 +904,7 @@ def zeros(
             data type of the array. Can be typestring,
             a :class:`numpy.dtype` object, :mod:`numpy` char string,
             or a NumPy scalar type. Default: ``None``
-        order ("C", or F"):
+        order ("C", or "F"):
             memory layout for the array. Default: ``"C"``
         device (optional): array API concept of device where the output array
             is created. ``device`` can be ``None``, a oneAPI filter selector
@@ -975,7 +975,7 @@ def ones(
             data type of the array. Can be typestring,
             a :class:`numpy.dtype` object, :mod:`numpy` char string,
             or a NumPy scalar type. Default: ``None``
-        order ("C", or F"): memory layout for the array. Default: ``"C"``
+        order ("C", or "F"): memory layout for the array. Default: ``"C"``
         device (optional): array API concept of device where the output array
             is created. ``device`` can be ``None``, a oneAPI filter selector
             string, an instance of :class:`dpctl.SyclDevice` corresponding to
@@ -1043,7 +1043,7 @@ def full(
         dtype (optional): data type of the array. Can be typestring,
             a :class:`numpy.dtype` object, :mod:`numpy` char string,
             or a NumPy scalar type. Default: ``None``
-        order ("C", or F"):
+        order ("C", or "F"):
             memory layout for the array. Default: ``"C"``
         device (optional): array API concept of device where the output array
             is created. ``device`` can be ``None``, a oneAPI filter selector
@@ -1121,7 +1121,7 @@ def full(
 
 
 def empty_like(
-    x, /, *, dtype=None, order="C", device=None, usm_type=None, sycl_queue=None
+    x, /, *, dtype=None, order="K", device=None, usm_type=None, sycl_queue=None
 ):
     """
     Returns an uninitialized :class:`dpctl.tensor.usm_ndarray` with the
@@ -1134,8 +1134,8 @@ def empty_like(
             data type of the array. Can be a typestring,
             a :class:`numpy.dtype` object, NumPy char string,
             or a NumPy scalar type. Default: ``None``
-        order ("C", or F"):
-            memory layout for the array. Default: ``"C"``
+        order ("C", "F", "A", or "K"):
+            memory layout for the array. Default: ``"K"``
         device (optional): array API concept of device where the output array
             is created. ``device`` can be ``None``, a oneAPI filter selector
             string, an instance of :class:`dpctl.SyclDevice` corresponding to
@@ -1161,11 +1161,8 @@ def empty_like(
     """
     if not isinstance(x, dpt.usm_ndarray):
         raise TypeError(f"Expected instance of dpt.usm_ndarray, got {type(x)}.")
-    if not isinstance(order, str) or len(order) == 0 or order[0] not in "CcFf":
-        raise ValueError(
-            "Unrecognized order keyword value, expecting 'F' or 'C'."
-        )
-    order = order[0].upper()
+    if order not in ("K", "C", "F", "A"):
+        order = "K"
     if dtype is None:
         dtype = x.dtype
     if usm_type is None:
@@ -1174,17 +1171,28 @@ def empty_like(
     if device is None and sycl_queue is None:
         device = x.device
     sycl_queue = normalize_queue_device(sycl_queue=sycl_queue, device=device)
-    shape = x.shape
     dtype = dpt.dtype(dtype)
-    _ensure_native_dtype_device_support(dtype, sycl_queue.sycl_device)
-    res = dpt.usm_ndarray(
-        shape,
-        dtype=dtype,
-        buffer=usm_type,
-        order=order,
-        buffer_ctor_kwargs={"queue": sycl_queue},
-    )
-    return res
+    x_flags = x.flags
+    f_contig = x_flags["F"]
+    c_contig = x_flags["C"]
+    if order == "A":
+        order = "F" if f_contig and not c_contig else "C"
+    if order == "K" and (f_contig or c_contig):
+        order = "C" if c_contig else "F"
+    if order == "K":
+        _ensure_native_dtype_device_support(dtype, sycl_queue.sycl_device)
+        return _empty_like_orderK(x, dtype, usm_type, sycl_queue)
+    else:
+        shape = x.shape
+        _ensure_native_dtype_device_support(dtype, sycl_queue.sycl_device)
+        res = dpt.usm_ndarray(
+            shape,
+            dtype=dtype,
+            buffer=usm_type,
+            order=order,
+            buffer_ctor_kwargs={"queue": sycl_queue},
+        )
+        return res
 
 
 def zeros_like(
@@ -1203,7 +1211,7 @@ def zeros_like(
             a :class:`numpy.dtype` object, :mod:`numpy` char string, or a
             NumPy scalar type. If `None`, output array has the same data
             type as the input array. Default: ``None``
-        order ("C", or F"):
+        order ("C", or "F"):
             memory layout for the array. Default: ``"C"``
         device (optional):
             array API concept of device where the output array
@@ -1231,11 +1239,8 @@ def zeros_like(
     """
     if not isinstance(x, dpt.usm_ndarray):
         raise TypeError(f"Expected instance of dpt.usm_ndarray, got {type(x)}.")
-    if not isinstance(order, str) or len(order) == 0 or order[0] not in "CcFf":
-        raise ValueError(
-            "Unrecognized order keyword value, expecting 'F' or 'C'."
-        )
-    order = order[0].upper()
+    if order not in ("K", "C", "F", "A"):
+        order = "K"
     if dtype is None:
         dtype = x.dtype
     if usm_type is None:
@@ -1244,20 +1249,37 @@ def zeros_like(
     if device is None and sycl_queue is None:
         device = x.device
     sycl_queue = normalize_queue_device(sycl_queue=sycl_queue, device=device)
-    sh = x.shape
     dtype = dpt.dtype(dtype)
-    return zeros(
-        sh,
-        dtype=dtype,
-        order=order,
-        device=device,
-        usm_type=usm_type,
-        sycl_queue=sycl_queue,
-    )
+    x_flags = x.flags
+    f_contig = x_flags["F"]
+    c_contig = x_flags["C"]
+    if order == "A":
+        order = "F" if f_contig and not c_contig else "C"
+    if order == "K" and (f_contig or c_contig):
+        order = "C" if c_contig else "F"
+    if order == "K":
+        _ensure_native_dtype_device_support(dtype, sycl_queue.sycl_device)
+        res = _empty_like_orderK(x, dtype, usm_type, sycl_queue)
+        _manager = dpctl.utils.SequentialOrderManager[sycl_queue]
+        # populating new allocation, no dependent events
+        hev, full_ev = ti._full_usm_ndarray(0, res, sycl_queue)
+        _manager.add_event_pair(hev, full_ev)
+        return res
+    else:
+        _ensure_native_dtype_device_support(dtype, sycl_queue.sycl_device)
+        sh = x.shape
+        return zeros(
+            sh,
+            dtype=dtype,
+            order=order,
+            device=device,
+            usm_type=usm_type,
+            sycl_queue=sycl_queue,
+        )
 
 
 def ones_like(
-    x, /, *, dtype=None, order="C", device=None, usm_type=None, sycl_queue=None
+    x, /, *, dtype=None, order="K", device=None, usm_type=None, sycl_queue=None
 ):
     """
     Returns a new :class:`dpctl.tensor.usm_ndarray` filled with ones and
@@ -1270,7 +1292,7 @@ def ones_like(
             data type of the array. Can be typestring,
             a :class:`numpy.dtype` object, :mod:`numpy` char string,
             or a NumPy scalar type. Default: `None`
-        order ("C", or F"):
+        order ("C", "F", "A", or "K"):
             memory layout for the array. Default: ``"C"``
         device (optional):
             array API concept of device where the output array
@@ -1298,11 +1320,8 @@ def ones_like(
     """
     if not isinstance(x, dpt.usm_ndarray):
         raise TypeError(f"Expected instance of dpt.usm_ndarray, got {type(x)}.")
-    if not isinstance(order, str) or len(order) == 0 or order[0] not in "CcFf":
-        raise ValueError(
-            "Unrecognized order keyword value, expecting 'F' or 'C'."
-        )
-    order = order[0].upper()
+    if order not in ("K", "C", "F", "A"):
+        order = "K"
     if dtype is None:
         dtype = x.dtype
     if usm_type is None:
@@ -1311,16 +1330,32 @@ def ones_like(
     if device is None and sycl_queue is None:
         device = x.device
     sycl_queue = normalize_queue_device(sycl_queue=sycl_queue, device=device)
-    sh = x.shape
     dtype = dpt.dtype(dtype)
-    return ones(
-        sh,
-        dtype=dtype,
-        order=order,
-        device=device,
-        usm_type=usm_type,
-        sycl_queue=sycl_queue,
-    )
+    x_flags = x.flags
+    f_contig = x_flags["F"]
+    c_contig = x_flags["C"]
+    if order == "A":
+        order = "F" if f_contig and not c_contig else "C"
+    if order == "K" and (f_contig or c_contig):
+        order = "C" if c_contig else "F"
+    if order == "K":
+        _ensure_native_dtype_device_support(dtype, sycl_queue.sycl_device)
+        res = _empty_like_orderK(x, dtype, usm_type, sycl_queue)
+        _manager = dpctl.utils.SequentialOrderManager[sycl_queue]
+        # populating new allocation, no dependent events
+        hev, full_ev = ti._full_usm_ndarray(1, res, sycl_queue)
+        _manager.add_event_pair(hev, full_ev)
+        return res
+    else:
+        sh = x.shape
+        return ones(
+            sh,
+            dtype=dtype,
+            order=order,
+            device=device,
+            usm_type=usm_type,
+            sycl_queue=sycl_queue,
+        )
 
 
 def full_like(
@@ -1334,7 +1369,7 @@ def full_like(
     usm_type=None,
     sycl_queue=None,
 ):
-    """ full_like(x, fill_value, dtype=None, order="C", \
+    """ full_like(x, fill_value, dtype=None, order="K", \
                   device=None, usm_type=None, sycl_queue=None)
 
     Returns a new :class:`dpctl.tensor.usm_ndarray` filled with `fill_value`
@@ -1349,8 +1384,8 @@ def full_like(
             a :class:`numpy.dtype` object, :mod:`numpy` char string, or a
             NumPy scalar type. If ``dtype`` is ``None``, the output array data
             type is inferred from ``x``. Default: ``None``
-        order ("C", or F"):
-            memory layout for the array. Default: ``"C"``
+        order ("C", "F", "A", or "K"):
+            memory layout for the array. Default: ``"K"``
         device (optional):
             array API concept of device where the output array
             is created. ``device`` can be ``None``, a oneAPI filter selector
@@ -1377,11 +1412,8 @@ def full_like(
     """
     if not isinstance(x, dpt.usm_ndarray):
         raise TypeError(f"Expected instance of dpt.usm_ndarray, got {type(x)}.")
-    if not isinstance(order, str) or len(order) == 0 or order[0] not in "CcFf":
-        raise ValueError(
-            "Unrecognized order keyword value, expecting 'F' or 'C'."
-        )
-    order = order[0].upper()
+    if order not in ("K", "C", "F", "A"):
+        order = "K"
     if dtype is None:
         dtype = x.dtype
     if usm_type is None:
@@ -1392,15 +1424,49 @@ def full_like(
     sycl_queue = normalize_queue_device(sycl_queue=sycl_queue, device=device)
     sh = x.shape
     dtype = dpt.dtype(dtype)
-    return full(
-        sh,
-        fill_value,
-        dtype=dtype,
-        order=order,
-        device=device,
-        usm_type=usm_type,
-        sycl_queue=sycl_queue,
-    )
+    x_flags = x.flags
+    f_contig = x_flags["F"]
+    c_contig = x_flags["C"]
+    if order == "A":
+        order = "F" if f_contig and not c_contig else "C"
+    if order == "K" and (f_contig or c_contig):
+        order = "C" if c_contig else "F"
+    if order == "K":
+        _ensure_native_dtype_device_support(dtype, sycl_queue.sycl_device)
+        if isinstance(fill_value, (dpt.usm_ndarray, np.ndarray, tuple, list)):
+            X = dpt.asarray(
+                fill_value,
+                dtype=dtype,
+                order=order,
+                usm_type=usm_type,
+                sycl_queue=sycl_queue,
+            )
+            X = dpt.broadcast_to(X, sh)
+            res = _empty_like_orderK(x, dtype, usm_type, sycl_queue)
+            _manager = dpctl.utils.SequentialOrderManager[sycl_queue]
+            # populating new allocation, no dependent events
+            hev, copy_ev = ti._copy_usm_ndarray_into_usm_ndarray(
+                src=X, dst=res, sycl_queue=sycl_queue
+            )
+            _manager.add_event_pair(hev, copy_ev)
+            return res
+        else:
+            res = _empty_like_orderK(x, dtype, usm_type, sycl_queue)
+            _manager = dpctl.utils.SequentialOrderManager[sycl_queue]
+            # populating new allocation, no dependent events
+            hev, full_ev = ti._full_usm_ndarray(fill_value, res, sycl_queue)
+            _manager.add_event_pair(hev, full_ev)
+            return res
+    else:
+        return full(
+            sh,
+            fill_value,
+            dtype=dtype,
+            order=order,
+            device=device,
+            usm_type=usm_type,
+            sycl_queue=sycl_queue,
+        )
 
 
 def linspace(
@@ -1536,7 +1602,7 @@ def eye(
             data type of the array. Can be typestring,
             a :class:`numpy.dtype` object, :mod:`numpy` char string, or
             a NumPy scalar type. Default: ``None``
-        order ("C" or F"):
+        order ("C" or "F"):
             memory layout for the array. Default: ``"C"``
         device (optional):
             array API concept of device where the output array