dpnp.linalg.diagonal¶

dpnp.linalg.diagonal(x, /, *, offset=0)[source]¶

Returns specified diagonals of a matrix (or a stack of matrices) x.

This function is Array API compatible, contrary to dpnp.diagonal the matrix is assumed to be defined by the last two dimensions.

For full documentation refer to numpy.linalg.diagonal.

Parameters:

x(..., M, N) {dpnp.ndarray, usm_ndarray}

Input array having shape (..., M, N) and whose innermost two dimensions form MxN matrices.

offsetint, optional

Offset specifying the off-diagonal relative to the main diagonal, where:

offset = 0: the main diagonal.

offset > 0: off-diagonal above the main diagonal.

offset < 0: off-diagonal below the main diagonal.

Default: 0.

Returns:

out(...,min(N, M)) dpnp.ndarray: An array containing the diagonals and whose shape is determined by removing the last two dimensions and appending a dimension equal to the size of the resulting diagonals. The returned array must have the same data type as x.

See also

dpnp.diagonal: Similar function with support for more keyword arguments.

Examples

>>> import dpnp as np
>>> a = np.arange(4).reshape(2, 2); a
array([[0, 1],
       [2, 3]])
>>> np.linalg.diagonal(a)
array([0, 3])

A 3-D example:

>>> a = np.arange(8).reshape(2, 2, 2); a
array([[[0, 1],
        [2, 3]],
       [[4, 5],
        [6, 7]]])
>>> np.linalg.diagonal(a)
array([[0, 3],
       [4, 7]])

Diagonals adjacent to the main diagonal can be obtained by using the offset argument:

>>> a = np.arange(9).reshape(3, 3)
>>> a
array([[0, 1, 2],
       [3, 4, 5],
       [6, 7, 8]])
>>> np.linalg.diagonal(a, offset=1)  # First superdiagonal
array([1, 5])
>>> np.linalg.diagonal(a, offset=2)  # Second superdiagonal
array([2])
>>> np.linalg.diagonal(a, offset=-1)  # First subdiagonal
array([3, 7])
>>> np.linalg.diagonal(a, offset=-2)  # Second subdiagonal
array([6])

The anti-diagonal can be obtained by reversing the order of elements using either dpnp.flipud or dpnp.fliplr.

>>> a = np.arange(9).reshape(3, 3)
>>> a
array([[0, 1, 2],
       [3, 4, 5],
       [6, 7, 8]])
>>> np.linalg.diagonal(np.fliplr(a))  # Horizontal flip
array([2, 4, 6])
>>> np.linalg.diagonal(np.flipud(a))  # Vertical flip
array([6, 4, 2])

Note that the order in which the diagonal is retrieved varies depending on the flip function.