Use separate coordinate format arrays to create sparse matrices.

Framework

- Accelerate

## 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`

is in row 2, column 2.

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:

### 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:

They lie outside the ranges

`0..<row`

orCount `0..<column`

, respectivelyCount `kind`

is`Sparse`

orTriangular `Sparse`

, and the coordinates lie in the wrong triangleUnit Triangular

If `kind`

is `Sparse`

, 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 `block`

greater than 1. The matrix described has `row`

rows and `column`

columns. For each `i in 0..<block`

, there is a structurally nonzero block at block position `(row[i], column[i])`

with numerical values `data[i * block`

. The block's values are interpreted as the elements of a dense column-major matrix with `block`

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:

They lie outside the ranges

`0..<row`

orCount `0..<column`

, respectivelyCount `kind`

is`Sparse`

orTriangular `Sparse`

, and the coordinates lie in the wrong triangleUnit Triangular

If `kind`

is `Sparse`

, 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 `block`

greater than 1. The matrix described has `row`

rows and `column`

columns. For each `i in 0..<block`

, there is a structurally nonzero block at block position `(row[i], column[i])`

with numerical values `data[i * block`

. The block's values are interpreted as the elements of a dense column-major matrix with `block`

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:

`Sparse`

for double-precision, floating-point valuesConvert From Coordinate(_: _: _: _: _: _: _: _:) `Sparse`

for single-precision, floating-point valuesConvert From Coordinate(_: _: _: _: _: _: _: _:)

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

`Sparse`

for double-precision, floating-point valuesConvert From Coordinate(_: _: _: _: _: _: _: _: _: _:) `Sparse`

for single-precision, floating-point valuesConvert From Coordinate(_: _: _: _: _: _: _: _: _: _:)