Welcome to Adams/Solver Subroutines - Kxcad.net

Welcome to Adams/Solver Subroutines 


User subroutines are commonly used in Adams/Solver, part of the Adams® suite of software, to model 

a variety of non-standard phenomena. You can customize Adams/Solver for their specific application by 

writing these subroutines. 

This section provides an overview of the subroutines you can use with Adams/Solver. This material 

applies to both FORTRAN and C++ versions of Adams/Solver unless specified otherwise. For more 

information on the FORTRAN version, see the Adams/Solver (FORTRAN) online help. For information 

on the C++ version, see the Adams/Solver (C++) online help. 

1

2 

Adams/Solver 

Conventions, Requirements and Types 

Subroutine Conventions 

Throughout the help, the following type styles are used as visual cues: 

This type of style: Indicates: 

CONSUB The subroutines that Adams recognizes. 

x The argument in Adams subroutines. 

i The type of value or types of parameters that are to follow the 

statement, command, or argument. A summary of these terms include: 

System Requirements 

i 

r 

c 

e 

v 

id 

x,y,z 

a,b,c 

Integer 

Real 

Character string (alphanumeric) 

Function expression 

Varying type (integer, real or 

alphanumeric) 

Identifier 

Cartesian coordinate (real) 

Angular coordinate (real) 

PART The underscored letters indicated the minimum allowable 

abbreviations of statements, commands, and arguments. 

{ } That you are to make a selection from a series of items. 

[ ] That you can optionally select an item. 

[[ ]] That you can select any combination of the items. 

A A two-dimensional matrix. 

a A one-dimensional matrix. 

R 

xˆ 

A vector. 

Unit vectors. 

To use subroutines, you need the system requirements outlined in the following sections.

Compilers and Linkers 


To work with user-written subroutines you must have the appropriate compilers and linkers. For more 

information, refer to the hardware and software specifications included with your installation 

instructions, and on the Adams Web site. 

Languages 

You can write user-written subroutines in any language, provided there is a way to call FORTRAN 

subroutines in that language. FORTRAN is the preferred language for writing user-written subroutines, 

although C and C++ are acceptable. 

Debuggers 

To facilitate the debugging of user-written subroutines, you should have a source-level debugger. 

Debuggers are not required when using your own subroutines with Adams/Solver, but are useful for 

finding mistakes, such as improper syntax or logic, in your subroutines. 

Types of Subroutines 

The following sections introduce the three types of subroutines that Adams/Solver provides: 

• About User-Written Subroutines 

• About Utility Subroutines 

• About Callable Subroutines (no longer supported) 

About User-Written Subroutines 

User-written subroutines are used primarily for modeling specialized phenomena or calculating 

nonstandard results. Many simulations require the modeling of special phenomena that are not a part of 

the standard Adams software. These phenomena may be expressed mathematically as differential 

equations, algebraic equations, applied forces, constraints, motion inputs to system, or a combination of 

these general modeling entities. 

Adams/Solver can accept user-specified descriptions of phenomena. You define the governing 

relationships for the phenomena in the user-written subroutines. Adams then evaluates these 

relationships as part of the solution process. 

For more information about user-written subroutines and details about each of the user-written 

subroutines, see User-Written Subroutines. 

About Utility Subroutines 

Utility subroutines are used for accessing current system state information. You typically use this 

information as input for defining phenomena or modeling elements that are not available as a part of 

standard Adams. 

For more information about utility subroutines and details about each of the utility subroutines, see 

Utility Subroutines. 

About Callable Subroutines 

3

4 


MSC no longer supports callable subroutines. If you have questions on callable subroutines, please refer 

to: 

