diff --git a/dpnp/dpnp_iface_manipulation.py b/dpnp/dpnp_iface_manipulation.py index af5784ff526b..da5720ff2152 100644 --- a/dpnp/dpnp_iface_manipulation.py +++ b/dpnp/dpnp_iface_manipulation.py @@ -554,16 +554,16 @@ def append(arr, values, axis=None): arr : {dpnp.ndarray, usm_ndarray} Values are appended to a copy of this array. values : {scalar, array_like} - These values are appended to a copy of `arr`. It must be of the - correct shape (the same shape as `arr`, excluding `axis`). If - `axis` is not specified, `values` can be any shape and will be - flattened before use. - These values can be in any form that can be converted to an array. - This includes scalars, lists, lists of tuples, tuples, - tuples of tuples, tuples of lists, and ndarrays. + These values are appended to a copy of `arr`. It must be of the correct + shape (the same shape as `arr`, excluding `axis`). If `axis` is not + specified, `values` can be any shape and will be flattened before use. + These values can be in any form that can be converted to an array. This + includes scalars, lists, lists of tuples, tuples, tuples of tuples, + tuples of lists, and ndarrays. axis : {None, int}, optional - The axis along which `values` are appended. If `axis` is not - given, both `arr` and `values` are flattened before use. + The axis along which `values` are appended. If `axis` is not given, + both `arr` and `values` are flattened before use. + Default: ``None``. Returns @@ -637,11 +637,11 @@ def array_split(ary, indices_or_sections, axis=0): If `indices_or_sections` is an integer, N, and array length is l, it returns ``l % n`` sub-arrays of size ``l//n + 1`` and the rest of size ``l//n``. - If `indices_or_sections` is a sequence of sorted integers, the entries indicate where along `axis` the array is split. axis : int, optional The axis along which to split. + Default: ``0``. Returns @@ -715,9 +715,11 @@ def asarray_chkfinite( of lists and ndarrays. Success requires no NaNs or Infs. dtype : {None, str, dtype object}, optional By default, the data-type is inferred from the input data. + Default: ``None``. order : {None, "C", "F", "A", "K"}, optional Memory layout of the newly output array. + Default: ``"K"``. device : {None, string, SyclDevice, SyclQueue}, optional An array API concept of device where the output array is created. @@ -726,15 +728,18 @@ def asarray_chkfinite( a non-partitioned SYCL device, an instance of :class:`dpctl.SyclQueue`, or a `Device` object returned by :obj:`dpnp.dpnp_array.dpnp_array.device` property. + Default: ``None``. usm_type : {None, "device", "shared", "host"}, optional The type of SYCL USM allocation for the output array. + Default: ``None``. sycl_queue : {None, SyclQueue}, optional A SYCL queue to use for output array allocation and copying. The `sycl_queue` can be passed as ``None`` (the default), which means to get the SYCL queue from `device` keyword if present or to use a default queue. + Default: ``None``. Returns @@ -825,24 +830,31 @@ def asfarray(a, dtype=None, *, device=None, usm_type=None, sycl_queue=None): protocol, an instance of :class:`numpy.ndarray`, an object supporting Python buffer protocol, a Python scalar, or a (possibly nested) sequence of Python scalars. - dtype : str or dtype object, optional + dtype : {None, str, dtype object}, optional Float type code to coerce input array `a`. If `dtype` is ``None``, :obj:`dpnp.bool` or one of the `int` dtypes, it is replaced with the default floating type (:obj:`dpnp.float64` if a device supports it, or :obj:`dpnp.float32` type otherwise). + + Default: ``None``. device : {None, string, SyclDevice, SyclQueue}, optional An array API concept of device where the output array is created. The `device` can be ``None`` (the default), an OneAPI filter selector string, an instance of :class:`dpctl.SyclDevice` corresponding to a non-partitioned SYCL device, an instance of :class:`dpctl.SyclQueue`, or a `Device` object returned by :obj:`dpnp.ndarray.device` property. + + Default: ``None``. usm_type : {None, "device", "shared", "host"}, optional The type of SYCL USM allocation for the output array. + + Default: ``None``. sycl_queue : {None, SyclQueue}, optional A SYCL queue to use for output array allocation and copying. The `sycl_queue` can be passed as ``None`` (the default), which means to get the SYCL queue from `device` keyword if present or to use a default queue. + Default: ``None``. Returns @@ -1145,7 +1157,7 @@ def broadcast_to(array, /, shape, subok=False): ---------- array : {dpnp.ndarray, usm_ndarray} The array to broadcast. - shape : tuple or int + shape : {int, tuple of ints} The shape of the desired array. A single integer ``i`` is interpreted as ``(i,)``. @@ -1200,6 +1212,8 @@ def can_cast(from_, to, casting="safe"): casting : {'no', 'equiv', 'safe', 'same_kind', 'unsafe'}, optional Controls what kind of data casting may occur. + Default: ``"safe"``. + Returns ------- out: bool @@ -1349,16 +1363,23 @@ def concatenate( axis : int, optional The axis along which the arrays will be joined. If axis is ``None``, arrays are flattened before use. + Default: ``0``. out : dpnp.ndarray, optional If provided, the destination to place the result. The shape must be correct, matching that of what concatenate would have returned if no out argument were specified. - dtype : str or dtype + + Default: ``None``. + dtype : {None, str, dtype object}, optional If provided, the destination array will have this dtype. Cannot be provided together with `out`. + + Default: ``None``. casting : {'no', 'equiv', 'safe', 'same_kind', 'unsafe'}, optional - Controls what kind of data casting may occur. Defaults to 'same_kind'. + Controls what kind of data casting may occur. + + Default: ``"same_kind"``. Returns ------- @@ -1440,11 +1461,15 @@ def copyto(dst, src, casting="same_kind", where=True): The array from which values are copied. casting : {'no', 'equiv', 'safe', 'same_kind', 'unsafe'}, optional Controls what kind of data casting may occur when copying. + + Default: ``"same_kind"``. where : {dpnp.ndarray, usm_ndarray, scalar} of bool, optional A boolean array or a scalar which is broadcasted to match the dimensions of `dst`, and selects elements to copy from `src` to `dst` wherever it contains the value ``True``. + Default: ``True``. + Examples -------- >>> import dpnp as np @@ -1524,6 +1549,7 @@ def delete(arr, obj, axis=None): axis : {None, int}, optional The axis along which to delete the subarray defined by `obj`. If `axis` is ``None``, `obj` is applied to the flattened array. + Default: ``None``. Returns @@ -1750,7 +1776,7 @@ def expand_dims(a, axis): ---------- a : {dpnp.ndarray, usm_ndarray} Input array. - axis : int or tuple of ints + axis : {int, tuple of ints} Position in the expanded axes where the new axis (or axes) is placed. Returns @@ -1841,13 +1867,15 @@ def flip(m, axis=None): ---------- m : {dpnp.ndarray, usm_ndarray} Input array. - axis : None or int or tuple of ints, optional + axis : {None, int, tuple of ints}, optional Axis or axes along which to flip over. The default, ``axis=None``, will flip over all of the axes of the input array. If `axis` is negative it counts from the last to the first axis. If `axis` is a tuple of integers, flipping is performed on all of the axes specified in the tuple. + Default: ``None``. + Returns ------- out : dpnp.ndarray @@ -2107,11 +2135,15 @@ def hstack(tup, *, dtype=None, casting="same_kind"): tup : {dpnp.ndarray, usm_ndarray} The arrays must have the same shape along all but the second axis, except 1-D arrays which can be any length. - dtype : str or dtype + dtype : {None, str, dtype object}, optional If provided, the destination array will have this dtype. + + Default: ``None``. casting : {'no', 'equiv', 'safe', 'same_kind', 'unsafe'}, optional Controls what kind of data casting may occur. Defaults to 'same_kind'. + Default: ``"same_kind"``. + Returns ------- out : dpnp.ndarray @@ -2184,6 +2216,7 @@ def insert(arr, obj, values, axis=None): axis : {None, int}, optional Axis along which to insert `values`. If `axis` is ``None`` then `arr` is flattened first. + Default: ``None``. Returns @@ -2478,6 +2511,7 @@ def pad(array, pad_width, mode="constant", **kwargs): Pads with undefined values. Padding function, see Notes. + Default: ``"constant"``. stat_length : {None, int, sequence of ints}, optional Used in ``"maximum"``, ``"mean"``, ``"median"``, and ``"minimum"``. @@ -2488,7 +2522,8 @@ def pad(array, pad_width, mode="constant", **kwargs): and after statistic lengths for each axis. ``(stat_length,)`` or ``int`` is a shortcut for ``before = after = statistic`` length for all axes. - Default: ``None``, to use the entire axis. + + Default: ``None``, to use the entire axis. constant_values : {sequence, scalar}, optional Used in ``"constant"``. The values to set the padded values for each axis. @@ -2498,6 +2533,7 @@ def pad(array, pad_width, mode="constant", **kwargs): and after constants for each axis. ``(constant,)`` or ``constant`` is a shortcut for ``before = after = constant`` for all axes. + Default: ``0``. end_values : {sequence, scalar}, optional Used in ``"linear_ramp"``. The values used for the ending value of the @@ -2508,12 +2544,14 @@ def pad(array, pad_width, mode="constant", **kwargs): and after end values for each axis. ``(constant,)`` or ``constant`` is a shortcut for ``before = after = constant`` for all axes. + Default: ``0``. reflect_type : {"even", "odd"}, optional Used in ``"reflect"``, and ``"symmetric"``. The ``"even"`` style is the default with an unaltered reflection around the edge value. For the ``"odd"`` style, the extended part of the array is created by subtracting the reflected values from two times the edge value. + Default: ``"even"``. Returns @@ -2647,6 +2685,7 @@ def ravel(a, order="C"): Fortran-like index order if `a` is Fortran *contiguous* in memory, C-like order otherwise. ``order=None`` is an alias for ``order="C"``. + Default: ``"C"``. Returns @@ -2735,6 +2774,7 @@ def repeat(a, repeats, axis=None): axis : {None, int}, optional The axis along which to repeat values. By default, use the flattened input array, and return a flat output array. + Default: ``None``. Returns @@ -2795,8 +2835,10 @@ def require(a, dtype=None, requirements=None, *, like=None): a : {dpnp.ndarray, usm_ndarray} The input array to be converted to a type-and-requirement-satisfying array. - dtype : {None, data-type}, optional + dtype : {None, str, dtype object}, optional The required data-type. If ``None`` preserve the current dtype. + + Default: ``None``. requirements : {None, str, sequence of str}, optional The requirements list can be any of the following: @@ -2804,6 +2846,8 @@ def require(a, dtype=None, requirements=None, *, like=None): * 'C_CONTIGUOUS' ('C') - ensure a C-contiguous array * 'WRITABLE' ('W') - ensure a writable array + Default: ``None``. + Returns ------- out : dpnp.ndarray @@ -2897,11 +2941,13 @@ def reshape(a, /, shape=None, order="C", *, newshape=None, copy=None): ---------- a : {dpnp.ndarray, usm_ndarray} Array to be reshaped. - shape : int or tuple of ints + shape : {int, tuple of ints}, optional The new shape should be compatible with the original shape. If an integer, then the result will be a 1-D array of that length. One shape dimension can be -1. In this case, the value is inferred from the length of the array and remaining dimensions. + + Default: ``None``. order : {None, "C", "F", "A"}, optional Read the elements of `a` using this index order, and place the elements into the reshaped array using this index order. ``"C"`` @@ -2915,13 +2961,17 @@ def reshape(a, /, shape=None, order="C", *, newshape=None, copy=None): ``order=None`` is an alias for ``order="C"``. ``"A"`` means to read / write the elements in Fortran-like index order if ``a`` is Fortran *contiguous* in memory, C-like order otherwise. + Default: ``"C"``. newshape : int or tuple of ints Replaced by `shape` argument. Retained for backward compatibility. + + Default: ``None``. copy : {None, bool}, optional If ``True``, then the array data is copied. If ``None``, a copy will only be made if it's required by ``order``. For ``False`` it raises a ``ValueError`` if a copy cannot be avoided. + Default: ``None``. Returns @@ -3175,6 +3225,8 @@ def roll(x, shift, axis=None): array is flattened before shifting, after which the original shape is restored. + Default: ``None``. + Returns ------- out : dpnp.ndarray @@ -3238,6 +3290,8 @@ def rollaxis(x, axis, start=0): lies before this position. The default, ``0``, results in a "complete" roll. + Default: ``0``. + Returns ------- out : dpnp.ndarray @@ -3294,10 +3348,12 @@ def rot90(m, k=1, axes=(0, 1)): Array of two or more dimensions. k : integer, optional Number of times the array is rotated by 90 degrees. + Default: ``1``. axes : (2,) array_like of ints, optional The array is rotated in the plane defined by the axes. Axes must be different. + Default: ``(0, 1)``. Returns @@ -3392,7 +3448,7 @@ def shape(a): Returns ------- - shape : tuple of integers + shape : {int, tuple of ints} The elements of the shape tuple give the lengths of the corresponding array dimensions. @@ -3434,6 +3490,7 @@ def size(a, axis=None): axis : {None, int}, optional Axis along which the elements are counted. By default, give the total number of elements. + Default: ``None``. Returns @@ -3501,6 +3558,7 @@ def split(ary, indices_or_sections, axis=0): an empty sub-array is returned correspondingly. axis : int, optional The axis along which to split. + Default: ``0``. Returns @@ -3574,11 +3632,13 @@ def squeeze(a, /, axis=None): ---------- a : {dpnp.ndarray, usm_ndarray} Input data. - axis : None or int or tuple of ints, optional + axis : {None, int, tuple of ints}, optional Selects a subset of the entries of length one in the shape. If an axis is selected with shape entry greater than one, an error is raised. + Default: ``None``. + Returns ------- out : dpnp.ndarray @@ -3624,16 +3684,24 @@ def stack(arrays, /, *, axis=0, out=None, dtype=None, casting="same_kind"): Each array must have the same shape. axis : int, optional The axis in the result array along which the input arrays are stacked. + + Default: ``0``. out : dpnp.ndarray, optional If provided, the destination to place the result. The shape must be correct, matching that of what stack would have returned if no out argument were specified. - dtype : str or dtype + + Default: ``None``. + dtype : {None, str, dtype object}, optional If provided, the destination array will have this dtype. Cannot be provided together with `out`. + + Default: ``None``. casting : {'no', 'equiv', 'safe', 'same_kind', 'unsafe'}, optional Controls what kind of data casting may occur. Defaults to 'same_kind'. + Default: ``"same_kind"``. + Returns ------- out : dpnp.ndarray @@ -3852,6 +3920,7 @@ def transpose(a, axes=None): numbered ``axes[i]`` of the input. If not specified or ``None``, defaults to ``range(a.ndim)[::-1]``, which reverses the order of the axes. + Default: ``None``. Returns @@ -3920,13 +3989,15 @@ def trim_zeros(filt, trim="fb", axis=None): to the edges of a dimension, with "front" referring to the side with the lowest index 0, and "back" referring to the highest index (or index -1). + Default: ``"fb"``. axis : {None, int}, optional - If ``None``, `filt` is cropped such, that the smallest bounding box is + If ``None``, `filt` is cropped such that the smallest bounding box is returned that still contains all values which are not zero. If an `axis` is specified, `filt` will be sliced in that dimension only on the sides specified by `trim`. The remaining area will be the smallest that still contains all values which are not zero. + Default: ``None``. Returns @@ -4037,23 +4108,28 @@ def unique( return_index : bool, optional If ``True``, also return the indices of `ar` (along the specified axis, if provided, or in the flattened array) that result in the unique array. + Default: ``False``. return_inverse : bool, optional If ``True``, also return the indices of the unique array (for the specified axis, if provided) that can be used to reconstruct `ar`. + Default: ``False``. return_counts : bool, optional If ``True``, also return the number of times each unique item appears in `ar`. + Default: ``False``. axis : {int, None}, optional The axis to operate on. If ``None``, `ar` will be flattened. If an integer, the subarrays indexed by the given axis will be flattened and treated as the elements of a 1-D array with the dimension of the given axis, see the notes for more details. + Default: ``None``. equal_nan : bool, optional If ``True``, collapses multiple NaN values in the return array into one. + Default: ``True``. Returns @@ -4205,6 +4281,7 @@ def unstack(x, /, *, axis=0): The array to be unstacked. axis : int, optional Axis along which the array will be split. + Default: ``0``. Returns @@ -4353,11 +4430,15 @@ def vstack(tup, *, dtype=None, casting="same_kind"): tup : {dpnp.ndarray, usm_ndarray} The arrays must have the same shape along all but the first axis. 1-D arrays must have the same length. - dtype : str or dtype + dtype : {None, str, dtype object}, optional If provided, the destination array will have this dtype. + + Default: ``None``. casting : {'no', 'equiv', 'safe', 'same_kind', 'unsafe'}, optional Controls what kind of data casting may occur. Defaults to 'same_kind'. + Default: ``"same_kind"``. + Returns ------- out : dpnp.ndarray