`scipy.sparse._dia:dia_array`

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

Signature

def dia_array(arg1, shape = None, dtype = None, copy = False, *, maxprint = None)

Summary

Sparse array with DIAgonal storage.

Extended Summary

This can be instantiated in several ways:

dia_array(D): where D is a 2-D ndarray
dia_array(S): with another sparse array or matrix S (equivalent to S.todia())
dia_array((M, N), [dtype]): to construct an empty array with shape (M, N), dtype is optional, defaulting to dtype='d'.
dia_array((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 array
offsets: DIA format offset array of the array
dtype : dtype: Data type of the array
shape : 2-tuple: Shape of the array
ndim : int: Number of dimensions (this is always 2)
format : str: Three letter code for the format of the array storage, e.g. 'dia'
nnz : int: Number of values stored in the array
size : int: Number of values stored in the array
T : dia_array: The transpose of the array
mT : dia_array: The matrix transpose of the array

Notes

Sparse arrays 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_array
dia_array((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_array((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_array
n = 10
ex = np.ones(n)
data = np.array([ex, 2 * ex, ex])
offsets = np.array([-1, 0, 1])
dia_array((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.]])