Using the C Math Library

Creating a Sparse Matrix

To create a sparse matrix, call the MATLAB C Math Library mlfSparse() routine. Using this routine, you can create sparse arrays in two ways:

• By converting an existing array to sparse format
• By specifying the data and the location of the data in the sparse array

Converting an Existing Matrix into Sparse Format

To create a sparse matrix from a standard numeric array, use the mlfSparse() routine. mlfSparse() converts the numeric array into sparse storage format.

To illustrate, the following code fragment creates a 12-by-12 identity matrix. Of the 144 elements in this matrix, only 12 elements have nonzero values. In full format, all 144 are allocated storage. When this identity matrix is converted to sparse matrix format, only the 12 nonzero elements have storage allocated for them.

In the example, the NULLs included in the call to mlfSparse() represent optional arguments. The following section describes these optional arguments.

mxArray *A = NULL;
mxArray *B = NULL;

/* Create the identity matrix  */
mlfAssign(&A, mlfEye(mlfScalar(12),NULL));
mlfPrintMatrix(A);

/* Convert the identity matrix to sparse format  */
mlfAssign(&B,mlfSparse(A,NULL,NULL,NULL,NULL,NULL));
mlfPrintMatrix(B);

mxDestroyArray(A); /* Free bound arrays */
mxDestroyArray(B);

This code displays the identity matrix in full and sparse formats.

1     0     0     0     0     0     0     0     0     0     0     0
0     1     0     0     0     0     0     0     0     0     0     0
0     0     1     0     0     0     0     0     0     0     0     0
0     0     0     1     0     0     0     0     0     0     0     0
0     0     0     0     1     0     0     0     0     0     0     0
0     0     0     0     0     1     0     0     0     0     0     0
0     0     0     0     0     0     1     0     0     0     0     0
0     0     0     0     0     0     0     1     0     0     0     0
0     0     0     0     0     0     0     0     1     0     0     0
0     0     0     0     0     0     0     0     0     1     0     0
0     0     0     0     0     0     0     0     0     0     1     0
0     0     0     0     0     0     0     0     0     0     0     1

(1,1)        1
(2,2)        1
(3,3)        1
(4,4)        1
(5,5)        1
(6,6)        1
(7,7)        1
(8,8)        1
(9,9)        1
(10,10)       1
(11,11)       1
(12,12)       1

Creating a Sparse Matrix from Data

You can create a sparse matrix, specifying the value and location of all the nonzero elements when you create it. Using mlfSparse(), you specify as arguments:

• Two vectors, i and j, that specify the row and column subscripts of the nonzero elements.
• One vector, s, containing the real or complex data you want to store in the sparse matrix. Vectors i, j and s should all have the same length.
• Two scalar arrays, m and n, that specify the dimensions of the sparse matrix to be created.
• An optional scalar array that specifies the maximum amount of storage that can be allocated for this sparse array.

The following code example illustrates how to create a sparse 8-by-7 sparse matrix from data. This call specifies a single value, 9, for all the nonzero elements of the sparse matrix which is replicated in all nonzero elements by scalar expansion. To see the pattern formed by this sparse matrix, see the output of this code which follows.

static double row_subscripts[] = { 3, 4, 5, 4, 5, 6 };
static double col_subscripts[] = { 4, 3, 3, 5, 5, 4 };

mxArray *i = NULL;
mxArray *j = NULL;
mxArray *S = NULL;

mlfAssign(&i, mlfDoubleMatrix(1, 6, row_subscripts, NULL));
mlfAssign(&j, mlfDoubleMatrix(1, 6, col_subscripts, NULL));

mlfAssign(&S, mlfSparse(i,    /* Row subscripts     */
                        j,    /* Column subscripts  */
                        mlfScalar(9),   /* Data  */
                        mlfScalar(8), 
                        mlfScalar(7), 
                        NULL));

mlfPrintMatrix(S);
mlfPrintMatrix(mlfFull(S));

mxDestroyArray(i);
mxDestroyArray(j);
mxDestroyArray(S);

This code produces the following output.

(4,3)   9
(5,3)   9
(3,4)   9
(6,4)   9
(4,5)   9
(5,5)   9

0    0    0    0    0    0    0
0    0    0    0    0    0    0
0    0    0    9    0    0    0
0    0    9    0    9    0    0
0    0    9    0    9    0    0
0    0    0    9    0    0    0
0    0    0    0    0    0    0
0    0    0    0    0    0    0

Sparse Matrices

Converting a Sparse Matrix to Full Matrix Format