scipy.sparse.

# diags#

scipy.sparse.diags(diagonals, offsets=0, shape=None, format=None, dtype=None)[source]#

Construct a sparse matrix from diagonals.

Warning

This function returns a sparse matrix – not a sparse array. You are encouraged to use `diags_array` to take advantage of the sparse array functionality.

Parameters:
diagonalssequence of array_like

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

offsetssequence of int or an int, optional
Diagonals to set:
• k = 0 the main diagonal (default)

• k > 0 the kth upper diagonal

• k < 0 the kth lower diagonal

shapetuple of int, optional

Shape of the result. If omitted, a square matrix 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 matrix format is returned. This choice is subject to change.

dtypedtype, optional

Data type of the matrix.

`spdiags`

construct matrix from diagonals

`diags_array`

construct sparse array instead of sparse matrix

Notes

This function differs from `spdiags` in the way it handles off-diagonals.

The result from `diags` is the sparse equivalent of:

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

Repeated diagonal offsets are disallowed.

Examples

```>>> from scipy.sparse import diags
>>> diagonals = [[1, 2, 3, 4], [1, 2, 3], [1, 2]]
>>> diags(diagonals, [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([1, -2, 1], [-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([1, 2, 3], 1).toarray()
array([[ 0.,  1.,  0.,  0.],
[ 0.,  0.,  2.,  0.],
[ 0.,  0.,  0.,  3.],
[ 0.,  0.,  0.,  0.]])
```