Reference: Matrix

Model Element

Description

Reference_Matrix defines a general, real-valued, M x N matrix for use in MotionSolve. Matrices may be specified in four different ways in MotionSolve:

•	As a dense matrix in row or column order in the XML file,

•	As a sparse matrix in the XML file,

•	In a compiled user written subroutine referenced in the XML file, and,

In an interpreted user-written subroutine referenced in the XML file.

Format

The four different methods for specifying a matrix in MotionSolve are shown below.

Dense Matrix Format:

In a Python User-Subroutine Referenced in XML File:

<Reference_Matrix

id = "integer"

[label = "string"]

nrow = "integer"

ncol = "integer"

[isroworder = "TRUE"]>

val_11, val_12, val_13, ... val_1n

... ... ... ...

val_11, val_12, val_13, ... val_1n

</Reference_Matrix>

<Reference_Matrix

id = "integer"

[label = "string"]

nrow = "integer"

ncol = "integer"

script_name = "valid_path_name"

interpreter = "PYTHON" | "MATLAB

usrsub_param_string = "USER(par_1, ... par_n)"

usrsub_fnc_name = "custom_fnc_name"

Sparse Matrix Format:

In a Compiled User-Subroutine Referenced in XML File:

<Reference_Matrix

id = "integer"

[label = "string"]

nrow = "integer"

ncol = "integer"

nval = "integer"

issparse = TRUE >

row_index_1 col_index_1 val_1

... ... ...

row_index_n col_index_n val_n

</Reference_Matrix

<Reference_Matrix

id = "integer"

[label = "string"]

nrow = "integer"

ncol = "integer"

usrsub_dll_name = "valid_path_name"

usrsub_param_string = "USER (par_1, ... par_n)"

usrsub_fnc_name = "custom_fnc_name"

Attributes

This specifies the element identification number (integer>0). This number is unique to all Reference_Matrix elements.

label

Specifies the name of the Reference_Matrix element. This parameter is optional.

nrow

The number of rows in the matrix. Nrow > 0

ncol

The number of columns in the matrix. Ncol > 0

isroworder

Set to "TRUE" if the matrix is specified in row order. When not specified, it implies that the matrix elements are specified in a column order. This argument is valid only for dense matrices.

issparse

Set to "TRUE" for sparse matrices. Do not use when the matrix is dense.

nval

Specifies the number of non-zero entries for a sparse matrix. Do not use when defining a dense matrix. When specified, Nval > 0

usrsub_dll_name

Specifies the path and name of the DLL or shared library containing the user subroutine. MotionSolve uses this information to load the user subroutine Matrix_Read in the DLL at run time.

usrsub_param_string

Define the list of parameters that are passed from the data file to the user-defined subroutine. This attribute is common to all types of user subroutines and scripts.

usrsub_fnc_name

Specifies an alternative name for the user subroutine Matrix_Read.

script_name

Specifies the path and name of the user written script that contains the routine specified by usrsub_fnc_name.

interpreter

Specifies the interpreted language that the user script is written in. Valid choices are MATLAB or PYTHON.

Comments

1.	Reference_Matrix defines a general M x N matrix.

2.	Reference_Matrix elements are referenced by Reference_ParamCurve and Control_Stateeqn elements. They may also be used as needed in other user-subroutines.

3.	Use the sparse matrix format when two-thirds or more of the elements are zero.

4.	Use the user-written subroutine, Matrix_Read, to read matrix data from a file.

Example

The following example defines a dense matrix with 4 rows and 5 columns. The data is specified in row order.

<Reference_Matrix

id = "1"

nrow = "4"

ncol = "5"

isroworder = "TRUE" >

11.0, 12.0, 13.0, 14.0, 15.0

21.0, 22.0, 23.0, 24.0, 25.0

31.0, 32.0, 33.0, 34.0, 35.0

41.0, 42.0, 43.0, 44.0, 45.0

</Reference_Matrix>

The second example illustrates how to specify the above 4x5 matrix in column-ordered format.

