Adams Basic Package > Adams Solver > Welcome to Adams Solver Subroutines > User-Written Subroutines > REQSUB

REQSUB

The REQSUB evaluation subroutine computes the output values for a REQUEST statement (C++ or FORTRAN). REQSUB is optional. You only need it if you do not want to use the standard requests or F1,F2,...,F8 expressions in the REQUEST 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; Reqsub 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 REQSUB (id, time, par, npar, iflag, result)

Input Arguments

 
id
An integer variable that provides the identifier of the REQUEST statement requesting information from REQSUB. From the identifier, Adams Solver automatically knows other information (such as the par argument) available in the corresponding statement.
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.
npar
An integer variable that indicates the number of constants specified in the USER parenthetical list. The primary purpose of npar is to provide REQSUB with the number of values stored in the par array.
par
A double-precision array of constants taken in order from the USER parenthetical list of the REQUEST statement.
time
A double-precision variable through which Adams Solver conveys the current simulation time.

Output Argument

 
result
A double-precision array of eight values that contains the values you calculate in the REQSUB. Adams Solver sends all the values and the current time to the tabular output file.
If the dataset contains an OUTPUT statement with the REQSAVE argument, Adams Solver stores values two through four, and six through eight in the request file for subsequent plotting in the postprocessor (see the C++ OUTPUT command or the FORTRAN OUTPUT command).
Adams Solver does not store columns one and five in the request file. These columns usually contain translational and rotational magnitude values for the request. If the dataset contains a RESULTS statement without the NODATASTRUCTURES argument, Adams Solver stores all eight values in the results file for subsequent postprocessing. If fewer than eight values are used in the result array, Adams Solver sets the remaining values to zero.

Extended Definition

The REQUEST and MREQUEST statements are usually adequate for outputting displacement, velocity, acceleration, or force data between two markers in the system. But if you want to output other quantities, include the FUNCTION=USER() argument in the REQUEST statement and define the request output in a REQSUB.
REQSUB passes back an array of eight values. You can call any utility subroutine from REQSUB to make any element in the result array functionally dependent on system displacements, velocities, accelerations, forces, user-defined differential variables, or on-spline data.
 
Tip:  
If the SYSARY or SYSFNC utility subroutine is 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 set of rotational coordinates that does not encounter a singularity.

FORTRAN - Prototype

A sample structure for REQSUB is shown next. The comments explain how the subroutine works.
      SUBROUTINE REQSUB ( ID, TIME, PAR, NPAR, IFLAG,
      &                    RESULT )
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            RESULT( 8 )
C 
C ID        Identifier of calling REQUEST 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    Array of values 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 - Create request information -----------
C
C Your algorithms
C
      ...
C
C Assign values to the result array
C
      RESULT(1) = ...
      ...
      RESULT(8) = ...
C
      RETURN
      END

C Style - Prototype

typedef void adams_c_REQSUB(const struct sAdamsRequest* req, double TIME, int IFLAG, double* OUTPUT);
 
/*
* REQUEST -----------------------------------------------------------------
*/
struct sAdamsRequest
{
int ID;
int NPAR;
const double* PAR;
const char* COMMENT;
const char* TITLE[8];
};
 

Examples

For an example of this subroutine, see reqsub.f.