`numpy:fill_diagonal`

source: /dev/numpy/build-install/usr/lib/python3.14/site-packages/numpy/lib/_index_tricks_impl.py:794

Signature

def fill_diagonal(a, val, wrap = False)

Summary

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

Extended Summary

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.

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]
a[1, 1]
a[2, 2]

✓

array([[0, 0, 0],
       [0, 0, 0],
       [0, 0, 4]])

The wrap option affects only tall matrices:

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

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

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
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.

Aliases

numpy.fill_diagonal