dpctl.tensor Functions

Other Functions

dpctl.tensor.__array_namespace_info__()

Returns a namespace with Array API namespace inspection utilities.

dpctl.tensor.all(x, axis=None, keepdims=False)

Tests whether all input array elements evaluate to True along a given axis.

Parameters:

• x (usm_ndarray) – Input array.

• axis (Optional[Union[int, Tuple[int,...]]]) – Axis (or axes) along which to perform a logical AND reduction. When axis is None, a logical AND reduction is performed over all dimensions of x. If axis is negative, the axis is counted from the last dimension to the first. Default: None.

• keepdims (bool, optional) – If True, the reduced axes are included in the result as singleton dimensions, and the result is broadcastable to the input array shape. If False, the reduced axes are not included in the result. Default: False.

Returns:

An array with a data type of bool containing the results of the logical AND reduction.

Return type:

usm_ndarray

dpctl.tensor.allclose(a1, a2, atol=1e-8, rtol=1e-5, equal_nan=False)

Returns True if two arrays are element-wise equal within tolerances.

The testing is based on the following elementwise comparison:

abs(a - b) <= max(atol, rtol * max(abs(a), abs(b)))

dpctl.tensor.any(x, axis=None, keepdims=False)

Tests whether any input array elements evaluate to True along a given axis.

Parameters:

• x (usm_ndarray) – Input array.

• axis (Optional[Union[int, Tuple[int,...]]]) – Axis (or axes) along which to perform a logical OR reduction. When axis is None, a logical OR reduction is performed over all dimensions of x. If axis is negative, the axis is counted from the last dimension to the first. Default: None.

• keepdims (bool, optional) – If True, the reduced axes are included in the result as singleton dimensions, and the result is broadcastable to the input array shape. If False, the reduced axes are not included in the result. Default: False.

Returns:

An array with a data type of bool containing the results of the logical OR reduction.

Return type:

usm_ndarray

dpctl.tensor.argmax(x, axis=None, keepdims=False)

Returns the indices of the maximum values of the input array x along a specified axis.

When the maximum value occurs multiple times, the indices corresponding to the first occurrence are returned.

Parameters:

• x (usm_ndarray) – input array.

• axis (Optional[int]) – axis along which to search. If None, returns the index of the maximum value of the flattened array. Default: None.

• keepdims (Optional[bool]) – if True, the reduced axes (dimensions) are included in the result as singleton dimensions, so that the returned array remains compatible with the input arrays according to Array Broadcasting rules. Otherwise, if False, the reduced axes are not included in the returned array. Default: False.

Returns:

an array containing the indices of the first occurrence of the maximum values. If the entire array was searched, a zero-dimensional array is returned. The returned array has the default array index data type for the device of x.

Return type:

usm_ndarray

dpctl.tensor.argmin(x, axis=None, keepdims=False)

Returns the indices of the minimum values of the input array x along a specified axis.

When the minimum value occurs multiple times, the indices corresponding to the first occurrence are returned.

Parameters:

• x (usm_ndarray) – input array.

• axis (Optional[int]) – axis along which to search. If None, returns the index of the minimum value of the flattened array. Default: None.

• keepdims (Optional[bool]) – if True, the reduced axes (dimensions) are included in the result as singleton dimensions, so that the returned array remains compatible with the input arrays according to Array Broadcasting rules. Otherwise, if False, the reduced axes are not included in the returned array. Default: False.

Returns:

an array containing the indices of the first occurrence of the minimum values. If the entire array was searched, a zero-dimensional array is returned. The returned array has the default array index data type for the device of x.

Return type:

usm_ndarray

dpctl.tensor.clip(x, min, max, out=None, order='K')

Clips to the range [min_i, max_i] for each element x_i in x.

Parameters:

• x (usm_ndarray) – Array containing elements to clip. Must be compatible with min and max according to broadcasting rules.

• min ({None, usm_ndarray}, optional) – Array containing minimum values. Must be compatible with x and max according to broadcasting rules. Only one of min and max can be None.

• max ({None, usm_ndarray}, optional) – Array containing maximum values. Must be compatible with x and min according to broadcasting rules. Only one of min and max can be None.

• out ({None, usm_ndarray}, optional) – Output array to populate. Array must have the correct shape and the expected data type.

• order ("C","F","A","K", optional) – Memory layout of the newly output array, if parameter out is None. Default: “K”.

Returns:

An array with elements clipped to the range [min, max]. The returned array has the same data type as x.

Return type:

usm_ndarray

dpctl.tensor.extract(condition, arr)

Returns the elements of an array that satisfies the condition.

If condition is boolean dpctl.tensor.extract is equivalent to arr[condition].

Note that dpctl.tensor.place does the opposite of dpctl.tensor.extract.

Parameters:

• conditions (usm_ndarray) – An array whose non-zero or True entries indicate the element of arr to extract.

• arr (usm_ndarray) – Input array of the same size as condition.

Returns:

Rank 1 array of values from arr where condition is True.

Return type:

usm_ndarray

dpctl.tensor.get_print_options()

Returns a copy of current options for printing dpctl.tensor.usm_ndarray class.

Returns:

dictionary with array

printing option settings.

Return type:

dict

Options:

• “linewidth” : int, default 75

• “edgeitems” : int, default 3

• “threshold” : int, default 1000

• “precision” : int, default 8

• “floatmode” : str, default “maxprec_equal”

• “suppress” : bool, default False

• “nanstr” : str, default “nan”

• “infstr” : str, default “inf”

• “sign” : str, default “-”

dpctl.tensor.isdtype(dtype, kind)

Returns a boolean indicating whether a provided dtype is of a specified data type kind.

See [array API](array_api) for more information.

[array_api]: https://data-apis.org/array-api/latest/

dpctl.tensor.logsumexp(x, axis=None, dtype=None, keepdims=False)

Calculates the logarithm of the sum of exponentials of elements in the input array x.

Parameters:

• x (usm_ndarray) – input array.

• axis (Optional[int, Tuple[int, ...]]) – axis or axes along which values must be computed. If a tuple of unique integers, values are computed over multiple axes. If None, the result is computed over the entire array. Default: None.

• dtype (Optional[dtype]) –

  data type of the returned array. If None, the default data type is inferred from the “kind” of the input array data type.

  • If x has a real-valued floating-point data type, the returned array will have the default real-valued floating-point data type for the device where input array x is allocated.

  • If x has a boolean or integral data type, the returned array will have the default floating point data type for the device where input array x is allocated.

  • If x has a complex-valued floating-point data type, an error is raised.

  If the data type (either specified or resolved) differs from the data type of x, the input array elements are cast to the specified data type before computing the result. Default: None.

• keepdims (Optional[bool]) – if True, the reduced axes (dimensions) are included in the result as singleton dimensions, so that the returned array remains compatible with the input arrays according to Array Broadcasting rules. Otherwise, if False, the reduced axes are not included in the returned array. Default: False.

Returns:

an array containing the results. If the result was computed over the entire array, a zero-dimensional array is returned. The returned array has the data type as described in the dtype parameter description above.

Return type:

usm_ndarray

dpctl.tensor.matrix_transpose(x)

Transposes the innermost two dimensions of x, where x is a 2-dimensional matrix or a stack of 2-dimensional matrices.

