MATLAB Function Reference
spdiags

Extract and create sparse band and diagonal matrices

Syntax

• ```[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`.

 Note    If a column of `B` is longer than the diagonal it's replacing, `spdiags` takes elements of super-diagonals from the lower part of the column of `B`, and elements of sub-diagonals from the upper part of the column of `B`.

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

Example 1. 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)
```

Example 2. 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`.

Example 3. 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
```

`diag`