trace#

ivy.trace(x, /, *, offset=0, axis1=0, axis2=1, out=None)[source]#

Return the sum along the specified diagonals of a matrix (or a stack of matrices) x.

Special cases

Let N equal the number of elements over which to compute the sum.

If N is 0, the sum is 0 (i.e., the empty sum).

For both real-valued and complex floating-point operands, special cases must be handled as if the operation is implemented by successive application of ivy.add():

Parameters:

x (Union[Array, NativeArray]) – input array having shape (..., M, N) and whose innermost two dimensions form MxN matrices. Should have a numeric data type.
offset (int, default: 0) –
offset specifying the off-diagonal relative to the main diagonal. - offset = 0: the main diagonal. - offset > 0: off-diagonal above the main diagonal. - offset < 0: off-diagonal below the main diagonal.

Default: 0.
axis1 (int, default: 0) – axis to be used as the first axis of the 2-D sub-arrays from which the diagonals should be taken. Defaults to 0. .
axis2 (int, default: 1) – axis to be used as the second axis of the 2-D sub-arrays from which the diagonals should be taken. Defaults to 1. .
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 traces and whose shape is determined by removing the last two dimensions and storing the traces in the last array dimension. For example, if x has rank k and shape (I, J, K, ..., L, M, N), then an output array has rank k-2 and shape (I, J, K, ..., L) where

out[i, j, k, ..., l] = trace(a[i, j, k, ..., l, :, :])

The returned array must have the same data type as x.

Examples

With ivy.Array inputs:

>>> x = ivy.array([[2., 0., 3.],
...                [3., 5., 6.]])
>>> y = ivy.trace(x, offset=0)
>>> print(y)
ivy.array(7.)

>>> x = ivy.array([[[1., 2.],
...                 [3., 4.]],
...                [[5., 6.],
...                 [7., 8.]]])
>>> y = ivy.trace(x, offset=1)
>>> print(y)
ivy.array([3., 4.])

>>> x = ivy.array([[1., 2., 3.],
...                [4., 5., 6.],
...                [7., 8., 9.]])
>>> y = ivy.zeros(1)
>>> ivy.trace(x, offset=1,out=y)
>>> print(y)
ivy.array(8.)

With ivy.NativeArray inputs:

>>> x = ivy.native_array([[2., 0., 3.],[3., 5., 6.]])
>>> y = ivy.trace(x, offset=0)
>>> print(y)
ivy.array(7.)

>>> x = ivy.native_array([[0, 1, 2],
...                       [3, 4, 5],
...                       [6, 7, 8]])
>>> y = ivy.trace(x, offset=1)
>>> print(y)
ivy.array(6)

With ivy.Container inputs:

>>> x = ivy.Container(
...        a = ivy.array([[7, 1, 2],
...                       [1, 3, 5],
...                       [0, 7, 4]]),
...        b = ivy.array([[4, 3, 2],
...                       [1, 9, 5],
...                       [7, 0, 6]])
...    )
>>> y = ivy.trace(x, offset=0)
>>> print(y)
{
    a: ivy.array(14),
    b: ivy.array(19)
}

>>> x = ivy.Container(
...        a = ivy.array([[7, 1, 2],
...                       [1, 3, 5],
...                       [0, 7, 4]]),
...        b = ivy.array([[4, 3, 2],
...                       [1, 9, 5],
...                       [7, 0, 6]])
...    )
>>> y = ivy.trace(x, offset=1)
>>> print(y)
{
    a: ivy.array(6),
    b: ivy.array(8)
}

With multiple ivy.Container inputs:

>>> x = ivy.Container(
...        a = ivy.array([[7, 1, 3],
...                       [8, 6, 5],
...                       [9, 7, 2]]),
...        b = ivy.array([[4, 3, 2],
...                       [1, 9, 5],
...                       [7, 0, 6]])
...    )
>>> offset = ivy.Container(a=1, b=0)
>>> y = ivy.trace(x, offset)
>>> print(y)
{
    a: ivy.array(6),
    b: ivy.array(19)
}

