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.

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

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.

Version History

5.6	Introduced