`scipy.sparse._construct:diags_array`

source: build-install/usr/lib/python3.14/site-packages/scipy/sparse/_construct.py:331

Signature

def diags_array(diagonals, /, offsets = 0, shape = None, format = None, dtype = None)

Summary

Construct a sparse array from diagonals.

Parameters

diagonals : sequence of array_like

Sequence of arrays containing the array diagonals, corresponding to offsets.

offsets : sequence of int or an int, optional

Diagonals to set (repeated offsets are not allowed):

k = 0 the main diagonal (default)
k > 0 the kth upper diagonal
k < 0 the kth lower diagonal

shape : tuple of int, optional

Shape of the result. If omitted, a square array large enough to contain the diagonals is returned.

format : {"dia", "csr", "csc", "lil", ...}, optional

Matrix format of the result. By default (format=None) an appropriate sparse array format is returned. This choice is subject to change.

dtype : dtype, optional

Data type of the array. If dtype is None, the output data type is determined by the data type of the input diagonals.

Returns

new_array : dia_array: dia_array holding the values in diagonals offset from the main diagonal as indicated in offsets.

Notes

Repeated diagonal offsets are disallowed.

The result from diags_array is the sparse equivalent of

np.diag(diagonals[0], offsets[0])
+ ...
+ np.diag(diagonals[k], offsets[k])

diags_array differs from dia_array in the way it handles off-diagonals. Specifically, dia_array assumes the data input includes padding (ignored values) at the start/end of the rows for positive/negative offset, while diags_array assumes the input data has no padding. Each value in the input diagonals is used.

Examples

from scipy.sparse import diags_array
diagonals = [[1.0, 2.0, 3.0, 4.0], [1.0, 2.0, 3.0], [1.0, 2.0]]
diags_array(diagonals, offsets=[0, -1, 2]).toarray()

✓

array([[1., 0., 1., 0.],
       [1., 2., 0., 2.],
       [0., 2., 3., 0.],
       [0., 0., 3., 4.]])

Broadcasting of scalars is supported (but shape needs to be specified):

diags_array([1.0, -2.0, 1.0], offsets=[-1, 0, 1], shape=(4, 4)).toarray()

✓

array([[-2.,  1.,  0.,  0.],
       [ 1., -2.,  1.,  0.],
       [ 0.,  1., -2.,  1.],
       [ 0.,  0.,  1., -2.]])

If only one diagonal is wanted (as in `numpy.diag`), the following works as well:

diags_array([1.0, 2.0, 3.0], offsets=1).toarray()

✗

array([[0., 1., 0., 0.],
       [0., 0., 2., 0.],
       [0., 0., 0., 3.],
       [0., 0., 0., 0.]])

Aliases

scipy.sparse.diags_array