To convert from a 1-dimensional array to a 2-dimensional column vector, use x[:, dpt.newaxis].

Parameters:

x (usm_ndarray) – Input array with shape (…, m, n).

Returns:

Array with shape (…, n, m).

Return type:

usm_ndarray

dpctl.tensor.max(x, axis=None, keepdims=False)

Calculates the maximum value of the input array x.

Parameters:

• x (usm_ndarray) – input array.

• axis (Optional[int, Tuple[int, ...]]) – axis or axes along which maxima must be computed. If a tuple of unique integers, the maxima are computed over multiple axes. If None, the max is computed over the entire array. Default: None.

• keepdims (Optional[bool]) – if True, the reduced axes (dimensions) are included in the result as singleton dimensions, so that the returned array remains compatible with the input arrays according to Array Broadcasting rules. Otherwise, if False, the reduced axes are not included in the returned array. Default: False.

Returns:

an array containing the maxima. If the max was computed over the entire array, a zero-dimensional array is returned. The returned array has the same data type as x.

Return type:

usm_ndarray

dpctl.tensor.mean(x, axis=None, keepdims=False)

Calculates the arithmetic mean of elements in the input array x.

Parameters:

• x (usm_ndarray) – input array.

• axis (Optional[int, Tuple[int, ...]]) – axis or axes along which the arithmetic means must be computed. If a tuple of unique integers, the means are computed over multiple axes. If None, the mean is computed over the entire array. Default: None.

• keepdims (Optional[bool]) – if True, the reduced axes (dimensions) are included in the result as singleton dimensions, so that the returned array remains compatible with the input array according to Array Broadcasting rules. Otherwise, if False, the reduced axes are not included in the returned array. Default: False.

Returns:

an array containing the arithmetic means. If the mean was computed over the entire array, a zero-dimensional array is returned.

If x has a floating-point data type, the returned array will have the same data type as x. If x has a boolean or integral data type, the returned array will have the default floating point data type for the device where input array x is allocated.

Return type:

usm_ndarray

dpctl.tensor.min(x, axis=None, keepdims=False)

Calculates the minimum value of the input array x.

Parameters:

• x (usm_ndarray) – input array.

• axis (Optional[int, Tuple[int, ...]]) – axis or axes along which minima must be computed. If a tuple of unique integers, the minima are computed over multiple axes. If None, the min is computed over the entire array. Default: None.

• keepdims (Optional[bool]) – if True, the reduced axes (dimensions) are included in the result as singleton dimensions, so that the returned array remains compatible with the input arrays according to Array Broadcasting rules. Otherwise, if False, the reduced axes are not included in the returned array. Default: False.

Returns:

an array containing the minima. If the min was computed over the entire array, a zero-dimensional array is returned. The returned array has the same data type as x.

Return type:

usm_ndarray

dpctl.tensor.nonzero(arr)

Return the indices of non-zero elements.

Returns the tuple of usm_narrays, one for each dimension of arr, containing the indices of the non-zero elements in that dimension. The values of arr are always tested in row-major, C-style order.

Parameters:

arr (usm_ndarray) – Input array, which has non-zero array rank.

Returns:

Indices of non-zero array elements.

Return type:

Tuple[usm_ndarray, …]

dpctl.tensor.place(arr, mask, vals)

Change elements of an array based on conditional and input values.

If mask is boolean dpctl.tensor.place is equivalent to arr[condition] = vals.

Parameters:

• arr (usm_ndarray) – Array to put data into.

• mask (usm_ndarray) – Boolean mask array. Must have the same size as arr.

• 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 elements of arr are to be masked, this sequence must be non-empty. Array vals must be one dimensional.

dpctl.tensor.print_options(*args, **kwargs)

Context manager for print options.

Set print options for the scope of a with block. as yields dictionary of print options.

dpctl.tensor.prod(x, axis=None, dtype=None, keepdims=False)

Calculates the product of elements in the input array x.

Parameters:

• x (usm_ndarray) – input array.

• axis (Optional[int, Tuple[int, ...]]) – axis or axes along which products must be computed. If a tuple of unique integers, products are computed over multiple axes. If None, the product is computed over the entire array. Default: None.

• dtype (Optional[dtype]) –

  data type of the returned array. If None, the default data type is inferred from the “kind” of the input array data type.

  • If x has a real-valued floating-point data type, the returned array will have the default real-valued floating-point data type for the device where input array x is allocated.

  • If x has signed integral data type, the returned array will have the default signed integral type for the device where input array x is allocated.

  • If x has unsigned integral data type, the returned array will have the default unsigned integral type for the device where input array x is allocated.

  • If x has a complex-valued floating-point data type, the returned array will have the default complex-valued floating-pointer data type for the device where input array x is allocated.

  • If x has a boolean data type, the returned array will have the default signed integral type for the device where input array x is allocated.

  If the data type (either specified or resolved) differs from the data type of x, the input array elements are cast to the specified data type before computing the product. Default: None.

• keepdims (Optional[bool]) – if True, the reduced axes (dimensions) are included in the result as singleton dimensions, so that the returned array remains compatible with the input arrays according to Array Broadcasting rules. Otherwise, if False, the reduced axes are not included in the returned array. Default: False.

Returns:

an array containing the products. If the product was computed over the entire array, a zero-dimensional array is returned. The returned array has the data type as described in the dtype parameter description above.

Return type:

usm_ndarray

dpctl.tensor.put(x, indices, vals, axis=None, mode='wrap')

Puts values of an array into another array along a given axis.

Parameters:

• x (usm_ndarray) – The array the values will be put into.

• 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. “wrap” - clamps indices to (-n <= i < n), then wraps negative indices. “clip” - clips indices to (0 <= i < n) Default: “wrap”.

dpctl.tensor.reduce_hypot(x, axis=None, dtype=None, keepdims=False)

Calculates the square root of the sum of squares of elements in the input array x.

Parameters:

• x (usm_ndarray) – input array.

• axis (Optional[int, Tuple[int, ...]]) – axis or axes along which values must be computed. If a tuple of unique integers, values are computed over multiple axes. If None, the result is computed over the entire array. Default: None.

• dtype (Optional[dtype]) –

  data type of the returned array. If None, the default data type is inferred from the “kind” of the input array data type.

  • If x has a real-valued floating-point data type, the returned array will have the default real-valued floating-point data type for the device where input array x is allocated.

  • If x has a boolean or integral data type, the returned array will have the default floating point data type for the device where input array x is allocated.

  • If x has a complex-valued floating-point data type, an error is raised.

  If the data type (either specified or resolved) differs from the data type of x, the input array elements are cast to the specified data type before computing the result. Default: None.

• keepdims (Optional[bool]) – if True, the reduced axes (dimensions) are included in the result as singleton dimensions, so that the returned array remains compatible with the input arrays according to Array Broadcasting rules. Otherwise, if False, the reduced axes are not included in the returned array. Default: False.

Returns:

an array containing the results. If the result was computed over the entire array, a zero-dimensional array is returned. The returned array has the data type as described in the dtype parameter description above.

Return type:

usm_ndarray

