Creation#

ivy.arange(start, /, stop=None, step=1, *, dtype=None, device=None, out=None)[source]#

Return 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], default: None) – the end of the interval. Default: None.
step (Number, default: 1) – the distance between two adjacent elements (out[i+1] - out[i]). Must not be 0; may be negative, this results in an empty array if stop >= start. Default: 1.
dtype (Optional[Union[Dtype, NativeDtype]], default: None) – output array data type. If dtype is None, the output array data type must be 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]], default: None) – device on which to place the created array. Default: None.
out (Optional[Array], default: None) – optional output array, for writing the result to. It must have a shape that the 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.

Examples

>>> stop = 5
>>> x = ivy.arange(stop)
>>> print(x)
ivy.array([0, 1, 2, 3, 4])

>>> start = 1
>>> stop = 5
>>> x = ivy.arange(start, stop)
>>> print(x)
ivy.array([1, 2, 3, 4])

>>> start = 1
>>> stop = 10
>>> step = 2
>>> x = ivy.arange(start, stop, step)
>>> print(x)
ivy.array([1, 3, 5, 7, 9])

>>> start = 1
>>> stop = 10
>>> step = 2
>>> dtype = "float64"
>>> device = "cpu"
>>> x = ivy.arange(start, stop, step, dtype=dtype, device=device)
>>> print(x, x.dtype, x.device)
ivy.array([1., 3., 5., 7., 9.]) float64 cpu

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

Convert the input to an array.

Parameters:

obj (Union[Array, NativeArray, Shape, NativeShape, bool, int, float, NestedSequence, TypeVar(SupportsBufferProtocol), ndarray]) – 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], default: None) – boolean, indicating whether or not to copy the input. Default: None.
dtype (Optional[Union[Dtype, NativeDtype]], default: None) – output array data type. If dtype is None, the output array data type must be the default floating-point data type. Default None.
device (Optional[Union[Device, NativeDevice]], default: None) – device on which to place the created array. Default: None.
out (Optional[Array], default: None) – optional output array, for writing the result to. It must have a shape that the inputs broadcast to.

Return type:

Array

Returns:

ret – An array interpretation of x.

Examples

With list of lists as input:

>>> ivy.asarray([[1,2],[3,4]])
ivy.array([[1, 2],
           [3, 4]])

With tuple of lists as input:

>>> ivy.asarray(([1.4,5.6,5.5],[3.1,9.1,7.5]))
ivy.array([[1.39999998, 5.5999999 , 5.5       ],
           [3.0999999 , 9.10000038, 7.5       ]])

With ndarray as input:

>>> x = ivy.np.ndarray(shape=(2,2), order='C')
>>> ivy.asarray(x)
ivy.array([[6.90786433e-310, 6.90786433e-310],
           [6.90786433e-310, 6.90786433e-310]])

With ivy.Container as input:

>>> x = ivy.Container(a = [(1,2),(3,4),(5,6)], b = ((1,2,3),(4,5,6)))
>>> ivy.asarray(x)
{
    a: ivy.array([[1, 2],[3, 4], [5, 6]]),
    b: ivy.array([[1, 2, 3],
               [4, 5, 6]])
}

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

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

Convert the input to an array.

Parameters:

obj (Union[Array, NativeArray, Shape, NativeShape, bool, int, float, NestedSequence, TypeVar(SupportsBufferProtocol), ndarray]) – 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], default: None) – boolean, indicating whether or not to copy the input. Default: None.
dtype (Optional[Union[Dtype, NativeDtype]], default: None) – output array data type. If dtype is None, the output array data type must be the default floating-point data type. Default None.
device (Optional[Union[Device, NativeDevice]], default: None) – device on which to place the created array. Default: None.
out (Optional[Array], default: None) – optional output array, for writing the result to. It must have a shape that the inputs broadcast to.

Return type:

Array

Returns:

ret – An array interpretation of x.

Examples

With list of lists as input:

>>> ivy.asarray([[1,2],[3,4]])
ivy.array([[1, 2],
           [3, 4]])

With tuple of lists as input:

