spdiags

Purpose

Extract and create sparse band and diagonal matrices.

Synopsis

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

Description

The spdiags function, which generalizes the built-in function diag, deals with three matrices, in various combinations, as both input and output:

  • A is an m-by-n matrix, usually (but not necessarily) sparse, with its nonzero or specified elements located on p diagonals.
  • B is a min(m,n)-by-p matrix, usually (but not necessarily) full, whose columns are the diagonals of A.
  • d is 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
    Four different operations, distinguished by the number of input arguments, are possible with spdiags:

    [B,d] = spdiags(A) extracts all nonzero diagonals.

    B = spdiags(A,d) extracts the diagonals specified by d.

    A = spdiags(B,d,A) replaces the specified diagonals.

    A = spdiags(B,d,m,n) creates a sparse matrix from its diagonals.

    The precise relationship among A, B, and d is

    if m >= n
    for k = 1:p
        for j = max(1,1+d(k)):min(n,m+d(k))
            B(j,k) = A(j-d(k),j);
        end
    end  
if m < n
    for k = 1:p
        for i = max(1,1-d(k)):min(m,n-d(k))
            B(i,k) = A(i,i+d(k));
        end
    end  
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 wilkinson):

    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.

    See Also 

    diag

    (c) Copyright 1994 by The MathWorks, Inc.