Matrix Storage Modes

In this section, the word “matrix” refers to a mathematical object, and the word “array” refers to its representation as a Python data structure. In the following list of array types, the IMSL Library for Python (PyNL) functions require as input all values of the matrix. In PyNL, an input array can be any Python data structure that can be converted into a 2-dimensional Numpy ndarray in row-major order. Since this is the data type that PyNL uses internally for matrix representation, it is recommended for performance and memory consumption reasons to use input arrays that are in row-major order already. As an example, consider the matrix

\(A = \begin{bmatrix} 1&2&3 \\ 4&5&6 \\ 7&8&9\end{bmatrix}\)

In PyNL, this matrix can, for example, be represented by a 2-dimensional list,

a = [[1.0, 2.0, 3.0],
     [4.0, 5.0, 6.0],
     [7.0, 8.0, 9.0]]

or by a Numpy ndarray in row-major order,

b = numpy.array([[1.0, 2.0, 3.0],
                 [4.0, 5.0, 6.0],
                 [7.0, 8.0, 9.0]])

or by a Numpy ndarray in column-major order:

c = numpy.array([[1.0, 2.0, 3.0],
                 [4.0, 5.0, 6.0],
                 [7.0, 8.0, 9.0]], order='F')

Arrays a and b are preferable over c, because they represent the matrix in row-major order already.

Each function processes the input array and typically returns a “result.” For example, in solving linear algebraic systems, the function returns the solution. For general real eigenvalue problems, the function returns the eigenvalues.

General Mode

A general matrix is a square n × n matrix. The data type of a general array can be float or complex.

Sparse Coordinate Storage Format

Only the non-zero elements of a sparse matrix need to be communicated to a function. Sparse coordinate storage (SCS) format stores the value of each non-zero matrix entry along with that entry’s row and column index. PyNL uses SciPy’s coo_matrix class to represent matrices in SCS format. Each coo_matrix object stores a matrix’s non-zero values, row and column indices in three separate Numpy arrays, accessible through attributes data, row and col. Class coo_matrix permits duplicate entries and facilitates fast conversion to and from other sparse matrix formats, like compressed sparse row (CSR) or compressed sparse column (CSC) format.

As an example, consider the 6 \(\times\) 6 matrix

\[\begin{split}A = \begin{bmatrix} 2&0&0&0&0&0\\0&9&-3&-1&0&0\\0&0&5&0&0&0\\ -2&0&0&-7&-1&0\\-1&0&0&-5&1&-3\\-1&-2&0&0&0&6 \end{bmatrix}\end{split}\]

The matrix A has 15 non-zero elements, and the sparse coordinate representation would be

row	0	1	1	1	2	3	3	3	4	4	4	4	5	5	5
col	0	1	2	3	2	0	3	4	0	3	4	5	0	1	5
data	2	9	-3	-1	5	-2	-7	-1	-1	-5	1	-3	-1	-2	6

Since this representation does not rely on order, an equivalent form would be

row	5	4	3	0	5	1	2	1	4	3	1	4	3	5	4
col	0	0	0	0	1	1	2	2	3	3	3	4	4	5	5
data	-1	-1	-2	2	-2	9	5	-3	-5	-7	-1	1	-1	6	-3

The following code fragment shows, how matrix A can be represented as a coo_matrix array and how this format can be converted into the CSC format:

>>> import numpy as np
>>> from scipy.sparse import coo_matrix
>>> row = np.array([0, 1, 1, 1, 2, 3, 3, 3, 4, 4, 4, 4, 5, 5, 5])
>>> col = np.array([0, 1, 2, 3, 2, 0, 3, 4, 0, 3, 4, 5, 0, 1, 5])
>>> data = np.array([2, 9, -3, -1, 5, -2, -7, -1, -1, -5, 1, -3, -1, -2, 6],
...                 dtype=float)
>>> # represent A in SCS format
>>> a_coo = coo_matrix((data, (row, col)))
>>> # convert A into CSC format
>>> a_csc = a_coo.tocsc()