General

Collection of general Ivy functions.

ivy.abs(x: ivy.NativeArray, f: Optional[ivy.Framework] = None) → ivy.NativeArray[source]

Returns the absolute value of each element in x.

Parameters
  • x (array) – Input array containing elements to absolute value.

  • f (ml_framework, optional) – Machine learning framework. Inferred from inputs if None.

Returns

A new array of the same shape as input array a, with all values now positive.

ivy.arange(stop: numbers.Number, start: numbers.Number = 0, step: numbers.Number = 1, dtype_str: Optional[str] = None, dev_str: Optional[str] = None, f: Optional[ivy.Framework] = None) → ivy.NativeArray[source]

Returns evenly spaced values within a given interval, with the spacing being specified.

Values are generated within the half-open interval [start, stop) (in other words, the interval including start but excluding stop). For integer arguments the function is equivalent to the Python built-in range function, but returns an array in the chosen ml_framework rather than a list.

See \(linspace\) for a certain number of evenly spaced values in an interval.

Parameters
  • stop (number) – End of interval. The interval does not include this value, except in some cases where step is not an integer and floating point round-off affects the length of out.

  • start (number, optional) – Start of interval. The interval includes this value. The default start value is 0.

  • step (number, optional) – Spacing between values. For any output out, this is the distance between two adjacent values, out[i+1] - out[i]. The default step size is 1. If step is specified as a position argument, start must also be given.

  • dtype_str (data-type string, optional) – The desired data-type for the array in string format, i.e. ‘float32’ or ‘int64’. If not given, then the type will be determined as the minimum type required to hold the objects in the sequence.

  • dev_str (str) – device on which to create the array ‘cuda:0’, ‘cuda:1’, ‘cpu’ etc.

  • f (ml_framework, optional) – Machine learning framework. Inferred from inputs if None.

Returns

Tensor of evenly spaced values.

For floating point arguments, the length of the result is ceil((stop - start)/step). Because of floating point overflow, this rule may result in the last element of out being greater than stop.

ivy.argmax(x: ivy.NativeArray, axis: int = 0, f: Optional[ivy.Framework] = None) → ivy.NativeArray[source]

Returns the index with the largest value across axes of an array.

Parameters
  • x (array) – Input array containing elements to argmax.

  • axis (int, optional) – Axis to perform the argmax, default is 0.

  • f (ml_framework, optional) – Machine learning framework. Inferred from inputs if None.

Returns

Tensor containing the indices of the maximum values across the specified axis.

ivy.argmin(x: ivy.NativeArray, axis: int = 0, f: Optional[ivy.Framework] = None) → ivy.NativeArray[source]

Returns the index with the smallest value across axes of an array.

Parameters
  • x (array) – Input array containing elements to argmin.

  • axis (int, optional) – Axis to perform the argmin, default is 0.

  • f (ml_framework, optional) – Machine learning framework. Inferred from inputs if None.

Returns

Tensor containing the indices of the minimum values across the specified axis.

ivy.args_to_ivy(*args: List[Any], **kwargs: Dict[str, Any]) → Tuple[List[Any], Dict[str, Any]][source]

Returns args and keyword args in their ivy.Array or ivy.Variable form for all nested instances, otherwise the arguments are returned unchanged.

Parameters
  • args (sequence of arguments) – The positional arguments to check

  • kwargs (dict of arguments) – The key-word arguments to check

Returns

the same arguments, with any nested arrays converted to ivy.Array or ivy.Variable instances.

ivy.args_to_native(*args: List[Any], **kwargs: Dict[str, Any]) → Tuple[List[Any], Dict[str, Any]][source]

Returns args and keyword args in their native backend framework form for all nested ivy.Array or ivy.Variable instances, otherwise the arguments are returned unchanged.

Parameters
  • args (sequence of arguments) – The positional arguments to check

  • kwargs (dict of arguments) – The key-word arguments to check

Returns

the same arguments, with any nested ivy.Array or ivy.Variable instances converted to their native form.

ivy.argsort(x: ivy.NativeArray, axis: int = - 1, f: Optional[ivy.Framework] = None) → ivy.NativeArray[source]

Returns the indices of a tensor that give its sorted order along an axis.

Parameters
  • x (array) – Input array containing elements to argsort.

  • axis (int, optional) – Axis to perform the argsort, default is -1.

  • f (ml_framework, optional) – Machine learning framework. Inferred from inputs if None.

Returns

The indices that would sort each slice of the given values along the given axis.

ivy.array(object_in: Union[List, numpy.ndarray, ivy.NativeArray], dtype_str: Optional[str] = None, dev_str: Optional[str] = None, f: Optional[ivy.Framework] = None) → ivy.NativeArray[source]

Creates an array.

Parameters
  • object_in (array) – An array_like object, which exposes the array interface, an object whose __array__ method returns an array, or any (nested) sequence.

  • dtype_str (data-type string, optional) – The desired data-type for the array in string format, i.e. ‘float32’ or ‘int64’. If not given, then the type will be determined as the minimum type required to hold the objects in the sequence.

  • dev_str (str) – device string on which to create the array ‘cuda:0’, ‘cuda:1’, ‘cpu’ etc..

  • f (ml_framework, optional) – Machine learning framework. Inferred from inputs if None.

Returns

An array object satisfying the specified requirements, in the form of the selected framework.

ivy.array_equal(x0: ivy.NativeArray, x1: ivy.NativeArray, f: Optional[ivy.Framework] = None) → bool[source]

Determines whether two input arrays are equal across all elements.

Parameters
  • x0 (array) – The first input array to compare.

  • x1 (array) – The second input array to compare.

  • f (ml_framework, optional) – Machine learning framework. Inferred from inputs if None.

Returns

Boolean, whether or not the input arrays are equal across all elements.

ivy.broadcast_to(x: ivy.NativeArray, newshape: List[int], f: Optional[ivy.Framework] = None) → ivy.NativeArray[source]

Broadcast the input tensor to newshape, adding dimensions of size 1 where the dimensions do not align.

Parameters
  • x (array) – Tensor to be broadcast to new shape.

  • newshape (sequence of ints) – The new shape the tensor should be broadcast to.

  • f (ml_framework, optional) – Machine learning framework. Inferred from inputs if None.

