Reference: Matrix
Model ElementReference_Matrix defines a general, real-valued, M x N matrix for use in MotionSolve.
Description
- 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:
-
<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>
- In a Python User-Subroutine Referenced in XML File:
-
<Reference_Matrix id = "integer" [label = "string"] nrow = "integer" ncol = "integer" script_name = "valid_path_name" interpreter = "string" usrsub_param_string = "USER(par_1, ... par_n)" usrsub_fnc_name = "custom_fnc_name" />
- Sparse Matrix Format:
-
<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>
- In a Compiled User-Subroutine Referenced in XML File
-
<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
- id
- 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 (example: "PYTHON"). See User-Written Subroutines for a choice of valid interpreted languages.
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.
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>
Comments
- Reference_Matrix defines a general M x N matrix.
- Reference_Matrix elements are referenced by Reference_ParamCurve and Control_Stateeqn elements. They may also be used as needed in other user-subroutines.
- Use the sparse matrix format when two-thirds or more of the elements are zero.
- Use the user-written subroutine, Matrix_Read, to read matrix data from a file.