SET_GSE_NONZERO_ENTRY

Use

Utility/Setup utility subroutine for GSE.

Format

Fortran Calling Syntax

SET_GSE_NONZERO_ENTRY (mat_type, row_idx, col_dix, errflag)

C/C++ Calling Syntax

c_set_discrete_interface(mat_type, row_idx, col_dix, errflag)

Python Calling Syntax

py_set_gse_nonzero_entry(mat_type, row_idx, col_dix, errflag)

Attributes

mat_type

[Character string]

Type of the matrix; valid types are "XX", "XU", "YX", and "YU".

row_idx

[integer]

Row index of the sparse entry. The index starts from one.

col_idx

[integer]

Column index of the sparse entry. The index starts from one.

Output

errflag

[integer]

Information about the call status. A nonzero value indicates failure.

Comments

1. All indices are 1-based. (i.e., the index starts from 1, not 0).
2. Without the usage of SET_GSE_NONZERO_ENTRY, all derivative matrices associated with the GSE are treated as full matrix. The usage of SET_GSE_NONZERO_ENTRY can improve the sparsity of the matrix and therefore improve the speed of simulation if the GSE involves a large number of states. It has no impact on the simulation results (accuracy). However, if the indices are specified incorrectly or incompletely, the robustness and simulation speed can regress. See Comment 4 for more detail.
3. Assume a GSE has one input, two states, one output, and the state equation is:

   stated(1) = input(1)

   stated(2) = states(1)

   output(1) = states(1)

   You can use SET_GSE_NONZERO_ENTRY to tell MotionSolve what entries in the derivative matrices have nonzero values. For the above case, the corresponding nonzero entries are:

   call SET_GSE_NONZERO_ENTRY ('XU', 1, 1, errflg)

   call SET_GSE_NONZERO_ENTRY ('XX', 2, 1, errflg)

   call SET_GSE_NONZERO_ENTRY ('YX', 1, 1, errflg)

   call SET_GSE_NONZERO_ENTRY ('YU', 0, 0, errflg)

   If an entire matrix is all zero (that is, YU in the above case), use 0 for both the row and column indices to tell MotionSolve that it is a NULL matrix. If you omit, say the second call for 'XX' matrix, MotionSolve treats the GSEXX matrix as a full matrix.

4. CAUTION:
   Common mistakes in using SET_GSE_NONZERO_ENTRY are incorrect column or row indices, or incomplete specification of all nonzero entries. When mistakes occur, the GSE derivative matrices are incorrect and/or incomplete and it can lead to simulation failures or longer solution time. MotionSolve cannot detect these errors with meaningful warnings except when the errors are obvious (for example, indices out of bound). If the GSE only involves a few states (for example, less than 30) or the derivative matrices are dense, the upside of using SET_GSE_NONZERO_ENTRY is very limited.