VFOSUB

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

VFOSUB

The VFOSUB evaluation subroutine computes force components for a VFORCE (C++ or FORTRAN). VFOSUB is optional. You only need it if you don't want to use function expressions in the VFORCE 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; Vfosub 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 VFOSUB (id, time, par, npar,dflag, iflag, result)

Input Arguments

id	An integer variable that contains the ID of the VFORCE statement requesting information from VFOSUB. From the identifier, Adams Solver automatically recognizes other information (such as the par argument) that is 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 VFORCE statement.
npar	An integer variable that indicates the number of constants you specify in the USER parenthetical list. The primary purpose of the npar argument is to provide to VFOSUB the number of values stored in the par array.
dflag	A logical variable that Adams Solver sets to true when it calls VFOSUB to evaluate the partial derivatives of the specified functions. Otherwise, Adams Solver sets the dflag argument to false. See Using the DFLAG Variable.
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 Arguments

result

A double-precision array that returns the three values of the VFORCE components, in x-y-z order.

Extended Definition

You can usually use the VFORCE statement with function expressions to define the three components of a translational vector force at a point. However, if the force expressions become lengthy and awkward or require external computations, it may be necessary to use a VFOSUB. If the algorithms use or consist of already-existing FORTRAN-77 subroutines, VFOSUB can be made to call them.

You can call utility subroutines, such as AKISPL, CUBSPL, SYSARY, and SYSFNC, from VFOSUB to obtain information about system variables, user-defined variables, and splines. (See AKISPL, CUBSPL, SYSARY, and SYSFNC).

The SYSARY and SYSFNC utility subroutines automatically set functional dependencies when the VFOSUB argument iflag is not zero. For Adams Solver to compute solutions efficiently, it must know on which other variables each user-defined variable depends directly. Adams Solver determines these functional dependencies at the beginning of the simulation by calling VFOSUB with the argument iflag set to not zero. During each call to VFOSUB, Adams Solver records which calls you make to SYSARY and SYSFNC and assumes that the resulting values are dependent only on those Adams Solver variables accessed through the SYSARY and SYSFNC calls.

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.

Caution:

■When the iflag argument is not zero, you must make all the calls to SYSARY and SYSFNC as are made to compute the component values of the VFORCE. This ensures that Adams Solver has the proper functional dependencies. In general, failure to account for dependencies in the VFORCE components can make it difficult for Adams Solver to converge to a solution and/or can force Adams Solver to take small integration steps. Both of these effects usually cause large increases in execution time.

■When the iflag argument is not zero, SYSARY and SYSFNC return zero values. Computations that divide by these values result in fatal errors when you execute Adams Solver. You should check for nonzero values or ensure that the iflag argument is set to zero before dividing by these values.

FORTRAN - Prototype

A sample structure for VFOSUB is shown next. The comments explain how the subroutine works.

      SUBROUTINE VFOSUB(ID, TIME, PAR, NPAR, DFLAG,
     &                  IFLAG, RESULT)
C
C === Type and dimension statements ===================
C
C - External variable definitions -----------
C
      INTEGER                             ID
      DOUBLE PRECISION                    TIME
      DOUBLE PRECISION                    PAR(*)
      INTEGER                             NPAR
      LOGICAL                             DFLAG
      INTEGER                             IFLAG
      DOUBLE PRECISION                    RESULT(3)
C
C  ID           Identifier of calling VFORCE statement
C  TIME         Current time
C  PAR          Array containing passed parameters
C  NPAR         Number of passed parameters
C  DFLAG        Differencing flag
C  IFLAG        Initial pass flag
C  RESULT       Array (dimension 3) of computed VFORCE
C               components returned to ADAMS
C
C - Local variable and parameter definitions ------
C      ...
C
C === Executable code =================================
C
C Assign readable variable names to passed parameters
C
      ...
C
C Call SYSFNC and/or SYSARY to collect information for
C the calculations below. Note: if IFLAG is true, these
C calls are actually setting functional dependencies.
C
      CALL SYSFNC (...)
C
C Check SYSFNC call through ERRMES utility routine
C
      CALL ERRMES (...)
C
C Repeat for all required SYSFNC or SYSARY calls
C
      ...
C
      IF (IFLAG) THEN
C
C - Subroutine initialization -------------
C
       ...
C
      ENDIF
C
C - Evaluate VFORCE components ------------
C
C Your algorithms
C
      ...
C
C Assign values to the RESULT array
C
      RESULT(1) = ...
      RESULT(2) = ...
      RESULT(3) = ...
C
      RETURN
      END

C Style - Prototype

typedef void adams_c_VFOSUB(const struct sAdamsVforce* vfo, double TIME, int DFLAG, int IFLAG, double* RESULT);

* VFORCE -----------------------------------------------------------------

struct sAdamsVforce

{

int ID;

int NPAR;

const double* PAR;

int I;

int JFLOAT;

int RM;

};

Examples

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