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.