# sparse_test

sparse_test, a MATLAB code which calls sparse(), which is a built-on MATLAB function for creating a sparse matrix.

## MATLAB's SPARSE function

MATLAB provides a sparse function of the form

matrix = sparse ( i, j, s, m, n, nz_max )
This function can be used to create a sparse matrix. The input arguments have the following meaning:
i
the row indices of the nonzero elements;
j
the column indices of the nonzero elements;
s
the values of the nonzero elements;
m
the number of rows in the matrix;
n
the number of columns in the matrix;
nz_max
the maximum number of nonzero elements in the matrix; nz_max is commonly omitted, in which case its value is taken from the length of s.
Note that nz_max is commonly omitted, in which case its value is taken from the length of s. Moreover, if you specify nz_max explicitly, or implicitly through the size of s, MATLAB will allow you to increase the number of nonzero elements at any time. Specifying nz_max correctly, then, is simply a matter of efficiency.

### Example: Creating a Sparse Matrix at Once

Although this is not the usual way to use the sparse command, the following example should help to understand what is going on. We mean to define the following matrix:

```        11  12   0   0  15
0  22  23   0   0
31   0  33  34  35
```
by the following MATLAB commands:
```        i = [  1,  1,  1,  2,  2,  3,  3,  3,  3 ];
j = [  1,  2,  5,  2,  3,  1,  3,  4,  5 ];
s = [ 11, 12, 15, 22, 23, 31, 33, 34, 35 ];
m = 3;
n = 5;
nz_max = 9;

a = sparse ( i, j, s, m, n, nz_max );
```

### Example: Building a Sparse Matrix in Steps

Of course, in many applications, the matrix data is only available one piece at a time, or has to be modified as you go. This is easy to do, as well. You may start by defining the matrix to be an "empty" sparse matrix of a particular size, as, for example:

```        i = [];
j = [];
s = [];
m = 100;
n = 100;
a = sparse ( i, j, s, m, n );
```
The matrix will be empty, and entries of the matrix are by default equal to zero. Then you can simply reference entries of the matrix as you need them. For instance,
```        a(1,1) = 3
a(3,8) = a(3,8) + 7
a(4,7) = a(9,5) + 2 * a(8,12)
a(4,7) = a(4,7) + 1
```
If you reference, on the right hand side of these equations, a matrix entry that doesn't exist, it is by default zero. If you assign a value on the left hand side to a matrix entry that doesn't exist, a space is created for it, and it is given this value. If the entry already existed, it is overwritten.

### Useful Commands

In some cases, Matlab's sparse matrix structure allows you to ignore the fact that you are using a sparse matrix. We have already seen that you can reference the (i,j) element of the matrix in the same way you would do for a full matrix, and this is true whether you are simply asking to "read" the current value of the element, or to "write" a new value for the element.

A particular example of this is the fact that you can solve a sparse linear system using the same "backslash" formula that you would use if the matrix were full:

x = A \ b;

Matlab includes many commands specifically for dealing with a sparse matrix. For our examples, we will be considering

• nnz(A) returns the number of nonzero matrix elements;
• nzmax(A) returns the maximum number of nonzero matrix elements allocated;
• find(A) returns all (i,j) indices of nonzero elements;
• nonzeros(A) returns all the nonzero elements;

Note that, in a sense, MATLAB actually uses two formats for sparse matrices. The user communicates with MATLAB by specifying what is known as a sparse triplet, that is, a set of row indices, column indices, and values. But internally, MATLAB uses what is known as the sparse compressed column format. This format allows MATLAB to access matrix entries rapidly.

To copy the nonzero entries from a sparse matrix, creating the sparse triplet structure:

```        [i,j,s] = sparse ( A );
[m,n] = size ( A );
```
Correspondingly, to create the sparse matrix from this data:
```        A = sparse ( i, j, s, m, n );
```

When using MATLAB's sparse matrix format, it is possible to refer to matrix entries directly, using the usual index notation like A(i,j). However, accessing specific entries in this way, whether to initialize, extract, increment, or zero them, is an expensive process. The MathWorks suggests extracting the sparse triplet information, working on it in the natural way, and then "repacking" it with the sparse() command.

### Languages:

sparse_test is available in a MATLAB version and a Python version.

### Related Data and Programs:

fem2d_heat_sparse, a MATLAB code which solves the time dependent heat equation in an arbitrary triangulated 2D region, using MATLAB's sparse matrix storage format and solver.

hb_io, a MATLAB code which reads and writes sparse linear systems stored in the Harwell-Boeing (HB) Sparse Matrix format.

hb_to_msm, a MATLAB code which converts a Harwell Boeing (HB) sparse matrix file to a MATLAB sparse matrix.

hb_to_st, a MATLAB code which converts the sparse matrix information stored in a Harwell Boeing (HB) file into a Sparse Triplet (ST) file.

mm_io, a MATLAB code which reads and writes sparse linear systems stored in the Matrix Market format.

msm_to_hb, a MATLAB code which converts a MATLAB sparse matrix into a Harwell Boeing (HB) file.

sparse_ccs, a data directory which contains examples of compressed column storage (CCS), equivalent to MATLAB's sparse format, and a file format suitable for storing such information.

sparse_crs, a data directory which contains a description and examples of the compressed row storage (CRS) format, for storing a sparse matrix, including a way to write the matrix as a set of three files.

sparse_display, a MATLAB code which can read information defining a matrix of numbers and display the sparsity pattern or location of the nonzero elements using gnuplot. This operation is already available in the built-in MATLAB "spy" command.

st, a data directory which contains examples of the "sparse triplet" format for storing sparse matrices. This format is equivalent to the form in which sparse matrix data is passed into MATLAB's sparse command (although the sparse compressed column format is used internally).

wathen, a MATLAB code which compares storage schemes (full, banded, sparse triplet, sparse) and solution strategies (A\x, Linpack, conjugate gradient) for linear systems involving the Wathen matrix, which can arise when solving a problem using the finite element method (FEM).

### Reference:

1. Timothy Davis,
Direct Methods for Sparse Linear Systems,
SIAM, 2006,
ISBN: 0898716136.
2. John Gilbert, Cleve Moler, Robert Schreiber,
Sparse Matrices in MATLAB: Design and Implementation,
SIAM Journal on Matrix Analysis and Applications,
Volume 13, Number 1, 1992, pages 333-356.
3. George Lindfield, John Penny,
Numerical Methods Using MATLAB,
Second Edition,
Prentice Hall, 1999,
ISBN: 0-13-012641-1,
LC: QA297.P45.
4. The Mathworks,
MATLAB Mathematics.

### Source Code:

• sparse_test01.m, sets up a simple 3 by 5 matrix;
• sparse_test02.m, sets up a sparse -1,2,-1 matrix of order 100;
• sparse_test03.m, demonstrates the use of the SIZE, NNZ and FIND functions to describe the structure of a sparse matrix;
• sparse_test04.m, demonstrates that a sparse matrix can be constructed and incremented one element at a time;
• sparse_test05.m, demonstrates how to set up a sparse matrix associated with the Poisson equation on a regular 2D grid;
• sparse_test06.m, compares the speed of zeroing out many entries of a matrix when it is stored in full or sparse mode;
• sparse_test07.m, compares the speed of zeroing out many entries of a matrix using full storage, sparse storage, or sparse triplet storage.
• timestamp.m, prints the current YMDHMS date as a timestamp;

Last revised on 26 October 2021.