>>> ivy.asarray(([1.4,5.6,5.5],[3.1,9.1,7.5]))
ivy.array([[1.39999998, 5.5999999 , 5.5       ],
           [3.0999999 , 9.10000038, 7.5       ]])

With ndarray as input:

>>> x = ivy.np.ndarray(shape=(2,2), order='C')
>>> ivy.asarray(x)
ivy.array([[6.90786433e-310, 6.90786433e-310],
           [6.90786433e-310, 6.90786433e-310]])

With ivy.Container as input:

>>> x = ivy.Container(a = [(1,2),(3,4),(5,6)], b = ((1,2,3),(4,5,6)))
>>> ivy.asarray(x)
{
    a: ivy.array([[1, 2],[3, 4], [5, 6]]),
    b: ivy.array([[1, 2, 3],
               [4, 5, 6]])
}

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

ivy.complex(real, imag, *, out=None)[source]#

Returns a complex array formed by combining a real and an imaginary component element-wise. The real and imaginary components must have the same shape.

Parameters:

real (Union[Array, NativeArray]) – An array representing the real part of the complex numbers.
imag (Union[Array, NativeArray]) – An array representing the imaginary part of the complex numbers.
out (Optional[Array], default: None) – optional output array, for writing the result to. It must have a shape that the inputs broadcast to.

Return type:

Array

Returns:

ret – A complex array where each element is formed by combining the corresponding elements of real and imag.

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

Examples

>>> real = ivy.array([2.25, 3.25])
>>> imag = ivy.array([4.75, 5.75])
>>> x = ivy.complex(real, imag)
>>> print(x)
ivy.array([2.25+4.75j, 3.25+5.75j])

>>> real = ivy.array(1.)
>>> imag = ivy.array(2.)
>>> x = ivy.complex(real, imag)
>>> print(x)
ivy.array(1.+2.j)

>>> real = ivy.array([1., 2.])
>>> imag = ivy.array([3., 4.])
>>> x = ivy.complex(real, imag)
>>> print(x)
ivy.array([1.+3.j, 2.+4.j])

ivy.copy_array(x, /, *, to_ivy_array=True, out=None)[source]#

Copy an array.

Parameters:

x (Union[Array, NativeArray]) – array, input array containing elements to copy.
to_ivy_array (bool, default: True) – boolean, if True the returned array will be an ivy.Array object otherwise returns an ivy.NativeArray object (i.e. a torch.tensor, np.array, etc., depending on the backend), defaults to True.
out (Optional[Array], default: None) – optional output array, for writing the result to. It must have a shape that the 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]], default: None) – output array data type. If dtype is None, the output array data type must be the default floating-point data type. Default: None.
device (Optional[Union[Device, NativeDevice]], default: None) – device on which to place the created array. Default: None.
out (Optional[Array], default: None) – optional output array, for writing the result to. It must have a shape that the 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.

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

Return 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]], default: None) – output array data type. If dtype is None, the output array data type must be inferred from x. Default: None.
device (Optional[Union[Device, NativeDevice]], default: None) – device on which to place the created array. If device is None, the output array device must be inferred from x. Default: None.
out (Optional[Array], default: None) – optional output array, for writing the result to. It must have a shape that the 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.

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

Return 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], default: None) – number of columns in the output array. If None, the default number of columns in the output array is equal to n_rows. Default: None.
k (int, default: 0) – index of the diagonal. A positive value refers to an upper diagonal, a negative value to a lower diagonal, and 0 to the main diagonal. Default: 0.
batch_shape (Optional[Union[int, Sequence[int]]], default: None) – optional input that determines returning identity array shape. Default: None.
dtype (Optional[Union[Dtype, NativeDtype]], default: None) – output array data type. If dtype is None, the output array data type must be the default floating-point data type. Default: None.
device (Optional[Union[Device, NativeDevice]], default: None) – the device on which to place the created array.
out (Optional[Array], default: None) – optional output array, for writing the result to. It must have a shape that the 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 as a replacement to any of the arguments.

Examples

With :’n_rows’ input:

>>> x = ivy.eye(3)
>>> print(x)
ivy.array([[1., 0., 0.],
           [0., 1., 0.],
           [0., 0., 1.]])

With :’n_cols’ input:

>>> x = ivy.eye(3,4)
>>> print(x)
ivy.array([[1., 0., 0., 0.],
           [0., 1., 0., 0.],
           [0., 0., 1., 0.]])

With :’k’ input:

>>> x = ivy.eye(3, k=1)
>>> print(x)
ivy.array([[0., 1., 0.],
           [0., 0., 1.],
           [0., 0., 0.]])

With :’dtype’ input:

>>> x = ivy.eye(4, k=2, dtype=ivy.IntDtype('int32'))
>>> print(x)
ivy.array([[0, 0, 1, 0],
           [0, 0, 0, 1],
           [0, 0, 0, 0],
           [0, 0, 0, 0]])

With :’batch_shape’ input:

>>> x = ivy.eye(2, 3, batch_shape=[3])
>>> print(x)
ivy.array([[[1., 0., 0.],
            [0., 1., 0.]],

[[1., 0., 0.], [0., 1., 0.]],

[[1., 0., 0.], [0., 1., 0.]]])

With :’out’ input:

>>> y = ivy.ones((3, 3))
>>> ivy.eye(3, out=y)
>>> print(y)
ivy.array([[1., 0., 0.],
           [0., 1., 0.],
           [0., 0., 1.]])

With :’device’ input:

>>> x = ivy.eye(3, device=ivy.Device('cpu'))
>>> print(x)
ivy.array([[1., 0., 0.],
           [0., 1., 0.],
           [0., 0., 1.]])

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

Return a new array containing the data from another (array) object with a __dlpack__ method or PyCapsule Object.

Parameters:

object (x) – input (array) object with a __dlpack__ method or PyCapsule Object.
out (Optional[Array], default: None) – optional output array, for writing the result to. It must have a shape that the 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.

ivy.frombuffer(buffer, dtype=None, count=-1, offset=0)[source]#

Interpret a buffer as a 1-dimensional array.

Note

Note that either of the following must be true: 1. count is a positive non-zero number, and the total number of bytes in the buffer is equal or greater than offset plus count times the size (in bytes) of dtype. 2. count is negative, and the length (number of bytes) of the buffer subtracted by the offset is a multiple of the size (in bytes) of dtype.

Parameters:

buffer (bytes) – An object that exposes the buffer interface.
dtype (Optional[Union[Dtype, NativeDtype]], default: None) – Data-type of the returned array; default: float.
count (Optional[int], default: -1) – Number of items to read. -1 means all data in the buffer.
offset (Optional[int], default: 0) – Start reading the buffer from this offset (in bytes); default: 0.

Return type:

Array

Returns:

out – 1-dimensional array.

Examples

With bytes inputs:

>>> x = b'\x00\x00\x00\x00\x00\x00\xf0?\x00\x00\x00\x00\x00\x00\x00@'
>>> y = ivy.frombuffer(x, dtype=ivy.float64)
>>> print(y)
ivy.array([1., 2.])

>>> x = b'\x01\x02\x03\x04'
>>> y = ivy.frombuffer(x, dtype='int8', count=-2, offset=1)
>>> print(y)
ivy.array([2, 3, 4])

>>> x = b'\x00<\x00@\x00B\x00D\x00E'
>>> y = ivy.frombuffer(x, dtype='float16', count=4, offset=2)
>>> print(y)
ivy.array([2., 3., 4., 5.])

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

Return 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]], default: None) – output array data type. If dtype is None, the output array data type must 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]], default: None) – device on which to place the created array. Default: None.
out (Optional[Array], default: None) – optional output array, for writing the result to. It must have a shape that the 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.

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]#

Return 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 (Number) – Scalar fill value
dtype (Optional[Union[Dtype, NativeDtype]], default: None) – output array data type. If dtype is None, the output array data type must be inferred from x. Default: None.
device (Optional[Union[Device, NativeDevice]], default: None) – device on which to place the created array. If device is None, the output array device must be inferred from x. Default: None.
out (Optional[Array], default: None) – optional output array, for writing the result to. It must have a shape that the 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.

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]#