dpctl.tensor.set_print_options(linewidth=None, edgeitems=None, threshold=None, precision=None, floatmode=None, suppress=None, nanstr=None, infstr=None, sign=None, numpy=False)

set_print_options(linewidth=None, edgeitems=None, threshold=None,

precision=None, floatmode=None, suppress=None, nanstr=None, infstr=None, sign=None, numpy=False)

Set options for printing dpctl.tensor.usm_ndarray class.

Parameters:

• linewidth (int, optional) – Number of characters printed per line. Raises TypeError if linewidth is not an integer. Default: 75.

• edgeitems (int, optional) – Number of elements at the beginning and end when the printed array is abbreviated. Raises TypeError if edgeitems is not an integer. Default: 3.

• threshold (int, optional) – Number of elements that triggers array abbreviation. Raises TypeError if threshold is not an integer. Default: 1000.

• precision (int or None, optional) – Number of digits printed for floating point numbers. Raises TypeError if precision is not an integer. Default: 8.

• floatmode (str, optional) –

  Controls how floating point numbers are interpreted.

  ”fixed:: Always prints exactly precision digits. “unique”: Ignores precision, prints the number of

  digits necessary to uniquely specify each number.

  ”maxprec”: Prints precision digits or fewer,

  if fewer will uniquely represent a number.

  ”maxprec_equal”: Prints an equal number of digits

  for each number. This number is precision digits or fewer, if fewer will uniquely represent each number.

  Raises ValueError if floatmode is not one of fixed, unique, maxprec, or maxprec_equal. Default: “maxprec_equal”

• suppress (bool, optional) – If True, numbers equal to zero in the current precision will print as zero. Default: False.

• nanstr (str, optional) – String used to represent nan. Raises TypeError if nanstr is not a string. Default: “nan”.

• infstr (str, optional) – String used to represent infinity. Raises TypeError if infstr is not a string. Default: “inf”.

• sign (str, optional) –

  Controls the sign of floating point numbers. “-”: Omit the sign of positive numbers. “+”: Always print the sign of positive numbers. ” “: Always print a whitespace in place of the

  sign of positive numbers.

  Raises ValueError if sign is not one of “-”, “+”, or ” “. Default: “-”.

• numpy (bool, optional) – If True, then before other specified print options are set, a dictionary of Numpy’s print options will be used to initialize dpctl’s print options. Default: “False”

dpctl.tensor.std(x, axis=None, correction=0.0, keepdims=False)

Calculates the standard deviation of elements in the input array x.

Parameters:

• x (usm_ndarray) – input array.

• axis (Optional[int, Tuple[int, ...]]) – axis or axes along which the standard deviations must be computed. If a tuple of unique integers, the standard deviations are computed over multiple axes. If None, the standard deviation is computed over the entire array. Default: None.

• correction (Optional[float, int]) – degrees of freedom adjustment. The divisor used in calculating the standard deviation is N-correction, where N corresponds to the total number of elements over which the standard deviation is calculated. Default: 0.0.

• keepdims (Optional[bool]) – if True, the reduced axes (dimensions) are included in the result as singleton dimensions, so that the returned array remains compatible with the input array according to Array Broadcasting rules. Otherwise, if False, the reduced axes are not included in the returned array. Default: False.

Returns:

an array containing the standard deviations. If the standard deviation was computed over the entire array, a zero-dimensional array is returned.

If x has a real-valued floating-point data type, the returned array will have the same data type as x. If x has a boolean or integral data type, the returned array will have the default floating point data type for the device where input array x is allocated.

Return type:

usm_ndarray

dpctl.tensor.sum(x, axis=None, dtype=None, keepdims=False)

Calculates the sum of elements in the input array x.

Parameters:

• x (usm_ndarray) – input array.

• axis (Optional[int, Tuple[int, ...]]) – axis or axes along which sums must be computed. If a tuple of unique integers, sums are computed over multiple axes. If None, the sum is computed over the entire array. Default: None.

• dtype (Optional[dtype]) –

  data type of the returned array. If None, the default data type is inferred from the “kind” of the input array data type.

  • If x has a real-valued floating-point data type, the returned array will have the default real-valued floating-point data type for the device where input array x is allocated.

  • If x has signed integral data type, the returned array will have the default signed integral type for the device where input array x is allocated.

  • If x has unsigned integral data type, the returned array will have the default unsigned integral type for the device where input array x is allocated.

  • If x has a complex-valued floating-point data type, the returned array will have the default complex-valued floating-pointer data type for the device where input array x is allocated.

  • If x has a boolean data type, the returned array will have the default signed integral type for the device where input array x is allocated.

  If the data type (either specified or resolved) differs from the data type of x, the input array elements are cast to the specified data type before computing the sum. Default: None.

• keepdims (Optional[bool]) – if True, the reduced axes (dimensions) are included in the result as singleton dimensions, so that the returned array remains compatible with the input arrays according to Array Broadcasting rules. Otherwise, if False, the reduced axes are not included in the returned array. Default: False.

Returns:

an array containing the sums. If the sum was computed over the entire array, a zero-dimensional array is returned. The returned array has the data type as described in the dtype parameter description above.

Return type:

usm_ndarray

dpctl.tensor.take(x, indices, axis=None, mode='wrap')

Takes elements from array along a given axis.

Parameters:

• x (usm_ndarray) – The array that elements will be taken from.

• 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. “wrap” - clamps indices to (-n <= i < n), then wraps negative indices. “clip” - clips indices to (0 <= i < n) Default: “wrap”.

Returns:

Array with shape x.shape[:axis] + indices.shape + x.shape[axis + 1:] filled with elements from x.

Return type:

usm_ndarray

dpctl.tensor.usm_ndarray_repr(x, line_width=None, precision=None, suppress=None, prefix='usm_ndarray')

usm_ndarray_repr(x, line_width=None, precision=None,

suppress=None, prefix=””)

Returns a formatted string representing the elements of a dpctl.tensor.usm_ndarray and its data type, if not a default type.

Parameters:

• x (usm_ndarray) – Input array.

• line_width (int, optional) – Number of characters printed per line. Raises TypeError if line_width is not an integer. Default: 75.

• precision (int or None, optional) – Number of digits printed for floating point numbers. Raises TypeError if precision is not an integer. Default: 8.

• suppress (bool, optional) – If True, numbers equal to zero in the current precision will print as zero. Default: False.

• prefix (str, optional) – String inserted at the start of the array string. Default: “”

Returns:

formatted string representing the input array

Return type:

str

dpctl.tensor.usm_ndarray_str(x, line_width=None, edge_items=None, threshold=None, precision=None, floatmode=None, suppress=None, sign=None, numpy=False, separator=' ', prefix='', suffix='')

usm_ndarray_str(x, line_width=None, edgeitems=None, threshold=None,

precision=None, floatmode=None, suppress=None, sign=None, numpy=False, separator=” “, prefix=””, suffix=””)

Returns a string representing the elements of a dpctl.tensor.usm_ndarray.

Parameters:

• x (usm_ndarray) – Input array.

• line_width (int, optional) – Number of characters printed per line. Raises TypeError if line_width is not an integer. Default: 75.

• edgeitems (int, optional) – Number of elements at the beginning and end when the printed array is abbreviated. Raises TypeError if edgeitems is not an integer. Default: 3.

