Skip to main content
`Ctrl`+`K`

# numpy.fill_diagonal

numpy.fill_diagonal(a, val, wrap=False)

  Fill the main diagonal of the given array of any dimensionality.

  For an array a with `a.ndim >= 2`, the diagonal is the list of values `a[i, ..., i]` with indices `i` all identical. This function modifies the input array in-place without returning a value.

  Parameters:
    a array, at least 2-D.

      Array whose diagonal is to be filled in-place.

    val scalar or array_like

      Value(s) to write on the diagonal. If val is scalar, the value is written along the diagonal. If array-like, the flattened val is written along the diagonal, repeating if necessary to fill all diagonal entries.

    wrap bool

      For tall matrices in NumPy version up to 1.6.2, the diagonal “wrapped” after N columns. You can have this behavior with this option. This affects only tall matrices.

  See also

  `diag_indices`, `diag_indices_from`

  Notes

  This functionality can be obtained via `diag_indices`, but internally this version uses a much faster implementation that never constructs the indices and uses simple slicing.

  Examples

      >>> import numpy as np
      >>> a = np.zeros((3, 3), int)
      >>> np.fill_diagonal(a, 5)
      >>> a
      array([[5, 0, 0],
             [0, 5, 0],
             [0, 0, 5]])

  The same function can operate on a 4-D array:

      >>> a = np.zeros((3, 3, 3, 3), int)
      >>> np.fill_diagonal(a, 4)

  We only show a few blocks for clarity:

      >>> a[0, 0]
      array([[4, 0, 0],
             [0, 0, 0],
             [0, 0, 0]])
      >>> a[1, 1]
      array([[0, 0, 0],
             [0, 4, 0],
             [0, 0, 0]])
      >>> a[2, 2]
      array([[0, 0, 0],
             [0, 0, 0],
             [0, 0, 4]])

  The wrap option affects only tall matrices:

      >>> # tall matrices no wrap
      >>> a = np.zeros((5, 3), int)
      >>> np.fill_diagonal(a, 4)
      >>> a
      array([[4, 0, 0],
             [0, 4, 0],
             [0, 0, 4],
             [0, 0, 0],
             [0, 0, 0]])

      >>> # tall matrices wrap
      >>> a = np.zeros((5, 3), int)
      >>> np.fill_diagonal(a, 4, wrap=True)
      >>> a
      array([[4, 0, 0],
             [0, 4, 0],
             [0, 0, 4],
             [0, 0, 0],
             [4, 0, 0]])

      >>> # wide matrices
      >>> a = np.zeros((3, 5), int)
      >>> np.fill_diagonal(a, 4, wrap=True)
      >>> a
      array([[4, 0, 0, 0, 0],
             [0, 4, 0, 0, 0],
             [0, 0, 4, 0, 0]])

  The anti-diagonal can be filled by reversing the order of elements using either `numpy.flipud` or `numpy.fliplr`.

      >>> a = np.zeros((3, 3), int);
      >>> np.fill_diagonal(np.fliplr(a), [1,2,3])  # Horizontal flip
      >>> a
      array([[0, 0, 1],
             [0, 2, 0],
             [3, 0, 0]])
      >>> np.fill_diagonal(np.flipud(a), [1,2,3])  # Vertical flip
      >>> a
      array([[0, 0, 3],
             [0, 2, 0],
             [1, 0, 0]])

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