Generate 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], default: None) – Axis along which the operation is performed.
endpoint (bool, default: True) – If True, stop is the last sample. Otherwise, it is not included.
dtype (Optional[Union[Dtype, NativeDtype]], default: None) – output array data type.
device (Optional[Union[Device, NativeDevice]], default: None) – device on which to create the array ‘cuda:0’, ‘cuda:1’, ‘cpu’ etc.
out (Optional[Array], default: None) – optional output array, for writing the result to. It must have a shape that the 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.

Examples

With float input:

>>> x = ivy.linspace(1, 2, 3)
>>> print(x)
ivy.array([1. , 1.5, 2. ])

>>> x = ivy.linspace(1, 2, 4, endpoint=False)
>>> print(x)
ivy.array([1., 1.25, 1.5 , 1.75])

>>> x = ivy.linspace(1, 10, 4, dtype="int32")
>>> print(x)
ivy.array([ 1,  4,  7, 10])

>>> x = ivy.linspace(1, 2, 4, device= "cpu")
>>> print(x)
ivy.array([1., 1.33333337, 1.66666663, 2.])

>>> y = ivy.array([0,0,0,0])
>>> ivy.linspace(1, 2, 4, out= y)
>>> print(y)
ivy.array([1, 1, 1, 2])

With ivy.Array input:

>>> x = ivy.array([1,2])
>>> y = ivy.array([4,5])
>>> z = ivy.linspace(x, y, 4, axis = 0)
>>> print(z)
ivy.array([[1, 2],
           [2, 3],
           [3, 4],
           [4, 5]])

ivy.logspace(start, stop, /, num, *, base=10.0, axis=0, endpoint=True, dtype=None, device=None, out=None)[source]#

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

Parameters:

start (Union[Array, NativeArray, float]) – First value in the range in log space. base ** start is the starting value in the sequence. Can be an array or a float.
stop (Union[Array, NativeArray, float]) – Last value in the range in log space. base ** stop is the final value in the sequence. Can be an array or a float.
num (int) – Number of values to generate.
base (float, default: 10.0) – The base of the log space. Default is 10.0
axis (int, default: 0) – Axis along which the operation is performed. Relevant only if start or stop are array-like. Default is 0.
endpoint (bool, default: True) – If True, stop is the last sample. Otherwise, it is not included. Default is True.
dtype (Optional[Union[Dtype, NativeDtype]], default: None) – The data type of the output tensor. If None, the dtype of on_value is used or if that is None, the dtype of off_value is used, or if that is None, defaults to float32. Default is None.
device (Optional[Union[Device, NativeDevice]], default: None) – device on which to create the array ‘cuda:0’, ‘cuda:1’, ‘cpu’ etc. Default is None.
out (Optional[Array], default: None) – optional output array, for writing the result to. It must have a shape that the inputs broadcast to. Default is None.

Return type:

Array

Returns:

ret – Tensor of evenly-spaced values in log space.
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

With float input:

>>> print(ivy.logspace(1, 2, 4))
ivy.array([ 10., 21.5443469, 46.41588834, 100.])

>>> print(ivy.logspace(1, 2, 4, endpoint=False))
ivy.array([10., 17.7827941, 31.6227766, 56.23413252])

>>> print(ivy.logspace(1, 2, 4, dtype= int))
ivy.array([ 10.,  10.,  10., 100.])

>>> out = ivy.array([0,0,0,0])
>>> ivy.logspace(1, 2, 4, out = out)
>>> print(out)
ivy.array([ 10,  21,  46, 100])

