Documentation

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

More About

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.

Introduced before R2006a

Was this topic helpful?