SENSUB
The SENSUB evaluation subroutine computes the values sensed by a SENSOR statement (C++ or FORTRAN). SENSUB is optional. You only need it if you do not want to use a function expression in the SENSOR statement.
Note: | Use mixed case names for the Adams subroutine names when using the C style interface. For the default subroutine name capitalize the first letter and have the remaining letters lower case; Sensub for example. Doing this ensures that Adams Solver correctly distinguishes a C style subroutine from Fortran and calls with the appropriate interface. |
Use
Corresponding Statement
Calling Sequence
SUBROUTINE SENSUB (id, time, par, npar, iflag, value)
Input Arguments
id | An integer variable that contains the ID of the SENSOR statement that requests information from SENSUB. From the identifier, Adams Solver automatically knows other information (such as the par argument) available in the corresponding statement. |
time | A double-precision variable through which Adams Solver conveys the current simulation time to SENSUB. |
par | A double-precision array of constants taken, in order, from the USER parenthetical list of the SENSOR statement. |
npar | An integer variable that indicates the number of constants specified in the USER parenthetical list. The primary purpose of npar is to provide SENSUB with the number of values stored in the par array. |
iflag | An integer variable that Adams Solver sets to indicate why the routine is being called:  Adams Solver sets iflag to 3 when it needs the functional dependency of the user-defined variable. The functional dependencies are set with the same calls to the SYSARY and SYSFNC utility subroutines that are made to compute the value of the user-defined variable. If iflag is 0, Adams Solver computes the value of the user-written variable. When your user-defined subroutine has static data that needs to be saved and restored to support the Adams Solver commands Save and Reload, then call the serialization functions for your data when iflag is set to 7, and the un-serialization functions when iflag is set to 9. Note: In simple subroutines where serializing data is not needed, you can declare iflag as a logical variable. In this case you declare your dependencies when Adams Solver sets iflag to true, and compute the subroutine's value when Adams Solver sets iflag to false. |
Output Argument
value | A double-precision variable that contains the value of the function that SENSUB evaluates. |
Extended Definition
The SENSOR statement with a function expression is usually adequate for most sensing requirements. However, if the expression becomes lengthy and awkward, you should use the FUNCTION=USER() argument in the SENSOR statement, and write a SENSUB to define the function you want to sense.
To access information on which the function depends, you can use the utility subroutines such as AKISPL, CUBSPL, SYSARY, and SYSFNC in SENSUB.
Tip: | If the SYSARY or SYSFNC utility subroutines are called to access angular displacements, the values returned by them may contain discontinuities. To avoid the discontinuities, use the RCNVRT utility subroutine to convert the rotational angles from Euler angles to some other rotational representation that does not encounter a singularity. |
FORTRAN - Prototype
A sample structure for SENSUB is shown next. The comments explain how the subroutine works.
SUBROUTINE SENSUB ( ID, TIME, PAR, NPAR, IFLAG,
& VALUE )
C
C === Type and dimension statements ===================
C
C - External variable definitions ---------
C
INTEGER ID
DOUBLE PRECISION TIME
DOUBLE PRECISION PAR( * )
INTEGER NPAR
INTEGER IFLAG
DOUBLE PRECISION VALUE
C
C ID Identifier of calling SENSOR statement
C TIME Current time
C PAR Array of passed statement parameters
C NPAR Number of passed parameters
C IFLAG Initialization pass flag
C VALUE The returned value of the sensor
C
C - Local variable definitions -----------
C
...
C
C === Executable code =================================
C
C Assign parameter values to readable variables
C
...
C
IF( IFLAG ) THEN
C
C - Subroutine initialization -----------
C
...
C
ENDIFCC - Evaluate sensor ----------------
C
C Your algorithm
C
...
C
C Assign the returned value
C
VALUE = ...
C
RETURN
END
& VALUE )
C
C === Type and dimension statements ===================
C
C - External variable definitions ---------
C
INTEGER ID
DOUBLE PRECISION TIME
DOUBLE PRECISION PAR( * )
INTEGER NPAR
INTEGER IFLAG
DOUBLE PRECISION VALUE
C
C ID Identifier of calling SENSOR statement
C TIME Current time
C PAR Array of passed statement parameters
C NPAR Number of passed parameters
C IFLAG Initialization pass flag
C VALUE The returned value of the sensor
C
C - Local variable definitions -----------
C
...
C
C === Executable code =================================
C
C Assign parameter values to readable variables
C
...
C
IF( IFLAG ) THEN
C
C - Subroutine initialization -----------
C
...
C
ENDIFCC - Evaluate sensor ----------------
C
C Your algorithm
C
...
C
C Assign the returned value
C
VALUE = ...
C
RETURN
END
C Style - prototype
typedef void adams_c_SENSUB(const struct sAdamsSensor* sensor, double TIME, int IFLAG, double* OUTPUT);
/*
* SENSOR -----------------------------------------------------------------
struct sAdamsSensorEval
{
int NPAR;
const double* PAR;
};
*/
struct sAdamsSensor
{
int ID;
int NPAR;
const double* PAR;
double VALUE;
double Error;
char Logic[2];
/* struct sAdamsSensorEval Eval; */
};
Examples
For an example of this subroutine, see sensub.f.