spdiags (MATLAB Function Reference)

Extract and create sparse band and diagonal matrices

[B,d] = spdiags(A)
B = spdiags(A,d)
A = spdiags(B,d,A)
A = spdiags(B,d,m,n)

Description

The spdiags function generalizes the function diag. Four different operations, distinguished by the number of input arguments, are possible:

[B,d] = spdiags(A)

extracts all nonzero diagonals from the m-by-n matrix A. B is a min(m,n)-by-p matrix whose columns are the p nonzero diagonals of A. d is a vector of length p whose integer components specify the diagonals in A.

B = spdiags(A,d)

extracts the diagonals specified by d.

A = spdiags(B,d,A)

replaces the diagonals specified by d with the columns of B. The output is sparse.

A = spdiags(B,d,m,n)

creates an m-by-n sparse matrix by taking the columns of B and placing them along the diagonals specified by d.

Remarks

If a column of B is longer than the diagonal it's replacing, spdiags takes elements from B's tail.

Arguments

The spdiags function deals with three matrices, in various combinations, as both input and output:


`A`	An `m`-by-`n` matrix, usually (but not necessarily) sparse, with its nonzero or specified elements located on `p` diagonals.
`B`	A `min(m,n)`-by-`p` matrix, usually (but not necessarily) full, whose columns are the diagonals of `A`.
`d`	A vector of length `p` whose integer components specify the diagonals in `A`.

Roughly, A, B, and d are related by

for k = 1:p
    B(:,k) = diag(A,d(k))
end

Some elements of B, corresponding to positions outside of A, are not defined by these loops. They are not referenced when B is input and are set to zero when B is output.

Examples

This example generates a sparse tridiagonal representation of the classic second difference operator on n points.

e = ones(n,1);
A = spdiags([e -2*e e], -1:1, n, n)

Turn it into Wilkinson's test matrix (see gallery):

A = spdiags(abs(-(n-1)/2:(n-1)/2)',0,A)

Finally, recover the three diagonals:

B = spdiags(A)

The second example is not square.

A = [11    0   13    0
      0   22    0   24
      0    0   33    0
     41    0    0   44
      0   52    0    0
      0    0   63    0
      0    0    0   74]

Here m = 7, n = 4, and p = 3.

The statement [B,d] = spdiags(A) produces d = [-3 0 2]' and

B = [41   11    0
     52   22    0
     63   33   13
     74   44   24]

Conversely, with the above B and d, the expression spdiags(B,d,7,4) reproduces the original A.