sparse

Create codistributed sparse matrix

Syntax

``S = sparse(A)``
``S = sparse(m,n)``
``S = sparse(i,j,v)``
``S = sparse(i,j,v,m,n)``
``S = sparse(i,j,v,m,n,nz)``

Description

example

````S = sparse(A)` converts a full codistributed matrix to sparse form by removing any zero elements. You can save memory by converting a matrix that contains many zeros to sparse storage.```
````S = sparse(m,n)` creates an `m`-by-`n` codistributed sparse matrix of all zeros.```
````S = sparse(i,j,v)` creates a codistributed sparse matrix `S` from the triplets `i`, `j`, and `v`. The number of rows in `S` is set by the maximum value of `i`, and the number of columns in `S` is set by the maximum value of `j`. The matrix has space allotted for `length(v)` nonzero elements.Each of the inputs `i`, `j`, and `v` must have either `1` or `N` elements, such that each non-scalar input has the same number of elements.```
````S = sparse(i,j,v,m,n)` specifies the size of `S` as `m`-by-`n`.```
````S = sparse(i,j,v,m,n,nz)` allocates space for `nz` nonzero elements. Use this syntax to allocate extra space for nonzero values to be filled in after construction.```

Examples

collapse all

Create a 1000-by-1000 codistributed dense triangular matrix, distributed by its second dimension (columns). Convert the codistributed matrix into a codistributed sparse matrix.

```spmd(4) C = triu(rand(1000,1000,"codistributed")); S = sparse(C); end```

With four workers, each worker contains a 1000-by-250 local piece of `C`.

Input Arguments

collapse all

Input matrix, specified as a full or sparse `codistributed` matrix. If `A` is already sparse, then `sparse(A)` returns `A`.

Subscript pairs, specified as separate arguments of scalars, vectors, or matrices. If `i` and `j` are not scalars, `i(k)`, `j(k)`, and `v(k)` specify the value of `S(i(k),j(k))` as:

`S(i(k),j(k)) = v(k)`

If `i` or `j` is a scalar, the function uses that value to specify multiple elements in `S`. For example if only `i` is a scalar, `j(k)` and `v(k)` specify the value of `S(i,j(k))` as:

`S(i,j(k)) = v(k)`

If `i` and `j` have identical values for several elements in `v`, then `sparse` aggregates the values in `v` that have repeated indices. The aggregation behavior depends on the data type of the values in `v`:

• For logical values, `sparse` applies the `any` function.

• For double values, `sparse` applies the `sum` function.

Values, specified as a scalar, vector, or matrix. The underlying type of `v` must be `double` or `logical`.

If `v` is not a scalar, `i(k)`, `j(k)`, and `v(k)` specify the value of `S(i(k),j(k))` as:

`S(i(k),j(k)) = v(k)`

If `v` is a scalar, the function uses that value to specify multiple elements in `S`. For example if only `v` is a scalar, `i(k)` and `j(k)` specify the value of `S(i(k),j(k))` as:

`S(i(k),j(k)) = v`

Any elements in `v` that are zero are ignored, as are the corresponding subscripts in `i` and `j`.

`sparse` sets the number of rows and columns in the output matrix before ignoring any zero elements in `v`. Therefore, if you set any values in `v` to 0, the size of the output matrix will not change.

Size of each dimension, specified as separate arguments of integers. The underlying type of `m` and `n` must be `double`. `m` is the row size and n is the column size. If you specify `m`, you must specify `n`.

If you do not specify `m` and `n`, then `sparse` uses the default values `m = max(i)` and `n = max(j)`. These maxima are computed before any zeros in `v` are removed.

Storage allocation for nonzero elements, specified as a nonnegative integer. The underlying type of `m` and `n` must be `double`.

The default value is `max([numel(i), numel(j), numel(v), 1])`. `nz` must be greater than or equal to this value.

For the sparse matrix `S`, the `nnz` function returns the number of nonzero elements in the matrix, and the `nzmax` function returns the amount of storage allocated for nonzero matrix elements. If `nnz(S)` and `nzmax(S)` return different results, then more storage might be allocated than is actually required. For this reason, set `nz` only if you want to fill in values.

Version History

Introduced in R2006b