CFFSUB

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

CFFSUB

The CFFSUB evaluation subroutine computes a set of friction force values for a CONTACT statement (C++ or FORTRAN). You can use a CFFSUB when the default friction force routine is not applicable to your model.

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; Cffsub for example. Doing this ensures that Adams Solver correctly distinguishes a C style subroutine from Fortran and calls with the appropriate interface.

Use

Calling Sequence

SUBROUTINE CFFSUB (id, time, par, npar, loci, locj, x, xdot, nforce, area, dflag, iflag, result)

Input Arguments

area	A double-precision variable that specifies the value of the contact area.
dflag	A logical variable that Adams Solver sets to true when it calls CFFSUB to evaluate the partial derivatives of the specified functions. Otherwise, Adams Solver sets the dflag argument to false.
id	An integer variable that provides the identifier of the CONTACT statement requesting information from CFFSUB. From the identifier, Adams Solver automatically recognizes other information (such as the par argument) that is 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.
loci	A double-precision array that specifies the vector from the reference marker of the CONTACT I Geometry (IGEOM) to the contact point on IGEOM. Expressed in the coordinate system of the reference marker of IGEOM. Note: In Flex Body Contact, loci is a node location on the Flex Body. There can be multiple nodes in each incident. The subroutine will be called for each node.
locj	A double-precision array that specifies the vector from the reference marker of the CONTACT J Geometry (JGEOM) to the contact point on JGEOM. Expressed in the coordinate system of the reference marker of JGEOM. Note: In Flex Body Contact, locj is a node location on the Flex Body. There can be multiple nodes in each incident. The subroutine will be called for each node.
nforce	A double-precision variable that specifies the value of the contact normal force.
npar	An integer variable that indicates the number of constants you specify in the USER parenthetical list. This variable provides the CFFSUB evaluation subroutine with the number of values stored in the par array.
par	A double-precision array of constants taken in order from the FRICTION_FUNCTION USER parenthetical list of the CONTACT statement.
time	A double-precision variable through which Adams Solver conveys the current simulation time.
x	A double-precision array that specifies the values of the contact deformation. (1) - Translational deformation since the beginning of contact along the x-axis of the contact I incident marker. (2) - Translational deformation since the beginning of contact along the y-axis of the contact I incident marker. (3) - Rotational deformation since the beginning of contact about the z-axis of the contact I incident marker.
xdot	A double-precision array that specifies the slip velocities at the contact point. (1) - Translational slip velocity along the x-axis of the contact I incident marker. (2) - Translational slip velocity along the y-axis of the contact I incident marker. (3) - Relative angular velocity of contacting surfaces about the z-axis of the contact I incident marker. Note: The contact incident I-marker is always oriented such that the x-axis is in the direction of slip. This means that the marker orientation is changing as the direction of slip changes. Therefore, the velocity along the y-axis (which is XDOT(2)) will always be zero.

Output Argument

result

A double-precision array that returns the three components of the friction force.

(1) - Translational force along the x-axis of the contact I incident marker.

(2) - Translational force along the y-axis of the contact I incident marker.

(3) - Rotational torque about the z-axis of the contact I incident marker.

Extended Definition

The default friction model in the CONTACT statement can only model simple dynamic friction. This means that to produce a friction force, contacting bodies must be sliding at the point of contact. Effects such as static friction and frictional torque are not modeled.

If you require another force model, you can use a CFFSUB. If the algorithms use or consist of already-existing FORTRAN-77 subroutines, CFFSUB can be made to call them. You can call utility subroutines, such as AKISPL, CUBSPL, SYSARY, and SYSFNC from CFFSUB, to obtain information about system variables, user-defined variables, and splines.

The SYSARY and SYSFNC utility subroutines set functional dependencies when the CFFSUB argument iflag is not zero. To compute solutions efficiently, Adams Solver must know the other variables on which each user-defined variable depends. Adams Solver determines these functional dependencies at the beginning of the simulation by calling CFFSUB with the argument iflag set to not zero. Adams Solver does this once for each CONTACT statement with a FRICTION_FUNCTION=USER() argument.

During each call to CFFSUB, Adams Solver records which calls you make to SYSARY and SYSFNC. Adams Solver assumes that the CONTACT components depend on those Adams Solver variables that are accessed through SYSARY and SYSFNC.

Using the DFLAG Variable

The use of the DFLAG variable is optional. Its purpose is to simply let you know that CFFSUB is being called to evaluate a partial derivative. One of the states on which the CFFSUB depends has been perturbed very slightly. In many situations, it is likely that major calculations in the CFFSUB are insensitive to small changes in state, and therefore, need not be recalculated. In such situations, you can structure the CFFSUB not to redo these calculations.

Tip:

If the SYSARY or SYSFNC subroutines are called to access angular displacements, the values returned by CFFSUB may contain discontinuities. Discontinuities occur if there is an Euler singularity. To avoid the Euler singularity (and thus the discontinuities), use the RCNVRT utility subroutine to convert the rotational angles from Euler angles to some other coordinate system that does not encounter a singularity.

