# sparse

Create sparse matrix

The `sparse` function generates matrices in the MATLAB® sparse storage organization.

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

````S = sparse(A)` converts a full matrix into sparse form by squeezing out any zero elements. If a matrix contains many zeros, converting the matrix to sparse storage saves memory.```
````S = sparse(m,n)` generates an `m`-by-`n` all zero sparse matrix.```
````S = sparse(i,j,v)` generates a sparse matrix `S` from the triplets `i`, `j`, and `v` such that `S(i(k),j(k)) = v(k)`. The `max(i)`-by-`max(j)` output matrix has space allotted for `length(v)` nonzero elements. `sparse` adds together elements in `v` that have duplicate subscripts in `i` and `j`.If the inputs `i`, `j`, and `v` are vectors or matrices, they must have the same number of elements. Alternatively, the argument `v` and/or one of the arguments `i` or `j` can be scalars.```
````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

### Save Memory Using Sparse Storage

Create a 10,000-by-10,000 full storage identity matrix.

```A = eye(10000); whos A ```
``` Name Size Bytes Class Attributes A 10000x10000 800000000 double ```

This matrix uses 800-megabytes of storage.

Convert the matrix to sparse storage.

```S = sparse(A); whos S ```
``` Name Size Bytes Class Attributes S 10000x10000 240008 double sparse ```

In sparse form, the same matrix uses roughly 0.25-megabytes of storage. In this case, you can avoid full storage completely by using the `speye` function, which creates sparse identity matrices directly.

### Sparse Matrix of All Zeros

```S = sparse(10000,5000) ```
```S = All zero sparse: 10000-by-5000 ```

### Sparse Matrix of Nonzeros with Specified Size

Create a 1500-by-1500 sparse matrix from the triplets `i`, `j`, and `v`.

```i = [900 1000]; j = [900 1000]; v = [10 100]; S = sparse(i,j,v,1500,1500) ```
```S = (900,900) 10 (1000,1000) 100 ```

When you specify a size larger than `max(i)` -by- `max(j)`, the `sparse` function pads the output with extra rows and columns of zeros.

```size(S) ```
```ans = 1500 1500 ```

### Preallocate Storage in Sparse Matrix

Create a sparse matrix with `10` nonzero values, but which has space allocated for `100` nonzero values.

```S = sparse(1:10,1:10,5,20,20,100); N = nnz(S) ```
```N = 10 ```
```N_alloc = nzmax(S) ```
```N_alloc = 100 ```

The `spalloc` function is a shorthand way to create a sparse matrix with no nonzero elements but which has space allotted for some number of nonzeros.

### Accumulate Values into Sparse Matrix

Use repeated subscripts to accumulate values into a single sparse matrix that would otherwise require one or more loops.

Create a column vector of data and two column vectors of subscripts.

```i = [6 6 6 5 10 10 9 9]'; j = [1 1 1 2 3 3 10 10]'; v = [100 202 173 305 410 550 323 121]'; ```

Visualize the subscripts and values side-by-side.

```[i,j,v] ```
```ans = 6 1 100 6 1 202 6 1 173 5 2 305 10 3 410 10 3 550 9 10 323 9 10 121 ```

Use the `sparse` function to accumulate the values that have identical subscripts.

```S = sparse(i,j,v) ```
```S = (6,1) 475 (5,2) 305 (10,3) 960 (9,10) 444 ```

## Input Arguments

collapse all

### `A` — Input matrixfull matrix | sparse matrix

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

Data Types: `double` | `logical`
Complex Number Support: Yes

### `i,j` — Subscript pairs (as separate arguments)scalars | vectors | matrices

Subscript pairs, specified as separate arguments of scalars, vectors, or matrices. Corresponding elements in `i` and `j` specify `S(i,j)` subscript pairs, which determine the placement of the values in `v` into the output. If either `i` or `j` is a vector or matrix, then the other input can be a scalar or can be a vector or matrix with the same number of elements. In that case, `sparse` uses `i(:)` and `j(:)` as the subscripts. If `i` and `j` have identical values for several elements in `v`, then those elements are added together.

 Note:   If any value in `i` or `j` is larger than `2^31-1` for 32-bit platforms, or `2^48-1` on 64-bit platforms, then the sparse matrix cannot be constructed.

Data Types: `double` | `logical`

### `v` — Valuesscalar | vector | matrix

Values, specified as a scalar, vector, or matrix. If `v` is a vector or matrix, then one of the inputs `i` or `j` must also be a vector or matrix with the same number of elements.

Any elements in `v` that are zero are ignored, as are the corresponding subscripts in `i` and `j`. However, if you do not specify the dimension sizes of the output, `m` and `n`, then `sparse` calculates the maxima ```m = max(i)``` and `n = max(j)` before ignoring any zero elements in `v`.

Data Types: `double` | `logical`
Complex Number Support: Yes

### `m,n` — Size of each dimension (as separate arguments)integer values

Size of each dimension, specified as separate arguments of integer values. If you specify `m` (the row size), you also must specify `n` (the column size).

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.

Data Types: `double`

### `nz` — Storage allocation for nonzero elementspositive integer scalar

Storage allocation for nonzero elements, specified as a positive integer scalar. `nz` must be greater than or equal to `max([numel(i), numel(j), numel(v)])`.

For a 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 in anticipation of later fill-in.

If you do not specify `nz`, the `sparse` function uses a default value of `max([numel(i), numel(j), numel(v)])`.

Data Types: `double`

collapse all

### Tips

• The `accumarray` function has similar accumulation behavior to that of `sparse`.

• `accumarray` groups data into bins using n-dimensional subscripts, but `sparse` groups data into bins using 2-D subscripts.

• `accumarray` adds elements that have identical subscripts into the output by default, but can optionally apply any function to the bins. `sparse` only adds elements that have identical subscripts into the output.