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:

Example 2:

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:

Example 2:

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:

Example 2:

Execution Information

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

This operator modifies the state of the following input parameter:

During execution of this operator, access to the value of this parameter must be synchronized if it is used across multiple threads.

Parameters

`MatrixID` (input_control, state is modified)  matrix `→` (handle)

Matrix handle of the input matrix.

`VectorID` (input_control)  matrix `→` (handle)

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.

Possible Predecessors

`create_matrix`

Possible Successors

`get_full_matrix`, `get_value_matrix`

`get_diagonal_matrix`