Returns

Newly broadcast array.

ivy.cache_fn(func: Callable) → Callable[source]

Wrap a function, such that when cache=True is passed as an argument, a previously cached output is returned.

Parameters

func (callable) – The function to wrap, whose output should be cached for later.

Returns

The newly cache wrapped function.

ivy.cast(x: ivy.NativeArray, dtype_str: str, f: Optional[ivy.Framework] = None) → ivy.NativeArray[source]

Casts an array to a specified type.

Parameters
  • x (array) – Input array containing elements to cast.

  • dtype_str (data-type string) – The desired data-type for the array in string format, i.e. ‘float32’ or ‘int64’. If not given, then the type will be determined as the minimum type required to hold the objects in the sequence.

  • f (ml_framework, optional) – Machine learning framework. Inferred from inputs if None.

Returns

A new array of the same shape as input array a, with data type given by dtype_str.

ivy.ceil(x: ivy.NativeArray, f: Optional[ivy.Framework] = None) → ivy.NativeArray[source]

Returns element-wise smallest integer not less than x.

Parameters
  • x (array) – Input array to ceil.

  • f (ml_framework, optional) – Machine learning framework. Inferred from inputs if None.

Returns

An array of the same shape and type as x, with the elements ceiled to integers.

ivy.clip(x: ivy.NativeArray, x_min: Union[numbers.Number, ivy.NativeArray], x_max: Union[numbers.Number, ivy.NativeArray], f: Optional[ivy.Framework] = None) → ivy.NativeArray[source]

Clips (limits) the values in an array.

Given an interval, values outside the interval are clipped to the interval edges (element-wise). For example, if an interval of [0, 1] is specified, values smaller than 0 become 0, and values larger than 1 become 1.

Parameters
  • x (array) – Input array containing elements to clip.

  • x_min (scalar or array) – Minimum value.

  • x_max (scalar or array) – Maximum value.

  • f (ml_framework, optional) – Machine learning framework. Inferred from inputs if None.

Returns

An array with the elements of x, but where values < x_min are replaced with x_min, and those > x_max with x_max.

ivy.clip_matrix_norm(x: ivy.NativeArray, max_norm: float, p: float = 2.0) → ivy.NativeArray[source]

Clips (limits) the matrix norm of an array.

Parameters
  • x (array) – Input array containing elements to clip.

  • max_norm (float) – The maximum value of the array norm.

  • p (float, optional) – The p-value for computing the p-norm. Default is 2.

Returns

An array with the matrix norm downscaled to the max norm if needed.

ivy.clip_vector_norm(x: ivy.NativeArray, max_norm: float, p: float = 2.0) → ivy.NativeArray[source]

Clips (limits) the vector p-norm of an array.

Parameters
  • x (array) – Input array containing elements to clip.

  • max_norm (float) – The maximum value of the array norm.

  • p (float, optional) – The p-value for computing the p-norm. Default is 2.

Returns

An array with the vector norm downscaled to the max norm if needed.

ivy.compile_fn(func: Callable, dynamic: bool = True, example_inputs: Optional[Union[Any, Tuple[Any]]] = None, f: Optional[ivy.Framework] = None) → Callable[source]

Provide a function which should be compiled, for faster inference. The handle to the newly compiled function is returned.

Parameters
  • func (callable) – Function to be compiled.

  • dynamic (bool, default True) – Whether to compile all conditional branches, regardless of inputs during first invocation.

  • example_inputs (single input or tuple of inputs.) – Example of inputs to the function to be compiled. Required for torch in non-dynamic mode, unused by other frameworks.

  • f (ml_framework, optional) – Machine learning framework. Inferred from inputs if None.

Returns

The handle to the newly compiled function.

ivy.concatenate(xs: List[ivy.NativeArray], axis: int = - 1, f: Optional[ivy.Framework] = None) → ivy.NativeArray[source]

Casts an array to a specified type.

Parameters
  • xs (sequence of arrays) – The input arrays must have the same shape, except in the dimension corresponding to axis (the first, by default).

  • axis (int, optional) – The axis along which the arrays will be joined. Default is -1.

  • f (ml_framework, optional) – Machine learning framework. Inferred from inputs if None.

Returns

The concatenated array.

ivy.constant_pad(x: ivy.NativeArray, pad_width: List[Tuple[int]], value: numbers.Number = 0, f: Optional[ivy.Framework] = None) → ivy.NativeArray[source]

Pads an array with a constant value.

Parameters
  • x (array) – Input array to pad.

  • pad_width (sequence of tuples of ints) – Number of values padded to the edges of each axis. Specified as ((before_1, after_1), … (before_N, after_N)), where N is number of axes of x.

  • value (float or int, default zero) – The constant value to pad the array with.

  • f (ml_framework, optional) – Machine learning framework. Inferred from inputs if None.

Returns

Padded array of rank equal to x with shape increased according to pad_width.

ivy.cross(x1: ivy.NativeArray, x2: ivy.NativeArray, f: Optional[ivy.Framework] = None) → ivy.NativeArray[source]

Returns the cross product of two (arrays of) vectors in R^3. The cross product of x1 and x2 in R^3 is a vector perpendicular to both x1 and x2. If x1 and x2 are arrays of vectors, the vectors are defined by the last axis of x1 and x2 by default which must have dimension 3.

Parameters
  • x1 (array) – Components of the first vector(s).

  • x2 (array) – Components of the second vector(s).

  • f (ml_framework, optional) – Machine learning framework. Inferred from inputs if None.

Returns

Vector cross product(s).

ivy.cumprod(x: ivy.NativeArray, axis: int = 0, exclusive: bool = False, f: Optional[ivy.Framework] = None) → ivy.NativeArray[source]

Returns the cumulative product of the elements along a given axis.

Parameters
  • x (array) – Input array.

  • axis (int) – Axis along which the cumulative product is computed. By default 0.

  • exclusive (bool, optional) – Whether to perform the cumprod exclusively. Defaults is False.

  • f (ml_framework, optional) – Machine learning framework. Inferred from inputs if None.

Returns

Input array with cumulatively multiplied elements along axis.