• Knowledge Base (http://support.adams.com/kb/) 

• ASK List (http://support.adams.com/services/support/tech_ask.shtm).

Utility Subroutines 

About Utility Subroutines 


The utility subroutines provide all the functionality found in the dataset function expressions, and more. 

You use utility subroutines to perform operations such as the following: 

• Access data defined in a model. 

• Access current state information. 

• Interpolate through raw data using standard curve-fitting techniques. 

• Evaluate standard functions. 

The utility subroutines are divided into the following categories: 

• Execution Control Subroutines 

• Data Access Subroutines 

• Unsupported Subroutines 

Execution Control Subroutines 

CONSUB is the only subroutine that can call execution control subroutines. In conjunction with 

ANALYS, DATOUT, and MODIFY, you can use CONSUB to control an Adams simulation. 

ANALYS and MODIFY contain the FORTRAN equivalents of interactive commands to initiate analysis 

and to modify the Adams/Solver dataset, respectively. DATOUT produces output from the simulation(s). 

These subroutines are of most value if you want to run many simulations on a single dataset or on 

variations of that dataset. 

Data Access Subroutines 

Subroutine: Does the following: 

ANALYS Performs an Adams analysis. 

DATOUT Outputs all data for the current time step 

into the specified output files. 

MODIFY Allows execution of any Adams/Solver 

commands, except CONTROL and STOP. 

The data access subroutines report the current values for system variables, or return static data stored in 

a model. User subroutines can use this data to define their output quantities. 

The following table lists the names and definitions for the data access subroutines: 

5

6 



AKISPL Uses the Akima cubic-curve fitting method to interpolate data specified 

in a SPLINE statement. 

BISTOP Evaluates a BISTOP function. 

CHEBY Evaluates a Chebyshev polynomial. 

CUBSPL Uses the traditional cubic-curve fitting method to interpolate data 

specified in a SPLINE statement. 

ERRMES Allows user subroutines to output information/warning error messages. 

FORCOS Evaluates a Fourier cosine series. 

FORSIN Evaluates a Fourier sine series. 

GETCPU Retrieves the current CPU time. 

GETINM Retrieves information as to whether the current Adams/Solver 

command input mode is interactive or command file-driven. 

GETINT Retrieves the type of integrator used for the current simulation. 

GETMOD Returns an integer variable that specifies the current analysis mode. 

GETSLV Retrieves the name of the active solver, either HARWELL or 

CALAHAN. 

GETSTM Retrieves the current simulation time. 

GETVER Retrieves the current Adams/Solver version number as it appears in the 

Adams/Solver banner. 

GTARAY Accesses the double-precision numbers stored by an IC-type ARRAY 

statement. 

GTCMAT Computes the compliance matrix for a set of markers in an 

Adams/Solver model. 

GTCURV Evaluates a B-spline or user-written curve that a CURVE statement 

creates. 

GTSTRG Accesses the character string that a STRING statement stores. 

GTUNTS Accesses model unit information from Adams/Solver. 

HAVSIN Evaluates a haversine function. 

IMPACT Provides a simple contact model. 

ISTRNG Converts a number in an integer variable to the characters representing 

that number. The character data in ISTRNG is always left justified. 

Unused space in ISTRNG is padded with blanks. 

MODINF Accesses the original mode numbers and the modal frequencies, in 

Hertz, of all active modes associated with a FLEX_BODY statement.


Unsupported Subroutines 


NMODES Accesses the number of modal generalized coordinates associated with 

a FLEX_BODY statement. 

POLY Evaluates a polynomial function. 

PUT_SPLINE Passes Adams/Solver the x, y, and z data that defines a SPLINE element. 

RCNVRT Converts rotational coordinates from one representation to another. 

RSTRNG Converts a double-precision variable to a character string. 

SHF Evaluates a simple harmonic function. 

STEP Approximates a STEP function with a cubic polynomial. 

STEP5 Approximates a STEP5 function with a quintic polynomial. 

SYSARY Provides system-state values, such as displacement and velocity, to your 

subroutines, and defines and stores the Adams/Solver state variables on 

which the system states are dependent. 

SYSFNC Provides a single-system state value, such as displacement or velocity, 

to your subroutines, and defines and stores the Adams/Solver state 

variables on which the system state is dependent. 

SYSPAR Allows you to supply the analytical partial derivatives of a subroutine 

with respect to values measured through SYSFNC and SYSARY. 

TCNVRT Converts translational coordinates from one type of coordinate system 

to another. 

TIMGET Returns the simulation time corresponding to the last successful 

simulation step. 

UCOVAR Used with UCOSUB, tells Adams/Solver which of the principal axes 

coordinates are used in the user-defined constraint. 

USRMES Allows you to output messages for information or for documenting 

errors that occur in user-written subroutines. 

Although Adams/Solver continues to recognize unsupported subroutines, new subroutines have made 

them obsolete. The new subroutines are more flexible and straightforward to use. We recommend that 

you use the new subroutines, as the unsupported ones might be removed from future Adams/Solver 

releases. 

The following table lists the unsupported subroutines, along with references to alternate subroutines: 

7

8 


Unsupported Subroutines and Their Alternates 

ADAMS_DECLARE_THREADSAFE 

A call to the ADAMS_DECLARE_THREADSAFE subroutine informs Adams/Solver (C++) that the 

user-written subroutine is threadsafe and that multiple threads can execute this user-written subroutine 

simultaneously. 

Use 

Called By 

Any user-written subroutine 

Prerequisite 

None 

Calling Sequence 

CALL ADAMS_DECLARE_THREADSAFE () 

Input Arguments 

None 

Output Arguments 

None 

Extended Definition 

Instead of: Use: 

DEQINF SYSFNC 

FNCDEP SYSARY; SYSFNC 

INFO SYSARY; SYSFNC 

SPLINE AKISPL; CUBSPL 

ANLMOD GETMOD 

Adams/Solver (C++) includes the option of threaded (parallel) execution. That is, multiple threads are 

permitted to execute portions of the code simultaneously. On machines with multiple processors, this can 

result in a significant reduction in the wall time required for a simulation to complete. 

This parallel capability places restrictions on the way the code is written to ensure that different threads 

do not adversely interact with each other. Code that is written in such a way is threadsafe. Care has been 

take to ensure that relevant portions of Adams/Solver (C++) are threadsafe, but no such assumption can


be made about user-written subroutines. Consequently, by default, all user-written subroutines are 

executed serially. By default, no user-supplied subroutine will take advantage of the parallel capabilities 

of Adams/Solver (C++). 

Because complex models often use user-written subroutines extensively, it can greatly improve 

performance to execute these in parallel, as well. If this is to be done, you must ensure that the userwritten 

subroutine and its dependants are threadsafe. If so, the user-written subroutine can indicate this 

with a call to ADAMS_DECLARE_THREADSAFE. This call should occur during subroutine 

initialization (iflag = true). Adams/Solver (C++) then permits threads to make simultaneous calls to that 

user-written subroutine. For more information, see the PREFERENCES statement. 

Writing Threadsafe Code 

While a complete guide to writing parallel code is left to other texts, a few general points are covered 

here. 

Code can be made thread-safe by eliminating any possibility for data (program variables) to be shared 

between different threads. For example, if all variables in a user-written subroutine were either passed in 

as arguments or are dynamically allocated local variables, then that user-written subroutine would be 

threadsafe. 

Coding in such a manner, however, is often not practical. There may be a need for a user-written 

subroutine to access constant tabular data or other parameters, which is most efficiently implemented as 

global data and shared by multiple threads. To allow for this, during subroutine initialization, all userwritten 

subroutines are run serially. In addition, calls to REQSUBs are always performed serially. 

General Guidelines 

1. The only data that can be modified at any time is: 

Dynamically allocated local variables. 

Static or global variable that are uniquely indexed so there is no possibility that two threads will 

modify them simultaneously. For example, a user-written subroutine with a static array of data 

could safely modify the array element that is uniquely mapped to the ID of the current modeling 

element being evaluated. Because each thread is evaluating a different modeling element, the 

threads will not access the same array element at the same time. 

2. All data that will be shared by multiple threads must be allocated and set during subroutine 

initialization. At other times, this data may be read, but must not be written to. 

3. No special coding practices need to be followed inside a REQSUB. 

FORTRAN-Specific Guidelines 

1. Some FORTRAN compilers (such as Digital/Compaq Visual FORTRAN) statically allocate 

local variables by default. This is avoided by using a compiler option (/automatic) that causes all 

local variables to be allocated on the stack (unless the SAVE statement is used). 

9

10 


2. Avoid or minimize the use of data in COMMON blocks. Such data is statically allocated and 

shared between threads. As stated in the General Guidelines above, such data must either be 

written during the initialization phase only or uniquely indexed. 

3. Avoid or minimize the use of SAVE statements. Again, this data is statically allocated and must 

either be written during the initialization phase only or uniquely indexed. 

Note: • There is no way to specify, ensure, or verify that any modeling element be 

evaluated by any particular thread. 

ADD_MASS_PROPERTY 

The ADD_MASS_PROPERTY utility subroutine accepts the mass properties for two parts or sets of 

parts and returns the mass properties for the aggregate set. 

It is primarily intended for use with the BODY_MASS_PROPERTY utility subroutine to compute the 

aggregate mass properties for a group of parts. 

Use 

Called By 


Prerequisite 

None 

• The use of synchronization constructs within the user-written subroutines 

themselves is not recommended. Because user-written subroutines are called so 

frequently, it is likely that the overhead of the synchronization will exceed the 

benefit of parallelization. 

vector returns: For iord value: 

(1) 

(2) 

0 1 2 

F( x, x') 

0 

∂ F( x, x') 

--------------------- 

∂ x 

∂ F( x, x') 

--------------------- 

∂ x' 

∂ 2 F( x, x') 

x 2 

----------------------- 

∂ 

∂ 2 F( x, x') 

----------------------- 

∂ x'∂ 

x 


CALL ADD_MASS_PROPERTY (cm1, mass1, ip1, cm2, mass2, ip2)



cm1 A double-precision array of length 3 containing the center of mass of the first part or set 

of parts expressed in the GCS. 

mass1 A double-precision variable containing the mass of the first part or set of parts. 

ip1 A double-precision array of length 6 giving the 6 independent terms in the inertia tensor 

for the first part or set of parts. (Ixx, Iyy, Izz, Ixy, Ixz, Iyz) These inertia terms much be 

computed about the center of mass of the part and oriented in GCS. 

cm2 A double-precision array of length 3 containing the center of mass of the second part or 

set of parts expressed in the GCS. 

mass2 A double-precision variable containing the mass of the second set. 


for the second part or set of parts. (Ixx, Iyy, Izz, Ixy, Ixz, Iyz) These inertia terms much 

be computed about the center of mass of the part and oriented in GCS. 


cm2 A double-precision array of length 3 containing the center of mass of the combined 

system of parts expressed in GCS. 

mass2 A double-precision variable containing the mass of the combined system of parts. 

Ip2 A double-precision array of length 6 containing the 6 independent components of in the 

inertia tensor for the combined system of parts. (Ixx, Iyy, Izz, Ixy, Ixz, Iyz) These inertia 

terms are expressed about the combined center of mass and are oriented in GCS. 


The ADD_MASS_PROPERTY utility subroutine provides a convenient way for user-written 

subroutines to compute the current mass properties of sets of parts. 

Cautions 

The user is responsible for employing consistent units when adding mass properties. 

Example 

C=======================================+=========================== 

SUBROUTINE REQSUB (ID, TIME, PAR, NPAR, IFLAG, RESULT) 

C+-----------------------------------------------------------------* 

C 

C This REQSUB gets the mass properties of part 2, and constructs the 

C aggregate mass properties of the set of parts 3-9 (constructed to be 

C equivalent, in aggregate, to part 2) and returns the first four 

terms 

C of the inertia tensor for each, 2 and 3-9, for comparison. 

C 

11

12 


IMPLICIT NONE 

C 

C Inputs: 

C 

INTEGER ID, NPAR, IBODY 

DOUBLE PRECISION PAR(*), TIME 

LOGICAL IFLAG 

C 

C Outputs: 

C 

DOUBLE PRECISION RESULT(8) 

C 

C Local Variables: 

C 

DOUBLE PRECISION CM(3), MASS, IP(6) 

DOUBLE PRECISION SUMCM(3), SUMMASS, SUMIP(6) 

C 

C+-----------------------------------------------------------------* 

C 

C 

C Output 8 variables. 

C - The first four elements of the IP of the reference body 

C - The first four elements of the IP of the equivalent set of 

bodies. 

C 

C Get the properties of the reference body 

C 

CALL BODY_MASS_PROPERTY ('Part', 2, CM, MASS, IP) 

C 

RESULT(1) = IP(1) 




C 

C Get the aggregate properties of the equivalent set of bodies. 

C 

SUMMASS = 0 

SUMCM(1) = 0 

SUMCM(2) = 0 

SUMCM(3) = 0 

SUMIP(1) = 0 

SUMIP(2) = 0 

SUMIP(3) = 0 

SUMIP(4) = 0 

SUMIP(5) = 0 

SUMIP(6) = 0 

DO IBODY=3, 9 

CALL BODY_MASS_PROPERTY ('Part', IBODY, CM, MASS, IP) 

CALL ADD_MASS_PROPERTY (CM, MASS, IP, SUMCM, SUMMASS, SUMIP) 

ENDDO 

RESULT (5) = SUMIP(1) 



RESULT (8) = SUMIP(4)

RETURN 

END 

AKISPL 


The AKISPL data access subroutine uses the Akima cubic-curve fitting method to interpolate data from 

the SPLINE statement (C++ or FORTRAN). 

Use 

Called By 


Prerequisite 

SPLINE statement in the dataset 


CALL AKISPL (xval, zval, id, iord, array, errflg) 

13

14 



xval A double-precision value that specifies the x value at which AKISPL is 

to interpolate y. 

zval A double-precision value that specifies the z value at which AKISPL is 

to interpolate y. 

id An integer variable that specifies the identifier of the corresponding 

SPLINE statement. 

iord An integer variable that specifies the order of the derivative that AKISPL 

is to return. The order is usually zero, but it can be one or two. 


array A double-precision array of length three. If iord equals zero, array(1) 

returns the value of y that AKISPL calculates. If iord equals one, array 

returns: 


∂ y 

----- 

∂ x 

2 

y 

∂ 

∂ 2 ------x 

AKISPL accesses data in a SPLINE statement (C++ or FORTRAN), using the Akima cubic-curve fitting 

method to fit a spline to the data (that is, to add interpolated points), and returns one of the following: 

• A value for the dependent variable (y) for each value it receives for the independent variable or 

variables. 

• The first partial derivatives of the dependent variable. 

and , respectively. If iord equals two, array returns: 

Note that: 

∂ y----- 

∂ z 

2 

y 

∂ 

----------- 

∂ x∂ z 

2 

y 

∂ 

∂ 2 -----z 

, , and , respectively. 

2 

y 

∂ ∂ 

----------- = 

----------- 

∂ z∂ x ∂ x∂ z 

errflg A logical (true or false) variable that AKISPL returns to the calling 

subroutine. If AKISPL detects an error in its calculations, it sets errflg to 

true before it returns errflg to the calling subroutine. 

• The second partial derivatives of the dependent variable. 

If the spline data input with the SPLINE statement has one independent variable, Adams/Solver uses a 

cubic polynomial to interpolate between points. If the spline data has two independent variables, 

Adams/Solver first uses a cubic interpolation method to interpolate between points of the first (x) 

2 

y


independent variable, and then uses a linear method to interpolate between curves of the second (z) 

independent variable. 

In addition to the AKISPL data access subroutine, Adams/Solver includes the CUBSPL data access 

subroutine, which uses the traditional cubic curve fitting method. Use CUBSPL if the primary usage is 

in MOTIONs. Use AKISPL if the primary concern is with the forces or torques acting on a model. 

If the spline data incorporates sudden changes in value, the CUBSPL data access subroutine gives more 

oscillatory results for the curve or surface than AKISPL gives. However, the first and second derivatives 

of CUBSPL are smoother than those AKISPL calculates. 

ANALYS 

The ANALYS subroutine performs the analysis requested of it. 

Use 

Called By 

CONSUB 

Prerequisite 

None 


CALL ANALYS (antype, cid, timbeg, timend, init, istat) 

15

16 



antype One of the character strings, DYNAMICS, KINEMATICS, STATICS, 

or TRANSIENT, that indicate the analysis type Adams/Solver is to 

perform. 

cid A character string or variable associated with this analysis. If the 

CONSUB driver subroutine calls DATOUT, Adams/Solver prints the 

current value of cid (truncated to twenty characters) in the IDANAL 

field of the analysis output block in the results file. 

timbeg A double-precision value that specifies the time at which you want the 

analysis to begin. This must equal the current simulation time. If it does 

not equal the current simulation time, Adams/Solver issues an error 

message, stops the simulation, and returns to the calling subroutine. 

timend A double-precision value that specifies the time at which you want the 

analysis to end. The value must be greater than or equal to timbeg. If 

timend is less than timbeg, Adams/Solver issues an error message, 

stops the simulation, and returns to the calling subroutine. 

Output Argument 


Note that Adams/Solver modifies this argument to reflect the 

simulation time to which the simulation has progressed. Therefore, you 

must be careful to pass a double-precision variable, not a constant, in 

the argument list for this variable. Passing in a constant can result in a 

fatal error or program crash. 

init A logical variable that tells Adams whether or not it should reformulate 

the equations of motion and perform system assembly at the start of the 

simulation. 

istat An integer variable that indicates either the success or the reason for the 

failure of the call to ANALYS. 

If: Then: 

istat = 0 The call to ANALYS was successful. 

istat = -1 antype is neither DYNAMICS, KINEMATICS, STATICS, nor 

TRANSIENT. 

istat = -9 timbeg is not equal to the current simulation time. 

istat =-10 timend is less than timbeg. 

ANALYS passes control to the Adams/Solver simulation routines. Adams/Solver performs the analysis


requested. This gives you complete control over the time for which to get a simulation. 

Call ANALYS from CONSUB as often as necessary to create the simulation required. After completion 

of each analysis, Adams/Solver returns program control to CONSUB. For an example of a CONSUB 

driver subroutine that calls ANALYS, see CONSUB. 

Caution: • ANALYS may only be called by CONSUB. 

BISTOP 

BISTOP evaluates a BISTOP function (C++ or FORTRAN). 

Use 

Called By 


Prerequisite 

None 


• Adams/Solver must generate the state equations before performing any analysis. If 

an analysis has been performed before ANALYS is called, the equations have 

already been set up for that type of analysis. Set init equal to true on the first call to 

ANALYS, otherwise. 

• When program control passes to CONSUB, automatic generation of output stops. 

To generate output, call DATOUT. 

CALL BISTOP (x, x', x1, x2, k, e, cmax, d, iord, vector, errflg) 

17

18 



x A double-precision variable that specifies the deformation to be used to 

compute the force. 

x' A double-precision variable containing the first time derivative of x. 

x1 A double-precision variable that specifies the lower bound of x. If x is less 

than x1, Adams/Solver calculates a positive value for the force. The value of 

x1 must be less than the value of x2. 

x2 A double-precision variable that specifies the upper bound of x. If 

x is greater than x2, Adams/Solver calculates a negative value for the force. 

The value of x2 must be greater than the value of x1. 

k A positive, double-precision variable that specifies the stiffness for the 

force-deformation law. 

e A positive, double-precision variable that specifies the exponent in the forcedeformation 

law. For a stiffening spring characteristic, use e > 1.0. For a 

softening spring characteristic, use 0 < e < 1.0. 

cmax A non-negative, double-precision variable that specifies the maximum 

damping coefficient that is to be applied. 

d A positive, double-precision variable that specifies the penetration at which 

Adams/Solver applies full damping, CMAX. 

iord An integer variable that specifies the order of the derivative that BISTOP is 

to return. IORD can be zero, one, or two. 


vector A double-precision vector that returns the values calculated by the 

subroutine. For BISTOP, vector is a vector of length three. The following 

table indicates what information vector returns for each of the possible values 

of iord. 

errflg A logical (true or false) variable that BISTOP returns to the calling 

subroutine. If BISTOP detects an error in a subroutine call statement, it sets 

errflg to true before it returns errflg to the calling subroutine. 


The BISTOP function models a force restricting the displacement of a body relative to a gap in another 

body. 

The force BISTOP evaluates is zero, as long as the floating part lies within the gap in the restricting body. 

It is nonzero when the floating part tries to move beyond the gap boundaries in either direction.


The force has two components: a spring or stiffness component and a damping or viscous component. 

The stiffness component is a function of the penetration of the floating part into the restricting part. The 

stiffness opposes the penetration. 

The damping component of the force is a function of the speed of penetration multiplied by a damping 

coefficient. The damping opposes the direction of relative motion. To prevent a discontinuity in the 

damping force at contact, the damping coefficient is, by definition, a cubic step function of the 

penetration. Therefore, at zero penetration, the damping coefficient is always zero. The damping 

coefficient achieves a maximum, cmax, at a user-defined penetration, d. Even though the points of 

contact between the floating part and the restricting part may change as the system moves, Adams/Solver 

always exerts the force between the I and the J markers. Examples of systems you can model with the 

BISTOP function include a ball rebounding between two walls and a slider moving in a slot. The slider 

is the floating body, and the part containing the slot is the restricting body. As long as the slider remains 

within the confines of the slot, there is no force acting on the slider. But if the slider tries to move beyond 

the slot, a force turns on, effectively preventing the slider's escape. 

The following summarizes the BISTOP function: 

• When x1 x x2, force = 0. 

• When x < x1, p = x1 - x and the force is positive. 

• When x > x2, p = x - x2 and the force is negative. 

• When p < d, the damping coefficient is a cubic step function of the penetration. 

• When p d, the damping coefficient is cmax. 

The values of k, e, cmax, and d depend on the materials used in the two parts and on the shapes 

of the parts. 

The following equation defines BISTOP: 

STOP 

Min k ( x1 – x) 

e ( ⋅ – STEP ( x, x1 – d, cmax, x10) ⋅x′0 

, ) 

0 

Max – k ( x – x2) e ⎧ 

x < x1 ⎪ 

= ⎨ 

x1 ≤x ≤x2 

⎪ 

⎩ ( ⋅ – STEP ( x, x2, 0, x2 + d, cmax ) ⋅x′0 

, ) x > x2 See an explanation of the STEP function (C++ or FORTRAN). 

Caution: • BISTOP is only used to determine forces or torques. 

• When e is less than or equal to one, the rate of change of the force is discontinuous 

at contact. This may cause convergence problems. 

BODY_MASS_PROPERTY 

The BODY_MASS_PROPERTY utility subroutine accepts specifiers for either a single part or the entire 

ADAMS model and returns to the caller the mass properties (mass, center of mass and inertia tensor) for 

that part or model. 

19

20 


Use 

Called By 

Any of a REQSUB, SENSUB, SEVSUB or CONSUB. 

Prerequisite 

None 


CALL BODY_MASS_PROPERTY (type, id, cm, mass, ip) 


type A character variable that specifies the type of modeling element for which the mass 

properties are requested. The valid options are one of "Part", "Point_Mass", 

"Flex_Body" or "Model". The input is case-insensitive but abbreviations are not 

permitted. 

id An integer variable that specifies the ID of the element of the type specified for which 

the mass properties are requested. If the type is "Model" then this input is ignored. 

For all other types this is required. 


cm A double-precision array of length 3 containing the center of mass of the requested 

modeling element expressed in GCS. 

mass A double-precision variable containing the mass of the requested modeling element. 

ip A double-precision array of length 6 containing the 6 independent components of in 

the inertia tensor for requested modeling element. (Ixx, Iyy, Izz, Ixy, Ixz, Iyz) These 

inertia terms are expressed about the elements center of mass and are oriented in GCS. 

Caution: The BODY_MASS_PROPERTY utility subroutine provides access to state-dependent 

information to the user-written subroutines. However, since this information is expected 

to be used only for monitoring and control purposes and not to affect the dynamics, no 

functional dependencies are registered. Consequently, this utility subroutine can only be 

called from the user-written subroutines that cannot add functional dependencies - 

REQSUB, SENSUB, SEVSUB and CONSUB. 

CHEBY 

The CHEBY subroutine evaluates a Chebyshev polynomial.

Use 

Called By 


Prerequisites 

None 


CALL CHEBY (x, x0, par, npar, iord, value, errflg) 


21

22 



x A double-precision variable that specifies the independent variable. 

x0 A double-precision variable that specifies a shift in the Chebyshev 

polynomial. 

par A double-precision array of coefficients (a0,...,an). 

npar An integer variable that specifies the number of coefficients specified. 

iord An integer variable that specifies the order of the derivative that CHEBY 

is to return. IORD can be zero, one, or two. 


value A double-precision value the subroutine returns. The table below 

summarizes the value it returns: 

errflg A logical (true or false) variable that CHEBY returns to the calling 

subroutine. If CHEBY detects an error in the subroutine call statement, 

it sets errflg to true before it returns errflg to the calling subroutine. 


CHEBY evaluates a Chebyshev polynomial. The following equation defines CHEBY: 

where: 

and: 

0 

1 

2 

, 

IORD: Value: 

F( x) 

∂ F( x) 

-------------- 

∂ x 

∂ F 2 ( x) 

∂ x 2 

---------------- 

Tj( x – x0) – 2 ⋅( x – x0) ⋅Tj 

– 1( ( x – x0) ⋅Tj 

– 2( x – x0) ) 

T0( x – x0) = 

1 

,

T1( x – x0) = 

x – x0 CUBSPL 

, 


CUBSPL uses the traditional cubic-curve fitting method to interpolate data in the SPLINE statement 

(C++ or FORTRAN). 

Use 

Called By 


Prerequisite 

SPLINE statement in the dataset 


j = 0 

ajTj( x – x0) CALL CUBSPL (xval, zval, id, iord, array, errflg) 

N 

∑ 

23

24 



xval A double-precision value that specifies the x value at which CUBSPL 

is to interpolate y. 

zval A double-precision value that specifies the z value at which CUBSPL 

is to interpolate y. 

id An integer variable that specifies the identifier of the corresponding 


iord An integer variable that specifies the order of the derivative that 

CUBSPL is to return. The order is usually zero, but can be one or two.




array A double-precision array of length three. The values contained in array 

depend on IORD. The table below summarizes what array is to contain: 

IORD: Array: 

0 The interpolated value of 

y 

Array(0) = y 

Array(1) = 0 

Array(2) = 0 

1 The first partial 

derivatives of y with 

respect to x and z. Array(1) = 

2 The second partial 

derivatives of y with 

respect to x and z. 

Note that: 

∂ 2 y 

----------- 

∂ z∂ x 

Array(2) = 

Array(3) = 0 

Array(1) = 

Array(2) = 

Array(3) = 

errflg A logical (true or false) variable that CUBSPL returns to the calling 

subroutine. If CUBSPL detects an error in its calculations, it sets errflg 

to true before it returns errflg to the calling subroutine. 

CUBSPL accesses data in a SPLINE statement, using the traditional cubic curve-fitting method to fit a 

spline to the data, and returns one of the following: 

• A value for the dependent variable (y) for each value it receives for the independent variable or 

variables. 

• The first partial derivatives of y with respect to the dependent variable(s). 

= 

∂ 2 y 

----------- 

∂ x∂ z 

∂ y 

----- 

∂ x 

∂ y 

----- 

∂ z 

∂ 2 y 

∂ 2 -------x 

∂ 2 y 

----------- 

∂ x∂ z 

∂ 2 y 

-------- 

25

26 


• The second partial derivatives of y with respect to the dependent variable(s). 

If the spline data input with the SPLINE statement has one independent variable, Adams/Solver uses a 

cubic polynomial to interpolate between points. If the spline data has two independent variables, 

Adams/Solver first uses a cubic interpolation method to interpolate between points of the first (x) 

independent variable, and then uses a linear method to interpolate between curves of the second (z) 

independent variable. 

In addition to CUBSPL, Adams/Solver includes the AKISPL data access subroutine, which uses the 

Akima cubic curve-fitting method. Use CUBSPL when defining motion inputs. Use AKISPL if the 

primary concern is with the forces or torques acting on the model. 

If the spline data incorporates sudden changes in value, CUBSPL gives more oscillatory results for the 

curve or surface than are given by the AKISPL data access subroutine. However, the first and second 

derivatives are smoother than those of the curve or surface given by AKISPL. This may be an important 

consideration. For example, if one of these spline subroutines is used to define a motion, Adams/Solver 

uses the second derivative to compute the force or torque attributable to the motion. It also uses the first 

and second derivatives to calculate results. If one of these spline subroutines is used to define a force, the 

dependent values give the force, and Adams/Solver uses the first derivative to calculate results. 

DATOUT 

DATOUT outputs all data from a simulation initiated by the ANALYS execution control subroutine. 

Depending on the statements in the dataset, Adams/Solver may output data to the request, graphics, 

results, and FEM files. 

Use 

Called By 

CONSUB 

Prerequisite 

Call to ANALYS 


CALL DATOUT (istat) Output Argument 

istat An integer variable that indicates whether the call to DATOUT was 

successful. If istat = 0, the call to DATOUT was successful. Currently, 

Adams/Solver always returns a value of zero. You do not need to check istat 

before continuing.



DATOUT outputs data from a simulation initiated by ANALYS. When you advance the simulation by a 

call to ANALYS, Adams/Solver does not automatically output data. If you want to process output (for 

example, requests, graphics), call DATOUT from the CONSUB driver subroutine. In this way, you can 

choose the type and amount of output. For an example of a CONSUB driver subroutine that calls 

DATOUT, see CONSUB. 

ERRMES 

ERRMES provides the facility for outputting error messages from user-written subroutines. 

Use 

Called By 


Prerequisite 

None 


CALL ERRMES (errflg, mesage, id, endflg) 


errflg A logical (true or false) variable. When errflg is true, ERRMES writes the 

message passed in to its output files. 

mesage A character string or variable of as many as eighty characters that you want 

ERRMES to document when the subroutine has an error. This character string 

should be a descriptive message and should include the name of the 

subroutine with the error. 

id An integer variable that specifies the identifier of the statement that is 

currently invoking the user-written subroutine. 

endflg A character variable that stops execution when it equals STOP. If endflg has 

any other value, Adams/Solver continues execution. 


The ERRMES data access subroutine allows you to output messages to document errors that occur in 

user-written subroutines. The messages always go to the message file, and during interactive execution, 

Adams/Solver displays them on the screen. 

27

28 


Although ERRMES can be called in response to any execution problem, it should always be called in 

response to a data access or a general subroutine call that returns an error flag. For an example of a 

DIFSUB evaluation subroutine that calls ERRMES, see DIFSUB. 

FORCOS 

FORCOS evaluates a Fourier cosine series. 

Use 

Called By 


Prerequisite 

None 


CALL FORCOS (x, x0, w, par, npar, iord, value, errflg)





x0 A double-precision variable that specifies a shift in the Fourier cosine 

function. 

w A double-precision variable that specifies the fundamental frequency of the 

series. The variable w must be in radians per unit of the independent 

variable. 


npar An integer variable that indicates the number of coefficients specified in the 

Fournier cosine series. 

iord An integer variable that defines the order of the derivative that FORCOS is 


errflg A logical (true or false) variable that FORCOS returns to the calling 

subroutine. If FORCOS detects an error in the subroutine call statement, it 

sets errflg to true before it returns errflg to the calling subroutine. 

value A double-precision number returned by FORCOS. The meaning of the 

quantity depends on the value of IORD. The table below explains in more 

detail: 

IORD: Value: 

0 Value of the FORCOS function. 

1 Partial derivative of the FORCOS 

function with respect to the 

independent variable, x. 

2 Second partial derivative of the 

FORCOS function with respect to 

the independent variable, x. 

F( x) 

∂ F 

----- 

∂ x 

∂ 2 F 

∂ 2 -------x 

29

30 



FORCOS evaluates a Fourier cosine series. The following equation defines FORCOS: 

n 

∑ 

j = 0 

where: 

For an example of a MOTSUB evaluation subroutine that calls FORCOS, see MOTSUB. 

FORSIN 

FORSIN evaluates a Fourier sine series. 

Use 

Called By 


Prerequisite 

None 

ajTj ( x – x0) Tj( x – x0) = 

cos( 

j ⋅w ⋅( 

x – x0) ) 


CALL FORSIN (x, x0, w, par, npar, iord, value, errflg)





x A double-precision variable that specifies the independent variable. If the 

independent variable in the function is time, x is the system variable TIME 

(click here to see the FORTRAN version of the TIME function or for C++, 

click here). 

x0 A double-precision variable that specifies a shift in the Fourier sine 

function. 

w A double-precision variable that specifies the fundamental frequency of 

the series. The variable w must be in radians per unit of the independent 

variable. 


npar An integer variable that indicates the number of coefficients specified in 

the Fournier sine series. 

iord An integer variable that defines the order of the derivative that FORSIN is 


errflg A logical (true or false) variable that FORSIN returns to the calling 

subroutine. If FORSIN detects an error in the subroutine call statement, it 


value A double-precision number returned by FORSIN. The meaning of the 

quantity depends on the value of IORD. The table below explains in more 

detail: 

IORD: Value: 

0 Value of the FORSIN function. 

1 Partial derivative of the FORSIN 

function with respect to the 


2 Second partial derivative of the 

FORSIN function with respect to the 


F( x) 

∂ F 

----- 

∂ x 

∂ 2 F 

∂ 2 -------x 

31

32 


FORSIN evaluates a Fourier sine series. The following equation defines FORSIN: 

n 

∑ 

j = 0 

where: 

GET_FULL_MATRIX_DATA 

Returns the values entered in a dataset MATRIX statement (C++ or FORTRAN) of type full, given the 

statement identifier. 

Use 

ajTj ( x – x0) Tj( x – x0) = 

cos( 

j ⋅w ⋅( 

x – x0) ) 

Called By 


Prerequisite 

MATRIX statement in the dataset 


GET_FULL_MATRIX_DATA(id, vals, size, ierr)



id An integer variable that specifies the ID of the corresponding MATRIX 

statement. 

size An integer variable that specifies the size of the MATRIX. 

GET_FULL_MATRIX_DATA uses this value to compare against the 

MATRIX’s true size; a check for a valid call. 


vals A double-precision array of size ‘size’ contains the values from the 

MATRIX statement. 

ierr An integer variable that indicates the success of the call to 

GET_FULL_MATRIX_DATA: 


GET_FULL_MATRIX_DATA returns the values stored in a dataset MATRIX statement of type full. You 

can determine the matrix ordering of the matrix data (row or column ordered), by the type that 

GET_MATRIX_INFO returns. The order may not be as entered in the MATRIX statement. 

GET_MATRIX_INFO 

Returns information about a dataset MATRIX statement given the statement identifier (C++ or 

FORTRAN). 

Use 

Called By 


Prerequisite 


• ierr=0 Successful 

• ierr=1 Failed, no MATRIX having an 

identifier of ID exists in the dataset 

• ierr=2 Failed, the value of ‘size’ does not 

match the size of the MATRIX 

• ierr=3 Failed, the MATRIX type is sparse 

Tip: Call GET_MATRIX_INFO to get the size and type of the MATRIX. 

33

34 



GET_MATRIX_INFO(id, type, nrows, ncols, size, ierr) 



statement. 


type An integer value that indicates the MATRIX type as stored by Adams/Solver. 


GET_MATRIX_INFO is useful when used with the GET_FULL_MATRIX_DATA and 

GET_SPARSE_MATRIX_DATA utility subroutines. It returns: 

• Matrix type needed to determine which utility to call to get the MATRIX data 

• MATRIX size needed in the call to GET_FULL_MATRIX_DATA or 

GET_SPARSE_MATRIX_DATA 

• Number of rows and columns needed to interpret the full matrix data. 

GET_GRAVITY 

• type=1 Sparse 

• type=2 Full, row-order 

• type=3 Full, column-order 

nrows An integer variable that contains the number of rows in the MATRIX. 

ncols An integer variable that contains the number of columns in the MATRIX. 

size An integer value that contains the total number of entries in a sparse MATRIX. 

For a full matrix, size is ncols*nrows. 

ierr An integer variable that indicated the success of the call to 

GET_MATRIX_INFO. 


• ierr=1 Failed, no MATRIX having an 

identifier of id exists in the dataset 

Returns the current Adams/Solver gravity vector. Specifically this is the gravity vector that would have 

been specified by the ACCGRAV statement or command. See the ACCGRAV documentation for more 

details.

Use 


Use this utility subroutine to obtain the Adams gravity vector from a user-written subroutine. 

Called by 

Any user-written subroutine. 

Prerequisite 

None 


CALL GET_GRAVITY (GX, GY, GX) 


None 


GX A double-precision variable containing the x component of gravitational 

acceleration with respect to the ground coordinate system (GCS) in model 

units. 

GY A double-precision variable containing the ycomponent of gravitational 


units. 

GZ A double-precision variable containing the zcomponent of gravitational 


units. 

GET_SPARSE_MATRIX_DATA 

Returns the values entered in a dataset MATRIX statement (C++ or FORTRAN) in sparse matrix form 

given the statement identifier. 

Use 

Called By 


Prerequisite 


35

36 



GET_SPARSE_MATRIX_DATA(id, rows, cols, vals, size, ierr) 



statement. 

size An integer variable that specifies the size of the MATRIX. 

GET_SPARSE_MATRIX_DATA uses this value to compare against the 

MATRIX’s true size; a check for a valid call. 


rows An integer array of size size that contains the row indices corresponding to the 

MATRIX values stored in vals. 

cols An integer array of size size that contains the column indices corresponding 

to the MATRIX values stored in vals. 

vals A double-precision array of size size that contains the values from the 

MATRIX statement in sparse form. 

ierr An integer variable that indicates the success of the call to 

GET_SPARSE_MATRIX_DATA: 


GET_SPARSE_MATRIX_DATA returns the values entered in a dataset MATRIX statement in sparse 

matrix form. It can be used with any matrix type, but may be inefficient for a large MATRIX of type full. 

Sparse matrix form is a compact way of storing matrix data when many data entries are zero; only the 

non-zero values are stored. The rows and cols arrays provides the row and column matrix locations for 

the corresponding data in the vals array. When using GET_SPARSE_MATRIX_DATA to get data of a 

matrix type full, all values are returned. GET_SPARSE_MATRIX_DATA makes no attempt to reduce 

the size of the data by eliminating zero entries. 

GETCPU 


• ierr=1 Failed, no MATRIX having an identifier of ID 

exists in the dataset 

• ierr=2 Failed, the value of size’ does not match the 

size of the MATRIX 

Tip: Call GET_MATRIX_INFO to get the size and type of the MATRIX.

GETCPU retrieves CPU time used so far. 

Use 

Called by 


Prerequisite 

None 


CALL GETCPU (value) 



value Double-precision variable that contains the current CPU time. 

GETINM 

The GETINM reports whether the current Adams/Solver command input mode is interactive or 

command file-driven. 

Use 

Called by 


Prerequisite 

None 


CALL GETINM (value) 


value A logical variable that returns true if the Adams/Solver command input mode 

is interactive, and false if it is command file-driven. 

GETINT 

37

38 


The GETINT data access subroutine retrieves the type of integrator used for the current simulation. The 

strings GETINT returns to indicate the integrator type are: ABAM, GSTIFF, GSTIFF_SI2, GSTIFF_SI1, 

WSTIFF, WSTIFF_SI2 and WSTIFF_SI1. 

Use 

Called by 


Prerequisite 

None 


CALL GETINT (value) 


value A character variable of ten characters containing the integrator type. 


GETINT returns the type of integrator used for the current simulation. It can have one of the following 

values: 

• ABAM - Adams-Bashforth-Adams-Moulton integrator 

• GSTIFF - The fixed coefficient BDF integrator using an index three equation formulation 

• GSTIFF_SI2- The fixed coefficient BDF integrator using a stabilized index two equation 

formulation 

• GSTIFF_SI1- The fixed coefficient BDF integrator using a stabilized index one equation 

formulation 

• WSTIFF - The variable coefficient BDF integrator 

• WSTIFF_SI2 - The fixed coefficient BDF integrator using a stabilized index two equation 

formulation 

• WSTIFF_SI1- The fixed coefficient BDF integrator using a stabilized index one equation 

formulation 

• UNDEF - The integrator is undefined 

Caution: Value is meaningful only during a simulation, that is, after you have issued a SIMULATE 

command. 

GETMOD

GETMOD returns the current analysis mode. 

Use 

Called By 



CALL GETMOD (mode) 



mode An integer variable that specifies the current analysis mode. 

GETSLV 

GETSLV returns the name of the active solver, either HARWELL or CALAHAN. 

Use 

Called by 


Variable: Analysis mode: 

mode=1 Kinematics 

mode=2 Reserved 

mode=3 Initial conditions 

mode=4 Dynamics 

mode=5 Statics 

mode=6 Quasi-statics 

mode=7 Linearization 

Caution: GETMOD should be called from a user-written subroutine only when iflag is false. (That 

is, GETMOD should not be called during the subroutine initialization.) Calls to GETMOD 

when iflag is true can result in erroneous mode information. 

39

40 


Prerequisite 

None 


CALL GETSLV (value) 


value A character*7 variable containing the name of the solver; HARWELL for the 

Harwell solver or CALAHAN for the Calahan solver. 


command. 

GETSTM 

GETSTM returns the current simulation time. 

Use 

Called by 


Prerequisite 

None 


CALL GETSTM (VALUE) 


value A double-precision variable containing the current simulation time. 


command. 

GETVER 

GETVER returns the current Adams/Solver version number as it appears in the Adams/Solver banner.

Use 

Called by 


Prerequisite 

None 


CALL GETVER (value) 



value A character*10 variable that contains the Adams/Solver version number. 

GSE 

Starting with the 2005r2 release, Adams/Solver (C++), returns a “+” as 

the last character in value. Adams/Solver (FORTRAN) leaves this 

character blank. Among other uses, this permits the user-supplied 

subroutine to determine which version of the solver, C++ or FORTRAN, 

is being used with it. 

The following defines a set of utility subroutines which are to be used in the GSE_DERIV and 

GSE_OUTPUT user subroutines that are associated with the GSE element. 

These utilities supplement and enhance the SYSARY and SYSPAR utility subroutines that are used in 

Adams/Solver (FORTRAN) to access the input and state arrays of the GSE, and provide the derivatives 

of the GSE. 

If you are using Adams/Solver (C++), you should use the utility subroutines described here rather than 

SYSARY and SYSPAR because they are more efficient and they permit access to enhanced GSE 

capabilities (sparse GSE and implicit GSE). 

The utility subroutines can be grouped into the following categories: 

• Dimension query utilities (GSE_NS, GSE_ND, GSE_NI, GSO_NO) 

• Array query utilities (GSE_X, GSE_XDOT, GSE_U, GSE_XD) 

• Partial-derivative entry utilities (GSEPAR_X, GSEPAR_U, GSEPAR_XDOT) 

• Partial-derivative mapping utilities (GSEMAP_X, GSEMAP_U, GSEMAP_XDOT) 

Note that none of the utility subroutines require that the ID of the GSE be provided. Adams/Solver knows 

which GSE is being referred to. 

41

42 


Dimension Query Utilities: GSE_NS, GSE_ND, GSE_NI, GSE_NO 

The dimension query utility subroutines are called to obtain information about the dimension of the 

various arrays associated with the GSE. Access to this information allows proper dimensioning of arrays. 

The dimensions obtained from these utilities must be passed to other utility subroutines as verification 

that the subroutine developer is aware of the required array dimension. 

Each of the dimension query utility subroutines takes a single integer argument. After the call to the 

subroutine, the integer contains the associated dimension. 

Called By 

GSE_DERIV, GSE_OUTPUT 

Prerequisite 

None 


CALL GSE_NS(NS) 

CALL GSE_ND(ND) 

CALL GSE_NI(NI) 

CALL GSE_NO(NO) 

Arguments 

NS Output integer - the number of states 

ND Output integer - the number of discrete states 

NI Output integer - the number of inputs 

NO Output integer - the number of outputs 

Array query utility subroutines: GSE_X, GSE_XDOT, GSE_XD, GSE_U 

The array query utility subroutines are called to obtain information about the values of: 

• Continuous states, X 

• Time derivative of the continuous states, XDOT 

• Discrete states, XD 

• GSE inputs, U 

Called By 

GSE_DERIV and GSE_OUTPUT

Prerequisite 


Require input values, which must be obtained by a previous call to the dimension query utility 

subroutines. 


CALL GSE_X(X,NS) 

CALL GSE_XDOT(XDOT,ND) 

CALL GSE_XD(XD,ND) 

CALL GSE_U(U,NI) 


NS Integer - the number of continuous states (used for validation) 

ND Integer - the number of discrete states (used for validation) 

NI Integer - the number of outputs (used for validation) 


X Double-precision array of dimension NS, the continuous states 

XDOT Double-precision array of dimension NS, the time derivative of the 

continuous states (IMPLICIT GSE only) 

XD Double-precision array of dimension ND, the discrete states 

U Double-precision array of dimension NI, the inputs 

Caution: • If the incorrect validation integer value is provided, Adams/Solver (C++) will stop 

with an error message. 

Partial derivative entry utility subroutines: GSEPAR_X, GSEMAP_XDOT, GSEPAR_U 

The partial derivative entry utility subroutines are used to provide Adams/Solver with: 

• The partial derivative of the GSE_DERIV and GSE_OUTPUT with respect to the continuous 

states, X 

• The time derivative of the continuous states, XDOT (implicit GSE only) 

• The inputs, U 

• Calls to GSE_XDOT are only appropriate for GSE elements defined with the 

IMPLICIT attribute and should only be made from the GSE_DERIV user 

subroutine, not from GSE_OUTPUT. 

43

44 


A call to GSEPAR_X from GSE_DERIV is understood to provide the partial derivative of GSE_DERIV 

with respect to X, and so on. 

The GSEPAR utility subroutines are assumed to provide full partials unless one or more calls were made 

to the corresponding GSEMAP when the GSE_DERIV or the GSE_OUTPUT user subroutine was called 

with IFLAG set. When full partials are provided with the GSEPAR utility subroutines, the order of the 

entries should be such that all the partial derivatives with respect to the first state or input should be 

provided in order before the partial derivatives with respect to the second state or input. If sparse partial 

derivatives are used, the entries to GSEPAR should be in the same order as was defined by GSEMAP. 

Called By 

GSE_DERIV and GSE_OUTPUT 

Prerequisite 

Calls may be dependent on calls made to GSEMAP utility subroutines when IFLAG was set. 


CALL GSEPAR_X(D,N) 

CALL GSEPAR_XDOT(D,N) 

CALL GSEPAR_U(D,N) 


D Double-precision array of partial derivatives in the appropriate order 

N Integer - the number of partials being provided (used for validation) 

Caution: • If N does not validate, Adams/Solver (C++) stops with an error message. For full 

partials it is expected to be the product of the corresponding dimensions. For 

example, the call to GSEPAR_X from a GSE_OUTPUT should have N = NI * NS, 

where NI and NS are the return values of GSE_NI and GSI_NS respectively. For 

sparse partials, the value of N should equal the number of calls made to the 

corresponding GSEMAP utility subroutine. 

• Calls to GSEPAR_XDOT are only appropriate for GSE elements defined with the 

IMPLICIT attribute and should only be made from the GSE_DERIV user 

subroutine, not from GSE_OUTPUT. 

Partial derivative mapping utility subroutines: GSEMAP_X, GSE_XDOT, GSEMAP_U 

The partial derivative mapping utility subroutines may optionally be used to configure the GSE to have 

sparse entries. For a GSE with a large number of states, inputs and/or outputs, the computational savings 

can be significant.


GSEMAP_X, GSEMAP_XDOT, and GSEMAP_U register dependencies with respect to state, the time 

derivative of state (implicit GSE only) and input, respectively. 

If Adams/Solver (C++) detects calls to the GSEMAP utility subroutines during calls to GSE_DERIV or 

GSE_OUTPUT, when IFLAG is set, then the corresponding partial derivative is taken to be sparse. 

GSEMAP utility subroutine calls may be made for one or more of the families of partial derivaties. For 

example, if GSEMAP_X is called from GSE_DERIV, this particular partial derivative is taken to be 

sparse while the other families of partial derivatives, for example the partial derivative of GSE_DERIV 

with respect to U, is taken to be full. 

Multiple calls are made to GSEPAR utility subroutines, one per dependency. For example, a call 

GSEMAP_X(1,1) from GSE_OUTPUT indicates to Adams/Solver (C++) that the first output depends 

on the first state. The order of the calls to GSEMAP utility subroutines is significant because entries in 

the array subsequently passed to the corresponding GSEPAR utility subroutines is assumed to be in this 

order. 

Called By 

GSE_DERIV and GSE_OUTPUT 

Prerequisite 

None 


CALL GSEMAP_X(I,J) 

CALL GSEMAP_XDOT(I,J) 

CALL GSEMAP_U(I,J) 


I Integer - the row index (the index of the state derivative or the output which 

has a functional dependency) 

J Integer - the column index (the index of the state or the input with respect to 

which the functional dependency is being registered) 

Caution: Calls to GSEMAP_XDOT are only appropriate for GSE elements defined with the 

IMPLICIT attribute and should only be made from the GSE_DERIV user subroutine, not 

from GSE_OUTPUT. 

GSE_SET_IMPLICIT 

This subroutine is used to specify the implicit/explicit character of the equations governing the GSE. 

45

46 


See the definition of the IMPLICIT attribute in the documentation for the GSE statement. 

When the GSE is initialized Adams/Solver (C++) will look for a GSE_SET_IMPLICIT entry point in the 

GSE (if it was not explicitly specified using the ROUTINE=). If GSE_SET_IMPLICIT is present, then 

during initialization of the GSE this subroutine will be called. 

Note: The value returned by GSE_SET_IMPLICIT will override any IMPLICIT attribute setting 

that is specified in the GSE statement 

This user-defined subroutine is new for Adams/Solver (C++) v2006r1 and gives the GSE the ability to 

define the implicit/explicit character of its governing equations. That is, the formulation of a GSE can 

be changed without changing the corresponding adams model (.amd). 

Calling Sequence and Structure 

SUBROUTINE GSE_SET_IMPLICIT (ID, IMPLICIT) 


ID An integer variable that gives the identifier of the GSE statement requesting information 

from the GSE subroutine. From the identifier, Adams/Solver automatically recognizes other 

information (such as the Par argument) that is associated with that GSE statement. 


IMPLICIT An integer specifying whether the GSE formulation is implicit or explicit. A nonzero 

(true) value for IMPLICIT specifies an implicit formulation. 

Example 

C 

C+===============================================================* 

C 

SUBROUTINE GSE_SET_IMPLICIT (ID, IMPLICIT) 

C 

C Inputs: 

C 

INTEGER ID 

C 

C Outputs: 

C 

INTEGER IMPLICIT 

C 

C This GSE is formulated implicitly. 

IMPLICIT = 1 

RETURN 

END


C 

C+===============================================================* 

C 

GSE_SET_ND 

This subroutine is used to specify the number of discrete internal states the in the GSE. 

When the GSE is initialized Adams/Solver (C++) will look for a GSE_SET_ND entry point in the GSE 

(if it was not explicitly specified using the ROUTINE=). If GSE_SET_ND is found, then during 

initialization of the GSE this subroutine will be called. 

Note: The value, ND, returned by GSE_SET_ND will override any value of ND that is specified 

in the GSE statement 


define its own number of discrete states. That is, the number of discrete states in a GSE can be changed 

without changing the corresponding adams model (.amd). 


SUBROUTINE GSE_SET_ND (ID, ND) 


ID An integer variable that gives the identifier of the GSE statement requesting 

information from the GSE subroutine. From the identifier, Adams/Solver 

automatically recognizes other information (such as the Par argument) that is 

associated with that GSE statement. 


ND An integer number giving the number of discrete states that this GSE maintains. 

Example 

C 

C+=================================================================* 

C 

SUBROUTINE GSE_SET_ND (ID, ND) 

C 

C Inputs: 

C 

INTEGER ID 

C 

C Outputs: 

47

48 


C 

INTEGER ND 

C 

C This GSE has two discrete internal states. 

ND = 2 

RETURN 

END 

C 

C+=================================================================* 

C 

GSE_SET_NS 

This subroutine is used to specify the number of internal states the in the GSE. 

When the GSE is initialized Adams/Solver (C++) will look for a GSE_SET_NS entry point in the GSE 

(if it was not explicitly specified using the ROUTINE=). If GSE_SET_NS is found, then during 

initialization of the GSE this subroutine will be called. 

Note: The value, NS, returned by GSE_SET_NS will override any value of NS that is specified 

in the GSE statement. 


define its own number of states. That is, the number of states in a GSE can be changed without changing 

the corresponding adams model (.amd). 


SUBROUTINE GSE_SET_NS (ID, NS) 



from the GSE subroutine. From the identifier, Adams/Solver automatically recognizes 

other information (such as the Par argument) that is associated with that GSE statement. 


NS An integer number giving the number of states that this GSE maintains. 

Example 

C 

C+=================================================================* 

C 

SUBROUTINE GSE_SET_NS (ID, NS)

C 

C Inputs: 

C 

INTEGER ID 

C 

C Outputs: 

C 

INTEGER NS 

C 

C This GSE has two internal states. 

NS = 2 


RETURN 

END 

C 

C+=================================================================* 

C 

GSE_SET_SAMPLE_OFFSET 

This subroutine is used to specify the simulation time at which the sampling of the discrete states is to 

start. 

See the definition of the SAMPLE_OFFSET attribute in the documentation for the GSE statement. 

When the GSE is initialized Adams/Solver (C++) will look for a GSE_SET_SAMPLE_OFFSET entry 

point in the GSE (if it was not explicitly specified using the ROUTINE=). If 

GSE_SET_SAMPLE_OFFSET is present, then during initialization of the GSE this subroutine will be 

called. 

Note: The value returned by GSE_SET_SAMPLE_OFFSET will override any 

SAMPLE_OFFSET attribute setting that is specified in the GSE statement. 


set the SAMPLE_OFFSET attribute itself. That is, the formulation of a GSE can be changed without 

changing the corresponding Adams model (.amd). 


SUBROUTINE GSE_SET_SAMPLE_OFFSET (ID, SAMPLE_OFFSET) 

49

50 




from the GSE subroutine. 


SAMPLE_OFFSET A double-precision variable specifying time simulation time at which the 

sampling of the discrete states is to start. 

Example 

C 

C+=================================================================* 

C 

SUBROUTINE GSE_SET_SAMPLE_OFFSET (ID, SAMPLE_OFFSET) 

C 

C Inputs: 

C 

INTEGER ID 

C 

C Outputs: 

C 

DOUBLE_PRECISION STATIC_HOLD 

C 

C Discrete states are to be sampled at time at time = 1.23. 

C 

SAMPLE_OFFSET = 1.23 

RETURN 

END 

C 

C+=================================================================* 

C 

GSE_SET_STATIC_HOLD 

This subroutine is used to enforce the condition that continuous states are or are not allowed to change 

during a static or quasi-static simulation. 

See the definition of the STATIC_HOLD attribute in the documentation for the GSE statement. 

When the GSE is initialized Adams/Solver (C++) will look for a GSE_SET_STATIC_HOLD entry point 

in the GSE (if it was not explicitly specified using the ROUTINE=). If GSE_SET_STATIC_HOLD is 

present, then during initialization of the GSE this subroutine will be called. 

Note: The value returned by GSE_SET_STATIC_HOLD will override any STATIC_HOLD 

attribute setting that is specified in the GSE statement.



set the STATIC_HOLD attribute itself. That is, the formulation of a GSE can be changed without 

changing the corresponding Adams model (.amd). 


SUBROUTINE GSE_SET_STATIC_HOLD (ID, STATIC_HOLD) 



from the GSE subroutine. 


STATIC_HOLD An integer specifying whether the GSE formulation has the STATIC_HOLD 

attribute set. A nonzero (true) value for STATIC_HOLD specifies that that GSE has 

its STATIC_HOLD attribute set. 

Example 

C 

C+=================================================================* 

C 

SUBROUTINE GSE_SET_STATIC_HOLD (ID, STATIC_HOLD) 

C 

C Inputs: 

C 

INTEGER ID 

C 

C Outputs: 

C 

INTEGER STATIC_HOLD 

C 

C Continuous variables are held constant during static or 

C quasi-static simulations. 

C 

STATIC_HOLD = 1 

RETURN 

END 

C 

C+=================================================================* 

C 

GTARAY 

51

52 


GTARAY returns the double-precision numbers stored by an IC-type ARRAY statement (C++ or 

FORTRAN). 

Use 

Called By 


Prerequisite 

ARRAY statement in dataset 


CALL GTARAY (id, array, number, istat) 

Input Argument 

id An integer variable that specifies the ID of the ARRAY statement. 


array A double-precision array containing the data defined in the ARRAY 

statement statement. 

istat An integer that indicates the success or the reason for the failure of the 

call to GTARAY. 

number A variable that indicates the number of values returned in the array. 

GTCMAT 

If: Then: 

istat = 0 The call to GTARAY was successful. 

istat = -1 ARRAY/id is not an IC-type. 

istat = -2 Adams/Solver could not find an ARRAY statement 

with the identifier indicated in id. 

Caution: • Make sure that array is large enough to hold all of the returned values. 

• You can only use GTARAY to access values for an IC-type ARRAY (the default 

type). If you want to access values for an X-type, a Y-type, or a U-type ARRAY, 

use SYSARY and the ARRAY function, or SYSFNC and the C++ ARYVAL 

function or the FORTRAN ARYVAL function.


GTCMAT computes the compliance matrix for a set of markers in an Adams/Solver model. 

Use 

Called By 

CONSUB 

Prerequisite 

Call to ANALYS to perform a static analysis 


CALL GTCMAT (nmid, mid, ndim, c, istat) 

53

54 



nmid An integer variable that specifies the number of marker, mid. nmid must 

be greater than zero and less than or equal to 100. 

mid An integer array containing a list of marker identifiers. GTCMAT 

computes the compliance matrix for these markers. The markers can be on 

any part except ground, and can lie anywhere on the parts. mid can contain 

more than one marker on a particular part. Each part with a marker listed 

in mid must also have a center-of-mass (CM) marker defined in the 

dataset. 

ndim An integer variable specifying the number of rows in c. ndim must be at 

least 6*nmid, since each marker results in six rows. You must dimension c 

in CONSUB with exactly ndim rows (and at least 6*nmid columns).



c A double-precision, two-dimensional array containing the compliance 

matrix for the markers specified in mid. The compliance terms are in the 

following directions: global x, y, and z displacements and small rotations 

about the global x-, y-, and z-axes. 


You must dimension c large enough to hold six rows and six columns for 

each marker, and assign ndim to be the number of rows in the matrix. To 

compute a matrix for three markers, for example, you should dimension c 

to be 18 by 18, and set ndim =18. The same matrix could also be used to 

compute a matrix for just one marker. In this case, you would still set ndim 

to 18, but GTCMAT fills only the elements in the first six rows and 

columns. 

istat An integer variable containing a status flag. If istat = 0, GTCMAT has 

successfully computed the compliance matrix. If istat < 0, GTCMAT has 

not computed the compliance matrix because of an error. istat can have 

one of the following values: 

If: Then: 

istat= 0 Normal return 

istat= -1 nmid < 0 

istat= -2 nmid > maximum number of markers allowed (100) 

istat= -3 ndim < 6 * nmid 

istat= -6 mid contains an illegal marker 

istat= -7 the system has zero degrees-of-freedom 

istat= -8 A UCON in the system prevents compliances from 

being calculated. 

istat= -9 The system Jacobian is singular. 

istat= -10 Miscellaneous problems 

istat= -11 One of the markers specified is on ground. 

istat= -12 Static equilibrium has not been performed. 

istat= -13 One of the parts referenced has no cm marker. 

The compliance matrix for a system, C, is defined as the partial derivatives of displacements with respect 

to applied forces: 

55

56 


Note that the compliance matrix is the inverse of the stiffness matrix for a system (which is defined as 

the partial derivatives of the applied forces with respect to the displacements). If a system is assumed to 

be linear, the compliance matrix can be used to predict the system movement due to force inputs: Dx = 

C Df 

From this perspective, matrix element cij is the displacement of system degree of freedom i due to a unit 

force at degree-of-freedom j. 

In order for the system to have meaningful compliances, it must have one or more degrees of freedom. 

A kinematic (zero-degree-of-freedom) model does not move in response to applied forces, so by 

definition the compliances are zero. GTCMAT returns an error if run on a kinematic model. 

GTCMAT returns a matrix containing six columns and six rows for each marker requested. The rows and 

columns are in groups of six, appearing in the same order as the markers are listed in mid. The rows 

correspond to global x, y, and z translations and global AX, AY, AZ rotations. The columns correspond 

to global x, y, and z forces and torques about the global x, y, and z axes. 

If, for example, you specify two marker identifiers in mid, GTCMAT returns a 12 12 matrix. Element 

c(2,4) is the change in the global y displacement of the first marker due to a unit torque about the global 

x-axis applied at the first marker (assuming a linear system). Element c(2,8) is the change in the global 

y displacement of the first marker due to a global Y force applied at the second marker. 

Using Adams/Solver (FORTRAN) 

When using Adams/Solver (FORTRAN), GTCMAT computes the compliance matrix by inverting the 

Jacobian from an Adams/Solver static solution. Because of this, you must first call ANALYS to perform 

a static solution, before calling GTCMAT. GTCMAT returns an error if you have not first run a static 

analysis. 

Using Adams/Solver (C++) 

When using Adams/Solver (C++), GTCMAT computes the compliance matrix as follows: 

1. A linearization of the system is performed (the linearization does not change the current state of 

the system) and a standard input-output representation is obtained: 

= AX + BU 

y = X 

where the output y consists of the displacements of the MARKERs and the input U consists of 

applied forces at the MARKERs’ locations. For more information on the state vector X and the 

state matrices A,B, , see the LINEAR command. 

2. Solving for X we find that 

X = A-1-A-1BU 

Putting this result into the equation for y we obtain: 

y = [-A-1B]U + [-A-1] 

3. The compliance matrix C is given by the expression:

C = [-A-1B] 


Notice that the term [-A-1] is due to perturbations of the velocities and accelerations of the system 

at the operating point, therefore it can be neglected. 

The GTCMAT subroutine can be called during a dynamic or a quasi-static simulation. 

Caution: If you don't dimension matrix c properly or don't assign the proper value to ndim, 

GTCMAT can overwrite other memory. 

GTCURV 

GTCURV evaluates a B-spline or user-written curve created by a CURVE statement (C++ or 

FORTRAN). 

Use 

Called By 


Prerequisite 

CURVE statement in the dataset 


CALL GTCURV (id, alpha, iord, array, istat) 

57

58 



id An integer variable that specifies the ID of the corresponding CURVE 

statement. 

alpha A double-precision variable that identifies the value of the independent 

parameter, a, at which GTCURV is to evaluate the curve. If the curve is a Bspline 

computed by the CURVE statement, alpha must be in the domain -1 

alpha 1. If the curve is computed by CURSUB, alpha must be in the domain 

MINPAR alpha MAXPAR (these are specified in the CURVE statement). 

iord An integer variable that specifies the order of the derivative the GTCURV is 

to return. The legal values are: 

• 0 - Returns the curve coordinate. 

• 1 - Returns the first derivative with respect to a. 

• 2 - Returns the second derivative with respect to a.



array A double-precision array of length three which contains the returned 

values of x, y, z. 

0 

1 

2 

iord array(1) array(2) array(3) 

x( α ) y( α ) z( α ) 

dx( α ) 

------------dα 

d 2 x( α ) 

dα 2 

----------------- 

dy( α ) 

------------dα 

d 2 y( α ) 

dα 2 

----------------- 

dz( α ) 

------------dα 

d 2 z( α ) 

dα 2 

---------------- 

istat An integer variable that indicates either the success or teason for the failure 

of the call to GTCURV. 

If: Then: 

istat= -1 Fatal error, invalid id or iord is out of the range. 

istat= 0 The call to GTCURV was successful. 

istat= 1 alpha is less than MINPAR, the curve was evaluated at 

MINPAR. 

istat= 2 alpha is greater than MAXPAR, the curve was 

evaluated at MAXPAR. 

59

60 


array A double-precision array of length three which contains the returned 

values of x, y, z. 

istat An integer variable that indicates either the success or teason for the 

failure of the call to GTCURV. 


GTCURV evaluates a B-spline or a user-written curve defined by a CURVE statements and returns one 

of the following: 

• A value for the dependent variables (x, y, z) for each value it receives for alpha. 

• The first partial derivatives of the dependent variable. 

• The second partial derivatives of the dependent variable. 

GTSTRG 

GTSTRG returns the character string stored in a STRING statement. 

Use 

Called By 


0 

1 

2 

iord array(1) array(1) array(1) 

x( α ) y( α ) z( α ) 

dx( α ) 

------------dα 

dx 2 ( α ) 

dα 2 

----------------- 

dy( α ) 

------------dα 

dy 2 ( α ) 

dα 2 

----------------- 

dxz( α ) 

---------------dα 

dz 2 ( α ) 

dα 2 

---------------- 

If: Then: 

istat= -1 Fatal error, invalid id or iord is out of the range. 

istat= 0 The call to GTCURV was successful. 

istat= 1 alpha is less than MINPAR, the curve was evaluated at 

MINPAR. 

istat= 2 alpha is greater than MAXPAR, the curve was evaluated 

at MAXPAR.

Prerequisite 

STRING statement in dataset 


CALL GTSTRG (id, string, nchars, istat) 



id An integer variable that specifies the ID of the STRING statement. 


istat An integer that indicates the success or failure of the call to GTSTRG. 

nchars The number of characters in the returned string. Trailing blank spaces are 

ignored. 

string The requested string. 

GTUNTS 

GTUNTS returns model unit information from Adams/Solver. 

Use 

Called By 


Prerequisite 

None 

If: Then: 

istat= 0 The call to GTSTRG was successful. 

istat= -2 Adams/Solver could not find a STRING statement with the 

identifier indicated in id. 

Caution: • Make sure that string is long enough to hold all of the string. 

• The string is left-justified (that is, Adams/Solver deletes all blank spaces to the left 

of the string). 

61

62 



CALL GTUNTS (exist, scales, units) 


exist A logical variable that, if true, indicates units were set for the model. 

scales A double-precision array containing conversion factors to go from model 

units to SI for time, length, force, and mass. 

units A character*2 array containing two-letter abbreviations for the model units 

for time, length, force, and mass. 

Example For example, if you have an Aero_Force defined in Newtons, and you want to convert to model 

units, you must divide your force by scales(3). 

DOUBLE PRECISION SCALES(4) 

LOGICAL EXIST 

CHARACTER*2 UNITS(4) 

INTEGER TIME, LENGTH, FORCE, MASS PARAMETER 

(TIME=1,LENGTH=2,FORCE=3, MASS=4) 

CALL GTUNTS(EXIST, SCALES, UNITS) 

Model_Force = Aero_Force/SCALES(FORCE) 

To compute a spring in MKS units, give disp, flen, and K in model units: 

MKS_F = ((flen - disp)*K)*SCALES(FORCE) VSIN 

Caution: GTUNTS uses the UNITS statement in your dataset to determine the units being used in 

your model. When a UNITS statement is missing, or if you use a unit consistency factor 

(UCF), GTUNTS is not able to determine time, length, mass, or force units. In that case, 

GTUNTS returns: 

The HAVSIN general subroutine evaluates a haversine function. 

Use 

Called By 

• exist = FALSE 


• scales = 1.0, 1.0, 1.0, 1.0 

• units = US

Prerequisites 

None 


CALL HAVSIN (x, x0, h0, x1, h1, iord, value, errflg) 


63

64 



h0 A double-precision variable that specifies the value of the function before 

the step (x £ x0). 

h1 A double-precision variable that specifies the value of the function after the 

step (x x1). 

iord An integer variable that defines the order of the derivative that HAVSIN is 

to return. The order is usually zero, but it can be one or two. 


x0 A double-precision variable that specifies the x value at which the haversine 

function begins. 

x1 A double-precision variable that specifies the value at which the haversine 

function ends. 


errflg A logical (true or false) variable that HAVSIN returns to the calling 

subroutine. If HAVSIN detects an error in the subroutine call 

statement, it sets errflg to true before it returns errflg to the calling 

subroutine. 

value A double-precision value the subroutine returns. If iord equals zero, 

value is the function evaluated at x. If iord equals one, value is the first 

derivative of F(x) with respect to the independent variable x. If iord 

equals two, value is the second derivative of F(x) with respect to the 

independent variable x. Value is: 


0 

1 

2 

IORD: Value: 

F( x) 

∂ F( x) 

-------------- 

∂ x 

∂ F 2 ( x) 

∂ x 2 

---------------- 

The HAVSIN general subroutine evaluates a haversine function. Figure 1 below illustrates the haversine

function. 


The value x is the independent variable, h0 and h1 are the initial and final values of the haversine 

function. The following equation defines HAVSIN: 

65

66 


a 

b 

c 

IMPACT 

IMPACT is a simple model for contacts. It evaluates a force that turns on when a distance falls below a 

nominal free length (that is, when two parts collide). 

Use 

( h0 + h1) = --------------------- 

2 

Called By 


Prerequisite 

None 

( h1 – h0) = --------------------- 

2 

( x – x0) = --------------------- 

( x1 – x0) HAVSIN 

h0 ; x ≤x0 

a b c π π 

⎧ ⎫ 

⎪ ⎪ 

⎪ ⎛ ⋅ – --⎞ 

⎪ 

= ⎨ + ⋅sin 

; x 

⎝ 2⎠ 

0 < x < x2⎬ ⎪ ⎪ 

⎪ 

⎩ 

h2 ; x ≥ x 

⎪ 

1 ⎭ 

Caution: • The value x1 must not equal x0. Equal values of x1 and x0 imply a sharp step, 

which HAVSIN cannot fit. 

• At x0 and x1, the second derivatives of the haversine function do not match the 

second derivatives of the constant regions. This discontinuity increases as the 

values for x1 and x0 become closer (that is, as the haversine becomes sharper). 

Because of the discontinuity, integration problems can arise if the haversine is 

sharp. 

• The STEP general subroutine (see STEP) is an alternative to HAVSIN.


CALL IMPACT (x, x', x1, k, e, cmax, d, iord, vector, errflg) 


67

68 



x A double-precision variable that specifies the distance variable you want to 

use to compute the force. 

x' A double-precision variable that communicates to IMPACT the time 

derivative of x. 

x1 A double-precision variable that specifies the free length of x. If x is less 

than x1, Adams/Solver calculates a positive value for the force. Otherwise, 

the force value is zero. The value of x1 must be greater than zero. 

k A positive, double-precision variable that specifies the stiffness of boundary 

surface interaction. 

e A positive, double-precision variable that specifies the exponent of the 

force-deformation law. For a stiffening spring characteristic, e > 1.0. For a 

softening spring characteristic, 0 < e < 1.0. 

cmax A non-negative, double-precision variable that specifies the maximum 

damping coefficient. 

d A positive, double-precision variable that specifies the boundary penetration 

at which Adams/Solver applies full damping. For a plot of damping 

coefficient versus penetration, see IMPACT function (C++ or FORTRAN). 

iord An integer variable that defines the order of the derivative IMPACT is to 

return. The order is usually zero, but it can be one or two.




errflg A logical (true or false) variable that IMPACT returns to the calling 

subroutine. If IMPACT detects an error during its calculations, it sets errflg 

to true. 

vector A double-precision vector of length 3, that returns the values calculated by 

the subroutine. The following table indicates the information in vector. 

IMPACT models collisions and contact. It evaluates a force that turns on when a distance falls below a 

nominal free length (that is, when two parts collide). 

The force has two components: a spring or stiffness component and a damping or viscous component. 

The stiffness component opposes the penetration. The damping component of the force is a function of 

the speed of penetration. The damping opposes the direction of relative motion. To prevent a 

discontinuity in the damping force at contact, the damping coefficient is, by definition, a cubic step 

function of the penetration. Thus at zero penetration, the damping coefficient is always zero. The 

damping coefficient achieves a maximum, cmax, at a user-defined penetration, d. 

An object colliding with ground is an example of a system that can be modeled with the IMPACT 

function. 

Let x be the instantaneous distance, x1 be the free length (when x is less than x1, the force turns on), x1 

- x be the penetration, and d be the penetration at which Adams/Solver applies full damping (cmax). 

• When x x1, force = 0. 

(1) 

• When x < x1, force is positive. 

vector 

returns: For iord values: 

(2) 0 

• When (x1-d) < x < x1, force is positive; there is damping, but it is less than cmax. 

• When x (x1-d), force is positive and damping = cmax. 

0 1 2 

F( x, x′ ) 

∂ F( x, x′ ) 

--------------------- 

∂ x 

∂ F( x, x′ ) 

--------------------- 

∂ x′ 

(3) 0 0 0 

∂ 2 F( x, x′ ) 

∂ x 2 

------------------------ 

∂ 2 F( x, x′ ) 

------------------------ 

∂ x′∂ x 

69

70 


The following equation defines IMPACT: 

IMPACT 

See an explanation of the STEP function (C++ or FORTRAN). 

Adams/Solver never returns a negative force for IMPACT. If the above expression evaluates to negative 

value, Adams/Solver returns a zero value. 

For an example of an SFOSUB that calls IMPACT, see SFOSUB. 

ISTRNG 

ISTRNG converts a number from integer format to character format. The character string representing 

the integer is always left justified. 

Use 

Called By 


Prerequisite 

None 


Max 0 k( x1x) e 

( , ) STEP x x1 ( d, cmax, x1, 0) 

x · 

⎧ ⎫ 

⎪ – ( , – ( ⋅ ) ) ; x < x ⎪ 

= 

1 

⎨ ⎬ 

⎪ 0 ; x ≥ x ⎪ 1 

⎩ ⎭ 

Caution: • IMPACT is only used to determine force or torque magnitudes. 

• The force value and the distance measure must both be positive in the same 

direction. 

• When e is less than or equal to one, the rate of change of the force is discontinuous 

at contact. This may cause convergence problems. 

CALL ISTRNG (number, string, length, istat)



number An integer variable that specifies the integer to be converted. 


istat An integer variable indicating the success or the reason for the failure of the 

call to ISTRNG. 


One purpose of ISTRNG is to provide the CONSUB driver subroutine with a character representation of 

an integer. This is necessary because the MODIFY execution control subroutine requires commands in 

the form of a character string that may include integers (for example, statement identifiers). The integer 

and the character string representing the integer appear identical when printed. 

MODIFY 

The MODIFY allows execution of any Adams/Solver command except CONTROL, STOP, from a 

CONSUB. 

Use 

Called By 

CONSUB 

Prerequisite 

None 

If: Then: 

istat= 0 The call to ISTRNG was successful. 

istat= -3 There was an error during conversion. 

istat= -4 The string was not dimensioned long enough. 

length An integer variable that returns the number of nonblank characters in the 

converted string. 

string A character string that represents the number. Adams/Solver left justifies 

the converted string (that is, it removes all leading blank spaces). 

Tip: If the dimension of the string is CHARACTER*12 or longer, the string can hold any 

integer defined on a 32-bit machine. 

71

72 



CALL MODIFY (comand, istat) 


comand A character string or variable that corresponds to the command 

to be executed. 


istat An integer variable that indicates whether or not the call to MODIFY was 

successful. 


You must build a character string for the input and pass the string to MODIFY as if it were an actual 

interactive command. The general subroutines RSTRNG and ISTRNG are available to help build these 

strings. CONSUB can call MODIFY. Program control returns to CONSUB after execution of the 

command(s) issued from MODIFY. For an example of a CONSUB driver subroutine that calls MODIFY, 

see CONSUB. 

MODINF 

MODINF returns the original mode numbers and the modal frequencies, in cycles per user-defined time, 

of all active modes associated with a FLEX_BODY statement (C++ or FORTRAN). 

Use 

Called By 


Prerequisite 

FLEX_BODY statement in dataset 


CALL MODINF (id, mode, freq, errflg) 

If istat = 0, the call to MODIFY was successful. 

Caution: Adams/Solver ignores any part of an argument following five blank spaces. Therefore, 

when using string concatenation to build a command, it is important to remove trailing 

blanks. Do this by referring only to the nonblank portion of the string.



id An integer variable that specifies the ID of the FLEX_BODY statement. 


mode An integer array that contains the original mode numbers of all the active 

modes associated with the specified FLEX_BODY. 

freq A double-precision array that contains the modal frequencies, in cycles per 

user-defined time, of all active modes associated with the specified 

FLEX_BODY. 

errflg A logical variable that returns true if an error has occurred during the call to 

MODINF. 

Caution: You must be sure mode and freq are dimensioned large enough to contain all the values 

returned by MODINF. You can check the number of active modes using NMODES. 

Example 

For examples of how MODINF is used, see the following files: 

For Windows, in the directory /install_dir/solver/samples, where install_dir is the directory in which you 

installed your Adams software. 

For UNIX, in the directory /install_dir/solver/samples, where install_dir is the directory in which you 


• sysary_sample.acf 

• sysary_sample.adm 

• sysary_sample.f 

• sysary_sample.mtx 

NMODES 

NMODES returns the number of modal generalized coordinates associated with a FLEX_BODY 

statement (C++ or FORTRAN). 

Use 

Called By 

When errflg is true, the values of mode and freq may be wrong. 


73

74 


Prerequisite 

FLEX_BODY statement in dataset 


CALL NMODES (id, nq, errflg) 


id An integer variable containing the identifier of the FLEX_BODY 

statement for which the number of modal generalized coordinates should 

be retrieved. 


nq An integer that indicates the number of modal generalized coordinates 

associated with the specified FLEX_BODY. 

errflg A logical variable that returns true if an error has occurred during the call 

to NMODES. 

Caution: • The value of nq will be zero and errflg will return true if there is no active 

FLEX_BODY corresponding to id. 

Example 

For samples of how NMODES is used, see the following files: 

For Windows, in the directory /install_dir/solver/samples, where install_dir is the directory in which you 


For UNIX, in the directory /install_dir/solver/samples, where install_dir is the directory in which you 


POLY 

• sysary_sample.acf 

• sysary_sample.adm 

• sysary_sample.f 

• sysary_sample.mtx 

• The value of nq may be wrong when is true. 

The POLY general subroutine evaluates a polynomial.

Use 

Called By 


Prerequisite 

None 


CALL POLY (x, x0, par, npar, iord, value, errflg) 


75

76 



iord An integer variable that defines the order of the derivative that POLY is 

to return. The order is usually zero, but it can be one or two. 

npar An integer variable that indicates the number of coefficients specified. 

The primary purpose of npar is to provide POLY with the number of 

values stored in the par array. 

par A double-precision array of any number of coefficients (a0,...,an). 


x0 A double-precision variable that specifies a shift in the polynomial. 


errflg A logical (true or false) variable that POLY returns to the calling 

subroutine. If POLY detects an error in the subroutine call statement, it 


value A double-precision value the subroutine returns. If iord equals zero, value 

is the function evaluated at x. If iord equals one, value is the first 

derivative of F(x) with respect to the independent variable x. If iord 

equals two, value is the second derivative of F(x) with respect to the 

independent variable x. Value is: 


A POLY general subroutine evaluates a polynomial. The following equation defines POLY: 

a 

∑ 

j = 0 

PUT_SPLINE 

aj( x – x0) j 

0 

1 

2 

IORD: Value: 

F( x) 

∂ F( x) 

-------------- 

∂ x 

∂ F 2 ( x) 

∂ x 2 

---------------- 

PUT_SPLINE is used in conjunction with SPLINE_READ. SPLINE_READ reads in the data points for 

a spline from a file. PUT_SPLINE is used to store this data within Adams/Solver.

Use 

Called By 

SPLINE_READ 


CALL PUT_SPLINE (id, nx, nz, x, y, z, errflg) 



id An integer variable containing the ID of the SPLINE statement. 

nx An integer variable that specifies the number of x values contained in the 

x array. The number of x values must be at least 4. 

nz An integer variable that specifies the number of z values contained in the 

z array. The number of z values must be at least 1. 

x A double-precision array containing the x values for the spline element. 

The number of x values must be at least nx. 

y A double-precision array containing the y values for the spline element. 

The number of y values must be at least nx · nz. 

z A double-precision array containing the z values for the spline element. 

The number of z values must be at least nz. 


errflg A logical variable that indicates if Adams successfully accepts the x, y, 

[and z] data. SPLINE_READ checks the value of errflg after calling 

PUT_SPLINE. 


PUT_SPLINE transfers spline data to Adams/Solver from local variables that you define in the 

SPLINE_READ user-written subroutine. For an example of a SPLINE_READ subroutine that calls 

PUT_SPLINE, see SPLINE_READ. 

Cautions 

• If there are more than nx values in x, more than nx · nz values in y, or more than nz values in z, 

then Adams/Solver ignores the extra values. 

77

78 


• The z array is not used when nz = 1. The value of z is irrelevant in this case; however, z must 

exist. 

IORD: Value: 

0 Value of the function. 

1 Partial derivative of the function with respect to x. 

2 Second partial derivative of the function with respect to x. 

• The order of values that are stored in the y array must correspond to the order of points in the x 

and z arrays as follows: 

• The y array must consist of nz consecutive sets of nx values (the values within each set 

correspond to the values in the x array, and the sets correspond to the values in the z array). It is 

possible to use either a single- or double-dimensioned array for y. 

• If a double-dimensioned array is used, the first dimension must be equal to nx, not greater, and 

the second dimension must be greater or equal to nz. 

RCNVRT 

RCNVRT converts rotational coordinates from one representation to another. 

Use 

Called By 


Prerequisite 

None 


CALL RCNVRT (sys1, coord1, sys2, coord2, istat)



79

80 


sys1 A character string specifying the system in which the values passed in 

coord1 were determined. The following table shows the possible character 

strings and their meanings: 

Character 

string: Means: 

'EULER' Adams/Solver Euler angles 

'EULPAR' Euler parameters PO, P1, P2, P3 

'AXAYAZ' Rotational displacements about the x, y, and z axes 

'YPR' Yaw-pitch-roll 

'COSINES' Directional cosines 

'BRYANT' Bryant angles 

'B123' Body-three: 1-2-3 (orientation angles) 

`B231' Body-three: 2-3-1 





`B121' Body-two: 1-2-1 

`B131' Body-two: 1-3-1 

`B212' Body-two: 2-1-2 

`B232' Body-two: 2-3-2 

`B313' Body-two: 3-1-3 (Adams/Solver Euler angles) 

`B323' Body-two: 3-2-3 

`S123' Space-three: 1-2-3 






`S121' Space-two: 1-2-1 

`S131' Space-two: 1-3-1 

`S212' Space-two: 2-1-2

`S232' Space-two: 2-3-2 

`S313' Space-two: 3-1-3 

`S323' Space-two: 3-2-3 

`RODPAR' Rodrigues parameters 


sys2 A character string specifying the system in which the values returned as 

output in coord2 are to be determined. Possible character strings are the 

same as those for sys1. 

coord1 A double-precision array containing the coordinates to be converted. 

Angles should be input in radians. 

81

82 



coord2 An array containing the converted coordinates. Angles are output in radians. 

istat An integer variable indicating the unqualified success, the qualified success, 

or the reason for the failure of the call to RCNVRT. The values for istat are 

as follows: 


If: Then: 

istat= 0 The call to RCNVRT was successful without 

qualifications. 

istat> 0 The call to RCNVRT was successful, but there are 

nonfatal errors in the input supplied. 

istat= +1 The sum of the squares of the Euler parameters is 

close to (within 0.5), but not exactly, 1.0. 

istat= +2 The sum of the squares of a column of the direction 

cosines is close to (within 0.5), but not exactly, 1.0. 

istat< 0 The call to RCNVRT was not successful because 

there are fatal errors in the input supplied. 

istat= -1 The coordinate system for sys1 was not correctly 

specified. 

istat= -2 The coordinate system for sys2 was not correctly 

specified. 

istat= -3 The absolute value of an Euler parameter is greater 

than 1.5 (Adams/Solver gives 0.5 tolerance). 

istat= -4 The sum of the squares of the Euler parameters is not 

within 0.5 of 1.0. 

istat= -5 The sum of the squares of a column of the direction 

cosines is not within 0.5 of 1.0. 

istat= -6 The input direction cosine matrix is not orthogonal; 

that is, the dot product of any two columns is greater 

than 0.5. 

istat= -7 The input direction cosine matrix is for left-handed, 

In Adams/Solver, rotational coordinates are often used to specify the orientation of a coordinate system. 

For example, a DIFSUB, a REQSUB, or an SFOSUB can call RCNVRT to change Euler angles to Euler 

parameters. 

Euler parameters are P0, P1, P2, and P3. P0 is the cosine of one-half the angle of rotation of the rotated 

frame with respect to the reference frame. P1, P2, and P3 are the x, y, and z components, respectively, of 

the unit vector around which the rotation occurs, multiplied by the sine of one-half the angle.


Rodrigues parameters (R1, R2, and R3) define the relative rotation between two frames of reference. The 

relationship between Rodrigues parameters and Euler parameters is R1 = P1/P0, R2 = P2/P0, and 

R3 = P3/P0. Rodrigues parameters become undefined when P0 = 0, that is, when the angle of rotation 

about the vector is 180 degrees. If the dimension of the string is CHARACTER*12 or longer, the string 

can hold any integer defined on a 32-bit machine. 

The coord1 and coord2 array length is three, except when the coordinates are in the EULPAR system 

(when the array length is four) or in the COSINES system (when the array length is nine). The nine 

values of the COSINES system, which forms a three-by-three matrix, are stored in column order in 

coord2. 

RSTRNG 

RSTRNG converts a double-precision variable to a character string. 

Use 

Called By 


Prerequisite 

None 


CALL RSTRNG (reel, string, length, istat) 

83

84 



reel The double-precision number to be converted. 


istat An integer variable indicating the success or the reason for the failure of 

the call to RSTRNG. 

length An integer variable that returns the number of nonblank characters in the 

converted string. 

string A character string that represents the number. Adams/Solver left justifies 

the converted string (that is, removes all leading blank spaces) and retains 

all other blank spaces. 


RSTRNG converts a double-precision number to the characters representing that number. One purpose 

of RSTRNG is to provide the CONSUB driver subroutine with a character representation of a real 

number. This is necessary because the MODIFY execution control subroutine requires commands in the 

form of a character string that can include real numbers (for example, data). The double-precision 

variable and the character string representing the number appear identical when printed. 

SHF 

SHF evaluates a simple harmonic function. 

Use 

Called By 


Prerequisite 

None 

If: Then: 

istat= 0 The call to RSTRNG was successful. 

istat= -3 There was an error during conversion. 

istat= -4 String was not dimensioned long enough. 

Tip: If the dimension of the string is CHARACTER*12 or longer, the string can hold any real 

number.

Callng Sequence 

CALL SHF (x, x0, a, w, phi, b, iord, value, errflg) 




The following equation defines SHF: 

STEP 

STEP approximates a step function with a cubic polynomial. 

Use 

Called By 




x0 A double-precision variable that specifies a shift in the independent variable. 

a A double-precision variable that specifies the amplitude of the harmonic 

function. 

w A double-precision variable that specifies the frequency of the sine function. 

The variable must be in radians per unit of the independent variable. 

phi A double-precision variable that specifies a phase shift in the sine function. 

The variable phi must be in radians. 

b A double-precision variable that specifies the average value of displacement. 

iord An integer variable that defines the order of the derivative that SHF is to 

return. The order is usually zero, but it can be one or two. 

errflg A logical (true or false) variable that SHF returns to the calling subroutine. 

If SHF detects an error in the subroutine call statement, it sets errflg to true 

before it returns errflg to the calling subroutine. 

value A double-precision value the subroutine returns. The value returned 

depends on IORD as follows 

a ⋅sin 

( w ⋅( 

x – x0) – φ ) + b 

85

86 


Prerequisite 

None 


CALL STEP (x, x0, h0, x1, h1, iord, value, errflg)




x0 A double-precision variable that specifies the x value at which the step 


h0 A double-precision variable that specifies the value of the function before 

the step. 




step. 

iord An integer variable that defines the order of the derivative that STEP is to 



errflg A logical (true or false) variable that STEP returns to the calling 

subroutine. If STEP detects an error in the subroutine call statement, it sets 



depends on IORD as follows: 


Figure 1 below demonstrates the step function. For a comparison of STEP and STEP5, and the first 

derivatives of STEP and STEP5, see: 

• STEP (C++ or FORTRAN) function 

• STEP5 (C++ or FORTRAN) function 

IORD: Value: 


1 Partial derivative of the function with respect 

to x. 

2 Second partial derivative of the function with 

respect to x. 

F( x) 

∂ F 

----- 

∂ x 

∂ 2 F 

∂ x 2 

-------- 

87

88 


Figure 1. Step Function 

The value x is the independent variable, x0 and x1 define the variable values at which the step begins and 

ends, h0 and h1 are the initial value and the final value of the step. The equation that defines STEP 

follows. 

STEP 

For an example of a SENSUB evaluation subroutine that calls STEP, see SENSUB. 

STEP5 

STEP5 approximates a step function with a quintic polynomial. 

Use 

Called By 


Prerequisite 

None 

⎧ h0 ; x ≤x 

⎫ 

0 

⎪ ⎪ 

⎪ ( x – x0) ( x – x0) ⎪ 

= ⎨ h0 + ( h1 – h0) ⋅ --------------------- ⋅2 ⋅ 3 – ⎛2 ⋅ --------------------- ⎞ ; x 

( x1 – x0) ⎝ ( x1 – x0) ⎠ 0 < x < x1⎬ ⎪ ⎪ 

⎪ ⎪ 

⎩ h1 ; x ≥ x1 ⎭ 

Caution: The value x1 must not equal x0. Equal values of x1 and x0 imply a discontinuous step, 

which STEP cannot fit.


CALL STEP5 (x, x0, h0, x1, h1, iord, value, errflg) 






h0 A double-precision variable that specifies the value of the function before the 

step. 




step. 

iord An integer variable that defines the order of the derivative that STEP5 is to 



errflg A logical (true or false) variable that STEP5 returns to the calling 

subroutine. If STEP5 detects an error in the subroutine call statement, it sets 



depends on IORD as follows: 

Extended Definition Figure 1 below demonstrates the STEP5 function. For a comparison of STEP and 

STEP5, and the first derivatives of STEP and STEP5, see: 

• STEP (C++ or FORTRAN) function 

• STEP5 (C++ or FORTRAN) function 

IORD: Value: 


1 Partial derivative of the function with respect 

to x. 

2 Second partial derivative of the function with 

respect to x. 

F( x) 

∂ F 

----- 

∂ x 

∂ 2 F 

∂ x 2 

-------- 

89

90 


Figure 1. STEP5 Function 

The value x is the independent variable, x0 and x1 define the variable values at which the step begins and 

ends, h0 and h1 are the initial and values of the step. The equation defining the STEP5 function is: 

a = h1 – h0 

∆ 

( x – x0) = --------------------- 

( x1 – x0) STEP5 

h0 ; x ≤x0 

h0 a ∆ 3 

10 – 15∆ 6∆ 2 

⎧ ⎫ 

⎪ ⎪ 

⎪ ⎪ 

= ⎨ + ( ⋅[ 

+ ] ) ; x0 < x < x ⎬ 

1 

⎪ ⎪ 

⎪ h1 ; x ≥ x1 ⎪ 

⎩ ⎭ 

The STEP5 subroutine calling sequence is identical to the STEP subroutine. For an example of a 

SENSUB evaluation subroutine that calls STEP5, see SENSUB. 

Caution: The value x1 must not equal x0. Equal values of x1 and x0 imply a discontinuous step, 

which STEP5 cannot fit. 

SUBTRACT_MASS_PROPERTY


The SUBTRACT_MASS_PROPERTY utility subroutine accepts the mass properties for two parts or 

sets of parts and returns the mass properties of the second set minus the mass properties of the first. 

Use 

Called By 


Prerequisite 

None 


CALL SUBTRACT_MASS_PROPERTY (cm1, mass1, ip1, cm2, mass2, ip2) 

91

92 



cm1 A double-precision array of length 3 containing the center of mass of the first part or set 

of parts expressed in the GCS (Ground/Global Coordinate System). 

mass1 A double-precision variable containing the mass of the first part or set of parts. 


for the first part or set of parts. (Ixx, Iyy, Izz, Ixy, Ixz, Iyz) These inertia terms much be 

computed about the center of mass of the part and oriented in GCS. 

cm2 A double-precision array of length 3 containing the center of mass of the second part or 

set of parts expressed in the GCS. 

mass2 A double-precision variable containing the mass of the second set. 


for the second part or set of parts. (Ixx, Iyy, Izz, Ixy, Ixz, Iyz) These inertia terms much 

be computed about the center of mass of the part and oriented in GCS. 


cm2 A double-precision array of length 3 containing the center of mass of the second system 

minus the first expressed in GCS. 

mass2 A double-precision variable containing the mass of the second system minus the first. 

Ip2 A double-precision array of length 6 containing the 6 independent components of in the 

inertia tensor for the second system minus the first. (Ixx, Iyy, Izz, Ixy, Ixz, Iyz) These 

inertia terms are expressed about the combined center of mass and are oriented in GCS. 


Although not required, the SUBTRACT_MASS_PROPERTY utility subroutine is intended to be used 

with the BODY_MASS_PROPERTY utility subroutine. 

If, for example, the aggregate mass properties of all of the elements of a large model were required, with 

the exception of just a few parts, the BODY_MASS_PROPERTY ("Model", … ) utility subroutine could 

be used to find the aggregate mass of the entire model and then BODY_MASS_PROPERTY and 

SUBTRACT_MASS_PROPERTY could be used to remove the contributions from the unwanted parts 

from the aggregate set. 

Specifically, if the mass properties of both the sprung and the unsprung mass of a vehicle were required, 

the properties of the unsprung mass (assuming there are fewer unsprung parts than sprung parts) could 

be computed as described in the ADD_MASS_PROPERTY documentation, the mass properties of the 

entire system could be computed with a single call to BODY_MASS_PROPERTY using the 'Model' part 

specifier, and the sprung mass could then be obtained with a single call to 

SUBTRACT_MASS_PROPERTY where the unsprung mass properties would be subtracted from the 

model mass properties.


The SUBTRACT_MASS_PROPERTY utility subroutine simply calls the ADD_MASS_PROPERTY 

utility subroutine with the negative of the mass and inertia values. 

The SUBTRACT_MASS_PROPERTY utility subroutine is very similar to ADD_MASS_PROPERTY 

utility subroutine and the documentation for ADD_MASS_PROPERTY should be referenced for 

examples. 

SYSARY 

The SYSARY data access subroutine provides system state values, such as displacement and velocity, to 

your subroutines, and defines and stores the Adams/Solver state variables on which the system states are 

dependent. 

Use 

Called By 

CONSUB, DIFSUB, GFOSUB, REQSUB, SENSUB, SFOSUB, VARSUB, VFOSUB, and VTOSUB 


CALL SYSARY (fncnam, ipar, nsize, states, nstates, errflg) 

93

94 



fncnam A character variable that specifies the name of the function whose data is 

being requested from SYSARY. The legal values for fncnam are derived 

from the list of functions available to you in the FUNCTION= expression 

construct. Any one of the following character strings is legal. 

Displacement Functions: 

DISP Returns all six components of displacement. 

TDISP Returns three translational components of displacement. 

RDISP Returns three B313 Euler rotations 

(Adams/Solver standard rotations). 

Q Returns the modal generalized coordinates for 

the flex body specified. 

UVX Returns the direction cosines of the x-axis of 

marker I in the coordinate system of marker J. 

UVY Returns the direction cosines of the y-axis of 


UVZ Returns the direction cosines of the z-axis of 


DC Returns the direction cosines of the x-, y-, and 

z-axes of marker I in the coordinate system of 

marker J.


95

96 


Velocity Functions: 

VEL Returns all six components of velocity. 

TVEL Returns three components of translational velocity. 

RVEL Returns three components of angular velocity. 

QDOT Returns the first time derivative of the modal generalized 

coordinates for the flex body specified. 

Acceleration Functions: 

ACC Returns all six components of acceleration. 

TACC Returns three components of translational acceleration. 

RACC Returns three components of angular 

acceleration. 

QDDOT Returns the second time derivative of the 

modal generalized coordinates for the flex body 

specified. 

Generic Force Functions: 

FORCE Returns all six components of net force (forces 

and torques) acting at a marker. 

TFORCE Returns three components of net translational 

force acting at a marker. 

RFORCE Returns three components of net rotational 

force torque) acting at a marker. 

System element variables: 

PINPUT Returns instantaneous values of all components 

of a PINPUT. 

POUTPUT Returns instantaneous values of all components 

of a POUTPUT. 

ARRAY Returns instantaneous values of all components 

of an ARRAY. 

ipar An integer array of size nsize that contains the parameter list for function 

fncnam. The table above defines the appropriate parameter list types and 

dimensions for the different functions available.


nsize An integer variable that gives the number of parameters that the function 

fncnam requires. Its value is dependent on the function name. See the table 

above for the number of parameters that function fncnam requires. 


errflg A logical variable that returns as true if an error occurred during your call 

to SYSARY. 

nstates An integer variable that returns the number of values Adams/Solver has 

put in states. Note that an integer variable must be used here for 

Adams/Solver to return the number of states. The value returned in this 

variable is as defined in the table above. 

states A double-precision array whose size depends on the fncnam (see the table 

above) that contains the values that SYSARY returns. When the iflag 

argument in the user subroutine is true or when input errors are found, 

states contains zeros. 


SYSARY returns a set of system states or stores the dependencies of the user value on the set of system 

states. You can use the system state values to compute the instantaneous values of a user-defined 

function; Adams/Solver uses the dependency on state variables to create the matrix of partial derivatives 

(Jacobian) of the system states with respect to the Adams/Solver state variables. Adams/Solver uses the 

Jacobian matrix in several analysis computations. 

When called from a force evaluation subroutine or from VARSUB, SYSARY returns the current 

predicted values of the state. SENSUB is called only after a completed integration state, so SYSARY 

returns the converged values when called from SENSUB. REQSUB is called at output steps and, like 

SENSUB, SYSARY returns the converged values when called from REQSUB. Therefore, the values 

returned from SYSARY are the current values of the state; whether they are the predicted values, or the 

corrected values, depends on where you are when calling SYSARY. 

You should use SYSFNC (see SYSFNC) to access a single system state corresponding to one modeling 

element. 

Where SYSFNC evaluates one Adams/Solver function, SYSARY evaluates several with one call. For 

example, to evaluate DX(12,10,99), DY(12,10,99) and DZ(12,10,99), you call SYSARY with: 

• fncnam='TDISP' 

• ipar(1)=12 

• ipar(2)=10 

• ipar(3)=99 

• nsize=3 

97

98 


SYSARY would return the requested x, y, and z displacements in states(1), states(2), and states(3), and 

return nstates=3. The following table lists the correspondence of other SYSARY fncnam values to 

Adams/Solver function names. 

fncnam: nsize: nstates: states: 

DISP 1-3 6 states(1) = DX(i1[,i2,i3]) 

states(2) = DY(i1[,i2,i3]) 

states(3) = DZ(i1[,i2,i3]) 

states(4) = PSI(i1[,i2]) 

states(5) = THETA(i1[,i2]) 

states(6) = PHI(i1[,i2]) 

TDISP 1-3 3 states(1) = DX(i1[,i2,i3]) 

states(2) = DY(i1[,i2,i3]) 

states(3) = DZ(i1[,i2,i3]) 

RDISP 1-2 3 states(1) = PSI(i1[,i2]) 

Q 1 NMODES* -- 

UVX** 2 3 -- 

UVY** 2 3 -- 

UVZ** 2 3 -- 

DC** 2 9 -- 

states(2) = THETA(i1[,i2]) 

states(3) = PHI(i1[,i2]) 

VEL 1-4 6 states(1) = VX(i1[,i2,i3,i4]) 

states(2) = VY(i1[,i2,i3,i4]) 

states(3) = VZ(i1[,i2,i3,i4]) 

states(4) = WX(i1[,i2,i3]) 

states(5) = WY(i1[,i2,i3]) 

states(6) = WZ(i1[,i2,i3])


TVEL 1-4 3 states(1) = VX(i1[,i2,i3,i4]) 

states(2) = VY(i1[,i2,i3,i4]) 

states(3) = VZ(i1[,i2,i3,i4]) 

RVEL 1-3 3 states(1) = WX(i1[,i2,i3]) 

QDOT 1 NMODES* -- 

states(2) = WY(i1[,i2,i3]) 

states(3) = WZ(i1[,i2,i3]) 

ACC 1-4 6 states(1) = ACCX(i1[,i2,i3,i4]) 

states(2) = ACCY(i1[,i2,i3,i4]) 

states(3) = ACCZ(i1[,i2,i3,i4]) 

states(4) = WDTX(i1[,i2,i3,i4]) 

states(5) = WDTY(i1[,i2,i3,i4]) 

states(6) = WDTZ(i1[,i2,i3,i4]) 

TACC 1-4 3 states(1) = ACCX(i1[,i2,i3,i4]) 

states(2) = ACCY(i1[,i2,i3,i4]) 

states(3) = ACCZ(i1[,i2,i3,i4]) 

RACC 1-4 3 states(1) = WDTX(i1[,i2,i3,i4]) 

QDDOT 1 NMODES* 

states(2) = WDTY(i1[,i2,i3,i4]) 

states(3) = WDTZ(i1[,i2,i3,i4]) 

FORCE 1-3 6 states(1) = FX(i1[,i2,i3]) 

states(2) = FY(i1[,i2,i3]) 

states(3) = FZ(i1[,i2,i3]) 

states(4) = TX(i1[,i2,i3]) 

states(5) = TY(i1[,i2,i3]) 

states(6) = TZ(i1[,i2,i3]) 

99

100 


TFORCE 1-3 3 states(1) = FX(i1[,i2,i3]) 

states(2) = FY(i1[,i2,i3]) 

states(3) = FZ(i1[,i2,i3]) 

RFORCE 1-3 3 states(1) = TX(i1[,i2,i3]) 

states(2) = TY(i1[,i2,i3]) 

states(3) = TZ(i1[,i2,i3]) 

PINPUT 1 n*** states(1) = PINVAL(i1,1) 

states(2) = PINVAL(i1,2) 

states(3) = PINVAL(i1,3) 

. 

. 

. 

states(n) = PINVAL(i1,n)


POUTPUT 1 n*** states(1) = POUVAL(i1,1) 

states(2) = POUVAL(i1,2) 

states(3) = POUVAL(i1,3) 

states(n) = POUVAL(i1,n) 

ARRAY 1 n*** states(1) = ARYVAL(i1,1) 

states(2) = ARYVAL(i1,2) 

states(3) = ARYVAL(i1,3) 

When the iflag argument in the user subroutine is true, SYSARY sets up the dependencies of the system 

states on the Adams/Solver state variables and sets the states array equal to zero. When the iflag 

. 

. 

. 

states(n) = ARYVAL(i1,n) 

*NMODES (see NMODES) is the number of active modes defined for that flex body. You can use the 

utility subroutine NMODES to determine the number of active modes. The ipar(1) array must contain 

the id of the flex body of interest. 

**Assume that the ipar array contains two markers, I and J. You can specify either I or J to be zero. In 

that case, the marker specified as zero defaults to the ground coordinate system. 

***Size as specified in the PINPUT, POUTPUT, or ARRAY statement. 

101

102 


argument is false, SYSARY returns the instantaneous values of the system states. You can make several 

calls to SYSARY, specifying each time the function used, and the parameters of the function. 

Tip: 1. Use SYSFNC to access individual states. Quite often, user-defined values depend 

on a single-system state such as the x component of the displacement between two 

markers, or the z component of the velocity between two markers. While you can 

use SYSARY to access the individual components, a single call to SYSFNC is 

convenient and more efficient. The use of SYSFNC is therefore recommended 

under these circumstances. 

Examples 

2. Use RCNVRT to convert rotational displacements Euler angles to any other angle 

representation, for example Adams AX, AY, AZ projected angles. 

CALL SYSFNC (`RDISP', IPAR, 2, ANGLES, NSTATE, ERRFLG) 

CALL RCNVRT (`EULER', ANGLES, `AXAYAZ', ANGLES, ISTAT) 

Use SYSFNC to access individual states.Quite often, user-defined values depend 

on a single-system state such as the x component of the displacement between two 

markers. While you may use SYSARY to access the individual components, a 

single call to SYSFNC is convenient and more efficient. The use of SYSFNC is 

therefore recommended under these circumstances. 

Caution: When the iflag argument is true, you must be sure to make the same SYSARY calls as when 

actually computing the results. Adams/Solver passes a parameter iflag to each user-written 

subroutine (xxxSUB). It indicates to you whether Adams/Solver is calling the subroutine 

for an initialization pass (iflag = true) or for a function evaluation (iflag =false). You must 

construct user-written subroutines such that all calls to SYSARY that are made during the 

simulation are also invoked when the iflag argument is true. Adams/Solver uses this 

information to construct the correct Jacobian matrix. 

This example shows properly written calls to SYSARY for UVX, UVY, UVE, and DC. 

SUBROUTINE VARSUB (ID, TIME, PAR, NPAR, DFLAG, IFLAG, VALUE) 

C 

C Inputs: 

C 

INTEGER ID, NPAR 

DOUBLE PRECISION TIME, PAR(*) 

LOGICAL DFLAG, IFLAG 

C 

C Outputs: 

C 

LOGICAL VALUE 

C 

C Local Variables:

C 

INTEGER IPAR(2), N_UVX, N_UVY, N_UVZ, N_DC, NSIZE 

DOUBLE PRECISION UVX(3), UVY(3), UVZ(3), DC(3,3) 

LOGICAL ERRFLG 

C 

C+-----------------------------------------------------* 

C 

IPAR(1) = NINT (PAR(1)) 

IPAR(2) = NINT (PAR(2)) 

NSIZE = 2 

C 

C Get the directions of the x axis 

C 

CALL SYSARY ('UVX', IPAR, NSIZE, UVX, N_UVX, ERRFLG) 

C 

C Get the directions of the y axis 

C 

CALL SYSARY ('UVY', IPAR, NSIZE, UVY, N_UVY, ERRFLG) 

C 

C Get the directions of the z axis 

C 

CALL SYSARY ('UVZ', IPAR, NSIZE, UVZ, N_UVZ, ERRFLG) 

C 

C Get the directions of the y axis 

C 

CALL SYSARY ('DC', IPAR, NSIZE, DC, N_DC, ERRFLG) 

C 

C Calculate the value of the variable: 

C 

VALUE = ... 

C 

RETURN 

END 


This example shows properly written calls to SYSARY for Q, QDOT, and QDDOT, as well as an 

associated use of the utility subroutines NMODES and MODINF. 

SUBROUTINE VARSUB ( ID, TIME, PAR, NPAR, DFLAG, 

& IFLAG, VALUE) 

C 

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

C 

C Note: For machines with 60 or more bits per word, 

C substitute "REAL" for "DOUBLE PRECISION". 

C 

C --- External variable definitions ------------------- 

103

104 


C 

INTEGER ID 

DOUBLE PRECISION TIME 

DOUBLE PRECISION PAR( * ) 

INTEGER NPAR 

LOGICAL DFLAG 

LOGICAL IFLAG 

DOUBLE PRECISION VALUE 

C 

C ID Identifier of calling VARIABLE statement 

C TIME Current time 

C PAR Array of passed statement parameters 

C NPAR Number of passed parameters 

C DFLAG Differencing flag 

C IFLAG Initialization pass flag 

C VALUE The VARIABLE value returned to ADAMS 

C 

C --- Local variables --------------------------------- 

C 

INTEGER NARG 

PARAMETER (NARG = 1) 

INTEGER MAXQ 

PARAMETER (MAXQ = 100) 

C 

CHARACTER*60 STRING 

CHARACTER*8 FNCNAM 

DOUBLE PRECISION MAXFRQ,C1,C2,C3,Q(MAXQ) 

DOUBLE PRECISION FREQ(MAXQ) 

INTEGER FBDYID,IPAR(NARG),NQ,I 

INTEGER OMODE(MAXQ) 


C 

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

C 

IF (NPAR .LT. 5) THEN 

STRING = 'Varsub requires 5 parameters' 

CALL ERRMES(.TRUE., STRING, ID, 'STOP' ) 

ELSE 

FBDYID = NINT( PAR(1) ) 

MAXFRQ = PAR(2) 

C1 = PAR(3) 

C2 = PAR(4) 

C3 = PAR(5) 

ENDIF 

C

CALL NMODES(FBDYID,NQ,ERRFLG) 

STRING = 'Cannot get number of modes' 

CALL ERRMES(ERRFLG, STRING, ID, 'STOP' ) 

IF (NQ .GT. MAXQ) THEN 

STRING = 'Too many modes, increase MAXQ in varsub' 

CALL ERRMES(.TRUE., STRING, ID, 'STOP' ) 

ENDIF 

C 

STRING = 'Cannot get frequencies of modes' 

CALL MODINF (FBDYID, OMODE, FREQ, ERRFLG) 


C 

IPAR(1) = FBDYID 

VALUE = 0.0 

C 

FNCNAM = 'Q' 

CALL SYSARY(FNCNAM, IPAR, NARG, Q, NQ, ERRFLG) 

STRING = 'Error calling SYSARY for Q.' 


DO 20 I=1,NQ 

IF (FREQ(I) .LT. MAXFRQ) VALUE = VALUE + C1*Q(I) 

20 CONTINUE 

C 

FNCNAM = 'QDOT' 


STRING = 'Error calling SYSARY for QDOT.' 


DO 30 I=1,NQ 


30 CONTINUE 

C 

FNCNAM = 'QDDOT' 


STRING = 'Error calling SYSARY for QDDOT.' 


DO 40 I=1,NQ 


40 CONTINUE 

C 

RETURN 

END 


For other examples that use the SYSARY data access subroutine, see the evaluation subroutines 

VFOSUB and VTOSUB. 

SYSFNC 

105

106 


The SYSFNC subroutine provides a single-system state value, such as displacement or velocity, to your 

subroutines, and defines and stores the Adams/Solver state variables on which the system state is 

dependent. 

Use 

Called By 

CONSUB, DIFSUB, GFOSUB, REQSUB, SENSUB, SFOSUB, VARSUB, VFOSUB, and VTOSUB 


CALL SYSFNC (fncnam, ipar, nsize, state, errflg)



fncnam A character variable specifying the name of the function whose data is 

being requested from SYSFNC. The legal values for fncnam are derived 

from the list of functions available to you in the FUNCTION= expression 

construct. Note that this function requires single quotes. For example, 

CALL SYSFNC (`DX', IPAR, 2, DX, ERRFLG) 

Here, the DX characters needs to be in single quotes. 

Any of the following character strings are legal: 

Functions/ 

variables: Character strings: 1 

Displacement DM, DX, DY, DZ, AX, AY, AZ, PSI, PHI, THETA, 

YAW, PITCH, ROLL 

Velocity VM, VR, VX, VY, VZ, WM, WX, WY, WZ 

Acceleration ACCM, ACCX, ACCY, ACCZ, WDTM, 

WDTX, WDTY, WDTZ 

Generic force FM, FX, FY, FZ, TM, TX, TY, TZ 

Elementspecific 

force 

BEAM, BUSH, FIELD, SPDP, SFORCE, VFORCE, 

VTORQ, GFORCE, NFORCE*, JOINT, JPRIM, 

MOTION, CVCV, PTCV 

System element DIF, DIF1, PINVAL, POUVAL, VARVAL, ARYVAL 

107

108 




Note: Adams/Solver (FORTRAN) - The NFORCE function is 

available only with SYSFNC from the REQSUB and SENSUB 

user written subroutines is not accessible from other user written 

subroutines. 

Adams/Solver (C++) - does not have support for the NFORCE 

measure from the SYSFNC utility subroutine. Instead, you 

should use the FX, FY, and FZ, measures. These can either be 

used to measure the sum of forces on a single marker, or the sum 

of forces transmitted by all connectors connecting a pair of 

markers. 

Unfortunately, these measures can not directly compute the force 

transmitted between two I markers on an NFORCE and 

something similar to FX(I1,J)-FX(I2,J) may be required. 

ipar An integer array containing the parameter list for fncnam. It consists of any 

valid list of parameters used in the associated Adams/Solver function, just 

as they would appear in a dataset FUNCTION = expression. 

nsize An integer variable specifying the number of values in ipar. 

errflg A logical variable that returns true if an error has occurred during your call 

to SYSFNC. 

state A double-precision variable returned by SYSFNC. State is zero when the 

iflag argument is set to true in the user-written subroutine, or when input 

errors are found. 

The SYSFNC subroutine provides system-state values (such as displacement and velocity) to user 

subroutines, and defines and stores the Adams/Solver state variables on which the system state is 

dependent. 

SYSFNC returns one system state or stores the dependency of the user value on the system state. You use 

the system state values to compute the instantaneous value of a user-defined function: Adams/Solver uses 

the dependency on state variables to create the matrix of partial derivatives (Jacobian) of the system state 

with respect to the Adams/Solver state variables. Adams/Solver uses the Jacobian matrix in several 

analysis computations. 

If you need to access several system states corresponding to one modeling element, you should use 

SYSARY (see SYSARY). 

SYSFNC requires that you specify system-state information as requested from Adams/Solver as a series 

of function call specifications. This is almost as if you were using the function expression capabilities to


obtain the system state. For example, to request DX(12,10,99), you can call SYSFNC with 

fncnam='DX', ipar(1)=12, ipar(2)=10, ipar(3)=99, and nsize=3. 

When the iflag argument in the user subroutine is true, SYSFNC sets up the dependencies of the system 

states on the Adams/Solver state variables and sets state equal to zero. When the iflag argument is false, 

SYSFNC returns the instantaneous values of the system states. 

Tip: Use SYSARY to simultaneously access several states. Quite often, user-defined values 

depend on a set of related system states such as all displacement components between two 

markers, or all velocity components between two markers. While SYSFNC can be called 

several times to access the individual components, a single call to SYSARY is not only 

more convenient, but more efficient. Therefore, we recommend that you use SYSARY 

under these circumstances. 

Caution: When the iflag argument is true, you must be sure to make the same SYSFNC calls as when 

actually computing the results. Adams/Solver passes a parameter iflag to each user-written 

subroutine (xxxSUB). It indicates to you whether Adams/Solver is calling the subroutine 

for an initialization pass (iflag = true) or for a function evaluation (iflag = false). You must 

construct user-written subroutines such that all calls to SYSFNC that are made during the 

simulation are also invoked when the iflag argument is true. Adams/Solver uses this 

information to construct the correct Jacobian matrix. 

Examples 

For examples using the SYSFNC data access subroutine, see the evaluation subroutines SFOSUB and 

VARSUB. 

SYSPAR 

The SYSPAR subroutine lets you supply the analytical partial derivatives of a subroutine with respect to 

values measured through SYSFNC and SYSARY. 

When you supply analytical partial derivatives, Adams/Solver does not need to resort to finite 

differencing to approximate these partial derivatives. Therefore, you potentially improve both accuracy 

and speed. 

SYSPAR can be used for any number (all, some, or none) of the SYSFNC or SYSARY calls made from 

your subroutine. 

You can also use SYSPAR intermittently. For example, you can use it only during the first half of the 

simulation. Adams/Solver will use the values you provide, when you provide them, and compute them 

automatically when you do not. 

Note: SYSPAR works primarily in the Adams/Solver (C++) or with the GSE statement 

in Adams/Solver FORTRAN. 

109

110 


Use 

Called By 

Any user subroutine that can call SYSFNC and SYSARY. 


CALL SYSPAR (fncname, iparam, nparam, partl, npartl, errflg) 


fncname A character variable specifying the name of the function corresponding 

to the partial derivatives that are being provided. The legal values for 

fncname are derived from the list of functions available to you in the 

FUNCTION = expression construct. Depending on the subroutine you 

are calling, see either SYSARY or SYSFNC for a list of legal characters. 

iparam An integer array containing the parameter list for fncnam. It consists of 

any valid list of parameters used in the associated Adams/Solver 

function, just as they would appear in a dataset FUNCTION = 

expression. 

nparam An integer variable specifying the number of values in ipar. 

partl Array of partial derivatives that you computed. 

npartl Number of partial derivatives in partl. Adams/Solver compares this 

number with the number that it expects, and issues an error message if 

you provide an incorrect number of partial derivatives. 


errflg A logical variable that returns true if an error has occurred during your 

call to SYSPAR. 


Adams/Solver offers a number of user subroutines that you can use to define the value of Adams 

variables, differential equations, forces, and so on. The subroutines return values of dimension 1, 3, or 6. 

Usually, the subroutines have a dependency on system states through measurements of the system state 

provided by a functional interface, SYSFNC and SYSARY. We define the following nomenclature: 

F - The value computed by the user subroutine 

Mi - The ith measured value 

q - The system generalized coordinates 

and observe that, in general:

F(M 1 (q), M 2 (q), ..., M N (q)) 


Because the user subroutine is effectively a black box, all that Adams/Solver knows about this function 

is that it depends on the measures, Mi, that you call through SYSFNC/SYSARY. 

During its analyses, Adams/Solver must construct a Jacobian matrix of the system of equations. For this 

purpose, Adams/Solver requires the partial derivatives, , of the function relative to the system- 

generalized coordinates, q. 

The FORTRAN 77 version of Adams/Solver approaches the problem of computing these partial 

derivatives in a direct manner, by altering the system states: 

∂ F 

----- 

∂ q 

F( qi + ∆) 

– F( qi) = ----------------------------------------- 

∆ 

We refer to this scheme as finite differencing or, more specifically, forward differencing. This approach 

has two main problems: 

• Some Adams elements, particularly the FLEX_BODY element, can have an extremely large 

number of generalized coordinates. Computing the partial derivatives in this way can be quite 

time consuming. Note that during finite differencing the user subroutine must be evaluated once 

for each state, qi, on which it depends. 

• You cannot assist Adams/Solver in the evaluation of the partial derivatives because you do not 

have direct access to the generalized coordinates, q, that Adams uses. 

To address these problems, the C++ version of Adams/Solver takes a different approach to 

computing the partial derivatives. The C++ version applies the chain rule: 

∂ F 

------- 

∂ qi N 

∂ F 

------- 

∂ M 

∂ Mj = ∑ --------- = 

∂ qi j = 1 

N 

∑ 

j = 1 

Note that in keeping with the observation that F is a black box, Adams/Solver continues to rely 

on finite differencing to compute , where Mj is well known and its partial derivatives can 

be evaluated analytically. This scheme solves both problems: 

• During finite differencing, the user subroutine only needs to be evaluated as many times as the 

total dimension of all the measures. 

For example, if F depends on the 3D TDISP measure of a marker on a FLEX_BODY, F must 

only be evaluated three times during finite differencing, even if the FLEX_BODY has 200 

modal generalized coordinates. This is a remarkable computational savings. 

∂ F 

----- 

∂ q 

F( Mj + ∆) 

– F( Mj) ---------------------------------------------- 

∆ 

∂ Mj --------- 

∂ qi ∂ F 

--------- 

∂ Mj 111

112 


Note that the computational savings are not always so generous. Consider a function F that 

depends on the two 6D measures, DISP and VEL, of a single PART marker, with respect to 

ground. During finite differencing, F must be evaluated 12 times, once for each dimension of 

each measure. Meanwhile, the function only depends on the 12 generalized displacements and 

velocities of the PART, so the 

FORTRAN 77 Adams/Solver would also only have needed 12 evaluations of F. 

• Because you are aware of the functional dependency of the function, F, on the measured 

∂ F 

--------- 

∂ Mj quantities, Mi, computing may be straightforward. Adams/Solver (C++) provides 

SYSPAR: an interface you can use to register these partial derivatives, in the cases where they 

are known and can be efficiently computed. 

Note that the potential of user-provided partial derivatives does not only affect the computational 

cost of evaluating the system Jacobian, but can also improve the accuracy of simulations and the 

rate of convergence. This is because your analytical derivatives are likely to be more accurate 

than those obtained using finite differencing. When Adams/Solver uses the Jacobian directly, as 

in Adams/Linear, the quality of the solution may also be improved. 

When F and M have dimension greater than 1, the partial matrix, should be stored in partl 

in FORTRAN 77 style column order. In other words, all the partial derivatives of F with respect 

to the first component of M come before the partial derivatives of F with respect to the second 

component of M, and so on. 

Each call to SYSFNC/SYSARY creates what the previous section refers to as a measure. For 

each of these measures, the creator of the user subroutine is allowed to register the partials of the 

function with respect to this measure. 

You do not need partial derivatives during every call to the user's subroutine, because they are 

only needed when the Jacobian is being evaluated. You must request the flag that indicates 

whether the partial derivatives are required, by calling the following function: 

CALL ADAMS_NEEDS_PARTIALS(PARFLG) 

∂ F 

--------- 

∂ Mj Note that, ideally, the PARFLG would have been added to the user subroutine call, alongside 

IFLAG and DFLAG, but the user subroutines have a standard interface that cannot be changed.

Examples 


You can make calls to SYSPAR only for those SYSFNC/SYSARY for which partials are 

conveniently available. As mentioned earlier, you can make SYSPAR calls intermittently. In 

other words, you can call SYSPAR only during some period of the simulation when partials can 

be easily computed, but skipped during other parts of the simulation. For example, when an 

impact force is zero, its partials are trivially zero. 

Caution: SYSPAR is optional. You should expect the number of function evaluations and CPU time 

to decrease. If they do not, you may have made a mistake. 

Using an SFOSUB with SYSPAR 

The following example shows how a SFOSUB has been modified to use SYSPAR. The SFOSUB 

computes VALUE = DX(1,2)*VZ(1,2). 

Relating this to the terminology used earlier, we have: 

F = M 1 M 2 

where M 1 = DX(1,2) and M 2 = VZ(1,2). Consequently: 

∂ F 

---------- = VZ( 1, 2) 

∂ M1 and 

∂ F 

---------- = 

DX( 1, 2) 

∂ M2 When you do not provide partial information, Adams/Solver fills in the blanks using finite 

differencing. 

It is, of course, an error to call SYSPAR without a matching call to SYSFNC or SYSARY. 

The SFOSUB implementation follows: 

SUBROUTINE SFOSUB (ID, TIME, PAR, NPAR, DFLAG, IFLAG, VALUE) 

INTEGER ID 



INTEGER NPAR 

LOGICAL DFLAG 

LOGICAL IFLAG 


113

114 


DOUBLE PRECISION DX, VZ 

INTEGER NUM, IPAR(2) 


LOGICAL PARFLG 


IPAR(1) = PAR(1) 

IPAR(2) = PAR(2) 

CALL SYSFNC('DX', IPAR, 2, DX, ERRFLG ) 

CALL SYSFNC('VZ', IPAR, 2, VZ, ERRFLG ) 

VALUE = DX*VZ 

IF(PARFLG) THEN 

CALL SYSPAR('DX', IPAR, 2, VZ, 1, ERRFLG) 

CALL SYSPAR('VZ', IPAR, 2, DX, 1, ERRFLG) 

ENDIF 

CALL ERRMES(ERRFLG,'ERROR FOR SFORCE ',ID,'STOP') 

RETURN 

END 

Using SYSPAR with Utility Subroutines 

This SFOSUB example shows how you can use SYSPAR in conjunction with utility subroutines. In this 

SFOSUB you have: 

VALUE = -IMPACT(400-DM(12,9),-VR(12,9)) 

or, using the nomenclature developed earlier: 

F = -IMPACT(400-M 1 ,-M 2 ) 

where M 1 = DM(12,9) and M 2 = VR(12,9). Here, you must rely on the ability of the IMPACT utility 

function to provide partial derivatives of its arguments. 

∂ F 

---------- 

∂ M1 ∂ F 

---------- 

∂ M2 = 

= 

∂ IMPACT 

-------------------------- ( 400 – M 

∂ M 1′ – M2) ( – 1) 

1 

∂ IMPACT 

-------------------------- ( 400 – M 

∂ M 1′ – M2) ( – 1) 

2 

The implementation follows. Pay close attention to the use of the IORD argument (argument 8) to the 

IMPACT function. It controls whether 0th, 1st, or 2nd derivative of the impact is being requested. Learn 

more about the IMPACT function (C++ or FORTRAN).

SUBROUTINE SFOSUB (ID, TIME, PAR, NPAR, DFLAG, IFLAG, VALUE) 

INTEGER ID 



INTEGER NPAR 

LOGICAL DFLAG 

LOGICAL IFLAG 


DOUBLE PRECISION DM, VR, V(3) 

INTEGER IPAR(2) 

LOGICAL ERRFLG, PARFLG 

IPAR(1)=12 

IPAR(2)=9 


CALL SYSFNC('DM', IPAR, 2, DM, ERRFLG ) 

CALL SYSFNC('VR', IPAR, 2, VR, ERRFLG ) 


CALL IMPACT(400.D0-DM,-VR,100D0,1.D2,1.5D0, 1D1,1.D0,1,V,ERRFLG) 

CALL SYSPAR('DM', IPAR, 2, V(1), 1, ERRFLG ) 

CALL SYSPAR('VR', IPAR, 2, V(2), 1, ERRFLG ) 

ENDIF 


CALL IMPACT(400-DM,-VR,100D0,100.0D0,1.5D0,10D0,1.0D0,0,V,ERRFLG) 

VALUE=-V(1) 

CALL ERRMES(ERRFLG,'ERROR FOR SFORCE',ID,'STOP') 

RETURN 

END 

Using FIESUB with SYSPAR 

This example, involving FIESUB, shows how SYSPAR has closed the functionality gap between 

GFOSUB and FIESUB. In the FORTRAN 77 version of Adams/Solver, the ability to define partial 

derivatives of the FIELD element in a FIESUB user subroutine gives it a computational advantage over 

the GFORCE force element and a GFOSUB user subroutine. The FIESUB user subroutine is defined as 

follows: 

CALL FIESUB(ID, TIME, PAR, NPAR, DISP, VELO, 

DFLAG, IFLAG, FIELD, DFDDIS, DFDVEL) 

where DISP and VELO are the displacement and velocity of the I and J markers of the field element that 

are input to FIESUB. FIESUB computes the 6D value of the force, FIELD. Also, when DFLAG is 

TRUE, you must provide the partial derivatives with respect to displacement, DFDDIS, and the partial 

derivatives with respect to velocity, DFDVEL. Learn more about FIELD (C++ or FORTRAN). 

115

116 


The removal of the advantage of FIESUB over GFOSUB is demonstrated by implementing the FIESUB 

in a GFOSUB: 

SUBROUTINE GFOSUB (ID, TIME, PAR, NPAR, DFLAG, IFLAG, RESULT) 

INTEGER ID 



INTEGER NPAR 

LOGICAL DFLAG 

LOGICAL IFLAG 


DOUBLE PRECISION DISP(6), VELO(6) 

DOUBLE PRECISION DFDDIS(6,6), DFDVEL(6,6) 

INTEGER IPAR(4) 

LOGICAL ERRFLG, PARFLG 

C 

C This GFOSUB should never be finite differenced 

C 

CALL ERRMES(DFLAG,'DFLAG=.TRUE. UNEXPECTED',ID,'STOP') 

C 

C Check if partials are needed 

C 


C 

C Measure displacements, projection angles and velocity 

C between markers I and J (PAR(1) and PAR(2)). Note that 

C velocity measure takes four marker arguments because 

C FIESUB uses velocity of I wrt J in coordinate system 

C of J with observer in J. 

C 

IPAR(1)=NINT(PAR(1)) 




C 

CALL SYSARY('TDISP', IPAR, 3, DISP, 3, ERRFLG ) 

CALL SYSFNC('AX', IPAR, 2, DISP(4), ERRFLG ) 

CALL SYSFNC('AY', IPAR, 2, DISP(5), ERRFLG ) 

CALL SYSFNC('AZ', IPAR, 2, DISP(6), ERRFLG ) 

CALL SYSARY('VEL', IPAR, 4, VELO, 6, ERRFLG ) 


DO 100 I = 1 , 6

DO 100 J = 1 , 6 

DFDDIS(I,J)=0.D0 

DFDVEL(I,J)=0.D0 

100 CONTINUE 

ENDIF 

C 

C Subtract the free length, PAR(3),...,PAR(8) 

C 

DO 200 I = 1 , 6 

DISP(I)=DISP(I)-PAR(I+2) 

200 CONTINUE 

CALL FIESUB(ID, TIME, PARS, NPAR, DISP, VELO, PARFLG, IFLAG, 

+ VALUE, DFDDIS, DFDVEL) 

IF (PARFLG) THEN 

CALL SYSPAR('TDISP', IPAR, 3, DFDDIS, 18, ERRFLG) 

CALL SYSPAR('AX', IPAR, 2, DFDDIS(1,4), 6, ERRFLG) 

CALL SYSPAR('AY', IPAR, 2, DFDDIS(1,5), 6, ERRFLG) 

CALL SYSPAR('AZ', IPAR, 2, DFDDIS(1,6), 6, ERRFLG) 

CALL SYSPAR('VEL', IPAR, 4, DFDVEL, 36, ERRFLG) 

ENDIF 

RETURN 

END 

Debugging 


When modifying a user subroutine by adding SYSPAR calls, you may be concerned about the 

correctness of the partial derivatives. In this case, you can define the environment variable 

MDI_DEBUG_SYSPAR. When this environment variable is set, Adams/Solver uses finite differencing 

to verify the user-provided partial derivative and write debug information to the standard output (the 

terminal). For example: 

SFOSUB(1): DZ(1,11) A: 5.00000E+00 U: 2.06158E+11 

which informs you that during the verification of the SFOSUB for SFORCE/1, you provided the value 

2.06158E+11 for the partial derivative with respect to the DZ(1,11) measure, but Adams/Solver found, 

using finite differencing, that this value should be 5.0. A closer inspection of the source code reveals that 

it contained single precision: 

CALL SYSPAR('DZ', IPAR, 2, 5., 1, ERRFLG) 

rather than double precision: 

CALL SYSPAR('DZ', IPAR, 2, 5.D0, 1, ERRFLG) 

117

118 


Computing Partial Derivatives 

The computation of the partial derivatives of a complicated FORTRAN subroutine can be an 

overwhelming task. MSC investigated the software, Automatic Differentiation of FORTRAN 

(ADIFOR), that may be able to automate this task. 

ADIFOR is a tool for automatic computation of derivatives of function defined in FORTRAN 77 

programs. 

Automatic differentiation is a technique for computing the derivatives of functions described by 

computer programs. ADIFOR implements automatic differentiation by transforming a collection of 

FORTRAN 77 subroutines that compute a function f into new FORTRAN 77 subroutines that compute 

the derivatives of the outputs of f with respect to a specified set of inputs of f. 

ADIFOR 2.0 consists of: 

• ADIFOR Preprocessor 

• ADIntrinsics template expander and library 

• SparsLinC library. 

Figure 1 shows a block diagram of the ADIFOR 2.0 process, which consists of three steps: 

1. Apply the ADIFOR Preprocessor to your FORTRAN 77 program to produce augmented code for 

the computation of derivatives. The preprocessor invokes the ADIntrinsics template expander 

directly. 

2. Construct a derivative driver code that invokes the generated derivative code and uses the 

computed derivatives. 

3. Compile the generated derivative code and your derivative driver code, and link these with the 

derivative support packages. That is, the ADIntrinsics exception handling package and 

(optionally) the SparsLinC sparse derivative package. 

Figure 1. Block Diagram of the ADIFOR Process


To retrieve the ADIFOR 2.0 automatic differentiation software for educational and non-profit research 

use, and for commercial evaluation, visit either of the ADIFOR group Web sites, at: 

http://www.mcs.anl.gov/adifor or http://www.cs.rice.edu/~adifor. These pages describe how to request 

access to ADIFOR 2.0 and download the software. The pages also contain links to publications related 

to ADIFOR, as well as legal notices. 

TCNVRT 

TCNVRT converts translational coordinates from one representation to another. 

Use 

Called By 


Prerequisite 

None 


CALL TCNVRT (sys1, coord1, sys2, coord2, istat) 

119

120 



sys1 A character string specifying the system in which the values passed in 

coord1 were determined. The possible character strings and their 

meanings are: 



MOTSUB, REQSUB, or SFOSUB can call TCNVRT to change the Cartesian coordinates used to specify 

a displacement vector to cylindrical coordinates. 

TIMGET 

CARTESIAN - Cartesian coordinates (x, y, and z). 

CYLINDRICAL - Cylindrical coordinates (radius, theta, and z). 

SPHERICAL - Spherical coordinates (radius, phi, and theta). 

Note: Do not confuse this phi and theta with the Euler angles named 

phi and theta. 

coord1 A double-precision array containing the coordinates to be converted. 

Angles should be input in radians. 

sys2 A character string specifying the system in which the values returned as 

output in coord2 are to be determined. Possible character strings are the 

same as those for sys1. 

coord2 The converted coordinates as output. Angles are output in radians. 

istat An integer variable indicating either the success or the reason for the 

failure of the call to TCNVRT. 

If: Then: 

istat= 0 The call to TCNVRT was successful. 

istat= -1 The coordinate system for sys1 was not 

correctly specified. 

istat= -2 The coordinate system for sys2 was not 

correctly specified. 

TIMGET returns the simulation time corresponding to the last successful simulation step.

Use 

Called By 



CALL TIMGET (time) 



time A double-precision scalar that contains the simulation time at the end of the 

last successful step. 


TIMGET is primarily useful in situations where past values of system states are to be used in defining 

the current values of system. In some applications, you need to determine when a specific time has been 

successfully passed in the simulation. The value of the time argument passed to user-written subroutines 

is the current simulation time, and is therefore not a reliable indicator of the last successful simulation 

time. Moreover, if convergence at the current time is not achieved, Adams/Solver backs up to the last 

successful simulation step and tries a new step. 

The value of simulation time returned by TIMGET represents a successful simulation time. 

Adams/Solver never backs up over this time again. 

Digital control systems are instances where the values provided by TIMGET are useful. Digital control 

systems are characterized by the fact that observations of system states are taken at pre-specified regular 

intervals named sampling periods. Based on the system states sampled and the governing control laws, 

forces acting on the system are defined. These forces are held constant until the next sample period, 

regardless of how the system state changed. 

Make sure that you only sample converged values of system states when determining the current system 

state. TIMGET is useful in this context, because it provides to user subroutines a record of when a set of 

system states have converged. 

Tip: SENSUB has commonly been used to identify a successful simulation step. You don't need 

to rely on TIMGET anymore. 

UCOVAR 

UCOVAR is used with UCOSUB, to tell Adams/Solver the part states that are used in the user-defined 

constraint. 

121

122 


Use 

Called By 

UCOSUB 

Prerequisite 

UCOSUB iflag parameter equals .TRUE. 


CALL UCOVAR (id, nparts, lparts, nvars, lvars)



id An integer variable that specifies the ID of the UCON statement for 

which you are defining the variables. Use the identifier in the UCOSUB 

argument list. 

nparts An integer variable that specifies the total number of elements in the 

array lparts. The value of nparts must equal the value of nvars. 

123

124 


lparts An integer array that lists the part identifiers corresponding to the 

variable types in lvars. The number of part identifiers in lparts must 

equal the number of integer codes in lvars. Thus the lparts and lvars 

arrays must be equal in length. 

nvars An integer value that indicates the total number of integer codes in lvars. 

The value of nvars must equal the value of nparts. 

The function: Means that: 

11 X displacement of the part center-of-mass with 

respect to ground 

12 Y displacement of the part center-of-mass with 


13 Z displacement of the part center-of-mass with 


14 Psi Euler rotation of part principle axis with respect 

to ground 

15 Theta Euler rotation of part principle axis with 


16 Phi Euler rotation of part principle axis with respect 


21 X velocity of the part center-of-mass with respect 


22 Y velocity of the part center-of-mass with respect 


23 Z velocity of the part center-of-mass with respect to 

ground 

24 Psi time derivative 

25 Theta time derivative 

26 Phi time derivative 

Note that the tens digit is one for displacement codes and two for 

velocity codes. Also, note that the ones digit indicates a translational or 

a rotational component with an integer from one to six. All translational 

variable values refer to the motion of the part center-of-mass, and all 

rotational variable values refer to the rotation of the principal axes, with 

respect to the ground reference frame. The number of integer codes in 

lvars must equal the number of part identifiers in lparts. Therefore, the 

lvars and lparts arrays must be equal in length.


lvars An integer array that contains the integer codes that identify the variables 

involved in the constraint. The table below defines the codes that lvars 

can contain. 


UCOVAR tells Adams/Solver which of the principal axes coordinates are used in the user-defined 

constraint. Adams/Solver subsequently passes these to the evaluation subroutine UCOSUB in the array 

q. UCOSUB should call UCOVAR in response to a true initialization flag (iflag). For an example of a 

UCOSUB evaluation subroutine that calls UCOVAR, see UCOSUB. 

Caution: • The arrays lparts and lvars can contain as many as thirty values. Don't attempt to 

load and pass these two arrays with more than thirty values in each. 

USRMES 

USRMES allows you to output messages for information or for documenting errors that occur in userwritten 

subroutines. 

Use 

Called By 


• When selecting the displacements or the velocities of the part principal axes for the 

constraint, remember that the part principal axes are not always identical to those 

of the part center-of-mass marker (cm). The following list summarizes the 

circumstances in which the part principal axes may differ from those of the part 

center-of-mass marker. 

• When the PART statement does not include the CM argument, the principal 

axes default to the body coordinate system. 

• Whenever the center-of-mass marker z-axis is parallel to the z-axis of the 

ground reference frame at time zero, Adams/Solver permutes the internal 

representation of the principal axes by 90-degree rotations, to avoid an Euler 

matrix singularity. 

• If the IP argument in the PART statement includes products of inertia, 

Adams/Solver computes the inertial representation of the principal axes so that 

the products of inertia all become zero. 

• When specifying an IM marker, Adams/Solver computes the principal axes, 

which may or may not be the axes of the cm marker. 

125

126 


Prerequisite 

None 


CALL USRMES (msgflg, mesage, id, msgtyp) 


id An integer variable that specifies the ID of the statement that is currently 

invoking the user-written subroutine. 

mesage A character string or variable of as many as eighty characters that you 

want USRMES to document. This character string should be a 

descriptive message and should include the name of the subroutine 

issuing the message. 

msgflg A logical (true or false) variable. When msgflg is true, USRMES 

documents a message. 

msgtyp A character variable that indicates what type of message is given. 

msgtyp can have one of four values: 


INFO - For information messages 

WARN - For warnings 

ERROR - For error messages 

FAULT - For fatal error messages 

INFO_NOPAD - Prints out the information message but without the 

USRMES:USER1 tag before the message 

LOGINF - Writes out the message in the message file but doesn’t print 

it out on the screen 

If msgtyp has any other value, Adams/Solver issues an information 

message. 

USRMES allows you to output messages from user-written subroutines. The messages always go to the 

Message File, and during interactive execution, Adams/Solver displays them on the screen.

User-Written Subroutines 


User-written subroutines, while a little more difficult to use, provide a degree of generality, efficiency 

and flexibility that function expressions do not. Subroutines allow you to use FORTRAN-77 features to 

define functions not otherwise available with Adams/Solver, and to tailor Adams/Solver to your needs. 

By linking in user-written subroutines, you don't lose any efficiency or decrease the simulation speed. 

Subroutines and function expressions serve essentially the same purpose: they both allow you to define 

non-standard input to Adams. 

Function expressions are easier to work with, because you don't have to compile or link programs. Also, 

they work on every machine on which Adams/Solver is available. User-written subroutines, however, 

are much more general. The power of the programming language is available to define modeling 

elements or special output. 

On the other hand, function expressions support a limited set of programming constructs. Therefore, 

complicated phenomena, especially those involving a lot of logic, cannot be easily described using 

function expressions. 

You use user-written subroutines when: 

• Dataset functions become awkward. 

• You need to define functions used by a group of users. 

• Statements, such as GSE and UCON, require them. 

• You want to control the running of complex simulations that require decision-making logic. 

Write user-written subroutines with care because incorrectly coded subroutines are very difficult to 

debug. Follow a crawl-walk-run approach for developing user subroutines. Start with simple versions of 

a user-written subroutine, make sure it works as desired, then gradually increase the complexity of the 

subroutine. Make sure that there are no compiler or linker warnings when your subroutine is linked into 

Adams. 

The "C" style interface to user subroutines has been enhanced to replace some of the arguments with a 

pointer to a structure. This will require changes to your user subroutine source code. If you are using the 

fortran style interface to user subroutines you will not be effected and no changes will be required. 

The new argument list to the "C" style interface replaces some of the arguments with a pointer to a 

structure. This structure contains the replaced arguments plus additional information. Old arguments 

such as ID, PAR, and NPAR have been incorperated into the structure. New arguments such as marker 

id's have been added to the structure. 

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. 

127

128 


Use 


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



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 A logical variable that Adams/Solver sets to true when it needs the functional 

dependency information from CFFSUB. Functional dependencies are 

established with the same calls to SYSARY and SYSFNC that are later used 

to compute the values of the CONTACT components (see SYSARY and 

SYSFNC). If the iflag argument is false, the values of the user-defined 

expressions are computed. 

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. 

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. 

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. 

129

130 


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. 

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. 

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 alreadyexisting 

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 true. 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 true. 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. 

Fortran - Prototype 

• 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 true: 

• 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 false, before dividing by these values. 

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

131

132 


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

& NFORCE, DFLAG, IFLAG, FORCE) 

C 


IMPLICIT NONE 

INTEGER ID 



INTEGER NPAR 

DOUBLE PRECISION LOCI(3) 

DOUBLE PRECISION LOCJ(3) 

DOUBLE PRECISION X(3) 

DOUBLE PRECISION XDOT(3) 

DOUBLE PRECISION NFORCE 

LOGICAL DFLAG 

LOGICAL IFLAG 

DOUBLE PRECISION FORCE(3) 

C 

C Input parameters 

C 

C ID Identifier of calling CONTACT statement 

C TIME Current timeC 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 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 

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; 

133

134 


}; 

CNFSUB 

The CNFSUB evaluation subroutine computes a set of normal force values for a CONTACT statement 

(C++ or FORTRAN). You can use a CNFSUB when the default normal force routine is not applicable to 

your model. 

Use 


SUBROUTINE CNFSUB (id, time, par, npar, loci, ni, locj, nj, gap, gapdot, gapdotdot, area, dflag, iflag, 

result)



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 CNFSUB to 



gap A double-precision variable that specifies the value of the contact penetration. 

gap ≥ no penetration 

gap < 0 penetration 

gapdot A double-precision variable that specifies the first time-derivative of the gap. 

gapdot ≥ 

0 gap is increasing (penetration is decresing) 

gapdot < 0 gap is decreasing (penetration is increasing) 

gapdotdot A double-precision variable that specifies the second time-derivative of the gap. 

gapdotdot >= 0 gapdot is increasing 

gapdotdot < 0 gapdot is decreasing 

id An integer variable that provides the identifier of the CONTACT statement 

requesting information from CNFSUB. From the identifier, Adams/Solver 




dependency information from CNFSUB. Functional dependencies are 

established with the same calls to SYSARY and SYSFNC that are later used to 

compute the values of the CONTACT components (see SYSARY and 

SYSFNC). If the iflag argument is false, the values of the user-defined 


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. 

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. 

ni A double-precision array that specifies the surface normal vector of the 

CONTACT I Geometry (IGEOM) at the contact location. Expressed in the 

coordinate system of the reference marker of IGEOM. 

nj A double-precision array that specifies the surface normal vector of the 

CONTACT J Geometry (JGEOM) at the contact location. Expressed in the 

coordinate system of the reference marker of JGEOM. 

135

136 



USER parenthetical list. This variable provides the CNFSUB evaluation 

subroutine with the number of values stored in the par array. 

par A double-precision array of constants taken in order from the 

NORMAL_FUNCTION USER parenthetical list of the CONTACT statement. 

time A double-precision variable through which Adams/Solver conveys the current 

simulation time. 


result A double-precision array that returns the value of the normal force. 


The IMPACT and POISSON force types in the CONTACT statement are usually sufficient to define the 

contact normal force. However, if you require another force model, you can use a CNFSUB. If the 

algorithms use or consist of already-existing FORTRAN-77 subroutines, CNFSUB can be made to call 

them. 

You can call utility subroutines, such as AKISPL, CUBSPL, SYSARY, and SYSFNC, from CNFSUB, 

to obtain information about system variables, user-defined variables, and splines. 

The SYSARY and SYSFNC utility subroutines set functional dependencies when the CNFSUB 

argument iflag is true. 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 CNFSUB with the argument iflag set to true. Adams/Solver 

does this once for each CONTACT statement with a 

NORMAL_FUNCTION=USER() argument. 

During each call to CNFSUB, 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 

Only the first value in the array is used by Adams/Solver. 

The use of the dflag variable is optional. Its purpose is to simply let you know that CNFSUB is being 

called to evaluate a partial derivative. One of the states on which the CNFSUB depends has been 

perturbed very slightly. In many situations, it is likely that major calculations in the CNFSUB are


insensitive to small changes in state, and therefore, need not be recalculated. In such situations, you can 

structure the CNFSUB not to redo these calculations. 

Tip: If the SYSARY or SYSFNC subroutines are called to access angular displacements, the 

values returned by CNFSUB may contain discontinuities. Discontinuities occur if there is 

a Euler singularity. To avoid the Euler singularity (and thus the discontinuities), use the 


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 iflag argument at all. You can just call 

SYSARY and/or SYSFNC, compute the user-defined variable value, and return to 

Adams/Solver. 

Caution: When the iflag argument is true: 

FORTRAN - Prototype 

• 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 


Adams/Solver (FORTRAN) 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 that the iflag argument 

is set to false, before dividing by these values. 

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

SUBROUTINE CNFSUB(ID, TIME,PAR, NPAR, LOCI, NI, LOCJ, NJ, 

& GAP, GAPDOT,& GAPDOTDOT, AREA, DFLAG, IFLAG, RESULT) 

C 


C 

IMPLICIT NONE 

INTEGER ID 



INTEGER NPAR 

DOUBLE PRECISION LOCI(3) 

DOUBLE PRECISION NI(3) 

DOUBLE PRECISION LOCJ(3) 

DOUBLE PRECISION NJ(3) 

DOUBLE PRECISION GAP 

DOUBLE PRECISION GAPDOT 

137

138 


DOUBLE PRECISION GAPDOTDOT 

DOUBLE PRECISION AREA 

LOGICAL DFLAG 

LOGICAL IFLAG 


C 

C Input parameters 

C 

C ID Identifier of calling CONTACT statement 


C PAR Array containing passed parameters 


C LOCI contact point location on I in I coordinates 

C NI contact normal on I in I coordinates 

C LOCI contact point location on J in J coordinates 

C NI contact normal on J in J coordinates 

C GAP contact penetration 

C GAPDOT first time derivative of GAP 

C GAPDOTDOT second time derivative of GAP CAREA contact area 

C 

C components returned to ADAMSC 

C RESULT Array (dimension 3) of computed normal force 

C RESULT(1) Normal forceC RESULT(2) not used 

C RESULT(3) not used 

C 

C ---Local variable and parameter definitions ------ 

C ... 

C 


C 

C Assign readable variable names to passed parameters 

C ... 

C 

C Call SYSFNC and/or SYSARY to collect information for 

C the following calculations. Note: if IFLAG is 

C true, these calls are actually setting functional 

C dependencies. 

C 

CALL SYSFNC (...) 

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) THENC 

C - Subroutine initialization ------------- 

C 

... 

C 

ENDIF 

C

C - Evaluate Normal Force components ------------- 

C 

C Your algorithms 

C 

... 

C 

C Assign values to the RESULT array 

C 

RESULT(1) = ... 

RESULT(2) = ... 

RESULT(3) = ... 

C 

RETURN 

END 



typedef void adams_c_CNFSUB(const struct sAdamsContactFriction* fric, 

double TIME, const double* LOCI, const double* NI, const double* 

LOCJ, const double* NJ, double GAP, double GAPDOT, double GAPDOTDOT, 

double AREA, int DFLAG, int IFLAG, double* VALUES ); 

typedef void STDCALL adams_f77_CNFSUB(const int* ID, const double* 

TIME, const double* PAR, const int* NPAR, const double* LOCI, const 

double* NI, const double* LOCJ, const double* NJ, const double* GAP, 

const double* GAPDOT, const double* GAPDOTDOT, 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; 


}; 

CONSUB 

The CONSUB driver subroutine can be used to control an Adams simulation from within a user 

subroutine. Interactively issuing the CONTROL command (C++ or FORTRAN) invokes CONSUB. 

Other user-written subroutines cannot call CONSUB. 

139

140 


Use 

Corresponding Command 

CONTROL/ [FUNCTION=USER(r1[,...,r30])[/]] 

[[ ]] Optionally select an item combination 


SUBROUTINE CONSUB (par, npar) 


npar An integer variable that indicates the number of constants specified in the 

parenthetical list of the USER keyword. The primary purpose of npar is to 

provide CONSUB with the number of values stored in the par array. 

par A double-precision array of constants taken in order from the parenthetical list 

in the USER keyword CONTROL command. 


Adams/Solver passes the parameters in the CONTROL statement FUNCTION=USER() argument as an 

array of real numbers to the user-written subroutine CONSUB. From CONSUB, any utility subroutines 

such as SYSARY, SYSFNC, or AKISPL can be called. 

• The MODIFY utility subroutine can be called to change an Adams/Solver statement just as it 

would be done interactively. 

• The ANALYS utility subroutine can be called to invoke one of the Adams/Solver analysis types. 

• The DATOUT utility subroutine can be called to process output from the Adams/Solver 

simulation(s). 

When execution of CONSUB stops, Adams/Solver prompts you for another command. 

Caution: When program control passes to CONSUB, automatic generation of output stops. If you 

want to create output, call the DATOUT utility subroutine. 


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

SUBROUTINE CONSUB ( PAR, NPAR ) 

C 

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

C 

C


C - External variable definitions --------- 

C INTEGER NPAR DOUBLE PRECISION 

PAR( * ) 

C 



C 

C - Local variable definitions ----------- 

C ... 

C 

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

C 

C - Your commands ----------------- 

C ... 

C 

RETURN 

END 


typedef void adams_c_CONSUB(const struct sAdamsControl* con); 

/* 

* CONTROL 

*/ 

struct sAdamsControl 

{ 

int NPAR; 


}; 

Examples 

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

COUSUB, COUXX, COUXX2 

The COUSUB, COUXX, and COUXX2 subroutines define a user-defined COUPLER (C++ or 

FORTRAN): 

• COUSUB specifies the coupler constraint as a function of the displacements of the joints being 

coupled. 

• COUXX returns to Adams/Solver the first partial derivatives of the coupler constraint, with 

respect to each joint displacement. 

• COUXX2 returns the matrix of second partial derivatives of the coupler constraint, with respect 

to the joint displacements. 

141

142 


Use 


COUPLER/id, JOINTS=id1, id2[,id3] 


SUBROUTINE COUSUB (id, time, par, npar, disp, ndisp, iflag, phi)SUBROUTINE COUXX (id, time, 

par, npar, disp, ndisp, iflag, dfda)SUBROUTINE COUXX2 (id, time, par, npar, disp, ndisp, iflag, dfda2)



id An integer variable that specifies the identifier of the COUPLER statement 

whose constraint function is being specified. 

time A double-precision variable that contains the current simulation time. 

par A double-precision array that contains the constants taken, in order, from the 

list of values provided with the USER argument in the COUPLER statement. 

npar An integer variable containing the number of entries in the PAR array. 

disp A double-precision array containing the instantaneous joint displacements. 

Translational displacements are in units of length and rotational displacements 

are in radians. 

ndisp An integer variable that defines the size of the DISP array. This is equal to the 

number of joints being coupled in the COUPLER statement. 

iflag A logical variable that is set to TRUE when COUSUB, COUXX and COUXX2 

are being called for an initialization pass. IFLAG is set to TRUE once for each 

COUPLER statement in a simulation. 


phi A double-precision scalar that contains the value of the coupler constraint 

equation. 


The constraint equation must be specified in implicit form. For example, the 

equation must be in the form: f (disp) = 0. 

dfda A double-precision array of length ndisp that contains the partial derivatives 

of phi with respect to disp. Therefore, fda(i) = phi / isp(i). 

dfda2 A double-precision array of dimensions ndisp that contains the second partials 

derivatives of phi with respect to disp. 

Therefore, dfda2(i) = 2 / disp (i) disp (i) 

The COUPLER statement is used to relate the motion of two or more joints. If the relationship between 

the motion in a set consisting of two or three joints is linear, the scale factors relating the motion can be 

directly specified in the dataset. 

However, when the relationship between the joints is nonlinear in nature, the equation specifying this 

relationship must be specified in the user-written subroutines COUSUB, COUXX, and COUXX2. 

143

144 


Therefore, if d1, d2, and d3 are displacement/rotations in three translational or revolute joints, the 

relationship between them may be written analytically as: ƒ1 (d1) + ƒ2(d2) + ƒ3(d3) = 0 

COUSUB, COUXX, and COUXX2 must only be functions of the input variables specified above. You 

cannot call SYSFNC or SYSARY to access other system states. 


A sample structure for COUSUB, COUXX, and COUXX2 is shown next. The comments explain the 

logical structure of each of the subroutines. 

COUSUB 

SUBROUTINE COUSUB (ID, TIME, PAR, NPAR, DISP, & 

NDISP, IFLAG, PHI) 

C 

C+----------------------------------------------------* 

C 

C Inputs: 

C INTEGER ID DOUBLE PRECISION TIME DOUBLE 

PRECISION PAR(*) INTEGER NPAR DOUBLE PRECISION 

DISP(*) INTEGER NDISP LOGICAL IFLAGCC 

Outputs: 

C DOUBLE PRECISION PHICC Local Variables: 

C ... ... 

C 

C+----------------------------------------------------* 

C Executable Code 

C+----------------------------------------------------* 

C 

C IF (IFLAG) THEN 

C 

C+----------------------------------------------------* 

C Initialization pass: Initialize necessaryC local 

variables 

C+----------------------------------------------------*C ... 

... 

C ELSEC 

C+----------------------------------------------------* 

C Evaluation pass: Define Phi the 

C coupler constraint 

C+----------------------------------------------------* 

C ... ... 

PHI = ... 

C 

ENDIF 

C 

C 

RETURN 

END


COUXX 

SUBROUTINE COUXX (ID, TIME, PAR, NPAR, DISP, 

& NDISP, IFLAG, DFDA) 

C 

C+----------------------------------------------------* 

C 

C Inputs: 

C 

INTEGER ID 


DOUBLE PRECISION PAR(*) 

INTEGER NPAR 

DOUBLE PRECISION DISP(*) 

INTEGER NDISP 

LOGICAL IFLAG 

C 

C Outputs: 

C 

DOUBLE PRECISION DFDA(*) 

C 


C 

... 

... 

C 

C+----------------------------------------------------* 

C 

Executable Code 

C+----------------------------------------------------* 

C 

C 

IF (IFLAG) THEN 

C 

C+----------------------------------------------------* 

C 

Initialization pass: Initialize 

C 

necessary local variables 

C+----------------------------------------------------* 

C 

... 

...C 

ELSE 

C 

C+----------------------------------------------------* 

C 

Evaluation pass: Define the partial 

C 

derivatives of the coupler constraint 

C+----------------------------------------------------* 

C 

... 

... 

DFDA(1) = ... 

145

146 


C 

C 

C 

ENDIF 

DFDA(2) = ... 

... 

RETURN 

END 

COUXX2 

SUBROUTINE COUXX2 (ID, TIME, PAR, NPAR, DISP, 

& NDISP, IFLAG, DFDA2) 

C 

C+----------------------------------------------------* 

C 

C Inputs: 

C 

INTEGER ID 



INTEGER NPAR 


INTEGER NDISP 

LOGICAL IFLAG 

C 

C Outputs: 

C 

DOUBLE PRECISION DFDA2(NDISP) 

C 


C 

... 

... 

C 

C+----------------------------------------------------* 

C 


C+----------------------------------------------------* 

C 

C 


C 

C+----------------------------------------------------* 

C 

Initialization pass: Initialize 

C 

necessary local variables 

C+----------------------------------------------------* 

C 

... 

... 

C 

ELSE 

C


C+----------------------------------------------------* 

C 

Evaluation pass: Define the second partial 

C 

derivatives of the coupler constraint 

C+----------------------------------------------------* 

C 

... 

... 

DFDA2(1) = ... 

DFDA2(2) = ... 

... 

... 

C 

ENDIF 

C 

C 

RETURN 

END 


typedef void adams_c_COUSUB(const struct sAdamsCoupler* coupler, 

double TIME, double*, int IFLAG, double* PHI); 

typedef void adams_c_COUXX(const struct sAdamsCoupler* coupler, 

double TIME, double*, int IFLAG, double* dFda); 

typedef void adams_c_COUXX2(const struct sAdamsCoupler* coupler, 

double TIME, double*, int IFLAG, double* d2Fda2); 

/* 

* COUPLER ------------------------------------------------- 

---------------- 

*/ 

struct sAdamsCoupler 

{ 

int ID; 

int NPAR; 


int NJOINT; 

int JOINTS[3]; 

char TYPE[3]; 

}; 

Examples 

The mechanical system shown in Figure 1 consists of three rigid bodies and two joints; the first is a 

revolute joint and the second translational. The translational joint represents an actuator whose output 

displacement controls the angular motion in the revolute joint. 

Let the displacement in the translational joint be defined as and the rotation in revolute joint as a. 

147

148 


Now assume that the variables s and a are related by the following equation: 

s = 10 * Cos (a) 

The dataset for this model is: 

!Part/1, GroundMarker/11Marker/12Part/2, Mass=10, Ip=10,10,10, Cm=21Marker/21, Qp=0,-5,0, 

REU=90d,90d,0Marker/22, REU=90d,0,0Part/3, Mass=25, Ip=75,75,150, Cm=31Marker/31, 

Qp=10,20,0, REU=90d,90d,0Marker/32Joint/1, Revolute, I=22, J=11Joint/2, Translational, I=32, 

J=12Motion/1, Joint=2, Function = 10*TimeCoupler/1, Joints=1,2, Function=User(10)End 

Subroutines COUSUB, COUXX, and COUXX2 for this model are: 

COUSUB 

SUBROUTINE COUSUB (ID, TIME, PAR, NPAR, DISP, 

& NDISP, IFLAG, PHI) 

C 

C+----------------------------------------------------* 

C 

C Inputs: 

C 

INTEGER ID 



INTEGER NPAR 


INTEGER NDISP 

LOGICAL IFLAG 

C 

C Outputs: 

C 

DOUBLE PRECISION PHI 

C 


C 

DOUBLE PRECISION LENGTH, S, ALPHA 

C 

C+----------------------------------------------------* 

C 


C+----------------------------------------------------* 

C 


C 

C 

there are no variables to initialize in this 

C 

example 

C 

ELSE 

C


C+----------------------------------------------------* 

C 

Evaluation pass: Define Phi the coupler 

C 

constraint 

C+----------------------------------------------------* 

C 

LENGTH = PAR(1) 

ALPHA = DISP(1) 

S = DISP(2) 

PHI = S - LENGTH * COS(ALPHA) 

C 

ENDIF 

C 

RETURN 

END 

COUXX 

SUBROUTINE COUXX (ID, TIME, PAR, NPAR, DISP, 

& NDISP, IFLAG, DFDA) 

C 

C+----------------------------------------------------* 

C 

C Inputs: 

C 

INTEGER ID 



INTEGER NPAR 


INTEGER NDISP 

LOGICAL IFLAG 

C 

C Outputs: 

C 

DOUBLE PRECISION DFDA(*) 

C 


C 

DOUBLE PRECISION LENGTH, S, ALPHA 

C 

C+----------------------------------------------------* 

C 


C+----------------------------------------------------*C 


C 

C 

there are no variables to initialize in this example 

C 

ELSE 

C 

C+----------------------------------------------------* 

149

150 


C 

Evaluation pass: Define the partial derivatives 

C 

of the coupler constraint 

C+----------------------------------------------------* 

C 



S = DISP(2) 

C 

DFDA(1) = + LENGTH * SIN(ALPHA) 

DFDA(2) = 1.0 

C 

ENDIF 

C 

RETURN 

END 

COUXX2 

SUBROUTINE COUXX2 (ID, TIME, PAR, NPAR, DISP, 

& NDISP, IFLAG, DFDA2) 

C 

C+----------------------------------------------------* 

C Inputs: 

C 

INTEGER ID 



INTEGER NPAR 


INTEGER NDISP 

LOGICAL IFLAG 

C 

C Outputs: 

C 

DOUBLE PRECISION DFDA2(NDISP) 

C 


C 

DOUBLE PRECISION LENGTH, ALPHA, S 

C 

C+----------------------------------------------------* 

C 


C+----------------------------------------------------* 

C 


C 

C 

no variables to initialize in this example. 

C 

ELSE


C 

C+----------------------------------------------------* 

C 

Evaluation pass: Define the second partial 

C derivatives of the coupler constraint 

C+----------------------------------------------------* 

C 



S = DISP(2) 

DFDA2(1) = LENGTH * COS(ALPHA) 

DFDA2(2) = 0.0 

C 

ENDIF 

C 

RETURN 

END 

CURSUB 

CURSUB is an evaluation subroutine that computes curve coordinates and their derivatives for a 

CURVE statement (C++ or FORTRAN). CURSUB is optional. You can use it to define a curve instead 

of using control points or data points. 

Use 

Corresponding Statement 


SUBROUTINE CURSUB (id, par, npar, alpha, iord, iflag, values) 

151

152 



alpha A double-precision variable that specifies the value of the independent 

parameter a which CURSUB uses to evaluate a curve. Adams/Solver 

restricts a to be: 

Greater than or equal to the MINPAR value on the CURVE statement (-1.0 

by default). 

Less than or equal to the MAXPAR value on the CURVE statement (1.0 by 

default). 

id An integer variable that provides the identifier of the CURVE statement, 

which requests information from the CURSUB. Adams/Solver 

automatically derives additional information (such as the par argument) 

from the identifier of the corresponding statement. 

iflag A logical variable that Adams/Solver sets to TRUE. for the initial call to 

CURSUB. In general, you do not need to check this flag in the subroutine. 

However, you can check it if computations occur that require evalution at the 

beginning of the simulation. In this case, if iflag is true, then the subroutine 

should evaluate the computations. 

iord An integer variable that specifies the order of the derivative that CURSUB 

returns. The possible values are: 

zero (return curve coordinates) 

one (return first derivatives with respect to a) 

two (return second derivatives with respect to a). 


USER parenthetical list. The primary purpose of npar is to provide the 

CURSUB evaluation subroutine with the number of values stored in the par 

array. 

par A double-precision array of constants that is taken in order from the USER 

parenthetical list of the CURVE statement.



values A double-precision array of size three that returns the x, y, and z 

coordinates of the curve or their first or second derivatives with respect to 

a. The values the CURSUB should compute and return depend on the 

input value of argument iord, as summarized next: 


The CURVE statement lets you define a uniform B-Spline curve using control points or a tensioned B- 

Spline curve that is fitted to data points. If you cannot represent the curve you want using a uniform or 

tensioned B-Spline, you can use the FUNCTION=USER ( ) argument in the CURVE statement and write 

a CURSUB evaluation subroutine to calculate the curve coordinates and derivatives. 


iord: 

values (1): 

values (2): 

values (3): 

0 

1 

2 

Caution: Define the curve only as a function of a. Don't make calls to the SYSARY and SYSFNC 

utility subroutines to access other system variables. 

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

SUBROUTINE CURSUB ( ID, PAR, NPAR, ALPHA, IORD, 

& IFLAG, VALUES ) 

C 


C 



C 


153

154 


C 

INTEGER ID 


INTEGER NPAR 

DOUBLE PRECISION ALPHA 

INTEGER IORD 

LOGICAL IFLAG 

DOUBLE PRECISION VALUES( 3 ) 

C 

C ID Identifier of calling CURVE statement 



C ALPHA Curve parameter value 

C IORD Derivative order of value to be returned 


C VALUES Derivative values of CURVE returned to ADAMS 

C 

C - Local variable and parameter definitions ---- 

C 

... 

C 


C 

C Assign parameters to readable variable names 

C...CIF ( IFLAG ) THEN 

C 

C - Subroutine initialization ----------- 

C 

... 

C 

ENDIF 

C 

C - Compute and assign the curve coordinates ---- 

C 

IF ( IORD .EQ. 0 ) THEN 

C 

C Your algorithm 

C 

... 

C 

C Assign values for the X, Y, and Z coordinates 

C 

VALUES(1) = ... 

VALUES(2) = ... 

VALUES(3) = ... 

C 

C - Compute and assign the curve first derivatives - 

C 

ELSE IF ( IORD .EQ. 1 ) THEN 

C 


C 

... 

C


C Assign values for the X, Y, and Z first derivatives 

C 

VALUES(1) = ... 

VALUES(2) = ... 

VALUES(3) = ... 

C 

C - Compute and assign the curve second derivatives - 

C 

ELSE 

C 


C 

... 

C 

C Assign values for the X, Y, and Z second derivatives 

C 

VALUES(1) = ... 

VALUES(2) = ... 

VALUES(3) = ... 

C 

ENDIF 

C 

RETURN 

END 


typedef void adams_c_CURSUB(const struct sAdamsCurve* crv, double 

ALPHA, int IORD, int IFLAG, double* VALUES ); 

/* 

* CURVE 

*/ 

struct sAdamsCurve 

{ 

int ID; 

int NPAR; 


int CLOSED; 

int ORDER; 

double MINPAR; 

double MAXPAR; 

}; 

Examples 

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

DIFSUB 

155

156 


The DIFSUB evaluation subroutine computes a differential-equation value for a DIFF statement (C++ or 

FORTRAN). DIFSUB is optional. You only need it if you don't want to use a function expression in the 

DIFF statement. 

Use 



SUBROUTINE DIFSUB (id, time, par, npar, dflag, iflag, value)



dflag A logical variable that Adams/Solver sets to true when it calls DIFSUB to 

evaluate partial derivatives of the function. Otherwise, Adams/Solver sets 

dflag to false. 

id An integer variable that provides the identifier of the DIFF statement 

requesting information from the DIFSUB. From the identifier, 

Adams/Solver automatically knows other information (such as the par 

argument) available in the corresponding statement. 

iflag A logical variable that Adams/Solver sets to true 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 false, Adams/Solver computes the value of the userwritten 

variable. 



DIFSUB evaluation subroutine 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 DIFF statement. 

time A double-precision variable through which Adams/Solver conveys the 

current simulation time. 


value A double-precision variable that returns the value of the differential 

equation. If the equation is in the explicit form, value contains the 

derivative. If the equation is in the implicit form, value contains the residual 

(that is, the error relative to zero) of the implicit equation. In this case, value 

can be a function of the dependent variable and its time derivative. 


A DIFF statement with a function expression is sufficient for defining most user-defined differential 

equations. However, if the expression becomes lengthy and awkward or if the definition of the equation 

requires additional features of FORTRAN-77, you should use the FUNCTION=USER() argument in the 

DIFF statement, and write a DIFSUB evaluation subroutine to define the differential equation. 

DIFSUB allows you to define a differential equation for a variable either explicitly or implicitly: 

• In an explicit definition, the derivative of the variable is evaluated on the right side of a 

FORTRAN-77 assignment statement. 

157

158 


• In an implicit definition, the right side of the statement is zero. 

For further information on implicit and explicit definitions, see the DIFF statement (C++ or FORTRAN). 

You can call utility subroutines, such as AKISPL, CUBSPL, SYSARY, and SYSFNC, from DIFSUB to 

obtain information about system variables, other user-defined variables, and splines. 

The SYSARY and SYSFNC utility subroutines automatically set functional dependencies when the 

DIFSUB argument iflag is true. In order for Adams/Solver to compute solutions efficiently, it must know 

on which other variables each user-defined variable directly depends. Adams/Solver determines these 

functional dependencies at the beginning of the simulation by calling a DIFSUB evaluation subroutine 

with argument iflag set to true. Adams/Solver does this once for each DIFF statement with a 

FUNCTION=USER() argument. During each call to the DIFSUB evaluation subroutine, Adams/Solver 

records which calls you make to SYSARY and SYSFNC. Adams/Solver assumes that the user-defined 

variable depends on those system and user-defined variables, and no others. 

Tip: • If the SYSARY or SYSFNC utility subroutine is called to access angular 

displacements, the values returned by DIFSUB may contain discontinuities. These 

discontinuities occur if there is a 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. 


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

C 

• 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 iflag argument at all. You can just call SYSARY and/or SYSFNC, compute the 

user-defined variable value, and return to Adams/Solver. 

Caution: • When the iflag argument is true, be sure to make all the same calls to the SYSARY 

and SYSFNC utility subroutines that are done when actually computing the value 

of the user-defined variable. This ensures that Adams/Solver has the proper 

functional dependencies. In general, failure to account for dependencies of the 

user-defined variables might make it difficult for Adams/Solver to converge to a 

solution, and/or might force Adams/Solver to take small integration steps, 

potentially causing large increases in execution time. 

• When the iflag argument is true, SYSARY and SYSFNC return zero values for 

system and user-defined variables. Computations that divide by these values result 

in system errors when Adams/Solver is executed. Be sure to check for nonzero 

values, or the iflag argument set to false, before dividing by these values. 

SUBROUTINE DIFSUB ( ID, TIME, PAR, NPAR, DFLAG, 

& IFLAG, VALUE )


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

C 



C 


C 

INTEGER ID 



INTEGER NPAR 

LOGICAL DFLAG 

LOGICAL IFLAG 


C 

C ID Identifier of calling DIFF statement 






C VALUE Computed value of DIFF returned to ADAMS 

C 

C - Local variables and parameters definitions --- 

C 

... 

C 

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

C 


C 

... 

C 



C true, these calls are actually setting 

C functional dependencies. 

C CALL SYSFNC ( ... ) 

C 


C 

CALL ERRMES ( ... ) 

C 


C 

... 

C 

IF ( IFLAG ) THEN 

C 


C 

... 

C 

ENDIF 

159

160 


C 

C - Evaluate differential equation --------- 

C 


C 

... 

C 

C Assign a value to the variable VALUE 

C 

VALUE = ... 

C 

RETURN 

END 


typedef void adams_c_DIFSUB(const struct sAdamsDiff* diff, double 

TIME, int DFLAG, int IFLAG, double* RESULT); 

struct sAdamsDiff 

{ 

int ID; 

int NPAR; 


int STATIC_HOLD; 

int IMPLICIT; 

double IC_R1; 

double IC_R2; 

}; 

Examples 

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

DMPSUB 

The DMPSUB evaluation subroutine computes the modal damping ratios for a FLEX_BODY statement 

(C++ or FORTRAN). DMPSUB is optional. You need it only if you want custom damping that is not the 

same for all modes, or if the modal damping changes with time. 

Use 



SUBROUTINE DMPSUB (id, time, par, npar, freq, nmode, h, cratios)



id An integer variable that provides the identifier of the FLEX_BODY 

statement requesting information from the DMPSUB. From the identifier, 



time A double-precision variable containing the current simulation time. 

par A double-precision array of constants taken, in order, from the USER 

parenthetical list of the FLEX_BODY statement. 



DMPSUB evaluation subroutine with the number of values stored in the par 

array. 

freq An array of natural frequencies for the modes in cycles per user-defined time. 

nmode The total number of modes associated with the FLEX_BODY statement. 

h The current integrator step size. This is useful if you are using damping to 

prevent integration problems. 


cratios An array of damping ratios as a fraction of critical damping. There must be 

one value computed for each of the modes. 

Examples 

To control the modal damping of individual modes using a user-written subroutine, use CRATIO=USER 

according to Adams standard practice. The damping ratios for the selected modes are obtained through 

a call to the DMPSUB subroutine. For a model using units of seconds for time, this example illustrates: 

• 1% critical damping for modes less than 100 Hz. 

• 10% critical damping for modes greater or equal to 100 Hz but less than 1 kHz. 

• 100% critical damping for modes greater than or equal to 1 kHz. 

The following statement defines the constants Adams/Solver is to pass to the DMPSUB evaluation 

subroutine: 

FLEX_BODY/1, I=101, J=201 

, CRATIO=USER(.01,100,.1,1000,1) 

For the current example of this subroutine, see dmpsub.f. 

161

162 



typedef void adams_c_DMPSUB(const struct sAdamsCratio* flex, double 

TIME, const double* FREQS, int NMODE, double STEPSIZE, double* 

CRATIOS); 

/* 

* FLEX_BODY ------------------------------------------------- 

---------------- 

*/ 

struct sAdamsFlexBody 

{ 

int ID; 

/* int NMAT; 

const int* MATRICES; 

int VM; 

int WM; */ 

}; 

struct sAdamsCratio 

{ 

struct sAdamsFlexBody FlexBody; 

int NPAR; 


}; 

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. 

Use 



SUBROUTINE FIESUB (id, time, par, npar, disp, velo,& dflag, iflag, field, dfddis, dfdvel)



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. 




parenthetical list of the FIELD statement. 


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 A logical variable that Adams/Solver sets to true for the initial call to 

FIESUB. In general, this flag does not need to be checked in the subroutine. 

If there are computations that need to be evaluated at the beginning of the 

simulation, you can check the iflag argument. In this case, if the iflag 

argument is true, the subroutine should evaluate the computations. 

163

164 



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. 


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 ¹ 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 true, 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 false, before dividing by disp or velo values. 

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 


C 

INTEGER ID 



INTEGER NPAR 

DOUBLE PRECISION DISP( 6 ) 

DOUBLE PRECISION VELO( 6 ) 

LOGICAL DFLAG 

165

166 


LOGICAL IFLAG 

DOUBLE PRECISION FIELD( 6 ) 

DOUBLE PRECISION DFDDIS( 6, 6 ) 

DOUBLE PRECISION DFDVEL( 6, 6 ) 

C 

C ID Identifier of calling FIELD statement 




C DISP Array of I with respect to J displacements 

C VELO Array of I with respect to J velocities 



C FIELD Array of field values 

C DFDDIS Displacement partial derivatives 

C DFDVEL Velocity partial derivatives 

C 


C 

... 

C 


C 


C 

... 

C 


C 


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) = ... 

... 


167

168 


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 


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; 


int I; 

int J; 

Examples 

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

GFOSUB 


The GFOSUB evaluation subroutine computes a set of six force values applied by a GFORCE statement 

(C++ or FORTRAN). You can use a GFOSUB when the functions are too cumbersome or complex to 

enter as expressions in a GFORCE statement. 

Use 



SUBROUTINE GFOSUB(id, time, par, npar, dflag, iflag, result) 

169

170 



id An integer variable that provides the identifier of the GFORCE statement 

requesting information from GFOSUB. From the identifier, 

Adams/Solver automatically recognizes other information (such as the 

par argument) that is available in the corresponding statement. 



parenthetical list of the GFORCE statement. 

npar An integer variable that indicates the number of constants you specify in 

the USER parenthetical list. This variable provides the GFOSUB 

evaluation subroutine with the number of values stored in the par array. 

dflag A logical variable that Adams/Solver sets to true when it calls GFOSUB 

to evaluate the partial derivatives of the specified functions. Otherwise, 



functional dependency information from GFOSUB. Functional 

dependencies are established with the same calls to SYSARY, and 

SYSFNC that are later used to compute the values of the GFORCE 

components. If the iflag argument is false, the values of the user-defined 



result A double-precision array that returns the six values of the GFORCE 

components. 


The GFORCE statement with a function expression is usually adequate for defining functions that 

represent the three translational and three rotational vector components of a force at a point. However, if 

the force and torque expressions become lengthy and awkward, you can use a GFOSUB. 

You can call utility subroutines, such as AKISPL, CUBSPL, SYSARY, and SYSFNC, from GFOSUB, 

to obtain information about system variables, user-defined variables, and splines. 

The SYSARY and SYSFNC utility subroutines set up functional dependencies when the GFOSUB 

argument iflag is true. In order for Adams/Solver to compute solutions efficiently, it must know the 

Solver states on which the GFORCES depend. Adams/Solver determines these functional dependencies 

at the beginning of the simulation by calling GFOSUB with the argument iflag set to true. Adams/Solver 

does this once for each GFORCE statement with a FUNCTION=USER() argument. During each call to 

GFOSUB, Adams/Solver records the calls you make to SYSARY and SYSFNC. Adams/Solver assumes 

that the GFORCE components depend on those Adams/Solver states that are accessed through SYSARY 

and SYSFNC.

Using the DFLAG Variable 


The use of the DFLAG variable with a GFOSUB is optional. It merely identifies that GFOSUB is being 

called to evaluate a partial derivative. One of the states on which the GFOSUB depends has been 

perturbed very slightly. In many situations, it is likely that major calculations in the GFOSUB are 

insensitive to small changes in state, and therefore, need not be recalculated. 

In such situations, you can structure the GFOSUB not to redo these calculations. For example, assume 

you are using a GFOSUB to model tire and terrain interactions. The terrain is modeled as a set of 

triangular patches, and the tire forces as a GFOSUB. A labor-intensive calculation in the problem is to 

identify the patch that is in contact with the tire. Because pertubations of system states are always small 

when DFLAG is true, it is not necessary to recalculate the patch that is in contact with the tire. 

Caution: • Euler angles calculated by SYSARY or SYSFNC subroutines may be 

discontinuous. To avoid discontinuity, use the RCNVRT utility subroutine to 

convert the rotational angles from Euler angles to some other rotational scheme 

that does not encounter discontinuity. 


• When the iflag argument is true, you must make all the calls to SYSARY and 

SYSFNC as are made to compute the component values of the GFORCE 

statement. This ensures that Adams/Solver has the proper functional dependencies. 

In general, failure to account for dependencies in the GFORCE components can 

make it difficult for Adams/Solver to converge to a solution and/or can force 

Adams/Solver to take small integration steps. It may increase simulation time 

dramatically. 


system and user-defined variables. Computations that divide by these values will 

result in fatal errors. You should check for nonzero values, or ensure the iflag 

argument is set to false, before dividing by these values. 

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

& 

SUBROUTINE GFOSUB(ID, TIME, PAR, NPAR, DFLAG, 

IFLAG, RESULT) 

C 


C 

C Note: For a machine with 60 or more bits per word, 

C 

C 

substitute "REAL" for "DOUBLE PRECISION". 

C - External variable definitions ----------- 

C 

INTEGER ID 



INTEGER NPAR 

LOGICAL DFLAG 

171

172 


LOGICAL IFLAG 

DOUBLE PRECISION RESULT( 6 ) 

C 

C ID Identifier of calling GFORCE statement 





C IFLAG Initial pass flag 

C RESULT Array (dimension 6) of computed GFORCE 


C 

C - Local variable and parameter definitions ----- 

C 

... 

C 


C 


C 

... 

C 



C true, these calls are actually setting functional 

C dependencies. 

C 


C 


C 


C 


C 

... 

C 


C 


C 

... 

C 

ENDIF 

C 

C - Evaluate GFORCE components ------------- 

C 


C 

... 

C 


C 

RESULT(1) = ...

C 

RESULT(2) = ... 

RESULT(3) = ... 

RESULT(4) = ... 

RESULT(5) = ... 

RESULT(6) = ... 

RETURN 

END 



typedef void adams_c_GFOSUB(const struct sAdamsGforce* gfo, double 


/* 

* GFORCE 

*/ 

struct sAdamsGforce 

{ 

int ID; 

int NPAR; 


int I; 

int RM; 

int JFLOAT; 

}; 

Examples 

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

GSE_DERIV, GSE_UPDATE, GSE_OUTPUT, GSE_SAMP 

These four subroutines are used to completely define a GSE (C++ or FORTRAN). Recall that the 

constitutive equations for a GSE have the form: 

• GSE_DERIV defines the function fc(), shown in Equation 1 above. GSE_DERIV also returns 

the partial derivatives: 

• GSE_UPDATE defines the function fd(), shown in Equation 2 above. It defines the derivative of 

the states that the GSE introduces. GSE_UPDATE does not return any partial derivatives. 

• GSE_OUTPUT defines the function g(), shown in Equation 3 above. GSE_OUTPUT also 

returns the partial derivatives: 

• GSE_SAMP defines the sampling period associated with Equation 2. The sampling period is the 

time between two consecutive updates. It does not need to be a constant. 

173

174 


Use 


GSE_DERIV 


SUBROUTINE GSE_DERIV (ID, TIME, PAR, NPAR, DFLAG, IFLAG, NS, XDOT) 


id An integer variable containing the ID of the GSE statement requesting 


automatically recognizes other information (such as the PAR argument) 

that is associated with that GSE statement. 


par A double-precision array containing the constant parameters taken in 

order from the USER parenthetical list in the GSE statement. 

npar An integer variable containing the number of constants in the 

Function=USER(...) parenthetical list in the GSE statement. The primary 

purpose is to provide the subroutine with the number of entries in the par 

array. 

dflag A logical variable that is set to true when Adams/Solver calls the 

subroutine to obtain partial derivatives of the function fc(). 

iflag A logical variable that is set to true when Adams/Solver calls the 

subroutine during the code initialization pass. For other evaluation 

subroutines, the flag is used when Adams/Solver needs functional 

dependency information and normally controls calls to the SYSFNC and 

SYSARY utility subroutines. You can use the IFLAG argument to control 

any other initialization you might need to do in the GSE evaluation 

subroutine. 

ns An integer variable containing the number of continuous states in the 

GSE; taken from the NS argument to the GSE statement. 


xdot A double-precision array of dimension NS, containing the derivatives of 

the state Xc. 

Examples 

For an example of this subroutine, see gse_deriv.f

GSE_UPDATE 



SUBROUTINE GSE_UPDATE (ID, TIME, PAR, NPAR, DFLAG, IFLAG, ND, XDplus1) 



information from the GSE subroutine. From the identifier, 


PAR argument) that is associated with that GSE statement. 





Function=USER(...) parenthetical list in the GSE statement. The 

primary purpose is to provide the subroutine with the number of entries 

in the Par array. 


subroutine to obtain partial derivatives of the function fc(). 





SYSARY utility subroutines. Although you cannot call these routines 

from any of the GSE evaluation subroutines, you can use the IFLAG 

argument to control any other initialization you might need to do in the 

GSE evaluation subroutine. 

nd An integer variable containing the number of discrete states in the GSE; 

taken from the ND argument to the GSE statement. 


XdPlus1 A double-precision array of dimension ND, containing the value of the 

GSE discrete states at time T=Tn+1. 

Examples 

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

GSE_OUTPUT 

175

176 



SUBROUTINE GSE_OUTPUT (ID, TIME, PAR, NPAR, DFLAG, IFLAG, NO, Y) 




automatically recognizes other information (such as the par argument) that 

is associated with that GSE statement. 





Function=USER(...) parenthetical list in the GSE statement. The primary 

purpose is to provide the subroutine with the number of entries in the PAR 

array. 


subroutine to obtain partial derivatives of the function g(). 









no An integer variable containing the number of outputs in the GSE; taken 

from the NO argument to the GSE statement. 


Y A double-precision array of dimension NO, containing the value of the GSE 

at the current simulation time. 

Example 

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

GSE_SAMP 


SUBROUTINE GSE_SAMP (ID, TIME, PAR, NPAR, IFLAG,Sample_Step)



id An integer variable that gives the identifier of the GSE statement 

requesting information from the GSE subroutine. From the identifier, 


Par argument) that is associated with that GSE statement. 





Function=USER(...) parenthetical list in the GSE statement. 

The primary purpose is to provide the subroutine with the number of 

entries in the Par array. 










sample_step A double-precision scalar, containing the sample step (that is, the 

difference between the next sample time, and the current simulation). 

Example 

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


typedef void adams_c_GSESUB(const struct sAdamsGSE* gse, double TIME, 

int DFLAG, int IFLAG, int NSTATE, const double* STATES, int NINPUT, 

const double* INPUTS, int NPUTPUT, double* STATED, double* OUTPUT); 

typedef void adams_c_GSEXU(const struct sAdamsGSE* gse, double TIME, 

int IFLAG, int NSTATE, const double* STATES, int NINPUT, const 

double* INPUTS, int NOUTPUTS, double* DERIVS); 

typedef void adams_c_GSEXX(const struct sAdamsGSE* gse, double TIME, 



typedef void adams_c_GSEYU(const struct sAdamsGSE* gse, double TIME, 



177

178 


typedef void adams_c_GSEYX(const struct sAdamsGSE* gse, double TIME, 

int IFLAG, int NSTATE, const double* STATES, int NINPUT, const double* 

INPUTS, int NOUTPUTS, double* DERIVS); 

typedef void STDCALL adams_f77_GSESUB(const int* ID, const double* 

TIME, const double* PAR, const int* NPAR, const int* DFLAG, const int* 

IFLAG, const int* NSTATE, const double* STATES, const int* NINPUT, 

const double* INPUTS, const int* NOUTPUT, double* STATED, double* 

OUTPUT); 

typedef void adams_c_GSEDERIV(const struct sAdamsGSE* gse, double 

TIME, int DFLAG, int IFLAG, int, double*); 

typedef void adams_c_GSEOUTPUT(const struct sAdamsGSE* gse, double 


typedef void adams_c_GSEUPDATE(const struct sAdamsGSE* gse, double 


typedef void adams_c_GSESAMPLE(const struct sAdamsGSE* gse, double 

TIME, int IFLAG, double* OUTPUT); 

typedef void adams_c_GSESETNS(int NS, int* ERR); 

typedef void adams_c_GSESETND(int ND, int* ERR); 

typedef void adams_c_GSESETIMPLICIT(int FLAG, int* ERR); 

typedef void adams_c_GSESETSTATICHOLD(int FLAG, int* ERR); 

typedef void adams_c_GSESETSAMPLEOFFSET(int UNTNUM, double* LOGERR); 

/* 

* GSE 

*/ 

struct sAdamsGSE 

{ 

int ID; 

int NPAR; 


int NI; 

int NO; 

int U; 

int Y; 

int NS; 

int X; 

int IC; 

int STATIC_HOLD; 

int IMPLICIT; 

int ND; 

int XD; 

int ICD; 

double SAMPLE_OFFSET; 

}; 

MFOSUB 

MFOSUB is an evaluation subroutine that computes the modal force corresponding to an MFORCE 

statement (C++ or FORTRAN). MFOSUB is optional. You need it only if you don't want to use a function 

expression in the MFORCE statement, or if you need the added capabilities of the USER form of the 

MFORCE statement.

Use 



You invoke the MFOSUB by using either the FUNCTION or FORCE option in the MFORCE statement. 

The MFOSUB output arguments are interpreted differently depending on the form used. Adams/Solver 

(C++) can invoke the MFOSUB using either form. Adams/Solver (FORTRAN) can only invoke the 

MFOSUB using FUNCTION. 


SUBROUTINE MFOSUB (id, time, par, npar, dflag, iflag,$modloads, nmodes, ncases,$scale, case, 

loadvec) 

179

180 



id An integer variable that provides the identifier of the MFORCE statement 

that is requesting information from the MFOSUB. 




parenthetical list of the MFORCE statement. 


USER parenthetical list. The primary purpose of npar is to enable 

MFOSUB to correctly dimension the par array. 

dflag A logical variable that Adams/Solver sets to true when calling MFOSUB 


Adams/Solver sets dflag to false. 

iflag A logical variable that Adams/Solver sets to true when determining the 

functional dependency information from MFOSUB. You establish the 

functional dependencies with the same calls to SYSARY and SYSFNC 

that Adams/Solver later uses to compute the values of the MFORCE 

components (see SYSARY and SYSFNC). If the iflag argument is false, 

you must compute the value of the user-written MFORCE. 

modloads A double-precision array containing the values of the modal load cases that 

are defined for the FLEX_BODY and that the MFORCE is acting on. The 

modload array has the dimensions modload (6+nmodes, ncases). 

nmodes An integer variable that indicates the number of modes in the associated 

FLEX_BODY. The value of nmodes provides MFOSUB with a way to 

correctly dimension the modloads and loadvec arrays. 

ncases An integer variable that indicates the number of load cases available in the 

associated FLEX_BODY. The value of ncases provides MFOSUB with a 

means to correctly dimension the modloads array. If ncases=0, then the 

contents of modloads are undefined because no user-defined load cases are 

available for the FLEX_BODY.


scale A double-precision variable. 

If MFOSUB is called with the FUNCTION form: 


This output argument contains the scale factor that is to be applied to the 

modal load vector. The value of scale can depend on the values 

Adams/Solver calls from SYSFNC and SYSARY (see SYSARY and 

SYSFNC). 

If MFOSUB is called with the FORCE form: 

Adams/Solver ignores this output argument. 

case An integer, in the range 0 to ncases. 


This output argument denotes a user-defined modal load case that is 

multiplied by the scale output argument to produce the modal load on the 

FLEX_BODY. If case=0, then Adams/Solver looks for a modal load case in 

the loadvec array. 


This output argument must be set to zero and Adams/Solver extracts the 

modal load directly from the loadvec array. 

loadvec A double-precision array of dimension loadvec(6+nmodes) that MFOSUB 

generates itself or generates based on the load cases it receives from the 

modloads array. 


If the output variable case is zero, Adams/Solver computes the modal force 

by multiplying the output array loadvec by the output variable scale. The 

values of loadvec can be a function of time, but not a function of the model 

response. For example, they must not depend on values obtained by calling 

SYSFNC and SYSARY. If case>0, then Adams/Solver ignores the contents 

of loadvec. 


Adams/Solver applies the contents of the loadvec array directly to the 

FLEX_BODY without scaling it. Each component of loadvec can depend on 

time and model response. That is, you can use the values obtained from 

SYSFNC and SYSARY to compute entries in the loadvec array. 

181

182 


Examples 

A sample for MFOSUB is shown next. In this example, MFOSUB is invoked using the FUNCTION form 

and uses load case 3 and scales it with 10. 

C 

C 

C 

SUBROUTINE MFOSUB(ID, TIME, PAR, NPAR, DFLAG, IFLAG, 

$ MODLOADS, NMODES, NCASES, 

$ SCALE, CASE, LOADVEC) 

INTEGER ID, NPAR, NMODES, NCASES 

LOGICAL DFLAG 


LOGICAL IFLAG 

DOUBLE PRECISION TIME, PAR(NPAR), MODLOADS(6+NMODES, NCASES) 

INTEGER CASE 

DOUBLE PRECISION SCALE, LOADVEC(6+NMODES) 

CASE = 3 

SCALE = 10. 

ERRFLG = NCASES.LT.CASE 

CALL ERRMES(ERRFLG, 'Trying to use an invalid load case.', 

& ID, 'STOP' ) 

RETURN 

END 

In this next example, the MFOSUB is called with the FORCE form of the MFORCE statement. The 

MFOSUB applies a critical modal damping force to the FLEX_BODY identified by the first entry in the 

USER parenthetical list. Note that the user-written subroutine assumes the generalized mass matrix is the 

identity matrix. 

SUBROUTINE MFOSUB(ID, TIME, PAR, NPAR, DFLAG, IFLAG, MODLOADS, 

& NMODS, NCASES, SCALE, CASE, LOADVEC) 

C 

IMPLICIT NONE 

C 

C... ARGUMENTS: 

C 

INTEGER ID 

INTEGER NPAR 

INTEGER NMODS 

INTEGER NCASES 

LOGICAL DFLAG 

LOGICAL IFLAG 


DOUBLE PRECISION PAR(NPAR) 

DOUBLE PRECISION MODLOADS(6+NMODS, NCASES) 

C 

C... RETURNS 

C


INTEGER CASE 

DOUBLE PRECISION SCALE, LOADVEC(6+NMODS) 

C 

C... PARAMETERSC 

INTEGER MAXN 

PARAMETER (MAXN = 100 ) 

DOUBLE PRECISION ZERO 

PARAMETER (ZERO = 0.0D+00) 

DOUBLE PRECISION ONE 

PARAMETER (ONE = 1.0D+00) 

DOUBLE PRECISION TWO 

PARAMETER (TWO = 2.0D+00) 

DOUBLE PRECISION PI 

PARAMETER (PI = 3.141592653589793D+00) 

C 

C... LOCALSC 


INTEGER I, NQ, FBYID 

INTEGER MNUM(MAXN) 

DOUBLE PRECISION GSTF, GMAS 

DOUBLE PRECISION MFRQ(MAXN), QDOT(MAXN) 

C 

C===================== EXECUTABLE CODE 

============================== 

C FBYID = NINT(PAR(1)) 

C 

C... GET MODE NUMBERS AND FREQUENCIES FOR ALL ACTIVE MODES 

C 

CALL MODINF (FBYID, MNUM, MFRQ, ERRFLG) 

CALL ERRMES(ERRFLG, 'FAILED CALL TO MODINF', ID, 'STOP') 

C 

C... GET TIME DERIVATIVE OF MODAL COORDINDATES 

CALL SYSARY('QDOT', FBYID, 1, QDOT, NQ, ERRFLG) 

CALL ERRMES(ERRFLG, 'FAILED CALL TO SYSARY', ID, 'STOP') 

C 

C... CASE MUST BE SET TO ZEROC 

CASE = 0CC... BUILD MODAL LOAD AND RETURN IN LOADVEC ARRAY 

C 

DO I = 1, 6 

LOADVEC(I) = ZERO 

END DO 

C 

DO I = 1, NMODS 

GMAS = ONE 

GSTF = (TWO * PI * MFRQ(I)) ** 2 

183

184 


C 

LOADVEC(I+6) = -TWO * DSQRT(GSTF * GMAS) * QDOT(I) 

END DO 

RETURN 

END 


typedef void adams_c_MFOSUB(const struct sAdamsMforce* mforce, double 

TIME, int DFLAG, int IFLAG, const double* MODLOADS, int NMODES, int 

NCASES, double* SCALE, int* CASE, double* LOADVEC); 

/* 

* MFORCE 

*/ 

struct sAdamsMforce 

{ 

struct sAdamsFlexBody FlexBody; 

int ID; 

int NPAR; 


int JFLOAT; 

}; 

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. 

Use 



SUBROUTINE MOTSUB(id, time, par, npar, iord, iflag,value)



id An integer variable that provides the identifier of the MOTION statement 

requesting information from MOTSUB. From the identifier, 




MOTSUB. In general, you do not need to check this flag in the 

subroutine. If there are computations that need to be evaluated once at the 

beginning of the simulation, you can check the iflag argument. In this 

case, if the iflag argument is true, the subroutine should evaluate the 

computations. 

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. 


parenthetical list of the MOTION statement. 



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. 

185

186 



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 userdefined 

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. 

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 



C 


C 

INTEGER ID 



INTEGER NPAR


INTEGER IORD 

LOGICAL IFLAG 


C 

C ID Identifier of calling MOTION statement 






C VALUE Derivative value of MOTION returned to ADAMS 

C 

C - Local variable and parameter definitions ---- 

C 

... 

C 


C 


C 

... 

C 


C 


C 

... 

C 

ENDIF 

C 

C - Compute and assign the motion displacement --- 

C 


C 


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 

... 

C 

C Assign a value to VALUE for the motion velocity 

C 

VALUE = ... 

C 

187

188 


C - Compute and assign the motion acceleration --- 

C 

ELSE 

C 


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 


/* 

* MOTION 

*/ 

struct sAdamsMotion 

{ 

int ID; 

int NPAR; 


int JOINT; 

const char* Type; 

int I; 

int J; 

char Which[2]; 

const char* DVA; 

}; 

Examples 

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

RELSUB 

The RELSUB restart subroutine allows you to reload any information needed to restart user-written 

subroutines. Adams/Solver calls SAVSUB during a SAVE command to write user data. RELSUB can 

then read the data during a RELOAD command. 

SAVSUB and RELSUB are optional. You only need them if you want the SAVE and RELOAD 

commands to save and reload user data, in addition to internal Adams/Solver data.

Use 



SUBROUTINE RELSUB(iunit, errflg) 



Structure 


iunit An integer variable that contains the FORTRAN IO unit of the 

Adams/Solver save file. Adams/Solver opens the save file as sequential 

and unformatted. If SAVSUB has written data to the save file, the RELSUB 

may read it from this unit with an unformatted FORTRAN READ 

statement. 

errflg A logical variable that indicates to Adams/Solver that an error has occurred 

while reading user data. If you set errflg to true, Adams/Solver writes an 

error message to the screen and to the message file. 

Tip: The most straightforward way to reinitialize user-written subroutines may be to collect the 

necessary variables in a COMMON block, use SAVSUB to write them to the save file, and 

RELSUB to read them back from the save file. 

Caution: RELSUB must read data from the save file in the same order in which SAVSUB wrote the 

data. 

A sample structure for RELSUB is shown next. The comments describe how the subroutine works. 

SUBROUTINE RELSUB(IUNIT, ERRFLG) 

C 


C 


C 

INTEGER IUNIT 


C 

C IUNIT FORTRAN IO unit attached to Save File 

C ERRLFG used to signal problems back to ADAMS 

C 

189

190 


C --- COMMON Blocks ----------------------------------- 

C 

COMMON ... 

C 


C 

C Read in the information which appears in the COMMON 

C blocks, through which this routine shares information 

C with other user-written subroutines. 

C 

READ (IUNIT) ... 

C 

RETURN 

END 

Example 

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

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. 

Use 



SUBROUTINE REQSUB (id, time, par, npar, iflag, result)



id An integer variable that provides the identifier of the REQUEST 

statement requesting information from REQSUB. From the identifier, 




REQSUB. In general, you do not need to test this flag in the subroutine. 

But if there are computations that need to be evaluated once at the 

beginning of the simulation, you can test the iflag argument. In this case, 

if the iflag argument is true, the subroutine should evaluate the 

computations. 



REQSUB with the number of values stored in the par array. 


parenthetical list of the REQUEST statement. 




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. 

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, 

191

192 


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. 


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 


C 

INTEGER ID 



INTEGER NPAR 

LOGICAL IFLAG 

DOUBLE PRECISION RESULT( 8 ) 

C 

C ID Identifier of calling REQUEST statement 





C RESULT Array of values returned to ADAMS 

C 


C 

... 

C 


C 

C Assign parameter values to readable variable names 

C 

... 

C 

IF( IFLAG ) THEN 

C 


C 

...

C 

ENDIF 

C 

C - Create request information ----------- 

C 


C 

... 

C 

C Assign values to the result array 

C 

RESULT(1) = ... 

... 

RESULT(8) = ... 

C 

RETURN 

END 



typedef void adams_c_REQSUB(const struct sAdamsRequest* req, double 


/* 

* REQUEST ------------------------------------------------- 

---------------- 

*/ 

struct sAdamsRequest 

{ 

int ID; 

int NPAR; 


const char* COMMENT; 

const char* TITLE[8]; 

}; 

Examples 

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

SAVSUB 

The SAVSUB restart subroutine allows you to store any information needed to later restart user-written 

subroutines. Adams/Solver calls SAVSUB during a SAVE command to write user data. The RELSUB 

restart subroutine can then read the data during a RELOAD command. 

SAVSUB and RELSUB are optional. You only need them if you want to use the SAVE and RELOAD 

commands to save and reload user data, in addition to internal Adams/Solver data. 

193

194 


Use 



SUBROUTINE SAVSUB(iunit, errflg) 


iunit An integer variable that contains the FORTRAN IO unit of the 

Adams/Solver save file. Adams/Solver opens the save file as sequential and 

unformatted. You may store data in the save file by writing it to this unit 

with an unformatted FORTRAN WRITE statement. 


errflg A logical variable that indicates to Adams/Solver that an error has 

occurred while saving user data. If you set errflg to true, Adams/Solver 

writes an error message to the screen and to the message file. 

Tip: The most straightforward way to reinitialize user-written subroutines might be to collect 

the necessary variables in a COMMON block, use SAVSUB to write them to the save file, 

and RELSUB to read them back from the save file. 

Caution: RELSUB must read data from the save file in the same order in which SAVSUB wrote the 

data. 

Structure 

A sample structure for SAVSUB is shown next. The comments describe how the subroutine works. 

SUBROUTINE SAVSUB(IUNIT, ERRFLG) 

C 


C 


C 

INTEGER IUNIT 


C 

C IUNIT FORTRAN IO unit attached to Save File 

C ERRLFG used to signal problems back to ADAMS 

C


C --- COMMON Blocks ----------------------------------- 

C 

COMMON... 

C 


C 

C Write out the information which appears in the COMMON 

C blocks, through which this routine shares information 

C with other user-written subroutines. 

C 

WRITE (IUNIT) ... 

C 

RETURN 

END 

Example 

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

SENSUB 

The SENSUB evaluation subroutine computes the values sensed by a SENSOR statement (C++ or 

FORTRAN). SENSUB is optional. You only need it if you do not want to use a function expression in 

the SENSOR statement. 

Use 



SUBROUTINE SENSUB (id, time, par, npar, iflag, value) 

195

196 



id An integer variable that contains the ID of the SENSOR statement that 

requests information from SENSUB. From the identifier, Adams/Solver 




current simulation time to SENSUB. 


parenthetical list of the SENSOR statement. 



SENSUB with the number of values stored in the par array. 


SENSUB. If there are computations that need to be evaluated once at the 

beginning of the simulation, you can check the iflag argument. In this case, if 

the iflag argument is true, the subroutine should evaluate the computations. 


value A double-precision variable that contains the value of the function that 

SENSUB evaluates. 


The SENSOR statement with a function expression is usually adequate for most sensing requirements. 

However, if the expression becomes lengthy and awkward, you should use the FUNCTION=USER() 

argument in the SENSOR statement, and write a SENSUB to define the function you want to sense. 

To access information on which the function depends, you can use the utility subroutines such as 

AKISPL, CUBSPL, SYSARY, and SYSFNC in SENSUB. 

Tip: If the SYSARY or SYSFNC utility subroutines are called to access angular displacements, 



other rotational representation that does not encounter a singularity. 


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

SUBROUTINE SENSUB ( ID, TIME, PAR, NPAR, IFLAG, 

& VALUE ) 

C 

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


C 


C 

INTEGER ID 



INTEGER NPAR 

LOGICAL IFLAG 


C 

C ID Identifier of calling SENSOR statement 





C VALUE The returned value of the sensor 

C 


C 

... 

C 


C 

C Assign parameter values to readable variables 

C 

... 

C 


C 


C 

... 

C 

ENDIFCC - Evaluate sensor ---------------- 

C 


C 

... 

C 

C Assign the returned value 

C 

VALUE = ... 

C 

RETURN 

END 

C Style - prototype 

typedef void adams_c_SENSUB(const struct sAdamsSensor* sensor, double 


/* 

* SENSOR ------------------------------------------------- 

---------------- 

197

198 


struct sAdamsSensorEval 

{ 

int NPAR; 


}; 

*/ 

struct sAdamsSensor 

{ 

int ID; 

int NPAR; 


double VALUE; 

double Error; 

char Logic[2]; 

/* struct sAdamsSensorEval Eval; */ 

}; 

Examples 

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

SEVSUB 

The SEVSUB evaluation subroutine computes a scalar value that a SENSOR statement (C++ or 

FORTRAN) stores and is available through the SENVAL function expression. SEVSUB is evaluated 

only when the event defined by the SENSOR occurs. SEVSUB is optional. You only need it if you do 

not want to use a function expression in the EVALUATE argument of the SENSOR statement. 

Use 



SUBROUTINE SEVSUB (id, time, par, npar, iflag, result)



id An integer variable that contains the ID of the SENSOR statement that 

requests information from SEVSUB. From the identifier, Adams/Solver 

automatically knows other information (such as the par argument) 



current simulation time to SEVSUB. 


parenthetical list of the SENSOR statement. 



SEVSUB with the number of values stored in the par array. 


SEVSUB. If there are computations that need to be evaluated once at the 

beginning of the simulation, you can check the iflag argument. In this case, 

if the iflag argument is true, the subroutine should evaluate the 

computations. 


result A double-precision variable that returns the value of the EVALUATE 

function for the SENSOR. 


Defining the EVALUATE argument of SENSOR with a function expression is usually sufficient for must 

users. If the expression becomes lengthy and awkward, however, you can use SEVSUB. If the algorithms 

for computing the EVALUATE function use or consist of existing subroutines, SEVSUB can be made to 

call them. 

SEVSUB is only called by Adams/Solver when the event defined by the SENSOR occurs. Adams/Solver 

evaluates whether a SENSOR event has occurred only when it has determined the state of the system for 

the current time step. 

Once the EVALUATE function has been evaluated, Adams/Solver stores the result until the SENSOR 

event reoccurs. The most recent value of the EVALUATE function is available through the SENVAL 

function expression. 


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

SUBROUTINE SEVSUB ( ID, TIME, PAR, NPAR, IFLAG, 

& RESULT ) 

199

200 


C 


C 

C 


C 

INTEGER ID 



INTEGER NPAR 

LOGICAL IFLAG 

DOUBLE PRECISION RESULT 

C 

C ID Identifier of calling SENSOR statement 





C RESULT Scalar value returned to ADAMS 

C 

C --- Local variable definitions ---------------------- 

C 

... 

C 


C 

C --- Assign parameter values to readable variable names 

C 

... 

C IF( IFLAG ) THEN 

C 

C --- Subroutine initialization ----------- 

C 

... 

C 

ENDIF 

C 

C --- Compute the result 

C 


C 

... 

C 

C --- Assign the return value 

C 

RESULT = ... 

C 

RETURN 

END 


typedef void adams_c_SEVSUB(const struct sAdamsSensor* sensor, double 

TIME, int IFLAG, double* OUTPUT);

* 

* SENSOR 

struct sAdamsSensorEval 

{ 

int NPAR; 


}; 

*/ 

struct sAdamsSensor 

{ 

int ID; 

int NPAR; 


double VALUE; 

double Error; 

char Logic[2]; 

/* struct sAdamsSensorEval Eval; */ 

}; 

Examples 

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

SFOSUB 


The SFOSUB evaluation subroutine computes the force magnitude for an SFORCE statement. SFOSUB 

is optional. You only need it if you don't want to use a function expression in the SFORCE statement 

(C++ or FORTRAN). 

Use 



SUBROUTINE SFOSUB (id, time, par, npar, dflag, iflag, value) 

201

202 



id An integer variable that contains the ID of the SFORCE statement that 

requests information from SFOSUB. From the identifier, Adams/Solver 

automatically knows other information (such as the par argument) 





parenthetical list of the SFORCE statement. 

dflag A logical variable that Adams/Solver sets to true when it calls SFOSUB 

to evaluate partial derivatives of the function. Otherwise, Adams/Solver 

sets dflag to false. See Using the DFLAG Variable. 


USER parenthetical list. The primary purpose of npar is to provide 

SFOSUB with the number of values stored in the par array. 


functional dependency of the user-defined SFORCE. Set functional 

dependencies by making the same calls to SYSARY and SYSFNC that 

you make to compute the value of the user-defined SFORCE (see 

SYSARY and SYSFNC). If the iflag argument is false, compute the value 

of the user-written SFORCE. 


value A double-precision variable that contains the force value that SFOSUB 

computes. 


The SFORCE statement (C++ or FORTRAN) with a function expression is usually adequate for defining 

most single-component forces. If the expression becomes lengthy and awkward, however, you should use 

the FUNCTION=USER() argument in the SFORCE statement, and write an SFOSUB to calculate the 

single-component force. 

You can call utility subroutines, such as SYSARY, SYSFNC, AKISPL, and CUBSPL, from SFOSUB to 

obtain information about system variables, user-defined variables, and splines. 


SFOSUB argument iflag is true. For Adams/Solver to compute solutions efficiently, it must know 

on which other variables each user-defined SFORCE directly depends. Adams/Solver determines these 

functional dependencies at the beginning of the simulation by calling SFOSUB evaluation subroutine 

with argument iflag set to true. Adams/Solver does this once for each SFORCE statement with a 

FUNCTION=USER() argument. During each call to SFOSUB, Adams/Solver records which calls you


make to SYSARY and SYSFNC. Adams/Solver assumes the SFORCE depends on those system 

variables, and no others. 


the values they return may contain discontinuities. To avoid the discontinuities, use the 



Caution: • Force attributes (such as translational, rotational, action-reaction, and action-only) 

influence the definition of positive and of negative forces. Review attribute 

influences in the SFORCE statement (C++ or FORTRAN). 


• The function you choose to define a force must be both continuous and 

differentiable. Forces with discontinuous derivatives cause a reduction of the 

integration step size at the discontinuity. As a result, simulation time may 

drastically increase and Adams/Solver may fail to converge to a solution. 

• When the iflag argument is true, be sure to make all the same calls to SYSARY 

and SYSFNC that are made when actually computing the value of the user-defined 

SFORCE. This ensures that Adams/Solver has the proper functional dependencies. 

In general, failure to account for dependencies of the user-defined SFORCE might 

make it difficult for Adams/Solver to converge to a solution and/or might force 

Adams/Solver to take small integration steps. Both of these usually cause large 

increases in execution time. 


system and user-defined variables. Computations that divide by these values result 

in system errors when Adams/Solver is executed. Be sure to check for nonzero 

values, or the iflag argument set to false, before dividing by these values. 

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

SUBROUTINE SFOSUB ( ID, TIME, PAR, NPAR, DFLAG, 


C 


C 



C 


C 

INTEGER ID 



INTEGER NPAR 

LOGICAL DFLAG 

203

204 


LOGICAL IFLAG 


C 

C ID Identifier of calling SFORCE statement 






C VALUE The SFORCE value returned to ADAMS 

C 


C 

... 

C 


C 


C 

... 

C 


C calculations below. Note: if IFLAG is true, these 

C calls are actually setting functional dependencies. 

C 

CALL SYSFNC ( ... ) 

C 


C 

C Repeat for all required SYSFN 

C or SYSARY calls 

C 

... 

C 


C 


C 

... 

C 

ENDIF 

C 

C - Evaluate force ----------------- 

C 


C 

... 

C 


C 

VALUE = ... 

C 

RETURN 

END



typedef void adams_c_SFOSUB(const struct sAdamsSforce* sforce, double 


/* 

* SFORCE 

*/ 

struct sAdamsSforce 

{ 

int ID; 

int NPAR; 


int I; 

int J; 

int ACTION_ONLY; 

const char* Type; 

}; 

Examples 

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

SPLINE_READ 

SPLINE_READ reads x, y, [and z] data from a file to a SPLINE statement. The SPLINE_READ 

subroutine is optional. You use it only if you do not want to use the X and Y arguments in the SPLINE 

statement (C++ or FORTRAN). 

Use 


SPLINE/id 

, X=x1, x2, x3, x4 [, . . . , xn] 

, Y=y1, y2, y3, y4 [, . . . , yn] 

[,LINEAR_EXTRAPOLATE] 

or 

SPLINE/id 

, X=x1, x2, x3, x4 [, . . . , xn] 

, Y=z1, y11, y12, y13, y14 [, . . . ,y1n] 

, Y=z2, y21, y22, y23, y24 [, . . . ,y2n] 

, Y=z3, y31, y32, y33, , LINEAR_EXTRAPOLATE y34 [, . . . ,y3n] 

, Y=z4, y41, y42, y43, y44 [, . . . ,y4n] 

[, . . . , Y=zm, ym1, ym2, ym3, ym4,[, . . . ,ymn]] 

[, LINEAR_EXTRAPOLATE] 

or 

205

206 


SPLINE/id 

, FILE=filename 

[, BLOCK=blockname] 

[, LINEAR_EXTRAPOLATE] 

[ ] Optionally select the item. 


SUBROUTINE SPLINE_READ (id, file_name, block_name, status) 


id An integer variable that indicates the identifier of the corresponding 


file_name A character array of dimension 132 that contains the FILE name that 

you specify using the FILE argument in the corresponding SPLINE 

statement. 

block_name A character array of dimension 132 that contains the BLOCK name (if 

any) that you specify using the BLOCK argument of the corresponding 



status A logical variable that indicates if SPLINE_READ successfully reads 

and passes the x, y, [and z] data from the file to Adams/Solver. If the 

SPLINE data does not pass correctly, you can set the status to .TRUE. 

using PUT_SPLINE, which stops the appropriate operations in 

Adams/Solver. Otherwise, set the status to .FALSE. 


If you are a novice Adams/SOLVER user, you can use the X and Y arguments in the SPLINE statement 

to define the spline elements. If you are an expert user and a sizeable amount of data is required to define 

the spline elements, you might prefer to use the FILE argument in the SPLINE statement in conjunction 

with the SPLINE_READ user-written subroutine. 

Adams/Solver calls SPLINE_READ during the model-input phase. At this point, the model is not fully 

defined, and consequently, SPLINE_READ may not call most utility subroutines. SPLINE_READ must 

call the PUT_SPLINE utility subroutine in order to pass Adams/Solver the x, y, [and z] data that it reads 

from the file (see PUT_SPLINE).



A sample structure for the SPLINE_READ subroutine follows next. The comments explain the activities 

that the subroutine performs. 

SUBROUTINE SPLINE_READ (ID, FILE_NAME, BLOCK_NAME, STATUS) 

C 


C 



C 


C 

INTEGERID 

CHARACTER*132FILE_NAME 

CHARACTER*132BLOCK_NAME 

LOGICALSTATUS 

C 

C IDIdentifier of calling SPLINE statement 

C FILE_NAMEName of file containing data to define spline 

C BLOCK_NAMEName of named block within the file to be 

C used for this spline 

C STATUS Error status flag 

C 


C 

... 

C 


C 

C open file, check validity, type... and read data into local 

variables 

C 

... 

CALL PUT_SPLINE(ID,NX,NZ,X,Y,Z,ERRFLG) 

C 

C check ERRFLG, clean-up (release memory if necessary, close 

file...), and set STATUS 

C 

... 

C 

RETURN 

END 


typedef void adams_c_SPLINE_READ(const struct sAdamsSpline* spline, 

int* IERR); 

/* 

* SPLINE ------------------------------------------------- 

---------------- 

*/ 

struct sAdamsSpline 

207

208 


{ 

}; 

int ID; 

const char* FILENAME; 

const char* BLOCKNAME; 

Examples 

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

SURSUB 

SURSUB is an evaluation subroutine that computes surface coordinates and their derivatives for a 

SURFACE element (C++). The use of SURSUB is optional; it is not required when a Parasolid file is 

provided as input for the surface definition. 

Use 



For FORTRAN use: 

SUBROUTINE SURSUB (ID, PAR, NPAR, U, V, IORD, IFLAG, VALUES, IERR)For C++ use: 

SURSUB (int ID, double* PAR, int NPAR, double U, double V, int IORD, int IFLAG, double* VALUES, 

int* IERR)



id An integer variable that provides the identifier of the SURFACE statement 

that is being defined by SURSUB. 

iflag A logical variable that Adams/Solver sets to TRUE for the initial call to 

SURSUB. Computations that should be done only once during an analysis 

should be performed and stored when IFLAG is true. 

iord An integer variable that specifies the order of the derivative that SURSUB 

returns. The possible values are: 

zero - Return surface coordinates. 

one - Return first derivatives with respect to u, v. 

two - Return second derivatices with respect to u, v. 


USER parenthetical list. The purpose of npar is to provide SURSUB with 

the number of values stored in the par array. 

par A double-precision array of constants that is taken in order from the USER 

parenthetical list of the SURFACE statement. 

u A double-precision variable that specifies the value of the independent 

parameter u, which SURSUB uses to evaluate coordinates of a point on the 

surface. Adams/Solver restricts u to be: 

Greater than or equal to the MINPAR[1] value on the SURFACE statement 

(-1.0 by default). 

Less than or equal to the MAXPAR[1] value on the SURFACE statement 

(1.0 by default). 

v A double-precision variable that specifies the value of the independent 

parameter v which SURSUB uses to evaluate coordinates of a point on the 

surface. Adams/Solver restricts v to be: 

Greater than or equal to the MINPAR[2] value on the SURFACE statement 

(-1.0 by default). 

Less than or equal to the MAXPAR[2] value on the SURFACE statement 

(1.0 by default). 

209

210 


Output Arguments


values A double-precision array that contains the output data. The data are 

dependent on IORD and IERR. This is elaborated below. 

Note: All data are to be returned, column ordered, in a single array. 

IORD=0, 

IERR=0 

IORD=0, 

IERR=1 

IORD=1, 

IERR=0 or 

IERR=1 

IORD=2, 

IERR=0 or 

IERR=1 

(3x1 array) 

(5x1 array) 

(3x2 array) 

(3x3 array) 

211

212 


IERR An integer variable that specifies whether or not the [u,v] provided as 

input is on the surface. 


IERR=0 implies the point is on the SURFACE 

IERR=1 implies the point is not on the SURFACE 

IERR should be set only when IORD=0. 

IF IERR=0, then SURSUB should just return the x ,y ,z coordinates of the 

point on the SURFACE. The first three components of the output array 

VALUES should contain this data. The last two components of VALUES 

can remain undefined. 

IF IERR=1, then SURSUB is required to extrapolate the SURFACE 

definition and return the x, y, z coordinates of the point on the 

extrapolated SURFACE. The first three components of the output array 

VALUES should contain this data. In addition, SURSUB is also expected 

to return the u,v values of the point on the surface closest to the x, y, z 

coordinates that were calculated. These values, u* and v*, are returned in 

components 4,5 of the output array VALUES. 

SURSUB is a user-written subroutine that allows you to define a SURFACE. The x, y, and z coordinates 

of a point on a parametric surface are functions of independent parameters, (u,v). As (u,v) vary from their 

minimum to maximum values, the functions x(u,v), y(u,v), and z(u,v) sweep out points on the surface. 

A surface can be open or closed in both u and v. A surface closed in u (UCLOSED) meets along the edges 

defined by the maximum and minimum values of u. A surface closed in v (VCLOSED) meets along the 

edges defined by the maximum and minimum values of v. 

Surfaces can be used in Adams constraints. A surface marker allowed to only move on the surface is 

provided for this purpose. Any valid constraint (joint, jprim, and so on) can be constructed using the 

surface marker. 

A surface has parameterization limits as prescribed by MINPAR and MAXPAR. It is likely, however, that 

there are regions within the parameter space where the surface is not defined. The finiteness of the surface 

(including holes) are modeled using a penalty approach. The penalty approach applies a force to prevent 

the surface marker from moving off the edge of an open surface, or from moving into a hole in the 

surface. This approach necessarily requires that the surface marker move off the surface for a short 

duration. In such a situation, the surface descriptor is provided with [u,v] values outside the domain of 

the surface. The descriptor is expected to extrapolate the surface definition to provide an estimated 

location of the surface marker at these [u,v] points. Linear extrapolation is adequate for most purposes. 

Adams/Solver automatically extrapolates the surface as needed when the surface description is provided 

as a Parasolid geometry file. You are required to perform such extrapolation when you provide the 

surface definition through a SURSUB user-written subroutine.


If [u,v] are the parameters corresponding to the current point on the surface, and [u*, v*] are the 

parameters for the closest material point on the surface to [u,v], the penalty force that is applied in the 

[u,v] domain is: 

F = -K * [(u-u)2 + (v-v*)2] 

K = 108 

At this time, you have no control over the stiffness parameter, K. 

Caution: Define the SURFACE only as a function of u, v. Do not make calls to the SYSARY and 

SYSFNC utility subroutines to access other system variables. 


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

SUBROUTINE SURSUB ( ID, PAR, NPAR, U, V, IORD, IFLAG, 

& VALUES, IERR ) 

C 

C Inputs: 

C 

INTEGER ID 


INTEGER NPAR 

DOUBLE PRECISION U,V 

INTEGER IORD 

LOGICAL IFLAG 

C 

C Outputs: 

C 

DOUBLE PRECISION VALUES( * ) 

INTEGER IERR 

C 

C+---------------------------------------------------------------* 

C 

C ID 

Identifier of calling CURVE statement 



C U,V Curve parameter value 



C VALUES Derivative values of CURVE returned to ADAMS 

C IERR Return flag; 0 =(U,V) on surface 

1 =(U,V) outside surface 

C 

C+---------------------------------------------------------------* 

C 


C 

... 

C 

213

214 


C External Functions:(Note : This function must be written by you) 

C 

EXTERNAL UV_IS_OUTSIDE_SURFACE 

LOGICAL UV_IS_OUTSIDE_SURFACE 

C 

C+---------------------------------------------------------------* 

C 


C 

C 

Initialization call: 

C 

... 

 

 

... 

RETURN 

ENDIF 

C 

C 

Computation call: 

C 

IERR = 0 


C 

C 

Check whether [u,v] lie on the surface: 

C 

IF ( UV_IS_OUTSIDE_SURFACE(...) ) THEN 

... 

 

C 

C 

C 

C 

C 

C 

C 

C 

C 

C 

C 

C 

C 

C 

VALUES(2) = y... 

VALUES(3) = z... 

ENDIF 

ELSEIF ( IORD .EQ. 1 ) THEN 


Need matrix of 1st partial derivatives wrt. Parameters u,v: 

... 

 

... 

Return the 3x2 matrix of partials, sorted by column 

VALUES(1) = dx_du... VALUES(2) = dy_du... 

VALUES(3) = dz_du... VALUES(4) = dx_dv... 

VALUES(5) = dy_dv... VALUES(6) = dz_dv... 

ELSEIF ( IORD .EQ. 2 ) THEN 

Need matrix of 2nd partial derivatives wrt. Parameters u,v: 

... 

 

... 

Return the 3x3 matrix of partials, sorted by column 

VALUES(1) = d2x_dudu... 

VALUES(2) = d2y_dudu... 

VALUES(3) = d2z_dudu... 

VALUES(4) = d2x_dudv... 

VALUES(5) = d2y_dudv... 

VALUES(6) = d2z_dudv... 

VALUES(7) = d2x_dvdv... 

VALUES(8) = d2y_dvdv... 

VALUES(9) = d2z_dvdv... 

ELSECC 

Error - Should not be here: 

CALL ERMESS (...) 

ENDIF 

RETURN 

END 

C Style Prototype 

typedef void adams_c_SURSUB(const struct sAdamsSurface* srf, double 

ALPHA, double BETA, int IORD, int IFLAG, double* VALUES, int* IERR ); 

/* 

* SURFACE 

215

216 


*/ 

struct sAdamsSurface 

{ 

int ID; 

int NPAR; 


/* const char* FILENAME; */ 

int ORDER[2]; 

int CLOSED[2]; 

double MINPAR[2]; 

double MAXPAR[2]; 

}; 

Examples 

The figure below illustrates a circular surface S with a hole H at its very center. The surface S belongs to 

a body A. A point P, belonging to a different body B, is required to move on the surface S. The bounds 

of the parameterization are the outer perimeter of the circular suface A circular surface with a hole in its 

center. 

A circular surface with a hole in its center. 

For an example of this subroutine, see sursub.c. 

UCOSUB 

The UCOSUB evaluation subroutine computes a constraint value and its derivatives for a UCON 

statement. You must write a UCOSUB whenever one or more UCON statements are used in a dataset. 

Use 


UCON/id, FUNCTION=USER(r1[,...,r30]) 

[ ] Optionally select the item. 


SUBROUTINE UCOSUB (id, time, q, par, npar, idrsel,& iflag, scalar, array, xmatrx)



id An integer variable that contains the ID of the UCON statement requesting 

information from UCOSUB. From the identifier, Adams/Solver 





q A double-precision array (of as many as thirty elements) that contains the 

current values of the part principal axes variables. These values are in the 

order specified by the call to UCOVAR. 


parenthetical list of the UCON statement; r1[,...,r30]. 


USER parenthetical list. The primary purpose of npar is to provide 

UCOSUB with the number of values stored in the par array. 

idrsel A three-element integer array containing control values for returning the 

proper information through scalar, array, and xmatrx. 

iflag A logical variable used as a switch to call UCOVAR for initial definition of 

the principal axes variables. If the iflag argument is true, UCOVAR should 

be called (see UCOVAR). 

217

218 


Output Arguments


array A thirty-element double-precision array that returns to Adams/Solver the 

first derivatives of the constraint relationship with respect to the principal 

axes variables or through which the second partials of the constraint 

relationship are returned with respect to time and the principal axes 

variables. The set of derivatives UCOSUB returns depends on the value 

of idrsel(2). In this table, q represents the variables, t stands for time, and 

F refers to the constraint equation. 

If idresel (2) is: 

array is: 

0 

No evaluation 

1 

array (m) = 

2 

array (m) = 

If any of the elements of array are symbolically zero, they don't need to 

be defined. 

219

220 


scalar A double-precision variable for returning the residue (the error relative to 

zero) of the implicit constraint expression, the nonprincipal axes variabledependent 

portion of the constraint expression (the value of the constraint 

expression if all principal axes variables are zero), or the various time 

derivatives of the constraint expression. 

The value UCOSUB returns to Adams/Solver depends on the value of 

idrsel(1). In the following table, q represents the variables, t stands for 

time, F refers to the constraint equation, and f refers to the equation when 

all variables (q) are set equal to zero. 


scalar is: 

0 

No evaluation 

1 

scalar = 

2 

scalar = 

3 

scalar = 

4 

scalar =


xmatrx A double-precision thirty-by-thirty array that returns to Adams/Solver the 

second derivatives of the constraint expression with respect to the 

principal axes variables. The second derivatives UCOSUB returns the 

value of idrsel(3): 



xmatrx is: 

0 

No evaluation 

1 

xmatrx(m,n) = 

The letter q represents the variables, t stands for time, and F refers to the 

constraint equation. If any of the elements of xmatrx are symbolically 

zero, they need not be defined. 

The standard constraint statements are usually adequate for defining commonly occurring displacement 

constraints between marker pairs. For displacement constraint combinations not available through these 

statements or for constraints involving velocity variables, you should use the FUNCTION=USER() 

argument in the UCON statement, and write a UCOSUB to define the constraint. The constraints defined 

in the subroutine can incorporate velocity variables. You can select as many as thirty displacements 

and/or velocities of part principal axes to be the variables in the constraint relationship for a UCON 

statement. Each UCON statement removes one degree of freedom from the system. 

At every evaluation step, Adams/Solver evaluates UCOSUB to determine the value of the constraints. 

During the initialization of UCOSUB, the utility subroutine UCOVAR should be called to declare the 

variables used in the relationship. PART statement identifiers and type codes identify the variables. To 

preserve the generality of UCOSUB, the identifiers and the type codes can be passed through the 

parameter list of the UCON statement. 

For the formulation of constraints, you cannot access information with SYSARY or SYSFNC. You can, 

however, access information with AKISPL or CUBSPL (see AKISPL, CUBSPL, and UCOVAR). You 

must set up UCOSUB system dependencies using UCOVAR, and use system information from the q 

parameter only. 

For each system constraint, Adams/Solver formulates a governing constraint equation. For standard 

Adams/Solver constraint statements, symbolic partial derivatives of the constraint equation with respect 

221

222 


to the system variables have been pre-computed and stored in the program for use in the system Jacobian 

when the particular constraint is involved. 

When you write a UCOSUB, equations of motion are added to the set of equations Adams/Solver 

generates for the standard constraint statements. You must provide the first and second derivatives of the 

constraint relationship with respect to the set of variables. You must code the constraint relationship in 

the implicit form. For information on implicit forms, see DIFF statement (C++ or FORTRAN). 

Caution: • When selecting the displacements or the velocities of the part principal axes for the 

constraint, remember that the part principal axes are not always identical to those 

of the part center-of-mass marker (CM). The following list summarizes the 

circumstances in which the part principal axes may differ from those of the part 

center-of-mass marker. 

Structure 

• When the PART statement does not include the CM argument, the principal 

axes default to the body coordinate system. 

• Whenever the center-of-mass marker z-axis is parallel to the z-axis of the 

ground reference frame at time zero, Adams/Solver permutes the internal 

representation of the principal axes by 90-degree rotations to avoid an Euler 

matrix singularity. 

• If the IP argument in the PART statement includes products of inertia, 

Adams/Solver computes the inertial representation of the principal axes so that 

the products of inertia become zero. 

• When specifying an IM marker, Adams/Solver computes the principal axes, 

which may or may not be the axes of the CM marker. 

• When the iflag argument is true, Adams sets q to zero. When you execute 

Adams/Solver, computations that divide by these values result in fatal errors. 

Before dividing by q values, you should check for nonzero values or ensure the 

iflag argument is false. 

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

SUBROUTINE UCOSUB (ID, TIME, Q, PAR, NPAR, 

& IDRSEL, IFLAG, SCALAR, ARRAY, 

& XMATRX) 

C 


C 


C 

INTEGER ID 


DOUBLE PRECISION Q( 30 ) 


INTEGER NPAR


INTEGER IDRSEL( 3 ) 

LOGICAL IFLAG 

DOUBLE PRECISION SCALAR 

DOUBLE PRECISION ARRAY( 30 ) 

DOUBLE PRECISION XMATRX( 30, 30 ) 

C 

C ID Identifier of calling UCON statement 


C Q Array of part state variables 



C IDRSEL UCON values selection control flag 


C SCALAR Scalar value returned to ADAMS 

C ARRAY Partial derivatives 

C XMATRX Second partial derivatives 

C 


C 

... 

C 


C 

C - Assign parameters to readable variable names -- 

C 

... 

C 


C 


C 

C Declare principal axis variables 

C 

CALL UCOVAR ( ... ) 

C 

ENDIF 

C 

C - Find implicit constraint relation ------- 

C 

IF ( IDRSEL(1) .EQ. 1 ) THEN 

C 


C 

... 

C 

C Assign scalar 

C 

SCALAR = ... 

C 

C - First time derivative of constraint relation -- 

C 

ELSE IF ( IDRSEL(1) .EQ. 2 ) THEN 

C 


223

224 


C 

... 

C 

C Assign first time derivative to scalar 

C 

SCALAR = ... 

C 

C - Second time derivative of constraint ------ 

C 

relation 

C 


C 


C 

... 

C 

C Assign second time derivative to scalar 

C 

SCALAR = ... 

C 

C - Nonprincipal-axes-dependent portion of ---- 

C 

constraint relation 

C 


C 


C 

... 

C 

C Assign nonprincipal-axes-dependent portion to scalar 

C 

SCALAR = ... 

C 

ENDIF 

C 

C - Evaluate array ----------------- 

C 

C - First derivative of constraint relationship with 

C respect to the variables 

C 

IF ( IDRSEL(2) .EQ. 1 ) THEN 

C 


C 

... 

C 

C Assign array values 

C 

ARRAY(1) = ... 

... 

ARRAY(30) = ... 

C

C - Derivatives of prior first derivatives with -- 

C respect to time 

C 


C 


C 

... 

C 

C Assign array values 

C 

ARRAY(1) = ... 

... 

ARRAY(30) = ... 

C 

ENDIF 

C 

C - Derivatives of prior first derivatives with -- 

C respect to the variables 

C IF ( IDRSEL(3) .EQ. 1 ) THEN 

C 


C 

... 

C 

C Assign matrix values 

C 

XMATRX(1, 1) = ... 

... 

XMATRX(30, 30) = ... 

C 

ENDIF 

C 

RETURN 

END 

Examples 

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

VARSUB 


The VARSUB evaluation subroutine computes an algebraic value for a VARIABLE statement (C++ or 

FORTRAN). VARSUB is optional. You only need it if you don't want to use a function expression in the 

VARIABLE statement. 

225

226 


Use 



CALL VARSUB(id, time, par, npar, dflag, iflag, value) 


id An integer variable that contains the ID of the VARIABLE statement 

requesting information from VARSUB. From the identifier, 






parenthetical list of the VARIABLE statement. 


the USER parenthetical list. The primary purpose of the npar argument is 

to provide VARSUB with the number of values stored in the par array. 

dflag A logical variable that Adams/Solver sets to true when it calls VARSUB 




functional dependency of the user-defined VARIABLE statement. 

Adams/Solver usually does this during the first pass through each 

VARIABLE statement that is calling the subroutine. You set functional 

dependencies with the same calls to SYSARY and SYSFNC that you use 

to compute the value of the user-defined VARIABLE statement (see 

SYSARY and SYSFNC). If the iflag argument is false, you should 

compute the value of the user-written VARIABLE statement. 


value A double-precision variable that returns the value of the variable. 


You can use the VARIABLE statement with the function expression to define most user-defined 

VARIABLE statements. However, if the expression becomes lengthy and awkward, you should use the 

FUNCTION=USER() argument in the VARIABLE statement, and write a VARSUB to define the 

VARIABLE statement.


You can call utility subroutines, such as AKISPL, CUBSPL, SYSARY, and SYSFNC, from VARSUB, 

to obtain information about system variables, user-defined variables, and splines (see AKISPL, 

CUBSPL, SYSARY, and SYSFNC). 


VARSUB argument iflag is true. 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 VARSUB with the argument iflag set to true. 

Adams/Solver does this once for each VARIABLE statement with a FUNCTION=USER() argument. 

During each call to VARSUB, Adams/Solver records which calls you make to SYSARY and SYSFNC. 

Adams/Solver assumes the user-defined variable depends on those system and user-defined variables, 

and no others. 





Caution: • When the iflag argument is true, you should make the same calls to SYSARY and 

SYSFNC as you do to compute the value of the user-defined VARIABLE 

statement. This ensures that Adams/Solver has the proper functional dependencies. 

In general, Adams/Solver may have difficulty converging to a solution and/or may 

take small integration steps if you fail to account for dependencies of the userdefined 

VARIABLE statement. These results usually cause large increases in 



system and user-defined variables. Computations that divide these values result in 

system errors when you execute Adams/Solver. You should check for nonzero 

values or ensure that the iflag argument is set to false before dividing by these 

values. 

• You must be careful when defining a VARIABLE statement dependent on another 

VARIABLE statement, or on other Adams/Solver statements that contain 

functions. If you define a system of equations without a stable solution, the 

convergence may fail for the entire Adams/Solver model. The following example 

refers to this type of VARIABLE statement: 

VARIABLE/1,FUNCTION=VARVAL(1)+1 

When looked at as an algebraic equation, it looks like the following: 

V=V+1 

However, when Adams/Solver tries to solve this equation using the Newton-Raphson 

iteration, the solution diverges and a message indicates that the corrector has failed to 

converge. 

227

228 



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

SUBROUTINE VARSUB ( ID, TIME, PAR, NPAR, DFLAG, 


C 


C 

C 


C 

INTEGER ID 



INTEGER NPAR 

LOGICAL DFLAG 

LOGICAL IFLAG 


C 

C ID Identifier of calling VARIABLE statement 






C VALUE The VARIABLE value returned to ADAMS 

C 


C 

... 

C 


C 


C 

... 

C 


C calculations below. Note: if IFLAG is true, these 


C 

CALL SYSFNC ( ... ) 

C 


C 

C Repeat for all required SYSFN 

C or SYSARY calls 

C 

... 

C 

IF( IFLAG ) THEN

C 


C 

... 

C 

ENDIF 

C 

C - Evaluate variable---------------- 

C 


C 

... 

C 


C 

VALUE = ... 

C 

RETURN 

END 



typedef void adams_c_VARSUB(const struct sAdamsVariable* variable, 

double TIME, int DFLAG, int IFLAG, double* RESULT); 

/* 

* VARIABLE 

*/ 

struct sAdamsVariable 

{ 

int ID; 

int NPAR; 


double IC; 

}; 

Examples 

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

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. 

Use 



SUBROUTINE VFOSUB (id, time, par, npar,dflag, iflag, result) 

229

230 



id An integer variable that contains the ID of the VFORCE statement 

requesting information from VFOSUB. From the identifier, 






parenthetical list of the VFORCE statement. 


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 


Adams/Solver sets the dflag argument to false. See Using the DFLAG 

Variable. 

iflag A logical variable that Adams/Solver sets to true when it needs 

functional dependency information from VFOSUB. Functional 

dependencies are established with the same calls to SYSARY and 

SYSFNC that are later used to compute the values of the VFORCE 

components (see SYSARY and SYSFNC). If the iflag argument is false, 

the values of the user-defined expressions are computed. 


result A double-precision array that returns the three values of the VFORCE 

components, in x-y-z order. 


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). 


VFOSUB argument iflag is true. 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 true. 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. 





Caution: • When the iflag argument is true, 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 


Adams/Solver to take small integration steps. Both of these effects usually cause 

large increases in execution time. 


• When the iflag argument is true, 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 false before dividing by these values. 

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

& 

SUBROUTINE VFOSUB(ID, TIME, PAR, NPAR, DFLAG, 


C 


C 


C 

INTEGER ID 



INTEGER NPAR 

LOGICAL DFLAG 

LOGICAL IFLAG 


C 

C ID Identifier of calling VFORCE statement 





C 

C 

IFLAG 

RESULT 

Initial pass flag 

Array (dimension 3) of computed VFORCE 


231

232 


C 

C - Local variable and parameter definitions ------ 

C ... 

C 


C 


C 

... 

C 


C the calculations below. Note: if IFLAG is true, these 


C 


C 


C 


C 


C 

... 

C 


C 


C 

... 

C 

ENDIF 

C 

C - Evaluate VFORCE components ------------ 

C 


C 

... 

C 


C 

RESULT(1) = ... 

RESULT(2) = ... 

RESULT(3) = ... 

C 

RETURN 

END 


typedef void adams_c_VFOSUB(const struct sAdamsVforce* vfo, double 


/* 

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

----------------

*/ 

struct sAdamsVforce 

{ 

int ID; 

int NPAR; 


int I; 

int JFLOAT; 

int RM; 

}; 

Examples 

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

VTOSUB 


The VTOSUB evaluation subroutine computes torque components for a VTORQUE statement (C++ or 

FORTRAN). VTOSUB is optional. You only need it if you don't want to use function expressions in the 

VTORQUE statement. 

Use 



SUBROUTINE VTOSUB(id, time, par, npar, dflag, iflag, result) 


id An integer variable that contains the ID of the VTORQUE statement 

requesting information from VTOSUB. From the identifier, Adams/Solver 






parenthetical list of the VTORQUE statement. 

233

234 



USER parenthetical list. The primary purpose of the npar argument is to 

provide VTOSUB with the number of values stored in the par array. 

dflag A logical variable that Adams/Solver sets to true when it calls VTOSUB to 




dependency of the user-defined expressions. You set functional 

dependencies with the same calls to the SYSARY and SYSFNC utility 

subroutines that are made to compute the values of the user-defined 

expressions (see SYSARY and SYSFNC). If the iflag argument is false, the 

values of the user-defined expressions are computed. 


result A double-precision array of length 3 that returns the x-, y-, and z-components 

of the VTORQUE. 


You can often use the VTORQUE statement with function expressions sufficient to define the three 

rotational vector components of a torque at a point. However, if the torque expressions become lengthy 

and awkward, you can use a VTOSUB evaluation subroutine. If the algorithms use or consist of already 

existing FORTRAN-77 subroutines, VTOSUB can be made to call them. 

You can call utility subroutines, such as AKISPL, CUBSPL, SYSARY and SYSFNC, from VTOSUB to 

obtain information about system variables, user-defined variables, and splines. See AKISPL, CUBSPL, 

SYSARY, and SYSFNC. 


VTOSUB argument iflag is true. In order 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 VTOSUB with the argument 

iflag set to true. Adams/Solver does this once for each VTORQUE statement with a 

FUNCTION=USER() argument. 

During each call to the VTOSUB evaluation subroutine, Adams/Solver records which calls you make to 

SYSARY and SYSFNC and assumes that the resulting values are dependent on only those Adams/Solver 

variables accessed through the SYSARY and SYSFNC calls. 


the values returned by these may contain discontinuities. To avoid the discontinuities, use 


other coordinate system that does not encounter a singularity.



Caution: • When the iflag argument is true, you must make all the same calls to SYSARY and 

SYSFNC as are made to compute the component values of VTORQUE. This 

ensures that Adams/Solver has the proper functional dependencies. In general, 

failure to account for dependencies in the VTORQUE components may make it 

difficult for Adams/Solver to converge to a solution and/or may force 

Adams/Solver to take small integration steps, potentially causing large increases in 



system and user-defined variables. 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 set to false before dividing by 

these values. 

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

& 

SUBROUTINE VTOSUB(ID, TIME, PAR, NPAR, DFLAG, 


C 


C 


C 

INTEGER ID 



INTEGER NPAR 

LOGICAL DFLAG 

LOGICAL IFLAG 


C 

C ID Identifier of calling VTORQUE statement 





C IFLAG Initial pass flag 

C RESULT Array (dimension 3) of computed VTORQUE 

C 

C 

components returned to ADAMS 

C - Local variable and parameter definitions ------ 

C 

... 

C 


C 


C 

... 

235

236 


C 


C the following calculations. Note: if IFLAG is true, these 


C 


C 


C 


C 


C 

... 

C 


C 


C 

... 

C 

ENDIF 

C 

C - Evaluate VTORQUE components ------------ 

C 


C 

... 

C 


C 

RESULT(1) = ... 

RESULT(2) = ... 

RESULT(3) = ... 

C 

RETURN 

END 


typedef void adams_c_VTOSUB(const struct sAdamsVtorque* vto, double 


/* 

* VTORQUE ------------------------------------------------- 

---------------- 

*/ 

struct sAdamsVtorque 

{ 

int ID; 

int NPAR; 


int I; 

int JFLOAT; 

int RM; 

};

Examples 

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

(1) 

(2) 0 

0 1 2 

F( x, x′ ) 

0 Value of the function 

1 Partial derivative of the function with respect to x. 


∂ 

F( x, x′ ) 

∂ x 

∂ 

F( x, x′ ) 

∂ x 

2 Second partial derivative of the function with respect to x. 

2 

x2 ∂ 

F( x, x′ ) 

∂ 

2 

∂ 

F( x, x′ ) 

∂ x′ ∂ x 

237

238 

Adams/Solver

Welcome to Adams/Solver Subroutines - Kxcad.net

Create successful ePaper yourself

Delete template?

Save as template?