Creation

class ivy.NestedSequence(*args, **kwargs)[source]

Bases: Protocol[_T_co]

__init__(*args, **kwargs)
ivy.arange(start, stop=None, step=1, /, *, dtype=None, device=None, out=None)[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
  • start (Number) – if stop is specified, the start of interval (inclusive); otherwise, the end of the interval (exclusive). If stop is not specified, the default starting value is 0.

  • stop (Optional[Number]) – the end of the interval. Default: None. (default: None)

  • step (Optional[Number]) – the distance between two adjacent elements (out[i+1] - out[i]). Must not be 0; (default: 1) may be negative, this results in an empty array if stop >= start. Default: 1.

  • dtype (Optional[Union[Dtype, NativeDtype]]) – output array data type. If dtype is None, the output array data type must be (default: None) inferred from start, stop and step. If those are all integers, the output array dtype must be the default integer dtype; if one or more have type float, then the output array dtype must be the default floating-point data type. Default: None.

  • device (Optional[Union[Device, NativeDevice]]) – device on which to place the created array. Default: None. (default: None)

  • out (Optional[Array]) – optional output array, for writing the result to. It must have a shape that the (default: None) inputs broadcast to.

Return type

Array

Returns

ret – a one-dimensional array containing evenly spaced values. The length of the output array must be ceil((stop-start)/step) if stop - start and step have the same sign, and length 0 otherwise.

This function conforms to the Array API Standard. This docstring is an extension of the docstring in the standard.

Both the description and the type hints above assumes an array input for simplicity, but this function is nestable, and therefore also accepts ivy.Container instances in place of any of the arguments.

ivy.array(obj, /, *, copy=None, dtype=None, device=None, out=None)

Converts the input to an array.

Parameters
  • obj (Union[Array, NativeArray, bool, int, float, NestedSequence, TypeVar(SupportsBufferProtocol)]) – input data, in any form that can be converted to an array. This includes lists, lists of tuples, tuples, tuples of tuples, tuples of lists and ndarrays.

  • copy (Optional[bool]) – boolean, indicating whether or not to copy the input. Default: None. (default: None)

  • dtype (Optional[Union[Dtype, NativeDtype]]) – output array data type. If dtype is None, the output array data type must (default: None) be the default floating-point data type. Default None.

  • device (Optional[Union[Device, NativeDevice]]) – device on which to place the created array. Default: None. (default: None)

  • out (Optional[Array]) – optional output array, for writing the result to. It must have a shape that the (default: None) inputs broadcast to.

Return type

Array

Returns

ret – An array interpretation of x.

This function conforms to the Array API Standard. This docstring is an extension of the docstring in the standard.

Both the description and the type hints above assumes an array input for simplicity, but this function is nestable, and therefore also accepts ivy.Container instances in place of any of the arguments.

ivy.asarray(obj, /, *, copy=None, dtype=None, device=None, out=None)[source]

Converts the input to an array.

Parameters
  • obj (Union[Array, NativeArray, bool, int, float, NestedSequence, TypeVar(SupportsBufferProtocol)]) – input data, in any form that can be converted to an array. This includes lists, lists of tuples, tuples, tuples of tuples, tuples of lists and ndarrays.

  • copy (Optional[bool]) – boolean, indicating whether or not to copy the input. Default: None. (default: None)

  • dtype (Optional[Union[Dtype, NativeDtype]]) – output array data type. If dtype is None, the output array data type must (default: None) be the default floating-point data type. Default None.

  • device (Optional[Union[Device, NativeDevice]]) – device on which to place the created array. Default: None. (default: None)

  • out (Optional[Array]) – optional output array, for writing the result to. It must have a shape that the (default: None) inputs broadcast to.

Return type

Array

Returns

ret – An array interpretation of x.

This function conforms to the Array API Standard. This docstring is an extension of the docstring in the standard.

Both the description and the type hints above assumes an array input for simplicity, but this function is nestable, and therefore also accepts ivy.Container instances in place of any of the arguments.

ivy.asarray_handle_nestable(fn)[source]
Return type

Callable

ivy.asarray_infer_device(fn)[source]
Return type

Callable

ivy.asarray_to_native_arrays_and_back(fn)[source]
Return type

Callable

ivy.copy_array(x, *, out=None)[source]

Copy an array.

Parameters
  • x (Union[Array, NativeArray]) – array, input array containing elements to copy.

  • out (Optional[Array]) – optional output array, for writing the result to. It must have a shape that the (default: None) inputs broadcast to.

Return type

Array

Returns

ret – a copy of the input array x.

Examples

With one ivy.Array input:

>>> x = ivy.array([-1, 0, 1])
>>> y = ivy.copy_array(x)
>>> print(y)
ivy.array([-1, 0, 1])
>>> x = ivy.array([1, 0, 1, 1])
>>> y = ivy.copy_array(x)
>>> print(y)
ivy.array([1, 0, 1, 1])
>>> x = ivy.array([1, 0, 1, -1])
>>> y = ivy.zeros((1, 4))
>>> ivy.copy_array(x, out=y)
>>> print(y)
ivy.array([1, 0, 1, -1])
>>> x = ivy.array([1, 0, 1, 1])
>>> ivy.copy_array(x, out=x)
>>> print(x)
ivy.array([1, 0, 1, 1])

With one ivy.Container input:

>>> x = ivy.Container(a=ivy.array([-1, 0, 1]))
>>> y = ivy.copy_array(x)
>>> print(y)
{
    a: ivy.array([-1, 0, 1])
}
>>> x = ivy.Container(a=ivy.array([-1, 0, 1]),b=ivy.array([-1, 0, 1, 1, 1, 0]))
>>> y = ivy.copy_array(x)
>>> print(y)
{
    a: ivy.array([-1, 0, 1]),
    b: ivy.array([-1, 0, 1, 1, 1, 0])
}

With one ivy.Container static method:

>>> x = ivy.Container(a=ivy.array([-1, 0, 1]),b=ivy.array([-1, 0, 1, 1, 1, 0]))
>>> y = ivy.Container.static_copy_array(x)
>>> print(y)
{
    a: ivy.array([-1, 0, 1]),
    b: ivy.array([-1, 0, 1, 1, 1, 0])
}

With one ivy.Array instance method:

>>> x = ivy.array([-1, 0, 1])
>>> y = x.copy_array()
>>> print(y)
ivy.array([-1, 0, 1])
>>> x = ivy.array([1, 0, 1, 1])
>>> y = x.copy_array()
>>> print(y)
ivy.array([1, 0, 1, 1])

With ivy.Container instance method:

>>> x = ivy.Container(a=ivy.array([1, 0, 1]),b=ivy.array([-1, 0, 1, 1]))
>>> y = x.copy_array()
>>> print(y)
{
    a: ivy.array([1, 0, 1]),
    b: ivy.array([-1, 0, 1, 1])
}
ivy.empty(shape, *, dtype=None, device=None, out=None)[source]

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

Parameters
  • shape (Union[Shape, NativeShape]) – output array shape.

  • dtype (Optional[Union[Dtype, NativeDtype]]) – output array data type. If dtype is None, the output array data type must be the (default: None) default floating-point data type. Default: None.

  • device (Optional[Union[Device, NativeDevice]]) – device on which to place the created array. Default: None. (default: None)

  • out (Optional[Array]) – optional output array, for writing the result to. It must have a shape that the (default: None) inputs broadcast to.

Return type

Array

Returns

ret – an uninitialized array having a specified shape

This function conforms to the Array API Standard. This docstring is an extension of the docstring in the standard.

Both the description and the type hints above assumes an array input for simplicity, but this function is nestable, and therefore also accepts ivy.Container instances in place of any of the arguments.

ivy.empty_like(x, /, *, dtype=None, device=None, out=None)[source]

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

Parameters
  • x (Union[Array, NativeArray]) – input array from which to derive the output array shape.

  • dtype (Optional[Union[Dtype, NativeDtype]]) – output array data type. If dtype is None, the output array data type must be (default: None) inferred from x. Deafult: None.

  • device (Optional[Union[Device, NativeDevice]]) – device on which to place the created array. If device is None, the output array (default: None) device must be inferred from x. Default: None.

  • out (Optional[Array]) – optional output array, for writing the result to. It must have a shape that the (default: None) inputs broadcast to.

Return type

Array

Returns

ret – an array having the same shape as x and containing uninitialized data.

This function conforms to the Array API Standard. This docstring is an extension of the docstring in the standard.

Both the description and the type hints above assumes an array input for simplicity, but this function is nestable, and therefore also accepts ivy.Container instances in place of any of the arguments.

ivy.eye(n_rows, n_cols=None, /, *, k=0, batch_shape=None, dtype=None, device=None, out=None)[source]

Returns a two-dimensional array with ones on the k diagonal and zeros elsewhere.

Parameters
  • n_rows (int) – number of rows in the output array.

  • n_cols (Optional[int]) – number of columns in the output array. If None, the default number of columns in (default: None) the output array is equal to n_rows. Default: None.

  • k (int) – index of the diagonal. A positive value refers to an upper diagonal, a negative (default: 0) value to a lower diagonal, and 0 to the main diagonal. Default: 0.

  • dtype (Optional[Union[Dtype, NativeDtype]]) – output array data type. If dtype is None, the output array data type must be the (default: None) default floating-point data type. Default: None.

  • device (Optional[Union[Device, NativeDevice]]) – device on which to place the created array. (default: None)

  • out (Optional[Array]) – optional output array, for writing the result to. It must have a shape that the (default: None) inputs broadcast to.

Return type

Array

Returns

ret – device on which to place the created array. Default: None.

This function conforms to the Array API Standard. This docstring is an extension of the docstring in the standard.

Both the description and the type hints above assumes an array input for simplicity, but this function is nestable, and therefore also accepts ivy.Container instances in place of any of the arguments.

ivy.from_dlpack(x, /, *, out=None)[source]

Returns a new array containing the data from another (array) object with a __dlpack__ method.

Parameters
  • object (x) – input (array) object.

  • out (Optional[Array]) – optional output array, for writing the result to. It must have a shape that the (default: None) inputs broadcast to.

Return type

Array

Returns

ret – an array containing the data in x.

Note

The returned array may be either a copy or a view. See data-interchange for details.

This function conforms to the Array API Standard. This docstring is an extension of the docstring in the standard.

Both the description and the type hints above assumes an array input for simplicity, but this function is nestable, and therefore also accepts ivy.Container instances in place of any of the arguments.

ivy.full(shape, fill_value, *, dtype=None, device=None, out=None)[source]

Returns a new array having a specified shape and filled with fill_value.

Parameters
  • shape (Union[Shape, NativeShape]) – output array shape.

  • fill_value (Union[float, bool]) – fill value.

  • dtype (Optional[Union[Dtype, NativeDtype]]) – output array data type. If dtype is None, the output array data type must (default: None) be inferred from fill_value. If the fill value is an int, the output array data type must be the default integer data type. If the fill value is a float, the output array data type must be the default floating-point data type. If the fill value is a bool, the output array must have boolean data type. Default: None.

  • device (Optional[Union[Device, NativeDevice]]) – device on which to place the created array. Default: None. (default: None)

  • out (Optional[Array]) – optional output array, for writing the result to. It must have a shape that the (default: None) inputs broadcast to.

Return type

Array

Returns

ret – an array where every element is equal to fill_value.

This function conforms to the Array API Standard. This docstring is an extension of the docstring in the standard.

Both the description and the type hints above assumes an array input for simplicity, but this function is nestable, and therefore also accepts ivy.Container instances in place of any of the arguments.

Functional Examples

With ivy.Shape input:

>>> shape = ivy.Shape((2,2))
>>> fill_value = 8.6
>>> x = ivy.full(shape, fill_value)
>>> print(x)
ivy.array([[8.6, 8.6],
           [8.6, 8.6]])

With ivy.NativeShape input:

>>> shape = ivy.NativeShape((2, 2, 2))
>>> fill_value = True
>>> dtype = ivy.bool
>>> device = ivy.Device('cpu')
>>> x = ivy.full(shape, fill_value, dtype=dtype, device=device)
>>> print(x)
ivy.array([[[True,  True],
            [True,  True]],
           [[True,  True],
            [True,  True]]])

With ivy.NativeDevice input:

>>> shape = ivy.NativeShape((1, 2))
>>> fill_value = 0.68
>>> dtype = ivy.float64
>>> device = ivy.NativeDevice('cpu')
>>> x = ivy.full(shape, fill_value, dtype=dtype, device=device)
>>> print(x)
ivy.array([[0.68, 0.68]])

With ivy.Container input:

>>> shape = ivy.Container(a=ivy.NativeShape((2, 1)), b=ivy.Shape((2, 1, 2)))
>>> fill_value = ivy.Container(a=0.99, b=False)
>>> dtype = ivy.Container(a=ivy.float64, b=ivy.bool)
>>> device = ivy.Container(a=ivy.NativeDevice('cpu'), b=ivy.Device('cpu'))
>>> x = ivy.full(shape, fill_value, dtype=dtype, device=device)
>>> print(x)
{
    a: ivy.array([[0.99],
                  [0.99]]),
    b: ivy.array([[[False, False]],
                  [[False, False]]])
}
ivy.full_like(x, /, fill_value, *, dtype=None, device=None, out=None)[source]

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

Parameters
  • x (Union[Array, NativeArray]) – input array from which to derive the output array shape.

  • fill_value (float) – Scalar fill value

  • dtype (Optional[Union[Dtype, NativeDtype]]) – output array data type. If dtype is None, the output array data type must (default: None) be inferred from x. Default: None.

  • device (Optional[Union[Device, NativeDevice]]) – device on which to place the created array. If device is None, the (default: None) output array device must be inferred from x. Default: None.

  • out (Optional[Array]) – optional output array, for writing the result to. It must have a shape that the (default: None) inputs broadcast to.

Return type

Array

Returns

ret – an array having the same shape as x and where every element is equal to fill_value.

This function conforms to the Array API Standard. This docstring is an extension of the docstring in the standard.

Both the description and the type hints above assumes an array input for simplicity, but this function is nestable, and therefore also accepts ivy.Container instances in place of any of the arguments.

Functional Examples

With int datatype:

>>> x = ivy.array([1, 2, 3, 4, 5, 6])
>>> fill_value = 1
>>> y = ivy.full_like(x, fill_value)
>>> print(y)
ivy.array([1, 1, 1, 1, 1, 1])
>>> fill_value = 0.000123
>>> x = ivy.ones(5)
>>> y = ivy.full_like(x, fill_value)
>>> print(y)
ivy.array([0.000123, 0.000123, 0.000123, 0.000123, 0.000123])

With float datatype:

>>> x = ivy.array([1.0, 2.0, 3.0, 4.0, 5.0, 6.0])
>>> fill_value = 0.000123
>>> y = ivy.full_like(x, fill_value)
>>> print(y)
ivy.array([0.000123, 0.000123, 0.000123, 0.000123, 0.000123, 0.000123])

With ivy.NativeArray input:

>>> x = ivy.native_array([3.0, 8.0])
>>> fill_value = 0.000123
>>> y = ivy.full_like(x,fill_value)
>>> print(y)
ivy.array([0.000123, 0.000123])
>>> x = ivy.native_array([[3., 8., 2.], [2., 8., 3.]])
>>> y = ivy.full_like(x, fill_value)
>>> print(y)
ivy.array([[0.000123, 0.000123, 0.000123],
       [0.000123, 0.000123, 0.000123]])

With ivy.Container input:

>>> x = ivy.Container(a=ivy.array([1.2,2.2324,3.234]),b=ivy.array([4.123,5.23,6.23]))
>>> fill_value = 15.0
>>> y = ivy.full_like(x, fill_value)
>>> print(y)
{
    a: ivy.array([15., 15., 15.]),
    b: ivy.array([15., 15., 15.])
}
ivy.linspace(start, stop, /, num, *, axis=None, endpoint=True, dtype=None, device=None, out=None)[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 (Union[Array, NativeArray, float]) – First entry in the range.

  • stop (Union[Array, NativeArray, float]) – Final entry in the range.

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

  • axis (Optional[int]) – Axis along which the operation is performed. (default: None)

  • endpoint (bool) – If True, stop is the last sample. Otherwise, it is not included. (default: True)

  • dtype (Optional[Union[Dtype, NativeDtype]]) – output array data type. (default: None)

  • device (Optional[Union[Device, NativeDevice]]) – device on which to create the array ‘cuda:0’, ‘cuda:1’, ‘cpu’ etc. (default: None)

  • out (Optional[Array]) – optional output array, for writing the result to. It must have a shape that the (default: None) inputs broadcast to.

Return type

Array

Returns

ret – Tensor of evenly-spaced values.

This function conforms to the Array API Standard. This docstring is an extension of the docstring in the standard.

Both the description and the type hints above assumes an array input for simplicity, but this function is nestable, and therefore also accepts ivy.Container instances in place of any of the arguments.

ivy.logspace(start, stop, /, num, *, base=10.0, axis=None, dtype=None, device=None, out=None)[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 (Union[Array, NativeArray, int]) – First entry in the range.

  • stop (Union[Array, NativeArray, int]) – Final entry in the range.

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

  • base (float) – The base of the log space. Default is 10.0 (default: 10.0)

  • axis (Optional[int]) – Axis along which the operation is performed. (default: None)

  • dtype (Optional[Union[Dtype, NativeDtype]]) – The data type of the output tensor. If None, the dtype of on_value is used or if (default: None) that is None, the dtype of off_value is used, or if that is None, defaults to float32.

  • device (Optional[Union[Device, NativeDevice]]) – device on which to create the array ‘cuda:0’, ‘cuda:1’, ‘cpu’ etc. (default: None)

  • out (Optional[Array]) – optional output array, for writing the result to. It must have a shape that the (default: None) inputs broadcast to.

Return type

Array

Returns

  • ret – Tensor of evenly-spaced values.

  • Both the description and the type hints above assumes an array input for simplicity,

  • but this function is nestable, and therefore also accepts ivy.Container

  • instances in place of any of the arguments.

ivy.meshgrid(*arrays, sparse=False, indexing='xy')[source]

Returns coordinate matrices from coordinate vectors.

Parameters
  • arrays (Union[Array, NativeArray]) – an arbitrary number of one-dimensional arrays representing grid coordinates. Each array should have the same numeric data type.

  • sparse (bool) – if True, a sparse grid is returned in order to conserve memory. Default: False. (default: False)

  • indexing (str) – Cartesian 'xy' or matrix 'ij' indexing of output. If provided zero or (default: 'xy') 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'.

Return type

List[Array]

Returns

ret – list of N arrays, where N is the number of provided one-dimensional input arrays. Each returned array must have rank N. For N one-dimensional arrays having lengths Ni = len(xi),

  • if matrix indexing ij, then each returned array must have the shape (N1, N2, N3, ..., Nn).

  • if Cartesian indexing xy, then each returned array must have shape (N2, N1, N3, ..., Nn).

Accordingly, for the two-dimensional case with input one-dimensional arrays of length M and N, if matrix indexing ij, then each returned array must have shape (M, N), and, if Cartesian indexing xy, then each returned array must have shape (N, M).

Similarly, for the three-dimensional case with input one-dimensional arrays of length M, N, and P, if matrix indexing ij, then each returned array must have shape (M, N, P), and, if Cartesian indexing xy, then each returned array must have shape (N, M, P).

Each returned array should have the same data type as the input arrays.

This function conforms to the Array API Standard. This docstring is an extension of the docstring in the standard.

Both the description and the type hints above assumes an array input for simplicity, but this function is nestable, and therefore also accepts ivy.Container instances in place of any of the arguments.

Functional Examples

With ivy.Array input:

>>> x = ivy.array([1, 2])
>>> y = ivy.array([3, 4])
>>> xv, yv = ivy.meshgrid(x, y)
>>> print(xv)
ivy.array([[1, 2],
        [1, 2]])
>>> print(yv)
ivy.array([[3, 3],
        [4, 4]])
>>> x = ivy.array([1, 2, 5])
>>> y = ivy.array([4, 1])
>>> xv, yv = ivy.meshgrid(x, y, indexing='ij')
>>> print(xv)
ivy.array([[1, 1],
        [2, 2],
        [5, 5]])
>>> print(yv)
ivy.array([[4, 1],
        [4, 1],
        [4, 1]])
>>> x = ivy.array([1, 2, 3])
>>> y = ivy.array([4, 5, 6])
>>> xv, yv = ivy.meshgrid(x, y, sparse=True)
>>> print(xv)
ivy.array([[1, 2, 3]])
>>> print(yv)
ivy.array([[4],
        [5],
        [6]])

With ivy.NativeArray input:

>>> x = ivy.native_array([1, 2])
>>> y = ivy.native_array([3, 4])
>>> xv, yv = ivy.meshgrid(x, y)
>>> print(xv)
ivy.array([[1, 2],
        [1, 2]])
>>> print(yv)
ivy.array([[3, 3],
        [4, 4]])
ivy.native_array(x, /, *, dtype=None, device=None)[source]

Converts the input to a native array.

Parameters
  • x (Union[Array, NativeArray, List[Number], Tuple[Number]Union[Dtype, NativeDtype]]) – datatype, optional. Datatype is inferred from the input data. (default: None)

  • device (Optional[Union[Device, NativeDevice]]) – device on which to place the created array. Default: None. (default: None)

Return type

NativeArray

Returns

ret – A native array interpretation of x.

ivy.one_hot(indices, depth, /, *, on_value=None, off_value=None, axis=None, device=None, out=None)[source]

Returns a one-hot array. The locations represented by indices in the parameter indices take value on_value, while all other locations take value off_value.

Parameters
  • indices (Union[Array, NativeArray]) – Indices for where the ones should be scattered [batch_shape, dim]

  • depth (int) – Scalar defining the depth of the one-hot dimension.

  • on_value (Optional[Number]) – Scalar defining the value to fill in output when indices[j] == i. (default: None) Default: 1.

  • off_value (Optional[Number]) – Scalar defining the value to fill in output when indices[j] != i. (default: None) Default: 0.

  • axis (Optional[int]) – Axis to scatter on. The default is -1, a new inner-most axis is created. (default: None)

  • dtype – The data type of the output tensor.

  • device (Optional[Union[Device, NativeDevice]]) – device on which to create the array ‘cuda:0’, ‘cuda:1’, ‘cpu’ etc. Same as x if (default: None) None.

  • out (Optional[Array]) – optional output array, for writing the result to. It must have a shape that the (default: None) inputs broadcast to.

Return type

Array

Returns

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

ivy.ones(shape, *, dtype=None, device=None, out=None)[source]

Returns a new array having a specified shape and filled with ones.

Parameters
  • shape (Union[Shape, NativeShape]) – output array shape.

  • dtype (Optional[Union[Dtype, NativeDtype]]) – output array data type. If dtype is None, the output array data type (default: None) must be the default floating-point data type. Default None.

  • device (Optional[Union[Device, NativeDevice]]) – device on which to place the created array. Default: None. (default: None)

  • out (Optional[Array]) – optional output array, for writing the result to. It must have a shape that the (default: None) inputs broadcast to.

Return type

Array

Returns

ret – an array containing ones.

This function conforms to the Array API Standard. This docstring is an extension of the docstring in the standard.

Both the description and the type hints above assumes an array input for simplicity, but this function is nestable, and therefore also accepts ivy.Container instances in place of any of the arguments.

Examples

>>> shape = (2,2)
>>> y = ivy.ones(shape)
>>> print(y)
ivy.array([[1., 1.],
       [1., 1.]])
ivy.ones_like(x, /, *, dtype=None, device=None, out=None)[source]

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

Parameters
  • x (Union[Array, NativeArray]) – input array from which to derive the output array shape.

  • dtype (Optional[Union[Dtype, NativeDtype]]) – output array data type. If dtype is None, the output array data type (default: None) must be inferred from x. Default None.

  • device (Optional[Union[Device, NativeDevice]]) – device on which to place the created array. If device is None, the output (default: None) array device must be inferred from x. Default: None.

  • out (Optional[Array]) – optional output array, for writing the result to. It must have a shape that the (default: None) inputs broadcast to.

Return type

Array

Returns

ret – an array having the same shape as x and filled with ones.

This function conforms to the Array API Standard. This docstring is an extension of the docstring in the standard.

Both the description and the type hints above assumes an array input for simplicity, but this function is nestable, and therefore also accepts ivy.Container instances in place of any of the arguments.

Functional Examples

With ivy.Array input:

>>> x1 = ivy.array([1, 2, 3, 4, 5, 6])
>>> y1 = ivy.ones_like(x1)
>>> print(y1)
ivy.array([1, 1, 1, 1, 1, 1])
>>> x2 = ivy.array([[0, 1, 2],[3, 4, 5]], dtype = ivy.float32)
>>> y2 = ivy.ones_like(x2)
>>> print(y2)
ivy.array([[1., 1., 1.],
        [1., 1., 1.]])
>>> x3 = ivy.array([3., 2., 1.])
>>> y3 = ivy.zeros(3)
>>> ivy.ones_like(x3, out=y3)
ivy.array([1., 1., 1.])

With ivy.NativeArray input:

>>> x1 = ivy.native_array([[3, 8, 2],[2, 8, 3]])
>>> y1 = ivy.ones_like(x1)
>>> print(y1)
ivy.array([[1, 1, 1],[1, 1, 1]])
>>> x2 = ivy.native_array([3, 8, 2, 0, 0, 2])
>>> y2 = ivy.ones_like(x2, dtype=ivy.IntDtype('int32'), device=ivy.Device('cpu'))
>>> print(y2)
ivy.array([1, 1, 1, 1, 1, 1])

# Array y2 is now stored on the CPU.

With ivy.Container input:

>>> x = ivy.Container(a=ivy.array([3, 2, 1]), b=ivy.array([8, 2, 3]))
>>> y = ivy.ones_like(x)
>>> print(y)
{
    a: ivy.array([1, 1, 1]),
    b: ivy.array([1, 1, 1])
}

Instance Method Examples

With ivy.Array input:

>>> x = ivy.array([2, 3, 8, 2, 1])
>>> y = x.ones_like()
>>> print(y)
ivy.array([1, 1, 1, 1, 1])

With :class:’ivy.Container’ input:

>>> x = ivy.Container(a=ivy.array([3., 8.]), b=ivy.array([2., 2.]))
>>> y = x.ones_like()
>>> print(y)
{
    a: ivy.array([1., 1.]),
    b: ivy.array([1., 1.])
}
ivy.tril(x, /, *, k=0, out=None)[source]

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

Parameters
  • x (Union[Array, NativeArray]) – input array having shape (…, M, N) and whose innermost two dimensions form MxN matrices.

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

  • out (Optional[Array]) – optional output array, for writing the result to. It must have a shape that the (default: None) inputs broadcast to.

Return type

Array

Returns

ret – an array containing the lower triangular part(s). The returned array must have the same shape and data type as x. All elements above the specified diagonal k must be zeroed. The returned array should be allocated on the same device as x.

This function conforms to the Array API Standard. This docstring is an extension of the docstring in the standard.

Both the description and the type hints above assumes an array input for simplicity, but this function is nestable, and therefore also accepts ivy.Container instances in place of any of the arguments.

ivy.triu(x, /, *, k=0, out=None)[source]

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

Parameters
  • x (Union[Array, NativeArray]) – input array having shape (…, M, N) and whose innermost two dimensions form MxN matrices. *,

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

  • out (Optional[Array]) – optional output array, for writing the result to. It must have a shape that the (default: None) inputs broadcast to.

Return type

Array

Returns

ret – an array containing the upper triangular part(s). The returned array must have the same shape and data type as x. All elements below the specified diagonal k must be zeroed. The returned array should be allocated on the same device as x.

This function conforms to the Array API Standard. This docstring is an extension of the docstring in the standard.

Both the description and the type hints above assumes an array input for simplicity, but this function is nestable, and therefore also accepts ivy.Container instances in place of any of the arguments.

ivy.zeros(shape, *, dtype=None, device=None, out=None)[source]

Returns a new array having a specified shape and filled with zeros.

Parameters
  • shape (Union[Shape, NativeShape]) – output array shape.

  • dtype (Optional[Union[Dtype, NativeDtype]]) – output array data type. If dtype is None, the output array data type must (default: None) be the default floating-point data type. Default None.

  • device (Optional[Union[Device, NativeDevice]]) – device on which to place the created array. Default: None. (default: None)

  • out (Optional[Array]) – optional output array, for writing the result to. It must have a shape that the (default: None) inputs broadcast to.

Return type

Array

Returns

ret – an array containing zeros.

This function conforms to the Array API Standard. This docstring is an extension of the docstring in the standard.

Both the description and the type hints above assumes an array input for simplicity, but this function is nestable, and therefore also accepts ivy.Container instances in place of any of the arguments.

Examples

>>> shape = (3, 5)
>>> x = ivy.zeros(shape)
>>> print(x)
ivy.array([[0., 0., 0., 0., 0.],
       [0., 0., 0., 0., 0.],
       [0., 0., 0., 0., 0.]])
ivy.zeros_like(x, /, *, dtype=None, device=None, out=None)[source]

Returns a new array filled with zeros and having the same shape as an input array x.

Parameters
  • x (Union[Array, NativeArray]) – input array from which to derive the output array shape.

  • dtype (Optional[Union[Dtype, NativeDtype]]) – output array data type. If dtype is None, the output array data type (default: None) must be inferred from x. Default: None.

  • device (Optional[Union[Device, NativeDevice]]) – device on which to place the created array. If device is None, the (default: None) output array device must be inferred from x. Default: None.

  • out (Optional[Array]) – optional output array, for writing the result to. It must have a shape that the (default: None) inputs broadcast to.

Return type

Array

Returns

ret – an array having the same shape as x and filled with zeros.

This function conforms to the Array API Standard. This docstring is an extension of the docstring in the standard.

Both the description and the type hints above assumes an array input for simplicity, but this function is nestable, and therefore also accepts ivy.Container instances in place of any of the arguments.

Functional Examples

With ivy.Array input:

>>> x1 = ivy.array([1, 2, 3, 4, 5, 6])
>>> y1 = ivy.zeros_like(x1)
>>> print(y1)
ivy.array([0, 0, 0, 0, 0, 0])
>>> x2 = ivy.array([[0, 1, 2],[3, 4, 5]], dtype = ivy.float32)
>>> y2 = ivy.zeros_like(x2)
>>> print(y2)
ivy.array([[0., 0., 0.],
        [0., 0., 0.]])
>>> x3 = ivy.array([3., 2., 1.])
>>> y3 = ivy.ones(3)
>>> ivy.zeros_like(x3, out=y3)
ivy.array([0., 0., 0.])

With ivy.NativeArray input:

>>> x1 = ivy.native_array([[3, 8, 2],[2, 8, 3]])
>>> y1 = ivy.zeros_like(x1)
>>> print(y1)
ivy.array([[0, 0, 0],[0, 0, 0]])
>>> x2 = ivy.native_array([3, 8, 2, 0, 0, 2])
>>> y2 = ivy.zeros_like(x2, dtype=ivy.IntDtype('int32'), device=ivy.Device('cpu'))
>>> print(y2)
ivy.array([0, 0, 0, 0, 0, 0])

# Array y2 is now stored on the CPU.

With ivy.Container input:

>>> x = ivy.Container(a=ivy.array([3, 2, 1]), b=ivy.array([8, 2, 3]))
>>> y = ivy.zeros_like(x)
>>> print(y)
{
    a: ivy.array([0, 0, 0]),
    b: ivy.array([0, 0, 0])
}

Instance Method Examples

With ivy.Array input:

>>> x = ivy.array([2, 3, 8, 2, 1])
>>> y = x.zeros_like()
>>> print(y)
ivy.array([0, 0, 0, 0, 0])

With :class:’ivy.Container’ input:

>>> x = ivy.Container(a=ivy.array([3., 8.]), b=ivy.array([2., 2.]))
>>> y = x.zeros_like()
>>> print(y)
{
    a: ivy.array([0., 0.]),
    b: ivy.array([0., 0.])
}

This should have hopefully given you an overview of the creation submodule,If you have any questions, please feel free to reach out on our discord in the creation channel or in the creation forum!