STFC
MPI für Kohlenforschung

University College London

Matrix Commands

Introduction

The matrix object is used to store a 2D array of numerical data values. A number of routines are provided to manipulate the matrix object directly, illustrated below by simple examples. In order to keep the data structure in memory, the matrix object has to be declared.

Note that vectors should be defined as two-dimensional matrices to distinguish between row and column vectors in order to be able to perform matrix operations consistently.

Matrix Creation, Allocation and Initialisation

List of Functions in this section:


set_matrix_size
create_matrix
initialise_matrix
copy_matrix

set_matrix_size

Command Line Arguments

Argument Argument type Mandatory Default To specify
matrix Matrix tag yes - tag matrix to create
datatype keyword yes - data type - must be real
dimensions list of 2 integers yes - matrix dimensions
name text yes - descriptive text string

Description:

Allocate memory for a matrix object

create_matrix

Command Line Arguments

Argument Argument type Mandatory Default To specify
matrix Matrix tag yes - tag of matrix to create
datatype keyword yes - data type - must be real
dimensions list of 2 integers yes - matrix dimensions
name text yes - descriptive text string
final arg text yes - input data

Description:

Create a matrix object, includes allocation of the memory and input of the data. The final argument is the data, e.g: 
create_matrix matrix=a datatype=real dimensions= {4 4} name=A {
1. 0. 0. 2.
0. 1. 0. 0.
0. 0. 1. 0.
3. 0. 0. 1.
}

initialise_matrix

Command Line Arguments

Argument Argument type Mandatory Default To specify
matrix Matrix tag yes - tag of matrix to create
datatype keyword yes - data type - must be real
dimensions list of 2 integers yes - matrix dimensions
name text yes - descriptive text string

Description:

Create a matrix object, and set all elements to zero. 
initialise_matrix matrix=a datatype=real dimensions= {4 4} name=A

copy_matrix

Command Line Arguments

Argument Argument type Mandatory Default To specify
from Matrix tag yes - input matrix
to Matrix tag yes - result matrix (will be created)

Description:

Copy a matrix

Obtaining information about a matrix object

List of Functions in this section:


get_matrix_element
get_matrix_dimensions
set_matrix_element
print_matrix

get_matrix_element

Command Line Arguments

Argument Argument type Mandatory Default To specify
matrix Matrix tag yes - denotes matrix to interrogate
format text no - output format e.g. %12.5f
indices list of 2 integers yes - which element to output

Description:

Return value of an element of a matrix, e.g. 
set a [ get_matrix_element matrix=a indices= {1 1} format=%12.5f ]

get_matrix_dimensions

Command Line Arguments

Argument Argument type Mandatory Default To specify
matrix Matrix tag yes - denotes matrix to interrogate

Description:

Return the dimensions of a matrix, as a Tcl list of 2 integers.

set_matrix_element

Command Line Arguments

Argument Argument type Mandatory Default To specify
matrix Matrix tag yes - denotes matrix to modify
indices list of 2 integers yes - which element to output
value real yes - value to assign

Description:

Assign an element of a matrix.

print_matrix

Command Line Arguments

Argument Argument type Mandatory Default To specify
matrix Matrix tag yes - denotes matrix to create
rows range no - which rows to print (default all)
columns range no - which columns to print (default all)
planes range no - for 3D matrices, which planes to print (default all)
format C format no - format for output

Description:

List contents of a matrix to stdout. Optional arguments may be used to specify the format used for printing, and the range of rows and columns to be listed. In the latter case, $ is used to denote the largest legal row or column value. 

print_matrix matrix=a  format=%12.4f rows = {2,$} \
columns = {1,5}

Matrix Algebra

List of Functions in this section:


diagonalise_matrix
invert_matrix
multiply_matrix
add_matrix
subtract_matrix
upscale_matrix
downscale_matrix
assign_matrix
transpose_matrix
symmetrize_matrix

diagonalise_matrix

Command Line Arguments

Argument Argument type Mandatory Default To specify
matrix Matrix tag yes - denotes matrix to diagonalise
evals Matrix tag yes - matrix to hold eigenvalues (will be created)
evecs Matrix tag yes - matrix to hold eigenvectors (will be created)

Description:

diagonalise_matrix will determine the eigenvalues and eigenvectors of a real symmetric matrix. 

diagonalise_matrix matrix=m  evals=m1 evecs=m2

invert_matrix

Command Line Arguments

Argument Argument type Mandatory Default To specify
matrix Matrix tag yes - denotes matrix to diagonalise
result Matrix tag yes - matrix to hold inverse (will be created)

Description:

Invert a matrix.

multiply_matrix

Command Line Arguments

Argument Argument type Mandatory Default To specify
left Matrix tag yes - left hand matrix
right Matrix tag yes - right hand matrix
result Matrix tag yes - result matrix (will be created)

