FIESUB
The FIESUB evaluation subroutine computes the force and torque components and their derivatives for a FIELD statement (C++ or FORTRAN). FIESUB is optional. You only need it if you don't want to use the constant stiffness and damping matrices in the FIELD 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; Fiesub 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 FIESUB (id, time, par, npar, disp, velo,& dflag, iflag, field, dfddis, dfdvel)
Input Arguments
id | An integer variable that provides the identifier of the FIELD statement requesting information from FIESUB. 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. |
par | A double-precision array of constants taken, in order, from the USER parenthetical list of the FIELD 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 FIESUB with the number of values stored in the par array. |
disp | A six-element, double-precision array that provides the x, y, and z translational displacements and the AX, AY, and AZ rotational displacements that Adams Solver measures at the I marker with respect to the J marker, resolved in the coordinate system of the J marker. For more information, see AX function (C++ or FORTRAN), AY function (C++ or FORTRAN), and AZ function (C++ or FORTRAN). |
velo | A six-element, double-precision array that provides the x, y, and z translational velocities and the x, y, and z rotational velocities that Adams Solver measures at the I marker with respect to the J marker, resolved in the coordinate system of the J marker. |
dflag | A logical variable that Adams Solver sets to true when it needs derivatives from FIESUB. FIESUB needs to evaluate dfddis and dfdvel only when the dflag argument is true. Otherwise, Adams Solver sets the dflag argument to false. |
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. 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. |
Output Arguments
field | A six-element, double-precision array that returns the x, y, and z translational forces and the x, y, and z rotational forces that Adams Solver applies at the I marker with respect to the J marker, resolved in the coordinate system of the J marker. |
dfddis | A six-by-six, double-precision array that returns the derivatives of the six field components with respect to the six displacement values in the disp array. For example, the derivative of the fourth FIELD component (TX) with respect to the second displacement variable (y) is dfddis (4,2). You only need to define dfddis when dflag is set to true. |
dfdvel | A six-by-six, double-precision array of the derivatives of the six field components with respect to the six velocity values in the velo array. For example, the derivative of the first FIELD component (FX) with respect to the sixth velocity variable (WZ) is dfdvel(1,6). You need to define dfdvel only when dflag is set to true. |
Extended Definition
The FIELD statement with KMATRIX and CMATRIX/CRATIO arguments specified may be used for defining six-component forces whose stiffness and damping matrices have constant entries. If, however, the force components are nonlinear functions of the relative displacements and the relative velocities of the FIELD I and J markers, then use a FIELD statement with FUNCTION=USER() and write a FIESUB to calculate the six FIELD components. These components and their derivatives can be functions of time and of the FIELD I marker component displacements and component velocities, with respect to the J marker. Adams Solver resolves the components in the J marker coordinate system.
FIESUB output must be strictly a function of the values in arrays disp and velo. Consequently, FIESUB may not call the SYSARY or SYSFNC utility subroutine. FIESUB may call other utility subroutines, such as AKISPL, and CUBSPL, that do not introduce a dependency on Solver states.
Caution: | ■The dfddis and dfdvel arrays must always be positive semidefinite. Adams Solver does not warn you if the dfddis array, the dfdvel array, or both, are not positive semidefinite. An array A is positive semidefinite if xT A x > 0 for all x not equal to 0. ■Don't attempt to make any of the six field components dependent on system variables other than those FIESUB passes through the arguments disp, velo, and time. This rule prohibits calls to the utility subroutines SYSARY and SYSFNC. Failure to comply with this rule does not produce error messages, but greatly reduces the integration step sizes, increases the CPU time, and decreases the probability of convergence to a solution. ■If FIESUB returns the six field components without their correct derivatives, simulation times may correspondingly increase, and the probability of convergence to a solution decreases. ■If AKISPL, CUBSPL, or any of the Adams Solver utility subroutines are used, don't forget to involve the derivatives returned by these subroutines when the FIESUB derivatives are evaluated. ■Field components with continuous derivatives are desirable. Discontinuous derivatives cause a reduction of integration step size at the discontinuity, and may cause Adams Solver to fail to converge to a solution. ■When the iflag argument is not zero, Adams Solver sets the disp and velo arguments to zeros. When you execute Adams Solver, computations that divide by these values result in fatal errors. You should check for nonzero values, or ensure the iflag argument is zero, before dividing by disp or velo values. |
FORTRAN - Prototype
A sample structure for FIESUB is shown next. The comments explain how the subroutine works.
SUBROUTINE FIESUB (ID, TIME, PAR, NPAR, DISP,
& VELO, DFLAG, IFLAG, FIELD,
& DFDDIS, DFDVEL )
C
C === Type and dimension statements ===================
C
C - External variable definitions ---------
C
INTEGER ID
DOUBLE PRECISION TIME
DOUBLE PRECISION PAR( * )
INTEGER NPAR
DOUBLE PRECISION DISP( 6 )
DOUBLE PRECISION VELO( 6 )
LOGICAL DFLAG
INTEGER IFLAG
DOUBLE PRECISION FIELD( 6 )
DOUBLE PRECISION DFDDIS( 6, 6 )
DOUBLE PRECISION DFDVEL( 6, 6 )
& VELO, DFLAG, IFLAG, FIELD,
& DFDDIS, DFDVEL )
C
C === Type and dimension statements ===================
C
C - External variable definitions ---------
C
INTEGER ID
DOUBLE PRECISION TIME
DOUBLE PRECISION PAR( * )
INTEGER NPAR
DOUBLE PRECISION DISP( 6 )
DOUBLE PRECISION VELO( 6 )
LOGICAL DFLAG
INTEGER IFLAG
DOUBLE PRECISION FIELD( 6 )
DOUBLE PRECISION DFDDIS( 6, 6 )
DOUBLE PRECISION DFDVEL( 6, 6 )
C
C ID Identifier of calling FIELD statement
C TIME Current time
C PAR Array of passed statement parameters
C NPAR Number of passed parameters
C DISP Array of I with respect to J displacements
C VELO Array of I with respect to J velocities
C DFLAG Differencing flag
C IFLAG Initialization pass flag
C FIELD Array of field values
C DFDDIS Displacement partial derivatives
C DFDVEL Velocity partial derivatives
C
C - Local variable definitions -----------
C
...
C
C === Executable code =================================
C
C Assign readable variable names to passed parameters
C
...
C
IF ( IFLAG ) THEN
C
C - Subroutine initialization -----------
C
...
C
ENDIF
C
C - Calculate field component forces --------
C
C X translation field force
C
...
FIELD(1) = ...
C
C Y translation field force
C
...
FIELD(2) = ...
C
C Z translation field force
C
...
FIELD(3) = ...
C
C - Calculate field component torques -------
C
C X rotational field torque
C
...
FIELD(4) = ...
C
C Y rotational field torque
C
...
FIELD(5) = ...
C
C Z rotational field torque
C
...
FIELD(6) = ...
C
C - Assign returned partial derivatives if this --
C is a differencing pass (DFLAG=.TRUE.)
C
IF ( DFLAG ) THEN
C
C Assign displacement partials for X force
C
DFDDIS(1,1) = ...
...
DFDDIS(1,6) = ...
C
C Assign displacement partials for Y force
C
DFDDIS(2,1) = ...
...
DFDDIS(2,6) = ...
C
C Assign displacement partials for Z force
C
DFDDIS(3,1) = ...
...
DFDDIS(3,6) = ...
C
C Assign displacement partials for X torque
C
DFDDIS(4,1) = ...
...
DFDDIS(4,6) = ...
C
C Assign displacement partials for Y torque
C
DFDDIS(5,1) = ...
...
DFDDIS(5,6) = ...
C
C Assign displacement partials for Z torque
C
DFDDIS(6,1) = ...
...
DFDDIS(6,6) = ...
C
C Assign velocity partials for X force
C
DFDVEL(1,1) = ...
...
DFDVEL(1,6) = ...
C
C Assign velocity partials for Y force
C
DFDVEL(2,1) = ...
...
DFDVEL(2,6) = ...
C
C Assign velocity partials for Z force
C
DFDVEL(3,1) = ...
...
DFDVEL(3,6) = ...
C
C Assign velocity partials for X torque
C
DFDVEL(4,1) = ...
...
DFDVEL(4,6) = ...
C
C Assign velocity partials for Y torque
C
DFDVEL(5,1) = ...
...
DFDVEL(5,6) = ...
C
C Assign velocity partials for Z torque
C
DFDVEL(6,1) = ...
...
DFDVEL(6,6) = ...
C
ENDIF
C
RETURN
END
C TIME Current time
C PAR Array of passed statement parameters
C NPAR Number of passed parameters
C DISP Array of I with respect to J displacements
C VELO Array of I with respect to J velocities
C DFLAG Differencing flag
C IFLAG Initialization pass flag
C FIELD Array of field values
C DFDDIS Displacement partial derivatives
C DFDVEL Velocity partial derivatives
C
C - Local variable definitions -----------
C
...
C
C === Executable code =================================
C
C Assign readable variable names to passed parameters
C
...
C
IF ( IFLAG ) THEN
C
C - Subroutine initialization -----------
C
...
C
ENDIF
C
C - Calculate field component forces --------
C
C X translation field force
C
...
FIELD(1) = ...
C
C Y translation field force
C
...
FIELD(2) = ...
C
C Z translation field force
C
...
FIELD(3) = ...
C
C - Calculate field component torques -------
C
C X rotational field torque
C
...
FIELD(4) = ...
C
C Y rotational field torque
C
...
FIELD(5) = ...
C
C Z rotational field torque
C
...
FIELD(6) = ...
C
C - Assign returned partial derivatives if this --
C is a differencing pass (DFLAG=.TRUE.)
C
IF ( DFLAG ) THEN
C
C Assign displacement partials for X force
C
DFDDIS(1,1) = ...
...
DFDDIS(1,6) = ...
C
C Assign displacement partials for Y force
C
DFDDIS(2,1) = ...
...
DFDDIS(2,6) = ...
C
C Assign displacement partials for Z force
C
DFDDIS(3,1) = ...
...
DFDDIS(3,6) = ...
C
C Assign displacement partials for X torque
C
DFDDIS(4,1) = ...
...
DFDDIS(4,6) = ...
C
C Assign displacement partials for Y torque
C
DFDDIS(5,1) = ...
...
DFDDIS(5,6) = ...
C
C Assign displacement partials for Z torque
C
DFDDIS(6,1) = ...
...
DFDDIS(6,6) = ...
C
C Assign velocity partials for X force
C
DFDVEL(1,1) = ...
...
DFDVEL(1,6) = ...
C
C Assign velocity partials for Y force
C
DFDVEL(2,1) = ...
...
DFDVEL(2,6) = ...
C
C Assign velocity partials for Z force
C
DFDVEL(3,1) = ...
...
DFDVEL(3,6) = ...
C
C Assign velocity partials for X torque
C
DFDVEL(4,1) = ...
...
DFDVEL(4,6) = ...
C
C Assign velocity partials for Y torque
C
DFDVEL(5,1) = ...
...
DFDVEL(5,6) = ...
C
C Assign velocity partials for Z torque
C
DFDVEL(6,1) = ...
...
DFDVEL(6,6) = ...
C
ENDIF
C
RETURN
END
C Style - Prototype
typedef void adams_c_FIESUB(const struct sAdamsField* fie, double TIME, double* DISP, double* VELO, int DFLAG, int IFLAG, double* FIELD, double* DFDDIS, double* DFDVEL);
/*
* FIELD -----------------------------------------------------------------
*/
struct sAdamsField
{
int ID;
int NPAR;
const double* PAR;
int I;
int J;
};
Examples
For an example of this subroutine, see fiesub.f