ivy.cumsum(x: ivy.NativeArray, axis: int = 0, f: Optional[ivy.Framework] = None) → ivy.NativeArray[source]

Returns the cumulative sum of the elements along a given axis.

Parameters
  • x (array) – Input array.

  • axis (int) – Axis along which the cumulative sum is computed. By default 0.

  • f (ml_framework, optional) – Machine learning framework. Inferred from inputs if None.

Returns

Input array with cumulatively summed elements along axis.

ivy.current_framework_str(f: Optional[ivy.Framework] = None) → Optional[str][source]

Return the string of the current globally set framework. Returns None if no framework is set.

Parameters

f (ml_framework, optional) – Machine learning framework. Inferred from inputs if None.

Returns

The framework string.

ivy.default(x: Any, default_val: Any, catch_exceptions: bool = False, rev: bool = False) → Any[source]

Returns x provided it exists (is not None), else returns default value.

Parameters
  • x (value if catch_exceptions=False else callable) – Input which may or may not exist (be None).

  • default_val (any) – The default value.

  • catch_exceptions (bool, optional) – Whether to catch exceptions from callable x. Default is False.

  • rev (bool, optional) – Whether to reverse the input x and default_val. Default is False.

Returns

x if x exists (is not None), else default.

ivy.dev(x: ivy.NativeArray, f: Optional[ivy.Framework] = None) → ivy.Device[source]

Get the native device handle for input array x.

Parameters
  • x (array) – Tensor for which to get the device handle.

  • f (ml_framework, optional) – Machine learning framework. Inferred from inputs if None.

Returns

Device handle for the array, in native framework format.

ivy.dev_str(x: ivy.NativeArray, f: Optional[ivy.Framework] = None) → str[source]

Get the device string for input array x.

Parameters
  • x (array) – Tensor for which to get the device string.

  • f (ml_framework, optional) – Machine learning framework. Inferred from inputs if None.

Returns

Device string for the array, e.g. ‘cuda:0’, ‘cuda:1’, ‘cpu’ etc..

ivy.dev_to_str(dev_in: ivy.Device, f: Optional[ivy.Framework] = None) → str[source]

Convert native data type to string representation.

Parameters
  • dev_in (device handle) – The device handle to convert to string.

  • f (ml_framework, optional) – Machine learning framework. Inferred from inputs if None.

Returns

Device string e.g. ‘cuda:0’.

ivy.dtype(x: ivy.NativeArray, f: Optional[ivy.Framework] = None) → ivy.Dtype[source]

Get the data type for input array x.

Parameters
  • x (array) – Tensor for which to get the data type.

  • f (ml_framework, optional) – Machine learning framework. Inferred from inputs if None.

Returns

Data type of the array

ivy.dtype_str(x: ivy.NativeArray, f: Optional[ivy.Framework] = None) → str[source]

Get the data type string for input array x.

Parameters
  • x (array) – Tensor for which to get the data type string.

  • f (ml_framework, optional) – Machine learning framework. Inferred from inputs if None.

Returns

Device string e.g. ‘float32’.

ivy.dtype_to_str(dtype_in: ivy.Dtype, f: Optional[ivy.Framework] = None) → str[source]

Convert native data type to string representation.

Parameters
  • dtype_in (data type) – The data type to convert to string.

  • f (ml_framework, optional) – Machine learning framework. Inferred from inputs if None.

Returns

Device string e.g. ‘float32’.

ivy.einops_rearrange(x: ivy.NativeArray, pattern: str, **axes_lengths: Dict[str, int]) → ivy.NativeArray[source]

Perform einops rearrange operation on input array x.

Parameters
  • x (array) – Input array to be re-arranged.

  • pattern (str) – Rearrangement pattern.

  • axes_lengths (keyword parameter args) – Any additional specifications for dimensions.

Returns

New array with einops.rearrange having been applied.

ivy.einops_reduce(x: ivy.NativeArray, pattern: str, reduction: Union[str, Callable], **axes_lengths: Dict[str, int]) → ivy.NativeArray[source]

Perform einops reduce operation on input array x.

Parameters
  • x (array) – Input array to be reduced.

  • pattern (str) – Reduction pattern.

  • reduction (str or callable) – One of available reductions (‘min’, ‘max’, ‘sum’, ‘mean’, ‘prod’), or callable.

  • axes_lengths (keyword parameter args) – Any additional specifications for dimensions.

Returns

New array with einops.reduce having been applied.

ivy.einops_repeat(x: ivy.NativeArray, pattern: str, **axes_lengths: Dict[str, int]) → ivy.NativeArray[source]

Perform einops repeat operation on input array x.

Parameters
  • x (array) – Input array to be repeated.

  • pattern (str) – Rearrangement pattern.

  • axes_lengths (keyword parameter args) – Any additional specifications for dimensions.

Returns

New array with einops.repeat having been applied.

ivy.equal(*xs: List[Any], equality_matrix: bool = False) → Union[bool, ivy.NativeArray][source]

Determines whether the inputs are all equal.

Parameters
  • xs (any) – inputs to compare.

  • equality_matrix (bool, optional) – Whether to return a matrix of equalities comparing each input with every other. Default is False.

Returns

Boolean, whether or not the inputs are equal, or matrix array of booleans if equality_matrix=True is set.

ivy.exists(x: Any) → bool[source]

Simple check as to whether the input is None or not.

Parameters

x (any) – Input to check.

Returns

True if x is not None, else False.

ivy.expand_dims(x: ivy.NativeArray, axis: int, f: Optional[ivy.Framework] = None) → ivy.NativeArray[source]

Expands the shape of an array. Inserts a new axis that will appear at the axis position in the expanded array shape.

Parameters
  • x (array) – Input array.

  • axis (int) – Position in the expanded axes where the new axis is placed.

  • f (ml_framework, optional) – Machine learning framework. Inferred from inputs if None.

Returns

array with the number of dimensions increased by onearray

ivy.flip(x: ivy.NativeArray, axis: Optional[int] = None, batch_shape: Optional[List[int]] = None, f: Optional[ivy.Framework] = None) → ivy.NativeArray[source]

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

