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

MOTSUB

The MOTSUB evaluation subroutine computes the joint displacement, velocity, or acceleration for a MOTION statement (C++ or FORTRAN). MOTSUB is optional. You only need it if you don't want to use a function expression in the MOTION 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; Motsub 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 MOTSUB(id, time, par, npar, iord, iflag,value)

Input Arguments

 
id
An integer variable that provides the identifier of the MOTION statement requesting information from MOTSUB. 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:
When iflag is 0 Adams Solver calling to compute the value of the user-written variable. When iflag is set to 1 or 3 do any initializations that your subroutine requires.
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 can do any initializations when Adams Solver sets iflag to true, and compute the subroutine's value when Adams Solver sets iflag to false.
iord
An input integer variable indicating the order of the time derivative that Adams Solver requires at different points in the analysis.
When the motion is a displacement, Adams Solver, at various times, calls MOTSUB with IORD set to 0, 1, or 2, requesting the displacement value and its first and second time derivatives, respectively.
When the motion is a velocity, Adams Solver only calls MOTSUB with IORD set to 0 or 1, and returns the velocity value and its time derivative, respectively. The second time derivative, a velocity motion, is never required.
When the motion is an acceleration, Adams Solver only uses IORD set to 0. No time derivatives of the function used in the MOTSUB for an acceleration motion are needed.
npar
An integer variable that indicates the number of constants specified in the USER parenthetical list. The primary purpose of npar is to provide MOTSUB 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 MOTION statement.
time
A double-precision variable through which Adams Solver conveys the current simulation time.

Output Arguments

 
value
A double-precision variable that returns the zeroth, first, or second derivative of the motion of the I marker with respect to the J marker. These derivatives represent the displacement, velocity, and acceleration of the motion, respectively. The value of IORD indicates which derivative of motion value must return.

Extended Definition

In most cases, the MOTION statement with a function expression is adequate for defining the motion input. However, if the expression becomes lengthy and awkward, you should use the FUNCTION=USER() argument in the MOTION statement, and write a MOTSUB to calculate the displacement.
MOTSUB measures translational displacements from the origin of the J marker to the origin of the I marker. The positive z-axis of the J marker defines the positive direction. MOTSUB measures rotational displacements from the x-axis of the J marker to the x-axis of the I marker. The right-hand rule defines a positive angle with respect to the positive z-axis of the J marker.
MOTSUB output must be strictly a function of time. Consequently, MOTSUB must not call the SYSARY and SYSFNC utility subroutines. To describe discrete time-dependent functions, MOTSUB may call the CUBSPL utility subroutine.
 
Caution:  
■Define the motion only as a function of time. Don't make calls to the SYSARY and SYSFNC utility subroutines to access other system variables or to access user-defined variables.
■Make sure the first and second derivatives MOTSUB returns for displacement are correct.
■If the CUBSPL utility subroutine or any of the Adams Solver utility subroutines are used, do not forget to involve the derivatives returned by these subroutines when the MOTSUB derivatives are evaluated.
■Avoid conditional branching that results in discontinuous accelerations, velocities, or displacements.
■Make sure MOTSUB uses length units to define translational displacements and their derivatives, and radians to define rotational displacements and their derivatives.

FORTRAN - Prototype

A sample structure for MOTSUB is shown next. The comments explain how the subroutine works.
      SUBROUTINE MOTSUB ( ID, TIME, PAR, NPAR, IORD,
      &                    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                    IORD
      INTEGER                    IFLAG
      DOUBLE PRECISION            VALUE
C
C ID       Identifier of calling MOTION statement 
C TIME     Current time
C PAR      Array containing passed parameters
C NPAR     Number of passed parameters
C IORD     Derivative order of value to be returned
C IFLAG    Initialization pass flag
C VALUE    Derivative value of MOTION returned to ADAMS
C
C - Local variable and parameter definitions ----
C
      ...
C
C === Executable code =================================
C
C Assign parameters to readable variable names
C
      ...
C
      IF ( IFLAG ) THEN
C
C - Subroutine initialization -----------
C
      ...
C
      ENDIF
C
C - Compute and assign the motion displacement ---
C
      IF ( IORD .EQ. 0 ) THEN
C
C Your algorithm
C
         ...
C
C Assign a value to VALUE for the motion displacement
C
         VALUE = ...
C
C - Compute and assign the motion velocity -----
C
      ELSE IF ( IORD .EQ. 1 ) THEN
C
C Your algorithm
C
         ...
C
C Assign a value to VALUE for the motion velocity
C
         VALUE = ...
C
C - Compute and assign the motion acceleration ---
C
      ELSE
C
C Your algorithm
C
         ...
C
C Assign a value to VALUE for the motion acceleration
C
         VALUE = ...
C
      ENDIF
C
      RETURN
      END

C Style - Protoype

typedef void adams_c_MOTSUB(const struct sAdamsMotion* motion, double TIME, int IORD, int IFLAG, double* RESULT);
/*
* MOTION
*/
 
struct sAdamsMotion
{
int ID;
int NPAR;
const double* PAR;
int JOINT;
const char* Type;
int I;
int J;
char Which[2];
const char* DVA;
};
 
The sAdamsMotion struct provides additional information related to the corresponding MOTION object. Member Type is either ROTATIONAL or TRANSLATIONAL, member DVA is either DISPLACEMENT, VELOCITY or ACCELERATION. For the translational case, member Which[0] stores a 'X' or a 'Y' or a 'Z'; Which[1] is ignored. For the rotational case, member Which[0] stores a 'B' and Which[1] stores a '1' or a '2' or a '3'.

Examples

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