• threshold (int, optional) – Number of elements that triggers array abbreviation. Raises TypeError if threshold is not an integer. Default: 1000.

• precision (int or None, optional) – Number of digits printed for floating point numbers. Raises TypeError if precision is not an integer. Default: 8.

• floatmode (str, optional) –

  Controls how floating point numbers are interpreted.

  ”fixed:: Always prints exactly precision digits. “unique”: Ignores precision, prints the number of

  digits necessary to uniquely specify each number.

  ”maxprec”: Prints precision digits or fewer,

  if fewer will uniquely represent a number.

  ”maxprec_equal”: Prints an equal number of digits

  for each number. This number is precision digits or fewer, if fewer will uniquely represent each number.

  Raises ValueError if floatmode is not one of fixed, unique, maxprec, or maxprec_equal. Default: “maxprec_equal”

• suppress (bool, optional) – If True, numbers equal to zero in the current precision will print as zero. Default: False.

• sign (str, optional) –

  Controls the sign of floating point numbers. “-”: Omit the sign of positive numbers. “+”: Always print the sign of positive numbers. ” “: Always print a whitespace in place of the

  sign of positive numbers.

  Raises ValueError if sign is not one of “-”, “+”, or ” “. Default: “-”.

• numpy (bool, optional) – If True, then before other specified print options are set, a dictionary of Numpy’s print options will be used to initialize dpctl’s print options. Default: “False”

• separator (str, optional) – String inserted between elements of the array string. Default: ” “

• prefix (str, optional) – String used to determine spacing to the left of the array string. Default: “”

• suffix (str, optional) – String that determines length of the last line of the array string. Default: “”

Returns:

string representation of input array.

Return type:

str

dpctl.tensor.var(x, axis=None, correction=0.0, keepdims=False)

Calculates the variance of elements in the input array x.

Parameters:

• x (usm_ndarray) – input array.

• axis (Optional[int, Tuple[int, ...]]) – axis or axes along which the variances must be computed. If a tuple of unique integers, the variances are computed over multiple axes. If None, the variance is computed over the entire array. Default: None.

• correction (Optional[float, int]) – degrees of freedom adjustment. The divisor used in calculating the variance is N-correction, where N corresponds to the total number of elements over which the variance is calculated. Default: 0.0.

• keepdims (Optional[bool]) – if True, the reduced axes (dimensions) are included in the result as singleton dimensions, so that the returned array remains compatible with the input array according to Array Broadcasting rules. Otherwise, if False, the reduced axes are not included in the returned array. Default: False.

Returns:

an array containing the variances. If the variance was computed over the entire array, a zero-dimensional array is returned.

If x has a real-valued floating-point data type, the returned array will have the same data type as x. If x has a boolean or integral data type, the returned array will have the default floating point data type for the device where input array x is allocated.

Return type:

usm_ndarray

dpctl.tensor.where(condition, x1, x2)

Returns dpctl.tensor.usm_ndarray with elements chosen from x1 or x2 depending on condition.

Parameters:

• condition (usm_ndarray) – When True yields from x1, and otherwise yields from x2. Must be compatible with x1 and x2 according to broadcasting rules.

• x1 (usm_ndarray) – Array from which values are chosen when condition is True. Must be compatible with condition and x2 according to broadcasting rules.

• x2 (usm_ndarray) – Array from which values are chosen when condition is not True. Must be compatible with condition and x2 according to broadcasting rules.

Returns:

An array with elements from x1 where condition is True, and elements from x2 elsewhere.

Return type:

usm_ndarray

The data type of the returned array is determined by applying the Type Promotion Rules to x1 and x2.

The memory layout of the returned array is F-contiguous (column-major) when all inputs are F-contiguous, and C-contiguous (row-major) otherwise.

Array Construction

dpctl.tensor.arange(start, /, stop=None, step=1, *, dtype=None, device=None, usm_type='device', sycl_queue=None)

Returns evenly spaced values within the half-open interval [start, stop) as a one-dimensional array.

Parameters:

• start – Starting point of the interval

• stop – Ending point of the interval. Default: None

• step – Increment of the returned sequence. Default: 1

• dtype – Output array data type. Default: None

• 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 dpctl.SyclDevice corresponding to a non-partitioned SYCL device, an instance of dpctl.SyclQueue, or a Device object returned by dpctl.tensor.usm_array.device. Default: None.

• usm_type ("device"|"shared"|"host", optional) – The type of SYCL USM allocation for the output array. Default: ‘device’.

• sycl_queue (dpctl.SyclQueue, optional) – The SYCL queue to use for output array allocation and copying. sycl_queue and device are exclusive keywords, i.e. use one or another. If both are specified, a TypeError is raised unless both imply the same underlying SYCL queue to be used. If both are None, a cached queue targeting default-selected device is used for allocation and copying. Default: None.

Returns:

Array populated with evenly spaced values.

Return type:

usm_ndarray

dpctl.tensor.asarray(obj, dtype=None, copy=None, device=None, usm_type=None, sycl_queue=None, order='K')

Converts obj to dpctl.tensor.usm_ndarray.

Parameters:

• obj – Python object to convert. Can be an instance of dpctl.tensor.usm_ndarray, an object representing SYCL USM allocation and implementing __sycl_usm_array_interface__ protocol, an instance of numpy.ndarray, an object supporting Python buffer protocol, a Python scalar, or a (possibly nested) sequence of Python scalars.

• dtype (data type, optional) – output array data type. If dtype is None, the output array data type is inferred from data types in obj. Default: None.

• copy (bool, optional) – boolean indicating whether or not to copy the input. If True, always creates a copy. If False, need to copy raises ValueError. If None, try to reuse existing memory allocations if possible, but allowed to perform a copy otherwise. Default: None.

• order ("C","F","A","K", optional) – memory layout of the output 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 dpctl.SyclDevice corresponding to a non-partitioned SYCL device, an instance of dpctl.SyclQueue, or a Device object returned by dpctl.tensor.usm_array.device. Default: None.

• usm_type ("device"|"shared"|"host", optional) – The type of SYCL USM allocation for the output array. For usm_type=None the allocation type is inferred from the input if obj has USM allocation, or “device” is used instead. Default: None.

• sycl_queue (dpctl.SyclQueue, optional) – The SYCL queue to use for output array allocation and copying. sycl_queue and device are exclusive keywords, i.e. use one or another. If both are specified, a TypeError is raised unless both imply the same underlying SYCL queue to be used. If both are None, a cached queue targeting default-selected device is used for allocation and copying. Default: None.

Returns:

Array created from input object.

Return type:

usm_ndarray

dpctl.tensor.asnumpy(usm_ary)

Copies content of dpctl.tensor.usm_ndarray instance usm_ary into numpy.ndarray instance of the same shape and same data type.

Parameters:

usm_ary (usm_ndarray) – Input array

Returns:

An instance of numpy.ndarray populated with content of usm_ary

Return type:

numpy.ndarray

dpctl.tensor.astype(array, new_dtype, order='K', casting='unsafe', copy=True)

Returns a copy of the dpctl.tensor.usm_ndarray, cast to a specified type.

Parameters:

• array (usm_ndarray) – An input array.

