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

    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.

    Tip

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

    Version History

    Introduced in R2006b

    See Also

    | |