SYSFNC
The SYSFNC subroutine provides a single-system state value, such as displacement or velocity, to your subroutines, and defines and stores the Adams Solver state variables on which the system state is dependent.
Use
Called By
CFFSUB, CNFSUB, CONSUB, DIFSUB, GFOSUB, REQSUB, SENSUB, SFOSUB, VARSUB, VFOSUB, and VTOSUB
Calling Sequence
CALL SYSFNC (fncnam, ipar, nsize, state, errflg)
Input Arguments
fncnam | A character variable specifying the name of the function whose data is being requested from SYSFNC. The legal values for fncnam are derived from the list of functions available to you in the FUNCTION= expression construct. Note that this function requires single quotes. For example, CALL SYSFNC (`DX', IPAR, 2, DX, ERRFLG) Here, the DX characters needs to be in single quotes. Any of the following character strings are legal:  |
Note: Adams Solver (FORTRAN) - The NFORCE function is available only with SYSFNC from the REQSUB and SENSUB user written subroutines is not accessible from other user written subroutines. Adams Solver (C++) - does not have support for the NFORCE measure from the SYSFNC utility subroutine. Instead, you should use the FX, FY, and FZ, measures. These can either be used to measure the sum of forces on a single marker, or the sum of forces transmitted by all connectors connecting a pair of markers. Unfortunately, these measures can not directly compute the force transmitted between two I markers on an NFORCE and something similar to FX(I1,J)-FX(I2,J) may be required. | |
ipar | An integer array containing the parameter list for fncnam. It consists of any valid list of parameters used in the associated Adams Solver function, just as they would appear in a dataset FUNCTION = expression. |
nsize | An integer variable specifying the number of values in ipar. |
Output Arguments
errflg | A logical variable that returns true if an error has occurred during your call to SYSFNC. |
state | A double-precision variable returned by SYSFNC. State is zero when the iflag argument is set not zero in the user-written subroutine, or when input errors are found. |
Extended Definition
The SYSFNC subroutine provides system-state values (such as displacement and velocity) to user subroutines, and defines and stores the Adams Solver state variables on which the system state is dependent.
SYSFNC returns one system state or stores the dependency of the user value on the system state. You use the system state values to compute the instantaneous value of a user-defined function: Adams Solver uses the dependency on state variables to create the matrix of partial derivatives (Jacobian) of the system state with respect to the Adams Solver state variables. Adams Solver uses the Jacobian matrix in several analysis computations.
If you need to access several system states corresponding to one modeling element, you should use SYSARY (see SYSARY).
SYSFNC requires that you specify system-state information as requested from Adams Solver as a series of function call specifications. This is almost as if you were using the function expression capabilities to obtain the system state. For example, to request DX(12,10,99), you can call SYSFNC with fncnam='DX', ipar(1)=12, ipar(2)=10, ipar(3)=99, and nsize=3.
The iflag is an integer variable that Adams Solver sets to indicate why the routine is being called:
Value | Description |
|---|---|
0 | Normal function evaluation |
1 | Expression construction (Adams Solver C++ only) |
3 | Mapping dependencies |
5 | Expression destruction (Adams Solver C++ only) |
7 | Expression serialization |
9 | Expression un-serialization |
When the iflag argument in the user subroutine is 3, SYSFNC sets up the dependencies of the system states on the Adams Solver state variables and sets state equal to zero. When the iflag argument is 0, SYSFNC returns the instantaneous values of the system states.
Tip: | Use SYSARY to simultaneously access several states. Quite often, user-defined values depend on a set of related system states such as all displacement components between two markers, or all velocity components between two markers. While SYSFNC can be called several times to access the individual components, a single call to SYSARY is not only more convenient, but more efficient. Therefore, we recommend that you use SYSARY under these circumstances. |
Caution: | When the iflag argument is 1 or 3, you must be sure to make the same SYSFNC calls as when actually computing the results. Adams Solver passes a parameter iflag to each user-written subroutine (xxxSUB). It indicates to you whether Adams Solver is calling the subroutine for an initialization pass (iflag = 1 or 3) or for a function evaluation (iflag = 0). You must construct user-written subroutines such that all calls to SYSFNC that are made during the simulation are also invoked when the iflag argument is 1 or 3. Adams Solver uses this information to construct the correct Jacobian matrix. User-written subroutines should not call SYSFNC when iflag = 5, 7 or 9. |
Examples
For examples using the SYSFNC data access subroutine, see the evaluation subroutines SFOSUB and VARSUB.