Parameters
  • x (array) – Input array.

  • axis (None or int or sequence of ints, optional) – Axis or axes along which to flip over. The default, axis: int = None, will flip over all axes.

  • batch_shape (sequence of ints, optional) – Shape of batch. Inferred from inputs if None.

  • f (ml_framework, optional) – Machine learning framework. Inferred from inputs if None.

Returns

An array with the entries of axis reversed.

ivy.floor(x: ivy.NativeArray, f: Optional[ivy.Framework] = None) → ivy.NativeArray[source]

Returns element-wise largest integer not greater than x.

Parameters
  • x (array) – Input array to floor.

  • f (ml_framework, optional) – Machine learning framework. Inferred from inputs if None.

Returns

An array of the same shape and type as x, with the elements floored to integers.

ivy.floormod(x: ivy.NativeArray, y: ivy.NativeArray, f: Optional[ivy.Framework] = None) → ivy.NativeArray[source]

Returns element-wise remainder of division.

Parameters
  • x (array) – Input array to floormod.

  • y (array) – Denominator input for floormod.

  • f (ml_framework, optional) – Machine learning framework. Inferred from inputs if None.

Returns

An array of the same shape and type as x, with the elements floor modded.

ivy.fourier_encode(x: ivy.NativeArray, max_freq: float, num_bands: int = 4, base: float = 2.0) → ivy.NativeArray[source]

Pads an array with fourier encodings.

Parameters
  • x (array) – Input array to encode.

  • max_freq (float) – The maximum frequency of the encoding.

  • num_bands (int, optional) – The number of frequency bands for the encoding. Default is 4.

  • base (float, optional) – The base of the encoding.

Returns

New array with the final dimension expanded, and the encodings stored in this channel.

ivy.gather(params: ivy.NativeArray, indices: ivy.NativeArray, axis: int = - 1, dev_str: Optional[str] = None, f: Optional[ivy.Framework] = None) → ivy.NativeArray[source]

Gather slices from params at axis according to indices.

Parameters
  • params (array) – The array from which to gather values.

  • indices (array) – Index array.

  • axis (int, optional) – The axis from which to gather from. Default is -1.

  • dev_str (str, optional) – device on which to create the array ‘cuda:0’, ‘cuda:1’, ‘cpu’ etc. Same as x if None.

  • f (ml_framework, optional) – Machine learning framework. Inferred from inputs if None.

Returns

New array with the values gathered at the specified indices along the specified axis.

ivy.gather_nd(params: ivy.NativeArray, indices: ivy.NativeArray, dev_str: Optional[str] = None, f: Optional[ivy.Framework] = None) → ivy.NativeArray[source]

Gather slices from params into a array with shape specified by indices.

Parameters
  • params (array) – The array from which to gather values.

  • indices (array) – Index array.

  • dev_str (str, optional) – device on which to create the array ‘cuda:0’, ‘cuda:1’, ‘cpu’ etc. Same as x if None.

  • f (ml_framework, optional) – Machine learning framework. Inferred from inputs if None.

Returns

New array of given shape, with the values gathered at the indices.

ivy.get_min_base() → float[source]

Get the global minimum base used by ivy for numerically stable power raising.

ivy.get_min_denominator() → float[source]

Get the global minimum denominator used by ivy for numerically stable division.

ivy.get_num_dims(x: ivy.NativeArray, as_array: bool = False, f: Optional[ivy.Framework] = None) → int[source]

Returns the number of dimensions of the array x.

Parameters
  • x (array) – Input array to infer the number of dimensions for.

  • as_array (bool, optional) – Whether to return the shape as a array, default False.

  • f (ml_framework, optional) – Machine learning framework. Inferred from inputs if None.

Returns

Shape of the array

ivy.gpu_is_available(f: Optional[ivy.Framework] = None) → bool[source]

Determine whether a GPU is available to use, with the backend framework.

Parameters

f (ml_framework, optional) – Machine learning framework. Inferred from inputs if None.

Returns

Boolean, as to whether a gpu is available.

ivy.identity(n: int, dtype_str: str = 'float32', batch_shape: Optional[List[int]] = None, dev_str: Optional[str] = None, f: Optional[ivy.Framework] = None) → ivy.NativeArray[source]

Returns the identity array. The identity array is a square array with ones on the main diagonal.

Parameters
  • n (int) – Number of rows (and columns) in n x n output.

  • dtype_str (data-type string, optional) – The desired data-type for the array in string format, i.e. ‘float32’ or ‘int64’. Default is ‘float32’.

  • batch_shape (sequence of ints, optional) – Shape of batch. Inferred from inputs if None.

  • dev_str (str) – device on which to create the array ‘cuda:0’, ‘cuda:1’, ‘cpu’ etc..

  • f (ml_framework, optional) – Machine learning framework. Inferred from inputs if None.

Returns

n x n array of type dtype_str, with its main diagonal set to one, and all other elements 0.

ivy.indices_where(x: ivy.NativeArray, f: Optional[ivy.Framework] = None) → ivy.NativeArray[source]

Returns indices or true elements in an input boolean array.

Parameters
  • x (array) – Boolean array, for which indices are desired.

  • f (ml_framework, optional) – Machine learning framework. Inferred from inputs if None.

Returns

Indices for where the boolean array is True.

ivy.is_array(x: Any, f: Optional[ivy.Framework] = None) → bool[source]

Determines whether the input x is an Ivy Array.

Parameters
  • x (any) – The input to check

  • f (ml_framework, optional) – Machine learning framework. Inferred from inputs if None.

Returns

Boolean, whether or not x is an array.

ivy.isnan(x: ivy.NativeArray, f: Optional[ivy.Framework] = None) → ivy.NativeArray[source]

Returns boolean map at locations where the input is not a number (nan).

Parameters
  • x (array) – Input array.

  • f (ml_framework, optional) – Machine learning framework. Inferred from inputs if None.

Returns

Boolean values for where the values of the array are nan.

ivy.linear_resample(x: ivy.NativeArray, num_samples: int, axis: int = - 1, f: Optional[ivy.Framework] = None) → ivy.NativeArray[source]

Performs linear re-sampling on input image.

Parameters
  • x (array) – Input array

  • num_samples (int) – The number of interpolated samples to take.

  • axis (int, optional) – The axis along which to perform the resample. Default is last dimension.

  • f (ml_framework, optional) – Machine learning framework. Inferred from inputs if None.

