DIAG_MATRIX

The DIAG_MATRIX function constructs a diagonal matrix from an input vector, or if given a matrix, then DIAG_MATRIX will extract a diagonal vector.

Syntax

Result = DIAG_MATRIX(A [, Diag] )

Return Value

If given an input vector with n values, the result is an n-by-n array of the same type. The DIAG_MATRIX function may also be used to construct subdiagonal or superdiagonal arrays.

If given an input n-by-m array, the result is a vector with MIN(n,m) elements containing the diagonal elements. The DIAG_MATRIX function may also be used to extract subdiagonals or superdiagonals.

Arguments

A

Either an n-element input vector to convert to a diagonal matrix, or a n-by-m input array to extract a diagonal. A may be any numeric type.

Diag

An optional argument that specifies the subdiagonal (Diag < 0) or superdiagonal (Diag > 0) to fill or extract. The default is Diag=0 which puts or extracts the values along the diagonal. If A is a vector with the m elements, then the result is an n-by-n array, where n = m + ABS(Diag). If A is an array, then the result is a vector whose length depends upon the number of elements remaining along the subdiagonal or superdiagonal.

Tip
The Diag argument may be used to easily construct tridiagonal arrays. For example, the expression,

DIAG_MATRIX(VL,-1) + DIAG_MATRIX(V) + DIAG_MATRIX(VU,1)
will create an n-by-n array, where VL is an (n - 1)-element vector containing the subdiagonal values, V is an n-element vector containing the diagonal values, and VU is an (n - 1)-element vector containing the superdiagonal values.

Keywords

None.

Examples

Create a tridiagonal matrix and extract the diagonal using the following program:

PRO ExDiagMatrix
; Convert three input vectors to a tridiagonal matrix:
diag = [1, -2, 3, -4]
sub = [5, 10, 15]
super = [3, 6, 9]
array = DIAG_MATRIX(diag) + $
DIAG_MATRIX(super, 1) + DIAG_MATRIX(sub, -1)
PRINT, 'DIAG_MATRIX array:'
PRINT, array

; Extract the diagonal:
PRINT, 'DIAG_MATRIX diagonal:'
PRINT, DIAG_MATRIX(array)
END

When this program is compiled and run, IDL prints:

DIAG_MATRIX array: 
1       3       0       0 
5      -2       6       0 
0      10       3       9 
0       0      15      -4 
DIAG_MATRIX diagonal: 
1      -2       3      -4

Version History


5.6	Introduced