SEVSUB
The SEVSUB evaluation subroutine computes a scalar value that a SENSOR statement (C++ or FORTRAN) stores and is available through the SENVAL function expression. SEVSUB is evaluated only when the event defined by the SENSOR occurs. SEVSUB is optional. You only need it if you do not want to use a function expression in the EVALUATE argument of 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; Sevsub 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 SEVSUB (id, time, par, npar, iflag, result)
Input Arguments
id | An integer variable that contains the ID of the SENSOR statement that requests information from SEVSUB. 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 SEVSUB. |
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 SEVSUB 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
result | A double-precision variable that returns the value of the EVALUATE function for the SENSOR. |
Extended Definition
Defining the EVALUATE argument of SENSOR with a function expression is usually sufficient for must users. If the expression becomes lengthy and awkward, however, you can use SEVSUB. If the algorithms for computing the EVALUATE function use or consist of existing subroutines, SEVSUB can be made to call them.
SEVSUB is only called by Adams Solver when the event defined by the SENSOR occurs. Adams Solver evaluates whether a SENSOR event has occurred only when it has determined the state of the system for the current time step.
Once the EVALUATE function has been evaluated, Adams Solver stores the result until the SENSOR event reoccurs. The most recent value of the EVALUATE function is available through the SENVAL function expression.
FORTRAN - Prototype
A sample structure for SEVSUB is shown next. The comments explain how the subroutine works.
SUBROUTINE SEVSUB ( ID, TIME, PAR, NPAR, IFLAG,
& RESULT )
C
C === Type and dimension statements ===================
C
C
C --- External variable definitions -------------------
C
INTEGER ID
DOUBLE PRECISION TIME
DOUBLE PRECISION PAR( * )
INTEGER NPAR
INTEGER IFLAG
DOUBLE PRECISION RESULT
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 RESULT Scalar value returned to ADAMS
C
C --- Local variable definitions ----------------------
C
...
C
C === Executable code =================================
C
C --- Assign parameter values to readable variable names
C
...
C IF( IFLAG ) THEN
C
C --- Subroutine initialization -----------
C
...
C
ENDIF
C
C --- Compute the result
C
C Your algorithm
C
...
C
C --- Assign the return value
C
RESULT = ...
C
RETURN
END
& RESULT )
C
C === Type and dimension statements ===================
C
C
C --- External variable definitions -------------------
C
INTEGER ID
DOUBLE PRECISION TIME
DOUBLE PRECISION PAR( * )
INTEGER NPAR
INTEGER IFLAG
DOUBLE PRECISION RESULT
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 RESULT Scalar value returned to ADAMS
C
C --- Local variable definitions ----------------------
C
...
C
C === Executable code =================================
C
C --- Assign parameter values to readable variable names
C
...
C IF( IFLAG ) THEN
C
C --- Subroutine initialization -----------
C
...
C
ENDIF
C
C --- Compute the result
C
C Your algorithm
C
...
C
C --- Assign the return value
C
RESULT = ...
C
RETURN
END
C Style - Prototype
typedef void adams_c_SEVSUB(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 sevsub.f.