sprandsym

Sparse symmetric random matrix

Syntax

R = sprandsym(S)

R = sprandsym(S,[],rc,3)

R = sprandsym(n,density)

R = sprandsym(n,density,rc)

R = sprandsym(n,density,rc,kind)

R = sprandsym(___,typename)

Description

R = sprandsym(S) returns a symmetric random sparse matrix whose lower triangle and diagonal have the same structure as matrix S. The elements of R are normally distributed, with a mean of 0 and variance of 1.

R = sprandsym(S,[],rc,3) returns a sparse matrix with the same structure as S and approximate condition number 1/rc.

R = sprandsym(n,density) returns a symmetric random n-by-n sparse matrix with approximately density*n*n nonzero entries, where 0 <= density <= 1. Each entry is the sum of one or more normally distributed random samples.

R = sprandsym(n,density,rc) returns a matrix with a reciprocal condition number equal to rc. The distribution of entries is nonuniform and is roughly symmetric about 0, with all entries between -1 and 1.

R = sprandsym(n,density,rc,kind) returns a positive definite matrix with form determined by kind.

R = sprandsym(___,typename) returns a sparse matrix of the specified data type. Specify the data type in addition to any of the input argument combinations in previous syntaxes. (since R2025a)

Examples

Create Sparse Matrices with Same Sparsity Pattern

Create the 479-by-479 west0479 sparse matrix. Plot the sparsity pattern of the matrix S.

load west0479
S = west0479;
spy(S)

Create a symmetric sparse matrix R whose lower triangle and diagonal have the same sparsity pattern as the matrix S, but with normally distributed random entries. Plot the sparsity pattern of R.

R = sprandsym(S);
spy(R)

Specify Density

Create a symmetric random 500-by-500 sparse matrix with density 0.1. The matrix has approximately 0.1*500*500 = 25000 normally distributed nonzero elements.

R = sprandsym(500,0.1);

Show the exact number of nonzero elements in the matrix R.

n = nnz(R)

n = 
23723

Specify Reciprocal Condition Number

Create a random 50-by-50 sparse matrix with approximately 0.2*50*50 = 500 normally distributed nonzero entries. Specify the reciprocal condition number of the matrix as 0.25.

R = sprandsym(50,0.2,0.25);

Show that the condition number of the matrix R is equal to 1/0.25 = 4.

cond(full(R))

ans = 
4.0000

Create another random 50-by-50 sparse matrix with approximately 0.2*50*50 = 500 normally distributed nonzero entries. Specify the reciprocal condition number of the matrix as 0.25. Specify the output form as 2 so that R is a shifted sum of outer products.

P = sprandsym(50,0.2,0.25,2);

Show that the condition number of the matrix P is approximately equal to 1/0.25 = 4.

cond(full(P))

ans = 
7.2903

Input Arguments

S — Input matrix

full matrix | sparse matrix

Input matrix, specified as a full or sparse matrix.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical
Complex Number Support: Yes

n — Square matrix dimension

nonnegative integer

Square matrix dimension, specified as a nonnegative integer.

Data Types: single | double

density — Density of nonzero elements

scalar

Density of nonzero elements, specified as a scalar. The value of density must be in the interval [0,1].

Data Types: single | double

rc — Reciprocal condition number

scalar | vector

Reciprocal condition number, specified as a scalar or vector. Values in rc must be in the interval [0,1].

If rc is a vector of length n, then sprandsym(n,density,rc) returns a matrix R that has rc as its eigenvalues. In this case, the function generates R by applying random Jacobi rotations to a diagonal matrix with the given eigenvalues or condition numbers. R has significant topological and algebraic structure.

Data Types: single | double

kind — Output form

1 | 2

Output form, specified as one of these values:

• 1 — Generate the output matrix R by applying random Jacobi rotation to a positive definite diagonal matrix. R is positive definite and has the exact specified condition number.

• 2 — Generate the output matrix R by computing shifted sum of outer products. While R is positive definite and roughly matches specified condition number, it has less structure.

Data Types: single | double

typename — Output data type

"double" (default) | "single"

Since R2025a

Output data type, specified as "double" or "single".

Output Arguments

R — Output matrix

sparse matrix

Output matrix, returned as a sparse symmetric random matrix.

Tips

• sprandsym uses the same random number generator as rand, randi, and randn. You can control this generator using rng.

Extended Capabilities

Thread-Based Environment

Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

This function fully supports thread-based environments. For more information, see Run MATLAB Functions in Thread-Based Environment.

GPU Arrays

Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

The sprandsym function supports GPU array input with these usage notes and limitations:

• To run this function on a GPU and obtain a gpuArray output, use any of these syntaxes:

  • R = sprandsym(S), where S is a gpuArray.

  • R = sprandsym(S,typename), where typename specifies the data type. (since R2025a)

  • R = gpuArray.sprandsym(S).

  • R = gpuArray.sprandsym(m,n,density) .

  • R = gpuArray.sprandsym(___,typename), where typename specifies the data type in addition to the input argument combinations in the two previous syntaxes. (since R2025a)

For more information, see Run MATLAB Functions on a GPU (Parallel Computing Toolbox).

Distributed Arrays

Partition large arrays across the combined memory of your cluster using Parallel Computing Toolbox™.

Usage notes and limitations:

• Support for these syntaxes only:

  R = sprandsym(S)

  R = sprandsym(n,density)

For more information, see Run MATLAB Functions with Distributed Arrays (Parallel Computing Toolbox).

Version History

Introduced before R2006a

R2025a: Create single-precision sparse matrix

You can specify the output data type by specifying the typename argument as "double" or "single".