Main Content

sparse

Create codistributed sparse matrix

collapse all in page

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

    example

    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

    See Also

    | |