Operators

# set_diagonal_matrix (Operator)

## Name

set_diagonal_matrix — Set the diagonal elements of a matrix.

## Signature

set_diagonal_matrix( : : MatrixID, VectorID, Diagonal : )

## Description

The operator set_diagonal_matrix overwrites the diagonal elements of the Matrix with the elements of the matrix Vector. The matrices are defined by their matrix handles MatrixID and VectorID. The matrix Vector must have one column and one row, n columns and one row or one column and n rows. n is the number of elements to be set in the Matrix (see below). If the matrix Vector has one column and one row, i.e., the matrix has one value, each element of the diagonal of the Matrix is overwritten by this value. Otherwise, the diagonal is overwritten by the elements of the matrix Vector.

If Diagonal = 0, the main diagonal of the Matrix is overwritten. The number n = min(number of rows of Matrix, number of columns of Matrix).

Example 1:

```
/   0.0   0.0   0.0   0.0  \
Matrix = |   0.0   0.0   0.0   0.0  |
\   0.0   0.0   0.0   0.0  /

Vector = [ 3.0   7.0   1.0 ]     Diagonal = 0

/   3.0   0.0   0.0   0.0  \
->   Matrix = |   0.0   7.0   0.0   0.0  |
\   0.0   0.0   1.0   0.0  /
```

Example 2:

```
/   0.0   0.0   0.0   0.0  \
Matrix = |   0.0   0.0   0.0   0.0  |
\   0.0   0.0   0.0   0.0  /

Vector = [ 3.0 ]    Diagonal = 0

/   3.0   0.0   0.0   0.0  \
->   Matrix = |   0.0   3.0   0.0   0.0  |
\   0.0   0.0   3.0   0.0  /
```

If Diagonal is positive, the Diagonal-th super-diagonal of Matrix is overwritten. For the example 1 the number n = min(number of rows of Matrix, parameter Diagonal). For the example 2 the number n = min(number of rows of Matrix, number of columns of Matrix).

Example 1:

```
/   0.0   0.0   0.0   0.0  \
Matrix = |   0.0   0.0   0.0   0.0  |
\   0.0   0.0   0.0   0.0  /

Vector = [  -2.0   6.0  ]     Diagonal = 2

/   0.0   0.0  -2.0   0.0  \
->   Matrix = |   0.0   0.0   0.0   6.0  |
\   0.0   0.0   0.0   0.0  /
```

Example 2:

```
/   0.0   0.0   0.0   0.0  \
Matrix = |   0.0   0.0   0.0   0.0  |
\   0.0   0.0   0.0   0.0  /

Vector = [  -2.0  ]     Diagonal = 2.0

/   0.0   0.0  -2.0   0.0  \
->   Matrix = |   0.0   0.0   0.0  -2.0  |
\   0.0   0.0   0.0   0.0  /
```

If Diagonal is negative, the Diagonal-th sub-diagonal of Matrix is overwritten. For the example 1 the number n = min(number of columns of Matrix, parameter Diagonal). For the example 2 the number n = min(number of rows of Matrix, number of columns of Matrix).

Example 1:

```
/   0.0   0.0   0.0   0.0  \
Matrix = |   0.0   0.0   0.0   0.0  |
\   0.0   0.0   0.0   0.0  /

Vector = [  -5.0  -4.0  ]     Diagonal = -1

/   0.0   0.0   0.0   0.0  \
->   Matrix = |  -5.0   0.0   0.0   0.0  |
\   0.0  -4.0   0.0   0.0  /
```

Example 2:

```
/   0.0   0.0   0.0   0.0  \
Matrix = |   0.0   0.0   0.0   0.0  |     Vector = [  -5.0  ]     Diagonal = -1
\   0.0   0.0   0.0   0.0  /

/   0.0   0.0   0.0   0.0  \
->   Matrix = |  -5.0   0.0   0.0   0.0  |
\   0.0  -5.0   0.0   0.0  /
```

## Attention

set_diagonal_matrix modifies the content of an already existing matrix.

## Parallelization

• Multithreading type: reentrant (runs in parallel with non-exclusive operators).
• Processed without parallelization.

## Parameters

MatrixID (input_control)  matrix (integer)

Matrix handle of the input matrix.

VectorID (input_control)  matrix (integer)

Matrix handle containing the diagonal elements to be set.

Diagonal (input_control)  integer (integer)

Position of the diagonal.

Default value: 0

Suggested values: -20, -10, -5, -4, -3, -2, -1, 0, 1, 2, 3, 4, 5, 10, 20

## Result

If the parameters are valid, the operator set_diagonal_matrix returns the value 2 (H_MSG_TRUE). If necessary, an exception is raised.