With ivy.Array input: >>> x = ivy.array([1, 2]) >>> y = ivy.array([4, 5]) >>> print(ivy.logspace(x, y, 4)) ivy.array([[1.e+01, 1.e+02],

[1.e+02, 1.e+03], [1.e+03, 1.e+04], [1.e+04, 1.e+05])

>>> x = ivy.array([1, 2])
>>> y = ivy.array([4, 5])
>>> print(ivy.logspace(x, y, 4, axis = 1))
ivy.array([[[1.e+01, 1.e+02, 1.e+03, 1.e+04],
           [1.e+02, 1.e+03, 1.e+04, 1.e+05]]])

>>> x = ivy.array([1, 2])
>>> y = ivy.array([4])
>>> print(ivy.logspace(x, y, 4))
ivy.array([[   10.,   100.],
       [  100.,   100.],
       [ 1000.,  1000.],
       [10000., 10000.]])

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

Return 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, default: False) – if True, a sparse grid is returned in order to conserve memory. Default: False.
indexing (str, default: 'xy') – 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'.

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.

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]#

Convert the input to a native array.

Parameters:

x (Union[Array, NativeArray, List[Number], Tuple[Number], ndarray]) – 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.
dtype (Optional[Union[Dtype, NativeDtype]], default: None) – datatype, optional. Datatype is inferred from the input data.
device (Optional[Union[Device, NativeDevice]], default: None) – device on which to place the created array. Default: None.

Return type:

NativeArray

Returns:

ret – A native array interpretation of x.

Examples

With List[Number] input:

>>> x = [1, 2, 3]
>>> x_native = ivy.native_array(x)
>>> print(x_native)
[1 2 3]

With np.ndarray input: >>> y = np.array([4, 5, 6]) >>> y_native = ivy.native_array(y) >>> print(y_native) [4 5 6]

With ivy.Array input: >>> z = ivy.array([7, 8, 9]) >>> z_native = ivy.native_array(z) >>> print(z_native) [7 8 9]

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

Return 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], default: None) – Scalar defining the value to fill in output when indices[j] == i. Default: 1.
off_value (Optional[Number], default: None) – Scalar defining the value to fill in output when indices[j] != i. Default: 0.
axis (Optional[int], default: None) – Axis to scatter on. The default is -1, a new inner-most axis is created.
dtype (Optional[Union[Dtype, NativeDtype]], default: None) – The data type of the output tensor.
device (Optional[Union[Device, NativeDevice]], default: None) – device on which to create the array ‘cuda:0’, ‘cuda:1’, ‘cpu’ etc. Same as x if None.
out (Optional[Array], default: None) – optional output array, for writing the result to. It must have a shape that the inputs broadcast to.

Return type:

Array

Returns:

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

Examples

With ivy.Array inputs:

>>> x = ivy.array([3, 1])
>>> y = 5
>>> z = x.one_hot(5)
>>> print(z)
ivy.array([[0., 0., 0., 1., 0.],
...    [0., 1., 0., 0., 0.]])

>>> x = ivy.array([0])
>>> y = 5
>>> ivy.one_hot(x, y)
ivy.array([[1., 0., 0., 0., 0.]])

>>> x = ivy.array([0])
>>> y = 5
>>> ivy.one_hot(x, 5, out=z)
ivy.array([[1., 0., 0., 0., 0.]])
>>> print(z)
ivy.array([[1., 0., 0., 0., 0.]])

With ivy.Container input:

>>> x = ivy.Container(a=ivy.array([1, 2]),         b=ivy.array([3, 1]), c=ivy.array([2, 3]))
>>> y = 5
>>> z = x.one_hot(y)
>>> print(z)
{
    a: ivy.array([[0., 1., 0., 0., 0.],
                [0., 0., 1., 0., 0.]]),
    b: ivy.array([[0., 0., 0., 1., 0.],
                [0., 1., 0., 0., 0.]]),
    c: ivy.array([[0., 0., 1., 0., 0.],
                [0., 0., 0., 1., 0.]])
}

>>> x = ivy.Container(a=ivy.array([2]),         b=ivy.array([], dtype=ivy.int32), c=ivy.native_array([4]))
>>> y = 7
>>> z = x.one_hot(y)
>>> print(z)
{
    a: ivy.array([[0., 0., 1., 0., 0., 0., 0.]]),
    b: ivy.array([], shape=(0, 7)),
    c: ivy.array([[0., 0., 0., 0., 1., 0., 0.]])
}

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

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

Note

