`scipy.sparse._dia:dia_matrix`

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

Signature

def dia_matrix(*args, **kwargs)

Summary

Sparse matrix with DIAgonal storage.

Extended Summary

This can be instantiated in several ways:

dia_matrix(D): where D is a 2-D ndarray
dia_matrix(S): with another sparse array or matrix S (equivalent to S.todia())
dia_matrix((M, N), [dtype]): to construct an empty matrix with shape (M, N), dtype is optional, defaulting to dtype='d'.
dia_matrix((data, offsets), shape=(M, N)): where the data[k,:] stores the diagonal entries for diagonal offsets[k] (See example below)

Attributes

data: DIA format data array of the matrix
offsets: DIA format offset array of the matrix
dtype : dtype: Data type of the matrix
shape : 2-tuple: Shape of the matrix
ndim : int: Number of dimensions (this is always 2)
format : str: Three letter code for the format of the matrix storage, e.g. 'dia'
nnz : int: Number of values stored in the matrix
size : int: Number of values stored in the matrix
T : dia_matrix: The transpose of the matrix
mT : dia_matrix: The matrix transpose

Notes

Sparse matrices can be used in arithmetic operations: they support addition, subtraction, multiplication, division, and matrix power. Sparse arrays with DIAgonal storage do not support slicing.

Format details

The data array stores the diagonal elements. The alignment of these elements within the rows of data depends on their position relative to the main diagonal:

Main diagonal (offsets[i] == 0): Elements start at column 0.
Super-diagonals (offsets[i] > 0): Elements are right-aligned (padded with zeros on the left).
Sub-diagonals (offsets[i] < 0): Elements are left-aligned (padded with zeros on the right).

Each column of data corresponds to a diagonal in the resulting matrix.

Mathematically, the element at row r and column c of the matrix is stored in the data array at row i and column c - max(0, -offsets[i]), where i is the index of the diagonal in offsets.

Note that if offsets is provided in decreasing order, this format matches the BLAS/LAPACK general band format (e.g., as used in dgbmv).

Examples

import numpy as np
from scipy.sparse import dia_matrix
dia_matrix((3, 4), dtype=np.int8).toarray()

✓

array([[0, 0, 0, 0],
       [0, 0, 0, 0],
       [0, 0, 0, 0]], dtype=int8)

data = np.array([[1, 2, 3, 4]]).repeat(3, axis=0)
offsets = np.array([0, -1, 2])
dia_matrix((data, offsets), shape=(4, 4)).toarray()

✓

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

from scipy.sparse import dia_matrix
n = 10
ex = np.ones(n)
data = np.array([ex, 2 * ex, ex])
offsets = np.array([-1, 0, 1])
dia_matrix((data, offsets), shape=(n, n)).toarray()

✓

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

Aliases

scipy.sparse.dia_matrix