■If the calculations always use the same SYSARY and SYSFNC calls through the whole simulation, and you have no initialization to do, you do not need to check the flag argument at all. You can just call SYSARY and/or SYSFNC, compute the user-defined variable value, and return to Adams Solver (FORTRAN)

Caution:

When the iflag argument is not zero:

■You must make all the calls to SYSARY and SYSFNC as they are made to compute the component values of the CONTACT statement. This ensures that Adams Solver has the proper functional dependencies. In general, failure to account for dependencies in the CONTACT statement components can make it difficult for Adams Solver to converge to a solution and/or can force Adams Solver to take small integration steps, potentially causing large increases in execution time.

■SYSARY and SYSFNC return zero values for system and user-defined variables. When you use Adams Solver, computations that divide by these values result in fatal errors. You should check for nonzero values, or ensure the iflag argument is set to zero, before dividing by these values.

Fortran - Prototype

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

     SUBROUTINE CFFSUB(ID, TIME, PAR, NPAR, LOCI, LOCJ, X, XDOT,

     & NFORCE, AREA, DFLAG, IFLAG, FORCE)

C

C     === Type and dimension statements ===================

      IMPLICIT NONE

      INTEGER ID

      DOUBLE PRECISION TIME

      DOUBLE PRECISION PAR( * )

      INTEGER NPAR

      DOUBLE PRECISION LOCI(3)

      DOUBLE PRECISION LOCJ(3)

      DOUBLE PRECISION X(3)

      DOUBLE PRECISION XDOT(3)

      DOUBLE PRECISION NFORCE

      DOUBLE PRECISION AREA

      LOGICAL DFLAG

       INTEGER  IFLAG

      DOUBLE PRECISION FORCE(3)

C

C     Input parameters

C

C     ID      Identifier of calling CONTACT statement

C     TIME    Current time

C     PAR     Array containing passed parameters

C        PAR(1) - stiction coefficient

C        PAR(2) - friction coefficient

C        PAR(3) - stiction velocity

C        PAR(4) - friction velocity

C     NPAR    Number of passed parameters

C     LOCI    contact point location on I in I coordinates

C     LOCI    contact point location on J in J coordinates

C     X       sliding displacement since the beginning of contact

C        X(1) - translational deformation in x

C        X(2) - translational deformation in y

C        X(3) - rotational deformation about z

C     XDOT    slip velocity of contact point

C        XDOT(1) - slip velocity in x

C        XDOT(2) - slip velocity in y

C        XDOT(3) - relative angular velocity about z

C     NFORCE  contact normal force

C     AREA    area of contact

C

C     components returned to ADAMS

C

C     FORCE Array (dimension 3) of computed CNFORC

C        FORCE(1) - force in x direction

C        FORCE(2) - force in y direction

C        FORCE(3) - torque about z axis

C     Local variable and parameter definitions

C

      DOUBLE PRECISION US 

      DOUBLE PRECISION UD 

      DOUBLE PRECISION VS

      DOUBLE PRECISION VD

      DOUBLE PRECISION H0, H1, X0, X1, TEMP1, TEMP2

	LOGICAL ERRFLG

C

C     ===Executable code ==================================

C

      US = PAR(1)

      UD = PAR(2)

      VS = PAR(3)

      VD = PAR(4)

      X0 = -VS

	H0 =  -1

	X1 =  VS

	H1 =   1

	CALL STEP(XDOT(1), X0, H0, X1, H1, 0, TEMP1, ERRFLG)

      CALL ERRMES(ERRFLG,'ERROR CALLING STEP',ID,'STOP')

      X0 = VS

	H0 = US

	X1 = VD

	H1 = UD

	CALL STEP(XDOT(1), X0, H0, X1, H1, 0, TEMP2, ERRFLG)

      CALL ERRMES(ERRFLG,'ERROR CALLING STEP',ID,'STOP')

	FORCE(1) = -NFORCE*TEMP1*TEMP2

	FORCE(2) = 0.0

	FORCE(3) = 0.0

      RETURN

END

C Style - Prototype

typedef void adams_c_CFFSUB(const struct sAdamsContactFriction* fric, double TIME, const double* LOCI, const double* LOCJ, const double* X, const double* XDOT, double NFORCE, double AREA, int DFLAG, int IFLAG, double* VALUES );

typedef void STDCALL adams_f77_CFFSUB(const int* ID, const double* TIME, const double* PAR, const int* NPAR, const double* LOCI, const double* LOCJ, const double* X, const double* XDOT, const double* NFORCE, const double* AREA, const int* DFLAG, const int* IFLAG, double* VALUES );

struct sAdamsContact

{

int ID;

int nIGEOM;

int nJGEOM;

int* IGEOM;

int* JGEOM;

int* IFLIP_GEOM;

int* JFLIP_GEOM;

};

struct sAdamsContactFriction

{

struct sAdamsContact contact;

int NPAR;

const double* PAR;

};