MATLAB Function Reference |
Extract and create sparse band and diagonal matrices
Syntax
Description
The spdiags
function generalizes the function diag
. Four different operations, distinguished by the number of input arguments, are possible.
B = 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
.
[B,d] = spdiags(A)
returns a vector d
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
.
Arguments
The spdiags
function deals with three matrices, in various combinations, as both input and output.
Roughly, A
, B
, and d
are related by
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.
How the Diagonals of A are Listed in the Vector d
An m-by-n matrix A
has m+n-1diagonals. These are specified in the vector d
using indices from -m+1 to n-1. For example, if A
is 5-by-6, it has 10 diagonals, which are specified in the vector d
using the indices -4, -3 , ... 4, 5. The following diagram illustrates this for a vector of all ones.
Example 1
A=[0 5 0 10 0 0;... 0 0 6 0 11 0;... 3 0 0 7 0 12;... 1 4 0 0 8 0;... 0 2 5 0 0 9] A = 0 5 0 10 0 0 0 0 6 0 11 0 3 0 0 7 0 12 1 4 0 0 8 0 0 2 5 0 0 9
The columns of the first output B
contain the nonzero diagonals of A
. The second output d
lists the indices of the nonzero diagonals of A
, as shown in the following diagram. See How the Diagonals of A are Listed in the Vector d.
Note that the longest nonzero diagonal in A
is contained in column 3 of B
. The other nonzero diagonals of A
have extra zeros added to their corresponding columns in B
, to give all columns of B
the same length. For the nonzero diagonals below the main diagonal of A
, extra zeros are added at the tops of columns. For the nonzero diagonals above the main diagonal of A
, extra zeros are added at the bottoms of columns. This is illustrated by the following diagram.
Example 2
This example generates a sparse tridiagonal representation of the classic second difference operator on n
points.
Turn it into Wilkinson's test matrix (see gallery)
:
Finally, recover the three diagonals:
Example 3
The second example is not square.
The statement [B,d]
=
spdiags(A)
produces d
=
[-3
0
2]'
and
Conversely, with the above B
and d
, the expression spdiags(B,d,7,4)
reproduces the original A
.
Example 4
This example shows how spdiags
creates the diagonals when the columns of B
are longer than the diagonals they are replacing.
B = repmat((1:6)',[1 7]) B = 1 1 1 1 1 1 1 2 2 2 2 2 2 2 3 3 3 3 3 3 3 4 4 4 4 4 4 4 5 5 5 5 5 5 5 6 6 6 6 6 6 6 d = [-4 -2 -1 0 3 4 5]; A = spdiags(B,d,6,6); full(A) ans = 1 0 0 4 5 6 1 2 0 0 5 6 1 2 3 0 0 6 0 2 3 4 0 0 1 0 3 4 5 0 0 2 0 4 5 6
Example 5A
This example illustrates the use of the syntax A = spdiags(B,d,m,n)
, under three conditions:
The command used in this example is
where B
is the 5-by-3 matrix shown below. The resulting matrix A
has dimensions m
-by-n
, and has nonzero diagonals at [-2 0 2]
(a sub-diagonal at -2
, the main diagonal, and a super-diagonal at 2
).
The first and third columns of matrix B
are used to create the sub- and super-diagonals of A
respectively. In all three cases though, these two outer columns of B
are longer than the resulting diagonals of A
. Because of this, only a part of the columns is used in A
.
When m
==
n
or m
>
n
, spdiags
takes elements of the super-diagonal in A
from the lower part of the corresponding column of B
, and elements of the sub-diagonal in A
from the upper part of the corresponding column of B
.
When m
<
n
, spdiags
does the opposite, taking elements of the super-diagonal in A
from the upper part of the corresponding column of B
, and elements of the sub-diagonal in A
from the lower part of the corresponding column of B
.
A = full(spdiags(B, [-2 0 2], 5, 5)) Matrix B Matrix A 1 6 11 6 0 13 0 0 2 7 12 0 7 0 14 0 3 8 13 == spdiags => 1 0 8 0 15 4 9 14 0 2 0 9 0 5 10 15 0 0 3 0 10
A(3,1)
, A(4,2)
, and A(5,3)
are taken from the upper part of B(:,1)
.A(1,3)
, A(2,4)
, and A(3,5)
are taken from the lower part of B(:,3)
.
A = full(spdiags(B, [-2 0 2], 5, 4)) Matrix B Matrix A 1 6 11 6 0 13 0 2 7 12 0 7 0 14 3 8 13 == spdiags => 1 0 8 0 4 9 14 0 2 0 9 5 10 15 0 0 3 0
A = full(spdiags(B, [-2 0 2], 4, 5)) Matrix B Matrix A 1 6 11 6 0 11 0 0 2 7 12 0 7 0 12 0 3 8 13 == spdiags => 3 0 8 0 13 4 9 14 0 4 0 9 0 5 10 15
A(3,1)
and A(4,2)
are taken from the lower part of B(:,1)
.A(1,3)
, A(2,4)
, and A(3,5)
are taken from the upper part of B(:,3)
.
Example 5B
Extract the diagonals from the first part of this example back into a column format using the command
You can see that in each case the original columns are restored (minus those elements that had overflowed the super- and sub-diagonals of matrix A
).
Matrix A Matrix B 6 0 13 0 0 1 6 0 0 7 0 14 0 2 7 0 1 0 8 0 15 == spdiags => 3 8 13 0 2 0 9 0 0 9 14 0 0 3 0 10 0 10 15
Matrix A Matrix B 6 0 11 0 0 0 6 11 0 7 0 12 0 0 7 12 3 0 8 0 13 == spdiags => 3 8 13 0 4 0 9 0 4 9 0
See Also
spconvert | speye |
© 1994-2005 The MathWorks, Inc.