Returns

The array after the linear resampling.

ivy.linspace(start: ivy.NativeArray, stop: ivy.NativeArray, num: int, axis: Optional[int] = None, dev_str: Optional[str] = None, f: Optional[ivy.Framework] = None) → ivy.NativeArray[source]

Generates a certain number of evenly-spaced values in an interval along a given axis.

See \(arange\) that allows to specify the step size of evenly spaced values in an interval.

Parameters
  • start (array) – First entry in the range.

  • stop (array) – Final entry in the range.

  • num (int) – Number of values to generate.

  • axis (int) – Axis along which the operation is performed.

  • dev_str (str) – device on which to create the array ‘cuda:0’, ‘cuda:1’, ‘cpu’ etc.

  • f (ml_framework, optional) – Machine learning framework. Inferred from inputs if None.

Returns

Tensor of evenly-spaced values.

ivy.logspace(start: ivy.NativeArray, stop: ivy.NativeArray, num: int, base: float = 10.0, axis: Optional[int] = None, dev_str: Optional[str] = None, f: Optional[ivy.Framework] = None) → ivy.NativeArray[source]

Generates a certain number of evenly-spaced values in log space, in an interval along a given axis.

See \(arange\) that allows to specify the step size of evenly spaced values in an interval.

Parameters
  • start (array) – First entry in the range.

  • stop (array) – Final entry in the range.

  • num (int) – Number of values to generate.

  • base (float, optional) – The base of the log space. Default is 10.0

  • axis (int) – Axis along which the operation is performed.

  • dev_str (str) – device on which to create the array ‘cuda:0’, ‘cuda:1’, ‘cpu’ etc.

  • f (ml_framework, optional) – Machine learning framework. Inferred from inputs if None.

Returns

Tensor of evenly-spaced values.

ivy.matmul(x1: ivy.NativeArray, x2: ivy.NativeArray, f: Optional[ivy.Framework] = None) → ivy.NativeArray[source]

Computes the matrix product of two arrays x1 and x2.

Parameters
  • x1 (array) – Input array 1.

  • x2 (array) – Input array 2.

  • f (ml_framework, optional) – Machine learning framework. Inferred from inputs if None.

Returns

The matrix product of the input arrays.

ivy.maximum(x: ivy.NativeArray, y: ivy.NativeArray, f: Optional[ivy.Framework] = None) → ivy.NativeArray[source]

Returns the max of x and y (i.e. x > y ? x : y) element-wise.

Parameters
  • x (array) – Input array containing elements to maximum threshold.

  • y (array) – Tensor containing maximum values, must be broadcastable to x.

  • f (ml_framework, optional) – Machine learning framework. Inferred from inputs if None.

Returns

An array with the elements of x, but clipped to not be lower than the y values.

ivy.memory_on_dev(dev_str: str) → float[source]

Get the total amount of memory for a given device string. In case of CPU, the total RAM is returned.

Parameters

dev_str (str) – The device string to conver to native device handle.

Returns

The total memory on the device in GB.

ivy.meshgrid(*xs: List[ivy.NativeArray], indexing: str = 'ij', f: Optional[ivy.Framework] = None) → List[ivy.NativeArray][source]

Broadcasts parameters for evaluation on an N-D grid.

Parameters
  • xs (sequence of arrays) – input arrays

  • indexing (str, optional) – The indexing method, either ‘xy’ or ‘ij’. Default is ‘ij’.

  • f (ml_framework, optional) – Machine learning framework. Inferred from inputs if None.

Returns

list of N-D coordinate arrays for evaluating expressions on an N-D grid

ivy.minimum(x: ivy.NativeArray, y: ivy.NativeArray, f: Optional[ivy.Framework] = None) → ivy.NativeArray[source]

Returns the min of x and y (i.e. x < y ? x : y) element-wise.

Parameters
  • x (array) – Input array containing elements to minimum threshold.

  • y (array) – Tensor containing minimum values, must be broadcastable to x.

  • f (ml_framework, optional) – Machine learning framework. Inferred from inputs if None.

Returns

An array with the elements of x, but clipped to not exceed the y values.

ivy.nested_map(x: Union[ivy.NativeArray, List, Tuple, Dict], fn: Callable) → Union[ivy.NativeArray, List, Tuple, Dict][source]

Applies a function on x in a nested manner, whereby all dicts, lists and tuples are traversed to their lowest leaves before applying the method and returning x. If x is not nested, the method is applied to x directly.

Parameters
  • x (any) – The item to apply the mapped function to.

  • fn (callable) – The function to map onto x.

Returns

x following the applicable of fn to it’s nested leaves, or x itself if x is not nested.

ivy.num_gpus(f: Optional[ivy.Framework] = None) → int[source]

Determine the number of available GPUs, with the backend framework.

Parameters

f (ml_framework, optional) – Machine learning framework. Inferred from inputs if None.

Returns

Number of available GPUs.

ivy.one_hot(indices: ivy.NativeArray, depth: int, dev_str: Optional[str] = None, f: Optional[ivy.Framework] = None) → ivy.NativeArray[source]

Returns a one-hot array :param indices: Indices for where the ones should be scattered [batch_shape, dim] :type indices: array :param depth: Scalar defining the depth of the one-hot dimension. :type depth: int :param dev_str: device on which to create the array ‘cuda:0’, ‘cuda:1’, ‘cpu’ etc. Same as x if None. :type dev_str: str, optional :param f: Machine learning framework. Inferred from inputs if None. :type f: ml_framework, optional :return: Tensor of zeros with the same shape and type as a, unless dtype provided which overrides.

ivy.ones(shape: List[int], dtype_str: str = 'float32', dev_str: Optional[str] = None, f: Optional[ivy.Framework] = None) → ivy.NativeArray[source]

Returns a new array of given shape and type, filled with ones.

Parameters
  • shape (sequence of ints) – Shape of the new array, e.g. (2, 3).

  • dtype_str – The desired data-type for the array in string format, i.e. ‘float32’ or ‘int64’.

Default is ‘float32’. :type dtype_str: data-type string, optional :param dev_str: device on which to create the array ‘cuda:0’, ‘cuda:1’, ‘cpu’ etc.. :type dev_str: str :param f: Machine learning framework. Inferred from inputs if None. :type f: ml_framework, optional :return: Tensor of ones with the given shape and dtype_str.