<Reference_Matrix

id = "1"

nrow = "4"

ncol = "5" >

11.0, 21.0, 31.0, 41.0

12.0, 22.0, 32.0, 42.0

13.0, 23.0, 33.0, 43.0

14.0, 24.0, 34.0, 44.0

15.0, 25.0, 35.0, 45.0

<Reference_Matrix>

The third example illustrates how to specify a sparse matrix.

Assume that a 10x10 matrix is to be specified. However, only 13 of these entries are non-zero. These are highlighted in light green below. In such situations, it is more efficient to specify the matrix as sparse instead of dense. The sparse matrix only requires the definition of the 13 non-zero entries whereas the dense matrix would require specification of all 100 entries.

RefMatrixTable

The MotionSolve statement for specifying the above matrix in sparse format is:

<Reference_Matrix

id = "1"

nrow = "10"

ncol = "10"

nval = "13" >

1, 1, 3.3

1, 7, 7.7

2, 8, 2.9

3, 9, 1.1

3, 6, 2.2

4, 4, 4.4

5, 8, 7.6

6, 2, 1.9

7, 10, 9.2

8, 7, 5.1

9, 9, 10.

10, 3, 4.2

</Reference_Matrix>

Model Element

Description

MATRIX defines a general, real-valued, M x N matrix for use in MotionSolve. Matrices may be specified in four different ways in MotionSolve:

•	As a dense matrix in row or column order.

•	As a sparse matrix.

Declaration

def MATRIX(id, LABEL="", FULL="RORDER", ROWS=0, COLUMNS=0, VALUES=[], SPARSE=False, I=[], J=[]

Attributes

id

Element identification number (integer>0). This number is unique among all the MATRIX elements.

LABEL

The name of the MATRIX element. This parameter is optional.

FULL

Set to "RORDER" if the matrix is specified in row order. When not specified or when set to "CORDER", it implies that the matrix elements are specified in a column order. This argument is valid only for dense matrices.

ROWS

The number of rows in the matrix. ROWS > 0.

COLUMNS

The number of columns in the matrix. COLUMNS > 0.

VALUES

Specifies the elements of the matrix in a row-wise manner if FULL="RORDER" (or) in a column-wise manner if FULL="CORDER".

In case when SPARSE=True, you may specify only the non-zero elements of the matrix. The position of elements is based on the corresponding values in I and J attributes.

SPARSE

Set to TRUE for sparse matrices. Do not use when the matrix is dense.

Specifies the row position of each element in the VALUES attribute.

J

Specifies the column position of each element in the VALUES attribute.

Comments

See Reference_Matrix

Example

The first example defines a dense matrix with 4 rows and 5 columns. The data is specified in row order.

MATRIX(1,LABEL="Matrix_1", FULL="RORDER",
ROWS=4,COLUMNS=5,
VALUES=[11,12,13,14,15,21,22,23,24,25,31,32,33,34,35,41,42,43,44,45],SPARSE=False)

The second example illustrates how to specify the above 4x5 matrix in column-ordered format.

MATRIX(1,LABEL="Matrix_1", FULL="CORDER", ROWS=4,COLUMNS=5,VALUES=[11,12,13,14,15,21,22,23,24,25,31,32,33,34,35,41,42,43,44,45],SPARSE=False)

The third example illustrates how to specify a sparse matrix. Assume that a 10x10 matrix is to be specified. However, only 13 of these entries are non-zero. These are highlighted in light green below. In such situations, it is more efficient to specify the matrix as sparse instead of dense. The sparse matrix only requires the definition of the 13 non-zero entries whereas the dense matrix would require specification of all 100 entries.

MATRIX(1,LABEL="Matrix_1",ROWS=10,COLUMNS=10,VALUES=[3.3,7.7,2.9,1.1,2.2,4.4,7.6,1.9,9.2,5.1,10,4.2],SPARSE=True, I=[1,7,8,9,6,4,8,2,10,7,9,3], J=[1,1,2,3,3,4,5,6,7,8,9,10])