With Array instance method example:

>>> x = ivy.array([[2., 0., 11.],
...                [3., 5., 12.],
...                [1., 6., 13.],
...                [8., 9., 14.]])
>>> y = x.trace(offset=1)
>>> print(y)
ivy.array(12.)

With Container instance method example:

>>> x = ivy.Container(
...        a=ivy.array([[2., 0., 11.],
...                     [3., 5., 12.]]),
...        b=ivy.array([[1., 6., 13.],
...                     [8., 9., 14.]])
...    )
>>> y = x.trace(offset=0)
>>> print(y)
{
    a: ivy.array(7.),
    b: ivy.array(10.)
}

Array.trace(self, /, *, offset=0, axis1=0, axis2=1, out=None)[source]#

ivy.Array instance method variant of ivy.trace. This method Returns the sum along the specified diagonals of a matrix (or a stack of matrices).

Parameters:

self (Array) – input array having shape (..., M, N) and whose innermost two dimensions form MxN matrices. Should have a floating-point data type.
offset (int, default: 0) – Offset of the diagonal from the main diagonal. Can be both positive and negative. Defaults to 0.
axis1 (int, default: 0) – axis to be used as the first axis of the 2-D sub-arrays from which the diagonals should be taken. Defaults to 0. .
axis2 (int, default: 1) – axis to be used as the second axis of the 2-D sub-arrays from which the diagonals should be taken. Defaults to 1. .
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:

out[i, j, k, …, l] = trace(a[i, j, k, …, l, :, :])

The returned array must have the same data type as x.

Examples

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

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

Container.trace(self, /, *, offset=0, axis1=0, axis2=1, key_chains=None, to_apply=True, prune_unapplied=False, map_sequences=False, out=None)[source]#

ivy.Container instance method variant of ivy.trace. This method Returns the sum along the specified diagonals of a matrix (or a stack of matrices).

Parameters:

self (Container) – input container having shape (..., M, N) and whose innermost two dimensions form MxN matrices. Should have a floating-point data type.
offset (Union[int, Container], default: 0) – Offset of the diagonal from the main diagonal. Can be both positive and negative. Defaults to 0.
axis1 (Union[int, Container], default: 0) – axis to be used as the first axis of the 2-D sub-arrays from which the diagonals should be taken. Defaults to 0. .
axis2 (Union[int, Container], default: 1) – axis to be used as the second axis of the 2-D sub-arrays from which the diagonals should be taken. Defaults to 1. .
key_chains (Optional[Union[List[str], Dict[str, str], Container]], default: None) – The key-chains to apply or not apply the method to. Default is None.
to_apply (Union[bool, Container], default: True) – If True, the method will be applied to key_chains, otherwise key_chains will be skipped. Default is True.
prune_unapplied (Union[bool, Container], default: False) – Whether to prune key_chains for which the function was not applied. Default is False.
map_sequences (Union[bool, Container], default: False) – Whether to also map method to sequences (lists, tuples). Default is False.
out (Optional[Container], default: None) – optional output array, for writing the result to. It must have a shape that the inputs broadcast to.

Return type:

Container

Returns:

ret – a container containing the traces and whose shape is determined by removing the last two dimensions and storing the traces in the last array dimension. For example, if x has rank k and shape (I, J, K, ..., L, M, N), then an output array has rank k-2 and shape (I, J, K, ..., L) where

out[i, j, k, …, l] = trace(a[i, j, k, …, l, :, :])

The returned array must have the same data type as x.

Examples

With ivy.Container input: >>> x = ivy.Container( … a = ivy.array([[7, 1, 2], … [1, 3, 5], … [0, 7, 4]]), … b = ivy.array([[4, 3, 2], … [1, 9, 5], … [7, 0, 6]])) >>> y = x.trace() >>> print(y) {

a: ivy.array(14), b: ivy.array(19)

}