An output array having a complex floating-point data type must contain complex numbers having a real component equal to one and an imaginary component equal to zero (i.e., 1 + 0j).

Parameters:

shape (Union[Shape, NativeShape]) – output array shape.
dtype (Optional[Union[Dtype, NativeDtype]], default: None) – output array data type. If dtype is None, the output array data type must be the default floating-point data type. Default None.
device (Optional[Union[Device, NativeDevice]], default: None) – device on which to place the created array. Default: None.
out (Optional[Array], default: None) – optional output array, for writing the result to. It must have a shape that the 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.

Examples

With ivy.Shape input:

>>> shape = (2,2)
>>> x = ivy.ones(shape)
>>> print(x)
ivy.array([[1., 1.],
       [1., 1.]])

With ivy.Dtype input:

>>> shape = (3,2)
>>> d_type = ivy.int64
>>> y = ivy.ones(shape, dtype=d_type)
>>> print(y)
ivy.array([[1, 1],
       [1, 1],
       [1, 1]])

With ivy.Device input:

>>> shape = (3,2)
>>> y = ivy.ones(shape, device="cpu")
>>> print(y)
ivy.array([[1., 1.],
       [1., 1.],
       [1., 1.]])

With ivy.Array input:

>>> shape = (1, 5, 2)
>>> x = ivy.zeros(shape)
>>> ivy.ones(shape, out=x)
>>> print(x)
ivy.array([[[1., 1.],
        [1., 1.],
        [1., 1.],
        [1., 1.],
        [1., 1.]]])

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

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

Note

An output array having a complex floating-point data type must contain complex numbers having a real component equal to one and an imaginary component equal to zero (i.e., 1 + 0j).

Parameters:

x (Union[Array, NativeArray]) – input array from which to derive the output array shape.
dtype (Optional[Union[Dtype, NativeDtype]], default: None) – output array data type. If dtype is None, the output array data type must be inferred from x. Default None.
device (Optional[Union[Device, NativeDevice]], default: None) – device on which to place the created array. If device is None, the output array device must be inferred from x. Default: None.
out (Optional[Array], default: None) – optional output array, for writing the result to. It must have a shape that the 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.

Examples

With ivy.Array input:

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

>>> x = ivy.array([[0, 1, 2],[3, 4, 5]], dtype = ivy.float32)
>>> y = ivy.ones_like(x)
>>> print(y)
ivy.array([[1., 1., 1.],
       [1., 1., 1.]])

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

With ivy.NativeArray input:

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

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

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])
}

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.to_dlpack(x, /, *, out=None)[source]#

Return PyCapsule Object.

Parameters:

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

Returns:

ret – Return PyCapsule Object.

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.

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

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

Note

The main diagonal is defined as the set of indices {(i, i)} for i on the interval [0, min(M, N) - 1].

Parameters:

x (Union[Array, NativeArray]) – input array having shape (…, M, N) and whose innermost two dimensions form MxN matrices.
k (int, default: 0) – diagonal above which to zero elements. 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.
out (Optional[Array], default: None) – optional output array, for writing the result to. It must have a shape that the 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.

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

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

Note

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

Parameters:

x (Union[Array, NativeArray]) – input array having shape (…, M, N) and whose innermost two dimensions form MxN matrices. *,
k (int, default: 0) – diagonal below which to zero elements. 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.
out (Optional[Array], default: None) – optional output array, for writing the result to. It must have a shape that the 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.

ivy.triu_indices(n_rows, n_cols=None, k=0, /, *, device=None)[source]#

Return the indices of the upper triangular part of a row by col matrix in a 2-by-N shape (tuple of two N dimensional arrays), where the first row contains row coordinates of all indices and the second row contains column coordinates. Indices are ordered based on rows and then columns. The upper triangular part of the matrix is defined as the elements on and above the diagonal. The argument k controls which diagonal to consider. If k = 0, all elements on and above the main diagonal are retained. A positive value excludes just as many diagonals above the main diagonal, and similarly a negative value includes just as many diagonals below the main diagonal. The main diagonal are the set of indices {(i,i)} for i∈[0,min{n_rows, n_cols}−1].