• new_dtype (dtype) – The data type of the resulting array. If None, gives default floating point type supported by device where array is allocated.

• order ({"C", "F", "A", "K"}, optional) – Controls memory layout of the resulting array if a copy is returned.

• casting ({'no', 'equiv', 'safe', 'same_kind', 'unsafe'}, optional) – Controls what kind of data casting may occur. Please see numpy.ndarray.astype() for description of casting modes.

• copy (bool, optional) – By default, astype always returns a newly allocated array. If this keyword is set to False, a view of the input array may be returned when possible.

Returns:

An array with requested data type.

Return type:

usm_ndarray

A view can be returned, if possible, when copy=False is used.

dpctl.tensor.copy(ary, order='K')

Creates a copy of given instance of dpctl.tensor.usm_ndarray.

Parameters:

• ary (usm_ndarray) – Input array.

• order ({"C", "F", "A", "K"}, optional) – Controls the memory layout of the output array.

Returns:

A copy of the input array.

Return type:

usm_ndarray

Memory layout of the copy is controlled by order keyword, following NumPy’s conventions. The order keywords can be one of the following:

• “C”: C-contiguous memory layout

• “F”: Fortran-contiguous memory layout

• “A”: Fortran-contiguous if the input array is also Fortran-contiguous, otherwise C-contiguous

• “K”: match the layout of usm_ary as closely as possible.

dpctl.tensor.empty(shape, dtype=None, order='C', device=None, usm_type='device', sycl_queue=None)

Creates dpctl.tensor.usm_ndarray from uninitialized USM allocation.

Parameters:

• shape (tuple) – Dimensions of the array to be created.

• dtype (optional) – data type of the array. Can be typestring, a numpy.dtype object, numpy char string, or a numpy scalar type. The None value creates an array of floating point data type. Default: None.

• 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 dpctl.SyclDevice corresponding to a non-partitioned SYCL device, an instance of dpctl.SyclQueue, or a Device object returned by dpctl.tensor.usm_array.device. Default: None.

• usm_type ("device"|"shared"|"host", optional) – The type of SYCL USM allocation for the output array. Default: “device”.

• sycl_queue (dpctl.SyclQueue, optional) – The SYCL queue to use for output array allocation and copying. sycl_queue and device are exclusive keywords, i.e. use one or another. If both are specified, a TypeError is raised unless both imply the same underlying SYCL queue to be used. If both are None, a cached queue targeting default-selected device is used for allocation and copying. Default: None.

Returns:

Created empty array.

Return type:

usm_ndarray

dpctl.tensor.empty_like(x, dtype=None, order='C', device=None, usm_type=None, sycl_queue=None)

Returns an uninitialized dpctl.tensor.usm_ndarray with the same shape as the input array x.

Parameters:

• x (usm_ndarray) – Input array from which to derive the output array shape.

• dtype (optional) – data type of the array. Can be typestring, a numpy.dtype object, numpy char string, or a numpy scalar type. Default: None.

• 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 dpctl.SyclDevice corresponding to a non-partitioned SYCL device, an instance of dpctl.SyclQueue, or a Device object returned by dpctl.tensor.usm_array.device. Default: None.

• usm_type (“device”|”shared”|”host”|None, optional) – The type of SYCL USM allocation for the output array. If usm_type is None, the the usm_type is inferred from the input array. Default: None.

• sycl_queue (dpctl.SyclQueue, optional) – The SYCL queue to use for output array allocation and copying. sycl_queue and device are exclusive keywords, i.e. use one or another. If both are specified, a TypeError is raised unless both imply the same underlying SYCL queue to be used. If both are None, a cached queue targeting default-selected device is used for allocation and copying. Default: None.

Returns:

Created empty array with uninitialized memory.

Return type:

usm_ndarray

dpctl.tensor.eye(n_rows, n_cols=None, /, *, k=0, dtype=None, device=None, usm_type='device', sycl_queue=None)

Creates dpctl.tensor.usm_ndarray with ones on the k-th diagonal.

Parameters:

• n_rows – number of rows in the output array.

• n_cols (optional) – number of columns in the output array. If None, n_cols = n_rows. Default: None.

• k – index of the diagonal, with 0 as the main diagonal. A positive value of k is a superdiagonal, a negative value is a subdiagonal. Raises TypeError if k is not an integer. Default: 0.

• dtype (optional) – data type of the array. Can be typestring, a numpy.dtype object, numpy char string, or a numpy scalar type. Default: None.

• 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 dpctl.SyclDevice corresponding to a non-partitioned SYCL device, an instance of dpctl.SyclQueue, or a Device object returned by dpctl.tensor.usm_array.device. Default: None.

• usm_type ("device"|"shared"|"host", optional) – The type of SYCL USM allocation for the output array. Default: “device”.

• sycl_queue (dpctl.SyclQueue, optional) – The SYCL queue to use for output array allocation and copying. sycl_queue and device are exclusive keywords, i.e. use one or another. If both are specified, a TypeError is raised unless both imply the same underlying SYCL queue to be used. If both are None, a cached queue targeting default-selected device is used for allocation and copying. Default: None.

Returns:

A diagonal matrix.

Return type:

usm_ndarray

dpctl.tensor.from_numpy(arg, device=None, usm_type='device', sycl_queue=None)

Creates dpctl.tensor.usm_ndarray from instance of numpy.ndarray.

Parameters:

• arg (array-like) – An instance of input convertible to numpy.ndarray

• device (object) – array API specification of device where the output array is created. Device can be specified by a a filter selector string, an instance of dpctl.SyclDevice, an instance of dpctl.SyclQueue, an instance of dpctl.tensor.Device. If the value is None, returned array is created on the default-selected device. Default: None.

• usm_type (str) – The requested USM allocation type for the output array. Recognized values are “device”, “shared”, or “host”.

• sycl_queue (dpctl.SyclQueue, optional) – A SYCL queue that determines output array allocation device as well as execution placement of data movement operations. 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. Default: None.

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.

dpctl.tensor.full(shape, fill_value, dtype=None, order='C', device=None, usm_type=None, sycl_queue=None)

Returns a new dpctl.tensor.usm_ndarray having a specified shape and filled with fill_value.

Parameters:

• shape (tuple) – Dimensions of the array to be created.

• fill_value (int,float,complex) – fill value

• dtype (optional) – data type of the array. Can be typestring, a numpy.dtype object, numpy char string, or a numpy scalar type. Default: None.

• 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 dpctl.SyclDevice corresponding to a non-partitioned SYCL device, an instance of dpctl.SyclQueue, or a Device object returned by dpctl.tensor.usm_array.device. Default: None.

• usm_type (“device”|”shared”|”host”|None, optional) – The type of SYCL USM allocation for the output array. If usm_type is None, it is inferred from fill_value input if it is an instance of ums_ndarray, or interpreted as “device” otherwise. Default: None.

• sycl_queue (dpctl.SyclQueue, optional) – The SYCL queue to use for output array allocation and copying. sycl_queue and device are exclusive keywords, i.e. use one or another. If both are specified, a TypeError is raised unless both imply the same underlying SYCL queue to be used. If both are None, a cached queue targeting default-selected device is used for allocation and copying. Default: None.

Returns:

New array initialized with given value.