ivy.ones_like(x: ivy.NativeArray, dtype_str: Optional[str] = None, dev_str: Optional[str] = None, f: Optional[ivy.Framework] = None) → ivy.NativeArray[source]

Returns an array of ones with the same shape and type as x, unless dtype_str provided which overrides.

Parameters
  • x (array) – The shape and data-type of a define these same attributes of the returned array.

  • dtype_str (data-type string, optional) – The desired data-type for the array in string format, i.e. ‘float32’ or ‘int64’. If not given, then the type of the original array is used.

  • dev_str (str, optional) – device on which to create the array ‘cuda:0’, ‘cuda:1’, ‘cpu’ etc. Same as x if None.

  • f (ml_framework, optional) – Machine learning framework. Inferred from inputs if None.

Returns

Tensor of zeros with the same shape and type as a, unless dtype_str provided which overrides.

ivy.repeat(x: ivy.NativeArray, repeats: Union[int, List[int]], axis: Optional[int] = None, f: Optional[ivy.Framework] = None) → ivy.NativeArray[source]

Repeat values along a given dimension

Parameters
  • x (array) – Input array.

  • repeats (int or sequence of ints.) – The number of repetitions for each element. repeats is broadcast to fit the shape of the given axis.

  • axis (int, optional) – The axis along which to repeat values. By default, use the flattened input array, and return a flat output array.

  • f (ml_framework, optional) – Machine learning framework. Inferred from inputs if None.

Returns

The repeated output array.

ivy.reshape(x: ivy.NativeArray, newshape: Union[int, List[int]], f: Optional[ivy.Framework] = None) → ivy.NativeArray[source]

Gives a new shape to an array without changing its data.

Parameters
  • x (array) – Tensor to be reshaped.

  • newshape (int or sequence of ints) – The new shape should be compatible with the original shape. One shape dimension can be -1. In this case, the value is inferred from the length of the array and remaining dimensions.

  • f (ml_framework, optional) – Machine learning framework. Inferred from inputs if None.

Returns

Reshaped array.

ivy.round(x: ivy.NativeArray, f: Optional[ivy.Framework] = None) → ivy.NativeArray[source]

Rounds the values of an array to the nearest integer, element-wise.

Parameters
  • x (array) – Input array containing elements to round.

  • f (ml_framework, optional) – Machine learning framework. Inferred from inputs if None.

Returns

An array of the same shape and type as x, with the elements rounded to integers.

ivy.scatter_flat(indices: ivy.NativeArray, updates: ivy.NativeArray, size: int, reduction: str = 'sum', dev_str: Optional[str] = None, f: Optional[ivy.Framework] = None) → ivy.NativeArray[source]

Scatter flat updates into a new flat array according to flat indices.

Parameters
  • indices (array) – Indices for the new values to occupy.

  • updates (array) – Values for the new array to hold.

  • size (int) – The size of the result.

  • reduction (str) – The reduction method for the scatter, one of ‘sum’, ‘min’, ‘max’ or ‘replace’

  • dev_str (str, optional) – device on which to create the array ‘cuda:0’, ‘cuda:1’, ‘cpu’ etc. Same as updates if None.

  • f (ml_framework, optional) – Machine learning framework. Inferred from inputs if None.

Returns

New array of given shape, with the values scattered at the indices.

ivy.scatter_nd(indices: ivy.NativeArray, updates: ivy.NativeArray, shape: List[int], reduction: str = 'sum', dev_str: Optional[str] = None, f: Optional[ivy.Framework] = None) → ivy.NativeArray[source]

Scatter updates into a new array according to indices.

Parameters
  • indices (array) – Indices for the new values to occupy.

  • updates (array) – Values for the new array to hold.

  • shape (sequence of ints) – The shape of the result.

  • reduction (str) – The reduction method for the scatter, one of ‘sum’, ‘min’ or ‘max’

  • dev_str (str, optional) – device on which to create the array ‘cuda:0’, ‘cuda:1’, ‘cpu’ etc. Same as updates if None.

  • f (ml_framework, optional) – Machine learning framework. Inferred from inputs if None.

Returns

New array of given shape, with the values scattered at the indices.

ivy.set_min_base(val: float) → None[source]

Set the global minimum base used by ivy for numerically stable power raising.

Parameters

val (float) – The new value to set the minimum base to.

ivy.set_min_denominator(val: float) → None[source]

Set the global minimum denominator used by ivy for numerically stable division.

Parameters

val (float) – The new value to set the minimum denominator to.

ivy.shape(x: ivy.NativeArray, as_array: bool = False, f: Optional[ivy.Framework] = None) → Union[List[int], Tuple[int]][source]

Returns the shape of the array x.

Parameters
  • x (array) – Input array to infer the shape of.

  • as_array (bool, optional) – Whether to return the shape as a array, default False.

  • f (ml_framework, optional) – Machine learning framework. Inferred from inputs if None.

Returns

Shape of the array

ivy.split(x: ivy.NativeArray, num_or_size_splits: Optional[Union[int, List[int]]] = None, axis: int = 0, with_remainder: bool = False, f: Optional[ivy.Framework] = None) → ivy.NativeArray[source]

Splits an array into multiple sub-arrays.

Parameters
  • x (array) – Tensor to be divided into sub-arrays.

  • num_or_size_splits (int, optional) – Number of equal arrays to divide the array into along the given axis if an integer. The size of each split element if a sequence of integers. Default is to divide into as many 1-dimensional arrays as the axis dimension.

  • axis (int, optional) – The axis along which to split, default is 0.

  • with_remainder (bool, optional) – If the tensor does not split evenly, then store the last remainder entry. Defaul is False.

  • f (ml_framework, optional) – Machine learning framework. Inferred from inputs if None.

Returns

A list of sub-arrays.

ivy.split_func_call(func: Callable, inputs: List[Union[ivy.NativeArray, ivy.Container]], chunk_size: int, input_axes: Union[int, List[int]] = 0, output_axes: Optional[Union[int, List[int]]] = None, mean: bool = False) → List[Union[ivy.NativeArray, ivy.Container]][source]

