6.1 Creating Sparse Matrices

A general spmatrix object can be thought of as a triplet description of a sparse matrix, i.e., a list of entries of the matrix, with for each entry the value, row index, and column index. Entries that are not included in the list are assumed to be zero. For example, the sparse matrix

    ⌊                 ⌋
       0    2  0 0  3
    ||  2    0  0 0  0 ||
A = ⌈ - 1 - 2  0 4  0 ⌉
       0    0  1 0  0
(6.1)

has the triplet description

(2,1,0),   (- 1,2,0),    (2,0,1),   (- 2,2,1),   (1,3,2),   (4,2,3),    (3,0,4).

The list may include entries with a zero value, so triplet descriptions are not necessarily unique. The list

(2,1,0),   (- 1,2,0),    (0,3,0),   (2,0,1),    (- 2,2,1),  (1,3,2),    (4,2,3),    (3,0,4)

is another triplet description of the same matrix.

An spmatrix object corresponds to a particular triplet description of a sparse matrix. We will refer to the entries in the triplet description as the nonzero entries of the object, even though they may have a numerical value zero.

Two functions are provided to create sparse matrices. The first, spmatrix(), constructs a sparse matrix from a triplet description.

spmatrix(x, I, J[, size[, tc]])

I and J are sequences of integers (lists, tuples, array arrays, xrange objects, …) or integer matrices (matrix objects with typecode ’i’), containing the row and column indices of the nonzero entries. The lengths of I and J must be equal. If they are matrices, they are treated as lists of indices stored in column-major order, i.e., as lists list(I), respectively, list(J).

size is a tuple of nonnegative integers with the row and column dimensions of the matrix. The size argument is only needed when creating a matrix with a zero last row or last column. If size is not specified, it is determined from I and J: the default value for size[0] is max(I)+1 if I is nonempty and zero otherwise. The default value for size[1] is max(J)+1 if J is nonempty and zero otherwise.

tc is the typecode, ’d’ or ’z’, for double and complex matrices, respectively. Integer sparse matrices are not implemented.

x can be a number, a sequence of numbers, or a dense matrix. This argument specifies the numerical values of the nonzero entries.

If I and J contain repeated entries, the corresponding values of the coefficients are added.

The function sparse() constructs a sparse matrix from a block-matrix description.

sparse(x[, tc])

tc is the typecode, ’d’ or ’z’, for double and complex matrices, respectively.

x can be a matrix, spmatrix, or a list of lists of matrices (matrix or spmatrix objects) and numbers (Python integer, float or complex).

The function spdiag() constructs a block-diagonal sparse matrix from a list of matrices.

spdiag(x)

x is a matrix with a single row or column, or a list of square dense or sparse matrices or scalars. If x is matrix, a sparse diagonal matrix is returned with the entries of x on its diagonal. If x is list, a sparse block-diagonal matrix is returned with the element in the list as its diagonal blocks.

The following example shows how to construct a sparse block-diagonal matrix.

>>> from cvxopt.base import matrix, spmatrix, spdiag  
>>> A = 3.0  
>>> B = matrix([[1,-2],[-2,1]])  
>>> C = spmatrix([1,1,1,1,1],[0,1,2,0,0,],[0,0,0,1,2])  
>>> D = spdiag([A, B, C])  
>>> print D  
[ 3.00e+00     0         0         0         0         0    ]  
[    0      1.00e+00 -2.00e+00     0         0         0    ]  
[    0     -2.00e+00  1.00e+00     0         0         0    ]  
[    0         0         0      1.00e+00  1.00e+00  1.00e+00]  
[    0         0         0      1.00e+00     0         0    ]  
[    0         0         0      1.00e+00     0         0    ]