Article

Creating a Sparse Matrix from Coordinate Format Arrays

Use separate coordinate format arrays to create sparse matrices.

Overview

In some cases—for example, if you are reading matrix values from a file—you may find it easier to create sparse matrix objects from coordinate format arrays. This approach requires three separate arrays: one containing the column indexes, another containing the row indexes, and a third containing the values. Each array contains the same number of items.

Create the Sparse Matrix

The following is an example of a symmetric sparse matrix:

Because this sparse matrix is symmetric, you can define it with the arrays shown below that describe its lower triangle. For example, the value 9.5 is in row 2, column 2.

row =      [ 0,   1,   3,    1,    2,   3,   2,   3]
column =   [ 0,   0,   0,    1,    1,   1,   2,   3]
values =   [10.0, 1.0, 2.5, 12.0, -0.3, 1.1, 9.5, 6.0] 

With the attributes parameter, you can specify that the matrix is symmetric and the items in the values array are derived from the lower triangle.

This code defines the attributes and creates the sparse matrix instance:

var attributes = SparseAttributes_t()
attributes.triangle = SparseLowerTriangle
attributes.kind = SparseSymmetric  
 
var row: [Int32] =      [ 0,   1,   3,    1,    2,   3,   2,   3]
var column: [Int32] =   [ 0,   0,   0,    1,    1,   1,   2,   3]
var values =            [10.0, 1.0, 2.5, 12.0, -0.3, 1.1, 9.5, 6.0] 
         
let blockCount = 8
let blockSize = 1
 
let A = SparseConvertFromCoordinate(4, 4,
                                    blockCount, UInt8(blockSize),
                                    attributes,
                                    &row, &column,
                                    &values)

Invalid and Duplicate Entries

The block element is ignored and is not included in the returned matrix if the coordinates (row[i], column[i]) are invalid, meaning either of the following is true:

If kind is SparseSymmetric, any entries in the wrong triangle are transposed and summed into the block at (column[i], row[i]) if one is present.

In all cases, if any duplicate coordinates are present, the elements are summed and replaced with a single entry.

The coordinate-conversion functions support block matrices, that is, those with a blockSize greater than 1. The matrix described has rowCount * blockSize rows and columnCount * blockSize columns. For each i in 0..<blockCount, there is a structurally nonzero block at block position (row[i], column[i]) with numerical values data[i * blockSize * blockSize:(i + 1) * blockSize * blockSize - 1]. The block's values are interpreted as the elements of a dense column-major matrix with blockSize rows and columns.

There are two variants of each converter. One variant allocates its own workspace internally and also allocates space for the resulting sparse matrix. The other requires you to pass storage for the new matrix and a separate workspace for precise control over allocations.

Convert Block Matrices

The block element is ignored and is not included in the returned matrix if the coordinates (row[i], column[i]) are invalid, meaning either of the following is true:

If kind is SparseSymmetric, any entries in the wrong triangle are transposed and summed into the block at (column[i], row[i]) if one is present.

In all cases, if any duplicate coordinates are present, the elements are summed and replaced with a single entry.

The coordinate-conversion functions support block matrices, that is, those with a blockSize greater than 1. The matrix described has rowCount * blockSize rows and columnCount * blockSize columns. For each i in 0..<blockCount, there is a structurally nonzero block at block position (row[i], column[i]) with numerical values data[i * blockSize * blockSize:(i + 1) * blockSize * blockSize - 1]. The block's values are interpreted as the elements of a dense column-major matrix with blockSize rows and columns.

Supply a User-Defined Workspace

There are two variants of each converter. One variant allocates its own workspace internally and also allocates space for the resulting sparse matrix:

The other requires you to pass storage for the new matrix and a separate workspace for precise control over allocations:

See Also

Sparse Matrices

Creating Sparse Matrices

Create sparse matrices for factorization and solving systems.

Implementing Iterative Methods

Use iterative methods to solve large problems faster and with a lower memory overhead than with direct methods.

Solving Systems Using Direct Methods

Use direct methods to solve systems of equations where the coefficient matrix is sparse.

Solving Systems Using Iterative Methods

Use iterative methods to solve systems of equations where the coefficient matrix is sparse.

Sparse Solvers

Solve systems of equations where the coefficient matrix is sparse.