Return type:

usm_ndarray

dpctl.tensor.full_like(x, fill_value, dtype=None, order='C', device=None, usm_type=None, sycl_queue=None)

Returns a new dpctl.tensor.usm_ndarray filled with fill_value and having the same shape as the input array x.

Parameters:

• x (usm_ndarray) – Input array from which to derive the output array shape.

• fill_value – the value to fill output array with

• dtype (optional) – data type of the array. Can be typestring, a numpy.dtype object, 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”.

• 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 dpctl.SyclDevice corresponding to a non-partitioned SYCL device, an instance of dpctl.SyclQueue, or a Device object returned by dpctl.tensor.usm_array.device. Default: None.

• usm_type (“device”|”shared”|”host”|None, optional) – The type of SYCL USM allocation for the output array. If None, output array has the same USM allocation type as the input array x. Default: None.

• sycl_queue (dpctl.SyclQueue, optional) – The SYCL queue to use for output array allocation and copying. sycl_queue and device are exclusive keywords, i.e. use one or another. If both are specified, a TypeError is raised unless both imply the same underlying SYCL queue to be used. If both are None, a cached queue targeting default-selected device is used for allocation and copying. Default: None.

Returns:

New array initialized with given value.

Return type:

usm_ndarray

dpctl.tensor.linspace(start, stop, num, dtype=None, device=None, endpoint=True, sycl_queue=None, usm_type='device')

Returns dpctl.tensor.usm_ndarray array populated with evenly spaced numbers of specified interval.

Parameters:

• start – the start of the interval.

• stop – the end of the interval. If the endpoint is False, the function must generate num+1 evenly spaced points starting with start and ending with stop and exclude the stop from the returned array such that the returned array consists of evenly spaced numbers over the half-open interval [start, stop). If endpoint is True, the output array must consist of evenly spaced numbers over the closed interval [start, stop]. Default: True.

• num – number of samples. Must be a non-negative integer; otherwise, the function raises ValueError exception.

• dtype – output array data type. Should be a floating data type. If dtype is None, the output array must be the default floating point data type. Default: None.

• 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 dpctl.SyclDevice corresponding to a non-partitioned SYCL device, an instance of dpctl.SyclQueue, or a Device object returned by dpctl.tensor.usm_array.device. Default: None.

• usm_type ("device"|"shared"|"host", optional) – The type of SYCL USM allocation for the output array. Default: “device”.

• sycl_queue (dpctl.SyclQueue, optional) – The SYCL queue to use for output array allocation and copying. sycl_queue and device are exclusive keywords, i.e. use one or another. If both are specified, a TypeError is raised unless both imply the same underlying SYCL queue to be used. If both are None, a cached queue targeting default-selected device is used for allocation and copying. Default: None.

• endpoint – boolean indicating whether to include stop in the interval. Default: True.

Returns:

Array populated with evenly spaced numbers in the requested interval.

Return type:

usm_ndarray

dpctl.tensor.meshgrid(*arrays, indexing='xy')

Creates list of dpctl.tensor.usm_ndarray coordinate matrices from vectors.

Parameters:

• arrays (usm_ndarray) – an arbitrary number of one-dimensional arrays representing grid coordinates. Each array should have the same numeric data type.

• indexing – Cartesian (xy) or matrix (ij) indexing of output. If provided zero or one one-dimensional vector(s) (i.e., the zero- and one-dimensional cases, respectively), the indexing keyword has no effect and should be ignored. Default: xy.

Returns:

list of N arrays, where N is the number of

provided one-dimensional input arrays. Each returned array must have rank N. For a set of n vectors with lengths N0, N1, N2, … The cartesian indexing results in arrays of shape (N1, N0, N2, …), while the matrix indexing results in arrays of shape (N0, N1, N2, …). Default: xy.

Return type:

List[array]

Raises:

ValueError – If vectors are not of the same data type, or are not one-dimensional.

dpctl.tensor.ones(shape, dtype=None, order='C', device=None, usm_type='device', sycl_queue=None)

Returns a new dpctl.tensor.usm_ndarray having a specified shape and filled with ones.

Parameters:

• shape (tuple) – Dimensions of the array to be created.

• dtype (optional) – data type of the array. Can be typestring, a numpy.dtype object, numpy char string, or a numpy scalar type. Default: None.

• 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 dpctl.SyclDevice corresponding to a non-partitioned SYCL device, an instance of dpctl.SyclQueue, or a Device object returned by dpctl.tensor.usm_array.device. Default: None.

• usm_type ("device"|"shared"|"host", optional) – The type of SYCL USM allocation for the output array. Default: “device”.

• sycl_queue (dpctl.SyclQueue, optional) – The SYCL queue to use for output array allocation and copying. sycl_queue and device are exclusive keywords, i.e. use one or another. If both are specified, a TypeError is raised unless both imply the same underlying SYCL queue to be used. If both are None, a cached queue targeting default-selected device is used for allocation and copying. Default: None.

Returns:

Created array initialized with ones.

Return type:

usm_ndarray

dpctl.tensor.ones_like(x, dtype=None, order='C', device=None, usm_type=None, sycl_queue=None)

Returns a new dpctl.tensor.usm_ndarray filled with ones and having the same shape as the input array x.

Parameters:

• x (usm_ndarray) – Input array from which to derive the output array shape.

• dtype (optional) – data type of the array. Can be typestring, a numpy.dtype object, numpy char string, or a numpy scalar type. Default: None.

• 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 dpctl.SyclDevice corresponding to a non-partitioned SYCL device, an instance of dpctl.SyclQueue, or a Device object returned by dpctl.tensor.usm_array.device. Default: None.

• usm_type (“device”|”shared”|”host”|None, optional) – The type of SYCL USM allocation for the output array. If None, output array has the same USM allocation type as the input array. Default: None.

• sycl_queue (dpctl.SyclQueue, optional) – The SYCL queue to use for output array allocation and copying. sycl_queue and device are exclusive keywords, i.e. use one or another. If both are specified, a TypeError is raised unless both imply the same underlying SYCL queue to be used. If both are None, a cached queue targeting default-selected device is used for allocation and copying. Default: None.

Returns:

New array initialized with ones.

Return type:

usm_ndarray

dpctl.tensor.to_numpy(usm_ary)

Copies content of dpctl.tensor.usm_ndarray instance usm_ary into numpy.ndarray instance of the same shape and same data type.

Parameters:

usm_ary (usm_ndarray) – Input array

Returns:

An instance of numpy.ndarray populated with content of usm_ary

Return type:

numpy.ndarray

dpctl.tensor.tril(x, k=0)

Returns the lower triangular part of a matrix (or a stack of matrices) x.

The lower triangular part of the matrix is defined as the elements on and below the specified diagonal k.

Parameters:

• x (usm_ndarray) – Input array.

• k (int, optional) – Specifies the diagonal above which to set elements to zero. If k = 0, the diagonal is the main diagonal. If k < 0, the diagonal is below the main diagonal. If k > 0, the diagonal is above the main diagonal. Default: 0.

Returns:

A lower-triangular array or a stack of lower-triangular arrays.

Return type:

usm_ndarray

dpctl.tensor.triu(x, k=0)