Call a function by splitting its inputs along a given axis, and calling the function in chunks, rather than feeding the entire input array at once. This can be useful to reduce memory usage of the device the arrays are on.

Parameters
  • func (callable) – The function to be called.

  • inputs (sequence of arrays) – A list of inputs to pass into the function.

  • chunk_size (int) – The size of each of the chunks to be fed into the function.

  • input_axes (int or sequence of ints, optional) – The axes along which to split each of the inputs, before passing to the function. Default is 0.

  • output_axes (int or sequence of ints, optional) – The axes along which to concat each of the returned outputs. Default is same as fist input axis.

  • mean (bool, optional) – Whether to compute a weighted mean based on the return from each chunk. Default is False.

Returns

The return from the function, following input splitting and re-concattenation.

ivy.split_func_call_across_gpus(func: Callable, inputs: List[Union[ivy.NativeArray, ivy.Container]], dev_strs: Union[int, List[int], List[str]], input_axes: Optional[Union[int, List[int]]] = None, output_axes: Optional[Union[int, List[int]]] = None, concat_output: bool = False) → List[Union[ivy.NativeArray, ivy.Container]][source]

Call a function by splitting its inputs along a given axis, and calling each chunk on a different device.

Parameters
  • func (callable) – The function to be called.

  • inputs (sequence of arrays or containers) – A list of inputs to pass into the function.

  • dev_strs (int, sequence of ints or sequence of strs) – The gpu device strings, in the format “gpu:idx”.

  • input_axes (int or sequence of ints, optional) – The axes along which to split each of the inputs, before passing to the function. Default is 0.

  • output_axes (int or sequence of ints, optional) – The axes along which to concat each of the returned outputs. Default is same as fist input axis.

  • concat_output (bool, optional) – Whether to concatenate each return values into a single array. Default is False.

Returns

The return from the function, following input splitting and re-concattenation across devices.

ivy.squeeze(x: ivy.NativeArray, axis: Optional[int] = None, f: Optional[ivy.Framework] = None) → ivy.NativeArray[source]

Removes a single-dimensional entry from the shape of an array.

Parameters
  • x (array) – Input data.

  • axis (int, optional) – Index for one of the single-dimensional entries in the shape. If an axis is selected with shape entry greater than one, an error is raised.

  • f (ml_framework, optional) – Machine learning framework. Inferred from inputs if None.

Returns

The input array, but with all (axis=None) or one (axis is int) of the dimensions of length 1 removed.

ivy.stable_divide(numerator: Any, denominator: Any, min_denominator: Optional[float] = None) → Any[source]

Divide the numerator by the denominator, with min denominator added to the denominator for numerical stability.

Parameters
  • numerator (any valid numerator, including containers) – The numerator of the division.

  • denominator (any valid denominator, including containers) – The denominator of the division.

  • min_denominator (float, optional) – The minimum denominator to use, use global ivy._MIN_DENOMINATOR by default.

Returns

The new item following the numerically stable division.

ivy.stable_pow(base: Any, exponent: Any, min_base: Optional[float] = None) → Any[source]

Raise the base by the power, with MIN_BASE added to the base when exponent > 1 for numerical stability.

Parameters
  • base (any valid numerator, including containers) – The numerator of the division.

  • exponent (any valid denominator, including containers) – The denominator of the division.

  • min_base (float, optional) – The minimum base to use, use global ivy._MIN_BASE by default.

Returns

The new item following the numerically stable division.

ivy.stack(xs: List[ivy.NativeArray], axis: int = 0, f: Optional[ivy.Framework] = None) → ivy.NativeArray[source]

Joins a sequence of arrays along a new axis. The axis parameter specifies the index of the new axis in the dimensions of the result. For example, if axis: int = 0, it will be the first dimension and if axis: int = -1, it will be the last dimension.

Parameters
  • xs (sequence of arrays) – Input arrays, each array must have the same shape.

  • axis (int, optional) – The axis in the result array along which the input arrays are stacked.

  • f (ml_framework, optional) – Machine learning framework. Inferred from inputs if None.

Returns

The stacked array has one more dimension than the input arrays.

ivy.str_to_dev(dev_str: str, f: Optional[ivy.Framework] = None) → ivy.Device[source]

Convert device string representation to native device type.

Parameters
  • dev_str (str) – The device string to conver to native device handle.

  • f (ml_framework, optional) – Machine learning framework. Inferred from inputs if None.

Returns

Native device handle.

ivy.swapaxes(x: ivy.NativeArray, axis0: int, axis1: int, f: Optional[ivy.Framework] = None) → ivy.NativeArray[source]

Interchange two axes of an array.

Parameters
  • x (array) – Input array.

  • axis0 (int) – First axis to be swapped.

  • axis1 (int) – Second axis to be swapped.

  • f (ml_framework, optional) – Machine learning framework. Inferred from inputs if None.

Returns

x with its axes permuted.

ivy.tile(x: ivy.NativeArray, reps: List[int], f: Optional[ivy.Framework] = None) → ivy.NativeArray[source]

Constructs an array by repeating x the number of times given by reps.

Parameters
  • x (array) – Input array.

  • reps (sequence of ints) – The number of repetitions of x along each axis.

  • f (ml_framework, optional) – Machine learning framework. Inferred from inputs if None.

Returns

The tiled output array.

ivy.to_dev(x: ivy.NativeArray, dev_str: Optional[str] = None, f: Optional[ivy.Framework] = None) → ivy.NativeArray[source]

Move the input array x to the desired device, specified by device string.

Parameters
  • x (array) – Array to move onto the device.

  • dev_str (str, optional) – device to move the array to ‘cuda:0’, ‘cuda:1’, ‘cpu’ etc. Keep same device if None.

  • f (ml_framework, optional) – Machine learning framework. Inferred from inputs if None.

Returns

The array x, but now placed on the target device.

ivy.to_ivy(x: Union[ivy.NativeArray, List, Tuple, Dict], nested: bool = False) → Union[ivy.NativeArray, List, Tuple, Dict][source]

Returns the input array converted to an ivy.Array instances if it is an array type, otherwise the input is returned unchanged. If nested is set, the check is applied to all nested leafs of tuples, lists and dicts contained within x.

