Reference: Matrix

Model ElementReference_Matrix defines a general, real-valued, M x N matrix for use in MotionSolve.

Description

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:
<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.

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.
Figure 1.

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

  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.