Returns the upper triangular part of a matrix (or a stack of matrices) x.

The upper triangular part of the matrix is defined as the elements on and above the specified diagonal k.

Parameters:

• x (usm_ndarray) – Input array.

• k (int, optional) – Specifies the diagonal below which to set elements to zero. If k = 0, the diagonal is the main diagonal. If k < 0, the diagonal is below the main diagonal. If k > 0, the diagonal is above the main diagonal. Default: 0.

Returns:

An upper-triangular array or a stack of upper-triangular arrays.

Return type:

usm_ndarray

dpctl.tensor.zeros(shape, dtype=None, order='C', device=None, usm_type='device', sycl_queue=None)

Returns a new dpctl.tensor.usm_ndarray having a specified shape and filled with zeros.

Parameters:

• shape (tuple) – Dimensions of the array to be created.

• dtype (optional) – data type of the array. Can be typestring, a numpy.dtype object, numpy char string, or a numpy scalar type. Default: None.

• 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 dpctl.SyclDevice corresponding to a non-partitioned SYCL device, an instance of dpctl.SyclQueue, or a Device object returned by dpctl.tensor.usm_array.device. Default: None.

• usm_type ("device"|"shared"|"host", optional) – The type of SYCL USM allocation for the output array. Default: “device”.

• sycl_queue (dpctl.SyclQueue, optional) – The SYCL queue to use for output array allocation and copying. sycl_queue and device are exclusive keywords, i.e. use one or another. If both are specified, a TypeError is raised unless both imply the same underlying SYCL queue to be used. If both are None, a cached queue targeting default-selected device is used for allocation and copying. Default: None.

Returns:

Constructed array initialized with zeros.

Return type:

usm_ndarray

dpctl.tensor.zeros_like(x, dtype=None, order='C', device=None, usm_type=None, sycl_queue=None)

Creates dpctl.tensor.usm_ndarray from USM allocation initialized with zeros.

Parameters:

• x (usm_ndarray) – Input array from which to derive the shape of the output array.

• dtype (optional) – data type of the array. Can be typestring, a numpy.dtype object, 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") – 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 dpctl.SyclDevice corresponding to a non-partitioned SYCL device, an instance of dpctl.SyclQueue, or a Device object returned by dpctl.tensor.usm_array.device. Default: None.

• usm_type (“device”|”shared”|”host”|None, optional) – The type of SYCL USM allocation for the output array. If None, output array has the same USM allocation type as the input array. Default: None.

• sycl_queue (dpctl.SyclQueue, optional) – The SYCL queue to use for output array allocation and copying. sycl_queue and device are exclusive keywords, i.e. use one or another. If both are specified, a TypeError is raised unless both imply the same underlying SYCL queue to be used. If both are None, a cached queue targeting default-selected device is used for allocation and copying. Default: None.

Returns:

New array initialized with zeros.

Return type:

usm_ndarray

Array Manipulation

dpctl.tensor.broadcast_arrays(*arrays)

Broadcasts one or more dpctl.tensor.usm_ndarrays against one another.

Parameters:

arrays (usm_ndarray) – an arbitrary number of arrays to be broadcasted.

Returns:

A list of broadcasted arrays. Each array must have the same shape. Each array must have the same dtype, device and usm_type attributes as its corresponding input array.

Return type:

List[usm_ndarray]

dpctl.tensor.broadcast_to(x, shape)

Broadcast an array to a new shape; returns the broadcasted dpctl.tensor.usm_ndarray as a view.

Parameters:

• x (usm_ndarray) – input array

• shape (Tuple[int,...]) – array shape. The shape must be compatible with x according to broadcasting rules.

Returns:

An array with the specified shape. The output array is a view of the input array, and hence has the same data type, USM allocation type and device attributes.

Return type:

usm_ndarray

dpctl.tensor.can_cast(from, to, casting="safe")

Determines if one data type can be cast to another data type according to Type Promotion Rules.

Parameters:

• from (usm_ndarray, dtype) – source data type

• to (dtype) – target data type

• casting ({'no', 'equiv', 'safe', 'same_kind', 'unsafe'}, optional) – controls what kind of data casting may occur.

Returns:

Gives True if cast can occur according to the casting rule.

Return type:

bool

dpctl.tensor.concat(arrays, axis)

Joins a sequence of arrays along an existing axis.

Parameters:

• arrays (Union[List[usm_ndarray, Tuple[usm_ndarray,...]]]) – input arrays to join. The arrays must have the same shape, except in the dimension specified by axis.

• axis (Optional[int]) – axis along which the arrays will be joined. If axis is None, arrays must be flattened before concatenation. If axis is negative, it is understood as being counted from the last dimension. Default: 0.

Returns:

An output array containing the concatenated values. The output array data type is determined by Type Promotion Rules of array API.

Return type:

usm_ndarray

All input arrays must have the same device attribute. The output array is allocated on that same device, and data movement operations are scheduled on a queue underlying the device. The USM allocation type of the output array is determined by USM allocation type promotion rules.

dpctl.tensor.expand_dims(x, axis)

Expands the shape of an array by inserting a new axis (dimension) of size one at the position specified by axis.

Parameters:

• x (usm_ndarray) – input array

• axis (int) – axis position (zero-based). If x has rank (i.e, number of dimensions) N, a valid axis must reside in the closed-interval [-N-1, N]. If provided a negative axis, the axis position at which to insert a singleton dimension is computed as N + axis + 1. Hence, if provided -1, the resolved axis position is N (i.e., a singleton dimension must be appended to the input array x). If provided -N-1, the resolved axis position is 0 (i.e., a singleton dimension is prepended to the input array x).

Returns:

Returns a view, if possible, and a copy otherwise with the number of dimensions increased. The expanded array has the same data type as the input array x. The expanded array is located on the same device as the input array, and has the same USM allocation type.

Return type:

usm_ndarray

Raises:

IndexError – if axis value is invalid.

dpctl.tensor.finfo(type)

Returns machine limits for floating-point data types.

Parameters:

dtype (dtype, usm_ndarray) – floating-point dtype or an array with floating point data type. If complex, the information is about its component data type.

Returns:

an object have the following attributes

• bits: int

  number of bits occupied by dtype.

• eps: float

  difference between 1.0 and the next smallest representable real-valued floating-point number larger than 1.0 according to the IEEE-754 standard.

• max: float

  largest representable real-valued number.

• min: float

  smallest representable real-valued number.

• smallest_normal: float

  smallest positive real-valued floating-point number with full precision.

• dtype: dtype

  real-valued floating-point data type.

Return type:

finfo_object

dpctl.tensor.flip(x, axis)

Reverses the order of elements in an array x along the given axis. The shape of the array is preserved, but the elements are reordered.

Parameters:

• x (usm_ndarray) – input array.

• axis (Optional[Union[int, Tuple[int,...]]]) – axis (or axes) along which to flip. If axis is None, all input array axes are flipped. If axis is negative, the flipped axis is counted from the last dimension. If provided more than one axis, only the specified axes are flipped. Default: None.

Returns:

A view of x with the entries of axis reversed.

Return type:

usm_ndarray

dpctl.tensor.iinfo(dtype)

Returns machine limits for integer data types.

Parameters:

dtype (dtype, usm_ndarray) – integer dtype or an array with integer dtype.

Returns:

An object with the following attributes * bits: int

number of bits occupied by the data type

• max: int

  largest representable number.

• min: int

  smallest representable number.

• dtype: dtype

  integer data type.

Return type:

iinfo_object

dpctl.tensor.moveaxis(x, source, destination)

Moves axes of an array to new positions.

Parameters:

• x (usm_ndarray) – input array

• source (int or a sequence of int) – Original positions of the axes to move. These must be unique. If x has rank (i.e., number of dimensions) N, a valid axis must be in the half-open interval [-N, N).

• destination (int or a sequence of int) – Destination positions for each of the original axes. These must also be unique. If x has rank (i.e., number of dimensions) N, a valid axis must be in the half-open interval [-N, N).

Returns:

Array with moved axes. The returned array must has the same data type as x, is created on the same device as x and has the same USM allocation type as x.

Return type:

usm_narray

Raises:

• AxisError – if axis value is invalid.

• ValueError – if src and dst have not equal number of elements.

dpctl.tensor.permute_dims(x, axes)

Permute the axes (dimensions) of an array; returns the permuted array as a view.

Parameters:

• x (usm_ndarray) – input array.

• axes (Tuple[int, ...]) – tuple containing permutation of (0,1,…,N-1) where N is the number of axes (dimensions) of x.

Returns:

An array with permuted axes. The returned array must has the same data type as x, is created on the same device as x and has the same USM allocation type as x.

Return type:

usm_narray

dpctl.tensor.repeat(x, repeats, axis=None)

Repeat elements of an array.

Parameters:

• x (usm_ndarray) – input array

• repeats (Union[int, Sequence[int, ...], usm_ndarray]) – The number of repetitions for each element. repeats is broadcast to fit the shape of the given axis. If repeats is an array, it must have an integer data type. Otherwise, repeats must be a Python integer, tuple, list, or range.

• axis (Optional[int]) – The axis along which to repeat values. If axis is None, the function repeats elements of the flattened array. Default: None.

Returns:

Array with repeated elements. The returned array must have the same data type as x, is created on the same device as x and has the same USM allocation type as x. If axis is None, the returned array is one-dimensional, otherwise, it has the same shape as x, except for the axis along which elements were repeated.

Return type:

usm_narray

Raises:

AxisError – if axis value is invalid.

dpctl.tensor.reshape(x, shape, order='C')

Reshapes array x into new shape.

Parameters:

• x (usm_ndarray) – input array

• shape (tuple) – the desired shape of the resulting array.

• order ({"C", "F"}, optional) – memory layout of the resulting array if a copy is found to be necessary. Supported choices are “C” for C-contiguous, or row-major layout; and “F” for F-contiguous, or column-major layout.

Returns:

Reshaped array is a view, if possible, and a copy otherwise with memory layout as indicated by order keyword.

Return type:

usm_ndarray

dpctl.tensor.result_type(arrays_and_dtypes)

Returns the dtype that results from applying the Type Promotion Rules to the arguments.

Parameters:

arrays_and_dtypes (object) – An arbitrary length sequence of arrays or dtypes.

Returns:

The dtype resulting from an operation involving the input arrays and dtypes.

Return type:

dtype

dpctl.tensor.roll(x, shift, axis)

Rolls array elements along a specified axis. Array elements that roll beyond the last position are re-introduced at the first position. Array elements that roll beyond the first position are re-introduced at the last position.

Parameters:

• x (usm_ndarray) – input array

• shift (Union[int, Tuple[int,...]]) – number of places by which the elements are shifted. If shift is a tuple, then axis must be a tuple of the same size, and each of the given axes must be shifted by the corresponding element in shift. If shift is an int and axis a tuple, then the same shift must be used for all specified axes. If a shift is positive, then array elements is shifted positively (toward larger indices) along the dimension of axis. If a shift is negative, then array elements must be shifted negatively (toward smaller indices) along the dimension of axis.

• axis (Optional[Union[int, Tuple[int,...]]]) – axis (or axes) along which elements to shift. If axis is None, the array is flattened, shifted, and then restored to its original shape. Default: None.

Returns:

An array having the same dtype, usm_type and device attributes as x and whose elements are shifted relative to x.

Return type:

usm_ndarray

dpctl.tensor.squeeze(x, axis)

Removes singleton dimensions (axes) from array x.

Parameters:

• x (usm_ndarray) – input array

• axis (Union[int, Tuple[int,...]]) – axis (or axes) to squeeze.

Returns:

Output array is a view, if possible, and a copy otherwise, but with all or a subset of the dimensions of length 1 removed. Output has the same data type as the input, is allocated on the same device as the input and has the same USM allocation type as the input array x.

Return type:

usm_ndarray

Raises:

ValueError – if the specified axis has a size greater than one.

dpctl.tensor.stack(arrays, axis)

Joins a sequence of arrays along a new axis.

Parameters:

• arrays (Union[List[usm_ndarray], Tuple[usm_ndarray,...]]) – input arrays to join. Each array must have the same shape.

• axis (int) – axis along which the arrays will be joined. Providing an axis specified the index of the new axis in the dimensions of the output array. A valid axis must be on the interval [-N, N), where N is the rank (number of dimensions) of x. Default: 0.

Returns:

An output array having rank N+1, where N is the rank (number of dimensions) of x. If the input arrays have different data types, array API Type Promotion Rules apply.

Return type:

usm_ndarray

Raises:

• ValueError – if not all input arrays have the same shape

• IndexError – if provided an axis outside of the required interval.

dpctl.tensor.swapaxes(x, axis1, axis2)

Interchanges two axes of an array.

Parameters:

• x (usm_ndarray) – input array

• axis1 (int) – First axis. If x has rank (i.e., number of dimensions) N, a valid axis must be in the half-open interval [-N, N).

• axis2 (int) – Second axis. If x has rank (i.e., number of dimensions) N, a valid axis must be in the half-open interval [-N, N).

Returns:

Array with swapped axes. The returned array must has the same data type as x, is created on the same device as x and has the same USM allocation type as x.

Return type:

usm_narray

Raises:

AxisError – if axis value is invalid.

dpctl.tensor.tile(x, repetitions)

Repeat an input array x along each axis a number of times given by repetitions.

For N = len(repetitions) and M = len(x.shape): - if M < N, x will have N - M new axes prepended to its shape - if M > N, repetitions will have M - N new axes 1 prepended to it

Parameters:

• x (usm_ndarray) – input array

• repetitions (Union[int, Tuple[int, ...]]) – The number of repetitions for each dimension.

Returns:

Array with tiled elements. The returned array must have the same data type as x, is created on the same device as x and has the same USM allocation type as x.

Return type:

usm_narray

dpctl.tensor.unstack(x, axis=0)

Splits an array in a sequence of arrays along the given axis.

Parameters:

• x (usm_ndarray) – input array

• axis (int, optional) – axis along which x is unstacked. If x has rank (i.e, number of dimensions) N, a valid axis must reside in the half-open interval [-N, N). Default: 0.

Returns:

Output sequence of arrays which are views into the input array.

Return type:

Tuple[usm_ndarray,…]

Raises:

AxisError – if the axis value is invalid.