Parameters
  • x (any) – The input to maybe convert.

  • nested (bool, optional) – Whether to apply the conversion on arguments in a nested manner. If so, all dicts, lists and tuples will be traversed to their lowest leaves in search of ivy.Array and ivy.Variable instances. Default is False.

Returns

the input in it’s native framework form in the case of ivy.Array or ivy.Variable instances.

ivy.to_list(x: ivy.NativeArray, f: Optional[ivy.Framework] = None) → List[source]

Creates a (possibly nested) list from input array.

Parameters
  • x (array) – Input array.

  • f (ml_framework, optional) – Machine learning framework. Inferred from inputs if None.

Returns

A list representation of the input array.

ivy.to_native(x: Union[ivy.NativeArray, List, Tuple, Dict], nested: bool = False) → Union[ivy.NativeArray, List, Tuple, Dict][source]

Returns the input item in it’s native backend framework form if it is an ivy.Array or ivy.Variable instance. otherwise the input is returned unchanged. If nested is set, the check is applied to all nested leafs of tuples, lists and dicts contained within x.

Parameters
  • x (any) – The input to maybe convert.

  • nested (bool, optional) – Whether to apply the conversion on arguments in a nested manner. If so, all dicts, lists and tuples will be traversed to their lowest leaves in search of ivy.Array and ivy.Variable instances. Default is False.

Returns

the input in it’s native framework form in the case of ivy.Array or ivy.Variable instances.

ivy.to_numpy(x: ivy.NativeArray, f: Optional[ivy.Framework] = None) → numpy.ndarray[source]

Converts array into a numpy array.

Parameters
  • x (array) – Input array.

  • f (ml_framework, optional) – Machine learning framework. Inferred from inputs if None.

Returns

A numpy array.

ivy.to_scalar(x: ivy.NativeArray, f: Optional[ivy.Framework] = None) → numbers.Number[source]

Converts an array with a single element into a scalar.

Parameters
  • x (array) – Input array with a single element.

  • f (ml_framework, optional) – Machine learning framework. Inferred from inputs if None.

Returns

A scalar.

ivy.tpu_is_available(f: Optional[ivy.Framework] = None) → bool[source]

Determine whether a TPU is available to use, with the backend framework.

Parameters

f (ml_framework, optional) – Machine learning framework. Inferred from inputs if None.

Returns

Boolean, as to whether a tpu is available.

ivy.transpose(x: ivy.NativeArray, axes: Optional[List[int]] = None, f: Optional[ivy.Framework] = None) → ivy.NativeArray[source]

Permutes the dimensions of an array.

Parameters
  • x (array) – Input array.

  • axes (sequence of ints of length N) – By default, reverse the dimensions, otherwise permute the axes according to the values given.

  • f (ml_framework, optional) – Machine learning framework. Inferred from inputs if None.

Returns

x with its axes permuted.

ivy.unstack(x: ivy.NativeArray, axis: int, keepdims: bool = False, f: Optional[ivy.Framework] = None) → ivy.NativeArray[source]

Unpacks the given dimension of a rank-R array into rank-(R-1) arrays.

Parameters
  • x (array) – Input array to unstack.

  • axis (int) – Axis for which to unpack the array.

  • keepdims (bool, optional) – Whether to keep dimension 1 in the unstack dimensions. Default is False.

  • f (ml_framework, optional) – Machine learning framework. Inferred from inputs if None.

Returns

List of arrays, unpacked along specified dimensions.

ivy.where(condition: ivy.NativeArray, x1: ivy.NativeArray, x2: ivy.NativeArray, f: Optional[ivy.Framework] = None) → ivy.NativeArray[source]

Returns elements chosen from x or y depending on condition.

Parameters
  • condition (bool array) – Where True, yield x1, otherwise yield x2.

  • x1 (array) – values from which to choose when condition is True.

  • x2 (array) – values from which to choose when condition is False.

  • f (ml_framework, optional) – Machine learning framework. Inferred from inputs if None.

Returns

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

ivy.zero_pad(x: ivy.NativeArray, pad_width: List[Tuple[int]], f: Optional[ivy.Framework] = None) → ivy.NativeArray[source]

Pads an array with zeros.

Parameters
  • x (array) – Input array to pad.

  • pad_width (sequence of tuples of ints) – Number of values padded to the edges of each axis. Specified as ((before_1, after_1), … (before_N, after_N)), where N is number of axes of x.

  • f (ml_framework, optional) – Machine learning framework. Inferred from inputs if None.

Returns

Padded array of rank equal to x with shape increased according to pad_width.

ivy.zeros(shape: List[int], dtype_str: str = 'float32', dev_str: Optional[str] = None, f: Optional[ivy.Framework] = None) → ivy.NativeArray[source]

Return a new array of given shape and type, filled with zeros.

Parameters
  • shape (sequence of ints) – Shape of the new array, e.g. (2, 3).

  • dtype_str – The desired data-type for the array in string format, i.e. ‘float32’ or ‘int64’.

Default is ‘float32’. :type dtype_str: data-type string, optional :param dev_str: device on which to create the array ‘cuda:0’, ‘cuda:1’, ‘cpu’ etc.. :type dev_str: str :param f: Machine learning framework. Inferred from inputs if None. :type f: ml_framework, optional :return: Tensor of zeros with the given shape and dtype_str.

ivy.zeros_like(x: ivy.NativeArray, dtype_str: Optional[str] = None, dev_str: Optional[str] = None, f: Optional[ivy.Framework] = None) → ivy.NativeArray[source]

Returns an array of zeros with the same shape and type as x, unless dtype_str provided which overrides.

Parameters
  • x (array) – The shape and data-type of x define these same attributes of the returned array.

  • dtype_str (data-type string, optional) – The desired data-type for the array in string format, i.e. ‘float32’ or ‘int64’. If not given, then the type of the original array is used.

  • dev_str (str, optional) – device on which to create the array ‘cuda:0’, ‘cuda:1’, ‘cpu’ etc. Same as x if None.

  • f (ml_framework, optional) – Machine learning framework. Inferred from inputs if None.

Returns

Tensor of zeros with the same shape and type as a, unless dtype_str provided which overrides.