Description:

multiply_matrix will determine the product of two matrices. The number of columns in the left matrix must match the number of rows in the right matrix. 

multiply_matrix left=m1 right=m2 result=r

add_matrix

Command Line Arguments

Argument Argument type Mandatory Default To specify
left Matrix tag yes - left hand matrix
right Matrix tag yes - right hand matrix
result Matrix tag yes - result matrix (will be created)

Description:

add_matrix will determine the sum of two matrices. The matrix may be added to itself, and the result matrix may be either of the two input matrices. 

add_matrix left=m1 right=m2 result=r

subtract_matrix

Command Line Arguments

Argument Argument type Mandatory Default To specify
left Matrix tag yes - left hand matrix
right Matrix tag yes - right hand matrix
result Matrix tag yes - result matrix (will be created)

Description:

subtract_matrix will determine the difference of two matrices. The matrix may be subtracted from itself, and the result matrix may be either of the two input matrices. The right matrix is subtracted from the left matrix. 

subtract_matrix left=m1 right=m2 result=r

upscale_matrix

Command Line Arguments

Argument Argument type Mandatory Default To specify
matrix Matrix tag yes - input matrix
factor real yes - scale factor
result Matrix tag yes - result matrix (will be created)

Description:

upscale_matrix will determine the result of a matrix multiplied by a scalar. The result matrix may be the input matrix. 

upscale_matrix matrix=m factor=3.0 result=r

downscale_matrix

Command Line Arguments

Argument Argument type Mandatory Default To specify
matrix Matrix tag yes - input matrix
factor real yes - scale factor
result Matrix tag yes - result matrix (will be created)

Description:

downscale_matrix will determine the result of a matrix divided by a scalar. The result matrix may be the input matrix. 

downscale_matrix matrix=m factor=3.0 result=r

assign_matrix

Command Line Arguments

Argument Argument type Mandatory Default To specify
from Matrix tag yes - input matrix
to real yes - scale factor
row_mapping Tcl list of integers no - rows to assign to
column_mapping Tcl list of integers no - columns to assign to
plane_mapping Tcl list of integers no - planes to assign to (3D matrices)

Description:

Assign_matrix copies the data values from a matrix to another matrix. The optional column_mapping and row_mapping arguments specify the destination row/column in the "to" matrix for each row/column in the "from" matrix. Setting a mapping value to "-1" indicates that the corresponding row/column should not be copied. The result matrix must exist and, if a mapping is not specified, must have the same shape as the input matrix. 
assign_matrix from=a to=b column_mapping= {1 2 3} row_mapping= {4 3 2 1}

In this example, the first row of b is copied from the fourth row of A, etc.

This routine also supports assignment of 3D matrices with the optional plane_mapping argument. The from and to matrices do not have to have the same number of dimensions providing an appropriate mapping is specified.

transpose_matrix

Command Line Arguments

Argument Argument type Mandatory Default To specify
matrix Matrix tag yes - input matrix
result Matrix tag yes - result matrix (will be created)

Description:

Transpose a matrix. If the result matrix does not exist at the time of the command, it is created. If the result matrix does exist, all previous information is lost. The result matrix may be the same as the input matrix, but results in a matrix filled with zero-valued elements. 

transpose_matrix matrix=a result=b

symmetrize_matrix

Command Line Arguments

Argument Argument type Mandatory Default To specify
matrix Matrix tag yes - input matrix
result Matrix tag yes - result matrix (will be created)

Description:

symmetrize_matrix will symmetrize a real square matrix. If the result matrix does not exist at the time of the command, it is created. If the result matrix does exist, all previous information is lost. The result matrix may be the same as the input matrix. 

symmetrize_matrix matrix=a result=b

Matrix Reduction to Scalar values

List of Functions in this section:


get_average_matrix_value
get_rms_matrix_value
get_absmax_matrix_value
get_abs_matrix_value

get_average_matrix_value

Command Line Arguments

Argument Argument type Mandatory Default To specify
matrix Matrix tag yes - input matrix

Description:

Calculate the average matrix element

get_rms_matrix_value

Command Line Arguments

Argument Argument type Mandatory Default To specify
matrix Matrix tag yes - input matrix

Description:

Calculate the RMS matrix element

get_absmax_matrix_value

Command Line Arguments

Argument Argument type Mandatory Default To specify
matrix Matrix tag yes - input matrix

Description:

Find the maximum absolute matrix element

get_abs_matrix_value

Command Line Arguments

Argument Argument type Mandatory Default To specify
matrix Matrix tag yes - input matrix

Description:

Retruns the square root of the sum of squares of all matrix elements (for example absolute value of the gradient).
For the programmer there is a list C-callable Matrix manipulation routines is also available

This manual was generated using htp, an HTML pre-processor Powered by htp