# 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)``
``S = sparse(___,codist)``
``S = sparse(___,codist,"noCommunication")``

## 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 rows 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.```
````S = sparse(___,codist)` returns a codistributed sparse matrix. For example, `sparse(codistributed(2),codistributed(3),codist)` creates a codistributed sparse 2-by-3 matrix using the codistributor object `codist`. You can use this syntax with any of the input arguments in the previous syntaxes.Specify the distribution of the array values across the memory of workers using the codistributor object `codist`. For more information about creating codistributors, see `codistributor1d` and `codistributor2dbc`.```
````S = sparse(___,codist,"noCommunication")` returns a codistributed sparse matrix without using communication between workers. You can specify `codist` or `codist,"noCommunication"`, but not both. When you create very large arrays or your communicating job or `spmd` block uses many workers, worker-worker communication can slow down array creation. Use this syntax to improve the performance of your code by removing the time required for worker-worker communication. TipWhen you use this syntax, some error checking steps are skipped. Use this syntax to improve the performance of your code after you prototype your code without specifying `"noCommunication"`. ```

## Examples

collapse all

Create a 1000-by-1000 codistributed sparse matrix, distributed by its second dimension (columns).

```spmd(4) C = sparse(1000,1000,'codistributed'); 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 `codistributed` 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 `codistributed` 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 are set 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 `codistributed` 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 `codistributed` 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.

Codistributor, specified as a `codistributor1d` or `codistributor2dbc` object. For information on creating codistributors, see the reference pages for `codistributor1d` and `codistributor2dbc`. To use the default distribution scheme, you can specify a codistributor constructor without arguments. 