Notes

Primary purpose of this function is to slice an array of shape (n,m). See https://numpy.org/doc/stable/reference/generated/numpy.triu_indices.html for examples

Tensorflow does not support slicing 2-D tensor with tuple of tensor of indices

Parameters:

n_rows (int) – number of rows in the 2-d matrix.
n_cols (Optional[int], default: None) – number of columns in the 2-d matrix. If None n_cols will be the same as n_rows
k (int, default: 0) – number of shifts from the main diagonal. k = 0 includes main diagonal, k > 0 moves upwards and k < 0 moves downwards
device (Optional[Union[Device, NativeDevice]], default: None) – device on which to place the created array. Default: None.

Return type:

Tuple[Array]

Returns:

ret – an 2xN shape, tuple of two N dimensional, where first subarray (i.e. ret[0]) contains row coordinates of all indices and the second subarray (i.e ret[1]) contains columns indices.
Function is nestable, and therefore also accepts ivy.Container
instances in place of any of the arguments.

Examples

>>> x = ivy.triu_indices(4,4,0)
>>> print(x)
(ivy.array([0, 0, 0, 0, 1, 1, 1, 2, 2, 3]),
ivy.array([0, 1, 2, 3, 1, 2, 3, 2, 3, 3]))

>>> x = ivy.triu_indices(4,4,1)
>>> print(x)
(ivy.array([0, 0, 0, 1, 1, 2]),
ivy.array([1, 2, 3, 2, 3, 3]))

>>> x = ivy.triu_indices(4,4,-2)
>>> print(x)
(ivy.array([0, 0, 0, 0, 1, 1, 1, 1, 2, 2, 2, 2, 3, 3, 3]),
ivy.array([0, 1, 2, 3, 0, 1, 2, 3, 0, 1, 2, 3, 1, 2, 3]))

>>> x = ivy.triu_indices(4,2,0)
>>> print(x)
(ivy.array([0, 0, 1]),
ivy.array([0, 1, 1]))

>>> x = ivy.triu_indices(2,4,0)
>>> print(x)
(ivy.array([0, 0, 0, 0, 1, 1, 1]),
ivy.array([0, 1, 2, 3, 1, 2, 3]))

>>> x = ivy.triu_indices(4,-4,0)
>>> print(x)
(ivy.array([]), ivy.array([]))

>>> x = ivy.triu_indices(4,4,100)
>>> print(x)
(ivy.array([]), ivy.array([]))

>>> x = ivy.triu_indices(2,4,-100)
>>> print(x)
(ivy.array([0, 0, 0, 0, 1, 1, 1, 1]), ivy.array([0, 1, 2, 3, 0, 1, 2, 3]))

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

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

Parameters:

shape (Union[Shape, NativeShape]) – output array shape.
dtype (Optional[Union[Dtype, NativeDtype]], default: None) – output array data type. If dtype is None, the output array data type must be the default floating-point data type. Default None.
device (Optional[Union[Device, NativeDevice]], default: None) – device on which to place the created array. Default: None.
out (Optional[Array], default: None) – optional output array, for writing the result to. It must have a shape that the 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.

Examples

With ivy.NativeShape input: >>> 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.]])

>>> x = ivy.zeros(5)
>>> print(x)
ivy.array([0., 0., 0., 0., 0.])

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

Return 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]], default: None) – output array data type. If dtype is None, the output array data type must be inferred from x. Default: None.
device (Optional[Union[Device, NativeDevice]], default: None) – device on which to place the created array. If device is None, the output array device must be inferred from x. Default: None.
out (Optional[Array], default: None) – optional output array, for writing the result to. It must have a shape that the 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.

Examples

With ivy.Array input:

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

>>> x = ivy.array([[0, 1, 2],[3, 4, 5]], dtype = ivy.float32)
>>> y = ivy.zeros_like(x)
>>> print(y)
ivy.array([[0., 0., 0.],
        [0., 0., 0.]])

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

With ivy.NativeArray input:

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

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

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])
}

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.])
}

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

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!