eye#

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

  • batch_shape (Optional[Union[int, Sequence[int]]]) – optional input that determines returning identity array shape. (default: None) Default: None.

  • 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]]) – the 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 # noqa 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.

Functional Examples

With :’n_rows’ input:

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

With :’n_cols’ input:

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

With :’k’ input:

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

With :’dtype’ input:

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

With :’batch_shape’ input:

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

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

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

>>> x1.shape
(3, 2, 3)
# Suppose batch_shape = [a, b] then the returning identity array shape is [a, b, numRows, numColumns]

With :’out’ input:

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

With :’device’ input:

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

# Array x1 is now stored on the CPU.