Diagonal Format (DIA)

• very simple scheme

• diagonals in dense NumPy array of shape (n_diag, length)

  • fixed length -> waste space a bit when far from main diagonal

  • subclass of _data_matrix (sparse array classes with .data attribute)

• offset for each diagonal

  • 0 is the main diagonal

  • negative offset = below

  • positive offset = above

• fast matrix * vector (sparsetools)

• fast and easy item-wise operations

  • manipulate data array directly (fast NumPy machinery)

• constructor accepts:

  • dense array/matrix

  • sparse array/matrix

  • shape tuple (create empty array)

  • (data, offsets) tuple

• no slicing, no individual item access

• use:

  • rather specialized

  • solving PDEs by finite differences

  • with an iterative solver

Examples

• create some DIA arrays:

  >>> data = np.array([[1, 2, 3, 4]]).repeat(3, axis=0)
  >>> data
  array([[1, 2, 3, 4],
         [1, 2, 3, 4],
         [1, 2, 3, 4]])
  >>> offsets = np.array([0, -1, 2])
  >>> mtx = sp.sparse.dia_array((data, offsets), shape=(4, 4))
  >>> mtx
  <DIAgonal sparse array of dtype 'int64'
      with 9 stored elements (3 diagonals) and shape (4, 4)>
  >>> mtx.toarray()
  array([[1, 0, 3, 0],
         [1, 2, 0, 4],
         [0, 2, 3, 0],
         [0, 0, 3, 4]])
  
  >>> data = np.arange(12).reshape((3, 4)) + 1
  >>> data
  array([[ 1,  2,  3,  4],
         [ 5,  6,  7,  8],
         [ 9, 10, 11, 12]])
  >>> mtx = sp.sparse.dia_array((data, offsets), shape=(4, 4))
  >>> mtx.data
  array([[ 1,  2,  3,  4],
         [ 5,  6,  7,  8],
         [ 9, 10, 11, 12]])
  >>> mtx.offsets
  array([ 0, -1,  2], dtype=int32)
  >>> print(mtx)
  <DIAgonal sparse array of dtype 'int64'
      with 9 stored elements (3 diagonals) and shape (4, 4)>
    Coords    Values
    (0, 0)    1
    (1, 1)    2
    (2, 2)    3
    (3, 3)    4
    (1, 0)    5
    (2, 1)    6
    (3, 2)    7
    (0, 2)    11
    (1, 3)    12
  >>> mtx.toarray()
  array([[ 1,  0, 11,  0],
         [ 5,  2,  0, 12],
         [ 0,  6,  3,  0],
         [ 0,  0,  7,  4]])
  

• explanation with a scheme:

  offset: row
  
       2:  9
       1:  --10------
       0:  1  . 11  .
      -1:  5  2  . 12
      -2:  .  6  3  .
      -3:  .  .  7  4
           ---------8
  

• matrix-vector multiplication

  >>> vec = np.ones((4, ))
  >>> vec
  array([1.,  1.,  1.,  1.])
  >>> mtx @ vec
  array([12.,  19.,   9.,  11.])
  >>> (mtx * vec).toarray()
  array([[ 1.,   0.,  11.,   0.],
         [ 5.,   2.,   0.,  12.],
         [ 0.,   6.,   3.,   0.],
         [ 0.,   0.,   7.,   4.]])