Routines (alphabetical) > Routines: D > DIAG_MATRIX

# 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

## See Also

IDENTITY, MATRIX_MULTIPLY, Manipulating Arrays