Skip to main content
`Ctrl`+`K`

# numpy.linalg.diagonal

linalg.diagonal(x, /, *, offset=0)

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

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

  Parameters:
    x(…,M,N) array_like

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

    offset int, 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.

  Returns:
    out(…,min(N,M)) 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

  `numpy.diagonal`

  Examples

      >>> 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 `numpy.flipud` or `numpy.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.