<!--
{
  "documentType" : "article",
  "framework" : "Accelerate",
  "identifier" : "/documentation/Accelerate/creating-a-sparse-matrix-from-coordinate-format-arrays",
  "metadataVersion" : "0.1.0",
  "role" : "article",
  "title" : "Creating a sparse matrix from coordinate format arrays"
}
-->

# Creating a sparse matrix from coordinate format arrays

Use separate coordinate format arrays to create sparse matrices.

## Discussion

In some cases — for example, if you’re 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 that contains the column indexes, a second that contains the row indexes, and a third that contains the matrix values. Each array contains the same number of elements.

### Create the sparse matrix

The following is an example of a symmetric sparse matrix:

![A four-by-four symmetric sparse matrix with four empty cells.](images/com.apple.accelerate/media-2887076@2x.png)

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

```objc
int row[] =       { 0,   1,   3,    1,    2,   3,   2,   3};
int column[] =    { 0,   0,   0,    1,    1,   1,   2,   3};
double values[] = {10.0, 1.0, 2.5, 12.0, -0.3, 1.1, 9.5, 6.0};
```

Use the `attributes` parameter to specify that the matrix is symmetric and the items in the values array derive from the lower triangle.

The following code defines the attributes and creates the sparse matrix instance:

```objc
SparseAttributes_t attributes = {
    .triangle = SparseLowerTriangle,
    .kind = SparseSymmetric
};
 
int row[] =       { 0,   1,   3,    1,    2,   3,   2,   3};
int column[] =    { 0,   0,   0,    1,    1,   1,   2,   3};
double values[] = {10.0, 1.0, 2.5, 12.0, -0.3, 1.1, 9.5, 6.0};
 
long blockCount = 8;
UInt8 blockSize = 1;
 
SparseMatrix_Double A = SparseConvertFromCoordinate(4, 4,
                                                    blockCount, blockSize,
                                                    attributes,
                                                    row, column,
                                                    values);
```

### Manage invalid and duplicate entries

The system ignores the block element and doesn’t include it in the returned matrix if the coordinates `(row[i], column[i])` are invalid, meaning either of the following is true:

- They lie outside the ranges `0..<rowCount` or `0..<columnCount`, respectively.
- [`kind`](/documentation/Accelerate/SparseAttributes_t/kind) is [`SparseTriangular`](/documentation/Accelerate/SparseTriangular) or [`SparseUnitTriangular`](/documentation/Accelerate/SparseUnitTriangular), and the coordinates lie in the wrong triangle.

If [`kind`](/documentation/Accelerate/SparseAttributes_t/kind) is [`SparseSymmetric`](/documentation/Accelerate/SparseSymmetric), the system transposes any entries in the wrong triangle and sums them into the block at `(column[i], row[i])`, if one is present.

The system sums elements with duplicate coordinates and replaces them with a single entry.

The coordinate-conversion functions support block matrices, that is, those with a `blockSize` greater than 1. The described matrix has `rowCount * blockSize` rows and `columnCount * blockSize` columns. For each `i in 0..<blockCount`, there’s a structurally nonzero block at block position `(row[i], column[i])` with numerical values `data[i * blockSize * blockSize:(i + 1) * blockSize * blockSize - 1]`. The system interprets the block’s values 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. The following functions allocate their own workspace internally and allocate space for the matrices that they return.

- [`SparseConvertFromCoordinate(_:_:_:_:_:_:_:_:)`](/documentation/Accelerate/SparseConvertFromCoordinate(_:_:_:_:_:_:_:_:)-4n2th) for real single-precision values
- [`SparseConvertFromCoordinate(_:_:_:_:_:_:_:_:)`](/documentation/Accelerate/SparseConvertFromCoordinate(_:_:_:_:_:_:_:_:)-4n2el) for real double-precision values
- [`SparseConvertFromCoordinate(_:_:_:_:_:_:_:_:)`](/documentation/Accelerate/SparseConvertFromCoordinate(_:_:_:_:_:_:_:_:)-58lgv) for complex single-precision values
- [`SparseConvertFromCoordinate(_:_:_:_:_:_:_:_:)`](/documentation/Accelerate/SparseConvertFromCoordinate(_:_:_:_:_:_:_:_:)-58kub) for complex double-precision values

The following functions require preallocated storage for the matrices that they return and a separate workspace for precise control over allocations:

- [`SparseConvertFromCoordinate(_:_:_:_:_:_:_:_:_:_:)`](/documentation/Accelerate/SparseConvertFromCoordinate(_:_:_:_:_:_:_:_:_:_:)-84plp) for real single-precision values
- [`SparseConvertFromCoordinate(_:_:_:_:_:_:_:_:_:_:)`](/documentation/Accelerate/SparseConvertFromCoordinate(_:_:_:_:_:_:_:_:_:_:)-56hv8) for real double-precision values
- [`SparseConvertFromCoordinate(_:_:_:_:_:_:_:_:_:_:)`](/documentation/Accelerate/SparseConvertFromCoordinate(_:_:_:_:_:_:_:_:_:_:)-2blwb) for complex single-precision values
- [`SparseConvertFromCoordinate(_:_:_:_:_:_:_:_:_:_:)`](/documentation/Accelerate/SparseConvertFromCoordinate(_:_:_:_:_:_:_:_:_:_:)-6ocm1) for complex double-precision values

---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)