Adams 2021.0.2 Adams Solver User Guide

Adams 2021.0.
2
Adams Solver User's Guide
Corporate Europe, Middle East, Africa
MSC Software Corporation MSC Software GmbH
4675 MacArthur Court, Suite 900 Am Moosfeld 13
Newport Beach, CA 92660 81829 Munich, Germany
Telephone: (714) 540-8900 Telephone: (49) 89 431 98 70
Toll Free Number: 1 855 672 7638 Email: europe@mscsoftware.com
Email: americas.contact@mscsoftware.com
Japan Asia-Pacific
MSC Software Japan Ltd. MSC Software (S) Pte. Ltd.
KANDA SQUARE 16F 100 Beach Road
2-2-1 Kanda Nishikicho, Chiyoda-ku #16-05 Shaw Tower
Tokyo 101-0054, Japan Singapore 189702
Telephone: (81)(3) 6275 0870 Telephone: 65-6272-0082
Email: MSCJ.Market@mscsoftware.com Email: APAC.Contact@mscsoftware.com
Worldwide Web
www.mscsoftware.com
Support
http://www.mscsoftware.com/Contents/Services/Technical-Support/Contact-Technical-Support.aspx
Disclaimer
This documentation, as well as the software described in it, is furnished under license and may be used only in accordance with the
terms of such license.
MSC Software Corporation reserves the right to make changes in specifications and other information contained in this document
without prior notice.
The concepts, methods, and examples presented in this text are for illustrative and educational purposes only, and are not intended
to be exhaustive or to apply to any particular engineering problem or design. MSC Software Corporation assumes no liability or
responsibility to any person or company for direct or indirect damages resulting from the use of any information contained herein.
User Documentation: Copyright © 2021 MSC Software Corporation. Printed in U.S.A. All Rights Reserved.
This notice shall be marked on any reproduction of this documentation, in whole or in part. Any reproduction or distribution of this
document, in whole or in part, without the prior written consent of MSC Software Corporation is prohibited.
This software may contain certain third-party software that is protected by copyright and licensed from MSC Software suppliers.
Additional terms and conditions and/or notices may apply for certain third party software. Such additional third party software terms
and conditions and/or notices may be set forth in documentation and/or at http://www.mscsoftware.com/thirdpartysoftware (or successor
website designated by MSC from time to time). Portions of this software are owned by Siemens Product Lifecycle Management, Inc.
© Copyright 2021
The MSC Software logo, MSC, MSC Adams, MD Adams, and Adams are trademarks or registered trademarks of MSC Software
Corporation in the United States and/or other countries. Hexagon and the Hexagon logo are trademarks or registered trademarks of
Hexagon AB and/or its subsidiaries. FLEXlm and FlexNet Publisher are trademarks or registered trademarks of Flexera Software.
Parasolid is a registered trademark of Siemens Product Lifecycle Management, Inc. All other trademarks are the property of their
respective owners.
ADAM:V2021.0.2:Z:Z:Z:DC-SOLVE
Documentation Feedback
At MSC Software, we strive to produce the highest quality documentation and welcome your feedback.
If you have comments or suggestions about our documentation, write to us at: documentation-
feedback@mscsoftware.com.
Please include the following information with your feedback:
 Document name
 Release/Version number
 Chapter/Section name
 Topic title (for Online Help)
 Brief description of the content (for example, incomplete/incorrect information, grammatical
errors, information that requires clarification or more details and so on).
 Your suggestions for correcting/improving documentation
You may also provide your feedback about MSC Software documentation by taking a short 5-minute
survey at: http://msc-documentation.questionpro.com.
Note: The above mentioned e-mail address is only for providing documentation specific
feedback. If you have any technical problems, issues, or queries, please contact Technical
Support.
1
About Adams Solver
About Adams Solver

Conventions
Throughout the help, the following type styles are used as visual cues.
Style: Indicates:
Name A string that is a legal name for use in interface products. The following criteria must
be met in order for a legal string to be defined:
 The name may only contain alpha numeric characters (upper and lower case).
 No white space in the name.
 No special characters in the name (e.g. @#$%^&*). The exception to this rule
is the underscore '_' character.
 Names must begin with an alpha character or an underscore. (e.g. 4bar is not
legal, while _4bar is legal).
x Arguments in Adams subroutines and functions
i Parameters that follow a statement, command, or argument:
i = Integer
r = Real
c= Character string (alphanumeric)
e = Function expression
v =Varying type (integer, real, or alphanumeric)
id =Identifier
x,y,z =Cartesian coordinate (real)
a,b,c =Angular coordinate (real)

PART Minimum abbreviations of statements, commands, and arguments
{} Selection you can make from a series of items
[] Optional selection you can make from a series of items
[[ ]] Combined selection you can make from a series of items
A Two-dimensional matrices
2 Adams Solver
Style: Indicates:
a One-dimensional matrices
R1 Vectors
x̂ Unit vectors
Guidelines for Solver Selection and Settings

This section provides some advice with regard to selection of solver types and integrators.
Solver Selection
There are two "flavors" of Adams Solver: the FORTRAN version the C++ version. The C++ version is the
default choice across the Adams product line. MSC recommends all Adams users to use the C++ version. It
is generally faster and more robust. It also supports more modeling capability than the FORTRAN version.
MSC plans to retire the FORTRAN Solver in a future release of Adams, so if you believe you have any
modeling conditions in which the FORTRAN solver appears to be favorable, please contact MSC technical
support and share what details you can about the case.
For a more detailed comparison of the FORTRAN and C++ versions of Adams Solver, see Adams Solver C++
vs. FORTRAN.
Integrator Selection
The two integrators most widely used are the GSTIFF and HHT integrators. The table below describes the
benefits, cautions and recommended usage when models are dominated by certain content. The GSTFF
integrator has two available formulations: I3 (whose error control is on the displacement states) and SI2
(which controls error on the velocity states). Each are listed separately below.
3
About Adams Solver
4 Adams Solver
Benefits Cautions Model Content

GSTIFF I3  High Speed  Velocities and especially  Recommended for most
 High accuracy of system accelerations can have numerically stiff models
displacements errors. An easy way to (many mechanical systems
minimize these errors is to with large range of
 Robust in handling a variety control HMAX so that the frequency content) and
of analysis problems integrator runs at a constant models with velocity inputs.
step size and runs
consistently at a high order
(three or more)
 You can encounter corrector
failures at small step sizes.
These occur because the
Jacobian matrix is a function
of the inverse of the step size
and becomes ill-conditioned
at small steps
GSTIFF SI2  Gives very accurate results,  Is typically 25% to 100%  Recommended for models
especially for velocities and slower for most problems where velocity or high
accelerations than regular GSTIFF, when frequency accuracy might be
 Usually allows an ERROR run with the same error important. Common
that is approximately 10 to  Requires that all velocity examples include models
100 times larger than regular inputs be differentiable. with contact or friction.
GSTIFF to produce the Therefore, you must define
same quality of results your MOTIONS so that
 Is very robust and stable at they are smooth and twice
small step sizes differentiable. Non-smooth
motions, which theoretically
 Corrector failures that small cause infinite accelerations,
step sizes cause occur less cause failures in the SI2
frequently than with formulation. The I3
GSTIFF I3 formulations can sometimes
 Singular matrices due to handle such models.
small step sizes occur less
frequently than with
GSTIFF I3
 Corrector failures are
typically indicative of a
modeling problem and not
of a numerical deficiency in
the Adams Solver software
 Tracks high frequency
oscillations very accurately
5
About Adams Solver
Benefits Cautions Model Content

HHT  Expected to result in a  Because of the reduced  Recommended for fast
smaller number of Jacobian order, the acceleration and solution of models with
evaluations reaction forces obtained are flexible bodies or those
 Unlike GSTIFF, behaves like going to be more spiky having high frequency
a low pass filter; it cuts high  The numerical damping content and/or durability
frequency spurious associated with HHT is loading.
oscillations, while accurately smaller than the one
preserving low frequency produced by GSTIFF
oscillations  If GSTIFF manages to run a
 Can control the cutoff simulation at order 4 or
frequency by adjusting higher, it will take step sizes
alpha; the smaller value (that significantly larger than
is, closer to -0.3, the lower HHT. This is because HHT
the cutoff threshold) is a low-order integrator and
 Stable at small value of the it needs to limit the step size
integration step size based on accuracy
characteristics.
Other integrators:
 WSTIFF: The benefits and cautions of the WSTIFF integrator are the same as those for GSTIFF
with the one added benefit that the step size can change without any loss of accuracy.
 Newmark: The benefits and cautions of the Newmark integrator are the same as those for HHT.
 HASTIFF: The benefits and cautions are similar to those for GSTIFF SI2 with the one added
benefit that this integrator does not become unstable at very small time steps.
For further discussion of Adams Solver integrators, see the documentation for the INTEGRATOR statement.
Best Practices
This section contains general tips on advanced modeling with Adams Solver.
 Discontinuities
 Units
 Dummy Parts
 Joints
 Motions
 Forces
 Contacts
 Subroutines
 Simulation/Integrators
6 Adams Solver
 Debugging
 Miscellaneous Tips
Discontinuities
 Discontinuities are the root cause of most simulation problems. Avoid them.
 Examples of discontinuous functions: MIN, MAX, DIM, MOD, IF.
 Discontinuous displacements and velocities cause corrector and integrator failures.
 Discontinuous accelerations cause integration failures (requires infinite force).
 Discontinuous forces cause corrector failures.
Units
 Widely separated magnitudes in a matrix can cause numeric difficulties (conditioning problems).
 Be careful when using inconsistent units.
 Choose units so that model states (displacements and velocities) are reasonable values. For example,
choosing "mm" for displacements of a rocket which travels thousands of kilometers is a poor choice.
 Choose units so that stiffness values are not very large.
 Choose time units appropriate to the phenomena being studied.
Dummy Parts
 A dummy part is any part with zero or very small mass.
 Sometimes dummy parts are useful; but generally, avoid using them.
 Avoid connecting dummy parts with compliant connections (BEAMs, BUSHINGs, and so on). If
the mass of the dummy part = 0, then the acceleration, a = F/m = F/0 = infinite. Even if the mass is
very small, a = F/m = very large number. Therefore, small masses/moments of inertia introduce high
frequencies into the system, which is usually undesirable since it has detrimental effects on the
solver.
 If you must use dummy parts, then constrain all DOF, since with no DOF for the dummy part,
a=F/m is not an issue.
 Dummy parts should be massless; 0.0 (or unassigned), not 1e-20.
Joints
 Avoid using FIXED joints. A FIXED joint adds equations to your system that aren’t necessary when
two or more parts can be combined or merged into a single part.
 Avoid using many FIXED joints to lock parts to ground. Enormous torques may develop due to
large moment arms.
 If you must lock something to ground with a FIXED joint, consider assigning it a very large
mass/inertia so that it can behave like ground, or consider merging it to ground (for more
information, see Simcompanion Knowledge Base Article KB8013580).
 When possible, create a FIXED joint at the center-of-mass (cm) of the lightest part, to minimize the
reaction forces/torques.
7
About Adams Solver
 Avoid redundant constraints. Adams eliminates them by looking at pivots in a constraint Jacobian,
which are in no particular order. As a result, the physical meaning may be disregarded.
Motions
 Ideally, motions should impose continuous accelerations.
 Avoid using splines in a motion (function based on time is ideal).
 If you must use splines as motion, use their velocity form (see Simcompanion Knowledge Base
Article KB8015319 for more information). This is true for both GSTIFF and SI2_GSTIFF
integrators.
 Avoid using motion as a function of variables (that is, states).
 In general, cubic splines (CUBSPL) may work better on motions than the Akima. The derivatives of
the cubic are better than those of the Akima, so they’re more useful in forces than in motions (see
Simcompanion Knowledge Base Article KB8013252 for more information).
Forces
 If using data, approximate forces with smooth, continuous splines.
 Don’t define a spring damper with spring length=0.
 Make sure velocities are correct in force expressions. For example, in this damping function:
-c*vx(i,j,j )
the 4th term is missing --^
The 4th term defines the reference frame in which the time derivatives are taken, and this may be
important.
Contacts
 Contacts should penetrate before statics. Models with impacts should have slight penetration in
model position when doing statics.
 All tires should penetrate the road. Models with tires should have slight penetration in model
position when doing statics. For example, if only rear tires penetrate, the static position could be a
handstand.
 Contact properties are model dependent. See the CONTACT statement, and Simcompanion
Knowledge Base Article KB8015613 for a starting point. Adjustment of the properties to match
experimental results is expected.
Subroutines
 If possible, use an Adams function over a subroutine.
 If you receive errors in your model, eliminate user subroutines so they’re not the source of the errors.
 Verify that your compiler is compatible with the current version of Adams.
8 Adams Solver
Simulation/Integrators
 Perform initial static first, when applicable. Note that a static solution may be more difficult to find
than a dynamic solution. If you care only about the dynamic solution and cannot find static
equilibrium, then either increase your error tolerance or forget about the static simulation.
 15-20 static iterations is suspect.
 If GSTIFF won't start, it’s most likely a problem with initial conditions.
 Don't let the integrator step over important events. Short duration events like an impulse can be
captured by setting maximum time step, HMAX, to value less than impulse width.
 Use HMAX so that Adams Solver acts as a fixed-step integrator.
 Spikes in results output may come from changes in step size. Reduce HMAX or try setting
HINIT=HMAX. Run with SI2 instead.
 Adams Solver uses a body 3-1-3 rotation sequence (psi, theta, phi). Theta=0d (or 180d) is bad (Euler
singularity). If the z-axis of part cm is parallel to z-axis of ground, there will be a Euler singularity.
 For Euler Singularities, Theta=90D will have good pivots. Models will run better, and won't act like
there is a discontinuity.
 Truncation (or round-off) errors accumulate when you let MAXIT go larger than 6. The theory of
GSTIFF says 2-3 iterations is desirable; it breaks down if it uses more than 4 or 5.
Debugging
 Try to understand mechanism from a physical standpoint.
 Use building blocks of concepts that worked in the past. Add enhancements to the model using
crawl-walk-run approach.
 Test with a small model to isolate problems.
 Have graphics for visualizing motion.
 Look at damping terms as a source of errors. Incorrect sign and missing terms are typical mistakes.
 Turn on DEBUG/EPRINT.
 Turn gravity off, since it can accentuate modeling errors.
 Models should have no warnings during simulation (for example, redundant constraints, splines,
and so on).
 Understand numerical methods (for example, understand your integrator).
 Look for results which become very large in magnitude; this could indicate a discontinuity.
Miscellaneous Tips
 Avoid very large numbers and very small numbers. Be wary when your model contains numbers like
1e+23 or 1e-20.
 Choose the right set of units. Length units of millimeters may not be appropriate if you’re modeling
an aircraft landing on runway.
 Use a reasonable time scale. If duration of dynamic event time is short, consider using milliseconds
units.
9
About Adams Solver
 Extend the range of spline data beyond the range of need.

 Don’t write function expressions that can potentially divide by zero (for example, use the MAX
function to prevent this: function =8/MAX(0.01,your_function).
 Add damping so frequencies can dissipate.
 Avoid very high damping rates. The high damping cause a rapid decay in response, which is difficult
for an integrator to follow.
 Avoid toggles, dual solutions, or bifurcations.
 Don’t use 1.0 for the exponent in IMPACT or BISTOP functions. This creates a “corner” (that is, a
non-smooth function). Instead, try 2.2 for the exponent.
 It is not possible to run more than one external simulation with the same name in the same
directory.Solver. In this case more than one Solver simulation will try to access the same file causing
the simulation(s) to fail. This include external Solver simulations from View or Car.
Additional Publications
You might find it helpful to refer to the following resources when modeling mechanical systems.
Recommended Publications:
To learn about: See:

Akima Method Akima, Hiroshi. A New Method of Interpolation and Smooth Curve
Fitting Based on Local Procedures. Journal of the Association for
Computing Machinery, Vol. 17, No. 4, pp. 589-602, New York:
JACM, October, 1970.
BDF Integration Algorithm Brayton, R. K., F. G. Gustavson, and G. D. Hatchel. A New Efficient
Algorithm for Solving Differential-Algebraic Systems using Implicit
Backward Differentiation Formulas. Proceedings of the IEEE, Vol. 60,
No. 1, pp. 98-108. New York: Institute of Electrical and Electronics
Engineers, 1972.
Chebyshev Polynomial Carnahan, B., H.A. Luther, and J.O. Wilkes. Applied Numerical
Methods. New York: John Wiley & Sons, 1969.
Cubic Curve Fitting Method Forsythe, G.E., M.A. Malcolm, and C.B. Moler. Computer Methods for
Mathematical Computations. Englewood: Prentice-Hall, Inc., 1977.
DASSL Computer Code Gear, W.C. Numerical Initial Value Problems in Ordinary Differential
Equations. Englewood Cliffs: Prentice-Hall. 1971; and Brenan, K.E.,
S.L. Campbell, and L.R. Petzold, Numerical Solution of Initial-Value
Problems in Differential-Algebraic Equations. New York: Elsevier
Science, 1989.
10 Adams Solver
To learn about: See:

Gear Stiff Gear, W.C. Simultaneous Numerical solution of Differential-algebraic
Equations. IEEE Transactions on Circuit Theory, Vol. CT-18, No. 1,
pp. 89-95. New York: Institute of Electrical and Electronics Engineers,
1971.
Numerical Stiffness Wielenga, T. The Effect of Numerical Stiffness on Mechanism Simulation.
Proceedings from the 1986 International Computers in Engineering
Conference, Vol. 1, pp. 369-378. New York: American Society of
Mechanical Engineers, 1986.
Rotational Coordinates Kane, T.R., P.W. Likins, and D.A. Levinson. Spacecraft Dynamics.
Edited by D.D. Heibert and M. Eichberg, New York: McGraw-Hill
Book Company, 1983.
Standard Beam Stiffness Matrix Przemieniecki, J. S. Theory of Matrix Structural Analysis, p. 79. New
York: McGraw-Hill, 1968.
Timoshenko Beams Oden, J. T., and E. A. Ripperger. Mechanics of Elastic Structures,
Second Edition, p. 351. New York: McGraw-Hill, 1981.
Vehicle Technology Vehicle Dynamics Terminology, SAEJ670e. Warrendale, PA: Society of
Automotive Engineers, Inc., 1978.
Adams Solver Glossary

This glossary defines terms that may be unfamiliar to you or that have meanings peculiar to the Adams Solver
documentation. The terms are listed alphabetically.
A B C D E F G H I J K L M
N O P Q R S T U V W X Y Z
A
Action-Only Force
A force that has one point of action and has no points of reaction.
Action-Reaction Force
A force that causes equal and opposite forces at its points of attachment
B
Base Frame
A reference frame with respect to which you position and orient another reference frame. For example, if you
define the position and orientation of a marker with respect to a body coordinate system (BCS), the BCS is
the base frame.
11
About Adams Solver
C
Command
Any interactive instruction that Adams Solver or the postprocessor accepts.
Constitutive Equation
A tensor equation that establishes a relation between statical and kinematical tensors. For example, the
following constitutive equation for a field force relates the statical force tensor (Fi) to the kinematical
displacement tensor (Uj) and velocity tensor (Vj) by means of stiffness (Kij) and damping (Cij) matrices,
respectively:
Fi = - (Kij * Uj) - (Cij * Vj)
D
DAE
Differential Algebraic Equation
DIFSUB (integrator)
An integrator written by C. W. Gear to solve stiff ODEs. MSC has modified this integrator to solve stiff
DAEs. This integrator is unrelated to the Adams Solver subroutine that is known by the same name. For
more on the DIFSUB integrator, see:
 Gear, C.W. Numerical Initial Value Problems in Ordinary Differential Equations. New Jersey:
Prentice-Hall.
Discrete Function
A function that you define with a set of data points rather than with a continuous equation.
Dynamic Analysis
An analysis, performed over time, of a system that relies on inertial effects to determine motion.
E
Euler Singularity
A singular matrix that results when the second Euler angle is zero. Therefore, the first and third Euler angles
are not uniquely defined, and this results in a singular Jacobian matrix.
F
Force
An effect that has magnitude and direction and that causes motion of a rigid part when there is no other
external effect on the rigid part. In Adams Solver, force sometimes refers to both translational and rotational
forces.
12 Adams Solver
H
Holonomic
An adjective associated with system constraints. A holonomic constraint equation is an equality configuration
constraint equation that can be expressed in the form F(q,t) = 0, where q denotes the system generalized
coordinates and t is time. The function need not be a function of time.
I
Integration Step
The steps at which Adams Solver integrates. Adams Solver varies the size of these steps as necessary to obtain
an accurate solution, to stay within the error limits you specify (if any), and to converge to a solution.
J
Joint
A system element that connects two parts and allows relative motion of one part with respect to another. You
must assign each joint to exactly two markers that are not in the same part.
K
Kinematic Analysis
An analysis of a mechanical model with zero degrees of freedom. Adams Solver calculates the reaction and
applied forces as well as the motion of the model.
L
Local Body Reference Frame
The local body reference frame is an orthogonal triad attached to and moving with the body. It acts as the
sole reference for defining any collection of markers that move with the body.
LU Factorization
The process of redefining a matrix, A, as a product of a lower triangular matrix, L, and an upper triangular
matrix, U:
LU = A
L and U are the factors of A.
M
Marker
A system element you use to mark the center of mass in a part, the inertia axis of a part, a boundary of a part,
the point at which a joint connects a part to another part, a point of action in a force field, or any other point
that is significant to the analysis or to the graphics output of the model. Every marker in an Adams Solver
model has a coordinate system associated with it. Adams Solver fixes each marker with respect to a part you
specify.
13
About Adams Solver
N
Nonholonomic
An adjective associated with system constraints. A nonholonomic constraint is a constraint equation that
cannot be expressed in the form F(q,t) = 0, where q is the generalized coordinate and t is time. The constraints
involve time derivatives of the generalized coordinates and are therefore often called motion constraints.
Nonstandard System Element
Any system element you describe with an Adams Solver statement that defines and passes constants to user-
written subroutine.
O
ODE
Ordinary Differential Equation
Output Step
A step at which you request output. Adams Solver varies the integration step size (see above), but writes
request information at the output steps you specify. The output step is nearly always larger than the
integration step.
P
Positioned Frame
A reference frame you position and orient with respect to another reference frame. For example, if you define
the position and orientation of a marker with respect to a BCS, the marker is the positioned frame.
Positive Semidefinite
A mathematical characteristic of a matrix. For example, the matrix K is positive semidefinite if, for any x,
transpose (x)Kx is greater than or equal to zero.
Principal Coordinate System
The coordinate system whose origin is at the part center of mass and whose axes have the same alignment
and direction as the axes of the principal moments of inertia. The part products of inertia associated with the
principal coordinate system are zero.
Program Abort
Program aborts (sometimes loosely referred to as FORTRAN crashes) occur when Adams Solver is unable to
reasonably prevent or protect against errors that cause problems for the operating system; the operating
system then responds to the error by prematurely aborting (stopping) Adams Solver execution.
Q
Quasi-Static Equilibrium Analysis
An analysis that finds the change in displacement over time without considering velocities or accelerations.
14 Adams Solver
R
Right-Hand Rule
A rule for determining the direction of a positive rotation about any axis in a right-handed reference frame.
If you point the right thumb in the positive direction along any axis, the curled fingers indicate the direction
of the positive rotation about that axis.
Rotational Force
A torque; that is, a force that causes rotation of a rigid part about the vector defining the rotational force when
there is no other external effect on the rigid part.
S
Standard System Element
A system element you describe with an Adams Solver statement that does not define and pass constants to a
user-written subroutine.
Statement
Any executable line in the Adams Solve data set. Adams Solver associates one statement with each element in
the model.
State Vector
The one-dimensional array of system variables defined by the equation set.
Static Equilibrium Analysis
An analysis of a mechanical system at the configuration at which all forces are equilibrated and all velocities
and accelerations are zero.
System Element
A mechanical characteristic of the system that you describe with an Adams Solver statement.
Symbolic Factorization
The map of the elements of a matrix, A, onto its lower and upper triangular factors, L and U. Once this map
has been computed, it can be stored for multiple uses for other matrices with identical structures but with
different numerical values.
Symbolic Refactorization
The process of redefining the symbolic factorization of a matrix after a previous factorization has resulted in
a singular matrix.
T
Translational Force
A force that causes rectilinear translation of a rigid part in the same direction as the translational force when
there is no other external effect on the rigid part.
15
Using Adams Solver
Using Adams Solver

Command File
Creating an Adams Solver Command File

This section explains how to create a command file. Learn about Command File Syntax.
Using a text editor, enter the commands you want to use to control your simulation, using the following
guidelines. There are two conventions to write the commands:
First two lines define model dataset name and output prefix
 The first line must contain the name of your dataset file.
 The second line is the prefix name you want assigned to the output files that Adams Solver creates.
 The following lines contain all of the different commands you want Adams Solver to use while
performing the simulation.
 The last line in your file contains the STOP command.
You should save the file with the extension .acf, although it is not required.
Example
compressor.adm ! First line: model dataset filename
run1 ! Second line: output prefix.
output/noseparator
simulate/transient, &
end=2, dtout=0.1
deactivate/motion, id=201
simulate/transient, end=5, dtout=0.01
16 Adams Solver
stop
First line is empty

 The first line must be empty (no comments are allowed).
 The next lines must either comments or a FILE command that defines a model.
 Once a model is defined, next lines contain all of the different commands you want Adams Solver to
use while performing the simulation.
 The last line in your file contains the STOP command.
You should save the file with the extension .acf, although it is not required.
Example
file/model=compressor.adm, output=run1 ! Second line (first line is
empty)
simulate/transient, &
end=2, dtout=0.1
deactivate/motion, id=201
simulate/transient, end=5, dtout=0.01
stop
In this example, the name of the dataset is compressor.adm and the base name that is assigned to all of the
output files Adams Solver creates is run1 (run1.msg, run1.out, and so on). The next four lines are identical
to the example above. The simulation is finally terminated with the STOP command.
In Adams View, you can create a simulation script, which is analogous to the Adams Solver command file.
To do this, select Simulate -> Simulation Script -> New, and then change Script Type to Adams Solver
Commands. The only difference is that the model name and output results name (the first two lines of the
Adams Solver command file) should not be used.
Command File Syntax

Adams Solver commands generally follow the syntactical rules governing Adams Solver statements.
Exceptions and special cases are:
 Angles
 Arguments
 Continuations
 Comments
Angles
Adams Solver generally assumes all angular data in an Adams Solver command is in radians. Therefore, if you
want to use degrees as the input value for your angular data instead of the default, use a D after the value to
indicate degrees.
17
Using Adams Solver
Arguments
If Adams Solver finds one of the following syntactical errors in the arguments of a command, then the code
issues an error message and ignores the entire command.
 An invalid number of values for an argument.
 An ambiguous argument abbreviation.
 An invalid value type for an argument (for example, you input a character value and the argument
requires a numeric value or you input a real number with a nonzero fractional part and the
argument requires an integer).
 Omission of a required argument or a required value for an argument.
If you assign an argument value that is not a member of the set of permissible values for that argument,
Adams Solver issues an error message and ignores the argument, but executes the rest of the command.
Continuations
Adams Solver allows a command line to be at most eighty characters long. To input a command that is more
than one line long, put an ampersand (&) as the last character of the input line. If you are entering commands
interactively, Adams Solver responds by asking you to type in the next line. You can enter as many lines of
input as you like.
Comments
Comments on any line start with a "!". All characters after the "!" are ignored.
Modeling and Simulating Process

This explains the general mechanical system modeling and simulating process you should follow when using
Adams Solver.
Process Overview
The figure below shows the steps in the modeling and simulating process. Although the steps that you
perform to model and simulate a mechanical system are listed as though you build the entire model at once
and then test, review, and improve it, you should build and test small elements of your model before building
the entire model. For example, create a few parts, connect them together, and then run a simulation. This
way you can ensure that each element works before moving on to the next step. This is referred to as the
crawl-walk-run approach.
Learn more about:
 Build
 Test
 Review
 Improve
18 Adams Solver
19
Using Adams Solver
Building Your Model

You define the elements of your model in a dataset. The dataset is an ASCII/text file you create using any
text editor or preprocessor to enter the Adams Solver statements that describe each element of the model.
For more information about Adams Solver datasets, see Working with Adams Solver Datasets.
The build step in the process includes:
 Idealizing the mechanical system so it can be represented mathematically. This involves deciding:
• How many parts really need to be modeled.
• How to connect the parts to represent the movement of the physical system.
• Which compliant connections need to be modeled.
• Which environment forces need to be modeled.
 Selecting the units.
 Creating the basic elements. This involves:
• Creating the parts of your model.
• Adding constraints to define movement.
• Defining forces that act on your model.
 Adding system equations.
 Including requests to Adams Solver to output specific data.
Testing Your Model

After you define the model in a dataset, you can run a simulation using Adams Solver commands to verify
its performance characteristics and response to a set of operating conditions.
We recommend that you simulate your model at various times during the building step. This allows you to
more readily find and correct any mistakes in the model. You can also set up simulations so that they are
interactive, allowing you to control and refine the simulation. During the simulation, Adams Solver solves a
set of equations of motion for your model.
Reviewing the Results

As you create your model, it’s important to consider the results you want. In general, it is best to output any
information you think is useful for model verification or system analysis. When you run a dynamic,
kinematic, or quasi-static simulation, Adams Solver outputs data at the fixed intervals you specify. These
fixed intervals are known as output time steps. When you run a static simulation, Adams Solver outputs data
only once.
You can request that Adams Solver output data for displacements, velocities, accelerations, reaction forces,
applied forces, user-defined variables, generic system elements, as well as system modeling element inputs
and outputs. Adams Solver writes all the data you request to a request file at each output time step. Adams
PostProcessor can read this file for plotting purposes. Plots are often useful for studying the specific behavior
20 Adams Solver
of a model. For example, if you needed to know the maximum translational loading at a joint, you could plot
the translational reaction forces at the joint over the course of the entire simulation and quickly determine
the maximum load. Figure 1 below shows a plot of the translational reaction forces in the translational joint
between the base and the upper link of a robot arm. For more information about the wide scope of tools
available in Adams PostProcessor for reviewing the response of your system, see the online help for Adams
PostProcessor.
Figure 1 Plot of Translational Joint Reaction Force
Adams Solver also outputs graphical data at each output step to the graphics file. Graphical output is often
useful for animating the overall behavior of the model and identifying specific problems, such as:
 Improper connectivity
 Misapplied motions or forces
 Unwanted oscillatory behavior
 Clearance problems
Figure 2 shows an animation with superimposed frames.
Figure 2 Superimposed Frames from the Animation of a Robot Arm

21
Using Adams Solver
Improving Your Model

After you have run initial simulations to determine the basic motion of your model, you can improve and
refine your model by adding more complexity to it. You can edit the dataset using more advanced statements
or replace simple function expressions with subroutines. After you modify the dataset, run more simulations
to verify the model.
When you have exhausted the features available in Adams Solver, you can transfer your model to Adams View
to add even more complexity. For example, using Adams View, you can establish parametric relationships
among modeling elements that allow you to perform design sensitivity studies to compare alternative designs.
For more information about the features available in Adams View, see Adams View.
For a detailed explanation of the subroutines available in Adams Solver, see Welcome to Adams Solver Subroutines.
Datasets
Working with Adams Solver Datasets

After you create an idealized model on paper and determine the units you want to work in, you are ready to
create your model in Adams Solver by entering statements and function expressions in the dataset. Most
statements define a model element. These include the specification of mass and inertia properties, geometry,
and connectivity, as well as analysis control and output specification. Each function expression, in general,
evaluates a mathematical equation and returns that value to the statement.
The following statements allow you to use the function expressions as part of the element definition:
 DIFF
 SFORCE
 GFORCE
 VARIABLE
 MOTION
 VFORCE
 REQUEST
 VTORQUE
 SENSOR
If you can develop an equation describing the desired characteristic and are familiar with FORTRAN syntax,
you have the knowledge to write a correct Adams Solver function expression.
You use a text editor to enter the statements and function expressions in a file. The file is called the Adams
model definition file or the dataset. Each statement consists of an identifier and a set of keywords that qualify
the statement. You can specify most system properties and data in the dataset.
Organizing the Dataset

You always start your dataset with a TITLE statement and end it with an END statement. The statements,
function expressions, and comments between the TITLE and END statements constitute the body of the
dataset. You can define statements in any order without affecting the results of an analysis. Carefully
arranging them, however, can greatly increase dataset readability and simplify debugging, mode sharing, and
22 Adams Solver
modification. This section suggests two methods for organizing datasets and discusses the implications of
each.
The following sample structure shows a dataset for a piston-crank mechanical system. The geometric
information in the dataset describes the model in the top dead-center position.
PISTON COMPRESSOR SAMPLE dataset
!****** PARTS AND THEIR MARKERS ****************************

PART/01, GROUND GROUND—PART 01
MARKER/0103 GLOBAL REFERENCE FOR REQUESTS
MARKER/0102, QP=0,0,-2 REVOLUTE JOINT TO CRANK
MARKER/0108, QP=12,0,0 TRANSLATIONAL JOINT,
, REULER=90D,90D,0 TO PISTON
MARKER/0109, QP=12.286,0,0 GAS FORCE APPLICATION POINT
PART/02, MASS=2, CM=0201 CRANK—PART 02
, IP=5,6,10
MARKER/0201, QP=0,0,-3 CENTER OF MASS
MARKER/0202, QP=0,0,-2 REVOLUTE JOINT TO GROUND
MARKER/0203 GRAPHICS MARKER
MARKER/0204, QP=2,0,0 SPHERICAL JOINT TO ROD
PART/03, MASS=1, CM=0305 ROD—PART 03
, IP=1.5,1.6,3, QG=2,0,0 BCS IN GLOBAL POSITION
MARKER/0305, QP=4,0,0 CENTER OF MASS
MARKER/0304, QP=0,0,0 SPHERICAL JOINT TO CRANK
MARKER/0306, QP=8,0,0 UNIVERSAL JOINT TO PISTON
PART/04, MASS=.5, CM=0407 PISTON—PART 04
, QG=10,0,0 BCS IN GLOBAL POSITION
, REULER=90D,90D,0
MARKER/0406, ZP=0,1,0 UNIVERSAL JOINT TO ROD
, XP=0,0,1
MARKER/0408, QP=2,0,0 TRANSLATIONAL JOINT TO
, REULER=90D,90D,0 GROUND AND GAS FORCE
MARKER/0409, QP=2,0,0 VISCOUS FORCE
, REULER=90D,90D,0
!****** CONSTRAINTS ****************************************

JOINT/0201, REVOLUTE CRANK TO GROUND
, I=0202, J=0102
JOINT/0302,SPHERICAL ROD TO CRANK
, I=0304, J=0204
JOINT/0403,UNIVERSAL PISTON TO ROD
, I=0406, J=0306
JOINT/9401,TRANSLATIONAL PISTON TO GROUND
, I=0408, J=0108
MOTION/0201, JOINT=0201, ROT SPECIFIED CRANK MOTION
, FUNCTION=POLY(TIME, 0, 0, 360D)
!****** FORCES**********************************************
SFORCE/0401, I=0408, J=0109 PISTON VISCOUS DAMPING
, TRANSLATION
, FUNCTION=POLY(VR(408, 109), 0, 0, -0.2)
SFORCE/0104, I=0409, J=0109 ISENTROPIC GAS FORCE
, TRANSLATION
23
Using Adams Solver
, FUNCTION=1422.0 * DM(0409, 0109) ** (-1.4) - 185.4

!****** REQUEST OUTPUT***************************************
REQUEST/01, DISPLACEMENT, I=0201, J=0103
, COMMENT=CRANK CENTER OF MASS DISPLACEMENT
REQUEST/02, ACCELERATION, I=0201, J=0103
, COMMENT=CRANK CENTER OF MASS ACCELERATION
, COMMENT=ROD CENTER OF MASS DISPLACEMENT
, COMMENT=ROD CENTER OF MASS ACCELERATION
, COMMENT=PISTON CENTER OF MASS DISPLACEMENT
, COMMENT=PISTON CENTER OF MASS ACCELERATION
REQUEST/07, FORCE, I=0202, J=0102
, COMMENT=CRANK/GROUND REACTION
, COMMENT=ROD/CRANK REACTION
, COMMENT=PISTON/ROD REACTION
, COMMENT=PISTON/GROUND REACTION
, COMMENT=PISTON VISCOUS DAMPING
, COMMENT=GAS PRESSURE FORCE
!****** GRAPHICS OUTPUT*************************************
GRAPHICS/0201 CRANK OUTLINE
, OUTLINE=0201,0203,0204
GRAPHICS/0202,CYLINDER FLYWHEEL
, CM=0201, RADIUS=2
, LENGTH=-2, SIDES=20, SEG=20
GRAPHICS/0301 ROD OUTLINE
, OUTLINE=0304,0306
GRAPHICS/0401,CYLINDER PISTON RIGHT HALF
, CM=0407, RADIUS=.75
, LENGTH= 1, SIDES=20, SEG=20
GRAPHICS/0402,CYLINDER PISTON LEFT HALF
, CM=0407, RADIUS=.75
!****** SOLUTION AND OUTPUT PARAMETERS**********************
OUTPUT/ GRSAVE, REQSAVE TURN ON GRAPHICS AND REQUEST FILES
END
The TITLE statement in the example is PISTON COMPRESSOR SAMPLE DATASET. Note that the
statements are in blocks or sections separated by blank lines. In some cases, the comments occupy entire lines;
and in other cases, the comments occupy parts of lines following executable statements. Adams Solver
requires neither sections nor comments, but both increase dataset readability.
You can organize the dataset into six major sections:
 Parts and their markers
 Constraints
24 Adams Solver
 Forces
 Request output
 Graphics output
 Solution, execution, and output parameters
When you have part drawings that provide the markers with respect to separate body coordinate systems
(BCS), this organization is particularly convenient. The major disadvantage of this organization is that it
separates statements for joints, forces, and requests from the MARKER statements to which they refer. For
example, the two MARKER statements that define a joint are beneath the PART statements and not with
the JOINT statement. In short, this organization makes it necessary to search the dataset to find all the
information you need concerning a particular system element, but it is hierarchically organized.
The following sample structure is an alternate organization scheme for the piston-crank mechanical system.
This structure emphasizes a relational organization of data.
PISTON COMPRESSOR SAMPLE dataset
!********PART MODULES *************************************

PART - (01) GROUND
PART/01,GROUND
MARKER/01 GLOBAL REQUEST REFERENCE
PART - (02) CRANK
PART/02, MASS=2, CM=02
, IP=5, 6, 10
MARKER/02, QP=0,0,-3 CENTER OF MASS
REQUESTS
, COMMENT=CRANK CG DISPLACEMENT
, COMMENT=CRANK CG ACCELERATION
GRAPHICS
GRAPHICS/01, OUTLINE=03,04,05 CRANK OUTLINE
GRAPHICS/02, CYLINDER, CM=03 FLYWHEEL
, RADIUS=2, LENGTH=-2
, SIDES=20, SEG=20
MARKER/03, QP=0,0,-3 GRAPHICS MARKER
MARKER/04, QP=0,0,0 GRAPHICS MARKER
PART - (03) ROD
PART/03, MASS=1, CM=06, IP=1.5, 1.6, 3
REQUESTS
, COMMENT=ROD CENTER OF MASS DISPLACEMENT
, COMMENT=ROD CENTER OF MASS ACCELERATION
GRAPHICS
GRAPHICS/03, OUTLINE=07,08 ROD OUTLINE
PART - (04) PISTON
PART/04, MASS=.5, CM=09
25
Using Adams Solver
REQUESTS
, COMMENT=PISTON CENTER OF MASS DISPLACEMENT
, COMMENT=PISTON CENTER OF MASS ACCELERATION
GRAPHICS
GRAPHICS/04, CYLINDER, CM=10 PISTON RIGHT HALF
, RADIUS=.75, LENGTH=1, SIDES=20, SEG=20
GRAPHICS/05, CYLINDER, CM=10 PISTON LEFT HALF
, RADIUS=.75, LENGTH=-1, SIDES=20, SEG=20
, REULER=90D,90D,0
!**********CONSTRAINT MODULES*******************************
CONSTRAINT - (REVOLUTE) CRANK ON GROUND
JOINT/01, REVOLUTE, I=11, J=12
MARKER/11, PART=02, QP=0,0,-2 CRANK MARKER
MARKER/12, PART=01, QP=0,0,-2 GROUND MARKER
, COMMENT=CRANK/GROUND REACTION
CONSTRAINT - (SPHERICAL) ROD ON CRANK
JOINT/02, SPHERICAL, I=13, J=14
MARKER/13, PART=03, QP=2,0,0 ROD MARKER
MARKER/14, PART=02, QP=2,0,0 CRANK MARKER
CONSTRAINT - (UNIVERSAL) PISTON ON ROD
JOINT/03, UNIVERSAL, I=15, J=16
MARKER/15, PART=04, QP=10,0,0 PISTON MARKER
, ZP=10,1,0, XP=10,0,1
MARKER/16, PART=03, QP=10,0,0 ROD MARKER
, COMMENT=PISTON/ROD REACTION
CONSTRAINT - (TRANSLATIONAL) PISTON ON GROUND
JOINT/04, TRANSLATIONAL, I=17, J=18
, REULER=90D,90D,0
MARKER/18, PART=01, QP=12,0,0 GROUND MARKER
, REULER=90D,90D,0
, COMMENT=PISTON/GROUND REACTION
CONSTRAINT - (MOTION) GROUND MOTION ON CRANK
MOTION/01, JOINT=01, ROT, FUNCTION=POLY(TIME, 0, 0, 360D)
!********** FORCE MODULES***********************************
FORCE - (SFO) PISTON VISCOUS DAMPING
SFORCE/01, I=19, J=20, TRANSLATION
, FUNCTION=POLY(VR(19, 20), 0, 0, -0.2)
MARKER/20, PART=01, QP=12.286,0,0 GROUND MARKER
, COMMENT=PISTON VISCOUS DAMPING
FORCE - (SFO) ISENTROPIC GAS PRESSURE FORCE
, FUNCTION=1422.0 * DM(21, 22) ** (-1.4) - 185.4
26 Adams Solver

MARKER/22, PART=01, QP=12.286,0,0 GROUND MARKER
, COMMENT=ISENTROPIC GAS PRESSURE FORCE
!********** SOLUTION AND OUTPUT PARAMETERS*******************

OUTPUT/ GRSAVE, REQSAVE ENABLE GRAPHICS AND REQUEST
FILES
Although the second sample dataset defines the same model as the first, the two differ in their organization.
Note that in the second sample dataset, the statements and comments are in four sections rather than in six.
The four sections are for:
 Parts
 Constraints
 Forces
 Solution, execution, and output parameters
Note that at time zero, the BCS of each part has the same location and orientation as the global coordinate
system or ground.
The major advantage of this dataset organization is that it groups MARKER statements with the statements
for parts, constraints, forces, and requests to which they refer. In addition, the position and orientation of
each BCS is the same; so to superimpose two markers for a joint, you simply input the same geometric data
for them. To describe any point in more than one part, constraint, force, or request, this organization requires
that you use multiple MARKER statements so that each MARKER statement is used only once. This dataset
organization decreases the time you spend searching for data and makes the dataset easier to modify.
In general, when you define parts with respect to the BCS, an organization like the one in the first sample
dataset is easier to use. However, if you are superimposing all the BCS on the global coordinate system, an
organization like the one in the second sample dataset is easier to use. The primary objective, of course, is to
find an organization that works best for you and for the types of models you are defining. In some cases, you
may find it useful to employ a dataset organization other than these two.
Using Statements to Define Your Model

These sections explain how to use statements to define your model:
 Formatting Statements
 About Arguments
 Understanding Statement Syntax
Formatting Statements
The figure below shows the general format for all Adams Solver statements.
27
Using Adams Solver
Every statement, except the TITLE statement, includes a name that indicates the statement type. Most
statements require:
 Slash (/) delimiter
 Identifier (id)
 One or more arguments (ARG1,...,ARGn)
Statement arguments can indicate:
 Condition
 Values (,...,vn)
 Character string (c) with values
 Expression (e)
About Arguments
You can classify arguments into three categories:
 Conditional - These arguments are of the form ARGUMENT.
 Assignment - These arguments are of one of two forms:
• ARGUMENT={v1[,...,vn]}
• ARGUMENT={c1[:...:cn]}
 Function expression - These arguments are of the form:
• ARG=e
• ARG=USER(r1[,...,r30])
A different set of arguments characterizes each Adams Solver statement. If you do not include mandatory
arguments, Adams Solver outputs an error message and stops execution after the input phase. Some of the
arguments in a statement may be optional; therefore, the number of arguments you use for a statement can
vary. Argument order can also vary without changing the overall meaning of a statement. For example, the
argument order in the statements below differ, but they provide Adams Solver with the same information.
REQUEST/04, I=0304, FORCE, J=0204
Although it is unnecessary to order arguments in a consistent fashion, such a practice facilitates locating
argument information. The following sections describe each argument category and its distinctive attributes
28 Adams Solver
Conditional Arguments
Arguments that specify a quality are named conditional arguments. Conditional arguments do not explicitly
contain any argument values. They consist solely of the argument key word. For example, consider the
following SFORCE statement:
SFORCE/0104, I=0408, J=0109
,TRANSLATION
,FUNCTION=1422.0 * DM(0408, 0109) * * (-1.4) - 185.4
The conditional argument in this statement is TRANSLATION, which specifies that the force is
translational instead of being rotational.
Assignment Arguments
Arguments that assign one or more values to a statement attribute are named assignment arguments. Each of
these arguments consists of:
 Argument key word
 Equal sign
 Set of values you want to assign to the attribute
In example formats, lower-case terms indicate the types of values that are to follow the argument key word.
The types of values can be:
 Identifiers (id1,...,idn)
 Cartesian coordinates (x, y, z)
 Angular values (a, b, c)
Which can take the form of:
 Integers (i1,...,in)
 Real numbers (r1,...,rn)
 Character strings (c1:...:cn)
In some cases, arguments accept more than one kind of value; their formats specify varying types (v1,...,vn).
Regardless of the kinds of values you enter for an assignment argument, you must precede all values except
the first with either a comma or a colon. A comma must separate numerical values and a colon must separate
character strings. You may break assignment arguments for a statement before any comma or colon. If you
break the argument before a comma, do not retain the separating comma.
The following PART statement includes the assignment arguments MASS, CM, IP, and QG:
PART/03, MASS=1, CM=0305
,IP=1.5,1.6,3, QG=2,0,0
Here, the value or values following indicate:
 MASS keyword indicates the value of the mass of the part.
 CM indicates the identifier of the part center-of-mass marker.
 IP indicates the three principal mass moments of inertia of the part about the part center-of-mass
marker location.
29
Using Adams Solver
 QG indicates the initial coordinates of the BCS of the part with respect to the global coordinate
system.
Function Arguments
Arguments that allow you to define their values with a FORTRAN-like expression in the dataset or with an
external user-written subroutine are called function-expression arguments. Each of these arguments consists
of the argument, an equal sign, and an expression that Adams Solver can evaluate.
There are two types of function-expression arguments:
 Define an expression (e).
 Pass constants to a user-written evaluation subroutine (USER=).
The following are examples of the two types of function-expression arguments:
 The MOTION statement below, includes a function-expression argument that uses an expression
to compute a MOTION.
MOTION/0201, JOINT=0201, FUNCTION=POLY(TIME,0,0,360D)
 The statement below includes a function-expression argument that defines constants Adams Solver
is to pass to the user-written subroutine MOTSUB:
MOTION/0201, JOINT=0201, FUNCTION=USER(0, 0, 6.28)
In the first example, the expression specifies the four values Adams Solver is to pass to the POLY function to
determine the motion. In most cases, defining an expression is easier than writing and then passing values to
a user-written subroutine as done in the second example. To find out more about user-written subroutines
and the Adams Solver utilities you can access from user-written subroutines, see Welcome to Adams Solver
Subroutines. You can break a function expression for continuation anywhere except:
 In the middle of a number
 In the middle of a function name
 Between a function name and the left parenthesis that follows it
If you break the expression before a comma, you must retain the comma (in addition to the continuation
comma).
To terminate a function expression, you must put the function expression argument last in your statement
or put a backslash at the end of the expression to explicitly specify the end of the expression.
Understanding Statement Syntax

Like all languages, the statements specifying a model definition must follow certain syntactical rules. Adams
Solver relies on these rules to decode a statement and understand it. The next sections explain the syntactical
rules that govern statement definitions and their interpretation:
 Angles
 Arguments
 Blanks and Tabs
 Comments
30 Adams Solver
 Continuations
 Delimiters
 Identifiers
 Numbers
 Statements
Angles
 Adams Solver assumes all angular data is in radians, unless indicated otherwise.
 If you want to indicate that angular values are in degrees, follow the values with a D, as in these
examples.
45.D
45D
1.E-3D
D does not specify double precision in Adams Solver as it does in FORTRAN. In Adams Solver, a D
after a number indicates that the number is to be scaled by the factor π ⁄ 180 .
 All output angular data defaults to radians, except for the rotational displacement data in the tabular
output file. If you want to scale angular displacement output from degrees to radians, use the
DSCALE argument on the OUTPUT command or statement.
Arguments
 Each argument indicates a condition, assigns a value, or evaluates an expression. Adams Solver has
three basic types of arguments, described in Formatting Statements.
 An equal sign separates the argument keyword from its values. Argument values can be in the form
of numbers (with an E added to indicate scientific notation and/or a D added to indicate degrees),
alphabetic characters, a combination of numbers and alphabetic characters, a string of words, and
function expressions.
 Five or more consecutive blank spaces in an argument (except a function expression argument) cause
Adams Solver to ignore the rest of the line (see Blanks and Tabs).
 You can abbreviate arguments. Underscores in statement formats, explained in Formatting Statements,
indicate minimum allowable argument abbreviations.
 Adams Solver accepts both uppercase and lowercase letters for arguments.
 You can arrange arguments in any order within the statement to which they belong.
 You can break function expression arguments before any comma or colon. If you break the
argument before a comma, retain the comma (in addition to the continuation comma). If you break
the argument before a colon, retain the colon. (See Continuations).
 You can break assignment arguments before any comma or colon. If you break the argument before
a comma, do not retain the comma (in addition to the continuation comma). If you break the
argument before a colon, retain the colon. (See Continuations.)
 If you do not provide an optional argument or value, Adams Solver uses the default.
31
Using Adams Solver
 Do not assign a real number value to an integer argument unless there is nothing except a zero after
the decimal point. If you assign a real number with a fractional part after the decimal point to an
integer argument, Adams Solver issues an error message.
 You can use scientific notation for both real and integer values.
 The following errors in the use of arguments cause Adams Solver to issue an error message and stop
execution at the end of the input phase:
• You assign argument values that are not numbers of the permissible set of values for that
argument.
• You input an invalid number of values for an argument.
• You input an ambiguous argument abbreviation.
• You input an invalid value type for an argument (for example, you input a character value, and
the argument requires a numeric value; or you input a real number with a nonzero fractional part,
and the argument requires an integer).
• You input two or more arguments that are mutually exclusive.
Blanks and Tabs

 Adams Solver ignores all data following five or more consecutive blank spaces on any line. There are
two exceptions to this rule: function expressions and the TITLE statement.
 Do not put blanks in numerical values.
 Blank spaces provide spacing within statements, and blank lines provide spacing between groups of
statements.
 You can have as many blank lines as you want in an Adams Solver dataset.
 Do not use tabs in Adams Solver statements. You can use tabs in comments.
Comments
 Use comments to describe statements and groups of statements. Adams Solver ignores comments.
 An exclamation point indicates to Adams Solver that the line is a comment.
 At least five consecutive blank spaces also indicate a comment everywhere, except within a function-
expression argument. Within a function-expression argument, five blank spaces do not cause Adams
Solver to stop reading the line.
 An Adams Solver dataset can have any number of consecutive or nonconsecutive comments.
 A comment can be on any line between the TITLE statement and END statement. (Adams Solver
does not read beyond the END statement.) A comment can be in the middle of a statement or even
in the middle of an argument, but if a comment is an entire continuation line, it must start with
either a continuation character (See Continuations below) or an exclamation mark.
32 Adams Solver
Continuations
Commas in column one are used to indicate continuation lines. To continue a statement on the next line,
break the line before any statement comma or colon and put a continuation comma in column one of the
following line before the rest of the statement.
 If you break the statement at a comma directly preceding an argument, you do not need to retain the
comma preceding the argument.
 If you break the statement before a comma within a function-expression argument, use both the
comma separating the values within the argument and the continuation comma.
 If you break the statement before a comma within an assignment argument, use only one comma.
 If you break the statement before a colon in either type of argument, retain the colon.
Alternately, ampersands (&) can indicate continuation lines. To continue a statement on the next line, break
the statement before any statement comma or colon and put an ampersand after the last statement character
on the line to indicate that the following input line is a continuation of the line with the ampersand. Because
Adams Solver ignores all comments, putting an ampersand after the comment does not indicate to Adams
Solver that the following input line is a continuation line. You cannot use an ampersand to continue a
function expression on the next line. If you must continue a function expression on the next line, use a
comma in the first column of the new line as described above.
Delimiters
Delimiters allow Adams Solver to interpret input, and they make datasets easier to read. Adams Solver
commonly requires or allows six delimiters:
 Slash - Separates a statement name from the remainder of the statement.
 Equal sign - Separates an argument key word from a value or a set of values.
 Comma - Separates arguments within a command and separates multiple integer values (i1,...,in)
and multiple real values (r1,...,rn) within multiple valued arguments.
 Backslash - Instead of the comma, separates a function-expression argument from any arguments
that follow it.
 Semicolon - Separates two statements on the same line.
The following errors in the use of delimiters cause Adams Solver to issue an error message and stop execution
at the end of the input phase:
 You do not use a delimiter when it is required. For example, you omit the backslash between a
function expression argument and the following argument.
 You use a delimiter when it is not allowed.
 You use two or more delimiters when only one is allowed. For example, you use two commas
between two arguments on the same line.
Identifiers
 Identifiers distinguish statements of the same type.
33
Using Adams Solver
 In a dataset, you should not have two or more statements with the same name and the same
identifier (for example, two GRAPHICS statements with the same identifier). If your dataset does
include two or more statements with the same name and the same identifier, Adams Solver issues
one or more warning messages and stores the last instance only. Not all statement types require an
identifier.
 If a statement type requires an identifier, the identifier string must follow a slash.
 The identifier you assign to a statement can be any positive integer with eight or fewer digits.
 The following errors in the use of identifiers cause Adams Solver to issue an error message and stop
• You omit a statement identifier that Adams Solver requires.
• You use a statement identifier that is negative, is a real number, or is a positive integer with more
than eight digits.
 If you include a statement identifier with a statement that does not require an identifier, Adams
Solver issues a warning message and ignores the identifier.
Numbers
 A real number is a number with a decimal point and/or a fractional part behind the decimal point.
 A single plus or minus sign can precede any number or exponent. Use of the plus sign is optional.
 Numbers must not contain blanks or commas.
 If a number contains a decimal point and/or an exponent, Adams Solver interprets it as a real
number.
 Adams Solver stores real numbers in a format that retains approximately fifteen significant digits in
32-bit machines.
 If a number does not contain either a decimal point or an exponent, Adams Solver interprets it as an
integer. You may assign an integer value when Adams Solver expects a real argument. However, if
you do this, Adams Solver converts the integer to a real number before storing it.
 Integer values input to Adams Solver must be greater than -231 -1 and less than +231 -1.
 You can assign a real number value when Adams Solver expects an integer if the fractional part of
the real number is zero. If you do this, Adams Solver converts the real number to an integer before
storing it.
 You can input exponents for real numbers and integers you assign to real arguments. The exponent
indicates an integer power of ten by which Adams Solver is to multiply the mantissa. To indicate the
exponent, immediately follow the number with an E (this is consistent with the E in FORTRAN).
Then, follow the E with the positive or negative integer exponent. The allowable range for
exponents depends on the particular computer on which you are running Adams Solver. The
following are examples of numbers with valid exponents:
.314159E1
314159E01
314.159E-02
314159E+2
34 Adams Solver
 Internally, Adams Solver uses radians for angular units. Adams Solver includes a degrees-to-radians
conversion factor to allow for easy conversion of degree quantities to radian quantities. Put a D
immediately following a number that you want Adams Solver to scale by that conversion factor.
Adams Solver multiplies the number by π ⁄ 180 before storing it.
You can use this conversion factor for any number in the dataset, including numbers in function
expressions. But this conversion factor is especially useful when you are assigning values to
arguments that expect angular quantities. For example, Adams Solver converts the argument:
REULER = 90D, 180.0D, 2.70E+2D
to
REULER = 1.5708, 3.1416, 4.714

before storing the information. D does not specify double precision in Adams Solver as it does in
FORTRAN.
 The following errors in the use of numbers cause Adams Solver to issue an error message and stop
• You include a fractional part other than zero in a real number you input for an integer argument
value.
• You include a blank or a comma in a number.
Statements
 A statement must begin in one of the first five columns of the line. If it does not, Adams Solver treats
it as a comment and does not read it.
 Statements can be defined only between column 1 and column 80.
 To continue a statement that is longer than eighty columns, use an ampersand (&) after the last
statement character in the line to be continued or use a comma as the first character in all
continuation lines (see Continuations). If you use the ampersand, the last statement character can be in
the seventy-ninth column at most because the ampersand would then have to be in the eightieth
column.
 Adams Solver can read two or more statements on the same line if they are separated by semicolons.
 You can abbreviate statement names. Underscores in statement formats, indicate minimum
allowable abbreviations. See C++ Statements.
 Adams Solver accepts both upper- and lower-case letters for statement names.
 Because the TITLE statement is read but not executed, it can include any combination of printable
characters and blank spaces.
 The following errors in the use of statements cause Adams Solver to issue an error message and stop
• You do not include all required arguments in a statement.
• You put two or more statements on the same line without semicolons separating them.
35
Using Adams Solver
• You continue a statement on the following line without either an ampersand at the end of the
first line or a comma at the beginning of the following line.
Understanding Adams Solver Modeling Concepts

This document contains the general modeling concepts of mechanical system simulation, and explains how
Adams Solver interprets the information you provide when defining a mechanical system. It contains the
sections:
 Vectors
 Reference Frames
 Coordinate Systems
 Positioning Methods
 Local versus Global Geometric Data
 Degrees of Freedom
 Force Direction and Application
Vectors
Vectors in Adams Solver are defined as quantities having magnitude and direction. They are used in
mechanical system simulation to define and measure the movement of bodies, such as displacement, velocity,
and acceleration. Vectors are also used to apply and measure forces in a mechanical system.
Unit vectors (where magnitude is equal to one) are most commonly used to define the direction portion of
vector quantities. For example, you can use unit vectors to define the direction along which displacement,
velocity, or acceleration occurs or to define the direction in which a force is applied.
Reference Frames
A reference frame specifies a reference for the calculation of velocities and accelerations in a mechanical
system. Reference frames do not have any graphic representation, but are used when specifying function
expressions which represent time derivatives of vector quantities. There are two types of reference frames in
Adams Solver:
 Ground coordinate system (GCS) - The GCS is the single Newtonian or inertial reference that
establishes absolute rest. By definition, any point attached to the GCS has zero velocity and
acceleration. Such a point is fixed in absolute space.
Adams Solver expresses Newton's Laws with respect to the GCS. For many applications, you can
consider the earth as a Newtonian reference frame, even though it travels in an elliptical path about
the sun and is therefore accelerating, and rotates on its own axis.
 Body coordinate system (BCS) - Every rigid body has one reference frame, named the BCS.
36 Adams Solver
Coordinate Systems
A coordinate system (CS) is essentially a measuring stick used to define kinematic and dynamic quantities.
Coordinate systems usually consist of an origin and a set of three mutually-perpendicular unit vectors that
specify three directions. Associated with each of these directions is a scale that permits measurement of
quantities with respect to that coordinate system. You can specify all kinematic and kinetic vector quantities
ˆ ˆ ˆ
as projections of the vector along three mutually-perpendicular unit vectors, x , y , and z , as shown in the
example of a Coordinate System and Vector below.
The example below illustrates a vector, R, that is defined as the displacement of point P with respect to point
O. For example, R x, R y, and R z are defined as the measure numbers of R along the x̂ G , ŷ G , and ẑ G axes,
respectively, of the global coordinate system.
Example of a Coordinate System and Vector
In Adams Solver, you use coordinate systems to define:

 Location or orientation of other coordinate systems.
 Point with respect to which a body's mass moments of inertia are defined.
 Axes about which a body's mass moments of inertia are defined.
 Points at which constraints are applied.
 Axes along or about which bodies are constrained to move.
 Points to which forces are applied.
 Axes along or about which forces are applied.
You can also use coordinate systems in Adams Solver to measure:
 Translational displacement of one point with respect to another point.
 Translational velocity or acceleration of one point with respect to some reference frame.
 Angular velocity or angular acceleration of one reference frame with respect to another reference
frame.
 Translational force or rotational force components acting on a body.
Adams Solver uses two types of coordinate systems, global and local, as introduced next.
37
Using Adams Solver
Global Coordinate System

The global coordinate system (GCS) rigidly attaches to the ground reference frame or the ground body. In
Adams Solver, your model has only one GCS that defines the absolute point (0,0,0) and provides a set of axes
that is referenced when creating body coordinate systems (see Body Coordinate Systems).
Local Coordinate Systems
In your model, you can use local coordinate systems to identify the location and orientation of key points
and axes. The origin of a local coordinate system defines its location or translational position in a mechanical
system, while the axes define its orientation or rotational position.
The next sections provide information about the two types of local coordinate systems: body coordinate
systems and markers.
Body Coordinate Systems

A body coordinate system (BCS) is created automatically for each rigid body you define in Adams Solver.
Every rigid body in your model has one and only one BCS. You specify the initial location and orientation of
each BCS by providing its location and orientation with respect to the GCS. The BCS defaults to the same
location and orientation as the GSC, if you do not specify a different position for it. The BCS moves with
its body.
Example of Global and Body Coordinate Systems
Markers
Markers are coordinate systems owned by a body. There is no limit on the number of markers you can have
in your model. You use markers to define any point of interest in a mechanical system such as:
 The location of a body's center of mass.
 The reference point with respect to which you specify a rigid body's mass moments of inertia.
38 Adams Solver
 A reference point for defining where you want graphical entities anchored.
 An initial location of a constraint you want to use to connect bodies together.
 A point where you want force applied to a body.
 All points where you want to measure displacement, velocity, acceleration, or force.
You can also use markers to define directions in a mechanical system such as:
 The axes about which you specify a body's mass moments of inertia.
 A direction you want to use when you specify a constrain.
 A direction you want to use when you specify a force.
 A direction you want to use when you specify graphical dimensions.
 The axes along which you want to measure displacement, velocity, acceleration, or force.
Example of Body and Marker Coordinate Systems
You have two types of markers in Adams Solver:

 Fixed markers - A fixed marker attaches to a body and moves with that body. To place a fixed marker
on a body, you must specify its location and orientation with respect to the BCS.
 Floating markers - You use a floating marker to specify sites for applying certain forces or constraints
to bodies. The force or constraint dictates the location and orientation of the floating marker.
Therefore, you do not specify a position for a floating marker. This allows the floating marker's
location and orientation to change with respect to its BCS during the simulation, as dictated by the
force or constraint.
Adams Solver forces and constraints that use floating markers include the six-component force, three-
component force, three-component torque, curve-to-curve constraint, and point-to-curve constraint.
Positioning Methods
You can tell Adams Solver the position of a local coordinate system by indicating its location and orientation.
There is only one way to locate a local coordinate system but two ways to orient it. A local coordinate system's
location is always defined the same way, regardless of the orientation method you use. In this section, the local
coordinate system that you are either locating or orienting is referred to as the positioned coordinate system
39
Using Adams Solver
and the coordinate system with respect to which you are locating or orienting it as the base coordinate system.
For example, if you are locating a BCS with respect to the GCS, the BCS is the positioned coordinate system
and the GCS is the base coordinate system. Similarly, if you locating a marker with respect to its BCS, the
marker is the positioned coordinate system and the BCS is the base coordinate system.
Note: When you locate and orient coordinate systems, remember that the BCS is always defined with
respect to the GCS and a marker is always defined with respect to the BCS of the body that owns it.
The next sections explain the Adams Solver location and orientation positioning methods.
Location Method
Adams Solver uses Cartesian coordinates to define the location of the origin of the positioned coordinate
system with respect to the base coordinate system. Cartesian coordinates are the distances to the point you
ˆ ˆ ˆ
are defining, measured from the origin and along the x , y , and z axes of the base coordinate system. The
example of the Cartesian Coordinates Location Method below shows an example of using Cartesian
coordinates to define the location of a positioned coordinate system.
Example of the Cartesian Coordinates Location Method
Orientation Methods
For orienting any BCS with respect to the GCS or any marker with respect to its BCS, you can use the
rotation sequence method or the three-point method (also known as the direction cosines method) as
explained next.
Rotation Sequence Method

The rotation sequence method used by Adams Solver to orient a local coordinate system uses rotation angles
associated with a particular sequence. Although there are 24 possible rotation sequences available, Adams
Solver uses only the body-fixed 3-1-3 (or z-x´-z´´) rotation sequence. The rotation angles associated with this
sequence are often referred to as Euler angles. When you use the Euler angles method to orient a positioned
40 Adams Solver
coordinate system, you need to define the orientation of the positioned coordinate system with respect to the
base coordinate system.
The example below of the Rotation Sequence Method (Body-Fixed 3-1-3 Euler Angles) shows how successive
rotations of Euler angles incrementally orient the axes of the positioned frame. Initially, the positioned
coordinate system has the same orientation as the base coordinate system (5a).
 The first Euler angle rotates the positioned coordinate system about its z-axis +90 degrees. This
repositions the x- and y-axes (5b).
 The second Euler angle rotates the positioned coordinate system about its new x-axis (x´) -90
degrees, to reposition the new y-axis and the z-axis (5c).
 The third Euler angle rotates the positioned coordinate system about its new z-axis (z´´) +90 degrees,
to reposition the new x-axis (x´´) and the second new y-axis (y´´).
Together and in sequence, these rotations define the orientation of the positioned coordinate system (5d).
The right-hand rule defines the direction of positive rotation about each axis. For example, if you look down
the initial z-axis, positive rotations are counterclockwise and negative rotations are clockwise.
Example of the Rotation Sequence Method (Body-Fixed 3-1-3 Euler Angles)
Because Euler angle rotations cumulatively define the orientation, you may find it difficult to imagine
orientations that involve rotations of other than 0, 45, or 90-degree increments. When orienting a coordinate
system that requires a complex combination of rotations, you may find it easier to use the three-point
orientation method, as described next.
Three-Point Method
You can use the three-point method to specify the orientation (in direction cosines) of the positioned
coordinate system relative to the base coordinate system. When you use the three-point method to orient a
positioned coordinate system, provide the following geometric data with respect to the base coordinate
system:
 Cartesian coordinates of the positioned coordinate system origin (point 1). You must specify this
point when using this method of orientation.
41
Using Adams Solver
 Cartesian coordinates of a point on the primary axis of the positioned coordinate system (point 2).
You can specify either the z- or x-axis as the primary axis of the positioned coordinate system. If you
do not specify a primary axis, the
z-axis is used by default. When it is important to exactly specify the z-axis of the positioned
coordinate system, provide the Cartesian coordinates of a point on the z-axis. When it is important
to exactly specify the x-axis of the positioned coordinate system, provide the Cartesian coordinates
of a point on the x-axis.
 Cartesian coordinates of a point that is in the x-z plane of the positioned coordinate system (point
3). Since three points in a straight line do not uniquely define a plane, you must make sure that
point 3 does not lie on the line defined by points 1 and 2. If the three points are collinear, Adams
Solver returns an error.
The example of the Three-Point Method below shows the points of the positioned coordinate system with
respect to the base coordinate system. Point 2 in the figure specifies the z-axis of the positioned coordinate
system and point 3 defines a point in the x-z plane of the positioned coordinate system. Note that in this
example, point 3 is placed directly on the x-axis of the positioned coordinate system but only needs to be in
the x-z plane.
By default, Adams Solver assumes that R 1 defines the the exact location of the coordinate system origin and
R 2 defines a point on the z-axis. Because the third point ( R 3 by default) does not necessarily lie on an axis
but happens to in this example, Adams Solver determines the vector cross product of vectors R 2 and R 3 to
form an orthogonal y-axis. Then, Adams Solver determines the vector cross product of the new y-axis and
the exact axis (the z-axis by default) to produce the orientation of the remaining axis (by default, the x-axis).
By calculating v 1 and v 2 , you can verify that the third point is in the x-z plane and that the three points
are not collinear.
42 Adams Solver
Local Versus Global Geometric Data

Regardless of the methods that you use to position the local coordinate systems, the location and orientation
of every marker with respect to the GCS is the summation of both BCS and marker positioning data. This
summation allows you to input points from a series of part drawings in which each drawing has its own BCS.
The geometric data you input to describe the location and orientation of each BCS with respect to the GCS
relates the BCS to one another.
Although the summation of the geometric data allows you to input data from part drawings with different
BCS, it can complicate the process of superimposing markers in global space and assigning parallel or
perpendicular orientations to their axes. Superimposing markers is sometimes necessary for defining joints
(superimpose one marker on one body with a second marker on another body). For example, if you define a
spherical or ball-and-socket joint, you must superimpose a marker origin at the center of the ball with a
marker origin at the center of the socket. Similarly, to allow for the proper assembly of the model, certain
joints require that one axis of a marker in one body remains parallel or perpendicular to a particular axis of a
marker in the other body.
If two markers do not have the correct origin locations or axis orientations, Adams Solver iteratively
repositions the bodies to bring the two markers to the correct position before continuing the analysis. For two
markers whose positions are reasonably close to what they should be, these iterations usually do not seriously
affect the solution process. For two markers whose positions are not reasonably close, Adams Solver might
43
Using Adams Solver
not be able to enforce the proper positioning during the initial phases of the simulation and will be unable
to solve for the model behavior. In other cases, Adams Solver may find an initial assembly position different
from the intended one, thus leading to a different solution. Consequently, when you define markers, you
must carefully specify their positions and the positions of their BCS.
Not all models describe the geometry of a mechanical system as explained above. For example, in the
automotive industry, it is common practice to dimension all the bodies in a single, and often large, drawing
of the assembly. Because Adams Solver does not require the BCS to lie within the boundaries of the bodies
to which they belong, it’s possible to superimpose all of the BCS on the GCS. When you do this, the initial
marker position with respect to the BCS is the same as the marker position with respect to the GCS. Under
these circumstances, the BCS positions are all zero. Because they default to zero if left unspecified, this
approach reduces the amount of data that you must provide.
In addition, even though you input the markers’ positions with respect to their different BCS, all markers
occupying the same position in space have identical position with respect to the GCS. In general, this
approach greatly simplifies the summation process for superimposing marker positions. When using this
approach, keep in mind that Adams Solver superimposes the disparate BCS on the GCS only at time zero.
As the model articulates during a subsequent dynamic, kinematic, or quasi-static equilibrium analysis or
settles during a subsequent static equilibrium analysis, the BCS move with their bodies with respect to the
stationary GCS.
44 Adams Solver
An example of local versus global data
Degrees of Freedom
Degrees of freedom dictate how a mechanical system is allowed to move. The following sections provide
information on understanding and calculating degrees of freedom in your model.
45
Using Adams Solver
 Removing Degrees of Freedom

 Calculating Degrees of Freedom Using the Gruebler Equation
 Checking for Redundant Constraints
Removing Degrees of Freedom

In mechanical systems, a degree of freedom (DOF) is a measure of how bodies can move relative to other
bodies. Therefore, the total number of degrees of freedom of a mechanical system is the number of
independent motions that characterize the model.
A freely floating rigid body in three-dimensional space is said to have six DOF. This implies that the body
can exhibit motion in six independent ways: three translations and three rotations. The DOF of a mechanical
system represent the minimum number of displacement coordinates needed to completely specify the system
configuration. Once you know these, you can calculate any other information pertinent to the configuration
as a function of these independent variables.
You can, of course, represent a mechanical system with more coordinates than there are degrees of freedom.
In such an instance, the coordinates are not all independent. There must be algebraic constraint equations
relating some of the coordinates. This is precisely how Adams Solver works.
For most mechanical systems, the number of degrees of freedom is constant throughout time. In some
mechanical systems, the number of degrees of freedom can change as their configurations change over time.
Adams Solver allows you to specify the position of each body in the model, regardless of the degrees of
freedom in the mechanical system. Different types of constraints constrain different combinations of motion,
thereby removing various DOF from the model. Revolute joints, for example, constrain two degrees of
rotational freedom and three degrees of translational freedom therefore allowing one degree of rotational
freedom. Cylindrical joints constrain two degrees of rotational and two degrees of translational freedom,
therefore allowing one rotational and one translation freedom. Rotational or translation motions, defined at
joints, constrain either one rotational or translational DOF, respectively. Below tables list the number of
DOF removed by Adams Solver constraints.
Table 1 Number and Types of DOF Removed by Joints

Removes number Removes number Removes total number
This joint type: translational DOF: rotational DOF: DOF:
Constant velocity 3 1 4
Cylindrical 2 2 4
Fixed 3 3 6
Hooke 3 1 4
Planar 1 2 3
Rack-and-pinion 0.5* 0.5* 1
Revolute 3 2 5
46 Adams Solver
Table 1 Number and Types of DOF Removed by Joints

Removes number Removes number Removes total number
This joint type: translational DOF: rotational DOF: DOF:
Screw 0.5* 0.5* 1
Spherical 3 0 3
Translational 2 3 5
Universal 3 1 4
* The rack-and-pinion and screw joints are shown as half translational and half rotational because they relate
a translational motion to a rotational motion. They each create one constraint, but the constraint is neither
purely translational nor purely rotational.
Table 2 Number and Types of DOF removed by Joint Primitives

This type of joint Removes Number Removes number Removes total number of
primitive: translational DOF: rotational DOF: DOF:
Atpoint 3 0 3
Inline 2 0 2
Inplane 1 0 1
Orientation 0 3 3
Parallel Axes 0 2 2
Perpendicular 0 1 1
Table 3 Number and Types of DOF removed by other constraints

Removes Removes
Removes number Removes number number new
This type of number trans. rotational mixed translational generalized Removes total
constraint DOF: DOF: & rotational DOF: DOF: number DOF:
Coupler -- -- 1 -- 1
Curve-to- -- -- -- 2 2
curve
Gear -- -- 1 -- 1
47
Using Adams Solver
Table 3 Number and Types of DOF removed by other constraints

Removes Removes
Removes number Removes number number new
This type of number trans. rotational mixed translational generalized Removes total
constraint DOF: DOF: & rotational DOF: DOF: number DOF:
Translational 1 -- -- -- 1
motion
Rotational -- 1 -- -- 1
motion
Point-to-curve -- -- -- 2 2
User-defined -- -- 1 -- 1
constraint
Calculating Degrees of Freedom Using the Gruebler Equation

To determine the total number of degrees of freedom (DOF) for a mechanical system, you can use the
Gruebler equation which is:
Degrees of freedom = [ 6 * (Number of movable bodies) ] - (Number
of constraints)
To evaluate this equation, you would count the number of movable bodies in your model and subtract the
DOF removed by the constraints and prescribed motions. Note that the body count does not include the
ground body since it does not contribute any DOF. For example, the Gruebler equation for a model that
contains three movable bodies, one rotational motion, three revolute joints, and one translational joint would
be:
DOF = ( 6 * 3 ) - ( 1 + 5 + 5 + 5 + 5 ) = 18 - 21 = -3
From this calculation, you see that the model has -3 DOF. When the Gruebler equation yields a DOF count
less than zero, it indicates that the model definitely has one or more constraints that are redundant.
If you use the same model and replace one of the revolute joints with a spherical joint and another revolute
joint with a cylindrical joint, the Gruebler equation would then be:
DOF = ( 6 * 3 ) - ( 1 + 5 + 3 + 4 + 5 ) = 18 - 18 = 0
This equation now indicates that there are zero DOF in the model. When the Gruebler equation is greater
than or equal to zero, you cannot be positive that the mechanical system does not contain constraints that
are redundant.
The Gruebler equation offers a good way to understand how the model is built, but to see if there are
redundant constraints or not, it is best to let Adams Solver perform an analysis. You will receive a message
from Adams Solver if the model contains redundant constraints. However, you do not know how many or
which ones Adams Solver sees as the redundant constraints. For information on how Adams Solver handles
models with redundant constraints, see Checking for Redundant Constraints below.
48 Adams Solver
Checking for Redundant Constraints

You can construct a legal and well-defined model where one set of joints constrain the model in exactly the
same way as another set of joints. In mathematical terms, you can state that the equations of constraint of
both sets of joints are redundant with each other.
An Adams Solver model is a mathematical idealization of a physical mechanical system. For this reason, your
model can contain redundant constraints even if you define your model with the same number and types of
joints as the physical mechanical system.
An example of a mechanical system with redundant constraints is a door supported by two hinges. In a real
door, minor violations of the hinge collinearity do not prevent the door from operating because of body
deformity and joint-play in the hinges. In the mathematical model, where the bodies are rigid and joints do
not permit any play, the two hinges are redundant but consistent when the axes of the two hinges are aligned.
If, however, the axes are not aligned, the door cannot move without breaking one of the hinges. In this case,
the two hinges are inconsistent and half of their constraints are redundant.
Adams Solver does not tolerate redundant constraints whether they are consistent or inconsistent. When
encountered, Adams Solver subjectively determines which constraints are redundant, deletes them from the
set of equations, and provides a set of results that characterize the motion and forces in the model. Note that
other solutions can also be physically realistic. Systems with redundant constraints do not have a unique
solution.
According to the Gruebler equation, an Adams Solver model with fewer than zero DOF is overconstrained.
Adams Solver can solve an overconstrained model only if the redundant constraints are consistent.
Redundant constraints are consistent if a solution satisfying the set of independent constraint equations also
satisfies the set of dependent or redundant constraint equations.
In the case of the door with two hinges, Adams Solver ignores five of the constraint equations. You,
unfortunately, do not know which equations are removed. If you assume that Adams Solver ignores all of the
equations corresponding to one of the hinges, that means that all the reaction forces are concentrated at the
other hinge in the Adams Solver solution. Adams Solver subjectively sets the reaction forces to zero at the
redundant hinge. However, as long as distribution of reaction forces maintains a constancy of the net reaction
force and torque, it also provides a correct solution.
Adams Solver does not always check joint initial conditions when it does overconstraint checking. If you
apply a motion on one joint and initial conditions on another joint, check to make sure that they are not
redundant because Adams Solver does not check them. As a general rule, you should not specify more initial
conditions than the model has degrees of freedom.
For a model with redundant constraints, constraints that are initially consistent can become inconsistent as
the model articulates over time. Adams Solver stops execution as soon as the redundant constraints become
inconsistent. Therefore, you should not intentionally input redundant constraints in your model. For
example, consider a planetary gear system with redundant constraints. Slight misalignment errors can
accumulate over time, eventually resulting in a failure of the consistency check. If this occurs, manually
remove the redundant constraints or replace them with flexible connections.
If you have redundant constraints in your model, try replacing joints with joint primitives or with
approximately equivalent flexible connections. By reviewing the messages saved in the message file after
Adams Solver tries to solves your model, you can find out how many and which redundant constraints are
being removed.
49
Using Adams Solver
Force Direction and Application

You can define any force vector in terms of its magnitude and direction. The following sections explain how
Adams Solver directs and applies the different forces available.
 Single-Component Forces
 Multi-Component Forces
Single-Component Forces
You can use two types of single-component forces in Adams Solver:
 Action-Only, Single-Component Forces
 Action-Reaction, Single-Component Forces
Action-Only, Single-Component Forces

An action-only, single-component force is an external force or torque applied to a single body in a model that
acts along a specified fixed axis. As you know from Newton’s third law, however, in nature there is no such
thing as an action-only force (that is, one with no reaction). Therefore, the body reacting to the action-only
force in Adams Solver is automatically defined as ground and shows no visible effect in your model.
Note: You may find the action-reaction, multi-component forces more intuitive to use than the action-
only, single-component force. If you want to apply force to only one body, you can use the
action-reaction, multi-component forces and specify the reaction marker on ground.
You can apply either a translational or rotational action-only, single-component force to a body in your
model. Note that a rotational force is a pure torque in Adams Solver. For both translational and rotational
action-only, single-component forces, you provide Adams Solver with two markers: action and direction. The
action marker declares the point of application for the force.
For a rotational force, or pure torque, the location of the action marker is irrelevant; only the body to which
it belongs is important. The z-axis of the direction marker specifies the direction of the force. Adams Solver
evaluates the signed magnitude and applies it to the action marker.
If the force is positive and translational (Figure 3), it acts in the positive direction along the z-axis of the
direction marker. If the force is positive and rotational (Figure 4), it acts in the positive direction about the z-
axis of the direction marker. The right-hand rule defines the positive direction.
50 Adams Solver
Figure 3 Translational, Action-Only, Single-Component Force
Figure 4 Rotational, Action-Only, Single-Component Torque
Action-Reaction, Single-Component Forces

An action-reaction force is a force applied to one body producing a reaction force on a second body that is
equal and opposite to the action force on the first body. You can apply either a translational or rotational
(torque) action-reaction, single-component force to your model.
 For translational, action-reaction, single-component forces (Figure 5), you provide Adams Solver with
two fixed markers: action and reaction. These markers specify the points of force application and the
line along which the instantaneous forces act, therefore no direction marker is needed. If the force
applied to the action marker is positive, the action marker is pushed away from the reaction marker.
If the force applied to the action marker is negative, the action marker is pulled towards the reaction
marker.
51
Using Adams Solver
 For rotational, action-reaction, single-component torques (Figure 6), you provide Adams Solver with
two fixed markers: action and reaction. These markers only specify the body affected by the torque
not a location on the body itself, because pure torques are independent of location. The z-axis of the
reaction marker specifies the axis about which the torque is applied. If the torque is positive, the
action marker tends to move counter-clockwise to the reaction marker. If the torque is negative, the
action marker tends to move clockwise to the reaction marker.
Figure 5 Translational, Action-Reaction, Single-Component Force
Figure 6 Rotational, Action-Reaction, Single-Component Torque
Multi-Component Forces
Adams Solver also allows you to define multi-component translational and rotational force vectors. For each
of the multi-component forces, you provide Adams Solver with two fixed and one floating marker: action
(fixed), reaction (floating), and direction (fixed). The action and reaction markers always remain coincident.
The axes of the direction marker define the directions of the vector components. You specify the x, y, z
measure numbers of the force components to define them with respect to the direction marker axes.
52 Adams Solver
If a vector component is positive and translational (Figure 7), it acts in the positive direction along the
corresponding axis of the direction marker. If a vector component is positive and rotational (Figure 8), it acts
in the positive direction about the corresponding axis of the direction marker according to the right-hand
rule. You should specify all of the components of each multi-component force to be applied to the action
marker, even if some are zero. Equal and opposite forces are automatically applied to the reaction (floating)
marker.
Figure 7 Three-Component, Action-Reaction Force
Figure 8 Three-Component, Action-Reaction Torque

53
Using Adams Solver
Figure 9 Six-Component, Action-Reaction Force/Torque
ROUTINE Argument
Many Adams Solver statements and commands feature the construct FUNCTION=USER(r1,r2,...,r30),
which specifies that Adams Solver is to obtain element characteristics by loading and calling a specific user
subroutine from a specific library of user subroutines. For example, Adams Solver calls the SFOSUB
subroutine for the SFORCE statement.
The ROUTINE argument allows you to optionally specify an alternative library and user subroutine name
for some or all elements.
The ROUTINE argument takes a string argument:
ROUTINE=libname::subname
The delimiter, ::, is required to separate the library name from the subroutine name. Both the libname and
the subname are optional, but the :: delimiter is required to distinguish the library name. For example, to
specify that a different subroutine name, mysfo, is to be loaded from the default subroutine library (the
library that was mentioned when Adams Solver was run in run-user mode), you should write:
ROUTINE=mysfo
or
ROUTINE=::mysfo
54 Adams Solver
If the default name (for example SFOSUB for SFORCE) is acceptable but the user subroutine is to be loaded
from a library 'mylib', you must write:
ROUTINE=mylib::
The table below lists the default names for user subroutines for Adams Solver statements and commands.
Statement/Command Default User Subroutine

MOTION MOTSUB
FIELD FIESUB
SFORCE SFOSUB
STORQUE SFOSUB
MFORCE MFOSUB
GFORCE GFOSUB
VFORCE VFOSUB
VTORQUE VTOSUB
VARIABLE VARSUB
DIFF DIFSUB
SENSOR SENSUB
SENSOR SEVSUB
REQUEST REQSUB
CURVE CURSUB
SURFACE SURSUB
CONTROL CONSUB
SPLINE SPLINE_READ
COUPLER See the COUPLER and GSE section below.
GSE See the COUPLER and GSE section below.
Note: The subroutine specified by the ROUTINE argument must have the same argument list as the
default subroutine. Only the name is changed. A failure to satisfy this requirement results in
unpredictable runtime failure.
Just like many elements of a particular type can share the default user subroutine, many elements may share
an alternative user subroutine. In other words, a group of your SFORCE elements may use the SFOSUB in
the default library while a different group of SFORCE elements is using mylib::mysfo.
You can either fully qualify the name and location of the library or rely on Adams Solver to search for the
library using predefined rules. For example, ROUTINE argument can specify absolute paths:
55
Using Adams Solver
ROUTINE=/home/jdoe/mylibs/libsforces.so::sfo312
or relative paths with abbreviated library names:
ROUTINE=mylibs/sforces::sfo312
In the latter case, you would be relying on Adams Solver knowing to search in /home/jdoe (see the
PREFERENCES statement for details about the library search path) and built-in search-rules that first look
for the specified name, and failing that, try to prepend the lib prefix and an architecture specific suffix (.dll
on the Microsoft Windows platform, .sl on the HP-UX platform and .so on other Linux platforms and
Linux).
COUPLER and GSE

The COUPLER and GSE elements deserve special mention because they require more than one user
subroutine.
The COUPLER element requires that three subroutines be provided. This is handled by providing a comma
separated list of three libname::subname pairs, for example:
ROUTINE=lib1::cou1, lib2::cou2, lib3::cou3
where lib1, lib2, and lib3 can be three different libraries. The default names for these subroutines are
COUSUB,COUXX,COUXX2, in that order.
The GSE case is further complicated by the fact that the GSE subroutine interface has recently been
redesigned and the ROUTINE argument had been previously reserved to address the now deprecated
GSESUB interface. To specify the new GSE_DERIV, GSE_OUTPUT, GSE_UPDATE, GSE_SAMP,
GSE_SET_NS, GSE_SET_ND, GSE_SET_IMPLICIT, GSE_SET_STATIC_HOLD,
GSE_SET_SAMPLE_OFFSET subroutines for GSE, use the INTERFACE argument:
INTERFACE=lib1::gse1,lib2::gse2,lib3::gse3,lib4::gse4,lib5::gse5
,lib6::gse6,lib7::gse7,lib8::gse8,lib9::gse9
to specify the subroutines that default to GSE_DERIV, GSE_OUTPUT, GSE_UPDATE, GSE_SAMP,
GSE_SET_NS, GSE_SET_ND, GSE_SET_IMPLICIT, GSE_SET_SATIC_HOLD,
GSE_SET_SAMPLE_OFFSET in that order. Note that not all of these routines need to be supplied. For
example, if only GSE_DERIV and GSE_OUTPUT are being used, then gse::lib pairs 3-9 can be omitted.
However, these gse::lib pairs must be listed in order and dummy interfaces need to be created to preserve the
order even if they are not being used. For example, if the GSE_SET_IMPLICIT interface is being specified,
then all of the preceeding interfaces need to be speciefied (if only in dummy form) also.
You can specify deprecated GSE subroutine interface using:
ROUTINE=lib1::gse1,lib2::gse2,lib3::gse3,lib4::gse4,lib5::gse5
to specify the subroutines that default to GSESUB, GSEXX, GSEXU, GSEYX, GSEYU, in that order.
56 Adams Solver
Joint types
Translational Joint
Joint reaction force (F), bending moment (Tm), torsional moment (Tn), and force preload (Fprfrc) are used
to compute the frictional force in a translational joint. You can individually turn off the force effects using
switches SW1 through SW4. The bending moment (Tm) is converted into an equivalent force using the Xs
block. Similarly, torsional moment is converted into an equivalent joint force using the friction arm (Rn).
Frictional force (Ffrict) is applied along the axis of translation in the direction that the FRD block computes.
For more information, see the Block Diagram of the Translational Joint.
57
Using Adams Solver
Note: Adams Solver (C++) computes DZ0 (the initial joint displacement) after the first successful
assembly of the model (initial conditions or first static simulation.
Revolute Joint
Joint reactions (Fa and Fr), bending moment (Tr), and torque preload (Tprfrc) determine the frictional
torque in a revolute joint. You can turn off one or more of these force effects using switches SW1 through
SW3. The joint reactions (Fa and Fr) are converted into equivalent torques using the respective friction arm
(Rn) and pin radius (Rp). The joint bending moment (Tr) is converted into an equivalent torque using pin
radius (Rp) divided by bending reaction arm (Rb). The frictional torque (Tfrict) is applied along the axis of
rotation in the direction that the FRD block computes. See the Block Diagram of the Revolute Joint.
58 Adams Solver
59
Using Adams Solver
In general, the pin radius (Rp) will be radius of the physical pin in the revolute joint. This accounts for the
contact along the length of the physical pin with the inner cylindrical surface of the sleeve (excluding the end
surface.) The normal force (Frd) on the joint times the pin radius (Rp) estimate a torque due to this
interaction.
The friction arm (Rn) accounts for the contact between the end circular surface of the physical pin and the
inner surface the sleeve touching the end of the pin. The friction arm (Rn) times the axial load (Fa) estimate
a torque due to this interaction.
The torque (Tr) times the pin radius (Rp) divided by the bending reaction arm (Rb) estimate a torque due
to the reaction torque on the joint.
All three torque contributions above are used to estimate the frictional torque on the joint.
Cylindrical Joint
Joint reaction (F) and reaction torque (Tm) combined with force preload (Fprfrc) and torque preload
(Tprfrc) yield the frictional force and torque in a cylindrical joint. As the block diagram indicates, you can
turn off one or more of these force effects using switches SW1 through SW3. The frictional force in a
cylindrical joint acts at the mating surfaces of the joint. The FRD block determines the direction of the
frictional force. Based on the frictional coefficient direction, the surface frictional force is broken down into
an equivalent frictional torque and frictional force acting along the common axis of translation and rotation.
See the Block Diagram of the Cylindrical Joint.
60 Adams Solver
61
Using Adams Solver
Universal/Hooke Joint
The universal/hooke joint contains two yokes (I_YOKE and J_YOKE) that are modeled independently. An
equivalent revolute joint represents each yoke. Frictional torques are applied along the axes of rotation of the
two yokes. See the Block Diagram of the Universal/Hooke Joint.
Spherical Joint
The reaction force (F) and the preload frictional torque (Tprfrc) are the two forcing effects used in
computing the frictional torque on a Spherical joint. The ball radius is used to compute an equivalent
frictional torque. The FRD block determines the direction of the frictional torque. See the Block Diagram
of the Spherical Joint.
62 Adams Solver
Error Codes
Adams Solver issues "Simulate status" or "Termination status" codes when a simulation ends, along with a
verbose error message description. The following table details the meanings of the numeric codes issued by
Solver:
Parameter Value Description

NOERRS 0 No errors
INPERR -101 Errors while opening Adams output files
BADSIT -102 Site security checking not successful
63
Using Adams Solver
Parameter Value Description

ERINPT -105 Errors while reading in Adams dataset
ERVRFY -117 Model did not pass verification phase
ERMEMO -118 Problem during memory initialization phase
ERRVRS -119 UCONFG Version mismatch
ERRDIM -120 UCONFG passes negative array dimensions
ERRLCK -121 Lockup detected
BADMEM -122 Problem allocating memory
BADAMD -123 Problem initiating AMD Command Parser
ERRSML -124 Simulation failure detected
NOTCXX -125 The Model is not compatible with the Adams Solver (C++)
TRMRCR -993 Recursion encountered when trying to terminate
SNHALT -994 Sensor Halt was imposed
ERTERM -995 Abnormal termination of Solver
PRFLER -996 Program Fault was encountered
INPTRM -997 Session terminated before completion during input phase
TERMNT -998 Current session terminated before completion
The above termination codes can be displayed by using the PREFERENCES/STATUS_MESSAGE=ON

solver command. See the PREFERENCES solver command (Adams Solver C++ only).
64 Adams Solver
Welcome to the C++ Version of Adams Solver 1
Adams Solver (C++) FAQs
Welcome to the C++ Version of

Adams Solver
The C++ version of Adams Solver, part of the Adams® suite of software, is the next generation of Solver
technology. It is available as an alternative to the commercially available FORTRAN 77 Solver. You can use
Adams Solver (C++) to test your models for compatibility and to take advantage of the new features.
The online help provides detailed information on the individual statements, function expressions, and
commands you use when working with Adams Solver (C++).
To Switch to the Adams Solver (FORTRAN) click Welcome to the FORTRAN Version of Adams Solver.
Adams Solver (C++) FAQs

Below is a list of the most common Adams Solver (C++) questions. For updated information or to ask another
Adams Solver (C++) question, use the Adams Knowledge Base.
Q: Why are the Adams Solver built-in graphics capabilities not available in Adams Solver (C++)?
A: The graphics capability in Adams Solver (FORTRAN) is surpassed by the graphical user interface, Adams
View. Since this capability has a limited user base, the following commands are not implemented in Adams
Solver (C++):
 ACENTER  CLEAR
 EXECUTION
 AINIT  DISPLAY
 PLOT
 AUTOSCALE  DRAW
 RETURN
 BACKUP  DT
 SET
 CENTER  ERASE
Q: Why is the UCON user-defined constraint element not supported in Adams Solver (C++)?
A: The UCON element was always an extremely difficult element for users to use and only expert users
derived a benefit from this element. The C++ version of Solver, with its analytical derivative capability, has
replaced UCON with an extremely user-friendly user-defined constraint element (see the GCON statement
and command), which does not require the user to write user subroutines containing the partial derivatives of
the constraint equations. Instead, the user provides a function expression which is to constrained to the value
zero.
Adams Solver (C++) computes all the required derivatives.
As a result, the UCON command and the UCON statement are not supported in Adams Solver (C++).
Q: Why are the LIST/NOLIST statements not supported in C++?
A: These statements are not supported because Adams Solver (C++) does not generate a tabular output file.
Q: Why is the tabular output file (.out) not supported in C++?
2 Adams Solver
Operators
A: The tabular output file was an early attempt at reporting results from Adams Solver. Due to, among other
things, a lack of machine readability, later versions of Adams added more robust output file formats, such as
the .res and .req file.
The tabular output file is considered obsolete and supporting it in the Adams Solver (C++) was not deemed
necessary. At the same time, it is recognized that the tabular output file contained valuable information not
reported elsewhere. Work on determining this information and where to report it is work in progress.
Operators
Function expressions consist of scalar or vector measures and functions, combined with a set of arithmetic
and grouping operators. The operators closely resemble those of the FORTRAN programming language,
with extensions for vector expressions.
Accepted Combinations
The following combinations are accepted. The symbol s represents a scalar subexpression and v represents a
vector subexpression.
Parentheses grouping to override operator precedence (vector and scalar):
(v), (s)
Vector construction from scalar expressions:
[s,s,s]
Simple scalar arithmetic, including unary plus and unary minus:
s+s, s-s, s*s, s/s, -s, +s
Power (scalars only):
s**s
Vector summation, subtraction, unary minus and unary plus:
v+v, v-v, +v, -v
Scaling of a vector by a scalar:
s*v, v*s, v/s
Note that division by a vector is not supported.
Inner product (dot product):
v*v
Cross product:
v%v
C++ Statements
Operators Precedence
Furthermore, in evaluating the arithmetic expressions, the following order of precedence is used:
**, - (unary), + (unary) Highest precedence, tightest binding

*, /, % Intermediate precedence
+, - Lowest precedence, loosest binding
Operators of equal precedence are applied from left to right, with the following exceptions for the power and
unary operators:
A**B**C is interpreted as A**(B**C), not (A**B)**C
** binds tighter than unary operators to its left and looser than unary operators to its right. For example:
-A**-B = -(A**(-B))
and
-A**-B**-C = -(A**(-(B**(-C))))
In some cases parentheses must be used to group scalar and vector quantities such that the expression is not
nonsensical. For example, v*v%v may need to be written as v*(v%v).
Vector subexpressions can appear in expressions where the final value is a scalar, and vice versa, for example:
VARIABLE/1, FUN=DXYZ(1,2)*VXYZ(1,2) + TIME
where a dot product of two vector measures results in a scalar quantity.
There are only two contexts in the current Adams language where a vector quantity is expected. These are the
recently added FXYZ and TXYZ arguments of the VFORCE, VTORQUE and GFORCE statement which
can be used instead of the FX, FY, FZ, TX, TY and TZ arguments to specify force and torque laws. In all
other contexts, the expression must evaluate to a scalar quantity.
C++ Statements
You use statements to define the elements of your model, request output from the simulation, and, optionally,
set analysis parameters to use during the simulation. Note that you can use the C++ version of Adams Solver
C++ Commands to set analysis parameters, which is often a better approach. Below are the Adams Solver (C++)
statements grouped according to their function. Detailed information on each statements can be found by
following the links:
4 Adams Solver
C++ Statements
Type of Statement Statement Name

Dataset delimiter END
TITLE
Inertia and material data FE_PART
FLEX_BODY
MATERIAL
PART
POINT_MASS
Geometry GRAPHICS
MARKER
Constraints COUPLER
CVCV
GEAR
GCON
JOINT
JPRIM
MOTION
PTCV
Forces ACCGRAV
BEAM
BUSHING
CONTACT
FE_LOAD
FIELD
FRICTION
GFORCE
MFORCE
NFORCE
SFORCE
SPRINGDAMPER
VFORCE
VTORQUE
Generic systems modeling DIFF
GSE
LSE
TFSISO
VARIABLE
Reference data ARRAY
CURVE
MATRIX
PINPUT
POUTPUT
SPLINE
STRING
SURFACE
C++ Statements

Analysis parameters DEBUG
ENVIRONMENT
EQUILIBRIUM
IC
INTEGRATOR
KINEMATICS
LSOLVER
PREFERENCES
SENSOR
UNITS
Output FEMDATA
LIST/NOLIST(Not yet supported)
MREQUEST(Not yet supported)
OUTPUT
REQUEST
RESULTS
Unsupported statements UCON
LIST/NOLIST
6 Adams Solver
C++ Statements
ACCGRAV
The ACCGRAV statement specifies the magnitude and direction of the acceleration of gravity. In
conjunction with the part masses, the gravitational field defines a body force at the center of gravity in each
part.
Format
Arguments
IGRAV Defines the x component of gravitational acceleration with respect to the ground coordinate
system.
Default: 0
JGRAV Defines the y component of gravitational acceleration with respect to the ground coordinate
system.
Default: 0
KGRAV Defines the z component of gravitational acceleration with respect to the ground coordinate
system.
Default: 0
Examples
ACCGRAV/JGRAV=-386.088
This ACCGRAV statement defines the gravitational constant of 386.088, acting along the y-axis of the
ground coordinate system (GCS) in the negative direction.
See other Forces available.
ARRAY 7
C++ Statements
ARRAY
The ARRAY statement defines a list of input variables (U), state variables (X), output variables (Y), or initial
conditions (IC) associated with system modeling elements such as GSE, LSE, and TFSISO (see GSE, LSE
and TFSISO). IC ARRAY's or ARRAY's without a type can also be used to define a list of constants. These
values may be accessed in function expressions or user-written subroutines.
Format
Arguments
IC Creates a one-dimensional array of real numbers that can be accessed in user-written

subroutines. You can use IC to designate an initial conditions array for an LSE or GSE. In
that case, you should ensure that t he SIZE is the same as the X (state variable) array of the
associated LSE or GSE.
NUMBERS= Allows you to enter a one-dimensional array of real numbers when using the IC array.
r1[,r2,...,]
SIZE=i Allows you to define the size of the array. In cases where Adams Solver (C++) calculates
the SIZE differently from the SIZE that you supply, Adams Solver (C++) returns an error
or warning message.
VARIABLES= Defines a list of identifiers of VARIABLE statements to group in an array. The
id1[,id2,...] VARIABLES argument is used with only an input array (U).
Range: Any valid VARIABLE id

8 Adams Solver
C++ Statements
X Designates an ARRAY statement to be the state variable array for a systems modeling
element, LSE, GSE, or TFSISO. To use these arrays, you must reference the ARRAY
statement as the state variable array in a system element statement. You can use a single X
array with only a single systems element. When you choose X, the only other argument
available is SIZE. When you don’t specify SIZE, the associated systems element
automatically sets the size.
U Creates an array that groups together a set of VARIABLES, normally to define the inputs
for a systems element, either LSE, GSE, or TFSISO. When you choose U, SIZE and
VARIABLES are the only other available arguments.
Y Designates an ARRAY statement as the output array for a systems element, either LSE,
GSE, or TFSISO. To use these arrays, you must reference the ARRAY statement as the
output array in the system element definition in the dataset. When you choose Y, SIZE is
the only other argument available. You can use a single Y array with only a single systems
element. The SIZE value, if supplied, must be consistent with the associated systems
element. When you don’t specify SIZE, the associated systems element automatically sets
it.
Extended Definition
The ARRAY statement defines a list of input variables (U), state variables (X), output variables (Y), and initial
conditions (IC) associated with system modeling elements such as GSE, LSE, and TFSISO. ARRAY may also be
used to define a list of constants. These values may be accessed in function expressions or user-written
subroutines.
There are three basic variations of the ARRAY statement:
 The X and Y arrays designate the state and output variable arrays for a systems element. Adams
Solver (C++) computes these values during a simulation.
 The U array defines an array of inputs for a systems element. Adams Solver (C++) computes these
values from the specified VARIABLE statements.
 The IC array defines an array of constants used as initial conditions.
For the X and Y arrays, the corresponding systems modeling element automatically determines the size of the
array and checks it against the ARRAY statement’s SIZE value (if given).
The IC and SIZE parameters are optional. Adams Solver (C++) determines the actual size of the array during
input-file parsing as it counts the NUMBERS argument. However, if you provide a value for SIZE, Adams
Solver (C++) checks the count for consistency.
For X and Y arrays, you should reference the array as the state variable array or output variable array of one
of the system elements in the dataset, either LSE, GSE, or TFSISO. U and IC arrays may exist independently.
Grouping VARIABLES in a U array does not offer any computational advantage, although it might have a
convenience value.
The SIZE argument, if used, should match the number of entries in the VARIABLES or NUMBERS
arguments or the size needed for the associated element. Adams Solver (C++) provides the SIZE argument
mainly for your convenience in dataset creation. For LSE arrays, the X size is the row dimension of the A and
B matrix, and the Y size is the row dimension of the C and D matrix. For TFSISO arrays, the transformation
ARRAY 9
C++ Statements
from the transfer function form to canonical state space form determines the X size; the size of Y and U is
always one. For GSE arrays, X is size NS as defined in the matching GSE statement and Y is size NO, as
defined in the same GSE statement.
Both function expressions and user-written subroutines can access the array values. Function expressions use
the function ARYVAL (id, nseq ) (see ARYVAL) to access the values. The id specifies the identifier of the
ARRAY, and nseq specifies the position of the desired value in the ARRAY statement. To access all the
elements of an array from a user written subroutine, you should call the subroutine SYSARY (see the SYSARY
subroutine). To access one element of an ARRAY in a subroutine, you should call the subroutine SYSFNC
(see the SYSFNC subroutine).
Examples
The following are three simple examples of the ARRAY statement.
ARRAY/1, X
ARRAY/2, U, VARIABLES=2
ARRAY/3, IC, NUMBERS= 0.0, 0.0

See other Reference data available.
10 Adams Solver
C++ Statements
BEAM
The BEAM statement defines a force and a torque corresponding to a massless elastic beam with a uniform
cross section. The beam transmits forces and torques between two markers in accordance with either linear
Timoshenko beam theory or the non-linear Euler-Bernoulli theory. Conversely to standard Finite Elements
codes, the BEAM element defines a force-only element; no equations of motion for the mass of the beam are
formulated.
The BEAM statement supports three formulations to construct the force and torque expressions for this
element. By default, the linear Timoshenko beam theory is used (see Using the FORMULATION=LINEAR option
below); this default model is the one used in previous versions of Adams Solver C++. However, the
FORMULATION option is available in order to use either a full non linear Euler-Bernoulli theory or a
simplified non linear theory.
Format
BEAM 11
C++ Statements
Arguments
AREA=r Specifies the uniform area of the beam cross section. The centroidal axis must be orthogonal to
this cross section.
ASY=r Specifies the correction factor (that is, the shear area ratio) for shear deflection in the y direction
for Timoshenko beams.
A Qy 2
ASY = ---2-   ------ dA
Iy A lz
where Qy is the first moment of cross-sectional area to be sheared by a force in the z direction,
and Iz is the cross section dimension in the z direction.
If you want to neglect the deflection due to y-direction shear, ASY does not need to be included
in a BEAM statement.
Defaults: 0
ASZ=r Specifies the correction factor (that is, the shear area ratio) for shear deflection in the z direction
for Timoshenko beams.
A Qz 2
ASZ = ---2-   ------ dA
 
Iz A ly
where Qz is the first moment of cross-sectional area to be sheared by a force in the y direction,
and Iy is the cross section dimension in the y direction.
If you want to neglect the deflection due to z-direction shear, ASZ does not need to be included
in a BEAM statement.
Defaults: 0
Commonly encountered values for the shear area ratio are:
Cross-section: (Shear area ratio)

Solid rectangular (6/5)
Solid circular (10/9)
Thin wall hollow circular (2)
See also “Roark’s Formulas for Stress and Strain,” Young, Warren C., Sixth Edition, page 201.
New York:McGraw Hill, 1989.
12 Adams Solver
C++ Statements
CMATRIX=r1,...,r21 Establishes a six-by-six damping matrix for the beam. Because this matrix is symmetric, only
one-half of it needs to be specified. The following matrix shows the values to input:
Enter the elements by columns from top to bottom, then by rows from left to right. If you do
not use either CMATRIX or CRATIO, CMATRIX defaults to a matrix with thirty-six zero
entries; that is, r1 through r21 each default to zero.
CRATIO=r Establishes a ratio for calculating the damping matrix for the beam. Adams Solver multiplies the
stiffness matrix by the value of CRATIO to obtain the damping matrix.
Defaults: 0
EMODULUS=r Defines Young’s modulus of elasticity for the beam material.
GMODULUS=r Defines the shear modulus of elasticity for the beam material.
I=id, J=id Specifies the two markers between which to define a beam. The J marker establishes the direction
of the force components.
IXX=r Denotes the torsional constant. This is sometimes referred to as the torsional shape factor or
torsional stiffness coefficient. It is expressed as unit length to the fourth power.
πr 4
For a solid circular section, Ixx is identical to the polar moment of inertia J = -------- where r is
2
the radius of the cross-section.
For thin-walled sections, open sections, and noncircular sections, you should consult a
handbook.
BEAM 13
C++ Statements
IYY=r,IZZ=r Denote the area moments of inertia about the neutral axes of the beam cross sectional areas (y-
y and z-z). These are sometimes referred to as the second moment of area about a given axis. They
are expressed as unit length to the fourth power.
πr 4
For a solid circular section, Iyy=Izz= -------- where r is the radius of the cross-section.
4
For thin-walled sections, open sections, and noncircular sections, you should consult a
handbook.
LENGTH=r Defines the underformed length of the beam along the x-axis of the J marker.
Specifies the formulation to be used to define the force and torque this element will apply. By
default the LINEAR theory is used (see Using the FORMULATION=LINEAR option below). If the
NONLINEAR option is used, the full non linear Euler-Bernoulli theory is used. If the STRING
option is used, a simplified non linear theory is used. The simplified non linear theory may speed
up your simulations with little performance penalties.
Extended Definition
The figure below shows the two markers (I and J) that define the extremities of the beam and indicates the
twelve forces (s1 to s12) it produces.
The x-axis of the J marker defines the centroidal axis of the beam. The y-axis and z-axis of the J marker are
the principal axes of the cross section. They are perpendicular to the x-axis and to each other. When the beam
is in an undeflected position, the I marker has the same angular orientation as the J marker, and the I marker
lies on the x-axis of the J marker a distance LENGTH away.
The beam statement applies the following forces to the I marker in response to the relative motion of the I
marker with respect to the J marker (see nomenclature in Figure above):
14 Adams Solver
C++ Statements
 Axial forces (s1 and s7)

 Bending moments about the y-axis and z-axis (s5, s6, s11, and s12)
 Twisting moments about the x-axis (s4 and s10)
 Shear forces (s2, s3, s8, and s9)
Using the FORMULATION=LINEAR option

When using the default FORMULATION or when explicitly using FORMULATION=LINEAR, the linear
Timoshenko beam theory is used to define the forces and moments. In this case Adams Solver (C++) uses a
linear translational and linear rotational action-reaction force between the two markers I and J. The forces
the beam produces are linearly dependent on the displacements, rotations, and corresponding velocities
between the markers at its endpoints.
The following constitutive equations define how Adams Solver applies a force and a torque to the I marker
depending on the displacement rotation and velocity of the I marker relative to the J marker.
Fx K 11 0 0 0 0 0
x–L
Fy 0 K 22 0 0 0 K 26 y
Fz 0 0 K 33 0 K 35 0 z
= –
Tx 0 0 0 K 44 0 0 a
Ty 0 0 K 53 0 K 55 0 b
Tz 0 K 62 0 0 0 K 66 c
c 11 c 21 c 31 c 41 c 51 c 61 V x
c 21 c 22 c 32 c 42 c 52 c 62 V y
c 31 c 32 c 33 c 43 c 53 c 63 V z
–
c 41 c 42 c 43 c 44 c 54 c 64 ω x
c 51 c 52 c 53 c 54 c 55 c 65 ω y
c 61 c 62 c 63 c 64 c 65 c 66 ω z
where:
 Fx, Fy, and Fz are the measure numbers of the translational force components in the coordinate
system of the J marker.
 x, y, and z are the translational displacements of the I marker with respect to the J marker measured
in the coordinate system of the J marker.
 Vx, Vy, and Vz are the time derivatives of x, y, and z, respectively.
BEAM 15
C++ Statements
 Tx, Ty, and Tz are the rotational force components in the coordinate system of the J marker.
 a, b, and c are the relative rotational displacements of the I marker with respect to the J marker as
expressed in the x-, y-, and z-axis, respectively, of the J marker.
 ω x , ω y , and ω z are the components of the angular velocity of the I marker with respect to the J
marker, as seen by the J marker and measured in the J marker coordinate system.
 Cij are the entries of the damping matrix either specified by the CMATRIX option or computed by
using the CRATIO option. All Cij entries default to zero.
Note that both matrices, Cij and Kij, are symmetric, that is, Cij=Cji and Kij=Kji. You define the twenty-one
unique damping coefficients when the BEAM statement is written. Adams Solver (C++) defines each Kij as
follows:
Adams Solver (C++) applies an equilibrating force and torque at the J marker, as defined by the following
equations:
Fj = - Fi
Tj = - Ti - L x Fi
L is the instantaneous vector from the J marker to the I marker. While the force at the J marker is equal and
opposite to the force at the I marker, the torque is usually not equal and opposite, because of vector L.
The BEAM statement implements a force in the same way the FIELD statement does, but the BEAM
statement requires you to input only the values of the beam’s physical properties, which Adams Solver (C++)
uses to calculate the matrix entries.
Using the FORMULATION=NONLINEAR option

When using the FORMULATION=NONLINEAR option, then the Euler-Bernoulli formulation is used to
define the forces and moments. In this case, Adams Solver (C++) uses the following constitutive equations to
apply a force and a torque to the I marker.
16 Adams Solver
C++ Statements
Where { F o } corresponds to the Timoshenko's constitutive equations shown above, and N is the axial force
on the beam computed as:
N = K 11 ( x – L ) + d
The axial force N corresponds to the term Fx computed using linear theory (see section Using the
FORMULATION=LINEAR option above.) If there is damping (options CRATIO or CMATRIX are used), the term
d corresponds to viscous damping and can be computed as shown above. See reference [2] for more
information.
The linear theory is the default model for the BEAM statement. The non linear theory should be used when
the BEAM elements in the model are subject to high axial forces. In those cases, the additional terms in the
force/torque equations help stabilize the numerical solution.
Using the FORMULATION=STRING option

When using the option FORMULATION=STRING, then a simplified Euler-Bernoulli formulation is used
to define the forces and moments. In this case, Adams Solver (C++) uses the following constitutive equations
to apply a force and a torque to the I marker.
Where { F 0 } and N are computed as described in Using the FORMULATION=NONLINEAR option above. This
simplification may provide accurate results faster. See Chapter 15 in reference [2] for more details on string
stiffness. Notice the stiffness matrices shown in all of the above equations show only a subset of a complete
stiffness matrix displayed in textbooks. The rest of the entries may be found applying equilibrium conditions.
BEAM 17
C++ Statements
Discussion
The BEAM element is a useful force/torque element but it does include inertial effects. If you need to include
inertial effects, see the FE_PART statement.
The fastest simulation time in the majority of cases is provided by the default formulation
(FORMULATION=LINEAR). However, the LINEAR formulation may lead into a simulation failure due
to instabilities if axial forces are high. The typical case is that of slender blades modelled using PARTs
connected by BEAMs and rotating at high angular speed. High axial loads may introduce numerical
instabilities. In order to obtain a stable and correct numerical solution, the NONLINEAR formulation is
required in those cases. Unfortunately, the NONLINEAR option requires higher simulation time due to the
complex expressions for the force and torque. In some cases, using the STRING option may speed up the
simulation time while providing accurate results.
Tip:  A FIELD statement can be used instead of a BEAM statement to define a beam with
characteristics unlike those the BEAM statement assumes. For example, a FIELD
statement should be used to define a beam with a nonuniform cross section or a beam with
nonlinear material characteristics.
 The beam element in Adams Solver (C++) is similar to those in most finite element
programs. That is, the stiffness matrix that Adams Solver (C++) computes is the standard
beam element stiffness matrix.
 The USEXP option on the MARKER statement may make it easier to direct the x-axis of
the J marker.
 Generally, it is desirable to define the x-axis of the Adams Solver (C++) beam on the shear
center axis of the beam being modeled.
18 Adams Solver
C++ Statements
Caution:  The K1 and K2 terms used by MSC.NASTRAN for defining the beam properties using
PBEAM are inverse of the ASY and ASZ used by Adams Solver (C++).
 When the x-axes of the markers defining a beam are not collinear, the beam deflection and,
consequently, the force corresponding to this deflection are nonzero. To minimize the
effect of such misalignments, perform a static equilibrium at the start of the simulation.
 By definition, the beam lies along the positive x-axis of the J marker. (This is unlike most
other Adams Solver (C++) force statements, for which the z-axis is the significant axis.)
Therefore, the I marker must have a positive x displacement with respect to the J marker
when viewed from the J marker. In its undeformed configuration, the orientation of the I
and the J markers must be the same.
 The damping matrix that CMATRIX specifies should be positive semidefinite. This
ensures that damping does not feed energy into the system. Adams Solver (C++) does not
warn you if CMATRIX is not positive semidefinite.
 When the beam element angular deflections are small, the stiffness matrix provides a
meaningful description of beam behavior. However, when the angular deflections are large,
they are not commutative; so the stiffness matrix that produces the translational and
rotational force components may not correctly describe the beam behavior. If BEAM
translational displacements exceed ten percent of the undeformed LENGTH, then Adams
Solver issues a warning message.
 By its definition a BEAM is asymmetric. Holding the J marker fixed and deflecting the I
marker produces different results than holding the I marker fixed and deflecting the J
marker by the same amount. This asymmetry occurs because the coordinate system frame
that the deflection of the BEAM is measured in moves with the J marker.
Examples
A cantilevered stainless steel beam is to be modeled with a circular cross section that has the loading shown
in the figure below.
BEAM 19
C++ Statements
A weight of 17.4533 lbf at the free end of the beam with a 100-inch axial offset in the negative y direction
causes torsion to the beam as shown in the figure above. The following statement defines this beam:
BEAM/0201, I=0010, J=0020, LENGTH=100
, IXX=100, IYY=50, IZZ=50, AREA=25.0663
, ASY=1.11, ASZ=1.11, EMOD=28E6, GMOD=10.6E6,
, CRATIO=0.0001
The beam lies between Marker 0010 and Marker 0020. The length of the beam is 100 inches; its torsional
constant is 100 inch4; its principal area moments of inertia about the y-axis is 50 inch4, and about the z-axis
is 50 inch4; its cross-sectional area is 25.0663 inch2; its shear area ratio in the y direction is 1.11; its shear area
ratio in the z direction is 1.11; its modulus of elasticity is 28E6 psi; its shear modulus is 10.6 psi; and its
damping ratio relative to the stiffness matrix Adams Solver (C++) calculates is 0.0001. Note that the beam
ends belong to different parts.
References
1. Roark's Formulas for Stress and Strain, Young, Warren C., Sixth Edition, page 201. New York:
McGraw Hill, 1989.
2. J.S. Przemieniecki, Theory of Matrix Structural Analysis. New York: McGraw-Hill Book Company,
1968
20 Adams Solver
C++ Statements
BUSHING
The BUSHING statement defines a massless bushing with linear stiffness and damping properties.
Format
Arguments
C=r1,r2,r3 Specifies three viscous damping coefficients for the force transferred by the bushing.
The three coefficients multiply the relative translational velocity components of the I
marker with respect to the J marker as seen by the J marker and along the x-, y-, and
z-axis of the J marker. The force due to damping is zero when there is no relative
translational velocity between the two markers. C must be in units of force-time per
unit displacement.
Default: 0,0,0
Range: C ≥ 0
CT=r1,r2,r3 Specifies three viscous damping coefficients for the torque transferred by the bushing.
The three coefficients multiply the components of the relative angular velocity of the
part containing the I marker with respect to the part containing the J marker as
expressed in the x-, y-, and z-axis of the J marker. The torque due to damping is zero
when there is no relative angular velocity between the two markers. CT must be in
units torque-time per radian.
Default: 0,0,0
Range: CT ≥ 0
FORCE=r1,r2,r3 Specifies three constant force (preload) values. Constant values indicate the force
components along the x-, y-, and z-axis of the J marker when both the relative
displacement and the relative velocity of the I and J markers are zero.
Default: 0,0,0
I=id, J=id Specifies the identifiers of the two markers between which the bushing is placed.
BUSHING 21
C++ Statements
K=r1,r2,r3 Specifies three stiffness coefficients for the force transferred by the bushing. The three
coefficients multiply the three translational displacement components of the I marker
with respect to the J marker as expressed in the x-, y-, and z-axis of the J marker. K
must be specified in terms of force per unit of deformation.
Default: 0,0,0
Range: K ≥ 0
KT=r1,r2,r3 Specifies three stiffness coefficients for the torque transferred by the bushing. The
three coefficients multiply the three rotational displacement components of the I
marker axes relative to the J marker axes as expressed in the x-, y-, and z-axis of the J
marker. KT must be in units of torque per radian.
Default: 0,0,0
Range: KT ≥ 0
TORQUE=r1,r2,r Specifies three constant torque (preload) values. Constant values indicate the torque
3 components about the x-, y-, and z-axis of the J marker when both the relative
displacement and the relative velocity of the I and the J markers are zero.
Default: 0,0,0
Extended Definition
The BUSHING statement defines a massless bushing with linear stiffness and damping properties. The
BUSHING statement applies a force and torque to two parts. You specify a marker on each part for force
and/or torque application.
Each force consists of three components in the coordinate system of the J marker, one in the x-axis direction,
one in the y-axis direction, and one in the z-axis direction.
Likewise each torque consists of three components in the coordinate system of the J marker: one about the
x-axis, one about the y-axis, and one about the z-axis. The force is linearly dependent upon the relative
displacement and the relative velocity of the two markers. The torque is dependent upon the relative angle of
rotation and the relative rotational velocity of the parts containing the specified markers.
A BUSHING statement has the same constitutive relation form as a FIELD statement. The primary
difference between the two statements is that certain coefficients (Kij and Cij, where i j) are zero for the
BUSHING statement. Only the diagonal coefficients (Kii and Cii) are defined for a BUSHING.
22 Adams Solver
C++ Statements
Fx K 11 0 0 0 0 0
x
Fy 0 K 22 0 0 0 0 y
Fz 0 0 K 33 0 0 0 z
= –
Tx 0 0 0 K 44 0 0 a
Ty 0 0 0 0 K 55 0 b
Tz 0 0 0 0 0 K 66 c
c 11 0 0 0 0 0 Vx F1
0 c 22 0 0 0 0 Vy F2
0 0 c 33 0 0 0 Vz F3
– +
0 0 0 c 44 0 0 ωx T1
0 0 0 0 c 55 0 ωy T2
0 0 0 0 0 c 66 ω z T3
Fx, Fy, and Fz are the measure numbers of the translational force components in the coordinate system of the
J marker. The terms x, y, and z are the translational displacements of the I marker with respect to the J marker
measured in the coordinate system of the J marker. The terms Vx, Vy, and Vz are the time derivatives of x, y,
and z, respectively. The terms F1, F2, and F3 represent the measure numbers of any constant preload force
components in the coordinate system of the J marker.
Tx, Ty, and Tz are the rotational force components in the coordinate system of the J marker. The terms a, b,
and c are the relative rotational displacements of the I marker with respect to the J marker as expressed in the
x-, y-, and z-axis, respectively, of the J marker. The terms ω x , ω y , and ω z are the angular velocity
components of the I marker with respect to the J marker, measured in the coordinate system of the J marker.
The terms T1, T2, and T3 are the measure numbers of any constant torque in the coordinate system of the J
marker.
Adams Solver (C++) applies an equilibrating force and torque to the J marker, as defined by the following
equations:
Fj=-Fi
Tj = - Ti - δ x Fi
BUSHING 23
C++ Statements
is the instantaneous deformation vector from the J marker to the I marker. While the force at the J marker
is equal and opposite to the force at the I marker, the torque at the J marker is usually not equal to the torque
at the I marker because of the deformation.
The BUSHING only models linear bushings. The GFORCE or FIELD (with a FIESUB) may be used to
model nonlinear bushings.
Caution: For the rotational constitutive equations to be accurate, at least two of the rotations (a, b, c)
must be small. That is, two of the three values must remain smaller than 10 degrees. In
addition, if a becomes greater than 90 degrees, b becomes erratic. If b becomes greater than
90 degrees, a becomes erratic. Only c can become greater than 90 degrees without causing
convergence problems. For these reasons, it is best to define your bushing such that angles a
and b (not a and c and not b and c) remain small.
Examples
BUSHING/1022, I=10, J=22, K=5000,5000,2000, C=5,5,2
, KT=50000,50000,0, CT=50,50,0
This BUSHING statement describes a bushing with translational spring rates of 5000 units in both the x-
axis and the y-axis directions of Marker 22 and of 2000 units in the z-axis direction of Marker 22. The
corresponding damping rates for the force are 5 units in both the x- and y-axis directions of Marker 22 and
2 units in the z-axis direction of Marker 22. The rotational spring rates are 50000 units about the x- and y-
axis of Marker 22. The corresponding damping rates for the torque are 50 units in both the x- and y-axis
directions of Marker 22 and zero units in the z-axis direction of Marker 22. Since the z components of KT
and CT are zero, the I marker can rotate about the z-axis of the J marker without generating any torque. There
are no FORCE or TORQUE values because there is no initial load (preload) associated with the input
positions of the markers.
24 Adams Solver
C++ Statements
CBKSUB
The CBKSUB statement is used to register an optional user-written subroutine that Adams Solver C++ calls
at a predefined set of milestones (also known as events) during the code execution. CBKSUB stands for
"callback subroutine". Typical events are the following: end of reading the Adams model, the start of a
command, the start of an iteration, the end of an iteration, the start of static simulation, a sensor triggered
and so on. A complete list of supported events is provided in the documentation of the user-written CBKSUB
(Adams Solver Subroutines)
Users can write a callback subroutine using FORTRAN or C or C++. The overhead of having a callback
subroutine is negligible unless the user performs lengthy numerical calculations therein.
The callback framework is intended for advanced users customizing numerical intensive Adams models
performing custom solutions. The callback framework helps writing code to initialize memory, make
computations that generate results to be shared by other user-written subroutines or to optimize custom
models.
Format
CBKSUB/id, PRIORITY=i, FUNCTION=USER(0), ROUTINE=libname::subname
Arguments
PRIORITY=i In case there is more than one callback subroutine, this option defines
the order in which callback subroutines are called. Callbacks with
higher priority are called first. If two or more callbacks have the same
priority, the order is not defined.
The priority has no default and it can be set to any integer value.
FUNCTION=USER(0) Adams Solver C++ does not pass user parameters to the callback
subroutines. Set this option to USER(0).
ROUTINE=libname::subname Specifies an alternative library and name for the user written callback
subroutine CBKSUB.
Learn more about the ROUTINE Argument.
Extended definition
A callback subroutine is called every predefined milestone during the code execution. Within a callback
subroutine user may write code to prepare computations, run custom solutions and so on in order to optimize
complex Adams models.
The main specifications of a callback subroutine are the following:
1. Callback subroutines are always called from the main thread.
2. Callback subroutines are called at every predefined set of events during the code execution.
3. Three parameters are passed on each call: the current simulation time, an event identifier, and an array
with data that depends on the type of event.
CBKSUB 25
C++ Statements
Example
CBKSUB/99, PRIORITY=10, FUNC=USER(0), ROUTINE=mylib::mycbksub
26 Adams Solver
C++ Statements
CLEARANCE
The CLEARANCE statement defines a measure of the distance between two or more geometries or
FLEX_BODIES.
Format
CLEARANCE/id, IGEOM=id1[,...,idn]
JGEOM=id2[,...,idn]
IFLEX=id1[,....,idn] [,IREGION=id1[,...,idn],[IEXCLUDE=c1[:...:cn]]
JFLEX=id2[...,idn] [,JREGION=id2[,...,idn],[JEXCLUDE=c2[:...:cn]]
[[,THRESHOLD = distance]]
[]Select one item

[[]] Optionally select the item
Arguments
IGEOM = id List of geometries id's

JGEOM = id List of geometries id's
IFLEX = id List of FLEX_BODY id's
JFLEX = id List of FLEX_BODY id's
IREGION/JREGION = id List matrix id's, the matrix is the list of node id's to include or exclude.
Notes:
1. Not specifying the IREGION or JREGION will automatically

include all nodes by default.
2. IREGION and JREGION can only be used with Flex Bodies. They
define a subset of the nodes on a flex body. Specifying a subset of nodes
rather than all nodes, can greatly speed up the Clearance calculation. See
Example 2 for more information.
IEXCLUDE/JEXCLUDE = id List of booleans to indicate if the nodes indicated by the matrix are to be
included or excluded. The default is false so the nodes are included be
default.
THRESHOLD = distance If the clearance between the bounding box of each geometry is greater
than the given THRESHOLD, the clearance between the bounding
boxes is computed. If the distance between bounding boxes is smaller
than the threshold, or if threshold is set to zero (default), Solve will
calculate the clearance between the actual geometries. Setting threshold
to a positive nonzero value can speed up simulations when clearances
above a threshold do not need to be precise and can be approximated.
CLEARANCE 27
C++ Statements
Extended Definition
The clearance statement defines a measure of the distance between two or more geometries or
FLEX_BODIES.
The results are written to the XRF results file as XYZ location on the I geometry, XYZ location on the J
geometry, the scalar distance between the two points, the id of the I geometry, and the id of J geometry. For
FLEX_BODIES it is possible to include or exclude a subset of nodes using the REGION and EXCLUDE
lists.
The clearance or one of its components may be referenced in an expression using the following 1D and 3D
functions.
DCLEAR IVCLEARZ JACCCLEARX

VCLEAR IACCCLEARX JACCCLEARY
ACCCLEAR IACCCLEARY JACCCLEARZ
ICLEAR IACCCLEARZ IDCLEAR
JCLEAR JDCLEARX IVCLEAR
IDCLEARX JDCLEARY IACCCLEAR
IDCLEARY JDCLEARZ JDCLEAR
IDCLEARZ JVCLEARX JVCLEAR
IVCLEARX JVCLEARY JACCCLEAR
IVCLEARY JVCLEARZ
ACCCLEAR(cid [,k]) Relative acceleration of the I and J clearance points

DCLEAR(cid) Clearance distance
IACCCLEAR(cid [,k] Acceleration of the I clearance point
IACCCLEARX(cid [,k] [,l]) X Acceleration of the I clearance point
IACCCLEARY(cid [,k] [,l]) Y Acceleration of the I clearance point
IACCCLEARZ(cid [,k] [,l]) Z Acceleration of the I clearance point
ICLEAR(cid) Adams id of the I graphic/flex body used in the clearance calculation
IDCLEAR(cid [,k]) Position of the I clearance point
IDCLEARX(cid [,k] ) X Position of the I clearance point
IDCLEARY(cid [,k]) Y Position of the I clearance point
IDCLEARZ(cid [,k]) Z Position of the I clearance point
IVCLEAR(cid [,k]) Velocity of the I clearance point
IVCLEARX(cid [,k] [,l] ) X Velocity of the I clearance point
IVCLEARY(cid [,k] [,l]) Y Velocity of the I clearance point
IVCLEARZ(cid [,k] [,l]) Z Velocity of the I clearance point
28 Adams Solver
C++ Statements
JACCCLEAR(cid [,k]) Acceleration of the J clearance point

JACCCLEARX(cid [,k] [,l]) X Acceleration of the J clearance point
JACCCLEARY(cid [,k] [,l]) Y Acceleration of the J clearance point
JACCCLEARZ(cid [,k] [,l]) Z Acceleration of the J clearance point
JCLEAR(cid) Adams id of the J graphic/flex body used in the clearance calculation
JDCLEAR(cid [,k]) Position of the J clearance point
JDCLEARX(cid [,k] ) X Position of the J clearance point
JDCLEARY(cid [,k]) Y Position of the J clearance point
JDCLEARZ(cid [,k]) Z Position of the J clearance point
JVCLEAR(cid [,k]) Velocity of the J clearance point
JVCLEARX(cid [,k] [,l] ) X Velocity of the J clearance point
JVCLEARY(cid [,k] [,l]) Y Velocity of the J clearance point
JVCLEARZ(cid [,k] [,l]) Z Velocity of the J clearance point
VCLEAR(cid [,k]) Relative velocity of the I and J clearance points
Where:
cid Is the Adams id of the clearance to measure
k The marker in whose coordinate is being calculated. Set k=0 if you the
results to be calculated in the global coordinate system.
l The reference frame in which the derivative of the vector is taken. Set l=0
if you want the time derivative to be taken in the ground reference frame.
Example 1
CLEARANCE/5, IGEOM=2, JGEOM=4
CLEARANCE/7, IFLEX=3,9, JGEOM=4
, IREGION=0,2, IEXCLUDE=F:T
Example 2
CLEARANCE/1
, IFLEX = 2
, JFLEX = 3
, IREGION = 4666
, JREGION = 5666
The id's of IREGION and JREGION are MATRIX id's, which are defined as:
CLEARANCE 29
C++ Statements
Matrix/4666, FULL=CORDER, ROWS=4, COLUMNS=1

, VALUES= 100, 101, 111, 112
Matrix/5666, FULL=CORDER, ROWS=4, COLUMNS=1

, VALUES= 10, 11, 21, 22
The VALUES in each matrix are node id's of Flex Bodies 2 and 3. IREGION specifies the four nodes in the
lower right corner of the flex body and JREGION specifies the four nodes in the upper left corner of the flex
body. The nodes are shown in Figure 1.
Figure 1 Nodes
30 Adams Solver
C++ Statements
One image is used because the geometry of both flex bodies is identical. The Clearance calculation works
with the tessellation of the flex bodies. This means that the surface mesh is divided into triangles. It is
important to note that a particular node of the flex body can be in more than one triangle.
The actual IREGION and JREGION used in the Clearance calculation are shown Figure 2.
Figure 2 I and J region
Notice that the regions are bigger than one would expect from looking at just the nodes. The reason is that
all triangles that touch a node are included in the region. If a user tries to specify just one node in a region,
he will actually get three nodes, because the Clearance must work with triangles and it takes three nodes to
specify one triangle.
By simulating the flex_clearance model and animating, it can be seen that the Clearance graphic goes from
the IREGION on FLEX_BODY/2 to the JREGION on FLEX_BODY/3.
CLEARANCE 31
C++ Statements
32 Adams Solver
C++ Statements
CONTACT
The CONTACT statement lets you define a two- or three-dimensional contact between a pair of geometric
objects. Adams Solver (C++) models the contact as a unilateral constraint, that is, as a force that has zero value
when no penetration exists between the specified geometries, and a force that has a positive value when
penetration exists between two geometries.
The CONTACT statement supports:
 Multiple contacts
 Dynamic friction
 Contact between three-dimensional solid geometries
 Contact between two-dimensional geometries
It does not support non-solid three-dimensional geometries, such as shells that do not encompass a volume
and sheets. It also does not support contact between a two-dimensional and a three-dimensional geometry.
Adams Solver (C++) has two geometry engines that it uses for three-dimensional contacts. It uses Parasolid,
a geometry toolkit from EDS/Unigraphics, and RAPID. Currently, RAPID is the default and Adams Solver
(C++) supports version 2.01.
Adams Solver understands some geometries as analytical. Whenever possible use analytical geometries to
speed up solution time and realize smoother contact forces. Analytical geometries are created via the
GRAPHICS/ statement. The table further below illustrates which geometry types Adams Solver treats
analytically.
Note that the tessellation of a box is simple enough (12 triangles) such that it performs as well as an analytical
box would.
For two-dimensional contacts, Adams Solver (C++) uses an internally developed geometry engine. Currently,
Adams Solver (C++) supports Parasolid 28.1.238. See the Extended Definition for more information.
The geometry engine is responsible for detecting contact between two geometries, locating the points of
contact, and calculating the common normal at the contact points.
Once the contact kinematics are known, contact forces, which are a function of the contact kinematics, are
applied to the intersecting bodies.
Note: You can only define two-dimensional contacts between bodies that are constrained to
be in the same plane. This is usually done with planar or revolute joints or an
equivalent set of constraints that enforce the planarity.
Failure to enforce planarity will result in a run-time error, when the bodies go out of
plane during a simulation.
The following table shows the legal combinations of geometry for the CONTACT statement. If you use
unsupported geometry combinations, you will receive an error.
CONTACT 33
C++ Statements
Supported Geometry Combinations
Note: You can set the default geometry library. See the PREFERENCES statement.
34 Adams Solver
C++ Statements
Format
{ } Select one item

[ ] Optionally select one item
CONTACT 35
C++ Statements
Arguments
COULOMB_FRICTION = Models friction effects at the contact locations using the Coulomb friction model
off/on/DYNAMICS_ONLY to compute the frictional forces.
 The friction model in CONTACT models dynamic friction but not stiction.
 The argument values, On/Off/DYNAMICS_ONLY, specify at run time
whether the friction effects are to be included. If the value is On, the friction
is active in all simulation types. If the value is Off, the friction is deactivated
in all simulation types. If the value is DYNAMICS_ONLY, the friction is
active only during dynamic simulations.
DAMPING = r Used when you specify the IMPACT model for calculating normal forces.
DAMPING defines the damping properties of the contacting material. You
should set the damping coefficient is about one percent of the stiffness
coefficient.
Range: DAMPING >0

DMAX = r Used when you specify the IMPACT model for calculating normal forces.
DMAX defines the penetration at which Adams Solver turns on full damping.
Adams Solver uses a cubic STEP function to increase the damping coefficient
from zero, at zero penetration, to full damping when the penetration is DMAX.
A reasonable value for this parameter is 0.01 mm. For more information, refer to
the IMPACT function.
Range: DMAX > 0

EXPONENT=r Used when you specify the IMPACT model for calculating normal forces. Adams
Solver (C++) models normal force as a nonlinear spring-damper. If PEN is the
instantaneous penetration between the contacting geometry, Adams Solver
calculates the contribution of the material stiffness to the instantaneous normal
forces as STIFFNESS * (PENALTY)**EXPONENT. For more information, see
the IMPACT function.
Exponent should normally be set to 1.5 or higher.
Range: 0 < EXPONENT

36 Adams Solver
C++ Statements
FRICTION_TRANSITION_VEL Used in the COULOMB_FRICTION model for calculating frictional forces at

OCITY = r the contact locations. Adams Solver (C++) gradually transitions the coefficient of
friction from MU_STATIC to MU_DYNAMIC as the slip velocity at the
contact point increases. When the slip velocity is equal to the value specified for
FRICTION_TRANSITION_VELOCITY, the effective coefficient of friction is
set to MU_DYNAMIC. For more details, see Extended Definition.
Note: Small values for FRICTION_TRANSITION_VELOCITY cause the

integrator difficulties. You should specify this value as:
FRICTION_TRANSITION_VELOCITY > 5* ERROR
where ERROR is the integration error used for the solution. Its default value is
1E-3.
Range:
FRICTION_TRANSITION_VELOCITY >
STICTION_TRANSITION_VELOCITY > 0
FRICTION_FUNCTION=USER(r Specifies up to 30 user-defined constants to compute the contact friction force
1[,...,r30]) components in a user-defined subroutine, CFFSUB.
FRICTION_ROUTINE = Specifies a library and a user-written subroutine in that library that calculates the
library::function contact friction force.
TYPE = {contact_type} Specifies contact type as:
 solid_to_solid
 curve_to_curve
 point_to_curve
 point_to_plane
 curve_to_plane
 sphere_to_plane
 sphere_to_sphere
 flex_to_solid
 flex_to_flex
 flex_edge_to_curve
 flex_edge_to_flex_edge
 flex_edge_to_plane
 cylinder_to_cylinder
IEDGE = id ID of an edge on the IFLEX Body. Specifies a single edge. List of IDs is not
supported. IEDGE cannot be used without IFLEX. IFLIP may be used with
IEDGE.
CONTACT 37
C++ Statements
IGEOM = id ID of the GRAPHICS statement that defines the first of two geometric bodies
between which a CONTACT is to be modeled. Specifies a list of GRAPHICS
IDs. The limit is 32,767. All geometries must belong to the same part.
JGEOM = id ID of the GRAPHICS statement that defines the second of two geometric bodies
between which a CONTACT is to be modeled. Specifies a list of GRAPHICS
IDs. The limit is 32,767. All geometries must belong to the same part.
IFLEX = id ID of the FLEX_BODY statement that defines the first of two flexible bodies
between which a CONTACT is to be modeled. Specifies a single FLEX ID. List
of IDs is not supported.
JEDGE = id ID of an edge on the JFLEX Body. Specifies a single edge. List of IDs is not
supported. JEDGE cannot be used without JFLEX. JFLIP may be used with
JEDGE.
JFLEX = id ID of the _BODY statement that defines the second of two flexible bodies
between which a CONTACT is to be modeled. Specifies a single FLEX ID. List
of IDs is not supported.
IFLIP_GEOMETRY = Specifies a list of GRAPHICS IDs associated with the IGEOM objects to be
id1,id2,...,idN reversed in direction (flipped). Use IFLIP_GEOMETRY with two-dimensional
geometries (for example, curves, arcs, and circles) and three-dimensional
geometries (for example, cylinders and spheres as ellipsoids with equal axes). For
an explanation of how CONTACT calculates tangents and normals, see Extended
Definition.
IMPACT Specifies that the IMPACT method is to be used to model the normal force. For
more information, see Extended Definition.
JFLIP_GEOMETRY = Specifies a list of GRAPHICS IDs associated with the JGEOM objects to be
id1,id2,...,idN reversed in direction (flipped). Use JFLIP_GEOMETRY with two-dimensional
geometries (for example, curves, arcs, and circles) and three-dimensional
geometries (for example, cylinders and spheres as ellipsoids with equal axes). For
an explanation of how CONTACT calculates tangents and normals, see Extended
Definition.
FACE_CONTACT_BOTTOM Specific to cylinder-to-cylinder contacts where one of the cylinders is using its
internal surface for contact (that is, referenced by I/JFLIP_GEOM). “Bottom”
face is defined as the one on which the cylinder geometry’s reference marker is
located. If set to “TRUE” then this face will enforce contact.
FACE_CONTACT_TOP Specific to cylinder-to-cylinder contacts where one of the cylinders is using its
internal surface for contact (that is, referenced by I/JFLIP_GEOM). “Top” face
is defined as the one on which the cylinder geometry’s reference marker is NOT
located. If set to “TRUE” then this face will enforce contact.
38 Adams Solver
C++ Statements
MU_DYNAMIC = r Specifies the coefficient of friction at a contact point when the slip velocity is
larger than the FRICTION_TRANSITION_VELOCITY. For information on
material types versus commonly used values of the coefficient of the dynamic
coefficient of friction, see the Material Contact Properties table. Excessively large
values of MU_DYNAMIC can cause integration difficulties.
Range:0 < MU_DYNAMIC < MU_STATIC

MU_STATIC=r Specifies the coefficient of friction at a contact point when the slip velocity is
smaller than the STICTION_TRANSITION_VELOCITY. For information on
material types versus commonly used values of the coefficient of static friction,
see the Material Contact Properties table. Excessively large values of MU_STATIC
can cause integration difficulties.
Range: MU_STATIC > 0

NORMAL_FUNCTION = Specifies up to 30 user-defined constants to compute the contact normal force
USER(r1,[,...,r30]) components in a user-defined subroutine, CNFSUB.
NORMAL_ROUTINE = Specifies a library and a user-written subroutine in that library that calculates the
library::function contact normal force.
PENALTY=r Used when you specify a restitution model for calculating normal forces.
PENALTY defines the local stiffness properties between the contacting material.
A large value of PENALTY ensures that the penetration, of one geometry into
another, will be small. Large values, however, will cause numerical integration
difficulties. A value of 1E6 is appropriate for systems modeled in Kg-mm-sec. For
more information on how to specify this value, see Extended Definition.
Range: PENALTY > 0

POISSON Specifies that a coefficient of restitution method is to be used to model the
normal force. For more information, see the Extended Definition.
CONTACT 39
C++ Statements
RESTITUTION_COEFFICIENT The coefficient of restitution models the energy loss during contact. A value of
=r zero specifies a perfectly plastic contact between the two colliding bodies. A value
of one specifies a perfectly elastic contact. There is no energy loss. The coefficient
of restitution is a function of the two materials that are coming into contact. For
information on material types versus commonly used values of the coefficient of
restitution, the Material Contact Properties table.
Range: 0 < RESTITUTION_COEFFICIENT < 1

STICTION_TRANSITION_VEL Used in the COULOMB_FRICTION model for calculating frictional forces at
OCITY = r the contact locations. Adams Solver (C++) gradually transitions the coefficient of
friction from MU_DYNAMIC to MU_STATIC as the slip velocity at the
contact point decreases. When the slip velocity is equal to the value specified for
STICTION_TRANSITION_VELOCITY, the effective coefficient of friction is
set to MU_STATIC. For more details, see the Extended Definition.
Note: A small value for STICTION_TRANSITION_VELOCITY causes

numerical integrator difficulties. A general rule of thumb for specifying
this value is:
STICTION_TRANSITION_VELOCITY> 5 ERROR
where ERROR is the accuracy requested of the integrator. Its default value is 1E-
3.
Range: 0 < STICTION_TRANSITION_VELOCITY <

FRICTION_TRANSITION_VELOCITY
STIFFNESS=r Specifies a material stiffness that you can use to calculate the normal force for the
impact model.
In general, the higher the STIFFNESS, the more rigid or hard the bodies in
contact are. Also note that the higher the STIFFNESS is, the harder it is for an
integrator to solve through the contact event.
Extended Definition
For more information on the key issues about the CONTACT statement, click a link below.
 Contact Kinematics
 Outward Normal Definition
 Contact Kinetics
 Contact Normal Force Calculation
 Contact Friction Force Calculation
 Contact Friction Torque Calculation
 Contact Prediction
 Contacts and Analysis Mode Issues
40 Adams Solver
C++ Statements
 Flexible Bodies
 FE Parts
 Contact Parameters for Parts with Small Mass
Contact Kinematics
The CONTACT statement lets you define contact between two geometry objects that you specify in
GRAPHICS entities in an Adams dataset (see the GRAPHICS statement). Adams Solver (C++) supports:
 Both two- and three-dimensional geometry.
 Two-dimensional or planar contact between POINT, PLANE, CIRCLE, ARC, and CURVE
geometries.
 Three-dimensional contact between CYLINDER, ELLIPSOID, BOX, FRUSTUM, and
EXTERNAL geometries.
Currently, Adams Solver (C++) does not support contact between two- and three-dimensional geometries.
The CURVE and the EXTERNAL graphics types are the generic geometry modeling entities. These provide
you with a way to specify arbitrarily complex two- and three-dimensional geometric shapes, respectively. For
both of these entities, the data is in files, which are usually generated by a geometry modeling system. The
CURVE object is specified as a series of x, y, and z points that are a function of an independent curve
parameter. The three-dimensional EXTERNAL object is more complex, and is specified in the format of the
geometry modeling system. Parasolid from Unigraphics is the default geometry modeling system in Adams
Solver (C++). This is a well-recognized, state-of-the-art geometry modeling system that is used in many CAD
systems. Parasolid geometry files typically have the extension xmt_txt.
During a simulation, the first step is to find out if the contact is occurring between the geometry pairs
identified in the CONTACT statements. If there is no contact, there is no force. If contact exists, the
geometry modeling system calculates the location of the individual contact points and the outward normals
to the two geometries at the contact point. Adams Solver (C++) calculates the normal and slip velocities of
the contact point from this information. Adams Solver (C++) then uses the velocities to calculate the contact
force at each individual contact.
Outward Normal Definition

The calculation of the outward normal for geometry is important because it defines where the material lies
and, therefore, determines the direction of the contact normal force.
For three-dimensional solids, which are closed by definition, the outward normal is implicit in the geometry
description, and there is no ambiguity in its definition.
For two-dimensional geometries, especially open curves, there is an ambiguity in calculating the outward
normal. Adams Solver (C++) uses the specified geometry to calculate a default outward normal, but allows
the user to reverse this direction using the IFLIP_NORMAL and JFLIP_NORMAL arguments.
The figure below shows an open curve with eight points defined in the coordinate system of the reference
marker (RM). The z-axis of the RM marker is directed out of the plane of the paper. This defines the bi-
ˆ
normal for the curve, denoted as b.
CONTACT 41
C++ Statements
The curve points are created in the sequence 1 through 8.
ˆ
The tangent at point 3 points towards point 4, and is denoted by t . The outward normals are defined as
follows:
ˆ ˆ ˆ
n = t×b
ˆ
IFLIP_NORMAL and JFLIP_NORMAL simply reverse the direction of n.
IFLIP_NORMAL and JFLIP_NORMAL only apply when a single ID is specified in IGEOM and JGEOM.
When lists of geometries are specified by IGEOM and JGEOM, use IFLIP_GEOMETRY and
JFLIP_GEOMETRY to flip normals.
Contact Kinetics
Two major types of contact are:
 Intermittent contact - Is characterized by contact for short periods of time. It is also known as
impulsive contact. Two geometries approach each other, undergo a collision, and separate as a result
of the contact. The collision results in the generation of an impulse, that affects the momentum of
the colliding bodies. Adams Solver (C++) develops an estimate of the contact force by modeling the
local deformation behavior of the contacting geometries.
Energy loss during the collision is usually modeled as a damping force that is specified with a
damping coefficient or a coefficient of restitution.
Intermittent contact is characterized by two distinct phases. The first is compression, where the
bodies continue to approach each other even after contact occurs. The kinetic energy of the bodies is
converted to potential and dissipation energy of the compressing contact material. When the entire
kinetic energy is transformed, the potential energy stored in the material reverses the motion of the
contacting bodies. Potential energy is transformed again to dissipation energy and kinetic energy.
This is known as the decompression phase. It is important to note that energy losses due to
dissipation occur in both phases.
42 Adams Solver
C++ Statements
 Persistent contact - Is characterized by contact for relatively long periods of time. External forces
acting between the two bodies serve to maintain continuous contact. Persistent contact is modeled as
a nonlinear spring damper, the stiffness modeling the elasticity of the surfaces of contact, and the
damping modeling the dissipation of energy. Two bodies are said to be in persistent contact when
the separation velocity, after a collision event, is close to zero. The bodies, therefore, cannot separate
after the contact.
Contact forces are calculated at each individual contact point. Individual contributions are summed up to
compute the net response of the system to the contact event.
Contact Normal Force Calculation

Two models for normal force calculations are available in Adams Solver (C++):
 IMPACT function model
 Coefficient of restitution or the POISSON model
Both force models result from a penalty regularization of the normal contact constraints. Penalty
regularization is a modeling technique in mechanics, in which a constraint is enforced mathematically by
applying forces along the gradient of the constraint. The force magnitude is a function of the constraint
violation.
Contact between rigid bodies theoretically requires that the two bodies not penetrate each other. This can be
expressed as a unilateral (inequality) constraint. The contact force is the force associated with enforcing this
constraint. Handling these auxiliary constraint conditions is usually accomplished in one of two ways, either
through introduction of Lagrange multipliers or by penalty regularization.
For contact problems, the latter technique has the advantage of simplicity; no additional equations or
variables are introduced. This is particularly useful when treating intermittent contact and algorithmically
managing active and inactive conditions associated with unilateral constraints. Additionally, a penalty
formulation is easily interpreted from a physical standpoint. For example, the magnitude of the contact
reaction force is equal to the product of material stiffness and penetration between contacting bodies, similar
to a spring force. For these reasons, Adams Solver (C++) uses a penalty regularization to enforce all contact
constraints. The disadvantage of the penalty regularization, however, is that you are responsible for setting an
appropriate penalty parameter, that is, the material stiffness. Furthermore, a large value for the material
stiffness or penalty parameter can cause integration difficulties.
Before presenting the contact normal force models in Adams Solver (C++), it is helpful to clearly define the
contact constraints and associated kinematic and kinetic quantities. First, impenetrability of two approaching
bodies is measured with a gap function g, where a positive value of g indicates penetration. Next, we denote
the normal contact force magnitude as Fn, where a positive value indicates a separation force between the
contacting bodies. With this notation in hand, the auxiliary contact constraints are defined as:
The first three equations reflect:

 The impenetrability constraint
 Separating, normal force constraint
 Requirement that the normal force be nonzero only when contact occurs.
CONTACT 43
C++ Statements
g≥0
Fn > 0
Fn ⋅ g = 0
dg
F n ⋅ ------ = 0
dt
The fourth condition is called the persistency condition and it specifies that the normal force is nonzero only
when the rate of separation between the two bodies is zero. The last constraint is particularly important when
you are interested in energy conservation or energy dissipation.
You obtain the IMPACT force model by replacing the first three auxiliary contact conditions with the
following expression:
F n = k*(g**e)
where k (stiffness) is a scalar penalty parameter. The penalization becomes exact as k approaches infinity, but
otherwise allows small violation of the impenetrability constraint. It is important to note that ill conditioning
of the governing equations, and ultimately an integrator failure, will result as the stiffness becomes excessively
large. Therefore, you must appropriately select k while preserving the stability of the solution.
You can also approximate the compliance of a body by correlating k to the bodies material and geometric
parameters; however, in doing so, you should recall the earlier remark concerning ill conditioning. In an effort
to incorporate general material constitutive relationships for the contacting bodies, as well as facilitate time
integration, Adams Solver (C++) augments the previous expression with nonlinear displacement-dependent,
viscous damping terms. The general form of the IMPACT force function is then given by:
where:
 g represents the penetration of one geometry into another.
dg
 ------ is the penetration velocity at the contact point.
dt
 e is a positive real value denoting the force exponent.
 dmax is a positive real value specifying the boundary penetration to apply the maximum damping
coefficient cmax.
Clearly, for cmax = 0 and e = 1, the original penalization is recovered. The POISSON force model is derived
dg
from the persistency condition, F n × ------ = 0 . A penalty regularization of the fourth contact constraint
dt
yields:
44 Adams Solver
C++ Statements
dg
F n = p × ------
dt
where p is a scalar penalty parameter. Again, the penalization is exact as p → ∞ , which carries the risk of ill
conditioning. In the context of dynamic contact problems, the POISSON model is more consistent with
conservation laws and conserves/dissipates energy appropriately. You can optionally provide a coefficient of
restitution e to model inelastic contact. In this case, the POISSON force model computes the normal contact
force as follows:
 e + 1 dg h  d 2 g 
F n = p  ------------  ------ – --- e  --------2  
 2  dt  2  dt  
Here, e is coefficient of restitution, g is the penetration depth, and h is the time step.
See Learning More about the Contact Detection Algorithm.
Contact Friction Force Calculation

Adams Solver (C++) uses a relatively simple velocity-based friction model for contacts. Specifying the
frictional behavior is optional. The figure below shows how the coefficient of friction varies with slip velocity.
In this simple model:

CONTACT 45
C++ Statements
 μ (-vs) = μ s
 μ (vs) = - μ s
 μ (0) = 0
 μ (-vd) = μ d
 μ (vd) = - μ d
 μ (v) = -sign(v). μ dfor |v| >vd
 μ (v) = -step(|v|,vs, μ s, vd, μ d) sign(v) for vs < |v| < vd
 μ (v) = step(v,-vs, μ s,vs,- μ s) for -vs < v < vs
where:
 V: Slip velocity at contact point
 vs: STICTION_TRANSITION_VELOCITY
 vd: FRICTION_TRANSITION_VELOCITY
 μ s: MU_STATIC
 μ d: MU_DYNAMIC
Contact Friction Torque Calculation

If Adams Solver detects an angular velocity about the contact normal axis, it will apply a torque proportional
to the friction force. The reason for this is that the contact friction force, by itself, cannot retard relative
rotation between bodies; it can only retard relative translation.
46 Adams Solver
C++ Statements
Notes: There is no contact stiction in Adams. Therefore, a slip velocity is necessary to generate
contact frictional forces.
In the case of rotational slip, there must be an axis of rotation. The slip velocity increases
from zero on the axis (r = 0) to a maximum at the edge of the contact area (r = R). We are
using the assumption that the contact area is circular.
The slip velocity is used to compute a coefficient of friction (mu). To compute mu in the case
of rotation, Adams uses the slip velocity at r = R/2. This can be thought of as the average slip
velocity of the entire contact area. This slip velocity is defined as v.
The kinematic relationship between the given slip velocity (v) and the corresponding angular
slip velocity (w) is:
w = v/(R/2)
or
w = 2v/R
The angular slip velocity (w) is used to compute the contact friction torque in the same way
translation slip velocity (v) is used to compute the contact friction force.
The magnitude of the contact friction torque is given by the formula:
2
T = --- RF
3
2
Where R is the radius of the contact area (which is assumed to be circular). The coefficient --- comes from
3
Marks' Standard Handbook for Mechanical Engineers.
Caution: If you need some other formulation of the friction torque, the only alternative is to write your
own friction force subroutine (CFFSUB). An example is given at the end of this section.
Contact Prediction
Contact is fundamentally a discontinuous event. When two geometries come into contact:
 A large normal force or an impulse is generated.
 The velocities of the bodies change sign.
 The accelerations are almost discontinuous, and have a large spike. This spike represents the impulse
that was generated due to the contact.
The bodies usually separate because of the contact forces or impulses. Numerical integrators assume that the
equations of motion are continuous. A contact event is, therefore, quite hard for an integrator to solve
CONTACT 47
C++ Statements
through. Adams Solver (C++) contains a contact predictor that predicts the onset of contact and controls the
integrator step size accordingly. The following paragraphs briefly summarize the contact prediction
algorithm.
When Adams Solver (C++) detects a new contact, it calculates the penetration and penetration velocity
between the two geometries. From these two values, Adams Solver (C++) estimates a more refined contact
time. Adams Solver (C++) rejects the current time step and uses the refined step size to accurately sense the
onset of contact.
Furthermore, the integrator order is set to one, so that Adams Solver (C++) does not use the time history of
the system to predict the future behavior of the system.
This algorithm essentially ensures that:
 The penetration for a new contact is small.
 The integrator is at first order when the contact event occurs.
 The integrator is taking small time steps.
Contacts and Analysis Mode Issues

This section explains how the various analysis modes deal with contact, and provides modeling tips on how
to successfully negotiate difficult contact events.
Contacts and Static Equilibrium
Both the static and quasi-static equilibrium analysis modes use Newton-Raphson (NR) iterations to solve the
nonlinear algebraic equations of force balance. The Jacobian matrix of first partial derivatives and the residue
of the equations of motion are used to set up an iterative scheme that normally converges to the solution.
The Jacobian matrix is a measure of the stiffness matrix of the system. The inverse of the Jacobian is, therefore,
the compliance in the system. The NR algorithm ensures that the system solution moves in the direction of
most compliance (least stiffness). When a contact is active, the stiffness in the direction of the normal force
is high, so the NR algorithm modifies the system states to decrease this force. If a contact is inactive, there is
no stiffness in the direction of increasing contact. The NR algorithm will likely compute a large movement
in this direction, leading to excessive penetration. During the very next iteration, since the contact force may
turn on, a large stiffness is detected in this direction, and the algorithm will change the system to dramatically
reduce the amount of penetration. It is not uncommon for the algorithm to overreact to this stiffness and
move the system sufficiently to deactivate the contact. The algorithm may never be able to resolve this
discontinuity in the system.
Adams Solver (C++) anticipates this situation and uses a contact-force-sensing mechanism to avoid excessive
contact. You can further enhance this method, however, by choosing the correct equilibrium parameters.
Here are some modeling tips for aiding equilibrium (static) analysis (for more information on equilibrium
analysis, see the EQUILIBRIUM statement):
 If possible, make sure that all contacts are active, and each contact penetration is small. This will
ensure that the contact forces are small, and the system is aware of the contacts.
 Set TLIMIT and ALIMIT small enough so gross contact violations are avoided.
 Increase the maximum number of iterations, MAXIT, so that you can get to convergence in spite of
the small values for TLIMIT and ALIMIT.
48 Adams Solver
C++ Statements
 Avoid neutral equilibrium situations. If you know that your model has neutral equilibrium
situations, increase STABILITY (try STABILITY = 0.1). Also increase MAXIT, the maximum
number of iterations you will allow to obtain convergence.
 See Best Practices for Working with Contacts for more information.
Contacts and Kinematics
In kinematically determinate systems, the system configuration is completely defined by the system
constraints (JOINTs, JPRIMs, COUPLERs, and so on) and MOTIONs. The contact penetration and force
at each configuration can only be obtained as outputs of this analysis. CONTACTS will not be able to
determine the configuration of the system.
Contacts and Linear Analysis
If contacts are active at the configuration at which linearization is performed, there will be a high stiffness in
the direction of the normal force. Therefore, you will see a large frequency corresponding to this stiffness. If
contacts are inactive, they will have no effect on the eigenvalues of the system.
Contacts and Dynamics
Default Corrector for Dynamics
The modified corrector (Integrator/Corrector=Modified) is the default for all models that contain
CONTACTS.
Handling solution difficulties:
Sometimes, you may encounter repeated corrector failures when a contact occurs. This is usually caused by:
 Too large a value for STIFFNESS (for IMPACT) or PENALTY (for POISSON).
 Too tight of an integration error.
 Too small of a value for FRICTION_TRANSITION_VELOCITY and
STICTION_TRANSITION_VELOCITY.
 Too large of a value for MU_STATIC and MU_DYNAMIC.
The following modeling tips will help dynamic analyses. For more information on integrator settings, see the
INTEGRATOR statement.
 Reduce STIFFNESS or PENALTY by a factor of 10 and see if Adams Solver (C++) can solve
through the contact.
 Increase the integration error tolerance using /ERROR=value. A larger integrator error results in a
looser corrector convergence criterion.
 Reduce damping. This decreases the duration of the contact and can help simulations.
 Set the maximum integration order to 2, using INTEGRATOR/KMAX=2. Lower-order integrators
are more stable than higher-order integrators.
 Set HMAX to a small value to prevent the integrator from taking large steps.
 Use the SI2 formulation. The corrector for this formulation is more stable than standard GSTIFF,
and may solve the problem where the standard GSTIFF failed.
 Always run a model without contact friction first, and refine the functioning model by adding
friction later.
CONTACT 49
C++ Statements
 If the addition of frictional forces causes numerical difficulties or simulation slowdowns, gradually
increase the values for STICTION_TRANSITION_VELOCITY and
FRICTION_TRANSITION_VELOCITY. Also reduce the coefficients of friction, which usually
helps the integrator.
Flexible Bodies
Flexible Bodies used in Contacts do not need a corresponding GRAPHICS statement. The geometry for the
Flexible Body is extracted from the Modal Neutral File (MNF), which is required.
FE Parts
When an FE Part is selected in Adams View to be used in Contacts, a GRAPHICS object is created.
For 3D FE Parts, the GRAPHICS object is a Parasolid file that represents the surface of the FE Part in its
undeformed state. The Parasolid file will be tessellated for contact. The tessellation is updated as the FE Part
deforms. 3D FE Part Contact can only be used with the RAPID Geometry Engine. 3D FE Part to 3D FE
Part Contact is supported. 3D FE Parts can be used in contact with all 3D geometry except Flex Body. 3D
FE Parts cannot be used in Contact with 2D geometry or with 2D FE Parts. When a 3D FE Part contacts a
Sphere, the Sphere is treated analytically. No other 3D geometry types are treated analytically.
For 2D FE Parts, the GRAPHICS object is the FE Part centerline. 2D FE Parts can be used in contact with
only Curves, Circles and other 2D FE Parts. No other 2D geometry types are supported.
The FE Part must be the IGEOM in all 2D and 3D Contacts, except when FE Part to FE Part Contact is
used. Lists of geometry are not supported on the FE Part but they are on JGEOM, when it is not an FE Part.
50 Adams Solver
C++ Statements
Caution:  An artificially low value of stiffness or penalty will not generate the necessary contact forces.
You may see a loss of energy when none is expected.
 If you find that your model response changes as the number of output steps is modified,
use INTEGRATOR/HMAX=value to control the integrator step-size and the quality of the
solution.
 The HHT integrator is incompatible with restitution (POISSON) contact.
If your model uses different length units than the stiffness properties you would like to use,
you need to scale the stiffness by:
length conversion factor**exponent
The reason for this is that the contact force due to penetration is defined as:
Adams View will do this conversion for you if you change the units under Settings.
However, you will need to do it if you enter the parameters in different units.
Example:
k = 3800 N/mm
e = 2.0
current model units: force = N, length = m
stiffness to enter for contact = 3800*(1000**2) = 3.8e9

Also note that only length is raised to the exponent, so if you have a different force unit, you
would only scale it by the force conversion factor.
 Contact cannot be defined between a Flexible Body and a list of 3D geometries

 FLIP cannot be used with flexible bodies
 The edges used in flexible body contact are modeled as 2D polylines. Higher order
interpolation is not allowed. Because they are 2D geometry, they may contact any other 2D
geometry (rigid or flexible). They cannot be used in contact with 3D geometry.
 The thickness of shell elements is ignored in flexible body contact.
CONTACT 51
C++ Statements
Tip: If you notice that energy is dissipated during contact events, note the following:
 Impact method - A three-dimensional contact with zero damping can exhibit some
dissipation of energy during the impact. The dissipation is due to the numerics of the
integration algorithm. To reduce the dissipation, reduce the time step or tighten (decrease)
the error tolerance.
 Restitution method - A three-dimensional contact with coefficient of restitution set to one
should conserve energy. If you notice some dissipation, try increasing the PENALTY
argument. Recall that the larger the PENALTY argument, the more exact the contact
constraint will be enforced. In the case of intermittent contact and a restitution coefficient
set to one, a larger penalty parameter more exactly enforces the conservation of
momentum during the contact event.
The PENALTY argument is analogous to the stiffness in the IMPACT function. The
larger the stiffness, the smaller the penetration. Parts with low mass (less than 0.01 kg) may
need the PENALTY argument reduced by several orders of magnitude to avoid integrator
failures.
Note: Solid-to-solid contact is limited to external contact surfaces. So, to take advantage of
analytical contact detection for sphere or cylinder geometry and use an internal surface for
contact one must specify TYPE = SPHERE_TO_SPHERE or
CYLINDER_TO_CYLINDER.
Material Contact Properties

The table below shows material types and their commonly used values for the dynamic coefficient of friction
and restitution.
Material 1: Material 2: Mu static: Mu dynamic: Restitution coefficient:

Dry steel Dry steel 0.70 0.57 0.80
Greasy steel Dry steel 0.23 0.16 0.90
Greasy steel Greasy steel 0.23 0.16 0.90
Dry aluminium Dry steel 0.70 0.50 0.85
Dry aluminium Greasy steel 0.23 0.16 0.85
Dry aluminium Dry aluminium 0.70 0.50 0.85
Greasy aluminium Dry steel 0.30 0.20 0.85
Greasy aluminium Greasy steel 0.23 0.16 0.85
52 Adams Solver
C++ Statements
Material 1: Material 2: Mu static: Mu dynamic: Restitution coefficient:

Greasy aluminium Dry aluminium 0.30 0.20 0.85
Greasy aluminium Greasy aluminium 0.30 0.20 0.85
Acrylic Dry steel 0.20 0.15 0.70
Acrylic Greasy steel 0.20 0.15 0.70
Acrylic Dry aluminium 0.20 0.15 0.70
Acrylic Greasy aluminium 0.20 0.15 0.70
Acrylic Acrylic 0.20 0.15 0.70
Nylon Dry aluminium 0.10 0.06 0.70
Nylon Greasy aluminium 0.10 0.06 0.70
Nylon Acrylic 0.10 0.06 0.65
Nylon Nylon 0.10 0.06 0.70
Dry rubber Dry steel 0.80 0.76 0.95
Dry rubber Greasy steel 0.80 0.76 0.95
Dry rubber Dry aluminium 0.80 0.76 0.95
Dry rubber Greasy aluminium 0.80 0.76 0.95
Dry rubber Acrylic 0.80 0.76 0.95
Dry rubber Nylon 0.80 0.76 0.95
Dry rubber Dry rubber 0.80 0.76 0.95
Greasy rubber Dry steel 0.63 0.56 0.95
Greasy rubber Greasy steel 0.63 0.56 0.95
Greasy rubber Dry aluminium 0.63 0.56 0.95
Greasy rubber Greasy aluminium 0.63 0.56 0.95
Greasy rubber Acrylic 0.63 0.56 0.95
Greasy rubber Nylon 0.63 0.56 0.95
Greasy rubber Dry rubber 0.63 0.56 0.95
Greasy rubber Greasy rubber 0.63 0.56 0.95
Caution: An artificially low value of stiffness or penalty will not generate the necessary contact forces.
You may see a loss of energy when none is expected.
If you find that your model response changes as the number of output steps is modified, use
INTEGRATOR/HMAX=value to control the integrator step-size and the quality of the
solution.
CONTACT 53
C++ Statements
Best Practices for Working with Contacts

The following list includes tips for working with contacts:
 Step size - Simulations allowed to run at large relative step sizes may cause contacts to have trouble
contributing to convergence. Large displacements (especially rotations) during integration steps can
cause significant discontinuities. Running with a smaller hmax can help some models by limiting the
predictor-induced displacements.
 Equilibrium - Static equilibrium is a very difficult problem to solve with contacts. Use good
modeling techniques, such as making sure that the objects expected to be in contact at equilibrium
are initially in contact in the input configuration. If this is not feasible, make sure that the objects
expected to be in contact are very close so that the contacts can be detected during equilibrium
iterations. It will also help to consider the appropriate TLIM and ALIM to help limit the
perturbations for finding equilibrium. Use dynamic equilibrium for models that have difficulty
finding static equilibrium.
 Thin shells - During one solution step, Adams may take several integrator steps in order to satisfy
predictor-corrector requirements. If input geometry is very thin, there is a possibility that one
geometry may completely pass through another, resulting in invalid volume of intersection
calculations. This can result in missed contacts, passthroughs, or generation of unusually high
contact force. Reducing hmax can help prevent this problem.
 Friction - Friction calculations are highly discontinuous and can cause numerical convergence
problems, especially at low relative velocities. The friction difficulties compound the already difficult
contact evaluations. Whenever possible, run a model without contact friction first, and refine the
functioning model by adding friction later. If the addition of frictional forces causes numerical
difficulties or simulation slowdowns, gradually increase the values for
STICTION_TRANSITION_VELOCITY and FRICTION_TRANSITION_VELOCITY. Also
reduce the coefficients of friction, which usually helps the integrator.
 Complex geometry - The time required to retrieve contact intersection information from the
geometric modeler is directly related to the complexity of the given geometry. Some methods are
deployed to bound geometry to avoid unnecessary calls when possible, but complex geometry can
still unduly affect the simulation. Consider the actual contact expected between the geometric pairs.
Trim or split the geometry as much as possible to assign contacts to the actual areas of contact
interest. Also, when possible, substitute imported or general geometry with geometric primitives,
such as cylinders and spheres. These shapes branch into a much faster calculation algorithm.
 Impact versus Restitution - The coefficient of restitution was provided for the case where no impact
values were available and restitution values were obtainable from material references or physical
testing. In general, the impact method is more numerically smooth and will result in faster
simulations. In addition, the impact method provides greater control of the contact behavior, such
as inclusion of damping, and force exponent, which can help tune a numerically satisfying result. In
general, the coefficient of restitution method should only be used when coefficient of restitution
data is available and impact values are not. If a method can be used to derive or determine impact
parameters for the given geometry, it should be used.
 Use Stabilized Index 2 Integrator - The Stabilized Index 2 (SI2) integrator provides better solutions
for velocities and derived accelerations without spikes. These acceleration spikes can have adverse
effects on contact behavior, so the SI2 integrator is the best choice for most contact models.
54 Adams Solver
C++ Statements
 Avoid CONSTANT_BDF (FORTRAN Only) - The constant BDF integrator was created for early
design iterations for increased robustness at the cost of accuracy. Models with contacts have been
found to perform poorly with constant BDF. Although the model will run more robustly, many
observations of contacts missing have been observed.
 2D Approximation for Contact Modeling Whenever Possible - When applicable, represent the
contact event using 2D elements. Choose from point-to-curve, curve-to-curve, or use the IMPACT
function defined in a SFORCE, VFORCE, or GFORCE element.
 Analytical Contact - Analytical contact should be used whenever possible.
 Contact Parameters (Stiffness, Damping, Force Exponent) - Take into account the mass and
inertia of each part in the mechanism and the resulting velocities at which the contact bodies are
traveling with respect to each other. Based on this, ensure that the contact parameters are defined
with appropriate values.
Examples
The example below demonstrates contact between two generic three-dimensional geometries.
star_geneva.xmt_txt is a geometry file that was generated by Parasolid. Adams View or any CAD package
using Parasolid as its geometry package can generate this file. It contains two geometries, SOLID4 and
SOLID3. Contact is to be defined between these two geometries.
The .adm file portion for this example is as follows:
MARKER/30027, PART = 1005
GRAPHICS/11,
, EXTERNAL,
, FILE = star_geneva.xmt_txt,
, ELEMENT = SOLID4,
, RM = 30027
!
GRAPHICS/12,
, EXTERNAL,
, ELEMENT = SOLID3,
, RM = 30028
An impact-type contact would be defined as:
CONTACT/1,
, IGEOM=11,
, JGEOM=12,
, IMPACT,
, STIFFNESS = 1E6,
, DAMPING = 10,
, DMAX = 0.1,
, EXPONENT = 2.2
A POISSON-type contact would be defined as:
CONTACT/1,
, IGEOM=11,
, JGEOM=12,
, POISSON,
CONTACT 55
C++ Statements
, PENALTY = 1E5,
, RESTITUTION_COEFFICIENT = 0.6
Below is an example of lists of geometry. Geometries 11 and 12 must belong to one part. Geometries 13, 14,
and 15 must all be on one part. Geometries 12, 13, and 15 are flipped.
CONTACT/1,
, IGEOM = 11, 12
, JGEOM = 13, 14, 15
, IFLIP_GEOMETRY = 12
, JFLIP_GEOMETRY = 13, 15
, IMPACT,
, STIFFNESS = 1E6,
, DAMPING = 10,
, DMAX = 0.1,
, EXPONENT = 2.2
Below is an example of user-written subroutines in contacts. The normal force subroutine (CNFSUB) and
the friction force subroutine (CFFSUB) are in the same library (cnforc1).
CONTACT/1
, IGEOM = 7
, JGEOM = 6
, NORMAL_ROUTINE = cnforc1::CNFSUB
, FRICTION_ROUTINE = cnforc1::CFFSUB
, NORMAL_FUNC = USER(1.0E+004, 1.0, 1000, 0.1)/
, FRICTION_FUNC = USER(0.37, 0.30, 10.0, 10)
The figure below shows a representation of the star_geneva mechanism.
star_geneva Mechanism
56 Adams Solver
C++ Statements
The example below demonstrates how to specify contact between two two-dimensional geometries:
GRAPHICS/11, CURVE, RM = 30027, CID = 147
!
GRAPHICS/12, CIRCLE, CM = 30028, RADIUS = 1.36
Below is an example of 2D contact for a FLEX_BODY. IEDGE is the ID of a MATRIX statement listing the
nodes on the FLEX_BODY which define the edge.
CONTACT/1
, IFLEX = 1
, IEDGE = 2
, JGEOM = 1
, IMPACT
, STIFFNESS = 1.0E+005
, DAMPING = 10
, DMAX = 0.1
, EXPONENT = 2.2
CONTACT 57
C++ Statements
Contact Parameters for Parts with Small Mass

This document gives a method for estimating contact stiffness and damping parameters in Adams for parts
with small mass.
The default contact stiffness and damping coefficients in Adams are:
 Stiffness = 1.0E+05 N/mm
 Damping = 10.0 N-s/mm
These coefficients were chosen for parts whose mass is on the order of 1.0 Kg and which are made of steel.
Call this part the "default part".
For parts with small mass these coefficients should be reduced to optimize Adams Solver performance and to
minimize the chance of simulation failure.
In the following discussion, assume that:
 M = Part mass
 R = Average dimension (size) of part (order of magnitude is sufficient)
 g = gravitational acceleration
 G = G force (1 G = M*g)
Since steel has a density of about 8000 Kg/m^3, the default part would have a radius of about 30 mm
(assuming it is spherical).
The expression for the contact spring force is:
e
F = Kx
where:
 F = Contact force
 K = Contact Stiffness
 x = penetration
 e = exponent (default value in Adams is 2.2)
We would like to calculate the contact force in G's on the default part when its penetration is 0.1% of its
radius:
We choose a penetration of 0.1% because most well behaved contact models do not exceed this amount.
To compute the appropriate stiffness for a small part, we specify that it should experience the same G force
when it has a penetration of 0.1% of its radius.
Assume the following small part properties:
 M = 4.0e-06 Kg
 R = 1 mm
 e = 2.2
58 Adams Solver
C++ Statements
We need to solve the following equation for K:

5*M*g = K*(0.001)^2.2
We get:
K ≅ 800N ⁄ mm
When both parts in contact are moving, the reduced mass may give a more accurate estimate of stiffness.
The reduced mass is given by:
M1 M2
M = ---------------------
M1 + M2
The contact damping coefficient for small parts should be calculated using critical damping.
The expression for critical damping is:
C = 2 KM
For the small part given above, the damping is:
The values for stiffness and damping are order of magnitude estimates. They can be tuned further (via
experiment) to refine performance.
Limitations
The contact code in Adams is designed to work with intersection volumes that are "thin", that is, that the
penetration squared is less than the area of contact. If this condition is violated, then the contact behavior is
unpredictable.
The below rule explains this condition:
If area > 2*d*d then contact force is calculated
If area < 2*d*d then contact force set to zero
where:
 area = contact area
 d = penetration
This condition was added to prevent the contact force from becoming excessively large or from being applied
in an unexpected direction.
See other Forces statements available.
COUPLER 59
C++ Statements
COUPLER
A COUPLER statement relates the translational and/or the rotational motion of two or three joints.
Format
Arguments
FUNCTION=USER(r1[,...,r3 Specifies up to thirty user-defined constants passed to the externally

0]) defined subroutine COUSUB, COUXX, COUXX2. These subroutines
define the coupler displacement constraint function, and provide its first
and second order partials, respectively (see the COUSUB, COUXX, COUXX2
subroutines).
JOINTS=id1,id2[,id3] Specifies the identifiers of as many as three joints whose translational
and/or rotational displacements are to be coupled. You can only specify
identifiers of translational, revolute, and cylindrical joints.
60 Adams Solver
C++ Statements
ROUTINE=lib1::cou1, Specifies alternative library and subroutine names for the user subroutines
lib2::cou2, lib3::cou3 COUSUB, COUXX, and COUXX2 respectively.

SCALES=[r1,]r2[,r3] Defines the relative motion of the joints specified with JOINTS. Adams
Solver (C++) uses the values in the SCALES argument to form the
equation:
(r1 * q1) + (r2 * q2) + (r3 * q3) = 0,
where r1, r2, and r3 are the scale factors for the three joints, and for each
joint, q1, q2, and q3 are the translational or rotational displacements of the
joint I marker with respect to the joint J marker. Suppose two joints are
being coupled, and SCALES=1,-2. The equation that relates the two joints
is:
(1 * q1) + (-2 * q2) = 0
or
q1 = 2 * q2.
The displacement (q1) of the I marker with respect to the J marker in the
first joint is twice that of the displacement (q2) of the I marker with respect
to the J marker in the second joint; the two displacements have the same
sign. If two joints are specified in the JOINTS argument, r2 must be
specified. Adams Solver (C++) assumes r2 if only one value is specified and
uses the default value of 1 for r1.
If three joints are specified in the JOINT argument, you should either
specify three scale values r1, r2, and r3, or provide only two scale values. In
the latter case, the two values are assigned by Adams Solver (C++) to r2 and
r3 (in this order) while r1 is given the default value 1.0.
Defaults: r1 (1); r2, r3 (none)
Range: non-zero real numbers

COUPLER 61
C++ Statements
Indicates whether joints transfer translational or rotational motion. If the

coupler includes no cylindrical joints, do not use TYPE. However, if the
coupler includes one or more cylindrical joints, TYPE must be used. In
that case, input T (translational) or R (rotational) for each joint specified
with JOINTS, even the translational or revolute joints. Because Adams
Solver (C++) assumes that translational joints transfer translational motion
and that revolute joints transfer rotational motion, Adams Solver (C++)
ignores Ts and Rs for translational and revolute joints; they are placeholders
only. But because a cylindrical joint permits either translational or
rotational motion, Adams Solver needs a T or R for each cylindrical joint
to determine the type of motion on which the coupler acts.
Extended Definition
The COUPLER statement relates the translational and/or rotational motion of two or three joints. This
statement lets you deliver or couple motion from one area of a mechanism to another. Components whose
behavior might be approximated with this statement are combinations of hydraulic generators, motors, and
pistons, and include flexible, rotational, transmission cables
62 Adams Solver
C++ Statements
Tip:  To measure translational motion, Adams Solver (C++) finds the displacement of the I
marker origin with respect to the J marker origin along the J marker z-axis. Positive
translations are along the positive z-axis of J, and negative translations are along its negative
z-axis.
 To measure rotational motion, Adams Solver (C++) finds the displacement of the x-axis of
the I marker with respect to the x-axis of the J marker about the common z-axis of the I
and the J markers. To determine the positive sense of rotation, apply the right-hand rule to
the z-axis.
 The COUPLER can relate any combination of translational and rotational motions. A
two-joint COUPLER, for example, can relate translational motion to translational
motion, rotational to rotational, or translational to rotational.
 The COUPLER is a constraint between joint degrees of freedom. Therefore, it models
only the reaction forces that are along or about the degrees of freedom that are being
coupled.
You can model a pair of mating spur gears as a COUPLER between two REVOLUTE
joints. If (I1, J1) are the I and J markers of the first joint and (I2, J2) are the I and J
markers of the second joint, the COUPLER constraint is:
AZ(I1,J1) * scale_1 + AZ(I2,J2) * scale_2 = 0
where scale_1 and scale_2 are the radii of the two gears.
The reaction forces generated by the COUPLER are the torques at the two joints required
to maintain the constraint shown above. The reaction on the first joint is the torque about
the z-axis of marker J1. The reaction on the second joint is the torque about the z-axis of
marker J2. You can compute the tooth force from these torques, but Adams Solver (C++)
does not explicitly solve for them.
You can also model a rack and pinion gear as a COUPLER relating the rotation in a
REVOLUTE joint, with the translation in a TRANSLATIONAL joint. If (I1, J1) are the I
and J markers of the REVOLUTE joint and (I2, J2) are the I and J markers of the
TRANSLATIONAL joint, the COUPLER constraint is:
AZ(I1,J1) * scale_1 + DZ(I2,J2,J2) * scale_2 = 0
where scale_1 is the pinion radius, and scale_2=1.
The COUPLER reaction on the REVOLUTE joint is a torque about the z-axis of Marker
J1, and the reaction on the TRANSLATIONAL joint is a force along the z-axis of Marker
J2.
COUPLER 63
C++ Statements
Caution:  When measuring rotational motions in couplers, Adams Solver (C++) assumes radians
rather than degrees. Use a D after the value to indicate that the units are degrees.
 When measuring translational motions in couplers, Adams Solver (C++) uses the system
units of translation.
 If one or more cylindrical joints for the coupler is specified, Adams Solver (C++) requires
you to input one or more entries for the TYPE argument, depending on the order of the
cylindrical joint(s) in the JOINTS argument list. Adams Solver (C++) must have a type
entry for every cylindrical joint and a place holder entry for every joint entered before a
cylindrical joint on the JOINTS argument.
Examples
COUPLER/01, JOINTS=4,6, TYPE=T:R, SCALES=90D, -1
This COUPLER statement relates the translational motion at Joint 4 to the rotational motion at Joint 6. Joint
4 is either a translational or cylindrical joint, and Joint 6 is either a revolute or cylindrical joint. The SCALES
argument indicates the relationship:
(90D)q1 - q2 = 0
or
(90D)q1 = q2.
In other words, when q1 is a positive translation of one system unit, q2 is a positive rotation of 90 degrees.
Internal to Adams Solver (C++), all values entered in degrees are converted to radians for calculation purposes.
The figure below shows a coupler.
Coupler
See other Constraints available.

64 Adams Solver
C++ Statements
CURVE
The CURVE statement defines a three-dimensional parametric curve that you can reference using PTCV,
CVCV, GRAPHICS statements, and function expressions.
Format
Arguments
CLOSED Specifies that the curve meets at the ends. If you specify CURVE_POINTS, Adams
Solver (C++) attempts to compute a curve that meets at the ends and has
continuous first and second derivatives across the closure. If you specify
FUNCTION, you must ensure that the defined curve meets at the ends and has
continuous first and second derivatives across the closure. If the curve is closed, the
first and last control or curve points must be the same. During a simulation, Adams
Solver (C++) moves a PTCV or CVCV contact point across the closure, if
necessary.
CURVE_POINTS Specifies that the MATRIX contains data points on the curve.
FUNCTION=USER Defines and passes constants to CURSUB, the user-written subroutine that
(r1[,...,r30])/ computes the curve coordinates and derivatives (see the CURSUB subroutine). The
FUNCTION argument must be either the last argument in the CURVE statement
or it must be followed by a backslash (\).
MATRIX=id Specifies a MATRIX statement that contains data for a curve. The matrix contains
the x, y, and z coordinates of the curve points. The matrix should have a row for
each point and three columns containing the x-, y-, and z-coordinates of the points.
You must supply at least four curve points. The first and last points must be the
same for a closed curve.
CURVE 65
C++ Statements
MAXPAR=r Specifies the maximum value of the curve parameter for a user-written curve.
Adams Solver (C++) uses this value when drawing a curve graphic. The maximum
parameter value is always 1.0 for curves you define using CURVE_POINTS.
Default: 1.0
MINPAR=r Specifies the minimum value of the curve parameter for a user-written curve.
Adams Solver (C++) uses this value when drawing a curve graphic. The minimum
parameter value is always -1.0 for curves you define using CURVE_POINTS.
Default: -1.0
OPEN Specifies that the curve does not meet at the ends. Adams Solver (C++) does not
allow a PTCV or CVCV contact point to move beyond the end of the curve.
ORDER Specifies the order of the B-spline interpolating the curve. A
B-spline of order K means that it is made up of piecewise polynomial segments of
degree K-1. A cubic B-spline is order 4. A B-spline of order 2 is called a polyline
because it is made up of straight line segments between each of the
CURVE_POINTS. It is important to note that a B-spline of order K will have K-
2 continuous derivatives. The discontinuities appear where the polynomial
segments join together. Increasing the order of the B-spline arbitrarily may
introduce unwanted oscillation into the curve.
Default: 4
Range: ORDER > 2

ROUTINE=libname: Specifies an alternative library and name for the user subroutine CURSUB.
:subname
Extended Definition
The x, y, and z coordinates of a point on a parametric curve are functions of an independent parameter, u. As
u varies from its minimum to maximum value, the functions x(u), y(u), and z(u) sweep out points on the
curve. A simple example of a parametric curve is a helix defined by the following equations and illustrated in
the figure below:
x = cos(u)
y = sin(u)
z = u
Example of a Parametric Curve
66 Adams Solver
C++ Statements
Adams Solver (C++) lets you create curves in two ways:

 Enter curve points to which Adams Solver (C++) matches a curve.
 Write a CURSUB evaluation subroutine with which Adams Solver (C++) computes curve
coordinates and derivatives.
A uniform B-spline is a piecewise polynomial spline used in many CAD (computer-aided design)
applications. A B-spline is defined by control points that form a polygon in space and a knot vector. Adams
Solver (FORTRAN) uses a non-uniform knot vector with quadruple multiplicity at both ends. The curve
starts at the first control point and ends at the last. In between, it is attracted to, but does not necessarily hit,
the intermediate control points. Adams Solver (FORTRAN) parameterizes a B-Spline starting at -1 and
ending at +1. The figure below shows a set of control points and the B-spline curve it defines.
Control Points and the Resulting B-Spline
CURVE 67
C++ Statements
Adams Solver (C++) computes the control points internally from the curve points.
To use a different type of curve, or to model an analytically-defined curve such as a helix, you can write a
CURSUB user-written subroutine. When providing a CURSUB, you can also specify MINPAR and MAXPAR
to define the limits of the curve. These default to -1 and +1, respectively.
A curve is OPEN or CLOSED. A CLOSED curve meets at the ends, connecting the curve at minimum and
maximum parameter values. Adams Solver (C++) automatically moves a PTCV or CVCV contact point
across the closure of a CLOSED curve, if needed. For instance, you can model a cam profile as a CLOSED
curve, and Adams Solver (C++) allows the follower to move across the closure as the cam rotates.
Caution: Adams Solver (C++) applies a force to prevent a PTCV or CVCV contact point from moving
off the end of an open curve. For an open curve that is referenced by a PTCV or CVCV
constraint, be sure to define an expected range of contact.
Examples
CURVE/5, OPEN, CURVE_POINTS, MATRIX=2

This statement creates an open curve using the curve point coordinates in MATRIX/2. Adams Solver (C++)
computes a B-spline curve to fit the points.
CURVE/7, CLOSED, CURVE_POINTS, MATRIX=1, ORDER=2
This statement creates a closed curve of order 2 (polyline) using the curve point coordinates in MATRIX/1.
Adams Solver (C++) computes a B-spline curve to fit the points.
Applications
The PTCV, CVCV, and GRAPHICS statements reference the CURVE statement:
 The PTCV uses a curve to define a point-curve constraint.
 The CVCV statement uses two curves to define a curve-curve constraint.
 The GRAPHICS statement generates a graphic depicting the curve.
In each case, you must specify a reference marker that identifies the part to which the curve attaches and the
coordinate system to which Adams Solver (C++) applies the curve coordinates. You can also reference a curve
in a function expression, much like the cubic or Akima splines (see the CURVE function).
68 Adams Solver
C++ Statements
CVCV
The CVCV statement defines a curve-to-curve constraint that restricts a planar curve on one part that is to
be in contact with, and tangent to, a planar curve on a second part. The curves must lie in the same plane,
but the parts to which they are attached may undergo three-dimensional motion.
Format
CVCV 69
C++ Statements
Arguments
ICURVE=id Specifies the identifier of a CURVE statement from which Adams Solver constructs the first
curve. The IRM marker specifies the coordinate system in which the x, y, z coordinates of
ICURVE are specified. The curve is attached rigidly to the part containing the IRM marker.
The z component of the curve must be zero. As a result, the curve lies in the x-y plane of the
IRM marker.
IDISP=x,y,z Specifies the initial point of contact on the first curve. Adams Solver (C++) uses a point on
the curve nearest to that specified if the point specified is not exactly on the curve. By default,
the contact point is specified in the IRM marker coordinate system. You may supply the
IICM argument and enter IDISP in IICM marker coordinates if another coordinate system
is more convenient.
Adams Solver (C++) assembles the system with the contact at the specified point on the curve
if you supply IDISP. Adams Solver (C++) assumes the initial contact is at the point on the
first curve closest to the second curve at the input configuration if you do not supply IDISP.
In this case, Adams Solver (C++) may adjust that contact point to maintain other part or
constraint initial conditions.
IFLOAT=id Specifies the identifier of a floating marker. Adams Solver (C++) positions the origin of the
IFLOAT marker to be at the instantaneous point of contact on the first curve, which is also
the global position of the JFLOAT marker on the second curve. Adams Solver (C++) orients
the IFLOAT marker so that its x-axis is along the tangent at the instantaneous contact point,
its y-axis is along the instantaneous normal, and its z-axis along the resultant binormal. For
a CVCV constraint, the binormal of ICURVE is always parallel to the z-axis of the IRM
marker. The IFLOAT and IRM markers must lie on the same part.
IICM=id Specifies the identifier of a fixed marker defining the coordinate system in which the values
for IDISP are defined. The IICM marker must be on the same part as the IRM marker.
Default: IRM marker

IRM=id Specifies the identifier of a fixed marker on the part containing ICURVE. The IRM marker
identifies not only the part that the ICURVE is attached to, but also identifies the coordinate
system in which the coordinates of ICURVE are specified. Adams Solver (C++) constructs
the ICURVE in the x-y plane of the IRM marker coordinate system. The IFLOAT and IRM
markers must lie on the same part.
70 Adams Solver
C++ Statements
IVEL=r Specifies the magnitude of the initial velocity of the contact point relative to the part
containing ICURVE. This is the speed at which the contact point is initially moving tangent
to the curve. IVEL is negative if the contact point is moving towards the start of the curve,
positive if the contact point is moving toward the end of the curve, or zero if the contact
point is stationary on the curve.
Adams Solver (C++) gives the contact point the specified initial speed along the first curve if
you supply IVEL. Adams Solver (C++) assumes the initial velocity is zero if you do not
supply IVEL, but may adjust the velocity to maintain other part or constraint initial
conditions.
Default: 0
JCURVE=id Specifies the identifier of a CURVE statement from which Adams Solver (C++) constructs
the second curve. The JRM marker specifies the coordinate system in which the x, y, z
coordinates of JCURVE are specified. The curve is attached rigidly to the part containing
the JRM marker. The z component of the CURVE must be zero. As a result, the curve lies
in the x-y plane of the JRM marker.
JDISP=x,y,z Specifies the initial point of contact on the second curve. Adams Solver (C++) uses a point
on the curve nearest to that specified if the point specified is not exactly on the curve. By
default, the contact point is specified in the JRM marker coordinate system. You may supply
the JICM argument and enter JDISP in JICM marker coordinates if another coordinate
system is more convenient.
Adams Solver (C++) assembles the system with the contact at the specified point on the curve
if you supply JDISP. Adams Solver (C++) assumes the initial contact is at a point on the
second curve closest to ICURVE in the input configuration if you do not supply JDISP. In
this case, Adams Solver (C++) may adjust that contact point to maintain other part or
Default: Closest point to ICURVE in the input configuration

JFLOAT=id Specifies the identifier of a floating marker. Adams Solver (C++) positions the origin of the
JFLOAT marker at the instantaneous point of contact on the second curve, which is also the
position of the IFLOAT marker on the first curve. Adams Solver (C++) orients the JFLOAT
marker so that its x-axis is along the tangent at the instantaneous contact point, its y-axis is
along the instantaneous normal, and its z-axis along the resultant bi-normal. For a CVCV
constraint, the bi-normal of JCURVE is always parallel to the z-axis of the JRM marker. The
JFLOAT and JRM markers must lie on the same part.
CVCV 71
C++ Statements
JICM=id Specifies the identifier of a fixed marker defining the coordinate system in which the values
for JDISP are defined. The JICM marker must be on the same part as the JRM marker.
Default: JRM marker

JRM=id Specifies the identifier of a fixed marker on the part containing JCURVE. The JRM marker
identifies not only the part the JCURVE is attached to, but also the coordinate system in
which the coordinates of JCURVE are specified. Adams Solver (C++) constructs JCURVE
in the x-y plane of the JRM marker coordinate system. The JFLOAT and JRM markers must
lie on the same part.
JVEL=r Specifies the magnitude of the initial velocity of the contact point relative to the part
containing JCURVE. This is the speed at which the contact point is initially moving tangent
to the curve. JVEL is negative if the contact point is moving towards the start of the curve,
positive if the contact point is moving toward the end of the curve, and zero if the contact
Adams Solver (C++) gives the contact point the specified initial speed along the second curve
if you supply JVEL. Adams Solver (C++) assumes the initial velocity is zero if you do not
supply JVEL, but may adjust that velocity to maintain other part or constraint initial
conditions.
Default: 0
Extended Definition
The CVCV statement defines a curve-to-curve constraint that restricts a planar curve on one part to be in
contact with, and tangent to, a planar curve on a second part. The curves must lie in parallel planes.
Adams Solver (C++) constructs the first curve from the ICURVE curve and IRM marker, and the second
curve from the JCURVE curve and JRM marker. In both cases, the CURVE statement (ICURVE or
JCURVE) defines x and y coordinates along the curve as a function of an independent parameter (u). The z
coordinates of the curves must be zero. The reference marker (IRM or JRM) defines the part on which the
constraining curve is attached and the coordinate system in which Adams Solver (C++) applies the
coordinates from the CURVE statement.
Both ICURVE and JCURVE may be open or closed curves, defined analytically or as a set of discrete data
points. Figure 3 below shows a curve-to-curve constraint.
A CVCV statement removes two degrees-of-freedom from the system. Adams Solver restricts the motion of
the parts such that the curves are always in contact and the curves are tangent at the contact point. The first
curve may slide or roll on the second, but may not move perpendicular to the curve tangents at the contact.
Figure 3 Curve-To-Curve Constraint

72 Adams Solver
C++ Statements
Tip: More than one CVCV statement can reference the same CURVE statement. You can enter
one CURVE statement if the mechanism contains several similar contacts and use it with
several CVCV constraints, each with a different IRM and JRM marker.
CVCV 73
C++ Statements
Caution:  Adams Solver (C++) requires that the curves lie in the same plane, however, this is not
enforced by the CVCV statement. The CVCV statement simply enforces that the two
curves remain in contact. You must build the model so that the curves are held in the same
plane.
 IVEL and JVEL are specified relative to the reference frame of the part containing the IRM
or JRM marker, respectively. In other words, IVEL is the speed of the contact point relative
to the part containing the first curve. This means if the contact point is not moving relative
to part, but the first curve is moving relative to the ground, then IVEL is still nonzero.
 Adams Solver (C++) applies a force to prevent the contact point from moving off the end
of an open curve. For this reason, you may want to specify an open curve that extends
beyond the range of actual curve travel on both ends of the curve.
 The initial conditions arguments, IDISP, JDISP, IVEL, and JVEL, impose constraints that
are active only during an initial conditions analysis. Adams Solver (C++) does not impose
these initial conditions during subsequent analyses.
 For a kinematic analysis, the initial conditions are redundant. Do not use the IDISP,
JDISP, IVEL, or JVEL arguments on the CVCV statements for systems with zero degrees
of freedom. Adams Solver (C++) requires that there be a unique contact point in the
vicinity of the IFLOAT and JFLOAT markers during simulation. If there is more than one
contact point, Adams Solver may be unable to find the correct contact point or may even
jump from one contact point to the next.
One way to ensure that contact points are unique is to specify curve shapes that are convex.
Figure 4 below depicts two curves, the first is convex and the second nonconvex. Note that
for a convex curve, any line segment connecting two arbitrary points on the curve lies in
the domain of the curve (that is, it does not intersect the curve). The same is not true for
the nonconvex curve.
 It is easy to accidently over-constrain a system using the CVCV constraint. For instance, in
a cam-follower configuration, the cam should usually be rotating on a cylindrical joint, not
a revolute joint. If the follower is held by a translational joint and the cam by a cylindrical
joint, the CVCV constraint between the follower and cam prevents the cam from
translating along the axis of rotation (that is, the axis of the cylindrical joint). A revolute
joint would add a redundant constraint in that direction.
Figure 4 Convex and Nonconvex Curves

74 Adams Solver
C++ Statements
Examples
CVCV/20, IFLOAT=402, ICURVE=11, IRM=401, JFLOAT=502,

, JCURVE=12, JRM=501
This statement creates a curve-curve constraint between a curve on the part containing Markers 401 and 402
and a curve on the part containing Markers 501 and 502. CURVE/11 defines the first curve in the coordinate
system of Marker 401. CURVE/12 defines the second curve in the coordinate system of Marker 501.
Applications
The CVCV statement models one curve rolling or slipping along another, such as in a cam-follower
mechanism. Figure 5 illustrates a cam follower.
Adams Solver (C++) automatically moves the contact across the closure as needed when a closed curve is
specified in the CURVE statement. This means that the cam may rotate as many times as needed during the
simulation.
A point-to-curve constraint, PTCV statement, can be used if the follower is small and sharp enough to be
considered a point.
The curves always maintain contact, even when the dynamics of the system would actually lift one curve off
the other, because CVCV is a geometric spatial constraint. You can examine the constraint forces to determine
if lift-off should have occurred. If an accurate simulation of intermittent contact is required, you should
model the contact forces directly using a VFORCE.
The CVCV statement models only one contact. Therefore, if the curves have contact at more than one point
you must enter a CVCV statement for each contact, each with a displacement initial condition (IDISP and
JDISP) near the appropriate point.
Figure 5 Cam-Follower Mechanism

CVCV 75
C++ Statements

76 Adams Solver
C++ Statements
DEBUG
The DEBUG statement outputs data that helps you debug a simulation.
Format
,JMDUMP
DEBUG/ EPRINT , MATLAB
,RHSDUMP
[] Optionally select the item

[[ ]] Optionally select an item combination
DEBUG 77
C++ Statements
Arguments
EPRINT Prints a block of information for each kinematic, static, or dynamic step. This information helps you
monitor the simulation process and locate the source of the error if there is a problem. Each step consists
of two phases: 1) a forward step in time (the predictor for dynamics) and 2) the solution of the equations
of motion (the corrector for dynamics). For the first phase, Adams Solver (C++) prints three or four pieces
of information. The information includes:
 The step number. This is a running count of the number of steps taken and can be used as a
measure of how hard Adams Solver (C++) is working.
 The order of the predictor for dynamics. This corresponds to the order of the polynomial Adams
Solver (C++) uses to predict the solution at the end of the integration step.
 The value of time at the beginning of the step.
 The size of the step.
For the second phase, Adams Solver (C++) prints out the cumulative number of iterations and a table of
information about the iterations. The cumulative number of iterations is a running count of the iterations
needed to solve the equations of motion and can be used as a measure of how many computations Adams
Solver (C++) is performing. The table contains information about the largest equation imbalance (error)
and maximum variable change for each iteration. For each iteration, Adams Solver (C++) prints out seven
or eight pieces of the following information:
 The iteration number. This is one at the beginning of each step and increments by one until
Adams Solver (C++) converges to a solution or exceeds the maximum allowable number of
iterations.
 The absolute value of the largest equation residual error. Each equation should have an error value
close to zero. This number is an indicator of how far Adams Solver (C++) is from a solution. This
number should decrease after every iteration.
 The dataset element associated with the largest equation residual error.
 The equation that has the largest equation residual error for the above dataset element.
 The absolute value of the largest change in a variable. The final iteration should not need to
change variables very much. This number is an indicator of how aggressive Adams Solver (C++)
needs to change variables to approach a solution. This number should decrease after every
iteration.
 The dataset element associated with the absolute value of the largest change in a variable.
 The variable with the largest change for the above dataset element.
 If Adams Solver (C++) has updated the Jacobian, YES appears under the new Jacobian header.
Default: Off
78 Adams Solver
C++ Statements
JMDUMP Dumps the Jacobian matrix at each iteration. The Jacobian is dumped in the working directory in the file
with extension *.jac and root name equal to the one of the message file.
Default: Off
MATLAB When specified in conjunction with the RHSDUMP or JMDUMP flags it changes the output format to
be such that the debug information can be easily imported into Matlab. Importing for example the
Jacobian matrix in Matlab can be useful for purposes such as computing the condition number of the
Jacobian, its norm and so on.
RHSDUM Dumps the values of the right-hand-side vector and states in the solution of each AX=b linear problem.
P The states and right-hand-side are dumped in the working directory in the file with extension *.rhs and
root name equal to the one of the message file.
Default: Off
Caution: An indiscriminate use of the arguments JMDUMP and RHSDUMP can result in an
extremely large tabular output file. If a dataset needs to be debugged, include these
arguments in the DEBUG statement and execute only a brief simulation.
Extended Definition
The DEBUG command section contains additional descriptions on the information returned by
DEBUG/EPRINT command.
Examples
DEBUG/EPRINT
This DEBUG statement generates the information in Figure 6 that appears in the message file.
In this example, Adams Solver (C++) is printing the information for the third step of a dynamic analysis. For
this step, Adams Solver (C++) uses a second-order polynomial to guess the solution. Using a time step of
7.25694E-04, the integration step goes from 6.458333333E-04 to 1.371527778E-03.
After the first iteration, the z velocity equation of PART/245330 has the largest error: its absolute value is
2E+00. The z coordinate of PART/245330 changes the most during the first iteration. The absolute value of
the change is 8.E-04. Adams Solver (C++) updates the Jacobian before the first iteration, but not before the
second or third.
DEBUG 79
C++ Statements
Figure 6 Sample EPRINT Information
See other Analysis parameters available.

80 Adams Solver
C++ Statements
DIFF
The DIFF statement creates a user-defined state variable and defines a first-order differential equation that
describes it.
Format
DIFF 81
C++ Statements
Argument
Specifies an expression for a differential equation or defines the

argument list for the user-written subroutine that defines the
differential equation. To define the equation with an expression,
follow FUNCTION with an equal sign and the expression. To
define the equation with a user-written subroutine, follow
FUNCTION with an equal sign, the character string USER, and
the argument list (r1[,...,r30]) of values and system variables to be
passed to the user-written subroutine DIFSUB (see the DIFSUB
subroutine). In a function expression, the system variable DIF(i) is
the value of the dependent variable defined by the DIFF/i
statement. DIF1(j) is the first derivative of the dependent variable
defined by the DIFF/j statement. Note that the FUNCTION
argument must either be the last argument in the DIFF statement
or be followed by a backslash (\).
IC=r1[,r2] Specifies the initial value of the user-defined variable and,
optionally, an approximate value of the initial time derivative. The
value r1 is the value of the user-defined variable at the start of the
simulation. If you enter an implicit equation, r2 may also need to
be specified, which is an approximate value of the time derivative of
the user-defined variable at the start of the simulation. Adams
Solver (C++) might adjust the value of the time derivative when it
performs an initial conditions analysis. Entering an initial value for
the time derivative helps Adams Solver (C++) converge to a desired
initial conditions solution. You do not need to supply r2 when you
enter a explicit equation since Adams Solver (C++) can compute the
initial time derivative directly from the equation. Adams Solver
(C++) requires you to enter r1.
Default: 0
IMPLICIT Indicates that the function expression or DIFSUB subroutine
defines the implicit form of a differential equation. Adams Solver
(C++) assumes that either the expression or user-written subroutine
defines the explicit form of the equation if IMPLICIT is not
specified. In this case, the time derivative of the state variable is set
to the value of FUNCTION.
82 Adams Solver
C++ Statements
ROUTINE=libname::subname Specifies an alternative library and name for the user subroutine
DIFSUB.

STATIC_HOLD Indicates that the DIFF state is not permitted to change during
static and quasi-static analysis.
DYNAMIC_HOLD Indicates that the DIFF state is not permitted to change during
dynamic analysis.
Extended Definition
describes it. The equation may be dependent on any Adams Solver (C++) state variable available in a function
expression. You can create systems of differential equations by using more than one DIFF statement or LSE
and GSE statements.
Both function expressions and user-written subroutines can access the DIFF state variable and its derivative.
Function expressions access the value by using the function DIF(id) and the derivative by using DIF1(id) (see
DIF and DIF1 functions). In each case, id specifies the identifier of the DIFF statement that defines the variable.
User-written subroutines access the value and derivative by calling the subroutine SYSFNC (see the SYSFNC
subroutine).
The function can be defined by a function expression, or by providing a user-written subroutine. Because
Adams Solver (C++) typically handles a function expression more efficiently than a user-written subroutine,
it is recommended that you use a function expression whenever possible.
The DIFF may be defined in either explicit or implicit form. The following equation defines the explicit form
of a differential equation:
y· = f (y, u, t)
where:
 y· is the time derivative of the user-defined state variable

 y is the user-defined state variable itself
 u is a vector of Adams Solver-defined state variables
You need to use the implicit form if the first derivative of the state variable cannot be isolated. The following
equation defines the implicit form of a differential equation:
0 = F( y, y· , u, t)
DIFF 83
C++ Statements
Caution:  Although you can currently use a DIFF statement to define an implicit, algebraic (rather
then differential) equation, Adams Solver (C++) might not allow this in the future. You
should use VARIABLE statements to define algebraic equations instead.
 During a static analysis, Adams Solver (C++) finds equilibrium values for user-defined
differential variables (DIFFs, GSEs, LSEs, and TFSISOs), as well as for the displacement
and force variables. This changes the initial conditions for a subsequent analysis. Adams
Solver (C++) sets the time derivatives of the user-defined variables to zero if
STATIC_HOLD is not specified during a static analysis, and uses the user-supplied initial-
condition values only as an initial guess for the static solution. Generally, the final
equilibrium values are not the same as the initial condition values. Adams Solver (C++)
then uses the equilibrium values of the user-defined variables as the initial values for any
subsequent analysis, just as with the equilibrium displacement and force values.
However, the user-specified initial conditions are retained as the static equilibrium values if
STATIC_HOLD is specified. Thus, the final equilibrium values are the same as the user-
specified initial conditions. Note that this does not guarantee that the time derivatives of
the user-defined variable are zero after static analysis.
Examples
DIFF/11, IC=1.75,
, FUNCTION = -2.0*DIF(11) + 4.0 + SIN(TIME)
DIFF/12, IC=1.75, IMPLICIT,
, FUNCTION = DIF1(12) + 2.0*DIF(12) - 4.0 - SIN(TIME)
These DIFF statements both define the following differential equation.
y· + 2y - 4 = sin (t), y(0) = 1.75
DIFF/11 defines the equation in explicit form, where the function expression computes y· as shown below.
y· = -2y + 4 + sin (t)
DIFF/12 defines the equation in implicit form, where Adams Solver equates the function expression to zero,
as shown below.
y· + 2y - 4 - sin (t) = 0
Applications
The DIFF statement defines a first order, linear or nonlinear, explicit or implicit, ordinary differential
equation for Adams Solver (C++) to integrate along with the dynamic simulation of a multibody system. The
equation may be independent of the rest of the problem or it may depend upon any variable in the state
vector. The solution to the differential equation can be used in the function expressions which define a
number of other elements in Adams Solver (C++) such as the SFORCE statement. Thus, you can use Adams
Solver (C++) to solve an independent initial value problem, or the differential equations defined by DIFF
statements may be fully coupled with the system of equations that governs the dynamics of the problem.
84 Adams Solver
C++ Statements
DIFF statements are best for creating single equations or small sets of equations. Although you may create
sets of DIFF statements to represent higher order equations or large systems of equations, other Adams Solver
(C++) elements such as TFSISO, LSE, or GSE may be more convenient in these cases.
See other Generic systems modeling available.
END 85
C++ Statements
END
An END delimiter indicates the end of a dataset. Although the file may contain additional data, Adams Solver
(C++) does not read any statements or comments that follow the END statement.
Format
END
See other Dataset delimiter statement available.
86 Adams Solver
C++ Statements
ENVIRONMENT
Using the ENVIRONMENT statement is an alternative way of setting an Adams Solver (C++) runtime
environment variable. For example, rather than using the setenv command when working with the Linux
operating system, one may use the ENVIRONMENT statement instead.
One feature of the ENVIRONMENT statement is the following, the execution of this statement does not
modify the operating system environment; it only affects the Adams Solver (C++) runtime environment for
the model being run. When the simulations are finished, the original operating system environment is left
intact.
A second feature is related to the collection of environment variables one may set. Only environment variables
related to the Adams Solver (C++) may be set. For example, you may not use this statement to set an
environment variable used by other products.
Format
ENVIRONMENT ⁄ NAME = c
ENVIRONMENT ⁄ NAME = c, VALUE = c
ENVIRONMENT ⁄ NAME = c, UNSET
Arguments
NAME=c Specifies a character string for the name of the Adams Solver (C++) runtime
environment variable being set.
VALUE=c Specifies a character string for the value of the Adams Solver (C++) runtime
environment variable being set. Some variables do not need a value to be
specified.
The character string may be enclosed between double quotes.

UNSET Specifies the removal of the variable from the Adams Solver (C++) runtime
environment.
Extended Definition
The operating system environment stands for a set of environment variables. Each of these environment variables
has a name, and it may have an associated value. Both name and value are character strings set by the user
using tools provided by the operating system.
The use of environment variables provides a simple mechanism to let users communicate preferences to a
running computer program. The use of environment variables is a practical way to trigger the execution of
undocumented features, workarounds, experimental methods, etc. without the need to modify the
AMD/ACF language layers of the Adams Solver (C++).
When the execution of Adams Solver (C++) starts, all the environment variables are scanned and the Adams
Solver (C++) runtime environment is created. The Adams Solver (C++) runtime environment is initialized
with all the environment variables that the Adams Solver (C++) recognizes. Environment variables used by
vertical applications or other products are not included in the Adams Solver (C++) runtime environment.
ENVIRONMENT 87
C++ Statements
Next, when the model is being read, all of the ENVIRONMENT statements are processed one by one in the
same order they are found in the ADM dataset file. The ENVIRONMENT statements will update or modify
the Adams Solver (C++) runtime environment. If there is at least one ENVIRONMENT statement in the
dataset file, Adams Solver (C++) prints a report of all the Adams Solver (C++) runtime environment variables
and their corresponding values (if any) along with a description of the feature the variable is used for.
You may change the value of an Adams Solver (C++) runtime environment variable using the
ENVIRONMENT command.
The advantages of having the ENVIRONMENT statement and command are:
 It allows setting preferences at the model level rather than at the operating system level.
 It helps reduce the pollution in the operating system environment and better manage the settings.
Examples
1. Let's assume the operating system has no definition for the environment variable by the name
MSC_ADAMS_SOLVER_BEAM_MODEL. Also, let's assume you run a model defined by an
ADM dataset including the following statement:
ENV/
, NAME=MSC_ADAMS_SOLVER_BEAM_MODEL,
, VALUE=NONLINEAR
Running the model, Adams Solver (C++) will print the following message:
List of User-environment variables defined in data/command files

---------------------------------------------------------------
MSC_ADAMS_SOLVER_BEAM_MODEL=NONLINEAR
Enforces Adams Solver C++ to use a different beam model.
Options are LINEAR, STRING, NONLINEAR.
Observe Adams Solver prints a brief description of the environment variable. Notice you do not need
to modify the operating system environment.
2. Let's assume you define the following environment variable from a Linux shell:
% setenv MSC_ADAMS_SOLVER_BEAM_MODEL=LINEAR
This environment variable specifies using a linear model for the BEAM formulation. Next, you run
a model defined by an ADM dataset including the following statement:
ENV/
, NAME=MSC_ADAMS_SOLVER_BEAM_MODEL,
, VALUE=NONLINEAR
Notice the intent is to overwrite any previous definition of the variable. Running the model, Adams
Solver (C++) will print the following message:
List of User-environment variables defined in data/command files

----------------------------------------------------------------
88 Adams Solver
C++ Statements
MSC_ADAMS_SOLVER_BEAM_MODEL=NONLINEAR
* Overwrites a previous definition.
Observe Adams Solver prints the note "Overwrites a previous definition" indicating that the
ENVIRONMENT statement overwrote the value of the environment variable set in the operating
system.
3. In this example we use the ENVIRONMENT statement to unset any previous definition of an
environment variable.
ENV/
, NAME=MSC_ADAMS_SOLVER_BEAM_MODEL, UNSET
If the environment variable was not defined, the statement is ignored with a warning message.
Caution: Environment variables are typically intended for experimentation and testing of
undocumented features. They may be removed in a future release without notice. Please bear
this in mind when using the ENVIRONMENT statement and command.

EQUILIBRIUM 89
C++ Statements
EQUILIBRIUM
The EQUILIBRIUM statement specifies error tolerances and other parameters for static equilibrium and
quasi-static equilibrium analyses.
Format
 
 ALIMIT = r 
 
 ,ERROR = r 
 
 ,IMBALANCE = r 
 
 ,MAXIT = i 
 
 ,PATTERN = c1 [:...: c10] 
 
 ,STABILITY = r 
 
 ,TLIMIT = r 
EQUILIBRIUM/  
 
 ,METHOD =i 
 
 ,ATOL = r 
 
 
 ,RTOL = r 
 
 ,MAXITL = i 
 
 ,ETAMAX = r 
 
 ,ETA = r 
 
{} Select one item

90 Adams Solver
C++ Statements
Arguments
ALIMIT=r Specifies the maximum angular increment allowed per iteration during a static or
quasi-static equilibrium analysis. The default units for ALIMIT are radians. To
specify ALIMIT in degrees, add a D after the value.
Default: 0.17453 (10 D)
Range: ALIMIT > 0
ERROR=r Specifies the relative correction convergence threshold. The iterative process
carried out during the equilibrium analysis can not converge prior to all relevant
relative corrections being smaller than this value.
Default: 1.0E-04
Range: ERROR > 0
IMBALANCE=r Specifies the equation imbalance convergence threshold. The iterative process
carried out during the equilibrium analysis can not converge prior to each
equation imbalance being smaller than this value.
Default: 1.0E-04
Range: IMBALANCE > 0
MAXIT=i Specifies the maximum number of iterations allowed for finding static
equilibrium.
Default: 25
Range: MAXIT > 0
PATTERN=c1[:...:c10] Allows you to specify as many as ten character strings that together establish the
pattern for evaluating the Jacobian matrix during the modified Newton-Raphson
iteration. For each iteration, T or TRUE indicates that Adams Solver (C++)
evaluates the Jacobian and F or FALSE indicates that Adams Solver (C++) does
not evaluate the Jacobian. Thus, cj determines whether or not Adams Solver
(C++) evaluates the Jacobian at the jth iteration. If necessary, Adams Solver (C++)
repeats the pattern of evaluations until it reaches the maximum number of
iterations (MAXIT). The number of Ts or TRUEs and Fs or FALSEs together
must be at least one and no more than ten.
Default: T:T:T:T:T:T:T:T:T:T, which evaluates the Jacobian at every iteration (for

example, the unmodified Newton-Raphson algorithm).
EQUILIBRIUM 91
C++ Statements
STABILITY=r Specifies the fraction of the mass and damping matrices (subsets of the
equilibrium Jacobian matrix) Adams Solver (C++) adds to the stiffness matrix (a
subset of the equilibrium Jacobian matrix) during static simulations performed
using static analyses. Adding a fraction of the mass and damping matrices to the
stiffness matrix can stabilize the iteration process and prevent the iteration from
diverging. Often the stiffness matrix is singular for a system because the system is
neutrally stable (for example, the system moves in certain directions without
affecting the potential energy). Adding a fraction of the mass and damping
matrices to the stiffness matrix removes this singularity and makes it possible to
solve for equilibrium positions. The value of STABILITY does not affect the
accuracy of the solution, but it does affect the rate of convergence of the iteration
process.
Default: 1.0E-05
Range: STABILITY >0
TLIMIT=r Specifies the maximum translational increment allowed per iteration.
Default: 20
Range: TLIMIT > 0
92 Adams Solver
C++ Statements
METHOD=i Specifies the option which determines the static solver method to be used for
equilibrium solution.
1. ORIGINAL, for running only the ORIGINAL Solver

2. ADVANCED, runs, in order, the following methods until one shows
progress:
a. ORIGINAL
b. ORIGINAL+Krylov
c. ORIGINAL+UMF
d. Newton+Krylov
e. Tensor-Krylov block-3
f. Tensor-Krylov block-2+
3. AGGRESSIVE, runs, in order, the following methods until one shows
progress:
a. ORIGINAL
b. ORIGINAL+Krylov
c. ORIGINAL+UMF
d. Newton+Krylov
g. Broyden-Armijo
h. Trust-Region
4. ALL, runs, in order, all the available methods, until one shows progress:
a. ORIGINAL
b. ORIGINAL+Krylov
c. ORIGINAL+UMF
d. Newton+Krylov
g. Broyden-Armijo
h. Trust-Region
i. Hooke-Jeeves
Default: ORIGINAL
ATOL Specifies the absolute tolerance value
Default: 1.0e-6
Range: 0.0 < ATOL < 1.0
EQUILIBRIUM 93
C++ Statements
RTOL Specifies the relative tolerance value
For all solvers, except ORIGINAL and ORIGINAL+Krylov, the tolerance is

defined as : TOL=ATOL+||xIC||*RTOL.
For ORIGINAL and ORIGINAL+Krylov solvers the tolerance is equal to ERROR.
Default: 0.0
Range: 0.0 < RTOL < 1.0
MAXITL Specifies the maximum number of allowed inner loops in all the solvers.
ORIGINAL, ORIGINAL+Krylov and ORIGINAL+UMF solver methods ignore
this parameter. For Hooke-Jeeves method, allowed budget of function evaluations
is set to MAXITL*N, where N is the size of the problem (number of unknowns).
Default: 40
Range: > 0
ETAMAX Specifies the maximum threshold for the error tolerance of the linear Krylov solver
(for Newton+Krylov and Tensor-Krylov methods) that solves the linear systems
required by Krylov algorithm. Maximum error tolerance for residual in inner
iteration. The inner iteration terminates when the relative linear residual is smaller
than eta*| F(x_c) |. eta is determined by the modified Eisenstat-Walker formula if
etamax > 0. If etamax < 0, then eta = |etamax| for the entire iteration.
Default: 0.9
Range: 0.0 < ETAMAX < 1.0
ETA Specifies the initial residual tolerance for the linear Krylov Solver for
Tensor_Krylov method. The Tensor-Krylov ETA parameter is maintained
adaptively by the Krylov algorithm but ETA is the indicated starting value, while
ETAMAX is the maximum threshold for ETA.
Default: 1.0e-4
Range: 0.0 < ETA < 1.0
Specifies the dimensionless radius of the trust-region for Trust-region method.

The smaller the value, the more the refinement of Trust-region solution (hence
more work).
Range: 0.0 < ETA < 0.25
Extended Definition
The EQUILIBRIUM statement specifies error tolerances and other parameters for static and quasi-static
equilibrium analyses. This statement is used when you want to change one or more of the tolerances or other
parameters from the default values.
Use the SIMULATE command to request one of the following:
94 Adams Solver
C++ Statements
 Single static equilibrium analysis.

 Series of static equilibrium analyses over time, for example, a quasi-static equilibrium analysis.
Static and quasi-static equilibrium analyses solve for displacement and static forces, but not for velocity,
acceleration, or inertia forces which are all assumed to be zero. To perform a static equilibrium analysis,
Adams Solver (C++) finds the configuration and static forces for which all the static forces in the system
balance after being evaluated at the current simulation time. This process requires the solution of a set of
nonlinear algebraic equations. Adams Solver (C++) uses the modified Newton-Raphson iteration to solve
these equations.
If neither an EQUILIBRIUM command nor an EQUILIBRIUM statement is issued in an Adams Solver
session, the default values for ALIMIT, ERROR, IMBALANCE, MAXIT, PATTERN, STABILITY, and
TLIMITare used when performing a static equilibrium or quasi-static equilibrium analysis.
Currently, there are 8 different types of solvers in addition to the Static Solver that was originally in the code
(ORIGINAL solver). ORIGINAL Solver used the Sparse linear solver:
1. ORIGINAL+Krylov has the same logic flow as the ORIGINAL but uses linear GMRES algorithm
[1.].
2. ORIGINAL + UMF has the same logic flow as the ORIGINAL but uses linear UMF algorithm [6.].
3. Newton+Krylov nonlinear solver uses a Newton + GMRES algorithm [1.].
4. Tensor-Krylov block 3 solver uses Tensor-Krylov method [2.], flavor block 3.
5. Tensor-Krylov block 2+ solver uses Tensor-Krylov method [2.], flavor block 2+.
6. Broyden-Armijo solver uses Broyden method [1.] with an Armijo line-search [1.] to account for global
strategies.
7. Trust-Region method Solver uses the Trust Region optimization algorithm [3.].
8. Hooke-Jeeves solver uses the Hooke-Jeeves optimization method [4.].
EQUILIBRIUM 95
C++ Statements
Tip:  Using the PATTERN argument to request less frequent evaluations of the Jacobian matrix
may decrease the computation time. However, infrequent evaluations could also be more
expensive since the modified Newton-Raphson algorithm might require more iterations
due to the slower convergence rates.
 Use the ALIMIT and TLIMIT arguments to limit incrementing displacement variables
during an iteration for static equilibrium. Excessive incrementing could prevent Adams
Solver (C++) from finding a static equilibrium position.
 Use the IMBALANCE argument if the physical units of the problem are such that the
default imbalance of 1.0E0-4 is excessively large or excessively small. Changing from an
inappropriate to an appropriate value for IMBALANCE saves CPU time.
 You can use the MSC_USE_ALTERNATE_SOLVERS environment variable to specify a
particular method to be used for equilibrium solution. The variable works as an integer
bit-mask with 9 bits, corresponding to the eight solvers above in the order: ORIGINAL
(bit0), ORIGINAL+Krylov (bit1), ORIGINAL+UMF (bit2), Newton+Krylov (bit3),
Tensor-Krylov block-3 (bit4), Tensor-Krylov block-2+ (bit5), Broyden-Armijo (bit6),
Trust-Region (bit7), Hooke-Jeeves (bit8). The lowest order bit, if set to 1, means
ORIGINAL solver will be used. The highest order bit, if set to 1, means Continuation
method will be used.
For example if the user wants to enforce the exclusive use of only ORIGINAL+Krylov,
ORIGINAL+UMF, Broyden-Armijo, and Trust-Region solvers, then the bits that must
be set are bit1, bit2, bit5, and bit7. Hence, the binary value of
MSC_USE_ALTERNATE_SOLVERS is 10100110, that is,
MSC_USE_ALTERNATE_SOLVERS=2^7+2^5+2^2+2^1=128+32+4+2=166.
Caution:  Setting STABILITY=0 results in a singularity if the system is neutrally stable. If the system
is neutrally stable, STABILITY must be greater than zero in order for Adams Solver (C++)
to compute static equilibrium.
 Static equilibrium, or quasi-static equilibrium analyses often have multiple equilibrium
solutions. Adams Solver (C++) makes no attempt to converge to a stable position. For
example, Adams Solver (C++) may converge to an inverted pendulum position rather than
the more common hanging pendulum. Items such as the initial position of parts and the
settings for ALIMIT, TLIMIT, and STABILITY can all influence the solution to which
Adams Solver (C++) converges.
 If MSC_USE_ALTERNATE_SOLVERS is set to a non-zero value, then its value overrides the
METHOD setting.
Examples
EQUILIBRIUM/ STABILITY=0.01, TLIMIT=10

, IMBALANCE=1.0E-05
96 Adams Solver
C++ Statements
This EQUILIBRIUM statement instructs Adams Solver (C++) to use these values instead of the defaults
when performing a static or quasi-static equilibrium analysis. It adds 0.01 times the sum of the mass and
damping matrices to the stiffness matrix during an equilibrium iteration. It limits the translation in any one
iteration to 10 length units. The force imbalance in the system must be less than 1.0E-05 force units for
Adams Solver (C++) to consider the system to be in equilibrium.
Bibliography:
1. Iterative Methods for Linear and Nonlinear Equations C.T. Kelley, SIAM 1995
2. Tensor-Krylov Methods for Solving Large-Scale Systems of Nonlinear Equations Brett W. Bader, Ph.D.
Thesis, 2003
3. Numerical Optimization Jorge Nocedal, Stephen J. Wright, Springer 1999
4. Iterative Methods for Optimization C.T. Kelley, SIAM 1999
5. Introduction to Numerical Continuation Method E.L. Allgower and K. Georg, 1990
6. MD Nastran Quick Reference Guide.
FE_LOAD 97
C++ Statements
FE_LOAD
The FE_LOAD statement defines a distributed applied load (force and moment) per unit length or per unit
area or per unit volume. The nature of the force depends on the FE_PART this load acts upon. For example,
if the FE_PART is a beam or cable, then the load is understood to have units of force and moment per unit
length.
The FE_LOAD is an action-only force and moment. There is no reactive component acting on some other
element.
For beams and cables, the function expressions can depend on measures S, SD, SV and SA. Function S takes
values between 0 and 1 and the other measures provide the values of the global position, velocity and
acceleration at the position defined by S (see documentation of functions S, SD, SV and SA).
Format
Arguments
FE_PART=id Specifies the FE_PART where this load is acting upon.

RM=id Specifies the MARKER which determines the orientation of the distributed
load components. If this option is not present, the load components are
relative to the ground origin coordinates.
FUNCTION=USER(r1[ Specifies up to thirty user-defined constants used to compute the value of the
,…,r30] distributed load components.
FX=e Specifies the magnitude and sign of the x component of the distributed force
applied by this element. The direction of this force component is parallel to
the x-axis of the RM marker.
FY=e Specifies the magnitude and sign of the y component of the distributed force
the y-axis of the RM marker.
FZ=e Specifies the magnitude and sign of the z component of the distributed force
the z-axis of the RM marker.
98 Adams Solver
C++ Statements
TX=e Specifies the magnitude and sign of the x component of the distributed force
the x-axis of the RM marker in the sense of the right-hand rule (that is, a
positive torque causes a counterclockwise rotation).
TY=e Specifies the magnitude and sign of the y component of the distributed force
the y-axis of the RM marker in the sense of the right-hand rule (that is, a
TZ=e Specifies the magnitude and sign of the z component of the distributed force
the z-axis of the RM marker in the sense of the right-hand rule (that is, a
ROUTINE=libname::sub Specifies an alternative library and name for the user subroutine. The default
name name for this user-written subroutine is FEloadsub. The name is case sensitive
and it must be written in C++. See the documentation for the FEloadsub.
Example
The FE_LOAD can be defined as follows for a general distributed load shown in the Figure 7.
Figure 7 A distribute load
FE_LOAD/1
, FE_PART=3
, FX= 0\
, FY= -30*SIN(PI*S)\
, FZ= 0\
, TX= 0\
, TY= 0\
, TZ= 0
FE_LOAD 99
C++ Statements
Parameter S has values between 0.0 and 1.0. When evaluating the loads during a simulation, Adams Solver
C++ sets the value of S at every integration point and computes the value of the given expression for the
distributed load and its derivatives.
Caution:  If the FE_LOAD is applied to 2D beam, the force components (FX, FY and FZ) must be
defined in the global coordinate system. Adams solver neglects the RM argument in this
case.
 If the FE_LOAD is applied to 2D beam, the applied moment per unit length is not
supported. Adams solver neglects the arguments: TX, TY, TZ in this case.
 For 2D beams, the measures SD, SV and SA have 3 components only. The first component
represents the translation along first axis of global plane, the second component represents
the translation along second axis of global plane and the third component represents the
in-plane rotation; for example, in the case of 2DBEAMZX, SV(1) = translational velocity
along global Z axis, SV(2) = translational velocity along global X axis, SV(3) = angular
velocity about global Y axis.
100 Adams Solver
C++ Statements
FE_NODE
The FE_NODE statement defines attributes required to create a node on FE_PART.
Arguments
FE_PART id of parent FE_PART.

LABEL Specifies label of FE_PART node. Label cannot be modified once given.
S Specifies the distance value for node. 0 <= S <= 1
ANGLE Specifies the value of twist angle to be given to node. Angle is mentioned in
radian.
SECTION_NODE id of SECTION with the cross-sectional characteristics defining this
FE_NODE.
QG Defines the Cartesian initial coordinates of the origin of the body coordinate
system (BCS) with respect to the global coordinate system (GCS).
REULER Defines the 3-1-3 Euler angles that Adams Solver (C++) uses to establish the
initial orientation of the BCS with respect to the coordinate system.
Example
adams_view_name='Fe_Node_3'
FE_NODE/1
, FE_PART = 2
, LABEL = 3
, S = 1
, ANGLE = 0
, SECTION_NODE = 9
, QG = 400, 300, 0
, REULER = 356.6335393D, 0D, 0D
FE_PART 101
C++ Statements
FE_PART
The FE_PART statement defines a set of finite elements with distributed mass. The finite elements are fully
embedded in the solution process, in other words, Adams Solver assembles the governing equations and solves
the corresponding governing finite elements equations that are coupled to the standard multibody dynamic
equations.
The TYPE of FE_PART specifies whether this set of elements is use to model 3D beam and 2D beam and
so on.
Format
102 Adams Solver
C++ Statements
Arguments
Specifies the type of finite element. A 3DBEAM is finite element beam

modeled using the Absolute Nodal Coordinate Formulation (ANCF). It has
advantages versus standard finite elements found in Nastran, namely it is
suited to fit multibody dynamics codes like Adams providing full
geometrically nonlinear behavior. See references for selected papers. The
2DBEAMXY, 2DBEAMYZ and 2DBEAMZX are special cases of 3DBEAM
when the beam has a planar behavior. Like 2D PARTS, they may have an
offset and they assemble a reduced set of equations of motion.
QG=x, y, z Defines the Cartesian initial coordinates of the origin of the body coordinate
REULER=a, b, c Defines the 3-1-3 Euler angles that Adams Solver (C++) uses to establish the
initial orientation of the BCS with respect to the coordinate system. The a, b,
and c rotations are in radians and are, respectively, about the z-axis of ground,
the new x-axis, and the new z-axis of the BCS. To input Euler angles in
degrees, add a D after each value.
MATERIAL = id Specifies the identifier of the MATERIAL statement used by this element.
NODE_LABELS=id1, Specifies the list of nodes used by this element to define its geometry. Straight
id2 [, id3…] beams may only require two nodes to completely define the element.
However, if cross sectional properties change along the axis of the beam, or if
the beam is curved, users may want to use more than two nodes to define the
beam. Adding more nodes adds more equations of motion but provides better
modeling of the real system.
The list of nodes provides the sequence in which the nodes are connected
forming the beam.
Each node defines a coordinate system. Each pair of nodes defines a beam like
finite element using the ANCF (Absolute Nodal Coordinate Framework)
element. The elements are curved following a polynomial interpolation.
COORDINATES_MAT Specifies the identifier of the MATRIX statement holding the nodal
RIX=id information for this element. The MATRIX must have 7 columns. Each row
must include an integer defining a node (that is, node ID) and 6 coordinates
specifying the location and orientation of the node with respect to the BCS of
the element. The node IDs defined in this statement are the nodes used in the
NODES option.
COORDINATES=id1, Specifies a list of values. The values are arranged in sets of 7 values each. The
x1,… first in the set is an integers (defining a node ID) followed by 6 coordinates
specifying the location and orientation of the node with respect to the BCS of
the element. The node IDs defined in this statement are the nodes used in the
NODES option.
FE_PART 103
C++ Statements
SECTION_MATRIX=id Specifies the identifier of the MATRIX statement holding the cross section
property values for each node. The MATRIX must have 6 columns. Each row
must include an integer corresponding to a node ID and 5 values defining the
Area, Iyy, Izz, Iyz and Jxx of the beam at the set node. See Note 1 below.
SECTION = id1, A1,… Specifies a list of values. The values are arranged in sets of 6 values each. The
first in the set is an integer specifying a node ID. The next 5 values are the
Area, Iyy, Izz, Iyz and Jxx of the beam at the specified node. See Note 1 below.
IC_MATRIX=id Specifies the identifier of the MATRIX statement holding the velocity initial
conditions at each node. The MATRIX must have 7 columns. Each row starts
with an integer corresponding to a node ID and 6 values defining the initial
velocities(vx,vy,vz,wx,wy,wz) of the set node with respect to the BCS or if
specified, VM and/or WM. All six values for all nodes of the FE Part must be
specified.
IC=id1, vx1,… Specifies a list of values. The values are arranged in sets of 7 values each. The
first in the set is an integer (a node ID) followed by 6 coordinates
(vx,vy,vz,wx,wy,wz) specifying the initial velocities of the set node with respect
to the BCS or if specified, VM and/or WM. All six values for all nodes of the
FE Part must be specified. Initial rotational velocities (wx,wy,wz) are specified
in radians per second.
CRATIOK=r Specifies the fraction of the stiffness matrix that contributes to the damping
matrix for this element.
Note: The CRATIOK and CRATIOM used in the FE part damping are
same as those in the Rayleigh damping; however, it should be noted
that since the FE part formulation includes geometrical
nonlinearity, the stiffness matrix and mass matrix are not constant
(except for the 2D FE part). So, the CRATIOM and CRATIOK is
multiplied to the instantaneous mass matrix and the instantaneous
stiffness matrix (that is, tangent stiffness matrix) respectively.
CRATIOM=r Specifies the fraction of the mass matrix that contributes to the damping
matrix for this element.
Note: The CRATIOK and CRATIOM used in the FE part damping are
same as those in the Rayleigh damping; however, it should be noted
that since the FE part formulation includes geometrical
nonlinearity, the stiffness matrix and mass matrix are not constant
(except for the 2D FE part). So, the CRATIOM and CRATIOK is
multiplied to the instantaneous mass matrix and the instantaneous
stiffness matrix (that is, tangent stiffness matrix) respectively.
104 Adams Solver
C++ Statements
PRELOAD = preload_file Specifies the name of a file containing preloaded conditions information for
this fe_part.
VM = id Specifies the identifier of the marker that specifies the direction of the
translational components of initial velocity defined in the IC or IC_MATRIX.
VM defaults to the FE Part BCS.
WM=id Specifies the identifier of the marker that specifies the axes about which
angular velocity initial condition (wx,wy,wz) are defined. WM defaults to the
BCS location (QG) and orientation (REULER). The origin of the WM
marker lies on the axis of rotation. This is useful for rotating systems.
Notes: 1. Iyy, Izz and Iyz are the area moments of the cross section around the nodal Y and Z
axes defined by the node information. Iyz is the product of inertia. Jxx is the torsional
constant which is used to assemble the torsional equation of motion. The warping
deformation is not considered here.
2. The number of nodes used, n, determines the number of degrees of freedom (DOF) of
the FE Part as such: DOF for 3DBeam : = 3*((4*number_of_nodes)-1), DOF of
2DBeams : = 4*(number_of_nodes)
Extended definition for beams

The nodes define the neutral axis of the beam. The neutral axis passes through the origin of each node. All
nodes must be oriented such that the positive x-axis is tangent to the neutral axis of the beam (centroid).
For simple uniform beam, two nodes are usually enough to model it. However, if the cross section properties
change along the axis, or if the beam is curved, users need to use more nodes. If the user decides to use more
nodes, then additional degrees of freedom are assigned to the element making it more accurate in modeling
the real system. If more than two nodes are used, the beam in fact becomes a set of finite elements.
One limitation of FE Part beams is that the shear center is assumed coincident with the neutral axis.
Each node defines a nodal coordinate system. This coordinate system has three purposes: the origin defines
the location of the neutral axis of the beam, that is, the location of the center of mass of the cross section.
Second, the x-axis defines normal to the cross section. Third, the other axes are used to define the cross
sectional properties and the rendering of graphics representing the cross section geometry.
See section FAQ for more information.
References
1. Gerstmayr, J. and Shaban, A. "Analysis of higher and lower elements for the Absolute Nodal
Coordinate Formulation". Proceedings of IDETC/CIE 2005.
2. Simo, J. and Vu-Quoc, L. "A Geometrically-exact rod model incorporating shear and torsion-
warping deformation", J. Solids Structures Vol 27, No3, pp 371-393, 1991.
FE_PART 105
C++ Statements
3. Berzeri, M. and Shabana, A. "Development of simple model for the elastic forces in the absolute nodal
co-ordinate formulation". Journal of Sound and Vibration (2000) 235(4), 539-565.
1. Example
A distributed-mass beam is shown in Figure 8 below. For this case, just two nodes are enough to model the
beam.
Figure 8 A simple beam
FE_PART/1
, TYPE = 3DBEAM
, QG = 130, 50, 0
, NODE_LABELS = 7, 77
, COORDINATES=
, 7, 0, 0, 0, 0, 0, 0
, 77, 6.5, 0, 0, 0, 0, 0
, SECTION=
, 7, 0.5, 4.E+4, 1.E+2, 0, 2.E+4
, 77,0.5, 4.E+4, 1.E+2, 0, 2.E+4
, MATERIAL=1
MARKER/700
, FE_PART=1, NODE_LABEL=7
106 Adams Solver
C++ Statements
MARKER/7700
, FE_PART=1, NODE_LABEL=77
MATERIAL/1
, NAME = steel
, DENSITY = 7801
, YOUNGS_MODULUS = 2.07E+011
, POISSONS_RATIO = 0.29
Notice the coordinates of the nodes are relative to the QG and REULER of the FE_PART.
MARKERs 700 and 7700 can now be used to create JOINTs or apply forces into the beam.
2. Example
A twisted straight-axis beam is shown in Figure 9 below. For this case, we decide to use four nodes. The cross
section is the same at each node but twisted. One option to define the geometry of the beam is:
Figure 9 Twisted straight-axis beam
! Version 1
! Nodes
MATRIX/1, FULL=RORDER, ROWS=4, COLUMNS=7, VALUES =
, 10, 0.0, 0, 0, 0, 0D, 0
, 11, 1.0, 0, 0, 0, 30D, 0
, 12, 2.0, 0, 0, 0, 60D, 0
, 13, 3.0, 0, 0, 0, 90D, 0
FE_PART 107
C++ Statements
! Section properties
, 10, 0.5, 4.E+4, 1.E+2, 0, 2E+4
, 11, 0.5, 4.E+4, 1.E+2, 0, 2E+4
, 12, 0.5, 4.E+4, 1.E+2, 0, 2E+4
, 13, 0.5, 4.E+4, 1.E+2, 0, 2E+4
! Beam
FE_PART/2
, TYPE = 3DBEAM
, NODE_LABELS = 10, 11, 12, 13
, COORDINATES_MATRIX = 1
, SECTION_MATRIX = 2
, MATERIAL=1
Notice the cross sectional properties in MATRIX/2 are constant along the axis of the beam. The beam above
could also be defined as follows:
! Version 2
! Nodes
, 10, 0.0, 0, 0, 0, 0, 0
, 11, 1.0, 0, 0, 0, 0, 0
, 12, 2.0, 0, 0, 0, 0, 0
, 13, 3.0, 0, 0, 0, 0, 0
! Section properties
, 10, 0.5, 4.E+4, 1.E+2, 0, 2E+4
, 11, 0.5, 9.E+3, 2.E+3, 2.E+1, 2E+4
, 12, 0.5, 2.E+3, 9.E+3, 2.E+1, 2E+4
, 13, 0.5, 1.E+2, 4.E+4, 0, 2E+4
108 Adams Solver
C++ Statements
! Beam
FE_PART/2
, TYPE = 3DBEAM
, NODE_LABELS = 10, 11, 12, 13
, MATERIAL=1
Notice the nodes in this second are equally oriented but the section properties change accordingly. Both
versions define equivalent beam properties
3. Example
Figure 10 below shows a section of a coil to be modeled by a curved distributed-mass beam. The nodal
coordinates were computed using a user-written script. The coil has constant cross section properties
Figure 10 A coil to be modeled using a curved distributed-mass beam

FE_PART 109
C++ Statements
! Nodes
, 21, 5.0000, 0.0000, 0.0000, 0.0000, 0.0599, 1.5708
, 22, 3.8303, 3.2139, 0.2094, 0.6981, 0.0599, 1.5708
, 23, 0.8684, 4.9240, 0.4189, 1.3962, 0.0599, 1.5708
, 24, -2.4997, 4.3303, 0.6283, 2.0943, 0.0599, 1.5708
, 25, -4.6983, 1.7105, 0.8377, 2.7924, 0.0599, 1.5708
, 26, -4.6986, -1.7096, 1.0472, 3.4906, 0.0599, 1.5708
, 27, -2.5005, -4.3298, 1.2566, 4.1887, 0.0599, 1.5708
, 28, 0.8675, -4.9242, 1.4660, 4.8868, 0.0599, 1.5708
, 29, 3.8297, -3.2146, 1.6755, 5.5849, 0.0599, 1.5708
! Section properties. All nodes have the same values

, 21, 0.5, 2.E+2, 2.E+2, 0, 4.E+2
, 22, 0.5, 2.E+2, 2.E+2, 0, 4.E+2
, 23, 0.5, 2.E+2, 2.E+2, 0, 4.E+2
, 24, 0.5, 2.E+2, 2.E+2, 0, 4.E+2
, 25, 0.5, 2.E+2, 2.E+2, 0, 4.E+2
, 26, 0.5, 2.E+2, 2.E+2, 0, 4.E+2
, 27, 0.5, 2.E+2, 2.E+2, 0, 4.E+2
, 28, 0.5, 2.E+2, 2.E+2, 0, 4.E+2
, 29, 0.5, 2.E+2, 2.E+2, 0, 4.E+2
! Beam
FE_PART/2
, TYPE = 3DBEAM
, NODE_LABELS = 21, 22, 23, 24, 25, 26, 27, 28, 29
, MATERIAL=1
For more information refer the FE_PART Appendix section.
110 Adams Solver
C++ Statements
FAQ
1. Why the coordinates and section properties need to have an additional column with the node number
information?
One reason is that users may want to label their nodes with arbitrary numbers. Second, the user may
specify a different set of nodes by simply removing/adding nodes from the NODES list. Adams Solver
C++ will ignore the nodal information not set in the NODES option.
2. Can two or more FE_PART have the same node numbers?
Yes, this allows users to duplicate statements for beams. However, users will need to take care of
assigning new IDs to MARKERs.
3. Can 2D beams have an offset with respect to the main global coordinate planes?
Yes, just like 2D PARTS, 2D beams may be located on a plane with an offset set by the QG option.
Limitations
Adams Solver C++ version 2015 has the following limitations:
1. No LINEAR support. Linearization and export of models having FE_PART require a complex
algorithm that will be supported in the near future.
2. No SAVE/RELOAD support.
3. Models with FE_PARTs will run only in serial mode. Multithreading capabilities will be added in
next releases.
FEMDATA 111
C++ Statements
FEMDATA
The FEMDATA statement produces data files of component loads, deformations, stresses, or strains for input
to subsequent finite element or fatigue life analysis. Also, FEMDATA can be used to output monitor point
time histories, if monitor point data is provided in the MNF.
You use the OUTPUT statement to specify the type of file FEMDATA produces. Except for HOTSPOTS
table and the old style (.fem) file, FEMDATA will not output data to any files unless you specify the format
in the OUTPUT statement.
Format
112 Adams Solver
C++ Statements
Arguments
CRITERION = c Specifies the criterion or value of stress or strain in determining hot spots.
Supported criteria are one of: VON_MISES, MAX_PRIN, MIN_PRIN,
MAX_SHEAR, NORMAL_X, NORMAL_Y, NORMAL_Z, SHEAR_XY,
SHEAR_YZ, SHEAR_XZ, and SIGNED_VON_MISES. Default criterion is
VON_MISES.
DATUM = node_id Specifies a node ID of the flexible body to be the datum of the nodal
displacements. Adams Solver computes all nodal displacements relative to this
node ID. If you do not specify a datum node, Adams Solver generates an
arbitrary relative set of nodal displacements. It displays a warning message if the
specified node does not belong to the flexible body.
END = t2 Specifies the time, t2, at which to end the output of the data or the search of a
peak load.
Default: Output or search to the end of the simulation.

Range: t2 > t1
HOTSPOTS = n Specifies the number of hot spots to locate and output on the flexible body or fe
part. A search for the top n locations (nodes or markers) that recorded the
highest stress or strain during the simulation will ensue. With the START, END
or SKIP arguments, FEMDATA only checks the time steps within those
specifications for hot spots. A text file containing a table of hot-spot data
(node/marker ID, maximum value, time of maximum value, and location) will
be output. The complete time history of stress or strain will be output as well for
each hot spot, if the STRAIN or STRESS option is specified in the OUTPUT
statement.
FE_PART = id Specifies the ID of the fe part whose data FEMDATA outputs. FEMDATA
outputs the data in the body coordinate system for the FE Part (LPRF), except
in the case of STRAIN or STRESS with the RM = id option.
FLEX_BODY = id Specifies the ID of the flexible body whose data FEMDATA outputs.
FEMDATA outputs the data in the FEM basic coordinate system that is
inherent to the flexible body, except in the case of STRAIN or STRESS with the
RM = id option.
FILE = name Specifies the output file name for the FEM data. You can specify an existing
directory, root name, and/or extension. By default, the file name will be
composed of the ADAMS run and body IDs according to the type of data and
file format that you specified in the OUTPUT statement.
LOADS Outputs all external forces (reaction and applied forces except gravity) acting on
the specified body and inertial forces of the specified body (angular velocities
and accelerations including effects of gravity) as a function of time. Load data
will be output in the simulation set of units.
FEMDATA 113
C++ Statements
MARKER = id1 [,…,idn] Specifies the marker id(s) of a fe part whose data is to be output. Adams Solver
issues a warning if a marker ID is specified that does not belong to the fe part.
MONITOR_POINTS Outputs monitor point time histories for the specified flexible body if monitor
point data blocks exist in the MNF of the flex body.
MODAL_DEFORMATI Outputs modal deformations as a function of time of the specified flexible body.
ON FEMDATA will only export coordinates of the active modes in the simulation.
NODAL_DEFORMATI Outputs nodal deformations as a function of time of the specified flexible.
ON FEMDATA writes the formations in the simulation set of units.
NODE = id1 [,…,idn] Specifies the node numbers of a flexible body whose data is to be output. If you
do not specify a node list, FEMDATA exports nodal data at each attachment
point of the flexible body. Adams Solver issues a warning if a node ID is specified
that does not belong to the flexible body.
NOINERTIA Turns off the output of inertia loads. Inertia loads include linear acceleration,
angular acceleration, and angular velocity of the part or flexible body. Only loads
due to reaction and applied forces are output with this option. This results in a
load imbalance specification for the body, so you must employ a technique, such
as inertia relief, to recover the inertia loads from the external loads in the finite
element program.
PEAK_SLICE = Specifies that FEM load data are to be output only at those time steps where the
FX:FY:FZ:FMAG:GMA specified peak load occurred in the simulation. With the START, END, or SKIP
G: TX:TY:TZ:TMAG arguments, FEMDATA only checks the time steps within those specifications
for the peak load. You can specify one or more of FX, FY, FZ, FMAG, GMAG,
TX, TY, TZ, TMAG.
RADIUS = r Specifies a radius between hot spots. If specified, all locations (nodes or markers)
falling within a sphere defined by radius r and centered about the location with
the highest stress/strain, will be considered one hot spot. A default value of zero
means that all locations for the flexible body or fe part are candidates for hot
spots.
114 Adams Solver
C++ Statements
RM = id Specifies the rigid body marker to be the reference coordinate system to output
loads. Because Adams Solver resolves all loads acting on the rigid body in the
coordinate system of the specified marker, the marker should represent the FEA
basic coordinate system of the part's finite element model (FEM).
If only RM is specified with no accompanying type (that is, LOADS or STRESS

or STRAIN), an old style .fem file is generated with loading information for
each rigid body that has a marker listed on this field.
For STRESS or STRAIN, optionally specifies the reference coordinate system in

which to output. If RM is not specified, stress/strain will be computed in the
flexible body or fe part's LPRF. If specified, the stress/strain tensor will be
transformed relative to instantaneous coordinate system of marker ID. The RM
does not have to belong to the flexible body or fe part, but can be any marker in
the model. All six components of stress or strain (Sxx, Syy, Szz, Sxy, Syz, Szx) can
be affected by this coordinate transformation. This option can be useful when
correlating test results such as strain gauge data on a flexible component.
SKIP = n Specifies the number of output steps to skip when outputting the data.
Default: n=0 (every step is output).

START = t1 Specifies the time at which to start outputting the data.
Default: Output at the start of the simulation.

Range: t1 > t2 (See END argument)
STRAIN Outputs strain information to fe part or flex body if strain modes are available
in the modal neutral file (MNF) of the specified flexible body. FEMDATA
outputs all six components of strain (normal-X, normal-Y, normal-Z, shear-XY,
shear-YZ, shear-ZX). It outputs strains in the basic FEA coordinate system of the
flexible body or LPRF of fe part, unless the RM = id option is specified.
STRESS Outputs stress information to fe part or flex body if modal stresses are available
in the MNF of the flexible body. FEMDATA outputs all six components of stress
(normal-X, normal-Y, normal-Z, shear-XY, shear-YZ, shear-ZX). It outputs
stresses output in the simulation set of units in the basic FEA coordinate system
of the flexible body or LPRF of fe part, unless the RM = id option is specified.
Extended Definition
Default File Naming Conventions
You can use the FILE argument to specify the directory, name, and/or extension (directory/name.extension)
for the output file. If you do not specify a directory, FEMDATA creates all its output files except DAC files
in the current working directory. Because several DAC files are typically generated for a FEMDATA
statement, FEMDATA creates them in a separate directory named after the body. It creates this directory in
the current working directory if it does not exist.
FEMDATA 115
C++ Statements
If a file name is not specified in the FILE argument, default file names are assigned according to the type of
FEM data and file format (which is specified in the OUTPUT statement) as shown in the table below.
FEMDATA Default File Names and Extensions
Type of data: Format:* File name: Extension:

(none) (none) <run_name> .fem
Loads DAC <run_name>_<channel_id> .dac
NASTRAN <run_name>_<body_name> .dat
ABAQUS <run_name>_<body_name> .dat
ANSYS <run_name>_<body_name> .dat
RPC <run_name> .rsp
Modal Deformation DAC <run_name>_<channel_id> .dac
Generic <run_name>_<body_name .mdf
NASTRAN <run_name>_<body_name> .mdf
PUNCH <run_name>_<body_name> .mdf
ANSYS <run_name> .out
RPC <run_name> .rsp
Nodal Deformation Generic <run_name>_<body_name> .ndf
NASTRAN <run_name>_<body_name> .spc
ANSYS <run_name>_<body_name> .inp
Strain DAC <run_name>_<node_id>e_<channel_id> .dac
Generic <run_name>_<body_name> .nsf
RPC <run_name>_<body_name> .rsp
Hotspots <run_name>_body_name>_hots .tab
Monitor Points CSV <run_name>_<body_name> .csv
Generic <run_name>_<body_name> .req
Stress DAC <run_name>_<node_id>se_<channel_id> .dac
Hotspots <run_name>_<body_name>_hote .tab
*Specified in the OUTPUT statement
Old Style FEMDATA

An older version of the FEMDATA statement where one or more RM markers are specified with no data type
is still being supported. The format of this version of FEMDATA is:
FEMDATA/id, RM=id1[,...,id100]
In this case, a text file with extension .fem is generated. This file contains generic load specifications for the
parent body of each RM marker specified.
116 Adams Solver
C++ Statements
Format of .fem File

The .fem file contains information sufficient to define all forces (inertial and applied) acting on one or more
parts. The data in this file is intended to be converted to boundary conditions input to a finite element
program. This file is composed of the following lines:
Line1: <Header>
Line 2: <Title>
Lines repeated for every part:
Lines repeated for every output step:
<Record 1> (RM Displacement)
<Record 2> (CM Displacement)
<Record 3> (CM Velocity)
<Record 4> (CM Acceleration)
<Record 5> (Force Displacement)
<Record 6> (Force Values)
<Header> Definition
Output: File Version #, Date&Time, User ID, Job ID, Program ID
Format: 1X, A4, 4X, A18, 6X, 2I10, 2X, A2
<Title> Definition
Output: Title of ADAMS run
Format: A80
<Record 1> Definition - RM Location
Output: Part ID, Time, 1, X, Y, Z, <Euler Angles (radians)>, RM ID
Format: I10, 1PE13.5, I2, 6(1PE13.5), I10
<Record 2> Definition - CM Location wrt RM
Output: Part ID, Time, 2, X, Y, Z, <Euler Angles (radians)>, CM ID
Format: I10, 1PE13.5, I2, 6(1PE13.5), I10
<Record 3> Definition - CM Velocity wrt RM
Output: Part ID, Time, 3, X’, Y’, Z’, Wx, Wy, Wz(radians/time), CM ID
Format: I10, 1PE13.5, I2, 6(1PE13.5), I10
<Record 4> Definition - CM Acceleration wrt RM
Output: Part ID, Time, 4, X’’, Y’’, Z’’, Wx’, Wy’, Wz’(radians/time**2), CM ID
Format: I10, 1PE13.5, I2, 6(1PE13.5), I10
<Record 5> Definition – External Force Location wrt RM
Output: Part ID, Time, 5, X, Y, Z, <Euler Angles (radians)>, Marker ID
Format: I10, 1PE13.5, I2, 6(1PE13.5), I10
<Record 6> Definition – External Force Record wrt RM
Output: Part ID, Time, 3, Fx, Fy, Fz, Tx, Ty, Marker ID
Format: I10, 1PE13.5, I2, 6(1PE13.5), I10
Peak Loads
FEMDATA 117
C++ Statements
Except for FMAG, GMAG, and TMAG, each PEAK_SLICE load specification (FX, FY, FZ, TX, TY, TZ)
generates two output time steps for each marker force of the component, one for the maximum (peak) and
one for the minimum (valley). For FMAG and TMAG, only one time step is output for each marker force
since these quantities are load magnitudes and generate only positive values. With GMAG, only one time
step is output per body. If:
 Fm(t) represents the force acting on the body at Marker m.
ˆ
 r x, rˆ y, rˆ z represents the unit vector of the reference coordinate system of the rigid body (FEA
coordinate system of the flexible body).
 r(t) represents the position of the reference marker (RM) in that coordinate system.
ˆ ˆ ˆ
 || || represents taking the magnitude or length of a vector (that is, || ( r x, r y, r z ) || = 1)
Then the following conditions apply:
ˆ
 FX = Output loads at time t when F m ( t ) ⋅ r x ( t ) is a maximum and minimum for each marker m.
ˆ
 FY = Output loads at time t when F m ( t ) ⋅ r y ( t ) is a maximum and minimum for each marker m.
ˆ
 FZ = Output loads at time t when F m ( t ) ⋅ r z ( t ) is a maximum and minimum for each marker m.
ˆ
 FMAG = Output loads at time t when F m ( t ) ⋅ r ( t ) is a maximum for each marker m.
 GMAG = Output loads at time t when
 ˆ ˆ ˆ 
 MAX   F m ( t ) ⋅ r x ( t ),  F m ( t ) ⋅ r y ( t ),  F m ( t ) ⋅ r z ( t ) .
m m m

Note: Similar expressions exist for TX, TY, TZ, and TMAG. The PEAK_SLICE argument is not
available when you specify a time history OUTPUT load format (DAC or RPC).
Modal Superposition
Nodal displacements, strains, and stresses are computed using the principal of modal superposition:
118 Adams Solver
C++ Statements
Here φ i are the respective mode shapes from FEA and {q(t)}are the modal displacements of the flexible body
that Adams Solver computes.
Coordinate Reference Transformation of Stress or Strain
Because stress and strain are second-order tensors, the following equation is used to transform these quantities
to a reference coordinate system:
Where A R is the skew-rotation matrix from the flexible body’s LPRF (FE origin) to the marker’s coordinate
reference, and S is the symmetric stress or strain tensor. That is:
S xx S xy S xz
[ S ] = S yx S yy S yz where S ij = S ji
S zx S zy S zz
Definition of Hot Spots
The figure below illustrates how the radius argument can affect the definition of a hot spot region. In this
figure, the top 7 hottest nodes (those with the largest stress) are listed. If the number 5 and no radius is
specified on HOTSPOTS, then only nodes 4, 5, 3, 6, and 2 would be output. If a radius of 0.5 mm is
specified, then only node 4 would be listed from this region and the other 4 hot spots would come from nodes
with the highest stress from other regions.
FEMDATA 119
C++ Statements
Limitations
Using FEMDATA to output loads encounters the same limitations as exporting FEA Loads in Adams View.
See Limitations for Exporting FEA Loads for more information.
120 Adams Solver
C++ Statements
Caution: Note that all FEMDATA are output in the Adams modeling units. This causes a problem
when the Adams units are inconsistent with those used in the finite element model, and the
data that is output will be included in a subsequent finite element analysis.
For example, when outputting FEMDATA of type LOADS to ANSYS or MSC.Nastran for
inclusion in the FE analysis, the Adams and FE modeling units must be consistent. This is
also true when outputting FEMDATA of type NODAL_DEFORMATION when the
OUTPUT format is ANSYS or MSC.Nastran and the data will be used as input to the FE
analysis.
In the case of outputting FEMDATA of type MODAL_DEFORMATION, the only

concern for units is when MSC.Nastran (or PUNCH) has been specified as the OUTPUT
format. This is because rigid body motion is included in the output file along with the modal
coordinates. By definition, modal coordinates are unitless, so the modal stresses (or strains)
will be recovered correctly in MSC.Nastran irregardless of unit settings. However, in order
for the overall displacement of the component to be correctly recovered, the unit of length
must be consistent between models.
Examples
FEMDATA/100, STRESS, FLEX_BODY=101
, HOTSPOTS = 7, CRITERION = MAX_PRIN
, RADIUS = 0.5, FILE = hotspots_101
OUTPUT/STRESS = DAC
These statements create a text file, named hotspots_101.tab containing hot spot information for flexible body
101. Seven hot spots with a radius of 0.5 based on maximum principal stress are requested. Also, a time
history of the stress for each node found to be a hot spot is output in DAC format. The names of the DAC
files are given the prefix “hotspots_101” as specified in the FILE argument.
FEMDATA/1, LOADS, RM=201
, PEAK_SLICE = GMAG
, FILE = peak201.nas
OUTPUT/LOADS = NASTRAN
These statements create a NASTRAN input file containing loads of the parent part of marker 201 in that
marker’s coordinate reference system. They output the loads for only one time step when the magnitude of
the global sum of all marker forces on the part is greatest in the simulation.
FEMDATA/2, LOADS, FLEX_BODY=101
, PEAK_SLICE = FX:FY:FZ:FMAG
OUTPUT/LOADS = ANSYS
These statements create an ANSYS input file with .dat default extension containing loads acting on flexible
body 101 in the FEA coordinate system. If the flexible body has, say 4 attachments, you should expect (3*2
+ 1)*4 load cases (loads from 28 time steps) to be output, because FX, FY and FZ output loads for 2 time
steps per attachment, and FMAG will output 1 per attachment.
, FILE = conrod
FEMDATA 121
C++ Statements
OUTPUT/LOADS = RPC
These statements create an RPC file, named conrod.rsp that contains the time history of loads for all load
channels acting on flexible body 101. A Nastran load map file is also generated, named conrod_lc.nas. This
file contains the unit loads definitions in Nastran input format that map to the load channels in the RPC file.
This file can be combined with the Nastran BDF that was used to define the flexible body’ mesh, and perform
a static solution in obtaining stress coefficients related to the unit loads. The stress coefficients can be
combined with the actual loads in the RPC file in a fatigue program such as FE-Fatigue or MSC.Fatigue to
perform a fatigue analysis based on linear superposition theory.
See other Output available.
122 Adams Solver
C++ Statements
FIELD
The FIELD statement applies a translational and rotational action-reaction force between two markers.
Format
FIELD 123
C++ Statements
Arguments
CMATRIX=r1,...,r36 Defines a 6x6 matrix of viscous damping coefficients. The following matrix shows the
values to input.
Enter the elements by columns from top to bottom, then from left to right. CMATRIX
defaults to a matrix with thirty-six zero entries if you do not use either CMATRIX or both
CRATIO and KMATRIX. The units for the translational and rotational components of
CMATRIX should be force-time per unit displacement and torque-time per radian,
respectively.
CRATIO = r Defines the ratio of CMATRIX to KMATRIX. If you input CRATIO, Adams Solver
(C++) multiplies KMATRIX by CRATIO to obtain CMATRIX. Do not use CRATIO
without also using KMATRIX.
Default: 0
FORCE=r1,...r6 Defines three preload force components and three preload torque components in the field
element when the I and J markers are separated/misaligned by the values specified in the
LENGTH argument. The terms r1,...,r6 are the force components along the x-, y-, and z-
axis of the J marker and the torque components about the x-, y-, and z-axis of the J marker,
respectively. FORCE is optional and defaults to six zero entries.
FUNCTION=USER(r1[,... Defines and passes constants to the user-written subroutine FIESUB to define a nonlinear
,r30]) field. Follow FUNCTION with an equal sign, the character string USER and the values
(r1[,...,r30]) that Adams Solver (C++) is to pass to FIESUB. Learn more information on
the FIESUB subroutine and nonlinear fields. The FUNCTION argument must either be the
last argument in the FIELD statement or be followed by a backslash (\).
I=id, J=id Specifies the identifiers of two markers between which the force and torque is to exert.
124 Adams Solver
C++ Statements
KMATRIX=r1,...,r36 Defines a 6x6 matrix of stiffness coefficients. The following matrix shows the values to
input.
Enter the elements by columns from top to bottom, then from left to right. KMATRIX
defaults to a matrix with thirty-six zero entries. The units for the translational and
rotational components of KMATRIX should be force per unit displacement and torque per
radian, respectively.
Adams Solver (C++) cannot calculate the damping coefficients if you do not use both
CRATIO and KMATRIX. In that case, CMATRIX must be explicitly defined if you want
to include damping coefficients in the calculation of the field forces.
LENGTH=r1,...,r6 Defines six reference length angles. This is the nominal position of the I marker with
respect to the J marker, resolved in the J marker coordinate system. The terms r1,...,r6 are
the x, y, and z translational components (specified in linear displacement units) of the
displacement between the I and J markers; and a, b, and c are rotational displacement of
the axes of the I marker with respect to the J marker, resolved in the J marker axes (specified
in radians). If the reference force is zero, LENGTH is the same as the free length.
LENGTH is optional and defaults to a six zero entry.
ROUTINE=libname::subn Specifies an alternative library and name for the user subroutine FIESUB.
ame
FORMULATION By default, the LINEAR option is used. The LINEAR option matches the behavior of
previous releases. The NONLINEAR option forces Adams Solver to add a geometric
stiffness term; this option is useful if the FIELD is being used to model beams. However,
if using the FUNCTION=USER() option, the NONLINEAR option is ignored.
Default: LINEAR
LENGTH_TOL When using FORMULATION=NONLINEAR, the geometric stiffness uses the larger of
the current length and length tolerance.
Default: 1.e-05
Extended Definition
FIELD 125
C++ Statements
To specify a linear field, use the arguments in the FIELD statement to specify constants for the six-by-six
stiffness matrix, a preload force, a six reference lengths, and a six-by-six damping matrix. The stiffness and
damping matrices must be positive semidefinite, but need not be symmetric. To specify a nonlinear field, use
the user-written subroutine FIESUB to define the three force components and three torque components and
use the argument FUNCTION=USER(r1[,...,r30]) to pass constants to FIESUB.
The following constitutive equations define how Adams Solver (C++) uses the data for a linear field to apply
a force and a torque to the I marker depending on the displacement and velocity of the I marker relative to
the J marker.
Fx K 11 K 12 K 13 K 14 K 15 K 16 x – x 0 C 11 C 12 C 13 C 14 C 15 C 16 V x F1
Fy K 21 K 22 K 23 K 24 K 25 K 26 y – y 0 C 21 C 22 C 23 C 24 C 25 C 26 V y F2
Fz K 31 K 32 K 33 K 34 K 35 K 36 z – z 0 C 31 C 32 C 33 C 34 C 35 C 36 V z F3
= – – +
Tx K 41 K 42 K 43 K 44 K 45 K 46 a – a 0 C 41 C 42 C 43 C 44 C 45 C 46 ω x T1
Ty K 51 K 52 K 53 K 54 K 55 K 56 b – b 0 C 51 C 52 C 53 C 54 C 55 C 56 ω y T2
Tz K 61 K 62 K 63 K 64 K 65 K 66 c – c 0 C 61 C 62 C 63 C 64 C 65 C 66 ω z T3
For a nonlinear field, the following constitutive equations are defined in the FIESUB subroutine:
F x = f 1 ( x, y, z, a, b, c, V x, V y, V z, ω x, ω y, ω z )
F y = f 2 ( x, y, z, a, b, c, V x, V y, V z, ω x, ω y, ω z )
F z = f 3 ( x, y, z, a, b, c, V x, V y, V z, ω x, ω y, ω z )
T x = f 4 ( x, y, z, a, b, c, V x, V y, V z, ω x, ω y, ω z )
T y = f 5 ( x, y, z, a, b, c, V x, V y, V z, ω x, ω y, ω z )
T z = f 6 ( x, y, z, a, b, c, V x, V y, V z, ω x, ω y, ω z )
Adams Solver (C++) applies the defined forces and torques at the I marker. In the linear and nonlinear
equations:
 Fx, Fy, and Fz are the three translational force measure numbers.
 Tx, Ty, and Tz are the three rotational force measure numbers associated with unit vectors directed
along the x-, y-, and z-axis of the J marker.
 K is the stiffness matrix.
 x0, y0, z0, a0, b0, and c0 are the free lengths.
 x, y, z, a, b, and c are the translational and the rotational displacements of the I marker with respect
to the J marker expressed in the coordinate system of the J marker.
126 Adams Solver
C++ Statements
 Vx,Vy,Vz, ω x , ω y , and ω z are the time derivatives of the deformation, respectively; C is the
damping matrix.
 F1, F2, F3, T1, T2, and T3 are the translational and the rotational pre-tensions.
All variables and time derivatives are computed in the J marker coordinate system.
Adams Solver (C++) applies an equilibrating force and torque at the J marker, as defined by the following
equations.
Fj = -Fi
Tj = -Ti - L x Fi
Nonlinear theory
When using the FORMULATION=NONLINEAR option, the force equations are modified by adding a
geometric stiffness term
F = (K + Kg)U.
Kg is described in reference [1] and it is used to include nonlinear geometric effects. Matrix Kg has the following
structure:
N is the current axial load and L is the largest of the current instantaneous length and the length tolerance.
Option NONLINEAR shall be used when the FIELD models a beam like element and you need to include
geometrically nonlinear effects.
Tip:  A FIELD statement can define any six-component, action-reaction force. However, when
defining massless beams, you may want to use a BEAM statement. It requires only six
input values to compute the thirty-six values for the Kmatrix (see BEAM).
 Finite element analysis programs can give the values for CMATRIX and KMATRIX.
FIELD 127
C++ Statements
Caution:  For the constitutive equations to be accurate, at least two of the rotations (a, b, c) must be
small. That is, two of the three values must remain smaller than 10 degrees. In addition, if
a becomes greater than 90 degrees, b becomes erratic. If b becomes greater than 90 degrees,
a becomes erratic. Only c can become greater than 90 degrees without causing problems.
For these reasons, it is best to define your field such that angles a and b (not a and c and
not b and c) remain small.
 The three rotational displacements (a, b, and c) that define the field are not Euler angles.
They are the projected angles of the I marker with respect to the J marker. Adams Solver
(C++) measures them about the x-, y-, and z-axis of the J marker.
 Adams Solver (C++) applies the component translational and rotational forces for a field to
the I marker and imposes reaction forces on the J marker.
 The K and C matrices must be positive semidefinite. In other words:
xtK x > 0 for all non-zero displacements x, and

ytC y > 0 for all non-zero velocities y.
If this is not true, the stiffness matrix of the field may be removing energy from the system.
Similarly, the damping matrix may be adding energy to the system. Both of these situations are
uncommon. Adams Solver (C++) does not warn you if the C matrix, K matrix, or both are not
positive semidefinite. While Adams Solver (C++) does not require that these matrices be
symmetric, it is most realistic.
Examples
Consider a cantilever, semimonocoque wing structure like the figure below.
Cantilever, Semimonocoque Wing Structure
128 Adams Solver
C++ Statements
In order to model the elastic freedoms at location I shown in the figure, the system stiffness matrix must first
be determined for the retained degrees of freedom. A finite element super element analysis is one method for
determining the matrix. Assume that all other degrees of freedom are either constrained or superfluous for
this analysis. The system stiffness matrix is:
X Z θy
X 0.198E+04 0.126E-01 -0.147E+04
Z 0.126E-01 0.208E+03 -0.933E-02
θy -0.147E+04 -0.933E-02 0.763E+07
Inserting these entries into a full six-by-six FIELD array yields:
X Y Z θx θy θz
X 0.198E+04 0 0.126E-01 0 -0.147E+04 0
Y 0 0 0 0 0 0
Z 0.126E-01 0 0.208E+03 0 -0.933E-02 0
θx 0 0 0 0 0 0
θy -0.147E+04 0 -0.933E-02 0 0.763E+07 0
θz 0 0 0 0 0 0
FIELD 129
C++ Statements
The FIELD statement describing these elastic forces applied to Marker 100 due to displacement of Marker
100 relative to Marker 57 is:
FIELD/1, I=100, J=57, KMATRIX=0.198E+04
, 0, 0.126E-01, 0, -0.147E+04, 0,
, 0, 0, 0, 0, 0, 0,
, 0.126E-01, 0, 0.208E+03, 0, -0.933E-02, 0,
, 0, 0, 0, 0, 0, 0,
,-0.147E+04, 0, -0.933E-02, 0, 0.763E+07, 0,
, 0, 0, 0, 0, 0, 0
, LENGTH=0, 150, 0, 0, 0, 0
These entries must be made column by column. The distance between the I and J markers is zero except in
the y direction (where it is 150).
References
1. Theory of Matrix Structural Analysis. J.S. Przemieniecki. Courier Dover Publications, 1985
130 Adams Solver
C++ Statements
FLEX_BODY
The FLEX_BODY statement defines a linear or nonlinear elastic body. The FLEX_BODY is capable of
undergoing large motion. For a linear FLEX_BODY this motion is, characterized by six nonlinear generalized
coordinates for a body coordinate system (BCS). The small, linear elastic deformations of the FLEX_BODY
relative to this BCS are described by a linear combination of mode shapes. These modal amplitudes are
additional generalized coordinates for the FLEX_BODY. The body can be connected to the rest of the
mechanical system through applied forces and kinematic constraints.
FLEX_BODY 131
C++ Statements
Format
132 Adams Solver
C++ Statements
Arguments
BDF_FILE = filename Specifies the path to the Nastran Bulk Data File (BDF) which will be
read in to create a non-linear flexible body in Adams. This BDF file will
be a complete run-ready Nastran deck that will include the executive and
case controls as well as the bulk data.
This is one of the three ways to specify the detailed properties of a flexible
body (See MNF_FILE and DB_FILE for the alternative). Note that this
argument is required by Adams Solver (C++) to define a nonlinear
flexible body.
CHAR_LEN = c_len Specifies the characteristic length of this flexible body for linear limit
check. This should be in the model length unit. The linear limit is
defined as 10% of this length.
If user enables linear limit check (See

PREFERENCES/FLEX_LIMIT_CHECK) and does not specify this length,
Adams Solver (C++) will try to calculate it directly from the MNF or
MD DB file specified in MNF_FILE or DB_FILE. If it fails to do so, a
warning will be issued and the linear limit check on this flexible body will
be disabled.
Specifies modal damping as a fraction of critical damping. You can
specify modal damping using a function expression or a user-written
subroutine. To define the modal damping with an expression, follow
CRATIO with an equal sign and the expression. The FXFREQ and FXMODE
function expression may be useful here.
To define modal damping with a user-written subroutine, follow

CRATIO with an equal sign, the character string USER, and the values
(r1[,...,r30] that the Adams Solver (C++) is to pass to the DMPSUB user-
written subroutine. If the CRATIO argument is used, it must either be
the last argument in the FLEX_BODY statement, or be followed by a
backslash (\).
If you omit CRATIO, Adams Solver (C++) applies default damping as

follows:
 1% to modes under 100 Hz

 10% to modes under 1 kHz
 Full critical damping to modes over 1 kHz
You can disable the default damping by specifying CRATIO=0.
FLEX_BODY 133
C++ Statements
DB_FILE=file_name Specifies the path to the MD DB file that defines the detailed properties
of the flexible body. If there are more than one flexible bodies stored in
the database, an INDEX argument should be specified to identify the
body.
body (See MNF_FILE and BDF_FILE for the alternatives). Note that
this argument (or MNF_FILE or BDF_FILE) is not required by Adams
Solver (C++) unless flexible body contact is defined, but is required by
Adams View.
DMODE=a1,a2,...,an Specifies the initial values of the modal generalized coordinates.
Default: 0
Range: Real values
DYNAMIC_LIMIT=d Specifies the dynamic limit frequency of this flexible body in Hertz.
Modes whose frequencies are higher than d will be treated as quasi-static
modes, that is, the dynamic effects ( q·· and q· terms) are ignored in
dynamic simulation. So for quasi-static mode, the equation of motion is
just Kq = F , where K is the generalized stiffness, q is the modal
coordinate and F is the modal force acting on this mode, which may
include the coupling effects with other DOFs of flexible body. When
only static deformations are of interest for a particular simulation, using
the dynamic limit may improve the simulation performance for models
that have a lot of high-frequency modes.
The damping specified by CRATIO or GDAMP will be ignored for

quasi-static modes. Please refer to STABILITY_FACTOR on how to specify
damping on quasi-static modes.
Default: + ∞
134 Adams Solver
C++ Statements
EXACT=c1:...:c6 Specifies as many as six rigid body coordinates of the BCS that Adams
Solver (C++) should not change as it iteratively solves for initial
conditions which satisfy all constraints. The six coordinates are:
X - x coordinate
Y - y coordinate
Z - z coordinate
PSI - Psi angle
THETA - Theta angle
PHI - Phi angle
These coordinates can be entered in any order following EXACT. Adams

Solver (C++) does not change coordinates unless the values specified are
inconsistent with initial conditions for a joint or defined motion.
Default: None
Range: X, Y, Z, Psi, Theta, or Phi
Specifies how the generalized damping matrix referenced in the
MATRICES argument should be applied to the FLEX_BODY. If
GDAMP is OFF, the generalized damping matrix is ignored. If FULL is
specified, the generalized damping matrix is applied to both the rigid and
modal coordinates of the FLEX_BODY. If you specify
INTERNAL_ONLY, only the portion of the generalized damping
matrix corresponding to the modal coordinates is applied.
Default: OFF
Note: You can only specify the GDAMP argument if you have
defined a GENDAMP matrix for the associated
FLEX_BODY.
INDEX=index Specify the index of the flexible body in DB_FILE. MD DB is capable
of storing more than one flexible body.
Default: 1
FLEX_BODY 135
C++ Statements
INVARIANTS=c1:...:c9 Specifies a true and false pattern indicating which of the nine inertia
invariants Adams Solver (C++) should use to model inertia coupling of
the flexible and rigid body motion. The order of the patterns corresponds
to the nine successive inertia invariants. For more details on the inertia
invariants, see the Theory of Flexible Bodies in Adams Flex.
The following combinations have special significance:
T:T:F:F:T:T:T:T:T - Full inertia coupling of deformation and rigid body

motion.
T:T:F:F:F:T:T:T:F - Ignore second-order deformation corrections to the

inertia tensor, and the first-order corrections to the rotational and
flexible inertia coupling. This is also called partial coupling.
T:T:F:F:F:T:T:F:F - Neglect all deformation corrections to the mass

matrix.
*:*:*:*:*:F:*:*:* - Disable all deformations.
The pattern T:T:F:F:F:T:T:T:F is the default, because although it

potentially sacrifices small levels of accuracy compared to the first pattern
of full inertia coupling, it does so with significant computational savings.
If an MNF has six rigidbody modes in it, theoretically, invariants 3 and
4 should be zero even though there may be some non-zero entries in the
MNF file due to numerical errors. This is the reason that they are
disabled by default. The pattern T:T:F:F:F:T:T:F:F should be used with
great care, because it only returns an accurate answer when the flexible
component is quite rigid. The pattern *:*:*:*:*:F:*:*:*, where the * can be
either T or F, offers a way to turn off all flexibility in the structure, usually
for debugging purposes. Note that even with this last pattern, the
FLEX_BODY statement does not function like a PART statement, due
to formulation differences.
It is hard to envision circumstances where it is appropriate to disable
invariants 1 (the total mass), 2 (the undeformed CM location), and 7
(the undeformed inertia tensor). Disabling these normally causes a
numerical singularity.
Default: T:T:F:F:F:T:T:T:F
136 Adams Solver
C++ Statements
MATRICES=id1,...,idn Specifies identifiers of matrices that contain the properties of the

FLEX_BODY, such as inertia, node locations, mode shape information,
applied modal loads, and preloads. Each matrix is defined via a MATRIX
statement. Normally, these matrices are generated by a modal flexibility
preprocessor (MNF2MTX), which writes these matrices to a file. The
MATRIX statement then references this file, along with the appropriate
name from the list below. To learn more about this process, see Creating
Matrix Files.
The FLEX_BODY recognizes the following matrix names. Their

identifiers can be specified in any order.
SELMOD: A list of selected modes and their natural frequency.

SELNOD: A list of selected nodes and their location and flag of interface
node.
GENSTIFF: The generalized stiffness matrix.
INVAR1: Invariant 1 - the total mass of the flexible body.
INVAR2: Invariant 2 - the mass scaled, undeformed center of mass
location.
INVAR3: Invariant 3 - First order modal deformation correction to
center of mass.
INVAR4: Invariant 4 - Inertial coupling matrix of deformations and
rotations.
INVAR5: Invariant 5 - First order correction to the flexible inertia
coupling.
INVAR6: Invariant 6 - the generalized modal mass.
INVAR7: Invariant 7 - the moment of inertia.
INVAR8: Invariant 8 - First order modal deformation correction to the
moment of inertia (INVAR7)
INVAR9: Invariant 9 - Second order modal deformation correction to
the moment of inertia (INVAR7)
T_MODE: Translational mode shape of selected modes at selected
nodes.
R_MODE: Rotational mode shape of selected modes at selected nodes.
PRELOAD: The preload on the selected modes.
MODLOAD: The modal loadcases on the selected modes.
GENDAMP The generalized damping matrix.
EDGE_xx: A list of selected nodes which define an edge of the flexible
body (xx denotes an arbitrary edge id).
Default: None
Range: Adams identifiers
FLEX_BODY 137
C++ Statements
MEXACT=d1, d2, ..., dn Specifies as many as n modal body coordinates that Adams Solver (C++)
should not change as it iteratively solves for initial conditions that satisfy
all constraints. The variable n is the number of modal coordinates.
These coordinates can be entered in any order following MEXACT.

They are not changed by Adams Solver (C++) unless the values specified
are inconsistent with initial conditions for a joint or defined motion.
Default: None
Range: Active mode numbers
MNF_FILE=file_name Specifies the path to the modal neutral file that defines the detailed
properties of the flexible body.
body (See DB_FILE and BDF_FILE for the alternatives). Note that this
argument( or DB_FILE or BDF_FILE) is not required by Adams Solver
(C++) unless flexible body contact is defined, but is required by Adams
View.
STABILITY_FACTOR=s Specifies the stability factor for quasi-static modes when the dynamic
limit feature is enabled on this flexible body. If the modal force acting on
quasi-static mode has high frequency component, it may affect the
convergence of dynamic simulation. In this case, user can specify
artificial damping to stabilize the solution using this argument.
The damping added to the mode will be s times of critical damping. So

the equation of motion of quasi-static mode will be 2smωq· + Kq = F ,
where ω is the frequency of the mode.
Default: 10.0
NUMBER_OF_THREADS=n Specifies the number of threads to be used on each nonlinear flexible
body. A separate process is used to solve a nonlinear flexible body. To
specify more than one thread in solving a flexible body on this process,
set Number of threads > 1. The number of threads, n, must be an integer
in the range of 1 to 8. The default is 1.
QG=x,y,z Defines the Cartesian initial coordinates of the BCS with respect to the
ground coordinate system.
Default: 0.0, 0.0, 0.0

Range: Real values
138 Adams Solver
C++ Statements
FEA_MEM_SETTINGS=mem_size Specifies the size of memory to be used on each nonlinear flexible body.
The mem_size can be specified as a positive real number in megabytes.
This argument has priority over MEMORY_SCALE_FACTOR if it's
also specified.
Default: Use half of the amount of physical memory

MEMORY_SCALE_FACTOR=mem_scale Specifies the scale factor of the amount of physical memory to be used
on each nonlinear flexible body. The mem_scale can be specified as a
positive real number less than or equal to 0.8. If zero is specified, 0.5 is
used as the default. If the model has more than one nonlinear flexible
body, mem_scale will be automatically divided by the number of
nonlinear flex bodies in the model. This argument will be ignored if
FEA_MEM_SETTINGS is specified.
Default: 0.5 divided by the number of nonlinear flex bodies

BUFFER_SIZE=buff_size Specifies the number of words per I/O record to be used for the
nonlinear flexible body. buff_size can be specified as a positive integer
number less than or equal to 65537. Recommended buff_size settings
based on FE model size (DOF ranges) are:
8193 (DOF <= 100,000)
16385 (100,000 < DOF <= 400,000)
32769 (400,000 < DOF <= 1,000,000)
65537 (DOF > 1,000,000).
Default: Estimated based on the FE model size

COMPUTE_RESOURCE=host_name[:port Specifies the name of a remote host machine and optionally port number
_number] to be used to solve each nonlinear flexible body. If host_name is
specified, the NLFE name server has to be started on the remote host
machine, and then the remote kernel has to be started on the machine
where Adams is running using the Adams-NLFE Client Manager, before
a simulation can be launched. The default of port_number is 45000 and
specify to change if it's busy. For more information on the Adams-NLFE
Client Manager see "Using Distributed Computing for Nonlinear
Adams Flex Bodies" in Chapter 7 of the Installation and Operations
Guide.
Default: None
FLEX_BODY 139
C++ Statements
REPRESENTATION= {MODAL, RIGID, Specifies that the flexible body is eligible for runtime type switching
NFORCE} between MODAL and RIGID representations during a simulation, or if
the simple flex method (NFORCE) is employed. If MODAL, the
flexible body will be treated as a flexible body initially and can be
switched to RIGID with the FLEX_BODY command. If RIGID, the
flexible body will be treated as a rigid body initially and can be switched
to MODAL with the FLEX_BODY command during the simulation. If
NFORCE, an equivalent formulation of NFORCE statement is applied
and stiffness and/or damping property is only considered based on a
MNF and cannot be switched during the simulation. If
REPRESENTATION is not specified, the flexible body is not eligible for
runtime type switching and original MODAL formulation is applied.
Note: 1. Setting the REPRESENTATION of the flexible body to

RIGID can speed up the simulation with no model change,
but can result in a loss in fidelity.
2. Dual-representation or flexible bodies using the simple flex

method (NFORCE) do not directly support contact with any
other bodies nor modal force. One would have to use dummy
part geometry fixed to the flexible body for contact modeling.
3.The simple flex method (NFORCE) can speed up the

simulation with stiffness and/or damping property but
dynamic property will be ignored. CRATIO can be specified
as proportional damping ratio as same as NFORCE. Function
expression and GDAMP are not allowed.
4.In flexible bodies using the simple flex method, NFORCE

formulation is applied on interface nodes and other nodes are
attached to a rigid body. And the 5th column of SELNOD in
MTX file is the flag of interface node. If old MTX file (4
columns SELNOD) is used, all attachment nodes are
recognized as interface node and it may cause singularity. In
addition, all interface nodes needs to have accurate stiffness of
6 degrees of freedom, for example in Nastran, 123456 have to
be defined as ASET. If not, it also may cause singularity.
REULER=a,b,c Defines the 3-1-3 Euler angles that Adams Solver (C++) uses to establish
the initial orientation of the BCS with respect to the ground coordinate
system. The a, b, and c rotations are in radians and are, respectively,
about the z-axis of ground, new x-axis, and new z-axis of the BCS. To
input Euler angles in degrees, you should add a D after each value.
Default: 0.0, 0.0, 0.0

Range: Real values
VM=id Specifies the identifier of the marker that specifies the direction of
translational velocity initial conditions (VX, VY, and VZ). VM defaults
to global orientation.
140 Adams Solver
C++ Statements
VMODE=b1,b2,...,bn Specifies the initial values of the time rate of change of the modal
generalized coordinates.
Default: 0
Range: Real Values
VX=x,VY=y,VZ=z Specifies the initial translational velocities of the Body Coordinate
System (BCS) along the x-axis (VX), y-axis (VY), and z-axis (VZ) of the
VM coordinate system.
Default: 0
Range: Real values
angular velocity initial conditions (WX, WY, and WZ) are defined. WM
defaults to the BCS location and orientation. The origin of the WM
marker lies on the axis of rotation. This is most useful for rotating
systems.
WX=a,WY=b,WZ=c Specifies the initial rotational velocities of the BCS along the x-axis
(WX), y-axis (WY), and z-axis (WZ) of the WM coordinate system.
Default: 0
Range: Real values
Tip:  The Adams Flex Toolkit is used to generate the input matrices in the Adams Solver matrix
format. For more information on generating matrix files for the FLEX_BODY statement,
see Translating an MNF or an MD DB into a Matrix File.
 The intrinsic variables FXMODE and FXFREQ are available so you can write function
expressions that define CRATIO as a function of mode number and/or modal frequency
(see FXMODE and FXFREQ functions).
 You can query the location, orientation, translational velocity and angular velocity of a
FLEX_BODY using the SYSARY utility subroutine with the FXDISP, FXDC, FXTVEL
and FXRVEL options. See the SYSARY documentation for details.
 If your FLEX_BODY undergoes high-speed, rigid body rotations about a stationary axis,
significant solver performance can be realized by aligning the z-axis of the body coordinate
system (BCS) with the spin axis. Because the BCS of the FLEX_BODY is defined by the
basic coordinate system in the finite element model, re-orientating the BCS with respect to
the body requires you to re-orient the finite element model with respect to its basic
coordinate system. In MSC.Nastran, this can be done easily with CORDxx Bulk Data
entries.
FLEX_BODY 141
C++ Statements
Caution:  All nodes to which markers are attached must be present in the SELNOD matrix.
 Function expressions defining CRATIO should be functions of TIME, MODE,
FXMODE, and/or FXFREQ only.
 Flexible body CONTACT is only supported when using Adams Solver (C++).
 Only use modes with nonzero eigenvalues. A mode with a zero eigenvalue (or frequency)
represents a rigid body degree of freedom that is already introduced by the BCS.
 Due to the numeric methods involved, rigid body modes may have nonzero
eigenvalues/frequencies. Typically, these eigenvalues are numerically small. Using these
modes will cause simulation problems.
 If there are less than six rigid body modes in the MNF it is strongly recommended to
enable INVAR3 and INVAR4 using INVARIANTS argument.
 None zero modal generalized velocities may be observed when switching from RIGID to
MODAL because reconciliation is done by solver to satisfy the constraints.
Examples
FLEX_BODY/1
, MATRICES=1,2,3,4,5,6,7,8,9,10,11,12,13,14
, CRATIO=0.0\
, DMODE=.0,.0,.0,.0
, VMODE=.0,.1,.0,.0
This statement defines a flexible body with a damping ratio of 0.0 on all modes. Zero initial modal
displacements are specified by the DMODE argument. The VMODE argument specifies an initial modal
velocity for mode 2 of 0.1.
FLEX_BODY/1
, CRATIO = STEP(TIME, 0.1, 1.0, 1.2, STEP(FXFREQ, 3000, 0.02, 10000,
0.2))\
,MATRICES = 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14
This example specifies modal damping that varies both with time and modal frequency, such that all modes
have 100% critical damping until t=0.1, after which:
 Modal damping decreases smoothly to between 2% and 20% of modal damping at time=1.2.
 Modes with modal frequencies less than 3,000 reach 2% modal damping.
 Modes with modal frequencies above 10,000 reach 20% modal damping.
 Modes with modal frequencies between 3,000 and 10,000 reach modal damping values smoothly
distributed between 2% and 20%.
FLEX_BODY/1,
, CRATIO = IF(FXFREQ-100:0.01,0.1,if(FXFREQ-1000:0.1,1.0,1.0)\
,MATRICES = 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14
This example recreates the default modal damping scheme using nested IF function expressions.
142 Adams Solver
C++ Statements
FLEX_BODY/1,
, MATRICES = 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14
, MNF_FILE=C:/models/link.mnf
This example specifies the detailed properties of this flexible body are in a MNF file, C:/models/link.mnf.
FLEX_BODY/1,
, MATRICES = 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14
, DB_FILE=C:/models/demo.MASTER, INDEX=3
This example specifies the detailed properties of this flexible body are stored as the third body in an MD DB
file, C:/models/demo.MASTER.
FLEX_BODY/1
,MATRICES = 1, 2, 3, 4
, BDF_FILE = DEMO_FLEX_BODY_1.dat
,NUMBER_OF_THREADS=4
This statement defines a non-linear flexible body which will have 4 threads allocated on the compute
machine. This non-linear flexible body has the Nastran Input file DEMO_FLEX_BODY_1.dat which will
contain all the information needed for the nonlinear finite element solution such as Solution Type, Model
Definition, Loading, Boundary Conditions and so on.
FLEX_BODY/1,
, MATRICES = 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14
, DYNAMIC_LIMIT=500.0
This statement defines a flexible body with a dynamic limit of 500.0 Hz. Any mode that is higher than 500.0
Hz will be treated as quasi-static mode. A damping of 10 times the critical damping will be applied to these
modes.
FLEX_BODY/1,
, MATRICES = 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14
, DYNAMIC_LIMIT=1.0e3
, STABILITY_FACTOR=0.0
This statement defines a flexible body with a dynamic limit of 1000.0 Hz. Any mode that is higher than
1000.0 Hz will be treated as quasi-static mode. No damping is applied to the quasi-static modes (Note that
solution may become unstable if there is high frequency excitation).
See other Inertia and material data statement available.
FRICTION 143
C++ Statements
FRICTION
The FRICTION statement defines parameters for frictional forces on translational, revolute, cylindrical,
hooke, universal, and spherical joints.
Note: Frictional forces and torques are computed by Adams Solver (C++) using a friction model
that supports dynamic friction and stiction.
144 Adams Solver
C++ Statements
Format
FRICTION 145
C++ Statements
Arguments
BALL_RADIUS=Rb Defines the radius of the ball in a spherical joint for use in friction-force and torque
calculations.
Default: 1.0
Range: BALL_RADIUS > 0
BENDING_REACTION_ARM= Defines the effective moment arm use to compute the contribution of the bending
Rb moment on the net friction torque in revolute, hooke, and universal joints.
Default: 1.0
Range: BENDING_REACTION_ARM > 0
STICTION_TRANSITION_VE Defines the absolute velocity threshold for the transition from dynamic friction to
LOCITY=r static friction. If the absolute relative velocity of the joint marker is below
STICTION_TRANSITION_VELOCITY, then static friction or stiction acts to
make the joint stick.
Default: 0.1 length units/unit time on the surface of contact in the joint.
Range: STICTION_TRANSITION_VELOCITY > 0
EFFECT={ALL[[STICTION, Defines the frictional effects included in the friction model. Stiction is static-
SLIDING]]} friction effect, while sliding is dynamic-friction effect. Excluding stiction in
simulations that don’t require it can greatly improve simulation speed.
Default: All
FRICTION_FORCE_PRELOAD Defines the joint’s preload frictional force, which is usually caused by mechanical
=r interference in the assembly of the joint.
Default: 0.0
Range: FRICTION_FORCE_PRELOAD > 0
FRICTION_ARM=Rn Defines the effective moment arm used to compute the axial component of the
friction torque in revolute, hooke, and universal joints.
Default: 1.0
Range: FRICTION_ARM > 0
INACTIVE=STATIC Specifies that frictional forces not be calculated for a static or quasi-static solution.
Default: none
Range: Static
146 Adams Solver
C++ Statements
INITIAL_OVERLAP=Xs0 Defines the initial overlap of the sliding parts in either a translational or cylindrical
joint. The joint's bending moment is divided by overlap to compute the bending
moment's contribution to frictional forces.
Default: 1000.0
Range: INITIAL_OVERLAP > 0
INPUTS=( {ALL, NONE Defines the input forces to the friction model. By default, all user-defined preloads
[[PRELOAD: and joint-reaction force and moments are included. You can customize the friction-
REACTION_FORCE: force model by limiting the input forces you list in the statement.
BENDING_MOMENT:
TORSIONAL_MOMENT]]} ) Default: ALL
Joint Type: (Available inputs)
Translational (PRELOAD, REACTION_FORCE, BENDING_MOMENT,

TORSIONAL_MOMENT)
Cylindrical, Revolute, Universal, Hooke (PRELOAD, REACTION_FORCE,

BENDING_MOMENT)
Spherical (PRELOAD, REACTION_FORCE)

JOINT=id Identifies the joint to which frictional forces apply.
MAX_STICTION_DEFORMAT Defines the maximum creep that can occur in a joint during the stiction regime.
ION=r The creep allows Adams Solver (C++) to impose the Coulomb conditions for
stiction or static friction, for example:
Friction force magnitude < μstatic * normal force
Therefore, even at zero velocity, a finite stiction force is applied if your system
dynamics requires it.
Default: 0.01 length units

Range: MAX_STICTION_DEFORMATION > 0
MU_DYNAMIC=r Defines the coefficient of dynamic friction. During the sliding regime, the
magnitude of the frictional force is the product of MU_DYN and the magnitude
of the normal force in the joint, for example:
Friction force magnitude, F = μN
where μ = MU_DYNAMIC and N = normal force

The dynamic frictional force acts in the opposite direction of the velocity of the
joint.
Default: none
Range: MU_DYNAMIC > 0
FRICTION 147
C++ Statements
MU_STATIC=r Defines the coefficient of static friction in the joint. The magnitude of the frictional
force is the product of a function of MU_STAT, MU_DYNAMIC, and the creep,
times the magnitude of the normal force in the joint, for example:
Friction Force Magnitude, F = μN
where μ = f (MU_STATIC, MU_DYNAMIC, creep) and N = normal force

The static frictional force acts to oppose the net force or torque along the degrees
of freedom of the joint.
Default: none
OVERLAP_DELTA={INCREAS To define friction in a sliding joint (either a translational or a cylindrical joint),
E, DECREASE, CONSTANT} Adams Solver (C++) computes the overlap of the joint. As the joint slides, the
overlap can increase, decrease, or remain constant. OVERLAP_DELTA is used to
define any change in overlap.
 INCREASE indicates that overlap increases as the

I marker translates in the positive direction along the
J marker; the slider moves to be within the joint.
 DECREASE indicates that the overlap decreases with positive translation
of the joint; the slider moves outside of the joint.
 CONSTANT indicates that the amount of overlap does not change as the
joint slides; all of the slider remains within the joint.
Default: CONSTANT
MAX_FRICTION_FORCE = r Defines the maximum of the friction force for use in translational or cylindrical
joint.
Default: 1.0E+40
Range: MAX_FRICTION_FORCE > 0
Note: When there is a preload friction force applied to the joint, the
MAX_FRICTION_FORCE is set to be:
FRICTION_FORCE_PRELOAD+MAX_FRICTION_FORCE.
BENDING_FACTOR = r Defines the coefficient that multiplies the term Tm/Xs when the
BENDING_MOMENT input is used for the friction force computation. This
coefficient was hardcoded to 1.0 in releases previous to 2016.
Default: 1.0
Range: BENDING_FACTOR>0.
148 Adams Solver
C++ Statements
MAX_FRICTION_TORQUE = r Defines the maximum of the friction torque for use in revolute, universal, hooke,
spherical, or cylindrical joint.
Default: 1.0E+40
Range: MAX_FRICTION_TORQUE > 0
Note: When there is a preload friction torque applied to the joint, the
MAX_FRICTION_TORQUE is set to be:
FRICTION_TORQUE_PRELOAD+MAX_FRICTION_TORQUE.
TRANSITION_VELOCITY_CO Defines the absolute velocity threshold for the transition from static friction to
EFFICIENT = r dynamic friction. If the absolute relative velocity of the joint marker is at or above
TRANSITION_VELOCITY_COEFFICIENT *
STICTION_TRANSITION_VELOCITY, then the dynamic friction coefficient
is applied. Between STICTION_TRANSITION_VELOCITY and
STICTION_TRANSITION_VELOCITY the coefficient of friction is
transitioning from the static coefficient of friction to the dynamic coefficient of
friction.
Default: 1.5
Range: TRANSITION_VELOCITY_COEFFICIENT > 1
PIN_RADIUS=Rp Defines the radius of the pin for a revolute, cylindrical, hooke, or universal joint.
Default: 1.0
Range: PIN_RADIUS > 0
REACTION_ARM=Rn Defines the effective moment arm of the joint-reaction torque about the
translational joint’s axial axis (the z-direction of the joint’s J marker). This value is
used to compute the contribution of the torsional moment to the net frictional
force.
Default: 1.0
Range: REACTION_ARM > 0
FRICTION_TORQUE_PRELO Defines the preload friction torque in the joint, which is usually caused by
AD=r mechanical interference in the assembly of the joint.
Default: 0.0
Range: FRICTION_TORQUE_PRELOAD > 0
I_YOKE J_YOKE I_YOKE and J_YOKE define the rotational constraint on which the FRICTION
statement acts. I_YOKE identifies the yoke to the I marker’s rotational constraint.
Likewise, J_YOKE identifies the yoke to the J marker’s rotational constraint. These
keywords are used with only hooke and universal joints.
FRICTION 149
C++ Statements
Extended Definition
Application of Friction in Joints
This section provides graphical descriptions and block diagrams of the joints and friction regimes available
in the FRICTION statement.
To learn about block diagrams and friction regimes, see:
 Conventions in Block Diagrams
 Friction Regime Determination (FRD)
To find information on a particular joint, see:
 Translational Joint
 Revolute Joint
 Cylindrical Joint
 Universal/Hooke Joint
 Spherical Joint
Conventions in Block Diagrams

The following tables identify conventions used in the block diagrams:
 Table 1 identifies symbols in the diagrams.
 Table 2 describes the relationship between the INPUTS argument in the FRICTION statement and
the switches used in the block diagrams.
Table 1 Legend for Block Diagrams
Symbol: Description:
_________ Scalar quantity
Vector quantity
Summing junction:
c=a+b
Multiplication junction:
c=axb
MAG Magnitude of a vector quantity

ABS Absolute value of a scalar quantity
FRD Friction regime determination
150 Adams Solver
C++ Statements
Table 2 Relationship Between the INPUTS Argument and Switches Used in the Block Diagrams
Switch: INPUTS=: Symbol: Acceptable Values:

SW1 PRELOAD Fprfrc or Tprfc ON/OFF
SW2 REACTION F or T ON/OFF
FORCE
SW3 BENDING Tr ON/OFF
MOMENT
SW4 TORSIONAL Tn ON/OFF
MOMENT
ALL/NONE sets all
applicable switches
ON/OFF,
respectively
Friction Regime Determination (FRD)

Three friction regimes are permissible in Adams:
Dynamic friction A joint is in dynamic friction if its joint velocity magnitude exceeds the
value of the transition velocity coefficient multiplied by the friction
transition velocity. The dynamic coefficient of friction (md) is used in the
computation of frictional forces.
Transition between dynamic If the joint velocity magnitude is between the value of the transition
and static friction velocity coefficient multiplied by the stiction transition velocity and
friction transition velocity, the joint is considered to be transitioning
between static and dynamic friction. A STEP function transitions the
coefficient of friction between the dynamic (md) and static (ms)
coefficients of friction.
Static friction A joint is in static friction when the joint velocity magnitude falls below
the stiction transition velocity. The effective coefficient of friction is
computed using the joint creep, joint velocity, and static coefficient of
friction (ms).
The joint velocity determines the instantaneous friction regime for a joint. The figure below shows the block
diagram of the friction regimes available in Adams Solver (C++).
FRICTION 151
C++ Statements
Examples
FRICTION/102, JOINT=102, I_YOKE
, Mu_Static=0.03, Mu_Dynamic=0.024
, Stiction_Transition_Velocity=0.1
, Max_Stiction_Deformation=0.15
, Pin_Radius=12.25
, Friction_Arm=8.2
, Effect=All
, Inputs=Reaction_Force
This statement creates frictional forces about the rotational degree of freedom associated with the I marker’s
part of either a hooke or universal joint. The following items apply:
 We assume that the joint has a 12.25 length-unit-radius pin and an effective-friction-moment arm
that is at the end caps of 8.2 length units.
 The friction model includes dynamic- and stiction-friction effect. The static-friction coefficient is
.03 and the dynamic-friction coefficient is .024.
 When computing the frictional force, Adams Solver (C++) identifies only the joint-reaction forces as
force inputs.
 The transition from dynamic friction to stiction occurs when the relative angular velocity in the
joint falls below 0.1 units of length/unit time. A maximum deflection of 0.15 length units is
permitted when the joint is stiction.
152 Adams Solver
C++ Statements
GCON
The GCON statement introduces a constraint equation that must be satisfied by Adams Solver (C++) during
the simulation. This allows you to specify both holonomic and non-holonomic constraints.
Format
GCON/id [, I=id], FUNCTION=exp
Arguments
I If specified, the reaction force on this marker is measured and reported as part of standard
results. The reaction force reported is the force that is exerted on the marker in order to
satisfy the constraint equation. Note that if a marker is specified and the FUNCTION exp
has no dependency on it, GCON reports a zero force.
Default value: the ground coordinate system (GCS)

FUNCTION Expression that Adams Solver (C++) forces to zero during the simulation. See the Extended
Definition for more information.
Extended Definition
While the JOINT statement describes a physically recognizable combination of constraints that are used to
connect bodies together, the GCON statement enables you to define an arbitrary constraint specific to a
particular model. The GCON statement is more general and can be used to equivalently define the existent
JOINT elements. Therefore, the spherical joint
JOINT/11, SPHERICAL, I=1,J=3
could be equivalently replaced by the following set of three GCONs:
GCON/111, I=2, FUNC=DX(2,3)
GCON/112, I=2, FUNC=DY(2,3)
GCON/113, I=2, FUNC=DZ(2,3)
The GCON statement allows you to define both holonomic and non-holonomic constraints. Holonomic
constraints only depend on position measures, like GCON/111 through GCON/113 above. A constraint is
non-holonomic if (a) its expression exp1 contains velocity measures, and (b) there is no expression exp2 that
is the time integral of exp1. An example of a non-holonomic constraint is a roll without slip condition
GCON/34, FUNC=VX(2) - WZ(2)*DY(2)
The GCON statement introduces a constraint to Adams Solver (C++) that is guaranteed to be handled
correctly as long as the FUNCTION is in Pfaffian form. In this context, note that any holonomic expression
is automatically in Pfaffian form. In the case of non-holonomic constraints, a Pfaffian constraint requires that
the FUNCTION is limited to expressions that are linear in velocity quantities. In other words, if there are
velocity quantities in the definition of the FUNCTION (as is the case in the previous GCON), a partial
derivative of the FUNCTION with respect to any velocity quantity present in its definition should lead to
GCON 153
C++ Statements
an expression that does not depend on velocity quantities. The previous GCON is therefore in Pfaffian form,
∂-------------------
FUNC- ∂FUNC
since = 1 , and -------------------- = – DX ( 2 ) , which makes the FUNC linear in velocity quantities.
∂VX ( 2 ) ∂WZ ( 2 )
Another example of a Pfaffian non-holonomic constraint is the perpendicularity condition
GCON/25, FU=VX(2,3)*DX(2,1)+ VY(2,3)*DY(2,1)+ VZ(2,3)*DZ(2,1)
that indicates that the velocity V(2,3) is orthogonal to the distance vector between markers I=2 and J=1.
An example of a non-Pfaffian GCON is
GCON/25,FU=VX(2,3)*VX(2,3)*DX(2,1)+VY(2,3)*DY(2,1)+ VZ(2,3)*DZ(2,1)
∂FU -
For this example, -------------------------- = 2 ⋅ VX (2,3) ⋅ DX (2,1) , which is an expression that depends on the
∂VX ( (2,3) )
velocity measure VX(2,3).
The FUNCTION expression exp can reference variables defined in the .adm file through the VARVAL
construct. It should be stressed again that correct handling of the GCON requires that the expression
defining the VARIABLE only depends on time, and position and velocity measures; in other words, the
Pfaffian character of the GCON is not undermined by the presence of the VARVAL.
Discussion on non-holonomic constraints
In all cases, whether a constraint φ is holonomic or non-holonomic, Adams Solver (C++) handles the said
T
constraint by adding the term φ q λ to the governing equations of motion. For a thorough theoretical
discussion on the handling of such constraints, see chapter 5 in reference [1] which is exclusively dedicated
to the issue of non-holonomic constraints. The reader will find therein that the topic of handling non-
holonomic constraints is still on the discussion table. Some researchers are of the opinion the physics of the
T
model is correctly handled by adding the term φ q λ to the governing equations, some researchers have no
opinion on the subject.
References
 John G. Papastavridis, Analytical Mechanics: A Comprehensive Treatise on the Dynamics of Constrained
Systems; For Engineeers, Physicists, and Mathematicians. 1st Edition. Oxford University Press, 2002.
Tip: There is no dedicated function that returns the reaction force induced by a user constraint
on a marker. You can invoke an existing function such as FX(I[; J][;K]) for this purpose. Note
that FX(I[; J][;K]) reports the force that acts on the I marker as a result of both constraint
and external forces applied to this marker. To only obtain the contribution of the GCON,
the markers that appear in FX(I[; J][;K]) should be exclusively used to define the GCON,
and no other elements such as applied forces, joints, or motions should refer them.
154 Adams Solver
C++ Statements
Caution:  As mentioned in the Extended Definition, correct handling of a GCON element assumes a
FUNCTION defined in Pfaffian form.
 Kinematic models are incompatible with velocity constraints. If a model is rendered
kinematic by displacement constraints, any additional velocity constraints will be either
redundant or conflicting. In either case, version 2003 of Adams Solver (C++) is incapable
of analyzing the model as explained in the Known Limitations. Consequently, a model that
contains velocity constraints can only be simulated using the dynamic solver.
 For a position-level GCON, the FUNCTION must be at least three times differentiable.
If the GCON introduces a velocity-level constraint, then the FUNCTION should be at
least twice differentiable. This requirement ensures that internally Adams Solver (C++) can
take the necessary derivatives to perform certain types of analyses such as
Acceleration/Force reconciliation, dynamic analysis, and so on. Note that if the expression
provided for GCON is not continuously differentiable for the required number of times,
the integrator will either fail, or have a difficult time finding the numerical solution.
 The ability of the Adams Solver (C++) to handle function expressions to provide the
necessary derivatives required by the GCON does not extend to user subroutines.
Consequently, a VARIABLE can only be referenced in a GCON provided it is defined
using function expressions, rather than a VARSUB subroutine.
 Use the RESULTS/XRF statement in order to get the reaction force on marker I reported
in the results file. This is the only output format currently able to handle GCON output.
 Models with GCONs defining velocity constraints can't be linearized. This limitation will
be removed in future releases.
Examples
The following example refers to a model that has two pendulums connected to ground through revolute
joints 1 and 2 (markers 5 and 7 are ground markers). The motion of the two pendulums takes place in the
Oxy plane. A rotational motion 17 is specified on the first revolute joint. The user defined constraint 23
enforces the second pendulum to follow the motion of the first pendulum:
JOINT/1, REVOLUTE, I = 5, J = 6
MOTION/17, ROTATIONAL, JOINT = 1, FUNCTION = 30.0D*time
GCON/23, FUNC=AZ(6, 5)-AZ(8, 7)
The generalized constraint GCON/23 requires the rotation angle about the global z-axis of marker 8 to be
identical to the same rotation angle for marker 6. The latter is the marker on which motion 17 acts. As a
result, this motion will actually drive both pendulums. Consequently, the torque applied to induce the
prescribed motion is going to be larger than when GCON 23 is not present in the model, because the motion
effectively drives both pendulums.
The situation described above, namely the extra torque required to make the second pendulum follow the
first pendulum, might not be what you want to see. In this case, the function AO, from Action Only, can be
used to indicate that the reaction torque on the first pendulum induced by the motion of the second
pendulum is to be ignored. Replacing GCON/23 with GCON/24:
GCON 155
C++ Statements
GCON/24, FUNC=AO(AZ(6))-AZ(8)
will keep the torque necessary to drive the first pendulum unchanged from the case when the GCON is
actually not present at all. Therefore, the second pendulum follows the motion of the first pendulum, but the
reaction torque in MOTION/17 is shielded from this effect.
An equivalent way of imposing that the second pendulum will follow the motion of the first one is by
replacing GCON 23 with the following user constraint:
GCON/25, FUNC=WZ(6)-WZ(8)
This user constraint indicates for the two markers that the angular velocity perpendicular to the plane of
rotation should be identical. As pointed out in the Caution: section, keep in mind that for this simple model,
the motion of the second pendulum is completely determined by the motion of the first pendulum.
Nevertheless, the number of degrees of freedom at the position level is one, and therefore the system is not
kinematically determinate. Consequently, simulation of this model requires the use of the dynamic solver.
The GEAR statement in the following .adm snippet:
JOINT/2,REVOLUTE,I=6,J=7
JOINT/3,REVOLUTE,I=8,J=9
GEAR/1,JOINTS=2,3, CV=10
could be replaced with a non-holonomic velocity based gear constraint:
GCON/1, I=6
,FUN=UVZ(10)*(WXYZ(6,7)%DXYZ(10,6)-WXYZ(8,9)%DXYZ(10,8))
The example also previews a 3D expression language extension wherein the UVZ(10) measure refers to a Unit
Vector (UV) in the direction of the z-axis of marker 10, and the ‘%’ corresponds to the cross product.
Likewise, DXYZ(10,6) represents the three-dimensional distance vector between markers 10 and 6, while
WXYZ(8,9) is the angular velocity of marker 8 with respect to marker 9. The 3D extensions cannot yet be
used with statements other than GCON and is not documented elsewhere.
Note that if the GEAR statement was changed to a GCON statement in a kinematically determinate model,
that is, a zero degree of freedom model, the model would gain one degree-of-freedom and become a dynamic
model. This is because one displacement constraint has been eliminated and replaced with a velocity
constraint.
Applications
The user-defined constraint is intended to be used to prescribe simple algebraic equations in position and
velocity measures that must be satisfied by Adams Solver (C++). The statement is a new feature added in
Adams Solver (C++). Due to its complexity and extremely general nature, it is highly probable that not all
possible applications have been anticipated and tested. Although models which exceed the capabilities of the
system will, in most cases, be detected, this can not be completely guaranteed. It is advisable to use the
GCON statement with a degree of caution. Some of the known limitations are listed below.
One possible use of this element is with complex models during preliminary setup stages. For example,
components in a car model can be coerced to satisfy certain constraints during an initial “settle down”
equilibrium analysis prior to specifying a steady-state motion to the whole car. Note that the user constraints
can be activated and deactivated through the Adams command language. Another possible use of GCON is
to specify arbitrary user-defined motions that relate time and various position and velocity measures.
156 Adams Solver
C++ Statements
Known Limitations
 Currently, there is no redundancy check for user constraints defined at the velocity level. Therefore,
you can impose constraints that are not redundant at the position level, but lead to a set of
redundant constraints when their time derivative is considered with other velocity level constraints
during the velocity Initial Conditions (IC) analysis. Consider the situation when two constraints are
defined as GCON/1, FU=DX(1,2), and GCON/2, FU=VX(1,2). Because the redundant constraint
analysis only includes position level constraints, Adams Solver (C++) will not identify that a velocity-
level constraint (GCON/2) induces a redundant constraint during the velocity computation. As a
result, a model that contains these two user constraints will fail during the velocity analysis with a
singular Jacobian error.
 The GCON does not support the DIFF, LSE, GSE and TFSISO elements. If you use GCON to
constrain the values of DIFF, LSE, GSE and TFSISO elements, note that they will not contribute
degrees of freedom that are considered removed by a GCON element. The GCON statement
functions properly for Pfaffian expressions depending on position and velocity measures and time, or
as mentioned earlier, on VARVALs measures for VARIABLEs that only depend on position and
velocity measures and time.
GEAR 157
C++ Statements
GEAR
The GEAR statement defines a gear pair constraint. Examples include a spur, helical, planetary, bevel, and
rack-and-pinion gear pairs.
Format
GEAR/id, JOINTS=id1,id2, CV=id
Arguments
CV=id Identifier of the marker that designates the point of contact and implicitly determines
the ratio of the two gears. The z-axis of the CV marker must point in the direction of
common velocity at the point of contact. The direction of common velocity is
tangent to both pitch circles and would be normal to the tooth surfaces of the gears
if the pressure angle was zero (Adams Solver (C++) always assumes a zero pressure
angle). The CV marker must belong to the carrier part that also hosts the J markers
of the joints.
JOINTS=id1,id2 Specifies the two joints whose relative motion is to be related with a gear. Each of
these two joints must be translational, revolute, or cylindrical. Note that both J
markers of these joints belong to a carrier part that must also host the CV marker.
Extended Definition
The GEAR statement uses the location of a common velocity CV marker to determine the point of contact
of the two gear pitch circles. The direction of the z-axis of the common velocity marker indicates the direction
of the common velocity of points on the gear teeth in contact. This is also the direction in which gear tooth
forces act. Note that the CV marker has constant position and orientation in the carrier body coordinate
system (BCS). The CV marker through its z-axis only provides a direction, and there is no need to be more
specific than this. In this context, there is no need to indicate things such as how the power flow occurs
through the gear.
The reaction force reported back to you for a GEAR element is the reaction force measured on the J marker
of the joint that is specified first in the GEAR definition. It is important to keep in mind that the J markers
for both joints associated with the GEAR element must belong to the carrier part (the part that hosts the CV
marker).
Caution:  Gear reaction forces and torques are difficult to obtain from the Request file because of the
way Adams Solver (C++) generates REQUEST statement output. Both joints associated
with the gear resist the tooth force generated by the gear. Therefore, the gear tooth reaction
force appears in both joints. The reaction torques due to the gear does not appear in the
joints, but they can be calculated from the gear tooth reaction force and the moment arms
to the joints. The Results file explicitly gives the gear tooth reaction force.
 A GEAR statement does not simulate the backlash and the other intermittent effects that
characterize actual gears.
158 Adams Solver
C++ Statements
Examples
The figure below illustrates the use of a GEAR statement to define a bevel gear pair.
Bevel Gear Pair
The GEAR statement for this gear pair is below.

GEAR/1, JOINTS=13,23, CV=303
This GEAR statement indicates that the gear pair relates the motions of Joints 13 and 23 and indicates the
common velocity marker. Below are the statements that work with this GEAR statement to communicate the
characteristics of the gear pair to Adams Solver (C++).
MARKER/303, PART=3, QP=-2, -2, 0
JOINT/13, I=101, J=301, REVOLUTE
MARKER/101, PART=1, QP=-10, 0, 0
, REULER=0, -90D, 0
MARKER/301, PART=3, QP=-10, 0, 0
, REULER=0,-90D, 0
MARKER/202, PART=2, QP=0, -10, 0
, REULER=90D, 90D, 0
MARKER/302, PART=3, QP=0,-10,0
, REULER=90D,90D,0
From JOINT statements 13 and 23, Adams Solver (C++) can determine that the first gear is Part 1 and that
it forms a revolute joint with the carrier, which is Part 3. Adams Solver (C++) can also determine that the
second gear is Part 2 and that it also forms a revolute joint with the carrier. MARKER statement 303 defines
the location of the common velocity marker.
The following figure is a schematic of a rack-and-pinion gear pair.
Rack-and-Pinion Gear Pair
GEAR 159
C++ Statements
For this gear pair, the same GEAR statement is used as the one in the previous example, but a different set of
JOINT and MARKER statements communicate characteristics of the gear to Adams Solver. Those
statements are as follows:
MARKER/303, PART=3, QP=0,0,0
JOINT/13, I=101, J=301, TRANSLATIONAL
, REULER=90D,90D,0
, REULER=90D,90D,0
In this example, JOINT statement 13 defines a translational joint rather than a revolute joint, and MARKER
statement 303, which defines the constant velocity marker, has the same position and orientation as the
ground coordinate system (GCS).
160 Adams Solver
C++ Statements
GFORCE
The GFORCE statement defines a force element that consists of three orthogonal translational force
components and three orthogonal torque components. You may define the GFORCE statement through
user-specified function expressions in the Adams Solver (C++) dataset or through user-written subroutines.
Format
Arguments
FUNCTION=USER(r1[,...,r30) Specifies up to thirty user-defined constants to compute the force

components in a user-defined subroutine GFOSUB.
FX=e Specifies the magnitude and sign of the x component of the GFORCE
translational force. Adams Solver (C++) applies this force parallel to the
x-axis of the RM marker.
FY=e Specifies the magnitude and sign of the y component of the GFORCE
y-axis of the RM marker.
FZ=e Specifies the magnitude and sign of the z component of the GFORCE
z-axis of the RM marker.
FXYZ=[e1, e2, e3] Specifies the magnitude and sign of the x, y and the z components of
the GFORCE translational force in a vector format. Adams Solver
(C++) applies these force components along the x-axis, y-axis, and z-axis
of the RM marker, respectively.
I=id Specifies the marker at which Adams Solver (C++) applies the forces and
torques. You must ensure that the I marker is a fixed marker and on a
different part than the JFLOAT marker. Because I is a fixed marker,
Adams Solver (C++) always applies the force at a fixed point on the part
containing the I marker.
GFORCE 161
C++ Statements
JFLOAT=id Specifies the marker at which Adams Solver (C++) applies the reaction
forces and torques. You must ensure that the JFLOAT marker is a
floating marker and on a different part than the I marker. Adams Solver
(C++) moves the JFLOAT marker to keep it superimposed on the I
marker, meaning that the point of application of the reaction force may
move with respect to its part. Adams Solver (C++) does not calculate
reaction forces when the JFLOAT marker is on the ground part.
RM=id Specifies the marker and therefore the coordinate system in which the
force and torque components are specified. You must ensure that RM is
a fixed marker. RM can be the same as I and can be fixed on any part in
your system.
GFOSUB.

TX=e Specifies the magnitude and sign of the x component of the GFORCE
rotational torque. Adams Solver (C++) applies this torque parallel to the
x-axis of the RM marker in the sense of the right-hand rule (that is, a
TY=e Specifies the magnitude and sign of the y component of the GFORCE
y-axis of the RM marker in the sense of the right-hand rule (that is, a
TZ=e Specifies the magnitude and sign of the z component of the GFORCE
z-axis of the RM marker in the sense of the right-hand rule (that is, a
TXYZ=[e1, e2, e3] Specifies the magnitude and sign of the x, y and the z components of
the GFORCE rotational torque in a vector format Adams Solver (C++)
applies these torque components along the x-axis, y-axis, and z-axis of
the RM marker in the sense of the right-hand rule (that is, a positive
torque causes a counterclockwise rotation).
Extended Definition
A GFORCE statement defines a force element that consists of three mutually orthogonal translational force
user-specified function expressions in the Adams Solver (C++) dataset or through user-written subroutines.
The element applies actions to the part to which the I marker belongs and corresponding reactions to the
part to which the JFLOAT marker belongs. The GFORCE statement internally establishes the position of
the JFLOAT marker. As the system moves, Adams Solver (C++) moves the JFLOAT marker on its part to
always keep the JFLOAT and I markers superimposed. Therefore, Adams Solver (C++) applies the reaction
force to the part containing the JFLOAT marker at the instantaneous position of the I marker.
162 Adams Solver
C++ Statements
The magnitude of the force depends on the expressions or subroutines you supply. You can specify these
functions with Adams Solver (C++) function expressions or user-written FORTRAN-77 subroutines.
The vector formed by the three user-defined component forces along the RM marker axes defines the
direction of the translational force action. The reaction is equal and opposite to the action.
The vector formed by the three component torques determines the direction of the rotational torque action.
You define these torques about the RM marker axes. The reaction is equal and opposite to the action.
Formulation
Action
Values
ˆ
F a = FXx rm + FYŷ rm + FZẑ rm
T a = TXx̂ rm + TYŷ rm + TZẑ rm

where:
 Fa is the translational action applied to the I marker.
 FX is the user-defined function for the x-component force magnitude.
 FY is the user-defined function for the y-component force magnitude.
 FZ is the user-defined function for the z-component force magnitude.
 Ta is the rotational action applied to the I marker.
 TX is the user-defined function for the x-component according to the right-hand rule.
 TY is the user-defined function for the y-component according to the right-hand rule.
 TZ is the user-defined function for the z-component according to the right-hand rule.
 x̂ rm is a unit vector along the + x-direction of the RM marker.

ˆ
 y rm is a unit vector along the + y-direction of the RM marker.
ˆ

z rm is a unit vector along the + z-direction of the RM marker.
Reaction
Applied to: JFLOAT marker
Values:
Fr = -Fa
Tr = -Ta
where Fr and Tr are the translational and rotational reactions applied at the JFLOAT marker, respectively.
GFORCE 163
C++ Statements
Tip: Depending on the nature of the desired force relationship, the RM marker may belong to
the same part as the I marker or JFLOAT marker, or to a third, unrelated part.
Caution: The user-defined forces FX, FY, FZ, TX, TY, and TZ should be smooth, continuous, and
single-valued. These conditions make the solution process very effective.
Examples
GFORCE/1, I=310, JFLOAT=9910, RM=310,
, FX = -20.*VX(310,9900,310)\
, FY = -20.*VY(310,9900,310)\
, FZ = -20.*VZ(310,9900,310)\
, TX = -6.*WX(310,9900,310)\
, TY = -6.*WY(310,9900,310)\
, TZ = -6.*WZ(310,9900,310)
This GFORCE statement defines a general, six-component force acting between fixed Marker 310 and
floating Marker 9910, which must belong to different parts. Expressions FX, FY, FZ, TX, TY, and TZ define
the force and torque components the x, y, and z axes of the reference marker, which is Marker 310. Adams
Solver (C++) superimposes floating Marker 9910 on Marker 310, and apply the reaction force and torque at
that point.
The above statement can also be written using FXYZ and TXYZ as
,FXYZ = [-20.*VX(310,9900,310), -20.*VY(310,9900,310), -20.*VZ(310,9900,310]\
,TXYZ = [-6.*WX(310,9900,310), -6.*WY(310,9900,310), -6.*WZ(310,9900,310)]
Applications
The GFORCE statement is most useful when you need to define a vector force and vector torque whose point
of application and/or direction is most easily formulated in a coordinate system which moves or is on a
different part than the parts containing the force application points. For example, a GFORCE statement
could be used to model the normal and friction force effects for a ball rolling down an inclined surface. See
the figure below.
Model of Ball Rolling Down Incline
164 Adams Solver
C++ Statements
For this application, the RM reference marker would be fixed to the surface and would supply the orientation
for the normal and friction forces and the torque about the ball center due to the friction.
When compared with the SFORCE (see SFORCE statement), the GFORCE statement can vary both its point
of application (with respect to the part containing the JFLOAT marker) and its resultant direction (with
respect to the RM-marker). In these cases, a single GFORCE statement can represent the complete
force/torque condition at a point along with its reaction forces, whereas it would require six translational
SFORCEs and six rotational SFORCEs, with appropriately-oriented markers, to accomplish the same thing.
GRAPHICS 165
C++ Statements
GRAPHICS
The GRAPHICS statement creates:
 Two- or three-dimensional geometry for CONTACT. You always define the geometry with respect
to a reference marker.
 Three-dimensional graphic data that represents the parts, constraints, or forces in a system.
The only graphic that can be defined on a flex body is a point.
Because there are two uses for geometry, one for contact and the second for the graphical display of objects,
we have divided the documentation into two separate sections:
 Graphics for Contact
 Graphics for Graphic Display of Objects
New types of graphics are available for representing a wide variety of geometries in contact. Adams Solver
does not write these new geometric entities (point, plane, ellipsoid, and external) to the graphics file, and
therefore, they cannot be displayed in standalone Adams Solver (C++). You can, however, view them from
Adams View.
See the Supported Geometry Combinations for CONTACT
Graphics for Contact
Format
166 Adams Solver
C++ Statements
{ } Select one item

[ ] Optionally select the item
Arguments
ARC Creates an arc. You use the following arguments to define the arc:
 CM to specify the center marker of the arc.

 RADIUS to define the radius of the arc.
 RANGLE to define the extent of the arc, with the arc always starting at the x-
axis of the CM marker.
 SEG to specify the number of line segments to use to display the arc.
BOTTOM=r Defines the bottom radius of a frustum.
BOX Creates a rectangular box. You use the following arguments to define the box:
 CORNER to specify the ID of a reference marker at one corner of the box.

 X, Y, and Z to define the extent of the box along the x-, y-, and z-axes of the
corner marker.
CID=id Specifies the identifier of the curve to be drawn.
CIRCLE Creates a circle. You use the following arguments to define the circle:
 CM to specify the center marker of the circle.

 RADIUS to specify the radius of the circle.
CM=id Defines the identifier of the marker at the center of an arc, circle, cylinder, frustum or
torus.
 For an arc, circle, or ellipsoid, the origin of the marker specifies the center.
 For a cylinder, or frustum, the origin of the marker specifies the center of the
bottom circle. The bottom circle lies in the plane contained by the x- and y-axes
of the marker. The z-axis of the marker defines the centerline axis of the
cylinder or frustum.
 For a torus, the origin of the marker specifies the center of the torus. The z-axis
of the marker defines the axis of revolution.
CRM=id Defines the reference marker with respect to which the curve data points are specified.
CORNER=id Defines a reference marker, which is at a corner of the box that is being created.
CURVE Creates a curve graphic based on a CURVE statement. You define the curve data with
respect to a reference marker (CRM). The CONTACT and CVCV modeling entities
require that the curve be planar. It must be in the plane defined by the x- and y-axes of
the RM marker, and must contain the origin of the marker.
GRAPHICS 167
C++ Statements
CYLINDER Creates a cylinder whose top and bottom are perpendicular to the cylinder central axis.
You use the following arguments to define the cylinder:
 CM to specify the center marker (CM) of the cylinder. The z-axis of the CM
marker defines the axis of the cylinder.
 RADIUS to define the radius of the cylinder.
 RANGLE to define the angular extent of the cylinder, with the arc always
starting at the x-axis of the CM marker.
 LENGTH to define the height of the cylinder.
ELEMENT = geometry_name Used with external geometry.
Specifies the name of a geometric entity in a file that FILE identifies. The file can
contain multiple geometries. You use ELEMENT to select a particular geometry from
the file even when it contains just one geometry. You will need additional GRAPHICS
statements if you want to read multiple geometries from the same file.
ELLIPSOID Creates an ellipsoid. You use the following arguments to define the ellipsoid:
 CM to specify the center marker (CM) of the ellipsoid.

 XSCALE, YSCALE, and ZSCALE to specify the diameters along the x-, y-, and
z-axes of the CM marker. If the argument values are all equal (XSCALE =
YSCALE = ZSCALE), then Adams Solver (C++) creates a sphere.
EXTERNAL Specifies that a three-dimensional solid geometry is to be created. The data for the
geometries is in an external file that the geometry engine of Adams Solver (C++) can
read. It use the following arguments to define the geometry:
 RM to specify the marker that defines the reference coordinate system.

 FILE identifies the file to be read. This file is commonly generated by the
geometry engine being used.
 ELEMENT to specify the name of a geometric entity in a file that FILE
identifies.
Adams Solver (C++) uses the geometry package Parasolid 14.0 to understand geometry.
Parasolid input files have the extension .xmt_txt and .xmt_bin. Both are supported,
however, .xmt_bin files are not portable across platforms.
Parasolid can read in the geometry data and tell Adams Solver (C++):
 Whether or not two geometries are in contact.

 Where the contact points are located on each geometry.
 The outward normals at the calculated contact points.
168 Adams Solver
C++ Statements
FACETING_TOLERANCE Specifies the faceting tolerance for this geometry. The faceting tolerance is applied only
to EXTERNAL geometry read from a Parasolid file. It is ignored for all other geometry
types. The faceting tolerance is used to mesh geometry for CONTACT. It is not used
for any other purpose.
The default value is 300.0028. However, if this tolerance is not set and
CONTACT_FACETING_TOLERANCE in the PREFERENCES statement or
command is set, then the PREFERENCES tolerance will be used for this geometry.
If this tolerance and the PREFERENCES tolerance are both set, then this tolerance will
be used for this geometry only.
If this tolerance is not set and the PREFERENCES tolerance is not set, then a faceting
tolerance of 300.0028 will be used for all Parasolid geometry.
See CONTACT_FACETING_TOLERANCE in the PREFERENCES statement or

command for more information.
EXTRUSION Creates an extrusion graphic. You use following arguments to specify an extrusion:
 CRM to specify the id of the reference marker for the extrusion.

 GID to specify the id of the closed curve or circle graphic to be extruded.
 PID to specify the id of the curve, arc, or circle graphic to extrude along.
FILE=file_name Specifies the name of a file containing one or more geometric entities. Adams Solver
(C++) can only read Parasolid files. Parasolids is an exact boundary representation (b-
rep) geometric modeler. This means that it represents solids (and other types of
geometry) by their boundaries. Other file formats (such as shell files) must be converted
to a boundary representation externally before the Adams Solver (C++) Parasolid
geometry engine can use them.
FRUSTUM Creates a frustum of a cone whose top and bottom are perpendicular to the cone central
axis. You use the following arguments to define the frustum:
 CM to specify the center marker (CM) of the frustum. The z-axis of the CM
marker defines the axis of the frustum.
 TOP and BOTTOM to define its top and bottom radii, respectively.
 RANGLE to define the angular extent of the frustum, with the arc always
 RADIUS to define the radius of the frustum cone.
 LENGTH to specify the height of the frustum.
GID=id Defines the id of the closed curve or circle graphic to be revolved or extruded.
GRAPHICS 169
C++ Statements
LENGTH=r Defines the height for either a cylinder or frustum. The two circles at the ends of a
cylinder or frustum are both perpendicular to the z-axis of the CM marker. Therefore,
the circles are parallel. Adams Solver (C++) uses the value of LENGTH to specify the z
distance between the two circles. There is no limit on the value of r. A positive value
specifies a cylinder or frustum along the positive z-axis of the CM marker, and a negative
value specifies a cylinder or frustum along the negative z-axis of the CM marker.
MAJOR_RADIUS Specifies the larger radius of the torus.
MINOR_RADIUS Specifies the smaller radius of the torus.
NODE_LABELS = id1 [, Specifies the list of nodes where this SECTION is to be drawn.
id2…]
ALPHAS = r1 [, r2, …, rn] Specifies a list of non dimensional arc length values where the section is to be drawn.
CID = id Specifies the identifier of the CURVE statement with coordinates defining this cross
section. The coordinates of the CURVE resolve to each nodal coordinate frame for the
nodes specified in the NODES option.
COORDINATES=y1, z1, …, Specifies the (y,z) coordinates of the cross sectional geometry of the beam.
yn, zn
PID Defines the id of the curve, arc, or circle graphic to extrude along.
PLANE Creates a finite plane. You use the following arguments to create a plane:
 RM to specify a reference coordinate system for the plane. The plane lies in the
x-y plane of the RM marker (that is, the z-axis of the RM marker is normal to
the plane).
 XMIN, XMAX, YMIN, and YMAX to specify the extent of the plane.
The plane is a two-dimensional element, and, therefore, you can only use it when
defining contact with another two-dimensional element (point, arc, circle, curve).
POINT Creates a graphic point at the origin of the RM marker.
RADIUS=r Defines the radius of a circle, arc, cylinder, or frustrum.
Range: Radius > 0

RANGLE=r Defines an angle measured positive (according to the right-hand rule) about the z-axis
of the CM marker. Adams Solver (C++) assumes RANGLE is in radians. The angle starts
at the positive x-axis of the CM marker and subtends the arc, the arc of the cylinder, or
the arc of the cone frustum.
Range: -2 π < RANGLE < 2 π

REVOLUTION Creates a revolution graphic. You use following arguments to define a revolution:
 CRM to specify the id of the marker that defines the center of revolution. The z-axis
of the CRM marker is the axis of revolution.
 GID to specify the id of the closed curve or circle graphic to be revolved.
170 Adams Solver
C++ Statements
RM=id Identifies the marker that defines the reference coordinate system for a point, plane, or
external geometric entity. Adams Solver (C++) defines the geometries in this coordinate
system.
TOP=r Defines the radius at the top of a frustum. The top is perpendicular to the CM marker
z-axis, and the center of the top is at the position on the CM marker z-axis that
LENGTH specifies. There is no limit on the value of r.
TORUS Creates a torus graphic. You use the following arguments to create a torus:
 CM to specify the id of the marker that defines the center of the torus. The z-axis of
the CM marker is the axis of revolution.
 MINOR_RADIUS to specify the smaller radius of the torus.
 MAJOR_RADIUS to specify the larger radius of the torus.
X=x, Y=y, Z=z Locates the vertex of the box that is diagonally opposite from the corner that the
argument CORNER defines. You must specify the values of X, Y, and Z with respect to
the marker coordinate system.
XMIN=r, XMAX = y, YMIN = Specifies the boundary edges of a plane. XMIN, XMAX, YMIN, and YMAX are relative
r, YMAX = r to the CM marker of the plane.
Range: XMIN < XMAX

YMIN < YMAX
XCALE = r, YSCALE = r, Specifies the diameters along the x-, y-, and z-axes of an ellipsoid.
ZSCALE = r
Range: XSCALE > 0
YSCALE > 0
ZSCALE > 0
Examples for Content

GRAPHICS/0202, CYLINDER, CM=0201, RADIUS=2
, LENGTH=-2
This GRAPHICS statement creates a cylinder with its base at Marker 0201. Marker 0201 is located at the
center of the circular cross-section, which has a radius of two. The cylinder has a length of two along the
negative z-axis of Marker 0201.
GRAPHICS/1297, EXTERNAL, RM=7921,
, FILE = GenevaWheel.xmt_txt
, ELEMENT = Geneva
This GRAPHICS statement creates a three-dimensional solid element. The data for this solid element is
contained in a Parasolid file, GenevaWheel.xmt_txt. Within this file, which contains several geometric
entities, the solid with a tag, Geneva, is to be extracted. The solid definition is specified with respect to Marker
7921.
The geometry associated with GenevaWheel.xmt_txt is shown next.
Geometry in Parasolid File GenevaWheel.xmt_txt
GRAPHICS 171
C++ Statements
172 Adams Solver
C++ Statements
Graphics for Graphic Display of Objects
Format
 OUTLINE = id1[,..., id2500] 

 
 BOX, CORNER = id, X = x, Y = y, Z = z 
 
 CIRCLE, CM = id {,RADIUS = r, RM = id} [ ,SEG = i ] 
 
 ARC, CM = id, RANGLE = r {,RADIUS = r, RM = id} [ ,SEG = i ] 
 
 CYLINDER, CM = id [ ,RANGLE = r], LENGTH = r [ ,SIDES = i] { ,RADIUS = r, RM = id} [ ,SEG = i ] 
 
 
 FRUSTUM, CM = id [ ,RANGLE = r], LENGTH = r [ ,SIDES = i] ,TOP = r, BOTTOM = r [ ,SEG = i ] 
 
 , DA = r, COILS = i 
 
 SPDP, I = id, J = id , DB = r, LA = r, LC = r 
 
 , DC = r, LB = r, LD= r 
 
  ETYPE = ALL, EMARKER = id  
   
  BEAM  
     
   BUSHING   
     
   FIELD   
GRAPHICS/id,      
   SFORCE   
   SPDP   
     
   VFORCE   
 FORCE,     
  ETYPE=  VTORQUE , EID= id, EMARKER = id  
     
   GFORCE   
   NFORCE   
     
   JOINT   
     
   JPRIM   
     
   PTCV   
   CVCV   
   
 
 CURVE, CID= id, CRM = id1 [ , ... , idn] [ , SEG = i ] 
 
 EXTRUSION, CRM = id, GID = id, PID = id 
 
 REVOLUTION, CRM = id, GID = id 
 
 TORUS, CM = id, MINOR_RADIUS = r, MAJOR_RADIUS = r [ ,SIDES = i ] [ ,SEG = i ] [ ,RANGLE = r ] 
 
{ } Select one item

GRAPHICS 173
C++ Statements
Arguments
ARC Creates an arc.

BOTTOM=r Defines the bottom radius of a frustum of a cone. The bottom is perpendicular to the
center marker z-axis, and the center of the bottom is at the center marker origin. There
is no limit on the value of r.
BOX Creates a box with parallel edges and orthogonal vertices.
CID=id Specifies the identifier of the CURVE statement to be drawn. Adams Solver (C++)
generates a curve graphic in each marker reference frame you specify with CRM.
CIRCLE Creates a circle.
CM=id Defines the identifier of the marker at the center of an arc, circle, cylinder, frustum, or
torus. If you are creating a circle or arc, orient the CM marker so that its z-axis is normal
to the plane of the circle or plane of the arc. Similarly, if you are defining a cylinder or
frustum, orient the CM marker so that its z-axis is normal to the bottom plane of the
cylinder or the frustum. For the torus the z-axis should be the axis of the revolution.
COILS Defines the number of coils in the spring of a spring-damper (SPDP) graphic.
Default: 0
Range: 99,999 > COILS > 0

CORNER=id Defines a reference marker at a corner of the box to be created.
CRM=id Specifies a list of up to 2,500 markers at which to draw the curve identified by CID.
1[,...,idn] Adams Solver generates a curve graphic in each marker reference frame specified.
CURVE Creates a curve graphic based on a CURVE statement.
CYLINDER Creates a cylinder whose top and bottom are perpendicular to the cylinder central axis.
DA=r Defines the diameter of the spring in a spring-damper (see the spring-damper figure
below). There is no limit on the value of r.
Default: 0
DB=r Defines the diameter of the damper in a spring-damper at the I marker (see the spring-
damper figure below). There is no limit on the value of r.
Default: 0
DC=r Defines the diameter of the damper in a spring-damper at the J marker (see the spring-
damper figure below). There is no limit on the value of r.
Default: 0
174 Adams Solver
C++ Statements
Spring-Damper
EID=id Specifies the identifier of the element whose force is to be displayed by the FORCE
graphic. You can not specify EID if ETYPE=ALL.
EMARKER=id Specifies the identifier of the marker where Adams Solver displays the force graphic. If
ETYPE=ALL, marker EMARKER must have at least one force applied to it. If you
enter a specific force type, and identifier EID, marker EMARKER must be one of the
markers upon which the specified force acts.
ETYPE = {ALL, Specifies the element type for which Adams Solver generates force graphics. In
BEAM, combination with EID, ETYPE specifies one force statement. If ETYPE=ALL, then
BUSHING, Adams Solver sums all forces applied to the EMARKER.
FIELD,
SFORCE, SPDP,
VFORCE,
VTORQUE,
GFORCE,
NFORCE,
JOINT, JPRIM,
PTCV, CVCV}

FORCE Creates an arrow whose direction is identical to the direction of a force and whose
length is proportional to the magnitude of a force.
FRUSTUM Creates a frustum of a cone whose top and bottom are perpendicular to the cone central
axis.
GRAPHICS 175
C++ Statements
GID Specifies the id of the closed curve or circle graphic to extruded or revolved.
I=id, J=id Defines the I and J markers for creating a spring-damper graphic. The I and J markers
define the attachment points of the spring-damper.
LA=r Defines the distance between the I marker and the end of the damper to which it is
closest (see the Spring-Damper figure). There is no limit on the value of r.
Default: 0
LB=r Defines the distance between the J marker and the end of the damper to which it is
closest (see the spring-damper figure). There is no limit on the value of r.
Default: 0
LC=r Defines the height of the damper at I. Adams Solver measures the height from the
bottom of the damper to its top along the line segment between the I and J marker.
There is no limit on the value of r.
Default: 0
LD=r Defines the height of the damper at J. Adams Solver measures the height from the
Default: 0
LENGTH=r Defines the height for either a cylinder or frustum. Because the two circles at the ends
of a cylinder or frustum are both perpendicular to the z-axis of the CM marker, they
are parallel. Adams Solver (C++) uses the value of LENGTH to specify the z distance
between the two circles. There is no limit on the value of r. A positive value specifies a
cylinder or frustum along the positive z-axis of the CM marker, and a negative value
specifies a cylinder or frustum along the negative z-axis of the CM marker.
MAJOR_RADIU Defines the larger radius of the torus.
S
MINOR_RADI Defines the smaller radius of the torus.
US
OUTLINE=id1[, Creates visible and invisible line segments to connect at least two and not more than
...,id2500] 2,500 markers. The values id 1[,...,id 2500] are marker identifiers. They define an
outline of line segments that Adams Solver (C++) draws from one marker to the next.
A comma (,) between two marker identifiers causes Adams Solver (C++) to draw a line
segment between two markers. A comma and minus sign (,-) between two marker
identifiers causes Adams Solver (C++) to draw an invisible line from the first marker to
the second.
PID Specifies the id of the curve, arc, or circle graphic to extrude along.
RADIUS=r Defines the radius of a circle, arc, or cylinder. There is no limit on the value of r.
176 Adams Solver
C++ Statements
RANGLE=r Defines an angle measured positive (according to the right-hand rule) about the z-axis
of the CM. Adams Solver (C++) assumes RANGLE is in radians. The angle starts at the
positive x-axis of the CM marker and subtends the arc, the arc of the cylinder, or the
arc of the cone frustum, or the arc of the Torus. Adams Solver (C++) clips to -2 π values
of r less than -2 π and clips to 2 π values of r greater than 2 π .
Range: 2 π > r > -2 π
 CRM to specify the id of the marker that defines the center of revolution. The z-
axis of the CRM marker is the axis of revolution.
RM=id Defines the radius of a circle, arc, or cylinder. Adams Solver (C++) measures the
distance from the CM marker to the RM marker to determine the radius.
SEG=i Defines the number of straight line segments Adams Solver uses to draw a curve, circle,
an arc, or the two circles at the ends of a cylinder or a frustum, or the arc of the Torus.
Default: 20
Range: 99,999 > SEG >0
SIDES=i Defines the number of straight line segments Adams Solver draws between the two
parallel circles of a cylinder or a frustum, or the arc of the Torus.
Default: 20
Range: 99,999 > SIDES > 0
SPDP Draws a spring-damper graphic representation (see the spring-damper figure). For
SPDP, use I and J. To draw just the spring, use DA and COILS. To draw just the
damper at the I marker, use DB, LA, and LC. To draw just the damper at the J marker,
use DC, LB, and LD. To draw the entire spring-damper, use all of the arguments for
SPDP. DA, DB, DC, LA, LB, LC, LD, and COILS are all optional, but Adams Solver
cannot draw anything unless you include (at a minimum) the arguments for the spring
or one of the dampers.
TOP=r Defines the radius at the top of a frustum. The top is perpendicular to the CM marker
z-axis, and the center of the top is at the position on the CM marker z-axis that
LENGTH specifies. There is no limit on the value of r.
 CM to specify the id of the marker that defines the center of the torus. The z-axis of
the CM marker is the axis of revolution.
X=x,Y=y,Z=z Locates the vertex of the box that is diagonally opposite from the corner defined by
CORNER. The values of X, Y, and Z must be specified with respect to the marker
coordinate system.
GRAPHICS 177
C++ Statements
Extended Definition
The GRAPHICS statement creates three-dimensional graphic data for display on a graphics device. You can
use it to create line segments, boxes, curves, circles, arcs, cylinders, frustums of cones, and spring-dampers.
Combinations of these images are attached to parts (including ground) to approximate their appearance.
These images move with their respective parts to produce a graphic simulation of the mechanism behavior.
You can also use the GRAPHICS statement to create force vectors so that the forces in the system can be
displayed.
Examples for Graphic Display of Objects
negative z-axis of Marker 0201. Twenty sides define the body of the cylinder, and the circles at the top and
at the bottom of the cylinder are actually twenty-sided polygons.
GRAPHICS/0001, OUTLINE=1001,1002,-1003,1004
This GRAPHICS statement creates a line from Marker 1001 to Marker 1002 and creates a line from Marker
1003 to Marker 1004. Because a minus sign (-) precedes Marker 1003, the statement creates an invisible line
segment from Marker 1002 to Marker 1003.
See other Geometry statement available.
178 Adams Solver
C++ Statements
GSE
The GSE (General State Equation) statement lets you represent a subsystem that has arrays of input variables
(u), internal continuous states (xc), internal discrete states (xd), and output variables (y).
The GSE is represented mathematically in one of two ways. The first is described by Equations (1), (2), and
(3) below. It is for systems in which the time derivative of the continuous states can be written explicitly, and
it is thus known as an explicit GSE:
·
x c = f c ( x c, u, t ) x c ( t 0 ) = x c0 (1)
x d ( n + 1 ) = f d ( x d ( n ), u, t n ) x d ( t 0 ) = x d0 (2)
y = g ( x c, x d, u, t ) (3)
This is the default form. This is also the only form available for Adams Solver (C++) versions prior to Adams
Solver version 2005r2 (and for any version of Adams Solver (FORTRAN)). The states xc are defined in
Equation (1) as explicit, first-order, ordinary differential equations. The function fc(xc, u, t) is specified in a
user-written subroutine, and is assumed to be continuous everywhere. (The names of this and other user-
written subroutines are specified by the user via the ROUTINE or INTERFACE attributes of the GSE
statement.) Integrators in Adams Solver (C++) evaluate fc(xc, u, t) as needed.
The states xd are defined in Equation (2) by the function fd(xd(n), u, tn). This function is specified in a second
user-written subroutine. Equation (2) is a difference equation. A sampling period is associated with Equation
(2), and integrators only evaluate Equation (2) at the sample times. The states xd are assumed to be constant
between sampling periods. In Equation (2), xd(n) is the short form for xd(tn).
The outputs y are defined in Equation (3) by g(xc, xd, u, t), and are sampled continuously. This function is
specified in a third user-written subroutine. It may be discontinuous in nature. If the outputs are to be fed
back into the mechanical system through a force element, then it is customary to eliminate the discontinuities
in y by passing the appropriate output variables through a low-pass filter before feeding those signals into the
force element. You can use the TFSISO element to define a low-pass filter. Failure to eliminate discontinuities
in y is likely to cause significant numerical-integration difficulties.
The second way (mentioned above) of representing a GSE mathematically is described by replacing Equation
(1) above with (4) below:
·
0 = f c ( x c, x c, u, t ) x c ( t 0 ) = x c0 (4)
This representation permits the modeling of implicitly-defined states – a more general capability than what
is possible with the default representation of Equation (1). This representation is thus known as an implicit
GSE, and its use requires the inclusion of the IMPLICIT attribute of the GSE statement. Equations (2) and
(3) are the same for explicit and implicit GSEs.
Note that the use (that is, interface) of the implicit form is more restricted than in the default case.
Specifically, you must call the Array query utility subroutines: GSE_X, GSE_XDOT, GSE_XD, GSE_U() to obtain the
values of x· c, x c, x d, and u respectively, because the SYSARY subroutine does not support access to this
GSE 179
C++ Statements
data. As well, the Partial derivative entry utility subroutines: GSEPAR_X, GSEPAR_XDOT, GSEPAR_U must be called to
·
supply the integrator with the partials of f c ( x c, x c, u, t ) with respect to x· c, x c, and u , respectively.
If Equation (1) or (4) is not present, the GSE is classified as a purely discrete GSE. If Equation (2) is not present,
the GSE is classified as being purely continuous. If both Equations 1(or 4) and 2 are present, the GSE is
classified as a sampled system. When neither Equations 1( or 4) nor 2 are present, the GSE does not contain
any internal states.
Format
180 Adams Solver
C++ Statements
Arguments
FUNCTION=USER(r1[,...,r30]) Specifies the parameters that are to be passed to the user-written

subroutines that define the constitutive equations of a GSE.
Two user subroutines are associated with a GSE.
 GSE_DERIV is called to evaluate f() in Equation (1) (or F() in

Equation (4) if IMPLICIT).
 GSE_OUTPUT is called to evaluate g() in Equation (3).
IC=id Identifies the ARRAY statement in the dataset that specifies the initial
conditions for the states in the system.
This is an optional argument. When you use the IC argument, an

ARRAY statement with this identifier must be in the dataset, it must
be of the IC type, and it must have the number of elements specified
in the argument NS.
When you do not specify an IC array for a GSE statement, all the
states are initialized to zero.
IMPLICIT Specifies that the constitutive equation governing the states is
implicitly defined and takes the form given in Equation (4).
Note that the use of this attribute mandates that the GSE_XDOT and
GSEPAR_XDOT utility subroutines get called by the user to obtain
and supply required information.
In the default case, when the IMPLICIT attribute is not present, the
equation governing the states must be explicit in state-space form as
given by Equation (1) (and the user is permitted to use any of the
available utility subroutines).
INTERFACE= Specifies an alternative library and subroutine names for the user
lib1::gse_deriv, subroutines GSE_DERIV, GSE_OUTPUT, GSE_UPDATE, GSE_SAMP,
lib2::gse_output, GSE_SET_NS, GSE_SET_ND, GSE_SET_IMPLICIT, GSE_SET_STATIC_HOLD,
lib3::gse_update, lib4::gse_samp, GSE_SET_SAMPLE_OFFSET respectively. The rules for the INTERFACE
lib5::gse_set_ns, lib6::gse_set_nd, argument are the same as for the ROUTINE argument.
lib7::gse_set_implicit,
lib8::gse_set_static_hold, Learn more about the ROUTINE Argument.
lib9::gse_set_sample_offset
ND=i Specifies the number of discrete states in the GSE. Discrete states are
updated by calling the function GSE_UPDATE at the sample times.
ND defaults to zero when not specified.
GSE 181
C++ Statements
NO=i A mandatory argument, NO, specifies the number of output

equations (algebraic variables) that are used in the definition of
Equation 2. If NO is greater than 0, you must also specify a Y array.
GSE outputs are evaluated by calling the user written subroutine
GSE_OUTPUT.
NS=i Specifies number of states in the GSE and is used in the definition of
Equation (1) (or Equation (4) if IMPLICIT). The time derivatives of the
states of a GSE are evaluated by calling the user-written subroutine
GSE_DERIV. NS defaults to zero when not specified.
ROUTINE=lib1::gse1, lib2::gse2, Specifies alternative library and subroutine names for the deprecated
lib3::gse3, lib4::gse4, lib5::gse5 user subroutines GSESUB, GSEXX, GSEXU, GSEYX, GSEYU
respectively.
SAMPLE_OFFSET=r Specifies the simulation time at which the sampling of the discrete
states is to start. All discrete states before SAMPLE_OFFSET are
defined to be at the initial condition specified. SAMPLE_OFFSET
defaults to zero when not specified.
SAMPLE_PERIOD=expression Specifies the sampling period associated with the discrete states of a
GSE. This tells Adams Solver (C++) to control its step size so that the
discrete states of the GSE are updated at:
last_sample_time + sample_period
In cases where an expression for SAMPLE_PERIOD is difficult to

write, you can specify it in a user-written subroutine GSE_SAMP(…).
Adams Solver (C++) will call this function at each sample time to find
out the next sample period.
STATIC_HOLD Indicates that the continuous GSE states are not permitted to change
during static and quasi-static simulations.
U=id Designates the ARRAY statement in the dataset that is used to define
the input variables for the GSE. The U argument is optional. When it
is not present in the GSE statement, there are no system inputs. When
you use the U argument an ARRAY with this identifier must be in the
dataset. The number of inputs to the GSE statement is inferred from
the number of VARIABLE statements in the U array.
X=id Designates the ARRAY statement in the dataset that is used to define
the states for the GSE. When you specify it, an ARRAY statement with
this identifier must be in the dataset, it must be of the X type, and it
may not be used in any other LSE, GSE, or TFSISO statement. If you
specify SIZE on the ARRAY statement, it must have the same value as
the argument NS.
182 Adams Solver
C++ Statements
Y=id Designates the ARRAY statement in the dataset that is used to define
the output variables for the GSE. The Y argument is optional, but it
must be provided if the argument NO is greater than zero. When it is
not present in the GSE statement (and NO=0), there are no system
outputs. When you use the Y argument, an ARRAY with this identifier
must be in the dataset. If you specify SIZE on the ARRAY statement,
it must have the same value as the argument NO.
XD=id Designates the ARRAY statement in the dataset that is used to access
the discrete states for the GSE. An ARRAY statement with this
identifier must be in the dataset, it must be of the X type, and it may
not be used in any other LSE, GSE, or TFSISO statement. If you
the argument ND.
STATICS_ONLY When included (or set to On) will only activate GSE for statics.
During dynamics the GSE will be inactive if set, and this should speed
up the Solver solution during dynamics since less number of states are
being solved.
Extended Definition
The GSE (General State Equation) statement defines the equations for modeling a nonlinear, time varying,
dynamic system. The statement is especially useful for importing nonlinear control laws developed manually
or with an independent software package. It can also be used to define an arbitrary system of coupled
differential and algebraic equations:
The GSE allows you to implement four different kinds of systems. These are:
 Continuous Systems
 Discrete Systems
 Sampled Systems
 Feed-Forward Only System
 Integrator step size selection
Continuous Systems
Continuous systems can be represented either explicitly or implicitly. The explicit case is written in state-
space form as:
·
x c = f c ( x c, u, t ) x c ( t 0 ) = x c0 (5)
y = g (x c,u ,t) (6)
where xc is called the state of the system, and contains n elements for an nth-order system. In matrix notation,
xc is a column matrix of dimension n x 1. u defines the inputs to the system. Its size is equal to the number
of inputs to the system being modeled. In this description, the system is assumed to have m inputs,
GSE 183
C++ Statements
consequently u is a column matrix of size m x 1. y defines the outputs from the system. If a system has p
outputs, y is represented with a column matrix of dimension p x 1.
Using this system description, a nonlinear, second-order differential equation, with a single input u, such as:
·· 2
y + 2ζω n yy· + ω n y = Ku (7)
can be written in a state-space form as:
   
 x· 1   x2 
  =   (8)
 x· 2   – 2ζω n x 1 x 2 – ω 2n x 1 + Ku 
   
y = x1 (9)
The system state Equation (8) is integrated by Adams Solver using its integrators. Therefore, it is necessary
that the functional relationship expressed in Equation (8) be continuous. This necessity is a minimum
requirement for successfully integrating these equations. Similarly, if the output is to be fed back into a plant
model, such as a mechanical system, Equation (9) is also required to be continuous. A higher degree of
differentiability will help the integrators solve these equations more efficiently.
When the IMPLICIT attribute is present, the governing equations take the form of:
·
0 = f c ( x c, x c, u, t ) x c ( t 0 ) = x c0 (10)
y = g ( x c ,u ,t ) (11)
where all of the variables are defined equivalently to the explicit case above. The continuity requirements
apply as well. For the implicit case, Equations (8) would be rewritten as:
x· 1 – x 2 0
· 2
= (12)
x 2 + 2ζω n x 1 x 2 + ω n x 1 – Ku 0
The major advantage of the implicit representation is that a more general set of equations can be solved
·
because the dependence on the x c terms can be nonlinear. A second advantage is that derivation of the state
equations for a dynamical system in implicit rather than explicit form is usually easier, and the required partial
derivatives of the state equations are usually much simpler expressions.
Discrete Systems
Discrete systems can be described by their difference equations. They are, therefore, represented in state-space
form as:
184 Adams Solver
C++ Statements
y = g ( x d ,u ,t ) (14)
xd is called the state of the system, and contains n elements for an nth-order system. In matrix notation, xd is
a column matrix of dimension n x 1. u and y have the same meaning as for continuous systems.
The fundamental difference between continuous and discrete systems is that the discrete or digital system
operates on samples of the sensed plant data, rather than on the continuous signal. The dynamics of the
controller are represented by recursive algebraic equations, known as difference equations, that have the form
of Equation (13).
The sampling of any signal occurs repetitively at instants in time that are τ seconds apart. τ is called the
sampling period of the controller. In complex systems, the sampling period is not a constant, but is, instead,
a function of time and the instantaneous state of the controller. The signal being sampled is usually
maintained at the sampled value in between sampling instances. This is called zero-order-hold. Determining
an appropriate sampling period is a crucial design decision for discrete and sampled systems.
One major problem to avoid with sampling is aliasing. This is a phenomenon where a signal at a frequency
ω 0 produces a component at a different frequency ω 1 only because the sampling occurs too infrequently.
The general rule of thumb for such situations is as follows:
If you want to avoid aliasing in a signal with a maximum frequency of ω , the sampling frequency ( ω s )
is calculated from ω s ≥ 2ω . This is an extreme lower limit for ω . If you want to obtain a reasonably
ωs
smooth time response, then choose ω such that 20 < ------ < 40 .
ω
The sampling rate for sampling the states of a discrete system must follow the above criterion to avoid aliasing.
Note that when an Adams Solver output time and a GSE sample time coincide, the output of the GSE at that
time will be calculated using the values of the discrete states before the update takes place. This is true for
discrete states in discrete systems and sampled systems.
Sampled Systems
There are many systems that are neither continuous nor discrete. Some signals are sampled at discrete
intervals, while others are sampled continuously. These systems are called sampled systems and are
represented in state-space form as:
·
x c = f c ( x c, u, t ) x c ( t 0 ) = x c0 (15)
·
0 = f c ( x c, x c, u, t ) x c ( t 0 ) = x c0 (16)
y = g ( x c, x d, u, t ) (18)
where either the explicit form (15) or implicit form (16) is chosen for the representation.
GSE 185
C++ Statements
Equation (15) or (16) represents the dynamics associated with the continuous portion of the sampled system.
Equation (17) represents the dynamics associated with the discrete portion of the sampled system. The
equations are evaluated only at discrete points in time: the sample times for the sampled system. In between
sample times, the discrete states are assumed to be constant.
Equation (18) defines the outputs of the system. It is important to note that the Adams integrators evaluate
Equation (18) as often as necessary. In many problems, it is required to examine the output between sampling
instants. Often, for example, the maximum overshoot may occur not at a sampling instant, but between
sampling instants. This implementation allows for such observations to be made on the output.
Feed-Forward Only System
Feed-Forward Only Systems are systems that have no internal states. The output of the system is an algebraic
function of the inputs. They can be represented as:
y = g (u,t) (19)
Integrator step size selection

When discrete GSE elements are included in a model, the integrators (GSTIFF, HHT and so on.) will select
the next time step taking into account the sample period of each GSE in the model. The process is as follows,
first the integrator will compute and propose a time step using its standard approach. Next the proposed time
step will be compared with all of the sample periods proposed by the GSE elements in the model. Finally, the
integrator will compute the step size making sure the system will not step beyond the sample period of any
GSE. In a case of the constant sample period, the sample period of each discrete GSE in the model should be
chosen such that the output step size (DTOUT) is an integer multiple of the sample period for optimal solver
performance. In a case of multiple discrete GSEs with constant sample periods, the sample periods should be
selected as the integer multiples of each other. Please note that these recommendations are made for optimal
solver performance only. The integrators will honor any sample period set by the user.
186 Adams Solver
C++ Statements
Caution:  The GSE statement provides a very general capability for modeling nonlinear systems.
However, the routines for solving the linear equations in Adams Solver (C++) have been
developed and refined to work particularly well with the sparse systems of equations that
come from the assembly of mechanical models. With the GSE statement, you can create
very dense sets of equations. If these equations form a large portion of the completed
model, Adams Solver (C++) may perform more slowly than expected.
 To improve the performance of Adams Solver (C++), any arrays of partial derivatives which
are not full can be represented in sparse form. This sparse form can substantially reduce the
effort required by the integrator. To represent the partials in sparse form, use the
GSEMAP_* utility subroutines, when calling GSE_DERIV with IFLAG=1, to define the
sparsity. Then, use the GSEPAR_* utility subroutines to pass the sparse partial arrays to
the integrator.
and force variables. This changes the initial conditions for a subsequent analysis. If
STATIC_HOLD is not specified, during a static analysis, Adams Solver (C++) sets the
time derivatives of the user-defined variables to zero, and uses the user-supplied initial-
However, the user-specified initial conditions are retained as the static equilibrium values
when STATIC_HOLD is specified. Thus, the final equilibrium values are the same as the
user-specified initial conditions. Note that this does not guarantee that the time derivatives
of the user-defined variable are zero after static analysis.
Examples
Modeling Control Systems
The example below demonstrates how you can use a GSE to define a controller in Adams. The plant consists
of a block on a translational joint. A control force is to be applied to the block so that it translates exactly 150
mm from its initial position. The control system is defined as follows.
Inputs
 The first input (u1) is the location of the block.
 The second input (u2) is the velocity of the block.
Outputs
 The output is an actuator signal.
States
 The controller is a linear PID controller.
GSE 187
C++ Statements
 It has two continuous states (x1 and x2).

Transfer Functions
The transfer functions of the controller are:
Y ( s )- – 2e7 Y ( s ) - --------------------------------------
– 1e3s – 1e7 -
------------- = --------------------------------------
-, --------------- =
U1 ( s ) 2
s + 2e3s + 1e7 U 2 ( s ) s 2 + 2e3s + 1e7
A GSE represents the controller. Standard Adams modeling elements PART, JOINT, and SFORCE represent
the block, translational joint, and the actuator, respectively.
Model Input File
GSE Test: Continuous states=2, Discrete states=0, Outputs=1
units/force=newton, mass=kilogram, length=millimeter, time = second
part/1, ground
marker/3, part = 1, reuler = 90d, 90d, 0d
marker/5, part = 1, qp = -150, 0, 0, reuler = 90d, 90d, 0d
part/2, qg = 0, 0, -100, mass = 46, cm = 6, ip = 2e5, 5e5, 4e5
marker/2, part = 2, qp = 0, 0, 100, reuler = 90d, 90d, 0d
marker/6, part = 2, qp = 0, 0, 100
marker/7, part = 2, qp = -150, 0, 100
joint/1, trans, i = 2, j = 3
sforce/1, trans, i = 4, j = 5, actiononly, function = aryval(2,1)
variable/2, function = dx(7)
variable/3, function = vx(7)
array/1, u, size = 2, variables = 2, 3 !Inputs for the GSE
array/2, y, size = 1 !Outputs for the GSE
array/3, x, size = 2 !States for the GSE
gse/99, ns = 2, no = 1, x = 3, u = 1, y = 2, function = user(3,1)
accgrav/jgrav = -9806.65
results/formatted
END
Simulation Results
The figure below shows the time history of the location and velocity of the block. Notice the displacement
(red curve) starts at 0 mm, and stops moving when it reaches a value of 150 mm. Notice also the overshoot
in the displacement of the block, which is subsequently corrected by the controller.
Time History of the Block Location
188 Adams Solver
C++ Statements
The next figure shows the time history of the actuator signal computed by the controller. This is the force
applied on the block. Notice that the actuator signal changes sign when the block is about to overshoot its
target value.
Time History of Actuator Signal Output by the Controller
GSE 189
C++ Statements
User-Written Subroutines for the controller modeled by GSE

SUBROUTINE GSE_DERIV(ID, TIME, PAR, NPAR, DFLAG, IFLAG, NS, XDOT)
C
C Inputs:
C
INTEGER ID, NPAR, NS
DOUBLE PRECISION PAR(*), TIME
LOGICAL IFLAG, DFLAG
C
C Outputs:
C DOUBLE PRECISION XDOT(*)
C
C Local Variables:
C
LOGICAL LEFLAG, PARFLG
INTEGER AX(1), AU(1), NSS, NU
DOUBLE PRECISION A(2,2), B(2,2), X(2), U(2)
SAVE A, B
DATA A /-1.0e3, 0.0, -2.0e4, -1.0e3/
DATA B /0.0, 1.0, -1.0, 0.0/
C
C+-----------------------------------------------------------------*
C
C Define the function fc():
C
AX(1) = NINT(PAR(1))
AU(1) = NINT(PAR(2))
190 Adams Solver
C++ Statements
CALL SYSARY ('ARRAY', AX, 1, X, NSS, LEFLAG)

CALL SYSARY ('ARRAY', AU, 1, U, NU, LEFLAG)
XDOT(1) = A(1,1)*X(1)+A(1,2)*X(2) + B(1,1)*U(1)+B(1,2)*U(2)
XDOT(2) = A(2,1)*X(1)+A(2,2)*X(2) + B(2,1)*U(1)+B(2,2)*U(2)
C
C Return the partial derivatives to ADAMS:
C
CALL ADAMS_NEEDS_PARTIALS (PARFLG)
IF (PARFLG) THEN
CALL SYSPAR ('ARRAY', AX, 1, A, NSS*NSS, LEFLAG)
CALL SYSPAR ('ARRAY', AU, 1, B, NSS*NU , LEFLAG)
ENDIF
RETURN
END
C
C+================================================================*
C
SUBROUTINE GSE_OUTPUT (ID, TIME, PAR, NPAR, DFLAG, IFLAG, NO, Y)
C
C Inputs:
C
INTEGER ID, NPAR, NO
C
C Outputs:
C
DOUBLE PRECISION Y(NO)
C
C Local Variables:
C
INTEGER AX(1), NS
DOUBLE PRECISION C(2), X(2)
SAVE C
DATA C/1.0e3, 0.0/
C
C+--------------------------------------------------------------*
C
C Define the function g():
C
CALL SYSARY ('ARRAY', AX, 1, X, NS, LEFLAG)
Y(1) = C(1)*X(1) + C(2)*X(2)
C
C
IF (PARFLG) THEN
CALL SYSPAR ('ARRAY', AX, 1, C, NS, LEFLAG)
ENDIF
C
C
RETURN
GSE 191
C++ Statements
END
Modeling Control Systems - Implicit formulation

This example models the same system in the example immediately above with an implicit formulation. This
is an extremely simple model, but it serves to highlight the differences. In general, the A, B, and E matrices
need not be constant, and the E matrix need not be diagonal.
In the .adm file, all that needs to be changed is the addition of the IMPLICIT attribute to the GSE statement.
gse/99, IMPLICIT, ns = 2, no = 1, x = 3, u = 1, y = 2, function = user(3,1)
For the implicit case, the GSE_DERIV user-supplied subroutine needs to be changed as follows (note
comments included in the code):
SUBROUTINE GSE_DERIV(ID, TIME, PAR, NPAR, DFLAG, IFLAG, NS, F)
C
C Inputs:
C
C
C Outputs:
C
DOUBLE PRECISION F(*)
C
C Local Variables:
C
INTEGER NStates, NInputs, i, j
DOUBLE PRECISION A(2,2), B(2,2), X(2), U(2), E(2,2), XDOT(2)
SAVE A, B
DATA A /-1.0e3, 0.0, -2.0e4, -1.0e3/
DATA B /0.0, 1.0, -1.0, 0.0/
DATA E /-1.0D0, 0.0D0, 0.0D0, -1.0D0/
C
C+-------------------------------------------------------------------
-*
C
C Explicit form of governing equation: Xdot = A*X + B*U
C Implicit form is: 0 = A*x + B*U + E*Xdot
C
C
C Query the utility subroutines for the number of states and inputs.
C
CALL GSE_NS (NStates)
CALL GSE_NI (NInputs)
C
C Query the utility subroutines for the current values of the state,
time derivative of state and input vectors.
C
CALL GSE_X (X, NStates)
CALL GSE_XDOT (Xdot, NStates)
CALL GSE_U (U, NInputs)
192 Adams Solver
C++ Statements
C
C Construct the return vector, f, in implicit form
C
DO i=1, NStates
F(i) = 0.0D0
DO j = 1, NStates
F(i) = F(i) + A(i,j)*X(j) + B(i,j)*U(j) + E(i,j)*Xdot(j)
ENDDO
ENDDO
C
C
IF (PARFLG) THEN
CALL GSEPAR_X (A, NStates*NStates)
CALL GSEPAR_XDOT (E, NStates*NStates)
CALL GSEPAR_U (B, NStates*NInputs)
ENDIF
RETURN
END
Of course, the results of the implicit and explicit formulations are identical to within roundoff error.
Modeling Control Systems – Implicit formulation with sparse representation of partial arrays
As a final example, this case again models the same system, again implicitly, but this time uses the
GSEMAP_* utility subroutines to specify the sparse representation of the partial derivative arrays.
Notes: 1. There is no attribute or other keyword used to specify a sparse representation. The use
of a GSE_MAP_* utility subroutine implies a sparse representation for that array.
2. Sparse and non-sparse representations can be mixed. As in this example, the E matrix
can be represented sparsely while the others are represented as full.
The only change to the previous example is in the GSE_DERIV user-supplied subroutine. In this case it looks
like:
SUBROUTINE GSE_DERIV(ID, TIME, PAR, NPAR, DFLAG, IFLAG, NS, F)
C
C Inputs:
C
C
C Outputs:
C
DOUBLE PRECISION F(*)
C
C Local Variables:
C
GSE 193
C++ Statements
INTEGER NStates, NInputs, i, j

DOUBLE PRECISION A(2,2), B(2,2), X(2), U(2), E(2), XDOT(2)
SAVE A, B
DATA A /-1.0e3, 0.0, -2.0e4, -1.0e3/
DATA B /0.0, 1.0, -1.0, 0.0/
DATA E /-1.0D0, -1.0D0/
C
C+-------------------------------------------------------------------
-*
C
C Explicit form of governing equation: Xdot = A*X + B*U
C Implicit form is: 0 = A*x + B*U + E*Xdot
C
C
C Specify a sparse representation for the E matrix
C
IF (IFLAG) then
CALL GSEMAP_XDOT(1,1)
CALL GSEMAP_XDOT(2,2)
ENDIF
C
C Query the utility subroutines for the number of states and inputs.
C
CALL GSE_NS (NStates)
CALL GSE_NI (NInputs)
C
C Query the utility subroutines for the current values of the state,
time derivative of state and input vectors.
C
CALL GSE_X (X, NStates)
CALL GSE_XDOT (Xdot, NStates)
CALL GSE_U (U, NInputs)
C
C Construct the return vector, f, in implicit form
C
DO i=1, NStates
F(i) = 0.0D0
DO j = 1, NStates
F(i) = F(i) + A(i,j)*X(j) + B(i,j)*U(j)
ENDDO
F(i) = F(i) + E(i)*Xdot(i)
ENDDO
C
C
IF (PARFLG) THEN
CALL GSEPAR_X (A, NStates*NStates)
CALL GSEPAR_XDOT (E, NStates )
CALL GSEPAR_U (B, NStates*NInputs)
ENDIF
RETURN
END
Again, the results are identical to the previous two examples to within roundoff error.
194 Adams Solver
C++ Statements

IC 195
C++ Statements
IC
The IC statement specifies error tolerances and other parameters for the analysis of the initial conditions and
for reconciling integrator output.
Format
Arguments
AERROR=r Specifies the maximum acceleration error Adams Solver (C++) is to allow during an
initial conditions solution or for reconciling integrator acceleration output.
Default: 1.0E-4
Range: AERROR > 0
ALIMIT=r Specifies the maximum angular increment Adams Solver (C++) is to allow while
testing trial solutions for a set of consistent initial conditions that satisfy all system
constraints. The default units for ALIMIT are radians. To specify ALIMIT in
degrees, add a D after the value.
Default: 30D
Range: ALIMIT > 0
AMAXIT=i Specifies the maximum number of iterations Adams Solver (C++) is to allow for
finding accelerations during an initial conditions solution or for reconciling
integrator acceleration output.
Default: 25
Range: AMAXIT > 0
196 Adams Solver
C++ Statements
APATTERN=c1[:. Specifies as many as ten character strings that together establish the pattern for
..:c10] evaluating the Jacobian matrix during the modified Newton-Raphson solution for
the accelerations. For each iteration, T or TRUE indicates that Adams Solver (C++)
is to evaluate the Jacobian, and F or FALSE indicates that Adams Solver (C++) is not
to evaluate the Jacobian. Thus, cj determines whether or not ADAMS is to evaluate
the Jacobian at the jth iteration. If necessary, Adams Solver (C++) repeats the pattern
of evaluation until it reaches the maximum number of iterations (AMAXIT). The
number of T's or TRUE’s and F’s or FALSE’s together must be at least one and no
more than 10.
Default: T:T:T:T:T:T:T:T:T:T, that is, to evaluating the Jacobian at every iteration.

ERROR=r Specifies the maximum displacement error Adams Solver (C++) is to allow for the
assembly process.
Default: 1.0E-10
Range: ERROR > 0
MAXIT=i Specifies the maximum number of iterations Adams Solver (C++) is to allow for
finding displacements during initial conditions, or when reconciling the position of
configuration during integration (interpolate on, or with the WSTIFF integrator),
and static analysis.
Default: 25
Range: MAXIT > 0
IC 197
C++ Statements
PATTERN=ci[:...: Specifies as many as ten character strings that together establish the pattern for
c10] evaluating the Jacobian matrix during the modified Newton-Raphson solution for
the displacements. For each iteration, T or TRUE indicates that Adams Solver (C++)
is to evaluate the Jacobian, and F or FALSE indicates that Adams Solver (C++) is not
to evaluate the Jacobian. Thus, cj determines whether or not ADAMS is to evaluate
the Jacobian at the jth iteration. If necessary, Adams Solver (C++) repeats the pattern
of evaluation until it reaches the maximum number of iterations (MAXIT). The
number of T’s or TRUE’s and F’s or FALSE’s together must be at least one and no
more than 10.

TLIMIT=r Specifies the maximum translational increment Adams Solver (C++) is to allow
while testing trial solutions during a solution step.
Default: 1.0E10 (no limit)

Range: TLIMIT > 0
VERROR=r Specifies the maximum velocity error that Adams Solver (C++) is to ignore during
an initial conditions solution. Adams Solver (C++) issues a warning if the value of
VERROR is exceeded. Adams Solver (C++) issues an error if
PREFERENCES/SIMFAIL=STOPCF is chosen.
Default: 1.0E-4
Range: VERROR > 0
Extended Definition
The IC statement specifies error tolerances and other parameters for the analysis of initial conditions and for
reconciling integrator output. By default, WSTIFF reconciles integrator results to be consistent with
constraints; GSTIFF does not, unless you set INTERPOLATE=ON.
This statement is used only when requesting a dynamic, static equilibrium, or quasi-static equilibrium
analysis, and when one or more of the tolerances and other parameters for the initial conditions analysis from
the default values is to be changed.
Use the SIMULATE command to request a dynamic, static equilibrium, or quasi-static equilibrium analysis.
Before performing one of these analyses, Adams Solver (C++) automatically does an initial conditions
analysis. An initial conditions analysis is not necessary when the system has zero degrees of freedom because
the kinematics of the system fully determine its configuration.
The initial conditions analysis ensures that the system satisfies all constraints within the system. If necessary,
Adams Solver (C++) moves parts until both parts of each joint are in contact. This analysis involves three
separate phases. First, Adams Solver (C++) makes the displacements between all parts and joints in the system
physically consistent. This requires the use of Newton-Raphson iteration to solve a set of nonlinear algebraic
equations. Once the displacements are consistent, Adams Solver (C++) makes the velocities physically
consistent. Since this requires solving a set of linear equations, iteration is not necessary. Finally, Adams Solver
198 Adams Solver
C++ Statements
(C++) also calculates consistent accelerations and forces. This solution also requires solving a set of nonlinear
equations using Newton-Raphson iteration.
When reconciling, the integrator uses the initial conditions solution process at each output step to ensure that
velocities, accelerations, and forces are consistent with the system constraints. If you set
INTERPOLATE=ON, the integrator also uses the initial conditions solution at each output step to ensure
displacements are consistent with the constraints. The IC parameters control those solutions as well as the
initial conditions solution.
If you issue neither the IC command nor statement in an Adams Solver (C++) session, the solver uses the
default values for AERROR, ALIMIT, AMAXIT, APATTERN, ERROR, MAXIT, PATTERN, TLIMIT,
and VERROR when finding initial conditions and reconciling integrator output.
Tip: Use the ALIMIT and TLIMIT arguments to limit incrementing displacement variables and
thus the size of the position change on successive iterations. This tends to prevent Adams
Solver (C++) from assembling the mechanism in an undesirable configuration.
Examples
IC/ALIMIT=10D, ERROR=1.0E-6, MAXIT=45
This statement instructs Adams Solver (C++) to use these values instead of the defaults when performing an
initial conditions analysis. It limits the angular increment per iteration to 10 degrees, reduces the
displacement error to 1.0E-6, and limits the number of iterations to 45.
INTEGRATOR 199
C++ Statements
INTEGRATOR
The INTEGRATOR statement lets you control the numerical integration of the equations of motion for a
dynamic analysis. You should use the INTEGRATOR statement when the default values for the numerical
solution parameters are not optimal for a particular simulation.
Format
200 Adams Solver
C++ Statements
Arguments
INTEGRATOR 201
C++ Statements
ALPHA=r Defining coefficient for the HHT method. Learn more about HHT.
Default value: -0.3
Range: -0.333333 <= ALPHA <= 0

BETA=r One of the two defining coefficients associated with the Newmark method.
Default Value: 0.36
Range: Defined in conjunction with GAMMA. Together
they must satisfy the stability condition.

2
 γ + 1---
 2
β ≥ --------------------
4
202 Adams Solver
C++ Statements
Specifies the corrector algorithm that is to be used with the integrators.
 CORRECTOR=original - Specifies that the corrector available in the

previous releases of Adams Solver (C++) be used. This is the default.
This implementation of the corrector requires that at convergence, the
error in all solution variables be less than the corrector error tolerance.
 CORRECTOR=modified - Specifies that a modified corrector is used.
For GSTIFF, WSTIFF and HASTIFF, this implementation of the
corrector requires that at convergence, the error in only those variables
for which integration error is being monitored be less than the corrector
error tolerance. This is a slightly looser definition of convergence, and
you should use proper care when selecting this setting. For HHT and
NEWMARK, this implementation of the corrector requires that the
convergence assessment is to be performed ignoring fluctuations of the
values in the Lagrange multipliers.
 CORRECTOR=orig_constant - Specifies that the original corrector is
set and that no automatic switching to the modified corrector is to be
performed. Adams Solver (C++) would switch from the original
corrector to the modified corrector automatically under any of these two
conditions:
a. The model has CONTACT elements. By default, Adams Solver
(C++) switches to the modified corrector when the model has
CONTACT elements.
b. There is an integration failure. In some cases, the integration
algorithm will automatically switch to the modified corrector
temporarily.
When using the orig_constant option, Adams Solver (C++) will use the
original corrector and no switching of the corrector algorithm is allowed.
For additional information, see the Extended Definition.
Default: corrector=original
Note: Models containing CONTACT elements automatically switch to the

modified formulation when Solver reads the model file. See Automatic
corrector algorithm switches for more details.
INTEGRATOR 203
C++ Statements
ERROR=r Specifies the relative and absolute local integration error tolerances that the
integrator must satisfy at each step. For BDF, HHT, and Newmark integrators,
Adams Solver (C++) monitors the integration errors in the displacement and state
variables that the other differential equations (DIFFs, LSEs, GSEs, and
TFSISOs) define. The SI2 formulation also monitors errors in velocity variables.
The larger the ERROR, the greater the error/step in your solution.
Note that the value for ERROR is units-sensitive. For example, if a system is
modeled in mm-kg-s units, the units of length must be in mm.
Assuming that all the translational states are larger than 1 mm, setting
ERROR=1E-3 implies that the integrator monitors all changes of the order of 1
micron.
The error tolerance is compared against a local error measure that depends on the
difference between the current predicted and corrected states, the past history of
the states, and the current integration order.
A slightly different integration ERROR definition is used for HHT and

Newmark integrators. For these two integrators, the default is 1E-5. For more
information, see Remarks.
Defaults:
 HHT and Newmark: 1E-5

 All other integrators: 1E-3
Range: ERROR > 0
FIXIT=i Specifies 'fixed' number of corrector iterations to be taken per time step. Must be
either unspecified or an integer from 1-10. If specified, the fixed step option is
employed. If FIXIT is unspecified, then the fixed step option is not employed and
Adams Solver integration proceeds in the traditional (that is, variable time step)
manner.
Default: unspecified
Range: 1 < FIXIT < 10

204 Adams Solver
C++ Statements
GAMMA=r One of the two (together with BETA) defining coefficients associated with the
Newmark method.
Default value: 0.7
Range: Defined in conjunction with BETA. Together they must satisfy the
stability condition
2
 γ + 1---
 2
β ≥ --------------------
4
GSTIFF Specifies that the GSTIFF (Gear) integrator is to be used for integrating the
differential equations of motion.
HHT Specifies that the HHT (Hilber-Hughes-Taylor) integrator is used for integrating
the equations of motion.
HINIT=r Defines the initial time step that the integrator attempts.
Default: 1/20 of the output step

Range: 0 < HMIN < HINIT < HMAX
HMAX=r Defines the maximum time step that the integrator is allowed to take.
Default:
 If INTERPOLATE = ON, the integration step size is limited to the

value specified for HMAX. If HMAX is not defined, no limit is placed
on the integration step size.
 If INTERPOLATE = OFF, the maximum step size is limited to the
output step.
HMIN=r Defines the minimum time step that the integrator is allowed to take.
Default:
 1.0E-6*HMAX for GSTIFF, WSTIFF, and I3

 Machine precision for GSTIFF, WSTIFF, SI2, and for HHT and
Newmark
INTEGRATOR 205
C++ Statements
HRATIO=i Specifies the 'fixed' ratio of the output sampling rate (aka "DTOUT") to the
integrator time step size (aka "H"). Must be a positive integer. If unspecified while
FIXIT is specified, this defaults to 1. HRATIO is only valid in the context of the
fixed step option; so, it's ignored if FIXIT is unspecified.
Default: 1 (with FIXIT on)
Range: positive integer

Specifies that the integrator is not required to control its step size to reach an
output point. Therefore, when the integrator crosses an output point, it
computes a preliminary solution by interpolating to the output point. Then, it
refines (or reconciles) the solution to satisfy the equations of motion and
constraint. Note that the IC statement/command defines the parameters
controlling the reconciliation processes. (For example, position MAXIT,
AERROR, and so on.) INTERPOLATE=OFF turns off interpolation for the
chosen integrator.
Default: OFF
Note: When using INTERPOLATE with models containing CONTACT,

you may see intermediate data at intervals that do not coincide with
your specified output interval. This intermediate data (the data in-
between the interpolated outputs) actually corresponds to contact
incidences. You can turn off these extra contact data points with an
environment variable, MDI_ADAMS_CONTACT_OUT.
I3 Specifies the Index-3 (I3) formulation be used. For more information, see
Extended Definition.
Default for GSTIFF/WSTIFF/HHT

206 Adams Solver
C++ Statements
KMAX=i Indicates the maximum order that the integrator can use. The order of
integration refers to the order of the polynomials used in the solution. The
integrator controls the order of the integration and the step size, and thus,
controls the local integration error at each step so that it is less than the error
tolerance specified.
Note:
 For problems involving discontinuities, such as contacts, setting
KMAX=2 can improve the speed of the solution. We do not recommend
that you set the KMAX parameter unless you are a very experienced user.
Any modification can adversely affect the integrators accuracy and
robustness.
 KMAX is irrelevant (ignored) if the integrator selected is HHT or
NEWMARK. Both these integrators are constant order (order 2 and 1,
respectively) and therefore, the order does not change during simulation
as is the case for the rest of the integrators available in the solver.
Default: KMAX = 6
Range: 1 < KMAX < 6
MAXERR=r Specifies the amount error above which the user would like the integrator to stop
trying to solve the problem if it can't do better than this when the fixed step
option is selected. If the local integration error exceeds MAXERR, the integrator
stops the simulation. MAXERR is a positive real number. Similar to HRATIO,
it's only relevant to the fixed step option; so, it's ignored if FIXIT is unspecified.
When FIXIT is specified and this value is unspecified, then there is no amount
of error which would cause Adams Solver to quit. Note that unlike ERROR,
MAXERR does not control the accuracy of results. MAXERR can be interpreted
as the pre-mature stopping criteria for simulation when the fixed step option is
selected.
Default: infinity
Range: ERROR > 0

MAXIT=i Specifies the maximum number of iterations allowed for the Newton-Raphson
iterations to converge to the solution of the corrector nonlinear equations.
Typically, MAXIT should not be set larger than 10. This is because round-off
errors start becoming large when a large number of iterations are taken. This can
cause an error in the solution.
Default: 10
Range: MAXIT > 0
NEWMARK Specifies that the NEWMARK integrator be used for integrating the equations of
motion.
INTEGRATOR 207
C++ Statements
PATTERN=c1[:...:c10] Indicates the pattern of trues and falses for reevaluating the Jacobian matrix for
Newton-Raphson. A value of true (T) indicates that Adams Solver (C++) is
evaluating a new Jacobian matrix for that iteration. A value of false (such as
PATTERN=F) turns on the adaptive Jacobian evaluation algorithm. The
evaluation of the integration Jacobian is then only done when needed.
The algorithm determines a corrector convergence speed and based on this value,
it extrapolates the configuration of the system after MAXIT iterations. The
Jacobian is updated if the algorithm indicates that the convergence rate is too slow
for the corrector to meet the convergence criteria. Overall, this approach is
expected to result in fewer Jacobian evaluations, which in turn can lead to shorter
simulation times.
PATTERN accepts a sequence of at least one character string and not more than
10 character strings. Each string must be either TRUE or FALSE, which you can
abbreviate with T or F. You must separate the strings with colons.
Default: T:F:F:F:T:F:F:F:T:F (For GSTIFF and WSTIFF and for

HHT/Newmark when FIXIT is specified)
Default: F (For HHT/Newmark when FIXIT is not specified)
Note: A pattern setting of all false implies that Adams Solver (C++) is to not
evaluate the Jacobian until it encounters a corrector failure. For
problems that are almost linear or are linear, this setting can improve
simulation speed substantially.
SI2 Specifies that the Stabilized Index-2 (SI2) formulation, in conjunction with the
GSTIFF, WSTIFF, or HASTIFF integrators, be used for integrating the
equations of motion.
The SI2 formulation takes into account constraint derivatives when solving for
equations of motion. This process enables the GSTIFF and WSTIFF integrators
to monitor the integration error of velocity variables, and, therefore, renders
highly accurate simulations. A positive side effect of the SI2 formulation is that
the Jacobian matrix remains stable at small step sizes, which in turn increases the
stability and robustness of the corrector at small step sizes.
The SI2 formulation is available only with GSTIFF, WSTIFF, and HASTIFF.

208 Adams Solver
C++ Statements
WSTIFF Specifies that the WSTIFF (Wielenga stiff ) integrator be used for integrating the
equations of motion. WSTIFF uses the BDF method that takes step sizes into
account when calculating the coefficients for any particular integration order.
Default: GSTIFF
HASTIFF Specify that the HASTIFF (Hiller Anantharaman stiff ) integrator be used for
integrating the differential equations of motion.HASTIFF uses the BDF method
that takes step sizes into account when calculating the coefficients for any
particular integration order.
HASTIFF integrator, be used for formulating and integrating differential
equations of motion. This process enables the HASTIFF integrator to monitor
the integration error of velocity variables, and therefore renders highly accurate
simulations. A positive side effect of the SI1 formulation is that the Jacobian
matrix remains stable at small step sizes, which increases the stability and
robustness of the corrector at small step sizes.
The SI1 formulation is available only with HASTIFF, for which it is the default.
Extended Definition
You use the INTEGRATOR statement to select an integrator when you choose to perform a dynamic
analysis. The dynamic analysis of a mechanical system consists essentially of numerically integrating the
nonlinear differential equations of motion.
Ordinary differential equations (ODEs) can be characterized as being stiff or non-stiff. A set of ODEs is said
to be stiff when it has widely separated eigenvalues (low and high frequencies) with the high frequency
eigenvalues being overdamped. Therefore, while the system has the ability to vibrate at high frequencies, it
usually does not because of the associated high damping, which dissipates this mode of motion.
The stiffness ratio of a set of ODEs is defined as the highest inactive frequency divided by the highest active
frequency. Stiff ODEs typically have a stiffness ratio of 200 or higher. In contrast, non-stiff systems have a
stiffness ratio less than 20. This basically means that for a non-stiff system of ODEs, the higher frequencies
of the system are active. The system can and does vibrate at these frequencies.
An example of a stiff system is a flexible body in which the higher frequencies have been damped out
completely, leaving only the lower frequency vibration modes active.
The system above becomes non-stiff if the higher frequencies are excited by an external force. Nonlinear
ODEs can be stiff at some points in time and non-stiff at other points.
Learn more about:
 Stiff and Non-Stiff Integrators
 Prediction
INTEGRATOR 209
C++ Statements
 Correction
 GSTIFF
 SI2
 ODE versus DAE
 WSTIFF
 The HHT and Newmark Integrators
 HASTIFF
 Models with Discrete GSEs
 Fixed Step Integrator Option
Stiff and Non-Stiff Integrators

Integrators are classified as stiff or non-stiff. A stiff integrator is one that can handle numerically stiff systems
efficiently. For stiff integrators, the integration step is limited by the inverse of the highest active frequency
in the system. For non-stiff integrators, the integration step is limited by the inverse of the highest frequency
(active or inactive) in the system. Thus, non-stiff integrators are notoriously inefficient for solving stiff
problems.
Because many mechanical systems are numerically stiff, the default integrator in Adams Solver (C++) is GSTIFF,
a stiff integrator that is based on the DIFSUB integrator developed by C.W. Gear. Gear's DIFSUB integrator
is unrelated to the Adams Solver subroutine that is known by the same name. WSTIFF is another stiff integrator
available in Adams Solver (C++). Both GSTIFF and WSTIFF integrators are based on Backward-Difference
Formulae (BDF) and are multi-step integrators. The solution for these integrators occurs in two phases: a
Prediction followed by a Correction.
Prediction
When taking a new step, the integrator fits a polynomial of a given order through the past values of each
system state, and then extrapolates them to the current time to perform a prediction. Standard techniques
like Taylor's series (GSTIFF) or Newton Divided Differences (WSTIFF) are used to perform the prediction.
Prediction is an explicit process in which only past values are considered, and is based on the premise that
past values are a good indicator of the current values being computed. The predicted value does not guarantee
that it will satisfy the equations of motion or constraint. It is simply an initial guess for starting the correction,
which ensures that the governing equations are satisfied.
The degree of polynomial used for prediction is called the order of the predictor. For example, a predictor of
order 3 will fit a cubic polynomial that includes the past 4 values for each state. Clearly, if the governing
equations are smooth, the prediction will be quite accurate. On the other hand, if the governing equations
are not smooth, the prediction can be quite inaccurate.
Correction
The corrector formulae are an implicit set of difference relationships (BDFs) that relate the derivative of the
states at the current time to the values of the states themselves. This relationship transforms the nonlinear
differential algebraic equations to a set of nonlinear, algebraic difference equations in the system states. The
Backward Euler integrator is an example of a first-order BDF. Given a set of ODEs of the form dy/dt = f (y,t),
the Backward Euler uses the difference relationship:
210 Adams Solver
C++ Statements
y n + 1 = y n + hy· n + 1 (20)
where:
 yn is the solution calculated at t = tn.
 h is the step size being attempted.
 yn+1 is the solution at = tn+1, which is being computed.
Notice that the subscript n+1 is on both sides of Equation (20). This is an implicit method.
Adams Solver (C++) uses an iterative, quasi-Newton-Raphson algorithm to solve the difference equations and
obtain the values of the state variables. This algorithm ensures that the system states satisfy the equations of
motion and constraint. The Newton-Raphson iterations require a matrix of the partial derivatives of the
equations being solved with respect to the solution variables. This matrix, known as the Jacobian matrix, is
used at each iteration to calculate the corrections to the states.
Assume that the equations of motion have the form:
F (y,y· ,t) = 0 (21)

where y represents all the states of the system.
k k
Linearization of Equation (21) about an operating y = y and y· = y· gives:
k k ∂F k ∂F k
F (y,y· ,t) = F (y ,y· ,t) + ------ ( y – y ) + -----·- ( y· – y· ) = 0
∂y ·k
∂y
y ,y·
k k k
y ,y
k
replacing y - yk with Δy and ( y· – y· ) with Δy· , you get:
k k ∂F ∂F
F (y ,y· ,t) + ------ Δy + -----·- Δy· = 0 (22)
∂y ·k
∂y
y ,y·
k k k
y ,y
From Equation (20), which is a first-order BDF, you can get the relationship:
1
Δy· = --- Δy (23)
h
Substituting Equation (23) into (22), you get:
∂-----
F- 1 ∂F k k
+ --- -----·- Δy = – F (y ,y· ,t) (24)
∂y ·k
h ∂y
y ,y·
k k k
y ,y
A generalization of (24)to higher-order BDFs gives:

INTEGRATOR 211
C++ Statements
∂-----
F- 1 ∂F k k
+ --------- -----·- Δy = – F (y ,y· ,t) (25)
∂y ·k
hβ 0 ∂y y ,y·
k k k
y ,y
where:
 β 0 is a scalar that is characteristic to an integration order. This scalar is constant for each integration
order.
 The matrix on the left side of Equation (25) is the Jacobian matrix of F.
 Δy are the corrections.
 F is the residue of equations (equation imbalances).
The corrector is said to have converged when the residue F and the corrections Δ y have become small.
After the corrector has converged to a solution, the integrator estimates the local integration error in the
solution. This is usually a function of the difference between the predicted value and the corrected value, the
step size, and the order of the integrator. If the estimated error is greater than the specified integration
ERROR, the integrator rejects the solution and takes a smaller time step. If the estimated error is less than
the specified local integration ERROR, the integrator accepts the solution and takes a new time step. The
integrator repeats the prediction-correction-error estimation process until it reaches the time specified in the
SIMULATE command.
Note: The premise for using predictions as an initial guess for the corrector is severely violated
when discontinuities occur or when large forces turn on or off in the model. Contact,
friction, and state transitions (as in hydraulics where a valve is suddenly closed or opened)
are examples of such phenomena. These kinds of models are difficult for multi-step
integrators.
The corrector in a stiff integrator ensures that all candidate solutions satisfy the equations of the system. The
two algorithms, original and modified, differ primarily in the strategy that they use to define when the
corrector iterations have converged.
The CORRECTOR=modified setting is helpful for models containing discontinuities in the forcing
functions. Problems with contacts belong in this category.
Correction summary tables:
Error control in corrector:
212 Adams Solver
C++ Statements
Integrator and formulation Original Corrector Modified corrector

GSTIFF I3, WSTIFF I3 Error control on displacements, Error control on displacements of
velocities of body equations, flex body equations, flex modes, and
modes, flex mode velocities, state variables from differential
applied forces, and state variables equations (DIFFs).
GSTIFF SI2, WSTIFF SI2, from differential equations Error control on displacements
HASTIFF SI1/SI2 (DIFFs); that is, all states except and velocities of body equations,
Lagrange multipliers, Lagrange flex modes, flex mode velocities,
multiplier velocities, and contact and state variables from
forces. differential equations (DIFFs).
GSTIFF SI1, WSTIFF SI1, Not Supported in the Adams Solver (C++)
CONSTANT_BDF SI1, SI2,
and I3
Error control of HHT and Newmark integrators:
HHT Newmark For both ORIGINAL and MODIFIED, the error control is done on
accelerations of body equations, flex mode accelerations, and state variables
from differential equations (DIFFs). If using ORIGINAL, the convergence
assessment is done on all state variables. If using MODIFIED, the
convergence assessment is done ignoring the fluctuations in the Lagrange
multipliers.
Automatic corrector algorithm switches

The default behavior of Adams Solver (C++) consisted of automatically switching from the ORIGINAL
corrector to the MODIFIED corrector under two circumstances:
a. The model has CONTACT elements. Upon reading the model data, if the ORIGINAL corrector
setting is set, Adams Solver (C++) will automatically switch to using the MODIFIED corrector.
Notice the switch can be prevented by setting the environment variable
MDI_ADAMS_CONTACT_COR. (See Adams Solver Advanced Settings for more details.) The
switch is done because CONTACT models are harder to solve, using the MODIFIED corrector
increases the chances to simulate the models to completion.
b. The dynamic integrator found difficulties integrating the equations of motion and needs to restart
the numerical integration process. If the ORIGINAL corrector was set, then Adams Solver (C++)
will automatically switch to the MODIFIED corrector in order to solve the equations of motion.
This switch is temporary and the corrector is restored to the ORIGINAL setting after successful
integration steps have been taken.
Notice that no switching of the corrector algorithm is performed when the MODIFIED corrector option was
set in the model.
INTEGRATOR 213
C++ Statements
Option ORIG_CONSTANT does not determine a new correction algorithm. Setting ORIG_CONSTANT
is equivalent to setting the ORIGINAL option, except no automatic switching of the corrector algorithm is
performed. Hence, if the model has CONTACT elements, no switching to the MODIFIED algorithm takes
place. Similarly, if the dynamic integrator has difficulties solving the equations of motion, no switching to
the MODIFIED corrector is performed during the restarting of the numerical integration process. This may
cause some simulations to fail.
Solver will inform the user in the message file whenever it switches the CORRECTOR setting.
GSTIFF
GSTIFF is based on the DIFSUB integrator. GSTIFF is the most widely-used and tested integrator in Adams
Solver (C++). It is a variable-order, variable-step, multi-step integrator with a maximum integration order of
six. The BDF coefficients it uses are calculated by assuming that the step size of the model is mostly constant.
Thus, when the step size changes in this integrator, a small error is introduced in the solution. This
formulation offers the following benefits and limitations:
Characteristics of GSTIFF Integrator
Benefits Limitations
 High speed.  Velocities and especially accelerations can have errors. An
 High accuracy of the system easy way to minimize these errors is to control HMAX so
displacements. that the integrator runs at a constant step size and runs
consistently at a high order (three or more).
 Robust in handling a variety of
analysis problems.  You can encounter corrector failures at small step sizes.
These occur because the Jacobian matrix is a function of the
inverse of the step size and becomes ill-conditioned at small
steps.
References
For more information on the GSTIFF integrator, see:
1. Gear, C.W. (1971a). The Simultaneous Solution of Differential Algebraic Systems. IEEE Transactions
on Circuit Theory,
CT-18, No.1, 89-95.
2. Gear, C.W. (1971b). Numerical Initial Value Problems in Ordinary Differential Equations. New
Jersey: Prentice-Hall.
SI2
SI2 (Stabilized-Index Two) is an equation formulation technique that can be used for equations describing
mechanical systems. This formulation is available with both GSTIFF and WSTIFF integrators.
To understand what the SI2 formulation does, you need to know what Differential Algebraic Equations
(DAE) are and understand the notions of Index of a DAE and stabilization of DAE. A brief summary is given
below. For more information, refer to:
214 Adams Solver
C++ Statements
 Brenan, K.E., Campbell, S.I., and Petzold, L.R. (1996). Numerical Solution of Initial Value Problems
in Differential-Algebraic Equations, Classics in Applied Mathematics.
ISBN: 0-89871-353-6 (pbk.)
ODEs Versus DAEs

E ≡ y· – f ( y ,t ) = 0, y ( 0 ) = y 0 (26)
is defined to be a set of ODEs, because y· are explicit in Equation (26).

∂E
Notice that for ODEs, -----·-
= I , and is never singular.
∂y
In contrast, DAEs are usually written as:
E ≡ F ( y· ,y ,t ) = 0, y ( 0 ) = y 0 (27)
∂E
It is an intrinsic property of DAE that the matrix -----·- is singular. Another way of stating this is that some of
∂y
the equations in a set of DAEs are not differential equations at all, they are algebraic equations of constraint.
In Adams Solver (C++), the equations of a mechanical system are formulated as:
T T
Mq·· + φ q λ – A F (q,q· ) = 0 (28)
φ (q,t) = 0 (29)
where:
 M is the mass matrix of the system.
 q is the set of coordinates used to represent displacements.
 φ is the set of configuration and applied motion constraints.
 F is the set of applied forces and gyroscopic terms of the inertia forces.
 AT is the matrix that projects the applied forces in the direction q.
 φ q is the gradient of the constraints at any given state and can be thought of as the normal to the
constraint surface in the configuration space.
Notice that Equation (28) is a second-order differential equation but Equation (29) is an algebraic equation.
Also notice the time derivatives of q are seen in Equations (28) and (29), but the time derivative of λ , the
Lagrange Multipliers of the constraints are not present in either Equation (28) or (29).
These are typical characteristics of DAEs.
Index of a DAE
The index of a DAE is defined as the number of time derivatives required to convert a set of DAEs to ODEs.
INTEGRATOR 215
C++ Statements
Equations (28) and (29) can be converted to a set of ODE by first taking two time derivatives of the kinematic
position constraint equations in Eq. (29), to obtain the set of kinematic acceleration constraint equations.
These equations together with the equations of motion in Eq. (28) can be formally solved for the accelerations
and the Lagrange multipliers λ . By taking a third and last time derivative of the Lagrange multipliers, you
are left with a set of ODE in accelerations and the Lagrange multipliers.
Therefore, the Euler-Lagrange equations for mechanical systems are said to have an Index=3.
Solution of DAEs
Equations (28) and (29)are converted to first-order form, so that commercially available DAE integrators can
solve them. This is usually done by introducing a new variable, the velocity variable u, which is defined as:
u – q· = 0 (30)
T T
Mu· + φ q λ – A F = 0 (31)
u – q· = 0 (32)
φ = 0 (33)
These are the DAE (in first order form) for a mechanical system. Applying the BDF formula (like Equation
(23), one obtains the Jacobian of Equation (31):
M- T T T T
-------- – A FU M q u· + φ qq λ – ( A F ) φq
hβ 0
I (34)
I – --------- 0
hβ 0
0 φq 0
This matrix becomes ill-conditioned as the integration step size h decreases, and becomes singular as h moves
closer to 0.
This is the reason why Index 3 formulations become unstable at small step sizes -- a very counter-intuitive
result.
Another important result for Index 3 formulations is that the integration error cannot be monitored on either
velocities, u, or reaction forces, λ .
Index reduction methods (IRM) are typically employed to make DAE more easily solvable by numerical
methods. The key benefit to using IRM is that the integration error can be monitored on velocities.
Index Reduction Methods
There are many ways to reduce the index of a DAE. In general, the lower the index of a DAE, the more
tractable it is to being numerically solved. So in general, it is a good idea to try to reduce the index of a DAE.
216 Adams Solver
C++ Statements
One common approach is to replace Equation (33) with the time derivatives of the constraint. Every level of
differentiation reduces the index by one.
For example, you may want to reduce the Index of Equation (31) to two by differentiating (33):
·
φ ( q ,u ) = 0 (35)
Solving Equations (31), (32), and (35) numerically adds a new complication, however. The solution satisfies
Equation (35), but is not guaranteed to solve Equation (33), the original constraint.
If you were to formulate a simple pendulum using Equations (31), (32), and (35) and solve them, you would
notice that after some time the pin-joint constraint is violated and the pendulum drifts off into space, grossly
violating the pin-joint, and the system Equation (31) is not aware.
Clearly, a means for considering Equation (33) along with Equations (31), (32), and (35) to prevent drift-off is
required. The SI2 formulation does precisely this.
The SI2 Formulation
Gear, Gupta, and Leimkuhler have shown that drift-off can be prevented by appending Equation (33) to (31)
and adding a new set of variable as follows:
T T
Mu· + φ q λ – A F = 0
T
u – q· + φ q μ = 0 (36)
·
φ ( q ,u ,t ) = 0
φ (q,t) = 0
·
The numerical solution of Equations (36) are guaranteed to satisfy both φ and φ . In this sense, the Equations
(36) are stabilized. Because the constraints φ have been differentiated once, Equation (36) has an Index = 2.
Equations (36) are called the Stabilized Index Two representation of Equations (31), (32), and (33). It has been
proven that Equation (36) and Equation (31), (32), and (33) have the same solution when μ = 0. This condition
is rigorously enforced by the SI2 formulation in Adams Solver (C++).
It can also be shown that the Jacobian of Equation (36) does not become ill-conditioned as h moves closer to
0. Furthermore, since Equation (36) has an Index of 2, the integrators can monitor integration error on both
u and q.
Benefits and Limitations
The benefits and limitations of the SI2 formulation are described in the following table:
Characteristics of the SI2 Formulation
INTEGRATOR 217
C++ Statements
Benefits of the SI2 formulation: Limitations of the SI2 formulation:

 Gives very accurate results, especially for velocities and  Is typically 25% to 100% slower for most
accelerations. problems than regular GSTIFF, when run
 Usually allows an ERROR that is approximately 10 to with the same error.
100 times larger than regular GSTIFF to produce the  Requires that all velocity inputs be
same quality of results. differentiable. Therefore, you must define
 Is very robust and stable at small step sizes. your MOTIONS so that they are smooth
and twice differentiable. Non-smooth
 Corrector failures that small step sizes cause occur less motions, which theoretically cause infinite
frequently than with the Index-3 GSTIFF accelerations, cause failures in the SI2
formulation. formulation. The I3 formulations can
 Singular matrices due to small step sizes occur less sometimes handle such models.
frequently than with the Index-3 GSTIFF
formulation.
 Corrector failures are typically indicative of a modeling
problem and not of a numerical deficiency in the
Adams Solver software.
 Tracks high frequency oscillations very accurately.
WSTIFF
WSTIFF is a stiffly stable, BDF-based, variable-order, variable-step, multi-step integrator. It has a maximum
order of six. The BDF coefficients it uses are a function of the integrator step size. Thus, when the step size
changes in this integrator, the BDF coefficients change. WSTIFF can change step size without any loss of
accuracy, which helps problems run more smoothly. The benefits and limitations of WSTIFF are the same as
those of GSTIFF and are listed in the Characteristics of GSTIFF Integrator table.
References
For information on the WSTIFF integrator, see the paper:
 Van Bokhoven, W.M.G. (1975, February). Linear Implicit Differentiation Formulas of Variable
Step and Order. IEEE Transactions on Circuits and Systems, 22 (2).
The HHT and Newmark Integrators

The HHT integrator is based on the α -method proposed by H.M. Hilber, T.J.R. Hughes, and R.L. Taylor
[1]. The α -method is widely used in the structural dynamics community for the numerical integration of
second order ordinary differential equations that are obtained at the end of finite element discretization. If
the finite element approach is linear, the equations assume the form:
Mq·· + Cq· + Kq – F ( t ) (37)

The mass, damping, and stiffness matrices, M, C, and K, respectively, are constant, and the force F depends
on time.
218 Adams Solver
C++ Statements
The α -method comes from the Newmark method proposed by N.M. Newmark [3], which defines a family
of integration formulas that depend on two parameters β and γ .
2
h
q n + 1 = q n + hv n + ----- [ ( 1 – 2β )a n + 2βa n + 1 ] (38)
2
v n + 1 – v n – h [ ( 1 – γ )a n + γa n + 1 ] (39)
In the Newmark formulation, these formulas are used to discretize the equations of motion (37)
Ma n + 1 + Cv n + 1 + Kq n + 1 = F n + 1 (40)
where an+1, vn+1, and qn+1 are numerical approximations for q··( t n + 1 ) , q· ( t n + 1 ) , and q ( t n + 1 )
respectively.
The Newmark method is implicit and A-stability (stability in the whole left plane) is guaranteed as soon as:
1
γ ≥ --- (41)
2
2
 γ + 1---
 2
β ≥ -------------------- (42)
4
1 1
The Newmark method is an order one integration method, unless β = --- and γ = --- , which makes the
4 2
Newmark method same as the trapezoidal rule, which is a second-order method. The drawback of the
trapezoidal rule is that it has poor damping properties, which is unacceptable for problems that have either:
 High oscillations that are of no interest
 Parasitic oscillations that are a byproduct of the finite element discretization process
The α -method came as an improvement as it preserved the A-stability of the Newmark formulas, while
achieving second-order accuracy when used with the second-order linear ODE problem of Equation (37). The
change to obtain this improvement does not pertain to the formulas proposed by Newmark, but rather the
form of the discretized equations of motion in (40). The new equation in which the integration formulas of
equations (38) and (39) are substituted is:
Ma n + 1 + ( 1 + α )Cv n + 1 – αCv n + ( 1 + α )Kq n + 1 – αKq n = F ( t̃ n + 1 ) (43)
where
t̃ n + 1 = t n + ( 1 + α )h (44)
The equations of motion associated with multi-body dynamics simulation in Adams are:
INTEGRATOR 219
C++ Statements
T
Mq·· + Φ q λ = F ( q· ,q ,t ) (45)
These equations are neither linear, nor ordinary differential as is the case in equation (37), because the solution
q(t) must also satisfy the kinematic constraint equations:
Φ ( q ,t ) = 0 (46)
Looking at equation (43), the idea behind the HHT discretization is that the α -scaling is done in conjunction
with the forces applied on the system. The current value of the force is first scaled by 1 + α , while the value
of the force at the previous time step is subtracted after being scaled by α . According to equation (45), for
T
the equations of motion in the multi-body formulation, the force is computed as Φ q λ – F ( q· ,q ,t ) ; (that
·· ). Therefore, in relation to the original HHT
is, everything that is not explicitly depending on acceleration q
formulation, the discretization of the multi-body dynamics equations of motion is:
T T
( Mq··) n + 1 + ( 1 + α ) ( Φ q λ – F ) n + 1 – α ( Φ q λ – F ) n = 0 (47)
From an implementation standpoint it is more advantageous to scale the equation above by (1 + α ) and
obtain the equivalent form:
1 - ·· T α T
------------ ( Mq ) + ( Φ q λ – F ) n + 1 – ------------- ( Φ q λ – F ) n = 0 (48)
1+α n+1 1 + α
The second set of equations that must be satisfied at time tn+1 are the position kinematic constraint equations:
Φ ( qn + 1 ) = 0 (49)
Using the notation:
1 T α T
e 1 ( q··,q· ,λ ) ≡ ------------- ( Mq··) n + 1 + ( Φ q λ – F ) n + 1 – ------------- ( Φ q λ – F ) n
1+α 1+α
e 2 ( q, t ) ≡ Φ ( q n + 1 ,t n + 1 )
the simulation is advanced from time tn to tn+1, by finding the solution of the nonlinear system:
 
··  e ( q··, λ ) 
Ψ ( q, λ ) =  1  (50)
 e 2 ( q, t ) 
 
The unknowns solved for are q·· and λ . Note that although q and q· appear in equation (50), they are
expressed in terms of q·· based on the formulas of equations (38) and (39) (the notation used there was v for
220 Adams Solver
C++ Statements
q· , and a for q·· ). These integration formulas define linear relationships of the form q n + 1 = f 1 ( q··n + 1 )
and q· n+1 = f ( q··
2 n+1 ) . It is easy to see that based on equations (38) and (39)
∂-----q 2 ∂-----q·
·· = βh = γh
∂q ∂q··
The Jacobian of the nonlinear system of equation (50) is given by:
∂e 1 1 - ∂F 1 T ∂F 2
-------
··- = ------------ M – -----·- hγ + ------------- ( Mq··) q ( Φ q λ ) q – -----··- βh
∂q 1 + α ∂q 1+α ∂q
∂e 1
-------- = Φ Tq λ
∂λ
∂e 2
- = Φ q ⋅ βh 2
-------
∂q··
∂e 2
-------- = 0
∂λ
Using the notation:
ˆ 1 ∂F 1 T ∂F 2
M = ------------- M – -----·- hγ + ------------- ( Mq··) q + ( Φ q λ ) q – -----··- βh (51)
1+α ∂q 1+α ∂q
one correction in the quasi-Newton algorithm is computed as the solution of the linear system:
ˆ T
M Φ q ∂q·· –e1
= (52)
Φ q ⋅ βh 0 ∂γ –e2
2
1-
To balance the coefficient matrix in the previous linear system, the last row is scaled by -------- :
2
βh
ˆ T
–e1
M Φ q ∂q·· =
e2 (53)
Φ q 0 ∂γ – --------2-
βh
The correction at iteration k is then applied as:
(k + 1) (k) k
q·· = q·· + δq·· (54)
INTEGRATOR 221
C++ Statements
(k + 1) (k) k
λ = λ + δλ (55)
(k + 1) (k + 1) ··( k + 1 ) and equations (41)

and the corresponding q and q· are computed using the new value q
and (42), respectively.
The role of the corrector is to calculate the quantities q ·· and λ at the new time step tn+1. After these
quantities are computed the accuracy of the results at the current step is verified against the user-specified
error tolerance. If the local integration error is less than the user-specified error the integration step is
accepted; otherwise, it is rejected and a new smaller step size is tried.
For more information on error-estimation step-size selection and corrector-stopping criteria, refer to
Simcompanion Knowledge Base Article KB8016154
Remarks:
 The following explains how the HHT and Newmark integrators are more efficient than the default
GSTIFF integrator:
1. The most time-consuming part of simulation is the computation of the Jacobian associated with the
nonlinear discretization system. The HHT integrator contains heuristics to reduce the number of
Jacobian evaluations as much as possible. Unlike the BDF integrator, where terms of the integration
Jacobian can become disproportionately large as a result of a scaling by the inverse of the step-size, the
HHT integrator employs a different approach, where certain values are multiplied (never divided) by
the step-size before populating the Jacobian. As long as the step-size does not change dramatically,
this approach better supports the recycling of the Jacobian over several consecutive time-steps.
2. When compared with the BDF-based approach, the resulting HHT Jacobian is numerically better
conditioned, which leads to more reliable corrections in the Newton-like iterative approach for large
problems. Typically, at each integration step, this results in a smaller number of corrector iterations.
In addition, because certain partial derivatives are scaled by the step-size, or the square of the step-size
before populating the Jacobian, small errors in the partial derivatives computation will have a lesser
negative effect on the overall quality of the Jacobian.
3. The BDF formulas of order higher than 1 contain regions of instability in the left plane. The higher
the order, the smaller the region of stability. In addition, BDF is intrinsically designed to maximize
the order and step-size of the integration. Because of these two conflicting attributes, particularly for
models that are mechanically stiff (models with stiff springs, flexible bodies), there are many instances
when a order/step-size choice puts the BDF integrator outside the stability region. These integration
time-steps are typically rejected, and smaller step-sizes are required to advance the simulation. This is
not an issue with the HHT integrator, which is a fixed low order method (second order for HHT,
mostly first order for Newmark).
4. The HHT is a one-step integration formula that further gives it a small edge over multi-step methods,
such as high-order BDF-type integrators.
222 Adams Solver
C++ Statements
 In the HHT, the α coefficient can assume any value in the range -0.3 < α < 0. Once a value is
selected, the β and γ coefficients of equations (38) and (39) are computed as:
2
1 – 2α (1 – α)
γ = ---------------- β = --------------------
2 4
 The Newmark method effectively sets α = 0 and then you are responsible for defining values for β
and γ that satisfy equations (41) and (42). Typical values are γ = 0.7 and β = 0.36.
 The priority of the HHT and Newmark integrator is speed rather than accuracy. If accuracy is of
concern, the current integrators available in Adams historically are very accurate and serve the
purpose well.
 The HHT and Newmark error control for DIFF, TFSISO, LSE, and GSE elements is significantly
more lax than the one carried out for these elements by the other integrators available in Adams
Solver (C++) (such as GSTIFF, WSTIFF, and so on). This is related to the nature of the HHT and
Newmark integration formulas, which deal exclusively with second-order differential equations. To
have these formulas accommodate DIFF's for example, these are first converted from first- into
second-order differential equations. The consequence of this transformation is that error control is
now performed on the integrals of the DIFF states, rather than on the actual states. As far as
smoothness is concerned, it is well known that an integral of a quantity is better behaved than the
quantity itself. Consequently, the HHT and Newmark integrators are typically more optimistic in
selecting integration step-sizes. While these step-sizes are fine for the level or error induced in the
integral of the DIFF's, sometimes they are too aggressive, which negatively reflects to the quality of
the actual states associated with the DIFF's. HHT and Newmark in the current implementation are
not recommended for models whose time evolution (or behavior) is dominated by elements, such as
DIFF, TFSISO, LSE, or GSE.
 The default ERROR for HHT and Newmark is 1.E-5. This tighter default value is intended to
counterbalance the different step-size selection strategy employed by these integrators, and can be
regarded as a calibration procedure. The goal is that working with the corresponding default values
of the ERROR attribute both the HHT and GSTIFF integrators will produce results of similar
quality.
Note that the default integrator in Adams Solver (C++) is GSTIFF, and, therefore, the default
ERROR associated with a simulation is 1.E-3. GSTIFF and ERROR=1.E-3 are the settings that are
provided to the solver if in the .adm file you do not explicitly sets these attributes through the
INTEGRATOR statement.It is important to understand that under these circumstances, if you later
change the integrator to HHT through a command issued in the .acf file, unless the command
explicitly specifies otherwise, the ERROR value of 1.E-3 (associated with GSTIFF) will be inherited.
The correct command to issue would be INTEGRATOR/HHT, DEFAULT, if the goal were to run
HHT with its default ERROR setting, that is ERROR=1.E-5. Learn more in the INTEGRATOR
command.
INTEGRATOR 223
C++ Statements
Benefits of the HHT and Newmark Integrators Limitations of the HHT and Newmark Integrators
 Because of the reduced order, the
 Expected to result in a smaller number of acceleration and reaction forces obtained
Jacobian evaluations. with this I3 formulation are going to be
 Unlike BDF-type formulas, behaves like a more spiky.
low pass filter; it cuts high frequency  The numerical damping associated with
spurious oscillations, while accurately HHT is smaller than the one produced by
preserving low frequency oscillations. BDF integrators used by the GSTIFF
 Can control the cutoff frequency by family.
adjusting α ; the smaller value (that is,  If a BDF-based integrator manages to run a
closer to -0.3, the lower the cutoff simulation at order 4 or higher, it will take
threshold). step sizes significantly larger than HHT.
 Stable at small value of the integration step This is because HHT is a low-order
size. integrator and it needs to limit the step size
based on accuracy characteristics.
References
1. H. M. Hilber, T. J. R. Hughes, and R .L. Taylor. Improved numerical dissipation for time integration
algorithms in structural dynamics. Earthquake Eng. and Struct. Dynamics, 5:283292, 1977.
2. D. Negrut. On the implementation of HHT and Newmark integrators in MSC.ADAMS. Knowledge
Base Article KB8016154.
3. N. M. Newmark. A method of computation for structural dynamics. Journal of the Engineering
Mechanics Division, ASCE, pages 6794, 1959.
HASTIFF
y'
J = hβF y + F y'
 M – hβS u 1 T 1
hβ ( M ( q, t )u' + Φ q ψ' – S ( q, u, t ) ) q
T
Φq 0
 
 T T 
( – hβI ) I – hβ ( Φ q χ' ) q 0 –Φq
=  
y', HA
J
 
 0 Φq 0 0 
 
 Φq ( Φ q u ) q + Φ q, t 0 0 
T T T T T
y= (u q ψ χ )
224 Adams Solver
C++ Statements
 Mu' + Φ Tq ψ' – S 1 ( q, u, t )
 
 T 
 q' – u – Φ q ψ' 
F ( y, y', t ) =  1-
 = 0
 ----- Φ ( q, t ) 
 hβ 
 
 1- 
----- ( Φ q u + Φt )
 hβ 
solving for y’ (y discretized as a function of y’):
y n + 1 = φ ( y n, ..., y n – k ) + hβy' n + 1
F ( φ + hβy', y', t ) = 0
HASTIFF is the integrator in Adams Solver (C++). It is a variable-order, variable-step, multi-step integrator
with a maximum integration order of six. The BDF coefficients it uses are calculated by assuming that the
step size of the model is mostly constant.
Characteristics of HASTIFF(Hiller - Anantharaman ) integrator
1. Lagrange Multipliers appear in their differential form .
2. Solving for y ', instead of y (y is discretized as a function of y')
3. The constrained are scale by 1/h1. β (h=steps-size, β is the BDF coefficient that multiplies y’).
4. The formulation is Stabilized Index-1: an index-1 formulation is preferable because it’s more stable
numerically, hence it potentially allows for bigger and fewer steps to reach the end-time.
5. Stabilized Index-1 (SI1) and Stabilized Index-2 (SI2) are available for HASTIFF. SI1 is the default
for HASTIFF.
The I1(Hiller - Anantharaman index -1 ) Formulation
Characterstics of index -1 formulation.
1. Ensures that the solution satisfies all both position and velocity constraints.
2. Does ensure that the velocities and accelerations calculated satisfy all first- and second-time
derivatives.
3. Monitors integration error only in system displacements and velocities.
4. Is as fast as GSTIFF SI-2.
5. The Jacobian matrix *cannot* become ill-conditioned even at small step sizes
See the theory of HASTIFF
Error in Handling Simulations

The following sections include descriptions and workarounds for common error conditions you might
encounter during a simulation. The sections include:
INTEGRATOR 225
C++ Statements
 Integration Failures
 Corrector Failures
 Integration Restarts
 Singular Matrices and Symbolic Refactorization
Integration Failures
An integration failure is the condition when the integrator calculates a solution, but then rejects it because it
does not meet the accuracy requirements you specified. Because all integrators attempt to take the largest time
step possible, failure is a fairly routine occurrence and is not cause for concern. Integrators can automatically
decrease the step size and/or integrator order and repeat the step. Integration failures in multi-step methods
are caused when the predictor and corrector lead to vastly different configurations. Such a situation can occur
often when a force is suddenly turned on or off, thus, causing a discontinuity in the solution. For this reason,
past values are not a good indicator of current values. The following tips can help you avoid integration
failure:
 When modeling, be sure that all motion inputs, user-defined forces, and user-written differential
equations are both continuous and differentiable. The smoother a function is, the easier it is to
integrate. Always use a STEP or, better yet, the STEP5 function to switch a signal on or off, instead
of using IF logic.
 Remember that cubic SPLINEs can only guarantee second-order differentiability. Inputting a
SPLINE through a displacement-based MOTION causes accelerations to be spiky. Therefore, input
the SPLINE in a velocity-based MOTION.
 For greater simulation control, use HMAX to control the maximum step size that the integrator can
take. HMAX enables the integrator to reach higher orders and maintain them consistently.
 Be careful when using non-differentiable intrinsic functions, such as IF, MIN, MAX, SIGN, MOD,
and DIM. These functions can give discontinuous answers and can cause integrator problems. The
integration failure diagnostic identifies the variable and its parent modeling element with the largest
error. Examine the entities that connect to the parent modeling element to see if you can identify the
cause of the failure.
Corrector Failures
A corrector failure occurs when the Newton-Raphson iterations in the correction phase do not converge to a
solution. Corrector failure occurs if the predictor cannot provide a reasonable initial guess and the equations
themselves are not smooth, as the Newton-Raphson algorithm assumes. A corrector failure is a fairly severe
event that you should avoid by changing your model. Some tips to help avoid corrector failure are:
 As with preventing integrator failures, be sure that all motion inputs, user-defined forces, user-
written differential equations, and user-defined algebraic variables are both continuous and
differentiable. The smoother a function is, the easier it is to solve for it. Use a STEP or STEP5
function to switch a signal on or off instead of using IF logic.
 Use the ERROR keyword to loosen the integration error. Loosening the value for ERROR also
decreases the tolerance that the corrector is required to meet.
 Use the SI2 formulation and see if the failures go away.
 Use the new corrector by setting CORRECTOR = MODIFIED.
226 Adams Solver
C++ Statements
Here are some diagnostic techniques for identifying the cause of some failures:
 Examine the EPRINT output from DEBUG to identify the modeling entities that are having the
greatest difficulty converging.
 If the modeling element is a force:
• Make sure that the force law it obeys is smooth.
• Examine the stiffness of the force entity. Reduce it if necessary to overcome the failures.
• Examine the damping of the force entity. Damping is usually less than 5% of the stiffness. Large
values of damping can also cause failures.
 If the modeling element causing the corrector failures is an equation of force/torque balance for a
PART, POINT_MASS, or FLEX_BODY, try to identify the entities that may be applying
anomalous forces on the body. Look at the accelerations of the body. A large acceleration in a certain
direction is always caused by a large force in that direction. Try to identify the modeling element
that is causing the large acceleration, examine how it is defined, and try to understand why it is
applying a large force.
 If the modeling element is a CONTACT, review the stiffness, damping, and frictional properties of
the contact. Reducing stiffness and damping helps. Similarly, increasing stiction and dynamic
friction transition velocities can help the integrator.
 If the modeling element is a FRICTION entity, increasing the stiction and dynamic friction
transition velocities usually helps. Evaluate the effect of reducing the friction coefficients and the
pre-load.
 If the modeling element is a DIFF or GSE, make sure that the derivatives you are defining have
reasonable values. Large derivatives cause problems. Make sure that the constitutive equations are
smooth (differentiable) and that they do not have any kinks.
 If the modeling element is a redundant constraint, this implies that Adams Solver is having difficulty
satisfying the constraint. The most likely cause for such a failure is an inconsistently defined or ill-
behaved model. Eliminate the inconsistency.
 If the modeling element is a constraint reaction, try to identify the applied force or torque that is
trying to break the constraint.
Integration Restarts
An integration restart is when the integrator fails to take a new step successfully. Adams Solver (C++)
calculates a new and consistent set of initial conditions at the point of failure and the solution progresses with
this new set of initial conditions. A restart occurs if the integrator encounters several consecutive integration
failures and/or corrector failures while attempting a new step. Integration restart is usually indicative of
discontinuous equations describing the system. To help avoid integration restart, you can:
 Increase ERROR value. Integration restarts sometimes occur simply because the value specified for
ERROR is too small.
 Identify modeling problems in your system. Typically, a single modeling element dominates an
integrator or corrector error. Identify that element and see why it may be causing problems.
Smoothen its definition if there is a function expression or user subroutine associated with it. For
more information on how to diagnose modeling problems, see Corrector Failures.
INTEGRATOR 227
C++ Statements
Singular Matrices and Symbolic Refactorization

A singular matrix condition occurs when the Jacobian matrix is not invertible. Recall that the corrector needs
to invert the Jacobian matrix during its iterations to solve a set of linearized algebraic equations. (See
Correction). A scalar analogy to a singular matrix is a divide-by-zero situation. Adams Solver (C++) does not
actually invert the matrix, but calculates the matrixs Lower and Upper triangular factors (LU factors). This
method of computation is very efficient and is equivalent to an inversion.
Given a Jacobian matrix, Adams Solver (C++) calculates and stores the LU factors in a symbolic form. In other
words, Adams Solver (C++) explicitly calculates the LU factors as a function of the values in the Jacobian
matrix. Adams Solver (C++) also assumes that the pivots are never zero. (Pivots are chosen during the
Gaussian elimination and are used to factorize the matrix.) Because the equations being solved are nonlinear,
it is likely that a set of pivots chosen earlier may not be optimal. Some of the pivots may become small or
even zero. This event is known as the singular matrix condition. When Adams Solver (C++) encounters this
condition, it recalculates the symbolic LU factors for the Jacobian matrix using the current values of the state
variables. This process is known as symbolic refactorization.
Occasional occurrences with singular matrices and symbolic refactorization are normal and are no cause for
alarm. However, if these events occur frequently, you should examine your model. The typical causes for
singular matrices are:
 A mass or inertia component is not specified.
 The system has reached a locked configuration, that is, it can no longer move without violating one
of its constraints.
 A large force or moment has been suddenly turned on or off.
 The integrator is forced to take an extremely small step because of a hidden discontinuity in an
element described in a user-written subroutine. IF statements, as well as non-differentiable intrinsic
functions, such as SIGN, MOD, MIN, MAX, and so on, can create non-differentiable or even
discontinuous descriptions of modeling elements. Be very careful when using these aspects of a
programming language.
The Index-3 Jacobian matrix (see Equation 6) contains some terms that are inversely proportional to the step
size being taken. As the step size shrinks, these terms grow larger. In fact, they grow so large that they eclipse
all other entries in the matrix. Computers typically have difficulty dealing with matrices that have entries
spanning a large range (matrices with large condition numbers). The smaller numbers consequently get lost
in round-off error, and, therefore, cause singular or ill-conditioned matrices to occur. The root cause for these
problems is that the step size is very small. The solution is to understand why the step size is so small, and
modify the model accordingly. Discontinuities are prime causes for problems related to small steps sizes.
Eliminating the discontinuities causes the integrator to take larger steps, and, therefore, avoid fatal singular
matrix condition. Using the SI2 formulation can also help solve this problem.
Choosing and Integration Error
The integration ERROR is a key parameter that you need to specify for a simulation. For calculating a
reasonable value for ERROR, we recommend that:
 For I3 formulation with GSTIFF and WSTIFF:
ERROR = VEPS *(6*Nb + 3*Np + Nu + 2*Nm)
228 Adams Solver
C++ Statements
 For SI2 formulation with GSTIFF and WSTIFF:

ERROR= K * VEPS * (12*Nb + 6*Np + Nu + 2*Nm)
where:
VEPS is the desired error per variable per integration step.
Nb is the number of rigid bodies in the model (excluding GROUND).
Np is the number of point masses in the system.
Nu is the number of user-defined differential equations in the system (DIFFs+LSEs+GSEs).
Nm is the total number of modal coordinates in the system:
• K =10 (for smooth problems).
• K =100 (for impact and friction problems).
 For HHT and Newmark integrators, use the error that you would use for GSTIFF but typically
scaled by a factor of 10-2.
All integrators require that you input a value, referred to as ERROR in the online help, that specifies the
degree of accuracy you want to achieve in a simulation. ERROR is the maximum error allowed per
integration step for the entire system. This can be confusing in Adams Solver (C++) because some of the
ERROR states are displacements, some are velocities, and others may be user-defined states (for example,
pressure, and temperature).
In Adams Solver (C++), integration ERROR is the difference between the exact solution f(t) and the
approximate solution p(t) being calculated. The difference, f(t)-p(t), is the truncation error.
For displacement variables, the truncation error has units of length. For velocities, the truncation error has
units of velocities. For example, if you are working in millimeters, your maximum error tolerance would be
smaller than 1 micron. Then, for each variable, you would have an error of 0.001 mm.
You find the error per step by estimating the total number of integration steps, and then dividing the error
per variable by the estimated number. Thus, if you estimate that you need 100 integration steps, the error per
step, VEPS, is 0.00001 mm. This is always a conservative calculation (sometimes too conservative) because
errors tend to be random and typically cancel each other out. The calculation shown earlier assumes the worst
case scenario, where the errors are always additive. You should use the information shown here as a guide, not
as a rule, for setting ERROR.
Velocities must be treated in the same way as displacements. However, keep in mind that the errors in the
derivatives are higher, and, if you impose an error on the velocities that are identical to the errors on the
displacements, you force a larger number of iterations per step to occur, which increases the simulation time.
In general, if an error-control exists on velocities, such as in SI2 and ABAM, then the errors computed for
the displacements can be increased by a factor of 10 and can also be applied for velocities.
Modal coordinates have small values, and, therefore, to be able to accurately capture their effects, you may
need to tighten the ERROR parameter. Typically, when the rigid body displacements and velocities are
accurate, then the modal coordinates and velocities are also fairly accurate.
INTEGRATOR 229
C++ Statements
Models with Discrete GSEs

Each integrator has a proprietary algorithm to select the next time step. Each algorithm selects the next time
step taking into consideration parameters set by the user (for example, HMAX), the proximity to an output
time step, integration error and so on. However, when a model has discrete GSE elements in it, the integrator
first computes a proposed time step and then reviews the sample periods of all discrete GSEs in the model. If
the proposed time step would set the system at a new time beyond a scheduled sample period, then the time
step is reduced so the system does not step beyond a sample period. In a case of the constant sample period,
the output step size (DTOUT) should be selected as an integer multiple of the sample period of the discrete
GSEs in the model for optimal solver performance.
Fixed Step Integrator Option

The fixed step option is introduced for the GSTIFF integrator supporting both the I3 and SI2 formulations
and for the HHT integrator. The purpose of the fixed step option is to ensure that a fixed amount of work is
completed in a given time to satisfy the requirements for a Linux real time operating system (RTOS). This is
achieved by limiting the number of Newton steps in the implicit solve (that is, number of corrector iterations
per integration time-step) to ensure a fixed amount of work is performed.
This option can be employed regardless of the environment; that is, it can be used also in non-RTOS scenario,
for example, to help determine ahead of time if a given analysis can be suitable for real-time simulation and
if the results will be acceptable. The fixed step option will be employed 'only' when the user specifies FIXIT.
It should be noted that the integration step size remains 'constant' or 'fixed' throughout the simulation when
the fixed step option is selected. The combination of DTOUT and HRATIO settings specifies the integration
step size as shown in the following figure:
 The dependencies of the other INTEGRATOR statement/command arguments when FIXIT is

specified are as follows:
 MAXIT will be ignored
 ERROR will be ignored
 INTERPOLATE will be ignored and always treated as though it is set "OFF"
 HINIT can still be specified, but if set >DTOUT/HRATIO then Adams Solver will reset it =
DTOUT/HRATIO
 HMIN will be ignored
 HMAX can still be specified but will be ignored if less than DTOUT/HRATIO
 KMAX can still be specified but will have no effect since the fixed step GSTIFF always runs with
K=1 and HHT always runs with K=2. So, in effect we have a fixed step and fixed order integrator
230 Adams Solver
C++ Statements
 CORRECTOR type will have no effect

 PATTERN can still be specified; note that default for GSTIFF remains T:F:F:F:T:F:F:F:T:F. This is
suitable for values of FIXIT less than or equal to 4. If larger values of FIXIT are necessary one may
want to consider setting PATTERN = T:F:F:F:F:F:F:F:F:F so as to avoid the time consuming
Jacobian re-evaluation during newton iterations for real-time performance. Adapative Jacobian
evaluation (that is, PATTERN = F) is not supported in the fixed step integrator as it does not
guarantee the fixed amount of work per time step. Note that the default pattern for HHT is changed
to T:F:F:F:T:F:F:F:T:F when the fixed step option is selected.
Suggested modeling practices with the fixed step integrator:
Discontinuities in Adams Solver, especially in the 0th and 1st derivatives, whether from function expressions
or from user-written subroutines, etc. are common source of solution failures even using the traditional
variable step integrators. Problems with discontinuities will likely be exacerbated when using the fixed step
integrator. Below is a list of suggested modeling practices in this regard:
 Do not use non-holonomic constraints
 Manually remove/resolve redundant constraints as opposed to letting Adams Solver automatically
remove these
 Scrutinize any IF statements in function expressions and, if they cause discontinuities, replace them
with STEP functions
 Consider analytic type alternatives to any surface-surface contacts
 Check the damping specifications in CONTACT and IMPACT elements against units. Strongly
consider avoiding damping penetration distances that are <0.001 length unit and damping values
that are >.01 * stiffness values.
 Avoid velocities which oscillate around zero. This can be common in certain kinds of friction
scenarios as well as bringing vehicle models to a stop
Handling sensors, contacts and discrete GSEs with the fixed step integrator:
The fixed step integrator supports the contact, sensors and the discrete GSEs. However, it does not honor any
step size change requests coming from these elements. The user should choose the constant step size (using
DTOUT and HRATIO combination) carefully when the model contains one of these elements. The discrete
GSE states will be updated every time step. For example, when Adams Smart Driver is used it is the user's
responsibility to select the 'fixed' step size such that it will be smaller than (or equal to) the discrete GSE (in
this case, 'SamplePeriod' in the driver control file).
Amplification of initial transients with the fixed step integrator:
Users should take extra care with models exhibiting initial transients in their results from the traditional
variable step integrators. If the model/event is not corrected to eliminate such initial transients they may very
likely be amplified when running the model with the fixed step integrator. Even relatively small amplitude
initial transients in the variable step integrator which a user might not deem important enough to worry
about normally can become amplified and problematic in the fixed step integrator.
Integrator restarts with the fixed step integrator:
It should be noted that the fixed step integrator option does not support 'integrator restarts.' This is done
intentionally to avoid the extra amount of computation associated with integrator restarts and also to
INTEGRATOR 231
C++ Statements
guarantee the fixed amount of work per integration time step. Integrator restarts are generally caused by i.
Singular or ill-conditioned Jacobian, ii. Discontinuity in forces, iii. Sensors forcing the integrator restart, or iv.
Euler Singularity. Ideally the user should avoid all these conditions when the fixed step integrator option is
selected. Note that the Euler singularity case is supported in the fixed step integrator option without forcing
an integrator restart.
Real Time Index (RTI) reporting with the fixed step integrator:
When using a fixed step integrator, Adams Solver (C++) will print (in both the message file and the display)
a report about the Real Time Index (RTI) measured during the dynamic simulations. The Real Time Index
is defined as the ratio t_elapsed to t_step where,
t_elapsed = wall time required by Adams Solver (C++) to step the system a single time step.
t_step = time step requested by the controller code (or set by the DOUT/HRATIO options).
A value for the RTI less than 1.0 means Adams Solver (C++) was able to step the system fast enough in a real
time environment. The printed report includes a heading with the following information:
a. The name of the fixed step integrator being used.
b. The time units of the model.
c. The HRATIO used in the INTEGRATOR statement or command.
d. The size of the time step requested in both user's units and in seconds.
e. The requested frequency in Hz.
f. The number of degrees of freedom of the model during simulation.
The report also includes:
a. The value of the minimum measured RTI during the simulation. The reported value includes the
corresponding frequency and the simulation time when this minimum value was measured.
b. The value of the average measured RTI for all the simulation and corresponding frequency.
c. The value of the largest measured RTI during the simulation. The reported value includes the
corresponding frequency and the time when this largest value was measured.
By default, the RTI report excludes the value the first-step RTI. The first-step RTI is typically larger than all
subsequent RTIs because it has the overhead of data initializations. This behavior is standard in all real time
systems but it is of no concern given that real time simulations usually begin with trivial maneuvers before
the actual simulation of interest begins. The value of the first RTI can be included in the report by adding
the option FIRSTRTI in the value of the environment variable MSC_ADAMS_REAL_TIME.
Note: When setting the environment variable MSC_ADAMS_REAL_TIME=ON, all messages and all
results are turned off by default. If you would like to get the RTI report without generating
message files, add the option TIMING as follows:
MSC_ADAMS_REAL_TIME=ON/TIMING
232 Adams Solver
C++ Statements
An example output is as follows:

--------------------------------
Real Time Index (RTI) statistics
--------------------------------
Integrator name : Fixed Step GSTIFF/I3
Time units : s (seconds)
HRATIO : 2
Time step : 5.00000e-02 s
Requested frequency : 100.00 Hz
ndof : 116
Minimum RTI index : 0.29999 (333 Hz) (at time 2.000000e-02 s)

Average RTI index : 0.38838 (257 Hz)
Maximum RTI index : 0.60001 (166 Hz) (at time 3.000000e-02 s)
Notes:
1. Minimum, Average and Maximum RTI are computed after the first integration
step.
2. The frequency (Hz) is measured as the inverse of the time (seconds)
required to step one whole step.
3. A zero RTI was detected. This is a limitation of the OS granularity in
measuring CPU time.
Notes: Setting the environment variable MSC_ADAMS_SOLVER_INTERPOLATE_ADAPTIVE

enforces Adams Solver to use a different output block generation. The scheme works as
follows:
 Instead of generating an output block at each requested interval provided in the

SIMULATE/DYNAMICS command, Adams Solver ignores the request of generating
equally spaced output blocks and generates an output block at any integration step past the
request interval. The end result is that Adams Solver generates output blocks at unequally
spaced times.
 Using this setting, the solver does not need to reduce the current time step in order to hit a
requested output block. Instead, it leaps over and prints an output block as soon as a
request output block was suggested. In some cases, the solver may leap over more than one
requested output blocks. The main benefit is speed performance. The main drawback is
that output blocks are not equally spaced.
INTEGRATOR 233
C++ Statements
Tip: GSTIFF and WSTIFF control errors specifically in displacements and user-defined
differential variables, and, therefore, yield acceptable accuracy in velocity, acceleration, and
force results. In some cases, however, the acceleration and force results may not be acceptable,
even when ERROR is set appropriately and the displacement results are accurate. In these
cases, use the HMAX argument to directly limit the size of the integration steps.
Using the PATTERN argument to request more frequent evaluations of the Jacobian matrix
can improve convergence rates. This can also increase the computation time.
For kinematic (zero-DOF) systems, a kinematic analysis is usually faster and less expensive
than a dynamic analysis. To force the integration of a kinematic system, use GSTIFF,
WSTIFF, HHT, or Newmark.
Caution: GSTIFF, HHT, and Newmark may introduce discontinuities in velocities and accelerations
when the integration step size changes. Most of the time, these discontinuities are within the
error tolerance and disappear quickly. The use of the INTERPOLATE argument can
sometimes eliminate these discontinuities. Alternatively, you can control the step size using
the HMAX argument, which helps make the step sizes nearly constant.
The HHT integrator is incompatible with restitution (POISSON) contact.
Examples
 INTEGRATOR/SI2, GSTIFF, ERROR=1.0E-4, HINIT=1.0E-6
This integrator statement specifies that dynamic simulations be run using the SI2 equation
formulation combined with the GSTIFF integrator.
• This solution has an error limit of 1.0E-4.
• The integrator is to take an initial step of 1.0E-6.
 INTEGRATOR/HHT, ERROR=5.0E-6, PATTERN=F, HMAX=1e-3
This integrator statement specifies that dynamic simulations be run using the HHT integrator with
the adaptive jacobian pattern.
• The maximum step size the integrator is to take is 1.0E-3.
 INTEGRATOR/GSTIFF, I3, FIXIT =3, HRATIO = 4, MAXERR = 0.5
This integrator statement specifies that dynamic simulations be run using the fixed step integrator
(GSTIFF-I3) option.
• The number of corrector iterations per time step is 3 throughout the simulation.
234 Adams Solver
C++ Statements
• The ratio of DTOUT (output step size) to H (integration step size) is 4 throughout the
simulation.
• The simulation will be stopped if the integration local error exceeds 0.5
JOINT 235
C++ Statements
JOINT
The JOINT statement describes a physically recognizable combination of constraints that are used to connect
bodies (rigid and flexible) together. Examples of joints include constant-velocity, cylindrical, fixed, Hooke,
planar, rack-and-pinion, revolute, screw, spherical, translational, and universal joints.
Format
236 Adams Solver
C++ Statements
Arguments
CONVEL Indicates the joint is a two-degree-of-freedom joint that allows rotation about two axes:
the zi and zj axes (see the figure below).
For the CONVEL joint, Adams Solver (C++) superimposes the origins of the I and J
markers and constrains the rotation about the z-axis of the I marker to be equal and
opposite to the rotation about the z-axis of the J marker. When connecting two shafts,
the z-axes of the I and J markers should point down the shafts, away from the center
of the joint. Additionally, the angle between the x-axis of the I marker and the y-axis
of the J marker must be the same as the angle between the y-axis of the I marker and
the x-axis of the J marker. The easiest way to ensure the x and y axes are properly
aligned is to make the I and J x-axes parallel, or the I and J y-axes parallel.
Convel Joint
CYLINDRICAL Indicates that the joint is a two-degree-of-freedom joint that allows both relative
translational and relative rotational displacement of one part with respect to another
(see the figure below). I marker translation along the zj axis and rotation about the zj
axis are permitted.
For the CYLINDRICAL joint, Adams Solver (C++) keeps the z-axis of the I marker
parallel to, and co-directed with, the z-axis of the J marker and confines the origin of
the I marker to the z-axis of the J marker so that the I and J markers have a common
z-axis. To determine translational motion, Adams Solver (C++) measures the
movement of the origin of the I marker along the z-axis and with respect to the J
marker. To determine rotational motion, Adams Solver (C++) measures the rotation of
the x-axis of the I marker about the common z-axis and with respect to the x-axis of
the J marker.
JOINT 237
C++ Statements
Cylindrical Joint
FIXED Indicates the joint is a zero-degree-of-freedom joint that completely locks the I and J
markers together (see the figure below).
For the FIXED joint, Adams Solver (C++) superimposes the origins and the axes of the
I and J markers, allowing no relative motion.
Fixed Joint
HOOKE Indicates the joint is a two-degree-of-freedom joint that allows rotation about two axes:
xi, the x-axis of the I marker and yj, the y-axis of the J marker (see the figure below).
For the HOOKE joint, Adams Solver (C++) superimposes the origins of the I and J
markers and constraint markers. It also keeps the x-axis of the I marker perpendicular
to the y-axis of the J marker so they outline the crosspiece of the joint. The origins of
the I and J markers are at the center of the cross. The HOOKE joint functions the same
as the universal joint, but uses different marker orientations.
238 Adams Solver
C++ Statements
Hooke Joint
I=id, J=id Specifies the identifier of one fixed marker in each part the joint connects. Adams
Solver (C++) connects one part at the I marker to the other at the J marker.
IC=r1,r2 Defines the initial conditions you want to impose on either a translational or revolute
joint. The value r1 is the velocity of the I marker with respect to the J marker as seen
by the J marker. The value r2 is the displacement of the I marker with respect to the J
marker. Adams Solver (C++) measures both the rotational velocity and the rotation of
the x-axis of the I marker about the common z-axis of the I and J markers with respect
to the x-axis of the J marker.
The IC argument imposes a constraint that is active only during initial conditions
analysis (not at the time of the initial configuration). Adams Solver (C++) does not
impose initial conditions during subsequent analyses. If the IC argument imposes
initial conditions on the joint that are inconsistent with those on one of the bodies the
joint connects, the initial conditions on the joint have precedence over those on the
body.
For the initial conditions for a translational joint, velocity is in units of translational
displacement per unit of time and displacement is in units of length. For the initial
conditions for a revolute joint, velocity is in radians per unit of time and displacement
is in radians.
JOINT 239
C++ Statements
ICROT=r1,r2 Defines the rotational initial conditions you want to impose on a cylindrical joint.
The value r1 is the angular velocity of the I marker with respect to the J marker (in
radians per unit of time).
The value r2 is the rotation of the I marker with respect to the J marker (in radians).
Adams Solver (C++) measures both the rotational velocity and the rotation of the x-
axis of the I marker about the common z-axis of the I and the J markers with respect
to the x-axis of the J marker.
The ICROT argument imposes a constraint that is active only during initial conditions
analysis (not at the time of the initial configuration). Adams Solver (C++) does not
impose initial conditions during subsequent analyses.
If the ICROT argument imposes initial conditions on the joint that are inconsistent
with those specified on one of the bodies the joint connects, the initial conditions on
the joint have precedence over those on the body.
ICTRAN=r1,r2 Defines the translational initial conditions you want to impose on a cylindrical joint.
The value r1 is the translational velocity of the I marker with respect to the J marker
(in units of length per unit of time). The value r2 is the translation of the I marker with
respect to the J marker (in units of length). Adams Solver (C++) measures both
translational velocity and translation at the origin of the I marker along the common
z-axis of I and J and with respect to the J marker.
The ICTRAN argument imposes a constraint that is active only during initial
conditions analysis (not at the time of the initial configuration). Adams Solver (C++)
does not impose initial conditions during subsequent analyses.
If the ICTRAN argument imposes initial conditions on the joint that are inconsistent
with those specified on one of the bodies the joint connects, the initial conditions on
PD=r Pitch diameter (PD) defines the pitch diameter of the pinion gear of a rack-and-pinion
joint. The pitch diameter relates the rotational motion of the pinion to the
translational motion of the rack. When the pinion turns in the positive direction
around the z-axis of the I marker, a positive pitch diameter moves the rack in the
positive direction along the z-axis of the J marker and a negative pitch diameter moves
the rack in the negative direction along the z-axis of the J marker.
PITCH=r Defines the translational displacement of a screw joint that corresponds to one
revolution of its rotational displacement. A positive pitch creates a right-hand thread,
and a negative pitch creates a left-hand thread.
240 Adams Solver
C++ Statements
PLANAR Indicates that the joint is a three-degree-of-freedom joint that allows a plane of one
part to slide on a plane on a second part (see the figure below). The x and y axis of the
I and J markers of the joint define the planes on the two parts.
For the PLANAR joint, Adams Solver (C++) constrains the z-axis of the I marker so
that it remains parallel to, and co-directed with, the z-axis of the J marker and does not
allow the linear displacement with respect to the J marker to have a z component.
Planar Joint
JOINT 241
C++ Statements
RACKPIN Indicates that the joint is a five-degree-of-freedom joint that constrains the rotational
displacement of the I marker to the translational displacement of the J marker and
measures both displacements with respect to the J marker. The I marker is at the center
of the pinion, and the J marker is in the rack. The figure below illustrates a rack-and-
pinion joint.
For the RACKPIN joint, the z-axis of the pinion must be parallel to and co-directed
with the x-axis of the rack. The separation between the two axes should be one-half the
pitch diameter of the pinion. The rack-and-pinion joint itself does not enforce the
position and orientation it requires, but the chain of both parts and joints that
connects markers I and J should enforce the position and orientation. A common
approach for enforcing the position and orientation is to support the rack with a
translational joint and to support the pinion with a revolute joint.
During simulation, the I marker displacement parallel to the J marker z-axis is a

function of the angle between the I marker x-axis and the J marker z-axis. Adams Solver
(C++) measures a positive rotation according to the right-hand rule. For every full
rotation, the distance the I marker moves parallel to the z-axis of the J marker is equal
to the value of PD times p. The direction the I marker moves depends on the sign of
PD. For a positive PD and positive rotation, the I marker moves in the negative
direction along the z-axis of the J marker (and the J marker moves in the positive
direction).
Rack and Pinion Joint (PD > 0)
REVOLUTE Indicates that the joint is a single-degree-of-freedom joint that allows rotation of one
part with respect to another about a common axis denoted as zi,j in the figure below.
For the REVOLUTE joint, Adams Solver (C++) superimposes the origins of the I and
J markers and keeps their z-axes parallel. Relative motion occurs about the common z-
axes.
242 Adams Solver
C++ Statements
Revolute Joint
SCREW Indicates that the joint is a five-degree-of-freedom joint that constrains the translation
of the I marker to its rotation (see the figure below).
For the SCREW joint, the z-axis of the I marker and the z-axis of the J marker must
always be parallel and co-directed. Although the SCREW joint does not enforce this
parallelism, the chain of parts and joints that connects the two markers should. During
simulation, the I marker displacement along the J marker z-axis is a function of the
relative angle of the x-axis of the I marker with respect to the x-axis of the J marker.
Adams Solver (C++) measures a positive rotation according to the right-hand rule. For
every full rotation, the displacement of the I marker along the z-axis of the J marker is
equal to the value of PITCH. If is zero, the translational displacement may be zero
or any multiple of PITCH.
Screw Joint
JOINT 243
C++ Statements
SPHERICAL Indicates that the joint is a three-degree-of-freedom joint (see the figure below).
While permitting all three rotations, a SPHERICAL joint constrains the origins of the
I and the J markers to always be superimposed.
Spherical Joint
244 Adams Solver
C++ Statements
TRANSLATION Indicates that the joint is a single-degree-of-freedom joint that allows translational
AL displacement of one part relative to another along the common z axes, zi and zj, as
shown in the figure below.
For the TRANSLATIONAL joint, Adams Solver (C++) keeps the axes of the I and the
J markers parallel and co-directed, and keeps the origin of the I marker on the z-axis
of the J marker so that the two markers have a common z-axis. To determine the
translational displacement of the I marker with respect to the J marker, Adams Solver
(C++) measures the origin of the I marker with respect to the origin of the J marker
along their common z-axis.
Translational Joint
JOINT 245
C++ Statements
UNIVERSAL Indicates a two-degree-of-freedom joint that rotates about two axes: the z-axis of the I
marker and the z-axis of the J marker (see the figure below).
For the UNIVERSAL joint, Adams Solver (C++) superimposes the origins of the I and
J markers and keeps their z-axes perpendicular, so they outline the crosspiece of the
joint. The origins of the I and J markers are at the center of the cross. The
UNIVERSAL joint functions the same as the HOOKE joint, but uses different marker
orientations.
Universal Joint
Extended Definition
The JOINT statement describes a physically recognizable combination of constraints such as constant-
velocity, cylindrical, fixed, Hooke, planar, rack-and-pinion, revolute, screw joints, spherical, translational,
and universal (see the figure on the Summary of Joints and the table on joint constraints that follows).
Summary of Joints
246 Adams Solver
C++ Statements
Joint Constraints
Removes Removes Rotational Removes Total

This type of Joint: Translational DOF: DOF: Number DOF:
Constant Velocity 3 1 4
Cylindrical 2 2 4
Fixed 3 3 6
Hooke 3 1 4
Planar 1 2 3
JOINT 247
C++ Statements
Removes Removes Rotational Removes Total

This type of Joint: Translational DOF: DOF: Number DOF:
Revolute 3 2 5
Screw 0.5* 0.5* 1
Spherical 3 0 3
Translational 2 3 5
Universal 3 1 4
The reaction force on Part A always acts at the I marker. The reaction force on Part B acts at the instantaneous
location of the I marker; that is, the point of application may vary with time. The reaction force on Part B is
always equal and opposite to the reaction force on Part A.
 Joints can be superimposed. Because a joint connects exactly two parts, you can include a part
between any two joints you superimpose. In general, if combinations of constraints are to be defined
other than those available with the JOINT statement, it is usually simpler to define these
combinations with the JPRIM statement.
 The spherical joint that a JOINT statement imposes is identical to the atpoint joint that the JPRIM
statement imposes.
 In general, the GEAR statement is easier to use than the JOINT statement to define a rack-and-
pinion joint. In addition, the GEAR statement is more accurate. The current RACKPIN joint
applies a parasitic rotational force to the rack part. For some models the parasitic rotational force
could cause inaccurate results. Learn more about the GEAR statement.
 The UNIVERSAL and HOOKE joints function identically. One may be more convenient to define
than the other, however, depending on the data you have available. If the joint is initially straight,
for instance, the HOOKE joint may be defined by two identical markers.
 Functionally, the constant-velocity joint is similar to the UNIVERSAL and HOOKE joints.
Connecting two shafts with a constant-velocity joint ensures that the shafts always spin at the same
rate, however, unlike the UNIVERSAL and HOOKE joints which cause some fluctuation as the
joint bends.
248 Adams Solver
C++ Statements
JOINT 249
C++ Statements
Caution:  The two markers that define a joint must be in two different parts.
 Be careful when defining UNIVERSAL and HOOKE joints. In an actual universal
joint, if the spin axis of either part comes into alignment with either rotational axis of
the joint, the joint can no longer transmit rotational motion. The figure below shows
a universal joint in this singular position.
Universal Joint in the Singular Position
In Adams Solver (C++), the singular position allows the universal joint to spin freely
and usually causes simulation failure.
 Be careful when defining CONVEL joints. Whenever the z-axes of the I and J
markers in a CONVEL joint become colinear and codirected, the joint is in a singular
position. The behavior of the CONVEL joint in the singular position is unpredictable
and may be incorrect.
 The screw joint relates the rotational motion of the I marker to the translational
motion of the I marker and measures both motions with respect to the J marker.
However, the screw joint does not model the backlash or slope that may occur in
actual screw joints.
 For both the rack-and-pinion and screw joints, Adams Solver (C++) positions the I
and J markers at the nearest pitch-multiple position that satisfies the constraint.
Examples of pitch multiples of a joint with a pitch value of 2.5 include -5.0, -2.5, 0.0,
2.5, 5.0, and so on. Therefore, you should ensure that the part, marker, and joint
information that contributes to the initial positioning of the I marker with respect to
the J marker correctly describes the initial position of the I marker.
250 Adams Solver
C++ Statements
 If the initial conditions are inconsistent with other conditions in the system, Adams
Solver (C++) varies the part initial positions through an iterative process to correct the
inconsistencies and then begins the simulation.
 Use caution when using the initial conditions arguments (IC, ICTRAN, ICROT)
with a MOTION statement on the same joint. If the MOTION statement and the
initial conditions argument(s) specify motion for the same degree of freedom, Adams
Solver (C++) uses the MOTION statement, ignores the initial conditions argument,
and issues a warning message.
 If the initial rotational displacement of a revolute or cylindrical joint (as specified by
the IC or the ICROT argument on the JOINT statement or by a MOTION
statement) varies by 5 to 60 degrees from the initial configuration of the joint as
indicated by the input positions of the two parts constituting the joint, Adams Solver
(C++) issues a warning message and continues execution. If the variation is greater
than 60 degrees, Adams Solver (C++) issues an error message and stops execution.
 The initial conditions arguments impose constraints that are active only during initial
conditions analysis. Adams Solver (C++) does not impose these initial conditions
during subsequent analyses.
 For a kinematic analysis, the initial conditions are redundant. Do not use initial
condition arguments on the JOINT statements for systems with zero degrees of
freedom.
 Adams Solver (C++) checks whether axes that are constrained to be parallel or
perpendicular are actually close to parallel or perpendicular as input in the dataset. If
you input joint markers such that constrained axes are misaligned by more than 5
degrees, Adams Solver (C++) issues a warning but continues the simulation. If you
misalign constrained axes by more than 60 degrees, Adams Solver (C++) issues an
error and stops the simulation. You may input unconstrained axes in any position. In
a REVOLUTE joint, for example, Adams Solver (C++) issues a warning if the angle
between the z-axes of the I and J markers is greater than 5 degrees, and an error if the
angle is greater than 60 degrees. The x-axes, however, may be at any angle.
JOINT 251
C++ Statements
 In the Adams Solver (C++) any joint can be attached to a marker on a flexible body,
thereby lifting restrictions in the Adams Solver (FORTRAN). Joints, however, which
do not keep the I and J markers coincident require special consideration when the J
marker is on a flexible body. In general, joint reaction forces only act on flexible
bodies at the marker attachment. If the joint permits the markers to move relative to
each other, the offset between the markers is treated as a rigid lever. That is, a reaction
force-moment pair (Fi, Mi) at marker I will cause a reaction force-moment pair (Fj,
Mj) at marker J according to:
Fj = -Fi
Mj = -Mi - r x Fi
Where r is the instantaneous position vector from marker J to marker I.
For example, an I marker on a part which is constrained by an cylindrical joint to
move on thez axis of a J marker on a flexible body should not be considered to be
sliding over the surface of the flexible body because the true effect of the joint is that
of a part sliding on a rigid rod which is welded to the flexible body at the location of J.
 Some JOINT elements purport to align marker axes so that they are parallel and point
in the same direction. In actuality, the JOINT only guarantees that the axes are either
parallel or anti-parallel (pointing in the opposite direction). Because the parallel
orientation is verified during model input, and because markers are very unlikely to
instantaneously to flip by 180 degrees, the likelihood of anti-parallel axes has been
very low. However, with the advent of curve-markers, which will experience an
orientation flip when passing through an inflection point, the situation has become a
possibility.
Although it would have been possible to forbid anti-parallel assembly of JOINT axes
and enforce this at run-time, the overhead of such checking would not be justifiable,
given the low probability of the occurrence. Furthermore, because the only recourse
would be to stop the simulation, it is not clear that this check would be very useful.
If the user requires that two axes (for example, the Z axes) remain parallel, as opposed
to anti-parallel, we recommend that the following GCON be added to the model:
GCON/id, FUN=UVZ(i)*UVZ(j)-1
(replace UVZ with UVX or UVY for X and Y axes, respectively). The GCON will be
flagged as a redundant constraint, but since Adams Solver (C++) stops as soon as a
redundant constraint becomes a conflicting constraint, a solution involving anti-
parallel axes will be prevented.
Examples
This JOINT statement indicates that Adams Solver (C++) is to connect one part at Marker 0406 to another
part at Marker 0306. Because the statement includes the argument UNIVERSAL, Adams Solver (C++) uses
a universal joint to make the connection.
252 Adams Solver
C++ Statements

JPRIM 253
C++ Statements
JPRIM
The JPRIM statement describes a joint primitive, which constrains one, two, or three degrees of either
translational or rotational freedom. JPRIMs do not usually have a physical analogue and are predominantly
useful in enforcing standard geometric constraints.
Format
254 Adams Solver
C++ Statements
Arguments
JPRIM 255
C++ Statements
256 Adams Solver
C++ Statements
ATPOINT Indicates a three-degree-of-freedom primitive that allows only rotational motion of

one part with respect to another (see the figure below).
For an atpoint primitive, Adams Solver (C++) constrains all three translational
displacements so that the I and J markers are always superimposed.
Atpoint Primitive
I=id,J=id Specifies the identifier of one fixed marker in each part the primitive connects.
Adams Solver (C++) connects one part at the I marker to another at the J marker.
INLINE Indicates a four-degree-of-freedom primitive that allows one translational and three
rotational motions of one part with respect to another (see the figure below).
For an inline primitive, Adams Solver (C++) imposes two translational constraints,
which confine the translational motion of the I marker to the line defined by the z-
axis of the J marker.
Inline Primitive
JPRIM 257
C++ Statements
INPLANE Indicates a five-degree-of-freedom primitive that allows both translational and

rotational motion of one part with respect to another (see the figure below).
For an inplane primitive, Adams Solver (C++) imposes one translational constraint,
which confines the translational motion of the I marker to the x-y plane of the J
marker.
Inplane Primitive
ORIENTATION Indicates a three-degree-of-freedom primitive that allows only translational motion

of one part with respect to another (see the figure below).
For an orientation primitive, Adams Solver (C++) imposes three rotational
constraints to keep the orientation of the I marker identical to the orientation of
the J marker.
Orientation Primitive
258 Adams Solver
C++ Statements
PARALLEL_AXES Indicates a four-degree-of-freedom primitive that allows both translational and

For a parallel axes primitive, Adams Solver (C++) imposes two rotational
constraints so that the z-axis of the I marker stays parallel to the z-axis of the J
marker. This primitive permits relative rotation about the common z-axis of I and
J and permits all relative displacements.
Parallel Axes Primitive
PERPENDICULAR Indicates a five-degree-of-freedom primitive that allows both translational and

For a perpendicular primitive, Adams Solver (C++) imposes a single rotational

constraint on the I and the J markers so that their z-axes remain perpendicular. This
allows relative rotations about either z-axis, but does not allow any relative rotation
in the direction perpendicular to both z-axes.
Perpendicular Primitive
JPRIM 259
C++ Statements
Extended Definition
translational or rotational freedom. The joint primitives, in general, do not have physical counterparts. The
next figure shows the degrees of freedom each joint primitive allows.
In these and subsequent joint primitive figures, thick solid arrows show permissible motions of the I marker
with respect to the J marker, thick dashed arrows show forbidden motions of the I marker with respect to the
J marker, and thin solid lines show the I marker. Ghost constructs suggest spatial relationships.
Summary of Joint Primitive
The table below lists the number of translational or rotational constraints each joint primitive imposes.
Primitive Constraints
260 Adams Solver
C++ Statements
This type of Joint Removes No. Removes No. of Removes Total

Primitive: Translational DOF Rotational DOF Number DOF
Atpoint 3 0 3
Inline 2 0 2
Inplane 1 0 1
Orientation 0 3 3
Parallel Axes 0 2 2
Perpendicular 0 1 1
The reaction force on the part containing the I marker always acts at the I marker. The reaction force on the
part containing the J marker acts at the instantaneous location of the I marker; that is, the point of application
can vary with time if the I and J markers translate with respect to one another. The reaction force on the part
containing the J marker is always equal and opposite to the reaction force on the part containing the I marker.
Joint primitives can be combined to define a complex constraint. In fact, they can be used to create any of
the recognizable joints (except for RACKPIN and SCREW). However, motions cannot be applied on joint
primitives as they can be on recognizable joints. For more information on recognizable joints, see JOINT.
Tip:  The atpoint primitive is identical to the spherical joint (see JOINT).
 Just as the JPRIM elements are the primitive forms of the JOINT elements, the
GCON element is an even more primite or abstract way to represent constraints in
the system. The GCON element can easily represent some of the constraints that
users have looked for in the JPRIM element. For example, users have occasionally
requested a distance JPRIM, a constraint that keeps two markers offset by a specified
distance. To do this, use:
GCON/id, I=i, FUN=DM(i,j)-<offset>
which will keep two markers, i and j, apart by the distance <offset> and report, as a
result, the reaction force applied to i to accomplish this. Note that <offset> must be
non-negative. Furthermore, an <offset> of zero should not be considered equivalent
to an ATPOINT JPRIM that removes three DOFs, when the GCON only removes
one. The <offset> value does not need to be constant, nor is it limited to functions of
time.
JPRIM 261
C++ Statements
Caution:  The two markers that define a joint primitive must be in two different parts.
In Adams Solver (C++), any joint primitive can be attached to a marker on a flexible
body, thereby lifting restrictions in the Adams Solver (FORTRAN). Joint primitives,
however, which do not keep the I and J markers coincident require special
consideration when the J marker is on a flexible body. In general, joint reaction forces
only act on flexible bodies at the marker attachment. If the joint permits the markers
to move relative to each other, the offset between the markers is treated as a rigid lever.
That is, a reaction force-moment pair (Fi, Mi) at marker I will cause a reaction force-
moment pair (Fj, Mj) at marker J according to:
Fj = -Fi
Mj = -Mi - r x Fi
Where r is the instantaneous position vector from marker J to marker I.
For example, an I marker on a part that is constrained by an inline joint primitive to
move on the z-axis of a J marker on a flexible body should not be considered to be
sliding over the surface of the flexible body because the true effect of the primitive is
that of a part sliding on a rigid rod that is welded to the flexible body at the location of
J.
 Some JPRIM elements purport to align marker axes so that they are parallel and point
in the same direction. In actuality, the JPRIM only guarantees that the axes are either
parallel or anti-parallel (pointing in the opposite direction). Because the parallel
orientation is verified during model input, and because markers are very unlikely to
instantaneously to flip by 180 degrees, the likelihood of anti-parallel axes has been
very low. However, with the advent of curve-markers, which will experience an
orientation flip when passing through an inflection point, the situation has become a
possibility.
Although it would have been possible to forbid anti-parallel assembly of JPRIM axes
and enforce this at run-time, the overhead of such checking would not be justifiable,
given the low probability of the occurrence. Furthermore, because the only recourse
would be to stop the simulation, it is not clear that this check would be very useful.
If the user requires that two axes (for example, the Z axes) remain parallel, as opposed
to anti-parallel, we recommend that the following GCON be added to the model:
GCON/id, FUN=UVZ(i)*UVZ(j)-1
(replace UVZ with UVX or UVY for X and Y axes, respectively). The GCON will be
flagged as a redundant constraint, but since Adams Solver (C++) stops as soon as a
redundant constraint becomes a conflicting constraint, a solution involving anti-
parallel axes will be prevented.
262 Adams Solver
C++ Statements
Examples
JPRIM/0101, INLINE, I=0140, J=0240
This JPRIM statement indicates that Adams Solver (C++) is to use an inline joint primitive to connect one
part to another. This connects the first part at Marker 0140 to the second at Marker 0240.
KINEMATICS 263
C++ Statements
KINEMATICS
The KINEMATICS statement specifies error tolerances and other parameters for kinematic analyses.
Format
Click the argument for a description.
Arguments
AERROR Specifies the maximum acceleration error Adams Solver (C++) is to allow for each time
step.
Default: 1.0E-4
Range: AERROR > 0
ALIMIT=r Specifies the maximum angular increment Adams Solver (C++) is to allow per iteration.
The default units for ALIMIT are radians. To specify ALIMIT in degrees, add a D after
the value.
Default: 30D
Range: ALIMIT > 0
AMAXIT=i Specifies the maximum number of iterations Adams Solver (C++) is to allow for finding
accelerations at a point in time.
Default: 25
Range: AMAXIT > 0
264 Adams Solver
C++ Statements
APATTERN=c Specifies as many as ten character strings that together establish the pattern for evaluating
1[:...:c10] the Jacobian matrix during the modified Newton-Raphson solution for the accelerations.
For each iteration, T or TRUE indicates that Adams Solver (C++) is to evaluate the
Jacobian, and F or FALSE indicates that Adams Solver (C++) is not to evaluate the
Jacobian. Thus, cj determines whether or not Adams Solver is to evaluate the Jacobian at
the jth iteration. If necessary, Adams Solver (C++) repeats the pattern of evaluations until
it reaches the maximum number of iterations (AMAXIT). The number of T’s or TRUE’s
and F’s or FALSE’s together must be at least one and no more than 10.
Default: T:T:T:T:T:T:T:T:T:T, that is, to evaluating the Jacobian at every iteration (that is,
the unmodified Newton-Raphson algorithm)
ERROR=r Specifies the maximum displacement error Adams Solver (C++) is to allow for each time
step.
Default: 1.0E-4
Range: ERROR > 0

HMAX=r Defines the maximum time step that the kinematics solver is allowed to take.
Default: The output step size.

MAXIT=i Specifies the maximum number of iterations Adams Solver (C++) is to allow for finding
the displacements at a point in time.
Default: 25
Range: MAXIT > 0
PATTERN=c1 Specifies as many as ten character strings that together establish the pattern for evaluating
[:...:c10] the Jacobian matrix during the modified Newton-Raphson solution for the displacements.
For each iteration, T or TRUE indicates that Adams Solver (C++) is to evaluate the
Jacobian and F or FALSE indicates that Adams Solver (C++) is not to evaluate the
Jacobian. Thus cj determines whether or not Adams Solver is to evaluate the Jacobian at
the jth iteration. If necessary, Adams Solver (C++) repeats the pattern of evaluations until
it reaches the maximum number of iterations (MAXIT). The number of T’s or TRUE’s
and F’s or FALSE’s together must be at least one and no more than ten.
Default: T:T:T:T:T:T:T:T:T:T, that is, to evaluating the Jacobian at every iteration (that is.,
the unmodified Newton-Raphson algorithm)
TLIMIT=r Specifies the maximum translational increment Adams Solver (C++) is to allow per
iteration.

Range: TLIMIT > 0
KINEMATICS 265
C++ Statements
Extended Definition
The KINEMATICS statement specifies error tolerances and other parameters for kinematic analyses. This
statement would only be used when you are requesting a kinematic analysis and you want to change one or
more of the tolerances and parameters from the default values.
Use the SIMULATE command to request a series of kinematic analyses over time. A kinematic analysis is only
appropriate when a system has zero degrees of freedom. A kinematic analysis solves for the displacements,
velocities, accelerations, and forces (if any) at a series of points in time. To find the displacements, Adams
Solver (C++) uses Newton-Raphson iteration to solve a nonlinear set of algebraic equations.
After finding the displacements, Adams Solver (C++) solves a system of linear equations to find the velocities,
then solves another set of nonlinear equations to find accelerations and forces. Adams Solver (C++) repeats
this procedure at successively later times until it obtains results over the period of time specified in a
SIMULATE command.
Unlike the Adams Solver (FORTRAN), the Adams Solver (C++) uses a Newton-Raphson iteration to solve
the linear equations for velocity, rather than a direct method. In spite of this change, the KINEMATICS
statement does not offer any controls over the iterative velocity solution. The modification is required because
in Adams Solver (C++), VARIABLE elements can influence the velocity analysis and such elements can be
self referencing. For example:
VARIABLE/1, FUN= (DX(1)+VARVAL(1))/2
A linear set of equations involving such self-referencing elements must be iteratively solved.
If you issue neither a KINEMATICS command nor statement in an Adams Solver (C++) session, Adams
Solver (C++) uses the default values for AERROR, ALIMIT, AMAXIT, APATTERN, ERROR, MAXIT,
PATTERN, and TLIMIT when performing a kinematic analysis.
Tip: Using a PATTERN argument to request less frequent evaluations of the Jacobian matrix may
decrease the computation time, decreasing the cost and improving the response time.
However, infrequent evaluations could also be more expensive since the modified Newton-
Raphson algorithm might require more iterations due to the slower convergence rates.
Use the ALIMIT and TLIMIT arguments to limit the increments in the displacement
variables and thus the size of the position change on successive iterations. This tends to
prevent Adams Solver (C++) from moving the mechanism to an undesirable configuration.
Examples
KINEMATICS/TLIMIT=10, MAXIT=30
This KINEMATICS statement assigns new values to TLIMIT and MAXIT for a kinematic analysis. Thus,
the maximum translational increment allowed in each iteration of a kinematic analysis is 10 length units and
the number of iterations of the algorithm for the solution of the nonlinear equations is limited to 30.
266 Adams Solver
C++ Statements
LSE
The LSE (Linear State Equation) statement defines the following linear system:
x· = Ax + Bu
y = Cx + Du
of first-order, explicit differential equations and algebraic equations in classical state-space form. The state
variables, x, the inputs, u, and the outputs, y, are specified by ARRAY statements. Use MATRIX statements
to define the coefficient matrices A, B, C, and D.
Format
LSE 267
C++ Statements
Arguments
A=id Designates the MATRIX statement in the dataset that defines the state transition matrix
for the linear system. You must have a MATRIX statement with this identifier in the
dataset; it must be a square matrix (same number of rows and columns); and it must have
the same number of columns as the number of rows in the X array.
B=id Designates the MATRIX statement in the dataset that defines the control matrix for the
linear system. The B argument is optional. When it appears on the LSE statement, you
must also include the U argument. A MATRIX statement with the identifier id must be
in the dataset; it must have the same number of rows as the A matrix and the same number
of columns as the number of elements in the U array.
C=id Designates the MATRIX statement in the dataset that defines the output matrix for the
linear system. The C argument is optional. When it appears on the LSE statement, you
must also include the Y argument. A MATRIX statement with the identifier id must be
of rows as the number of elements in the Y array.
D=id Designates the MATRIX statement in your dataset that defines the feed forward matrix
for the linear system. When the D argument is used, you must also include both Y and U
arguments in the LSE definition. A MATRIX statement with this identifier must be in the
dataset; it must have the same number of rows as the number of elements in the Y array
and the same number of columns as the number of elements in the U array.
IC=id Designates the ARRAY statement in the dataset that defines the column matrix of initial
conditions for the linear system. The IC argument is optional. When it appears on the
LSE statement, you must have an ARRAY statement with the identifier id in the dataset;
and it must have the same number of elements as the X array (equal to the number of rows
in the A matrix). When no IC array is specified for an LSE, all states are initialized to zero.
STATIC_HOL Indicates that the LSE states are not permitted to change during static and quasi-static
D analyses.
268 Adams Solver
C++ Statements
U=id Designates the ARRAY statement in the dataset that defines the input (or control) array
for the linear system. The U argument is optional. When it is used on the LSE statement,
there must be an ARRAY statement with the identifier id in the dataset; and it must be of
the U type. One or both of the B or D argument must appear along with the U argument
in the LSE statement. The corresponding MATRIX statements must have the same
number of columns as there are elements in the U array.
X=id Designates the ARRAY statement in the dataset that defines the state array for the linear
system. You must have an ARRAY statement with this identifier in the dataset; it must be
of the X type; and it may not be used in any other LSE, GSE, or TFSISO statement.
Y=id Designates the ARRAY statement in your dataset that defines the column matrix of output
variables for the linear system. The Y argument is optional. When it is used on the LSE
statement, an ARRAY statement with the identifier id must be in the dataset; it must be
of the Y type, and it may not be used in any other LSE, GSE or TFSISO statement. One
or both of the C or D arguments must appear along with the Y argument on the LSE
statement. The corresponding MATRIX statements must have the same number of rows
as there are elements in the Y array.
Extended Definition
The LSE (Linear State Equation) statement is used, along with associated ARRAY and MATRIX statements,
to define a system of constant coefficient, explicit, differential and algebraic equations in state-space form.
The system of equations describes a model for a linear, time-invariant dynamic system. The LSE, ARRAY,
and MATRIX statements provide the means for importing controllers developed manually or with other
software packages. It can also be used, however, to define an arbitrary set of coupled, constant-coefficient
differential and algebraic linear equations in the form
 x·  A B x 
   
y  C D u 
where at least the A matrix must be nonzero.

The LSE statement follows standard control systems terminology, where x is the state array, y is the output
array, u is the input array, and the initial conditions are defined for x(t=0). In the Adams Solver dataset, each
of these arrays is defined using an ARRAY statement. Similarly, A is the state matrix, B is the control matrix,
C is the output matrix, and D is the feedforward matrix. Each of these matrices is defined using a MATRIX
statement.
All MATRIX and ARRAY sizes must be conformable as required by the above equation. ARRAY statements
with zero-length and zero-sized matrices should not be defined; Adams Solver (C++) correctly formulates the
system equations based on the ARRAY and MATRIX statements included in the dataset.
LSE 269
C++ Statements
Caution:  The LSE statement provides a very general capability for defining a linear element. The
Adams solvers, however, have been developed and refined for sparse systems of equations
that arise from the modeling of mechanical systems. With the LSE statement, you can
create very dense sets of equations. If these equations form a large portion of your
completed model, Adams Solver (C++) may perform more slowly than expected.
 Note that, if the algebraic equations defined by the LSE statement have no solution or
multiple solutions (this is possible because of the general nature of the input ARRAY),
Adams Solver (C++) most likely fails to converge or possibly converge to an unexpected
answer. To avoid this possibility, you should not reference the X (state) or Y (output)
ARRAY statements in the VARIABLE statements listed in the U (input) array.
and force variables. This changes the initial conditions for a subsequent analysis. If
STATIC_HOLD is not specified, during a static analysis, Adams Solver (C++) sets the
time derivatives of the user-defined variables to zero, and uses the user-supplied initial-
 However, if STATIC_HOLD is specified, the user-specified initial conditions are retained
as the static equilibrium values. Thus, the final equilibrium values are the same as the user-
specified initial conditions. Note that this does not guarantee that the time derivatives of
the user-defined variable are zero after static analysis.
Examples
LSE/10, X=10, A=10, U=11, B=11, IC=12
ARRAY/10, X
ARRAY/11, U, VARIABLE=11
ARRAY/12, IC, NUMBER=0.0,0.0
MATRIX/10, FULL=RORDER, ROW=2, COL=2,
, VALUE=0.0,1.0,-986.96,-6.2832
MATRIX/11, FULL=RORDER, ROW=2, COL=1, VALUE=0.0,1.0
VARIABLE/11, FUNCTION=5.0*SIN(PI*TIME**2)
These statements define the following set of linear state equations.
x· = 0 1 x + 0 5 sin ( πt ) , x ( 0 ) = 0
2
– 956.96 – 6.2832 1 0
 ARRAY/10 is the state array (x).
 ARRAY/11 is the input array (u).
 ARRAY/12 is the initial condition array. The input is defined by VARIABLE/11.
 MATRIX/10 is the state matrix (A).
270 Adams Solver
C++ Statements
 MATRIX/11 is the control matrix (B). This LSE has no output, so there is no output array (y),
output matrix (C), or feedforward matrix (D) specified.
Applications
The LSE statement may be most useful for adding feedback control systems to an Adams Solver (C++) model.
The A, B, C and D matrices can be derived manually or imported directly from a control system design
program such as MATRIXx or MATLAB. Normally, the mechanical portion of the model includes some kind
of actuator that depends on one or more of the LSE statement outputs or states.
LSE statements can also be conveniently used in many cases to replace systems of coupled DIFF and
VARIABLE statements (for nonlinear equations, the GSE statement should be used). Examples of possible
dynamical system uses include unsteady aerodynamics and electrodynamics.
You can use the current values of LSE states and outputs in both function expressions and user-written
subroutines using the associated ARRAY facilities (see the ARYVAL function and SYSARY and SYSFNC
subroutines). That is, instead of Adams Solver (C++) functions and FORTRAN callable subroutines
dedicated expressly to the LSE statement, the system states and outputs are accessed by offset referencing
through the appropriate ARRAY routines. This allows for consistent access to system states and outputs for
all three system modeling elements, the LSE, GSE, and TFSISO statements.
LSOLVER 271
C++ Statements
LSOLVER
The LSOLVER statements allows the user to change the linear solver used by the Adams Solver (C++). The
linear solver is invoked multiple times throughout the simulation to compute corrections in the system state.
Format
Arguments
AUTO Specifies that Adams Solver (C++) is to automatically choose the most appropriate solver
based on the model being solved. This is the default setting.
CALAHAN Specifies that Adams Solver (C++) is to use the CALAHAN solver exclusively. The
Calahan solver is usually fastest for most models.
UMF Specifies that the Adams Solver (C++) is to use the Unstructured Multi-Frontal sparse
matrix solver. This solver is faster for very large models.
STABILITY=r Specifies the factor used in the modified Markowitz criterion [1] during the pivot
selection of a LU matrix factorization. The value must be bigger than zero and smaller
than 1.0.
This setting only affects the Redundant Constraint Analysis, Initial Conditions
(displacements, velocities, accelerations) Analyses, and Dynamic Analysis. Static
Analysis, Quasi-static Analysis and Linearization are not affected by this option.
The default value of the STABILITY used for analyses that are affected by this option is
0.01. This values optimizes the fill-in of the linear algebra solution. However, for some
models the default value may results in slow convergence. Using a higher value may
improve the performance of the numerical algorithms.
Prior to Adams 2015, the Calahan solver was the default solver for all Adams models. This linear algebra
solver performs a symbolic factorization of the linear system and is consequently very fast and accurate for all
models except those that are very large.
272 Adams Solver
C++ Statements
The UMF solver (Unstructured Multi-Frontal) uses a very different solution technique than the Calahan
solver. The advantages of the UMF solver are 1) reduced memory use for large models, 2) better performance
for large models and 3) ability to use SMP parallelism for the linear system solution. The UMF solver begins
to show an advantage over the Calahan solver when the number of degrees of freedom in the model is
relatively large and/or the structure of the matrix is very dense. Note, however, that for some models, like
simply-connected long chains, the Calahan solver can be superior even when the number of degrees of
freedom is much larger.
When the LSOLVER/ is set to AUTO (the default) the particular solver used depends only on the number
of equations in the system. The user can determine this transition with the environment variable
ADAMS_SPARSE_SOLVER_SWITCH_AT
For models with number of equations smaller than the ADAMS_SPARSE_SOLVER_SWITCH_AT, the Calahan
solver will be used. Models with more equations will use the UMF solver. If the environment variable is not
explicitly set it will default to 1 million.
Beginning in version 2017.2, a new parallel Calahan linear algebra code is the default linear algebra solver
used in Adams. A prototype of this parallel code was available in earlier releases by setting the environment
variable MSC_ADAMS_SOLVER_PARALLEL_CALAHAN. Given that a new version of that parallel code is now
the default, the said environment variable has been deprecated, instead, a new environment variable
MSC_ADMS_SOLVER_SERIAL_CALAHAN has been created for the rare case of needing to revert to the old
serial code.
The parallel Calahan algorithm uses a number of threads (POSIX API) set by the NTHREAD option in the
PREFERENCES statement. If NTHREDS is set to 1, the old serial code is executed. If NTHREADS is set
to a number higher than the number of CPU cores in the host machine, then the parallel code will use the
number of cores as the number of threads.
Tip:  The CALAHAN and UMF solvers use different strategies for picking pivots during the
linear solution. One may work better on a particular model than the other and the
simulation results from the different solvers may have small differences.
 The UMF solver is built on the BLAS (Basic Linear Algebra Subprograms) library and
comes with a generic implementation of the BLAS library for all architectures. However,
using a BLAS library that is optimized for the specific architecture will usually result in a
substantial performance benefit. These optimized BLAS libraries are typically supplied by
the hardware vendor.
On Linux systems, the UMF solver will automatically search for the Intel MKL BLAS
libraries in locations defined by the LD_LIBRARY_PATH environment variable.
On Windows and other Linux systems, or if a non Intel MKL BLAS library is desired on
Linux, the environment variable BLASLIB should be defined giving the full path to the
desired library. If the BLAS implementation is dependent on multiple libraries, (as is the
case for MKL 10+) then BLASLIB should be defined as the paths to all of the necessary
libraries (using semicolon separators on Windows architectures and colon separators on all
other architectures).
A maximum of six libraries can be specified in the BLASLIB environment variable.
LSOLVER 273
C++ Statements
Caution: Note that the UMF solver does not support all of the capability that is supported by the
Calahan solver. In these cases, such as redundant constraint analysis, the appropriate solver
(Calahan) will automatically be used.
References
Markowitz, H.M., 1957, "The Elimination Form of the Inverse and Its Applications to Linear
Programming," Management Science, vol. 3, pp. 255-269.
See other available Analysis parameters.
274 Adams Solver
C++ Statements
MARKER
The MARKER statement defines three mutually perpendicular coordinate axes emanating from a common
origin. A marker can exist on a PART, POINT_MASS, FLEX_BODY, FE_PART, CURVE, SURFACE, or
GROUND.
Format
MARKER 275
C++ Statements
Arguments
CURVE=id Specifies the identifier of the CURVE along which the marker will move.
Range: Curve IDs

FLOATING Defines the marker as ones that moves relative to the PART with which it is
associated. A floating marker must be used with VTORQUE, VFORCE,
GFORCE, CVCV, and PTCV, and cannot exist without being referenced by one
of these statements.
FLEX_BODY=id Specifies the identifier of the flexible body to which the marker belongs. A
FLEX_BODY argument is not required in the MARKER statement if the
MARKER statement follows the associated FLEX_BODY statement with no
intervening FLEX_BODY or PART statements.
Default: ID of preceding PART or FLEX_BODY

Range: Flexible body IDs
276 Adams Solver
C++ Statements
NODE=n1, Specifies that a marker is to be attached, not necessarily positioned, to the points on
[n2,...,nn] a structure defined by the finite element nodes n1, n2,...,nn. If the NODE
argument is not specified for a marker on a FLEX_BODY, the marker behaves as if
it were attached to a rigid body; its position, velocity, and acceleration are invariant
to deformation, and all forces/torques defined on that marker only project onto the
rigid body degrees of freedom. The NODE argument can only be applied to a
marker on a FLEX_BODY.
Default: None
Range: IDs of nodes on the FLEX_BODY

FE_PART=id Specifies the identifier of the FE_PART to which the marker belongs.
NODE_LABEL = id Specifies a node to which this marker is attached to. The marker may not be
necessarily coincident with the node. Adams Solver C++ will compute the initial
offset (position and/or orientation) to the node and it will keep the offset in
subsequent computations.
PART=id Specifies the identifier of the part to which the marker belongs. A PART argument
is not required in the MARKER statement if the MARKER statement follows the
associated PART statement with no intervening FLEX_BODY or PART
statements.
Default: ID of preceeding PART or FLEX_BODY
Range: Part IDs

POINT_MASS=id Specifies the identifier of the point mass to which the marker belongs. A
POINT_MASS argument is not required in the MARKER statement if the
MARKER statement follows the associated POINT_MASS statement with no
intervening FLEX_BODY, PART, or POINT_MASS statement.
Default: ID of preceding FLEX_BODY, PART or POINT_MASS
Range: Point mass IDs

QP=x,y,z Defines the x-, y-, and z-coordinates of the origin of the MARKER with respect to
the element on which it lies. If the marker is associated with a FE_PART,
FLEX_BODY or PART, the coordinates are specified in the body coordinate system
(BCS). For a marker on a FE_PART or FLEX_BODY, the position specified by QP
does not have to be coincident with a node. For markers associated with CURVES
and SURFACES, the coordinates are specified in the RM coordinate system and are
susceptible to change as the Adams Solver (C++) iteratively solves for initial
conditions that satisfy all constraints while maintaining the marker on the curve.
Range: Real numbers for x, y, and z

MARKER 277
C++ Statements
RM=id Defines a reference marker for CURVE and SURFACE markers on the same part
with respect to which Adams Solver (C++) interprets QP, XP, ZP, and REULER.
REULER=a,b,c Specifies the Euler angle 3-1-3 sequence rotation defining the spatial orientation of
the marker axes relative to the element on which it lies. If the marker is associated
with a FE_PART, FLEX_BODY or PART, the orientation is relative to the body
coordinate system (BCS). For markers associated with CURVES and SURFACES,
the orientation is relative to the natural coordinate system of the CURVE or
SURFACE.
For every point on a CURVE or SURFACE, Adams Solver (C++) computes a

natural coordinate system defined by tangent, normal, and binormal orthonormal
vectors. In general, as the solution progresses and the marker moves along the
CURVE or SURFACE, the orientation of the natural coordinate system changes,
but the orientation of the marker relative to the natural coordinate system remains
fixed. The fixed orientation of the marker relative to the natural coordinate system
is defined by the Euler angle 3-1-3 sequence a,b,c.
The a, b, and c, values represent the set of body-fixed 3-1-3 Euler angles expressed
in radians. These angles can be interpreted by following the steps below.
To orient a marker:
1. Align the marker axes identical to the axes of the parent coordinate system
to which the orientation will be relative.
2. Perform a right-handed rotation of the marker x- and y-axes by a radians
about the positive z-axis of the marker.
3. Rotate the marker y- and z-axes by b radians about the current marker
positive x-axis.
4. Perform a right-handed rotation of the x- and y-axes of the marker by c
radian about the current z-axis of the marker.
To enter the Euler angles in degrees instead of radians, add a D after each value.
Range: Real numbers for a, b, and c

SURFACE=id Specifies the identifier of the SURFACE along which the marker will move.
Range: Surface IDs

USEXP When using the x-point-z-point method of orientation, USEXP causes the marker
to be oriented with the x-axis lying on XP, and ZP lying in the positive x-z plane.
This is useful for orienting markers that are used in BEAM statements. Examples of
using the ZP, XP and USEXP
278 Adams Solver
C++ Statements
XP=x,y,z By default, defines the coordinates of any point in the positive x-z plane of the
marker, but not on the z-axis of the marker. A point on the positive x-axis may be
the most convenient. When used with USEXP, XP defines the coordinates of any
point on the positive x-axis of the marker.
If the marker is associated with a FLEX_BODY or PART, the x-, y-, and z-
coordinates are specified in the body coordinate system (BCS). For markers
associated with CURVES and SURFACES, the x-, y-, and z-coordinates are
specified in the natural coordinate system of the CURVE or SURFACE.

is specified with XP and ZP arguments. Examples of using the ZP, XP and USEXP
ZP=x,y,z By default, defines the coordinates of any point on the positive z-axis of the marker.
When used with USEXP, ZP defines the coordinates of any point in the positive x-
z plane of the marker, but not on the x-axis of the marker.
If the marker is associated with a FLEX_BODY or PART, the x-, y-, and z-
coordinates are specified in the body coordinate system (BCS). For markers
associated with CURVES and SURFACES, the x-,y- and z-coordinates are specified
in the natural coordinate system of the CURVE or SURFACE.

is specified with XP and ZP arguments. Examples of using the ZP, XP and USEXP
MARKER 279
C++ Statements
VEL=r For a marker associated with a CURVE, VEL=r defines the initial velocity of the
marker origin along the curve. VEL is negative if the marker is initially moving
toward the start of the curve, and it is positive if the marker is moving toward the
end of the curve.
VX=x, VY=y, VZ=z For a marker on a CURVE or SURFACE, this argument specifies the initial
translational velocity of the marker along the x-axis (VX), y-axis (VY), and z-axis
(VZ) of the RM coordinate system. Adams Solver (C++) will project the initial
velocity onto the CURVE or SURFACE. Therefore, any contribution of the
specified initial velocity vector which is not along the CURVE or SURFACE will
be discarded.
V1=r1, V2=r2 For a marker associated with a SURFACE, V1=r1, and V2=r2 define the initial
velocity of the marker on the surface along the two-dimensional surface
parameterization.
Extended Definition
The MARKER statement defines a geometric point in space and a set of three mutually perpendicular
coordinate axes emanating from that point. MARKERs are the basic building blocks for specifying applied
forces, constraints, or simply points of interest in the model.
MARKERs are always associated with a specific element in the model (for example, PART, FLEX_BODY,
CURVE, or SURFACE) and could be fixed on the element or move relative to it.
Markers on Parts
A marker on a PART can either be fixed or it may float relative to the PART. A MARKER statement identifies
the location and orientation of a marker with respect to the body coordinate system (BCS).(For more
information on BCS, see Coordinate Systems and Local Versus Global Geometric Data.) Requests for information
pertaining to fixed and floating markers are easy to write (see REQUEST). However, only information on fixed
markers can be used in function arguments that affect how the model behaves. You may reference the position
of a floating marker in a REQUEST statement or a REQSUB evaluation subroutine, for example, but not in an
SFORCE statement or a SFOSUB evaluation subroutine.
Markers on Flexible Bodies

Adams Solver (C++) distinguishes between positioning a marker on a flexible body and attaching a marker
to a flexible body. Positioning the marker using arguments QP, REULER, ZP, and XP defines the initial
position and orientation relative to the BCS of the flexible body. Attaching defines the interaction between
the marker and the flexible body; namely, how forces acting on the marker will project onto the flexible body,
and how the deformation of the flexible body will effect the kinematics of the marker.
A marker can be positioned anywhere on or off a flexible body and can be attached to zero or more nodes. In
general, the position of the marker will be given by:
280 Adams Solver
C++ Statements
x = X + Ao s +  ( ui + ( Ai – I )rc )wi
i=1
where:
x = Position vector of marker, resolved in the ground coordinate system (GCS)
X = Position vector of BCS, resolved in the GCS
Ao = Transformation matrix from BCS to GCS
n = Number of attachment nodes
s = Initial position of marker relative to BCS, resolved in the BCS
ui = Displacement vector of node i relative to BCS, resolved in the BCS
rc = Initial position of marker relative to the centroid of the attachment nodes, resolved in the BCS
Ai = Small rotation transformation from frame fixed to node i during deformation back to the BCS
ri = Initial position of node i relative to BCS, resolved in the BCS
I = 3 x 3 identity matrix
wi = Weighting parameter
1
-------------------
ri – rc
w i = ----------------------------
n
1 -
 ------------------
rj – rc
j=1
where wi satisfies,
 ≥1 for all i

wi =  = 1 for r i = r c

= 0 when there exists a k, not equal to i where rk = rc
and the sum of wi equals one. Therefore, the position of a marker relative to BCS is a least square weighted
average of the relative position of the attachment nodes in their deformed configuration. Furthermore, the
kinematics of the marker are more strongly influenced by attachment nodes closer to the centroid of the
attachment nodes.
MARKER 281
C++ Statements
Several marker attachment configurations can be obtained from the general form given above:
1. Marker positioned on a node, attached to the same node (n=1, w1=1, rc=0)
The position of the marker is then given by x = X + Ao [s + u1]
2. Marker positioned off node, attached to a single node (n=1, w1=1, rc=r1)
The position of the marker is then given by x = X + Ao (r1 + u1 + A1 (s - r1))
Note that the marker is not required to be on the flexible body. It is attached to the node by a rigid
lever.
3. Marker positioned anywhere on or off the flexible body and attached to multiple nodes. This is the
general case given above.
4. Marker positioned anywhere on or off the body and attached to no node (n=0). This is an exception
case. Here, the position of the marker is given by standard rigid body marker kinematics: x = X + Aos
Important: Warning messages for a node has zero mode shapes
The warning messages is printed from C++ solver when a node has zero mode shapes is
attached to some connectors in MD/MSC Adams 2011 and later. This message is inviting
user's attention to find out a potential problem in the model because the flexibility of the
node is infinite, the other words the node behave the same as the marker on rigid part, and
it may not be user's intention. The example of the message for zero rotational mode shapes
is shown below.
Floating Markers on Flexible Bodies

When applied to flexible bodies, a floating marker can be either associated with a node or not. Because a
floating marker is often moving across the body to which it belongs, it typically does not make sense to
associate a flexible body’s floating marker with any particular node. Be advised, that this means the reaction
loads from the force object which the floating marker supports will be applied to the rigid body motion of
the flexible body and not on a modal basis deforming the part locally at the nodes near the force application
point.
Markers on Curves
The orientation (natural coordinate system) of curve markers is defined by the following convention:
282 Adams Solver
C++ Statements
 The x-axis of the curve marker will point along the curve tangent vector at the marker location.
 The y-axis of the curve marker will point along the curve normal vector at the marker location. The
curve normal vector points from the marker location toward the center of curvature (if known).
 The z-axis of the curve marker will point along the curve BI-normal vector at the marker location.
The curve BI-normal is defined as the cross product of the curve tangent and normal vectors.
Markers on Surfaces
The orientation (natural coordinate system) of surface markers is slightly more complex than curve markers
because parameterized surfaces have two linearly independent tangent vectors.
 The x-axis of the surface marker will point along the surface u (alpha) tangent vector at the marker
location.
 The z-axis of the surface marker will point along the surface v (beta) tangent vector at the marker
location.
 The y-axis of the surface marker will point along the surface normal vector at the marker location.
Tip: Select one of the following three methods to define the position and orientation of the
marker.
Note: In general, locate and orient a marker with respect to its parent BCS. If the marker is
on the ground part or is on a part whose BCS is superimposed on the ground
coordinate system (GCS) at time zero, the marker can be positioned and oriented
with respect to the ground coordinate system (GCS).
 To select the Euler angles method, add QP and/or REULER.
 To select the x-point-z-point method using the ZP point to define a point on the z-
axis, add QP, ZP, and/or XP. It is often unnecessary to define XP.
 To select the x-point-z-point method using the XP point to define a point on the z-
axis, add QP, ZP, and/or ZP as well as USEXP. It is often unnecessary to define ZP
MARKER 283
C++ Statements
Caution: If a curve is a straight line, or it has inflection points, the center of curvature will not be
uniquely defined at all of the curve points. In these situations, Adams Solver (C++) will still
determine a normal, but it is just one possibility from an infinite set of normal vectors. It is
also possible for the curve marker normal to jump discontinuously as it goes through an
inflection point. In most situations, this will not cause a simulation to fail, but you should
be aware that it can happen.The REULER arguments for curve and surface markers are
relative to the curve/surface natural coordinate system. This is different from the usual
REULER convention for rigid markers where the transformation is always relative to the part
BCS. If the REULER arguments are at their default value (0,0,0) for a curve/surface marker,
then the marker will coincide with the natural coordinate system.
Rotational constraints applied to curve/surface markers must be done with care. For
example, if you want to create a fixed joint between a curve marker on one part and a rigid
marker on another part, it is imperative that the curve marker axes are close to parallel with
the corresponding rigid marker axes. The REULER arguments may have to be set for the
curve marker or the rigid marker to ensure this condition. If the REULER arguments are
incompatible with the curve/surface natural coordinate system and the constraints, the
model may fail to assemble.
Applying rotational constraints to surface markers is even more problematic than with curve
markers, because you usually have no idea how the surface will be parameterized. If the
surface was created using a CAD package, the CAD package will perform the
parameterization of the surface automatically. All that you can be sure of is that the surface
marker y-axis will be normal to the surface. For this reason, extreme care must be taken when
applying any type of rotational constraint to a surface marker. The REULER arguments
should not be used for surface markers if rotational constraints are being applied and the
parameterization is unknown. It is possible to define surfaces using a user-written subroutine
SURSUB. This is the best solution if you need precise control over how a surface is
parameterized.
If a MARKER statement for a PART or FLEX_BODY is written without arguments to

define its position and orientation, Adams Solver (C++) defines a marker with the same
position and orientation as the BCS.
1. Examples
MARKER/0406, ZP=0,1,0, XP=0,0,1, PART=4
This MARKER statement assigns Marker 0406 to Part 4 and defines the position and orientation of 0406
with respect to the BCS of Part 4 using the x-point-z-point method. QP defaults to QP=0, 0, 0, so Adams
Solver (C++) positions Marker 0406 at the origin of the BCS. The ZP values indicate that the marker z-axis
is parallel to the BCS y-axis and that the XP point lies on the BCS z-axis.
MARKER/040, QP=2,0,0, REULER=90D, 90D, 0, PART=4
284 Adams Solver
C++ Statements
This MARKER statement, like the previous one, describes a marker on Part 4. Adams Solver (C++) places
the origin of Marker 0408 at coordinates 2,0,0 with respect to the BCS. To orient the marker, Adams Solver
(C++) aligns it with its BCS and then rotates the marker 90 degrees about its z-axis, 90 degrees about its new
x-axis, and 0 degrees about its new z-axis.
MARKER/1002, FLOATING, PART=2
This MARKER statement defines a floating marker named Marker 1002 on Part 2. A floating marker
requires the use of one of the following: VFORCE, VTORQUE, GFORCE, PTCV, or CVCV. The
statement referencing the floating marker determines the instantaneous location and orientation of this
marker.
MARKER/8007, XP=0,0,1, ZP=0.1,0,0.1, USEXP, PART=8
This MARKER statement defines Marker 8007 on Part 8. QP defaults to QP=0,0,0, so Adams Solver (C++)
positions Marker 8007 at the origin of the BCS. With USEXP active, the XP values indicate that the marker
x-axis passes through point 0,0,1, and the ZP values indicate the z-x plane passes through BCS coordinates
0.1, 0.0, 0.1.
Below is an example of a curve marker:
MARKER/2002, CURVE = 11, RM = 20, QP = 4, 0, 0, VEL =10
The MARKER statement above defines a curve marker that moves along curve 11. Marker 20 is the reference
marker for this curve. This means that the data for curve 11 is relative to the RM marker. QP is the initial
displacement of the curve marker relative to the RM marker. Adams Solver (C++) may modify this value to
enforce the requirement that the curve marker remains on curve 11. VEL is the initial velocity of the curve
marker along the curve.
The following is an example of a surface marker:
MARKER/1001, SURFACE = 7, RM = 10, QP = 0,0,3, V1 = -1, V2 = 3
This MARKER statement defines a surface marker that moves on surface 7. Marker 10 is the reference marker
for this surface. This means that the data for surface 7 is relative to this coordinate system. QP is the initial
displacement of the surface marker relative to the RM marker. Adams Solver (C++) may modify this value to
enforce the requirement that the surface marker remains on surface 7. All surfaces in Adams are parameterized
as 2D surfaces in 3D space. V1 is the initial velocity of the surface marker along the direction defined by the
first surface parameter (usually called alpha). V2 is the initial velocity of the surface marker along the direction
defined by the second surface parameter (usually called beta).
Examples of using the ZP, XP and USEXP

Four cases are considered. In all cases, the solver will first compute the unit vectors defining the orientation
of the MARKER. Euler angles are then computed using the unit vectors found. Notice that QP defaults to
the zero vector.
Case 1. ZP and XP given
The typical case example is:
MARKER/QP=1.1, 1.2, 1.3, ZP=2.1, 2.2, 2.3, XP=3.1, 3.2, 3.3
When both ZP and XP are given (no USEXP option used) the solver will compute the orientation as shown
below.
MARKER 285
C++ Statements
The solver will compute the unit vectors doing these operations (notice vector x is redefined):
z = ZP – QP
x = XP – QP
y = z×x
x = y×z
Finally, vectors x, y and z are normalized and Euler angles will be computed using the normalized unit vectors.
Case 2. ZP, XP and USEXP given
The typical example is:
MARKER/QP=1.1, 1.2, 1.3, ZP=2.1, 2.2, 2.3, XP=3.1, 3.2, 3.3, USEXP
In this case, the solver computes the orientation as shown below.
286 Adams Solver
C++ Statements
In this case the operations are (here vector z is redefined).:

z = ZP – QP
x = XP – QP
y = z×x
z = x×y
Finally, unit vectors are obtained normalizing x, y and z.
Case 3. ZP given
The typical case is:
MARKER/QP=1.1, 1.2, 1.3, ZP=2.1, 2.2, 2.3
In this case, the solver will compute a point XP as shown in figure below.
MARKER 287
C++ Statements
The computed operations to obtain XP are:

z = ZP – QP = ( a x, a y, a z )
XP = QP + ( – a y, a x, 0 )
x = XP – QP = ( – a y, a x, 0 )
The rest of operations are the same as in Case 1.

Case 4. XP and USEXP given.
The typical case is:
MARKER/QP=1.1, 1.2, 1.3, XP=3.1, 3.2, 3.3, USEXP
In this case, the solver will compute a point ZP as shown in figure below.
288 Adams Solver
C++ Statements
The operations to compute ZP are:

x = XP – QP = ( a x, a y, a z )
ZP = QP + ( 0, – a z, a y )
z = ZP – QP = ( 0, – a z, a y )
The rest of operations are the same as in Case 2.
2. Example: FE Part
The example below creates a MARKER attached to NODE_LABEL 1 of a FE_PART. The QP and REULER
values define the position and orientation of the MARKER relative to the BCS of the FE_PART.
MARKER/22
, FE_PART=3
, NODE_LABEL =1
, QP = 3, 5, 6
Note: For a MARKER located exactly on a node, the QP and REULER values must be coincident
with the information of the said node.
Applications
Use markers on PARTs to:
 Designate the center of mass of a part (see the PART statement).
MARKER 289
C++ Statements
 Indicate the position and orientation of the coordinate system with respect to which you specify the
part moment of inertia.
 Define the position and orientation of a joint or joint-primitive connection point/direction. This
requires two markers, one in each part that the joint or joint primitive connects (see the JOINT and
JPRIM statements).
 Denote force direction and action and reaction points. For more information, see the following
statements:
• BUSHING
• FIELD
• SFORCE
• SPRINGDAMPER
 Specify points for requests and graphics output (see the REQUEST and GRAPHICS statements)
 Provide coordinate system(s) other than ground coordinate system(s) for resolving the components
of vector quantities such as velocities, accelerations, and forces (see the REQUEST statement).
Use floating markers on PARTs or flexible bodies to:
 Denote reaction points that can change position on a part (see the VFORCE, VTORQUE, and GFORCE
statements).
 Denote contact points in CVCV and PTCV constraints.
Use markers on flexible bodies to:
 Define the position and orientation of a joint or joint primitive connection point/direction. This
requires two markers, one in each part that the joint or joint primitive connects (see the JOINT and
JPRIM statements).
 Denote force direction and action and reaction points. For more information, see the following
statements:
• BUSHING
• FIELD
• SFORCE
• SPRINGDAMPER
 Provide coordinate system(s) other than ground coordinate system(s) for resolving the components
of vector quantities such as velocities, accelerations, and forces (see the REQUEST statement).
Use markers on curves to:
requires two markers, one in each part that the joint or joint primitive connects.
Use markers on surfaces to:
requires two markers, one in each part that the joint or joint primitive connects.
See other Geometry statement available.
290 Adams Solver
C++ Statements
MATERIAL
The MATERIAL statement defines a collection of constants appearing in the constitutive equations (stress-
strain equations) for a linear elastic material.
The constants are grouped depending on the form of the constitutive equations. For instance, a linear
orthotropic material used in flexural beams, has a particular type of constitutive equation requiring a relation
between { σ x, τ xy, τ zx } and { ε x, γ xy, γ zx } only.
Format
MATERIAL/id
, NAME = s
, DENSITY = r
MATERIAL 291
C++ Statements
Arguments
ANISOTROPICBEAM=c11, c12, Specifies the elastic constants of the stress-strain relationship in

c13, c22, c23, c33 flexural beam elements having a general linear elastic anisotropic
material.
ORTHOTROPICBEAM=E, Gxy, Specifies the elastic constants of the stress-strain relationship in

Gyz flexural beam elements having a linear elastic orthotropic material.
NAME=s Indicates a name for the material.

YOUNGS_MODULUS=E Specifies the Young's modulus of a linear isotropic elastic material.
POISSONS_RATIO= ν Specifies the Poisson's ratio of an isotropic elastic material.
DENSITY=r Specifies the density of this material.
Note: A MATERIAL statement is required in models having one or more FE_PART statements.
FE_PART statements are used to define embedded Finite Elements in Adams.
Example
MATERIAL/2
, NAME=composite
, DENSITY = 7801
, ORTHOTROPICBEAM=1.E+13, .5E+07, .4E+07
292 Adams Solver
C++ Statements
MATRIX
The MATRIX statement provides the means for inputting a two-dimensional array of numerical values. It is
used primarily to support other statements such as CURVE, LSE, and FLEX_BODY. The entries in the matrix can
be assigned values with the arguments on the MATRIX statement itself or the MATRIX statement can specify
the name of another data file from which the code reads the values. The data file can be in one of two formats:
the Adams Solver (C++) format or the standard FSAVE format supported by the MATRIXx software package.
Format
MATRIX 293
C++ Statements
Arguments
COLUMNS=i Specifies the number of columns (N) in the matrix.

FILE=c Specifies the name of a file containing the values of the matrix. The file name can
include the directory on operating systems that support path names, such as Linux. You
can use the FILE argument to read large matrices into Adams Solver (C++). There is no
limit on the size of an array read from a file.
The first record in the file contains an 80-character header of which the first seven or
eight characters are meaningful.
 If the first record begins with the characters ADAMSMAT or ADAMSMAT2,

then the file is assumed to be in a format used by the Adams Solver (C++)
code.
 If the first record begins with the characters MATRIXx, then the file is
assumed to be in the FSAVE format of the MATRIXx software package.
 If the first record begins with the characters MATSAVE, then the file is
assumed to be in the MATSAVE format of the MATRIXx software package.
Note that the three specifications for the format of the data file are case sensitive.
Capital letters and a lower case x must be used to make the MATRIXx selection.
No other kinds of files are currently supported. However, the ADAMSMAT and
ADAMSMAT2 options are fairly general since the format for reading in the data is
specified within the file. See the example, Multiple Matrix Input Using the FILE Option, for
details on the structure of an ADAMSMAT file.
Because the FILE argument and value can be at most eighty characters long, the file
path and name are limited from seventy-five characters (if you do not abbreviate
FILE=) to seventy-seven characters (if you abbreviate FILE= to FI=).
Range: All printable characters except '!', ';', ',', and '&'
FULL={RORDER Specifies a full-input format where all of the M x N entries are specified with the
,CORDER} VALUES argument. RORDER indicates the values are listed by row in the VALUES
argument. CORDER indicates the values are listed by column.
I=i1,...,in Specifies the row position of each of the n entries in the VALUES argument for a sparse
matrix.
Range: 1 < ik < M, k = 1,...,n

J=i1,...,in Specifies the column position of each of the n entries in the VALUES argument for a
sparse matrix.
Range: 1 < ik < N, k = 1,...,n

294 Adams Solver
C++ Statements
NAME=c Specifies the name of a matrix in the file identified by the FILE argument. All types of
files, ADAMSMAT, ADAMSMAT2, MATRIXx , and MATSAVE, can contain data for
more than one matrix. You use the NAME argument to select a particular matrix from
a file even if it contains just one. Additional MATRIX statements are needed if multiple
matrices are to be read from the same file.
Maximum Number of Characters: 8 (all on the same line)
ROWS=i Specifies the number of rows (M) in the matrix.
SPARSE Specifies that a SPARSE input format is used where the row position, column position,
and value are given, usually only for nonzero entry values.
VALUES=r1,...,rn If you select the FULL option, the VALUES argument specifies all of the m times n
entries in the matrix. The sequence depends on the value of the FULL argument. If
RORDER is specified, the values are listed row-by-row. If CORDER is specified, the
values are listed column-by-column.
If you select the SPARSE option, the VALUES argument specifies only the entries that
may be nonzero. That is, Adams Solver (C++) assumes all entries in the M x N array not
assigned values by the I, J, and VALUES arguments are equal to zero. The kth entry in
VALUES is assigned to the row identified by the kth entry in I and to the column
identified by the kth entry in J for k=1,...,n.
Each pair of I and J entries must specify a unique entry in the array; there can be no
duplicate entries for the same position in the matrix.
Extended Definition
The MATRIX statement defines a general M x N array that can be a rectangular or square two-dimensional
matrix or even a row or column matrix. You can enter the data in a FULL or SPARSE format. When the
matrix has approximately one-third or more of its entries nonzero, the FULL format is more efficient. When
the matrix is mostly empty and the labor associated with entering each nonzero entry’s row position, column
position, and value is less than entering all of the values, you should use the SPARSE format. In cases where
the matrix to be input is very large, you should use the FILE and NAME arguments to specify an external
file containing the matrix.
You can enter data for an M x N matrix into Adams Solver (C++) from a file specified by the FILE argument
on the MATRIX statement. The contents of the file can be in one of four formats: ADAMSMAT,
ADAMSMAT2, or either the standard FSAVE format or the optional MATSAVE format.
The first 7,8, or 9 characters in the header of the file must be MATRIXx, MATSAVE, ADAMSMAT, or
ADAMSMAT2 to identify the format of the data. Although the remaining content of an ADAMSMAT or
ADAMSMAT2 file (as well as all of an Adams Solver (C++) dataset) is case insensitive, the identifying labels
at the beginning of the first record in a matrix file must appear exactly as shown.
MATRIX 295
C++ Statements
A file in the in the ADAMSMAT or ADAMSMAT2 format consists of variable-length records that must be
laid out as described in the following paragraphs. The example at the end, Table 3, and Table 4 illustrate the
details. The FSAVE and MATSAVE formats are described in MATRIXx literature.
To select the option, the header or first record must begin with the characters ADAMSMAT or
ADAMSMAT2. The remainder of the first record can be used as a title to identify the kind of data in the file.
The second record contains only an integer n right-justified within the first five spaces (the I5 FORTRAN
format). It tells how many matrices are contained in the file. The next several records (one or more) contain
the alphanumeric names (eight characters or less) of all of the matrices in the file. The names are listed
sequentially, four to a line, in eight-character fields separated by ten blanks. That is, the FORTRAN format
for the records containing the matrix names is A8, 10X, A8, 10X, A8, 10X, A8.
Sets of contiguous records define each matrix. Without any intervening blank lines, the blocks of records
begin immediately after the last line of matrix names. The first record in each block contains the name of the
matrix in the first eight characters of the line. The code searches through the file until it finds the block of
records corresponding to the NAME argument on the MATRIX statement.
The first record of the block contains the type of matrix (either FULL or SPARSE) within the second eight
spaces on the record. If the type is FULL, the next eight spaces (from 17 through 24) contain the string
CORDER or RORDER to indicate that the values are listed by column or by row, respectively. Otherwise,
if the type is SPARSE, the space is left blank.
The numerical values specified on the first record of the block include the:
 Number of rows M in the matrix
 Number of columns N
 Total number of entries to be assigned values from the file
If the matrix type is SPARSE, then the total number of entries must be less than or equal to
(generally much less than) M x N. If the matrix is FULL, the total number must be equal to M x N.
 For a matrix in the ADAMSMAT format, the values for M, N, and the total number of entries must
be right justified in the fields 25 to 29, 30 to 34, and 35 to 39, respectively.
 For a matrix in the ADAMSMAT2 format, the values for M, N, and the total number of entries
must be separated by spaces.
The final entry on the first line of the block of records defining each matrix is the format
specification for the records containing the values of the matrix. Beginning in column 40, 41 spaces
are allowed for the character string containing the FORTRAN format specification which must
include delimiting parentheses. The lines of data begin on the next record and continue with
successive records until the code has read into storage either M x N values in case the matrix is FULL
or the total number specified in case the matrix is SPARSE.
296 Adams Solver
C++ Statements
Table 3 Specifications for the ADAMSMAT Matrix File
Number of Argument or FORTRAN

Item: records: Contents: symbol: format:
1 1 Header for the file ADAMSMAT A
2 1 Number of matrices in the file n I5
3 (n+3)/4 Number of the n matrices NAME 4 (8A,10X)
4 1 Name of the matrix NAME A8,
{FULL or SPARSE} A8,
{CORDER or RORDER if FULL M,N, A8,
or blank if SPARSE} number
Number of rows, columns, and total format 3I5
number of entries
FORTRAN format specification A41
5 variable All entries in the matrix if FULL A(I,J) FORMAT
or or
The indices and nonzero entries in I,J, A(I,J) FORMAT
the matrix if SPARSE
Note: Items 4 and 5 have to be repeated n times, once for each matrix named in Item 3.
Table 4 Specifications for the ADAMSMAT12 Matrix File

1 1 Header for the file ADAMSMAT2 A
{CORDER or RORDER if FULL M,N, A8,
or blank if SPARSE} number
Number of rows, columns, and total Values separated
number of entries by spaces
format
or or
The indices and nonzero entries in I,J, A(I,J) FORMAT
the matrix if SPARSE
MATRIX 297
C++ Statements
For a FULL matrix, the code simply reads matrix entries sequentially from the file. If the matrix is SPARSE,
the data have to be organized in triplets: Adams Solver (C++) reads the row and column indices followed by
the corresponding entry in the matrix. One triplet follows another until the specified total number of values
have been read into the storage arrays.
If another matrix is contained in the file, the block of records defining its structure and containing its values
must follow immediately after the last line of data for the previous matrix.
Tip: The largest square matrix that may be entered directly in the dataset is 48 48. In order to
enter a larger matrix, you must supply the matrix entries in a file using the FILE and NAME
arguments.
Caution: The file name must be on one line following the argument FILE =, which if abbreviated,
limits the identifier to about 75 characters.
Examples
Small Matrix Input
Assume that the following matrix is needed in an Adams Solver analysis:
1.364 0.000
TRF = 0.000 0.000
– 3.546 4.008
0.000 0.799
Because it is small in size, you will have little difficulty in entering the matrix directly into the Adams Solver
(C++) dataset.
 Version 1, FULL Format (row order):
MATRIX/1, FULL = RORDER, ROWS=4, COLUMNS=2,
, VALUES=1.364,0.000,0.000,0.000,-3.546,4.008,0.000,0.799
 Version 2, FULL Format (column order):
MATRIX/1, FULL = CORDER, ROWS=4, COLUMNS=2,
, VALUES= 1.364,0.000,-3.546,0.000,0.000,0.000,4.008,0.799
 Version 3, SPARSE Format:
MATRIX/1, SPARSE, ROWS=4, COLUMNS=2,
, I=1,3,3,4,J=1,1,2,2,
, VALUES=1.364,-3.546,4.008,0.799
Multiple Matrix Input Using the FILE Option
298 Adams Solver
C++ Statements
Assume that in addition to the matrix above, there are two additional matrices you want to enter into Adams
Solver (C++).
1.97 0.00 – 3.44

VALK = 0.00 4.52 6.02
– 3.44 6.02 2.11
01
1.698045 ×10
01
– 2.307452 ×10
0
STL = 0.000000 ×10
0
0.016390 ×10
0
0.011271 ×10
0
0.000000 ×10
Assume that you want to use an external file to input the matrices and that all of the matrices are resident in
a file called prob.dat which is in the system subdirectory, /home/staff/demo. The Adams Solver (C++) dataset
entries would appear as the following:
MATRIX/1, File=/home/staff/demo/prob8.dat, Name= trf
MATRIX/2, File=/home/staff/demo/prob8.dat, Name= valk
MATRIX/3, File=/home/staff/demo/prob8.dat, Name= stl

The leading record of a matrix file is read as character data. The first seven or eight columns must contain
one of the three character strings: MATRIXx, MATSAVE, or ADAMSMAT.
In the current example, the prob.dat is in the directory, /home/staff/demo, and contains the following data:
1 2 3 4 5 6 7
8123456789012345678901234567890123456789012345678901234567890123456789012345
67890
ADAMSMAT Floating platform example
3
TRF VALK STL
TRF FULL RORDER 4 2 8 ( 8F8.5 )
1.36400 0.00000 0.00000 0.00000 -3.54600 4.00800 0.00000 0.79900
VALK FULL CORDER 3 3 9 ( 3F6.3 )
1.970 0.000-3.440
0.000 4.510 6.020
-3.440 6.020 2.110
STL SPARSE 6 1 4 ( 2( 2I5, E14.6 ) )
1 1 0.169805E+02 2 1 -0.230745E+02
4 1 0.016390E+00 5 1 0.011271E+00
The second and third records are read with format I5 and 4(A8,10X), respectively. Then, the first record of
each of the blocks corresponding to the three matrices TRF, VALK, and STL is read with the format 3A8,
MATRIX 299
C++ Statements
3I5, A41. Finally, as can be seen in the copy of the file shown above between the two strings of 80 characters
that mark the columns (which, of course, are not part of the file), the single record of data for the matrix TRF
is read with the format 8F8.5; the three records for VALK are read with 3F6.3; and the two records for STL
with 2(2I5,E14.6).
Applications
The CURVE, LSE, and FLEX_BODY statements refer to the MATRIX statement. The CURVE statement
specifies a MATRIX statement containing the coordinates of the points defining a general curve in space. For
the LSE statement (Linear State Equation), the MATRIX statement is used to store the system state matrices
(A, B, C, and D). For the FLEX_BODY statement, the MATRIX statement is used to input the various
inertia invariants, the generalized stiffness matrix, the mode shape information, modal loads and preloads.
The MATRIX statements for the FLEX_BODY reference matrix data in an external file, which is
automatically computed by a preprocessor.
300 Adams Solver
C++ Statements
MFORCE
The MFORCE statement applies a force directly to the modal coordinates and rigid body degrees of freedom
of a FLEX_BODY.
Format
Arguments
FLEX_BODY=id Specifies the FLEX_BODY on which the modal load is applied. Multiple MFORCE
elements can reference the same FLEX_BODY.
JFLOAT=id Specifies the floating marker on which the reaction force is applied. If you do not
specify a floating marker, Adams Solver (C++) ignores the reaction force.
CASE_INDEX=i Specifies the modal load case number that defines the MFORCE. The modal load cases
are force distributions that have been predefined and stored in a modal neutral file
(MNF) for an associated FLEX_BODY. Specifically, CASE_INDEX refers to a column
in the MODLOAD matrix that is referenced in the FLEX_BODY statement. The
column contains the modal loads for the modes selected for an Adams simulation. For
more information about how to generate modal load cases, see the Adams Flex Help.
Note: You can use the CASE_INDEX/SCALE combination of arguments to define

an MFORCE only if you have defined a MODLOAD matrix for the
associated FLEX_BODY.
SCALE=e Specifies an expression for the scale factor to be applied to the load case referenced by
CASE_INDEX. The scale factor and the load case are used in combination to define
the modal load. If you use the SCALE argument, it must be the last argument in the
MFORCE statement, or it must be followed by a backslash (\).
Note: You can use the CASE_INDEX/SCALE combination of arguments to define

an MFORCE only if you have defined a MODLOAD matrix for the
associated FLEX_BODY.
MFORCE 301
C++ Statements
ROUTINE=libna Specifies an alternative library and name for the user subroutine MFOSUB.
me::subname
FORCE=USER(r1 Specifies up to thirty user-defined constants that Adams Solver (C++) passes to a
{r2,...,r30}) MFOSUB to directly compute the modal force on the FLEX_BODY. Each component
of the modal force can depend on time or the state of the system.
FUNCTION=US Specifies up to thirty user-defined constants the Adams Solver (C++) passes to a
ER(r1{r2,...,r30}) MFOSUB to directly compute the modal load case and scale function whose product
is the modal force applied to the FLEX_BODY. The scale function can depend on time
or the state of the system. The load case can only be a function of time.
Extended Definition
The MFORCE statement allows you to apply any distributed load vector F to a FLEX_BODY. Such a load
vector is typically generated with a finite element program. Examples of distributed load cases include thermal
expansion or pressure loads. To help you understand how Adams handles distributed loads, the following
section discusses the equations of motion of a flexible body, starting with the physical coordinate form that
the finite element program uses.
Equations
[ M ]x·· + [ K ]x = F
where [ M ] and [ K ] are the finite element mass and stiffness matrices for the flexible component; x is the
nodal coordinate vector; and F is the distributed load vector. This equation can be transformed into the
modal coordinates, q:
T T T
[ P ] [ M ] [ P ]q·· + [ P ] [ K ] [ P ]q = [ P ] F
where [ P ] is the matrix of mode shapes. The modal form simplifies to:
ˆ ˆ
[ M ]q·· + [ K ]q = f
ˆ ˆ
where [ M ] and [ K ] are the generalized mass and stiffness matrices, and f is a modal load case vector that
Adams uses to define the MFORCE element.
The projection of the nodal force vector on the modal coordinates:
T
f = [P] F
is computationally expensive and is typically undertaken by a finite element program when the modal neutral
file (MNF) is created. The modal load case f is then stored in the MNF and available to optionally define a
modal force on a FLEX_BODY in Adams.
Because Adams only requires the modal form of the load, the expensive projection of the load from physical
to modal coordinates is performed only once during the creation of the MNF, rather than repeatedly during
302 Adams Solver
C++ Statements
the Adams simulation. The MNF can store several modal load cases, which are denoted here as f1, f2,…, fn.
From the modal load cases, a total modal force fT can be applied to the FLEX_BODY by defining an
MFORCE element in one of the following five ways.
Definition 1: Specifying Scalar Function and Modal Load Case
The easiest way to construct an MFORCE is to specify a scalar function expression using the SCALE
argument and a single modal load case using the CASE_INDEX argument:
MFORCE/id, FLEX_BODY = id [,JFLOAT=id], CASE_INDEX = i
, SCALE = e
A modal force of the form
fT(q,t) = e(q,t) fi
is then applied to the FLEX_BODY, where CASE_INDEX = i references load case fi in the MNF, and
SCALE = e defines the state-dependent scalar function e(q,t).
Definition 2: Defining MFOSUB Subroutine
If the scalar function expression is too complicated to define using the Adams Solver (C++) function
expression language, you can use the MFOSUB user-written subroutine interface and specify the MFORCE
as follows:
MFORCE/id, FLEX_BODY = id [,JFLOAT=id], FUNCTION = USER(r1,[r2,…r30])
The applied modal force is equivalent to Definition 1, that is:
fT(q,t) = e(q,t) fi
However, here the load case index is returned from the MFOSUB as well as the state dependent scalar
function e(q,t). The dependency on q arises from calls to the SYSFNC and SYSARY utilities in the user-
written subroutine.
Definition 3: Combining Modal Load Cases
Alternatively, you can use an MFOSUB to combine the modal load cases, f1,...,fn as follows:
fT(q,t) = e(q,t) [ g1(t) f1 + g2(t) f2 + … tgn(t) fn ]
where g1(t), g2(t), … gn(t) are scalar functions of time only. The MFORCE is specified the same way as
Definition 2, namely:
Rather than referencing a single modal load case, however, the MFOSUB computes a new modal load case
by combining the existing load cases in a time-varying way. Adams Solver (C++) then scales the new modal
load case by a scale factor that is also computed by the MFOSUB. The resulting modal force is then applied
to the FLEX_BODY. It is important to note that although the scale factor can be a function of time and
system state, the new modal load case may only be a function of time. In other words, using values obtained
by calls to SYSFNC or SYSARY to define the functions gi(t) is not allowed.
Definition 4: Computing Modal Load Case
MFORCE 303
C++ Statements
If the MNF does not contain modal load cases, then the MFOSUB can compute one. The MFORCE is
defined in the same way as Definitions 2 and 3:
Again, the computed modal load case can be a function of time only, while the scale factor that is applied to
it can be a function of both time and system state:
fT(q,t) = e(q,t) fu(t)
where e(q,t) is the user-defined scale factor and fu(t) is the user-defined load vector. This method of
specifiying an MFORCE is primarily provided for completeness, and will be used primarily by very
experienced users.
Definition 5: Using the Force Form
The general force description:
fT(q,t) = f(q,t)
where each component of f(q,t) depends independently on time and system state can only be achieved
through the MFOSUB interface and the following MFORCE specification
MFORCE/id, FLEX_BODY = id [,JFLOAT=id], FORCE = USER(r1,[r2,…r30])
Note that the keyword FORCE is used instead of FUNCTION. This instructs Adams Solver (C++) to ignore
the scale function returned from the user-written subroutine and apply the load case defined in the
subroutine directly to the FLEX_BODY. Furthermore, calls to SYSFNC and SYSARY establish state
dependencies in the individual modal force components, not just the scalar function. An MFORCE defined
in this way is more general, but less efficient than the previous forms. Therefore, it should only be used if
your application does not allow for the previous definitions.
Definition 6: Combining Modal Load Cases using multiple scale factors
This is expanded definition of Definition 3 to allow you to indicate multiple scale factors. The force
description is same as Definition 3 as follows:
fT(q,t) = e(q,t) [g1(t) f1 + g2(t) f2 + … + gn(t) fn]
The values of e(q,t) and g1(t), g2(t), … gn(t) are specified in MFOSUB instead of e(q,t) and the term of [] in
Definition 3. The MFORCE specification is also same as Definition 3, namely:
Note that the modeling is quite same as Definition 3 but this is useful for correct MFORCE visualization in
Adams PostProcessor.
304 Adams Solver
C++ Statements
Resultant Forces
For distributed loads that have an external resultant, portions of the load will project on the rigid body modes
of the flexible body. However, the rigid body modes must be disabled because Adams Solver (C++) will
replace them with the non-linear, large motion, generalized coordinates: X, Y, Z, ψ , θ , and φ . In this case,
the load on the rigid body modes are transferred to the large motion generalized coordinates.
Part of this transfer occurs during the MNF2MTX translation of the flexible body's MNF, and, consequently,
the MODLOAD matrix has a dimension that equals 6 plus the number of modes. The first 6 entries in each
column correspond to the external force and torque acting on the flexible body for this modal load case,
expressed relative to the body coordinate system (BCS). When the modal load case is an internal force (as
would be expected in the case of a thermal load), this force and torque will be zero.
You should also be aware of the way modal truncation affects the application of modal loads. When you
define a distributed load, it will be projected on the available modes. It is important to understand that the
available modes form an efficient but incomplete basis for the flexible component. Therefore, it is inevitable
that some portion of the load will be orthogonal to the modal basis. This portion of the load will be
irretrievably lost. Furthermore, during mode selection within Adams, you should realize that a mode whose
removal is being considered may also have a significant modal load associated with it. In this case, the mode
should not be disabled.
Examples
MFORCE/1, FLEX_BODY = 1, CASE_INDEX = 1
, SCALE = SIN(TIME)*DX(1,4)
Using the first load case defined for FLEX_BODY/1, this example defines a modal load on FLEX_BODY/1
by scaling the values of the load case by the function expression SIN(TIME)*DX(1,4). The reaction force
that corresponds to this load is ignored.
MFORCE/2, FLEX_BODY = 2, JFLOAT = 4
, FUNCTION = USER(10,1e5,23.)
This example defines a modal load whose reaction resultant force acts on the parent part of floating marker
2. The magnitude and shape of the load is provided by the MFOSUB user-written subroutine, based on the user
parameters 10,1e5,23. Furthermore, Adams Solver (C++) builds the applied modal force by multiplying the
scale and load case returned from the user-written subroutine, and only the scale function is assumed to
depend on state.
, FORCE = USER(10,1e5,23.)
This example is identical to the previous one, except that Adams Solver (C++) builds the applied modal force
directly from the load case returned from the user-written subroutine, and any component of the load case
can depend on state or time.
MOTION 305
C++ Statements
MOTION
The MOTION statement specifies a system degree of freedom as an explicit function of time. The freedom
is specified by either:
 Specifying the joint and type of motion (translational or rotational).
 Identifying a specific translation or rotational displacement component between two markers
The time dependency can be described in either a function expression or user-written subroutine. The
motion inputs may be a displacement, velocity, or acceleration. Velocity and accelerations are numerically
integrated to provide the displacements, with the initial conditions providing the constants of integration.
Format
306 Adams Solver
C++ Statements
Arguments
ACCELERATION Specifies that the FUNCTION argument defines a second time

derivative expression as a function of time. This expression is
integrated twice to calculate a corresponding displacement. Notice,
the provided expression may or may not define the acceleration of
a component in the model. For example, if using the B2 option, the
provided expression is the second time derivative of B2 (Euler
angle) which may need other terms to define the angular
acceleration of some component of the model.
Default: DISPLACEMENT
B1 Specifies the first angle of the Body 1-2-3 Euler angle sequence as a
function of time. The 123 rotation sequence of the I marker
coordinate system is defined with respect to the J marker coordinate
system.
Range: None
Default: None
B2 Specifies the second angle of the Body 1-2-3 Euler angle sequence
as a function of time. The 123 rotation sequence of the I marker
system.
Range: None
Default: None
B3 Specifies the third angle of the Body 1-2-3 Euler angle sequence as
a function of time. The 123 rotation sequence of the I marker
system.
Range: None
Default: None
DISPLACEMENT Specifies that the FUNCTION argument defines the motion
displacement. This is the default.
MOTION 307
C++ Statements
Specifies an expression or defines and constants to be passed to the

 e  MOTSUB user-written subroutine to determine the motion. The
FUNCTION =   motion must be a function of time only and not a function of the
 USER ( r1 [ ,... ,r30 ] ) 
state variables. To determine the motion with an expression, follow
FUNCTION with an equal sign and the expression. To determine
the motion with a user-written subroutine, follow FUNCTION
with an equal sign, the character string USER, and the values
(r1[,...,r30]) that you want Adams Solver (C++) to pass to
MOTSUB (see the MOTSUB subroutine). If the FUNCTION
argument is used, it must either be the last argument in the
MOTION statement or be followed by a backslash (\).
ICDISP Specifies the initial displacement of the motion, when the motion
is defined in terms of velocity or acceleration.
Default: 0
ICVEL Specifies the initial velocity of the motion, when the motion is
defined in terms of acceleration.
Default: 0
I=id, J=id Specifies the identifiers of the two markers whose displacement is
being controlled.
Range: Any valid non-floating marker not belonging to a flexible

body
Default: None
JOINT=id Specifies the identifier of the joint to which the motion is assigned.
The joint must be either translational, revolute, or cylindrical. If
you specify a translational joint, Adams Solver (C++) assumes you
are assigning translational motion and does not allow you to assign
rotational motion. Similarly, if you specify a revolute joint, Adams
Solver (C++) assumes you are assigning rotational motion and does
not allow you to assign translational motion. However, if a
cylindrical joint is specified, either translational or rotational
motion can be specified with TRANSLATION or ROTATION,
respectively.
ROTATION Designates a rotational motion. This argument is necessary only
when rotational motion is being applied to a cylindrical joint.
MOTSUB.

TRANSLATION Designates a translational motion. This argument is necessary only
when translational motion is being applied to a cylindrical joint.
308 Adams Solver
C++ Statements
VELOCITY Specifies that the FUNCTION argument defines a time derivative

expression as a function of time. This expression is integrated to
calculate the corresponding displacement. This expression may or
may not define the velocity of a component in the model. For
example, if using the B2 option, the provided expression is the time
derivative of B2 (Euler angle) which may need other terms to define
the angular velocity of some component in the model.
X Specifies DX(I,J,J) as a function of time. DX is the x component of
the displacement of the I marker with respect to the J marker
evaluated in the J marker coordinate system.
Range: None
Default: None
Y Specifies DY(I,J,J) as a function of time. DY is the y component of
Range: None
Default: None
Z Specifies DZ(I,J,J) as a function of time. DZ is the z component of
Range: None
Default: None
Extended Definition
The MOTION statement specifies a translational or rotational degree-of-freedom as a function of time. You
can apply MOTIONs to either joints or between a pair of markers. When a motion is applied on a joint, a
joint degree of freedom is controlled as a function of time. When a motion is applied between a pair of
markers, movement along a user-specified direction is controlled as a function of time. You can define the
value of the degree-of-freedom being controlled, either as a function expression or user-written subroutine.
Motions on Joints
Motions can be specified to act on joints. A translational motion is specified at either a translational or
cylindrical joint. A rotational motion is specified at either a revolute or cylindrical joint. The type of the joint
together with the markers of the joint specify the degree-of-freedom being controlled.
For a translational motion, Adams Solver (C++) moves the I marker along the z-axis of the J marker. The J
marker origin represents zero displacement while the z-axis of the J marker defines the positive direction.
MOTION 309
C++ Statements
For a rotational motion, Adams Solver (C++) rotates the I marker about the z-axis of the J marker. The right-
hand rule is used to determine the sign of the motion. The z-axis of the I marker must be collinear with the
z-axis of the J marker at all times. The angle is zero when the x-axis of the I marker is also collinear with the
x-axis of the J marker.
If options VELOCITY or ACCELERATION are used, then the FUNCTION expression does define a local
velocity or acceleration relative to the JOINT Markers.
Motions on Markers
Motions can also be specified to act directly between a pair of markers. No joint is needed when you use this
method. If I and J are the pair of markers between which a motion is specified, then any one of the following
six degrees of freedom may be directly controlled by the motion.
 DX(I,J,J) is the displacement of the origin of the I marker with respect to the origin of the J marker
along the x-axis of the J marker.
 DY(I,J,J) is the displacement of the origin of the I marker with respect to the origin of the J marker
along the y-axis of the J marker.
 DZ(I,J,J) is the displacement of the origin of the I marker with respect to the origin of the J marker
along the z-axis of the J marker.
 B1(I,J) is the first angle of a Body 1-2-3 Euler rotation sequence that measures the orientation of the
I marker with respect to the J marker.
 B2(I,J) is the second angle of a Body 1-2-3 Euler rotation sequence that measures the orientation of
the I marker with respect to the J marker.
 B3(I,J) is the third angle of a Body 1-2-3 Euler rotation sequence that measures the orientation of
If options VELOCITY or ACCELERATION are used, along with options X or Y or Z, then the
FUNCTION expression does defines either a local translational velocity or acceleration in the I Marker
reference frame. However, if using options VELOCITY or ACCELERATION with options B1 or B2 or B3,
then the FUNCTION expression may not define a local acceleration of a component in the model.
Tip:  If you want to determine the translational or rotational force a motion applies, use a
REQUEST statement with the FORCE argument.
 A MOTION statement can define zero motion with respect to time.
 Although the extended capabilities of Adams Solver (C++) in the area of constraint
equations would not require that the FUNCTION expression be limited to an explicit
function of time, it was rejected on the grounds of backward compatibility with Adams
Solver (FORTRAN). Users interested driving a motion generator with a function of
displacements, velocities, or variables are encouraged to study the general constraint
element (GCON).
310 Adams Solver
C++ Statements
Important: The FORTRAN Solver does not consider any change to MOTION function expression to
be a topology change. This is because the FORTRAN Solver assumes that MOTION
function expression will always be an explicit function of time.
The C++ Solver attempts to determine if a MOTION function expression is an explicit

function of time by analyzing it. If the C++ Solver determines that a MOTION function
expression that IS an explicit function of time has changed to a new expression that is also
an explicit function of time, then there is no change in model topology (which is equivalent
to the FORTRAN Solver).
However, if a MOTION function expression changes to something that IS NOT an explicit

function of time, then the C++ Solver concludes that a topology change has occurred and an
analysis separator will be added to the output files. This is different behavior from the
FORTRAN Solver because the FORTRAN Solver will never add separators to the output
files when a MOTION expression changes.
MOTION 311
C++ Statements
Caution:  The motion must be a function of only time, not displacements, forces, or any other
variables in the system. Otherwise, Adams Solver (C++) may have difficulty finding a
solution.
 Motion function expressions are required to have first and second time derivatives. Non-
smooth functions that do not have continuous first and second time derivatives can
cause severe numerical problems.
 Be careful when specifying multi-axial rotational motions between a pair of markers. B1,
B2, and B3 specify a Body 1-2-3 rotation sequence and are Euler angles. This implies
that the first rotation occurs about the x-axis of the J marker, the second rotation about
an intermediate y-axis and the last about the z-axis of the I marker. For example, if you
are measuring rotations between two markers in the sequence z, y, x, this corresponds to
a Body 3 -2 1 rotation sequence, you will have to convert this to a Body 1-2-3 rotation
sequence before specifying it in a MOTION.
 When using any of the following motion types: B1, B2, or B3, avoid situations where
the B2 angle is at +/- 90degrees or +/- 270 degrees. At these angles the Body 1-2-3 angles
are undefined. If this situation occurs, Adams Solver (C++) issues a warning and stops
the execution. There is no solution for this condition.
 Do not use an initial conditions argument, such as, IC, ICTRAN, or ICROT, on a
JOINT statement with a motion that acts in the same direction on the joint. If both are
used, Adams Solver (C++) uses the MOTION statement and ignores the initial
conditions argument(s) specifying motion in the same direction(s) specified by the
JOINT statement.
 If the initial rotational displacement of a revolute or cylindrical joint (as specified by an
IC or ICROT argument on a JOINT statement or by a MOTION statement) varies by
anywhere from 5 to 60 degrees from the initial configuration of the joint as indicated by
the input positions of the two markers constituting the joint, Adams Solver (C++) issues
a warning message and continues execution. If the variation is greater than 60 degrees,
Adams Solver (C++) issues an error message and stops execution.
312 Adams Solver
C++ Statements
 If a MOTION statement generates non-zero initial part accelerations, the Adams Solver
(C++) integrator may not produce reliable accelerations and velocities for the first two or
three internal integration steps. Adams Solver (C++) automatically corrects for this, so
that values returned at the first output step are accurate. However, a sensor that depends
on the accelerations or reaction forces due to this motion may trip unexpectedly prior to
the first output step, even though the solution appears correct when the sensor is
removed. If this occurs, you should modify the displacement function in the MOTION
statement so that the initial accelerations are zero.
 Adams Solver (FORTRAN) is incapable of performing a kinematic analysis on a zero
degree-of-freedom model containing motions with VELOCITY and
ACCELERATION arguments. Not so for Adams Solver (C++), which uses a more
advanced quadrature scheme to integrate the MOTION function. This is a potential
source of differences in the results produced by the two solvers.
 A function expression for a MOTION statement can not use BISTOP and/or IMPACT
functions.
Examples
MOTION/101, JOINT=101, FUNCTION=10 * SIN(TIME)**2
This MOTION statement acts on the translational joint (101), which implies that the motion is
translational. The motion value as a function of time is 10 * SIN(TIME)**2.
The following MOTION statement is equivalent to the one mentioned above:

MOTION/101, I=1011, J=1012, Z, FUNCTION=10 * SIN(TIME)**2.
MOTION/201, JOINT=201, FUNCTION=POLY(TIME, 0, 0, 360D)
This MOTION statement acts on the revolute joint (201), which implies that the motion is rotational. The
motion value as a function of time is POLY(TIME,0,0,360D).
The following MOTION statement is equivalent to the one described above:

MOTION/201, I=2011, J=2013, B3,
MARKER/11, QP=1,2,3, REU=30D, 45D, 60D, PART=12
MARKER/12, QP=4,5,6, REU=45D, 60D, -34D, PART=23
MOTION/1, I=22, J=11, X, FU=30D*SIN(360D*TIME+30D)
MOTION/2, I=22, J=11, B3, FU=30D*COS(TIME)
This MOTION statement acts between a pair of markers (11 and 12). Two degrees of freedom are explicitly
specified as a function of time:
 The displacement of the origin of Marker 11 with respect to the origin of Marker 12, along the x-
axis of Marker 12, is specified to be 30d*SIN(360D*TIME+30D).
 The rotation about the z-axis of Marker 11 (third angle of the Body 1-2-3 rotation sequence
between Markers 11 and 12) is specified to be 30D*COS(TIME).
MOTION 313
C++ Statements

MOTION/3014, I=3011, J=3012, B1
, FU=30D*SIN(360D*TIME+30D)
MOTION/3015, I=3011, J=3012, B2
, FU=-25D*SIN(360D*TIME-25D)
MOTION/3016, I=3011, J=3012, B3
, FU=45D*SIN(360D*TIME-57D)
These MOTION statements control the three rotational degrees-of-freedom in a spherical joint by specifying
the Body 1-2-3 angles between the I and J markers of the joint as functions of time.
JOINT/401, PLANAR, I=4011, J=4012
MOTION/4011, I=4011, J=4012, X
, FU=STEP5(TIME, 0.5, 0.0, 4.0, 1.0)*50
MOTION/4012, I=4011, J=4012, Y
, FU=-SHF(TIME, 0.0, 10/2, 2*PI, 90D, 10/2)
MOTION/4016, I=4011, J=4012, B3, FU=0D
 These MOTION statements control the three degrees-of-freedom in a planar joint:
 The displacement of the origin of Marker 4011 with respect to the origin of Marker 4012, along the
x-axis of Marker 4012, is specified as 40*TIME-25.2.
y-axis of Marker 4012, is specified as -25*SIN(360D*TIME-25D).
 The rotation of Marker 4011 with respect to Marker 4012 about the z-axis of Marker 4011 is
specified to be zero.
314 Adams Solver
C++ Statements
NFORCE
The NFORCE statement creates a multi-point force element which establishes linear force-displacement
(stiffness) and/or force-velocity (damping) relationships between many markers (up to 351) in the model.
Format
Arguments
CMATRIX=id Specifies the identifier of the MATRIX that the NFORCE uses as its damping
matrix. The CMATRIX is a 6n · 6n matrix (n is the number of I markers) that
defines the linear relationships between the I marker velocities relative to the J
marker and the viscous forces generated by the NFORCE. The CMATRIX is
derived in the J marker’s coordinate system. If neither CMATRIX nor CRATIO is
given, the NFORCE is undamped. Marker translational and rotational velocities
appear sequentially in Vx, Vy, Vz, ω x, ω y, ω z order, while the markers appear in
the same sequence as in the IMARKER argument.
CRATIO=r Specifies the proportional damping ratio for the NFORCE. The elements of the
damping matrix are determined by multiplying the corresponding stiffness element
value by this number. If direct input of the damping properties is desired, the
CMATRIX may be used. If neither CMATRIX nor CRATIO is given, the
NFORCE is undamped.
FORCE Specifies the identifier of the MATRIX that contains the forces and torques that the
NFORCE would produce if all the I markers were at the positions given in
LENGTH. FORCE is a 6n · 1 matrix (n is the number of I markers) of forces and
torques, appearing sequentially for each marker in Fx, Fy, Fz, Tx, Ty, Tz order, while
the markers appear in the same sequence as in the IMARKER argument. The force
and torque components are expressed in the J marker’s coordinate system. When
LENGTH is used to specify the system’s free lengths, FORCE gives the preloads.
If FORCE is not given, the NFORCE acts as though a matrix of zeros are input.
NFORCE 315
C++ Statements
IMARKERS=id1,...,i Lists the markers (except for the J marker) between which the NFORCE forces and
dn torques act.
Number of values: 1 to 350

J=id Specifies the identifier of the marker that determines the reference frame in which
the relative velocities and all of the forces associated with the NFORCE are
calculated and the coordinate system in which all the components and LENGTHs
are evaluated. The NFORCE automatically applies the proper reaction forces at the
J marker.
KMATRIX=id Specifies the identifier of the MATRIX that the NFORCE uses as its stiffness
matrix. The KMATRIX is a 6n · 6n matrix (n is the number of I markers) that
defines the linear relationships between the I marker displacements relative to the
J marker and elastic forces generated by the NFORCE. The KMATRIX is specified
in the J marker’s coordinate system. Marker translational and rotational
displacements appear sequentially in Dx, Dy, Dz, Ax, Ay, Az, order, while the
markers appear in the same sequence as in the IMARKER argument.
LENGTH=id Specifies the identifier of the MATRIX that defines a reference location for each of
the I markers with respect to the J marker, measured in the J marker’s coordinate
system. LENGTH is a 3n · 1 column matrix (n is the number of I markers) of
translational displacements only, in Dx, Dy, Dz order. Usually, LENGTH is used
to specify the system’s free (no internal force) lengths when they differ from the
input positions. If LENGTH is not given, the NFORCE assumes that the input
positions of the I markers are at the reference locations.
Extended Definition
The NFORCE creates a set of forces and torques which act between the I and J markers which appear in the
NFORCE statement. These forces and torques are linear functions of the relative displacements and velocities
of the markers, in a manner equivalent to the finite element method. For each NFORCE, one marker (J) is
used as the reference marker. The velocities are resolved into the J marker’s reference frame and expressed in
the J marker’s coordinate system. The force and torque components computed by the NFORCE are also
given in the J marker’s coordinate system.
The force-displacement and force-velocity relationships are specified using stiffness and damping matrices,
or by using a stiffness matrix and a proportional damping ratio. These matrices are defined using MATRIX
statements in the dataset. The stiffness and damping matrices that Adams Solver requires are defined for the
I markers only; that is, they should be derived normally using the 6(n+1) J marker and I marker degrees-of-
freedom, but are input using only the rows and columns corresponding to the I marker degrees-of-freedom.
This is equivalent, in finite element terminology, to applying fixed boundary conditions at the J marker by
simply removing the corresponding rows and columns from the matrices. Adams Solver automatically
computes and applies the correct reaction forces at the J marker.
316 Adams Solver
C++ Statements
Formulation
For n+1 points in the NFORCE system (n I markers and 1 J marker).
Action Forces (Forces on the I markers)
·
FI = - KMATRIX (X - L) - CMATRIX X + FORCE
where:
 FI is the 6n x 1 matrix of forces exerted on the I markers.
 KMATRIX is the 6n x 6n truncated stiffness matrix, created by striking out the rows and columns
associated with the J marker’s degrees-of-freedom.
 X is the 6n x 1 matrix of the translational and angular displacements of the I markers with respect to
the J marker, expressed in the J marker’s coordinate system.
 L is a 6n x 1 matrix of the reference displacements of the I markers with respect to the J marker,
expressed in the J marker’s coordinate system. The translational displacements in L are the elements
of LENGTH, while the angular reference displacements are always zero.
 CMATRIX is the 6n x 6n truncated damping matrix, created by striking out the rows and columns
 X· is the 6n x 1 matrix of the translational and linearized angular velocities of the I markers with
respect to the J marker, and expressed in the J marker’s coordinate system.
 FORCE is the 6n x 1 matrix of the reference forces on the I markers; that is, the forces on the I
markers when their displacements relative to the J marker are specified by L. When LENGTH
contains the free lengths, FORCE is the preload.
Reaction Forces (Forces on the J marker)
F jtrans = –  F itrans
i
F j rot = –  ( F irot + X ji + F i trans )

i
where:
 trans denotes translational degrees-of-freedom
 rot denotes rotational degrees-of-freedom
 Xji is the instantaneous vector from the J marker to each I marker.
NFORCE 317
C++ Statements
Tip:  When importing stiffness and damping matrices that are developed using finite element
methods, the LENGTH and FORCE arguments are most easily thought of as the system
free lengths (zero internal stress) and preloads. You can, however, specify any consistent set
of reference lengths and resulting forces, just as for the SPRINGDAMPER element.
 Physically meaningful NFORCES have positive semi-definite KMATRIX and CMATRIX
matrices. That is, the diagonal entries of the matrices have positive value. Adams Solver
only accepts NFORCES having positive semi-definite matrices.
Caution:  Like the BEAM, the NFORCE is a linear element, so that the forces computed are
generally valid only for small displacements. When the applied loading is such that the
small displacement limits are exceeded (a good estimate is ten percent of lengths and less
than 0.2 radian rotations), the NFORCE results may be less accurate. In cases where the
structure undergoes large overall deflections but remains linearly elastic (small local
deflections), you can use more NFORCE elements, so that each NFORCE element
remains locally within small displacement limits. Note that because of the way that Adams
Solver computes angular displacements, the absolute magnitude of this inaccuracy due to
overly large displacement may depend on the instantaneous spatial orientation of the
system.
 A two-point NFORCE is not identical to a field, although it is very similar. The following
differences make it difficult to create exactly equivalent NFORCEs and FIELDs.
 The FIELD defaults reference lengths to zero, while the NFORCE assumes by default
that the input positions of the I markers are at the reference locations.
 The FIELD allows you to specify reference angles for the rotational displacements,
while the NFORCE assumes the reference angles are always zero.
318 Adams Solver
C++ Statements
Examples
The figure below illustrates a simple, planar, triangular truss attached to some large base body.
Simple, Planar, Triangular Truss
The following NFORCE statement defines a 24 force components acting between Markers 10, 20, 30, and
40.
NFORCE/1234, J=10, I=20,30,40, KMATRIX=1234, CRATIO=0.02
Marker 10 is the J marker. This means Matrix 1234 is an 18-by-18 stiffness matrix relating forces to
displacements at Markers 20, 30 and 40. The forces and displacements are measured in the coordinate system
of Marker 10. Because the LENGTH argument is not included, Adams Solver measures the displacements
from the input position. Because the FORCE argument is not specified, there are no loads at the reference
position (in this case the input position). In other words, the truss has been input in the unloaded,
undeformed configuration. The damping matrix is .02 times the stiffness matrix.
Depending on the assumptions you make, the stiffness matrix for this structure could be quite elaborate. A
simple case, however, is to assume the ends of the truss members are pinned, and that the truss members only
transmit translational, in-plane forces.
Due to the simple geometry, this matrix can be determined by inspection, and is shown in the table shown
next.
NFORCE 319
C++ Statements
Simple Stiffness Matrix
Because this matrix is mostly empty, the SPARSE option on the MATRIX statement is more convenient than
listing all the matrix entries. The following MATRIX statement defines this stiffness matrix.
MATRIX/1234, SPARSE, ROW=18, COL=18,
, I=1,1,1,1,2,2,2,2,7,7,7,7,7,8,8,8,8,8,13,13,13,13,14,14,14,14,
, J=1,2,7,8,1,2,7,8,1,2,7,13,14,1,2,8,13,14,7,8,13,14,7,8,13,14,
, VALUE=150,-50,-50,50,-50,50,50,-50,-50,50,100,-50,50,
, 50,-50,200,50,-50,-50,50,150,-50,50,-50,-50,50
Applications
The NFORCE statement may be most useful for importing finite element representations of flexible
structure into an Adams Solver model, but it may also be used whenever the forces between a set of points in
the system are linearly dependent on their relative displacements and velocities. If the set includes only two
points, it is easily use one of the simpler Adams Solver force elements, SPRINGDAMPER, SFORCE,
320 Adams Solver
C++ Statements
BEAM, BUSHING or FIELD, depending on the type of forces desired. However, whenever the set includes
three or more points, you should use the NFORCE statement. (Note that some of the other force elements
do allow for nonlinear force relationships.)
You may develop the NFORCE statement stiffness and damping matrices in several ways. For simple
structures, you can derive the matrices analytically or compute them from standard formulas. For complex
cases, you can use finite element analysis (FEA) to approximate the stiffness and damping characteristics.
For example, the figure below illustrates a satellite deploying flexible panels. In this instance, the panels are
first modeled using a 6 6 finite element grid (36 elements), which are then reduced to a 3 3 grid using super-
element condensation before importing it into Adams Solver as an NFORCE. Because of formulational
differences between FEA and Adams’ multibody systems analysis, it is generally not possible to have a one-
to-one correspondence between Adams Solver PARTs and FEA nodes, unless the FEA model is very small.
Flexible Satellite Panels

OUTPUT 321
C++ Statements
OUTPUT
The OUTPUT statement controls the generation of request and graphics files.
The OUTPUT statement has been extended to control generation and format of output files from
FEMDATA or REQUEST statements. For example, it lets you generate RPC III and DAC files of Adams
Solver (C++) request data.
Format
REQSAVE
OUTPUT/ [ ,NOSEPARATOR ] [ ,YPR ]
,GRS AVE
ABAQUS
 
 ANSYS 
 
,LOADS =  DAC 
 
 NASTRAN 
 RPC 
 ANSYS 
 DAC 
 
 GENERIC 
,MODAL_DEFORMATION =  
 NASTRAN 
 PUNCH 
 
 RPC 
DACSAVE  CSV 
 
, ,MONITOR_POINTS =  GENERIC 
RPCSAVE  
 RPC 
 ANSYS 
 
,NODAL_DEFORMATION =  GENERIC 
 
 NASTRAN 
 DAC 
 
,STRAIN =  GENERIC 
 
 RPC 
 DAC 
 
,STRESS =  GENERIC 
 
 RPC 
{ } Select one item

322 Adams Solver
C++ Statements
Arguments
ABAQUS Specifies the output of FEM data to an ABAQUS-readable format. Load

data are written out as ABAQUS input commands.
ANSYS Specifies the output of FEM data to an ANSYS-readable format. Load data
or nodal deformations are written out as ANSYS input commands. Modal
deformations are written out to a file format supported by the Adams MSR
ANSYS-customized macro, available in Adams Durability
CSV Saves all monitor point FEM data to Comma Separator Value (csv) format.
This file format can be imported into spreadsheet program like Excel®
DAC Specifies the output of FEM data to DAC files. DAC is a file format
supported by nCode/nSoft. A DAC file is generated for each component of
load, stress or strain, or modal coordinate.
DACSAVE Saves all request output in DAC format. If you do not specify DACSAVE,
Adams Solver (C++) does not save request data in DAC format.
GENERIC Specifies the output of FEM data to a human-readable (ASCII) text file.
GRSAVE Saves graphics output in the graphics file so a postprocessor can be used to
display graphics. If neither GRSAVE nor GR521SAV is specified, Adams
Solver (C++) does not save graphics output in the graphics file.
LOADS Controls output of FEM data to the specified format. If you do not specify
LOADS, Adams Solver (C++) does not process any FEMDATA/LOADS
statements.
MODAL_DEFORMATIO Controls output of modal deformation data to the specified format. If you
N do not specify MODAL_DEFORMATION, Adams Solver (C++) does not
process any FEMDATA/MODAL_DEFORMATION statements.
MONITOR_POINTS Controls output of monitor point data to specified format. If you do not
specify MONITOR_POINTS, no monitor point data will be output.
NASTRAN Specifies the output of FEM data to a NASTRAN-readable format. Load
data or nodal deformations are written out as NASTRAN input commands.
Modal deformations are written out to NASTRAN OUTPUT2 (binary)
format.
NODAL_DEFORMATIO Controls output of nodal deformation data to the specified format. If you
N do not specify NODAL_DEFORMATION, Adams Solver (C++) does not
process any FEMDATA/NODAL_DEFORMATION statements.
OUTPUT 323
C++ Statements
NOSEPARATOR Specifies that Adams Solver (C++) is not to write separators to the request,
graphics, results, and tabular output files when you modify the model
topology in the middle of a simulation. You can change the model topology
by using interactive commands to activate an element, deactivate an
element, change a marker position, or change the type or point of
application of a force or constraint during a simulation.
When you change the model topology, by default, Adams Solver (C++)
writes a separator and new header to the request, graphics, results, and
tabular output files. Adams Solver (C++) then writes subsequent simulation
output after the new headers. This ensures that the changes are correctly
reflected in the output files, but it creates two sets of output that cannot be
plotted or animated continuously. The NOSEPARATOR argument
prevents Adams Solver (C++) from breaking up the files; instead it creates a
continuous set of output that can be plotted and animated from beginning
to end.
Note: This output may be misleading because the graphics file does not
include the effects of any changes in marker, force, or constraint
positions during the simulation. While the part motions are
correct, the force, joint, and marker graphics remain in their
original positions, even if you move them during the simulation.
PUNCH Specifies modal deformations to be output to NASTRAN PUNCH (text
file) format.
REQSAVE Saves request output in the request file so that you can use a postprocessor
to display x-y plots. If you do not specify REQSAVE, Adams Solver (C++)
does not save the request output in the request file.
RPC Saves FEM data output in RPC III format.
RPCSAVE Saves all request output in RPC III format. If you do not specify RPCSAVE,
Adams Solver (C++) does not save request data in RPC III format.
324 Adams Solver
C++ Statements
STRAIN Controls output of strain data to the specified format. If you do not specify
STRAIN, Adams Solver (C++) does not process any FEMDATA/STRAIN
statements.
Note: An Adams Durability license is required to output STRAIN.

STRESS Controls output of stress data to the specified format. If you do not specify
STRESS, Adams Solver (C++) does not process any FEMDATA/STRESS
statements.
Note: An Adams Durability license is required to output STRESS.

YPR Outputs rotational displacement values in yaw, pitch, and roll coordinates,
rather than in psi, theta, and phi coordinates. Using dashed lines to
represent original orientations and using solid lines to represent new
orientations, Figure below shows how these coordinates define a rotational
orientation.
Figure. Successive Yaw, Pitch, and Roll Rotations
First, Adams Solver (C++) rotates about the z-axis. Next, it makes a negative
rotation about the new y-axis (y'), and then about the second new x-axis
(x"). If you do not specify YPR, Adams Solver (C++) outputs rotational
displacement values in psi, theta, and phi coordinates.
YPR only affects rotational displacement output. Adams Solver (C++)

always outputs angular velocities and accelerations as vectors, with
orthogonal x, y, and z components.
Extended Definition
The OUTPUT statement controls the generation and format of REQUEST or FEM data. Specifically, the
OUTPUT statement controls the following:
 Output of FEMDATA
 Output of Request Data in RPCIII and DAC Formats
OUTPUT 325
C++ Statements
Output of FEMDATA
With LOADS, the ABAQUS, ANSYS, or NASTRAN format option creates a text file of the input
commands of the respective FEA package (case control and bulk data in the case of NASTRAN) of all the
part forces.
With NODAL_DEFORMATION, the ANSYS or NASTRAN option creates a text file of input commands
for defining enforced displacements in the respective FEA package (for example, SPC* cards in the case of
NASTRAN).
With MODAL_DEFORMATION, the NASTRAN option produces an OUTPUT2 (NASTRAN binary)
file. This file can be imported by NASTRAN for stress recovery on the flexible body with the Adams
Durability Modal Stress Recovery DMAP. Note that this file format is machine dependent. NASTRAN will
not be able to read the file if it was created on a platform different than the one running NASTRAN.
Alternatively, the PUNCH format option for MODAL_DEFORMATIONS produces a text file that can be
imported by NASTRAN for stress recovery. This file format is not as compact as the OUTPUT2 format (see
NASTRAN option), but it is machine independent. If NASTRAN is run on a different platform than
Adams, the modal deformations can be transferred using this file format for subsequent NASTRAN runs.
Also, with MODAL_DEFORMATIONS, the ANSYS option produces a file of modal deformations. This
file can be processed by ANSYS using a custom macro provided by the Adams Durability. Modal
deformations can be combined with the modal stress shapes stored in the ANSYS database to recover dynamic
stresses in ANSYS using modal superposition.
Output of Request Data in RPCIII and DAC Formats
You can save request data in RPC III and DAC format.
 RPC III format- Adams Solver (C++) creates one RPC file of all data components specified in the
REQUEST statements.
The RPC III file is named according to the naming convention:
Prefix.rsp
where:
• Prefix is the prefix specified when you set up Adams results.
 DAC format - Adams Solver (C++) can only store one channel of data in a DAC file. Therefore,
Adams Solver (C++) creates six DAC files, one per request component. The files are named
according to the DAC file naming convention:
prefix_request name_component label.dac
where:
• prefix is the prefix you specified when you set up the Adams results.
• request name is the request name you specified when you created a new request.
• component label is the reserved label assigned to the six components of request data by Adams
(one of X, Y, Z, R1, R2, R3).
326 Adams Solver
C++ Statements
Examples
OUTPUT/GRSAVE, REQSAVE
This OUTPUT statement causes Adams Solver (C++) to save both graphics and request output.
, FILE=adams
, NODE=100, 200, 300
OUTPUT/STRESS=DAC
DAC files are created with the job name adams in the FLEX_BODY_201 subdirectory. Each DAC file
contains the time history of one of the six stress components (Sx, Sy, Sz, Txy, Tzx, Tyz) at a node. Since three
nodes are specified, a total of eighteen DAC files are created.
OUTPUT/MODAL=NASTRAN, NODAL=GENERIC
A NASTRAN binary file will be created of each FEMDATA statement with modal deformations. No output
files will be generated for loads, strain or stress since no OUTPUT specification was given for these types of
FEMDATA.
REQUEST/1, DISPLACEMENT, I=201, J= 103, TITLE=REQ01
OUTPUT/DACSAVE
This OUTPUT statement causes Adams Solver (C++) to save request output defined in the above
REQUEST statement to DAC files only. Adams Solver (C++) creates a total of six DAC files in the current
working directory with the following names:
adams_req01_x.dac
adams_req01_y.dac
adams_req01_z.dac
adams_req01_r1.dac
adams_req01_r2.dac
adams_req01_r3.dac
REQUEST/1, FORCE, I=201, J=103, TITLE=REQ01
REQUEST/3 FORCE, I=203, J=105, TITLE=REQ03
OUTPUT, RPCSAVE
This OUTPUT statement causes Adams Solver (C++) to save request output defined in the three REQUEST
statements to an RPC III file. Adams Solver (C++) creates one RPC III file named Adams.rsp, containing 18
channels of data (six per REQUEST statement).
PART 327
C++ Statements
PART
The PART statement defines the inertial properties of a rigid body and its initial position, orientation, and
velocity. Parts can have any shape or size and are the only model elements that can have mass, although they
can be massless under certain circumstances. Adams Solver (C++) assumes that all parts are rigid bodies. The
PART statement is also used to specify which part is used as the fixed inertial (or ground) global coordinate
system. Each movable part (that is, other than ground) can add up to six degrees of freedom (DOF) to a
system.
Format
328 Adams Solver
C++ Statements
Arguments
CM=id Specifies the identifier of the marker that defines the location of the part center of mass
and, in the absence of the inertia marker, the orientation of the inertia axes for the IP
values.
EXACT=c1:...:c6 Specifies as many as six part coordinates that Adams Solver (C++) should not change as
it iteratively solves for initial conditions that satisfy all constraints. The six coordinates
are
:
X x coordinate
Y y coordinate
Z z coordinate
PSI Psi angle
THETA Theta angle
PHI Phi angle
These coordinates can be entered in any order following EXACT. Adams Solver (C++)
does not change these unless the values specified are inconsistent with initial conditions
for a joint or defined motion.
GROUND Indicates the part being defined as the Newtonian reference frame. It is, by definition,
at absolute rest. Because there can be only one ground part in the system, a dataset must
never have more than one PART statement with the GROUND argument.
IM=id Specifies the identifier of the marker about which you specify the moments of inertia
for the part. This marker can be any marker in the part. The IM marker defaults to the
CM marker.
PART 329
C++ Statements
IP=xx,yy,zz[,xy,xz, Specifies the mass-inertia tensor as computed about the origin of the IM marker,
yz] expressed in the coordinate system of the IM marker.
You can compute the individual terms of the IP argument as:
In the above formulae, x, y, and z are the components of the displacement of the center
of an infinitesimal volume of mass dm, measured from the origin of the inertia marker
in the coordinate system of the inertia marker. The integral is performed over the entire
volume of the body. If the inertia marker is not specified, it defaults to the CM marker.
In that case, these quantities are computed about the origin of the CM marker in the
coordinate system of the CM marker.
Note: Adams Solver (C++) defines Ixy, Ixz and Iyz as positive integrals, as shown.
Some references define these terms as the negative of these integrals. Be sure
to compute these values as shown above. See section Inertia input data for more
information.
MASS=r Specifies the part mass.
PLANAR Indicates that the part only has three degrees of freedom. These are global x and y
translations and a rotation about the global z axis. The body can have a constant z offset
as given by the QG argument.
It is best to think of the planar part as a regular 3D part with a built-in planar joint
connected to ground.
QG=x,y,z Defines the Cartesian initial coordinates of the origin of the body coordinate system
(BCS) with respect to the global coordinate system (GCS).
330 Adams Solver
C++ Statements
REULER=a,b,c Defines the 3-1-3 Euler angles that Adams Solver (C++) uses to establish the initial
orientation of the BCS with respect to the coordinate system. The a, b, and c rotations
are in radians and are, respectively, about the z-axis of ground, the new x-axis, and the
new z-axis of the BCS. To input Euler angles in degrees, add a D after each value.
VM=id Specifies the identifier of the marker that specifies the direction of translational velocity
initial conditions (VX, VY, and VZ). VM defaults to global orientation.
VX=x, VY=y, Specifies the initial translational velocities of the CM marker with respect to the ground
VZ=z coordinate system (GCS) along the x-axis (VX), the y-axis (VY), and the z-axis (VZ) of
the VM coordinate system.
WM=id Specifies the identifier of the marker that specifies the axes about which angular velocity
initial conditions (WX, WY, and WZ) are defined. WM defaults to the CM location
and orientation. The origin of the WM marker lies on the axis of rotation. This is most
useful for rotating systems. A typical application is a spinning flexible satellite model in
space. In this case, you add a marker to your system at the combined CG location of
the system and orient the marker such that one of its axes is along the spin axis of the
satellite.
WX=a, WY=b, Specifies the initial rotational velocities, in radians per second, of the part about the x-
WZ=c axis (WX), the y-axis (WY), and the z-axis (WZ) of the WM coordinate system.
Note: WM can also contribute to the initial translation velocities, V as

V′ = V + ( ω × R )
XG=x,y,z Defines the coordinates, measured in the GCS, of any point in the positive x-z plane of
the part BCS, but not on the z-axis of the part BCS.
XY Specifies that a planar part will move in the global xy plane. The argument can only
appear with the PLANAR argument and is the default.
YZ Specifies that a planar part will move in the global yz plane. The argument can only
appear with the PLANAR argument. If it is not provided, the planar part will move in
the global xy plane.
ZG=x,y,z Defines the coordinates measured in the GCS of any point on the positive z-axis of the
BCS.
ZX Specifies that a planar part will move in the global zx plane. The argument can only
appear with the PLANAR argument. If it is not provided, the planar part will move in
the global xy plane.
PART 331
C++ Statements
Tip:  If the part has no CM marker, as may be the case for some massless parts, Adams Solver
(C++) uses the part BCS to represent the position and orientation of the part internally.
For more information on BCS, see Coordinate Systems and Local Versus Global Geometric Data.
 Using a CM on a massless part can improve model robustness by removing large offsets
between the BCS and markers on the massless part, without repositioning all the markers
on the massless part. Do not be confused by the contradiction of specifying a center-of-
mass on a massless part. In this case, the CM marker is simply suggesting an advantageous
choice of internal coordinate systems.
 If the part has mass, Adams Solver (C++) uses the position of the CM marker to represent
the translational position of the part internally and uses the principal axes of the inertia
tensor about the CM marker to represent the orientation of the part internally. This
internal coordinate system is commonly referred to as the part principal coordinate system.
 Because of a basic property of Euler angles, a singularity occurs when the principal z-axis of
the CM becomes parallel to the ground z-axis. Whenever the principal z-axis of the part
nearly parallels the ground z-axis, Adams Solver (C++) rotates the part principal axes 90
degrees about the z-axis and then 90 degrees about the new x-axis to avoid the singularity.
Adams Solver (C++), however, does not change the marker locations and orientations with
respect to the BCS nor does it alter the BCS location or orientation with respect to
ground. (The principal axes of the inertia tensor of the CM are referred to as the part
principal axes.)
 The BCS for each part can have any position and orientation. In fact, the location of the
BCS does not have to be within the physical confines of the part. It may be at some
convenient point outside the actual part boundaries.
 To superimpose the BCS of a part on the GCS, define QG=0,0,0 and REULER=0,0,0 or
let QG and REULER default. The position and orientation data for the markers on the
part is now with respect to the GCS.
 As stated earlier, the planar can be viewed as a normal 3D part with a built-in planar joint.
This is a combination of elements often found in certain models that contain 2D
subsystems. Unlike a part and a planar joint pair that combine to add 18 equations to an
index-3 dynamic analysis in Adams Solver, the planar part only adds 6 equations.
 This is not an attempt to create a 2D version of Adams. Because the planar part can be
contained in a full 3D Adams model and coexist with, and be connected to, 3D part
elements, performance will not compare with a 2D dynamics analysis software.
332 Adams Solver
C++ Statements
Caution:  Each part defined with the PART statement, with the exception of ground, must have at
least one marker associated with it (see MARKER).
 For the argument IP, if you specify one of the moments of inertia (xx, yy, or zz), you must
also specify the other two. Similarly, if you specify one of the products of inertia (xy, xz, or
yz), you much also specify the other two.
 Make sure the units for mass moments of inertia and for mass products of inertia are
consistent with the units for the rest of the system.
 Parts that are not fully constrained (that is, they can move dynamically because of the
effect of forces) must have nonzero masses and/or inertias. You may assign a default zero
mass to a part whose six degrees of motion are fully constrained with respect to parts that
do have mass.
 EXACT, VX, VY, VZ, WX, WY, and WZ arguments ensure that the corresponding
displacements or velocities are maintained to an accuracy of six digits. Accuracy beyond six
digits is not guaranteed.
 Use the EXACT, VX, VY, VZ, WX, WY, and WZ arguments with caution. Do not specify
more initial displacements to be exact than the system has degrees of freedom. After you
are sure the system has zero or more degrees of freedom, look at the model and see if the
remaining set of part motions will permit Adams Solver (C++) to adjust the system to
satisfy all the initial conditions. Remember that IC, ICTRAN, and ICROT arguments on
the JOINT statement remove degrees of freedom from a system during initial conditions
analysis. Similarly, do not specify more initial velocities than the system has degrees of
freedom.
 A part without mass cannot have moments of inertia, initial conditions on displacement or
velocity, or an IM marker.
 If you specify the mass for a part, you must also specify the CM marker for the part.
 A planar part is implicitly constrained to move in a plane at a fixed global value of Z. Any
force applied to the planar part in the global Z direction will be discarded. The same
applies to torques about the global X and Y axes. It is not possible to measure the reaction
forces required to constrain the planar part to stay in plane. If such forces are desired, the
equivalent part and planar joint combination must be substituted.
Examples
PART/01, GROUND
The PART statement above indicates that Part 1 is the ground part.
PART/02, MASS=2, CM=0201, IP=5,6,10
The PART statement above specifies the mass (2 units), the center-of-mass marker identifier (0201), and the
principal moments of inertia for Part 2:
 Ixx = 5 units
 Iyy = 6 units
PART 333
C++ Statements
 Izz = 10 units
The principal moments of inertia are about the x-axis (5), the y-axis (6), and the z-axis (10) of the center-of-
mass marker. Because this statement includes no arguments that define the orientation or position of Part 2,
Adams Solver (C++) superimposes Part 2 on the ground coordinate system (GCS). This statement identifies
no IM marker, so Adams Solver (C++) assumes that the inertias are defined with respect to the part CM
marker.
PART/04, MASS=.5, CM=0407, QG=10,0,0
The statement above specifies:
 Mass (.5 units)
 Center-of-mass marker identifier (0407)
 Initial position of the BCS (10,0,0) with respect to the ground coordinate system (GCS).
This statement does not define the principal moments of inertia, so the inertia of the part is zero about each
of the CM marker axes. In addition, this statement has no arguments to indicate the orientation of Part 4, so
Adams Solver (C++) aligns the axes of the BCS of Part 4 with the axes of the GCS.
Inertia input data

The inertia matrix to be assembled into the equations of motion is the following:
2 2
 (y + z ) dm –  xy dm –  xz dm
2 2
J = –  xy dm  (x + z ) dm –  yz dm
2 2
–  xz dm –  yz dm  (x + y ) dm
A lot of confusion arises by the way different computer codes ask for above entries of the J matrix. There are
two conventions. On one hand, some computer programs define the J matrix as follows (this is not the way
Adams Solver defines the J matrix):
Ixx Ixy Ixz

J = Ixy Iyy Iyz .
Ixz Iyz Izz
Clearly, the user is requested to compute the above values of Ixx, Iyy, Izz, Ixy, Ixz and Iyz. If that is the case,
the user needs to compute say
Ixy = –  xy dm
and enter that value.
On the other hand, some other computer programs (for example, Adams Solver) define the J matrix as
follows:
334 Adams Solver
C++ Statements
Ixx – Ixy – Ixz

J = – Ixy Iyy – Iyz .
– Ixz – Iyz Izz
In that case the user is requested to compute
Ixy =  xy dm
and enter that value. In other words, the negative sign is applied by the computer code. Adams Solver follows
the latter convention. Both Adams Solver and Nastran follow the same convention.
PINPUT 335
C++ Statements
PINPUT
The PINPUT statement defines a list of VARIABLE statements that Adams Solver (C++) recognizes as
system input during a LINEAR/STATEMAT analysis (see the LINEAR command).
Format
PINPUT/id, VARIABLES=id1[,id2,...]
Arguments
VARIABLES=id1[,id2,...] Specifies the VARIABLE statements used as inputs by the Adams Solver
(C++) model.
Extended Definition
The PINPUT statement, along with a POUTPUT statement, is used with the LINEAR/STATEMAT
command. PINPUT defines a set of inputs to the mechanical system, and POUTPUT defines the set of
measured outputs from the system. The LINEAR/STATEMAT command linearizes the system equations to
the following form
x· = Ax + Bu
y = Cx + Du
where x is the linearized system state array, u is the array of system inputs defined by the PINPUT statement,
and y is the array of system outputs defined by the POUTPUT statement. This form is commonly referred
to as the state space form of the system equations in control theory. Adams Solver (C++) outputs the A, B,
C, and D matrices for use in a control-system design or any other linear system analysis software. If only the
A matrix is required, PINPUT and POUTPUT are not necessary.
When you run an analysis type other than LINEAR/STATEMAT, the PINPUT statement acts only as a
pointer to the list of the specified VARIABLE statements.
Both function expressions and user-written subroutines can access the PINPUT statement. Function
expressions access the values by using the internal Adams Solver (C++) function PINVAL(i1,i2) (see the
PINVAL function), where i1 specifies the PINPUT id, and i2 specifies the i2th VARIABLE in the PINPUT
statement list. Note that i2 is not the id of the VARIABLE statement.
User-written subroutines call the subroutine SYSFNC to access single elements of the PINPUT list and call
the subroutine SYSARY to access all values for a PINPUT (see SYSARY and SYSFNC subroutines).
Tip: VARIABLE statements may appear in more than one PINPUT statement. This allows you
to output two or more sets of state matrices at the same time.
336 Adams Solver
C++ Statements
Examples
PINPUT/3, VARIABLES=12,13,25
This PINPUT statement identifies VARIABLES 12, 13, and 25 as inputs to the mechanical system. These
variables might appear in expressions for computing actuating forces, for instance. You may refer to this
PINPUT in a LINEAR/STATEMAT command.
Applications
The PINPUT statement along with the POUTPUT, VARIABLE, ARRAY, TFSISO, LSE, and GSE
statements make up the interface between Adams Solver (C++) and control design and analysis packages such
as MATRIXx and MATLAB.
As shown in the figure below, PINPUT and POUTPUT act as sockets for input and output to your
controller, organizing the VARIABLE wires.
PINPUT and POUTPUT as Sockets
The LINEAR command uses PINPUT and POUTPUT statements to identify which variables to consider
system inputs and outputs when generating state matrices. A control design program can use these matrices
to design a controller for the system. The resulting controller may then be included in the Adams Solver
(C++) model using VARIABLE, ARRAY, TFSISO, LSE, or GSE statements.
POINT_MASS 337
C++ Statements
POINT_MASS
The POINT_MASS statement defines a point mass. Point masses may have mass, position, and translational
velocities. They may also have orientation, but this orientation is constant during the course of a simulation.
Point masses, unlike parts, may not have inertias or angular velocities. Each POINT_MASS adds three
degrees of freedom to a system.
Similarly, translational forces that can be applied to point masses are limited to:
 ACCGRAV
 TRANSLATIONAL SFORCE
 TRANSLATIONAL SPRINGDAMPER
 VFORCE
Format
338 Adams Solver
C++ Statements
Arguments
CM=id Specifies the identifier of the marker that defines the location of the point mass
relative to the local body coordinate system (BCS).
Default: None
Range: Valid fixed MARKER id’s

EXACT=c1:c2:c3 Specifies as many as three point mass coordinates that Adams Solver should not
change as it iteratively solves for initial conditions which satisfy all constraints. The
three coordinates are below.
x x coordinate
y y coordinate
z z coordinate
These coordinates can be entered in any order following EXACT. These are not
changed by Adams Solver (FORTRAN) unless the values specified are inconsistent
with initial conditions for a joint or motion.
Default: None
Range: X, Y, or Z
MASS=r Specifies the magnitude of the mass.
Default: 0
Range: r > 0
QG=x,y,z Defines the Cartesian initial coordinates of the BCS with respect to the global
coordinate system.
Default: 0.0, 0.0, 0.0

Range: Any real values
REULER=a,b,c Defines the 3-1-3 Euler angles that Adams Solver uses to establish the initial
orientation of the BCS with respect to the coordinate system. The a, b, and c
rotations are in radians and are, respectively, about the z-axis of ground, the new
x-axis, and the new z-axis of the BCS. To input Euler angles in degrees, add a D
after each value.
Defaults: 0.0, 0.0, 0.0 when REULER, XG, and ZG are omitted
POINT_MASS 339
C++ Statements
VX=x, VY=y, VZ=z Specifies the initial translational velocities of the CM marker with respect to the
ground coordinate system (GCS) along the x-axis (VX), y-axis (VY), and z-axis
(VZ) of the global coordinate system.
Default: Inexact 0, 0, 0
XG=x,y,z Defines the coordinates, measured in the global coordinate system, of any point in
the positive x-z plane of the part BCS, but not on the z-axis of the part BCS.
Default: If ZG is omitted, XG is oriented like the global x-axis

ZG=x,y,z Defines the coordinates measured in the global coordinate system of any point on
the positive z-axis of the BCS.
Default: If XG is omitted, ZG is oriented like the global z-axis

Extended Definition
Although the point mass concept would normally suggest a particle, this is not how a point mass is
implemented in Adams. If a particle is subjected to a torque, a singularity ensues. This was not considered a
practical behavior for an element in Adams.
Rather than thinking of the point mass as a particle think of it as a rigid body with built-in angular constraints
removing any rotational degrees of freedom. It is legal to apply torques to a point mass, and such torques are
simply discarded. If one takes care not to apply a torque, the Adams point mass behaves exactly like a particle.
The point mass offers all the computational benefits of a particle without the complications which would
arise from forbidding the application of a torque.
340 Adams Solver
C++ Statements
Tip:  All markers on a point mass that are involved in constraints or are at force application
points should be at the point mass CM. Otherwise, Adams Solver issues a warning. Adams
Solver does not generate moments due to offsets from CM.
 The CM can be offset from the BCS, but still the markers involved in constraints or at
force application points must be at the CM.
 Markers on a point mass to which no constraints or forces are applied (such as markers for
only graphics or requests), do not have to be on the CM.
 Function expressions may reference markers associated with point masses. However,
Adams Solver rejects expressions that should not refer to point mass markers, such as TM,
TX, TY, TZ, and NFORCE. You may use point mass markers in rotational function
expressions (such as AX, PSI, WY, and WDTZ), but remember that the orientation of
point mass markers is constant and their rotational velocities and accelerations are always
zero with respect to the ground coordinate system (GCS).
 Adams Solver permits you to request displacements, velocities, accelerations, and forces
between two point mass markers. However, the rotational displacements are always
constants, the rotational velocities are always zero, the rotational accelerations are always
zero, and the torques are zero.

POUTPUT 341
C++ Statements
POUTPUT
The POUTPUT statement defines a list of VARIABLE statements that Adams Solver (C++) recognizes as
system output during a LINEAR/STATEMAT analysis (see the LINEAR command).
Format
POUTPUT/id, VARIABLES=id1[,id2,...]
Arguments
VARIABLES=id1id1[,id2,...] Specifies the VARIABLE statements that describes the outputs of the
Adams Solver (C++) model.
Extended Definition
The POUTPUT statement, along with a PINPUT statement, is used with the LINEAR/STATEMAT
command. POUTPUT defines the set of measured outputs from the system and PINPUT defines a set of
inputs to the mechanical system. The LINEAR command linearizes the system equations to the following
form:
x· = Ax + Bu
y = Cx + Du
where:
 x is the linearized system state array
 u is the array of system inputs defined by the PINPUT statement.
 y is the array of system outputs defined by the POUTPUT statement.
This form is commonly referred to as the state space form of the system equations in control theory. Adams
Solver (C++) outputs the A, B, C, and D matrices for use in a control-system design or any other linear system
analysis software. If only the A matrix is required, PINPUT and POUTPUT are not necessary.
When you run an analysis type other than LINEAR, the POUTPUT statement acts only as a pointer to the
list of VARIABLE statements specified.
Both function expressions and user-written subroutines can access the POUTPUT statement. Function
expressions access the values by using the internal Adams Solver (C++) function POUVAL(i1,i2) (see the
PINVAL function), where i1 specifies the POUTPUT id, and i2 specifies the i2th VARIABLE in the
POUTPUT statement list. Note that i2 is not the id of the VARIABLE.
User-written subroutines access single elements of the POUTPUT list and call the subroutine SYSFNC to
access all values for a POUTPUT by calling the subroutine SYSARY (see the SYSARY and SYSFNC subroutines).
342 Adams Solver
C++ Statements
Tip: VARIABLE statements may appear in more than one POUTPUT statement. This allows
you to output two or more sets of state matrices at the same time.
Examples
POUTPUT/4, VARIABLES=4,8,9,10
This POUTPUT statement identifies VARIABLES 4, 8, 9, and 10 as outputs from the mechanical system.
These variables might represent part displacements and velocities, for instance. You may refer to this
POUTPUT in a LINEAR/STATEMAT command.
Applications
The POUTPUT statement with the PINPUT, VARIABLE, ARRAY, TFSISO, LSE, and GSE statements
define the interface between Adams Solver (C++) and control design and analysis packages such as MATRIXx
and MATLAB.
As shown in the figure below, PINPUT and POUTPUT act as socket for input and output to your controller,
organizing the VARIABLE wires.
(C++) model using VARIABLE, ARRAY, TFSISO, LSE, or GSE statements. See the LINEAR command.
PINPUT and POUTPUT as 'Sockets'

PREFERENCES 343
C++ Statements
PREFERENCES
The PREFERENCES statement controls general options that apply to the model defined in the Adams
Solver (C++) dataset or the commands defined in the Adams Solver (C++) command file.
Format
Note: NTHREADS is an option for PREFERENCES C++ statement, so it would go in the Adams
dataset, that is ADM file.
344 Adams Solver
C++ Statements
Arguments
PREFERENCES 345
C++ Statements
Select the geometry library to be used for contact operations:
 Parasolid - Specifies the Parasolid geometry library be

used for three-dimensional contact determination. Adams
Solver (C++) supports Parasolid version 28.1.238.
 Default_library - Specifies that the default geometry
library be used for three-dimensional contact
determination. The default library is based on RAPID, a
polygon-based interface detection package developed at
the University of North Carolina. Currently, Adams
Solver (C++) supports RAPID 2.01.
For many models, the Default Library can substantially reduce
simulation time. Because it is polygon-based, however, it is not
always as accurate as the Parasolid geometry engine. Parasolid is an
exact boundary-representation geometric modeler, which makes it
highly accurate, but not as fast as a polygon-based engine. For these
reasons, you can switch from one to the other depending on your
needs.
CONTACT_FACETING_TOLERANCE=value Specifies the resolution of the mesh that is to be created from the
solid geometries in the model. Contact kinematics are calculated
by intersecting the meshes corresponding to two solid geometries.
A finer mesh results in more accurate contact calculations.
Calculations may be slower, however, and computer memory
requirements increase as the mesh resolution increases.
The faceting tolerance is defined as the maximum error between

the true surface and the surface of the faceted representation of the
geometry. The maximum error is guaranteed not to exceed
(1/value) * the minimum dimension of each geometry's bounding
box.
The default value of this parameter is 300.0028.
The value specified for the faceting tolerance only applies to

geometry read from a Parasolid file. All native geometry (ellipsoid,
cylinder, box, frustum, torus, surface of revolution, and extrusion)
is tessellated with a fixed tolerance when a faceting tolerance is
specified. Stl and shl files have fixed faceting that cannot be
changed.
LIBPATH=dir1:dir2:... Specifies a colon-separated list of directories which are to be
searched for user subroutine plug-in libraries before searching in
the default locations. See the ROUTINE Argument for more
information.
346 Adams Solver
C++ Statements
NTHREADS=n Specifies the number of parallel threads that Adams Solver (C++)
will use when performing the simulation.
The number of threads, n, must be an integer in the range of 1 to

128. The default value is 1.
By executing multiple threads in parallel across multiple

processors, Adams Solver (C++) can reduce the walltime required
for a simulation.
Typically, the optimal number of threads is between N and 2N,

where N is the number of processors (including virtual processors,
such as Pentium processors supporting HyperThreading).
Note that this option has no effect on IRIX architectures.
Note: The Intel® Pentium® 4 processor introduced a feature

called Hyper Threading, where a single physical
processor can support more than one logical instruction
stream, simulating multiple logical processors on a single
physical processor. For many applications and
environments, this capability may offer performance
improvements over non-Hyper Threading processors. If
multiple analysis jobs are running concurrently, however,
there may be performance degradations. If an
installation determines this to be the case, hyper
threading should be disabled. This can be done on a
permanent basis through BIOS operations or, for
Windows platforms, hyper threading may be disabled on
a process by process basis using the “hyperthreads”
keyword.
Learn about Threaded (Parallel) Operation of Adams Solver(C++).
STATUS_MESSAGE Controls the presence of two status messages in the .msg file
produced by Adams Solver (C++). These status messages mimic
status messages produced by Adams Solver (FORTRAN). This
preference has no effect on Adams Solver (FORTRAN).
Default: OFF
The first status message is sent after every simulation and has the
form “Simulate status =i”.
The second message is sent when Adams Solver (C++) terminates

and has the form “Termination status = i”.
In both cases, “i” is an integer number reporting the status.

PREFERENCES 347
C++ Statements
FLEX_LIMIT_CHECK={skin, SELNOD} Enables flexible body linear limit checking on all the flexible
bodies.
 skin - Adams Solver (C++) will check the deformation of

all the nodes on the skin to see whether they exceed the
linear limit. To use this option, MNF_FILE or DB_FILE
need to be specified in FLEX_BODY statement.
 SELNOD - Adams Solver (C++) will only check the nodes
specified in SELNOD section in MTX file.
The linear limit is defined as 10% of the characteristic length of the
flexible body. User can use CHAR_LEN in FLEX_BODY
statement to specify the characteristic length. If CHAR_LEN is
not specified, Adams Solver (C++) will try to calculate the
characteristic length use MNF or MD DB if MNF_FILE or
DB_FILE is specified. Otherwise, Adams Solver (C++) will issue a
warning.
FLEX_LIMIT_CHECK_ACTION={HALT, Specifies what action Adams Solver (C++) should take if a flexible
RETURN, MESSAGE_ONLY} body exceeds its linear limit.
 HALT - Terminates execution of Adams Solver (C++).

 RETURN - Stops the simulation and returns to the
command level.
 MESSAGE_ONLY - Issue a warning message only
(Default).
FLEX_BODY_FORMULATION = {ORIGINAL, Specifies which formulation Adams Solver (C++) should use for all
OPTIMIZED, MAX_OPTIMIZATION} the flexible bodies in model
 ORIGINAL: This is the conventional flexible body

formulation in which all the equations are solved
simultaneously.
 OPTIMIZED: In this formulation, the 'modal equations' of
each flex body are solved separately from the rest of equations.
A separate numerical integrator is used for each subsystem of
modal equations.
 MAX_OPTMIZATION: In this formulation, the 'modal
equations' of each flex body are solved separately from the rest
of equations using semi-analytical solution method.
Please see Formulations in Adams Solver for more details.
Threaded (Parallel) Operation of Adams Solver(C++)

Adams Solver (C++) allows for threaded operations (multiple threads of execution operating in parallel).
Selecting multiple threads can allow Adams Solver (C++) to take advantage of systems with multiple
348 Adams Solver
C++ Statements
processors and, therefore, reduce the walltime for a simulation to complete (that is, the amount of time the
operator spends waiting).
The reduction in execution time that threaded operation can provide depends greatly on the particular model
being simulated. You can expect walltime speed ups of 1.2 times (serial execution time/threaded execution
time). Depending on the model, however, anywhere from no speed improvement to more than 2 times are
possible.
Models that reference user-written subroutines will not see the full benefit of parallelization unless the user-
written subroutines declare themselves as threadsafe. See the utility subroutine, ADAMS_DECLARE_THREADSAFE,
for more information.
Note that some differences in simulation results are expected between the different versions of Adams Solver
(C++). These are due to roundoff and code reorganization and do not represent an error. The results of
threaded simulations should always be carefully checked to determine whether or not the solution quality is
acceptable. In particular, repeated simulations of the same model should give identical answers. If not, the
degree of parallelization should be reduced, first by removing calls to
ADAMS_DECLARE_THREADSAFE, and if that isn't sufficient, by setting
PREFERENCES/NTHREADS=1, until the results are correct.
Examples
Using the Parasolid geometry provided by MSC Software:
PREFERENCES/CONTACT_GEOMETRY_LIBRARY=Parasolid
Loading a user subroutine plugin:
VARIABLE/1, ROUTINE=foo::bar, FUN=USER(2,3)
PREFERENCES/LIBPATH=/home/joe/plugins:/usr/projects/lifters
Adams Solver (C++) searches for a user subroutine named BAR in a dynamically loaded library named
libfoo.so (see documentation for ROUTINE Argument for more information about library name rules) in the
directories /home/joe/plugins and /usr/projects/lifters, before searching in the default plugin directories.
Caution: The LIBPATH argument only influences the search for the highest level plugin library. For
example, if a plugin library, libA.so, depends on another library, libB.so, and this library is
located in a directory specified by LIBPATH, then libB.so will not be found, unless the
DT_RPATH or DT_RUNPATH attributes are present on libA.so, as specified (often with
an -rpath option) during the creation of libA.so. This shortcoming of LIBPATH is
unavoidable, because the dependency on libB.so is resolved by the underlying runtime
loader, whose search paths cannot be altered at run-time.

PSTATE 349
C++ Statements
PSTATE
The PSTATE statement defines a set of user-defined coordinates to be used during a LINEAR analysis (see
the LINEAR command).
You can specify as many states as there are degrees-of-freedom. If a smaller set of states are provided, then the
system will "fill in" by choosing a set of internally available states for the ones that were not explicitly
specified. If too many states are specified, Adams Solver (C++) identifies and discards the redundant states.
For theoretical details, see the white paper in Simcompanion Knowledge Base Article KB8016460.
For an example of using PSTATE, see Simcompanion Knowledge Base Article KB8016414.
Format
PSTATE/id, VARIABLES=id1[,id2,...]
Arguments
VARIABLES=id1[,id2,...] Specifies a list of VARIABLE statements. Each VARIABLE must define a

displacement or angular expression; the expressions must be nonconstant.
The VARIABLE expressions constitute a set of user-defined coordinates to

be used during a linearization or eigensolution computation.
Extended Definition
The PSTATE statement is used with the LINEAR/STATEMAT or LINEAR/EIGENSOL or LINEAR/MKB
command. PSTATE defines a set of user-defined coordinates. The LINEAR/STATEMAT command
linearizes the system equations to the following form:
x· = Ax + Bu
y = Cx + Du
where:
 x is the linearized system state array.
Solver (C++) outputs the A, B, C, and D matrices for use in a control-system design or any other linear system
analysis software.
By default, the system state array x is a subset of the system coordinates (and respective derivatives) used by
Adams Solver (C++) to build the linearized equations. The system coordinates are global rotations (AX, AY
350 Adams Solver
C++ Statements
and AZ) and global displacements (DX, DY and DZ) of the PART's BCS with respect to the GROUND
origin expressed in the GROUND coordinate axes. However, the user may change the default set of system
coordinates and have Adams Solver (C++) use arbitrarily defined coordinates instead. Using a PSTATE
statement, the linearized equations are:
s· = A's + B'u
y = C's + Du'
where the system state array s is the set of user-defined coordinates.
Use the following guidelines when creating PSTATE objects and their associated VARIABLEs' function
expressions:
1. Function expressions must be define a nonconstant displacement or angular measure.
Example
VARIABLE/2, FU=DX(10,7)
VARIABLE/3, FU=PSI(8,7)
PSTATE/33, VAR=2, 3
If the function expression is a constant or it is not a displacement, the code will reject the definition.
2. The displacement or angular measures can be global or relative.
Example
! Defining a relative coordinate
VARIABLE/2, FU=DX(10,5,7)
PSTATE/33, VAR=2
3. The number of VARIABLES in the PSTATE statement can be less than the number of degrees of
freedom of the model. Adams Solver (C++) completes the state array using coordinates taken from
the set of default system coordinates.
4. The number of VARIABLES in the PSTATE statement can be greater than the number of degrees-
of-freedom of the model. Adams Solver (C++) selects the required number of user-defined
coordinates and ignores the rest.
5. Adams Solver (C++) rejects redundant definitions.
Example
! Redundant definitions
VARIABLE/7, FU=DX(10,2)
VARIABLE/8, FU=8*DX(10,2)
PSTATE/34, VAR=7, 8
In this example, Adams Solver (C++) ignores one of the above VARIABLE definitions.
6. Adams Solver (C++) may ignore a user-defined coordinate if there is already an equivalent default
definition.
PSTATE 351
C++ Statements
Tip:  VARIABLE statements may appear in more than one PSTATE statement.
 Do not confuse a PSTATE statement with the PSTATE option in the LINEAR command.
Examples
The model shown in the figure below is a simple rigid helicopter blade.
Assuming that MARKER/10 is located on the CM of the blade, by default, Adams Solver (C++) will linearize
the model using the rotation AZ(10). If you want to linearize the model using the displacement 'y' shown in
the figure, then add the following objects to the data set:
VARIABLE/1, FU=DY(10)
PSTATE/1, VAR=1
In the command file add
LINEAR/STATE, PSTATE=1
In this case, Adams Solver (C++) linearizes the system using the 'y' coordinate shown in the figure (see Using
the PSTATE option section in the LINEAR command).
Applications
The PSTATE statement is of fundamental importance in cases in which you need to linearize the system using
relative coordinates. The most important case is the eigenvalue calculations of rotating systems. Theory shows
that in a rotating (or accelerating) system, the eigenvalues depend on the choice of coordinates used to
linearize the model.
For example,
LINEAR/EIGENSOL, PSTATE=2
forces Adams Solver (C++) to linearize and compute eigenvalues of a model in terms of the user-defined
coordinates found in the VARIABLEs belonging to the PSTATE/2 object.
352 Adams Solver
C++ Statements
PTCV
The PTCV statement defines a point-to-curve constraint, which restricts a fixed point defined on one part
to lie on a curve defined on a second part. This is an instance of a higher pair constraint.
Format
Arguments
CURVE=id Specifies the identifier of a CURVE statement that defines the contour or shape on which
the fixed marker can move. The x, y, z values associated with the curve are the coordinates
of points lying on the curve and are calculated in the coordinate system of the RM marker.
DISP=x,y,z Specifies the initial point of contact on the curve. If the point specified is not exactly on the
curve, Adams Solver (C++) uses a point on the curve nearest to that specified. By default,
DISP is specified in the RM marker coordinate system. If another coordinate system is more
convenient, you may supply the ICM argument and enter DISP in ICM marker
coordinates.
If you supply DISP, Adams Solver (C++) assembles the system with the I marker at the
specified point on the curve. If you do not supply DISP, Adams Solver (C++) assumes the
initial contact is at the point on the curve closest to the initial I marker position. However,
it may adjust that contact point to maintain other part or constraint initial conditions.
I=id Specifies the identifier of a fixed MARKER that Adams Solver (C++) constrains to lie on the
curve defined by CURVE and RM. The I and RM markers must belong to different parts.
ICM=id Specifies the identifier of a fixed MARKER defining the coordinate system in which the
values for DISP are specified. The ICM marker must be on the same part as the RM marker.
PTCV 353
C++ Statements
JFLOAT=id Specifies the identifier of a floating marker. Adams Solver (C++) positions the origin of the
JFLOAT marker at the instantaneous point of contact on the curve. Adams Solver (C++)
orients the JFLOAT marker such that the x-axis is tangent to the curve at the contact point,
the y-axis points outward from the curve's center of curvature at the contact point, and the
z-axis is along the binormal at the contact point.
RM=id Specifies the identifier of a fixed marker on the J part containing the curve on which the I
marker must move. The RM marker is used to associate the shape defined by the CURVE
identifier to the part on which the RM marker lies. The curve coordinates are therefore
specified in the coordinate system of the RM marker. The JFLOAT and RM markers must
belong to the same PART.
VEL=r Specifies the magnitude initial tangential velocity of the I marker with respect to the part
containing the curve. This is the speed at which the I marker is initially moving relative to
the curve. VEL is negative if the I marker is moving towards the start of the curve, positive
if the I marker is moving toward the end of the curve, and zero if the I marker is stationary
on the curve.
If you supply VEL, Adams Solver (C++) gives the I marker the specified initial tangential
speed along the curve. If you do not supply VEL, Adams Solver (C++) assumes the initial
tangential velocity is zero, but may adjust that velocity to maintain other part or constraint
initial conditions.
Default: 0
Extended Definition
The PTCV statement defines a point-to-curve constraint. The part containing the I marker is free to roll and
slide on the curve that is fixed to the second part. Lift-off is not allowed, that is, the I marker must always lie
on the curve.
Is located at the contact point on the curve; its orientation is defined by the tangent, normal and binormal
at the contact point (see Figure 11).
Figure 12 shows a schematic of the point-to-curve constraint.
A PTCV statement removes two translational degrees-of-freedom from the system. Adams Solver (C++)
restricts the origin of the I marker to always lie on the curve. The I marker may translate only in one direction
relative to the curve, along the instantaneous tangent. The I marker is free to rotate in all three directions.
Figure 11 Geometric Interpretation of the Orientation of the JFLOAT Marker

354 Adams Solver
C++ Statements
Figure 12 Point-To-Curve Constraint

PTCV 355
C++ Statements
Tip: More than one PTCV statement may reference the same CURVE statement. If the
mechanism contains several similar contacts, you may enter just one CURVE statement,
then use it with several PTCV constraints, each with a different RM marker.
Caution:  VEL is specified relative to the part containing the RM marker. In other words, VEL
is the tangential speed of the I marker relative to the part containing the curve. This
means that if the I marker is stationary relative to ground, but the curve is moving
relative to ground, then VEL is still nonzero.
 Adams Solver (C++) applies a restoring force tangent to the curve at the contact point
if the contact point moves off the end of an open curve. The magnitude of the force
applied is defined as:
Force = COSH(MIN(200,500*DELTA)) - 1, if DELTA > 0

 where DELTA is a normalized penetration of the end of the curve, defined as:
DELTA = (ALPHA-MAXPAR)/ABS(MAXPAR-MINPAR), if ALPHA > MAXPAR
or
DELTA = -(ALPHA-MINPAR)/ABS(MAXPAR-MINPAR), if ALPHA < MINPAR
This force is intended to prevent solution problems when unexpected situations

occur, and should not be relied upon intentionally. You should make sure the
CURVE statement defines the curve over the expected range of motion.
 The initial conditions arguments, DISP and VEL, impose constraints that are active
only during an initial conditions analysis. Adams Solver (C++) does not impose these
initial conditions during subsequent analyses.
 For a kinematic analysis, the initial conditions are redundant. Do not use the DISP or
VEL arguments on the PTCV statements for systems with zero degrees of freedom.
 It is easy to accidentally over-constrain a system using the PTCV constraint. For
instance, in a cam-follower configuration, the cam should usually be rotating on a
cylindrical joint, not a revolute joint. If the follower is held by a translational joint and
the cam by a cylindrical joint, the PTCV constraint between the follower and cam
prevents the cam from moving along the axis of rotation (that is, the axis of the
cylindrical joint). A revolute joint would add a redundant constraint in that direction.
Examples
PTCV/55, I=201, JFLOAT=301, CURVE=10, RM=302>
This statement creates a point-curve constraint between Marker 201 and a curve on the part containing
floating Marker 301 and fixed Marker 302. CURVE/10 defines the x, y, z coordinates curve in the coordinate
356 Adams Solver
C++ Statements
system of Marker 302. Because the statement does not specify initial conditions, Adams Solver (C++) assumes
that the initial position of the contact point on the curve is set to be the minimum distance between the
specified I marker and the curve. Adams Solver (C++) also assumes the velocity of Marker 201 with respect
to the curve is zero, meaning it is initially stationary on the curve. Adams Solver (C++) may adjust these
assumed initial conditions in order to enforce other part or constraint initial conditions.
PTCV/55, I=201, JFLOAT=301, CURVE=10, RM=302,
, DISP=2.,3.,0., VEL=-5.
This statement is the same as the last example, except it contains initial conditions. Adams Solver assembles
the system with Marker 201 at the point on the curve nearest to coordinates (2.,3.,0.) in the Marker 302
coordinate system. Adams Solver imposes an initial speed of -5.0 on Marker 201 with respect to the curve,
meaning Marker 201 is moving towards the start of the curve.
Applications
The simplest point-curve constraint application is a pin-slot connection as illustrated in Figure 13 below.
Figure 13 Slot and Pin Reciprocating Mechanism
The point-curve constraint keeps the center of the pin in the center of the slot, while allowing it to move
freely along the slot and rotate in the slot. Note that the point-curve constraint does not stop the pin at the
end of the slot. If the travel of the pin must be restricted, a force element, such as an SFORCE with an
IMPACT function, must be used.
A point-curve constraint may also represent a point follower on a cam, where the follower has a very small
radius compared to the curvature of the cam. Figure 14 below illustrates a point follower on a cam.
If the CURVE statement specifies a closed curve, Adams Solver (C++) automatically moves the point across
the closure as needed. This means the cam may rotate as many times as needed during the simulation.
In some cases, the PTCV statement may be used to model a circular follower on a curve. This requires you
to construct a curve offset from the actual profile by a distance equal to the radius of the follower. Figure 15
illustrates the follower, original profile, and offset curve.
Figure 14 Point-Follower Mechanism

PTCV 357
C++ Statements
Figure 15 Modeling a Circular Follower Using an Offset Curve
To model more complex cam-follower applications, see the CVCV statement. In the CVCV statement, both
the follower and cam can be represented as curves.
Because PTCV is a constraint, the point always maintains contact with the curve, even when the dynamics
of the system would actually lift the point off the profile. You may examine the constraint forces to determine
Unlike the CVCV statement, the PTCV statement is not restricted to planar curves. PTCV can model three-
dimensional slots and cams, as well as mechanisms riding on nonplanar tracks, or a robot end-effector
following a three-dimensional path in space.
358 Adams Solver
C++ Statements
REQUEST
The REQUEST statement indicates a set of data you want Adams Solver (C++) to write in the request file,
and the XML formatted results file. Using a REQUEST statement, you can output a set of displacements,
velocities, accelerations, or forces with respect to markers in the system. FUNCTION keywords allow you to
explicitly define the output variables or employ a user-written subroutine REQSUB to define nonstandard
output.
Format
REQUEST 359
C++ Statements
Arguments
360 Adams Solver
C++ Statements
REQUEST 361
C++ Statements
ACCELERATION Outputs the acceleration of the I marker with respect to the J marker. The output
data includes the translational x component (ACCX), the translational y
component (ACCY), the translational z component (ACCZ), the rotational x
component (WDTX), the rotational y component (WDTY), and the rotational z
component (WDTZ). Adams Solver (C++) calculates this acceleration data (the
second derivative of the displacement of the I marker with respect to the J marker)
in the global coordinate system. If you specify RM, Adams Solver (C++) resolves
the translational x component, the translational y component, the translational z
component, the rotational x component, the rotational y component, and the
rotational z component in the coordinate system of the RM marker.
CNAMES (Component Names) Sets one or more strings that identify the names of the result
set components produced by this REQUEST in XML results files.
For example, by default a result set for a request looks like:
<entity name="REQUST_1" objectId="11">

<component name="mag" id="42">
<component name="x" id="43">
...
By default, there are 8 components per result set.
Specifying CNAMES=MG, X_comp, Y_comp, the XML results file will look like
this instead:

<component name="Mg" id="42"/>
<component name="X_comp" id="43"/>
Result set components can be deleted from storage in the database and in the XRF
by omitting them in the CNAMES argument. For example, the following
CNAMES argument will remove the first and fourth components from the result
set:
CNAMES=””, X_Comp, Y_Comp, Z_Comp, ““, R1, R2, R3
This can be helpful if you wish to reduce the memory overhead of the simulation
data.
362 Adams Solver
C++ Statements
COMMENT=c Specifies a title for the top of each set of information the REQUEST statement
outputs. The entire comment must be on one line. Because input lines can be only
eighty characters long at most, the comment can be from seventy-two characters
long (if you do not abbreviate COMMENT=) to seventy-eight characters long (if
you abbreviate COMMENT= to C=). Blank spaces and all alphanumeric
characters can be used. However, the comma (,), the semicolon (;), the ampersand
(&), and the exclamation point (!) cannot be used. The COMMENT data is
printed in the request file only.
CUNITS (Component Units) Sets one or more strings that identify the unit dimension of the
result set components in XML result files. If the CUNITS argument is omitted,
then the units of the components are predefined based upon standard request type
(e.g. displacement, velocity, and acceleration) or they are considered user units and
no unit conversion will be performed. This argument is mutually exclusive with the
CLABELS argument.
The legal choices for the CUNITS parameter are:
MASS AREA
TIME VOLUME
FORCE TORQUE
LENGTH PRESSURE
VELOCITY DENSITY
ACCELERATION ENERGY
ANGLE TORSIONAL_STIFFNESS
ANGULAR_VELOCITY TORSIONAL_DAMPING
ANGULAR_ACCELERATION FREQUENCY
INERTIA AREA_INERTIA
STIFFNESS FORCE_TIME
DAMPING TORQUE_TIME
CLABELS (Component Labels) Sets one or more strings that identify the label to be used
when plotting the result set components. This argument is mutually exclusive with
the CUNITS parameter. Labels may be strings that include white space. However,
quotes must be used to define the string if special characters or white space are used.
This option is only used with XML result files.
REQUEST 363
C++ Statements
DISPLACEMENT Outputs the displacement of the I marker with respect to the J marker. The output
data includes:
 x component (X)
 y component (Y)
 z component (Z)
 psi angle (PSI)
 theta angle (THETA)
 the phi angle (PHI)
The psi, theta, and phi angles are the Euler angle displacements of the I marker with
respect to the J marker. Adams Solver (C++) calculates this displacement data in the
global coordinate system. If you specify RM, Adams Solver (C++) resolves the
translational x-component, the translational y component, and the translational z-
component in the coordinate system of the RM marker. RM does not affect psi,
theta, and phi. If the YPR argument is placed in the OUTPUT statement, the psi,
theta, and phi rotations are converted to yaw, pitch, and roll rotations.
F1=e Defines the first component of the request that is being specified. If the F1
argument is used, it must either be the last argument in the REQUEST statement
or be followed by a backslash (\) (not a comma).
F2=e Defines a component of the request that is being specified. If the F2 argument is
used, it must either be the last argument in the REQUEST statement or be
followed by a backslash (\) (not a comma).
F5=e Defines the fifth component of the request that is being specified. If the F5
argument is used, it must either be the last argument in the REQUEST statement
or be followed by a backslash (\) (not a comma).
364 Adams Solver
C++ Statements
FORCE Outputs the force associated with the I and the J markers or, if the I marker and not
the J marker is given, outputs the action-only forces on the I marker. When both
the I and the J markers are given, Adams Solver (C++) sums the forces on the I
marker due to the forces associated with the I and the J markers. These forces can
include both applied forces (such as spring dampers and bushings) and reaction
forces from constraint elements (such as joints and motions).
When the I marker and not the J marker is given, Adams Solver (C++) sums all of
the action-only forces applied to the I marker. If RM is specified, Adams Solver
(C++) reports the components of the resulting vectors in the reference frame of the
RM marker. If RM is not specified, Adams Solver (C++) reports the components
in the ground coordinate system (GCS). The output data includes the time, the
three components of the translational force, and the three components of the
torque.
FUNCTION=USER Defines and passes constants to the user-written subroutine REQSUB to define the
{r1[,...,r30]} request. Follow FUNCTION with an equal sign, the character string USER, and
the values (r1[,...,r30]) that you want Adams Solver (C++) to pass to REQSUB (see
the REQSUB subroutine). If the FUNCTION argument is used, it must either be the
last argument in the REQUEST statement or be followed by a backslash (\).
Because back compatibility requirements, REQSUB can define 8 columns of data,
but only columns 2, 3, and 4 and columns 6, 7, and 8 are written in the request file.
I=id, J=id Identifies the fixed or floating marker(s) for which Adams Solver (C++) outputs
data. Both markers for DISPLACEMENT, VELOCITY, and ACCELERATION
must be identified. For force requests, the I marker and the J marker must have on
them either applied forces, such as bushings and sforces, or constraints, such as
joints and jprims, or both. You should identify both markers for force unless you
are outputting data for an action-only force. In the last case, only the I marker needs
to be identified.
RM=id Identifies the marker with respect to which you want to resolve information. Adams
Solver (C++) computes the data identified by the I marker and the J marker, then
reports the data as x, y, and z components in the reference frame of the RM marker.
Angular displacements, which are not vectors, are not affected by RM. RM defaults
to zero, which causes Adams Solver (C++) to resolve components in the ground
coordinate system (GCS).
RESULTS_NAME Specifies the name of the result set in which all result set components produced by
this request are placed when the result file is written in XML. If there is an existing
result set with this name, then the result set components are placed in that result
set. If there isn't an existing result set, then a new one is created and all the result
set components are placed there.
This is helpful if you wish to group the output from multiple requests into a single
result set. For example, you might have several different requests measuring driver
input for a vehicle, and you might wish to place them all within a result set named
Driver_Inputs for easier viewing in Adams PostProcessor.
REQUEST 365
C++ Statements
ROUTINE=libname Specifies an alternative library and name for the user subroutine REQSUB.
::subname
TITLE=c Specifies the title of the REQUEST output.
VARIABLES It identifies one or more VARIABLES that represent the components associated
with this REQUEST. The VARIABLES argument requires one or more
VARIABLE id references. This option is only used in XML result files.
VELOCITY Outputs the velocity of the I marker with respect to the J marker. The output data
includes:
 translational x component (VX)

 translational y component (VY)
 translational z component (VZ)
 rotational x component (WX)
 rotational y component (WY)
 rotational z component (WZ)
Adams Solver (C++) calculates this velocity data (the first derivative of the
displacement of the I marker with respect to the J marker) in the global coordinate
system. If you specify RM, Adams Solver (C++) resolves the translational and
rotational velocities vector in the coordinate system of the RM marker.
Extended Definition
The REQUEST statement indicates a set of data you want Adams Solver (C++) to write in the request file.
Using a REQUEST statement, you can output a set of displacements, velocities, accelerations, or forces with
respect to markers in the system. FUNCTION keywords allow you to explicitly define the output variables
or employ a user-written subroutine REQSUB to define nonstandard output.
Adams Solver (C++) calculates all time derivatives in the ground coordinate system (GCS), although you can
specify that the data be resolved in another reference frame. This is of no importance in the case of force data,
but it can be very important in the case of velocities and accelerations. For example, joint velocities are
actually translational and rotational velocity difference vectors of the joint I marker and the joint J marker in
ground. Joint accelerations are actually translational and rotational acceleration difference vectors of the joint
I marker in ground and the joint J marker in ground.
When requesting force information, you must specify the identifiers of markers on which there are forces.
The forces on these markers can be either applied or reaction forces.
Adams Solver (C++) writes REQUEST data to the request file only if you include an OUTPUT statement
with the REQSAVE argument. You may load the request file into Adams PostProcessor and plot the request
data.
366 Adams Solver
C++ Statements
Tip:  Note that the units for rotational displacement data in the request output of the
tabular output file default to degrees. The units for all other angular output data
default to radians.
 You only need to enter as many of the six function expressions F2,F3,F4,F6,F7,F8 as
required. Adams Solver (C++) outputs zeros for any function left unspecified.
REQUEST 367
C++ Statements
368 Adams Solver
C++ Statements
Caution:  Applied forces and torques are those generated by beams, bushings, fields, general
forces (GFORCEs), single-component forces (SFORCEs), spring dampers
(SPRINGDAMPERs), vector forces (VFORCEs), and vector torques (VTORQUEs).
Adams Solver outputs the applied forces and torques acting at the request I marker
(which may be either the applied force I marker or the applied force J marker). The
magnitude and point of force application on the part containing the applied force J
marker varies according to the type and source of the force.
For spring dampers, action-reaction single-component forces, general forces, vector
forces, and vector torques, the forces and torques acting at the J marker are equal and
opposite to the forces and torques acting at the I marker. For action-only single-
component forces, there is no force or torque acting at the applied force J marker. For
beams, fields, bushings, and multi-point forces, the forces acting at the applied force J
marker are equal and opposite to the forces acting at the applied force I marker. As
long as the applied force I marker and the applied force J marker are coincident, the
torques acting at the applied force J marker are equal and opposite to the torques
acting at the applied force I marker. If there is a finite separation between the I and the
J markers, the torques acting at the applied force J marker are calculated by solving the
moment balance equation at the J marker.
 Reaction forces and torques are those generated by constraint-inducing elements. For
revolute, spherical, and universal joints and for atpoint, orientation, parallel axes, and
perpendicular joint primitives, Adams Solver (C++) outputs the reaction forces and
torques acting at the request I marker (which may be either the constraint I marker or
the constraint J marker). The force and torque acting at the request J marker are equal
and opposite to the force and torque acting at the request I marker. Depending on the
type of constraint, some or all of the torques acting at the I marker are zero.
Determining reaction forces and torques for cylindrical, planar, rack-and-pinion,
screw, and translational joints and for inline and inplane joint primitives is more
complex.
If the request I marker corresponds to the constraint I marker, then Adams Solver
(C++) outputs the force and torque acting at the constraint I marker. If the request I
marker corresponds to the constraint J marker, then Adams Solver (C++) outputs the
force and torque acting at the instantaneous location of the constraint I marker, but
on the part containing the constraint J marker. The force translated to the constraint J
marker is the same as computed above. If the I and the J markers are coincident, the
torque translated to the constraint J marker is the same as computed above. But if
there is a finite separation between the I and the J markers, the torque translated to
the constraint J marker is different from the one computed above (because of the
moments contributed by the reaction forces).
REQUEST 369
C++ Statements
Caution:  You must be careful when requesting a force with the I and the J markers reversed
from those specified in the force-producing element. Adams Solver (C++) reports the
force as if it were applied to the J marker of the force-producing element. The
translational force on the J marker of the force element is equal and opposite to the
translational force on the I marker of the force element if it is not action-only. The
force is zero if it is action only. The torque on the J marker of the force element has
components that may have significance. The torque is the sum of two contributions.
The first contribution is the opposite of the torque on the I marker. The second
contribution is due to the force acting across the separation between the I and the J
markers. If the force acts along the line of sight of the two markers, this extra torque is
zero. To minimize misunderstandings, attach the REQUEST markers in the same
order as the markers on the force-producing element.
 When computing velocity and acceleration for a marker pair that includes a floating
marker, Adams Solver (C++) computes the velocity and acceleration as though the
floating marker were permanently attached to the part at its current position.
Examples
This REQUEST statement requests displacement data for Marker 0201 with respect to Marker 0103. Adams
Solver outputs the comment CRANK CENTER OF MASS DISPLACEMENT to the request file.
This REQUEST statement requests data for an action-reaction force on Marker 0304 from Marker 0204.
Adams Solver outputs the comment ROD/CRANK REACTION, to the request file.
REQUEST/21, F2=VARVAL(1)/ F3=DIF1(1)*5/ F4=DX(2109,409)
This REQUEST statement requests the value of VARIABLE/1, the first time derivative of DIFF/1 multiplied
by five, and the x component of the displacement of Marker 2109 relative to Marker 409.
,CNAMES="", X_100, Y_100
,RESULTS_NAME=PQT
,CNAMES="", X=200, Y=200
,RESULTS_NAME=PQT
If using XML, these two REQUEST statements generate a combined result set named "PQT" containing
only 4 channels named X_100,Y_100, X_200 and Y_200. The result set would look as follows:
<entity name="PQT" objectId="25">
<component name="X_100" id="67"/>
<component name="Y_100" id="68"/>
</entity>
370 Adams Solver
C++ Statements
Instead of generating 2 result sets with 8 channels each (default XML behaviour), only one result set with 4
channels is created.
Applications
Requests are used whenever a particular output is desired from Adams Solver (C++). The output generated
from the request contains data needed for plotting in a postprocessor. The writing of this files is controlled
by the OUTPUT statement.
An alternative to the use of REQUESTS is the RESULTS statement, which causes all the results for the analysis
to be saved to a results file. This file can then be used in a postprocessor. The major drawbacks to using the
RESULTS statement is the size of the file, and having the data in a form that needs to be translated by a
postprocessor.
When using a REQUEST statement, you must also have an OUTPUT/REQSAV statement in order to
create a request file (.req).
Data from certain Adams Solver (C++) statements is accessible only through the request functions (F2,...,F8).
The statements include PINPUT, POUTPUT, VARIABLE, ARRAY, LSE, GSE, TFSISO, and DIFF. To
request information on PINPUT, POUTPUT, ARRAY, or VARIABLE, you should write the function
expression referencing PINVAL, POUVAL, ARYVAL, and VARVAL, respectively. To request information on
LSE, GSE, TFSISO, you should write the function expression referencing ARYVAL. To request information
on DIFF, you should write the function expression referencing DIF for the value of the independent variable
associated with a user-defined differential equation, and DIF1 for the value of the time derivative of the
independent variable of the user-defined differential equation.
RESULTS 371
C++ Statements
RESULTS
The RESULTS statement creates a results file that includes all the simulation output from Adams Solver
(C++). The results file can be either unformatted (binary) or formatted (ASCII).
Format
,NOACCELERATIONS
,NOAPPLIEDFORCES
,NODATASTRUCTURES
,NODISPLACEMENTS
,NOFLOATINGMARKERS
,NOLINEAR
RESULTS/[FORMATTED][XRF]
,NOREACTIONFORCES
,NOREQUESTS
,NOSYSTEMELEMENTS
,NOVELOCITIES
,NOCONTACTS
,NODE_INCIDENTS
* The following arguments are only available with XRF.
,DECIMALPLACES = i
,ROUNDOFF
,SCIENTIFICATION = i1, i2
RESULTS/[XRF]
,SIGINIFICANTFIGURES = i
,TRAILINGZEROES
,ZEROTHRESHOLD = r

372 Adams Solver
C++ Statements
Arguments
DECIMALPLACES=i This argument is only available with XRF.
Specifies how many digits are written after the decimal point for real
numbers. The default value is 17 decimal places (full precision for recovery
of double-precision numbers).
FORMATTED Specifies that the results file is to be a formatted (text) file. The default is
an unformatted (binary) file. The formatted results file contains Adams
Solver (C++) output in plain text that you can read. You cannot examine
an unformatted results file directly. Although the unformatted results file is
not user-readable, it is generally preferred for several reasons. The
unformatted file is smaller, contains more precise data, and is much quicker
for Adams Solver (C++) to write and for a postprocessor to read. Contact
incidents can not be part of unformatted (binary) file however the XML
type will have that. A formatted file is useful only when you wish to
examine the data directly, or when transferring the file between computer
systems with incompatible binary formats.
NOACCELERATIONS Specifies that the results file is not to include part accelerations. the default
is a results file that includes part accelerations.
NOAPPLIEDFORCES Specifies that the results file is not to include applied forces. The default is
a results file that includes applied forces.
NODATASTRUCTURES Specifies that the results file is not to include results from data structures
such as variables, plant inputs, plant outputs and user-defined requests.
The default is a results file that contains results from data structures.
NODISPLACEMENTS Specifies that the results file is not to include part displacements. The
default is a results file that includes part displacements.
NOFLOATINGMARKERS Specifies that the results file is not to include results for floating markers.
The default is a results file that contains results for floating markers.
NOLINEAR Specifies that the results file is not to include results from linear analyses.
The default is a results file that contains results from linear analyses.
NOREACTIONFORCES Specifies that the results file is not to include constraint reaction forces. The
default is a results file that includes constraint reaction forces.
NOREQUESTS Specifies that the results file not include request output. The default is a
results file that includes user-defined request, in the case of a classic results
file, or all request data (in the case of an XML-formatted results file (XRF)).
NOSYSTEMELEMENTS Specifies that the results file is not to include results for system modeling
elements such as user-defined differential equations, linear state equations,
general state equations, and transfer functions. The default is a results file
that contains results for system modeling elements.
RESULTS 373
C++ Statements
NOVELOCITIES Specifies that the results file is not to include part velocities. The default is
a results file that includes part velocities.
NOCONTACTS Specifies that the results file does not include contact incidents. The default
is a results file that includes contact incidents.
NODE_INCIDENTS Specifies that the results file includes node incidents for contact on Flex
Bodies. The default is a results file that does not include node incidents.
ROUNDOFF This argument is only available with XRF.
Enables the roundoff feature for real numbers (the default is disabled). The
SIGNIFICANTFIGURES argument controls the actual numbers of digits
retained during rounding off.
SCIENTIFICNOTATION= This argument is only available with XRF.
i1,i2
Specifies the boundaries at which the format for real numbers switches
from a fixed point format to scientific notation. The values are exponents
for the base ten. The default values are -4 and 5, meaning that any number
less than or equal to 1.0E-04 or greater than or equal to 1.0E+05 will be
written in scientific notation.
SIGNIFICANTFIGURES=i This argument is only available with XRF.
Specifies how many significant figures of a real number are retained during
round off (when round off is enabled). The default is to use ten significant
figures.
This number is distinct from the number of places actually printed for a
real number, which the DECIMALPLACES argument controls.
Note: SIGNIFICANTFIGURES includes digits to the left and right of

the decimal point.
374 Adams Solver
C++ Statements
TRAILINGZEROS This argument is only available with XRF.
Specifies that trailing zeros are printed for real numbers. The default is not
to print trailing zeros. When enabled, all the digits after the decimal point
will be printed, whether they are zero or not. When disabled, any zeros at
the end of the fractional part of the number will be dropped, leaving the
last digit as a non-zero digit.
XRF Specifies the format of the results file to be XML. XML (Extensibile
Markup Language) is an industry-standard format facilitating structured
data representation and web communication.
XRF will produce an XML-formatted results file even if the

FORMATTED parameter has not been specified.
ZEROTHRESHOLD=r This argument is only available with XRF.
Specifies the zero threshold value for numbers being written to an output
file. If a number has an absolute value smaller than the zero threshold value,
then it will be written out as zero. This value is independent of units.
Extended Definition
The RESULTS statement creates a results file that includes selections of output from an Adams Solver (C++)
simulation. This all-purpose file can contain all the simulation output from Adams Solver (C++). The results
file can contain any combination of the following information:
 Displacements - Displacements of the BCS with respect to ground and resolved in the ground
 Velocities - Velocities of the the BCS with respect to ground and resolved in the GCS.
 Accelerations - Accelerations of the BCS with respect to ground and resolved in the GCS.
 Reaction forces - Forces on the I marker required to enforce each constraint, resolved in the GCS.
 Applied forces - Forces on the I marker applied by Adams Solver (C++) force elements, resolved in
the GCS.
 Data structures - Values computed for data structures such as variables, plant inputs, plant outputs,
and requests defined by expressions in the dataset or by a user-written REQSUB.
 System elements - Inputs, outputs, state variables, and state derivatives defined by system modeling
elements such as user-written differential equations, linear state equations, general state equations,
and transfer functions.
 Tires - Displacements, velocities, accelerations, forces, and other information about tires.
 Floating markers - Displacements of floating markers.
 Linear - Eigenvectors, eigenvalues, and state matrices computed by a linear analysis invoked by the
LINEAR command.
 Contact Incidents - Values computed for individual contact points on Rigid and Flex Bodies in
contact.
RESULTS 375
C++ Statements
 Node incidents - Values computed for Flex Body nodes on Flex Bodies in contact.
Tip: The title specified in the COMMENT argument helps identify the results file. If you do not
include the COMMENT argument in the RESULTS statement, Adams Solver (C++) uses a
blank line for the title of the results file.
Because results files can contain all the information generated by Adams Solver (C++) during
a simulation, they may become quite large. The NO... arguments should be used to remove
unwanted output and conserve disk space.
Caution: The NODATASTRUCTURES argument has superseded the old NOUSERRESULTS

argument and the NOSYSTEMELEMENTS argument has superseded the old NODIFF
argument.
Including Node Incidents for Flex Body Contact may generate a very large results file.
Examples
RESULTS/FORMATTED, NODATASTRUCTURES, NOSYSTEMELEMENTS
RESULTS/NODISPLACEMENTS, NOVELOCITIES
,NOACCELERATIONS, NODATASTRUCTURES
,NOSYSTEMELEMENTS, NOFLOATINGMARKERS
376 Adams Solver
C++ Statements
SECTION
The SECTION statement defines section properties at a node on an FE_PART. The supported TYPES of
SECTION are rectangular, ellipse, circular, beam, properties and generic.
The SECTION statement is ignored by solver and is used by Adams View to restore SECTION data in an
Adams View session. This is because the FE_PART statement, itself, directly stores each node's area and area
inertia information (which is, of course, derived from the sections created in Adams View and assigned there
to each node).
SECTION 377
C++ Statements
Format
378 Adams Solver
C++ Statements
Arguments
TYPE Specifies the type (string, shown in above format) of the section to be created.
 SOLID RECTANGULAR
 HOLLOW RECTANGULAR
 ELLIPSE
 SOLID CIRCULAR
 HOLLOW CIRCULAR
 I BEAM
 PROPERTIES: No geometry is supported, only AREA, IYY, IYZ, IZZ,
JXX are needed.
 GENERIC: Cross-section geometry is defined by the set of points
specified by the POINTS argument.
CYL_RADIUS Specifies the radius of the cylinder if the section is cylindrical in nature.
CYL_THICKNESS Specifies the thickness of the cylinder if the section is cylindrical in nature and
is hollow.
RECT_BASE Specifies the base of the rectangle if the section is rectangular in nature.
RECT_HEIGHT Specifies the height of the rectangle if the section is rectangular in nature.
RECT_THICKNESS Specifies the thickness of the rectangle if the section is rectangular and hollow
in nature.
MAJOR_RADIUS Specifies the major radius of the ellipse if the section is elliptical in nature.
MINOR_RADIUS Specifies the minor radius of the ellipse if the section is elliptical in nature.
START_ANGLE Specifies the start angle of the ellipse if the section is elliptical in nature.
END_ANGLE Specifies the start angle of the ellipse if the section is elliptical in nature.
IB_HEIGHT Specifies the height of the beam if the section is in the form of a beam.
IB_BASE Specifies the base dimension of the beam if the section is in the form of a beam.
IB_FLANGE Specifies the flange of the beam if the section is in the form of a beam.
IB_WEB Specifies the web of the beam if the section is in the form of a beam.
SECTION 379
C++ Statements
POINTS Specifies the location of the series of points defining the generic cross section
in an x-y plane. Because the local cross sectional plane of an FE Part is
expressed in local z-y coordinates, we no longer recommend using this option.
Instead use the ZY_POINTS option. Existing datasets that make use of the
POINTS argument will continue to be supported but in the interactive
section editor dialog they will be mapped to the equivalent ZY_POINTS and
displayed that way. Furthermore, subsequent adm file export actions will
convert to an equivalent ZY_POINTS argument.
ZY_POINTS Specifies the location of the series of points defining the generic cross section.
Syntax: z1, y1, z2, y2 and so on.
Z, Y points of section drawn on grid.
AREA Specifies the cross-section area of the section.

380 Adams Solver
C++ Statements
IYY Specifies the moment of inertia about the Y axis.
Defaults to 1.0.
IYZ Specifies the product of inertia with respect to the Y and Z axes. Default value
is 10.
IZZ Specifies the moment of inertia about the Z axis. Defaults to 1.0.
JXX Specifies the polar moment of inertia. It is the torsional constant which is used
to assemble the torsional equation of motion describing the ability to resist
torque.
Extended definition for sections
1. Example - SOLID RECTANGULAR

A distributed-mass beam is shown in Figure 16 below. For this case, just two nodes are enough to model the
beam.
Figure 16 RECTANGULAR SECTION
!----------------------- SECTIONS -----------------------------------

SECTION 381
C++ Statements
!
! adams_view_name='SECTION_2'
SECTION/2
, TYPE = SOLID RECTANGULAR
, RECT_BASE = 15
, RECT_HEIGHT = 10
, IYY = 2812.5
, IZZ = 1250
, IYZ = 0
, JXX = 2934.567901
, AREA = 150
2. Example - I-BEAM
Figure 17 I-BEAM
SECTION/4
, TYPE = I BEAM
, IB_HEIGHT = 50
, IB_BASE = 25
, IB_FLANGE = 5
, IB_WEB = 5
382 Adams Solver
C++ Statements
, IYY = 13437.5
, IZZ = 1.5375E+005
, IYZ = 0
, JXX = 3958.333333
, AREA = 450
3. Example - ELLIPSE
Figure 18 ELLIPSE
SECTION/6
, TYPE = ELLIPSE
, MAJOR_RADIUS = 100
, MINOR_RADIUS = 50
, START_ANGLE = 0D
, END_ANGLE = 360D
, IYY = 3.926990817E+007
, IZZ = 9.817477042E+006
, IYZ = 0
, JXX = 3.141592654E+007
, AREA = 15707.96327
For more information refer the Create Section dialog box.
SECTION 383
C++ Statements
4. Example - GENERIC
User can create a cross-section of choice by using Generic Section supported for FE Part.
Points for cross-section are the input for Section definition.
! adams_view_name='SECTION_1'
SECTION/1
, TYPE = Generic
, ZY_POINTS = -115, 60, -115, -45, 105, -45, 105, -20, -90, -20, -90, 60, -115
, 60
, IYY = 4.34375E+007
, IZZ = 7.9625E+006
, IYZ = -3.20625E+006
, JXX = 10
, AREA = 7500
!
Figure 19 GENERIC
Example of drawing a section on grid:

384 Adams Solver
C++ Statements
SENSOR
The SENSOR statement is used to modify the simulation when a user-defined event occurs during run-time.
The event is defined by a logical expression which compares an expression to a target value. If the logical
expression becomes true during the simulation, the sensor modifies the simulation by the means described
below.
Format
SENSOR 385
C++ Statements
Arguments
BISECTION Specifies that a bisection search algorithm will be used to

isolate the activation time of the sensor.
When not present the default, secant-type root-finding

algorithm is used.
CODGEN Generates a new pivot sequence for matrix factorization
when the event Adams Solver (C++) is monitoring
becomes true. This may help the integrator to produce
more accurate data or to proceed more smoothly at
troublesome points in time. A pivot sequence for matrix
factorization is generated before the start of a simulation.
A new pivot sequence is not generated unless the
CODGEN argument is used or Adams Solver (C++)
determines it is necessary to reach convergence.
Default: Off
DT=r Redefines the time between consecutive output steps
becomes true.
Default: Time between output steps determined by

SIMULATE command
EQ Used to define the event logical expression. The event is
true (active) if the function expression (or user-written
subroutine) minus VALUE is equal or less than ERROR.
Default: EQ
ERROR=r Used to define the event logical expression. ERROR
specifies the absolute value of allowable error to be
realized in VALUE.
Default: 0.001
386 Adams Solver
C++ Statements
Specifies an expression or defines and passes constants to

a user-written subroutine that is evaluated when the event
Adams Solver (C++) is monitoring becomes true. The
scalar value of the expression or the return value of the
user-written subroutine can then be obtained using the
SENVAL function expression.
If you want to define the evaluated function with an

expression, EVALUATE must be followed with an equal
sign and the expression. If you want to define the
evaluated function with a user-subroutine, FUNCTION
must be followed with an equal sign, the character string
USER, and the selected values (r1[,...,r30]) that Adams
Solver (C++) passes to the user-written subroutine
SEVSUB.
If the EVALUATE argument is used, it must either be the

last argument in the SENSOR statement or be followed
by a backslash (\).
EVALUATE_ROUTINE=libname::subname Specifies an alternative library and name for the user
subroutine SEVSUB.

Specifies an expression or defines and passes constants to
a user-written subroutine to define the event logical
expression. To define an expression, follow FUNCTION
with an equal sign and the expression (e). To define a user-
written subroutine, follow FUNCTION with an equal
sign, the character string USER, and the values
(r1[,...,r30]) that you want Adams Solver (C++) to pass to
the user-written subroutine SENSUB. If the FUNCTION
argument is used, it must either be the last argument in
the SENSOR statement, or be followed by a backslash (\).
Default: None
Range: An expression or user-parameter list of 1 to 30 real
values
GE Used to define the event logical expression. The event is
true (active) if the function or user-written subroutine is
equal to or greater than (VALUE-ERROR).
Default: EQ
SENSOR 387
C++ Statements
HALT Terminates execution when the event Adams Solver (C++)

is monitoring becomes true (active).
Default: Off
LE Used to define the event logical expression. The event is
true (active) if the function or user-written subroutine is
equal to or less than (VALUE + ERROR).
Default: EQ
PRINT Writes data to the request, graphics, and results files when
the event Adams Solver (C++) is monitoring becomes
true.
Default: Off
RESTART Restarts the integration when the event Adams Solver
(C++) is monitoring becomes true. Adams Solver (C++)
reduces the integration order to one. If the SENSOR
includes STEPSIZE, the integration step size is
reinitialized to the specified value. If you do not specify
STEPSIZE, Adams Solver (C++) reinitializes the
integration step size to HINIT.
Default: Off
RETURN Stops the simulation and returns to the command level
becomes true.
Default: Off
ROUTINE=libname::subname Specifies an alternative library and name for the user
subroutine SENSUB.

STEPSIZE=r Redefines the trial integration step size when the event
Adams Solver (C++) is monitoring becomes true. This
change is temporary and lasts only for the next step.
Default: An integrator determined value except when the

SENSOR statement includes the RESTART argument.
In this case, STEPSIZE defaults to HINIT.
Range: STEPSIZE > 0

388 Adams Solver
C++ Statements
TERROR Specifies the temporal error with which the activation

time of the sensor is isolated.
Default: 1e-6
VALUE=r Specifies the value to be compared to the function
expression (or evaluation of the user-written subroutine).
When using GE with VALUE, the event logical
expression is true only if the function expression is equal
to or greater than (VALUE - ERROR). When using EQ
with VALUE, the event logical expression is true only if
the absolute value of the function expression minus
VALUE is equal to or less than ERROR. When using LE
with VALUE, the event logical expression is true only if
the function expression is less than (VALUE + ERROR).
Default: None
Range: Any real number

YYDUMP Dumps the state variable vector when the event Adams
Solver (C++) is monitoring becomes true.
Default: Off
Extended Definition
The SENSOR statement defines a user-defined event that affects a set of simulation controls when the event
occurs. The event is defined by a logical expression that compares a function expression (or evaluation of a
user-written subroutine) to a target value using a relational operator. If the logical expression becomes true
during the simulation, the sensor modifies a set of simulation controls, which include output and integration
step sizes, simulation end time, and the Jacobian pivot sequence. A sensor can also output diagnostic
information and store the value of a function expression for later recall.
Adams Solver (C++) evaluates the logical expression after every successful integration step when doing
dynamic analysis and after every successful output step when doing other types of analyses. To define the
function, use a function expression or a user-written subroutine. User-written subroutines and utility
subroutines discuss the subroutines they can access.
Adams Solver (C++) uses a different algorithm for sensor detection from the one used by Adams Solver
(FORTRAN). Adams Solver (FORTRAN) uses a prediction to try to pick an integration step that will detect
the sensor. Adams Solver (C++) uses three methods of search algorithms for sensor detection:
1. Bisection method (primarily meant for discrete signals)
2. Time-based method
3. Secant method
SENSOR 389
C++ Statements
If the method is chosen as bisection, then the sensor will look at the current sensor function value and
determine if it is within the ERROR tolerance. If the sensor function is within the ERROR, then it will use
bisection method to refine the time to within TERROR. This method does not use a sign change to detect
if the sensor function crosses the trigger value, so it is possible to cross the value outside of the ERROR, and
the sensor will not trigger. If bisection is not explicitly selected, then the sensor looks at the function itself to
determine the sensor detection algorithm. If the sensor function depends on time, or uses a SENSUB and
sysfnc or sysary are not called, then it uses a time-based algorithm to predict exactly when the sensor value is
hit.
If the sensor function depends on Adams states, or uses a SENSUB, then it uses a secant algorithm for sensor
detection. This method will determine if the current and last values of the sensor function have crossed the
trigger values, and if so, will use the secant method to attempt to refine to the trigger value. Finally, it will
then determine if the sensor function is within the ERROR specified and trigger the sensor if this is true. This
method behaves differently to the bisection method in that it will trigger the sensor even if the current and
last sensor values do not fall within the sensor ERROR. However, if there are even roots in the sensor
function, the sensor may miss this case unless a smaller integrator step is used.
Importing MATLAB controls systems dlls into Adams as GSEs creates the following sensors:
 Sensor for continuous state reset
 Sensor for tracking Zero-Crossings
 Sensor created by the Adams Solver to manage discrete GSEs
Sensor for continuous state reset

This SENSOR is for a GSE/External System Library (ESL).
Purpose: to detect continuous state change in ESL that requires integrator restart.
Function returns 1 if states are changed/reset by the ESL; otherwise, -1.
The cdriver parameters are as follows:
1. adams id of array for GSE continuous states (-1 = none used)
2. adams id of array for GSE inputs (-1 = none used)
3. adams id of array for parameters (-1 = none used)
4. adams id for string for name of library
5. number of parameters for library
6. length of string for name of library
7. adams id of the GSE associated with this sensor
This sensor is added to the database.
Sensor for tracking Zero-Crossings

This sensor is created when Zero-crossings are enabled in MATLAB/Simulink/RTW ESL.
Purpose: to track zero crossing functions in MATLAB/Simulink/RTW ESL
Function returns the MATLAB zero-crossing function value.
390 Adams Solver
C++ Statements
To remove, disable Zero-Crossings in MATLAB/Simulink before creating ESL and importing into Adams
The subroutine Sensub_zc_eq parameters are as follows:
1. adams id for string for name of library
2. length of string for name of library
3. number of parameters for library
4. adams id of the GSE associated with this sensor
5. index of the zero crossing vector in ESL to track
This sensor is added to the database.
Sensor created by the Adams Solver to manage discrete GSEs

Adams Solver (C++) may automatically create SENSORs to manage discrete GSEs in the model. In those
cases, Adams Solver (C++) will print an info message and assign an Adams ID to the created SENSOR. (This
Sensor is custom created and it is not to be found in the database.)
SENSORs in the model are verbose objects that may print large quantity of messages into the message files
and the output display. To silence a SENSOR or a set of SENSORs, set the environment variable
MSC_ADAMS_SENSOR_MESSAGES to a comma separated list of options. Options are the words ON, OFF,
ALL and a list of Adams IDs. For example:
MSC_ADAMS_SENSOR_MESSAGES=OFF, 4, 7, 11-20
will disable sending messages from SENSORs with Adams IDs provided in the list.
MSC_ADAMS_SENSOR_MESSAGES=OFF, ALL
will disable sending messages from all SENSORs in the model.
MSC_ADAMS_SENSOR_MESSAGES=ON, 3
will enable sending messages from SENSOR/3
Caution:  When using the default search algorithm in Adams Solver (C++), the SENSOR function
must be continuous. The secant-type search algorithm is inaccurate and time consuming
when the function is discontinuous. For that reason, functions of time or displacements
work best for sensors; functions of velocities, accelerations, and forces are less desirable.
 Use the BISECTION attribute when discontinuous SENSOR functions must be used, or
when a slower but more robust search algorithm is desired.
 Adams Solver (C++) tests the sensor after every successful time step during dynamic
analyses and after every output step during other analyses. If the sensor becomes active,
Adams Solver (C++) modifies the simulation control accordingly and does not test the
sensor again until it has completed three time steps. Then, Adams Solver (C++) again tests
the sensor after every time step.
SENSOR 391
C++ Statements
 If you want Adams Solver (C++) to take an action, make sure to include one of the action
arguments (CODGEN, DT, HALT, PRINT, RESTART, RETURN, STEPSIZE,
EVALUATE, and YYDUMP) in the SENSOR statement. The sensor can become active
even if one of the action arguments is not included. However, Adams Solver (C++) does
not, of course, take action unless one is specified.
 If a MOTION statement generates nonzero initial part accelerations, the Adams Solver
(C++) integrator may not produce reliable accelerations and velocities for the first two or
three internal integration steps. Adams Solver (C++) automatically corrects for this, so that
the values returned at the first output step are accurate. A SENSOR, however, which
depends on the accelerations or reaction forces due to this motion may trip unexpectedly
prior to the first output step, even though the solution appears correct when the SENSOR
is removed. If this occurs, you should modify the displacement function in the MOTION
 In some cases, Adams Solver (C++) may not be able to use the specified STEPSIZE.
 If this step size gives poor convergence or generates too much error, Adams
Solver(C++) tries other step sizes.
 For those INTEGRATOR statements where you set INTERPOLATE=OFF, if the
specified step size steps past the next output step, Adams Solver (C++) reduces the
step size to reach the output step exactly.
 If the specified step size is larger than HMAX, Adams Solver (C++) uses HMAX.
 If the specified step size is smaller than HMIN, and you specify RESTART, the value
of HMIN overrides the value of STEPSIZE.
 Adams Solver (C++) may occasionally have difficulty enforcing an equality (EQ)
SENSOR, especially if the specified error is very small. In these cases, Adams Solver (C++)
may appear to pass through the sensed value without invoking the sensor action. If this
occurs, you should try increasing the error tolerance, if possible. An alternative is to change
to an inequality (GE or LE) sensor, then DEACTIVATE the sensor after it has triggered.
Examples
SENSOR/231, FUNCTION=DX(0201,0307)/
,VALUE=3.24, RETURN
This SENSOR statement senses the x-component for the displacement of Marker 0201 with respect to
Marker 0307 and resolves the displacement in the ground coordinate system (GCS). When the relative x
displacement equals 3.24 (+/- 0.001), the statement stops the simulation and returns to the command level.
392 Adams Solver
C++ Statements
SFORCE
The SFORCE statement applies a single-component force or a torque to one or both of the parts it connects.
Format
SFORCE 393
C++ Statements
Arguments
ACTIONONLY Indicates that you are describing an action-only force rather than
an action-reaction force. Adams Solver (C++) applies no reaction
at the J marker.
Specifies an expression or defines and passes constants to a user-
written subroutine to define the single-component force. To define
the force with an expression, follow FUNCTION with an equal
sign and the expression. To define the force with a user-written
subroutine, follow FUNCTION with an equal sign, the character
string USER, and the values (r1[,...,r30]) that Adams Solver (C++)
is to pass to the user-written evaluation subroutine SFOSUB. If the
FUNCTION argument is used, it must either be the last argument
in the SFORCE statement or be followed by a backslash (\).
I=id, J=id Specifies the identifiers of two markers necessary to define the
force. If SFORCE defines a translational action-reaction force, I
and J specify the identifiers of the two markers between which you
want to exert the force. Adams Solver (C++) applies the
translational action-reaction force along the line of action defined
by the line segment connecting I and J. If SFORCE defines an
action-only force, I specifies the point of application, and the z-axis
of J specifies the direction of the force. If SFORCE defines a
torque, the z-axis of the J marker specifies the axis of rotation. In
the case of action-reaction torques, the z-axis of the J marker must
be parallel to, and pointed in the same direction as, the z-axis of
the I marker.
Note: You can use the same marker for both the I and J markers
when you are specifying an action-only SFORCE. For
example, you would do this when specifying rocket thrust
forces.
ROTATION Designates a rotational force, that is, a torque. For an action-
reaction torque, the z-axes of the I and the J markers must be
parallel and must point in the same direction. Adams Solver (C++)
applies a torque about each z-axis. By definition, the right-hand
rule defines a positive torque.
SFOSUB.

TRANSLATION Designates a translational force. Adams Solver (C++) applies the
translational force between the I and the J markers.
394 Adams Solver
C++ Statements
Extended Definition
The SFORCE statement applies a force or torque to two parts. You specify a marker on each part for force
or torque application. The magnitude of the force may be defined as a function of any combination of
displacements, velocities, other applied forces, user-defined variables, and time. An SFORCE statement can
apply action-reaction forces or can apply action-only forces.
For translational action-reaction forces, Adams Solver (C++) applies an action and reaction force along the
line connecting the I and the J markers. The force exerted on I is directed from J toward I, while the force
exerted on J is directed from I toward J. The magnitude of each is specified in the FUNCTION argument.
For translational action-only forces, Adams Solver (C++) applies the force on the I marker only. There is no
reaction on the J marker. The force on the I marker is directed along a vector parallel to and co-directed with
the z-axis of the J marker.
For rotational action-reaction forces, Adams Solver (C++) applies an action torque on the I marker about the
z-axes of the I marker and a reaction torque on the J marker about the z-axis of the J marker. Furthermore,
Adams Solver (C++) assumes that the z-axes of the I and the J markers are parallel.
For rotational action-only forces, Adams Solver (C++) applies the torque on the I marker only. There is no
reaction on the J marker. The torque on the I marker is applied about a vector parallel to and co-directed with
the z-axis of the J marker.
You write a function expression or a user-written subroutine (SFOSUB) to define the constitutive equation
for the force applied at the I marker. Adams Solver (C++) evaluates the reaction forces at the J marker.
Tip:  When an SFORCE statement defines a translational action-reaction force, Adams

Solver (C++) applies a translational force along the line connecting the I and the J
markers. But when an SFORCE statement defines a translational action-only force,
Adams applies the force to the I marker in the J marker z-axis direction.
 For action-reaction translational forces in Adams, a positive force (that is, positive
value of the FUNCTION argument) between two markers causes them to repel each
other and a negative force causes them to attract each other.
Caution: For rotational action-reaction SFORCEs, the z-axes of the I and the J markers must be
parallel and pointed in the same direction. If they are not, the results are unpredictable and
may differ between the Adams Solver (C++) and Adams Solver (FORTRAN).
Examples
, FUNCTION=IF((DM(0409,0109)-10.0):
, -100.00*(DM(0409,0109)-10.0),0,0)
This SFORCE statement describes an action-reaction, compression-only force exerted on Marker 0409 by
Marker 0109. The argument TRANSLATION designates a translational force, and the argument
SFORCE 395
C++ Statements
FUNCTION gives the free length (10.0), establishes that the force is active only in compression, and defines
the force in terms of the displacement (DM) of the I marker with respect to the J marker.
In a second example, suppose you wish to model a translational spring that transmits a nonlinear, dissipative
force between two parts of a mechanical system. Let the following equations represent the magnitude of the
attracting force acting between the two connecting parts.
F= k0 + k1(x-1) + k2(x-1)2 + cx'
where k0 is a static preload, x is the instantaneous length of the translational spring, x' is the time derivative
of x, l is the natural, unstretched spring length, k1 and k2 are stiffness coefficients, and c is a damping
coefficient. This equation representing the force magnitude can be rewritten in the following polynomial
format:
2
F =  Kj ( x – l ) j + cx'
j=0
If k0 = -10.1, k1 = 15.2, k2 = 4.1, c = 1.5, and l = 3.142, then the Adams Solver (C++) statement that represents
this translational spring acting between two parts containing Markers 12 and 34, respectively, appears as
, FUNCTION=-POLY(DM(12,34), 3.142, -10.1, 15.2, 4.1)
, VR(12,34) * 1.5
The DM function is used to calculate the instantaneous spring length x, the VR function is used to calculate
x', and the POLY function is used to simplify the input and computation of the nondissipative portion of the
force. Note that Adams Solver (C++) interprets the value of the FUNCTION argument as the magnitude of
the repelling force between two markers; hence, a negative sign was prepended to the attracting force
expression defined earlier.
396 Adams Solver
C++ Statements
SPLINE
The SPLINE statement defines discrete data that Adams Solver (C++) interpolates using the AKISPL and
CUBSPL function expressions and the AKISPL and CUBSPL data-access subroutines. A SPLINE statement
provides one or two independent variables and one dependent variable for each data point you supply.
If you are licensed to use the Adams Durability plugin, the SPLINE statement includes arguments to perform
durability analyses. These arguments are explained in the following pages along with the standard arguments.
Format
SPLINE/id
,X = x1, x2, x3, x4 [, ..., xn]
,Y = y1, y2, y3, y4 [, ..., yn]
[, XUNITS = string ]
[, YUNITS = string ]
[, UNITS = string ]
[, 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, y34 [, ..., y3n]
,Y = z4, y41, y42, y43, y44 [, ..., y4n]
[, ..., Y = zm, ym1, ym2, ym3, ym4 [, ..., ymn]]
[, ZUNITS = string ]
[, UNITS = string ]
or
SPLINE/id
, FILE = filename
[, BLOCK = blockname]
[ , CHANNEL = id ]
[, UNITS = string ]
[, ROUTINE=libname::subname]
SPLINE 397
C++ Statements
Arguments
BLOCK Specifies the use of a particular, named block within a file. The BLOCK argument
is optional, and requires the FILE argument.
CHANNEL For use with Adams Durability only.
Specifies the integer ID of a particular channel of data in the file referenced by the
SPLINE. This argument is used for files of type RPC III, which can contain more
than one channel of data. An error results if the specified file is of type RPC and no
CHANNEL argument is given or if the supplied channel ID does not exist in the
file. Adams Solver ignores this argument for files of type DAC, which by definition
contain only one channel of data.
Default: (none)
Range: 1 < n < 128
FILE Specifies the use of a file, rather than the X and Y arguments, to supply data for the
SPLINE. FILE causes Adams Solver (C++) to call the user-written subroutine
SPLINE_READ, which you must provide. The FILE argument and the X and Y
arguments are mutually exclusive.
If you are using FILE with Adams Durability, it specifies the name of the time
history file that supplies data for the SPLINE. The file can be of type DAC (nSoft
format) or RPC III (MTS format).
For more on how to define a SPLINE using the FILE argument, see the example
in SPLINE_READ subroutine.
LINEAR_EXTRAP Causes Adams Solver (C++) to extrapolate a SPLINE that exceeds a defined range
OLATE by applying linear function(s) tangent to the spline at the end(s) of the defined
range. By default, Adams Solver (C++) extrapolates a SPLINE that exceeds a
defined range by applying a cubic function over the first or last three data points.
ROUTINE=libname Specifies an alternative library and name for the user-written subroutine
::subname SPLINE_READ. Learn more about the ROUTINE Argument.
X=x1,x2,x3,x4[ , . . . , Specifies at least four x values. The maximum number of x values, n, depends on
xn] whether you specify a single curve or a family of curves.
Values must be constants; Adams Solver (C++) does not allow expressions.
Values must be in increasing order: x1 < x2 < x3, and so on.

Y=y1,y2,y3,y4 [ , . . . Approximates a single curve by specifying the corresponding y value:
, yn] y1,y2,y3,y4[, . . . ,yn] for each x value.
Values must be constants; Adams Solver (C++) does not allow expressions.
398 Adams Solver
C++ Statements
Y=z1,y11,y12,y13,y1 Approximates a family of curves by specifying the corresponding y values:

4 [ , . . . , y1n] y1,y2,y3,y4[, . . . ,yn] for the x values at unique z values
,Y=z2,y21,y22,y23,y (z1[, . . . ,zm]).
24 [ , . . . , y2n]
,Y=z3,y31,y32,y33,y Values must be constants; Adams Solver (C++) does not allow expressions.
34 [
,ym1,ym2,ym3,ym4 Values for z must be in increasing order: z1 < z2 < z3, and so on.
[ , . . . , ymn]]
UNITS For use with Adams Durability only.
Specifies the type of units to be used for all the sets of values. Valid values are:
"angle", "force", "frequency", "length", "mass", "time", "inertia", "velocity",
"acceleration", "angular_velocity", "angular_acceleration", "stiffness", "damping",
"torsion_stiffness", "torsion_damping", "area", "volume", "torque", "pressure",
"area_inertia", "density", "energy", "force_time", "torque_time",
"flowrate_pressure_d", "flow_rate", "force_per_angle", "damping_per_angle".
Default: (none)
XUNITS Specify the type of units to be used for individual set of values (X, Y or Z
YUNITS respectively). In general X units will be “time” and Y units will be of type “length”.
ZUNITS Valid values are: "angle", "force", "frequency", "length", "mass", "time", "inertia",
"velocity", "acceleration", "angular_velocity", "angular_acceleration", "stiffness",
"damping", "torsion_stiffness", "torsion_damping", "area", "volume", "torque",
"pressure", "area_inertia", "density", "energy", "force_time", "torque_time",
Default: (none)
Extended Definition
Adams Solver (C++) applies curve-fitting techniques that interpolate between data points to create a
continuous function. If the SPLINE data has one independent variable, Adams Solver (C++) uses a cubic
polynomial to interpolate between points. If the SPLINE data has two independent variables, Adams Solver
(C++) uses a cubic method to interpolate between points of the first independent variable, and then uses a
linear method to interpolate between curves of the second independent variable.
The next sections explain more about using the SPLINE statement:
 Using the Spline Function
 Spline Function Interpolation Methods
 Using SPLINE with Adams Durability
Using the Spline Function
SPLINE 399
C++ Statements
To use discrete data input with a SPLINE statement, you must write either a function expression that includes
one of the two Adams Solver (C++) spline functions (AKISPL and CUBSPL) or a user-written subroutine
that calls one of the two spline data-access subroutines (AKISPL and CUBSPL).
Spline Function Interpolation Methods
The SPLINE functions and data-access subroutines use two different interpolation methods: the Akima
method and a traditional cubic interpolation method.
 The AKISPL function and the AKISPL subroutine use the Akima method of interpolation. This
method includes a local, cubic, curve-fitting technique.
 The CUBSPL function and the CUBSPL subroutine use the traditional cubic method of
interpolation. This method includes a global, cubic, curve-fitting technique.
Both the Akima method and the traditional cubic method use cubic polynomials to interpolate values that
fall between two adjacent points on a curve. Both provide closer approximations than other curve fitting
techniques (for example, Lagrange polynomials, difference tables, and Fourier series). For data with two
independent variables, Adams Solver (C++) uses linear interpolation to determine values that fall between
curves. For more information about these curve-fitting techniques, see AKISPL and CUBSPL functions.
Using Spline with Adams Durability
The Adams Durability SPLINE statement is an extension of the Adams Solver (C++) SPLINE statement that
supports the input of experimental test data from industry standard formats DAC and RPC III. The DAC
format comes from nCode/nSoft. The RPC III file format comes from MTS.
DAC or RPC III files do not have standard file extensions. To determine which of these file types is in use,
Adams Solver (C++) opens the file and reads a minimal amount of information contained in the file head. If
the specified file is not of type DAC or RPC III, Adams Solver (C++) assumes that the file is a user-defined
file format, and processes the SPLINE statement using a SPLINE_READ user-supplied subroutine. For more
on how to define a SPLINE using the FILE argument for user-defined file formats, see the example in
SPLINE_READ subroutine.
To use DAC or RPC III data that is specified in a SPLINE statement as input to Adams Solver (C++), you
must write a function expression that includes the INTERP function. For more on how to use the Adams
Durability INTERP function, see the INTERP function.
Tip: When selecting points to represent a curve or a surface:
 Crowd points in regions with high rates of change.

 Spread out points in regions with slow rates of change.
400 Adams Solver
C++ Statements
Caution: The x and z data must cover the anticipated range of values. However, the following
situations sometimes cause Adams Solver (C++) to evaluate a spline outside of its defined
range:
 Adams Solver (C++) occasionally approximates partial derivatives using a finite

differencing algorithm.
 Adams Solver (C++) occasionally attempts an iteration that moves the independent
variable outside of its defined range. If this occurs, Adams Solver (C++) issues a
warning message and extrapolates the four closest spline points. If the extrapolation is
poor, Adams Solver (C++) may have difficulty reaching convergence, which may
affect the results.
To avoid these problems, try to use real points, and extend spline values 10 percent beyond
the total dynamic range.
Examples
The set of values in the table below relates the force in a spring to its deformation.
Data Relating Spring and Spring-Deflection Force
Deflection Force
-0.33 -38.5
-0.17 -27.1
-0.09 -15.0
0.0 0.0
0.10 10.0
025 30.0
0.40 43.5
0.70 67.4
From this table, you can determine force when deflection equals -0.33, and you can determine force when
deflection equals -0.17. However, what is the force when deflection equals -0.25?
To determine the force at any deflection value, Adams Solver (C++) creates a continuous function that relates
deflection and force. This continuous approximation can evaluate the value of the spring force at a deflection
of -0.25. If you input two sets of values (X and Y) with the SPLINE statement, then Adams Solver can
effectively define the function as a curve. The following example illustrates how the SPLINE statement is
used to store the discrete data in the table above.
SPLINE/01,
, X=-0.33, -0.17, -0.09, 0.0, 0.1, 0.25, 0.4, 0.7
, Y=-38.5, -27.1, -15.0, 0.0, 10.0, 30.0, 43.5, 67.4
, XUNITS = “length”
SPLINE 401
C++ Statements
, YUNITS = “force”
This SPLINE statement passes the data in the table above to a subroutine or function that uses cubic spline
functions to fit a curve to the values. The curve allows Adams Solver (C++) to interpolate a value of Y for any
value of X. It also specifies that the X values are of type length and Y values are of type force.
The set of values in the table below details a set of nonlinear, force-deflection relationships of a spring at
various temperatures.
Data Relating Spring Force to Spring Deflections at Various Temperatures
Force at degrees Fahrenheit:

Deflection: 20° 30° 40° 50°
-0.33 -38.5 -36.0 -30.0 -25.1
-0.17 -27.1 -25.4 -21.7 -18.6
-0.09 -15.0 -13.1 -9.6 -4.4
0.0 0.0 0.0 0.0 0.0
0.1 10.0 9.1 7.5 4.6
0.25 30.0 26.4 21.3 17.8
0.40 43.5 37.9 34.1 27.1
0.70 67.4 60.3 53.2 46.3
From table above, you can determine force when deflection equals -0.33 and when temperature equals 20°.
You can also determine force when deflection equals -0.17 and when temperature equals 30°. However, what
is the force when deflection equals -0.25 and when temperature equals 25°?
To determine the force at any deflection and temperature, you need to define a set of continuous functions
that generally relate force to deflection and temperature. If deflection is the independent x value and
temperature is the independent z value, you can define a set of functions in a family of curves using the
SPLINE statement. The SPLINE statement for this example is shown next:
SPLINE/02,
, X=-0.33, -0.17, -0.09, 0.0, 0.10, 0.25, 0.40, 0.70
, Y=20, -38.5, -27.1, -15.0, 0.0, 10.0, 30.0, 43.5, 67.
, Y=30, -36.0, -25.4, -13.1, 0.0, 9.1, 26.4, 37.9, 60.3
, Y=40, -30.0, -21.7, -9.6, 0.0, 7.5, 21.3, 34.1, 53.2
, Y=50, -25.1, -18.6, -4.4, 0.0, 4.6, 17.8, 27.1, 46.3
functions to fit a curve to the y values at each set of x and z values.
Examples Using the SPLINE Statement with Adams Durability
The following examples require a licence for the Adams Durability plugin to Adams Solver (C++).
SPLINE/101,
FILE=test.dac
MOTION/6, I=401, J=402, B3
,FUNCTION=INTERP(TIME,3, 101)*DTOR
402 Adams Solver
C++ Statements
The SPLINE statement defines a spline using test data supplied from a DAC file named test.dac. The
MOTION statement controls the rotation of Marker 401 with respect to Marker 402 about the z-axis of
Marker 401 using a function expression.
The function expression for the MOTION statement references data from the SPLINE statement using the
INTERP function. The test data from the DAC file is known to be acquired in degrees, and since Adams
Solver (C++) expects rotational motion to be specified in radians, a conversion from degrees to radians (factor
DTOR) is also included in the function expression.
SPLINE/201,FILE=test.rpc,CHANNEL=1
MOTION/1, I=401, J=402, X, FUNCTION=INTERP(TIME,3,201)
MOTION/2, I=401, J=402, Y, FUNCTION=INTERP(TIME,3,202)
MOTION/3, I=401, J=402, Z, FUNCTION=INTERP(TIME,3,203)
This example defines three splines that reference three different channels of test data from the same RPC III
file. Each of these splines supplies the test data to a MOTION statement using the INTERP function.
SPRINGDAMPER 403
C++ Statements
SPRINGDAMPER
The SPRINGDAMPER statement applies a rotational or a translational springdamper between two markers.
Format
Arguments
ANGLE=r Defines the reference angle for the torsional spring. If the reference torque of the
spring is zero, ANGLE equals the free angle. Adams Solver (C++) assumes ANGLE
is in radians unless a D is added after the value.
Default: 0
C=r Specifies the viscous damping coefficient for the force. The force due to damping
is zero when the system is at rest.
Range: C > 0
CT=r Specifies the viscous damping coefficient for the torque. The torque due to
damping is zero when the system is at rest. CT must be in units of torque per
radian per unit of time.
Range: CT > 0
FORCE=r Specifies the reference force at LENGTH.
Default: 0
404 Adams Solver
C++ Statements
I=id, J=id Specifies the identifiers of the two markers between which the force or the torque
is to be exerted.
K=r Specifies the spring stiffness coefficient for the force.
Range: K > 0
KT=r Specifies the spring stiffness coefficient for the torque. KT must be in units of
torque per radian.
Range: KT > 0
LENGTH=r Defines the reference length for the spring. If the reference force of the spring is
zero, LENGTH equals the free length.
Range: LENGTH > 0
Default: 0
ROTATIONAL Designates a rotational springdamper.
TORQUE=r Specifies the reference torque of the torsional spring at ANGLE.
Default: 0
TRANSLATIONAL Designates a translational springdamper.
Extended Definition
For a rotational springdamper, the z-axis of the I marker and the z-axis of the J marker must be parallel and
must point in the same direction.
Because the springdamper force is always an action-reaction force, the direction of the translational force is
along the line segment connecting the I and the J markers. Thus, if the force is positive, the markers
experience a repelling force along this line, and if the force is negative, the markers experience an attracting
force. The magnitude of the translational force applied to the parts containing the two markers is linearly
dependent upon the relative displacement and velocity of the two markers. The following linear constitutive
equation describes the force applied at the I marker:
Fa = -C (db/dt) - K(b-LENGTH) + FORCE
The force value is the force on the I marker applied by the J marker; the force on the J marker is equal and
opposite. The term b is the distance between the I and the J markers. Adams Solver (C++) assumes that b is
always greater than zero. Adams Solver (C++) automatically computes the terms db/dt and b. The following
linear constitutive equation describes the torque applied at the I marker:
Ta = -CT (da/dt) - KT(a-ANGLE) + TORQUE
The torque value is applied to the I marker about the positive z-axis of the I marker; the torque on the J
marker is equal and opposite to the torque on the I marker. The right-hand rule defines a positive torque.
The term a is the angle of the I-marker x-axis relative to the J-marker x-axis, measured about the J-marker z-
SPRINGDAMPER 405
C++ Statements
axis. Adams Solver (C++) takes into account the total number of complete rotations. Adams Solver (C++)
automatically computes the terms da/dt and a.
Caution:  If the z-axis of the I marker is not parallel to, and/or not pointed in the same direction
as, the z-axis of the J marker for a rotational springdamper, the results are
unpredictable.
 Since the line-of-sight method determines the direction of a translational
springdamper force, the I and the J markers cannot be coincident.
Examples
SPRINGDAMPER/012, I=25, J=30, K=5, C=.1, L=.01
, TRANSLATION
This SPRINGDAMPER statement describes a force that Marker 30 applies to Marker 25. Marker 25 also
applies a force of equal magnitude and opposite direction to Marker 30. The argument TRANSLATION
indicates that this is a translational springdamper, rather than a rotational one. Therefore, the magnitude of
the force is proportional to the spring free length, to the distance between the two markers, and to the time
rate of change of the distance between the two markers. The L argument indicates that the spring free length
is 0.01 length units (L is the free length because the FORCE argument defaults to zero). The spring constant
K is 5 force units per unit length, and the damping constant C is 0.1 force units-seconds per unit length.
406 Adams Solver
C++ Statements
STRING
The STRING statement defines a character string that may be referred to later in the execution of Adams
Solver. An interactive STRING command can be used to alter or review this character string. A GTSTRG
subroutine can be used to retrieve this character string in a user-written subroutine.
Format
STRING/id, STRING=c
Arguments
STRING=c Specifies the character string to be stored. You must include a character
string and the supplied string may be as long as 1024 characters. The STRING
argument and value must appear together on one line.
Caution: The following characters are not permitted in a STRING argument because they are
delimiters in the Adams Solver command language: comma (,), semicolon (;), ampersand
(&), and exclamation point (!). This is because the comma indicates that additional Adams
Solver arguments follow; the semicolon indicates that additional Adams Solver statements
follow on the same line; the ampersand indicates that the next line is a continuation of the
statement on this line; and the exclamation point indicates that Adams Solver is to stop
reading the line.
Examples
STRING/101, STRING=MARKER=
This STRING statement enters the character string MARKER= for later reference. The GTSTRG
subroutine can retrieve this string.
SURFACE 407
C++ Statements
SURFACE
The SURFACE statement defines a three-dimensional parametric surface that you can reference using the
MARKER statement.
Format
Arguments
FILE=file_name Specifies the name of a Parasolid geometry file. The file must
contain a single face of a sheet body.
FUNCTION=USER Defines constants that are passed to SURSUB, the user-written
(r1[,...,r30])/ subroutine that computes the surface coordinates and derivatives.
The FUNCTION argument must be either the last argument in
the SURFACE statement or followed by a backslash (\).
MAXPAR=r1, r2 Specifies the maximum values of the surface (u,v) parameters for a
user-written surface. If a file is specified, the file is queried for the
MAXPAR values.
Default: (1.0, 1.0)

MINPAR=r1, r2 Specifies the minimum values of the surface (u,v) parameters for a
user-written surface. If a file is specified, the file is queried for the
MINPAR values.
Default: (-1.0, -1.0)

408 Adams Solver
C++ Statements
SURSUB.

UCLOSED Specifies that a user-written surface is closed along the u parameter.
If specified, you must ensure that the defined surface meets along
the u edges and has continuous first and second derivatives across
the closure. If a file is specified, the file is queried for UCLOSED.
Default: surface is open in u

VCLOSED Specifies that a user-written surface is closed along the v parameter.
If specified, you must ensure that the defined surface meets along
the v edges and has continuous first and second derivatives across
the closure. If a file is specified, the file is queried for VCLOSED.
Default: surface is open in v
Extended Definition
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 simple example of a parametric surface is defined by the following equations and
illustrated in the figure below:
x=u
y=v
z = cos( u2 + v2)
Example of a Parametric Surface
SURFACE 409
C++ Statements
Adams Solver (C++) lets you create surfaces in two ways:

 Enter the name of a Parasolid geometry file containing one face of a sheet body.
 Write a SURSUB evaluation subroutine with which Adams Solver (C++) computes surface coordinates
and derivatives.
To model an analytically defined surface such as a cylinder, you can write a SURSUB user-written subroutine.
When providing a SURSUB, you can also specify MINPAR and MAXPAR to define the limits of the surface.
These default to (-1,-1) and (1, 1), respectively.
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.
410 Adams Solver
C++ Statements
Adams Solver (C++) 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. See SURSUB for more details.
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, users have no control over the stiffness parameter, K.
Examples
SURFACE/2, UCLOSED, MINPAR=0,0, MAXPAR=6.2832, 0.5
, FUNCTION=USER(0.2)
This statement creates a user-written surface closed in u and open in v. The range of u is (0, 6.2832). The
range of v is (0, 0.5).
SURFACE /8, FILE=hemisphere.xmt_txt
This statement creates a surface from a Parasolid geometry file. The file must contain a single face of a sheet
body.
Applications
Each SURFACE is always associated with a surface marker. Surface markers, in turn, can be used to create a
variety of higher-pair constraints. Typical examples include:
 A point sliding on a surface (spherical joint connecting a surface marker to an ordinary marker on a
different body).
 Two surfaces sliding on each other (revolute joint connecting two surface markers).
 A robot end-effector executing a specific work-path while orienting the end-effector to be always
normal to the surface of the work path (a fixed joint connecting a surface marker on one part to an
ordinary marker on a second part).
The SURFACE statement can only be referenced by a MARKER statement. See the MARKER statement for
more information.
TFSISO 411
C++ Statements
TFSISO
The TFSISO (Transfer Function, Single-Input, Single-Output) statement defines a single-input, single-
output transfer function as a ratio of two polynomials in the Laplace domain when used with the associated
ARRAY statements.
Format
Arguments
DENOMINATOR=a0[,...,a29 Specifies the coefficients of the polynomial in the denominator of the

] transfer function. Coefficients are listed in order of ascending powers of
s, starting with s to the zero power, including any intermediate zero
coefficients. The number of coefficients for the denominator must be
greater than or equal to the number of coefficients for the numerator.
NUMERATOR=b0[,...,b29] Specifies the coefficients of the polynomial in the numerator of the
transfer function. Coefficients are listed in order of ascending powers of
s, starting with s to the zero power, including any intermediate zero
coefficients. The number of coefficients for the numerator must be less
than or equal to the number of coefficients for the denominator.
STATIC_HOLD Indicates that the TFSISO states are not permitted to change during
static and quasi-static analysis.
412 Adams Solver
C++ Statements
U=id Designates the ARRAY statement in the dataset that is used to define the
input (or control) for the transfer function. You must have an ARRAY
statement with this identifier in the dataset and it must be of the U type.
If you specify the SIZE of the U ARRAY, it must be 1.
X=id Designates the ARRAY statement in the dataset that is used to define the
state variable array for the transfer function. You must have an ARRAY
statement with this identifier in the dataset; it must be of the X type; and
it may not be used in any other LSE, GSE, or TFSISO statement. If you
specify the SIZE of the X ARRAY, it must be one less than the number
of coefficients in the denominator.
Y=id Designates the ARRAY statement in the dataset that is used to define the
output for the transfer function. You must have an ARRAY statement
with this identifier in the dataset; it must be of the Y type; and it may not
be used in any other LSE, GSE, or TFSISO statement. If you specify the
SIZE of the Y ARRAY, it must be 1.
Extended Definition
The TFSISO (Transfer Function, Single-Input, Single-Output) statement is designed to model a linear, time-
invariant dynamic system defined in the Laplace domain, especially to facilitate the import of elements from
control-system block diagrams. It can also be used, however, to define an arbitrary set of constant-coefficient,
differential and algebraic equations which can be expressed in the Laplace domain as
y(s) bo + b1 s 1 + … + bm s m
G ( s ) = ---------- = -----------------------------------------------------
-
u(s) ao + a1 s 1 + … + ak s k
where m < k
The TFSISO follows standard control systems terminology, where x is the state variable array, y is the output
variable, and u is the input variable. Initial conditions are assumed to be identically zero. In the Adams Solver
(C++) dataset, each of these arrays is defined using an ARRAY statement. The characteristic equation for a
single TFSISO statement, defined by the DENOMINATOR argument, can be a polynomial of degree less
than 30.
Internally to Adams Solver (C++), there is an algorithm to automatically convert the list of fixed numerator
and denominator coefficients to a canonical state-space form; that is, a set of coupled, linear, constant-
coefficient differential equations and a single algebraic equation.
When you reference only the output of the TFSISO, the details of the internal equations are unimportant.
In some cases, however, it may be useful to understand how Adams Solver (C++) constructs the equations.
When interpreting Adams Linear output or examining the values in the X ARRAY, for instance, it may be
necessary to determine what the internal states represent.
The conversion from transfer function to canonical state-space form is done in two steps. First, the numerator
and denominator are normalized by the coefficient of the largest power of s in the denominator.
q = [b0/ak,b1/ak,...,bm/ak,0,...,0,0]
TFSISO 413
C++ Statements
p = [a0/ak,a1/ak,...,ak-1/ak,1]
where array p is of length k+1. Array q is also of length k+1, padded with zeros, if necessary. The entries in
arrays p and q are labeled from 0 to k for the following analogous transfer function:
y(s) qo + q1 s1 + … + qk sk
G ( s ) = ---------- = --------------------------------------------------
-
u(s) p o + ps 1 + … + p k s k
 x·  A B x 
The equivalent state space realization of this transfer function is:   =  
y  C D u 
where:
–pk – 1 1 0 . . . 0 0 qk – 1 – pk – 1 qk
–pk – 2 0 1 . . . 0 0 qk – 2 – pk – 2 qk
. . . 1 . . . . .
A = . . . . . . . . B = .
. . . . . . 1 . .
–p1 0 0 . . . 0 1 q1 – p1 qk
–po 0 0 . . . 0 0 qo – po qk
C = 1 0 0 . . . 0 0 D = qk
Note: Except in the specific case where the numerator and denominator are of equal orders, qk= 0.
Tip:  Keeping track of which ARRAY statements go with which system elements is easier if all system
elements are numbered uniquely and the ARRAY statements are numbered consistently. For
example, the X ARRAY that goes with TFSISO/100 could be ARRAY/100; the U ARRAY
would then be ARRAY/101, and the Y ARRAY would be ARRAY/102.
 Often, transfer functions are needed where the order of the numerator is larger than the
denominator. The classic example of this is the pure differentiator. It is generally possible to
avoid this situation in Adams Solver (C++) by using the derivative of the input, that is, marker
velocity or acceleration instead of displacement or velocity. In other cases, you may need to
algebraically incorporate another transfer function into a system or subsystem such that the
overall transfer function has a higher degree denominator.
414 Adams Solver
C++ Statements
Caution:  Although the TFSISO statement allows for up to 30 numerator and denominator
coefficients in the transfer function, the conversion to the canonical state-space form
is typically not robust for higher-order systems. Such systems should be used only
when you are confident that the problem is well-posed. An alternate approach more
suited to Adams Solver (C++) would be to break up (factor) the large transfer function
into a series of smaller ones in separate TFSISO statements.
 Note that, if the output equation defined by the TFSISO statement has no solution or
Adams Solver (C++) most likely fails to converge or possibly converge to an
unexpected answer. You can avoid this possibility by not referencing the X (state) or Y
(output) ARRAYs in the definition of the VARIABLE in the U (input) ARRAY.
 You must be sure to list the coefficients in order of increasing powers of s. Some texts
and programs use the opposite convention, listing coefficients in order of decreasing
powers of s.
 Adams Solver (C++) does not check for pole-zero cancellation in the TFSISO
numerator and denominator. In this case, the canonical transform used in Adams
Solver leads to an unobservable but controllable state space realization. Adams Solver
(C++) models containing such elements when tested for observability in control
design software are indicated having some unobservable portions. You should perform
any pole-zero cancellation prior to defining the TFSISO data.
differential variables (DIFFs, GSEs, LSEs, and TFSISOs), as well as for the
displacement and force variables. This changes the initial conditions for a subsequent
analysis. If STATIC_HOLD is not specified, during a static analysis, Adams Solver
(C++) sets the time derivatives of the user-defined variables to zero, and uses the user-
supplied initial-condition values only as an initial guess for the static solution.
Generally, the final equilibrium values are not the same as the initial condition values.
Adams Solver (C++) then uses the equilibrium values of the user-defined variables as
the initial values for any subsequent analysis, just as with the equilibrium
displacement and force values.
 However, if STATIC_HOLD is specified, the user-specified initial conditions are
retained as the static equilibrium values. Thus, the final equilibrium values are the
same as the user-specified initial conditions. Note that this does not guarantee that the
time derivatives of the user-defined variable are zero after static analysis.
Examples
ARRAY/100, X
ARRAY/102, Y
VARIABLE/101, FUNCTION=ACCZ(5,99,5)
TFSISO/100, X=100, U=101, Y=102,
, NUMERATOR=1.0, DENOMINATOR=100.0,10.0,1.0
These statements define the following transfer function.
TFSISO 415
C++ Statements
1
G ( s ) = ----------------------------------
2
-
s + 10s + 100
ARRAY/100 is the state array. ARRAY/101 is the input array. ARRAY/102 is the output array.
VARIABLE/101 defines the input.
Applications
The TFSISO statement may be most useful for adding feedback controls to an Adams Solver (C++) model.
A series of TFSISO statements can be assembled to resemble any linear block diagram arrangement. The
transfer function can be derived manually or may be imported directly from a control system design program
such as MATRIXx or MATLAB. Normally, the mechanical portion of the model includes some kind of
actuator which depends on the TFSISO output.
TFSISO statements can also be conveniently used in many cases to replace systems of coupled DIFF and
VARIABLE statements (for nonlinear equations, the GSE statements should be used). Examples of possible
dynamics system uses include unsteady aerodynamics, hydraulics, power transmission, and electrodynamics.
You can use the current values of TFSISO state variables and outputs in both function expressions and user-
written subroutines via the associated ARRAY facilities (see the function expression ARYVAL, and the
subroutines: GTARAY, SYSARY, and SYSFNC). That is, instead of Adams Solver (C++) functions and FORTRAN
callable subroutines dedicated explicitly to the TFSISO statement, the system states and outputs are accessed
by offset referencing through the appropriate ARRAY routines. This method of referencing the variables
makes access to the system states and outputs consistent for all three system modeling elements, the TFSISO
statement, the GSE statement, and the LSE statement.
416 Adams Solver
C++ Statements
TITLE
The TITLE delimiter is the entire first line in a dataset and describes the dataset. The title cannot be more
than 80 characters and must fit on one line. It may contain any printable ASCII characters and any number
of blank spaces. The title may be left blank.
Examples
Satellite with Flexible Panels: Deployment Study #13, 05/98
•
•
•
(statements)
•
•
•
END
This example contains a TITLE delimiter and an END delimiter that indicates the end of the dataset. Adams
Solver (C++) writes out the TITLE delimiter for you in the output files. For example it appears in the message
file (.msg) as follows:
Adams Solver dataset Title:
See other Dataset delimiter statement available.
UNITS 417
C++ Statements
UNITS
The UNITS statement sets the appropriate units for an Adams Solver (C++) analysis. This ensures that
computations, both on input and output, correctly conform to your choice of force, mass, length, and time
units.
Format
418 Adams Solver
C++ Statements
Arguments
FORCE = {CENTINEWTON, DYNE, Selects a predefined unit for forces. Must be used in
KILOGRAM_FORCE, KNEWTON, conjunction with LENGTH, MASS, and TIME.
KPOUND_FORCE, MEGANEWTON,
MICRONEWTON, MILLINEWTON,
NANONEWTON, NEWTON,
OUNCE_FORCE, POUND_FORCE,
POUNDAL}
LENGTH = {ANGSTROM, Selects a predefined unit for lengths. Must be used in
CENTIMETER, FOOT, KILOMETER, conjunction with FORCE, MASS, and TIME.
INCH, METER, MICROINCH,
MICROMETER, MILE, MILLIMETER,
MILS, NANOMETER, YARD}
MASS = {GRAM, KILOGRAM, Selects a predefined unit for masses. Must be used in
KPOUND_MASS, MILLIGRAM, conjunction with FORCE, LENGTH, and TIME.
MICROGRAM, NANOGRAM,
OUNCE_MASS, POUND_MASS,
SLINCH, SLUG, TONNE, US_TON}
SYSTEM = {CGS, FPS, IPS, MKS, NONE} Selects a predefined units system instead of selecting each
unit individually. MKS implies meter, kilogram, second
and newton. CGS implies centimeter, gram, second and
dyne. FPS implies foot, pound mass, second and pound
force. IPS implies inch, pound mass, second and pound
force. NONE implies that the dataset is written non
dimensionally and that Adams Solver (C++) sets UCF = 1.
TIME = {DAY, HOUR, MICROSECOND, Selects a predefined unit for time. Must be used in
MILLISECONDS, MINUTE, conjunction with FORCE, LENGTH, and MASS.
NANOSECOND, SECOND}
UCF = r Specifies a Units Consistency Factor (UCF) when you
prefer to work in a system of units not covered by any of
the choices listed above. The UCF is the conversion factor
from model mass units to dynamical mass units as shown
by the following equation:
Mass
Force = ------------- Acceleration
UCF
Examples of how to calculate the UCF for your choice of
units are given below in the Extended Definition of the
UNITS statement.
UNITS 419
C++ Statements
Extended Definition
The UNITS statement sets the appropriate units for an Adams Solver (C++) analysis and allows Adams View
to account for your choice. Usually the choice of units is simply a matter of preference or convenience.
However, sometimes the choice of units can significantly affect the solution calculated by Adams Solver
(C++), or even whether a solution can be found. The reasons for this are related to the scale of the problem,
as discussed below.
In most cases, you select a system of units by using the SYSTEM argument or the FORCE, MASS,
LENGTH, and TIME arguments. For cases not covered by the predefined choices, specifying the appropriate
UCF still allows Adams Solver (C++) to make correct calculations. Note that if the UNITS statement is not
used in a model, Adams Solver (C++) will treat the model the same as if the UNITS statement were used to
specify SYSTEM = NONE. Adams Solver (C++) always uses radians as the unit for angular measurements.
Understanding the UCF

Adams Solver (C++) always calculates and uses a UCF, even when you don't use the option to specify it
explicitly. It is worth understanding how this works because it can help you select the appropriate units for a
model that may suffer from scaling problems.
To discuss the UCF, let us define the terms model units and dynamical units. Model units are whatever choices
you make for units for force, mass, length, and time. That is, you write you model using model units.
Dynamical units are any valid choice of units for force, mass, length, and time such that Newton's 2nd law
(for a particle in one dimension)
F = MA (1)
is true when written using that choice of units. The CGS and MKS options for the SYSTEM argument of
the UNITS statement are dynamical units. Model units may be dynamical units, but that is not a
requirement.
To work with model units that are not dynamical units, the UCF is defined to make Newton's 2nd law valid
with that choice of model units by dividing the inertia values by the UCF to account for the inconsistency of
the model units. To see why this is legitimate, consider a system of model units (denoted by the "primes") F',
M', L', and T', and any valid system of dynamical units F, M, L, and T, where the model units are related to
the dynamical units by the scale factors sF, sM, sL, and sT:
sFF' = F (2)
sMM' = M (3)
sLL' = L (4)
sTT' = T (5)
Equation (4) and Equation (5) imply that acceleration expressed in model units is related to acceleration in
dynamical units by
s
-----L-2 A' = A (6)
sT
420 Adams Solver
C++ Statements
Using Equation (2), Equation (3), and Equation (6) to substitute F, M, and A, and into Equation (1) gives
sM sL
F' = M'A' ------------2 (7)
sF sT
By defining the UCF as
sF s T2
UCF = ------------ (8)
sM sL
to combine the four scale factors into one, Equation (7) can then be rewritten as
M'
F' = ------------ A' (9)
UCF
And thus, UCF = 1 for any valid system of dynamical units.
So, in what units does Adams Solver (C++) actually express equations to perform computations? For
quantities of force, length, and time, the units for computations are the same as model units. For quantities
of mass and rotational inertia, they are model units divided the UCF. (Note that quantities of angle are always
expressed in radians for internal computations. It is not possible make another choice with Adams Solver
(C++).)
What if multiple systems of model units have the same UCF, as for the SYSTEM choices of CGS and MKS:
how does Adams Solver (C++) "know" which it is using? The answer is, it does not, at least as far as the solving
the equations of motion are concerned. But, you as the modeler must know what model units you have
chosen. You will write your model with force, mass, length, and time expressed in these units, which will
affect the numerical values of model parameters such as spring and damping rates. Forces and torques
expressed in model units will then cause inertias expressed in model units, divided by the UCF, to have
translational and angular accelerations in model units. The first and second integrals of the accelerations will
then lead to translational and angular velocities, and translational displacements in model units. (To reiterate,
angular displacements are always in radians.)
However, if you do use the UNITS statement to choose the force, mass, length, and time units explicitly, or
use the SYSTEM argument to choose one of CGS, FPS, IPS, or MKS, Adams View will have information
about the model units. It can then use this information for pre- and post-processing, such as for switching
unit systems (even for angles) prior to sending a model to Adams Solver (C++) for analysis, and for putting
unit-labels on output plots and charts. Thus, unless you must use the UCF argument for the UNITS
statement, it is recommended that you avoid doing so.
Explicitly calculating the UCF

There are at least three reasons that you might need to calculate the UCF. One is if the available choice of
units supported by the UNITS statement does not suit you needs. Say, for example, you want to work in
model units of TON_FORCE, US_TON, YARD, and MINUTE. You would calculate the UCF according
to Equation (8), taking note that the scale factors sF, sM, sL, and sT are the numbers by which you multiply
numerical values expressed in model units to convert them to dynamical units. It does not matter with respect
to what system of dynamical units the scale factors are expressed. (Adams Solver (C++) always expresses them
UNITS 421
C++ Statements
with respect to the MKS system when it calculates the UCF when the SYSTEM (for FPS and IPS) or the
FORCE, MASS, LENGTH, and TIME arguments of the UNITS statement are used.) In our example,
NEWTON
s F = 8896.443230521 ------------------------------------ (10)
TON FORCE
KILOGRAM
s M = 907.18474 -------------------------------- (11)
US TON
METER
s L = 0.9144 -------------------- (12)
YARD
SECOND
s T = 60 ------------------------- (13)
MINUTE
When these values are substituted into Equation (8), the result is UCF = 38608.858267716525. Note that sF,
sM, sL, and sT are the same as the values in the scales array argument of the utility subroutine GTUNTS
(although they are returned in scales in the order: (sT, sL, sF, sM)).
A second reason that you might need to calculate the UCF, even if you do not specify it explicitly with the
UNITS statement, is if you write an expression that uses the numerical value of an inertia property, in model
units, of a PART, FLEX_BODY, or POINT_MASS. If you use such an expression for the definition of a
VARIABLE, as for example, a component of the angular momentum of a PART with respect to a fixed point,
you must be aware of your use of this variable. If it is to be used such that it will play a role in the system
dynamics (that is, not just for output purposes such as plot or charts), be sure to write the expression with
the value of the inertia (in model units) divided by the UCF. Otherwise it will have the wrong scaling and the
solution will be incorrect. However, this is not a concern when using the utility subroutine
BODY_MASS_PROPERTY: it returns inertia properties in model units. That is, it multiplies Adams Solver (C++)'s
internal values of the inertias by the UCF before returning them to the caller.
A third reason you might need to calculate the UCF is to see how it will affect the scaling of your problem,
particularly with regard to the timescale over which you are simulating. This is discussed in a subsequent
subsection.
The scale factors sF, sM, sL, and sT used by Adams Solver (C++) to calculate the UCF are listed in Tables 1 to
4. These are exact values in all cases except for the mass units of slinch and slug, which are approximate to 17
digits. The IEEE standard for computer arithmetic calls for using 17 digits for double precision calculations
if a value cannot be represented exactly with fewer. Whether all 17 digits are actually used depends on the
particular processor, operating system, and other factors. However, it is recommended that you use 17 digits
for scale factors that you may need to compute to enter into Equation (8), as well as the resulting value of the
UCF.
422 Adams Solver
C++ Statements
Table 1 Force Conversion Factors
(Value in model units) * SF = (Value in Newtons)

Model Units SF
CENTINEWTON 0.01
DYNE 1.0e-5
KILOGRAM_FORCE 9.80665 (§)
KNEWTON 1000
KPOUND_FORCE 4448.2216152605 (‡, §)
MEGANEWTON 1.0e6
MICRONEWTON 1.0e-6
MILLINEWTON 0.001
NANONEWTON 1.0e-9
OUNCE_FORCE 0.27801385095378125 (‡, §, ¶)
POUND_FORCE 4.4482216152605 (‡, §)
POUNDAL 0.138254954376 (‡, §)
‡ Depends on the definition 1 lbm = 0.45359237 kg, exactly.

§ Depends on the definition standard gravity = 9.80665 m/s2, exactly.
¶ It may seem that SF is approximate for the OUNCE_FORCE, but it turns out that 17 digits are just enough to represent it exactly.
UNITS 423
C++ Statements
Table 2 Mass Conversion Factors
(Value in model units) * SM = (Value in kilograms)

Model Units SM
GRAM 0.001
KPOUND_MASS 453.59237 (‡)
MILLIGRAM 1.0e-6
MICROGRAM 1.0e-9
NANOGRAM 1.0e-12
OUNCE_MASS 0.028349523125 (‡)
POUND_MASS 0.45359237 (‡)
SLINCH 175.12683524647638 (¶, ‡, §)
SLUG 14.593902937206365 (¶, ‡, §)
TONNE 1000
US_TON 907.18474 (‡)
‡ Depends on the definition 1 lbm = 0.45359237 kg, exactly.

§ Depends on the definition standard gravity = 9.80665 m/s2, exactly.
¶ Approximate to 17 digits.
Table 3 Length Conversion Factors
(Value in model units) * SL = (Value in meters)

Model Units SL
ANGSTROM 1.0e-10
CENTIMETER 0.01
FOOT 0.3048
KILOMETER 1000
INCH 0.0254
MICROINCH 2.54e-08
MICROMETER 1.0e-6
MILE 1609.344
MILLIMETER 0.001
MILS 2.54e-05
NANOMETER 1.0e-9
YARD 0.9144
424 Adams Solver
C++ Statements
Table 4 Time Conversion Factors
(Value in model units) * ST = (Value in seconds)

Model Units ST
DAY 86400
HOUR 3600
MICROSECOND 1.0e-6
MILLISECOND 0.001
MINUTE 60
NANOSECOND 1.0e-9
Choice of units for the timescale of the problem

Choosing units appropriate for the timescale of the problem you are analyzing can sometimes be critical. One
example of this is related to the choice of units of time. If your model is to be simulated over very short
durations, choosing time units that are smaller than the second is worth considering. One reason for this is
because several of the numerical integrators in Adams Solver (C++) use the reciprocal of the integration time
step to calculate some terms of the Jacobian matrix it must form and solve as part of a linear system of
equations. If the time step is very small, its reciprocal will be very large, causing this matrix to be ill-
conditioned. This can lead to more required iterations to find a solution, a less accurate solution, and in the
worst case, the inability to find a solution.
Additionally, modeling elements that depend on time for updates, such as the dependence of a GSE with
discrete states on its sample time, can benefit from using time units smaller that the second. This is because
Adams Solver (C++) determines whether a sample time is “hit” within a temporal-error tolerance. For very
small sample times, using smaller time units can improve the accuracy of the behavior of such modeling
elements.
Examples
UNITS/FORCE=KILOGRAM_FORCE,
,MASS=KILOGRAM, LENGTH=MILLIMETER, TIME=SECOND
The UNITS statement selects force units of KILOGRAM _FORCE, mass units of KILOGRAM, length
units of MILLIMETER, and time units of SECOND.
VARIABLE 425
C++ Statements
VARIABLE
The VARIABLE statement defines a variable in terms of a scalar algebraic equation for independent use, or
as part of the PINPUT, POUTPUT, or ARRAY statement.
Format
Arguments
Specifies an expression or defines and passes constants to a

user-written subroutine to define a variable. If you want to
define the variable with an expression, FUNCTION must be
followed with an equal sign and the expression. If you want to
define the variable with a user-written subroutine,
FUNCTION must be followed with an equal sign, the
character string USER, and the selected values (r1[,...,r30])
that Adams Solver (C++) passes to the user-written subroutine
VARSUB.
IC = r Specifies an approximate initial value for the VARIABLE.
Adams Solver (C++) may adjust the value of IC when it
performs an initial condition analysis. Entering an accurate
value for IC may help Adams Solver (C++) converge to the
ROUTINE = libname::subname Specifies an alternative library and name for the user
subroutine VARSUB.
Extended Definition
The VARIABLE statement creates a user-defined algebraic equation. The value of the VARIABLE statement
may depend on almost any Adams Solver (C++) system variable.
You can define the value of the VARIABLE statement by either writing a function expression in the dataset
or by calling a VARSUB user-written subroutine. Learn more on User-Written Subroutines and Utility Subroutines.
Function expressions and user-written subroutines can access the value of the VARIABLE statement with the
Adams Solver (C++) function VARVAL(id) (see VARVAL) to represent the value, where id specifies the user-
426 Adams Solver
C++ Statements
selected identifier of the VARIABLE statement. User-written subroutines access single VARIABLE statement
values by calling the subroutine SYSFNC.
Caution:  Use caution when defining a VARIABLE statement that is dependent on another
VARIABLE statement or on an Adams Solver (C++) statement that contains
functions. If a defined system of equations does not have a stable solution,
convergence may fail for the entire Adams Solver (C++) 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 (C++) tries to solve this equation using the Newton-
Raphson iteration, the solution diverges and Adams Solver (C++) displays a message
on the screen indicating that the solution has failed to converge.
 The IC argument should be used whenever a zero value might cause a floating point
exception or lead Adams Solver (C++) away from the desired solution.
Examples
VARIABLE/4, FUNCTION = IMPACT(DZ(10,90),
, VZ(10,90), 1, 3E5, 1.2, 1,.05)
This VARIABLE statement defines an impact function. You may refer to this function as VARVAL(4) in
other function expressions. This may make the other expressions more concise and readable, and might avoid
repeated impact function calculations.
VFORCE 427
C++ Statements
VFORCE
The VFORCE statement creates a translational vector force element that is specified using three orthogonal
components. You may define the VFORCE statement through user-specified function expressions in the
Adams Solver (C++) dataset or through user-written subroutines.
Format
Arguments
FX=e Specifies the magnitude and sign of the x component of the VFORCE
translational force. The direction of this component is parallel to the
x-axis of the RM marker.
FY=e Specifies the magnitude and sign of the y component of the VFORCE
y-axis of the RM marker.
FZ=e Specifies the magnitude and sign of the z component of the VFORCE
z-axis of the RM marker.
FXYZ=e3d Specifies the 3D vector expression for the VFORCE force relative to
the RM marker.
FUNCTION=USER(r1[,...,r30]) Specifies up to 30 user-defined constants for use in computing the
force components in a user-defined subroutine VFOSUB.
I=id Specifies the marker at which Adams Solver (C++) applies the action
force. You must ensure that the I marker is a fixed marker and on a
Adams Solver (C++) always applies the force at a fixed point on the
part.
428 Adams Solver
C++ Statements
JFLOAT=id Specifies the marker at which Adams Solver (C++) applies the reaction
force. You must ensure that the JFLOAT marker is a floating marker
and on a different part than the I marker. Adams Solver (C++) moves
the JFLOAT marker to keep it superimposed on the I marker, which
means that the reaction force may move with respect to the part.
Adams Solver (C++) does not calculate reaction forces when the
JFLOAT marker is on the ground part.
RM=id Specifies the marker which determines the orientation of the force
components. You must ensure that RM is a fixed marker. RM may be
the same as I and may be on any part in your system.
VFOSUB.
Extended Definition
The VFORCE statement creates an Adams Solver (C++) translational vector force element that applies a
three-component force between two parts of the system. The element applies an action force to the part to
which the I marker belongs and a corresponding reaction force to the part to which the JFLOAT marker
belongs. The VFORCE statement establishes the position of the JFLOAT marker. As the system moves,
Adams Solver (C++) moves the JFLOAT marker on its part to keep the JFLOAT and I markers superimposed.
Therefore, Adams Solver (C++) applies the reaction force to the JFLOAT marker’s part at the instantaneous
position of the I marker.
The total vector force depends on the vector sum of the individual force components that you specify. The
magnitude of the force is the square root of the sum of the squares of the magnitude of the three mutually-
orthogonal force components. You can specify the functions with function expressions (see C++ Functions) or
user-written FORTRAN subroutines (see User-Written Subroutines).
RM marker axes determine the direction of the force action. The reaction is equal and opposite to the action.
Formulation
Action
Applied to: I marker
Values:
F a = FXxˆ rm + FYyˆ rm + FZzˆ rm

where:
 Fa is the action applied to the I marker
 FX is the user-defined function defining the magnitude and sign of the x-component
 FY is the user-defined function defining the magnitude and sign of the y-component
VFORCE 429
C++ Statements
 FZ is the user-defined function defining the magnitude and sign of the z-component
 xˆ rm is a unit vector along the + x-direction of the RM marker
 yˆ rm is a unit vector along the + y-direction of the RM marker
 zˆ rm is a unit vector along the + z-direction of the RM marker

Reaction
Values:
Fr = -Fa
where Fr is the reaction applied to the JFLOAT marker.
the same part as the I marker, or the JFLOAT marker, or to a third, unrelated part.
Caution: The user-defined functions FX, FY, and FZ should be smooth, continuous, and single-
valued. These conditions make the solution process very effective.
Example 1
VFORCE/5, I=310, JFLOAT=9910, RM=310,
, FX = -20.*VX(310,9900,310)\
, FY = -20.*VY(310,9900,310)\
, FZ = -20.*VZ(310,9900,310)
This VFORCE statement defines a vector force acting between fixed Marker 310 and floating Marker 9910.
Expressions FX, FY, and FZ define the magnitudes and signs of the force components along the x, y, and z
axes of the reference marker, which is also Marker 310. Adams Solver (C++) superimposes floating Marker
9910 on Marker 310, and apply the reaction force at that point.
Example 2
, FXYZ = -20.*VXYZ(310,9900,310) + [0, SIN(TIME), 0]
Applications
The VFORCE statement is most useful to define a vector force whose point of application and/or direction
is most easily formulated in a coordinate system that moves or is on a different part. You can use a VFORCE
statement to model a point mass sliding down an inclined cantilever for normal and frictional force effects
430 Adams Solver
C++ Statements
(see the figure below). The RM reference marker is fixed to the cantilever and supplies the orientation for the
normal and frictional forces.
Model of a Point Mass Sliding Down Incline
You can also use the VFORCE statement to represent the tractive, cornering, and vertical tire forces associated
with the tire contact patch of a moving vehicle. In this instance, the RM reference marker would be fixed to
the vehicle at the approximate point where the tire contacts the ground. The global velocity of the contact
point, resolved onto the RM axes, would provide the velocity information necessary to compute the tractive
and cornering forces.
When compared with the SFORCE statement (see SFORCE), the VFORCE statement can vary both its point
respect to the RM marker).
If torque effects are important, you can use the VFORCE statement in conjunction with the VTORQUE
statement (see VTORQUE) to supply resultant moment components. Alternatively, you may employ a single
GFORCE statement (see GFORCE) to specify a unified six-component force set.
VTORQUE 431
C++ Statements
VTORQUE
The VTORQUE statement defines a vector torque that consists of three orthogonal components. You can
define the VTORQUE statement through user-specified function expressions in the Adams Solver (C++)
dataset or through user-written subroutines.
Format
Arguments
FUNCTION=USER(r1[,...,r30] Specifies up to thirty user-defined constants used to compute the

) torque components in an externally-defined subroutine VTOSUB.
I=id Specifies the marker on the part to which Adams Solver (C++) applies
the action torque. You must ensure that the I marker is a fixed marker
and on a different part than the JFLOAT marker.
JFLOAT=id Specifies the marker on the part to which Adams Solver (C++) applies
the reaction torque. You must ensure that the JFLOAT marker is a
marker. Adams Solver (C++) does not calculate reaction forces when
the JFLOAT marker is on the ground part.
RM=id Specifies the marker which determines the orientation of the torque
the same as I and on any part in the system.
VTOSUB.

TXYZ=e3d Specifies the 3D vector expression for the VTORQUE torque relative
to the RM marker.
432 Adams Solver
C++ Statements
TX=e Specifies the magnitude and sign of the x component of the torque
exerted by the VTORQUE element. The direction of this torque
component is parallel to the x-axis of the RM marker in the sense of the
right-hand rule (that is, a positive torque causes a counterclockwise
rotation).
TY=e Specifies the magnitude and sign of the y component of the torque
component is parallel to the y-axis of the RM marker in the sense of
the right-hand rule (that is, a positive torque causes a counterclockwise
rotation).
TZ=e Specifies the magnitude and sign of the z component of the torque
component is parallel to the z-axis of the RM marker in the sense of the
rotation).
Extended Definition
The VTORQUE statement creates an Adams Solver (C++) rotational force element, that applies a vector
torque between two parts of the system. The element applies an action to the part to which the I marker
belongs and a corresponding reaction to the part to which the JFLOAT marker belongs. The VTORQUE
statement establishes the position of the JFLOAT marker. As the system moves, Adams Solver (C++) moves
the JFLOAT marker on its part to keep the JFLOAT and I markers superimposed. Thus, Adams Solver (C++)
applies the reaction torque to the JFLOAT marker’s part.
The components of the torque depend on expressions or subroutines that you supply. The magnitude of the
torque is the square root of the sum of the squares of the magnitudes of the three mutually orthogonal torque
components. You can specify these functions using function expressions (see C++ Functions) or user-written
FORTRAN subroutines (see User-Written Subroutines).
The direction of the torque action is determined by the resultant vector formed by the three component
torque you defined along the RM marker axes. The reaction is equal and opposite to the action.
Formulation
Action
Values:
T a = TXxˆ rm + TYyˆ rm + TZzˆ rm

where:
 Ta is the action applied to the I marker
VTORQUE 433
C++ Statements
 TX is the user-defined function defining the magnitude and sign of the x-component according to
the right-hand rule
 TY is the user-defined function defining the magnitude and sign of the y-component according to
the right-hand rule
 TZ is the user-defined function defining the magnitude and sign of the z-component according to
the right-hand rule
Reaction
Values:
Tr = -Ta
where Tr is the reaction applied to the JFLOAT marker.
Tip: Depending on the nature of the desired torque relationship, the RM marker may belong to
the same part as the I marker or the JFLOAT marker, or to a third, unrelated part.
Caution: The user-defined functions TX, TY, and TZ should be smooth, continuous, and single-
Examples 1
VTORQUE/3, I=310, JFLOAT=9911, RM=310,
, TX = -6.*WX(310,9900,310)\
, TY = -6.*WY(310,9900,310)\
, TZ = -6.*WZ(310,9900,310)
This VTORQUE statement defines a vector torque acting between fixed Marker 310 and floating Marker
9911. Expressions TX, TY, and TZ define the magnitude and sign of the torque components about the x, y,
and z axes of the reference marker, which is also Marker 310. Adams Solver (C++) superimposes floating
Marker 9911 on Marker 310, and apply the reaction force at that point.
Example 2
, TXYZ = -6.*WXYZ(310,9900,310) + [0, SIN(TIME), 0]
434 Adams Solver
C++ Statements
Applications
The VTORQUE statement is particularly useful when you need to define a vector torque whose point of
application and/or direction is most easily formulated in a coordinate system which moves or is on a different
part.
For example, the VTORQUE statement could be used to represent the yaw, pitch, and rolling moments on
a flight vehicle (see the figure below). In this instance, the RM marker would be fixed to the vehicle at its
aero-dynamic center. You can use a VFORCE statement (see VFORCE) to supply the remaining translational
forces, or the GFORCE statement (see GFORCE) to provide all six forces using a single entity. In any event, you
can use the reference marker to resolve the aircraft inertial velocity onto aircraft axes for subsequent
calculation of aerodynamic forces.
Yaw, Pitch, and Rolling Moments on a Flight Vehicle
Another application where a VTORQUE would significantly simplify modeling and analysis is in
consideration of gravitational torques exerted on Earth-orbiting satellites. In this case the RM marker would
not be fixed in the satellite or the Earth, but would move with the rotating line segment extending between
the satellite and the Earth.
When compared with the SFORCE statement (see SFORCE), the VTORQUE statement offers the advantage
that the resultant torque direction (with respect to the RM marker) can vary.
1
C++ Functions
C++ Functions
You use function expressions to define a wide variety of nonstandard phenomena in your model. A
comprehensive set of symbolic variables operators and functions are provided for this purpose. Learn more
about Operators. These can be used to create complex expressions.
Below are the Adams Solver (C++) function expressions grouped according to their function. Detailed
information on each function expression can be found by following the links.
Category Name
FORTRAN 77 intrinsic functions ABS LOG10
ACOS MAX
AINT MIN
ANINT MOD
ASIN SIGN
ATAN SIN
ATAN2 SINH
COS SQRT
COSH TAN
EXP TANH
LOG
Simulation parameters and constants CPU NRHS
HSIZE ORDER
TIME PI
MODE DTOR
NJAC RTOD
Displacement measures AX INCANG
AY ORIENT
AZ PHI
DM PITCH
DX PSI
DXYZ ROLL
DY THETA
DZ YAW
Velocity measures VM VZ
VR WM
VX WX
VXYZ WY
VY WZ
Acceleration measures ACCM WDTM
ACCX WDTX
ACCY WDTY
ACCZ WDTZ
2 Adams Solver
C++ Functions
Category Name
Generic force measures FM TM
FX TX
FY TY
FZ TZ
Element-specific applied force measures BEAM SFORCE
BUSH SPDP
FIELD VFORCE
FRICTION VTORQ
GFORCE
Element-specific reaction force measures CVCV MOTION
JOINT PTCV
JPRIM
System element measures ARYVAL POUVAL
DIF SENVAL
DIF1 VARVAL
PINVAL
Arithmetic IF IF
Action Only Constraint Function AO
Interpolation functions AKISPL
CUBSPL
CURVE
INTERP
Miscellaneous Adams intrinsic functions BISTOP INVPSD
CHEBY POLY
DELAY SHF
FORCOS STEP
FORSIN STEP5
HAVSIN SWEEP
IMPACT
Flexible body constants FXFREQ
FXMODE
Vector measures ACCXYZ UVY
DXYZ UVZ
FXYZ VXYZ
TXYZ WXYZ
UVX WDTXYZ
Vector functions UV
MAG
TRANS
ABS 3
C++ Functions
ABS
The ABS function returns the absolute value of the expression a.
Format
ABS(a)
Arguments
a Any valid function expression.
Number of Arguments: 1
Examples
Variable/1, FUNCTION= ABS(DX(21,11)*VX(21,11)+DY(21,11)*VY(21,11)
+ DZ(21,11)*VZ(21,11))
This variable statement defines a new state variable. Its value is the absolute value of the radial velocity
between Markers 21 and 11.
See other FORTRAN 77 intrinsic functions available.
4 Adams Solver
C++ Functions
ACCM
The ACCM function calculates the magnitude of the second time derivative of the displacement vector of
marker i from marker j. The time derivatives are taken in the reference frame of marker l. Markers j and l
default to the global coordinate system and the global reference frame if they are not specified.
Format
ACCM(i[,j][,l])
Arguments
i The marker whose acceleration is being measured.

j The marker with respect to which the acceleration is being measured. Set j = 0, while still
specifying l, if you want j to default to the global coordinate system.
l The reference frame in which the second time derivative of the displacement vector is taken. Set
l = 0 or omit the argument if you want the time derivatives to be calculated in the ground
Extended Definition
Mathematically, ACCM is calculated as follows:
(l) 2 (l) 2 (l) 2 (l) 2

d d d d
ACCM ( i ,j ,l ) = Ri – Rj ⋅ Ri – Rj
dt2 d t2 dt2 d t2
where R i is the displacement of marker i in ground and R j is the displacement of marker j in ground.
Note that for any vector quantity p:
(A) d (B) d
p≠ p
dt dt
Examples
REQUEST/10, F2=ACCM(21,11)
This statement defines the second component of a user-defined request as the magnitude of translational
acceleration of Marker 21 with respect to Marker 11. Since the l marker is not specified, the derivatives are
taken in the inertial reference frame.
REQUEST/10, F2=ACCM(21,11,32)
This statement defines the second component of a user-defined request as the magnitude of the translational
acceleration of Marker 21 with respect to Marker 11. Vector time derivatives taken in reference to Marker 32.
See other Acceleration measures available.
ACCX 5
C++ Functions
ACCX
The ACCX function returns the x-component of the difference between the acceleration vector of marker i
and the acceleration vector of marker j as computed in the coordinate system of marker k. All vector time
derivatives are taken in the reference frame of marker l. Marker j defaults to the global coordinate system if
it is not specified. Similarly, markers k and l default to the global coordinate system and the global reference
frame if they are not specified.
Format
ACCX(i[,j][,k][,l])
Arguments

j The marker with respect to which the acceleration is being measured. Set j = 0, while still specifying
l, if you want j to default to the global coordinate system.
k The marker in whose coordinate system the acceleration vector is being expressed. Set k = 0, while
still specifying l, if you want the results to be calculated along the x-axis of the global coordinate
system.
l The reference frame in which the second time derivative of the displacement vector is taken. Set l
= 0 or omit the argument if you want the time derivatives to be taken in the ground coordinate
system (GCS).
Extended Definition
Mathematically, ACCX is calculated as follows:
(l) 2 (l) 2
d d ˆ
ACCX ( i ,j ,k ,l ) = Ri – Rj ⋅ xk
dt2 dt 2
ˆ
where R i is the displacement of marker i in ground, R j is the displacement of marker j in ground, and x k
is the unit vector along the x-axis of marker k.
Examples
DIFF/1, IC=0, FUNCTION=ACCX(21,11)
This statement defines a user-specified differential equation. The time derivative of the state is specified to be
the x-component of the acceleration of Marker 21 with respect to Marker 11. The coordinate system for
calculating the component, and for referencing the frame that takes time derivatives, defaults to ground.
DIFF/2, IC=1, FUNCTION=ACCX(21,0,31)
the x-component of the acceleration vector of Marker 21 with respect to the global origin. The vector is
6 Adams Solver
C++ Functions
expressed in the coordinate system of Marker 31. All time derivatives are taken in the inertial reference frame
since the l marker is not specified.
ACCXYZ 7
C++ Functions
ACCXYZ
The ACCXYZ measure returns the difference between the acceleration vector of marker i and the acceleration
vector of marker j resolved in the coordinate system of marker k. All vector time derivatives are taken in the
reference frame of marker l.
Format
ACCXYZ(i[,j][,k][,l])
Arguments

j The marker with respect to which the acceleration is being measured. If j is not specified, it defaults
to the global origin. Specify j = 0 if you want to use this default, then specify k or l.
k The marker in whose coordinate system the acceleration vector is being expressed. If not specified,
k defaults to the global coordinate system. Specify k = 0 if you want to use this default, then specify l.
l The reference frame in which the second time derivative of the displacement vector is taken. Set l =
0 or omit the argument if you want the time derivative to be taken in the global reference frame.
Extended Definition
Mathematically, ACCXYZ is calculated as follows:
 (l)
d
2 (l)
d
2
ˆ 
 Ri – R j ⋅ xk 
 dt2 d t2 
   ACCX 
 (l) 2 (l) 2
ACCXYZ ( i ,j ,k ,l ) =  d d ˆ  =  ACCY 
Ri – Rj ⋅ yk   
 dt2 d t2   
   ACCZ 
(l) 2 (l) 2
 d d ˆ 
 R i– R j ⋅ zk 
 d t2 dt2 
where:
 R i is the displacement of marker i with respect to the global origin.
 R j is the displacement of marker j with respect to the global origin.

(l) 2
d
 denotes two time differentiations in the reference frame of the l marker.
dt2
 ACCX is the ACCX measure.
8 Adams Solver
C++ Functions
 ACCY is the ACCY measure.

 ACCZ is the ACCZ measure.
ˆ
 x k is the unit vector along the x-axis of marker k.
ˆ
 y k is the unit vector along the y-axis of marker k.
ˆ
 z k is the unit vector along the z-axis of marker k.
Examples
Unlike VR, the Adams function expression language does not provide support for radial acceleration (or
separation acceleration), ACCR. The following variable shows how this quantity could be computed.
VARIABLE/1, FUNCTION = ACCXYZ(21,11) * UV(DXYZ(21,11))
See other Vector measures available.

ACCY 9
C++ Functions
ACCY
The ACCY function returns the y-component of the difference between the acceleration vector of marker i
Format
ACCY(i[,j][,k][,l])
Arguments

still specifying l, if you want the results to be calculated along the y-axis of the global coordinate
system.
l The reference frame in which the second time derivative of the displacement vector is taken. Set l =
0 or omit the argument if you want the time derivatives to be taken in the ground coordinate system
(GCS).
Extended Definition
Mathematically, ACCY is calculated as follows:
(l) 2 (l) 2
d d ˆ
ACCY ( i ,j ,k ,l ) = Ri – Rj ⋅ yk
dt2 dt 2
ˆ
where R i is the displacement of marker i in ground, R j is the displacement of marker j in ground, and y k
is the unit vector along the y-axis of marker k.
Examples
DIFF/1, IC=0, FUNCTION=ACCY(21,11)
the y-component of the acceleration of Marker 21 with respect to Marker 11. The coordinate system for
DIFF/2, IC=1, FUNCTION=ACCY(21,0,31)
the y-component of the acceleration vector of Marker 21 with respect to the global origin. The vector is
10 Adams Solver
C++ Functions
ACCZ 11
C++ Functions
ACCZ
The ACCZ function returns the z-component of the difference between the acceleration vector of marker i
Format
ACCZ(i[,j][,k][,l])
Arguments

k The marker in whose coordinate system the acceleration vector is being expressed. Set k = 0 if you
want the results to be calculated along the z-axis of the global coordinate system.
l The reference frame in which the second-time derivative of the displacement vector is taken. Set l
= 0, or omit the argument, if you want the time derivatives to be taken in the ground coordinate
system (GCS).
Extended Definition
Mathematically, ACCZ is calculated as follows:
(l) 2 (l) 2
d d ˆ
ACCZ ( i ,j ,k ,l ) = Ri – Rj ⋅ zk
dt2 dt 2
ˆ
where R i is the displacement of marker i in ground, R j is the displacement of marker j in ground, and z k
is the unit vector along the z-axis of marker k.
Examples
DIFF/1, IC=0, FUNCTION=ACCZ(21,11)
DIFF/2, IC=1, FUNCTION=ACCZ(21,0,31)
12 Adams Solver
C++ Functions

ACOS 13
C++ Functions
ACOS
The ACOS function calculates the arc cosine of an expression a. Expression a must evaluate to a value whose
absolute value is less than or equal to 1. The value returned by ACOS lies in the range [0, π ] (i.e., 0 <
ACOS(a) < π ).
Format
ACOS(a)
Arguments
Examples
VARIABLE/1, FU=ACOS((DX(21,11)*DX(31,41)+DY(21,11)*DY(31,41)
+ DZ(21,11)*DZ(31,41))/(DM(21,11)*DM(31,41))
This statement specifies a new user-defined state variable. Its value is the included angle of the lines joining
Markers 11 and 21 and Markers 41 and 31. The result is in radians.
14 Adams Solver
C++ Functions
AINT
The AINT function returns the nearest integer whose magnitude is not larger than the integer value of the
expression a.
AINT(a)= 0 if ABS(a)< 1
AINT(a)=int(a) if ABS(a) > 1

The value of the mathematical function int of a variable x is equal to x if x is an integer. If x is not an integer,
then int(x) is equal to the nearest integer to x whose magnitude is not greater than the magnitude of x. Thus:
int(-7.0) = -7, int(-4.8) = -4, and int(4.8) = 4.
Format
AINT(a)
Arguments
Caution: Note that AINT is not a differentiable function. Be careful when using this function in an
expression that defines a force or motion input to the system.
Examples
AINT(-6.5) = -6
AINT(4.6 ) = 4
AKISPL 15
C++ Functions
AKISPL
The AKISPL function returns the iord derivative of the interpolated value of SPLINE/id at X=x and Z=z.
Format
AKISPL (x, z, id)
or
AKISPL (x,0,id [,iord])
Arguments
x A real variable that specifies the independent variable value along the x-axis of the AKISPL.
z A real variable that specifies the second independent variable value along the z-axis of the surface
being interpolated. Specify z = 0 if the SPLINE statement defines only one curve.
id An integer variable that specifies the identifier of a SPLINE statement that you define in the
Adams Solver dataset.
iord An integer variable that specifies the order of the derivative to be taken at the interpolated point.
iord may not be specified when interpolating on a surface (for example, when z = 0).
Default: 0
Range: 0 < iord < 2
Extended Definition
The AKISPL function uses the Akima method of interpolation to create a spline function across a set of data
points. The data points to be interpolated are defined by a SPLINE statement in the Adams Solver dataset.
The SPLINE that you define in the dataset may represent a curve (x-y points) or a surface (x-y-z points).
Interpolation in the y direction is cubic, and interpolation in the z direction is linear. To interpolate the values
specified in a curve, set z = 0.
iord specifies the order of the derivative and may be used only when interpolating a curve (that is, when z = 0).
AKISPL is very fast, since it uses local methods. It always produces good results for the value of the function
being approximated. AKISPL returns good estimates for the first derivative of the approximated function
when the data points are evenly spaced. In instances where the data points are unevenly spaced, the estimate
of the first derivative may be in error. In all cases, the second derivative of the function being approximated is
unreliable.
For more information on the Akima method of interpolation, see the references listed in Additional
Publications.
16 Adams Solver
C++ Functions
Tip: If you want to force a particular region of a spline function to be linear, you should know that
four consecutive points on a straight line will yield a linear section in the region between the
central two points, and, similarly, four consecutive points on a straight line at the end of a
spline will yield a linear fit from the second point onward.
Examples
, FUNCTION=AKISPL(TIME, 0, 1, 1)
This SFORCE statement defines a translational force that acts between Markers 409 and 109. The SPLINE
statement provides the discrete data used to generate the interpolation function using the Akima spline. Since
this SPLINE statement defines only one curve, the value of z is defined to be 0. AKISPL returns the first
derivative of the spline at the interpolated point since iord = 1.
See other Interpolation functions available.
ANINT 17
C++ Functions
ANINT
The ANINT function calculates the nearest integer to a.
ANINT(a) = int(a + .5) if a > 0
ANINT(a) = int(a - .5) if a < 0
then int(x) is equal to the nearest integer to x whose magnitude is not greater than the magnitude of x. Thus:
int(-7.0) = -7, int(-4.8) = -4, and int(4.8) = 4.
Format
ANINT(a)
Arguments
Number of arguments: 1
Examples
ANINT(-4.6) = -5
ANINT(4.6) = 5
18 Adams Solver
C++ Functions
AO
The AO (Action Only) function isolates certain portions of a scalar expression from a reaction force when
the expression appears in the context of a general constraint (GCON). The AO function has no effect in
expressions that are not constraint expressions.
Format
AO(exp)
Arguments
exp The subexpression which is to be isolated from a reaction force.
Extended Definition
To understand the purpose of the AO function, it is best to examine Lagrange's equations for a constrained
system:
d  ∂L ∂L
– + λ T Cq = 0 T
d t  ∂ q· ∂ q
C ( q ,t ) = 0
where L is the system Lagrangian, q are the generalized coordinates, C are the constraints, and λ are the
Lagrange multipliers.
The equation illustrates how Adams Solver (C++) uses the constraint Jacobian Cq to project Lagrange
multipliers (reaction forces) into the generalized equations of motion. The AO function has the effect of
making certain generalized coordinates, q, exempt from these reaction forces.
Examples
GCON/1, FUN=DX(1) - AO(DX(2))
GCON/2, FUN=DY(1) - AO(DY(2))
GCON/3, FUN=DZ(1) - AO(DZ(2))
This set of GCON elements is similar to a spherical joint in that Adams Solver (C++) ensures that markers 1
and 2 are coincident. Unlike the spherical joint, however, a constraint force will only be applied to marker 1
without a corresponding reaction force acting on marker 2.
A physical interpretation is that Adams Solver(C++) pushes marker 1 toward marker 2 without pushing
marker 2 back toward marker 1.
The next example demonstrates how a displacement constraint could be influenced by velocity, without the
velocity being influenced by the constraint.
GCON/10, FUN=DM(1,2) - AO(VR(3,4))/200
AO 19
C++ Functions
Note: Excessive use of AO may lead to systems which are impossible to solve. For example, the
following constraints:
GCON/1, FUN=AO(DX(1,2))
GCON/2, FUN=AO(DY(1,2))
GCON/3, FUN=AO(DZ(1,2))
instruct Adams Solver (C++) to keep markers 1 and 2 coincident, but render it powerless to do
so. Because a constraint force will not be applied to either marker, the constraint is unlikely to
be satisfied and a convergence failure will occur.
20 Adams Solver
C++ Functions
ARYVAL
The ARYVAL function returns component comp of ARRAY/id. Depending on the definition of ARRAY/id,
this may be a constant that you defined in the Adams Solver (C++) dataset, an input to an LSE, GSE, or
TFSISO, a state variable defined by an LSE, GSE, or TFSISO, or an output from an LSE, GSE, or TFSISO.
Format
ARYVAL (id, comp)
Arguments
id The identifier of the array whose data is being requested.

comp An integer that specifies the component of the array to be returned.
Examples
ARRAY/17, NUM=11.465,2.321
SFORCE/19, ROT, I=23, J=11
, FUNCTION=-ARYVAL(17,1)*(AZ(23,11)-ARYVAL(17,2))
This example illustrates how a value defined in an ARRAY statement can be accessed using the ARYVAL
function.
LSE/1, X=1, U=2, Y=3, A=11, B=12, C=13, D=14
This statement defines a set of linear state equations. The A, B, C, and D matrices for this LSE are defined
by matrices 11-14.
SFORCE/6, ROT, I=23, J=11, FUNCTION=ARYVAL(3,2)
The second output of the LSE is used to define a torque acting on the system.
See other System element measures available.
ASIN 21
C++ Functions
ASIN
The ASIN function computes the arc sine of an expression a. ASIN is defined only when the absolute value
of a is less than or equal to 1. The range of ASIN is [- π /2, π /2] (that is, - π /2 < ASIN(a) < π /2).
Format
ASIN(a)
Arguments
Examples
DIFF/1, IC=1.05, FUNCTION=ASIN(DX(21,11)/DM(21,11))
This statement defines a user-specified differential equation. The initial value of the state variable is 1.05. The
time derivative of the state variable is the expression:
ASIN(DX(21,11)/DM(21,11))
22 Adams Solver
C++ Functions
ATAN
The ATAN function returns the arc tangent of an expression a. The range of ATAN is [- π /2, π /2] (that is,
- π /2 < ATAN(a)< π /2).
Format
ATAN(a)
Arguments
Examples
SFORCE/1, ROTATIONAL, I=21, J=11
, FUNCTION=-10*ATAN(DY(42,33)/DX(42,33))
This SFORCE statement defines a torque acting between Markers 21 and 11. The value of the torque is the
spring constant (10) multiplied by the angle between the line joining Markers 33 and 42 and the global x-
axis as shown in the figure below.
Example Illustrating the Use of the ATAN Function

ATAN2 23
C++ Functions
ATAN2
The ATAN2 function expression returns the arc tangent of the expression a1/a2. a1 and a2 themselves may
be expressions. The implementation uses the standard C++ function std::atan2(double, double) to compute
the numerical value.
- π < ATAN2(a1,a2) < π

ATAN2(a1,a2) > 0 if a1 > 0
ATAN2(a1,a2) = 0 if a1 = 0, a2 > 0
ATAN2(a1,a2) = π if a1 = 0, a2 < 0
ATAN2(a1,a2) < 0 if a1 < 0
ABS(ATAN2(a1,a2))= π /2 if a2 = 0
ATAN2(a1,a2) = 0 if a1 = 0, and a2 = 0
Format
ATAN2(a1,a2)
Arguments
a1 Any valid function expression.

Caution: Notice the singular case when a1=0 and a2=0 does not generate a domain error; instead the
function returns zero. However, partial derivatives may be infinite potentially causing
convergence failures. To alleviate the issue, Adams Solver C++ returns a small quantity for the
partial derivatives when the absolute value of both arguments fall below a small threshold. To
revert to the behavior prior to version 2016, set the environment variable
MSC_ADAMS_SOLVER_STANDARD_ATAN2 to any value.
Examples
VARIABLE/1,
, FUNCTION=ATAN2(DY(21,31,41), DX(21,31,41))
This VARIABLE statement defines an algebraically-determined, user-defined state variable in Adams Solver
(C++). Its value is specified by the expression containing ATAN2.
24 Adams Solver
C++ Functions
AX
The AX function returns the rotational displacement (in radians) of marker i about the x-axis of marker j,
and accounts for angle wrapping.
Marker j defaults to the global coordinate system if it is not specified. This value is computed as follows:
assume that rotations about the other two axes (y- and z-axes) of marker j are zero. Then, AX is the angle
between the two y-axes (or the two z-axes). AX is measured in a counter-clockwise sense from the y-axis of
marker J to the y-axis of marker I (see the figure below).
Measurement of AX
Format
AX(i[,j])
Arguments
i The marker whose rotations are being sought.

j The marker whose coordinate system is used as a reference to calculate the rotations of marker i.
When j is not specified, Adams Solver (C++) defaults to the global coordinate system.
Extended Definition
Mathematically, AX is calculated as:
AX = ATAN2 ( – zˆ i • yˆ j, zˆ i • zˆ j )
where:
 zˆ i is the z-axis of marker i
 yˆ j is the y-azis of marker j
 zˆ j is the z-axis of marker j

AX 25
C++ Functions
Tip: If you want to change the AX function so it does not account for angle wrapping, use the
MOD function. For example, use the function:
(MOD(AX(2,1) + PI, 2 * PI) - PI
The MOD function achieves the cyclic effect and the +PI and -PI shift the curve accordingly.
Caution: For large rotations (greater than 10 degrees) about the y-axis or z-axis on Marker j, the AX
function becomes increasingly non-physical. Moreover, AX is undefined when both arguments
to ATAN2 are zero. This occurs when the z-axis of marker i is orthogonal to the plane defined
by the y and z-axis of the j marker.
Examples
GFORCE/1, I=21, JFLOAT=31, RM=41
, FX=-20*AX(43,32)
This GFORCE statement applies a force at the origin of Marker 21 along the x-axis of Marker 41. The
reaction force is on floating Marker 31. The floating Marker 31 can belong to another part but its location
is always the same as Marker 21.
The value of the force is -20 times the angle between the y axes of Markers 43 and 32. The angle is measured
in a counterclockwise sense from the y-axis of Marker 32 to the y-axis of Marker 43.
See other Displacement measures available.
26 Adams Solver
C++ Functions
AY
The AY function returns the rotational displacement (in radians) of marker i about the y-axis of marker j, and
accounts for angle wrapping.
Marker j defaults to the global coordinate system if it is not specified. The values are computed as follows:
assume rotations about the other two axes (x-, z-axes) of marker j are zero. Then AY is the angle between the
two x-axes (or the two z-axes). AY is measured counter-clockwise from the z-axis of the J marker to the z-axis
of the I marker (see the figure below).
Measurement of AY
Format
AY(i[,j])
Arguments

j The marker with respect to which the rotations are being measured.
Extended Defintion
Mathematically, AY is calculated as:
AY = ATAN2 ( zˆ i • xˆ j, zˆ i • zˆ j )
where:
 xˆ j is the x-azis of marker j

AY 27
C++ Functions
Tip: If you want to change the AY function so it does not account for angle wrapping, use the MOD
function. For example, use the function:
(MOD(AY(2,1)+PI,2*PI)-PI)
Caution: For large rotations (greater than 10 degrees) about the x-axis or z-axis of marker j, the AY
function becomes increasingly non-physical. Moreover, AY is undefined when both arguments
by the x and z-axis of the j marker.
Examples
SFORCE/10, ROTATION, I=23, J=34
, FUNCTION=-4*(AY(46,57)**2)
This SFORCE statement applies a moment about the common z-axes of Markers 23 and 34. The torque acts
on Marker 23; the reaction torque acts on Marker 34.
The value of the torque being applied is -4 times the square of the angle between the z axes of Markers 46
and 57. The angle is measured in a counterclockwise sense from the z-axis of Marker 57 to the z-axis of
Marker 46.
28 Adams Solver
C++ Functions
AZ
The AZ function returns the rotational displacement (in radians) of marker i about the z-axis of marker j, and
assume that rotations about the other two axes (x-, y-axes) of marker j are zero. Then AZ is the angle between
the two x-axes (or the two y-axes). AZ is measured in a counterclockwise sense from the x-axis of the J
marker to the x-axis of the I marker (see the figure below).
Measurement of AZ
Format
AZ(i [,j ])
Arguments

Extended Definition
Mathematically, AZ is calculated as:
AZ = ATAN2 ( x̂ i • ŷ j, x̂ i • x̂ j )
where:
 xˆ i is the x-axis of marker i
 yˆ j is the y-axis of marker j

AZ 29
C++ Functions
Tip: If you want to change the AZ function so it does not account for angle wrapping, use the
(MOD(AZ(2,1)+PI,2*PI)-PI)
Caution: For large rotations (greater than 10 degrees) about the x-axis or y-axis of marker j, the AZ
function becomes increasingly non-physical. Moreover, AZ is undefined when both arguments
to ATAN2 are zero. This occurs when the x-axis of marker i is orthogonal to the plane defined
by the x and y-axis of the j marker.
Examples
VTORQUE/1, I=21, JFLOAT=31, RM=41
, TX=-10*(AX(21,32)-10D)/
, TY=-15*(AY(21,32)-15D)/
, TZ=-30*(AZ(21,32)-25D)
This VTORQUE statement applies a moment at Marker 21. The reaction moment is at the floating Marker
31. The torques are expressed in the coordinate system of Marker 41.
30 Adams Solver
C++ Functions
BEAM
The BEAM function returns component comp of a force due to BEAM/id as calculated in the coordinate
system of marker rm. If jflag is set to zero, the value returned is the force/torque acting on the I marker of
the BEAM. If jflag is set to 1, the value returned is that acting on the J marker. rm may be specified as zero
if the results are desired in the global coordinate system.
Format
BEAM (id, jflag, comp, rm)
Arguments
id An integer specifying the identification number of the beam.

jflag An integer flag specifying the beam connectivity marker at which the forces and torques are
computed.
0 = forces and moments at the I marker
1 = forces and moment at the J marker

comp An integer value that specifies the component of the beam force to be returned.
1 = Magnitude of the force

2 = x component of the force
3 = y component of the force
4 = z component of the force
5 = Magnitude of the torque
6 = x component of the torque
7 = y component of the torque
8 = z component of the torque
rm The coordinate system in which the results are expressed. To return the results in the global
coordinate system, set rm = 0.
Examples
REQUEST/1
, F2=BEAM(1001,0,2,0)/
, F3=BEAM(1001,0,3,0)/
, F4=BEAM(1001,0,4,0)
This REQUEST statement stores the x-, y-, and z-component of the forces in BEAM/1001 in columns 2, 3,
and 4, respectively. The forces are calculated at the I marker. The results are computed in the global
coordinate system.
See other Element-specific applied force measures available.
BISTOP 31
C++ Functions
BISTOP
The BISTOP function models a gap element (see Figure 1).
Format
BISTOP (x, x· , x1, x2, k, e, cmax, d)
Arguments
x The distance variable you want to use to compute the force. For example, if you want to use the
x displacement of Marker 0201 with respect to 0301, then x is DX(0201,0301,0301).
x· The time derivative of x to BISTOP. For example, if x is DX(0201,0301,301) then is
VX(0201,0301,0301,0301).
x1 The lower bound of x. If x is less than x1 Adams Solver (C++) calculates a positive value for the
force. The value of x1 must be less than the value of x2.
x2 The upper bound of x. If x is greater than x2 Adams Solver (C++) calculates a negative value for
the force. The value of x2 must be greater than the value of x1.
k A non-negative value that specifies the stiffness of the boundary surface interaction.
e A positive value that specifies the exponent of the force deformation characteristic. For a
stiffening spring characteristic, e > 1.0. For a softening spring characteristic, 0 < e < 1.0.
cmax A non-negative variable that specifies the maximum damping coefficient.
d A positive real variable that specifies the penetration at which the full damping coefficient is
applied.
Extended Definition
The BISTOP function models a gap element. Figure 1 below illustrates the BISTOP force. The gap element
consists of a slot which defines the domain of motion of a Part I located in the slot. As long as Part I is inside
the slot and has no interference with the ends of the slot, it is free to move without forces acting on it. When
Part I tries to move beyond the physical definition of the slot, impact forces representing contact are created
by the BISTOP function. The created force tends to move Part I back into the slot.
The BISTOP force has two components: A stiffness component dependent on the penetration of Part I into
the restricting Part J and a damping or viscous component that may be used to model energy loss.
Figure 1 Example of the BISTOP Function

32 Adams Solver
C++ Functions
To prevent a discontinuity in the damping force at zero penetration, the damping coefficient is defined as 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. Even though the points of
contact between the floating part and the restricting part may change as the system moves, Adams Solver
(C++) always exerts the force between the I and the J markers.
Figure 2 Damping Coefficient versus Penetration
Caution: When e is < 1, the defined force contains a slope discontinuity that may casue difficulty for the
integrator.
Examples
You may model a slider in a slot with a BISTOP function as depicted in Figure 1. Assume a translational joint
constrains the slider to move in a slot. The line of translation is along the colinear z-axes of the I and the J
markers, I belonging to the slider and J to the part containing the slot. You can use an SFORCE statement
together with the BISTOP function to restrict the movement of the slider in the slot and model the gap.
In Figure 1:
 x is the instantaneous distance between the I and the J markers.
 N is the distance between the J marker and the left end of the slot.
BISTOP 33
C++ Functions
 M1 is the distance between the I marker and the left edge of the floating part.
 L is the length of the slot.
 M2 is the distance between the I marker and the right edge of the floating part.
 x1 is the instantaneous distance between the I and the J markers when the floating part first comes
into contact with the left end of the slot.
into contact with the right end of the slot.
Therefore, the parameters for BISTOP for this example are:
x = DZ(I,J,J) and x· = VZ(I,J,J,J)
x= N + M1 for the left end of the slot and
x = N + L - M2 for the right end of the slot or
x1 = N + M1, and
x2 = N + L - M2
Note that when:
 x1 < x < x2, there is no penetration and the force is zero (penetration p = 0).
 x < x1 penetration occurs at the end closer to the J marker and the force is > 0 (penetration p = x1 -
x).
 x > x2 penetration occurs at the end farther away from the J marker, and the force is < 0 (penetration
p = x - x2).
Also note that when p < d the instantaneous damping coefficient is a cubic step function of the penetration,
p; when p > d the instantaneous damping coefficient is cmax.
The BISTOP function for this example is:
BISTOP(DZ(I,J,J,J), VZ(I,J,J,J), x1, x2, k, e, cmax, d)
The values of k, e, cmax, and d depend on the materials used in the two parts and on the shapes of the parts
and are used to define the contact force.
The BISTOP force can be mathematically expressed as follows:
e
 Max ( k ⋅ ( x 1 – x ) – STEP ( x, x 1 – d, c max, x 1, 0 ) ⋅ x', 0 ): x < x1 
 
BISTOP =  0 : x1 ≤ x ≤ x2 
 
 Min ( – k ⋅ ( x – x 2 ) e – STEP ( x, x 2, 0, x 2 + d, c max ) ⋅ x', 0 ): x > x2 
See other Miscellaneous Adams intrinsic functions available.
34 Adams Solver
C++ Functions
BUSH
The BUSH function returns component comp of a force due to BUSHING/id as calculated in the coordinate
system of marker rm. If jflag is set to zero, the value returned is the force/torque acting on the I marker of the
BUSHING. If jflag is set to 1, the value returned is that acting on the J marker. rm may be specified as zero
Format
BUSH (id, jflag, comp, rm)
Arguments
id An integer specifying the identification number of the bushing.

jflag An integer flag specifying the bushing connectivity marker at which the forces and torques are
computed.

comp An integer value that specifies the component of the bushing force to be returned.

Examples
REQUEST/1
, F2=BUSH(1001,0,2,0)/
, F3=BUSH(1001,0,3,0)/
, F4=BUSH(1001,0,4,0)
This REQUEST statement stores the x-, y-, and z-component of the forces in BUSH/1001 in columns 2, 3,
coordinate system.
CHEBY 35
C++ Functions
CHEBY
The CHEBY function evaluates a Chebyshev polynomial at a user specified value x.
Format
CHEBY (x, x0, a0, a1,..., a30)
Arguments
x An expression that specifies the independent variable. For example, if the independent
variable in the function is time, x is the system variable TIME.
x0 The phase shift in the Chebyshev polynomial.
a0, a1,..., a30 The coefficients for the Chebyshev polynomial. A maximum of thirty-one coefficients
may be specified.
Extended Definition
The CHEBY function evaluates a Chebyshev polynomial at a user specified value x. x0, a0, a1,..., a30 are
parameters used to define the constants for the Chebyshev polynomial. The Chebyshev polynomial is defined
as:
C(x) =  aj Tj (x-x0)
where the functions Tj are recursively defined as:
Tj (x-x0) = 2 * (x-x0) * Tj-1 (x-x0) - Tj-2 (x-x0)
with T0 (x-x0) = 1, and T1 (x-x0) =x-x0.
The index “j” has a range from zero to “n”, where “n” is the number of terms in the series.
Note the following:
T2 (x-x0) = 2 * (x-x0)2 - 1
T3 (x-x0) = 4 * (x-x0)3 - 3 * (x-x0)
Examples
MOTION/1, JOINT=21, TRANSLATION,
,FUNCTION = IF (TIME-2:CHEBY(TIME, 1, 1, 0, -1), 0, 0)
This MOTION statement defines a motion using a quadratic Chebyshev polynomial and the system variable
TIME. The arithmetic IF ensures that the function remains zero after 2 time units. When time is less than 2
time units, Adams Solver (C++) evaluates a Chebyshev polynomial to determine the motion. The polynomial
defined in the above example is:
Cheby = 1 + 0 * (time-1) - 1 * [2 (time-1)2 - 1]= -2*time2 +4*time
36 Adams Solver
C++ Functions
CONTACT
The CONTACT function returns the component comp of the force in CONTACT/id in the coordinate
system of marker rm. If jflag is set to zero, Adams Solver (C++) returns the value of the force/torque that acts
on the I marker of CONTACT. If jflag is set to 1, Adams Solver (C++) returns the value that acts on the J
marker. To obtain results in the global coordinate system, you can specify rm as zero.
Format
CONTACT (id, jflag, comp, rm)
Arguments
id An integer specifying the identification number of the CONTACT.

jflag An integer flag specifying the CONTACT connectivity marker at which the forces and torques
are computed.
 0 = forces and moments at the I marker

 1 = forces and moment at the J marker
comp An integer value that specifies the component of the CONTACT to be returned.
 1 - Magnitude of the force applied by all incidents of contact ID

 2 - x-component of the force applied by all incidents of contact ID
 3 - y-component of the force applied by all incidents of contact ID
 4 - z-component of the force applied by all incidents of contact ID
 5 - Magnitude of the torque applied by all incidents of contact ID
 6 - x-component of the torque applied by all incidents of contact ID
 7 - y-component of the torque applied by all incidents of contact ID
 8 - z-component of the torque applied by all incidents of contact ID
Examples
REQUEST/1
, F2= CONTACT(11,0,2,0)/
, F3= CONTACT(11,0,3,0)/
, F4= CONTACT(11,0,4,0)/
, F6= CONTACT(11,0,6,0)/
, F7= CONTACT(11,0,7,0)/
, F8= CONTACT(11,0,8,0)
This REQUEST statement outputs the x-, y- and z-components of the force and torque at the I marker of
CONTACT/11. Because rm is specified as zero, all vectors are expressed in the global coordinate system.
COS 37
C++ Functions
COS
The COS function returns the cosine of an expression a.
Format
COS(a)
Arguments
Examples
MOTION/2060, JOINT=2060, ROTATION,
, FUNCTION=20D+COS(2*PI*TIME)
This MOTION statement defines a rotational motion acting on JOINT/2060. The rotational degree of
freedom is specified to be 20D+COS(2*PI*TIME).
38 Adams Solver
C++ Functions
COSH
The COSH function computes the hyperbolic cosine of an expression a.COSH(a) = (ea + e-a) / 2.0
Format
COSH(a)
Arguments
Examples
REQUEST/36,
, F2=COSH(DZ(21,11,11))
This REQUEST statement returns the hyperbolic cosine of the z-component of the displacement of Marker
21 with respect to Marker 11 in its second column. The result is computed in the coordinate system of
Marker 11.
CPU 39
C++ Functions
CPU
Number of seconds of CPU time used during an Adams run.
Format
CPU
Example
SENSOR/1
, VALUE=100
, GE
, HALT
, FUN=CPU
In the example above, the sensor stops a simulation if it is taking longer than 100 seconds.
See other Simulation parameters and constants available.
40 Adams Solver
C++ Functions
CUBSPL
The CUBSPL function returns the interpolated value of SPLINE/id at X=x and Z=z or returns the iord
derivative at the interpolated value of SPLINE/id at X=x, Z=0.
Format
CUBSPL (x, z, id)
or
CUBSPL (x, 0, id [,iord])
Arguments
x A real variable that specifies the independent variable value along the x-axis of the CUBSPL.
A real variable that specifies the second independent variable value along the z-axis of the surface
being interpolated. If the SPLINE statement defines only one curve, Adams Solver (C++) ignores
this variable.
id An integer variable that specifies the identifier of a CUBSPL statement.
iord An optional integer that specifies the order of the derivative at the interpolate value to be returned
by CUBSPL.
Range: 0 < iord < 2
Extended Definition
The CUBSPL function uses the standard cubic method of interpolation to create a spline function across a
set of data points. The data points are defined in the SPLINE statement in Adams Solver (C++) data deck.
The SPLINE that you define in the Adams Solver dataset may represent a curve (x-y points) or a surface (x-
y-z points). Interpolation in the y direction is cubic and interpolation in the z direction is linear. To
interpolate the values specified in a curve, set z = 0.
iord specifies the order of the derivative and may be used only when interpolating a curve (that is, when z = 0.
CUBSPL, though not as fast as AKISPL, always produces good results for the value of the function being
approximated, its first and second derivatives. There is no requirement on the data points being evenly
spaced. This may be an important consideration when you use splines to define functions in Adams Solver
(C++). The solution process often requires estimates of derivatives of the functions being defined. The
smoother a derivative is, the easier it is for the solution process to converge.
If the spline data contains sudden changes in value, the CUBSPL function gives more oscillatory results for
the curve or surface than are given by the AKISPL function.
For more information on the cubic method of interpolation, see the references listed in Additional
Publications.
CUBSPL 41
C++ Functions
Examples
SPLINE/1,
, X= -3, -2, -1, 0, 1, 2, 3
, Y= -67.4, -48.6, -33.7, 4.8, 24.12, 37.6, 48.4
SFORCE/1, I=409, J=109, TRANSLATION,
, FUNCTION=CUBSPL(TIME, 0, 1)
This SFORCE statement defines the translational force acting between Markers 409 and 109. The SPLINE
statement provides the discrete data used to generate the interpolation function using the cubic spline. Since
the SPLINE statement defines only one curve, the value of z is defined to be 0.
42 Adams Solver
C++ Functions
CURVE
The CURVE function evaluates a B-spline or user-written curve that is created with the CURVE statement.
Format
CURVE (alpha, iord, comp, id)
Arguments
alpha A real variable that identifies the value of the independent parameter, α , at which the CURVE
function evaluates the curve. If the curve is a B-spline computed by the CURVE statement,
alpha must be in the domain -1 < α < 1. If the curve is computed by a CURSUB, alpha must
be in the domain MINPAR < α < MAXPAR (these are specified in the CURVE statement).
iord An integer variable that specifies the order of the derivative the CURVE function returns. The
legal values are:
0 - returns the curve coordinate

1 - returns the first derivative
2 - return the second derivative
comp An integer variable that specifies the component that the CURVE function returns. The legal
values are:
1 - returns the x coordinate or derivative

2 - returns the y coordinate or derivative
3 - returns the z coordinate or derivative
Parameters iord and icomp together allow you to request any one of the following nine return
values:
iord icomp = 1 icomp = 2 icomp = 3
0 x(α) y(α) z(α)
x ( α -)
d------------- y ( α -)
d------------- z ( α )-
d-------------
1
dα dα dα
d2x( α ) d2y( α ) d2z( α )
2 ----------------- ----------------- -----------------
dα 2 dα 2 dα 2
id An integer variable that specifies the identifier of the CURVE statement.
Examples
, FX=CURVE(.4*TIME - 1, 0, 1, 8)/
, FY=CURVE(.4*TIME - 1, 0, 2, 8)/
, FZ=CURVE(.4*TIME - 1, 0, 3, 8)
CURVE 43
C++ Functions
This example applies to a VFORCE acting between Markers 101 and 201. The CURVE statement defines
the force components as a function of alpha, which varies from -1.0 to 1.0. The term 4*TIME-1 computes
the instantaneous value of alpha from the simulation time.
44 Adams Solver
C++ Functions
CVCV
The CVCV function returns component comp of a force or torque due to CVCV/id as calculated in the
coordinate system of marker rm. If jflag is set to zero, the value returned is the force/torque acting on the
IFLOAT marker of the CVCV. If jflag is set to one, the value returned is that acting on the JFLOAT marker.
rm may be specified as zero if the results are desired in the global coordinate system
Format
CVCV (id,jflag,comp,rm)
Arguments
id An integer specifying the identification number of a curve_curve constraint.

jflag An integer flag specifying the curve_curve constraint marker at which the forces and torques are
computed.
0 = forces and moments at the IFLOAT marker

1 = forces and moment at the JFLOAT marker
comp An integer value that specifies the component of the curve_curve constraint to be returned.

coordinate system, set rm = 0
Examples
REQUEST/18,
, F2=CVCV(210,0,2,0)/
, F3=CVCV(210,0,3,0)/
, F4=CVCV(210,0,4,0)/
, F6=CVCV(210,0,6,0)/
, F7=CVCV(210,0,7,0)/
, F8=CVCV(210,0,8,0)
This REQUEST statement returns all three components of the forces and moments acting at the IFLOAT
marker of CVCV Joint 210.
See other Element-specific reaction force measures available.
DEFORM 45
C++ Functions
DEFORM
The DEFORM function calculates the x, y, or z component, or magnitude of the local deformation, or
velocity or acceleration of marker i with respect to marker j on a linear flexible body as computed in the
coordinate system of marker k. Marker j defaults to the LPRF of the flexible body if not specified. Similarly,
marker k defaults to LPRF if it is not specified.
Format
DEFORM(component, Marker* i, Marker* j, Marker* k)
Arguments
component 1 to 24
 1-3 are translational deformation in X, Y, Z and 4 is magnitude of them
 5-7 are angular deformation in X, Y, Z and 8 is magnitude of them
 9-11 are translational deformation velocity in X, Y, Z and 12 is magnitude of them
 13-15 are angular deformation velocity in X, Y, Z and 16 is magnitude of them
 17-19 are translational deformation acceleration in X, Y, Z and 20 is magnitude of
them
 21-23 are angular deformation acceleration in X, Y, Z and 24 is magnitude of them
i The marker whose origin is being measured.
j The marker whose origin is the reference point for the deformation
displacement/velocity/acceleration calculation. Set j = 0 if you want the result to be
calculated along with rigid body marker at i marker.
k The marker that is referenced to calculate the deformation
displacement/velocity/acceleration vector. Set k = 0 if you want the results to be calculated
along rigid body marker at the j marker.
Notes:  i and j marker must be on the same flexible body.

 DEFORM does not include the rigid body motion of the flexible body.
 By definition, local deformation of a linear flexible body is infinitesimal, in other
words, small displacements and small rotations that commute. This means that a
component of motion is independent of and completely orthogonal to the other
two components.
46 Adams Solver
C++ Functions
DELAY
The DELAY function returns the value of an expression at a delayed time.
The DELAY function is useful to define Delay Differential Equations (DDE) or Delay Differential-Algebraic
Equations (DDAE) of the retarded type (when delays are positive). Neither DDE nor DDAE of the advance
type (negative delays) are supported.
The DELAY function can be used in MOTION and GCON definitions (possibly involving neutral type of
DDE or DDAE).
During linearization the DELAY function is approximated by a first order polynomial equivalent to an order
1 Padé approximant.
The user does not require to specify a buffer size. Adams Solver (C++) will manage a variable-size buffer
automatically.
Format
DELAY (e_delayed, e_delay, e_history [, id])
Arguments
e_delayed Adams expression to be delayed. The expression may be time and/or state dependent.
The expression may be explicitly defined or it may be computed by the solver during
the simulation. See Limitations section below.
e_delay Adams expression defining the magnitude of the delay. The delay can be constant or
state dependent. The magnitude of the delay must be positive. Negative values will be
taken as zero.
e_history Initial history of the expression; the history must provide for the values of 'e_delayed'
for the values of time less than zero (t<0). The history must be a function of TIME or
a constant.
id The identifier of an array of type IC containing the order of interpolation, a jump
threshold, an angle threshold, and a refinement parameter.
The delayed expression can have jumps and derivative discontinuities. If the signal has jumps, a jump
threshold J (see Figure below) can be specified. The default jump threshold is 0.5. If the signal has corners,
an angle corner threshold A (see Figure below) can be specified. The default angle corner threshold is π/8.
The default interpolation order is 6. In cases in which the delayed expression changes abruptly, a lower
integration order may be required. If the interpolation order is equal to 1, the corner and jump detection are
disabled.
By default the refinement parameter R is 200. The value of R controls the separation T (see Figure below)
between points used by the interpolator. Only points such that
t − tl > τ / R
DELAY 47
C++ Functions
are stored in the history of the expression. In the above expression, t is the current time, tl is the last point in
the stored history, and τ is the current value of the delay. The bigger the value of R, the more integration
points are stored in the history of the delayed expression. The value τ /R can be seen as a lower bound for the
separation between points in the delayed expression history. For delays smaller than the current integration
step, R is ignored and all integration points are recorded.
Limitations
The DELAY function may be used in any force equation, constraint equation, variable equation, or a
differential equation. Given that Adams Solver (C++) requires to compute time derivatives of the delayed
expression, the delayed expression shall not be an acceleration expression. However, a workaround consists of
wrapping the delayed expression using the AO function. See Example 4 below.
Example 1
Here we solve a simple DDE system. The equations below define a typical DDE system with a state-
dependent delay expression:
The expression to delay (e_delayed) is x2, the delay expression (e_delay) is τ, and the history (e_history) is
the constant expression 0.95.
This system could be modeled in Adams as follows:
DIF/1, FU=5*DELAY(DIF(2), DIF(1)-3*DIF(2), 0.95))
DIF/2, FU=3*DIF(1)*DELAY(DIF(2), DIF(1)-3*DIF(2), 0.95)
or
VARIABLE/1, FU=DELAY(DIF(2), DIF(1)-3*DIF(2), 0.95)
DIF/1, FU=5*VARVAL(1)
DIF/2, FU=3*DIF(1)*VARVAL(1)
48 Adams Solver
C++ Functions
Example 2
A simple mass-spring-damper system.
Figure below shows a MATLAB model to study the dynamics of a simple mass-spring-damper system
governed by the following equation:
mx·· + kx ( t – τ ) + cx· = 0
where the delay τ is given by the following expression:
τ = 0.01 + 0.05 x· < 0.035
and zero initial history ( x(t)=0 for t<0 ) and x· ( 0 ) = 1 . System properties are m=1, k=30 and c=2.
The corresponding Adams model is the following:

Simple spring-damper system
! Varying delay equal to 0.01+abs(vz(3))*0.05 < 0.035
! M=1, K=30, C=2
!
units/system=mks
!
part/1, ground
marker/1
marker/2, floating
!
part/2, mass=1, ip=1,1,1, cm=3, vz=1
DELAY 49
C++ Functions
marker/3
!
var/2, fun=0.01+abs(vz(3))*0.05
var/3, fun=if(varval(2)-0.035:varval(2),varval(2),0.035)
var/1, fun=-30*delay(dz(3),varval(3), 0)-2*vz(3)
!
joint/1, trans, i=1, j=3
!
vforce/1, i=3, j=2, rm=1, fx=0\ fy=0\ fz=varval(1)
!
results/formatted, xrf
end
A discontinuous signal.
This example sets the delay to 1, the initial history to 0 and the optional array id is 77.
var/1, fun=delay(dz(3),1, 0, 77)
!
Array/77, type=ic, size=4, numbers=
,6 ! Order of interpolator
,0.3 ! Jump threshold
,0.3 ! Angle corner threshold (rads)
,40 ! Refinement parameter R
!
Example 3
This example illustrates the potential problem of not having smooth data fed into the history of the DELAY
object. This example consists of a model that has no dynamic states; it simply defines a set of variables as
follows:
Example of DELAY function
!
! adams_view_name='ground'
PART/1
, GROUND
!
! adams_view_name='reference_harmonic'
VARIABLE/1
, FUNCTION = sin(25*time)
!
! adams_view_name='delay_test'
VARIABLE/2
, FUNCTION = delay(varval(1), 0.5*time+0.01, 0)
!
! adams_view_name='feedback'
VARIABLE/3
, FUNCTION = step(time,0,0,0.05,sin(time*25))+delay(varval(3),2*PI/25,0)
!
RESULTS/XRF
!
END
We run this model for 2.0 seconds using 200 output steps and 20 output steps respectively:
sim/kin, end=2, step=200

stop
50 Adams Solver
C++ Functions
and

stop
The results are presented in the figure below.
Notice the poor solution for the case of only 20 steps. The reason is that the integrator took large steps feeding
a history with data that can not be properly interpreted by the interpolation algorithm used by the DELAY
object.
In order to remedy this behavior, one option is to specify the HMAX option of the kinematic command as
follows:
kinematics/hmax=0.01
stop
The new solution is presented in figure below.

DELAY 51
C++ Functions
Example 4
τ
This example shows the case of a function of time X(t) that depends on an acceleration. The delay value is
and the delay X(t- τ ) may be defined as follows. Assuming X(t) is defined in VARIABLE/2 and the delay τ
is defined by VARIABLE/3 we have:
VARIABLE/2, FUNCTION=SIN(TIME)*ACCX(8) ! Function X(t)
VARIABLE/3, FUNCTION=0.5 ! The delay τ
Then the delayed expression (VARIABLE/4) is:
VARIABLE/4, FUNCTION=DELAY(AO(VARVAL(2)), VARVAL(3), 0)
Here we assumed the initial history is zero. Notice we use the AO function to wrap the expression to be
delayed.
Caution: The DELAY function uses an internal buffer, that holds the history of the expression 'e-
delayed'. This history is fed by the integrator. The number of steps or the HMAX option in
the INTEGRATOR provide smooth data as shown in Example 3 above.
52 Adams Solver
C++ Functions

DIF 53
C++ Functions
DIF
The DIF function returns the value of the state associated with DIFF/id.
Format
DIF(id)
Arguments
id An integer variable that specifies the identifier of a DIFF statement.
Examples
SFORCE/1, I=21, J=11, ROTATION
, FUNCTION= -20*(AZ(21,11)-10)**1.5
, -5*WZ(21,11,11)
DIFF/1, IC=0, FUNCTION=SFORCE(1,0,8,11)*WZ(21,11)
This SFORCE statement specifies a nonlinear rotational spring acting between Markers 21 and 11. The
spring torque acts about the z axis of Marker 11. DIFF/1 specifies the instantaneous power used by
SPRING/1.
The expression DIF(1) returns the integral of the instantaneous power (that is, the total work done by
SPRING/1). DIF1(1) returns the instantaneous power in SPRING/1.
54 Adams Solver
C++ Functions
DIF1
The DIF1 function returns the value of the time derivative of the state variable associated with DIFF/id. In
instances where DIFF/id is used to define an implicit algebraic equation, DIF1 returns an approximation of
the time derivative obtained by numerical differencing.
Format
DIF1(id)
Arguments
Examples
, FUNCTION= -20*(AZ(21,11)-10)**1.5
, -5*WZ(21,11,11)
SPRING/1.
DIM 55
C++ Functions
DIM
The DIM function calculates the positive difference of the instantaneous values of two expressions a1 and a2.
DIM(a1,a2) = 0 if a1 < a2
DIM(a1,a2) =a1-a2 if a1 > a2
Caution: DIM is a discontinuous function and must be used with caution.
Format
DIM(a1,a2)
Arguments

Example
The following function returns 0 as long as TIME < 5, and TIME - 5 for TIME > 5. TIME is the current
simulation time.
DIM(TIME,5)
56 Adams Solver
C++ Functions
DM
The DM function returns the magnitude of the translational displacement vector from marker j to marker i.
Marker j defaults to the global coordinate system if it is not specified. DM is the distance between markers i
and j and, by definition, is always non-negative.
Format
DM(i[,j])
Arguments

j The marker whose origin is the reference point for the displacement calculation.
Extended Definition
Mathematically, DM is calculated as follows:
DM = [ Ri – Rj ] • [ Ri – Rj ]
where R i is the displacement of marker i in the global coordinate system and R j is the displacement of
marker j in the global coordinate system.
Examples
, FUNCTION=-30*(DM(21,11)-25)**1.72
This SFORCE statement defines a nonlinear spring whose free length is 25. The stiffness is 30 force units per
unit deformation. DM(21,11)-25 represent the deformation in the spring. 1.72 is the exponent to which the
deformation is raised.
DTOR 57
C++ Functions
DTOR
The DTOR variable returns degrees to radians conversion factor (PI/180).
Format
DTOR
Examples
VARIABLE/1, FUNCTION=30*DTOR*TIME
This VARIABLE statement specifies a user-defined, algebraically-determined state variable whose value is 30
degrees*time. The state variable is stored in radians.
58 Adams Solver
C++ Functions
DX
The DX function returns the x-component of the translational displacement vector from marker j to marker
i as expressed in the marker k coordinate system. Marker j defaults to the global coordinate system if it is not
specified. Similarly, marker k defaults to ground if it is not specified.
Format
DX(i[,j][,k])
Arguments

j The marker whose origin is the reference point for the displacement calculation. Set j=0 if you want
j to default to the global coordinate system while still specifying l.
k The marker that is referenced to calculate the x-component of the displacement vector. Set k = 0 if
you want the results to be calculated along the x-axis of the global coordinate system.
Extended Definition
Mathematically, DX is calculated as follows:
DX = [ R i – R j ] ⋅ xˆ k
where:
 R i is the displacement of marker i in the global coordinate system.
 R j is the displacement of marker j in the global coordinate system.

 xˆ k is the unit vector along the x-axis of marker k.
Examples
VARIABLE/1, FUNCTION=DX(21,11,32)**2
This VARIABLE statement specifies a user-defined, algebraically-determined state variable. Its value is the
square of the x-displacement of Marker 21 with respect to Marker 11 as computed in the coordinate system
of Marker 32.
DXYZ 59
C++ Functions
DXYZ
The DXYZ measure returns the translational displacement vector from marker j to marker i as expressed in
the coordinate system of marker k.
Format
DXYZ(i[,j][,k])
Arguments

j to default to the global coordinate system while still specifying k.
k The marker in whose coordinate system the displacement vector is being expressed. If not specified,
k defaults to the global coordinate system.
Extended Definition
ˆ
 [ Ri – Rj ] ⋅ xk   DX 
   
DXYZ =  [ R i – R j ] ⋅ yˆ k  =  DY 
   
 [ R i – R j ] ⋅ zˆ k   DZ 
where:

 DX is theDX measure.
 DY is the DY measure.
 DZ is the DZ measure.
 yˆ k is the unit vector along the y-axis of marker k.
 zˆ k is the unit vector along the z-axis of marker k.
Examples
The following statement:
60 Adams Solver
C++ Functions
VARIABLE/1, FUNCTION=MAG(DXYZ(21,11,32))
is equivalent to:
VARIABLE/1, FUNCTION=DM(21,11)
and because a magnitude is taken, the use of the coordinate system of marker 32 as an alternative to the
ground coordinate system is redundant (and wasteful).
DY 61
C++ Functions
DY
The DY function returns the y-component of the translational displacement vector from marker j to marker
specified. Similarly, marker k defaults to the global coordinate system if it is not specified.
Format
DY(i[,j][,k])
Arguments

k The coordinates of the marker that are referenced to calculate coordinates the y-component of the
displacement vector is being calculated. Set k = 0 if you want the results to be calculated along the
y-axis of the global coordinate system.
Extended Definition
Mathematically, DY is calculated as follows:
DY = [ R i – R j ] ⋅ yˆ k
where:

Examples
VARIABLE/1, FUNCTION=DY(21,11,32)**2
square of the y-displacement of Marker 21 with respect to Marker 11 as computed in the coordinate system
of Marker 32.
62 Adams Solver
C++ Functions
DZ
The DZ function returns the z-component of the translational displacement vector from marker j to marker
specified. Similarly marker k defaults to the global coordinate system if it is not specified.
Format
DZ(i[,j][,k])
Arguments

k The marker in whose coordinates the z-component of the displacement vector is being calculated.
Set k = 0 if you want the results to be calculated along the z-axis of the global coordinate system.
Extended Definition
Mathematically, DZ is calculated as follows:
DZ = [ R i – R j ] ⋅ zˆ k
where:

Examples
VARIABLE/1, FUNCTION=DZ(21,11,32)**2
square of the z-displacement of Marker 21 with respect to Marker 11 as computed in the coordinate system
of Marker 32.
EXP 63
C++ Functions
EXP
The EXP function computes the value ea, where a is any expression.
Format
EXP(a)
Arguments
Examples
REQUEST/10, F2=EXP(WDTX(21,11,11,31))
In its second column, REQUEST/10 stores the value:
eWDTX(21,11,11,31)
where WDTX (21,11,11,31) is the x-component of the accelerations of Marker 21 with respect to Marker
11 as expressed in the coordinate system of Marker 11. The time derivative is taken in the reference frame of
Marker 31.
64 Adams Solver
C++ Functions
FIELD
The FIELD function returns component comp of a force due to FIELD/id as calculated in the coordinate
system of marker rm. If jflag is set to zero, the value that is returned is the force/torque acting on the I marker
of the FIELD. If jflag is set to 1, the value that is returned is the value acting on the J marker. For results that
are in the global coordinate system, you can specify rm as zero.
Format
FIELD (id, jflag, comp, rm)
Arguments
id An integer specifying the identification number of the FIELD.

jflag An integer flag specifying the FIELD connectivity marker at which the forces and torques are
computed.

comp An integer value that specifies the component of the FIELD force to be returned.

Examples
REQUEST/1
, F2=FIELD(1001,0,2,0)/
, F3=FIELD(1001,0,3,0)/
, F4=FIELD(1001,0,4,0)
This REQUEST statement stores the x-, y-, and z-component of the forces in FIELD/1001 in columns 2, 3,
and 4, respectively. Adams Solver (C++) calculates the forces at the I marker, and computes results in the
global coordinate system.
FM 65
C++ Functions
FM
The FM measure returns the magnitude of the net translational force acting on marker i. All force and
constraint elements acting between markers i and j are included in the calculation of the force. If j is not
specified, FM measures the sum of all force and constraint elements acting on marker i.
Format
FM(i[,j])
Arguments
i An integer that specifies the identifier of the marker at which the magnitude of the net force is to
be calculated.
j A second integer that specifies a marker identifier. All forces acting between the [i,j] pair are to be
included in the calculation. Set j = 0 or do not specify if you are interested in all forces acting on
marker i.
Examples
VARIABLE/1, FUNCTION=FM(23)
A user-defined state variable is specified by this VARIABLE statement. Its value is the magnitude of the sum
of all action-only forces acting at Marker 23.
VARIABLE/1, FUNCTION=FM(23,11)
of all the applied and constraint forces at Marker 23 and acting between Markers 23 and 11.
See other Generic force measures available.
66 Adams Solver
C++ Functions
FORCOS
The FORCOS function evaluates a Fourier Cosine series at a user-specified value x. The x0, a0, a1,...,a30 are
parameters used to define the constants for the Fourier Cosine series.
Format
FORCOS (x, x0, w, a0, a1,...,a30)
Arguments
x A real variable that specifies the independent variable. For example, if the independent
x0 A real variable that specifies a shift in the Fourier Cosine series.
w A real variable that specifies the fundamental frequency of the series. Adams Solver (C++)
assumes w is in radians per unit of the independent variable unless you use a D after the value.
a0 A real variable that defines the constant bias term for the function.
a1,...,a30 The real variables that define as many as thirty-one coefficients for the Fourier Cosine series.
Extended Definition
The Fourier Cosine series is defined:
n
F ( x ) = ao +  aj × Tj ( x – xo )
j=1
where the function T j are defined as:
T j ( x – x o ) = cos { j ⋅ ω ⋅ ( x – x o ) }
The index j has a range from 1 to n, where n is the number of terms in the series.
Examples
, FUNCTION=FORCOS(TIME, 0, 360D, 1, 2, 3, 4)
This MOTION statement defines a harmonic motion as a function of time. The motion has no shift, has a
fundamental frequency of 1 cycle (360D) per time unit, has a constant value of 1.0. The function defined is:
FORCOS = 1+2*COS(1*360D*TIME)
+3*COS(2*360D*TIME)
+4*COS(3*360D*TIME)
The curve is shown next.
Curve of a Harmonic Motion Defined by FORCOS
FORCOS 67
C++ Functions

68 Adams Solver
C++ Functions
FORSIN
The FORSIN function evaluates a Fourier Sine series at a user specified value x. x0,a0,a1,...,a30 are parameters
used to define the constants for the Fourier Sine series.
Format
FORSIN (x, x0,w,a0,a1,...,a30)
Arguments
x0 A real variable that specifies a shift in the Fourier Sine series.
w A real variable that specifies the fundamental frequency of the series. Adams Solver (C++)
assumes ω is in radians per unit of the independent variable unless you use a D after the
value.
a1,...,a30 The real variables that define as many as thirty-one coefficients for the Fourier Sine series.
Extended Definition
The Fourier Sine series is defined:
n
F ( x ) = ao +  aj × Tj ( x – xo )
j=1
T j ( x – x o ) = sin { j ⋅ ω ⋅ ( x – x o ) }
Examples
, FUNCTION=FORSIN(TIME,-0.25, PI, 0, 1, 2, 3)
This MOTION statement defines a harmonic motion as a function of time. The motion has a -0.25 second
shift, a fundamental frequency of 0.5 cycle ( π radians or 180 degrees) per time unit, and no constant value.
The function defined is:
FORSIN = 0+SIN( *(TIME+0.25))
+2*SIN(2 π *(TIME+0.25))
+3*SIN(3 π *(TIME+0.25))
FORSIN 69
C++ Functions

Curve of a Harmonic Motioned Defined by FORSIN

70 Adams Solver
C++ Functions
FRICTION
The FRICTION function returns force and other friction data from the FRICTION statement. You can use
this function in only REQUEST and SENSOR function expressions.
Format
FRICTION (id, index)
Arguments
id An integer variable specifying the identification of a FRICTION statement from which

output data is requested.
INDEX An integer variable specifying the output component index to be returned. See the table
below for a list of component indices.
Friction Index
Index: Name: Description:

1 FFX Friction force along the x-axis of the JOINT’s J marker
2 FFY Friction force along the y-axis of the JOINT’s J marker
3 FFZ Friction force along the z-axis of the JOINT’s J marker
4 FTX Friction torque about the x-axis of the JOINT’s J marker
5 FTY Friction torque about the y-axis of the JOINT’s J marker
6 FTZ Friction torque about the z-axis of the JOINT’s J marker
7 μx Friction coefficient along the x-axis of the JOINT’s J marker
8 μy Friction coefficient along the y-axis of the JOINT’s J marker
9 μz Friction coefficient along the z-axis of the JOINT’s J marker
10 μ rx Friction coefficient about the x-axis of the JOINT’s J marker
11 μ ry Friction coefficient about the y-axis of the JOINT’s J marker
12 μ rz Friction coefficient about the z-axis of the JOINT’s J marker
13 μ1 Effective friction coefficient at static friction (returns zero if sliding)
14 Vx Joint velocity at sliding surfaces along the x-axis of the JOINT’s J marker
15 Vy Joint velocity at sliding surfaces along the y-axis of the JOINT’s J marker
16 Vz Joint velocity at sliding surfaces along z-axis of the JOINT’s J marker
17 Wx Joint angular velocity about the x-axis of the JOINT’s J marker
18 Wy Joint angular velocity about the y-axis of the JOINT’s J marker
19 Wz Joint angular velocity about the z-axis of the JOINT’s J marker
FRICTION 71
C++ Functions
20 CREEP_X Static friction creep along the x-axis of the JOINT’s J marker
21 CREEP_Y Static friction creep along the y-axis of the JOINT’s J marker
22 CREEP_Z Static friction creep along the z-axis of the JOINT’s J marker
23 CREEP_RX Static friction creep about the x-axis of the JOINT’s J marker
24 CREEP_RY Static friction creep about the y-axis of the JOINT’s J marker
25 CREEP_RZ Static friction creep about the z-axis of the JOINT’s J marker
26 BETA Stiction transition factor
Examples
Request/101
,F2=FRICTION (2,1)/, F3=FRICTION (2,2)/, F4=FRICTION (2,3)/

This REQUEST statement defines a user REQUEST that returns the friction forces associated with the
statement FRICTION/2. The second component of the user request contains the X component of the
friction-force vector resolved in the associated J marker coordinate system of the JOINT.
Caution: The FRICTION function is accessible only through the REQUEST and SENSOR function
expressions.
The FRICTION function evaluates to zero if the index corresponds to a force or velocity
which is not used by the corresponding friction model. For example, if FRICTION/2 from
above is applied on a translational joint, then FRICTION (2,1) would be zero because the
friction force is applied along the z axes of the joint.

72 Adams Solver
C++ Functions
FX
The FX measure returns the x-component of the net translational force acting on marker i, represented in the
coordinate system of marker k. All force and constraint elements acting between markers i and j are included
in the calculation of the force. If j is not specified, FX measures the sum of all force and constraint elements
acting on marker i. If k not specified or if k=0, the force is represented in the GROUND coordinate system.
To specify k without specifying j, use j=0.
Format
FX(i[,j][,k])
Arguments
i An integer that specifies the identifier of the marker at which the magnitude of the net force is to be
calculated.
marker i.
k An integer that specifies the identifier of a marker (coordinate system) in which the x-component of
the force is to be returned. k defaults to the global coordinate system when it is not specified.
Examples
VARIABLE/1, FUNCTION=FX(23,0,432)
A user-defined state variable is specified by this VARIABLE statement. Its value is FX(23,0,432). This is the
x-component of the sum of all the action-only forces acting at Marker 23 as computed in the coordinate
system of Marker 32.
FXFREQ 73
C++ Functions
FXFREQ
The FXFREQ function returns the modal frequency in cycles per user-defined time for the current mode of
the current FLEX_BODY when used in function expressions defining the CRATIO argument of a
FLEX_BODY. FXFREQ returns zero when used in other expressions. Learn more about FLEX_BODY.
Format
FXFREQ
Extended Definition
Adams Solver (C++) evaluates the function expression used to define CRATIO of a FLEX_BODY separately
for each active mode of the FLEX_BODY (each mode has a CRATIO value). FXFREQ returns the modal
frequency of the mode for which CRATIO is being evaluated.
Examples
FLEX_BODY/1,
, CRATIO = IF(FXFREQ-100:0.01,0.1,IF(FXFREQ-1000:0.1,1.0,1.0))
For a model using units of seconds for time, this example recreates the default modal damping scheme using
nested IF function expressions.
See other Flexible body constants available.
74 Adams Solver
C++ Functions
FXMODE
The FXMODE function returns the mode number of the current mode of the current FLEX_BODY when
used in function expressions defining the CRATIO argument of a FLEX_BODY. FXMODE returns zero
when used in other expressions. Learn more about FLEX_BODY.
Format
FXMODE
Extended Definition
Adams Solver (C++) evaluates the function expression used to define CRATIO of a FLEX_BODY separately
for each active mode of the FLEX_BODY (each mode has a CRATIO value). FXMODE returns the mode
number of the mode for which CRATIO is being evaluated.
The FXMODE function returns the mode number as found in the corresponding *.mtx file. For example, if
the *.mtx file has this data:
SELMOD FULL RORDER 4 2 8 ( 1I8, 1E14.6 )
2 1.591549E+00
3 2.756644E+00
7 3.856574E+00
8 2.561644E+01
then FXMODE will return the values 2, 3, 7 and 8. It does not return 1, 2, 3 nor 4.
Examples
FLEX_BODY/1
, CRATIO = STEP(TIME, 0.1, 1.0, 1.2, STEP(FXMODE, 5.0, 0.02, 10, 0.2))
This example specifies modal damping that varies both with time and mode number, such that all modes have
100% critical damping until time = 0.1, after which:
 Modal damping decreases smoothly to between 2% and 20% of modal damping at time = 1.2.
 Mode numbers 1 through 5 reach 2% modal damping.
 Mode numbers 6 through 9 reach modal damping values smoothly distributed between 2% and
20%.
 Mode numbers 10 and up reach 20% modal damping.
FXYZ 75
C++ Functions
FXYZ
The FXYZ measure returns the net translational force vector acting on marker i, represented in the coordinate
system of marker k. All force and constraint elements acting between markers i and j are included in the
calculation of the force. If j is not specified, FXYZ measures the sum of all force and constraint elements
acting on marker i. If k is not specified or if k=0, the force is represented in the GROUND coordinate system.
To specify k without specifying j, use j=0.
Format
FXYZ(i[,j][,k])
Arguments
calculated.
marker i.
Extended Definition
Mathematically, FXYZ is calculated as:
 FX 
 
FXYZ ( i ,j ,k ) =  FY 
 
 FZ 
where:
 FX is the FX measure.
 FY is the FY measure.
 FZ is the FZ measure.
Examples
Magnitude of torque at marker 5 due to all forces applied at marker 4.
VARIABLE/1, FUN=MAG(DXYZ(4,5)%FXYZ(4))

76 Adams Solver
C++ Functions
FY
The FY measure returns the y-component of the net translational force acting on marker i, represented in the
in the calculation of the force. If j is not specified, FY measures the sum of all force and constraint elements
acting on marker i. If k not specified or if k=0 the force is represented in the GROUND coordinate system.
To specify k without specifying j use j=0.
Format
FY(i[,j][,k])
Arguments
calculated.
marker i.
k An integer that specifies the identifier of a marker (coordinate system) in which the y-component of
Examples
SFORCE/1, I=132, J=234, TRANSLATION, ACTIONONLY
, FUNCTION=-0.3*FY(677,866)
This SFORCE statement defines a translation, action-only force acting at Marker 132. The force is directed
along the z-axis of Marker 234. The value of the force is -0.3 times the y-component of the net force along
the global y-axis, acting at Marker 677. All forces acting between Markers 677 and 866 are included in this
calculation.
FZ 77
C++ Functions
FZ
The FZ measure returns the z-component of the net translational force acting on marker i, represented in the
in the calculation of the force. If j is not specified, FZ measures the sum of all force and constraint elements
acting on marker i. If k not specified or if k=0 the force is represented in the GROUND coordinate system.
To specify k without specifying j use j=0.
Format
FZ(i[,j][,k])
Arguments
calculated.
marker i.
k An integer that specifies the identifier of a marker (coordinate system) in which the z-component of
Examples
, FUNCTION=STEP5(FZ(34), -1.5, -200, 1.5, 200)
This SFORCE statement defines a translational, action-only, nonlinear force. The force is directed along the
z-axis of Marker 11. The value of the force is a 5th order step function (see STEP5). The independent variable
for the STEP5 function is FZ(34), the net force acting along the global z-axis at Marker 34. Since no j marker
is specified, only action-only forces acting at Marker 34 are included in the calculation of FZ().
78 Adams Solver
C++ Functions
GFORCE
The GFORCE function returns the component comp of the force in GFORCE/id in the coordinate system
of marker rm. If jflag is set to zero, Adams Solver (C++) returns the value of the force/torque that acts on the
I marker of GFORCE/id. If jflag is set to 1, Adams Solver (C++) returns the value that acts on the J marker.
To obtain results in the global coordinate system, you can specify rm as zero.
Format
GFORCE (id, jflag, comp, rm)
Arguments
id An integer specifying the identification number of the GFORCE.

jflag An integer flag specifying the GFORCE connectivity marker at which the forces and torques
are computed.

comp An integer value that specifies the component of the GFORCE to be returned.

Examples
GFORCE/1, I=516, J=34, RM=23
, FX=-0.3*GFORCE(1,0,4,23)/
, FY=0/
, FZ=IMPACT(DZ(516,0,23),VZ(516,0,23,23),4.6,1e5,1.5,10,0.01)
This GFORCE statement defines a force acting at Marker 516. The components of the force are defined
along the x-, y-, z-axes of Marker 23.
The x-component of the force is -0.3 times the z-component of the force.
The z-component of the force is defined as an impact force (see IMPACT ) that is a function of the displacement
and velocity of Marker 516, as seen by Marker 23.
HAVSIN 79
C++ Functions
HAVSIN
The HAVSIN function defines a haversine function. It is used most often to represent a smooth transition
between two functions.
Format
HAVSIN (x, x0, h0, x1, h1)
Arguments
x The independent variable.

x0 A real variable that specifies the x value at which the haversine function begins.
x1 A real variable that specifies the x value at which the haversine function ends.
h0 The initial value of the haversine function.
h1 The final value of the haversine function.
Extended Definition
The HAVSIN function is used most often to represent a smooth transition between two functions (see the
figure below). As an example, a HAVSIN may be used to smoothly ramp up the motion in a joint from h0
to some constant value h1.
Haversine Function
The equation defining HAVSIN is:

a = (h0 + h1)/2
b = (h1 - h0)/2
c = (x - x0)/(x1 - x0)
80 Adams Solver
C++ Functions
 h0 : ( x ≤ x0 ) 
 
HAVSIN =  a + b ⋅ sin ( c ⋅ π – π ⁄ 2 ) : xo < x < x1 
 
 h1 :x ≥ x 1 
Tip: The HAVSIN function behavior is similar to the STEP function. It has a discontinuous
second derivative and, therefore, is not recommended for use in displacement level motions.
Examples
MOTION/1, JOINT=21, VELOCITY
, FUNCTION=HAVSIN(TIME, 1, 0, 2, 1)
This MOTION statement defines a smooth transition in velocity from time 1 to time 2. Note that the
motion is specified in velocity rather than displacement.
HSIZE 81
C++ Functions
HSIZE
The instantaneous simulation step size being used for any simulation that advances time (for example,
dynamic, kinematic and quasistatic analyses).
Example
SENSOR/1
, VALUE=1e-4
, ERR=1e-5
, LE
, HALT
, FUN=HSIZE+1*STEP(TIME,0.799,1,0.8,0)
In above example, the sensor halts the simulation if the step size is smaller than 1e-4. Note that a STEP
function is used to delay the sensor to avoid the start-up condition of a step size-0.0, and to accommodate
HMIN and allow the integrator to start.
82 Adams Solver
C++ Functions
IF
The arithmetic IF function allows you to conditionally define a function expression.
IF (expression 1: expression 2, expression 3, expression 4)
Adams Solver (C++) evaluates expression 1.
 If the value of expression 1 is less than zero, the arithmetic IF is evaluated using expression 2.
 If the value of expression 1 is zero, the arithmetic IF is evaluated using expression 3.
 If the value of expression 1 is greater than zero, the arithmetic IF is evaluated using expression 4.
Format
IF (test : lt, eq, gt)
Arguments
test Any valid function expression. Adams Solver (C++) evaluated the test expression to determine
which branch of the arithmetic IF, lt, eq, or gt will be selected.
lt Any valid function expression. If the value of the test expression is less than zero, Adams Solver
(C++) evaluates the lt expression and the IF function takes the value of lt. Otherwise, the lt
expression is not evaluated.
eq Any valid function expression. If the value of the test expression is equal to zero, Adams Solver
(C++) evaluates the eq expression and the IF function takes the value of eq. Otherwise, the eq
gt Any valid function expression. If the value of the test expression is equal to zero, Adams Solver
(C++) evaluates the gt expression and the IF function takes the value of gt. Otherwise, the gt
Caution: When using an arithmetic IF function, ensure that the resulting function is continuous. If the
function is discontinuous, Adams Solver (C++) may fail to find a solution when it encounters
the discontinuity. Even the greater reliability can be achieved if continuity of the first derivative
can be ensured.
Much greater care is required when using an arithmetic IF function to define a MOTION or
GCON element. In this case, a continuous second derivative is also required. The use of
arithmetic IF functions to define MOTION and GCON elements is best avoided.
Examples
SFORCE/1, I=20, J=31,
, FUNCTION=-6*IF(VR(10,31): 0, 0, VR(10,31)**3)
IF 83
C++ Functions
This function is interpreted as follows:

 If the radial velocity (see VR) between Markers 20 and 31 is less than or equal to zero, the value of
SFORCE/1 is zero.
 If the radial velocity between Markers 10 and 31 is greater than zero, the value of SFORCE/1 is -
6*VR(10,31)**3.
84 Adams Solver
C++ Functions
IMPACT
The IMPACT function models collisions.
Format
IMPACT (x, x· , x1, k, e, cmax, d)
Arguments
x Expression that specifies a distance variable that is used to compute the IMPACT function. For
example, if you use the x displacement of Marker 0201 with respect to Marker 0301, then x is
DX(0201,0301,0301).
x· Expression that specifies the time derivative of x to IMPACT. For example, if x is
DX(0201,0301), then x· is VX(0201,0301,0,0301).
x1 Positive real variable that specifies the free length of x. If x is less than x1, then Adams Solver
(C++) calculates a positive value for the force. Otherwise, the force value is zero. You can define
x1as a real number, function, or variable.
k Non-negative real variable that specifies the stiffness of the boundary surface interaction.
e Positive real variable that specifies the exponent of the force deformation characteristic. For a
cmax Non-negative real variable that specifies the maximum damping coefficient.
d Positive real variable that specifies the boundary penetration at which Adams Solver (C++)
applies full damping.
Extended Definition
The IMPACT function activates when the distance between the I and J markers falls below a nominal free
length (x1), that is, when two parts collide. As long as the distance between the I and J markers is greater than
x1; the force is zero. An example of a system you can model with the IMPACT function is a ball falling
towards the ground. Figure 3 below shows the free length value x1at which the IMPACT force turns on.
The force has two components, a spring or stiffness component, and a damping or viscous component. The
stiffness component is proportional to k, and is a function of the penetration of the I marker within the free-
length distance from the J marker. 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.
Figure 3 Example Illustrating the IMPACT Function

IMPACT 85
C++ Functions
The equation defining IMPACT is:
 Max ( 0, k ( x 1 – x ) – STEP ( x, x 1 – d, c max, x 1, 0 ) ⋅ x· )

e : x < x1 
IMPACT =  
0 : x ≥ x 1
Note that when:
 x > x1, no penetration occurs and the force is zero (penetration p = 0)
 x < x1, penetration occurs at the end closer to the J marker, and the force is > 0 (penetration p = x1 -
x)
Also note that when p < d, the instantaneous damping coefficient is a cubic step function of the penetration,
p.
When p > d, the instantaneous damping coefficient is cmax.
Adams Solver (C++) never returns a negative force for IMPACT. If the above expression is negative, Adams
Solver (C++) returns a value of zero.
Figure 4 below is a plot of damping coefficient versus penetration.

86 Adams Solver
C++ Functions
Tip: Define the exponent value as: e > 2.1 for the contact modeling fu. According to design studies,
models run better using this exponent value in the IMPACT function.
Caution:  For maximum performance, define e >1. When e is <1, the defined force contains a
slope discontinuity that may cause difficulty for the integrator.
 If your model uses different length units than the stiffness properties you would like
to use, you need to scale the stiffness by:
F n = k* (g**e)
Example:
k = 3800 N/mm
e = 2.0
Also note that only length is raised to the exponent, so if you have a different force
unit, you would only scale it by the force conversion factor.
IMPACT 87
C++ Functions
Examples
, FUNCTION=IMPACT(DZ(11,21,21),
, VZ(11,21,21,21),1.0, 100, 1.5, 25, 0.1)
This statement defines an impact force when a ball penetrates another object such as a table. The force is a
single-component force at Marker 11 and along the z-axis of Marker 21. DZ(11,21,21) defines the
instantaneous displacement of Marker 11 with respect to Marker 21 along the z-axis of Marker 21.
VZ(11,21,21,21) defines the instantaneous velocity.
The free length is 1; that is, the radius of the ball is 1 unit. The stiffness is 100, the exponent of deformation
is 1.5, and the maximum damping coefficient is 25. The penetration at which Adams Solver (C++) applies
full damping is 0.1.
VFORCE/1, I=27, JFLOAT=25, RM=26
, FX=0/
, FY=IMPACT(DY(4,1,1), VY(4,1,1), 1-AKISPL(DX(4,1,1),
, DZ(4,1,1),3),le7, 1.01, le4,.25)/
, FZ=0
This statement defines an impact force when a ball penetrates a surface defined by a spline. The force is a
translational force at Marker 27. The DY(4,1,1) defines the y-component of the instantaneous displacement
of Marker 4 with respect to Marker 1. The VY(4,1,1) defines the y-component of the instantaneous velocity.
The free length is defined using spline 3, which represents the surface.
The independent variables in the spline are defined using the x- and z-components of the instantaneous
displacement of Marker 4 with respect to Marker 1, DX(4,1,1) and DZ(4,1,1), respectively. The stiffness is
le7, the exponent of deformation is 1.01, the maximum damping coefficient is le4, and the penetration at
which Adams Solver (C++) applies full damping is 0.25.
88 Adams Solver
C++ Functions
INCANG
The INCANG function computes the included angle between the line defined by markers i and j, and the
line defined by markers j and k. The three markers can be on separate parts.
Note: During the simulation, the first non-zero value is always positive.
Format
INCANG (i, j, k)
Arguments
i A marker on the first line.

j A marker on the first line.
k A marker on the second line.
Examples
Variable/1, Fun=INCANG(3,2,4)*RTOD/
The variable computes the angle between the line segments that markers 2 and 3, and markers 2 and 4, define.
INTERP 89
C++ Functions
INTERP
The INTERP function returns the iord derivative of the interpolated value of SPLINE/id at time=x. The
INTERP function supports time-series splines, which are splines that include a FILE argument that specifies
a time history file of type DAC or RPC III.
Format
INTERP (x, degree, id [,iord])
Arguments
x A real variable that specifies the value of time, the independent variable along the x-axis of the
time series spline that is being interpolated.
degree An integer variable that specifies the degree of interpolation. For example, a value of 1 performs
linear interpolation, while 3 performs cubic interpolation of the spline data.
Range: degree > 1

Adams Solver dataset. The SPLINE id must reference time series data from a DAC or RPC III
file.
iord An integer variable specifying the order of the derivative that Adams Solver takes at the
interpolated point, and then returns through INTERP.
Default: 0 (take no derivative)

Range: 0 < iord < 2
Extended Definition
The INTERP function uses a B-Spline formulation to create a function across a set of data points. The data
points are defined in a SPLINE statement in the Adams Solver data deck. The SPLINE statement with the
FILE argument that you define in the Adams Solver dataset must reference a time series file of type DAC or
RPC III. For more information on these file types, see Adams Durability.
In general, the INTERP function with linear interpolation will not be a smooth function because, in almost
all cases, the function will be discontinuous in the first derivative. Therefore, the estimate of the first
derivative may be erroneous even though, by definition, the data points of a DAC or RPC time history file
are evenly spaced. In all cases, the second derivative of the function being approximated is unreliable with
linear interpolation.
On the other hand, with cubic interpolation, the INTERP function will be continuous to the second
derivative. Therefore, we recommend that you use cubic or a higher degree of interpolation, especially if first
or second derivatives of the function will be evaluated.
90 Adams Solver
C++ Functions
Note: You may increase the order of interpolation beyond that of a cubic fit by setting the degree
argument to an integer value greater than 3. However, you may see a performance penalty in
doing so as higher order fitting is more computationally expensive than lower order fitting.
Typical Adams simulations run satisfactorily with cubic or lower order of interpolation.
Examples
SPLINE/101
,FILE=test_data.rsp
,CHANNEL=9
,FUNCTION=INTERP(TIME,3,101)
The SFORCE statement defines a translational force that acts between Markers 409 and 109. The SPLINE
statement specifies that the discrete data used to interpolate the value of the SFORCE comes from
CHANNEL 9 of the RPC III file test_data.rsp.
The INTERP function references this spline, defines the independent variable to be simply, TIME, and
selects cubic as the degree of interpolation.
INVPSD 91
C++ Functions
INVPSD
The INVPSD (Inverse Power Spectral Density) function regenerates a time signal from a power spectral
density description.
Format
INVPSD (x, id, fo, fi, nf, linlog, seed)
Arguments

id The id number of the spline containing the PSD versus frequency data.
f0 A real variable that specifies the lowest frequency to be regenerated.
f1 A real variable that specifies the highest frequency to be regenerated.
nf An integer that specifies the number of frequencies. The number of frequencies is unlimited.
linlog An integer variable that acts as a flag indicating whether the PSD data points are interpolated in
the linear or logarithmic domain.
The legal values are:
 yes (0) - linear domain

 no (1) - logarithmic domain
seed A real variable that specifies a seed for a random number generator, used to calculate the phase
shifts. The seed is a real number that will be cast to an integer using the int() C++ operator.
Adams Solver C++ has no limits on the number of different integer seeds that can be used.
Extended Definition
Mathematically, INVPSD is calculated as follows:
nf
INVPSD =  ( Ai ⋅ sin ( 2πfi ⋅ x + ϕi ) )

i=1
The regenerated signal consists of a series of sinusoidal functions where the amplitudes, Ai, are determined
in such a way that the effective value for the PSD and the time signal are the same. The phase angle,
ϕ i ( 0 ≤ ϕ i ≤ 2π ) , is calculated by a pseudo-random number generator.
Using the same seed value will always result in the same set of phase angles.
92 Adams Solver
C++ Functions
Examples
For the power spectral density data shown in Figure 5, INVPSD(TIME, spline_1, 1, 10, 20, 0, 0) regenerates
the time signal shown in Figure 6.
Figure 5 PSD vs. Frequencey in Log-Log Scale
Figure 6 Regenerated Time Signal

JOINT 93
C++ Functions
JOINT
The JOINT function returns component comp of a force or torque due to JOINT/id as calculated in the
coordinate system of marker rm. If jflag is set to zero, the value returned is the force/torque acting on the I
marker of the JOINT. If jflag is set to one, the value returned is that acting on the J marker. rm may be
specified as zero if the results are desired in the global coordinate system.
Format
JOINT (id, jflag, comp, rm)
Arguments
id An integer specifying the identification number of the joint.

jflag An integer flag specifying the joint connectivity marker at which the forces and torques are
computed.
1 = forces and moments at the J marker
comp An integer value that specifies the component of the joint force to be returned.
Examples
, FUNCTION=-0.4*SIGN(1.0,WZ(46,23,23)*5.6*,
, (JOINT(1,0,1,23)-ABS(JOINT(1,0,4,23))))
This example illustrates how a simple dynamic friction force can be added to a revolute joint. JOINT/1 is the
revolute joint to which frictional effects are to be added. 0.4 is the coefficient of friction and 5.6 is the radius
of the sleeve defining the revolute joint. WZ(46,23,23) determines the direction of rotation and the negative
sign indicates that the frictional moment about the z-axis of Marker 23 opposes this motion.
JOINT(1,0,1,23) determines the magnitude of the reaction force at Marker 23. JOINT(1,0,4,23)
determines the component of the constraint force along the axis of the rotational of the joint.
JOINT(1,0,12)-ABS(JOINT(1,0,4,23)) defines the radial load in the revolute joint (i.e., the normal force).
94 Adams Solver
C++ Functions
JPRIM
The JPRIM function returns component comp of a force due to JPRIM/id as calculated in the coordinate
JPRIM. If jflag is set to one, the value returned is that acting on the J marker. rm may be specified as zero if
the results are desired in the global coordinate system.
Format
JPRIM (id, jflag, comp, rm)
Arguments
id An integer specifying the identification number of the JPRIM.

jflag An integer flag specifying the JPRIM connectivity marker at which the forces and torques are
computed.

comp An integer value that specifies the component of the JPRIM force to be returned.

Examples
REQUEST/1
, F2=JPRIM(212,1,8,346)
In its second column, this REQUEST statement stores the z component of the torque acting at the J marker
of JPRIM 212. The torque component is calculated in the coordinate system of Marker 346.
JPRIM 95
C++ Functions

96 Adams Solver
C++ Functions
LOG
The LOG function returns the natural logarithm an expression a. If ex=a then LOG(a)=x. The LOG function
is defined only for positive values of a (that is, a > 0). It is undefined for all other values.
Format
LOG(a)
Arguments
a Any valid function expression that returns a positive value during a simulation.
Examples
DIFF/1, IC=3.6
, FUNCTION=LOG(1+VM(21,31,31))
This DIFF statement defines a user specified differential equation. The initial condition for the associated
state is 3.6 and its derivative is the natural logarithm of the expression 1+VM(21,31,31).
LOG10 97
C++ Functions
LOG10
The LOG10 function returns log to base 10 of an expression a. If 10^x=a, then LOG10(a)= x. The LOG10
function is defined only for positive values of a (a>0). It is undefined for all other values.
Format
LOG10(a)
Arguments
Examples
DIFF/1, IC=3.6
, FUNCTION=LOG10(1+VM(21,31,31))
98 Adams Solver
C++ Functions
MAG
The MAG function returns the magnitude of an arbitrary vector function expression.
Format
MAG(exp)
Arguments
exp An arbitrary vector function expression.
Extended Definition
Mathematically, MAG is calculated as:
MAG ( exp ) = exp ⋅ exp
where exp is an arbitrary vector function expression.
Examples
VARIABLE/1, FUN=MAG(VXYZ(i,j))
VARIABLE/2, FUN=SQRT(VXYZ(i,j)*VXYZ(i,j))
VARIABLE/3, FUN=VM(i,j)
Variables 1, 2 and 3 are synonymous. They all compute the magnitude of the relative velocity of markers i
and j.
See other Vector functions available.
MAX 99
C++ Functions
MAX
The MAX function returns the maximum of two expressions a1 and a2.
MAX(a1,a2) = a1 if a1 > a2
MAX(a1,a2) = a2 if a2 > a1
Format
MAX(a1,a2)
Arguments

Caution: The MAX function is generally discontinuous. Use this function expression with care when
you are specifying force or motion input.
Examples
SFORCE/1, ROTATIONAL, ACTIONONLY, I=21, J=11
, FUNCTION=MAX(0,-3*(AZ(21,11)-25D))
This SFORCE statement defines an action-only torque that acts at Marker 21 and acts along the z-axis of
Marker 11. The torque is defined to always be non-negative through the use of the MAX function. Thus, the
torque can only act to decrease the AZ rotation of Marker 21 with respect to Marker 11 (see AZ).
100 Adams Solver
C++ Functions
MIN
The MIN function returns the minimum of two expressions a1 and a2.
MIN(a1,a2) = a1 if a1 < a2
MIN(a1,a2) = a2 if a2 < a1
Format
MIN(a1,a2)
Arguments

Caution: The MIN function is generally discontinuous. Use this function expression with care when
Examples
, FUNCTION=MIN(0,-3*(AZ(21,11)-25D))
Marker 11. The torque is defined to always be negative through the use of the MIN function. Thus, the
MOD 101
C++ Functions
MOD
The MOD function returns the remainder when a1 is divided by a2.
MOD(a1,a2) = a1 - int(a1/a2) * a2
Format
MOD(a1,a2)
Arguments

a2 Any valid non-zero function expression.
Caution: The MOD function is generally discontinuous. Use this function expression with care when
Examples
MOD(45,16)=13
102 Adams Solver
C++ Functions
MODE
The MODE function returns the current analysis mode. These are defined as:
1 = Kinematics
2 = Reserved
3 = Initial conditions
4 = Dynamics
5 = Statics
6 = Quasi-statics
7 = Linear analysis
Format
MODE
Caution: Use the MODE function with care if you use the STATICS argument on the SIMULATE
command to request a static or quasi-static simulation of a kinematic system, Adams Solver
(C++) performs a kinematic analysis and, consequently, returns a MODE analysis constant of
1 (not 5 or 6).
Examples
SFORCE/1, TRANSLATION, I=21, J=11
, FUNCTION=IF(MODE-4:0,0,-4*(DM(21,11)-10.6)
This example defines a translational force that is active only during statics, quasi-static, and linear analysis
modes. For these analysis modes, the SFORCE acts as a simple spring. For all other analyses, the net force
applied by the SFORCE is zero.
MOTION 103
C++ Functions
MOTION
The MOTION function returns component comp of a force due to MOTION/id as calculated in the
marker of the MOTION. If jflag is set to one, the value returned is that acting on the J marker. rm may be
Format
MOTION (id, jflag, comp, rm)
Arguments
id An integer specifying the identification number of the motion.

jflag An integer flag specifying the motion connectivity marker at which the forces and torques are
computed.

comp An integer value that specifies the component of the motion force to be returned.

Examples
MOTION/1, ROTATIONAL, JOINT=34, FUNCTION=TIME**2
DIFF/1, IC=0
, FUNCTION=WZ(21,11)*MOTION(1,0,8,11)
This DIFF statement defines a user defined state. Its derivative is the instantaneous power required to effect
the displacement specified by MOTION/1. Therefore, the value of the state is the total work done by
MOTION/1 during a simulation.
104 Adams Solver
C++ Functions
NJAC
The number of times the Jacobian matrix has been reevaluated. (See the PATTERN argument on the
INTEGRATOR statement and INTEGRATOR command for information about user control over Jacobian
evaluation.)
Example
! adams_view_name='FUNCTION_MEA_NJAC'
VARIABLE/1
, FUNCTION = NJAC
NRHS 105
C++ Functions
NRHS
The number of times that the equations of motion have been evaluated. You can use it as a counter for the
number of iterations needed during the Adams solution.
Example
!
! adams_view_name='FUNCTION_MEA_NRHS'
VARIABLE/3
, FUNCTION = NRHS
106 Adams Solver
C++ Functions
ORDER
The current order of a variable-order integrator.
Example
!
! adams_view_name='FUNCTION_MEA_ORDER'
VARIABLE/2
, FUNCTION = ORDER
ORIENT 107
C++ Functions
ORIENT
The ORIENT function returns a scalar rotational value related to two Markers. The rotational value is
defined by specifying an orientation system and a specific component. The ORIENT function may be used
to compute Euler angles corresponding to rotation sequences other than the standard body-fixed 3-1-3 Euler
rotation sequence used by Adams Solver (C++). The exact meaning of the computed value depends on the
parameters supplied by the user.
Format
ORIENT( orientation_system, component, i [,j] )
Arguments
orientation_system A value specifying the orientation system or convention. (See table below.)
component A value specifying the value to be computed. (See table below.)
i The first Marker.
j The second marker. When j is not specified, Adams Solver (C++) defaults to the
global coordinate system.
Orientation
system Component Computed value Comment
1 1, 2 or 3 First, second or third Euler angle of a body-fixed
1-2-3 Euler rotation sequence respectively.
108 Adams Solver
C++ Functions
Orientation
11 1, 2 or 3 First, second or third Euler angle of a body-fixed Standard Euler sequence used
3-1-3 Euler rotation sequence respectively. by Adams Solver (C++). First
angle is PSI, second angle is
THETA and third angle is
PHI.
13-24 Not supported by Adams
Solver (C++)
25 1, 2 or 3 AX(i, j), AY(i, j) or AZ(i, j) respectively.
26 1, 2 or 3 YAW(i, j), PITCH(i, j) or ROLL(i, j) respectively.
27 1, 2, 3, or 4 First, second, third or fourth Euler parameter
respectively.
28 Not supported by Adams
Solver (C++)
29 1, 2, 3, 4, 5, 6, Entry of the direction cosine matrix. The values
7, 8 or 9 are returned in row order, for example,
component 1 stands for entry a11, component 2
stands for entry a12, component 3 stands for entry
a13, component 4 stands for entry a2,1, and so
forth.
Caution: For large rotations (greater than 10 degrees) about the y-axis or z-axis on Marker j, the AX, AY
and AZ functions becomes increasingly non-physical. See documentation for AX, AY and AZ
functions.
ORIENT 109
C++ Functions
Examples
, FX=-20*ORIENT(3, 2, 43, 32)
The value of the force is -20 times an angle between Markers 43 and 32. The angle is the second angle in a
body-fixed Euler 3-1-2 rotation sequence.
110 Adams Solver
C++ Functions
PHI
The PHI function calculates the third angle (in radians) of a body-fixed-3-1-3 Euler rotation sequence
between markers i and j. Marker j defaults to the global coordinate system if it is not specified. See Figure 7
for a schematic description of the body-fixed-3-1-3 Euler rotation sequence.
Format
PHI(i[,j])
Arguments

Examples
REQUEST/1, F2=PHI(222,434)
This REQUEST statement outputs the phi angle between Markers 222 and 434 in its second column.
Figure 7 Body-fixed-3-1-3 Euler Angles

PHI 111
C++ Functions
The body-fixed-3-1-3 sequence is started by rotating

counterclockwise the initial system of axes, xyz, by an
angle Ψ about the z-axis. The resultant axes are
labeled ξηζ . (Notice that z coincides with ζ .)
In the second stage the intermediate axes, ξηζ , are

rotated counterclockwise about the ξ -axis by an angle
θ . The new resultant planes are labelled ξ'η'ζ' . The
ξ' - axis is at the intersection of the xy and ξ'η' planes
and is known as the line of nodes. (Notice that ξ
coincides with ξ' .)
In the final rotation, the – ξ' – η' – ζ' axes are rotated
counterclockwise by an angle φ about the ζ -axis to
produce the x' y' z' axes, which is the desired final
direction. (Notice that ζ' coincides with z'.)
112 Adams Solver
C++ Functions
PI
PI returns the ratio of the circumference of a circle to its diameter (3.14159...).
Format
PI
PINVAL 113
C++ Functions
PINVAL
The PINVAL function returns component comp of PINPUT/id.
Format
PINVAL (id, comp)
Arguments
id The identifier of the PINPUT whose data is being requested.

comp An integer that specifies the component of the PINPUT to be returned.
Examples
VARIABLE/21, FUNCTION=10*SIN(2.4*TIME)+3.5
VARIABLE/22, FUNCTION=DZ(21,11,32)
PINPUT/10, VARIABLES=21,22
SFORCE/1, TRANSLATIONAL, I=62, J=47
, FUNCTION=-1.08*(PINVAL(10,2)-4.6)
PINPUTs and POUTPUTs are used to generate the A, B, C, and D matrices for a mechanical system at an
operating point. PINPUTs define the inputs to the system (plant) and POUTPUTs define the outputs from
the system (plant). These can be accessed with function expression also, as shown in the example above.
PINVAL(10,2) is the second element in the VARIABLES list for PINPUT/10 (that is, VARIABLE/22).
114 Adams Solver
C++ Functions
PITCH
Returns the negative value of the second angle of a body-fixed 3 2 1 yaw-pitch-roll rotation sequence between
marker i and marker j.
Note: Following automotive conventions, the PITCH function returns the negative value of the
second body-fixed 3 2 1 rotation sequence.
Format
PITCH(i[,j])
Arguments

Examples
REQUEST/2, F2=PITCH(143)
This REQUEST statement outputs the pitch angle (in radians) of Marker 143 relative to the global
coordinate system.
POLY 115
C++ Functions
POLY
The POLY function evaluates a standard polynomial at a user-specified value x.
Format
POLY (x, x0, a0, a1,..., a30)
Arguments
x0 A real variable that specifies a shift in the polynomial.
a0, a1,..., a30 The real variables that define as many as thirty-one coefficients for the polynomial series.
Extended Definition
The POLY function evaluates a standard polynomial at a user-specified value x. x0, a0, a1,..., a30 are
parameters used to define the constants for the polynomial. The standard polynomial is defined as:
n
P(x) =  aj ( x – xo )j
j=0
= ao + a1 ⋅ ( x – xo ) + a2 ⋅ ( x – xo ) 2 … + an ⋅ ( x – xo ) n
The index j has a range from zero to n, where n is the number of terms in the series.
Examples
MOTION/1, JOINT=21, TRANSLATION
, FUNCTION=POLY(TIME, 0, 0, 0, 1)
This MOTION statement uses a quadratic polynomial function with respect to the system variable TIME
to define a motion. That expanded function is:
Poly = time2
, FUNCTION = IF(TIME-5: 0, 0, POLY(TIME, 5, 0, 10))
This MOTION statement uses an arithmetic IF in its function expression to switch between functions.
The expanded function is:
if (time > 5) then Poly=0
else Poly=10*time-5
, FUNCTION=-POLY(DM(10, 20), 10, 0, 25, 0, 0.75)
116 Adams Solver
C++ Functions
This SFORCE statement defines a force with a nonlinear force deformation characteristic. This relationship
is:
Poly=-25*[DM(10,20)-10]- 0.75*[DM(10,20)-10]3
where, DM(10,20) represents the magnitude of the displacement of Marker 10 with respect to Marker 20.
The free length of the spring is 10 units.
POUVAL 117
C++ Functions
POUVAL
The POUVAL function returns component comp of POUTPUT/id.
Format
POUVAL (id, comp)
Arguments
id The identifier of the POUTPUT whose data is being requested.

comp An integer that specifies the component of the POUTPUT to be returned.
Examples
POUTPUT/10, VARIABLES=21,22
, FUNCTION=-1.08*(POUVAL(10,2)-4.6)
POUVAL(10,2) is the second element in the VARIABLES list for POUTPUT/10 (that is, VARIABLE/22).
118 Adams Solver
C++ Functions
PSI
The PSI function expression calculates the first angle (in radians) of a body-fixed-3-1-3 Euler rotation
sequence between markers i and j. Marker j defaults to the global coordinate system if it is not specified. For
a schematic of the body-fixed-3-1-3 Euler angles, click here.
Format
PSI(i[,j])
Arguments

Examples
REQUEST/1, F2=PSI(222,434)
This REQUEST statement outputs the psi angle between Markers 222 and 434 in its second column.
PTCV 119
C++ Functions
PTCV
The PTCV function returns component comp of a force due to PTCV/id as calculated in the coordinate
system of marker rm. If jflag is set to zero, the value returned is the force acting on the I marker of the PTCV.
If jflag is set to one, the value returned is that acting on the JFLOAT marker. rm may be specified as zero if
Format
PTCV (id, jflag, comp, rm)
Arguments
id An integer specifying the identification number of the point-to-curve constraint.

jflag An integer flag specifying the point-to-curve connectivity marker at which the forces and
torques are computed.
comp An integer value that specifies the component of the point-to-curve constraint to be returned.

Examples
REQUEST/1
, F2=PTCV(31,0,2,0)/
, F3=PTCV(31,0,3,0)/
, F4=PTCV(31,0,4,0)/
, F5=PTCV(31,0,5,0)/
, F6=PTCV(31,0,6,0)/
, F7=PTCV(31,0,7,0)/
, F8=PTCV(31,0,8,0)/
This REQUEST statement outputs the x-, y-, and z-components of the force and torque at the I marker of
PTCV/31. Since rm is specified as zero, all vectors are expressed in the global coordinate system.
120 Adams Solver
C++ Functions
Q
The Q function returns the current value of the modal coordinate for mode number mode_number for
FLEX_BODY/id.
Format
Q(id, mode_number)
Arguments
id The identifier of the FLEX_BODY.

mode_number The mode whose modal coordinate data is requested.
Example
MFORCE/20,FLEX_BODY=6,CASE_INDEX=1,SCALE=Q(5,10)
In this example, a modal force, whose loadcase is scaled by the current value of the modal coordinate
corresponding to mode number 10 on FLEX_BODY/5, is defined.
QDDOT 121
C++ Functions
QDDOT
The QDDOT function returns the second time derivative of the modal coordinate for mode number
mode_number of FLEX_BODY/id.
Format
QDDOT(id, mode_number)
Arguments

Example
MFORCE/20,FLEX_BODY=6,CASE_INDEX=1,SCALE=QDDOT(5,10)
In this example, a modal force, whose loadcase is scaled by the second time derivative of the modal coordinate
122 Adams Solver
C++ Functions
QDOT
The QDOT function returns the first time derivative of the modal coordinate for mode number
mode_number of FLEX_BODY/id.
Format
QDOT(id, mode_number)
Arguments

Example
MFORCE/20,FLEX_BODY=6,CASE_INDEX=1,SCALE=QDOT(5,10)
In this example, a modal force, whose loadcase is scaled by the first time derivative of the modal coordinate
ROLL 123
C++ Functions
ROLL
The ROLL function calculates the third angle of a body-fixed 3 2 1 yaw-pitch-roll rotation sequence between
markers i and j. Marker j defaults to the global coordinate system if it is not specified. Note that roll is an
Euler angle.
Format
ROLL (i[,j])
Arguments

Examples
REQUEST/2, F2=ROLL(143)
This REQUEST statement outputs the roll angle (in radians) of Marker 143 relative to the global coordinate
system.
124 Adams Solver
C++ Functions
RTOD
RTOD returns the radians to degrees conversion factor.
Format
RTOD
Examples
REQUEST/1, F2=ROLL(23,14)*RTOD
This REQUEST statement outputs the roll angle between Markers 23 and 14 in degrees.
S 125
C++ Functions
S
The S function returns a value between 0.0 and 1.0 along the neutral axis of a FE_PART. Function S
corresponds to a non dimensional arc length.
This function is exclusively used in the definition of distributed loads. This function has an undetermined
value if used in another context.
When evaluating distributed loads during a simulation, Adams Solver C++ sets the value of S at every
integration point and computes the value of the expressions for the load and its derivatives. For example, an
expression such as "DX(7)*S" will get a value depending on the specific location along the axis of the beam.
The value of S is set by Adams Solver when evaluating the expression.
This function does not have arguments.
Format
S
Example
FE_LOAD/1, FE_PART=3, FZ=-30*SIN(PI*S)*VARVAL(3)
126 Adams Solver
C++ Functions
SA
The SA function returns the value of the acceleration at a given location S along a beam. The value of S ranges
between 0.0 and 1.0. A given value of S determines a unique location along the axis of FE_PART.
When evaluating the loads during a simulation, Adams Solver C++ sets the value of S at every integration
point and computes the value of the distributed load and its derivatives. Accordingly, it sets the value of the
function SA depending on the specified component.
Format
SA(comp)
Arguments
comp An integer value specifying the kinematic component at a given position. All values are in the
global frame.
1 = x component of acceleration
2 = y component of acceleration
3 = z component of acceleration
4 = x component of angular acceleration
5 = y component of angular acceleration
6 = z component of angular acceleration
Example
FE_LOAD/1, FE_PART=3, FX=3.3*(SA(1)-ACCX(7))
In this example, the distributed load depends on the global x acceleration along the beam.
SD 127
C++ Functions
SD
The SD function returns the value of a global position or angle at a given location S along a beam. The value
of S ranges between 0.0 and 1.0. A given value of S determines a unique location along the axis of FE_PART.
function SD depending on the specified component.
Format
SD(comp)
Arguments
global frame.
1 = x component of position
2 = y component of position
3 = z component of position
4 = Psi Euler angle
5 = Theta Euler angle
6 = Phi Euler angle
Example
FE_LOAD/1, FE_PART=3, FX=3.3*(SD(3)-DZ(7))
In this example, the distributed load depends on the global z position along the beam.
128 Adams Solver
C++ Functions
SENVAL
The SENVAL function returns the last scored value from the function expression or user-written subroutine
associated with the EVALUATE argument on SENSOR/id. See the SENSOR statement for more information.
Format
SENVAL(id)
Arguments
id An integer specifying the identification number of the SENSOR.
Caution: If the SENSOR/id does not have the EVALUATE argument, SENVAL(id) returns zero.
Examples
VARIABLE/1, FUNCTION=SENVAL(100)
SENSOR/100, EQ, VALUE=0
, FUNCTION=AZ(22,11)-PI/2/
, EVALUATE=SENVAL(100) +1
This SENSOR statement counts the number of times function AZ(22,11) passes through π /2. The
VARIABLE statement defines a variable equal to the count.
SFORCE 129
C++ Functions
SFORCE
The SFORCE function returns component comp of a force due to SFORCE/id as calculated in the
coordinate system of marker rm. If jflag is set to zero, the value returned is the force or torque acting on the
I marker of the SFORCE/id. If jflag is set to 1, the value returned is that which acts on the J marker. You can
specify rm as zero if you want the results to be returned in the global coordinate system.
Format
SFORCE (id, jflag, comp, rm)
Arguments
id An integer specifying the identification number of the SFORCE.

jflag An integer flag specifying the SFORCE connectivity marker at which the forces and torques are
computed.

comp An integer value that specifies the component of the SFORCE to be returned.

rm The coordinate system in which the results are expressed.
Set rm = 0 if you want to return the results in the global coordinate system.
Examples
REQUEST/1
, F2=SFORCE(31,0,2,0)/
, F3=SFORCE(31,0,3,0)/
, F4=SFORCE(31,0,4,0)/
, F5=SFORCE(31,0,5,0)/
, F6=SFORCE(31,0,6,0)/
, F7=SFORCE(31,0,7,0)/
, F8=SFORCE(31,0,8,0)
SFORCE/31. Since rm is specified as zero, all vectors are expressed in the global coordinate system.
130 Adams Solver
C++ Functions
SHF
The SHF function evaluates a simple harmonic function. The following equation defines SHF:
SHF = a*sin( ω *(x-x0)-phi)+b
Format
SHF (x, x0, a, w, phi, b)
Note: The “x” can be variable, the other arguments are to be constant.
Arguments
x The independent variable in the function. It may be any valid expression. For example, if the
independent variable in the function is twice the current simulation time, x is the system variable
2*TIME.
x0 The offset in the independent variable x.
a The amplitude of the harmonic function.
ω The frequency of the harmonic function. Adams Solver assumes ω is in radians per unit of the
independent variable. Conversion to degrees per unit of the independent is achieved by
appending a D after the number specifying ω .
phi A phase shift in the harmonic function. Adams Solver assumes phi is in radians unless you use
a D after the value.
b The average value of displacement of the harmonic function.
Examples
, FUNCTION=SHF(TIME, 25D, PI, 360D, 0, 5)
This MOTION statement uses SHF to define the harmonic function:
SHF = 5+PI*sin(360D*(time-25D))
The motion has a shift of 25 degrees, has an amplitude of PI, has a frequency of 1 cycle (360D) per time unit,
has zero phase shift, and has an average value of displacement of 5 units.
SIGN 131
C++ Functions
SIGN
The SIGN function transfers the sign of a2 to the magnitude of a1.
SIGN(a1,a2) = ABS(a1) if a2 > 0
SIGN(a1,a2) = -ABS(a1) if a2 < 0
Format
SIGN (a1,a2)
Arguments

Caution: The SIGN function is discontinuous. Use this function with care to avoid creating expressions
that are discontinuous.
Examples
VARIABLE/23, FUNCTION=10*SIGN(DM(24,33),VZ(24,33))
When VZ(24,33) >0, the value of VARIABLE/23 is +10*DM(24,33). When VZ(24,33) < 0, the value of
VARIABLE/23 is -10*DM(24,33).
132 Adams Solver
C++ Functions
SIN
The SIN function returns the sine of an expression a.
Format
SIN(a)
Arguments
Examples
, FUNCTION=SIN(10*TIME)
A translational force is defined to be acting along the line joining Markers 23 and 34. The force at Marker
23 is defined to be SIN(10*TIME).
SINH 133
C++ Functions
SINH
The SINH function return the hyperbolic sine of an expression a.
SINH(a) = (ea - e-a) /2.0
Format
SINH(a)
Arguments
Examples
VARIABLE/1, FUNCTION=SINH(DX(21,32))
The value of VARIABLE/1 is the hyperbolic sine of the x-component of the displacement between Markers
21 and 32, as calculated in the global coordinate system.
134 Adams Solver
C++ Functions
SPDP
The SPDP function returns the component comp of a force due to SPRINGDAMPER/id as calculated in
the coordinate system of marker rm. If jflag is set to zero, the value returned is the force/torque that acts on
the I marker of the SPRINGDAMPER. If jflag is set to 1, the value returned is the value that acts on the j
marker. To get results in the global coordinate system, you can specify rm as zero.
Format
SPDP (id, jflag, comp, rm)
Arguments
id An integer specifying the identification number of the SPDP.

jflag An integer flag specifying the SPDP connectivity marker at which the forces and torques are
computed.

comp An integer value that specifies the component of the SPDP force to be returned.

Examples
REQUEST/1
, F2=SPDP(31,0,2,0)/
, F3=SPDP(31,0,3,0)/
, F4=SPDP(31,0,4,0)/
, F6=SPDP(31,0,6,0)/
, F7=SPDP(31,0,7,0)/
, F8=SPDP(31,0,8,0)
This REQUEST statement output the x-, y- and z-components of the force and torque at the I marker of
SPDP/31. Since rm is specified as zero, all vectors are expressed in the global coordinate system.
SQRT 135
C++ Functions
SQRT
The SQRT function returns the square root of an expression a. The square root function is defined only for
non-negative values of the argument a.
Format
SQRT(a)
Arguments

Examples
VARIABLE/23,
, FUNCTION=SQRT (FX(23,11)**2+FY(23,11)**2)
A new state variable with a value equal to the square root of the sum of the squares of the global x- and y-
components of the net force acting between Markers 21 and 11.
136 Adams Solver
C++ Functions
STEP
The STEP function approximates the Heaviside step function with a cubic polynomial. It has continuous
first derivatives. Its second derivatives are discontinuous at x=x0 and x=x1.
Format
STEP (x, x0, h0, x1, h1)
Arguments
x The independent variable. It can be a function expression.

x0 A real variable that specifies the x value at which the STEP function begins.
x1 A real variable that specifies the x value at which the STEP function ends.
h0 The initial value of the step.
h1 The final value of the step.
Extended Definition
The STEP function approximates the Heaviside step function with a cubic polynomial. The figure below
illustrates the STEP function.
Step Function
The equation defining the STEP function is:
a = h1 – h0
Δ = ( x – x0 ) ⁄ ( x1 – x0 )
STEP 137
C++ Functions
 h0 : x ≤ x0 
 
STEP =  h 0 + a ⋅ Δ 2 ( 3 – 2Δ ) : x0 < x < x1 
 
h1 : x ≥ x1 
Tip: HAVSIN, STEP5, and TANH offer other approximations for the Heaviside step function. These
(except for HAVERSINE) have a higher degree of continuity and differentiability, but may
have larger derivatives.
The figure shown next compares the STEP, STEP5, HAVSIN, and TANH functions.
Comparisons of STEP, STEP5, HAVSIN, and TANH
The next figure shows the first derivatives of these four functions.
First Derivatives of STEP, STEP5, HAVSIN, and TANH
138 Adams Solver
C++ Functions
Examples
, FUNCTION=STEP(TIME, 1, 0, 2, 1)
This MOTION statement defines a smooth step function from time 1 to time 2 with a velocity from 0 to 1.
Note that the motion is specified at the velocity rather than the position level. This prevents the second-order
derivative to be invoked during acceleration computation, which is something that would happen if the
motion were defined as a displacement level motion.
STEP5 139
C++ Functions
STEP5
The STEP5 function provides approximation to the Heaviside step function with a quintic polynomial. It
has continuous first and second derivatives. Its third derivative is discontinuous at x=x0 and x=x1.
Format
STEP5 (x, x0, h0, x1, h1)
Arguments

x0 A real variable that specifies the x value at which the STEP5 function begins.
x1 A real variable that specifies the x value at which the STEP5 function ends.
Extended Definition
The figure shown next illustrates the STEP5 function.
STEP5 Function
The equation defining the STEP5 function is:
α = h1 – h0
Δ = ( x – x0 ) ⁄ ( x1 – x0 )
140 Adams Solver
C++ Functions
 h0 : x ≤ x0 
 
STEP5 =  h 0 + a ⋅ Δ 3 [ 10 – 15Δ + 6Δ 2 ] : x0 < x < x1 
 
 h1 : x ≥ x1 
Examples
, FUNCTION=STEP5(TIME, 1, 0, 2, 1)
This MOTION statement defines a smooth step function from TIME = 1 to TIME = 2 with a displacement
from 0 to 1.
SV 141
C++ Functions
SV
The SV function returns the value of a velocity at a given location S along a beam. The value of S ranges
between 0.0 and 1.0. A given value of S determines a unique location along the axis of FE_PART.
function SV depending on the specified component.
Format
SV(comp)
Arguments
global frame.
1 = x component of velocity
2 = y component of velocity
3 = z component of velocity
4 = x component of angular velocity
5 = y component of angular velocity
6 = z component of angular velocity
Example
FE_LOAD/1, FE_PART=3, FX=3.3*(SV(1)-VX(7))
In this example, the distributed load depends on the global x velocity along the beam.
142 Adams Solver
C++ Functions
SWEEP
The SWEEP function returns a constant amplitude sinusoidal function with linearly increasing
instantaneous frequency (linear chirp).
Format
SWEEP (x, a, x0, f0, x1, f1, dx)
Arguments

a The amplitude of the sinusoidal function.
x0 The value of the independent variable at which the SWEEP function begins.
f0 The initial instantaneous frequency (in Hz) of the sinusoidal function.
x1 The value of the independent variable value at which the SWEEP function ends
f1 The final instantaneous frequency (in Hz).
dx The interval in which the SWEEP function becomes fully active.
Note: Error message will be triggered if x 0 ≥ x1 .
Extended Definition
Mathematically, SWEEP is calculated as follows:
SWEEP 143
C++ Functions
The SWEEP function is an implementation of a linear chirp function.

See details in section Mathematical background below.
Examples
The following example defines motion with a sinusoidal function with a rising frequency from 2 to 6Hz
during the time interval 0 to 5.
MOTION/1,JOINT=1
, FUNCTION=SWEEP(TIME, 1.0, 0.0, 2.0, 5.0, 6.0, 0.01)
144 Adams Solver
C++ Functions
Figure 8 Example SWEEP function
Mathematical background
Given a waveform of type:
x ( t ) = sin ( ϕ ( t ) ) (1)
where t is time. The instantaneous frequency f(t) of this type of signal is defined as:
1 dϕ ( t )
f ( t ) = ------ ------------- (2)
2π dt
If function f(t) is a linear function, the waveform x(t) is called a linear chirp. The SWEEP function
implements a linear chirp as shown in Figure 9.
SWEEP 145
C++ Functions
Figure 9 Linear chirp implemented in SWEEP function
For the case t 0 ≤ t ≤ t 1 we see that function f(t) takes the form:
f1 – f0
f ( t ) = f 0 + -------------- ( t – t 0 ) (3)
t1 – t0
Integrating Equation (2) we obtain:
t
ϕ ( t ) – ϕ ( t 0 ) = 2π  f ( t ) dt
t0
or
t
f1 – f0
ϕ ( t ) = 2π   f 0 + -------------- ( t – t 0 ) dt + ϕ ( t 0 )
t1 – t0
t0
Evaluating the integral we get:

2
 f1 – f0 ( t – t0 ) 
ϕ ( t ) = 2π ⋅  f 0 ( t – t 0 ) + -------------- -------------------  + ϕ ( t 0 )
 t1 – t0 2 
Rearranging this expression we obtain:
 ( f1 – f0 ) ⋅ ( t – 2 ⋅ t0 ) ( f1 – f0 ) ⋅ t0 ⋅ t0 
ϕ ( t ) = 2π ⋅   f 0 + ----------------------------------------------- t +  ------------------------------------  – 2π ⋅ f 0 t 0 + ϕ ( t 0 )
 2 ⋅ ( t1 – t0 ) 2 ⋅ ( t1 – t0 ) 
The last two constants terms can be arbitrarily dropped to obtain:

146 Adams Solver
C++ Functions
 ( f1 – f0 ) ⋅ ( t – 2 ⋅ t0 ) ( f1 – f0 ) ⋅ t0 ⋅ t0 
ϕ ( t ) = 2π ⋅   f 0 + ----------------------------------------------- t +  ------------------------------------  (4)
 2 ⋅ ( t1 – t0 )   2 ⋅ ( t1 – t0 ) 
 
Notice that dropping the above constants, the time derivative of Equation (4) still matches Equation (3).
Using Equation (4) at times t0 and t1, the angular function ϕ ( t ) has these values:
ϕ ( t 0 ) = 2π ⋅ { ( f 0 )t 0 + ( 0 ) } (5)
and
ϕ ( t 1 ) = 2π ⋅ { ( f 1 )t 1 + ( 0.5 ⋅ ( f 0 – f 1 ) ( t 0 + t 1 ) ) } (6)
Finally, Equations (4), (5) and (6) are used to define functions h(x) and p(x) presented in the definition of the
SWEEP function above.
Notice the first argument to the SWEEP function is not limited to time.
For the case when t0 > 0 you may see a discontinuity in the value of ϕ ( t ) , hence you may want to set a non
zero value for dx (last argument of the SWEEP function) in order to ramp up the value of the angular function
starting from zero.
References
1. Chirp, https://en.wikipidia.org/wiki/Chirp
2. MATLAB, https://www.mathworks.com/help/signal/ref/chirp.html
SYSTEM_KINETIC_ENERGY 147
C++ Functions
SYSTEM_KINETIC_ENERGY
The SYSTEM_KINETIC_ENERGY utility subroutine computes the total Kinetic Energy of all Bodies with
mass in a model. This includes PART (PLANAR and 3D), FE_PART (2D and 3D), FLEX_BODY, and
POINT_MASS.
Use
Called By
Any of a REQSUB, SENSUB, SEVSUB, CONSUB or CBKSUB.
Prerequisite
None
Calling Sequence
CALL SYSTEM_KINETIC_ENERGY (ke)
Input Arguments
none
Output Arguments
ke A double-precision variable that specifies the total Kinetic Energy of all Bodies with mass.
Caution: The SYSTEM_KINETIC_ENERGY 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, CONSUB and
CBKSUB.
148 Adams Solver
C++ Functions
SYSTEM_MOMENTUM
The SYSTEM_MOMENTUM utility subroutine computes the total Momentum (Linear and Angular) of
all Bodies with mass in a model. This includes PART (PLANAR and 3D), FE_PART (2D and 3D),
FLEX_BODY, and POINT_MASS. The computed Momentum is returned in Global coordinates. The
Angular Momentum is computed about a specified reference location.
Use
Called By
Any of a REQSUB, SENSUB, SEVSUB, CONSUB or CBKSUB.
Prerequisite
None
Calling Sequence
CALL SYSTEM_MOMENTUM (rm, p, l)
Input Arguments
rm A marker ID which references location for computing Angular Momentum.
Output Arguments
p A double-precision variable that specifies the total Linear Momentum of all

Bodies with mass. The value is expressed in GCS.
l A double-precision variable that specifies the total Angular Momentum of all
Bodies with mass. The value is expressed in GCS. It is computed about the
location specified by input parameter rm.
Caution: The SYSTEM_MOMENTUM 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, CONSUB and CBKSUB.
TAN 149
C++ Functions
TAN
The TAN function returns the tangent of an expression a.
Format
TAN(a)
Arguments
Examples
, FUNCTION=TAN(10*TIME)
23 is defined to be TAN(10*TIME).
150 Adams Solver
C++ Functions
TANH
The TANH function returns the hyperbolic tangent of an expression a.
TANH(a) = (ea - e-a) / (ea + e-a)
Format
TANH(a)
Arguments
Extended Definition
The figure below illustrates the TANH function.
TANH Function
Example
, FUNCTION=0.5(1+TANH(5*(TIME-1.5)))
This MOTION statement defines a smooth step function that transitions from a value of 0 to 1. The value
of the step function at time=1.5 is 0.5.
THETA 151
C++ Functions
THETA
The THETA function calculates the second angle (in radians) of a body-fixed-3-1-3 Euler rotation sequence
between markers i and j. Marker j defaults to the global coordinate system if it is not specified. View a schematic
of the body-fixed-3-1-3 Euler angles.
Format
THETA(i[,j])
Arguments

Examples
REQUEST/1, F2=THETA(222,434)
This REQUEST statement outputs the theta angle between Markers 222 and 434 in its second column.
152 Adams Solver
C++ Functions
TIME
The TIME variable returns the current simulation time.
Format
TIME
Examples
, FUNCTION=10*SIN(2*PI*TIME)
This SFORCE statement defines a translational force acting between the origins of Marker 21 and Marker
11. The value of the force is 10*SIN*(2*PI*TIME).
TM 153
C++ Functions
TM
The TM measure returns the magnitude of the net translational torque acting on marker i. All force and
constraint elements acting between markers i and j are included in the calculation of the torque. If j is not
specified, TM measures the sum of all force and constraint elements acting on marker i.
Format
TM(i[j])
Arguments
i An integer that specifies the identifier of the marker at which the magnitude of the net torque is to
be calculated.
marker i.
Examples
MOTION/1, ROTATION, JOINT=1, FUNCTION=10*TIME
VARIABLE/31, FUNCTION=TM(32,44)
In this example a revolute joint and motion (through the joint) act between Marker 32 and 44. A new state
variable VARIABLE/31 is defined to have the magnitude of the net torque between these two markers as its
value.
154 Adams Solver
C++ Functions
TRANS
The TRANS function transforms an arbitrary vector function expression represented in the coordinate
system of marker j to the coordinate system of marker i.
Format
TRANS(exp,i[,j])
Arguments

i The marker whose coordinate system the expression, exp, is to be represented.
j The marker in whose coordinate system the expression, exp, is specified. If not specified, the
expression, exp, is assumed to be specified in the global coordinate system.
Examples
VFORCE/1, I=1, JFLOAT=2, RM=3, FXYZ=VXYZ(i,j,k)
VFORCE/2, I=1, JFLOAT=2, RM=3, FXYZ=TRANS(VXYZ(i,j),k)
VFORCE/3, I=1, JFLOAT=2, RM=3, FXYZ=TRANS(VXYZ(i,j,l),k,l)
Variables 1, 2 and 3 are synonymous. They all specify a vector force law that is equal to the velocity vector of
marker i with respect to marker j, represented in the coordinate system of marker k.
TX 155
C++ Functions
TX
The TX measure returns the x-component of the net translational torque acting on marker i, represented in
the coordinate system of marker k. All force and constraint elements acting between markers i and j are
included in the calculation of the torque. If j is not specified, TX measures the sum of all force and constraint
elements acting on marker i. If k not specified or if k=0 the torque is represented in the GROUND coordinate
system. To specify k without specifying j use j=0.
Format
TX(i[,j][,k])
Arguments
be calculated.
marker i.
k An integer that specifies the identifier of a marker (coordinate system) in which the x-component
of the torque is to be returned. k defaults to the global coordinate system when it is not specified.
Examples
VARIABLE/31, FUNCTION=TX(32,44)
variable VARIABLE/31 is defined to have the x-component of the sum of all torques acting between markers
32 and 44 as computed in the global coordinate system. Since JOINT 1 and motion 1 are defined between
markers 32 and 44, their reaction torque will be included in the computation of TX().
156 Adams Solver
C++ Functions
TXYZ
The TXYZ measure returns the net translational torque vector acting on marker i, represented in the
in the calculation of the torque. If j is not specified, TXYZ measures the sum of all force and constraint
elements acting on marker i. If k is not specified or if k=0, the torque is represented in the GROUND
coordinate system. To specify k without specifying j, use j=0.
Format
TXYZ(i[,j][,k])
Arguments
be calculated.
marker i.
Extended Definition
Mathematically, TXYZ is calculated as:
 TX 
 
TXYZ ( i ,j ,k ) =  TY 
 
 TZ 
where:
 TX is the TX measure.
 TY is the TY measure.
 TZ is the TZ measure.
Examples
The total torque on marker 5, resolved on the x-axis of marker 4.
VARIABLE/1, FUN=TXYZ(5)*UVX(4)
which is alternatively available as TX(5,0,4).
TY 157
C++ Functions
TY
The TY measure returns the y-component of the net translational torque acting on marker i, represented in
included in the calculation of the torque. If j is not specified, TY measures the sum of all force and constraint
Format
TY(i[,j][,k])
Arguments
be calculated.
marker i.
k An integer that specifies the identifier of a marker (coordinate system) in which the y-component
Examples
VARIABLE/31, FUNCTION=TY(32,44)
variable VARIABLE/31 is defined to have the y-component of the sum of all torques acting between markers
32 and 44 as computed in the global coordinate system. Since joint 1 and motion 1 are defined between
markers 32 and 44, their reaction torque will be included in the computation of TY().
158 Adams Solver
C++ Functions
TZ
The TZ measure returns the z-component of the net translational torque acting on marker i, represented in
included in the calculation of the torque. If j is not specified, TZ measures the sum of all force and constraint
Format
TZ(i[,j][,k])
Arguments
be calculated.
marker i.
k An integer that specifies the identifier of a marker (coordinate system) in which the z-component
Examples
VARIABLE/31, FUNCTION=TZ(32,44
In this example a revolute joint and motion (through the joint) act between Marker 32 and 44. A determined
state variable VARIABLE/31 is defined to have the z-component of the sum of all torques acting between
markers 32 and 44 as computed in the global coordinate system. Since joint 1 and motion 1 are defined
between markers 32 and 44, their reaction torque will be included in the computation of TZ( ).
UV 159
C++ Functions
UV
The UV function returns the unit vector in the direction of an arbitrary vector function expression.
Format
UV(exp)
Arguments
Extended Definition
Mathematically, UV is calculated as:
exp
UV ( exp ) = --------------------------
exp ⋅ exp
where exp is an arbitrary vector function expression.

Note that Adams Solver (C++) attempts to handle the singular case when the vector function expression is
the zero vector. For instance, the expression UV(DXYZ(i,j)) is problematic if markers i and j become
coincident. In this case, Adams Solver (C++) will reuse the last valid direction of the unit vector. It is
recommended that you avoid computing the unit vector in the direction of expressions that start with a zero
value or are persistently zero (such as velocity measurements during a static equilibrium analysis).
Examples
VARIABLE/1, FUN=VXYZ(i,j)*UV(DXYZ(i,j))
VARIABLE/2, FUN=VR(i,j)
Variables 1 and 2 are synonymous. They both compute the separation velocity of markers i and j: the
projection of the relative velocity vector on a unit vector in the direction of the position vector between the
markers.
160 Adams Solver
C++ Functions
UVX
The UVX measure returns the unit vector in the direction of the x axis of marker i, resolved in the coordinate
system of marker k.
Format
UVX(i[,k])
Arguments
i The marker whose x-axis unit vector is being measured.

k The marker in whose coordinate system the unit vector is being expressed. If k is not specified,
Extended Definition
Mathematically, UVX is calculated as:
ˆ ˆ
 xi ⋅ xk 
 
UVX ( i, k ) =  xˆ i ⋅ yˆ k 
ˆ ˆ 
x ⋅ z  i k
where:
 xˆ i is the unit vector along the x-axis of marker i.
Examples
VARIABLE/1, FUN=DXYZ(i,j)*UVX(k)
VARIABLE/2, FUN=DX(i,j,k)
Variables 1 and 2 are synonymous. They both produce the translational displacement between markers i and
j along the direction of the x-axis of marker k.
UVY 161
C++ Functions
UVY
The UVY measure returns the unit vector in the direction of the y axis of marker i, resolved in the coordinate
system of marker k.
Format
UVY(i[,k])
Arguments
i The marker whose y-axis unit vector is being measured.

k The marker in whose coordinate system the unit vector is being expressed. If k is not specified,
Extended Definition
Mathematically, UVY is calculated as:
ˆ ˆ
 yi ⋅ xk 
 
UVY ( i, k ) =  yˆ i ⋅ yˆ k 
ˆ ˆ 
y ⋅ z i k
where:
 yˆ i is the unit vector along the y-axis of marker i.
 xˆ i is the unit vector along the x-axis of marker k.
Examples
VARIABLE/1, FUN=DXYZ(i,j)*UVY(k)
VARIABLE/2, FUN=DY(i,j,k)
j along the direction of the y-axis of marker k.
162 Adams Solver
C++ Functions
UVZ
The UVZ measure returns the unit vector in the direction of the z axis of marker i, resolved in the coordinate
system of marker k.
Format
UVZ(i[,k])
Arguments
i The marker whose z-axis unit vector is being measured.

k The marker in whose coordinate system the unit vector is being expressed. If k is
not specified, k defaults to the global coordinate system.
Extended Definition
Mathematically, UVZ is calculated as:
ˆ ˆ
 zi ⋅ xk 
 
UVZ ( i, k ) =  zˆ i ⋅ yˆ k 
ˆ ˆ 
z ⋅ z  i k
where:
 zˆ i is the unit vector along the z-axis of marker i.
Examples
VARIABLE/1, FUN=DXYZ(i,j)*UVZ(k)
VARIABLE/2, FUN=DZ(i,j,k)
j along the direction of the z-axis of marker k.
VARVAL 163
C++ Functions
VARVAL
The VARVAL function returns current value of VARIABLE/id.
Format
VARVAL (id)
Arguments
id The identifier of the VARIABLE whose data is being requested.
Examples
VARIABLE/10, FUNCTION=DX(21,32,43)
, FUNCTION=(VARVAL(10)-5)**2
In this example, VARIABLE/10 defines an algebraically determined user-specified state. SFORCE/20 is a
nonlinear translational spring whose force magnitude is a function of this variable.
164 Adams Solver
C++ Functions
VFORCE
The VFORCE function returns the component comp of the force in VFORCE/id in the coordinate system
of marker rm. If jflag is set to zero, Adams Solver (C++) returns the value of force/torque that acts on the I
marker of VFORCE/id. If jflag is set to 1, Adams Solver (C++) returns the value that acts on the J marker.
To obtain results in the global coordinate system, you can specify rm as zero.
Format
VFORCE (id, jflag, comp, rm)
Arguments
id An integer specifying the identification number of the VFORCE.

jflag An integer flag specifying the VFORCE connectivity marker at which the forces and
torques are computed.

comp An integer value that specifies the component of the VFORCE that is returned.

Examples
MARKER/236, QP=4,6,7, EU=90D,90D,0, PART=23
MARKER/169, PART=16, FLOATING
MARKER/168, QP=1,2,3, EU=30D,45D,60D, PART=16
VFORCE/19, I=236, JFLOAT=169
,FX=-10*VX(236,168,168,168)/
,FY=-10*VY(236,168,168,168)/
,FZ=-10*VZ(236,168,168,168)
REQUEST/1
,F2=VFORCE(23,0,2,0)/
This REQUEST statement contains the x-component of the force exerted by VFORCE/19 calculated in the
coordinate system of Marker 168.
VFORCE 165
C++ Functions

166 Adams Solver
C++ Functions
VM
The VM function calculates the magnitude of the first time derivative of the displacement vector of marker
i with respect to marker j. The vector time derivative is taken in the reference frame of marker l. Markers i
and j default to the global coordinate system if they are not specified.
Format
VM(i[,j][,l])
Arguments
i The marker whose velocity is being measured.

j The marker with respect to which the velocity is being measured. Set j = 0, while still specifying l, if
you want j to default to the global coordinate system.
l The reference frame in which the time derivative of the displacement vector is taken. Set l = 0 or omit
the argument if you want the time derivatives to be taken in the ground coordinate system (GCS).
Extended Definition
Mathematically, VM is calculated as follows:
(l) d (l) d (l) d (l) d

VM ( i, j, l ) = Ri – Rj ⋅ Ri – Rj
dt dt dt dt
Examples
DIFF/51, IC=-6.2, FUNCTION=VM(23,0,32)
A dynamically determined user state is defined by DIFF/51. The time derivative of the user-state is the
magnitude of the velocity of the origin of Marker 23 with respect to ground. The time derivative for the
velocity computation is taken in the reference frame of Marker 32.
VARIABLE/1, FUNCTION=VM(21,32,43)
This VARIABLE statement defines an algebraic, user-defined state whose instantaneous value is the
magnitude of the velocity vector between Markers 21 and 32, as seen by an observer at Marker 43.
See other Velocity measures available.
VR 167
C++ Functions
VR
The VR function calculates the radial (separation) velocity of marker i with respect to marker j. The vector
time derivative is taken in the reference frame of marker l. Markers j and l default to the global coordinate
system if they are not specified.
Format
VR(i[,j][,l])
Arguments

j The marker with respect to which the velocity is being measured. Set j = 0, while still specifying l,
if you want j to default to the global coordinate system.
l The reference frame in which the time derivative of the displacement vector is taken. Set l = 0 or
omit the argument if you want the time derivatives to be taken in the ground coordinate system
(GCS).
Extended Definition
Mathematically, VR is calculated by projecting the velocity vector on a unit vector along the line of sight
between i and j, as follows:
(l) d (l) d
Ri – Rj ⋅ [ Ri – Rj ]
dt dt
VR ( i, j, l ) = -------------------------------------------------------------------- = VXYZ ⋅ UV ( DXYZ )
[ Ri – Rj ] ⋅ [ Ri – Rj ]
where:

As markers i and j separate from each other, VR is positive. VR is negative when markers i and j approach
each other.
Although the VR function accepts an l argument as the reference frame in which the time derivative is taken,
it is invariant of the coordinate system in which it is computed.
The VR function is actually the time derivative of the invariant DM function, which can be seen as follows:
DM ( i, j ) = [ Ri – Rj ] ⋅ [ Ri – Rj ]
168 Adams Solver
C++ Functions
d-
---- d
R i – ----- R j ⋅ [ R i ⋅ R j ]
d- dt dt
---- DM ( i, j ) = --------------------------------------------------------- = VR ( i, j )
dt [ Ri – Rj ] ⋅ [ Ri – Rj ]
This is useful to know when using DM and VR together as the displacement and velocity terms in an
SFORCE. Please see the SFORCE statement for an example.
Examples
, FUNCTION=-10*VR(467,764)
This SFORCE statement defines a translational damper with a damping constant of 10.
VTORQ 169
C++ Functions
VTORQ
The VTORQ function returns the component comp of force in VTORQUE/id in the coordinate system of
marker rm. If jflag is set to zero, Adams Solver (C++) returns the value of the torque that acts on the I marker
of VTORQUE/id. If jflag is set to 1, Adams Solver (C++) returns the value that acts on the J marker. To
obtain results in the global coordinate system, you can specify rm as zero.
Format
VTORQ (id, jflag, comp, rm)
Arguments
id An integer specifying the identification number of the VTORQ.

jflag An integer flag specifying the VTORQ connectivity marker at which the forces and torques are
computed.

comp An integer value that specifies the component of the VTORQ force to be returned.
1 = Magnitude of the force (which is zero for a VTORQUE)

2 = x component of the force (which is zero for a VTORQUE)
3 = y component of the force (which is zero for a VTORQUE)
4 = z component of the force (which is zero for a VTORQUE)
Set rm = 0 if you want the results returned in the global coordinate system.
Examples
VTORQUE/19, I=236, JFLOAT=169
,TX=-10*WX(236,168,168,168)/
,TY=-10*WY(236,168,168,168)/
,TZ=-10*WZ(236,168,168,168)
REQUEST/1
, F2=VTORQ(19,0,2,168)/
This REQUEST statement contains the x-component of the torque exerted by VTORQUE/19 calculated in
the coordinate system of Marker 168.
170 Adams Solver
C++ Functions

VX 171
C++ Functions
VX
The VX function returns the x-component of the difference between the velocity vector of marker i and the
velocity vector of marker j as computed in the coordinate system of marker k. All vector time derivatives are
taken in the reference frame of marker l. Marker j defaults to the global coordinate system if it is not specified.
Similarly, markers i and j default to the global coordinate system if they are not specified.
Format
VX(i[,j][,k][,l])
Arguments

k The marker in whose coordinate system the velocity vector is being expressed. Set k = 0, while still
specifying l, if you want the results to be calculated along the x-axis of the global coordinate system.
l The reference frame in which the first time derivative of the displacement vector is taken. Set l = 0
or omit the argument if you want the time derivatives to be taken in the ground coordinate system
(GCS).
Extended Definition
Mathematically, VX is calculated as follows:
(l) d (l) d ˆ
Vx ( i, j ,k, l ) = Ri – Rj ⋅ xk
dt dt
where:
 R i is the displacement of marker i in ground.
 R j is the displacement of marker j in ground.

ˆ
(l)
d
 denotes time differentiation in the reference frame of the l marker.
dt
Examples
172 Adams Solver
C++ Functions
,FX=-10*VX(236,168,168,168)/
,FY=-15*VY(236,168,168,168)/
,FZ=-20*VZ(236,168,168,168)
This VFORCE statement defines a damper acting between Markers 236 and 168. Marker 169 is a floating
marker that defines the reaction point on Part 16. The damping force components are proportional to the
components of the velocity between Markers 236 and 168 as seen and measured by an observer at Marker
168.
VXYZ 173
C++ Functions
VXYZ
The VXYZ measure returns the difference between the velocity vector of marker i and the velocity vector of
marker j resolved in the coordinate system of marker k. All vector time derivatives are taken in the reference
frame of marker l.
Format
VXYZ(i[,j][,k][,l])
Arguments

j The marker with respect to which the velocity is being measured. If j is not specified, it defaults to
the global origin. Specify j = 0 if you want to use this default and you need to specify k or l.
k The marker in whose coordinate system the velocity vector is being expressed. If not specified, k
defaults to the global coordinate system. Specify k = 0 if you want to use this default and you need
to specify l.
l The reference frame in which the first-time derivative of the displacement vector is taken. Set l =
0 or omit the argument if you want the time derivatives to be taken in the global reference frame.
Extended Definition
Mathematically, VXYZ is calculated as follows:
(l) d (l) d ˆ
 Ri – Rj ⋅ xk 
 dt dt 
   VX 
 (l) d (l) d ˆ  =  
VXYZ ( i ,j ,k ,l ) =  Ri – Rj ⋅ yk   VY 
 dt dt   
 (l) d (l) d
  VZ 
 ˆ 
 Ri – Rj ⋅ zk 
dt dt
where:

 VX is the VX measure.
 VY is the VY measure.
 VZ is the VZ measure.
174 Adams Solver
C++ Functions
(l) d
dt
Examples
This variable statement:
VARIABLE/1, FUNCTION = VXYZ(21,11) * UV(DXYZ(21,11))
computes the projection of the velocity vector of marker 21 from marker 11 on a unit vector along the line
of sight to marker 21 from marker 11. This quantity is also known as the radial velocity and can be written
more compactly as:
VARIABLE/1, FUNCTION = VR(21,11)
VY 175
C++ Functions
VY
The VY function returns the y-component of the difference between the velocity vector of marker i and the
Format
VY(i[,j][,k][,l])
Arguments

j The marker with respect to which the velocity is being measured. Set j = 0, while still specifying i,
specifying l, if you want the results to be calculated along the y-axis of the global coordinate system.
(GCS).
Extended Defintion
Mathematically, VY is calculated as follows:
(l) d (l) d ˆ
VY ( i ,j ,k ,l ) = Ri – Rj ⋅ yk
dt dt
where:

ˆ
 y k is the unit vector along the y-axis of marker k.
(l)
d
dt
Examples
176 Adams Solver
C++ Functions
,FX=-10*VX(236,168,168,168)/
,FY=-15*VY(236,168,168,168)/
,FZ=-20*VZ(236,168,168,168)
168.
VZ 177
C++ Functions
VZ
The VZ function returns the z-component of the difference between the velocity vector of marker i and the
Format
VZ(i[,j][,k][,l])
Arguments

k The marker in whose coordinate system the velocity vector is expressed. Set k = 0, while still
specifying l, if you want the results to be calculated along the z-axis of the global coordinate system.
(GCS).
Extended Definition
Mathematically, VZ is calculated as follows:
(l) d (l) d ˆ
VZ ( i ,j ,k ,l ) = Ri – Rj ⋅ zk
dt dt
where:

ˆ
 z k is the unit vector along the z-axis of marker k.
(l)
d
dt
Examples
178 Adams Solver
C++ Functions
,FX=-10*VX(236,168,168,168)/
,FY=-15*VY(236,168,168,168)/
,FZ=-20*VZ(236,168,168,168)
168.
WDTM 179
C++ Functions
WDTM
The WDTM function returns the magnitude of the difference between the angular acceleration vector of
marker i in the reference frame of marker l and the angular acceleration of marker j in the reference frame of
marker l.
Format
WDTM(i[,j][,l])
Arguments

i, if you want j default to the global coordinate system.
l The reference frame in which the first time derivative of the angular velocity vector is taken. Set l =
0 if you want the time derivatives to be taken in the ground reference frame.
Extended Definition
Mathematically, WDTM is calculated as follows:
(l) d (l) d (l) d (l) d

WDTM ( i ,j, l ) = ωi – ωj ⋅ ωi – ωj
dt dt dt dt
where:
 ω i is the angular velocity vector of marker i in ground.
 ω j is the angular velocity vector of marker j in ground.
Examples
MARKER/1236, QP=4,6,7 EU=90D,90D,90D, PART=23
MARKER/2169, PART=16
REQUEST/16
,F1=WDTM(1236,2169)/
,F2=WDTX(1236,2169,2169,2169)/
,F3=WDTY(1236,2169,2169,2169)/
,F4=WDTZ(1236,2169,2169,2169)
In its first column REQUEST/16 contains the magnitude of the angular acceleration vector of Marker 1236
with respect to Marker 2169, as seen in the global coordinate system and measured in the ground reference
frame.
180 Adams Solver
C++ Functions
WDTX
The WDTX function returns the x-component of the difference between the angular acceleration vector of
marker i in the reference frame of marker l and the angular acceleration vector of marker j in the reference
frame of marker l, as computed in the coordinate system of marker k. Marker j defaults to global coordinate
system if it is not specified. Similarly, marker k and l default to global coordinate system if they are not
specified.
Format
WDTX(i[,j][,k][,l])
Arguments

i, if you want j to default to the global coordinate system.
still specifying i, if you want the results to be calculated along the x-axis of the global coordinate
system.
l The reference frame in which the first time derivative of the angular acceleration vector is taken. Set
l = 0 if you want the time derivatives to be taken in the ground coordinate system (GCS).
Extended Definition
Mathematically, WDTX is calculated as follows:
(l) d (l) d ˆ
WDTX ( i ,j ,k ,l ) = ωi – ωj ⋅ xk
dt dt
where:

ˆ
Examples
REQUEST/16
,F1=WDTM(1236,2169)/
,F2=WDTX(1236,2169,2169,2169)/
WDTX 181
C++ Functions
,F3=WDTY(1236,2169,2169,2169)/
,F4=WDTZ(1236,2169,2169,2169)
In its second column REQUEST/16 contains the x-component of the angular acceleration vector of Marker
1236 with respect to Marker 2169, as seen in the global coordinate system of Marker 2169 and measured in
the reference frame containing Marker 2169.
182 Adams Solver
C++ Functions
WDTXYZ
The WDTXYZ measure returns the difference between the angular acceleration vector of marker i and the
angular acceleration vector of marker j resolved in the coordinate system of marker k. All vector time
derivatives are taken in the reference frame of marker l.
Format
WDTXYZ(i[,j][,k][,l])
Arguments

j The marker with respect to which the angular acceleration is being measured. If j is not specified,
it defaults to the global origin. Specify j = 0 if you want to use this default, and then specify k or l.
k The marker in whose coordinate system the angular acceleration vector is being expressed. If not
specified, k defaults to the global coordinate system. Specify k = 0 if you want to use this default,
and then specify l.
l The reference frame in which the first time derivative of the angular velocity vector is taken. Set l
= 0 or omit the argument if you want the time derivative to be taken in the global reference frame.
Extended Definition
Mathematically, WDTXYZ is calculated as:
(l) d (l) d ˆ
 ωi – ωj ⋅ xk 
 dt dt 
   WDTX 
 (l) d (l) d   
WDTXYZ ( i ,j ,k ,l ) =  ωi – ω j ⋅ yˆ k  =  WDTY 
 dt dt   
   WDTZ 
(l) d (l) d
 ωi – ω j ⋅ zˆ k 
 dt dt
where:

(l)
d
dt
 WDTX is the WDTX measure.
 WDTY is the WDTY measure.
WDTXYZ 183
C++ Functions
 WDTZ is the WDTZ measure.

ˆ
Examples
A vector expression for angular acceleration might be used directly in the definition of a vector torque
element:
, TXYZ = -6.*WDTXYZ(310,9900,310)
184 Adams Solver
C++ Functions
WDTY
The WDTY function returns the y-component of the difference between the angular acceleration vector of
frame of marker l, as computed in the coordinate system of marker k. Marker j defaults to the global
coordinate system if it is not specified. Similarly, marker k and l default to the global coordinate system if they
are not specified.
Format
WDTY(i[,j][,k][,l])
Arguments

still specifying i, if you want the results to be calculated along the y-axis of the global coordinate
system.
Extended Definition
Mathematically, WDTY is calculated as follows:
(l) d (l) d
WDTY ( i ,j ,k ,l ) = ωi – ω j ⋅ yˆ k
dt dt
where:
Examples
REQUEST/16
,F1=WDTM(1236,2169)/
,F2=WDTX(1236,2169,2169,2169)/
WDTY 185
C++ Functions
,F3=WDTY(1236,2169,2169,2169)/
,F4=WDTZ(1236,2169,2169,2169)
In its third column REQUEST/16 contains the y-component of the angular acceleration vector of Marker
186 Adams Solver
C++ Functions
WDTZ
The WDTZ function returns the z-component of the difference between the angular acceleration vector of
coordinate system if it is not specified. Similarly, marker k and l default to the global coordinate if they are
not specified.
Format
WDTZ(i[,j][,k][,l])
Arguments

still specifying i, if you want the results to be calculated along the z-axis of the global coordinate
system.
l The reference frame in which the first time derivative of the angular acceleration vector is taken.
Set l = 0 if you want the time derivatives to be taken in the ground coordinate system (GCS).
Extended Definition
Mathematically, WDTZ is calculated as follows:
(l) d (l) d
WDTZ ( i ,j ,k ,l ) = ωi – ω j ⋅ zˆ k
dt dt
where:
Examples
REQUEST/16
,F1=WDTM(1236,2169)/
,F2=WDTX(1236,2169,2169,2169)/
WDTZ 187
C++ Functions
,F3=WDTY(1236,2169,2169,2169)/
,F4=WDTZ(1236,2169,2169,2169)
In its fourth column REQUEST/16 contains the z-component of the angular acceleration vector of Marker
188 Adams Solver
C++ Functions
WM
The WM function returns the magnitude of the angular velocity vector of marker i with respect to marker j.
Marker j defaults to the global coordinate system if it is not specified.
Format
WM(i[,j])
Arguments

Extended Definition
Mathematically, WM is calculated as follows:
WM ( i ,j ) = [ ωi – ωj ] ⋅ [ ωi – ωj ]
where:
Examples
REQUEST/16
,F1=WM(1236,2169)/
,F2=WX(1236,2169,2169)/
,F3=WY(1236,2169,2169)/
,F4=WZ(1236,2169,2169)
In its first column, REQUEST/16 contains the magnitude of the angular velocity vector of Marker 1236 and
Marker 2169.
WX 189
C++ Functions
WX
The WX function returns the x-component of the difference between the angular velocity vector of marker i
in ground and the angular velocity vector of marker j in ground, and expressed in the coordinate system of
marker k. Marker j defaults to the global coordinate system if it is not specified. Similarly, marker k defaults
to the global coordinate system if it is not specified.
Format
WX(i[,j][,k])
Arguments

k The marker in whose coordinate system the velocity vector is being expressed. Set k = 0 if you want
the results to be calculated along the x-axis of the global coordinate system.
Extended Definition
Mathematically, WX is calculated as follows:
ˆ
WX ( i ,j ,k ) = [ ω i – ω j ] ⋅ x k
where:

ˆ
Examples
REQUEST/16
,F1=WM(1236,2169)/
,F2=WX(1236,2169,2169)/
,F3=WY(1236,2169,2169)/
,F4=WZ(1236,2169,2169)
In its second column, REQUEST/16 contains the x-component of the angular velocity Markers 1236 and
2169 as measured in the coordinate system of Marker 2169.
190 Adams Solver
C++ Functions
WXYZ
The WXYZ measure returns the difference between the angular velocity vector of marker i and the angular
velocity vector of marker j resolved in the coordinate system of marker k.
Format
WXYZ(i[,j][,k])
Arguments

j The marker with respect to which the angular velocity is being measured. If j is not specified, it
defaults to the global origin. Specify j = 0 if you want to use this default, and then specify k.
k The marker in whose coordinate system the angular velocity vector is being expressed. If not
specified, k defaults to the global coordinate system.
Extended Definition
Mathematically, WXYZ is calculated as:
 
 [ ωi – ωj ] ⋅ xk   WX 
   
WXYZ ( i ,j ,k ) =  [ ω i – ω j ] ⋅ yˆ k  =  WY 
   
 [ ω i – ω j ] ⋅ zˆ   WZ 
 k
where:
 ωi is the angular velocity vector of marker i in ground.
 ωj is the angular velocity vector of marker j in ground.
 WX is the WX measure.
 WY is the WY measure.
 WZ is the WZ measure.
ˆ

WXYZ 191
C++ Functions
Examples
A vector expression for angular velocity might be used directly in the definition of a vector torque element:
, TXYZ = -6.*WXYZ(310,9900,310)
192 Adams Solver
C++ Functions
WY
The WY function returns the y-component of the difference between the angular velocity vector of marker i
Format
WY(i[,j][,k])
Arguments

j The marker with respect to which the velocity is being measured. Set j = 0, while still specifying
k The marker in whose coordinate system the velocity vector is being expressed. Set k = 0 if you
want the results to be calculated along the y-axis of the global coordinate system.
Extended Definition
Mathematically, WY is calculated as follows:
WY ( i ,j ,k ) = [ ω i – ω j ] ⋅ yˆ k
where:
Examples
REQUEST/16
,F1=WM(1236,2169)/
,F2=WX(1236,2169,2169)/
,F3=WY(1236,2169,2169)/
,F4=WZ(1236,2169,2169)
In its third column, REQUEST/16 contains the y-component of the angular velocity Markers 1236 and
WZ 193
C++ Functions
WZ
The WZ function returns the z-component of the difference between the angular velocity vector of marker i
Format
WZ(i[,j][,k])
Arguments

the results to be calculated along the z-axis of the global coordinate system.
Extended Definition
Mathematically, WZ is calculated as follows:
WZ ( i ,j ,k ) = [ ω i – ω j ] ⋅ zˆ k
where:
Examples
REQUEST/16
,F1=WM(1236,2169)/
,F2=WX(1236,2169,2169)/
,F3=WY(1236,2169,2169)/
,F4=WZ(1236,2169,2169)
In its fourth column, REQUEST/16 contains the z-component of the angular velocity Markers 1236 and
194 Adams Solver
C++ Functions
YAW
The YAW function calculates the first angle of a body-fixed 3 2 1 yaw-pitch-roll rotation sequence between
markers i and j. Marker j defaults to the global coordinate system if it is not specified. Note that yaw is an
Euler angle.
Format
YAW(i[,j])
Arguments

Examples
REQUEST/1
,F2=YAW(21,11)/
,F3=PITCH(21,11)/
,F4=ROLL(21,11)
This REQUEST statement calculates the yaw, pitch, and roll angles between Markers 21 and 11 for output
purposes.

1
C++ Commands
C++ Commands
You use commands to control the simulation. Commands allow you to modify statements, invoke and
control the simulations, and display simulation output and status information.
Below are the Adams Solver (C++) commands grouped according to their function. Detailed information on
each command can be found by following the links.
a
Type of command: Command name:

Inertia and material data PART
bordered MARKER
FLEX_BODY
Constraints JOINT
MOTION
GCON
Forces ACCGRAV
BEAM
BUSHING
FIELD
FRICTION
GFORCE
SFORCE
SPRINGDAMPER
VFORCE
VTORQUE
SPLINE
STRING
VARIABLE
EQUILIBRIUM
IC
INTEGRATOR
KINEMATICS
LSOLVER
SENSOR
2 Adams Solver
C++ Commands

Output OUTPUT
REQUEST
Simulation ACTIVATE
CONTROL
DEACTIVATE
DIFF
ENVIRONMENT
FILE
LINEAR
PREFERENCES
RELOAD
SAVE
SIMULATE
STOP
Information HELP
INFO
MENU
SHOW
TIME
ACCGRAV 3
C++ Commands
ACCGRAV
The ACCGRAV command redefines and/or lists the data for a ACCGRAV statement.
Format
Arguments
IGRAV=r Respecifies the x component of gravitational acceleration with respect to the ground
JGRAV=r Respecifies the y component of gravitational acceleration with respect to the ground
KGRAV=r Respecifies the z component of gravitational acceleration with respect to the ground
LIST Lists the current values of the data in the ACCGRAV statement.
Examples
ACCGRAV/LIST
This ACCGRAV command lists all the data for the ACCGRAV statement in the dataset.
4 Adams Solver
C++ Commands
ACTIVATE
The ACTIVATE command activates a statement that was previously turned off by the DEACTIVATE command.
Format
Arguments
BEAM Specifies that Adams Solver (C++) is to activate BEAM statements.

CONTACT Specifies that Adams Solver (C++) is to activate CONTACT statements.
CLEARANCE Specifies that Adams Solver (C++) is to activate CLEARANCE statements.
COUPLER Specifies that Adams Solver (C++) is to activate COUPLER statements.
BUSHING Specifies that Adams Solver (C++) is to activate BUSHING statements.
DIFF Specifies that Adams Solver (C++) is to activate DIFF statements.
FE_LOAD Specifies that Adams Solver (C++) is to activate FE_LOAD statements.
FIELD Specifies that Adams Solver (C++) is to activate FIELD statements.
GCON Specifies that Adams Solver (C++) is to activate the GCON statements.
GFORCE Specifies that Adams Solver (C++) is to activate GFORCE statements.
ACTIVATE 5
C++ Commands
ID=id1[,...,id30] Lists up to 30 statement identifiers for statements that Adams Solver (C++)
activates. You may use the ID argument in conjunction with the RANGE
argument.
JOINT Specifies that Adams Solver is to activate JOINT statements.
JPRIM Specifies that Adams Solver (C++) is to activate JPRIM statements.
LIST Indicates that Adams Solver (C++) is to display a list of all the existing elements of
the specified type, along with their current activity status.
MOTION Specifies that Adams Solver (C++) is to activate MOTION statements.
RANGE=id1,id2 Defines a range of statement identifiers for statements that Adams Solver (C++) is
to activate. Adams Solver (C++) activates all statements with identifiers that are
numerically between the given identifiers, inclusively. The range may contain
unused identifiers. You may use the RANGE argument in conjunction with the ID
argument.
Range: id1 < id2

SENSOR Specifies that Adams Solver (C++) is to activate SENSOR statements.
SFORCE Specifies that Adams Solver (C++) is to activate SFORCE statements.
SPRINGDAMPER Specifies that Adams Solver (C++) is to activate SPRINGDAMPER statements.
VFORCE Specifies that Adams Solver (C++) is to activate VFORCE statements.
VTORQUE Specifies that Adams Solver (C++) is to activate VTORQUE statements.
Extended Defintion
The ACTIVATE command, used in conjunction with the DEACTIVATE command, switches Adams Solver
(C++) elements on and off. All Adams Solver (C++) elements are active by default in the input dataset, but
can be deactivated using the DEACTIVATE command. For simulation purposes, when Adams Solver (C++)
activates a statement, the statement appears as though it was always in the dataset. When Adams Solver (C++)
deactivates a statement, the statement effectively disappears from the model. Both the ACTIVATE and
DEACTIVATE commands take effect when you issue the next SIMULATE command.
After the activation of any element, Adams Solver (C++) reprocesses the model at the next SIMULATE
command, as if it had just been read in from the dataset. During the reprocessing, Adams Solver (C++) checks
the entire model for consistency, reinitializes user subroutines, and recomputes initial conditions.
While checking the entire model, Adams Solver (C++) verifies that the model is still valid when the newly
activated elements are included. For example, if an activated JOINT overconstrains a model resulting in an
immobile system, Adams Solver (C++) issues an error message. Adams Solver (C++) also reinitializes all user
subroutines to re-establish functional dependencies. For each element that refers to a user-written subroutine,
Adams Solver (C++) calls the user-written subroutine with IFLAG set to true.
Prior to the actual simulation, Adams Solver (C++) computes initial conditions for the model. If this is the
first simulation, Adams Solver (C++) begins with the positions and velocities specified in the dataset, and
maintains any user-supplied joint initial-conditions and part positions specified as EXACT. If you ran a
6 Adams Solver
C++ Commands
previous simulation, Adams Solver (C++) begins with the final displacements and velocities. Adams Solver
(C++) then adjusts the initial conditions to ensure that they are consistent with the model constraints.
Tip: Use the ACTIVATE and DEACTIVATE commands after a FILE or RELOAD command to
set up the model for a particular loadcase or configuration.
Examples
ACTIVATE/SFORCE,ID=201,202
This ACTIVATE command activates SFORCEs 201 and 202.
ACTIVATE/JPRIM,RANGE=400,499
This ACTIVATE command activates JPRIMs 400 and 499, and all JPRIMs with identifiers between 400 and
499.
See other Simulation available.
ARRAY 7
C++ Commands
ARRAY
The ARRAY command redefines and/or lists the array of up to 1,200 real numbers for an IC-type ARRAY
statement.
Format
ARRAY/id [,NUMBERS=r1 [,r2,...]] [,LIST]
Arguments
LIST Lists the number(s) in storage.

[,NUMBERS=r1 [,r2,...]] Respecifies at least one real number to be stored.
Caution: You can use the ARRAY command on only an IC-type ARRAY statement (the default type).
Adams Solver (C++) issues an error message if you specify an X-, U-, or Y-type ARRAY
statement.
Example
ARRAY/12, NUMBERS=0.5,0.12, LIST
8 Adams Solver
C++ Commands
BEAM
The BEAM command redefines and/or lists the data for a BEAM statement. Although you cannot redefine the
I and the J markers, you can redefine any of the other BEAM arguments.
Format
Arguments
AREA=r Respecifies the uniform area of the beam cross-section. The centroidal axis must
be orthogonal to this cross-section.
ASY=r Respecifies the correction factor for shear deflection in the y direction for
Timoshenko beams.
ASZ=r Respecifies the correction factor for shear deflection in the z direction for
Timoshenko beams.
CMATRIX=r1,...,r21 Respecifies the six-by-six damping matrix for the beam. Because this matrix is
symmetric, you need to specify only one-half of it, that is, twenty-one entries. The
units for the translational and rotational components of CMATRIX should be
force-time per displacement unit and torque-time per radian, respectively.
CRATIO=r Respecifies the ratio for calculating the structural damping matrix for the beam.
Adams Solver (C++) multiplies the stiffness matrix by the value of CRATIO to
obtain the damping matrix.
EMODULUS=r Respecifies Young’s modulus of elasticity for the beam material.
GMODULUS=r Respecifies the shear modulus of elasticity for the beam material.
BEAM 9
C++ Commands
IXX=r Denotes the torsional constant. This is sometimes referred to as the torsional
shape factor or torsional stiffness coefficient. It is expressed as unit length to the
fourth power.
For a solid circular section, Ixx is identical to the polar moment of inertia
where r is the radius of the cross-section.
For thin-walled sections, open sections, and noncircular sections, you should
consult a handbook.
IYY=r,IZZ=r Denotes the area moments of inertia about the neutral axes of the beam cross
sectional area (y-y and z-z). These are sometimes referred to as the second
moment of area about a given axis. They are expressed as unit length to the fourth
power.
For a solid circular section, Iyy=Izz= where r is the radius of the cross-
section.
For a thin-walled sections, open sections, and noncircular sections, the user
should consult a handbook.
LENGTH Respecifies the undeformed length of the beam along the x-axis of the J marker.
LIST Lists the current values of the data in the BEAM statement.

10 Adams Solver
C++ Commands
BUSHING
The BUSHING command redefines and/or lists the data for a BUSHING statement. Although you cannot
define the I and J markers defining the bushing, you can redefine other characteristics of the bushing.
Format
Arguments
C=r1,r2,r3 Respecifies three viscous damping coefficients for the force transferred by the
bushing.
CT=r1,r2,r3 Respecifies three viscous damping coefficients for the torque transferred by the
bushing.
FORCE=r1,r2,r3 Respecifies three constant force (preload) values.
K=r1,r2,r3 Respecifies three stiffness coefficients for the force transferred by the bushing.
KT=r1,r2,r3 Respecifies three stiffness coefficients for the torque transferred by the bushing.
LIST Lists the current values of the data in the BUSHING statement.
TORQUE=r1,r2,r3 Respecifies three constant torque (preload) values.
Caution: For the rotational constitutive equations to be accurate, at least two of the rotations (a, b, and
c) must be small. That is, two of the three values must remain smaller than 10 degrees. In
addition, if a becomes greater than 90 degrees, b becomes erratic. If b becomes greater than
90 degrees, a becomes erratic. Only c can become greater than 90 degrees without causing
problems. For these reasons, it is best to define your BUSHING such that angles a and b (not
a and c and not b and c) remain small.

CONTROL 11
C++ Commands
CONTROL
The CONTROL command branches program control to the driver subroutine CONSUB (see the CONSUB
subroutine). Adams Solver (C++) passes parameter arguments to the command as an array. Upon completion
of CONSUB, Adams Solver (C++) prompts you for another command.
Format
CONTROL/[FUNCTION=USER(r1[,...,r30])[\]][ROUTINE=libname::subname]
[ ] Optionally select the item.
Arguments
FUNCTION=USER(r1[,...,r30]) Specifies and passes up to thirty constants to a CONSUB driver

subroutine to regulate and control one or more Adams Solver (C++)
simulations. Follow FUNCTION with an equal sign, the character
string USER, and the real values (r1[,...,r30]) to be passed to
CONSUB.
CONSUB.
See ROUTINE Argument for more information.
Caution: Adams Solver (C++) issues an error message and ignores the entire command if a
CONTROL command is issued when no CONSUB driver subroutine is linked with Adams
Solver (C++).
Tip: A CONSUB driver subroutine can be thought of as an Adams command file programmed
in the FORTRAN programming language. The FORTRAN facilities for control and logic
may be used in conjunction with Adams utility subroutines to drive the Adams simulation.
In particular, the MODIFY utility subroutine can be used to issue Adams commands.

12 Adams Solver
C++ Commands
DEACTIVATE
The DEACTIVATE command turns off a statement that was previously turned on by the ACTIVATE
command, or that was active by default.
Format
Arguments
BEAM Indicates that Adams Solver (C++) is to deactivate BEAM statements.

BUSHING Indicates that Adams Solver (C++) is to deactivate BUSHING statements.
CLEARANCE Indicates that Adams Solver (C++) is to deactivate CLEARANCE statements.
CONTACT Indicates that Adams Solver (C++) is to deactivate CONTACT statements.
COUPLER Specifies that Adams Solver (C++) is to deactivate COUPLER statements.
DIFF Specifies that Adams Solver (C++) is to deactivate DIFF statements.
FE_LOAD Specifies that Adams Solver (C++) is to deactivate FE_LOAD statements.
FIELD Indicates that Adams Solver (C++) is to deactivate FIELD statements.
GCON Indicates that Adams Solver (C++) is to deactivate GCON statements.
GFORCE Indicates that Adams Solver (C++) is to deactivate GFORCE statements.
DEACTIVATE 13
C++ Commands
ID=id1[,...,id30] Lists up to 30 statement identifiers for statements that Adams Solver (C++) is to
deactivate. You may use the ID argument in conjunction with the RANGE
argument.
JOINT Indicates that Adams Solver (C++) is to deactivate JOINT statements.
JPRIM Indicates that Adams Solver (C++) is to deactivate JPRIM statements.
LIST Indicates that Adams Solver (C++) is to display a list of all the existing elements of
the specified type, along with their current activity status.
MOTION Indicates that Adams Solver (C++) is to deactivate MOTION statements.
RANGE=id1, id2 Indicates a range of statement identifiers for statements that Adams Solver (C++) is
to deactivate. Adams Solver (C++) deactivates all statements with identifiers that are
numerically between the given identifiers, inclusively. The range may contain
unused identifiers. You may use the RANGE argument in conjunction with the ID
argument.
Range: id1 < id2

SENSOR Indicates that Adams Solver (C++) is to deactivate SENSOR statements.
SFORCE Indicates that Adams Solver is to deactivate SFORCE statements.
SPRINGDAMPER Indicates that Adams Solver (C++) is to deactivate SPRINGDAMPER statements.
VFORCE Indicates that Adams Solver (C++) is to deactivate VFORCE statements.
VTORQUE Indicates that Adams Solver (C++) is to deactivate VTORQUE statements.
Extended Definition
The DEACTIVATE command, used in conjunction with the ACTIVATE command, switches Adams Solver
(C++) elements off and on. All Adams Solver (C++) elements are active by default in the input dataset, but
some may be deactivated using the DEACTIVATE command. For simulation purposes, when Adams Solver
(C++) deactivates a statement, the statement effectively disappears from the model. When a statement is
activated, the statement appears as though it were always in the dataset. Both the DEACTIVATE and
ACTIVATE commands take effect when you issue the next SIMULATE command. Once deactivated, a
statement remains inactive until it is activated using an ACTIVATE command.
After the deactivation of any element, Adams Solver (C++) reprocesses the model at the next SIMULATE
command as if it had just been read in from the dataset. During the reprocessing, Adams Solver (C++) checks
Adams Solver (C++) reports zero forces for the inactive element if a force request or force graphic refers to an
inactive element. Additionally, references to deactivated elements in function expressions evaluate to zero.
Adams Solver (C++) also reinitializes all user subroutines to re-establish functional dependencies. For each
element that refers to a user-written subroutine, Adams Solver (C++) calls the user-written subroutine with
IFLAG set to true.
first simulation, Adams Solver (C++) begins with the positions and velocities specified in the dataset. If you
14 Adams Solver
C++ Commands
ran a previous simulation, Adams Solver (C++) begins with the final displacements and velocities. Adams
Solver (C++) then adjusts the initial conditions to ensure that they are consistent with the model constraints.
If this is the first simulation, Adams Solver (C++) also maintains any user-supplied joint initial-conditions
and part positions specified as EXACT.
Adams Solver (C++) reports zero values in all output files for any forces associated with inactive elements,
including both applied forces and joint reaction forces. This includes force requests, force graphics, and forces
in the Results File.
Tip: Typically, you use DEACTIVATE and ACTIVATE to set up the model for a particular
loadcase or configuration after a FILE or RELOAD command.
Caution: Deactivating elements may produce strong discontinuities in the model causing convergence
difficulties and reduced integrator performance. It is important that you use these commands
carefully to avoid discontinuities.
Examples
DEACTIVATE/JOINT,ID=71,72,73
This DEACTIVATE command deactivates JOINTs 71, 72, and 73.
DEACTIVATE/SENSOR,RANGE=5,10
This DEACTIVATE command deactivates all SENSORs with identifiers between 5 and 10, including 5 and
10.
You can turn off contact forces in your model during a simulation by using the DEACTIVATE command in
the .acf file.
SIMULATE/TRANSIENT, END=1.0, STEPS=100
DEACTIVATE/CONTACT,ID=1,3, LIST
SIMULATE/TRANSIENT, DURATION=1.0, STEPS=100
This simulates four active contact elements for one second, disabling two out of four contacts, then
continuing the simulation for another second. The LIST argument is useful for obtaining feedback in the
.msg file on the status of active elements. When deactivation has taken place, you will see a similar message:
CONTACT/1, INACTIVE CONTACT/2, ACTIVE CONTACT/3, INACTIVE CONTACT/4, ACTIVE
DEBUG 15
C++ Commands
DEBUG
The DEBUG command redefines and/or lists the data for a DEBUG statement. See the DEBUG statement for
more information.
Format
16 Adams Solver
C++ Commands
Arguments
DUMP Writes the current representation of a dataset to the Message File. This facility essentially saves the
system at the current time and also provides numeric values for functions and orientations.
Default: Off
monitor the simulation process and to locate the source of the error if there is a problem. Each step
consists of two phases: 1) a forward step in time (the predictor for dynamics) and 2) the solution of
the equations of motion (the corrector for dynamics). For the first phase, Adams Solver prints out the
following information:
measure of how hard Adams Solver is working.
Solver uses to predict the solution at the end of the integration step.
For the second phase, Adams Solver prints out the cumulative number of iterations and a table of
information about the iterations. The cumulative number of iterations is a running count of the
iterations needed to solve the equations of motion and can be used as a measure of how many
computations Adams Solver is performing. The table contains information about the maximum
equation error and maximum variable change for each iteration. For each iteration, Adams Solver
prints out the following information:
Adams Solver converges to a solution or exceeds the maximum allowable number of iterations.
 The largest (in absolute value) equation residual. Each equation should have an error value close to
zero. This number is an indicator of how far Adams Solver is from a solution. This number should
decrease after every iteration.
change variables very much. This number is an indicator of how far Adams Solver needs to change
variables to approach a solution. This number should decrease after every iteration.
 If Adams Solver has updated the Jacobian, YES appears under the new Jacobian header.
Default: NOEPRINT
DEBUG 17
C++ Commands
JMDUMP Dumps the Jacobian matrix at each iteration. The Jacobian is dumped in the working directory in the
file with extension *.jac and root name equal to the one of the message file.
Default: NOJMDUMP
LIST Lists the current values of the data in the DEBUG statement.
NOEPRINT Suppresses the printing of three numbers at each integration step and five numbers at each corrector
iteration during an integration.
Default: NOEPRINT
NOJMDUMP Disables the dumping of the Jacobian matrix at each iteration.
Default: NOJMDUMP
NOREQDUM Disables the dumping of REQUEST and MREQUEST statement output at each iteration.
P
Default: NOREQDUMP
NORHSDUM Disables the dumping of the YY array (state vector), the RHS array (error terms), and the DELTA array
P (increment to state vector) at each iteration.
Default: NORHSDUMP
NOVERBOSE Deactivates the output of explanations and possible remedies and the output of the names of
subroutines from which Adams Solver sends diagnostics.
Default: NOVERBOSE
REQDUMP Enables the dumping of the REQUEST and the MREQUEST statement output at each iteration.
Default: NOREQDUMP
RHSDUMP Dumps the values of the right-hand-side vector and states in the solution of each AX=b linear problem.
The states and right-hand-side are dumped in the working directory in the file with extension *.rhs
and root name equal to the one of the message file.
Default: NORHSDUMP
VERBOSE Outputs to the screen such additional information as the name of the subroutine from which Adams
Solver sends each diagnostic, explanations, and possible remedies (when available). If you do not
include the VERBOSE argument, Adams Solver outputs to the screen only basic error messages.
Whether or not you include the VERBOSE argument, Adams Solver outputs VERBOSE information
to the Message File.
Default: NOVERBOSE
MATLAB When specified in conjunction with the RHSDUMP or JMDUMP flags it changes the output format
to be such that the debug information can be easily imported into Matlab. Importing for example the
18 Adams Solver
C++ Commands
Extended Definition
Of all the arguments in the DEBUG command, EPRINT is perhaps the most useful. This section explains
the EPRINT argument in detail.
The kinematic, dynamic, and quasi-static analyses in Adams Solver involve the solution of the governing
equations of motion. Static analysis is the solution of the equilibrium and the initial conditions analysis solves
the assembly equations at a particular point in time.
The equations to be solved, for all these analyses, are non-linear algebraic or differential-algebraic equations.
The solution of these equations is an iterative process. The EPRINT argument enables Adams Solver to write
out the information pertaining to the solution process in a succinct and understandable format. All analyses
that march through time consist of two distinct phases: predictor phase and corrector phase.
Predictor Phase
In order to proceed efficiently from one time to the next, Adams Solver uses a predictor. The predictor is
simply a means of estimating the values of the system state by looking at the past values of the state and
extrapolating the data based on a simple curve fitting algorithm.
Consider a series of values yi defined at discrete times ti
where i=1...n. A simple first order predictor that may be used to predict the value yn+1 at tn+1 is:
where superscript p implies a predicted value. This is shown graphically in Figure 1.
Figure 1 First Order Predictor
You can easily surmise from Figure 1, a first order predictor simply consists of connecting the points yn-1 and
yn with a straight line and extending it to time tn+1.
DEBUG 19
C++ Commands
A second order predictor, similarly, can be thought of as constructing a parabola between the points (tn-2, yn-
2), (tn-1, yn-1) and (tn, yn) and extending the parabola to time tn+1. The predicted value of y at tn+1 is the
intersection of the vertical line t=tn+1 with this parabola. Predictors are typically polynomials (linear,
quadratic, cubic and so on.) and the order of the polynomial is frequently called the order of the solution
method.
For kinematic analyses, Adams Solver employs a first or second order predictor. For quasi-statics, a first order
predictor is used. For dynamic analyses much higher order predictors are used. The BDF methods (GSTIFF
and WSTIFF) use up to six order predictors. ABAM on the other hand can use up to a 12th order predictor.
Sophisticated numerical analysis is employed to determine the most appropriate order of prediction to use at
any given step.
Furthermore, sophisticated curve fitting methods like Newton-Divided Difference tables are usually
employed to efficiently predict the system state. Figure 2 shows the format of the output produced by the
EPRINT argument and explains the data pertinent to the predictor phase of a dynamic analysis step.
The predictor polynomials used for the dynamic analyses interpolate previous values and the slope of the
variable at the current time to estimate the solution at the next time. Therefore, in Figure 5, a second order
polynomial that fits the solution at times t4 and t5 and the slope of the solution at time t5 is used to predict
the value of the solution at time t6.
Figure 2 A Successful Integration Step
Corrector Phase
20 Adams Solver
C++ Commands
Since all predictors simply look at past values to estimate the solution at the next time, the predicted values
almost never satisfy the governing equations. They simply constitute a good initial guess for the solution. The
refining of the predicted solution to one that satisfies the governing equations is called the correction. Since
the governing equations are usually non-linear, an iterative scheme like Newton-Raphson iterations are used.
This methodology is explained for the simplest case of one non-linear algebraic equation in one variable. Let
f(x) be a smooth function of a single variable x. Given an initial guess x=x0, a solution x=xc that satisfies f(x)=0
is desired for this simple example. The Newton-Raphson iterations may be expressed as:
for i=0 ... max_no_iterations. ε is a small user-defined number that specifies the convergence criterion.
1. Evaluate ri = f(xi)
2. If || err(xi) || < ε return xi as the solution

where err(xi) is the error measure being maintained during Newton Raphson iterations
3. Evaluate
Ji = ∂f
∂ x x = xi
4. Calculate
–1
Δx i = J i r i
5. Set x i = x i + Δx i
6. Set i = i+1 and go to Step 1.

The quantity ri is frequently called the residual and is a measure of the accuracy of the solution. The quantity
Ji is the partial derivative of f with respect to x, evaluated at x=xi and is commonly known as the Jacobian.
The graph on the left side of Figure 3 illustrates the Newton-Raphson iterations for the one-dimensional
example discussed above.
DEBUG 21
C++ Commands
Figure 3 The Newton-Raphson Algorithm for a Single Nonlinear Equation
J0 is the slope of the curve f(x) at x=x0. Through simple trigonometry it can be seen that x0-x1 = r0/J0 (i.e.,
x1 = x0 - r0/J0).
22 Adams Solver
C++ Commands
Similarly,
The corrector in Adams Solver involves the solution of many variables simultaneously. The algorithm for one
dimension is easily extended to n dimensions as follows:
Let x = {x1, x2,... xn} be a set of n variables and f = {f1(x), f2(x),... fn(x)} be a set of n non-linear equations in
the variables x.
Define:
J= ,
where i=1,...,n and j=1,...,n. Then the Newton-Raphson iterations for the n-dimensional case becomes: given
an initial guess x = x0 = {x01, x02,... x0n} for i=0,...,max_no_interations. is a small user-defined number
that specifies the convergence criterion.
2. If || ri || < return x = xi as the solution
3. Calculate , where j=1,...,n and k=1,...,n
4. Evaluate
5. Set ,
For the n-dimensional case, evaluating the Jacobian Ji and its inverse at each iteration can be quite expensive
and is the most expensive part of the iteration process. In order to decrease the computational overhead, the
Jacobian Ji is not evaluated at each iteration. It is only updated periodically. This technique can dramatically
increase the overall speed of the corrector iterations and is termed Modified Newton-Raphson iterations.
The graph on the right side of Figure 3 demonstrates the use of the Modified Newton-Raphson iterations to
solve the one-dimensional problem f(x)=0. In this example, the initial Jacobian f’(x0) is re-used for the first 4
corrections before it is re-evaluated for iteration 5. The data are shown in Figure 4 for the modified Newton-
DEBUG 23
C++ Commands
Raphson iterations in a dynamic analysis. The numbers on the left are the values of the maximum residuals
at each iteration. The maximum corrections are on the right. In practice, the convergence rate of the iterations
is used to determine whether a Jacobian evaluation is to be performed or not.
Figure 4 The Modified Newton-Raphson Algorithm for a System of Non-linear Equations
Figure 5 Predictor Polynomial and Corrected Value
The DEBUG/EPRINT option generates a table of data on the action of Adams Solver for each of the iterative
algorithms in the various analyses. The iterative algorithm, or corrector, is used to evaluate the variables
governed by the system of non-linear equations. Table 1 contains the DEBUG/EPRINT information for the
variables associated with the mass-bearing elements (parts, point masses, and flexible bodies) and for the
corresponding equations. A combination of several equations is needed to define each joint and joint
primitive. Table 2 includes the variables for the various joint constraints and the corresponding equations.
24 Adams Solver
C++ Commands
Adams Solver uses a combination of equations to represent the different types of forces. While certain
equations are specific to a particular force, others are generic to all types. The combination of variables and
corresponding equations for the forces are included in Table 3. The DEBUG/EPRINT information for the
variables and corresponding equations that define the Adams system elements is contained in Table 4. Finally,
Table 5 includes the information on the variables and equations for the remaining miscellaneous elements in
an Adams system.
Table 1 Mass Bearing Elements Debug Descriptions
EQUATIONS VARIABLES
Element
type: Code: Explanation: Code: Explanation:
Parts X Force Translational force, X Vel Translational coordinate,
x-direction, GCS x-direction, GCS
Y Force Translational force, Y Vel Translational coordinate,
y-direction, GCS y-direction, GCS
Z Force Translational force, Z Vel Translational coordinate,
z-direction, GCS z-direction, GCS
X Vel Kin Velocity equation, X Disp Translational coordinate,
Eqn x-coordinate, GCS x-direction, GCS
Y Vel Kin Velocity equation, Y Disp Translational coordinate,
Eqn y-coordinate, GCS y-direction, GCS
Z Vel Kin Velocity equation, Z Disp Translational coordinate,
Eqn z-coordinate, GCS z-direction, GCS
Psi Torque Torque, the ψ component Psi Vel Rotational rate, first component, 3-
1-3 Euler angles, GCS
Theta Torque, the θ component Theta Rotational rate, second component, 3-
Torque Vel 1-3 Euler angles, GCS
Phi Torque Torque, the φ component Phi Vel Rotational rate, third component, 3-
1-3 Euler angles, GCS
Psi Vel Kin Equation for the time- Psi Rotational coordinate, first
Eqn derivative of the ψ Angle component, 3-1-3 Euler angles, GCS
coordinate
Theta Vel Equation for the time- Theta Rotational coordinate, second
Kin Eqn derivative of the Angle component, 3-1-3 Euler angles, GCS
θ coordinate
Phi Vel Kin Equation for the time- Phi Rotational coordinate, third
Eqn derivative of the Angle component, 3-1-3 Euler angles, GCS
φ coordinate
DEBUG 25
C++ Commands
EQUATIONS VARIABLES
Element
Psi Algebraic equation for the Psi Rotational rate, first component, 3-
Momentum ψ component of the Mom 1-3 Euler angles, GCS
angular momentum
Theta Algebraic equation for the Theta Rotational rate, second component,
Momentum θ component of the Mom 3-1-3 Euler angles, GCS
angular momentum
Phi Algebraic equation for the Phi Rotational rate, third component, 3-
Momentum φ component of the Mom 1-3 Euler angles, GCS
angular momentum
Flexible X Force Translational force, X Vel Translational coordinate,
Bodies x-direction, GCS x-direction, GCS
Y Force Translational force, Y Vel Translational coordinate,
Z Force Translational force, Z Vel Translational coordinate,
X Vel Kin Velocity equation, X Disp Translational coordinate,
Eqn x-coordinate, GCS x-direction, GCS
Y Vel Kin Velocity equation, Y Disp Translational coordinate,
Eqn y-coordinate, GCS y-direction, GCS
Z Vel Kin Velocity equation, Z Disp Translational coordinate,
Eqn z-coordinate, GCS z-direction, GCS
Psi Torque First of three equations of Psi Vel Time-derivative of the ψ coordinate
motion for torque
Theta Second of three equations Theta Time-derivative of the θ coordinate
Torque of motion for torque Vel
Phi Torque Third of three equations of Phi Vel Time-derivative of the φ coordinate
motion for torque
Psi Vel Kin Equation for the time- Psi Rotational coordinate, first
Eqn derivative of the ψ Angle component, 3-1-3 Euler angles, GCS
coordinate
Theta Vel Equation for the time- Theta Rotational coordinate, second
Kin Eqn derivative of the Angle component, 3-1-3 Euler angles, GCS
θ coordinate
Phi Vel Kin Equation for the time- Phi Rotational coordinate, third
Eqn derivative of the Angle component, 3-1-3 Euler angles, GCS
φ coordinate
26 Adams Solver
C++ Commands
EQUATIONS VARIABLES
Element
Psi Algebraic equation for the Psi ψ component of the angular
Momentum ψ component of the Mom momentum
angular momentum
Theta Algebraic equation for the Theta θ component of the angular
Momentum θ component of the Mom momentum
angular momentum
Phi Algebraic equation for the Phi φ component of the angular
Momentum φ component of the Mom momentum
angular momentum
Modal Force Inertial equations for modal QD 'j' Time-derivatives of modal
'j' coordinates for 1 ≤ j ≤ coordinates for 1 ≤ j ≤ number of
number of flexible modes flexible modes
Modal Kin Equation for the time- Q 'j' Modal coordinates for 1 ≤ j ≤
Eqn 'j' derivatives of modal number of flexible modes
coordinates for 1 ≤ j ≤
number of flexible modes
Point X Force Translational force, X Vel Translational velocity,
Masses x-direction, GCS x-direction, GCS
Y Force Translational force, Y Vel Translational velocity,
Z Force Translational force, Z Vel Translational velocity,
Table 2 Joint and Joint Primitive Debug Descriptions
EQUATIONS VARIABLES
Element type: Code: Explanation: Code: Explanation: Notes:
Joint Initial X Delta At Point Constraint LAM Reaction Force (x) 1
Condition, (x) xi − xj = 0
Translational Y Delta At Point Constraint LAM Reaction Force (y) 1
(y) yi − y j = 0
Z Delta At Point Constraint LAM Reaction Force (z) 1
(z) zi − zj = 0
Joint Initial xi • yj Angular Constraint (xi, LAM Reaction Torque (xi, 2
Condition, yj) xi • yj = 0 yj)
Rotational zi • xj Angular Constraint (zi, LAM Reaction Torque (zi, 2
xj) zi • xj = 0 xj)
DEBUG 27
C++ Commands
EQUATIONS VARIABLES
zi • yj Angular Constraint (zi, LAM Reaction Torque (zi, 2
yj) zi • yj = 0 yj)
Cylindrical zi • xj Angular Constraint (zi, LAM Reaction Torque (zi, 2
Joint xj) zi • xj = 0 xj)
s • xj Sliding Constraint (s, LAM Reaction Force (s, xj) 3
xj) s • xj = 0
s • yj Sliding Constraint(s, LAM Reaction Force (s, yj) 3
yj) s • yj = 0
Convel Joint X Delta At Point Constraint LAM Reaction Force (x) 2
(x) xi − xj = 0
Y Delta At Point Constraint LAM Reaction Force (y) 2
(y) yi − yj = 0
(z) zi − zj = 0
xi • yj Angular Constraint (xi, LAM Reaction Torque (xi, 3
yj) xi • yj = 0 yj)
Fixed Joint X Delta At Point Constraint LAM Reaction Force (x) 1
(x) xi − xj = 0
Y Delta At Point LAM Reaction Force (y) 1
Constraint(y) yi − yj =
0
(z) zi − zj = 0
zi • xj Angular Constraint (zi, LAM Reaction Torque (zi, 2
GCON User User defined Constraint LAM Reaction Force or
Torque
Hooke Joint X Delta At Point LAM Reaction Force (x) 2
Constraint(x) xi − xj =
0
28 Adams Solver
C++ Commands
EQUATIONS VARIABLES
(y) yi − y j = 0
(z) zi − zj = 0
Planar Joint zi • xj Angular Constraint (zi, LAM Reaction Torque (zi, 2
s • zj Sliding Constraint (s, LAM Reaction Force (s, zj) 3
zj) s • zj = 0
Rack-&- Alpha • Rotation/Translation LAM Reaction Force ( ) 4
Pinion Joint P Dependency
Revolute Joint X Delta At Point Constraint LAM Reaction Force (x) 1
(x) xi − xj = 0
(y) yi − y j = 0
(z) zi − zj = 0
zi • xj Angular Constraint (zi, LAM Reaction Torque (zi, 2
Screw Joint Alpha • Rotation/Translation LAM Reaction Force ( ) 4
P Dependency
Spherical Joint X Delta At Point Constraint LAM Reaction Force (x) 1
(x) xi − xj = 0
(y) yi − y j = 0
(z) zi − zj = 0
Translational zi • xj Angular Constraint (zi, LAM Reaction Torque (zi, 2
DEBUG 29
C++ Commands
EQUATIONS VARIABLES
s • xj Sliding Constraint (s, LAM Reaction Force (s, xj) 3
xj) s • xj = 0
s • yj Sliding Constraint (s, LAM Reaction Force (s, yj) 3
yj) s • yj = 0
Universal Joint X Delta At Point Constraint LAM Reaction Force (x) 1
(x) xi − xj = 0
(y) yi − yj = 0
(z) zi − zj = 0
zi • zj Angular Constraint (zi, LAM Reaction Torque (zi, 2
zj) zi • zj = 0 zj)
Atpoint Joint X Delta At Point Constraint LAM Reaction Force (x) 1
Primitive (x) xi − xj = 0
(y) yi − yj = 0
(z) zi − zj = 0
Inline Joint Si•Xj Equivalent to Sliding LAM Reaction Force (s, xj) 3
Primitive Constraint (s, xj) s • xj = 0
Orientation zi • xj Angular Constraint (zi, LAM Reaction Torque (zi, 2
Joint Primitive xj) zi • xj = 0 xj)
Parallel Joint zi • xj Angular Constraint (zi, LAM Reaction Torque (zi, 2
Primitive xj) zi • xj = 0 xj)
Perpendicular zi • zj Angular Constraint (zi, LAM Reaction Torque (zi, 2
Joint Primitive zj) zi • zj = 0 zj)
Notes
30 Adams Solver
C++ Commands
1. An At Point Constraint ensures that the origins of the two markers connected by this constraint
remain spatially collocated during the simulation. This constraint is made up of 3 equations for the
displacement between the two markers in the global X, Y and Z directions, respectively. For each of
the equations, a corresponding variable is introduced to represent the constraint reaction in the X, Y
and Z directions, respectively. In Table 3 a at point constraint equation in the n1 direction is denoted
by At_point_constraint(n1) and the corresponding reaction force by Reaction_force(n1).
The three At Point Constraint equations are: xi - xj = 0, yi - yj = 0, and zi - zj = 0.
2. An Angular Constraint ensures that two vectors fixed in separate mass bearing elements (PARTs,
POINT_MASSes, or FLEX_BODY) (MBE) remain mutually perpendicular during the simulation.
This constraint is represented by 1 equation. This equation requires the dot product of the two vectors
to be zero. Corresponding to this equation, a variable is introduced to represent the constraint
reaction torque. In Table 3, this constraint is denoted as Angular Constraint(v1,v2) and its reaction
torque as Reaction Torque(v1,v2).
An Angular Constraint is given as .
3. A Sliding constraint is a constraint between a spanning vector and a direction fixed in a MBE. A
spanning vector is defined as the spatial vector from the origin of marker i to the origin of marker j.
A sliding constraint ensures that a spanning vector remains perpendicular to the vector fixed in a
MBE. This constraint is enforced by 1 equation that sets the dot product between the spanning vector
and the fixed vector to zero. Introduction of this equation in a model causes a variable in the form of
a constraint reaction force to be included in the model. In Table 3, the equation for this constraint is
denoted as Sliding_constraint(s,v1) and the reaction force by Reaction_force(s,v1).
A Sliding constraint is given as .

4. A Rotation/Translation Dependency Constraint requires the angular displacement between two
markers with common z-axes to be a constant (pitch) times the translational displacement between
the origins of these markers. This constraint is represented by one equation and has a corresponding
reaction force. In Table 3, this constraint is represented as Rotation/Translation Dependency and the
reaction force as Reaction Force(). Equation for a Rotation/Translation Dependency Constraint is
given as , where s is the distance travelled along the z-axis, α is the angle of rotation,
and p is the user specified pitch.
DEBUG 31
C++ Commands
Table 3 Force Debug Descriptions
EQUATIONS VARIABLES
BEAM, X Force x direction force equation X Force Force in the 5
BUSHING, x direction
FIELD Y Force y direction force equation Y Force Force in the 5
y direction
Z Force z direction force equation Z Force Force in the 5
z direction
X Torque x axis torque equation X Torque Torque about the 6
x axis
Y Torque y axis torque equation Y Torque Torque about the 6
y axis
Z Torque z axis torque equation Z Torque Torque about the 6
z axis
GFORCE X Force x force equation X Force Force in the x direction 5
Y Force y force equation Y Force Force in the y direction 5
Z Force z force equation Z Force Force in the z direction 5
X Torque x torque equation X Torque Torque in the x direction 6
Y Torque y torque equation Y Torque Torque in the y direction 6
Z Torque z torque equation Z Torque Torque in the z direction 6
MFORCE FQ force equation FQ force

32 Adams Solver
C++ Commands
EQUATIONS VARIABLES
NFORCE X Force x force equation X Force Force in the x direction 5
Translational Force Equation for element Force Force in element 7

SFORCE Mag force Mag
X Force x force equation X Force Force in the x direction 5
Rotational Torque Element torque equation Torque Torque in element 6

SFORCE Mag Mag

DEBUG 33
C++ Commands
EQUATIONS VARIABLES
Translational Force Equation for element Force Force in element 7
Springdamper Mag force Mag
X Force x force equation X Force Force in the x direction 5

Springdamper Mag Mag
VFORCE X Force x force equation X Force Force in the x direction 5
VTORQUE X Torque x torque equation X Torque Torque in the x direction 6

34 Adams Solver
C++ Commands
Notes
5. Force equations and variables: forces are defined via explicit force equations. These equations take the
general form of:
Force_variable - Force_expression = 0
where:
• Force_variable denotes the force in the x, y or z direction, respectively.
• Force_expression is an expression defining the force in terms of state variables and user defined
coefficients.
6. Torque equations are defined in a manner similar to force equations. These equations take the form
of:
Torque_variable - Torque_expression = 0
where:
• Torque_variable denotes the torque in the element in the x, y, or z direction, respectively.
• Torque_expression defines the torque in term of state variables and user defined coefficients.
7. In addition to force and torque equations, element-specific equations and variables can be used to
define force elements. Typically these equations are to define intermediate kinematic quantities used
in force and torque computation.
Table 4 System Elements Debug Descriptions
EQUATIONS VARIABLES
Element
DIFF Func Equation for the ODE DIF Variable for the solution of
the ODE
GSE xj Eqn General, first order state xj Variables for the solution to
equations for 1 ≤ j ≤ number the differential equations.
of states
yj Eqn Algebraic equations for 1 ≤ j ≤ yj Variables for the values of
number of outputs the output equations.
LSE xj Eqn First order linear state xj Variables for the solution to
of states
yj Eqn Linear algebraic equations for yj Variables for the values of
1 ≤ j ≤ number of outputs the linear equations.
DEBUG 35
C++ Commands
EQUATIONS VARIABLES
Element
TFSISO xj Eqn Linear, first order, differential xj Values of the states for the
equations for the single-input, single-input, single-output
single-output transfer function transfer function.
x· = Ax + Bu for
1 ≤ j ≤ number of states.
yj Eqn Linear equation y = Cx + Du in yj Values of the output for the
terms of the states x and the transfer function.
input u.
VARIABLE Func Equation for the variable val Value of the variable
Table 5 Miscellaneous Elements Debug Descriptions
EQUATIONS VARIABLES
Element
type: Code: Explanation: Code: Explanation: Notes:
COUPLER Coupler Constraint relating joint LAM Reaction force
displacements
CVCV X Delta At point constraint (x) LAM Reaction force (x) 2
Y Delta At point constraint (y) LAM Reaction force (y) 2
Z Delta At point constraint (z) LAM Reaction force (z) 2
Xi.Yj Constraint to force the tangent to LAM Constraint torque

curve 1 to be perpendicular to variable
normal to curve 2
CVMK Alpha Curve Marker displacement Alpha Curve Marker alpha
AlphaD Curve Marker AlphaD Time derivative of

Curve Marker alpha
velocity
GEAR Gear Constraint relating displacements LAM Reaction force
in two joints
36 Adams Solver
C++ Commands
EQUATIONS VARIABLES
Element
MOTION JntRtL0 Rotational Joint displacement LAM Reaction force
specified as a function of time
JntRtL1 Rotational Joint velocity specified as LAM Reaction force

a function of time
JntRtL2 Rotational Joint acceleration LAM Reaction force

IJ_RtL0 Rotational I-J Marker displacement LAM Reaction force

IJ_RtL1 Rotational I-J Marker velocity LAM Reaction force

IJ_RtL2 Rotational I-J Marker acceleration LAM Reaction force

MotTrL0 Translational Joint displacement LAM Reaction force

MotTrL1 Translational Joint velocity specified LAM Reaction force

as a function of time
MotTrL2 Translational Joint acceleration LAM Reaction force

IJ_TrL0 Translational I-J Marker LAM Reaction force

displacement specified as a function
of time
IJ_TrL1 Translational I-J Marker velocity LAM Reaction force
IJ_TrL2 Translational I-J Marker LAM Reaction force

acceleration specified as a function
of time
PTCV X Delta At point constraint (x) LAM Reaction force (x) 2
DEBUG 37
C++ Commands
EQUATIONS VARIABLES
Element
Y Delta At point constraint (y) LAM Reaction force (y) 2
Z Delta At point constraint (z) LAM Reaction force (z) 2
SFMK alpha Surface Marker alpha displacement alpha Surface Marker

alpha
beta Surface Marker beta displacement beta Surface Marker beta
alphaD Surface Marker alpha velocity alphaD Time derivative of

Surface Marker
alpha
betaD Surface Marker beta velocity betaD Time derivative of
Surface Marker beta
JMDUMP Format
Adams Solver constantly needs to solve a linear problem JX=b where J stands for Jacobian matrix. Option
JMDUMP will send a representation of the Jacobian matrices to a file. The representation depends on
whether the MATLAB option is used or not. If the MATLAB option is used, then all Jacobian matrices will
be dumped using ready-to-use MATLAB code that can be copied and pasted. For example:
RC Analysis
Jacobian Matrix Statistics for the Pos. Constraints
=====================================================
J = zeros(5,6);
J( 1, 1) = 1;
J( 2, 2) = 1;
J( 3, 3) = 1;
J( 1, 4) = -10;
J( 3, 5) = 10;
J( 5, 5) = -1;
J( 4, 6) = 1;
The first two lines stand for the name of the analysis being done (in this example the Redundant Constraint
Analysis) and a brief description of the Jacobian. Next, the MATLAB representation of the matrix is printed.
Notice that only the nonzero entries are exported.
Usually matrices are square. However, the Redundant Constraint analysis uses a rectangular matrix and no
actual JX=b solution is needed.
38 Adams Solver
C++ Commands
In the case of transient simulations, the title has three lines to include the time at which the Jacobian is
exported. For example:
Time: 0.003
Gstiff Integrator...
Jacobian Matrix Statistics for the Corrector Stage
=====================================================
J = zeros(22,22);
J( 4, 6) = 1000;
J( 13, 6) = 1;
J( 5, 5) = 1000;
J( 15, 5) = 1;
J( 6, 4) = 1000;
J( 17, 4) = 1;
J( 3, 1) = 10000;
J( 6, 1) = -1;
J( 18, 1) = 1;
…
For Dynamic Analysis and other solutions, the Jacobian matrix is square as shown above.
In case the MATLAB option is not used, the format of the Jacobian is the following. First, a title section is
printed (similar as the case of using the MATLAB option) followed by the contributions of each modeling
element. The contribution of each modeling element starts with the name of the element and five columns.
The first column is labelled NP (standing for n-th position). The values of NP are 1 to the number of entries
into the Jacobian matrix the element is contributing to. For example:
Displacement solution for IC analysis

Jacobian Matrix Statistics for the Iteration: 1
=====================================================
Part/2 X Force ID = 2
NP NPOSR NPOSC
1 0 0 Part/2 X Force Part/2 X Disp
2 1 1 Part/2 Y Force Part/2 Y Disp
3 2 2 Part/2 Z Force Part/2 Z Disp
4 3 3 Part/2 Psi Torque Part/2 Psi Angle
5 4 4 Part/2 Phi Torque Part/2 Phi Angle
6 5 5 Part/2 Theta Torque Part/2 Theta Angle
RevJnt/1 X Delta ID = 1
NP NPOSR NPOSC
7 3 6 Part/2 Psi Torque RevJnt/1 LM X Delta
8 4 6 Part/2 Phi Torque RevJnt/1 LM X Delta
9 5 6 Part/2 Theta Torque RevJnt/1 LM X Delta
10 0 6 Part/2 X Force RevJnt/1 LM X Delta
11 6 3 RevJnt/1 X Delta Part/2 Psi Angle
12 6 4 RevJnt/1 X Delta Part/2 Phi Angle
13 6 5 RevJnt/1 X Delta Part/2 Theta Angle
14 6 0 RevJnt/1 X Delta Part/2 X Disp
DEBUG 39
C++ Commands
Notice here that Part/2 contributes with 6 entries into the Jacobian matrix for Initial Conditions analysis.
The revolute joint RevJnt/1 contributes with another set of entries starting at NP equal to 7. The first column
NP is the index of a Jacobian entry. The second and third column show the row and column location of each
entry. The values of rows and columns is zero-based. Finally, the fourth and fifth columns display the name
of the equation the entry belongs to, and the name of the corresponding state of the solution.
After the maps for all elements are printed, the actual values of all entries follow. For each element a list of
entry-value is printed. For example:
NP G(NP)
1 1.00000E+000 2 1.00000E+000 3 1.00000E+000 4 1.00000E+000
5 1.00000E+000 6 1.00000E+000
NP G(NP)
7-1.00000E+001 8 0.00000E+000 9 0.00000E+000 10 1.00000E+000
11-1.00000E+001 12 0.00000E+000 13 0.00000E+000 14 1.00000E+000
15 0.00000E+000 16 0.00000E+000 17 0.00000E+000 18 1.00000E+000
19 0.00000E+000 20 0.00000E+000 21 0.00000E+000 22 1.00000E+000
…
Notice subtitle ‘NP G(NP)’ stands for the n-th position (NP) and the corresponding G(NP) value for the
Jacobian entry.
There is fundamental difference between the default dump format and the dump using the MATLAB option.
In the default format, zero entries may be included in both the map and value tables. Moreover, the map and
value tables may include entries that contribute to the same position in the Jacobian matrix. The MATLAB
option only shows the total value at each entry and it does not print a mapping to show the individual
contributions of the modeling elements.
RHSDUMP Format
For analyses that require solving a linear problem JX=b, option RHSDUMP will send a representation of the
current state values, the actual right-hand side b in equation JX=b, and the value of X after the solution. This
information is printed at each iteration. For example, if using the MATLAB option, a typical output is as
follows:
Time: 0
Displacement IC - State
====================================================
States
====================================================
x(1) = 0.000000000000E+000;
x(2) = -5.000000000000E+000;
x(3) = 0.000000000000E+000;
x(4) = 1.570796326795E+000;
x(5) = 0.000000000000E+000;
...
40 Adams Solver
C++ Commands
Displacement solution for IC analysis - RHS

Statistics for the Iteration: 1
====================================================
Equations
====================================================
rhs(1) = 0.000000000000E+000;
rhs(2) = 0.000000000000E+000;
rhs(3) = 0.000000000000E+000;
rhs(4) = 0.000000000000E+000;
rhs(5) = 0.000000000000E+000;
...
Displacement solution for IC analysis - Delta

====================================================
Equations
====================================================
rhs(1) = 2.514146621547E-016;
rhs(2) = -5.000000000000E+000;
rhs(3) = -6.123233995737E-016;
rhs(4) = -2.464849628968E-017;
rhs(5) = 1.224646799147E-016;
...
Notice, first the states value are printed in a MATLAB array x. Next, array rhs shows the values of b in
equation JX=b (hence the label RHS shown in the title for this array). Finally, the third set shows the solution
X reusing array rsh. Given that the actual solution X usually stands for an incremental correction to the states,
we use the label Delta in the title for this set.
If the MATLAB option is not used, the output looks similar. For example:
Time: 0
====================================================
States
====================================================
1 Part/2 X Disp 0.0000000000E+000
2 Part/2 Y Disp -5.0000000000E+000
3 Part/2 Z Disp 0.0000000000E+000
4 Part/2 Psi Angle 1.5707963268E+000
5 Part/2 Phi Angle 0.0000000000E+000
...

====================================================
Equations
====================================================
1 Part/2 X Force 0.000000000000E+000
2 Part/2 Y Force 0.000000000000E+000
3 Part/2 Z Force 0.000000000000E+000
4 Part/2 Psi Torque 0.000000000000E+000
5 Part/2 Phi Torque 0.000000000000E+000
...
DEBUG 41
C++ Commands

====================================================
Equations
====================================================
1 Part/2 X Force 2.514146621547E-016
2 Part/2 Y Force -5.000000000000E+000
3 Part/2 Z Force -6.123233995737E-016
4 Part/2 Psi Torque -2.464849628968E-017
5 Part/2 Phi Torque 1.224646799147E-016
...
In this case, each group of information shows three columns, the first column shows the index of the state or
the name of the corresponding equation, the second the name of the corresponding state or equation. The
third column shows the corresponding value.
42 Adams Solver
C++ Commands
DIFF
The DIFF command redefines and/or lists the characteristics of a DIFF statement. The implicit/explicit
nature of a DIFF element may not be changed, for example, the IMPLICIT option in the database may not
be changed.
Format
Argument
Redefines an expression or redefines the list of constants passed to

a user-written subroutine, for example, DIFSUB.
IC=r1[,r2] Redefines the value of the differential state. If you specify r2, the
value of r2 will be used to start the computation of the derivative
value of the differential state.
STATIC_HOLD Redefines the differential state to remain constant during static and
quasi-static simulations. Notice the STATIC_HOLD argument
may not be changed (once a differential state is defined as
STATIC_HOLD, it will remain STATIC_HOLD for the rest of
the simulation).
DIFF 43
C++ Commands
DYNAMIC_HOLD Redefines the differential state to remain constant during dynamic

simulations. Notice the DYNAMIC_HOLD argument may not be
changed (once a differential state is defined as
DYNAMIC_HOLD, it will remain DYNAMIC_HOLD for the
rest of the simulation).
DIFSUB.

LIST Lists the current values of the data defining the differential state.
Extended Definition
The DIFF command allows you to list and/or modify the characteristics of a differential state. Adams Solver
(C++) allows you to modify most of the characteristics set in the DIFF statement.
After changes to a DIFF element are processed, Adams Solver (C++) will also reprocess the numerical
solutions to accommodate the changes set in this command.
Examples
DIFF/99, FUNCTION=-2*DIF(99) + SIN(TIME), LIST

DIFF/34, DYNAMIC_HOLD, LIST
See other available SIMULATE commands.
44 Adams Solver
C++ Commands
ENVIRONMENT
Using the ENVIRONMENT command is an alternative way of setting an Adams Solver (C++) runtime
environment variable. For example, rather than using the setenv command when working with the Linux
operating system, one may use the ENVIRONMENT command instead.
One feature of the ENVIRONMENT command is the following, the execution of this command does not
modify the operating system environment; it only affects the Adams Solver (C++) runtime environment for
the model being run. When the simulations are finished, the original operating system environment is left
intact.
A second feature is related to the collection of environment variables one may set. Only environment variables
related to the Adams Solver (C++) may be set. For example, you may not use this command to set an
environment variable used by other products.
Format
ENVIRONMENT ⁄ NAME = c [ ,LIST ]
ENVIRONMENT ⁄ NAME = c, VALUE = c [ ,LIST ]
ENVIRONMENT ⁄ NAME = c, UNSET [ ,LIST ]
Arguments
NAME=c Specifies a character string for the name of the Adams Solver (C++) runtime environment
variable being set.
VALUE=c Specifies a character string for the value of the Adams Solver (C++) runtime environment
variable being set. Some variables do not need a value to be specified.
The character string may be enclosed between double quotes.

UNSET Specifies the removal of the variable from the Adams Solver (C++) runtime environment.
LIST Lists all Adams Solver (C++) runtime environment variables found.
Extended Definition
The operating system environment stands for a set of environment variables. Each of these environment variables
has a name, and it may have an associated value. Both name and value are character strings set by the user
using tools provided by the operating system.
The use of environment variables provides a simple mechanism to let users communicate preferences to a
running computer program. The use of environment variables is a practical way to trigger the execution of
undocumented features, workarounds, experimental methods, etc. without the need to modify the
AMD/ACF language layers of the Adams Solver (C++).
When the execution of Adams Solver (C++) starts, all the environment variables are scanned and the Adams
Solver (C++) runtime environment is created. The Adams Solver (C++) runtime environment is initialized
with all the environment variables that the Adams Solver (C++) recognizes. Environment variables used by
vertical applications or other products are not included in the Adams Solver (C++) runtime environment.
ENVIRONMENT 45
C++ Commands
Next, when the model is being read, all of the ENVIRONMENT statements are processed one by one in the
same order they are found in the ADM dataset file. The ENVIRONMENT statements will update or modify
the Adams Solver (C++) runtime environment. If there is at least one ENVIRONMENT statement in the
dataset file, Adams Solver (C++) prints a report of all the Adams Solver (C++) runtime environment variables
and their corresponding values (if any) along with a description of the feature the variable is used for.
You may change the value of an Adams Solver (C++) runtime environment variable using the
ENVIRONMENT command.
The advantages of having the ENVIRONMENT statement and command are:
 It allows setting preferences at the model level rather than at the operating system level.
 It helps reduce the pollution in the operating system environment and better manage the settings.
Examples
1. Let's assume you define the following environment variable from a Linux shell:
% setenv MSC_ADAMS_SOLVER_BEAM_MODEL=LINEAR
Let's assume the ADM dataset file has no ENVIRONMENT statements and that the ACF command
file has the following commands:
ENV/NAME=MSC_ADAMS_SOLVER_BEAM_MODEL, VALUE=NONLINEAR
FILE/MODEL=beam_model
ENV/NAME=MSC_ADAMS_STATICS_NO_RESTORE_VELOCITIES
SIM/STA
Running the model, Adams Solver (C++) will print the following messages:
OS-environment variable
MSC_ADAMS_SOLVER_BEAM_MODEL=LINEAR
command: FILE/COMMAND=beam_model
command:
command: ENVIRONMENT/NAME=MSC_ADAMS_SOLVER_BEAM_MODEL,
VALUE=STRING
User-environment variable
MSC_ADAMS_SOLVER_BEAM_MODEL=STRING
* Overwrites a previous definition.
command:
command: file/model=beam_model
---------------------------------------------------------------
| Model Title |
|==============================================================|
| |
| Beam model |
46 Adams Solver
C++ Commands
| |
----------------------------------------------------------------
command:
command: env/name = MSC_ADAMS_STATICS_NO_RESTORE_VELOCITIES
User-environment variable
MSC_ADAMS_STATICS_NO_RESTORE_VELOCITIES
Enforces Adams Solver C++ not to restore initial velocities after
a STATIC analysis at time t=0.
Observe Adams Solver prints two messages regarding the

MSC_ADAMS_SOLVER_BEAM_MODEL variable. The first one is printed when processing the
operating system environment. The second one is printed when processing the ENVIRONMENT
command. Notice the message "Overwrites a previous definition" indicating that the
ENVIRONMENT command overwrote the value of the environment variable set in the operating
system.
2. In this example the ENVIRONMENT command generates an error message. Let's assume the ACF
command file is the following:
FILE/MODEL=beam_model
ENVIRONMENT/NAME=MSC_ADAMS_SOLVER_BEAM_MODEL, VALUE=NONLINEAR
SIM/STA
Running the above ACF command file, the following message is printed:
command: environment/name=MSC_ADAMS_SOLVER_BEAM_MODEL,
value=STRING
---- START: ERROR ----

Environment variable MSC_ADAMS_SOLVER_BEAM_MODEL must be set
before the model is constructed.
Command will be ignored.
To avoid this problems do one of these:

(1) Set the env variable in the operating system.
(2) Set the env variable in the *.adm file.
(3) Issue the ENV/ command before the FILE/MODEL command.
---- END: ERROR ----

Adams Solver (C++) prints an error message and ignores the setting of the the
MSC_ADAMS_SOLVER_BEAM_MODEL because the model has already been constructed.
ENVIRONMENT 47
C++ Commands
Caution: Environment variables are typically intended for experimentation and testing of
undocumented features. They may be removed in a future release without notice. Please bear
this in mind when using the ENVIRONMENT statement and command.
See other Simulation command available.

48 Adams Solver
C++ Commands
EQUILIBRIUM
An EQUILIBRIUM command redefines and/or lists the data for an EQUILIBRIUM statement. If an
EQUILIBRIUM statement is not included in the Adams Solver model and an EQUILIBRIUM command
is not issued before a static or quasi-static simulation, Adams Solver (C++) uses the default values for ALIMIT,
ERROR, IMBALANCE, MAXIT, PATTERN, STABILITY, and TLIMIT for the analysis.
Format
 
 
 ALIMIT = r 
 
 ,ERROR = r 
 
 ,IMBALANCE = r 
 
 ,MAXIT = i 
 
 ,PATTERN = c1 [:...: c10] 
 
 ,STABILITY = r 
 
 ,TLIMIT = r 
 
EQUILIBRIUM/   [ ,LIST ]
 
 ,METHOD =i 
 
 ,ATOL = r 
 
 ,RTOL = r 
 
 ,MAXITL = i 
 
 ,ETAMAX = r 
 
 
 ,ETA = r 
 
DEFAULT
{} Select one item

EQUILIBRIUM 49
C++ Commands
Arguments
ALIMIT=r Specifies the maximum angular increment allowed per iteration during a static
or quasi-static equilibrium analysis. The default units for ALIMIT are radians.
To specify ALIMIT in degrees, add a D after the value.
Range: ALIMIT > 0
DEFAULT Resets all options to the default values specified in the EQUILIBRIUM statement,
namely:
ALIMIT = 10D
ERROR = 1.0E-4
IMBALANCE = 1.0E-4
MAXIT = 25
PATTERN = T:T:T:T:T:T:T:T:T:T
STABILITY = 1.0E-5
TLIMIT = 20
ERROR=r Specifies the relative correction convergence-threshold. The iterative process
carried out during the equilibrium analysis can not converge prior to all relevant
relative corrections being smaller than this value.
Range: ERROR > 0
IMBALANCE=r Specifies the equation imbalance convergence threshold. The iterative process
carried out during the equilibrium analysis can not converge prior to each
equation imbalance being smaller than this value.

LIST Lists the current values of the data in the EQUILIBRIUM statment.
equilibrium.
Range: MAXIT > 0

PATTERN=c1[:...:c10] Specifies as many as ten character strings that together establish the pattern for
evaluating the Jacobian matrix during the modified Newton-Raphson iteration.
For each iteration, T or TRUE indicates that Adams Solver (C++) evaluates the
Jacobian and F or FALSE indicates that Adams Solver (C++) does not evaluate
the Jacobian. Thus, cj determines whether or not Adams Solver (C++) evaluates
the Jacobian at the jth iteration. If necessary, Adams Solver (C++) repeats the
pattern of evaluations until it reaches the maximum number of iterations
(MAXIT). The number of Ts or TRUEs and Fs or FALSEs together must be at
least one and no more than ten.
50 Adams Solver
C++ Commands
equilibrium Jacobian matrix) Adams Solver (C++) adds to the stiffness matrix (a
subset of the equilibrium Jacobian matrix) during static simulations performed
using static analyses. Adding a fraction of the mass and damping matrices to the
stiffness matrix can stabilize the iteration process and prevent the iteration from
diverging. Often the stiffness matrix is singular for a system because the system
is neutrally stable (for example, the system moves in certain directions without
affecting the potential energy). Adding a fraction of the mass and damping
matrices to the stiffness matrix removes this singularity and makes it possible to
solve for equilibrium positions. The value of STABILITY does not affect the
accuracy of the solution, but it does affect the rate of convergence of the iteration
process.>
Range: STABILITY >0

Range: TLIMIT > 0

EQUILIBRIUM 51
C++ Commands
METHOD=i Specifies the option which determines the static solver method to be used for
equilibrium solution.
1. ORIGINAL, for running only the ORIGINAL Solver

2. ADVANCED, runs, in order, the following methods until one shows
progress:
a. ORIGINAL
b. ORIGINAL+Krylov
c. ORIGINAL+UMF
d. Newton+Krylov
3. AGGRESSIVE, runs, in order, the following methods until one shows
progress:
a. ORIGINAL
b. ORIGINAL+Krylov
c. ORIGINAL+UMF
d. Newton+Krylov
g. Broyden-Armijo
h. Trust-Region
4. ALL, runs, in order, all the available methods, until one shows progress:
a. ORIGINAL
b. ORIGINAL+Krylov
c. ORIGINAL+UMF
d. Newton+Krylov
g. Broyden-Armijo
h. Trust-Region
i. Hooke-Jeeves
Default: ORIGINAL
ATOL Specifies the absolute tolerance value
Default: 1.0e-6
Range: 0.0 < ATOL < 1.0
52 Adams Solver
C++ Commands
RTOL Specifies the relative tolerance value

For all solvers, except ORIGINAL and ORIGINAL+Krylov, the tolerance is
defined as : TOL=ATOL+||xIC||*RTOL.
For ORIGINAL and ORIGINAL+Krylov solvers the tolerance is equal to
ERROR.
Default: 0.0
Range: 0.0 < RTOL < 1.0
MAXITL Specifies the maximum number of allowed inner loops in all the solvers.
ORIGINAL, ORIGINAL+Krylov and ORIGINAL+UMF solver methods
ignore this parameter. For Hooke-Jeeves method, allowed budget of function
evaluations is set to MAXITL*N, where N is the size of the problem (number of
unknowns).
Default: 40
Range: > 0
ETAMAX Specifies the maximum threshold for the error tolerance of the linear Krylov
solver (for Newton+Krylov and Tensor-Krylov methods) that solves the linear
systems required by Krylov algorithm. Maximum error tolerance for residual in
inner iteration. The inner iteration terminates when the relative linear residual is
smaller than eta*| F(x_c) |. eta is determined by the modified Eisenstat-Walker
formula if etamax > 0. If etamax < 0, then eta = |etamax| for the entire iteration.
Default: 0.9
Range: 0.0 < ETAMAX < 1.0
ETA Specifies the initial residual tolerance for the linear Krylov Solver for Tensor-
Krylov method. The Tensor-Krylov ETA parameter is maintained adaptively by
the Krylov algorithm but ETA is the indicated starting value, while ETAMAX
is the maximum threshold for ETA.
Default: 1.0e-4
Range: 0.0 < ETA < 1.0
Specifies the dimensionless radius of the trust-region for Trust-region method.

The smaller the value, the more the refinement of Trust-region solution (hence
more work).
Range: 0.0 < ETA < 0.25
Extended Definition
For an extended definition on the EQUILIBRIUM command and corresponding tips, cautions, and
examples, refer to the EQUILIBRIUM statement.
FIELD 53
C++ Commands
FIELD
The FIELD command redefines and/or lists the data for a FIELD statement. You cannot redefine the I and the
J markers, but you can redefine any other argument values.
Format
Arguments
CMATRIX=r1,...,r36 Respecifies the six-by-six matrix of viscous damping coefficients. Enter

the elements by columns from top to bottom, then from left to right.
The units for the translational and rotational components of
CMATRIX should be force-time per displacement unit and torque-
time per radian, respectively.
CRATIO=r Respecifies the ratio of CMATRIX to KMATRIX. Adams Solver (C++)
multiplies KMATRIX by CRATIO to obtain CMATRIX.
FORCE=r1,...,r6 Respecifies three preload force components and three preload torque
components transferred by the FIELD element when the I and J
markers are separated/misaligned by the values specified in the
LENGTH argument. The terms r1,...,r6 are the force components
along the x-axis, the y-axis, and the z-axis of the J marker and the torque
components about the x-axis, the y-axis, and the z-axis of the J marker,
respectively. FORCE is optional.
54 Adams Solver
C++ Commands
FUNCTION=USER(r1[,...,r30]) Respecifies the USER parenthetical list for a nonlinear field. Follow
FUNCTION with an equal sign, the character string USER, and the
values (r1[,...,r30]) that you want Adams Solver (C++) to pass to the
FIESUB user-written subroutine. The FUNCTION argument is used,
it must either be the last argument in the FIELD command or be
followed by a backslash (\).
KMATIX=r1,...r36 Respecifies the six-by-six matrix of stiffness coefficients. The units for
the translational and rotational components of KMATRIX should be
force per displacement unit and torque per radian, respectively. Enter
LENGTH=r1,...r6 Respecifies six reference length angles. This is the nominal position of
the I marker with respect to the J marker, resolved in the J marker
coordinate system. The terms r1,...,r6 are the x, y, and z translational
components (specified in linear displacement units) of the
displacement between the I and J markers; and a, b, and c are rotational
displacement of the axes of the I marker with respect to the J marker,
resolved in the J marker axes (specified in radians). If the reference force
is zero, LENGTH is the same as the free length.
LIST Lists the current values of the data in the FIELD statement.
ROUTINE=libname::subname Specifies an alternative library and name for the user subroutine FIESUB.
Tip: Finite element analysis programs can give the values for CMATRIX and KMATRIX.
FIELD 55
C++ Commands
Caution:  The three rotational displacements (a, b, and c) that define the field are not Euler angles.
They are the projected angles of the I marker with respect to the J marker. Adams Solver
(C++) measures them about the x-, y-, and z-axis of the J marker.
 For the constitutive equations to be accurate, at least two of the rotations (a, b, c) must be
small. That is, two of the three values must remain smaller than 10 degrees. In addition, if
a becomes greater than 90 degrees, b becomes erratic. If b becomes greater than 90 degrees,
a becomes erratic. Only c can become greater than 90 degrees without causing convergence
problems. For these reasons, it is best to define your field such that angles a and b (not a
and c and not b and c) remain small.
 Adams Solver (C++) applies the component translational and rotational forces for a field to
the I marker and imposes reaction forces on the J marker.
 The FIELD command allows you to define all six-component, action-reaction forces.
However, when massless beams are being defined, you may want to use the BEAM
command. It requires only six input values to compute the thirty-six values for the
KMATRIX argument (see the BEAM statement).

Similarly, the damping matrix may be adding energy to the system. Both of these situations
are uncommon. Adams Solver (C++) does not warn you if the C matrix, K matrix, or both
are not positive semidefinite. While Adams Solver (C++) does not require that these
matrices be symmetric, that is most realistic.

56 Adams Solver
C++ Commands
FILE
The FILE command loads a new model from a dataset file, or executes commands from a Command file.
Format
Arguments
COMMAND=c Specifies the file name of a file that contains Adams Solver (C++) commands. The
file name may include the directory on operating systems that support path
names, such as Linux. Adams Solver (C++) assumes an .acf file extension if you do
not specify one. Because the COMMAND argument and value can be at most
eighty characters long, the file name and path name are limited from seventy-two
characters (if you do not abbreviate COMMAND=) to seventy-six characters (if
you abbreviate COMMAND= to COM=).
Range: All printable characters except “!”, “;”, “,” and “&”
MODEL=c Specifies the file name of an Adams Solver (C++) model definition file.
The file name may include the directory on operating systems that support path
names, such as Linux. Adams Solver (C++) assumes an .adm file extension if you
do not specify one. Because the argument and value can be at most eighty
characters long, the file name and path are limited from seventy-three characters
(if you do not abbreviate MODEL=) to seventy-six characters (if you abbreviate
MODEL= to MOD=).
OUTPUT_PREFIX=c Optionally, specifies a new file base name for output files that Adams Solver (C++)
generates by subsequent simulations. The file extensions conform to standard
Adams Solver (C++) naming conventions. If you do not specify an
OUTPUT_PREFIX argument, Adams Solver (C++) defaults to the basename of
the MODEL argument. Because the OUTPUT_PREFIX argument and value can
be at most eighty characters long, the basename and path are limited from sixty-
six characters (if you do not abbreviate OUTPUT_PREFIX) to seventy-six
characters (if you abbreviate OUTPUT_PREFIX to OUT=).
FILE 57
C++ Commands
Extended Definition
The FILE command either restarts Adams Solver (C++) with a new model, or a executes a set of commands
from a file.
The MODEL argument specifies a new dataset (.adm) file. Adams Solver (C++) closes any output files from
a previous simulation, and then completely restarts by setting the simulation time to zero and reading the
new model. Next, Adams Solver (C++) prompts you for a new command, just as if Adams Solver (C++) had
read the model when first started. By default, the output files use the same base name as the model file. The
optional OUTPUT_PREFIX argument specifies a different base name, if needed. An OUTPUT_PREFIX
argument only changes the names of the output files (files with .res, .req, and .gra extensions). A message file
with a new name is not created. Every message from a single Adams Solver (C++) session is logged in the same
message file.
The COMMAND argument specifies a file containing Adams Solver (C++) commands. Adams Solver (C++)
reads and executes the commands in the file. If the FILE command was interactive, Adams Solver (C++)
returns to interactive input when the command file is exhausted. If the FILE command was in a command
file itself, Adams Solver (C++) returns to reading commands from that file. Command files can contain other
FILE commands.
Tip:  The FILE/MODEL= command allows you to execute a series of simulations within one
Adams Solver (C++) run. This may be quicker and more convenient than invoking Adams
Solver (C++) separately for each simulation.
 Although the FILE command may be used to repeatedly reload the same model, the SAVE
and RELOAD combination is much quicker than rereading the original dataset.
Caution:  The COMMAND argument does not automatically load a new model, it executes
commands just as they appear in the specified file. Unlike a Command file used to start
Adams Solver (C++), a Command file read here must start with an Adams Solver (C++)
command, not input and output file names.
 Since Adams Solver (C++) does not support TIRE 5.2.1, the TIRE_LIST_FILE is not
supported.
Examples
FILE/MODEL=TURN45
This FILE command loads dataset TURN45.ADM. The output files default to TURN45.REQ,
TURN45.GRA, etc.
FILE/MODEL=TURN45,OUTPUT_PREFIX=TEST2
This FILE command also loads dataset TURN45.ADM, but the output files are TEST2.REQ,
TEST2.GRA, etc.
58 Adams Solver
C++ Commands
FLEX_BODY
The FLEX_BODY command redefines and/or lists the data for the FLEX_BODY statement that defines linear
elastic body.
Format
Arguments
Redefines modal damping as a fraction of critical damping. You can

specify modal damping using a function expression or a user-written
subroutine. To define the modal damping with an expression, follow
CRATIO with an equal sign and the expression. The FXFREQ and
FXMODE function expression may be useful here.
To define modal damping with a user-written subroutine, follow

CRATIO with an equal sign, the character string USER, and the
values (r1,[,...,r30] that the Adams Solver (C++) is to pass to the
DMPSUB user-written subroutine. If the CRATIO argument is used, it
must either be the last argument in the FLEX_BODY statement, or
be followed by a backslash (\).
LIST Lists the current values of the FLEX_BODY arguments.
REPRESENTATION={MODAL, Switches the flexible body representation from MODAL to RIGID or
RIGID} vice versa during the simulation. To enable this option during
runtime, the REPRESENTATION argument must have been
specified on the FLEX_BODY statement. Note that switching the
flexible body REPRESENTATION to RIGID can speed up the
simulation, but can result in a loss in fidelity.
See other bordered available.

FRICTION 59
C++ Commands
FRICTION
The FRICTION command defines parameters that enable joint friction forces on translational, revolute,
cylindrical, hooke, universal, and spherical joints.
Note: Frictional forces and torques are computed by Adams Solver (C++) using a friction model
that supports dynamic frictions and stiction.
60 Adams Solver
C++ Commands
Format
FRICTION 61
C++ Commands
Arguments
BALL_RADIUS=Rb Defines the radius of the ball in a spherical joint for use in friction-force and
torque calculations.

STICTION_TRANSITION_VEL Defines the absolute velocity threshold for the transition from dynamic friction to
OCITY=r static friction. If the absolute relative velocity of the joint marker is below

FRICTION_FORCE_PRELOAD= Defines the joint’s preload frictional force, which is usually caused by mechanical
r interference in the assembly of the joint.

FRICTION_ARM=Rn, Defines the effective moment arm used to compute the axial component of the
friction torque in revolute, Hooke, and universal joints.

Range: STATIC

[[PRELOAD: and joint-reaction force and moments are included. You can customize the
REACTION_FORCE: friction-force model by limiting the input forces you list in the statement.
BENDING_MOMENT:
TORSIONAL_MOMENT]]} ) Joint type: (Available inputs:)
TORSIONAL_MOMENT)
BENDING_MOMENT)
JOINT=id Identifies the JOINT to which frictional forces apply.
62 Adams Solver
C++ Commands
MAX_STICTION_DEFORMATI Defines the maximum creep that can occur in a joint during the stiction regime.
ON=r The creep allows Adams Solver (C++) to impose the Coulomb conditions for

MU_DYNAMIC=r Defines the coefficient of dynamic friction during the sliding regime. The
joint.

LIST Lists the current values of the FRICTION statement.
MU_STATIC=r Defines the coefficient of static friction in the joint. The magnitude of the
frictional force is the product of a function of MU_STATIC, MU_DYNAMIC,
and the creep, times the magnitude of the normal force in the joint, for example:
where μ = ƒ(MU_STATIC, MU_DYNAMIC, creep) and N = normal force
The static frictional force acts to oppose the net force or torque along the degrees
of freedom of the joint.

FRICTION 63
C++ Commands
OVERLAP_DELTA={INCREASE, To define friction in a sliding joint (either a translational or a cylindrical joint),

DECREASE, CONSTANT} Adams Solver (C++) computes the overlap of the joint. As the joint slides, the
overlap can increase, decrease, or remain constant. OVERLAP_DELTA is used to
define any change in overlap.
 INCREASE indicates that overlap increases as the I Marker translates in the

positive direction along the J Marker; the slider moves to be within the joint.
 DECREASE indicates that the overlap decreases with positive translation of
the joint; the slider moves outside of the joint.
BENDING_FACTOR = r Defines the coefficient that multiplies the term Tm/Xs when the
BENDING_MOMENT input is used for the friction force computation. This
coefficient was hardcoded to 1.0 in releases previous to 2016.
Range: BENDING_FACTOR>0.
PIN_RADIUS=Rp Defines the radius of the pin for a revolute, cylindrical, Hooke, or universal joint.

force.

FRICTION_TORQUE_PRELOA Defines the preload friction torque in the joint, which is usually caused by
D=r mechanical interference in the assembly of the joint.

I_YOKE I_YOKE and J_YOKE define the rotational constraint on which the FRICTION
J_YOKE statement acts. I_YOKE identifies the yoke to the I marker’s rotational constraint.
Likewise, J_YOKE identifies the yoke to the J marker’s rotational constraint.
These keywords are used with only Hooke and UNIVERSAL joints.
Extended Defintion
For an extended definition on the statement associated with this command, see the FRICTION statement.
Examples
FRICTION/102, INPUTS=NONE
This command turns off the friction calculations of FRICTION/102.
64 Adams Solver
C++ Commands
GCON
The GCON (general constraint) command lists all the data for a GCON statement.
Format
GCON/id [,LIST]
Arguments
LIST Lists the current values of the data in the GCON statement.
Examples
GCON/10, LIST
This GCON command lists all the data for GCON 10.
GFORCE 65
C++ Commands
GFORCE
The GFORCE command redefines and/or list the data for a GFORCE statement that defines a force element
that consists of three orthogonal translational force components and three orthogonal torque components.
Format
Arguments
FUNCTION=USER(r1[,...,r30]) Respecifies up to thirty user-defined constants to compute the force

FX=e Respecifies the magnitude and sign of the x component of the
GFORCE translational force. Adams Solver (C++) applies this force
parallel to the x-axis of the RM marker.
FY=e Respecifies the magnitude and sign of the y component of the
parallel to the y-axis of the RM marker.
FZ=e Respecifies the magnitude and sign of the z component of the
parallel to the z-axis of the RM marker.
FXYZ=e3d Respecifies the 3D vector expression for the force component of the
GFORCE relative to the RM marker.
66 Adams Solver
C++ Commands
TXYZ=e3d Respecifies the 3D vector expression for the torque component of the
GFORCE relative to the RM marker.
I=id Respecifies the marker at which Adams Solver (C++) applies the forces
and torques. You must ensure that the I marker is a fixed marker and on
a different part than the JFLOAT marker. Because I is a fixed marker,
Adams Solver (C++) always applies the force at a fixed point on the part
containing the I marker.
JFLOAT=id Respecifies the marker at which Adams Solver (C++) applies the
reaction forces and torques. You must ensure that the JFLOAT marker
is a floating marker and on a different part than the I marker. Adams
Solver (C++) moves the JFLOAT marker to keep it superimposed on the
I marker, meaning the point of application of the reaction force may
move with respect to its part. Adams Solver (C++) does not calculate
LIST Lists the current values of the GFORCE arguments.
RM=id Respecifies the marker and therefore the coordinate system in which the
a fixed marker. RM may be the same as I and may be fixed on any part
in your system.
GFOSUB.

TX=e Respecifies the magnitude and sign of the x component of the
GFORCE rotational torque. Adams Solver (C++) applies this torque
parallel to the x-axis of the RM marker in the sense of the right-hand
rule (that is, a positive torque causes a counterclockwise rotation).
TY=e Respecifies the magnitude and sign of the y component of the
parallel to the y-axis of the RM marker in the sense of the right-hand
TZ=e Respecifies the magnitude and sign of the z component of the
parallel to the z-axis of the RM marker in the sense of the right-hand
Extended Definition
The GFORCE command lists or redefines a force element that consists of three mutually orthogonal
translational force components and three orthogonal torque components. You can alter one or both points
of force and torque application, change the force reference marker, and change the force and torque function
expressions or the parameters passed to the GFOSUB user-written subroutine.
GFORCE 67
C++ Commands
After a change to a GFORCE, Adams Solver (C++) reprocesses the model at the next SIMULATE command,
as if it had just been read in from the dataset. During the reprocessing, Adams Solver (C++) checks the entire
model for consistency, reinitializes user subroutines, and recomputes initial conditions.
While checking, Adams Solver (C++) verifies that the model is still valid with the new GFORCE. If, for
example, the GFORCE function expression refers to an inactive element, Adams Solver (C++) issues an error.
IFLAG set to true.
first simulation, Adams Solver begins with the positions and velocities specified in the dataset. If you ran a
previous simulation, Adams Solver begins with the final displacements and velocities. Adams Solver (C++)
then adjusts the initial conditions to ensure that they are consistent with the model constraints. If this is the
first simulation, Adams Solver (C++) also maintains any user supplied joint initial-conditions and positions
specified as EXACT.
Caution: The user-defined functions FX, FY, FZ, TX, TY, TZ, FXYZ and TXYZ should be smooth,
continuous, and single-valued. These conditions make the solution process very effective.
Example 1
GFORCE/1, I=8, JFLOAT=6, RM=7, LIST, &
FY = 0/ &
FZ = 0/ &
TY = 0/ &
TZ = 0
This GFORCE command redefines and lists the general, six-component force acting between fixed Marker
310 and floating Marker 9910. The force and torque components FY, FZ, TY, and TZ are set to zero along
the y and z axes of the reference marker, which is Marker 310. Adams Solver (C++) superimposes floating
Marker 9910 on Marker 310 and applies the FX and TX reaction force and torque at that point.
Example 2
FXYZ = -20*DXYZ(8, 22, 22) - [0,0, SIN(TIME)]
This GFORCE command redefines the force component using vector 3D expressions.
68 Adams Solver
C++ Commands
HELP
The HELP command opens the online help for Adams Solver.
To navigate through the help:
 Select a topic from the left.
See other Information available.
IC 69
C++ Commands
IC
The IC command redefines and/or lists the data for an IC statement. If you issue neither the IC command
nor statement in an Adams Solver (C++) session, Adams Solver (C++) uses the default values for AERROR,
ALIMIT, AMAXIT, APATTERN, ERROR, MAXIT, PATTERN, TLIMIT, and VERROR when finding
initial conditions.
Format
Arguments
AERROR=r Respecifies the maximum acceleration error Adams Solver (C++) is to allow
during an initial conditions solution or for reconciling INTEGRATOR
acceleration output.
Range: AERROR > 0

ALIMIT=r Respecifies the maximum angular increment Adams Solver (C++) is to allow
while testing trial solutions for a set of consistent initial conditions that satisfy
all system constraints. The default units for ALIMIT are radians. To specify
ALIMIT in degrees, add a D after the value.
Range: ALIMIT > 0

AMAXIT=i Respecifies the maximum number of iterations Adams Solver (C++) is to allow
for finding accelerations during an initial conditions solution or for reconciling
INTEGRATOR acceleration output.
Range: AMAXIT > 0

70 Adams Solver
C++ Commands
APATTERN=c1[:...:c10] Respecifies as many as ten character strings that together establish the pattern
for evaluating the Jacobian matrix during the modified Newton-Raphson
solution for the accelerations. For each iteration, T or TRUE indicates that
Adams Solver (C++) is to evaluate the Jacobian, and F or FALSE indicates that
Adams Solver (C++) is not to evaluate the Jacobian. Thus, cj determines
whether or not ADAMS is to evaluate the Jacobian at the jth iteration. If
necessary, Adams Solver (C++) repeats the pattern of evaluation until it reaches
the maximum number of iterations (AMAXIT). The number of T's or TRUE’s
DEFAULT Resets all options to the default values specified in the IC statement, namely:
AERROR = 1.0E-4
ALIMIT = 30D
AMAXIT = 25
APATTERN = T:T:T:T:T:T:T:T:T:T
ERROR = 1.0E-10
MAXIT = 25
TLIMIT = 1.0E10
VERROR = 1.0E-4
ERROR Respecifies the maximum displacement error Adams Solver (C++) is to allow
for the assembly process.
Range: ERROR > 0

LIST Lists the current values of the data in the IC statement.
MAXIT=i Specifies the maximum number of iterations Adams Solver (C++) is to allow
for finding displacements during initial conditions, or when reconciling the
position of configuration during integration (interpolate on, or with the
WSTIFF integrator), and static analysis.
Range: MAXIT > 0

IC 71
C++ Commands
PATTERN=c1[:...:c10] Respecifies as many as ten character strings that together establish the pattern
solution for the displacements. For each iteration, T or TRUE indicates that
whether or not the solver is to evaluate the Jacobian at the jth iteration. If
necessary, Adams Solver (C++) repeats the pattern of evaluation until it reaches
the maximum number of iterations (MAXIT). The number of T’s or TRUE’s
TLIMIT=r Respecifies the maximum translational increment Adams Solver (C++) is to
allow while testing trial solutions during a solution step.
Range: TLIMIT > 0

VERROR=r Respecifies the maximum velocity error that Adams Solver (C++) is to ignore
during an initial conditions solution. If the value of VERROR is exceeded,
Adams Solver (C++) issues a warning. If
PREFERENCES/SIMFAIL=STOPCF is chosen, Adams Solver (C++) issues
an error.
Range: VERROR > 0
Tip: Use the ALIMIT and TLIMIT arguments to limit the increments of the displacement
variables if Adams Solver (C++) fails to converge to a solution or converges to an undesirable
configuration. This lessens the position change on successive iterations, and tends to keep
the solution closer to the initial configuration.

72 Adams Solver
C++ Commands
INFO
The INFO command lists the vector components for the displacement, velocity, or acceleration of one
marker with respect to another or displays force values at the current simulation time. This command resolves
components in the ground coordinate system (GCS) or in another specified reference frame.
Format
Arguments
ACCELERATION Lists the accelerations of the I marker minus the accelerations of the J marker. Adams
Solver (C++) reports translational accelerations in units of displacement per time
squared and rotational accelerations in units of radians per time squared.
DISPLACEMENT Lists the x, y, z, psi, theta, and phi displacements of the I marker with respect to the
J marker. Adams Solver (C++) reports translational displacements in units of
displacement and rotational displacements in units of radians.
FORCE Lists the components for the force at the I marker. A BEAM, BUSHING, CVCV,
FIELD, GFORCE, JOINT, JPRIM, MOTION, NFORCE, PTCV, SFORCE,
SPRINGDAMPER, VFORCE, or VTORQUE statement can define the force. You
should include both the I and the J arguments to measure the action-reaction force(s)
between two markers (I, J). You should include the I argument and either give zero
as the J argument or omit the J argument altogether to measure the action-only
force(s) at a marker (I).
I=id Specifies the identifier of the fixed or floating marker for which Adams Solver (C++)
is to measure displacements, velocities, accelerations, or action forces.
INFO 73
C++ Commands
J=id Specifies the identifier of the fixed or floating marker with respect to which Adams
Solver (C++) is to measure the displacements, velocities, or accelerations of the I
marker, or the identifier of the marker for which Adams Solver (C++) is to measure
reaction forces.
RM=id Specifies the identifier of the fixed or floating marker relative to which Adams Solver
(C++) resolves displacements, velocities, accelerations, or forces. If a value for the RM
argument is not set or if the RM argument is set equal to zero, Adams Solver (C++)
resolves the displacements, velocities, accelerations, or forces in the ground
VELOCITY Lists the velocities of the I marker minus the velocities of the J marker. Translational
velocities are given in units of displacement per time. Rotational displacements are
given in units of radians per time.
Examples
INFO/ DISP, I=10, J=15, RM=43
This INFO command lists the x, y, z, psi, theta, and phi displacements of Marker 10 with respect to Marker
15. Adams Solver (C++) measures x, y, and z in the Cartesian coordinates of Marker 43.
INFO/ ACC, I=12, J=100
This INFO command lists the x, y, and z translational and rotational accelerations of Marker 12 with respect
to Marker 100. Adams Solver (C++) measures x, y, and z in the Cartesian coordinates of the ground
74 Adams Solver
C++ Commands
INTEGRATOR
The INTEGRATOR command lets you redefine data in the INTEGRATOR statement.
Format
INTEGRATOR 75
C++ Commands
Arguments
76 Adams Solver
C++ Commands
ALPHA = r Defining coefficient for the HHT method.
Default value: -0.3
Range: -0.333333 <= ALPHA <= 0

BETA = r One of the two defining coefficients associated with the Newmark method.
Default Value: 0.36
Range: Defined in conjunction with GAMMA. Together they must satisfy the
stability condition.
2
γ + 1 ---
 2
β ≥ --------------------
4
INTEGRATOR 77
C++ Commands
Specifies the corrector algorithm that is to be used with the integrators. The
corrector ensures that all candidate solutions satisfy the equations of the system.
The two options, original and modified, differ in how they asses convergence.

previous releases of Adams Solver (C++) be used. This is the default. This
implementation of the corrector requires that at convergence, the error in
all solution variables be less than the corrector error tolerance.
 CORRECTOR=modified - Specifies that a modified corrector is used.
For GSTIFF, WSTIFF and HASTIFF, this implementation of the
corrector requires that at convergence, the error in only those variables for
which integration error is being monitored be less than the corrector error
tolerance. This is a slightly looser definition of convergence, and you
should use proper care when selecting this setting. For HHT and
NEWMARK, this implementation of the corrector requires that the
convergence assessment is to be performed ignoring fluctuations of the
values in the Lagrange multipliers. The CORRECTOR=modified setting
is helpful for models containing discontinuities in the forcing functions.
Problems with contacts belong to this category.
 CORRECTOR=orig_constant - Specifies that the original corrector is set
and that no automatic switching to the modified corrector is to be
performed. Adams Solver (C++) would switch from the original corrector
to the modified corrector automatically under any of these two
conditions:
a. The model has CONTACT elements. By default, Adams Solver (C++)
switches to the modified corrector when the model has CONTACT
elements.
b. There is an integration failure. In some cases, the integration algorithm
will automatically switch to the modified corrector temporarily.
When using the orig_constant option, Adams Solver (C++) will use the
original corrector and no switching of the corrector algorithm is allowed.
For additional information, see the Extended Definition in the INTEGRATOR
statement.
78 Adams Solver
C++ Commands
DEFAULT Resets the integrator parameters to the default values specified in the
INTEGRATOR statement, namely:
GSTIFF, I3
CORRECTOR = original
ERROR = 1.0E-3
HINIT = 1/20 of the output step
HMAX = the output step
HMIN = 1.0E-6*HMAX
INTERPOLATE = OFF
MAXIT = 10
KMAX = 6
PATTERN = T:F:F:F:T:F:F:F:T:F
ERROR=r Specifies the relative and absolute local integration error tolerances that the
integrator must satisfy at each step. For BDF integrators, Adams Solver (C++)
monitors the integration errors in the displacement and state variables that the
other differential equations (DIFFs, LSEs, GSEs, and TFSISOs) define. The larger
the ERROR, the greater the error/step in your solution.
Note that the value for ERROR is units-sensitive. For example, if a system is
modeled in mm-kg-s units, the units of length must be in mm.
Assuming that all the translational states are larger than 1mm, setting
ERROR=1E-3 implies that the integrator monitors all changes of the order of 1
micron.
The error tolerances (e) are enforced as:
||Yc - Y|| < MAX (e,e * ||Y||)
where Yc is the column matrix of computed values for the unknowns, Y. The
symbol || || indicates the root-mean-square of the array of numbers.
Range: ERROR > 0

FIXIT=i Specifies 'fixed' number of corrector iterations to be taken per time step. Must be
either unspecified or an integer from 1-10. If specified, the fixed step option is
employed. If FIXIT is unspecified, then the fixed step option is not employed and
Adams Solver integration proceeds in the traditional (that is, variable time step)
manner.
Default: unspecified
Range: 1 < FIXIT < 10

INTEGRATOR 79
C++ Commands
GAMMA One of the two (together with BETA) defining coefficients associated with the
Newmark method.
Default value: 0.7
Range: Defined in conjunction with BETA. Together they must satisfy the stability
condition.
2
γ + 1 ---
 2
β ≥ --------------------
4
HHT Specifies that the HHT (Hilber-Hughes-Taylor) integrator is used for integrating
the equations of motion.

Default: When setting the argument INTERPOLATE = ON, the integration step
size is limited to the value specified for HMAX, but if HMAX is not defined, no
limit is placed on the integration step size. If INTERPOLATE = OFF, the
maximum step size is limited to the output step.

Default:
 1.0E-6*HMAX for GSTIFF, WSTIFF, and I3

 Machine precision for GSTIFF, WSTIFF, SI2, and for HHT and
Newmark
HRATIO=i Specifies the 'fixed' ratio of the output sampling rate (aka "DTOUT") to the
integrator time step size (aka "H"). Must be a positive integer. If unspecified while
FIXIT is specified, this defaults to 1. HRATIO is only valid in the context of the
fixed step option; so, it's ignored if FIXIT is unspecified.
Default: 1 (with FIXIT on)
Range: positive integer

80 Adams Solver
C++ Commands
INTERPOLATE=ON specifies that the integrator is not required to control its

step size to hit an output point. Therefore, when the integrator crosses an output
point, it computes a preliminary solution by interpolating to the output point. It
then refines or reconciles the solution to satisfy the equations of motion and
constraint. INTERPOLATE=OFF turns off interpolation for the chosen
integrator.
Note: When using INTERPOLATE with models containing CONTACT,

you may see intermediate data at intervals that do not coincide with
your specified output interval. This intermediate data (the data in-
between the interpolated outputs) actually corresponds to contact
incidences. You can turn off these extra contact data points with an
environment variable, MDI_ADAMS_CONTACT_OUT.
I3 Specifies the Index-3 (I3) formulation be used. Default for
GSTIFF/WSTIFF/HHT.

statement.
KMAX=i Indicates the maximum order that the integrator can use. The order of integration
refers to the order of the polynomials used in the solution. The integrator controls
the order of the integration and step size, and therefore, controls the local
integration error at each step so that it is less than the error tolerance specified.
Note: For problems involving discontinuities, such as contacts, setting

KMAX=2 can improve the speed of the solution. However, we do not
recommend that you set the KMAX parameter unless you are a very
experienced user. Any modification can adversely affect the integrator’s
accuracy and robustness.
Range: 1 < KMAX < 6
LIST Lists current values of the integrator arguments.
MAXERR=r Specifies the amount error above which the user would like the integrator to stop
trying to solve the problem if it can't do better than this when the fixed step option
is selected. If the local integration error exceeds MAXERR, the integrator stops the
simulation. MAXERR is a positive real number. Similar to HRATIO, it's only
relevant to the fixed step option; so, it's ignored if FIXIT is unspecified. When
FIXIT is specified and this value is unspecified, then there is no amount of error
which would cause Adams Solver to quit. Note that unlike ERROR, MAXERR
does not control the accuracy of results. MAXERR can be interpreted as the pre-
mature stopping criteria for simulation when the fixed step option is selected.
Default: infinity
Range: ERROR > 0

INTEGRATOR 81
C++ Commands
iterations to converge to the solution of the nonlinear equations. The corrector
uses Newton-Raphson iterations.
MAXIT should not be set larger than 10. This is because round-off errors increase
when a large number of iterations are taken. This can cause an error in the solution.
Range: MAXIT > 0

NEWMARK Specifies that the NEWMARK integrator be used for integrating the equations of
motion.
PATTERN=c1[:...:c10] Indicates the pattern of trues and falses for re-evaluating the Jacobian matrix for
Newton-Raphson. A value of true (T) indicates that Adams Solver (C++) is
evaluating a new Jacobian matrix for that iteration. A value of false (F) indicates
that Adams Solver (C++) is using the previously calculated Jacobian matrix as an
approximation of the current one.
Note: PATTERN accepts a sequence of at least 1 character string and not

more than 10 character strings. Each string must be either TRUE or
FALSE, which you can abbreviate with T or F. You must separate the
strings with colons.: A pattern setting of all false, implies that Adams
Solver (C++) is not to evaluate the Jacobian until it encounters a
corrector failure. For problems that are linear or almost linear, this
setting can improve simulation speed substantially.
GSTIFF, WSTIFF, or HASTIFF integrators, be used for formulating and
integrating differential equations of motion.
The SI2 formulation takes into account constraint derivatives when numerically
solving the equations of motion. This process enables the integrator to monitor the
integration error of velocity variables, and, therefore, renders highly accurate
simulations. A positive side effect of the SI2 formulation is that the Jacobian matrix
remains stable at small step sizes, which increases the stability and robustness of the
corrector at small step sizes.
The SI2 formulation is available only with GSTIFF, WSTIFF, and HASTIFF.
82 Adams Solver
C++ Commands
differential equations of motion. WSTIFF uses the BDF method that takes step
sizes into account when calculating the coefficients for any particular integration
order.
HASTIFF Specify that the HASTIFF (Hiller Anantharaman stiff ) integrator be used for
integrating the differential equations of motion.HASTIFF uses the BDF method
that takes step sizes into account when calculating the coefficients for any
particular integration order.
HASTIFF integrator, be used for formulating and integrating differential
equations of motion. This process enables the HASTIFF integrator to monitor the
integration error of velocity variables, and therefore renders highly accurate
The SI1 formulation is available only with HASTIFF, for which it is the default.
Extended Definition
For a detailed definition, cautions, tips, and more, see the Extended Defintion in the INTEGRATOR statement.
Notes: Setting the environment variable MSC_ADAMS_SOLVER_INTERPOLATE_ADAPTIVE

follows:

equally spaced output blocks and generates an output block at any integration step
past the request interval. The end result is that Adams Solver generates output blocks
at unequally spaced times.
 Using this setting, the solver does not need to reduce the current time step in order to
hit a requested output block. Instead, it leaps over and prints an output block as soon
as a request output block was suggested. In some cases, the solver may leap over more
than one requested output blocks. The main benefit is speed performance. The main
drawback is that output blocks are not equally spaced.
INTEGRATOR 83
C++ Commands
Caution: The INTEGRATOR command is not equivalent to the INTEGRATOR statement. The
statement lets you specify explicitly or implicitly the collection of attributes that define the
integration formula used and the integration parameters. The command allows you to adjust
some of these settings. Therefore, if no INTEGRATOR statement is present in the .adm file
and later an INTEGRATOR command sets the INTEGRATOR to be HHT, the ERROR
setting will be 1.E-3 rather than the HHT default of ERROR=1.E-5. This is because the
integrator GSTIFF was considered the default, along with its default ERROR=1.E-3 in the
.adm file. Changing the integrator from GSTIFF to HHT does not change the value of
ERROR. The correct command to make HHT work with its default value ERROR=1.E-5
is either INTEGRATOR/HHT, DEFAULT, or INTEGRATOR/HHT, ERROR=1.E-5.
The INTEGRATOR command changes one attribute at a time, and this operation has no
side effect, such as implicitly changing other attributes that have been explicitly or implicitly
defined through the INTEGRATOR statement.
Examples
 INTEGRATOR/SI2,GSTIFF, ERROR=1.0E-4, HINIT=1.0E-6, LIST
This command specifies a dynamic simulation using the SI2 equation formulation combined with
the GSTIFF integrator.
• The integrator has an error limit of 1.0E-4 and overrides the default value of 1.0E-3.
• HINIT =1.0E-6 specifies an initial timestep of 1.0E-6, which overrides the default of 1/20th of
the output step.
• LIST prints all current settings of the INTEGRATOR to the screen and message file.
 INTEGRATOR/HHT, ERROR=5.0E-6, PATTERN=F, HMAX=1e-3
This integrator statement specifies that dynamic simulations be run using the HHT integrator with
the adaptive jacobian pattern.
• The maximum step size the integrator is to take is 1.0E-3.
84 Adams Solver
C++ Commands
JOINT
The JOINT command lists all the data for a JOINT statement.
Format
JOINT/id [,LIST]
Arguments
LIST Lists the current values of the data in the JOINT statement.
Examples
JOINT/10, LIST
This JOINT command lists all the data for Joint 10.
KINEMATICS 85
C++ Commands
KINEMATICS
The KINEMATICS command redefines and/or lists the data for a KINEMATICS statement. If you issue neither
the KINEMATICS command nor statement in an Adams Solver (C++) session, Adams Solver (C++) uses the
default values for AERROR, ALIMIT, AMAXIT, APATTERN, ERROR, MAXIT, PATTERN, and TLIMIT
when performing a kinematic analysis.
Format
Arguments
AERROR=r Respecifies the maximum acceleration error Adams Solver (C++) is to allow for
each time step.
Range: AERROR > 0

ALIMIT=r Respecifies the maximum angular increment Adams Solver (C++) is to allow
per iteration. The default units for ALIMIT are radians. To specify ALIMIT in
degrees, add a D after the value.
Range: ALIMIT > 0

AMAXIT=i Respecifies the maximum number of iterations Adams Solver (C++) is to allow
for finding accelerations at a point in time.
Range: AMAXIT > 0

86 Adams Solver
C++ Commands
whether or not Adams Solver (C++) is to evaluate the Jacobian at the jth
iteration. If necessary, Adams Solver (C++) repeats the pattern of evaluations
until it reaches the maximum number of iterations (AMAXIT). The number
of T’s or TRUE’s and F’s or FALSE’s together must be at least one and no more
than 10.
DEFAULT Resets the kinematic analysis simulation parameters to their default settings,
namely:
AERROR=1.0E-4
ALIMIT=30D
AMAXIT=25
APATTERN=T:T:T:T:T:T:T:T:T:T, (evaluate the
acceleration Jacobian at every iteration)
ERROR=1.0E-4
MAXIT=25
PATTERN=T:T:T:T:T:T:T:T:T:T, (evaluate the
position Jacobian at every iteration)
TLIMIT=1.0E10 (no limit)
ERROR=r Respecifies the maximum displacement error Adams Solver (C++) is to allow
for each time step.
Range: ERROR > 0

HMAX=r Defines the maximum time step that the KINEMATICS solution is allowed to
take.
When performing kinematic simulations on systems with parts that are

rotating at very high speeds (at or more than one revolution per time step), it
is possible for the kinematic to fail or provide inaccurate results because of lack
of information on the system between output step solutions. The HMAX value
can be used to limit the time between solution steps without having to specify
a large number of output steps.
LIST Lists the current values of the data in the KINEMATICS statement.
KINEMATICS 87
C++ Commands
MAXIT=i Respecifies the maximum number of iterations Adams Solver (C++) is to allow
for finding the displacements at a point in time.
Range: MAXIT > 0

Adams Solver (C++) is to evaluate the Jacobian and F or FALSE indicates that
Adams Solver (C++) is not to evaluate the Jacobian. Thus cj determines
whether or not Adams Solver (C++) is to evaluate the Jacobian at the jth
iteration. If necessary, Adams Solver (C++) repeats the pattern of evaluations
until it reaches the maximum number of iterations (MAXIT). The number of
T’s or TRUE’s and F’s or FALSE’s together must be at least one and no more
than ten.
TLIMIT=r Respecifies the maximum translational increment Adams Solver (C++) is to
allow per iteration.
Range: TLIMIT > 0
Tip:  Using the PATTERN argument to request less frequent evaluations of the Jacobian matrix
may decrease the computation time, thereby decreasing the cost and improving the
response time. However, it could also have the opposite effect since more iterations may be
required to reach the solution with a stale Jacobian matrix.
 Use the ALIMIT and TLIMIT arguments to limit the increments of the displacement
variables if Adams Solver (C++) fails to converge to a solution or converges to an
undesirable configuration. This lessens the position change on successive iterations, and
tends to keep the solution closer to the previous configuration.

88 Adams Solver
C++ Commands
LINEAR
The LINEAR command is divided into the following sections:
 General
 Definition
 Format
 Arguments
 Extended Definition
• Eigensolutions
Scope
Using the RM option
Using the PSTATE option
Using both the RM and PSTATE options
Coordinates, Kinetic, Dissipative and Strain options
Further details on kinetic energy tables
Kinetic energy reported in Adams View
Differences in results compared with Adams Solver FORTRAN
Advanced eigensolution issues
Eigenvectors and mode shapes
• State matrices and MKB computation
Scope
Using the RM and PSTATE options
Plant inputs and Plant outputs
MATRIXX format
MATLAB format
Contents of the STATES matrix
Contents of the PINPUT and POUTPUT matrices
• Nastran bulk data deck export
Scope
Limitations
BLACKBOX and WHITEBOX exported cards

LINEAR 89
C++ Commands
Configuration file syntax
Configuration file examples
Theoretical background
 Examples
 Applications
• Eigen analysis application
• State matrices output
 Appendix
 Limitations
1. General
You can use the LINEAR command to linearize Adams models. Linearized Adams models can be represented
by complex valued eigendata (eigenvalues, mode shapes) or by a state-space representation in the form of real-
valued state matrices. Two state-space representations are possible, the ABCD standard representation and
the MKB Nastran representation. Moreover, the LINEAR command can be used to export the linearized
Adams model into an equivalent Nastran bulk data deck.
Adams Solver (C++) uses a state-of-the-art condensation scheme to reduce an Adams model to a minimal
linear form for efficient solution. (For more information, see On an approach for the linearization of the
Differential Algebraic Equations of Multi-body Dynamic, D. Negrut and J. L. Ortiz. Fifth ASME International
Conference on Multibody Systems, Nonlinear Dynamics and Control, ASME 2005.)
The LINEAR command has four main options designed to provide important insight into the dynamic
behavior of the model. For instance, the LINEAR/EIGENSOL option can be used to assess the stability of
the model. Stability properties of the model have a direct relationship to the real part of the complex
eigenvalues. Eigenvalues with positive real parts represent unstable modes of the system, while those with
negative real parts represent stable modes. If bounded inputs to the system cause excitation of an unstable
mode, the system produces an unbounded response. On the other hand, bounded excitation of a stable mode
results in a bounded response. Eigenvalues computed by Adams Solver (C++) can be plotted on a real-
imaginary plot and the mode shapes can be animated using Adams View. In addition to verifying stability,
eigendata is used for validating implementation of models with eigendata from other modeling approaches
or experimental data. This is especially true if an elastic or control sub-system model has been implemented
in Adams Solver (C++). If you issue the LINEAR/EIGENSOL option, Adams Solver (C++) computes the
model eigendata and reports the model eigenvalues to the workstation screen. If the results outputs are
enabled, eigendata is also written into the results (.res) file, and may be taken to Adams for further processing.
Important: The LINEAR/EIGENSOL option RESULTS statement should have the XRF option.
Otherwise the eigendata is not written into the results file and this cannot be postprocessed
in Adams View or PPT.
90 Adams Solver
C++ Commands
Both the LINEAR/STATEMAT and the LINEAR/MKB options output a state-space representation in a
form suitable for importation into matrix manipulation and control design packages such as MATRIXx and
MATLAB (for more information see the Xmath Basics Guide, 1996, Integrated Systems Inc., Santa Clara,
CA and Matlab User's Guide, The MathWorks Inc., Natick, Massachusetts). A state-space model
representation is suitable for obtaining frequency response of the Adams model, verifying model control
properties (controllability and observability), and designing feedback controllers for Adams models. If you
issue the LINEAR/STATEMAT or LINEAR/MKB command, Adams Solver (C++) computes the state
matrices for the model and writes them to a user-specified file or files. If enabled, state matrices are also
written out to the Results file.
Option LINEAR/EXPORT is used to export the linearized model into an equivalent Nastran model. Using
this option, Adams Solver (C++) creates an ASCII file containing a Nastran bulk data deck. Two sub options
are available: a "blackbox" sub option equivalent to a state space representation, and a "whitebox" sub option
in which an element-to-element export is performed. Using the "whitebox" sub option, rigid Adams PARTS
are exported as CONM2 cards, Adams JOINTS are exported as RJOINT cards or sets of MPC cards and so
on. Both the "blackbox" and "whitebox" sub options honor a configuration file which is used to fine tune
the exporting process. The configuration file can be used to custom the exported model. See below for current
limitations of the LINEAR/EXPORT option.
2. Definition
The LINEAR command linearizes the nonlinear system equations of motion and provides four basic
capabilities: an eigensolution, a standard state-space matrix calculation, a Nastran-specific state space
calculation, and an export to a Nastran bulk data deck.
The eigensolution option determines natural frequencies and mode shapes while the state space calculations
compute the linear state space matrices that describe the linearized mechanical system.
You may issue this command following initial conditions, a static or a transient analysis. Depending on the
options you specify, the results of the command are reported on the screen and written to the Message file,
the Results file, and, if required, the user-specified files.
The LINEAR/EXPORT option has been modified to support all types of operating points (static or
dynamic). However, matching eigenvalues with Nastran can be obtained using static operating points only.
Kinematic models (zero degrees of freedom) can only be exported using the WHITEBOX option.
For theoretical details on the linearization algorithm, see the white paper in Simcompanion Article
KB8016460.
LINEAR 91
C++ Commands
3. Format
92 Adams Solver
C++ Commands
4. Arguments
CONFIG=c Specifies a file name from which Adams Solver (C++) reads configuration
directives to customize the export process to a Nastran bulk data deck. If no
configuration file is specified, Adams Solver (C++) will use default
configuration parameters. See below for the syntax of the configuration file.
Range: Valid file name.
Type: Optional with EXPORT.

COORDS=i1[,i2] Specifies that a table of coordinates for mode numbers in the range i1 to i2
be computed and output. If i2 is not specified, Adams Solver (C++) produces
the table of coordinates for mode number i1 only.
Range: i1 > 1, i2 > i1
Type: Optional with EIGENSOL; mutually exclusive with NOVECTOR

DISSIPAT=i1[,i2] Specifies that a table of dissipative energy distribution for mode numbers in
the range i1 to i2 be computed and output. If i2 is not specified, Adams
Solver (C++) produces the table of dissipative energy distribution for mode
number i1 only.
Range: i1 > 1, i2 > i1

EIGENSOL Specifies that Adams Solver (C++) performs an eigenanalysis of the Adams
model.
Type: Optional (either EIGENSOL, MKB, STATEMAT or EXPORT is

required)
EXPORT Specifies that Adams Solver (C++) performs a Nastran bulk data deck export.

required)
LINEAR 93
C++ Commands
FILE=c If using the STATEMAT or MKB options, specifies a file name to which
Adams Solver (C++) writes the state matrices. If the output is in the
MATRIXX format, all matrices are written to this file. For the MATLAB
format, the file name is used as a base name. Each matrix is written to a
separate file, whose name Adams Solver (C++) automatically constructs by
appending the matrix name to the user-specified base name.
If using the EXPORT option, specifies a file prefix for the bulk data deck to
which Adams Solver (C++) writes the exported data.
Range: Valid file name up to 76 characters
Type: Required with MKB or STATEMAT or EXPORT

Specifies the name of the software in whose input format Adams Solver
 MATRIXX 
FORMAT =   (C++) is to output the state matrices. Presently, two software formats are
 MATLAB  supported: MATRIXX (FSAVE format) and MATLAB (ASCII flat file
format). This argument is a qualifier for the MKB or STATEMAT option.
Type: Optional with MKB or STATEMAT
Default: MATRIXX
KINETIC=i1[,i2] Specifies that a table of kinetic energy distribution for mode numbers in the
range i1 to i2 be computed and output.
If i2 is not specified, Adams Solver (C++) produces the table of kinetic energy
distribution for mode number i1 only.
Range: i1 > 1, i2 > i1

MKB Specifies that Adams Solver (C++) calculates the M, K, B, C and D matrices
for the Adams model. These matrices are used as inputs to a
MSC.NASTRAN model.

required)
MLIST=id1[,id2..., idn] Specifies that a table of marker mode for mode numbers in the MRANGE
be computed and output. Specify the marker IDs: id1, id2 ..., idn.
Range: i1 > 1, i2 > i1
Type: Optional with EIGENSOL; mutually exclusive with NOVECTOR.

Required with MRANGE.
94 Adams Solver
C++ Commands
MRANGE=i1[,i2] Specifies that a table of marker mode for mode numbers in the range i1 to i2
be computed and output. If i2 is not specified, Adams Solver (C++) produces
the table of marker mode for mode number i1 only.
Range: i1 > 1, i2 > i1
Type: Optional with EIGENSOL; mutually exclusive with NOVECTOR.

Required with MLIST.
FCOORDS=r1, r2 Specifies that a table of coordinates for modes with frequencies in the range
r1 to r2 be computed and output. If a mode has a real-only frequency, the
mode is ignored. If a mode has a complex eigenvalue, the table will be output
only if the absolute value of the imaginary part is in the specified range.
Range: r2 > r1 > 0.

and COORDS.
FKINETIC=r1, r2 Specifies that a table of kinetic energy distribution for modes with
frequencies in the range r1 to r2 be computed and output. If a mode has a
real-only frequency, the mode is ignored. If a mode has a complex eigenvalue,
the table will be output only if the absolute value of the imaginary part is in
the specified range.
Range: r2 > r1 > 0.

and KINETIC.
FSTRAIN=r1, r2 Specifies that a table of strain energy distribution for modes with frequencies
in the range r1 to r2 be computed and output. If a mode has a real-only
frequency, the mode is ignored. If a mode has a complex eigenvalue, the table
will be output only if the absolute value of the imaginary part is in the
specified range.
Range: r2 > r1 > 0.

and STRAIN.
LINEAR 95
C++ Commands
FDISSIPAT=r1, r2 Specifies that a table of dissipative energy distribution for modes with
frequencies in the range r1 to r2 be computed and output. If a mode has a
real-only frequency, the mode is ignored. If a mode has a complex eigenvalue,
the table will be output only if the absolute value of the imaginary part is in
the specified range.
Range: r2 > r1 > 0.

and DISSIPAT.
NAMES Specifies that Adams View names be included in all modal tables. By default,
no Adams View names are printed. For back-compatibility, this option is
honored only if the TABLE_PRECISION is different than 2.
TABLE_PRECISION=i Specifies that Adams Solver (C++) will use the specified number of
significant digits in the output of the modal coordinates tables. The default
is 2. The valid range is i>2. For back-compatibility, if the precision is 2, the
old output format is used for all real values. In C/C++ jargon the default uses
a format equal to "%7.2f". If the precision is bigger than 2, an exponential
formatting option is used where the size of the formatted field is 8 plus the
given precision. For example, if the precision is 6, the formatting string to be
used is "%14.6e".
NODAMPIN Specifies that Adams Solver (C++) ignores damping while performing an
eigenanalysis for the Adams model. This argument affects only force
statements (such as SPRINGDAMPER, SFORCE, BEAM, BUSHING,
and so on) and VARIABLE statements whose definition includes velocity
dependencies. This argument is a qualifier to the EIGENSOL or MKB
option.
Type: Optional with EIGENSOL or MKB

NOVECTOR Specifies that Adams Solver (C++) performs the eigenanalysis without
computation of mode shapes. This argument is a qualifier to the
EIGENSOL option. This argument does not have any values.
Type: Optional with EIGENSOL

PINPUT=id Specifies the identifier of the PINPUT statement that Adams Solver (C++)
uses as plant inputs in the state matrices computation. If this argument is not
specified, the B and D matrices will not be output. This argument is a
qualifier for the MKB or STATEMAT option.

96 Adams Solver
C++ Commands
POUTPUT=id Specifies the identifier of the POUTPUT statement that Adams Solver
(C++) uses as plant outputs in the state matrices computation. If this
argument is not specified, the C and D matrices will not be output. This
argument is a qualifier for the MKB or STATEMAT option.

PSTATE=id Specifies the identifier of the PSTATE statement that Adams Solver (C++)
uses as user-defined coordinates for the linearization. If this argument is not
specified, Adams Solver (C++) uses default state coordinates or coordinates
generated by the RM option.
Type: Optional with EIGENSOL, STATEMAT, or MKB

RM=id Specifies the identifier of the MARKER statement that Adams Solver (C++)
uses to generate user-defined coordinates for linearization. This argument is
a qualifier for the STATEMAT, EIGENSOL, or MKB option.
Type: Optional with EIGENSOL, STATEMAT, or MKB

STATEMAT Specifies that Adams Solver (C++) calculates state matrices for the ADAMS
model.
Type: Optional (either MKB,STATEMAT or EIGENSOL is required)

STRAIN=i1[,i2] Specifies that a table of strain energy distribution for mode numbers in the
range i1 to i2 be computed and output. If i2 is not specified, Adams Solver
(C++) produces the table of strain energy distribution for mode number i1
only.
Range: i1 > 1, i2 > i1

Specifies the type of Nastran bulk data deck export. Using the BLACKBOX
 WHITEBOX  option Adams Solver (C++) exports the state space matrices MKB using
TYPE =   DMIG cards. Using the WHITEBOX option Adams Solver (C++) exports
BLACKBOX
the model using an element-to-element translation.
Type: Required with EXPORT.
5. Extended Definition
To linearize an Adams model about an operating point, issue the SIMULATE/INITIAL,
SIMULATE/STATIC, STATIC/DYNAMIC, or SIMULATE/TRANSIENT commands and then issue the
LINEAR command to exercise a linear analysis on the model. Option EXPORT can be used at any operating
point (static or dynamic). Notice however that after performing a STATIC analysis at time t=0, all initial
velocities found in the model are restored. This means that the operating point may not be truly static at time
t=0 after a static simulation. Use the environment variable
MSC_ADAMS_STATICS_NO_RESTORE_VELOCITIES to override the default solver behavior.
LINEAR 97
C++ Commands
Use the option EIGENSOL to compute the eigenvalues and mode shapes for the Adams model. To compute
the state matrices representation of the Adams model use the STATEMAT or the MKB options. To export
the linearized model as a Nastran bulk data deck use the EXPORT option.
5.1 Eigensolutions
5.1.1 Scope
If you specify the EIGENSOL option, Adams Solver (C++) computes the A state matrix of the Adams model
and it performs an eigenanalysis. Eigendata results from the solution of a generalized eigenvalue problem of
the form:
Az=μz
where:
 z is the eigenvector.
 μ is the eigenvalue.
 A is the state matrix computed by Adams Solver (C++) from the Adams model.
The standard approach to compute the state matrix (A) consists of a direct linearization of the equations of
motion, hence the state variables (x) are a subset of the default coordinates used to build the equations of
motion. However, the default state variables may not be the best choice. In rotational systems (turbines,
helicopter blades and so on), you may prefer using relative coordinates or user-defined coordinates instead of
the default coordinates. The RM and PSTATE options (see Using the RM Option) allow you to specify user-
defined coordinates, which results in better eigensolution computations.
Once the eigensolution is completed, the eigenvector is mapped to the mode shape prior to output to the
results (.res) file.
If you specify the NODAMPIN argument, Adams Solver (C++) does not include the velocity-dependent
terms in forces nor does it include velocity-dependent terms in the VARIABLE statements in the A matrix.
Using this option may be beneficial in determining the underlying modes for a system with critical or greater
than critical damping.
If you specify the NOVECTOR argument, Adams Solver (C++) computes only the eigenvalues and not the
mode shapes. Adams Solver (C++) reports on the screen eigenvalues that result from the eigensolution. If you
use the RESULTS statement to enable output to the results file (.res) in the Adams Solver (C++) dataset, the
eigenvalues and mode shapes (if computed) will be written to this file. The results file may be taken to a
postprocessor, such as Adams View, for further processing.
All eigenvalues are normalized to be in cycles/second. The imaginary component of the eigenvalue represents
the oscillatory behavior of the mode and the real component the damping characteristic.
The model eigenvalues are reported to the workstation screen. In general, the eigenvalues are complex values,
made up of real and imaginary components. The imaginary component represents the damped natural
frequency ω d . The damping ratio must be less than 1 in order to produce an imaginary component in the
eigenvalue - in other words, the damped natural frequency is zero whenever the damping ratio is 1 or greater.
The undamped natural frequency and damping ratio obeys the following equations:
98 Adams Solver
C++ Commands
ωn = ( λ r2 + λ i2 )
λ
ζ = -----r-
ωn
where:
 λ r is the real part of eigenvalue.

 λ i is the imaginary part of eigenvalues.
 ω n is the undamped natural frequency.
 ζ is the damping ratio ( ζ < 1).
The relationship between the damped natural frequency, ω d , and undamped natural frequency, ω n , is:
ωd = ωn ⋅ ( 1 – ζ 2 )
The damped natural frequency is the actual frequency at which the system is oscillating for that mode.
5.1.2 Using the RM option

By default (if no RM option and no PSTATE option are used), Adams Solver (C++) uses the global
displacements and global rotations about the ground origin of all PARTS to build the linearized equations of
motion. The complete set of defaults coordinates is shown in the next table.
Default linearization coordinates (no RM, no PSTATE options used)

 Global displacements of the BCS of all PARTS, FLEX_BODY and POINT_MASS relative to
the ground coordinate system, namely DX(BCS), DY(BCS) and DZ(BCS).
 Global rotations of the BCS of all PARTS and FLEX_BODY relative to the ground coordinate
system, namely AX(BCS), AY(BCS) and AZ(BCS).
 All active modal coordinates in FLEX_BODY.
 All states in LSE, TFSISO, LSE and GSE objects.
 All states in DIFF objects.
Note: BCS stands for an internal MARKER located at the Body Coordinate System which is the
location specified by the QG and REULER arguments of the PART, FLEX_BODY and
POINT_MASS statements.
LINEAR 99
C++ Commands
The default linearization coordinates are not a minimal set. Therefore, Adams Solver (C++) selects an optimal
subset x (the state variables) and linearizes the system in terms of those variables. As mentioned above, the
default coordinate selection may not be the best choice in cases of rotating or accelerating systems. The first
tool to customize the state variables is the RM option. The RM option sets the ADAMS id of a MARKER,
for example:
LINEAR/EIGENSOL, RM=b
MARKER/b may be located on a rotating hub or accelerating subsystem of the model. When the option RM
is used, the default coordinates are the following:
Default linearization coordinates using RM=b

 Relative displacements of the BCS of all PARTS, FLEX_BODY and POINT_MASS relative to
MARKER/b, namely DX(BCS,b,b), DY(BCS,b,b) and DZ(BCS,b,b). There is one exception:
for the PART that owns MARKER/b, the default coordinates are DX(GROUND,b,b),
DY(GROUND,b,b) and DZ(GROUND,b,b).
 Relative rotations of the BCS of all PARTS and FLEX_BODY relative to MARKER/b, namely
AX(BCS,b), DY(BCS,b) and DZ(BCS,b). There is one exception: for the PART that owns
MARKER/b, the default coordinates are AX(GROUND,b), AY(GROUND,b) and
AZ(GROUND,b).
 All active modal coordinates in FLEX_BODY.
 All states in LSE, TFSISO, LSE and GSE objects.
 All states in DIFF objects.
The RM option is useful in linearizing helicopter blades, turbines, etc. If no RM option is used, the computed
frequencies reflect a dependency on the rotation frequency, hiding the frequencies of interest. When the RM
option is used, Adams Solver (C++) selects a subset x of the coordinates shown in the table above to perform
the linearization.
For example, Figure 6 below shows a rotating system modeled using coordinates α and u.
100 Adams Solver
C++ Commands
Figure 6 Rotating spring-mass system
The exact equations of motion in terms of the shown coordinates are the following:
·
·· 2Buu· α
α = – ------------------2-
A + Bu
· K ( u – uo ) U
u·· = u α 2 – ----------------------- + -------
2B 2B
where:
1
A = --- ( m 1 h 12 + I 1 + I 2 )
2
1
B = --- m 2
2
Setting m1=m2=3, I1=I2=10, e=1, K=5, uo=10 and selecting an operating point defined by t=0, α =10, u=0,
·
α =0, u· =0, we obtain that one eigenvalue is zero and the other is 2.63056 Hz.
The corresponding Adams dataset file is:
UNITS/FORCE = NEWTON, MASS = KILOGRAM, LENGTH = METER, TIME = SECOND
PART/1, GROUND
MARKER/6, PART = 1
PART/2, MASS = 3, CM = 7, IP = 10, 10, 10, WZ = 10
MARKER/5, PART = 2
MARKER/7, PART = 2, QP = 1, 0, 0
MARKER/10, PART = 2, REULER = 90D, 90D, 0D
PART/3, MASS = 3, CM = 8, IP = 10, 10, 10, WZ = 10
MARKER/8, PART = 3, QP = 10, 0, 0
JOINT/2, TRANSLATIONAL, I = 9, J = 10
SPRINGDAMPER/1, TRANSLATIONAL, I = 6, J = 8, K = 5, L = 10
ACCGRAV/I=0, J=0, K=0
RESULTS/XRF
END
PART/2 corresponds to the first link and PART/3 is the mass on the tip. Computing an eigensolution using
the default command LINEAR/EIG, we obtain the following results shown in the message file:
This model has
4 kinematic states (displacement and velocities)
0 differential states (DIFFs, LSEs, etc.)
The selected kinematic states are:
1 Global rotation AZ(BCS) PART/2
2 Global displacement DX(BCS) PART/3
The other kinematic states are the respective derivatives.
LINEAR 101
C++ Commands
E I G E N V A L U E S at time = 0.00000E
Number Real(cycles/unit time) Imag.(cycles/unit time)
1 0.00000E
2 0.00000E
3 0.00000E 3.07455E
Notice that the selected states are the global rotation of PART/2 about the z-axis (AZ(BCS) PART/2) and the
global x-displacement of PART/3 (DX(BCS) PART/3). While the first one coincides with the coordinate
alpha used to generate the equations of motion, the second one does not correspond to coordinate u.
The correct results are obtained using the following command:
LINEAR/EIGEN, RM=5
Where MARKER/5 is located on the first link. The corresponding results are:
This model has
0 differential states ( DIFFs, LSEs, etc.)
1 Relative rotation AZ(GROUND,5) PART/2
2 Relative displacement DX(BCS,5,5) PART/3
1 0.00000E
2 0.00000E
3 0.00000E 2.63056E
Notice that the selected states now coincide with α and u and that the results match the theoretical ones.
For an example of using RM, see Simcompanion Knowledge Base Article KB8016438.
5.1.3 Using the PSTATE option

The PSTATE option is used to indicate the ADAMS ID of a PSTATE object. A PSTATE object is a set of
VARIABLES defining user-defined coordinates (see the PSTATE statement). You may want to linearize the
system using specific coordinates that the RM option does not provide. The methodology is:
1. Create as many variables as user-defined coordinates you want Adams Solver (C++) to use when
linearizing the model.
2. Create a PSTATE object and enter the Adams id of all variables created in the previous step.
3. Issue a LINEAR/EIGEN command using the PSTATE=id option.
The following example illustrates these steps.
102 Adams Solver
C++ Commands
Figure 7 Simple model of a rigid helicopter blade
Figure 7 shows a simplified model of a rigid helicopter blade where the first link has a prescribed angular
velocity w. Observe that the system has one degree of freedom but there are several coordinates to choose from
to build the equations of motion. The classical approach is to use angle α but there may be a requirement
to use coordinate y instead.
If the angle α is used, the equation of motion is:

··
( I + ml 2 ) α + mel ω 2 sin ( α – ω t ) = 0
Linearizing this equation in terms of α the following state matrix is obtained (at time t=0):
mel ω 2-
–------------------
[A] = 0
I + ml 2
1 0
and the corresponding frequency is
mel ω
λ 1, 2 = ± i -----------------
I + ml 2
where i is the imaginary constant. Setting m=3, e=2, l=10, I=10, and w=10, we obtain λ = 0.70019 Hz.
The corresponding Adams dataset is:
UNITS/FORCE=NEWTON, MASS=KILOGRAM, LENGTH=METER, TIME=SECOND
PART/1, GROUND
MARKER/6, PART = 1
PART/2
MARKER/5, PART = 2
MARKER/8, PART = 2, QP = 2, 0, 0
PART/3, MASS = 3, CM = 10, IP = 0, 0, 10, WZ = 10
LINEAR 103
C++ Commands
MARKER/7, PART = 3, QP = 2, 0, 0
MARKER/10, PART = 3, QP = 12, 0, 0
MARKER/12, PART = 3, QP = 22, 0, 0
MOTION/1, ROTATIONAL, JOINT = 1, FUNCTION = 10*TIME
ACCGRAV/I=0, J=0, K=0
RESULTS/XRF
END
where PART/2 is the first link and PART/3 is the rigid blade. Running the model with a LINEAR/EIG
command, we obtain the following output:
This model has
0 differential states ( DIFFs, LSEs, etc.)
1 0.00000E 7.00188E-01
Notice the exact match with the theoretical results. However, let's assume you want to linearize the model
using coordinate y instead. If that is the case, the state matrix is now:
melw 2
-----------------
[ A∗ ] = 0 – – w2
I + ml 2
1 0
and the frequencies are:
mel
λ∗ 1, 2 = ± iw -----------------2- + 1
I + ml
Using the same physical parameters, the frequency turns out to be λ = 1.73867 Hz. To obtain this second
result, add the following lines to the dataset file:
VARIABLE/1, FUN=DY(10)
PSTATE/1, VAR=1
Notice that MARKER/10 is located on the CM of the blade, therefore DY(10) is the coordinate y shown in
the figure above. Re-running the model using the following command:
LIN/EIGEN, PSTATE=1
The corresponding results are:
This model has
0 differential states (DIFFs, LSEs, etc.)
1 PSTATE VARIABLE VAR/1 DY(10)
104 Adams Solver
C++ Commands

1 0.00000E 1.73876E
Notice that the results match the theory.

The documentation for the PSTATE statement provides guidelines for the correct definition of user-defined
coordinates. Below is a brief summary:
 The VARIABLE's function expression must define a non constant displacement or angular measure.
 The displacement or angular measure can be global or relative.
 The number of user-defined coordinates can be less than the number of degrees of freedom of the
model. Adams Solver (C++) will complete the state array using coordinates taken from the set of
default coordinates.
 The number of user-defined coordinates can be greater than the number of degrees of freedom of
the model. Adams Solver (C++) selects the required number, ignoring the rest.
 Redundant definitions will be rejected.
 Adams Solver (C++) may ignore a user-defined coordinate if there is already an equivalent default
definition.
For an example of using PSTATE, see Simcompanion Knowledge Base Article KB8016414
5.1.4 Using both the RM and PSTATE options

You may safely use both the RM and the PSTATE options. Adams Solver (C++) assigns a higher priority to
the user-defined states specified by the VARIABLES referenced in the PSTATE object. Default coordinates
generated by the RM option have a lower priority.
For example, the following command linearizes the model using both options.
LINEAR/EIGEN, RM=77, PSTATE=3
5.1.5 Coordinates, Kinetic, Dissipative and Strain options

If you specify the COORDS, KINETIC, DISSIPAT, STRAIN, FCOORDS, FKINETIC, FDISSIPAT or
FSTRAIN arguments, Adams Solver (C++) computes tabular output tables and writes them to an ASCII text
file. The name of the text file has the same base name as the message file and it has an extension *.txt. For
each mode in the specified mode range or frequency range, the printed output could consist of up to five
sections.
The first section is a header that contains the mode number, undamped natural frequency, the absolute value
of the damping ratio, generalized stiffness, generalized mass and model energy for the mode. Generalized
stiffness and generalized mass are in user-specified units. See section Units in Coordinates, Kinetic, Dissipative and
Strain modal tables for units used in the tables.
The following lines show the eigenvalues of simple model (this output is taken from a message file). In this
particular case all eigenvalues have an imaginary part:
E I G E N V A L U E S at time = 0.00000E+00
LINEAR 105
C++ Commands

1 0.00000E+00 +/- 1.59155E+01
2 0.00000E+00 +/- 2.75664E+01
Assuming the above eigensolution was generated using the command:

linear/eigen, coords=1,2, kinetic=1,2, dissipat=1,2, strain=1,2
The corresponding tabular output found in the text file for mode number 1 looks as follows:
------------------------------------------------------------------
Energy table for MODE 1
------------------------------------------------------------------
Damping ratio = 1.20792E-15
Undamped natural freq. = 1.59155E+1 Cycles per unit time
Generalized stiffness = 2.00000E+0 User mass/time^2
Generalized mass = 2.00000E-4 User mass
Kinetic energy = 1.00000E+0 User mass/time^2
For the case of a vibrational mode, Adams Solver (C++) defines the following quantities:
e = a + bi
damping ratio = abs(a/b)
Undamped natural freg. = a×a+b×b

Where e=a+bi is the corresponding eigenvalue. In case the magnitude of the eigenvalue is zero, the damping
ratio is defined as zero. Notice above the printed value of the first eigenvalue's real part is zero. However, this
is just a formatting choice to print zeros for very small numbers. The real part is very small hence the small
value for the damping ratio printed in the header above.
The following lines show the eigenvalues of second simple model where all eigenvalues don't have imaginary
parts:
E I G E N V A L U E S at time = 0.00000E+00
1 -6.83125E-01
2 -2.24739E+00
3 -1.47243E+04
4 -7.57688E+05
This corresponding header for the first mode is now:
------------------------------------------------------------------
------------------------------------------------------------------
Damping ratio = 1.00000E+0
Undamped natural freq. = 6.83125E-1 Cycles per unit time
106 Adams Solver
C++ Commands
Generalized mass = 2.21680E+0 User mass

For the case of non-vibrational modes (imaginary part is zero), the damping ratio and undamped natural
frequencies are defined by Adams Solver (C++) as:
e=a+0*i
damping ratio = 1.0
Undamped natural freg. = abs(a)
In all cases (for either real-only or imaginary eigenvalues), the generalized stiffness, generalized mass and
kinetic energy are defined as follows:
Generalized mass = 2 * (Total energy)
2
Kinetic energy = 2 * (Generalized mass) * a2 * π
Generalized stiffness = 2 * (Kinetic energy)
Where a is real part of the corresponding eigenvalue. The Total energy is computed as the summation of all
the kinetic energy corresponding to all rigid and flexible inertial objects in the Adams model. The kinetic
energy is computed with the velocity entries in the corresponding eigenvector. See more details on the kinetic
energy computation in Section 5.1.6.
The second section is a table of coordinates if the COORDS or FCOORDS argument is specified. This
section is not output if the COORDS or FCOORDS argument is not specified or if the particular mode
number is not within the range specified on the COORDS or FCOORDS argument. Each part in the Adams
Solver (C++) model has one row in this table. The part translational coordinates in columns labeled (X,Y, and
Z), represent the small translational displacements of the part center-of-mass (cm) marker in the global
reference frame. The part rotational coordinates, in columns labeled (RX, RY, and RZ), represent the small
rotational displacements of the part about the global x, y and z axes, respectively. Each coordinate in this table
is represented by a magnitude and a phase. The mode is normalized so that the largest component in the
mode has a value of 1.0 and a phase angle of 0 degrees. Magnitude and phase of all other components in the
mode are reported relative to this largest component. Phase angles are represented in the range 0 to 355
degrees. Phase angles in the range 175 to 185 degrees are reported as 180 degrees. Phase angles in the range
355 to 360 degrees as well as phase angles in the range zero to five degrees are reported as zero degrees. States
of elements resulting in user supplied differential equations are also represented in the coordinate table. All
components with zero magnitude are also reported as having zero phase angles.
The third section is a table of modal kinetic energy distribution if the KINETIC or FKINETIC arguments
are specified. This section is not present in the output for a particular mode if the mode number is not within
the range of the modes specified on the KINETIC or FKINETIC arguments. Each part is represented by a
single row in this table. Each entry in this table represents the percentage of the total modal kinetic energy
for that part in a particular direction. Translational directions in which the modal kinetic energy distribution
is computed are x, y and z displacement of the part center-of-mass (cm) in the global reference frame.
Rotational directions are denoted by RXX, RYY, and RZZ; these represent the small displacement rotations
of the part about the global x, y and z axes, respectively. The cross rotations are represented as RXY, RYZ, and
RXZ. The sum of all values in a modal energy distribution table should be 100.0. Elements resulting in user-
supplied differential equations are not considered in the computation for this table.
LINEAR 107
C++ Commands
The fourth section is a table of modal strain energy distribution if the STRAIN or FSTRAIN argument is
specified. This section is not present in the output for a particular mode if the mode number is not within
the range of the modes specified on the STRAIN or FSTRAIN argument. Each force element is represented
by one or more rows in this table. The table below shows the contribution of various element types to this
table. Computation of strain energy accounts for the direct and indirect dependence of the force on PART
displacements. The indirect dependence on PART displacements may be through dependence of the force
on other FORCEs, VARIABLEs, or algebraic DIFFs that may be directly or indirectly dependent on PART
displacements.
Elements Contributing to Table for Dissipative and Strain Energy Computations
Total X Y Z RX RY RZ
BEAM X X X X X X X
BUSHING X X X X X X X
CONTACT X X X X X X X
FIELD X X X X X X X
GFORCE X X X X X X X
NFORCE for marker 1 X X X X X X X
... X X X X X X X
for marker n X X X X X X X
SFORCE (translational) X X X X
SFORCE (rotational) X
SPRINGDAMPER X X X X
(translational)
SPRINGDAMPER X
(rotational)
VFORCE X X X X
VTORQUE X X X X
In the table, X, Y, and Z refer to translation components along the global x, y and z directions and RX, RY,
and RZ refer to rotational components about the global x, y and z directions. An X indicates locations for
contributions for individual elements. The column labeled Total contains a summation of the
strain/dissipative energy contribution due to the element in various directions.
The fifth section is a table of modal dissipative energy distribution if the DISSIPAT or FDISSIPAT argument
is specified. This section is not present in the output for a particular mode if the mode number is not within
the range of the modes specified on the DISSIPAT or FDISSIPAT argument. Each force element is
represented by one or more rows in this table. The table shows the contribution of elements to this table.
Computation of dissipative energy accounts for the direct and indirect dependence of the force on PART
velocities. The indirect dependence on PART velocities may be through dependence of the force on other
FORCEs, VARIABLEs, or algebraic DIFFs that may be directly or indirectly dependent on PART velocities.
108 Adams Solver
C++ Commands
By default, all tabular real data is printed using a format displaying only two decimal values. If engineering
format is required, use the TABLE_PRECISION option with a value bigger than 2. If the precision is set to
3 or bigger, an engineering (exponential) format is use. Moreover, option NAMES will force Adams Solver
(C++) to add the Adams View names found in the Adams modeling database.
5.1.6 Further details on kinetic energy tables

Modal energy tables are printed to an ASCII *.txt file when the options KINETIC or FKINETIC are used.
This section provides more details on how the kinetic energy tables are computed for the case of rigid PARTs
and FLEX_BODIES. The case of POINT_MASSs is handled similarly. Figure 8 (a) shows a typical PART at
the moment a linearization command is issued. Notice the principal inertia frame 1-2-3 of this PART (in blue
color) is not necessarily coincident with the global reference frame x-y-z shown in black. At the current
principal orientation 1-2-3 the inertia tensor I (considering only the rotational coordinates) is the following:
I1 0 0
I = 0 I2 0
0 0 I3
The first step in preparing the contribution of this PART to the kinetic energy tables is to transform the
principal inertia tensor expressing it in global coordinates coincident with the x-y-z frame as shown in Figure 8
(b).
Figure 8 A PART at the current linearization state.
The inertia tensor of this PART expressed in global coordinates x-y-z is the following:
LINEAR 109
C++ Commands
J xx J xy J xz
T
J = AIA = J xy J yy J yz .
J xz J yz J zz
Where A is the local kinematic transformation from the 1-2-3 frame to the global frame. Notice the terms
J xy , J xz and J yz can be negative. With the inertia tensor aligned with the global reference frame, the
kinetic energy K has this expression:
m 0 0 vx J xx J xy J xz w x
1 T 1 T
K = --- ( v x v y v z ) 0 m 0 v y + --- ( w x w y w z ) J xy J yy J yz w y
2 2
0 0 m vz J xz J yz J zz w z
In the above expression, a variable z with an overbar represents the complex conjugate of z. In order to
compute the kinetic energy, velocities and angular velocities are extracted from the corresponding mode
shape. In general, these quantities are complex numbers. However, given the symmetry of the inertia tensors,
it can be demonstrated that the above expression for the kinetic energy is always a real number bigger or equal
than zero. Introducing the following terms:
1
X = --- mv x v x ,
2
1
Y = --- mv y v y
2
1
Z = --- mv z v z
2
1
RXX = --- J xx w x w x
2
1
RYY = --- J yy w y w y
2
1
RZZ = --- J zz w z w z
2
1
RXY = --- J xy ( w x w y + w y w x )
2
110 Adams Solver
C++ Commands
1
RXZ = --- J xz ( w x w z + w z w x )
2
1
RYZ = --- J yz ( w y w z + w z w y ) .
2
the kinetic energy K can be rewritten as:
K = X + Y + Z + RXX + RYY + RZZ + RXY + RXZ + RYZ .

Notice that the terms associated with cross products (RXY, RXZ and RYZ) can be negative when the
transformation of the principal moment of inertia from local to global coordinates results in negative
products of inertia (off-diagonal terms).
Adams Solver computes the quantities X, Y, Z, RXX, RYY, RZZ, RXY, RXZ and RYZ and prints them as
shown below.
The kinetic energy for FLEX_BODYs has the following expression:
M tt M tr M tm
v
1 · T T
K = --- ( vwq ) M tr M rr M rm w .
2
T T
M tm M rm M mm q·
Here v, w and q· stand for vector quantities (velocity, angular velocity and modal velocities respectively) and
the overbar indicates a complex conjugate. The notation matches that of the FLEX_BODY theoretical
documentation.
Notice matrix Mtt is a 3x3 diagonal matrix with the total mass of the body in the diagonal terms. Notice also
that matrix Mrr is similar to the inertia tensor of a rigid PART. Hence, the contributions of the rigid body
motion of the FLEX_BODY is computed exactly the same way as computed for a rigid PART. Therefore the
kinetic energy of a FLEX_BODY is expressed as:
K = X + Y + Z + RXX + RYY + RZZ + RXY + RXZ + RYZ + Modal

Where Modal has the following expression:
LINEAR 111
C++ Commands
0 M tr M tm
v
1 · T T
Modal = --- ( vwq ) M tr 0 M rm w
2
T
M tm M rm M mm
T q·
Previous to version Adams 2013, the Modal contribution was not reported; that was the reason the kinetic
energy did not sum up to 100% in models having flexible bodies.
Starting Adams 2013, the energy tables do report the Modal values along with the total kinetic energy per
body. An example typical table is shown below.
Notice in this example the RXY contribution of the rigid PART/2 is negative. Notice also the Modal
contribution is particularly important in this case.
5.1.7 Kinetic energy reported in Adams View

Previous section describes the ASCII *.txt output generated by Adams Solver in batch mode or when running
the external solver from Adams View. When running the internal solver, the Modal kinetic energy reported
by Adams View is split into two terms. The Modal contribution is rewritten as follows:
Modal = Modal 1 + Modal 2

Where
1 T 1 1 1
Modal 1 = --- q· M mm q· = --- q· 1 M mm 1 q· 1 + --- q· 2 M mm 2 q· 2 + … + --- q· n M mmn q· n
2 2 2 2
0 M tr M tm
v
1
--
- · T T
Modal 2 = ( vwq ) M tr 0 M rm w
2
T T
M tm M rm 0 q·
112 Adams Solver
C++ Commands
Term Modal1 is displayed in a two-column table showing the contribution of each individual mode i and
1
--- q· M mmi q· i . Term Modal2 is lumped into a single number called Offset Diagonal
corresponding value
2
Coupling.
5.1.8 Differences in results compared with Adams Solver FORTRAN

Adams Solver FORTRAN uses an old linearization technology limited to providing good results for static
cases only. Adams Solver FORTRAN finds the linearization matrix by assembling the static equations and
extracting the linearization matrix from the statics equations to solve. Perhaps the major limitation of Adams
Solver FORTRAN is that the linearization matrix is obtained in terms of the simulation states only (global
translations and global Euler angles). Adams Solver C++, on the other hand, uses a modern and general
algorithm suitable for all operating points (static and dynamic) with no simplifications. Moreover, Adams
Solver C++ can linearize the system in terms of arbitrary coordinates; its algorithm is not constrained to use
the coordinates used in formulating the equations of motion, any coordinate definition can be chosen. Users
may also define the linearization states to be used in the linearization and obtain custom linear representations
for the system.
Regardless of the implemented linearization algorithm, the first step is the selection of the independent states
for the linearization. The independent states correspond to the minimal state-space representation of the
system. When using Adams Solver FORTRAN, the independent states are a subset of the coordinates used
to solve the equations of motion (global translations, global Euler angles, differential states). When using the
Adams Solver C++, the default linearization states are a subset of global translations and instantaneous global
rotations about GROUND origin. The decision was made based on the popularity of global rotations in FEA
codes. Hence, the main difference between Adams Solver FORTRAN and Adams Solver C++ is the set of
linearization states. Although linearization states may be different, eigenvalues may match (see reference
mentioned in Section 1.0). However, modal table results may be different but both are correct. To illustrate
this point the model in Figure 9 shows a simple model of a vertical pendulum (red box with a hinge on top)
connected by a spring-damper to GROUND (blue box on the right).
LINEAR 113
C++ Commands
Figure 9 A simple pendulum with a spring-damper force.
The data set describing this model is presented in the Appendix, Listing 6, Listing 7 and Listing 8 show the
command files *.acf used to linearize this model using Adams Solver FORTRAN and Adams Solver C++
respectively. Running both solvers the reader can verify both solvers provide the same eigensolution but
different results in selected linearization states and different results in modal tables (generalized mass, general
stiffness). Observing the message files created by both solvers we first notice the following. The FORTRAN
solver reports:
SCRCRD:COORDS
Coordinate X of PART/2 (model_1.PART_2)
While the C++ solver reports:

Notice the FORTRAN solver selected the horizontal displacement of PART/2 while the C++ solver selected
the instantaneous rotation of PART/2 as the respective linearization states. Notice although different, the
114 Adams Solver
C++ Commands
selected states provide the same eigenfrequency. However, inspecting the *.out file created by the FORTRAN
solver, we find:

Undamped natural freq.= 9.59339E-01 Cycles per second
Generalized stiffness = 4.09672E+00 User mass/second^2
Generalized mass = 1.12754E-01 User mass
Kinetic energy = 2.04836E+00 User mass/second^2
While the results printed by the C++ solver (in an *.txt) file are:

These results while different are correct given that the generalized mass and generalized stiffness are based on
the mode shape which in turn depend on the selected linearization states. Nevertheless, the C++ solver can
match the results of the FORTRAN solver by using the PSTATE option. In that regard, Listing 9 shows the
command file used to run the C++ solver. Listing 9 executes the linearization using a custom coordinate
defined by VARIABLE/5:
VARIABLE/5
, FUNCTION = DX(7)
VARIABLE/5 defines the global horizontal translation of PART/2 (used by the FORTRAN solver). Running
the C++ solver and observing the message file we find:

1 PSTATE VARIABLE VAR/5 DX(7)
This message means the C++ solver honored the request of the PSTATE option in the LINEAR command.
The reader can now verify the *.txt created by the C++ solver matches the computation of the FORTRAN
solver.
5.1.9 Advanced eigensolution issues

In case you need to compare the computed eigensolution with results from another software package, you
may export the linearization matrices using the LINEAR/STATEMAT option. The exported [A] matrix is
the one we send to the eigensolver.
In general, the issues affecting the quality of the eigensolution are the following:
a. Models in singular configurations. Models in singular configuration may report spurious modes
and frequencies or they may report different values (with a sign reverse) under small perturbations.
LINEAR 115
C++ Commands
For instance, the beam shown in the figure above is at an unstable equilibrium position. A small
perturbation moving the tip downward will cause the torque to restore the previous equilibrium
position (complex eigenvalue). However, a small perturbation moving the tip upward will case
the system to move away from the horizontal position (real eigenvalue). At exactly the horizontal
position the eigenvalues are zero. Solving a complex system with the same overall topology may
results in spurious eigenvalues.
b. Accelerating models. Accelerating or rotating components usually involve mode shapes involving
velocity states and may show strange mode shapes.
c. Multiple rigid body modes. If the model has the potential to experiment rigid body motion, the
eigensolver may show up with noisy frequencies instead of a zero value. This depends on the size
of the model. Moreover, if the model has DIFFs or LSEs or GSEs or TFSISOs objects, then some
modes will be related to the differential states with almost no coupling with overall motion of the
system. Those modes will show no animation.
d. Overdamped models. Damping may create spurious modes that create clutter and make difficult
to find the modes of interest. Since the damping is hard to estimate, we recommend also running
the eigensolution with the NODAMP option to gain perspective on the interesting modes.
Damping can be added afterward to estimate its influence in the solution.
e. Friction in stiction regime. If the model has FRICTION objects running in the stiction mode,
you may get spurious frequencies and mode shapes due to the stiffness of the force element added
to model the stiction.
f. Numerical limitations. In general, the linearization matrix [A] is non-symmetric, ill-conditioned
and sparse. In addition, there is a natural limitation in the precision of the arithmetic operations
of the computer. The end results may be that frequencies and mode shapes may include noisy
results especially in both the lower end of the real eigenvalues (real-only eigenvalues with small
values) and in the lower imaginary spectrum (complex eigenvalues with small imaginary part).
Higher real-only eigenvalues and higher imaginary eigenvalues are usually better extracted.
5.1.10 Eigenvectors and mode shapes

The technical literature usually makes no difference between an eigenvector and a mode shape by using the
terms interchangeably. In Adams, however, we use the term eigenvector for the vectors z in the solution of
the complex eigenproblem:
Az = μz
where matrix A corresponds to the minimum state-space representation of the model. The size of array z, in
the most general case, has this value:
116 Adams Solver
C++ Commands
N = 2 ⋅ nq + nd
where n q is the number of degrees of freedom and n d is the number of differential equations in the model.
The number of degrees of freedom is computed from:
nq = nX – m
where n X is the number of coordinates used to define the model and m is the number of constraint
equations. Adams Solver C++ does not scale the eigenvectors z nor makes them available for the user. If there
is a need to obtain the z eigenvectors, the user may obtain the A matrix using the STATEMAT option and
compute the eigenvectors using a third party code. Notice that n q ≤ n X which implies only a subset of all
coordinates is used perform the linearization. Moreover, the user may define linearization states using the
PSTATE option. In any case, the list of linearization states is printed in the message file and exported to a
text file when using the STATEMAT option.
When using the Post-processor, the raw eigenvectors z are not usable for visualizing the vibrations of the
model. In order to visualize the vibrations of the model, Adams defines the mode shapes as follows:
ϕ = Tz
where matrix T is a transformation from the minimal state-space representation to the full set of coordinates
used in the model. Matrix T is obtained during the reduction from the full Lagrange equations of motion to
the minimum state-space representation. Mode shapes ϕ are scaled by searching for the entry with the largest
modulus and dividing the vector by the entry with the largest modulus.
The size of the mode shapes is given by the following expression:
S = 2 ⋅ nX + nd
Mode shapes ϕ are available to the user in the results files and they are used by the Post-processor to perform
animations of the vibrating model. Mode shapes are also printed to a text file when using the COORD option
in the LINEAR command.
5.1.11 Units in Coordinates, Kinetic, Dissipative and Strain modal tables

Given that Modal coordinates tables, as well as kinetic, dissipative and strain energy tables are computed
using normalized eigenvectors, length units have been dropped out.
For example, the generalized stiffness and the kinetic energy are displayed using units of User-mass/time^2:
-----------------------------------------------------------
-----------------------------------------------------------
Damping ratio = 1.00000E+0
LINEAR 117
C++ Commands
Theoretically, energy has units of mass times velocity square. Dropping the length dimension, we obtain
mass/time^2.
5.2 State matrices and MKB computation
5.2.1 Scope
If you issue the LINEAR/STATEMAT command, Adams Solver (C++) computes the state matrices
representation of the Adams model. The linearized Adams model is represented as:
s· = As + Bu
y = Cs + Du
where:
 Vector s represents the state variables of the plant model. The state variables can be user-defined
coordinates (see the RM and PSTATE options). By default, the state variables are displacements, modal
coordinates (from flexible elements) and their corresponding time derivatives. The state variables
also include all of the differential states from DIFs, LSEs, GSEs and TFSISOs.
 Vector u represents the inputs of the plant model.
 Vector y represents the outputs from the plant model.
 Matrices A, B, C, and D are the state-space matrices representing the plant.
Matrices A, B, C and D are exported to the text file specified in the FILE option of the command. The
exported text file includes a STATES matrix with information on the state vector s. Moreover, the export will
create matrices PINPUT and POUTPUT with information on the inputs and outputs to the plant.
Vector s stands for the minimum state-space realization of the model. If you do not specify RM nor PSTATE
options, Adams Solver (C++) will select the best choice of the coordinates in order to perform the
linearization of the model. In general, vector s will have this format:
118 Adams Solver
C++ Commands
Where xi stands for a position state, vi stands for the corresponding time derivative, and zi stands for a
differential state in the model. You could inspect vector s in the output file under the STATES matrix. See
Section 5.2.6 for more information on the contents of the STATES matrix.
Caution: Vector s has a different format if the MKB option is selected instead.
By default all exported matrices (A, B, C, D, STATES, PINPUT, POUTPUT) are exported in a single file
using the MATRIXX format. If you specify the FORMAT=MATLAB option in the command, then Adams
Solver C++ will export up to seven files named xxxa, xxxb, xxxc, xxxd, xxxst, xxxpi and xxxpo, where 'xxx'
stands for the root filename specified in the mandatory FILE=filename option of the LINEAR/STATEMAT
command.
If you specify the MKB option, Adams Solver (C++) computes an alternative form of the state matrices
representation for an Adams model. In this case, the linearized Adams model is first linearized in this format:
mx· + kx + A 4 z + bx· = pu
z· + A 1 x + A 2 z + A 3 x· = 0
x 
 
y = C  z  + Du
·
x 
Where x are the position level linearization states and z stands for the differential states. Defining:
x· – v = 0
The state vector s is defined now as:
LINEAR 119
C++ Commands
With this definitions the first equations of the state representation can be written as follows:
·
I 0 0  x  0 0 –I  x 
  0
0 I 0  ·
z + A A A z = 0 u
1 2 3  
 ·  
0 0 m v  k A4 b  v  p
Defining:
I 0 0 0 0 –I 0
M = 0 I 0 , KB = A 1 A 2 A 3 , P = 0
00m k A4 b p
We obtain:
Ms·· + KBs = Pu
y = Cs + Du
where:
 Vector s represents the state variables of the plant model. The state variables can be user-defined
coordinates (see the RM and PSTATE options.) In this case the state variables are the displacements,
modal coordinates (from flexible elements) and all differential states from DIFS, LSEs, GSEs and
TFSISOs.
 Vector u represents the inputs of the plant model.
 Vector y represents the outputs from the plant model.
 Matrices M, KB, C, P and D are state matrices representing the plant.
Matrices M, KB, P, C and D are exported to the text file specified in the FILE option of the command. The
exported text file includes a STATES matrix with information on the state vector s. Moreover, the export job
will create matrices PINPUT and POUTPUT with information on the inputs and outputs to the plant.
The MKB option is useful if you need to export the Adams model to be a subsystem of an MSC.NASTRAN
model.
5.2.2 Using the RM and PSTATE options

See sections Using the RM and PSTATE options.
5.2.3 Plant inputs and Plant outputs

You can specify the definition of plant inputs with the PINPUT argument value. Similarly, plant outputs are
specified by the POUTPUT argument. States variables (x) are automatically selected by Adams Solver (C++)
out of the total set of coordinates used to model the mechanical system. However, using the RM and/or the
PSTATE options, you may have Adams Solver (C++) use user-defined coordinates for linearization. This is
120 Adams Solver
C++ Commands
particularly important for rotating systems. While several PINPUT statements and POUTPUT statements
may be present in an Adams model, you can specify only one of each on the LINEAR command.
Corresponding to each VARIABLE id specified on the PINPUT statement, a column exists in the B and D
matrices (STATEMAT option). Similarly, for each VARIABLE id specified on the POUTPUT statement, a
row exists in the C and D matrices. In effect, each VARIABLE id specified on the PINPUT or POUTPUT
statement specifies an input or output channel, respectively.
Input channels are important in the computation of state matrices. It is important to notice that Adams
Solver (C++) assumes the function expressions of all input channels are zero. If the function expression of an
input VARIABLE is not zero, then you have two choices to properly model the system (assume the original
input variable is VARIABLE/f ):
1. Remove VARIABLE/f from the INPUT statement. This is usually the simples and correct choice.
2. Create a new VARIABLE/d and add it to the INPUT statement. Remove VARIABLE/f from the
INPUT statement and modify its function expression to original_expression + VARVAL(d). Choose
this approach if you need to keep the size of the B to an specified value.
Following the above recommendation you may properly model both open-loop and close-loop control
systems.
Tip:  To reduce computing time, specify the NOVECTOR argument with the EIGENSOL
option if mode shapes are not desired.
 Specify the LINEAR command to assess stability of Adams models by computing its
eigenvalues. Eigenvalues with positive real parts correspond to unstable modes of the
system.
 If you specify the PINPUT and the POUTPUT arguments for state matrices output,
Adams Solver (C++) produces all four matrices (A, B, C, and D). If you do not specify the
PINPUT argument, Adams Solver (C++) does not produce the B or D matrices. Similarly,
if you do not specify the POUTPUT argument, Adams Solver (C++) will not produce the
C or D matrices. If you do not specify either the PINPUT or POUTPUT arguments,
Adams Solver (C++) produces only the A matrix.
 You may define several PINPUT and POUTPUT statements in an Adams Solver (C++)
dataset, however, a LINEAR command allows only one PINPUT and one POUTPUT
statement to be specified at a time. If you issue a series of LINEAR commands, Adams
Solver (C++) computes alternate state matrix descriptions at the same operating point with
different combinations of PINPUT and POUTPUT identifiers. Changes in the PINPUT
and POUTPUT descriptions are reflected in the A, B, C, and D matrices.
5.2.4 MATRIXX format

State matrices output by Adams Solver (C++) in the MATRIXX format conforms to the MATRIXx FSAVE
ASCII file specification. These specifications are given in the Xmath Basics Guide, 1996, Integrated Systems
Inc., Santa Clara, CA.
LINEAR 121
C++ Commands
More than one matrix may be present in a single file. The Adams Solver (C++) state matrices file can have up
to seven matrices. The first four matrices are the A, B, C, and D state matrices. The next three matrices are
STATES, PINPUT, and POUTPUT. The contents and format of these matrices are explained in the next
sections.
5.2.5 MATLAB format

State matrices output by Adams Solver (C++) in the MATLAB format conform to the ASCII flat file format.
This format requires that all entries in a row of the matrix be written in a single record. Successive values in
a row are separated by a single space. A file is allowed to contain only one matrix. Therefore, Adams Solver
(C++) may create up to seven output files, one each for the A, B, C, and D matrices, one for STATES, one
for PINPUT, and one for POUTPUT. The contents and format of the last three matrices are as shown in the
next sections. The file name you specify is used as a base name and is appended with the matrix name to write
the matrix of the appropriate type. The file names used for the seven matrices are as given in the table below.
File Names Used for MATLAB State Matrices Output
Matrix Name file Name

A "base_name" "a"
B "base_name" "b"
C "base_name" "c"
D "base_name" "d"
STATES "base_name" "st"
PINPUT "base_name" "pi"
POUTPUT "base_name" "po"
5.2.6 Contents of the STATES matrix

The STATES matrix contains information regarding states that Adams Solver (C++) has chosen for the state
matrices representation. For each state, one record exists in this matrix. The following information is
contained in each record:
Type_of_element Element_identifier Element_coordinate
Type_of_element
Type_of_element can take on the following values:
1. PART coordinates (using Euler angles)
2. States in a LSE element
3. States in a TFSISO element
4. States in a GSE element
5. Diff variable
122 Adams Solver
C++ Commands
6. Coordinate for a PTCV element

7. Coordinates for a CVCV element
8. FLEX_BODY element
9. POINT_MASS element
10. PSTATE variable (a VARIABLE used in a PSTATE object)
11. Derivative of a PSTATE variable
21. PART coordinates (no RM option was used)
28 FLEX_BODY element (no RM option was used)
29 POINT_MASS element (no RM option was used)
31 PART coordinates (RM option was used)
38 FLEX_BODY element (RM option was used)
39 POINT_MASS element (RM option was used)
Element_identifier
Element_identifier is the eight-digit Adams Solver (C++) identifier of the element.
Element_coordinate
If Type_of_element=1, the Element_coordinate can take on the values:
1 Global x-displacement of PBCS (See the Note: below)
2 Global y-displacement of PBCS
3 Global z-displacement of PBCS
4 Global Ψ angle of part principal axis of PBCS
5 Global θ angle of part principal axis of PBCS
6 Global φ angle of angle of part principal axis of PBCS
7 to 12 Correspond to the respective derivatives
Note: PBCS stands for Principal Body Coordinate System. PBCS is a frame coincident with the
PARTs CM MARKER but it is oriented along the principal inertia axis. PBCS is an internal
MARKER used by Adams Solver (C++) to build the equations of motion.

1 Global x-displacement of BCS (See the Note: below)
2 Global y-displacement of BCS
3 Global z-displacement of BCS
4 Global rotation of BCS about the global x-axis
5 Global rotation of BCS about the global y-axis
LINEAR 123
C++ Commands
6 Global rotation of BCS about the global z-axis

Note: BCS stands for Body Coordinate System. For details on BCS, see the PART command.

1 Relative x-displacement of BCS with respect to the RM marker
2 Relative y-displacement of BCS with respect to the RM marker
3 Relative z-displacement of BCS with respect to the RM marker
4 Relative rotation of BCS about the x-axis of the RM marker
5 Relative rotation of BCS about the y-axis of the RM marker
6 Relative rotation of BCS about the z-axis of the RM marker
For Type_of_element=2 to 5, Element_coordinate is the sequence number in the set of states defining that
element.
For Type_of_element=6, the only permissible value for Element_coordinate is 1, that is, the alpha parameter
value that defines the contact point on the curve.
For Type_of_element=7, Element_coordinate may take on the value of 1 or 2, representing the parameter
values for the first (I) or second (J) curve in a CVCV statement that defines the contact point on the curve.
For Type_of_Element=8, the Element_coordinate can take on the values:
1 - 12 same as for Type_of_Element=1
1 E6 + n nth modal generalized coordinate
2 E6 + n first time derivative of the nth modal generalized coordinate
For Type_of_Element=9, the Element_coordinate can take on the following values:
4 - 6 Correspond to the respective derivatives
124 Adams Solver
C++ Commands

4 -6 Correspond to the respective derivatives
4 -6 Correspond to the respective derivatives
For Type_of_Element=10, the Element_coordinate takes the value 1.
For Type_of_Element=11, the Element_coordinate takes the value 2.
In the MATRIXX format, this data is organized in column order form so that the STATES matrix contains
three rows and number of columns is equal to the number of states in the model. In the MATLAB format,
this data is organized in the row order form. Therefore, the STATES file contains data organized in the three
columns and the number of rows is equal to the number of states in the model.
For example, find the states used by the linearization computation from the listing shown below (the listing
is obtained by using the FILE and MATRIXX options in a STATEMAT or MKB)
STATES 3 2 0(3(1PE25.17))
2.10000000000000000e+01 3.00000000000000000e+00 1.20000000000000000e+01
2.10000000000000000e+01 3.00000000000000000e+00 6.00000000000000000e+00
The first column shows a 21, which stands for a PART. No option RM was used in the linearization
command. The second column shows a 3 which stands for the ADAMS id of the PART. The third column
shows a 12 and a 6, therefore the states used by the linearization are:
1. Global rotation of the BCS of PART/3 about the global z-axis
2. The derivative of the global rotation of the BCS of PART/3 about the global z-axis.
5.2.7 Contents of the PINPUT and POUTPUT matrices

The first record in the PINPUT (or POUTPUT) exported matrix data contains the Adams Solver (C++)
identifier of the PINPUT (or POUTPUT) statement that was used on the LINEAR command to generate
these state matrices. Subsequent records contain the Adams Solver (C++) identifiers of the VARIABLE
statement identifiers used on these statements. In the MATRIXX as well as the MATLAB format, this data
is organized as a matrix with 1 column and number of rows equal to one plus the number of variables on the
PINPUT (or POUTPUT) statement.
All data for the STATES, PINPUT, and POUTPUT matrices is written as floating point data.
5.3 Nastran bulk data deck export
5.3.1 Scope
Using the EXPORT option Adams Solver (C++) exports the linearized Adams model as a set of Nastran bulk
data deck files. The Nastran bulk data deck export is also known as "Adams-to-Nastran". In a few words, this
option creates an equivalent Nastran model (linear model) equivalent to the Adams model at the operating
point when the export command is executed. Adams-to-Nastran can be seen as a model translation process.
LINEAR 125
C++ Commands
The translation process is done with high fidelity. For medium to small models, eigenvalues computed in the
Adams environment will match eigenvalues computed in the Nastran environment.
The syntax to invoke the EXPORT job calls for the type of export (WHITEBOX or BLACKBOX), the name
of the main bulk data deck file to be created (FILE argument), and an optional name for a configuration file
(CONFIG argument). The configuration file is useful to customize the export process.
The translation process supports two types of EXPORT jobs, namely, a WHITEBOX option or a
BLACKBOX option which must be specified using the TYPE argument. These two types are conceptually
different. Using the BLACKBOX option, Adams Solver (C++) computes the MKB matrices and exports the
model as a set of three DMIGs. Individual contributions to the MKB matrices from all of the inertial
elements, applied forces and constraints cannot be identified, hence the exported model is practically non
modifiable. On the other hand, using the WHITEBOX option, the linearized model is exported as a set of
Nastran cards where an element-to-element translation takes place; this option exports a model that can be
further edited and modified.
Using the EXPORT option, a configuration file can be specified to fine tune the export job. The syntax of
the configuration file allows the user to select the solution number, specify exported MARKERS, single out
applied forces, change the default numbering of GRID and other Nastran cards, select include directories,
choose a type of graphical output, select a style of file generation, etc.
5.3.2 Limitations
There are no limitations on the type of previous analysis prior to the invocation of the LINEAR/EXPORT
command if using the BLACKBOX export type. Also, eigenvalues computed by Nastran on the exported
model will match eigenvalues computed by Adams on the Adams model. In a few words, both, static and
dynamic operating points are supported by the BLACKBOX export.
When using the WHITEBOX export type, we guarantee matching eigenvalues computed by both, Nastran
and Adams, only if the operating point is a static one (if the previous simulation in Adams was either STATIC
or QUASISATIC). Notice that a STATIC simulation at time t=0 may not be a truly static operating point
because Adams Solver restores the initial velocities found in the model. This restoration of velocities after a
STATIC simulation at time t=0 can be avoided by setting the environment variable
MSC_ADAMS_STATICS_NO_RESTORE_VELOCITIES.
If the previous simulation done by Adams is a dynamic or kinematic analysis, the exported model includes
TIC cards defining the velocities of the model. However, eigenvalues computed by both, Nastran and Adams
will not necessarily match. This is not a limitation on the Adams side but a limitation inherent to most
linear/nonlinear Finite Element codes available in the market.
If the operating point is KINEMATIC (no degrees of freedom), the only type allowed is WHITEBOX. No
BLACKBOX export is possible for that type of operating point.
5.3.3 BLACKBOX and WHITEBOX exported cards

The BLACKBOX option exports the following cards:
1. One DMIG for each of the mass, stiffness, and damping matrices. The BLACKBOX option exports
the model as a state-space set of matrices.
2. A set of SPOINTs to define the states of the model and one GRID fixed to the origin.
126 Adams Solver
C++ Commands
The WHITEBOX option exports the following cards:

1. A set of GRID cards representing the center of mass of each PART, POINT_MASS and
FLEX_BODY in the Adams model. Depending of the style chosen by the user, this information may
be included in a single file or in a set of files. See directive file_name_styles for more information
below.
2. One GRID fixed to the origin.
3. A set of SPOINT cards representing differential states from DIF, LSE, TFSISO and GSE objects in
the Adams model.
4. A set of CONM2 cards representing PART and POINT_MASS objects in the Adams model.
5. As set of RJOINT and/or MPC cards representing each of the JOINTS, GCON, JPRIM and
MOTION objects in the model.
6. A set of DMIG cards representing the dynamic contributions from DIF, LSE, TFSISO and GSE
objects in the Adams model.
7. A set of DMIG representing the contribution of applied forces, gravity and flexible bodies. By default,
all applied force, gravity and flexible bodies are exported into a single DMIG. The configuration file
can be used to single out applied forces and flexible bodies. There are configuration directives to
export forces using CBUSH cards.
8. By default, the WHITEBOX option exports the geometric entities found in the Adams model as fully
constrained triangular or quadrilateral shell elements with a small thickness. The exported geometries
do not add degrees of freedom to the Nastran model. For the case of geometries attached to an Adams'
RIGID PART, the exported geometry is fully constrained to the GRID corresponding to the center
of mass of the RIGID PART using RBE2 cards. For the case of FLEX_BODYs in Adams, the
exported geometry corresponds to the tessellation (triangles only) used internally by Adams. Note the
tessellated geometry does not match the element geometry found in the original FEA model nor the
"surface geometry" found in the created mnf (modal neutral file). Moreover, the exported
FLEX_BODY's geometry to Nastran will be constrained to the global reference frame (it will not
deform during a mode shape animation in Nastran).
Both, BLACKBOX and WHITEBOX options export the following cards
1. If the configuration file defines outputs channels and solution 108 is specified, the bulk data will
include a set of CORD2R and GRID cards representing the output channels. Along with each GRID
card, a set of MPC cards are exported.
2. If the configuration file defines input channels and solution 108 is specified, the bulk data will include
a set of CORD2R and GRID cards representing each of the input channels. Along with each GRID
card, a set of MPC cards are exported.
3. If the configuration file defines subcases, the bulk data will include a FREQ1 (or FREQ2) card. A set
of TABLED1 cards to define the force magnitude of the actuators, and a set of DLOAD cards and
corresponding RLOAD1, FORCE, MOMENT and DPHASE cards defining the input channels, are
also included.
4. By default, solution 107 and corresponding cards are exported. The configuration file can be used to
select solution 108.
LINEAR 127
C++ Commands
5. A set of CORD2R and GRID cards representing Adams MARKERS in the model. Each exported
Adams MARKER creates GRIDs (with corresponding RBE2 cards) or a set of required MPC cards.
MARKERS are not exported by default if BLACKBOX type is selected. See the syntax of the
configuration files to export Adams MARKERS.
5.3.4 Configuration file syntax

The configuration file is an ASCII file used to fine tune the export job. The file can be seen as a set of
configuration directives and data definitions. Configuration directives have the syntax:
KEY = VALUE1 [, VALUE2]
Data definitions have the syntax:
DATA_NAME {
KEY = VALUE1 [, VALUE2]
…
}
If a KEY is repeated, the latest definition is used. Comments start with the character $. The contents are case
sensitive.
Supported directives
The list of current supported directives, using the following format:
Syntax
Example
Explanation
128 Adams Solver
C++ Commands
actuator_swept_sine {
name = [string]
magnitude = [real]
phase_angle = [angle]
}
name = actuator_1
magnitude = 2.2
phase_angle = 45D
}
Creates an actuator to be used in the creation of an input channel. Field name
is required and the value of the given name is case sensitive. The phase_angle
is to be given in radians. A "D" can be used to specify degrees. Both magnitude
and phase angle are optional; defaults are 1.0 and 0.0 respectively.
Ignored if solution 107 is specified.
Required if solution 108 is specified.

LINEAR 129
C++ Commands
add_space_before_names= {yes | no }
add_space_before_names = yes
If this directive is set to yes, Adams Solver adds a space between the leading $
and the name of the Adams object when exporting its equivalent Nastran
cards.
Optional in all types of solution sequences.
Ignored if job is BLACKBOX
Default is no.
all_flexbodies_editable = [yes| no]

all_flexbodies_editable = no
Specifies to export all flexible bodies one by one creating sets of DMIGs per
body.
Ignored if job is BLACKBOX.
Default is yes.
all_forces_editable = [yes|no]
all_forces_editable = no
Specifies to export all forces creating a CBUSH and residual DMIGs per
forcing object.
Default is yes.
130 Adams Solver
C++ Commands
automset = { yes | lusol }

automset = yes
Sets the value of the AUTOMSET option in the exported Nastran dataset
deck.
Beginning Nastran 2016, a new option LUSOL is available. Must be used with
value 'yes' for previous versions of Nastran.
Default is lusol.
begin_frequency = [real]
begin_frequency = 1.0
Sets the initial value of the frequency for a frequency response analysis.
clan_region= [real], [real], [real], [real], [real], [integer]

clan_region= 1.2, 4.0, 6.4, 4.0, 1.1, 20
Specifies the parameters ALPHAAJ, OMEGAAJ, ALPHABJ, OMEGABJ, LJ
and NDJ, defining a search region when using the eigc_method = clan
directive.
You may enter as many clan_region directives as needed.

LINEAR 131
C++ Commands
cmethod_number = [integer]
cmethod_number = 445
Sets the number of CMETHOD card.
Optional if solution 107 is specified.
Default is 101.
cbush_offset = [integer]
cbush_offset = 7000000
Sets the offset number of the CBUSH card to be exported.
Optional if job is WHITEBOX.
Default is 6000000.
conm2_offset= [integer]
conm2_offset = 2000
Sets the initial id value of the CONM2 exported cards.
Default is 1.
cord2r_offset = [integer]
cord2r_offset = 600
Sets the number of the first CORD2R card to be exported.
Default is 100.
132 Adams Solver
C++ Commands
cquad4_offset= [integer]
cquad4_offset = 2000
Sets the initial id value of the CQUAD4 exported cards.
Default is 1.
crod_offset= [integer]
crod_offset = 2000
Sets the initial id value of the CROD exported cards.
Default is 1.
ctria3_offset= [integer]
ctria3_offset = 2000
Sets the initial id value of the CTRIA3 exported cards.
Default is 1.
LINEAR 133
C++ Commands
debug = { yes | no }
debug = yes
Causes Adams Solver (C++) to output each of the directives found in the
configuration file and print detailed information of each processed directive.
Default is "no".
differentials_dmig_name = [string]
differentials_dmig_name = ZQ
If job is WHITEBOX, defines the name of the DMIG used to export the
stiffness and damping contribution of all differential elements (DIFF, LSE,
TFSISO and GSE). Adams Solver (C++) will append the given name to
predefined roots to form the names of the matrices to be exported.
Default is ZZZ.
disp_plot_punch = {string}
disp_plot_punch = plot
Prints PLOT, PUNCH or both in the DISP cards. Options for the string: plot,
punch, and both.
Default is "both".
134 Adams Solver
C++ Commands
displacement_output_channel {
name = [string]
marker_id = [integer]
marker_name = [string]
mode = { local | global }
}
name = oc_1
marker_by_name = model.MARKER_77
mode = local
}
Creates an output channel.
Field name is required; the given name is case sensitive.
Either marker_id or marker_name must be specified to define the location of

the output channel.
Field mode is optional and it specifies whether the output channel reports
global or local information about the specified MARKER; the default value is
"local".
dload_card_number = [integer]
dload_card_number = 558
Sets the number of the first DLOAD card. See
dload_card_number_increment.
Default is 100.
LINEAR 135
C++ Commands
dload_card_number_increment = [integer]
dload_card_number_increment = 2
Sets the increment when numbering DLOAD cards.
Default is 1.
dphase_card_number = [integer]
dphase_card_number = 658
Sets the number of the first DPHASE card. See
dphase_card_number_increment.
Default is 400.
136 Adams Solver
C++ Commands
dphase_card_number_increment = [integer]
dphase_card_number_increment = 2
Sets the increment when numbering DPHASE cards.
Default is 1.
LINEAR 137
C++ Commands
eigc_method = [hess | clan]

eigc_method = clan
Specifies the method of eigenvalue extraction in the exported EIGC card.
Option hess refers to the upper Hessenberg method. Option clan refers to the
Complex Lanczos method. When using the clan option, use the clan_region
directive as many times as required.
Default is “hess”.
end_frequency = [real]
end_frequency = 1.0E+09
Sets the final value of the frequency for a frequency response analysis.
export_all_markers = { yes | no }
export_all_markers = yes
Causes to export all rigid and flexible MARKERS.
Ignored if job is WHITEBOX.
Default is "no".
138 Adams Solver
C++ Commands
export_cbush= {yes | no }
export_cbush = yes
If this directive is set to yes, Adams Solver will attempt to export selected forces
using CBUSH cards. The selected forces are singled out using the directives
force_editable_by_id and force_editable_by_name. If the attempt fails, the
force will be exported using DMIG cards.
Default is “yes”.
export_external = { yes | no }
export_external = no
If this directive is set to yes, Adams Solver exports EXTERNAL objects using
CTRIA3 elements.
export_graphics = { yes | no }
export_graphics = no
If this directive is set to yes, Adams Solver exports a set of cards defining the
geometric elements found in the Adams model. Cylinders, boxes, spheres, etc.
are exported as CQUAD4 elements fully constrained to the corresponding
exported parts. All the elements used to define the geometry of the Adams
model have negligible mass hence, results are not affected.
See Section 5.3.3 regarding the export of geometric entities.
Default is "yes".
LINEAR 139
C++ Commands
export_ground_markers = { yes | no }
export_ground_markers = yes
Causes to export all ground MARKERS found in the Adams model.
Default is "no".
export_markers_by_id = [list of ranges]

export_markers_by_id = 1, 3, 45-52, 88
Causes to export rigid, flexible or ground MARKERS. An error is triggered if
the given ID corresponds to a floating, curve or surface MARKER.
export_markers_by_name = [list of string]

export_markers_by_name = model.MARKER_8,
model.MARKER_77
Causes to export rigid, flexible or ground MARKERS. An error is triggered if
the given name corresponds to a floating, curve or surface MARKER.

140 Adams Solver
C++ Commands
export_mode_shapes = [yes | no]

export_mode_shapes = yes
If this directive is set to yes, Adams Solver exports a punch file (*.pch) with
mode shape information of a subset of GRIDs and SPOINTs of the model.
Only GRIDs corresponding to the CM of parts and SPOINTs corresponding
to flexible bodies and differential states are exported.
Default is “no”
export_rbe_connectivity = [yes | no]

export_rbe_connectivity = yes
If this directive is set to yes, Adams Solver exports a file with RBE2 cards
restoring the connectivity lost when using the option file_name_style=C.
Default is "no"
LINEAR 141
C++ Commands
export_residuals= {yes | no }
export_residuals = yes
If this directive is set to yes, Adams Solver exports the residual DMIG cards
obtained by subtracting the stiffness matrix of a CBUSH from the exact
DMIG matrix corresponding to the exact linearization of a force.
For example, assume we have a VFORCE/567 with its corresponding exact

linearization given by matrix K1. Assume Adams Solver exports this force as a
CUBSH with a corresponding stiffness matrix K2. The residual is K1-K2.
Hence, if you use both, directive export_cbush = yes and directive
export_residual = yes, then the eigensolutions in both, Adams and Nastran will
match.
Notice the residuals are not always small due to an intrinsic limitation of linear
and non linear Finite Element codes performing a premature linearization for
eigenvalue computation.
Ignored if directive export_cbush is set to no.
Default is “yes”
export_spc_connectivity = {yes | no }
export_spc_connectivity = yes
If this directive is set to yes and the directive file_name_style = C is used,
Adams Solver exports breaks the topological connection created by RJOINTs
and CBUSH cards and exports a set of SPC cards to be used by external scripts
to restore the topological connections.
Ignored if directive file_name_style is not set to C.
Default is “no”.
142 Adams Solver
C++ Commands
export_spdp = {yes | no}

export_spdp = no
If this directive is set to yes, Adams Solver exports graphical SPDP objects
using CQUAD4, RBE2, RJOINT and GRID cards to represent spring
damper graphics.
SPDP objects are not exported if using directive file_name_style = C.
Default is "yes".
export_tic_cards = {yes | no}

export_tic_cards = yes
If this directive is set to yes, Adams Solver exports the cards corresponding to
transient initial conditions.
Default is "no".
file_include_extension= [string]
file_include_extension = .bdf2
When using the directive file_name_style = A, it specifies the extension of all
included files except the main file defining the model.

Ignored if directive file_name_style is different than A.
Default is “.bdf ”.
LINEAR 143
C++ Commands
file_name_style= {A | B | C }
file_name_style = C
If this directive is set to A and the export command option FILE is FILE =
path, the exported files are:
path.dat (main file)

path_MODEL.nas (model file, all parts, flexible bodies and joints)
path_DMIGNAMES.bdf (several files, one file per DMIG)
Notice the ".dat", ".nas" and ".bdf" extensions are appended to the given path.
You may change the extensions using directives main_file_include_extension,
model_include_extension, and file_include_extension.
If this directive is set to B and the export command option FILE is FILE =
path.ext, the exported files are:
path.ext
path_MODEL.ext
path_DMIGNAMES.ext
Notice that the extension is obtained from the LINEAR/EXPORT command.
The content of the exported files is identical to that of style A.
If this directive is set to C and the export command option FILE is FILE =
path, the exported files are:
path.dat
path_PROPERTY.nas
path_BODY.nas (several file, one per Adams PART)
path_CONNECTIVITY.nas
Notice the extension is appended to the given path.
Default is A.
144 Adams Solver
C++ Commands
flexbody_editable_by_id = [integer], [string]

flexbody_editable_by_id = 9900, FB9900
Causes to export a flexible body. The first argument corresponds to the ID of
the element. The second argument is a suffix used to create the DMIG cards.
flexbody_editable_by_name = [string], [string]

flexbody_editable_by_name = model.FLEX_BODY_9900,
FB9900
Causes to export a flexible body. The first argument corresponds to the name
of the element. The second argument is a suffix used to create the DMIG
cards.
force_card_number = [integer]
force_card_number = 558
Sets the number of the first FORCE or MOMENT card. See
force_card_number_increment.
Default is 300.
LINEAR 145
C++ Commands
force_card_number_increment = [integer]
force_card_number_increment = 2
Sets the increment when numbering FORCE and MOMENT cards.
Default is 1.
force_editable_by_id = [string], [integer], [string]

force_editable_by_id = beam, 979, B979
Causes to export an applied force. The first string argument determines the
type of applied force. The available types are: sforce, springdamper, bushing,
beam, field, vforce, vtorque, friction, or gforce. The second argument
corresponds to the ID of the element. The third argument is a suffix used to
create the DMIG cards.
force_editable_by_name = [string], [string], [string]

force_editable_by_name = beam, model.BEAM_979,
B979
Causes to export an applied force. The first string argument determines the
type of applied force. The available types are: sforce, springdamper, bushing,
beam, field, vforce, vtorque, friction, or gforce. The second argument
corresponds to the name of the element. The third argument is a suffix used
to create the DMIG cards.

146 Adams Solver
C++ Commands
force_input_channel {
name = [string]
marker_id = [integer]
marker_name = [string]
dof = { x | y | z | rx | ry | rz }
actuator_name = [string]
mode = { local | global }
}
name = ic_1
marker_by_name = model.MARKER_88
dof = rx
actuator_name = actuator_1
mode = local
}
Creates an input channel.
Field name is required; the given name is case sensitive.
Either marker_id or marker_name must be specified to define the location of

the input channel.
The dof field is optional and it specifies the coordinate where the input
channel is acting upon; default value is "x".
Field actuator_name is required and it must refer to a previously defined

actuator_swept_sine data.
Field mode is optional and it specifies whether the input force acts globally or
on the local coordinate system defined by the MARKER; the default value is
"local".

LINEAR 147
C++ Commands
forces_dmig_name = [string]
forces_dmig_name = FQ
If job is BLACKBOX, defines the name of the DMIG cards used to export the
stiffness matrix. If job is WHITEBOX, defines the name of the DMIG used
to export the stiffness contribution of all forces and flexible bodies which have
not been singled out by other directives. See for example
force_editable_by_name.
Default is VVV.
frequency_card_number = [integer]
frequency_card_number = 770
Sets the number of the FREQ1 or FREQ2 card to be exported.
Default is 600.
148 Adams Solver
C++ Commands
frequency_response_subcase {
number = [integer]
input_channel_names = [list of string]
output_channel_names = [list of string]
}
number = 107
input_channel_names = ic_1, ic_2, ic_3
output_channel_names = oc_7, oc_8
}
Creates a subcase for a frequency response analysis.
Field number is required; defines the number of the SUBACASE card.
Field input_channel_names is required and it is a list of input channels names

previously defined in the file. All names are case sensitive.
Field output_channel_names is required and it is a list of output channel

names previously defined in the file. All names are case sensitive.
graphics_grid_offset= [integer]
graphics_grid_offset = 5000
Specifies the grid point identification number of the first GRID card used to
export graphical information.
Default is 4000000.
LINEAR 149
C++ Commands
grid_offset = [integer]
grid_offset = 1000
Specifies the grid point or spoint identification number of the first GRID or
SPOINT card exported. All other GRID and SPOINT identifications will be
sequentially numbered. This option is ignored if the directive use_adams_ids
is set to true.
Default is 1.
150 Adams Solver
C++ Commands
ignore_errors = { yes | no }
ignore_errors = yes
Causes Adams Solver (C++) to ignore errors found processing the
configuration file. For example, if an export_marker_by_id directive specifies
a non existing MARKER, the directive will be ignored and the export job will
be performed.
Default is "no".
include_directory= [string]
include_directory = myinclude
Specifies the include directory to be used in all INCLUDE cards. Use a blank
string to override the default.
Default is the path of to the exported file used in the LINEAR/EXPORT

command.
initial_dmig_set = [integer]
initial_dmig_set = 50
Specifies the number of the first SET to create a list of DMIG names.
Default 1
load = [integer]
load = 4
Sets the number of LOAD card.
Default is 1.
LINEAR 151
C++ Commands
main_file_include_extension = [string]
main_file_include_extension=.data
When using the directive file_name_style = A, it specifies the extension of the
main exported file. This extension is appended to the name specified in the
LINEAR/EXPORT command.
Default is .dat
marker_offset = [integer]
marker_offset = 30000
If using the directive use_adams_ids = yes, this offset is used to generate the
GRID identification numbers using the Adams IDs.
Default is 1000000
material_card_number= [integer]
material_card_number = 500
Specifies the material identification number of the first MAT1 card used to
export graphical information.
Ignored if directive use_wireframe is set to true.
Default is 1000.
152 Adams Solver
C++ Commands
matrix_entry_zero_tolerance = [real]
matrix_entry_zero_tolerance = 1.e-06
Defines the tolerance Adams Solver (C++) uses to determine whether a matrix
entry is zero.
Default is 1.E-08.
model_include_extension = [string]
model_include_extension = .bdf
When using the directive file_name_style = A, it specifies the file extension of
the main included file defining the model.
When using the directive filename_style = C, it specifies the file extension of

all included files.
Caution: You should include a period when defining this extension.

Ignored if using directive file_name_style = B
Default is “.nas”
mpc_set = [integer]
mpc_set = 700
Defines the number of the MPC set.
Default is 1.
LINEAR 153
C++ Commands
number_of_eigenvalues = [integer]
number_of_eigenvalues = 40
Sets the number of eigenvalues specified in the EIGC card.
Default is the size of the state matrix [A].
param_post = [integer]
param_post = 1
Sets the value of the PARAM POST card.
Default is 0.
pbush_offset= [integer]
pbush_offset = 2000
Sets the initial id value of the PBUSH exported cards.
Default is 6000000.
154 Adams Solver
C++ Commands
pointmass_offset = [integer]
pointmass_offset = 30000
If using directive use_adams_ids = yes, this offset is used to generate the GRID
identification numbers using the Adams IDs of POINTMASS objects.
Default is 2000000
prod_offset= [integer]
prod_offset = 2000
Sets the initial id value of the PROD exported cards.
Default is 1.
pshell_offset= [integer]
pshell_offset = 2000
Sets the initial id value of the PSHELL exported cards.
Default is 1.
LINEAR 155
C++ Commands
rbe2_offset= [integer]
rbe2_offset = 2000
Sets the initial id value of the RBE2 exported cards.
Default is 1.
remove_unused_items=[string] [,string]
remove_unused_items = cbush, grid
Removes empty CBUSH cards and/or GRID cards not being used.
By default, no cards are removed.
rjoint_offset= [integer]
rjoint_offset = 2000
Sets the initial id value of the RJOINT exported cards.
Default is 1.
156 Adams Solver
C++ Commands
rload1_card_number = [integer]
rload1_card_number = 558
Sets the number of the first RLOAD1 card. See
rload1_card_number_increment.
Default is 200.
rload1_card_number_increment = [integer]
rload1_card_number_increment = 2
Sets the increment when numbering RLOAD1 cards.
Default is 1.
set_card_number = [integer]
set_card_number = 558
Sets the number of the first SET card. See set_card_number_increment.
Default is 900.
LINEAR 157
C++ Commands
set_card_number_increment = [integer]
set_card_number_increment = 2
Sets the increment when numbering SET cards.
Default is 1.
single_included_dmig = {yes | no}

single_included_dmig = yes
Sets the flag to either create a single included file or multiple included files. If
the option "yes" is used, all DMIG and graphical information is exported in a
single included file.
Default is "no".
small_mass= [real]
small_mass = 1
Specifies the value of the small mass to be set to zero-mass parts during the
export process. After the export process is finished, zero-mass parts are restored
to their original configuration.
If this value is zero, Adams Solver will use the smallest mass in the model
divided by 1.e+08.
Default is 0.
158 Adams Solver
C++ Commands
solution_number = [integer]
solution_number = 108
Specifies the solution number to be exported.
Only solution 107 and 108 are currently supported.
Default is 107.
spacing_frequency = { log | linear }

spacing_frequency = log
spacing_frequency = linear
Sets the type of frequency spacing, whether linear or logarithmic.
Default is "linear".
spc_set = [integer]
spc_set = 10
Specifies the set identification number of the SPC card.
Default is 1.
LINEAR 159
C++ Commands
spc_set_connectivity= [integer]
spc_set_connectivity = 1
Specifies the set identification number of the first SPC card used to export the
broken connectivity of the model when these two conditions met:
1. The directive export_spc_connectivity is set to true.

2. The directive file_name_style is set to C.
Default is 30000.
split_dmigs = [yes|no]
split_dmigs = no
Specifies whether DMIG matrices are split into a symmetric and an
antisymmetric matrices.
Optional if solution 108 is specified
Default is yes.
spoint_offset = [integer]
spoint_offset = 30000
If using directive use_adams_ids = yes, this offset is used to generate the
SPOINT identification numbers using the Adams IDs.
Default is 3000000
160 Adams Solver
C++ Commands
steps_frequency = [integer]
steps_frequency = 50
Sets the number of steps in which the frequency range is to be divided.
subtitle = [string]
subtitle = Ann Arbor run - J. P. & L. L.
Defines the SUBTITLE card.
Default is a string showing the current simulation time.
tabled1_card_number = [integer]
tabled1_card_number = 555
Sets the number of the first TABLED1 card. See
tabled1_card_number_increment.
Default is 500.
tabled1_card_number_increment = [integer]
tabled1_card_number_increment = 3
Sets the increment when numbering TABLED1 cards.
Default is 1.
LINEAR 161
C++ Commands
tic_set= [integer]
tic_set = 500
Specifies the set identification number of the TIC cards used to export the
current velocities of the model.
Caution: Adams Solver does not export the IC Case Control command.
Default is 2.
title = [string]
title = Export 1.2.22 - Type 722.7-b
Defines the TITLE card.
Default is "ADAMS2NASTRAN Export Utility".
use_adams_ids = [yes | no]

use_adams_ids = yes
If this directive is set to yes, Adams Solver exports identification numbers of
GRIDS, RJOINTS, RBE2, etc. using the Adams IDs and an offset.
For example. GRIDs corresponding to the CM of PART/77 and PART/199

would be exported as GRID 100077 and GRID100199 respectively
(assuming the offset is 100000).
162 Adams Solver
C++ Commands
use_damping = {yes | no }
use_damping = no
Specifies to use damping in the linearization analysis.
Default is "yes".
use_dmig_long_format = { yes | no }
use_dmig_long_format = no
If this directive is set to yes, Adams Solver will use Nastran's long format (16
characters wide) to export DMIG cards. Otherwise, short format (8 characters
wide) is used.
Default is "yes".
use_includes = { yes|no}
use_includes = no
By default, all DMIG and graphical information is exported using included files.
You may have the export process export either a set of multiple files or a single
file. This option can be used to export a file without using included files.
Default is "yes".
LINEAR 163
C++ Commands
use_long_format = { yes | no }
use_long_format = no
If this directive is set to yes, Adams Solver will use Nastrans's long format (16
characters wide) to export all cards except DMIG cards. Otherwise, short format
(8 characters wide) is used.
Default is "yes".
use_plotel = {yes | no }
use_plotel = yes
If this directive is set to yes, Adams Solver exports linear graphical objects using
PLOTEL cards.
Ignored if using directive use_wireframe = yes.
164 Adams Solver
C++ Commands
use_rjoints={yes|no}
use_rjoints = no
If this directive is set to yes, Adams Solver exports Adams joints using
RJOINT cards, if possible. Otherwise, the Adams joint is exported using
MPC cards.
use_short_part_file_names = [yes | no]

use_short_part_file_names = yes
Specifies using shorter file names for included files.
use_view_names = [yes | no]

use_view_names = no
Specifies using Adams View or Adams Car names. If this directive is set to
"no", the exported names are a combination of the object type and its Adams
ID.
Optional in all solution sequences.
Default is "yes".
LINEAR 165
C++ Commands
use_wireframe={yes | no }
use_wireframe = yes
If this directive is set to yes, Adams Solver exports all graphical information
using PLOTEL cards.
verbatim {
}
verbatim {
$ Added the following control cards
ECHO=BOTH
}
Adds a set of cards to the case control cards.
All lines between the curly brackets are printed to the exported file.
verbose_names=[ yes | no ]
verbose_names = no
If this directive is set to yes, Adams Solver exports names using a verbose
approach.
5.3.5 Configuration file examples

A typical configuration file using solution 107 is the following:
$ Configuration file prepared by J.Smith
166 Adams Solver
C++ Commands
$ Model 1.45-7-a_2.33.XPRWS/USA@@3410001109ABD-7a'StrA7'/88
$
use_damping = yes
grid_offset = 1000
$
$ All MARKERS in specified range
export_markers_by_id = 1-99
$
$ We need this MARKER located on ground
export_marker_by_name = model.PART_999.MARKER_919
$
$ Export SFORCE/7, to be replaced by custom force
force_editable_by_id = sforce, 7, SF7
$ End
A typical configuration file using solution 108 is the following:

$ Configuration file prepared by J.Smith Jr.
$ Model 1.45-7-a_2.33.XPRWS/USA@@3410001109ABD-7a'StrA7'/89
$
$ One actuator, two inputs, one output, two subcases
name = act1
magnitude = 2.2
phase_angle = 45D $ 45 degrees
}
name = inp1
marker_id = 88
dof = X
actuator_name = act1
}
name = inp2
marker_id = 88
dof = RZ
actuator_name = act1
}
name = out1
marker_id = 77
}
number = 100
input_channel_names = inp1, inp2
output_channel_names = out1
}
LINEAR 167
C++ Commands
number = 200
input_channel_names = inp1
output_channel_names = out1
}
begin_frequency = 1.0
end_frequency = 1000.0
steps_frequency = 20
spacing_frequency = log
use_damping = yes
grid_offset = 1000
$
$ End
5.3.6 Theoretical background

The BLACKBOX option exports the state space matrix representation of the Adams model following an exact
approach mentioned in section 1.0 above. The BLACKBOX export is straight forward to implement.
On the other hand, the WHITEBOX option poses a delicate problem. Next sections present the exact
linearization of the equations of motion, an approximate linearization method, and some issues related to
exporting the model to Nastran.
Exact linearization
Lagrange's equations of motion (as assembled by Adams Solver (C++)) have the following partitioned form:
Where the u's are the dependent coordinates and the v's are the independent coordinates. The independent
coordinates are not arbitrarily selected but chosen after performing a LU factorization of the constraint
equations using full pivoting. The LU factorization will select the best choice of coordinates for the
independent states.
The first step to exactly linearize the system is to define matrix P as:
Multiplying the top row of the equations of motion by P and summing it to the second one, the Lagrange
multipliers are eliminated:
··
( M + PM 1 ) u·· + ( M 4 + PM 2 )υ = f υ + Pf u (1)
3
168 Adams Solver
C++ Commands
Differentiating the constraint equations one time we obtain:

Φ q q· + Φ t = 0
A second differentiation returns:
Φ q q·· + ( Φ q q· ) q q· + 2Φ q q· + Φ = 0
t tt
Partitioning the first term of the last equation we get:
··
Φ u·· + Φ υ + ( Φ q q· ) q q· + 2Φ q q· + Φ = 0
u υ t tt
Rearranging this result we find:
Putting this result into Equation (1), the ODE (minimal representation) of the equations of motion is found
to be:
··
( M 3 P T + PM 1 P T + M 4 + PM 2 )υ + ( M 3 + P M 1 ) Ψ = f v + Pf u
Notice that this equation has a functional dependency on both u and its first derivatives. However, both
quantities can always be obtained from the constraint equations.
The final step is to perturb the ODE to obtain the linearized form:
··
δ { ( M 3 P T + PM 1 P T + M 4 + PM 2 )υ + ( M 3 + P M 1 ) Ψ } = δ ( f v + Pf u ) (2)
Adams Solver (C++) computes the equation above by using a different yet equivalent approach. Equation
above is important because it shows that the contribution of each element can be singled out and exported.
However, for the general dynamical case, the contribution of each element (inertial element, force or
constraint) is heavily distributed all over the state matrices making very difficult the replacement of say an
exported force by a new set of Nastran cards.
Approximate linearization
An approach followed by several computer codes consists of first linearizing the constraint equations, the
equations motion and then assembling the ODE. The linearized constraints are:
Φuδu + Φυδυ= 0 (3)
Redefining matrix P as
LINEAR 169
C++ Commands
we obtain that
δ u = P T δυ
Notice that in this case matrix P is numerically equal to matrix P defined in the previous section. However,
in this case matrix P is a constant; therefore taking two time derivatives of the last expression we arrive to:
··
δ u··= P T δυ (4)
The linearized equations of motion have this form:
(5)
Multiplying the first row by P and summing it to the second row we find:
··
( M + PM 1 )δ u·· + ( M 4 + PM 2 )δυ = δ f υ + P δ fu
3
Combining this result with Equation (4) we arrive to:
··
( M 3 P T + PM 1 P T + M 4 + PM 2 )δυ = δ f υ + P δ fu (6)
This is the set of assembled equations of motion obtained from the linearized constraint equations
(Equation (3)) and the linearized equations of motion (Equation (5)).
Feasibility of the export approach
Comparing Equation (6) and Equation (2) we notice that, in the general case, eigenvalues computed by those
two equations do not match. The complete variation of Equation (2) involves terms that are missing in Equation
(2). (Notice that matrix P in Equation (6) is a constant.)
However, both Equation (6) and Equation (2) will produce the same eigenvalues only for the static case. If both
velocities and accelerations are zero, several terms drop from Equation (2) and matching expressions are
obtained except for the right-hand side (applied forces). The variation of the right-hand side on Equation (2) is:
δ ( f v + Pf u ) = δ f v + P δ f u + δ Pf u
which compared with the right-hand side of Equation (6) shows that there is a missing term a linear code can
not compute. The solution is to export applied forces as DMIG cards.
Some of the issues addressed during the export job (WHITEBOX option) are the following:
170 Adams Solver
C++ Commands
1. The linearization is internally performed using the same coordinates Nastran uses to assemble the
equations of motion. This is accomplished by using Adams Solver (C++) capability to linearize the
system in terms of user-defined coordinates.
2. The linearized constraint equations (Equation (3)) are evaluated by a two-stages process and exported
a set of MPC cards.
3. The inertia elements (PARTS and POINT_MASS) are exported as CONM2 cards. This information
is taken directly from a mass matrix obtained by temporarily deactivating all constraints. The mass
matrices of flexible bodies are obtained in a similar way.
4. The stiffness and damping contribution of applied forces are computed and exported as DMIG cards.
By default all forces and flexible bodies contributions are dumped into the same set of DMIGs. The
configuration file can be used to single out the contribution of each applied force or flexible body,
however, each singled out element involves one extra linearization.
5. All differential states contributions to the equations of motion are dumped into a set of DMIGs and
SPOINT cards. Currently there are no tools to single out the contribution of differential states.
6. Examples
The command
LINEAR/EIGENSOL
computes an eigenanalysis for the Adams model. Adams Solver (C++) writes the eigenvalues and mode shapes
to the Results file where they can be read and displayed by a postprocessor such as Adams View.
The command
LINEAR/STATEMAT, PINPUT=10, POUTPUT=20
, FORMAT=MATRIXX FILE=STATES.MAT
computes state matrices for the Adams model, using PINPUT/10 as inputs and POUTPUT/20 as outputs.
The state matrices are written to file STATES.MAT in MATRIXX format.
7. Applications
There are several areas in which the LINEAR command is required. Some examples include:
1. Eigensolutions provide you with information that may be used in assessing stability of the Adams
model. If you import control systems descriptions or distributed elasticity data from external sources,
you can verify the stability of their Adams models.
2. Eigendata computed by Adams Solver (C++) can be used to validate Adams models against eigendata
from external sources.
3. State matrices descriptions can be used in designing control systems for Adams models. This
description is suitable for computing frequency response data in matrix manipulation software
packages (see the PINPUT, POUTPUT, and VARIABLE statements).
4. State matrices output by Adams Solver (C++) in the MATRIXX format are suitable for being read
into a second Adams model with a MATRIX statement. These matrices can form the definition of a
dynamical system defined by an LSE statement in the second Adams model.
LINEAR 171
C++ Commands
5. Exported linearized model as Nastran bulk data decks using the "whitebox" option can be used in
eigensolutions, frequency response analysis using Nastran. The exported model can be further edited
to perform other types of solution sequences in Nastran.
7.1 Eigen analysis application

Consider a model of an inverted pendulum on a sliding cart as shown in the figure shown next. The listing
of the Adams Solver (C++) dataset for this model is shown in Listing 1 (see Appendix).
Figure 10 Inverted Pendulum on Sliding Cart Model
The sliding cart in this model is represented by PART/1 and the inverted pendulum is represented by
PART/2. PART/1 slides along the global x axis in translational joint, JOINT/1, while PART/2 can rotate
about the axis of revolute joint, JOINT/2. PART/1 is connected to ground by a SPRINGDAMPER/1.
TFSISO/1 represents an actuator connected between PART/1 and PART/2. Force generated by this actuator
is applied on the two parts by SFORCE/1. No input is applied to the actuator for the present. To assess
stability of this model, execution of Adams Solver (C++) is initiated. Once Adams Solver (C++) verifies that
the model data is syntactically correct, issue the SIMULATE/STATIC command. On achieving static
equilibrium, issue the LINEAR/EIGEN command. Eigenvalues reported by Adams Solver (C++) are shown
in the table below.
Model Eigenvalues
EIGENVALUES
Number Real (cycles/unit time) Imag. (cycles/unit time)
1 5.00909210E-02 0.00000000E+00
2 -5.00924580E-02 0.00000000E+00
3 -3.18309800E+01 0.00000000E+00
4 -3.17994185E-01 +/- 6.36188992E-01
The table shows that the system has three stable and one unstable mode. To determine the cause of this
instability, use the data produced by Adams Solver (C++) (.res, .adm, and so on) in Adams to display the
deformed mode shapes of the model.
172 Adams Solver
C++ Commands
Figure 11 (a) and (b) show mode shapes for mode 1, which is unstable, and mode 4, which is stable.
Figure 11 Deformed Mode Shape 4(a) and Deformed Mode Shape 4 (b)
Figure 11 (a) shows that PART/1 is essentially stationary while PART/2 is moving. You can conclude that
PART/2 is the cause of the instability in this model. This is an expected result for this model, since the
inverted pendulum is at an unstable operating point. It is obvious that disturbing the pendulum will cause it
to swing about the revolute joint axis.
As illustrated by this example, viewing mode shapes in a graphical display can provide very significant insight
into the dynamic behavior of the model. In complicated Adams models, this insight is vital in understanding
the model dynamics. In Example 2: State Matrices Output below, based on the state matrices computed for
this model, a feedback control law will be designed to stabilize this model.
7.2 State matrices output

This section presents the design and implementation of a control system for the Adams model described in
Section 7.1. The purpose of the control design exercise is to design a feedback controller to attempt to
stabilize the inverted pendulum. For control design purposes, the state matrix representation of the Adams
model is required and is generated by the LINEAR/STATEMAT command.
Stabilization of this model requires that PART/2 maintain its inverted vertical position despite external
disturbances applied on it. External disturbances considered here are gravity acting vertically downwards and
an external force applied to the pendulum in the x-direction. On sensing a deviation of the pendulum from
the desired position, the control law determines an appropriate signal to apply to actuator TFSISO/1 to
restore PART/2 to its desired position. The control law operates on the basis of measuring output signals from
the plant and then computes a signal to apply to the actuator.
As shown in Figure 12 for the present model, 3 signals are output by the plant. VARIABLE/10 is a
measurement of the relative x displacement between PART/1 and PART/2. VARIABLE/20 is a measurement
LINEAR 173
C++ Commands
of the relative x velocities between the two parts. VARIABLE/30 is the integral of the relative x displacements
between the two parts. These 3 signals are designated as outputs from the plant by POUTPUT/1.
Input to the plant, that is, input signal to the actuator, is defined as VARIABLE/2. This is designated as input
to the plant by PINPUT/1. Adams Solver (C++) implementation of the input/output structure and the
external disturbances is shown in Listing 2: Plant Input/output Specification (see Appendix). This implementation,
when combined with the plant model as shown in dataset 1 in. This implementation, when combined with
the plant model as shown in dataset 1 in FILE=c results in the open-loop model. When the open-loop model
is complete, an Adams Solver (C++) execution session is initiated.
Figure 12 Open-Loop Model
The model is read into Adams Solver (C++). After Adams Solver (C++) verifies the model data syntax, issue
the SIMULATE/STATIC command to determine the equilibrium position. On achieving the equilibrium
position, issue the LINEAR/EIGEN, NOVECTOR command to verify the eigenvalues of the model. The
next table shows the eigenvalues for the open-loop model.
Open-Loop Eigenvalues
EIGENVALUES
1 -2.66440631E-17 0.00000000E+00
2 5.00909210E-02 0.00000000E+00
3 -5.00924580E-02 0.00000000E+00
4 -3.18309800E+01 0.00000000E+00
5 -3.17994185E-01 +/- 6.36188992E-01
The table shows that the open-loop model has one eigenvalue more than the model in Eigenanalysis Application.
This is due to the introduction of the relative displacement integrator TFSISO/2 in the open-loop model. To
linearize the model and compute the state matrices, issue the LINEAR/STATEMAT, PINPUT=1,
POUTPUT=1, file=adams.mat command. Adams Solver (C++) linearizes the model and writes the state
matrices in the default format to adams.mat file. Contents of the ADAMS.MAT file are in Listing 3: State
Matrices (FSAVE Format) for the Open-Loop Model (see Appendix). The Adams Solver (C++) session then terminates.
You may design a controller by reading the ADAMS.MAT file into the control design package exercising
various control design methodologies. The description of the control design step is beyond the scope of the
present document. A text on this subject or documentation for control design software packages should be
consulted for further details.
174 Adams Solver
C++ Commands
Now that the feedback control has been designed, it needs to be implemented in Adams Solver (C++) for a
closed-loop simulation (see Listing 4 in the Appendix). The controller designed for this example is a dynamic
compensator. As shown in Figure 13 below, this is implemented in Adams Solver (C++) as LSE/1. The A, B
and C matrices associated with this LSE are defined by MATRIX/100, 200, and 300, respectively. Adams
Solver (C++) reads the data for these matrices from a file named incomp.dat (see Listing 5 in the Appendix).
To connect this feedback compensator to the plant model, inputs to LSE/1, ARRAY/303 are connected to
outputs from the plant model. Also, ARRAY/1, which is input to the actuator, TFSISO/1, is now defined as
the output from the compensator, VARIABLE/2. This completes the closed-loop Adams model. The
complete Adams Solver (C++) dataset for this model Listing 4 (see Appendix).
Figure 13 Closed-Loop Model
To verify and simulate the closed-loop model, an Adams Solver (C++) simulation is initiated. The closed-loop
model is first equilibrated in its static position. The eigenvalues for this model are computed and represented
in Table 4 shown next.
Closed-Loop Eigenvalues
EIGENVALUES
1 -5.35233760E-01 0.00000000E+00
2 -3.18270747E+01 0.00000000E+00
3 -2.37397000E-01 +/- 7.54488218E-02
4 -7.37798519E-03 +/- 1.51611302E-01
LINEAR 175
C++ Commands
5 -5.47796070E-01 +/- 5.12745191E-01

6 -2.43466412E-01 +/- 5.71313964E-01
7 -2.46528313E+01 +/- 1.00614794E+01
Table 4 above shows that the closed-loop model is stable. The closed-loop model has more eigenvalues than
the open-loop model. This is due to the dynamical state variables introduced by LSE/1. Eigenvalues for the
closed-loop Adams model can be compared with the closed-loop eigenvalues computed in the control design
package. Now that the stability properties of the closed-loop Adams model have been verified, it can be
simulated to obtain its dynamic response. The time profile of the external disturbance is as shown in Figure 14.
The closed-loop model response to external disturbance is as shown in Figure 15. As illustrated in this figure,
the closed-loop model provides complete disturbance rejection for displacement of PART/2.
Figure 14 Time Profile of External Disturbance

176 Adams Solver
C++ Commands
Figure 15 Closed-Loop System Response
The input signal applied to the actuator and the force generated by the actuator are shown in Figure 16 and
Figure 17, respectively.
LINEAR 177
C++ Commands
Figure 16 Input Signal to Actuator
Figure 17 Force Generated by Actuator
The process of control design and simulation is an iterative one. If the closed-loop system does not perform
as expected, the control design specifications may have to be changed and a new controller designed to
achieve better performance.
178 Adams Solver
C++ Commands
8. Appendix
Listing 1: Inverted Pendulum Model
ADAMS Inverted pendulum model.
!
pa/99, ground
ma/99,qp=0,0,0, zp =1,0,0
!
! ===> Sliding cart <===
pa/1,ma=10,ip=10,10,10,cm=10
ma/10,qp=5,0,0 ! CM marker.
ma/11,qp=5,0,2, zp=5,1,2 ! revolute joint marker.
ma/12,qp=3,-2,-2 ! graphics marker.
ma/13,qp=5,0,0, zp=6,0,0 ! translational joint marker.
ma/14,qp=5,0,12
ma/15,qp=12,0,2 ! actutator attachment point
!
! ===> Inverted pendulum <===
pa/2,ma=1,cm=20, ip=1,1,1
ma/22,qp=5,0,12, zp=5,1,12 ! graphics marker.
!
joint/1,tran,i=13,j=99
joint/2,rev,i=11,j=21
!
! ===> Spring damper between cart and ground <===
springdamper/1,tran,i=99,j=13,k=200,c=40,l=5
!
gra/2, circle,cm=20, r=1.5,seg=20
gra/4, cylind,cm=24, l=8.5, r=0.25,seg=10,side=10
gra/5, box, corn=12, x=9, y=4, z=4
!
! ===> External disturbance <===
sforce/1001, i=20, j=99, action, tran,
,fun=step(time,0,0,.5,10)-step(time,1,0,1.5,10)
!
! ===>Actuator Dynamics<===
tfsiso/1,num=10, den=1,0.005
,u=1,x=2,y=3
array/1,u,var=2 ! input signal to actuator
array/2,x ! actuator state
array/3,y ! force generated by actuator.
!
! ===>Actuator force<===
sforce/1,i=15,j=23, trans,
,function=aryval(3,1)
!
! ===>Input to Actuator<===
vari/2,fun=0
!
LINEAR 179
C++ Commands
accgrav/kg=-1
result/format
!
end
Listing 2: Plant Input/output Specification

! ===> PLANT INPUT/OUTPUT definition <===
! -------------------
!
var/1,fun=dx(20,14)
Displacement integrator
tfsiso/2, num=1, den=0,1
,u=20,x=21,y=22
array/20, U, VAR=1
array/21, X
array/22, Y
!
! ===> Outputs <===
vari/10, function= varval(1) ! displacement
vari/20, function= vx(20,14) ! velocity
vari/30, function= aryval(22,1) ! displ. integrated
!
!
! ===> Plant input designation <===
pinput/1,var=2
!
! ===> Plant output designation <===
poutput/1,var=10,20,30
!
Listing 3:State Matrices (FSAVE Format) for the Open-Loop Model

MATRIXx VERSION 700 7 2005-04-21 19:31:36
A 6 6B 6 1C 3 6D 3 1
STATES 3 6PINPUT 2 1POUTPUT 4 1

A 6 6 0(3(1PE25.17))
-3.99604352126607365e+00 1.00000000000000000e+00 3.95647873392680538e-01
0.00000000000000000e+00 0.00000000000000000e+00 0.00000000000000000e+00
-1.99802176063303669e+01 0.00000000000000000e+00 1.97823936696340263e+00
0.00000000000000000e+00 0.00000000000000000e+00 0.00000000000000000e+00
0.00000000000000000e+00 0.00000000000000000e+00 0.00000000000000000e+00
1.00000000000000000e+00 0.00000000000000000e+00 0.00000000000000000e+00
-9.89119683481701345e-02 0.00000000000000000e+00 1.08803165182987160e-01
0.00000000000000000e+00 0.00000000000000000e+00 1.00000000000000000e+01
4.02439896739235914e-02 0.00000000000000000e+00 -4.42683886413159505e-02
0.00000000000000000e+00 -2.00000000000000000e+02 0.00000000000000000e+00
0.00000000000000000e+00 0.00000000000000000e+00 0.00000000000000000e+00
0.00000000000000000e+00 0.00000000000000000e+00 0.00000000000000000e+00
B 6 1 0(3(1PE25.17))
0.00000000000000000e+00 0.00000000000000000e+00 0.00000000000000000e+00
0.00000000000000000e+00 2.00000000000000000e+03 0.00000000000000000e+00
C 3 6 0(3(1PE25.17))
0.00000000000000000e+00 0.00000000000000000e+00 0.00000000000000000e+00
0.00000000000000000e+00 0.00000000000000000e+00 0.00000000000000000e+00
180 Adams Solver
C++ Commands
0.00000000000000000e+00 1.00000000000000000e+01 0.00000000000000000e+00

1.00000000000000000e+01 0.00000000000000000e+00 0.00000000000000000e+00
0.00000000000000000e+00 0.00000000000000000e+00 0.00000000000000000e+00
0.00000000000000000e+00 0.00000000000000000e+00 1.00000000000000000e+00
D 3 1 0(3(1PE25.17))
0.00000000000000000e+00 0.00000000000000000e+00 0.00000000000000000e+00
STATES 3 6 0(3(1PE25.17))
2.10000000000000000e+01 1.00000000000000000e+00 7.00000000000000000e+00
2.10000000000000000e+01 1.00000000000000000e+00 1.00000000000000000e+00
2.10000000000000000e+01 2.00000000000000000e+00 1.10000000000000000e+01
2.10000000000000000e+01 2.00000000000000000e+00 5.00000000000000000e+00
3.00000000000000000e+00 1.00000000000000000e+00 1.00000000000000000e+00
3.00000000000000000e+00 2.00000000000000000e+00 1.00000000000000000e+00
PINPUT 2 1 0(3(1PE25.17))
1.00000000000000000e+00 2.00000000000000000e+00
POUTPUT 4 1 0(3(1PE25.17))
1.00000000000000000e+00 1.00000000000000000e+01 2.00000000000000000e+01
3.00000000000000000e+01
Listing 4: Closed-Loop Model

ADAMS Inverted pendulum closed-loop model.
!
pa/99, ground
ma/99,qp=0,0,0, zp =1,0,0
!
pa/1,ma=10,ip=10,10,10,cm=10
ma/14,qp=5,0,12
!
pa/2,ma=1,cm=20, ip=1,1,1
!
!
!
gra/2, circle,cm=20, r=2,seg=10
gra/4, cylind,cm=24, l=8, r=0.5,seg=10,side=10
gra/5, box, corn=12, x=9, y=4, z=4
!
LINEAR 181
C++ Commands
!
,u=1,x=2,y=3
!
!
!
! ===> PLANT OUTPUT definition <===
! -------------------
!
var/1,fun=dx(20,14)
,u=20,x=21,y=22
array/20, u, var=1
array/21, x
array/22, y
!
! ===> Outputs <===
!
!
!
!
! ===>Feedback compensator<===
! --------------------
!
lse/1,a=100, b=200, c=300,
,x=101,y=202,u=303,ic=404
!
array/101, x ! compensator state
array/202, y ! compensator output
array/303, u, var= 10, 20, 30 ! compensator input
array/404, ic, num=0,0,0,0,0,0
!
matrix/100,
,file=incomp.mat, name=ac
matrix/200,
,file=incomp.mat, name=bc
matrix/300,
,file=incomp.mat, name=cc1
!
! ===> Feedback signal from compensator to actuator <===
182 Adams Solver
C++ Commands
variable/2, fun=-aryval(202,1)
!
accgrav/kg=-1
result/format
!
End
Listing 5: "incomp.mat" Input Data file
MATRIXx VERSION 700 3 04-OCT-91 15:27
AC 6 6BC 6 3CC1 1 6
AC 6 6 0(1P3E25.17)
-1.00799962154710574E+01 9.75162440467575053E-01 9.98460749273361898E+01
9.61406957584617916E-01 3.11437948419828955E-03 -1.78574044858736743E+04
-8.50683303123077716E-01 -4.98921809045884790E-01 1.01587769607181722E+00
1.14325442554075640E+00 -4.49484043101296749E-01 -1.69576019090885748E+04
9.98009512743940519E+00 2.48375595324249708E-02 -9.98470640470196713E+01
3.85930424153820839E-02 -3.11437948419828955E-03 1.79036593612407414E+04
-1.48327577193440696E-01 4.98921809045884790E-01 -1.02576889290663420E+00
-1.14325442554075640E+00 4.49484043101296749E-01 1.74318979368853470E+04
-1.20450308829068348E-01 7.73595535159733033E-02 -1.23564688768258060E-01
-4.73156382486152438E-01 -1.34087821455120393E+00 2.82840625758381648E+04
4.02439896739235914E-02 0.00000000000000000E+00 -4.02439896739235858E-01
0.00000000000000000E+00 0.00000000000000000E+00 -2.09248210623341492E+02
BC 6 3 0(1P3E25.17)
1.38436380363864547E-01 -4.98921809064772792E-01 1.12468086129738198E+00
1.14325442558403734E+00 5.50515956881686863E-01 -9.30005800767228163E-01
-9.98009512743940519E+00 -2.48375595324249708E-02 9.98470640470196713E+01
9.61406957584617916E-01 3.11437948419828955E-03 -1.36246052474731605E+04
1.20450308829068348E-01 -7.73595535159733033E-02 1.23564688768258060E-01
4.73156382486152438E-01 1.34087821455120393E+00 2.08671855656208993E-01
CC1 1 6 0(1P3E25.17)
2.11639961920025588E+00 8.47833595164392051E+00 -2.13952705688378986E+00
-8.71548396554230820E+00 -1.41421356238469098E+01 4.62410531167074812E-03
Listing 6: Input data file used in Section Differences in results compared with Adams Solver FORTRAN
Adams View model name: MODEL_1
!
UNITS/
, FORCE = NEWTON
, MASS = KILOGRAM
, LENGTH = MILLIMETER
, TIME = SECOND
!
PART/1
, GROUND
!
! adams_view_name='MARKER_4'
MARKER/4
, PART = 1
, QP = 0, 400, 0
!
MARKER/6
, PART = 1
, QP = 300, 350, 0
LINEAR 183
C++ Commands
!
MARKER/9
, PART = 1
, QP = 300, 400, 0
!
! adams_view_name='BOX_6'
GRAPHICS/6
, BOX
, CORNER = 9
, X = 150
, Y = -250
, Z = 300
!
! adams_view_name='PART_2'
PART/2
, MASS = 2.945180253
, CM = 7
, IP = 48894.82242, 48589.74352, 513.6958387
!
MARKER/1
, PART = 2
, QP = 0, 400, 0
, REULER = 284.0362435D, 0D, 0D
!
MARKER/3
, PART = 2
, QP = 0, 400, 0
!
MARKER/5
, PART = 2
, QP = 50, 200, 0
!
! adams_view_name='cm'
MARKER/7
, PART = 2
, QP = 50, 200, 0
, REULER = 194.0362435D, 90.00000002D, 90.00000017D
!
MARKER/10
, PART = 2
, QP = -50, 400, 0
!
! adams_view_name='BOX_7'
GRAPHICS/7
, BOX
, CORNER = 10
, X = 100
, Y = -350
, Z = 200
184 Adams Solver
C++ Commands
! adams_view_name='SPRING_1.I_graphic'
GRAPHICS/1
, FORCE
, ETYPE = SFORCE
, EID = 1
, EMARKER = 5
!
! adams_view_name='SPRING_1.J_graphic'
GRAPHICS/2
, FORCE
, ETYPE = SFORCE
, EID = 1
, EMARKER = 6
!
! adams_view_name='SPRING_1.spring_graphic'
GRAPHICS/3
, SPDP
, I = 5
, J = 6
, COILS = 10
, DA = 58.30951895
!
! adams_view_name='SPRING_1.damper_graphic'
GRAPHICS/4
, SPDP
, I = 5
, J = 6
, COILS = 0
, DB = 29.15475947
, DC = 23.32380758
, LC = 195.3368885
, LD = 195.3368885
!
! adams_view_name='JOINT_1'
JOINT/1
, REVOLUTE
, I = 3
, J = 4
!
! adams_view_name='SPRING_1.sforce'
SFORCE/1
, TRANSLATIONAL
, I = 5
, J = 6
, FUNCTION = - 1.2E-002*(DM(5,6)-291.5475947423)
, - 2.9E-003*VR(5,6)
, + 0.0
!
! adams_view_name='SPRING_1.deformation'
VARIABLE/1
, FUNCTION = DM(5,6) - 291.5475947423
!
! adams_view_name='SPRING_1.deformation_velocity'
VARIABLE/2
LINEAR 185
C++ Commands
, FUNCTION = VR(5,6)
!
! adams_view_name='SPRING_1.force'
VARIABLE/3
, FUNCTION = (DX(5,6)*FX(5,6) +
, DY(5,6)*FY(5,6) +
, DZ(5,6)*FZ(5,6))/
, DM(5,6)
!
! adams_view_name='VARIABLE_5'
VARIABLE/5
, FUNCTION = DX(7)
!
! adams_view_name='PSTATE_1'
PSTATE/1
, VARIABLES = 5
!
ACCGRAV/
, JGRAV = -9806.65
!
RESULTS/
, XRF
!
END
Listing 7: Adams Solver FORTRAN command file used in section Differences in results compared with Adams
Solver FORTRAN.
model_1
F77
preferences/solver=f77
SIMULATE/STATIC
LINEAR/EIGENSOL, ENERGY=1, DISSIPAT=1, KINETIC=1, STRAIN=1
Stop
Listing 8: Adams Solver C++ command file used in Section Differences in results compared with Adams Solver
FORTRAN.
model_1
CxxNoPstate
SIMULATE/STATIC
LINEAR/EIGENSOL, ENERGY=1, DISSIPAT=1, KINETIC=1, STRAIN=1
stop
Listing 9: Adams Solver C++ command file used in Section Differences in results compared with Adams Solver
FORTRAN using PSTATE.
model_1
CxxYesPstate
SIMULATE/STATIC
LINEAR/EIGENSOL, ENERGY=1, DISSIPAT=1, KINETIC=1, STRAIN=1, PSTATE=1
186 Adams Solver
C++ Commands
stop
9. Limitations
 Although Adams Solver C++ has a sound implementation of a linearization algorithm, it does have
limitations. One such limitation is related to very stiff systems. The process to assemble the
linearization matrix requires the solution of an enormous system of equations. If your system is too
stiff (large disproportion of stiffness elements), the solution process is affected and the quality of the
obtained matrix may be degraded.
 Another limitation is related to large models. Currently in standard hardware configurations
running Windows 7 with 8G RAM, the limit appears to be between 20,000 and 30,000 degrees-of-
freedom. Such large models can't be linearized due to memory addressing issues. This limitation will
be removed in future releases.
 Models with GCONs defining velocity constraints can't be linearized. This limitation will also be
removed in future releases.
 Notice that an implicit algebraic DIFF does not create a differential equation in the model, in fact
they are equivalent to a variable definition. For instance,
DIFF/4, IMPLICIT, FUNCTION=DIF(4)-TIME*DX(777)
is such a case because the above FUNCTION definition makes no use of the expression DIF1(4)
(the time derivative of the state), only DIF(4) is used (the plain value of the state). Implicit algebraic
DIFFs are usually defined with the purpose to obtain the time derivative of an expression. For
example, DIF1(4) will in fact return the time derivative of the expression TIME*DX(777) for the
above statement. However, the time derivative in this case is compute numerically as a byproduct of
the numerical integration. Hence, using the expression DIF1(4) in a force definition will produce
wrong linearization results because the partial derivatives of the time derivative DIF1(4) with respect
to the states of the system will return a zero value. Adams Solver C++ does not have an expression for
DIF1(4) that can be used to compute the required partial derivatives.
LSOLVER 187
C++ Commands
LSOLVER
The LSOLVER command allows the user to change the linear solver used by the Adams Solver (C++). The
linear solver is invoked multiple times throughout the simulation to compute corrections in the system state.
Format
Arguments
AUTO Specifies that Adams Solver (C++) is to automatically choose the most appropriate solver
based on the model being solved. This is the default setting.
CALAHAN Specifies that Adams Solver (C++) is to use the CALAHAN solver exclusively. The
Calahan solver is usually fastest for most models.
LIST Lists the current name of the selected solver and the value of the current stability.
STABILITY=r Specifies the factor used in the modified Markowitz criterion [1] during the pivot
selection of a LU matrix factorization. The value must be bigger than zero and smaller
than 1.0.
This setting only affects the Redundant Constraint Analysis, Initial Conditions
(displacements, velocities, accelerations) Analyses, and Dynamic Analysis. Static
Analysis, Quasi-static Analysis and Linearization are not affected by this option.
The default value of the STABILITY used for analyses that are affected by this option is
0.01. This values optimizes the fill-in of the linear algebra solution. However, for some
models the default value may results in slow convergence. Using a higher value may
improve the performance of the numerical algorithms.
UMF Specifies that the Adams Solver (C++) is to use the Unstructured Multi-Frontal sparse
matrix solver. This solver is faster for very large models.
Prior to Adams 2015, the Calahan solver was the default solver for all Adams models. This linear algebra
solver performs a symbolic factorization of the linear system and is consequently very fast and accurate for all
models except those that are very large.
188 Adams Solver
C++ Commands
The UMF solver (Unstructured Multi-Frontal) uses a very different solution technique than the Calahan
solver. The advantages of the UMF solver are 1) reduced memory use for large models, 2) better performance
for large models and 3) ability to use SMP parallelism for the linear system solution. The UMF solver begins
to show an advantage over the Calahan solver when the number of degrees of freedom is relatively large and/or
the structure of the matrix is dense. Note, however, that for some models, like simply-connected long chains,
the Calahan solver can be superior even when the number of degrees of freedom is much larger.
When the LSOLVER/ is set to AUTO (the default) the particular solver used depends only on the number
of equations in the system. The user can determine this transition with the environment variable
ADAMS_SPARSE_SOLVER_SWITCH_AT
For models with number of equations smaller than the ADAMS_SPARSE_SOLVER_SWITCH_AT, the Calahan
solver will be used. Models with more equations will use the UMF solver. If the environment variable is not
explicitly set it will default to 1 million.
Beginning in version 2017.2, a new parallel Calahan linear algebra code is the default linear algebra solver
used in Adams. A prototype of this parallel code was available in earlier releases by setting the environment
variable MSC_ADAMS_SOLVER_PARALLEL_CALAHAN. Given that a new version of that parallel code is now
the default, the said environment variable has been deprecated, instead, a new environment variable
MSC_ADMS_SOLVER_SERIAL_CALAHAN has been created for the rare case of needing to revert to the old
serial code.
The parallel Calahan algorithm uses a number of threads (POSIX API) set by the NTHREAD option in the
PREFERENCES statement. If NTHREDS is set to 1, the old serial code is executed. If NTHREADS is set
to a number higher than the number of CPU cores in the host machine, then the parallel code will use the
number of cores as the number of threads.
When using the STABILITY option, values higher than the default will increase computational time because
the fill-in is bigger. However, the absolute value of the selected pivots is higher resulting in faster convergence.
In cases of dealing with very stiff systems, a higher value is recommended.
LSOLVER 189
C++ Commands
Tip:  The CALAHAN and UMF solvers use different strategies for picking pivots during the
linear solution. One may work better on a particular model than the other and the
simulation results from the different solvers may have small differences.
 The UMF solver is built on the BLAS (Basic Linear Algebra Subprograms) library and
comes with a generic implementation of the BLAS library for all architectures. However,
using a BLAS library that is optimized for the specific architecture will usually result in a
substantial performance benefit. These optimized BLAS libraries are typically supplied by
the hardware vendor.
On Linux systems, the UMF solver will automatically search for the Intel MKL BLAS
libraries in locations defined by the LD_LIBRARY_PATH environment variable.
On Windows and other Linux systems, or if a non Intel MKL BLAS library is desired on
Linux, the environment variable BLASLIB should be defined giving the full path to the
desired library. If the BLAS implementation is dependent on multiple libraries, (as is the
case for MKL 10+) then BLASLIB should be defined as the paths to all of the necessary
libraries (using semicolon separators on Windows architectures and colon separators on all
other architectures).
A maximum of six libraries can be specified in the BLASLIB environment variable.
Caution: Note that the UMF solver does not support all of the capability that is supported by the
Calahan solver. In these cases, such as redundant constraint analysis, the appropriate solver
(Calahan) will automatically be used.
References
1. Markowitz, H.M., 1957, "The Elimination Form of the Inverse and Its Applications to Linear
Programming," Management Science, vol. 3, pp. 255-269.
See other available Analysis parameters.
190 Adams Solver
C++ Commands
MARKER
The MARKER command moves and/or reorients an existing fixed Adams Solver (C++) marker. (See the
MARKER statement for more information). You may also list information about the position of the marker.
Format
MARKER 191
C++ Commands
Arguments
LIST Lists the current values of the MARKER data. The data is with respect to the body
coordinate system (BCS) coordinates.
QP=x,y,z Redefines the the x-, y-, and z-coordinates of the origin of the MARKER with respect
to the PART on which it lies. The coordinates are specified in the body coordinate
system (BCS) of the PART to which it belongs. For markers associated with CURVES
and SURFACES, the coordinates are specified in the RM coordinate system and are
susceptible to change as Adams Solver (C++) iteratively solves for initial conditions that
satisfy all constraints while maintaining the marker on the curve.
REULER=a,b,c Redefines the three-dimensional spatial orientation of the marker axes relative to the
axes of the BCS. For markers associated with CURVES and SURFACES, the
orientation is relative to the natural coordinate system of the CURVE or SURFACE.
The a, b, and c values represent a set of body-fixed 3-1-3 Euler angles expressed in
radians. These angles can be interpreted as follows:
 To orient a marker, first align the marker axes identically to the BCS axes.
 Perform a right-handed rotation of the marker x- and y-axes by a radians about the
positive z-axis of the marker.
 Rotate the marker y- and z-axes by b radians about the current marker positive x-
axis.
 Perform a right-handed rotation of the x- and y-axes of the marker by c radians
about the current z-axis of the marker.
This technique can be used to define any arbitrary orientation of the marker relative to
the part BCS. To enter the Euler angles in degrees instead of radians, add a D after each
value.
RM Redefines a reference marker with respect to which Adams Solver (C++) interprets QP,
XP, ZP, and REULER.
192 Adams Solver
C++ Commands
USEXP When using the x-point-z-point method of orientation, USEXP causes the marker to
be oriented with the x-axis lying on XP and ZP lying in the positive x-z plane. This is
useful to orient markers for use in BEAM statements.Examples of using the ZP, XP and
USEXP.
XP=x,y,z By default, redefines the BCS coordinates of any point in the positive x-z plane of the
marker, but not on the z-axis of the marker. A point on the positive x-axis may be the
most convenient. When used with USEXP, XP defines the BCS coordinates of any
point on the positive x-axis of the marker.
If the marker is associated with a FLEX_BODY or PART, the x-, y-, and z-coordinates
are specified in the BCS. For markers associated with CURVES and SURFACES, the
x-, y-, and z-coordinates are specified in the natural coordinate system of the CURVE
or SURFACE.
For every point on a CURVE or SURFACE, Adams Solver (C++) computes a natural
coordinate system defined by tangent, normal, and binormal orthonormal vectors. In
general, as the solution progresses and the marker moves along the CURVE or
SURFACE, the orientation of the natural coordinate system changes, but the
orientation of the marker relative to the natural coordinate system remains fixed. The
fixed orientation of the marker relative to the natural coordinate system is specified with
XP and ZP arguments. Examples of using the ZP, XP and USEXP.
ZP=x,y,z By default, redefines the BCS coordinates of any point in the positive z-axis of the
marker. When used with USEXP, ZP defines the BCS coordinates of any point in the
positive x-z plane of the marker, but not on the x-axis of the marker.
If the marker is associated with a FLEX_BODY or PART, the x-, y-, and z-coordinates
are specified in the BCS. For markers associated with CURVES and SURFACES, the
x-,y- and z-coordinates are specified in the natural coordinate system of the CURVE or
SURFACE.
For every point on a CURVE or SURFACE, Adams Solver (C++) computes a natural
coordinate system defined by tangent, normal, and binormal orthonormal vectors. In
general, as the solution progresses and the marker moves along the CURVE or
SURFACE, the orientation of the natural coordinate system changes, but the
orientation of the marker relative to the natural coordinate system remains fixed. The
fixed orientation of the marker relative to the natural coordinate system is specified with
XP and ZP arguments. Examples of using the ZP, XP and USEXP.
Extended Definition
The MARKER command allows you to reposition and/or reorient a fixed marker with respect to the body
coordinate system (BCS) of the element to which the marker is attached, or to another nonfloating marker
on the same element. You may use any of the standard Adams Solver (C++) methods to specify the location
and orientation of the marker. Floating markers may not be moved, but their current information may be
listed. For more information on BCS, see Coordinate Systems and Local Versus Global Geometric Data.
MARKER 193
C++ Commands
After a change to a MARKER, Adams Solver (C++) reprocesses the model at the next SIMULATE command,
While checking, Adams Solver (C++) verifies that the model is still valid with the new MARKER positions.
If a JOINT is now misaligned, for instance, Adams Solver (C++) issues a warning or error.
Adams Solver (C++) also reinitializes user subroutines to re-establish functional dependencies. For each
IFLAG set to true.
have run a previous simulation, Adams Solver (C++) begins with the final displacements and velocities.
Adams Solver (C++) then adjusts the initial conditions to ensure that they are consistent with the model
constraints. If this is the first simulation, Adams Solver (C++) also maintains any user supplied joint initial-
conditions and positions specified as EXACT.
If you change a MARKER in the middle of a simulation, by default Adams Solver (C++) splits the tabular,
request, graphics, and results output into two separate sets of output concatenated together. This ensures that
the output correctly reflects the new system geometry.
The OUTPUT/NOSEPARATOR argument prevents Adams Solver (C++) from splitting the file. This allows
you to plot or animate the output continuously from beginning to end, but may result in misleading graphics
during postprocessing. See the OUTPUT statement for more information on the NOSEPARATOR argument.
Tip: You can use the QP argument to translate the marker while maintaining the existing
orientation. If you use only the REULER argument, Adams Solver (C++) reorients the
marker while maintaining the existing position.
Caution:  When reorienting a marker, you should completely specify the necessary information for
the selected orientation method. Adams Solver (C++) uses the new orientation
information; it does not try to combine it with old information from the dataset statement
or a previous command. For example, if you supply ZP but not XP, Adams Solver (C++)
uses a default position for the x-axis. Adams Solver (C++) does not use a value of XP from
the statement or an earlier command.
 When you change a marker, Adams Solver (C++) updates all elements that depend on that
marker. Moving a marker may have subtle effects since many Adams Solver (C++)
elements rely on them. Be careful when moving markers as unintended side effects (for
example, moving both a joint and force that share a common marker) may occur.
Examples
MARKER/10,REULER=15D,0,0
This MARKER command reorients marker 10.
194 Adams Solver
C++ Commands
MARKER/10,QP=2,15,0
This MARKER command relocates marker 10.
MARKER/10,QP=2,15,0,ZP=3,15,0
This MARKER command relocates and reorients marker 10.
MARKER/18, QP=0,0,0, REULER=0d,0d,0d, RM=8
This MARKER command repositions/reorients Marker 18 so that it has the same location and orientation
as Marker 8.
See other bordered commands available.
MENU 195
C++ Commands
MENU
The MENU command lists all of the Adams Solver (C++) interactive commands.
Format
MENU
196 Adams Solver
C++ Commands
MOTION
The MOTION command redefines and/or lists the characteristics of a MOTION statement which specifies
a system degree of freedom as an explicitly function of time. For more information, see the MOTION statement.
Format
Arguments
ACCELERATION Respecifies that the FUNCTION argument defines the motion

acceleration as a function of time.
B1 Respecifies the first angle of the Body 1-2-3 Euler angle sequence
as a function of time.
Range: None
B2 Respecifies the second angle of the Body 1-2-3 Euler angle
sequence as a function of time.
Range: None
MOTION 197
C++ Commands
B3 Respecifies the third angle of the Body 1-2-3 Euler angle

sequence as a function of time.
Range: None
DISPLACEMENT Respecifies that the FUNCTION argument defines the motion
Respecifies an expression or redefines and passes constants to a
user-written subroutine to determine the motion. The motion
must be a function of time only and not a function of the state
variables.
ICDISP Respecifies the initial displacement of the motion, when the
motion is defined in terms of velocity or acceleration.
ICVEL Respecifies the initial velocity of the motion, when the motion is
I=id, J=id Respecifies the identifiers of the two markers whose displacement
is being controlled.

body
JOINT Respecifies the identifier of the joint to which the motion is
assigned. The joint must be translational, revolute, or cylindrical.
LIST Lists the current values of the data in the MOTION statement.
ROTATION Respecifies that Adams Solver (C++) is to apply a rotational
motion. The type of motion is ambiguous for cylindrical joints
only.
MOTSUB.

TRANSLATION Respecifies that Adams Solver (C++) is to apply a translational
motion. The type of motion is ambiguous for cylindrical joints
only.
VELOCITY Respecifies that the FUNCTION argument defines the motion
velocity.
X Respecifies DX(I,J,J) as a function of time. Range: None
Y Respecifies DY(I,J,J) as a function of time. Range: None
Z Respecifies DZ(I,J,J) as a function of time. Range: None
198 Adams Solver
C++ Commands
Extended Definition
The MOTION command allows you to list or modify the characteristics of an existing MOTION statement.
You can change the motion definition, change the joint to which the motion is being applied, and/or change
the type of motion on a cylindrical joint.
After a change to a MOTION, Adams Solver (C++) reprocesses the model at the next SIMULATE
While checking, Adams Solver (C++) verifies that the model is still valid with the new MOTION. If, for
example, the new MOTION conflicts with another MOTION at the same joint, Adams Solver (C++) issues
an error.
IFLAG set to true.
If this is the first simulation, Adams Solver (C++) also maintains any user-supplied joint initial-conditions
and part positions specified as EXACT.
Examples
MOTION/3,JOINT=21
This MOTION command applies Motion 3 to Joint 21.
MOTION/11, FUNCTION=5+2*TIME
This MOTION command specifies, as a function of time, the translation or rotation for Motion 11.
OUTPUT 199
C++ Commands
OUTPUT
The OUTPUT command redefines and/or lists the data for an OUTPUT statement.
Format
Arguments
GRSAVE Resaves graphics output in the Graphics file so that you can use a postprocessor to
display graphics.
LIST Lists the current values of the data in the OUTPUT statement.
NOGRSAVE Stops saving graphics output in the Graphics file.
NOREQSAVE Stops saving request output in the Request file.
REQSAVE Resaves the request output in the Request file so you can use a postprocessor to display
x-y plots.
Extended Definition
Like the OUTPUT statement, the OUTPUT command controls the generation of the request file and
graphics file.
200 Adams Solver
C++ Commands
PART
The PART command redefines and/or lists the data for a PART statement. Although you cannot redefine the
center-of-mass markers, the inertia markers, you are free to move and reorient those markers using the MARKER
command. You can also redefine the mass of the part and the 6 values of the inertia tensor.
Format
PART/id [,MASS=r] [,IP=xx,yy,zz [, xy,xz, yz] [,LIST]

PART 201
C++ Commands
Arguments
IP=xx,yy,zz Specifies the mass-inertia tensor as computed about the origin of the IM marker, expressed
in the coordinate system of the IM marker.
Ixx =  ( y 2 + z 2 ) dm
Iyy =  ( x 2 + z 2 ) dm
Izz =  ( x 2 + y 2 ) dm
Ixy =  xy dm
Ixz =  xz dm
Iyz =  yz dm
In the above formulae, x, y, and z are the components of the displacement of the center of
an infinitesimal volume of mass dm, measured from the origin of the inertia marker in the
coordinate system of the inertia marker. The integral is performed over the entire volume of
the body. If the inertia marker was not specified by the PART statment for the part, the IM
marker defaults to the CM marker. In that case, these quantities are computed about the
origin of the CM marker in the coordinate system of the CM marker.
Note: Adams Solver (C++) defines Ixy, Ixz, and Iyz as positive integrals, as shown. Some
references define these terms as the negative of these integrals. Be sure to compute
these values as shown above.
LIST Lists the current values of the data in the PART statement.
MASS=r Respecifies the part mass.
Caution: Unlike Adams Solver (FORTRAN) the PART command in Adams Solver (C++) is followed
by an initial condition analysis and an integrator restart, if applicable. This is a consequence
of the added freedom in respecifying inertia properties and the location and orientation of
inertia markers.
Examples
PART/2, MASS=10
This PART command respecifies the mass of Part 2.
202 Adams Solver
C++ Commands
PART/5, IP=0,3,6, LIST

This PART command respecifies the moments of inertia of Part 5 as principal moments of inertia and lists
all the data for the Part. If the original definition of Part 5 included an IM marker the moments of inertia are
w.r.t. this marker, otherwise the CM marker. If the original definition of Part 5 specified all 6 inertia tensor
values, the off-diagonal values are set to zero as a consequence of not being respecified.
PREFERENCES 203
C++ Commands
PREFERENCES
The PREFERENCES command controls general options that apply to the model defined in the Adams
Solver (C++) dataset or the commands defined in the Adams Solver (C++) command file.
Format
Note: SOLVERBIAS is an argument for the PREFERENCES C++ command and hence it would
go in the ACF file.
204 Adams Solver
C++ Commands
Arguments
PREFERENCES 205
C++ Commands
Specifies the geometry library to be used to 3D

contact determination:
 Parasolid - Specifies the Parasolid geometry

library to be used for 3D contact
determination.
 Default_library - Specifies that the default
geometry library to be used for 3D contact
determination.
For more on the different libraries, see the
PREFERENCES statement.
CONTACT_FACETING_TOLERANCE=value Specifies the resolution of the mesh that is to be
created from the solid geometries in the model.
Contact kinematics are calculated by intersecting the
meshes corresponding to two solid geometries. A
finer mesh will result in more accurate contact
calculations. However, calculations may be slower,
and computer memory requirements will increase as
the mesh resolution increases.
The faceting tolerance is defined as the maximum

error between the true surface and the surface of the
faceted representation of the geometry. The
maximum error is guaranteed not to exceed (1/value)
* the minimum dimension of each geometry's
bounding box.
The value specified for the faceting tolerance only

applies to geometry read from a Parasolid file. All
native geometry (ellipsoid, cylinder, box, frustum,
torus, surface of revolution, and extrusion) is
tessellated with a fixed tolerance when a faceting
tolerance is specified. Stl and shl files have fixed
faceting that cannot be changed.
206 Adams Solver
C++ Commands
Specifies whether or not to stop command-file

execution when a simulation fails.
A value of STOPCF indicates that Adams Solver

(C++) should stop if a static, quasi-static, kinematic,
or dynamic analysis fails to find a solution or reach
the specified end time. Adams Solver (C++) finishes
writing output and exit, just as if a STOP command
were the next command in the command file.
A value of NOSTOPCF indicates that Adams Solver

(C++) should continue to process commands from a
command file even after a simulation fails.
PREFERENCES 207
C++ Commands
When you run Adams Solver, this specifies which

version of Adams Solver to run: C++ (Cxx),
FORTRAN (F77), or none. Adams Solver only runs
the version if it supports your model. For example,
the Adams Solver (FORTRAN) supports some
statements that are not supported in Adams Solver
(C++). If "none" is selected, Adams Solver uses the
default solver.
If the simulation is being run with an command file

(.acf ) and the .acf file has a
Preferences/SolverBias={Cxx,F77,none} command
in it, Adams Solver runs with the specified solver. If
more than one Preferences/SolverBias commands is
present, it uses the first command it finds. Issuing
this command during a simulation has no effect.
This argument is only useful when executing Adams
Solver from a command file.
When you are running Adams Solver (FORTRAN),

and issue Preferences/SolverBias=Cxx, Adams Solver
returns the following warning:
---- WARNING ----

Once the Solver session is executing it is not possible
to change to the Cxx Solver. Solverbias=cxx is being
ignored, and the simulation is proceeding with the
F77
Solver.
If you are running Adams Solver C++, and issue

Preferences/SolverBias=F77, Adams Solver ignores
the command.
LIST Lists the current values of the PREFERENCES
statement.
208 Adams Solver
C++ Commands
STATUS_MESSAGE Controls the presence of two status messages in the

.msg file produced by Adams Solver (C++). These
status messages mimic status messages produced by
Adams Solver (FORTRAN). This preference has no
effect on Adams Solver (FORTRAN).
Default: OFF
The first status message is sent after every simulation

and has the form “Simulate status =i”.
The second message is sent when Adams Solver

(C++) terminates and has the form “Termination
status = i”.
In both cases “i” is an integer number reporting the

status. The values of "i" are the Error Codes.
Examples
Using the Parasolid geometry library provided by MSC:
Caution: CONTACT_GEOMETRY_LIBRARY and CONTACT_FACETING_TOLERANCE

parameters are accepted only at the start of the simulation. Once the simulation starts
changing these parameters will not affect the simulation.

RELOAD 209
C++ Commands
RELOAD
The RELOAD command restarts a simulation from a previously saved model or simulation state.
Format
RELOAD/{ STATES, BUFFER=c }
{ SYSTEM, FILE=c, [OUTPUT_PREFIX=c] [TITLE=c] }
Arguments
BUFFER Specifies the internal memory buffer for state values you created with the SAVE
command. The buffer memory is allocated dynamically. The buffer exists only
during the current Solver session and cannot be saved to disk.
Range: All printable characters except "!", ";", "," and "&"
FILE=c Specifies the complete name of a file you created with the SAVE command. The
file name may include the directory on operating systems that support path
names, such as Linux. There is no default extension for this file. Because the FILE
argument and value can be at most eighty characters long, the file name and path
name are limited from seventy-five characters (if you do not abbreviate FILE=) to
seventy-six characters (if you abbreviate FILE= to FIL=).
OUTPUT_PREFIX=c Optionally specifies a new base (root) name for output files (.req, .res, .gra, and so
on) from simulations which follow this RELOAD command. If you do not
specify the OUTPUT_PREFIX argument, Adams Solver (C++) appends the
output to the currently-open output files after writing a special delimiter line into
the file. Because the OUTPUT_PREFIX argument and value can be at most
eighty characters long, the basename and path are limited from sixty-six characters
(if you do not abbreviate OUTPUT_PREFIX) to seventy-six characters (if you
abbreviate OUTPUT_PREFIX to OUT=).
210 Adams Solver
C++ Commands
STATES Specifies Adams Solver (C++) reloads just the saved simulation time and state
values (displacements, velocities, force values, user-defined variable values, and so
on), while maintaining the existing model definition.
SYSTEM Specifies that Adams Solver (C++) reloads the entire saved system, including the
model definition (parts, markers, joints, and so on), simulation time and state
on), and solver data (integrator parameters, state derivatives, and so on). This
completely replaces the existing model and simulation conditions with the saved
model and simulation conditions.
TITLE=c Optionally specifies a new title for the model in output from simulations which
follow this RELOAD command. The title string may not contain any special
Adams Solver (C++) characters and must fit on a single line (no continuations). If
not the last argument, the title is terminated by the last non-blank prior to the
following comma. Because the TITLE argument and value can be at most eighty
characters long, the file name and path name are limited from seventy-four
characters (if you do not abbreviate TITLE=) to seventy-six characters (if you
abbreviate TITLE= to TIT=).
Extended Definition
Using the RELOAD command with the STATES argument allows you to reload the saved simulation time
and state values, including displacements, velocities, force values, and user-defined variable values. Adams
Solver (C++) resets the simulation time to the saved values, and uses the saved states as initial conditions for
the next simulation.
Using the RELOAD command with the SYSTEM argument allows you to reload the entire saved system,
including the model definition (parts, markers, joints, and so on), simulation time and state values
(displacements, velocities, force values, user-defined variable values, and so on), and solver data (integrator
parameters, state derivatives, and so on). Adams Solver (C++) completely resets all model, simulation, and
solver data to that stored in the file. Except for interactive plotting, Adams Solver (C++) responds to
subsequent commands just as it would have at the time the file was saved. (Because past simulation results
are not stored in the Save file, they cannot be plotted when the file is restored.)
Tip: Except for the leading delimiter line, the appended sections of the output files are complete
(that is, they may be extracted with any editor, renamed, and handled like any other Adams
Solver (C++) output).
RELOAD 211
C++ Commands
Caution:  Files are saved in a machine- and code-dependent binary format. They are not portable
across platforms or between versions of Adams Solver (C++).
 Save files generated by Adams Solver (FORTRAN) cannot be reloaded by Adams Solver
(C++). Similarly, save files generated by Adams Solver (C++) cannot be reloaded by Adams
Solver (FORTRAN).
 Save files generated by a specific version of Adams Solver (C++) (for example, 2005r2)
cannot be reloaded by any other version of Adams Solver (C++) such as 2005 r1. This also
applies to any service packs that may be applied to Adams Solver (C++).
 RELOAD/STATES cannot be used with FILE and RELOAD/SYSTEM cannot be used
with BUFFER.
 Models containing nonlinear flexible bodies are not supported by the [SAVE/RELOAD]
command.
Examples
RELOAD/SYSTEM,FILE=TCT1.SAV,TITLE=TEST#2
This RELOAD command reloads the model and simulation states saved in file TCT1.SAV. Adams Solver
(C++) appends subsequent output to the currently open output files with the new title TEST#2.
The SAVE and RELOAD commands can help simulate several versions of the same model when used with
other interactive Adams Solver (C++) commands. SAVE/SYSTEM creates a baseline configuration that you
can then reload and simulate repeatedly without leaving Adams Solver (C++). After each
RELOAD/SYSTEM, you may modify the model, and use the ACTIVATE and DEACTIVATE commands
to switch sets of loads on and off, for example.
The following command file uses the SAVE/SYSTEM and RELOAD/SYSTEM commands to run three
simulations from the same input file, creating three sets of output files: case1, case2, and case3. The command
file loads example.adm, the original model, that contains three sets of forces. After deactivating all the forces
and performing a static solution, the SAVE command saves the whole system. ACTIVATE commands then
turn on one set of forces at a time.
Between simulations, the RELOAD command restores the saved version of the model. Reloading the save
file returns the model to the conditions at the time of the save. In this case, the saved version of the model is
at static equilibrium with all the forces inactive.
example
case1
dea/sfo,id=101,102,201,202,301,302 !Deactivate all forces
sim/static !Find static equilbrium
save/system, file=ex.sav ! Save system at static, no forces
act/sfo, id=101,102 ! Activate first set of forces
sim/dyn, end=.25, steps=100 !Simulate
rel/system, file=ex.sav, out=case2 ! Reload(now back at static,no forces)
212 Adams Solver
C++ Commands
act/sfo, id=201,202 ! Activate second set of forces

sim/dyn, end=.05, steps=20 ! Simulate
act/sfo, id=301,302 ! Activate third set of forces
stop
The following command file demonstrates using SAVE/STATES and RELOAD/ STATES.
deactivate/contact,id=1 ! Deactivate contact

sim/dyn, end=1.3, dtout=0.004 ! Simulate
save/states, buffer=1 ! Save states to buffer
activate/contact,id=1 ! Activate contact
reload/states, buffer=1 ! Reload states from buffer

REQUEST 213
C++ Commands
REQUEST
The REQUEST command redefines and/or lists the data for a REQUEST statement, and/or redefines the
function expressions for a REQUEST statement.
Format
Arguments
F2=e Redefines a component of the request that is being specified. If the

F2 argument is used, it must either be the last argument in the
REQUEST statement or be followed by a backslash (\) (not a
comma).
comma).
comma).
comma).
214 Adams Solver
C++ Commands

comma).
comma).
FUNCTION=USER(r1[,...,r30])[/] Redefines and passes constants (r1[,...,r30]) to the user-written
subroutine REQSUB to define the request (see REQSUB Using Adams
Solver Subroutines). If the FUNCTION argument is used, it must
either be the last argument in the REQUEST statement or be
followed by a backslash (\). Because of compatibility requirements,
REQSUB can define 8 columns of data, but only columns 2, 3, and
4 and columns 6, 7, and 8 are written in the request file.
LIST Lists the current values of the data in the REQUEST statement.
REQSUB.
Examples
REQUEST/21, F4=DX(2110, 409)/F8=DX(2115, 409)
This REQUEST command changes the channels F4 and F8 expressions for REQUEST/21. The other
function expressions remain as they were.
SAVE 215
C++ Commands
SAVE
The SAVE command stores the current Adams Solver (C++) model and simulation conditions or only the
current simulation states. This allows you to return to the model or states at a later time using the RELOAD
command.
Format
SAVE/ { STATES, BUFFER = c }
{ SYSTEM, FILE = c }
Arguments
BUFFER Specifies the internal memory buffer for state values. The buffer memory is allocated
dynamically. The buffer exists only during the current Solver session and cannot be saved
to disk.
Range: All printable characters except "!", ";", "," and "&"
FILE=C Specifies the complete file name where Adams Solver (C++) writes the SAVE command
information. The file name may include the directory on operating systems that support
such path names, such as Linux. There is no default extension for this file.
STATES Specifies Adams Solver (C++) to save just the current simulation time and state values
(displacements, velocities, force values, user-defined variable values and so on). The
RELOAD/STATES command can later reload these states to restart the simulation from
this point.
SYSTEM Specifies that Adams Solver (C++) saves the entire current system, including the model
definition (parts, markers, joints, and so on), simulation time and state values
(displacements, velocities, force values, user-defined variable values, and so on), and solver
data (integrator parameters, state derivatives, and so on). SYSTEM creates a complete
record of the current model and simulation conditions. The RELOAD/SYSTEM
command can later reload this record to return to these model and simulation conditions.
Extended Definition
You can use the SAVE command with the STATES argument to save the current simulation time and state
values, including displacements, velocities, force values, and user-defined variable values. You can later restart
a simulation from this point by reloading the states with the RELOAD/STATES command. When you reload
this buffer, Adams Solver (C++) resets the simulation time to the saved value and uses the saved states as initial
conditions for the next simulation.
You can use the SAVE command with the SYSTEM argument to save the entire current system, including
the model definition (parts, markers, joints, and so on), simulation time, state values (displacements,
velocities, force values, user-defined variable values, and so on), and solver data (integrator parameters, state
216 Adams Solver
C++ Commands
derivatives, and so on). SAVE/SYSTEM creates a complete record of the current model and simulation
conditions. You can later return to this point by reloading the conditions using the RELOAD/SYSTEM
command.
When you reload a system file, Adams Solver (C++) completely resets all model, simulation, and solver data
to that stored in the file. Except for interactive plotting, Adams Solver (C++) responds to subsequent
commands just as it would have at the time the file was saved. (Because past simulation results are not stored
in the save file, they cannot be plotted when the file is restored.)
across platforms or between versions of Adams Solver (C++).
 Save files generated by Adams Solver (FORTRAN) cannot be reloaded by Adams Solver
(C++). Similarly, save files generated by Adams Solver (C++) cannot be reloaded by Adams
Solver (FORTRAN).
 SAVE/STATES cannot be used with FILE and SAVE/SYSTEM cannot be used with
BUFFER.
command.
Examples
SAVE/SYSTEM,FILE=BASE1.SAV
This SAVE command saves the current model and simulation information in file BASE1SAV. When this file
is reloaded with the RELOAD command, Adams Solver (C++) returns to this exact configuration.
Used with other interactive Adams Solver (C++) commands, SAVE and RELOAD can help simulate several
versions of the same model. SAVE/SYSTEM creates a baseline configuration which you can then reload and
simulate repeatedly without leaving Adams Solver (FORTRAN). After each RELOAD/SYSTEM, you may
modify the model. This can be done by using the ACTIVATE and DEACTIVATE commands to switch sets
of loads on and off, for example.
file loads example.adm, the original model, which contains three sets of forces. After deactivating all the forces
example
case1
dea/sfo,id=101,102,201,202,301,302 ! Deactivate all forces
SAVE 217
C++ Commands
sim/static ! Find static equilibrium

stop
The following command file demonstrates using SAVE/STATES and RELOAD/ STATES.
deactivate/contact,id=1 ! Deactivate contact

save/states, buffer=1 ! Save states to buffer
activate/contact,id=1 ! Activate contact
reload/states, buffer=1 ! Reload states from buffer

218 Adams Solver
C++ Commands
SENSOR
The SENSOR command lists the data for a SENSOR statement, and/or redefines the function expression.
Format
Arguments
EVALUATE_ROUTINE=libname::subname Specifies an alternative library and name for the user

subroutine SEVSUB.

Respecifies an expression or defines and passes constants
to a user-written subroutine to define the sensor. To
define the sensor with an expression, follow
FUNCTION with an equal sign and the expression (e).
To define the sensor with a user-written subroutine,

follow FUNCTION with an equal sign, the character
string USER, and the values (r1[,...,r30]) that you want
Adams Solver (C++) to pass to the user-written
subroutine SENSUB (see the SENSUB subroutine). If the
FUNCTION argument is used, it must either be the last
argument in the SENSOR statement or be followed by a
backslash (\).
Range: An expression or a user parameter list of 1 to 30

real values
LIST Lists the current values of the data in the SENSOR
statement.
subroutine SENSUB.

SENSOR 219
C++ Commands
Examples
SENSOR/231, FUNCTION=DX(0202,0307)
This SENSOR command changes the function for SENSOR/231 to DX(0202,0307).
220 Adams Solver
C++ Commands
SFORCE
The SFORCE command lists or changes the characteristics of an SFORCE statement.
Format
SFORCE 221
C++ Commands
Arguments
ACTIONONLY Respecifies an action-only force. Adams Solver (C++) applies no

reaction at the J marker.
user-written subroutine to redefine a single-component force.
To redefine the force with an expression, follow FUNCTION
with an equal sign and the expression. To redefine the force with
a user-written subroutine, follow FUNCTION with an equal
sign, the character string USER, and the values (r1[,...,r30]) that
you want Adams Solver (C++) to pass to the user-written
evaluation subroutine SFOSUB (see the SFOSUB subroutine). If
the FUNCTION argument is used, it must either be the last
argument in the SFORCE statement or be followed by a
backslash (\). The force function may be changed from an
expression to the subroutine or the reverse. If neither argument
is given, the force definition does not change. FUNCTION
must either be the last argument given, or be followed by a
backslash (\).
I=id,J=id Respecifies the identifiers of two markers necessary to define the
force. If the SFORCE command defines a translational action-
reaction force, I and J specify the identifiers of the two markers
between which you want to exert the force. Adams Solver (C++)
applies the translational action-reaction force along the line of
action defined by the line segment connecting I and J. If the
SFORCE command defines an action-only force, I specifies the
point of application, and the z-axis of J specifies the direction of
the force. If SFORCE defines a torque, the z-axis of the J marker
specifies the axis of rotation. In the case of action-reaction
torques, the z-axis of the J marker must be parallel to, and
pointed in the same direction, as the z-axis of the I marker.
LIST Lists the current values of the data in the SFORCE statement.
REACTION Respecifies an action-reaction force. Adams Solver (C++) applies
reaction forces or torques at the J marker.
SFOSUB.
Extended Defintion
The SFORCE command lists or changes the characteristics of an existing SFORCE element. You can alter
one or both points of force application, change the force from ACTIONONLY to ACTION-REACTION,
or the reverse, or change the force from TRANSLATION to ROTATION, or the reverse. In addition, you
222 Adams Solver
C++ Commands
can change the force definition function expression or SFOSUB parameter list, or switch the definition
between function expression and subroutine.
After a change to an SFORCE, Adams Solver (C++) reprocesses the model at the next SIMULATE
While checking, Adams Solver (C++) verifies that the model is still valid with the new SFORCE. If, for
example, the SFORCE function expression refers to an inactive element, Adams Solver (C++) issues an error.
IFLAG set to true.
If this is the first simulation, Adams Solver (C++) also maintains any user supplied joint initial-conditions
and positions specified as EXACT.
Examples
SFORCE/201,FUNCTION=-10.*VR(101,201)
This SFORCE command changes the force definition for SFORCE 201.
SFORCE/6,I=28
This SFORCE command applies SFORCE 6 to Marker 28, leaving the J marker unchanged.
SHOW 223
C++ Commands
SHOW
The SHOW command lists statistics for any of these topics: CPU time, graphics options, status, and time.
Format
ALL
SHOW [CPUTIME] STATUS= ,GRAPHICS [TIME]
[GROPTIONS]
,REQUESTS
,SIMULATIO
N
Arguments
CPUTIME Lists the current total use of CPU time for the execution.
GROPTIONS Lists the options controlling graphics display.
Lists the statistics for each GRAPHICS statement, the statistics for
each REQUEST statement, or the statistics for the simulation, or all
of these statistics.
TIME Lists the current time and date.

224 Adams Solver
C++ Commands
SIMULATE
The SIMULATE command specifies the type of simulation you want Adams Solver (C++) to run. It also
defines the run time and the number or size of the output steps.
Format
Arguments
ACCELERATION Specifies that initial displacement, velocity, and acceleration analyses of the
mechanism are to be performed if such analyses have not already been
performed at the current time step and with the current model.
DISPLACEMENT Specifies that an initial displacement analysis of the mechanism is to be
performed if such an analysis has not already been performed at the current
time step and with the current model.
DTOUT=r Specifies the size of the output step for the analysis in model time units.
Range: DTOUT > 0

DURATION Specifies the duration of the analysis in model time units.
Range: DURATION > 0

SIMULATE 225
C++ Commands
DYNAMICS Specifies that Adams Solver (C++) is to integrate the dynamics equations. If a
dynamic analysis is requested for a system with zero degrees of freedom, Adams
Solver (C++) issues a warning message and integrates the equations instead of
using kinematic analysis. Kinematic analysis is faster.
END Specifies the end time for a dynamic, a kinematic, or a quasi-static equilibrium
analysis.
Range: END > Begin Time > 0

INITIAL_CONDITION Specifies that an initial-conditions analysis of the mechanism is to be
S performed. All three initial-conditions analyses are performed if 1) no
DISPLACEMENT, VELOCITY, or ACCELERATION argument or if 2) the
ACCELERATION argument is specified and no initial condition analyses
have been performed at the current time step with the current model.
Displacement and velocity initial conditions are performed if the VELOCITY
argument is specified and no initial condition analyses have been performed at
the current time step with the current model. Displacement initial conditions
are performed if the DISPLACEMENT argument is specified and no initial-
conditions analyses have been performed at the current time step with the
current model.
KINEMATICS Specifies that Adams Solver (C++) is to run a kinematic analysis. If a kinematic
analysis is requested for a system with one or more degrees of freedom, Adams
Solver (C++) issues a warning message and switches to dynamic analysis.
SETTLE Specifies that Adams Solver (C++) is to run a steady-state analysis. This type
of analysis consists of modifying the states of all differential elements until all
first order derivatives of the said states are zero. Only differential states are
modified during this simulation. If the model has no differential states, for
example, DIFF, LSE, GSE, TFSISO, this simulation has no effect on the
model.
The current simulation time of the model does not change during this type of
analysis.
STATICS Specifies that Adams Solver (C++) perform either a static equilibruim
simulation or a quasi-static equilibrium simulation. Adams Solver (C++):
 Performs a static equilibrium simulation at the current time if you use

the STATICS argument and you do not specify an end time or steps.
 Performs a quasi-static equilibrium simulation if you use the
STATICS argument and specify an end time and steps.
 Uses kinematic analyses to perform static simulations for models that
have zero degrees of freedom. If you request a quasi-static simulation
on a model that has zero degrees of freedom, Adams Solver (C++)
computes the same motion as in a kinematic analysis, but ignores (set
to zero) velocities and accelerations.
226 Adams Solver
C++ Commands
STEPS=i Specifies the number of output steps wanted for the analysis.
Range: STEPS > 1

TRANSIENT Specifies that Adams Solver (C++) is to run a kinematic analysis if the system
has zero degrees of freedom or a dynamic analysis if the system has one or more
degrees of freedom.
VELOCITY Specifies that initial displacement and velocity analyses of the mechanism are
to be performed if such analyses have not already been performed at the
current time step and with the current model.
Extended Definition
Adams Solver (C++) allows you to do one or more analyses on the same dataset until the STOP command is
issued. These analyses can be different types as long as they meet the degree-of-freedom requirements for that
type of analysis. For example, it is often useful or necessary to do a static equilibrium analysis on a model to
establish equilibrium conditions before doing a dynamic analysis.
Tip: Note the distinction between END and DURATION. At time zero, a SIMULATE
command with END=1 or DURATION=1 indicates an end time of one second. At time
one second, a SIMULATE command with END=1.5 indicates an end time of 1.5 seconds;
a SIMULATE command with DURATION=1.5 indicates an end time of 2.5 seconds.
SIMULATE 227
C++ Commands
Caution:  Before a dynamic simulation that follows a static simulation, Adams Solver (C++) computes
the velocity and acceleration initial conditions even if they were computed prior to the static
simulation. This ensures that the velocity and acceleration initial conditions are consistent
with the displacements from the static simulation.
 When you use END and STEPS parameters with the SIM/STAT command, time
increments past time = 0. As such, initial velocities are no longer valid and are not considered
in subsequent dynamic analyses.
 If a static simulation directly follows a dynamic simulation, Adams Solver (C++) sets the
velocities and accelerations (except gravity) to zero and repeats the displacement initial
conditions.
 Adams Solver (C++) automatically performs a dynamic analysis for kinematic systems that
include DIFFs and sets the MODE analysis constant to 4 (not 1).
 The STEPS and DTOUT arguments can indirectly affect the accuracy of the results
computed by the integrator. Under these circumstances, Adams Solver (C++) controls
solution error by adjusting the integration time step to meet the error tolerance specified by
the integrator or default values. These integrators do not use a time step greater than the
interval to the next output time, however. The output times are determined by STEPS or
DTOUT in combination with END or DURATION. Specifying a smaller output step than
the integrators would ordinarily take results in more integrator steps than actually required to
meet the error tolerance. In this case, varying the output step may vary the accuracy of the
computed results, although all results are within the specified error tolerance. If the
computed solution changes greatly when you change STEPS or DTOUT, the error tolerance
is too large. You should reduce the error tolerance. If you set the error tolerance properly, the
number of output steps should have very little effect on the computed results.
 Adams Solver (C++) may internally construct one or more differential elements in order to
handle velocity and acceleration constraints. In those cases, the model will never be
kinematical. Hence, attempts to run SIMULATE/KINEMATICS will trigger the dynamic
solver to run the simulation.
Examples
SIMULATE / KINEMATICS, END=5, STEPS=200
This SIMULATE command instructs Adams Solver (C++) to perform a kinematic analysis from the begin
time to 5 time units with 200 output steps. If this is the first analysis on this dataset in this session, the begin
time is 0 time units. Adams Solver (C++) can execute this command only if the system has zero degrees of
freedom.
SIMULATE / KINEMATICS, DURATION=2, DTOUT=.025
This SIMULATE command instructs Adams Solver (C++) to perform a kinematic analysis for 2 time units
with one output step every .025 time units.
See other Simulation commands available.
228 Adams Solver
C++ Commands
SPLINE
The SPLINE command modifies or lists an existing SPLINE statement. You can change the values of the
SPLINE data, and in the process increase or decrease the number of X data or the number of curve families.
You can only modify the name of the file using SPLINE command, if the SPLINE data is defined via Adams
Durability type (DAC/RPC). It is also required that the SPLINE is defined using Adams Durability type in
SPLINE statement.
 For information on the corresponding statement, see the SPLINE statement
 For information on the corresponding subroutine, see the SPLINE_READ subroutine.
Format
SPLINE/id
, X=x1, x2, x3, x4 [, . . . , xn]
, Y=y1, y2, y3, y4 [, . . . , yn]
, LIST
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, y34 [, . . . ,y4n], Y=z4, y41,
y42, y43, y44 [, . . . ,y4n][, . . . , Y=zm, ym1, ym2, ym3, ym4,[, . . . ,ymn]]
, LIST
or
SPLINE/id
, FILE= filename
[, CHANNEL= id]

SPLINE 229
C++ Commands
Arguments
X=x1,x2,x3,x4[ , . . . , xn]  Specifies at least four x values. The maximum number of x

values, n, depends on whether you specify a single curve or a
family of curves.
 Values must be constants; Adams Solver (C++) does not
allow expressions.
 Values must be in increasing order: x1< x2 < x3, and so on.
Y=y1,y2,y3,y4 [ , . . . , yn]  Approximates a single curve by specifying the corresponding
y value: y1,y2,y3,y4[, . . . ,yn] for each x value.
 Values must be constants; Adams Solver (C++) does not
allow expressions.
Y=z1,y11,y12,y13,y14 [ , . . . , y1n]  Approximates a family of curves by specifying the
,Y=z2,y21,y22,y23,y24 [ , . . . , y2n] corresponding y values, y1,y2,y3,y4[, . . . ,yn], for the x
,Y=z3,y31,y32,y33,y34 [ , . . . , y3n] values at unique z values (z1[, . . . ,zm]).
,Y=z4,y41,y42,y43,y44 [ , . . . , y4n]  Values must be constants; Adams Solver (C++) does not
[ ,...,Y=zm,ym1,ym2,ym3,ym4 [ , . . . , allow expressions.
ymn]]
 Values for z must be in increasing order: z1 < z2 < z3, and so
on.
FILE For use with Adams Durability only.
Modify the SPLINE to use a different Adams Durability file. It

specifies the name of the time history file that supplies data for
the SPLINE. The file can be of type DAC (nSoft format) or
PRC III (MTS format).
Using this command requires the SPLINE statement also

referencing Adams Durability file.
230 Adams Solver
C++ Commands
LINEAR_EXTRAPOLATE Causes Adams Solver (C++) to extrapolate a SPLINE that

exceeds a defined range by applying linear function(s) tangent to
the spline at the end(s) of the defined range. By default, Adams
Solver (C++) extrapolates a SPLINE that exceeds a defined
range by applying a cubic function over the first or last three
data points.
CHANNEL Specifies the integer ID of a particular channel of data in the file
referenced by the SPLINE. This argument is used for files of
type RPC III, which can contain more than one channel of data.
An error results if the specified file is of type RPC and no
CHANNEL argument is given or if the supplied channel ID
does not exist in the file. Adams Solver ignores this argument for
files of type DAC, which by definition contain only one channel
of data.
Default: (none)
Range: 1 < n < 128

LIST Lists the current SPLINE data.

SPRINGDAMPER 231
C++ Commands
SPRINGDAMPER
The SPRINGDAMPER command redefines and/or lists the data for a SPRINGDAMPER statement. You cannot
redefine the I and J marker defining the springdamper or the translational/rotational characteristic, but you
can redefine other characteristics.
Format
Arguments
ANGLE=r Respecifies the reference angle for the torsional spring. If the reference torque of the spring
is zero, ANGLE equals the free angle. Adams Solver (C++) assumes ANGLE is in radians
unless a D is added after the value.
C=r Respecifies the viscous damping coefficient for the force. The force due to damping is zero
when the system is at rest. C must be greater than or equal to zero.
CT=r Respecifies the viscous damping coefficient for the torque. The torque due to damping is
zero when the system is at rest. CT must be in units of torque per radian per unit of time.
Range: CT > 0
FORCE=r Respecifies the reference force at LENGTH.
K=r Respecifies the spring stiffness coefficient for the force.
Range: K > 0
KT=r Respecifies the spring stiffness coefficient for the torque. KT must be in units of torque per
radian.
Range: KT > 0
232 Adams Solver
C++ Commands
LENGTH=r Respecifies the reference LENGTH for the spring. If the reference force of the spring is zero,
LENGTH equals the free length.
Range: LENGTH > 0

LIST Lists the current values of the data in the SPRINGDAMPER statement.
TORQUE=r Respecifies the reference torque of the torsional spring at ANGLE.

STOP 233
C++ Commands
STOP
The STOP command terminates execution of Adams Solver (C++) in the interactive mode and returns
control to the operating system.
Format
STOP
234 Adams Solver
C++ Commands
STRING
The STRING command redefines and/or lists the data for a STRING statement.
Format
STRING/id [,STRING=c] [,LIST]
Arguments
STRING=c Respecifies the string to be stored. The STRING argument and value must appear
together on one 80-character line. If STRING is abbreviated to S and starts a line, the
supplied string can be as long as 1024 characters.
LIST Lists the string in storage.
Caution: The following characters are not permitted in a STRING argument because they are
delimiters in the Adams Solver (C++) command language: comma (,), semicolon (;),
ampersand (&), and exclamation point (!). This is because the comma indicates that
additional Adams Solver (C++) arguments follow, the semicolon indicates that additional
Adams Solver (C++) statements follow on the same line, the ampersand indicates that the
next line is a continuation of the statement on this line, and the exclamation point indicates
that Adams Solver (C++) is to stop reading the line.

TIME 235
C++ Commands
TIME
The TIME command shows the simulation time, integration step size, number of function evaluations
completed, and number of integration steps completed.
Format
TIME
Examples
TIME
Current Simulation Time = 5.0E-02
Current Integration Step Size = 1.0E-03
Number of Function Evaluations = 133
Number of Integration Steps = 59

236 Adams Solver
C++ Commands
VARIABLE
A VARIABLE command redefines or lists data for a VARIABLE statement that defines a variable in terms of a
scalar algebraic equation. The variable can be either independently used, or as part of the PINPUT,
POUTPUT, or ARRAY statement.
Format
Arguments

user-written subroutine to define a variable. If you want to define
the variable with an expression, FUNCTION must be followed
with an equal sign and the expression. If you want to define the
variable with a user-written subroutine, FUNCTION must be
followed with an equal sign, the character string USER, and the
selected values (r1[,...,r30]) that Adams Solver (C++) passes to the
user-written subroutine VARSUB (see the VARSUB subroutine).
IC=r Respecifies an approximate initial value for the VARIABLE. Adams
Solver (C++) may adjust the value of IC when it performs an initial
condition analysis. Entering an accurate value for IC may help
Adams Solver (C++) converge to the initial conditions solution.
LIST Lists the current values of the VARIABLE arguments.
VARSUB.
Extended Definition
The VARIABLE command redefines or lists a user-defined algebraic equation and its initial value. After a
change to a variable, Adams Solver (C++) reprocesses the model at the next SIMULATE command, as if it
had just been read in from the dataset. During the reprocessing, Adams Solver (C++) checks the entire model
for consistency, reinitializes user subroutines, and recomputes initial conditions.
VARIABLE 237
C++ Commands
the IFLAG argument set to true.
Tip: Consider using ARRAY instead of VARIABLE if the function is a constant value
Caution:  Caution should be used when defining a VARIABLE statement that is dependent on
another VARIABLE statement or on an Adams Solver (C++) statement that contains
functions. If a defined system of equations does not have a stable solution, convergence
may fail for the entire Adams Solver (C++) model. The following example refers to this
type of VARIABLE statement:
V=V+1.
However, when Adams Solver (C++) tries to solve this equation using the Newton-
Raphson iteration, the solution diverges and a message appears on the screen indicating
that the solution has failed to converge.
 The IC argument can be altered only prior to a simulation. If you run a simulation and
then try to alter IC, Adams Solver (C++) rejects the entire VARIABLE command.
exception or lead Adams Solver (C++) away from the desired solution.

238 Adams Solver
C++ Commands
VFORCE
The VFORCE command redefines and/or lists the data for a VFORCE statement that defines a translational
vector force element as specified using three orthogonal components.
Format
Arguments

VFORCE translational force. The direction of this component is
FXYZ=e3d Respecifies the 3D vector expression for the VFORCE force relative to
the RM marker.
FUNCTION=USER(r1[,...,r30]) Respecifies up to 30 user-defined constants for use in computing the
force components in a user-defined subroutine VFOSUB (see the
VFOSUB subroutine).
I=id Respecifies the marker at which Adams Solver (C++) applies the action
force. You must ensure that the I marker is a fixed marker and on a
Adams Solver (C++) always applies the force at a fixed point on the part.
VFORCE 239
C++ Commands
JFLOAT=id Respecifies the marker at which Adams Solver (C++) applies the
reaction force. You must ensure that the JFLOAT marker is a floating
marker and on a different part than the I marker. Adams Solver (C++)
moves the JFLOAT marker to keep it superimposed on the I marker,
which means that the reaction force may move with respect to the part.
Adams Solver (C++) does not calculate reaction forces when the
LIST Lists the current values of the VFORCE arguments.
RM=id Respecifies the marker that determines the orientation of the force
VFOSUB.
Extended Definition
The VFORCE statement lists or redefines a force element that consists of three mutually orthogonal
translational force components. You can alter one or both points of force application, change the force
reference marker, and change the force function expressions or the parameters passed to the VFOSUB user-
written subroutine.
After a change to a VFORCE, Adams Solver (C++) reprocesses the model at the next SIMULATE command,
While checking, Adams Solver (C++) verifies that the model is still valid with the new VFORCE. If, for
example, the VFORCE function expression refers to an inactive element, Adams Solver (C++) issues an error.
IFLAG set to true.
the same part as the I marker, or the JFLOAT marker, or to a third, unrelated part.
240 Adams Solver
C++ Commands
Caution: The user-defined functions FX, FY, and FZ should be smooth, continuous, and single-
Example
VFORCE/10,LIST &
,FX= -90.5*Dx(109,102,102) - 9.05*Vx(109,102,102,102)\ &
,FY= -90.5*Dy(109,102,102) - 9.05*Vy(109,102,102,102)\ &
,FZ=-750.8*Dz(109,102,102) - 75.08*Vz(109,102,102,102)
Example 2
VFORCE/10, LIST &
,FXYZ = -90.5*DXYZ(109,102,102) - 9.05*VXYZ(109,102,102) - [0, 0,
660.3*DZ(109,102,102), 66.03*VZ(109,102,102,102)]
VTORQUE 241
C++ Commands
VTORQUE
The VTORQUE command redefines and/or lists the data for a VTORQUE statement that defines a vector
torque that consists of three orthogonal components.
Format
Arguments
FUNCTION=USER(r1[,...,r30]) Respecifies up to thirty user-defined constants used to compute the

torque components in an externally-defined subroutine VTOSUB (see
the VTOSUB subroutine).
JFLOAT=id Respecifies the marker on the part to which Adams Solver (C++) applies
the reaction torque. You must ensure that the JFLOAT marker is a
marker. Adams Solver (C++) does not calculate reaction forces when the
I=id Respecifies the marker on the part to which Adams Solver (C++) applies
the action torque. You must ensure that the I marker is a fixed marker
and on a different part than the JFLOAT marker.
LIST Lists the current values of the VTORQUE arguments.
ROUTINE=libname::subname Specifies an alternative library and name for the user subroutine VTOSUB.

RM=id Respecifies the marker that determines the orientation of the torque
242 Adams Solver
C++ Commands
TXYZ=e3d Respecifies the 3D vector expression for the VTORQUE torque relative
to the RM marker.
TX=e Respecifies the magnitude and sign of the x component of the torque
rotation).
TY=e Respecifies the magnitude and sign of the y component of the torque
component is parallel to the y-axis of the RM marker in the sense of the
rotation).
TZ=e Respecifies the magnitude and sign of the z component of the torque
rotation).
Extended Definition
The VTORQUE command lists or redefines a force element that consists of three mutually orthogonal
translational torque components. You can alter one or both points of torque application, change the torque
reference marker, and change the torque function expressions or the parameters passed to the VTOSUB user-
written subroutine.
After a change to a VTORQUE, Adams Solver (C++) reprocesses the model at the next SIMULATE
While checking, Adams Solver (C++) verifies that the model is still valid with the new VTORQUE. If, for
example, the VTORQUE function expression refers to an inactive element, Adams Solver (C++) issues an
error.
IFLAG set to true.
VTORQUE 243
C++ Commands
Tip: Depending on the nature of the desired torque relationship, the RM marker may belong to
Caution: The user-defined functions TX, TY, and TZ should be smooth, continuous, and single-
Example 1
VTORQUE/10, LIST &
,TX= -90.5*Dx(109,102,102) - 9.05*Vx(109,102,102,102)\ &
,TY= -90.5*Dy(109,102,102) - 9.05*Vy(109,102,102,102)\ &
,TZ=-750.8*Dz(109,102,102) - 75.08*Vz(109,102,102,102)
Example 2
VTORQUE/10, LIST &
,TXYZ = -90.5*DXYZ(109,102,102) - 9.05*VXYZ(109,102,102) - [0, 0,
660.3*DZ(109,102,102), 66.03*VZ(109,102,102,102)]
244 Adams Solver
C++ Commands
Welcome to the FORTRAN Version of Adams Solver 1
Adams Solver (FORTRAN) Statements
Welcome to the FORTRAN Version of

Adams Solver
The FORTRAN version of Adams Solver, part of the Adams® suite of software, is a powerful numerical
analysis application that automatically solves the equations of motion for kinematic, static, quasi-static, and
dynamic simulations. You can use Adams Solver (FORTRAN) to build, test, and refine mechanical system
models. If you combine Adams Solver (FORTRAN) with the optional Adams Linear product, you can also
perform linearization simulations. You can then take your simulation results from Adams Solver
(FORTRAN) into a graphical user interface, such as Adams View, that lets you animate and optimize models,
automate the simulation process, and customize the interface to suit your particular needs.
The online help provides detailed information on the individual statements, function expressions, and
commands you use when working with Adams Solver (FORTRAN). Find detailed information on subroutines you
use with Adams Solver (FORTRAN).
Switch to Adams Solver (C++).

You use statements to define the elements of your model, request output from the simulation, and, optionally,
set analysis parameters to use during the simulation. Note that you can use the FORTRAN version of Adams
Solver commands to set analysis parameters, which is often a better approach.
Below are the Adams Solver (FORTRAN) statements grouped according to their function. Detailed
information on each statements can be found by following the links:

Dataset delimiter END
TITLE
FLEX_BODY
POINT_MASS
bordered GRAPHICS
MARKER
Constraints COUPLER
CVCV
GEAR
JOINT
JPRIM
MOTION
PTCV
UCON
2 Adams Solver

Forces ACCGRAV
BEAM
BUSHING
CONTACT
FIELD
FRICTION
GFORCE
MFORCE
NFORCE
SFORCE
SPRINGDAMPER
VFORCE
VTORQUE
Generic systems modeling DIFF
GSE
LSE
TFSISO
VARIABLE
CURVE
MATRIX
PINPUT
POUTPUT
SPLINE
STRING
EQUILIBRIUM
IC
INTEGRATOR
KINEMATICS
PREFERENCES
SENSOR
UNITS
Output FEMDATA
LIST/NOLIST
MREQUEST
OUTPUT
REQUEST
RESULTS
ACCGRAV 3
ACCGRAV
The ACCGRAV statement specifies the magnitude and direction of the acceleration of gravity. In
conjunction with the part masses, the gravitational field defines a body force at the center of gravity in each
part.
Format
Arguments
IGRAV Defines the x component of gravitational acceleration with respect to the ground coordinate
system.
Default: 0
JGRAV Defines the y component of gravitational acceleration with respect to the ground coordinate
system.
Default: 0
KGRAV Defines the z component of gravitational acceleration with respect to the ground coordinate
system.
Default: 0
Examples
ACCGRAV/JGRAV=-386.088
This ACCGRAV statement defines the gravitational constant of 386.088, acting along the y-axis of the
ground coordinate system (GCS) in the negative direction.
4 Adams Solver
ARRAY
The ARRAY statement defines a list of input variables (U), state variables (X), output variables (Y), or initial
conditions (IC) associated with system modeling elements such as GSE, LSE, and TFSISO (see GSE, LSE
and TFSISO). IC ARRAY's or ARRAY's without a type can also be used to define a list of constants. These
values may be accessed in function expressions or user-written subroutines.
Format
{ } Select one item
Arguments
IC Creates a one-dimensional array of real numbers that can be accessed in

user-written subroutines. You can use IC to designate an initial conditions
array for an LSE or GSE. In that case, you should ensure that t he SIZE is
the same as the X (state variable) array of the associated LSE or GSE.
NUMBERS=r1[,r2,...] Allows you to enter a one-dimensional array of real numbers when using the
IC array.
SIZE=i Allows you to define the size of the array. In cases where Adams Solver
(FORTRAN) calculates the SIZE differently from the SIZE that you
supply, Adams Solver (FORTRAN) returns an error or warning message.
VARIABLES=id1[,id2,...,] Defines a list of identifiers of VARIABLE statements to group in an array.
The VARIABLES argument is used with only an input array (U).
Range: Any valid VARIABLE id

ARRAY 5
X Designates an ARRAY statement to be the state variable array for a systems

modeling element, LSE, GSE, or TFSISO. To use these arrays, you must
reference the ARRAY statement as the state variable array in a system
element statement. You can use a single X array with only a single systems
element. When you choose X, the only other argument available is SIZE.
When you don’t specify SIZE, the associated systems element automatically
sets the size.
U Creates an array that groups together a set of VARIABLES, normally to
define the inputs for a systems element, either LSE, GSE, or TFSISO.
When you choose U, SIZE and VARIABLES are the only other available
arguments.
Y Designates an ARRAY statement as the output array for a systems element,
either LSE, GSE, or TFSISO. To use these arrays, you must reference the
ARRAY statement as the output array in the system element definition in
the dataset. When you choose Y, SIZE is the only other argument available.
You can use a single Y array with only a single systems element. The SIZE
value, if supplied, must be consistent with the associated systems element.
When you don’t specify SIZE, the associated systems element automatically
sets it.
Extended Definition
The ARRAY statement defines a list of input variables (U), state variables (X), output variables (Y), and initial
conditions (IC) associated with system modeling elements such as GSE, LSE, and TFSISO. ARRAY may also be
used to define a list of constants. These values may be accessed in function expressions or user-written
subroutines.
There are three basic variations of the ARRAY statement:
 The X and Y arrays designate the state and output variable arrays for a systems element. Adams
Solver (FORTRAN) computes these values during a simulation.
 The U array defines an array of inputs for a systems element. Adams Solver (FORTRAN) computes
these values from the specified VARIABLE statements.
 The IC array defines an array of constants used as initial conditions.
For the X and Y arrays, the corresponding systems modeling element automatically determines the size of the
array and checks it against the ARRAY statement’s SIZE value (if given).
The IC and SIZE parameters are optional. Adams Solver (FORTRAN) determines the actual size of the array
during input-file parsing as it counts the NUMBERS argument. However, if you provide a value for SIZE,
Adams Solver (FORTRAN) checks the count for consistency.
For X and Y arrays, you should reference the array as the state variable array or output variable array of one
of the system elements in the dataset, either LSE, GSE, or TFSISO. U and IC arrays may exist independently.
Grouping VARIABLES in a U array does not offer any computational advantage, although it might have a
convenience value.
6 Adams Solver
The SIZE argument, if used, should match the number of entries in the VARIABLES or NUMBERS
arguments or the size needed for the associated element. Adams Solver (FORTRAN) provides the SIZE
argument mainly for your convenience in dataset creation. For LSE arrays, the X size is the row dimension
of the A and B matrix, and the Y size is the row dimension of the C and D matrix. For TFSISO arrays, the
transformation from the transfer function form to canonical state space form determines the X size; the size
of Y and U is always one. For GSE arrays, X is size NS as defined in the matching GSE statement and Y is
size NO, as defined in the same GSE statement.
Both function expressions and user-written subroutines can access the array values. Function expressions use
the function ARYVAL (id, nseq) to access the values. The id specifies the identifier of the ARRAY, and nseq
specifies the position of the desired value in the ARRAY statement. To access all the elements of an array from
a user written subroutine, you should call the subroutine SYSARY (see the SYSARY subroutine). To access one
element of an ARRAY in a subroutine, you should call the subroutine SYSFNC.
Examples
The following are three simple examples of the ARRAY statement.
ARRAY/1, X
ARRAY/2, U, VARIABLES=2
ARRAY/3, IC, NUMBERS= 0.0, 0.0

BEAM 7
BEAM
The BEAM statement defines a massless elastic beam with a uniform cross section. The beam transmits forces
and torques between two markers in accordance with Timoshenko beam theory.
Format
8 Adams Solver
Arguments
AREA=r Specifies the uniform area of the beam cross section. The centroidal axis must be
orthogonal to this cross section.
ASY=r Specifies the correction factor (that is, the shear area ratio) for shear deflection in
the y direction for Timoshenko beams.
A Qy 2
ASY = -----2-   ------ dA
 
Iy A lz
where Qy is the first moment of cross-sectional area to be sheared by a force in the

z direction, and lz is the cross section dimension in the z direction.
If you want to neglect the deflection due to y-direction shear, ASY does not need
to be included in a BEAM statement.
Defaults: 0
ASZ=r Specifies the correction factor (that is, the shear area ratio) for shear deflection in
the z direction for Timoshenko beams.
A Qz 2
ASZ = -----2-   ------ dA
 
Iz A ly
where Qz is the first moment of cross-sectional area to be sheared by a force in the

y direction, and ly is the cross section dimension in the y direction.
If you want to neglect the deflection due to z-direction shear, ASZ does not need
to be included in a BEAM statement.
Defaults: 0
Commonly encountered values for the shear area ratio are:
Cross-section: (Shear area ratio)
Solid rectangular (6/5)
Solid circular (10/9)
Thin wall hollow circular (2)
See also “Roark’s Formulas for Stress and Strain,” Young, Warren C., Sixth Edition,
page 201. New York:McGraw Hill, 1989.
BEAM 9
CMATRIX=r1,...,r Establishes a six-by-six damping matrix for the beam. Because this matrix is
21 symmetric, only one-half of it needs to be specified. The following matrix shows
the values to input:
r01
r02 r07
r03 r08 r12
r04 r09 r13 r16
r05 r10 r14 r17 r19
r06 r11 r15 r18 r20 r21
Enter the elements by columns from top to bottom, then by rows from left to right.
If you do not use either CMATRIX or CRATIO, CMATRIX defaults to a matrix
with thirty-six zero entries; that is, r1 through r21 each default to zero.
CRATIO=R Establishes a ratio for calculating the damping matrix for the beam. Adams Solver
multiplies the stiffness matrix by the value of CRATIO to obtain the damping
matrix.
Defaults: 0
EMODULUS=r Defines Young’s modulus of elasticity for the beam material.
GMODULUS=r Defines the shear modulus of elasticity for the beam material.
I=id, J=id Specifies the two markers between which to define a beam. The J marker establishes
the direction of the force components.
IXX=r Denotes the torsional constant. This is sometimes referred to as the torsional shape
factor or torsional stiffness coefficient. It is expressed as unit length to the fourth
power. For a solid circular section, Ixx is identical to the polar moment of inertia,
4
πr
J = --------
2
where r is the radius of the cross-section. For thin-walled sections, open sections,
and noncircular sections, you should consult a handbook.
IYY=r,IZZ=r Denote the area moments of inertia about the neutral axes of the beam cross
sectional areas (y-y and z-z). These are sometimes referred to as the second moment
of area about a given axis. They are expressed as unit length to the fourth power.
For a solid circular section,
4
πr -
-------
Iyy=Izz=
4
where r is the radius of the cross-section. For thin-walled sections, open sections,
and noncircular sections, you should consult a handbook.
LENGTH=r Defines the underformed length of the beam along the x-axis of the J marker.
10 Adams Solver
Extended Definition
To model the effects of a beam, Adams Solver (FORTRAN) uses a linear translational and linear rotational
action-reaction force between two markers. The forces the beam produces are linearly dependent on the
displacements, rotations, and corresponding velocities between the markers at its endpoints.
The figure below shows the two markers (I and J) that define the extremities of the beam and indicates the
twelve forces (s1 to s12) it produces.
Massless Beam
The x-axis of the J marker defines the centroidal axis of the beam. The y-axis and z-axis of the J marker are
the principal axes of the cross section. They are perpendicular to the x-axis and to each other. When the beam
is in an undeflected position, the I marker has the same angular orientation as the J marker, and the I marker
lies on the x-axis of the J marker a distance LENGTH away.
The beam statement applies the following forces to the I marker in response to the relative motion of the I
marker with respect to the J marker:
 Axial forces (s1 and s7)
 Bending moments about the y-axis and z-axis (s5, s6, s11, and s12)
 Twisting moments about the x-axis (s4 and s10)
 Shear forces (s2, s3, s8, and s9)
The following constitutive equations define how Adams Solver uses the data for a linear field to apply a force
and a torque to the I marker depending on the displacement rotation and velocity of the I marker relative to
the J marker.
BEAM 11
Fx K 11 0 0 0 0 0
x–L
Fy 0 K 22 0 0 0 K 26 y
Fz 0 0 K 33 0 K 35 0 z
= –
Tx 0 0 0 K 44 0 0 a
Ty 0 0 K 53 0 K 55 0 b
Tz 0 K 62 0 0 0 K 66 c
c 11 c 21 c 31 c 41 c 51 c 61 V x
c 21 c 22 c 32 c 42 c 52 c 62 V y
c 31 c 32 c 33 c 43 c 53 c 63 V z
–
c 41 c 42 c 43 c 44 c 54 c 64 ω x
c 51 c 52 c 53 c 54 c 55 c 65 ω y
c 61 c 62 c 63 c 64 c 65 c 66 ω z
where:
 Fx, Fy, and Fz are the measure numbers of the translational force components in the coordinate
system of the J marker.
 x, y, and z are the translational displacements of the I marker with respect to the J marker measured
in the coordinate system of the J marker.
 Vx, Vy, and Vz are the time derivatives of x, y, and z, respectively.
 Tx, Ty, and Tz are the rotational force components in the coordinate system of the J marker.
 a, b, and c are the relative rotational displacements of the I marker with respect to the J marker as
expressed in the x-, y-, and z-axis, respectively, of the J marker.
 ω x , ω y , and ω z are the components of the angular velocity of the I marker with respect to the J
marker, as seen by the J marker and measured in the J marker coordinate system.
 Cij are the entries of the damping matrix either specified by the CMATRIX option or computed by
using the CRATIO option. All Cij entries default to zero.
Note that both matrices, Cij and Kij, are symmetric, that is, Cij=Cji and Kij=Kji. You define the twenty-one
unique damping coefficients when the BEAM statement is written. Adams Solver (FORTRAN) defines each
Kij as follows:
12 Adams Solver
Adams Solver (FORTRAN) applies an equilibrating force and torque at the J marker, as defined by the
following equations:
Fj = - Fi
T j = - T i - L x Fi
The BEAM statement implements a force in the same way the FIELD statement does, but the BEAM
statement requires you to input only the values of the beam’s physical properties, which Adams Solver
(FORTRAN) uses to calculate the matrix entries.
Tip:  A FIELD statement can be used instead of a BEAM statement to define a beam with
characteristics unlike those the BEAM statement assumes. For example, a FIELD
statement should be used to define a beam with a nonuniform cross section or a beam
with nonlinear material characteristics.
 The beam element in Adams Solver is similar to those in most finite element
programs. That is, the stiffness matrix that Adams Solver (FORTRAN) computes is
the standard beam element stiffness matrix.
 The USEXP option on the MARKER statement may make it easier to direct the x-
 Generally, it is desirable to define the x-axis of the Adams Solver (FORTRAN) beam
on the shear center axis of the beam being modeled.
BEAM 13
Caution:  The K1 and K2 terms used by MSC.NASTRAN for defining the beam properties
using PBEAM are inverse of the ASY and ASZ used by Adams Solver (FORTRAN).
 When the x-axes of the markers defining a beam are not collinear, the beam deflection
and, consequently, the force corresponding to this deflection are nonzero. To
minimize the effect of such misalignments, perform a static equilibrium at the start of
the simulation.
 By definition, the beam lies along the positive x-axis of the J marker. (This is unlike
most other Adams Solver force statements, for which the z-axis is the significant axis.)
Therefore, the I marker must have a positive x displacement with respect to the J
marker when viewed from the J marker. In its undeformed configuration, the
orientation of the I and the J markers must be the same.
 The damping matrix that CMATRIX specifies should be positive semidefinite. This
ensures that damping does not feed energy into the system. Adams Solver
(FORTRAN) does not warn you if CMATRIX is not positive semidefinite.
 When the beam element angular deflections are small, the stiffness matrix provides a
meaningful description of beam behavior. However, when the angular deflections are
large, they are not commutative; so the stiffness matrix that produces the translational
and rotational force components may not correctly describe the beam behavior. If
BEAM translational displacements exceed ten percent of the undeformed LENGTH,
then Adams Solver issues a warning message.
 By its definition a BEAM is asymmetric. Holding the J marker fixed and deflecting
the I marker produces different results than holding the I marker fixed and deflecting
the J marker by the same amount. This asymmetry occurs because the coordinate
system frame that the deflection of the BEAM is measured in moves with the J
marker.
Examples
A cantilevered stainless steel beam is to be modeled with a circular cross section that has the loading shown
in the figure below.
14 Adams Solver
A weight of 17.4533 lbf at the free end of the beam with a 100-inch axial offset in the negative y direction
causes torsion to the beam as shown in the figure above. The following statement defines this beam:
BEAM/0201, I=0010, J=0020, LENGTH=100
, IXX=100, IYY=50, IZZ=50, AREA=25.0663
, ASY=1.11, ASZ=1.11, EMOD=28E6, GMOD=10.6E6,
, CRATIO=0.0001
The beam lies between Marker 0010 and Marker 0020. The length of the beam is 100 inches; its torsional
constant is 100 inch4; its principal area moments of inertia about the y-axis is 50 inch4, and about the z-axis
is 50 inch4; its cross-sectional area is 25.0663 inch2; its shear area ratio in the y direction is 1.11; its shear area
ratio in the z direction is 1.11; its modulus of elasticity is 28E6 psi; its shear modulus is 10.6 psi; and its
damping ratio relative to the stiffness matrix Adams Solver (FORTRAN) calculates is 0.0001. Note that the
beam ends belong to different parts.
References
1. Roark's Formulas for Stress and Strain, Young, Warren C., Sixth Edition, page 201. New York:
McGraw Hill, 1989.
See other Forces statement available.
BUSHING 15
BUSHING
The BUSHING statement defines a massless bushing with linear stiffness and damping properties.
Format
Arguments
C=r1,r2,r3 Specifies three viscous damping coefficients for the force transferred by the bushing.
The three coefficients multiply the relative translational velocity components of the I
marker with respect to the J marker as seen by the J marker and along the x-, y-, and
z-axis of the J marker. The force due to damping is zero when there is no relative
translational velocity between the two markers. C must be in units of force per unit
length per unit of time.
Default: 0,0,0
Range: C > 0
CT=r1,r2,r3 Specifies three viscous damping coefficients for the torque transferred by the bushing.
The three coefficients multiply the components of the relative angular velocity of the
part containing the I marker with respect to the part containing the J marker as
expressed in the x-, y-, and z-axis of the J marker. The torque due to damping is zero
when there is no relative angular velocity between the two markers. CT must be in
units of torque per radian per unit of time.
Default: 0,0,0
Range: CT > 0
FORCE=r1,r2,r3 Specifies three constant force (preload) values. Constant values indicate the force
components along the x-, y-, and z-axis of the J marker when both the relative
displacement and the relative velocity of the I and J markers are zero.
Default: 0,0,0
I=id, J=id Specifies the identifiers of the two markers between which the bushing is placed.
16 Adams Solver
K=r1,r2,r3 Specifies three stiffness coefficients for the force transferred by the bushing. The three
coefficients multiply the three translational displacement components of the I marker
with respect to the J marker as expressed in the x-, y-, and z-axis of the J marker. K
must be specified in terms of force per unit of deformation.
Default: 0,0,0
Range: K > 0
KT=r1,r2,r3 Specifies three stiffness coefficients for the torque transferred by the bushing. The
three coefficients multiply the three rotational displacement components of the I
marker axes relative to the J marker axes as expressed in the x-, y-, and z-axis of the J
marker. KT must be in units of torque per radian.
Default: 0,0,0
Range: KT > 0
TORQUE=r1,r2,r Specifies three constant torque (preload) values. Constant values indicate the torque
3 components about the x-, y-, and z-axis of the J marker when both the relative
displacement and the relative velocity of the I and the J markers are zero.
Default: 0,0,0
Extended Definition
The BUSHING statement defines a massless bushing with linear stiffness and damping properties. The
BUSHING statement applies a force and torque to two parts. You specify a marker on each part for force or
torque application.
Each force consists of three components in the coordinate system of the J marker, one in the x-axis direction,
one in the y-axis direction, and one in the z-axis direction.
Likewise each torque consists of three components in the coordinate system of the J marker: one about the
x-axis, one about the y-axis, and one about the z-axis. The force is linearly dependent upon the relative
displacement and the relative velocity of the two markers. The torque is dependent upon the relative angle of
rotation and the relative rotational velocity of the parts containing the specified markers.
A BUSHING statement has the same constitutive relation form as a FIELD statement. The primary
difference between the two statements is that certain coefficients (Kij and Cij, where i j) are zero for the
BUSHING statement. Only the diagonal coefficients (Kii and Cii) are defined for a BUSHING.
BUSHING 17
Fx K 11 0 0 0 0 0
x
Fy 0 K 22 0 0 0 0 y
Fz 0 0 K 33 0 0 0 z
= –
Tx 0 0 0 K 44 0 0 a
Ty 0 0 0 0 K 55 0 b
Tz 0 0 0 0 0 K 66 c
c 11 0 0 0 0 0 Vx F1
0 c 22 0 0 0 0 Vy F2
0 0 c 33 0 0 0 Vz F3
– +
0 0 0 c 44 0 0 ωx T1
0 0 0 0 c 55 0 ωy T2
0 0 0 0 0 c 66 ω z T3
Fx, Fy, and Fz are the measure numbers of the translational force components in the coordinate system of the
J marker. The terms x, y, and z are the translational displacements of the I marker with respect to the J marker
measured in the coordinate system of the J marker. The terms Vx, Vy, and Vz are the time derivatives of x, y,
and z, respectively. The terms F1, F2, and F3 represent the measure numbers of any constant preload force
components in the coordinate system of the J marker.
Tx, Ty, and Tz are the rotational force components in the coordinate system of the J marker. The terms a, b,
and c are the relative rotational displacements of the I marker with respect to the J marker as expressed in the
x-, y-, and z-axis, respectively, of the J marker. The terms ω x , ω y , and ω z are the angular velocity
components of the I marker with respect to the J marker, measured in the coordinate system of the J marker.
The terms T1, T2, and T3 are the measure numbers of any constant torque in the coordinate system of the J
marker.
Adams Solver (FORTRAN) applies an equilibrating force and torque to the J marker, as defined by the
following equations:
Fj=-Fi
Tj = - Ti - δ x Fi
δ is the instantaneous deformation vector from the J marker to the I marker. While the force at the J marker
is equal and opposite to the force at the I marker, the torque at the J marker is usually not equal to the torque
at the I marker because of the deformation.
18 Adams Solver
The BUSHING only models linear bushings. The GFORCE or FIELD (with a FIESUB) may be used to
model nonlinear bushings.
Caution: For the rotational constitutive equations to be accurate, at least two of the rotations (a, b, c)
must be small. That is, two of the three values must remain smaller than 10 degrees. In
addition, if a becomes greater than 90 degrees, b becomes erratic. If b becomes greater than 90
degrees, a becomes erratic. Only c can become greater than 90 degrees without causing
convergence problems. For these reasons, it is best to define your bushing such that angles a
and b (not a and c and not b and c) remain small.
Examples
BUSHING/1022, I=10, J=22, K=5000,5000,2000, C=5,5,2
, KT=50000,50000,0, CT=50,50,0
This BUSHING statement describes a bushing with translational spring rates of 5000 units in both the x-
axis and the y-axis directions of Marker 22 and of 2000 units in the z-axis direction of Marker 22. The
corresponding damping rates for the force are 5 units in both the x- and y-axis directions of Marker 22 and
2 units in the z-axis direction of Marker 22. The rotational spring rates are 50000 units about the x- and y-
axis of Marker 22. The corresponding damping rates for the torque are 50 units in both the x- and y-axis
directions of Marker 22 and zero units in the z-axis direction of Marker 22. Since the z components of KT
and CT are zero, the I marker can rotate about the z-axis of the J marker without generating any torque. There
are no FORCE or TORQUE values because there is no initial load (preload) associated with the input
positions of the markers.
CONTACT 19
CONTACT
The CONTACT statement lets you define a two- or three-dimensional contact between a pair of geometric
objects. Adams Solver (FORTRAN) models the contact as a unilateral constraint, that is, as a force that has
zero value when no penetration exists between the specified geometries, and a force that has a positive value
when penetration exists between two geometries.
The CONTACT statement supports:
 Multiple contacts
 Dynamic friction
 Contact between three-dimensional solid geometries
 Contact between two-dimensional geometries
It does not support non-solid three-dimensional geometries, such as shells that do not encompass a volume
and sheets. It also does not support contact between a two-dimensional and a three-dimensional geometry.
Adams Solver (FORTRAN) has two geometry engines that it uses for three-dimensional contacts. It uses
Parasolid, a geometry toolkit from EDS/Unigraphics and RAPID. Currently, RAPID is the default and
Adams Solver (FORTRAN) supports version 2.01.
For two-dimensional contacts, Adams Solver (FORTRAN) uses an internally developed geometry engine.
Currently, Adams Solver (FORTRAN) supports Parasolid 28.1.238. See the Extended Definition for more
information.
The geometry engine is responsible for detecting contact between two geometries, locating the points of
contact, and calculating the common normal at the contact points.
Once the contact kinematics are known, contact forces, which are a function of the contact kinematics, are
applied to the intersecting bodies.
Note: You can only define two-dimensional contacts between bodies that are constrained to be in the
same plane. This is usually done with planar or revolute joints or an equivalent set of
constraints that enforce the planarity.
Failure to enforce planarity will result in a run-time error, when the bodies go out of plane
during a simulation.
The following table shows the legal combinations of geometry for the CONTACT statement. If you use
unsupported geometry combinations, you will receive an error.
Supported Geometry Combinations
20 Adams Solver
Note: You can set the default geometry library. See the PREFERENCES statement.
CONTACT 21
Format
22 Adams Solver
Arguments
AUGMENTED_LAGRANGIA Refines the normal force between two sets of rigid geometries that are
N_FORMULATION in contact. It uses iterative refinement to ensure that penetration
between the geometries is minimal. It also ensures that the normal force
magnitude is relatively insensitive to the penalty or stiffness used to
model the local material compliance effects.
You can use this formulation only with the POISSON model for
normal force.
COULOMB_FRICTION = Models friction effects at the contact locations using the Coulomb
off/on friction model to compute the frictional forces.
 The friction model in CONTACT models dynamic friction

but not stiction.
 The argument values, On/Off, specify at run time whether the
friction effects are to be included.
DAMPING = r Used when you specify the IMPACT model for calculating normal
forces. DAMPING defines the damping properties of the contacting
material. You should set the damping coefficient is about one percent of
the stiffness coefficient.
Range: DAMPING > 0

DMAX = r Used when you specify the IMPACT model for calculating normal
forces. DMAX defines the penetration at which Adams Solver turns on
full damping. Adams Solver uses a cubic STEP function to increase the
damping coefficient from zero, at zero penetration, to full damping
when the penetration is DMAX. A reasonable value for this parameter
is 0.01 mm. For more information, refer to the IMPACT function.
Range: DMAX > 0

EXPONENT=r Used when you specify the IMPACT model for calculating normal
forces. Adams Solver (FORTRAN) models normal force as a nonlinear
spring-damper. If PEN is the instantaneous penetration between the
contacting geometry, Adams Solver calculates the contribution of the
material stiffness to the instantaneous normal forces as STIFFNESS *
(PENALTY)**EXPONENT. For more information, see the IMPACT
function.
Exponent should normally be set to 1.5 or higher.
Range: 0 < EXPONENT

CONTACT 23
FRICTION_TRANSITION_V Used in the COULOMB_FRICTION model for calculating frictional

ELOCITY = r forces at the contact locations. Adams Solver gradually transitions the
coefficient of friction from MU_STATIC to MU_DYNAMIC as the
slip velocity at the contact point increases. When the slip velocity is
equal to the value specified for
FRICTION_TRANSITION_VELOCITY, the effective coefficient of
friction is set to MU_DYNAMIC. For more details, see Extended
Definition.
Note: Small values for FRICTION_TRANSITION_VELOCITY

cause the integrator difficulties. You should specify this value
as:
FRICTION_TRANSITION_VELOCITY > 5* ERROR
where ERROR is the integration error used for the solution. Its default
value is 1E-3.
Range:
FRICTION_TRANSITION_VELOCITY >
STICTION_TRANSITION_VELOCITY > 0
FRICTION_FUNCTION=US Specifies up to thirty user-defined constants to compute the contact
ER(r1[,...,r30]) friction force components in a user-defined subroutine, CNFSUB.
FRICTION_ROUTINE = Specifies a library and a user-written subroutine in that library that
library::function calculates the contact friction force.
TYPE = {contact_type} Specifies contact type as:
 solid_to_solid
 curve_to_curve
 point_to_curve
 point_to_plane
 curve_to_plane
 sphere_to_plane
 sphere_to_sphere
 flex_to_solid
 flex_to_flex
 flex_edge_to_curve
 flex_edge_to_flex_edge
 flex_edge_to_plane
 cylinder_to_cylinder
24 Adams Solver
IGEOM = id ID of the GRAPHICS statement that defines the first of two geometric
bodies between which a CONTACT is to be modeled. Specifies a list of
GRAPHICS IDs. The limit is 32,767. All geometries must belong to
the same part.
JGEOM = id ID of the GRAPHICS statement that defines the second of two
geometric bodies between which a CONTACT is to be modeled.
Specifies a list of GRAPHICS IDs. The limit is 32,767. All geometries
must belong to the same part.
IFLIP_GEOMETRY = Specifies a list of GRAPHICS IDs associated with the IGEOM objects
id1,id2,...,idN to be reversed in direction (flipped). Use IFLIP_GEOMETRY with
two-dimensional geometries (for example, curves, arcs, and circles) and
three-dimensional geometries (for example, cylinders and spheres as
ellipsoids with equal axes). For an explanation of how CONTACT
calculates tangents and normals, see Extended Definition.
IMPACT Specifies that the IMPACT method is to be used to model the normal
force. For more information, see Extended Definition.
JFLIP_GEOMETRY = Specifies a list of GRAPHICS IDs associated with the JGEOM objects
id1,id2,...,idN to be reversed in direction (flipped). Use JFLIP_GEOMETRY with
two-dimensional geometries (for example, curves, arcs, and circles) and
three-dimensional geometries (for example, cylinders and spheres as
ellipsoids with equal axes). For an explanation of how CONTACT
calculates tangents and normals, see Extended Definition.
MU_DYNAMIC = r Specifies the coefficient of friction at a contact point when the slip
velocity is larger than the FRICTION_TRANSITION_VELOCITY.
For information on material types versus commonly used values of the
coefficient of the dynamic coefficient of friction, see the Material Contact
Properties table. Excessively large values of MU_DYNAMIC can cause
integration difficulties.
Range:0 < MU_DYNAMIC < MU_STATIC

MU_STATIC=r Specifies the coefficient of friction at a contact point when the slip
velocity is smaller than the STICTION_TRANSITION_VELOCITY.
For information on material types versus commonly used values of the
coefficient of static friction, see the Material Contact Properties table.
Excessively large values of MU_STATIC can cause integration
difficulties.

NORMAL_FUNCTION = Specifies up to thirty user-defined constants to compute the contact
USER(r1,[,...,r30]) normal force components in a user-defined subroutine, CNFSUB.
NORMAL_ROUTINE = Specifies a library and a user-written subroutine in that library that
library::function calculates the contact normal force.
CONTACT 25
PENALTY=r Used when you specify a restitution model for calculating normal
forces. PENALTY defines the local stiffness properties between the
contacting material. A large value of PENALTY ensures that the
penetration, of one geometry into another, will be small. Large values,
however, will cause numerical integration difficulties. A value of 1E6 is
appropriate for systems modeled in Kg-mm-sec. For more information
on how to specify this value, see Extended Definition.
Range: PENALTY > 0

POISSON Specifies that a coefficient of restitution method is to be used to model
the normal force. For more information, see the Extended Definition.
26 Adams Solver
RESTITUTION_COEFFICIE The coefficient of restitution models the energy loss during contact. A
NT = r value of zero specifies a perfectly plastic contact between the two
colliding bodies. A value of one specifies a perfectly elastic contact.
There is no energy loss. The coefficient of restitution is a function of the
two materials that are coming into contact. For information on material
types versus commonly used values of the coefficient of restitution, the
Material Contact Properties table.
Range: 0 < RESTITUTION_COEFFICIENT < 1

STICTION_TRANSITION_V Used in the COULOMB_FRICTION model for calculating frictional
ELOCITY = r forces at the contact locations. Adams Solver gradually transitions the
coefficient of friction from MU_DYNAMIC to MU_STATIC as the
slip velocity at the contact point decreases. When the slip velocity is
equal to the value specified for
STICTION_TRANSITION_VELOCITY, the effective coefficient of
friction is set to MU_STATIC. For more details, see the Extended
Definition.
Note: A small value for STICTION_TRANSITION_VELOCITY

causes numerical integrator difficulties. A general rule of
thumb for specifying this value is:
STICTION_TRANSITION_VELOCITY > 5 ERROR
where ERROR is the accuracy requested of the integrator. Its default

value is 1E-3.
Range: 0 < STICTION_TRANSITION_VELOCITY <

FRICTION_TRANSITION_VELOCITY
STIFFNESS=r Specifies a material stiffness that you can use to calculate the normal
force for the impact model.
In general, the higher the STIFFNESS, the more rigid or hard the
bodies in contact are. Also note that the higher the STIFFNESS is, the
harder it is for an integrator to solve through the contact event.
Extended Definition
For more information on the key issues about the CONTACT statement, select one of the following:
 Contact Kinematics
 Outward Normal Definition
 Contact Kinetics
 Contact Normal Force Calculation
 The Augmented Lagrangian Technique
 Contact Friction Force Calculation
CONTACT 27
 Contact Friction Torque Calculation

 Contact Prediction
 Contacts and Analysis Mode Issues
 Contact Geometry Engines
 Contact Parameters for Parts with Small Mass
Contact Kinematics
The CONTACT statement lets you define contact between two geometry objects that you specify in
GRAPHICS entities in an Adams dataset (see the GRAPHICS statement). Adams Solver (FORTRAN) supports:
 Both two- and three-dimensional geometry.
 Two-dimensional or planar contact between POINT, PLANE, CIRCLE, ARC, and CURVE
geometries.
 Three-dimensional contact between CYLINDER, ELLIPSOID, BOX, FRUSTUM, and
EXTERNAL geometries.
Currently, Adams Solver (FORTRAN) does not support contact between two- and three-dimensional
geometries.
The CURVE and the EXTERNAL graphics types are the generic geometry modeling entities. These provide
you with a way to specify arbitrarily complex two- and three-dimensional geometric shapes, respectively. For
both of these entities, the data is in files, which are usually generated by a geometry modeling system. The
CURVE object is specified as a series of x, y, and z points that are a function of an independent curve
parameter. The three-dimensional EXTERNAL object is more complex, and is specified in the format of the
geometry modeling system. Parasolid from Unigraphics is the default geometry modeling system in Adams
Solver (FORTRAN). This is a well recognized, state-of-the-art geometry modeling system that is used in
many CAD systems. Parasolid geometry files typically have the extension xmt_txt.
During a simulation, the first step is to find out if the contact is occurring between the geometry pairs
identified in the CONTACT statements. If there is no contact, there is no force.
If contact exists, the geometry modeling system calculates the location of the individual contact points and
the outward normals to the two geometries at the contact point. Adams Solver (FORTRAN) calculates the
normal and slip velocities of the contact point from this information. Adams Solver (FORTRAN) then uses
the velocities to calculate the contact force at each individual contact.
Outward Normal Definition

The calculation of the outward normal for geometry is important because it defines where the material lies
and, therefore, determines the direction of the contact normal force.
For three-dimensional solids, which are closed by definition, the outward normal is implicit in the geometry
description, and there is no ambiguity in its definition.
For two-dimensional geometries, especially open curves, there is an ambiguity in calculating the outward
normal. Adams Solver (FORTRAN) uses the specified geometry to calculate a default outward normal, but
allows the user to reverse this direction using the IFLIP_NORMAL and JFLIP_NORMAL arguments.
28 Adams Solver
The figure below shows an open curve with eight points defined in the coordinate system of the reference
marker (RM). The z-axis of the RM marker is directed out of the plane of the paper. This defines the bi-
ˆ
normal for the curve, denoted as b.
The curve points are created in the sequence 1 through 8.

ˆ
The tangent at point 3 points towards point 4, and is denoted by t . The outward normals are defined as
follows:
ˆ ˆ ˆ
n = t×b
ˆ
IFLIP_NORMAL and JFLIP_NORMAL simply reverse the direction of n.
IFLIP_NORMAL and JFLIP_NORMAL only apply when a single ID is specified in IGEOM and JGEOM.
When lists of geometries are specified by IGEOM and JGEOM, use IFLIP_GEOMETRY and
JFLIP_GEOMETRY to flip normals.
Contact Kinetics
Two major types of contact are:
 Intermittent contact - Is characterized by contact for short periods of time. It is also known as
impulsive contact. Two geometries approach each other, undergo a collision, and separate as a result
of the contact. The collision results in the generation of an impulse, that affects the momentum of
the colliding bodies. Adams Solver (FORTRAN) develops an estimate of the contact force by
modeling the local deformation behavior of the contacting geometries.
Energy loss during the collision is usually modeled as a damping force that is specified with a
damping coefficient or a coefficient of restitution.
Intermittent contact is characterized by two distinct phases. The first is compression, where the
bodies continue to approach each other even after contact occurs. The kinetic energy of the bodies is
converted to potential and dissipation energy of the compressing contact material. When the entire
kinetic energy is transformed, the potential energy stored in the material reverses the motion of the
contacting bodies. Potential energy is transformed again to dissipation energy and kinetic energy.
This is known as the decompression phase. It is important to note that energy losses due to
dissipation occur in both phases.
CONTACT 29
 Persistent contact - Is characterized by contact for relatively long periods of time. External forces
acting between the two bodies serve to maintain continuous contact. Persistent contact is modeled as
a nonlinear spring-damper, the stiffness modeling the elasticity of the surfaces of contact, and the
damping modeling the dissipation of energy. Two bodies are said to be in persistent contact when
the separation velocity, after a collision event, is close to zero. The bodies, therefore, cannot separate
after the contact.
Contact forces are calculated at each individual contact point. Individual contributions are summed up to
compute the net response of the system to the contact event.
Contact Normal Force Calculation

Two models for normal force calculations are available in Adams Solver (FORTRAN):
 IMPACT function model
 Coefficient of restitution or the POISSON model
Both force models result from a penalty regularization of the normal contact constraints. Penalty
regularization is a modeling technique in mechanics, in which a constraint is enforced mathematically by
applying forces along the gradient of the constraint. The force magnitude is a function of the constraint
violation.
Contact between rigid bodies theoretically requires that the two bodies not penetrate each other. This can be
expressed as a unilateral (inequality) constraint. The contact force is the force associated with enforcing this
constraint. Handling these auxiliary constraint conditions is usually accomplished in one of two ways, either
through introduction of Lagrange multipliers or by penalty regularization.
For contact problems, the latter technique has the advantage of simplicity; no additional equations or
variables are introduced. This is particularly useful when treating intermittent contact and algorithmically
managing active and inactive conditions associated with unilateral constraints. Additionally, a penalty
formulation is easily interpreted from a physical standpoint. For example, the magnitude of the contact
reaction force is equal to the product of material stiffness and penetration between contacting bodies, similar
to a spring force. For these reasons, Adams Solver (FORTRAN) uses a penalty regularization to enforce all
contact constraints. The disadvantage of the penalty regularization, however, is that you are responsible for
setting an appropriate penalty parameter, that is, the material stiffness. Furthermore, a large value for the
material stiffness or penalty parameter can cause integration difficulties.
Before presenting the contact normal force models in Adams Solver (FORTRAN), it is helpful to clearly
define the contact constraints and associated kinematic and kinetic quantities. First, impenetrability of two
approaching bodies is measured with a gap function g, where a positive value of g indicates penetration. Next,
we denote the normal contact force magnitude as Fn, where a positive value indicates a separation force
between the contacting bodies. With this notation in hand, the auxiliary contact constraints are defined as:
30 Adams Solver
g≥0
Fn > 0
F n∗ g = 0
dg
F n∗ ------ = 0
dt
The first three equations reflect:
 The impenetrability constraint
 Separating, normal force constraint
 Requirement that the normal force be nonzero only when contact occurs.
The fourth condition is called the persistency condition and it specifies that the normal force is nonzero only
when the rate of separation between the two bodies is zero. The last constraint is particularly important when
you are interested in energy conservation or energy dissipation.
We obtain the IMPACT force model by replacing the first three auxiliary contact conditions with the
F n = k*(g**e)
where k (stiffness) is a scalar penalty parameter. The penalization becomes exact as k approaches infinity, but
otherwise allows small violation of the impenetrability constraint. It is important to note that ill conditioning
of the governing equations, and ultimately an integrator failure, will result as the stiffness becomes excessively
large. Therefore, you must appropriately select k while preserving the stability of the solution.
You can also approximate the compliance of a body by correlating k to the bodies material and geometric
parameters; however, in doing so, you should recall the earlier remark concerning ill conditioning. In an effort
to incorporate general material constitutive relationships for the contacting bodies, as well as facilitate time
integration, Adams Solver (FORTRAN) augments the previous expression with nonlinear displacement-
dependent, viscous damping terms. The general form of the IMPACT force function is then given by:
dg
F n = k ( *(g**e) + Step (g, 0, 0, d max, c max )*
dt
where:
 g represents the penetration of one geometry into another.
dg
------ is the penetration velocity at the contact point.

dt
 e is a positive real value denoting the force exponent.
 dmax is a positive real value specifying the boundary penetration to apply the maximum damping
coefficient cmax.
CONTACT 31
Clearly, for cmax = 0 and e = 1, the original penalization is recovered. The POISSON force model is derived
dg
from the persistency condition, Fn * ------ = 0. A penalty regularization of the fourth contact constraint yields:
dt
dg
Fn = p * ------
dt
where p is a scalar penalty parameter. Again, the penalization is exact as p -> , which carries the risk of ill
conditioning. In the context of dynamic contact problems, the POISSON model is more consistent with
conservation laws and conserves/dissipates energy appropriately. You can optionally provide a coefficient of
restitution e to model inelastic contact. In this case, the POISSON force model computes the normal contact
force as follows:
dg
F n = p ( ε – 1 )  ------
 dt 
Here ε is coefficient of restitution.

See Learning More about the Contact Detection Algorithm.
The Augmented Lagrangian Technique

When using penalty methods to enforce contact constraints, large penalty (or stiffness) parameters cannot be
used without the risk of making the equations of motion ill conditioned. Ill conditioning manifests itself in
a loss of numerical accuracy during the solution process, causing either slowed convergence or even
divergence. However, softening the penalty parameter compromises the accuracy of the unilateral contact
constraint by permitting excessive penetration between interacting bodies.
To circumvent penalty sensitivity, Adams Solver (FORTRAN) offers an augmented Lagrangian solution
technique. The method involves an iterative process to calculate the unknown contact force. For example, in
the context of the POISSON force model, with k being the iteration counter, the augmented Lagrangian
iterations are:
The above augmented Lagrangian regularization is more general than the POISSON force model presented
earlier, but encompasses a particular case, when the iteration process is executed only once. For subsequent
iterations, the penalty parameter does not need to be very large, because the accumulated force during the
iterative procedure eliminates the resulting error in the contact constraints.
32 Adams Solver
Contact Friction Force Calculation

Adams Solver (FORTRAN) uses a relatively simple velocity-based friction model for contacts. Specifying the
frictional behavior is optional. The figure below shows how the coefficient of friction varies with slip velocity.
In this simple model:
 μ ( –vs ) = μs
 μ ( vs ) = –μs
 μ(0) = 0
 μ ( vd ) = μd
 μ ( –vd ) = –μd
 μ ( v ) = -sign(v). μ d for |v| > vd
 μ ( v ) = -step(|v|,vs, μ s, vd, μ d) sign(v) for vs < |v| < vd
 μ ( v ) = step(v,-vs, μ s ,vs, – μ s ) for -vs < v < vs
where:
CONTACT 33
V: Slip velocity at contact point

vs: STICTION_TRANSITION_VELOCITY
vd: FRICTION_TRANSITION_VELOCITY
μ s : MU_STATIC
μ d : MU_DYNAMIC
Contact Friction Torque Calculation

If Adams Solver detects an angular velocity about the contact normal axis, it will apply a torque proportional
to the friction force. The reason for this is that the contact friction force, by itself, cannot retard relative
rotation between bodies; it can only retard relative translation.
The magnitude of the contact friction torque is given by the formula:
2
T = --- RF
3
2
Where R is the radius of the contact area (which is assumed to be circular). The coefficient --- comes from
3
Marks' Standard Handbook for Mechanical Engineers.
Caution: If you need some other formulation of the friction torque, the only alternative is to write your
own friction force subroutine (CFFSUB). An example is given at the end of this section.
Contact Prediction
Contact is fundamentally a discontinuous event. When two geometries come into contact:
 A large normal force or an impulse is generated.
 The velocities of the bodies change sign.
 The accelerations are almost discontinuous, and have a large spike. This spike represents the impulse
that was generated due to the contact.
The bodies usually separate because of the contact forces or impulses. Numerical integrators assume that the
equations of motion are continuous. A contact event is, therefore, quite hard for an integrator to solve
through. Adams Solver (FORTRAN) contains a contact predictor that predicts the onset of contact and
controls the integrator step size accordingly. The following paragraphs briefly summarize the contact
prediction algorithm.
When Adams Solver (FORTRAN) detects a new contact, it calculates the penetration and penetration
velocity between the two geometries. From these two values, Adams Solver (FORTRAN) estimates a more
refined contact time. Adams Solver (FORTRAN) rejects the current time step and uses the refined step size
to accurately sense the onset of contact.
Furthermore, the integrator order is set to one, so that Adams Solver (FORTRAN) does not use the time
history of the system to predict the future behavior of the system.
This algorithm essentially ensures that:
34 Adams Solver
 The penetration for a new contact is small.

 The integrator is at first order when the contact event occurs.
 The integrator is taking small time steps.
Contacts and Analysis Mode Issues

This section explains how the various analysis modes deal with contact, and provide modeling tips on how
to successfully negotiate difficult contact events.
Contacts and Static Equilibrium
Both the static and quasi-static equilibrium analysis modes use Newton-Raphson (NR) iterations to solve the
nonlinear algebraic equations of force balance. The Jacobian matrix of first partial derivatives and the residue
of the equations of motion are used to set up an iterative scheme that normally converges to the solution.
The Jacobian matrix is a measure of the stiffness matrix of the system. The inverse of the Jacobian is, therefore,
the compliance in the system. The NR algorithm ensures that the system solution moves in the direction of
most compliance (least stiffness). When a contact is active, the stiffness in the direction of the normal force
is high, so the NR algorithm modifies the system states to decrease this force. If a contact is inactive, there is
no stiffness in the direction of increasing contact. The NR algorithm will likely compute a large movement
in this direction, leading to excessive penetration. During the very next iteration, since the contact force may
turn on, a large stiffness is detected in this direction, and the algorithm will change the system to dramatically
reduce the amount of penetration. It is not uncommon for the algorithm to over-react to this stiffness and
move the system sufficiently to deactivate the contact. The algorithm may never be able to resolve this
discontinuity in the system.
Adams Solver (FORTRAN) anticipates this situation and uses a contact-force-sensing mechanism to avoid
excessive contact. You can further enhance this method, however, by choosing the correct equilibrium
parameters.
Here are some modeling tips for aiding equilibrium (static) analysis (for more information on equilibrium
analysis, see the EQUILIBRIUM statement):
 Use EQUILIBRIUM/DYNAMICS to specify that a quasi-dynamic algorithm is to be used to find
static equilibrium. For more information, see the EQUILIBRIUM statement.
 If possible, make sure that all contacts are active, and each contact penetration is small. This will
ensure that the contact forces are small, and the system is aware of the contacts.
 Set TLIMIT and ALIMIT small enough so gross contact violations are avoided.
 Increase the maximum number of iterations, MAXIT, so that you can get to convergence in spite of
the small values for TLIMIT and ALIMIT.
 Avoid neutral equilibrium situations. If you know that your model has neutral equilibrium
situations, increase STABILITY (try STABILITY = 0.1). Also increase MAXIT, the maximum
number of iterations you will allow to obtain convergence.
Contacts and Kinematics
In kinematically determinate systems, the system configuration is completely defined by the system
constraints (JOINTs, JPRIMs, COUPLERs, and so on) and MOTIONs. The contact penetration and force
CONTACT 35
at each configuration can only be obtained as outputs of this analysis. CONTACTS will not be able to
determine the configuration of the system.
Contacts and Linear Analysis
If contacts are active at the configuration at which linearization is performed, there will be a high stiffness in
the direction of the normal force. Therefore, you will see a large frequency corresponding to this stiffness. If
contacts are inactive, they will have no effect on the eigenvalues of the system.
Contacts and Dynamics
Default Corrector for Dynamics
The modified corrector (Integrator/Corrector=Modified) is the default for all models that contain
CONTACTS.
Handling solution difficulties:
Sometimes, you may encounter repeated corrector failures when a contact occurs. This is usually caused by:
 Too large a value for STIFFNESS (for IMPACT) or PENALTY (for POISSON).
 Too tight of an integration error.
 Too small of a value for FRICTION_TRANSITION_VELOCITY and
STICTION_TRANSITION_VELOCITY.
 Too large of a value for MU_STATIC and MU_DYNAMIC.
The following modeling tips will help dynamic analyses. For more information on integrator settings, see the
INTEGRATOR statement.
 Reduce STIFFNESS or PENALTY by a factor of 10 and see if the solver can solve through the
contact.
 Increase the integration error tolerance using INTEGRATOR/ERROR=value. A larger integrator
error results in a looser corrector convergence criterion.
 Reduce damping. This decreases the duration of the contact and can help simulations.
 Set the maximum integration order to 2, using INTEGRATOR/KMAX=2. Lower-order integrators
are more stable than higher-order integrators.
 Set HMAX to a small value to prevent the integrator from taking large steps.
 Turn on AUGMENTED_LAGRANGIAN to minimize the penetration for the reduced stiffness or
penalty if you are using the Poisson method for normal force calculations. Remember to decrease
PENALTY by a factor of 10 to 100 when you use the AUGMENTED_LAGRANGIAN.
 Use the SI2 formulation. The corrector for this formulation is more stable than standard GSTIFF,
and may solve the problem where the standard GSTIFF failed.
 Always run a model without contact friction first, and refine the functioning model by adding
friction later.
 If the addition of frictional forces causes numerical difficulties or simulation slowdowns, gradually
increase the values for STICTION_TRANSITION_VELOCITY and
FRICTION_TRANSITION_VELOCITY. Also reduce the coefficients of friction, which usually
helps the integrator.
36 Adams Solver
Contact Geometry Engines

Adams Solver (FORTRAN) has two different geometry engines that can be used for three-dimensional
contact detection. The first geometry engine is based on Parasolid and it is fundamentally the same engine
that was available in ADAMS 11.0 and ADAMS 12.0. Currently, Adams Solver (FORTRAN) supports
Parasolid version 28.1.238. The second geometry engine is based on RAPID a polygon based interference
detection package developed at the University of North Carolina. Currently, Adams Solver (FORTRAN)
supports RAPID version 2.01.
The RAPID geometry engine was added to Adams Solver (FORTRAN) because, for many models, it can
substantially reduce the simulation time. However, because it is polygon based, it is not always as accurate as
the Parasolid geometry engine. Parasolid is an exact boundary-representation geometric modeler, which
makes it highly accurate, but not as fast as a polygon-based engine. For these reasons, it was decided to include
both geometry engines in Adams Solver (FORTRAN) and give you the capability of switching from one to
the other.
The RAPID geometry engine is the default geometry in this release of Adams Solver (FORTRAN). To switch
to the Parasolid geometry engine, you must set the PREFERENCES statement.
The RAPID geometry engine has another environment variable, MDI_FACETING_TOLERANCE, which
controls the faceting of 3D geometry. Faceting is the process of approximating the surface of an object by a
mesh of triangles. All polygon-based geometry engines used faceted representations of surfaces. The default
value of MDI_FACETING_TOLERANCE is 300.0028. Increasing this value will result in a finer mesh of
triangles, which gives a more accurate representation of surfaces which are curved. However, increasing the
tolerance also increases the memory requirements of the geometry engine and adds to the computational
overhead, which makes it run slower. Setting the faceting tolerance to values greater than 1000 is not
recommended. Values smaller than 300.0028 will give negligible performance improvements. The value
specified for MDI_FACETING_TOLERANCE only applies to geometry read from a Parasolid file. All
native geometry (ellipsoid, cylinder, box, frustum, torus, surface of revolution, and extrusion) is tessellated
with a fixed tolerance when MDI_FACETING_TOLERANCE is specified. Stl and shl files have fixed
faceting that cannot be changed.
CONTACT 37
Tip: If you notice that energy is dissipated during contact events, note the following:
 Impact method - A three-dimensional contact with zero damping can exhibit some
dissipation of energy during the impact. The dissipation is due to the numerics of the
integration algorithm. To reduce the dissipation, reduce the time step or tighten
(decrease) the error tolerance.
 Restitution method - A three-dimensional contact with coefficient of restitution set
to one should conserve energy. If you notice some dissipation, try activating the
Augmented Lagrangian or increasing the PENALTY argument. Recall that the larger
the PENALTY argument, the more exact the contact constraint will be enforced. In
the case of intermittent contact and a restitution coefficient set to one, a larger penalty
parameter more exactly enforces the conservation of momentum during the contact
event.
The PENALTY argument is analogous to the stiffness in the IMPACT function. The
larger the stiffness, the smaller the penetration. Parts with low mass (less than 0.01 kg)
may need the PENALTY argument reduced by several orders of magnitude to avoid
integrator failures.
38 Adams Solver
Caution:  An artificially low value of stiffness or penalty will not generate the necessary contact
forces. You may see a loss of energy when none is expected.
 If you find that your model response changes as the number of output steps is
modified, use INTEGRATOR/HMAX=value to control the integrator step-size and
the quality of the solution.
 Adams View will do this conversion for you if you change the units under Settings.
 Example:
k = 3800 N/mm
e = 2.0
Contact Parameters for Parts with Small Mass

This document gives a method for estimating contact stiffness and damping parameters in Adams for parts
with small mass.
The default contact stiffness and damping coefficients in Adams are:
 Stiffness = 1.0E+05 N/mm
 Damping = 10.0 N-s/mm
These coefficients were chosen for parts whose mass is on the order of 1.0 Kg and which are made of steel.
Call this part the "default part".
For parts with small mass these coefficients should be reduced to optimize Adams Solver performance and to
minimize the chance of simulation failure.
In the following discussion, assume that:
 M = Part mass
CONTACT 39
 R = Average dimension (size) of part (order of magnitude is sufficient)

 g = gravitational acceleration
 G = G force (1 G = M*g)
Since steel has a density of about 8000 Kg/m^3, the default part would have a radius of about 30 mm
(assuming it is spherical).
The expression for the contact spring force is:
e
F = Kx
where:
 F = Contact force
 K = Contact Stiffness
 x = penetration
 e = exponent (default value in Adams is 2.2)
We would like to calculate the contact force in G's on the default part when its penetration is 0.1% of its
radius:
We choose a penetration of 0.1% because most well behaved contact models do not exceed this amount.
To compute the appropriate stiffness for a small part, we specify that it should experience the same G force
when it has a penetration of 0.1% of its radius.
Assume the following small part properties:
 M = 4.0e-06 Kg
 R = 1 mm
 e = 2.2
We need to solve the following equation for K:
5*M*g = K*(0.001)^2.2
We get:
K ≅ 800N ⁄ mm
When both parts in contact are moving, the reduced mass may give a more accurate estimate of stiffness.
The reduced mass is given by:
M1 M2
M = ---------------------
M1 + M2
The contact damping coefficient for small parts should be calculated using critical damping.
40 Adams Solver
The expression for critical damping is:
C = 2 KM
For the small part given above, the damping is:
The values for stiffness and damping are order of magnitude estimates. They can be tuned further (via
experiment) to refine performance.
Examples
The example below demonstrates contact between two generic three-dimensional geometries.
star_geneva.xmt_txt is a geometry file that was generated by Parasolid. Adams View or any CAD package
using Parasolid as its geometry package can generate this file. It contains two geometries, SOLID4 and
SOLID3. Contact is to be defined between these two geometries.
The .adm file portion for this example is as follows:
GRAPHICS/11,
, EXTERNAL,
, ELEMENT = SOLID4,
, RM = 30027
!
GRAPHICS/12,
, EXTERNAL,
, ELEMENT = SOLID3,
, RM = 30028
An impact-type contact would be defined as:
CONTACT/1,
, IGEOM=11,
, JGEOM=12,
, IMPACT,
, STIFFNESS = 1E6,
, DAMPING = 10,
, DMAX = 0.1,
, EXPONENT = 2.2
APOISSON-type contact would be defined as:
CONTACT/1,
, IGEOM=11,
, JGEOM=12,
, POISSON,
, PENALTY = 1E5,
, RESTITUTION_COEFFICIENT = 0.6
CONTACT 41
Below is an example of lists of geometry. Geometries 11 and 12 must belong to one part. Geometries 13, 14,
and 15 must all be on one part. Geometries 12, 13, and 15 are flipped.
CONTACT/1,
, IGEOM = 11, 12
, JGEOM = 13, 14, 15
, IFLIP_GEOMETRY = 12
, JFLIP_GEOMETRY = 13, 15
, IMPACT,
, STIFFNESS = 1E6,
, DAMPING = 10,
, DMAX = 0.1,
, EXPONENT = 2.2
Below is an example of user-written subroutines in contacts. The normal force subroutine (CNFSUB) and
the friction force subroutine (CFFSUB) are in the same library (cnforc1).
CONTACT/1
, IGEOM = 7
, JGEOM = 6
, NORMAL_ROUTINE = cnforc1::CNFSUB
, FRICTION_ROUTINE = cnforc1::CFFSUB
, NORMAL_FUNC = USER(1.0E+004, 1.0, 1000, 0.1)/
, FRICTION_FUNC = USER(0.37, 0.30, 10.0, 10)
The figure below shows a representation of the star_geneva mechanism.
star_geneva Mechanism
The example below demonstrates how to specify contact between two two-dimensional geometries:
42 Adams Solver

GRAPHICS/11, CURVE, RM = 30027, CID = 147
!
GRAPHICS/12, CIRCLE, CM = 30028, RADIUS = 1.36
A POISSON-type contact with Augmented Lagrangian iterations, and no energy dissipation would be
defined as:
CONTACT/1,
, IGEOM=11,
, JGEOM=12,
, POISSON,
, PENALTY = 1E5,
, RESTITUTION_COEFFICIENT = 1.0,
, AUGMENTED_LAGRANGIAN_FORMULATION
CURVE 43
CURVE
The CURVE statement defines a three-dimensional parametric curve that you can reference using PTCV,
CVCV, GRAPHICS statements, and function expressions.
Format
Arguments
CLOSED Specifies that the curve meets at the ends. If you specify
CURVE_POINTS, Adams Solver (FORTRAN) attempts to compute a
curve that meets at the ends and has continuous first and second
derivatives across the closure. If you specify FUNCTION, you must
ensure that the defined curve meets at the ends and has continuous first
and second derivatives across the closure. If the curve is closed, the first
and last control or curve points must be the same. During a simulation,
Adams Solver (FORTRAN) moves a PTCV or CVCV contact point
across the closure, if necessary.
CURVE_POINTS Specifies that the MATRIX contains data points on the curve.
FUNCTION=USER Defines and passes constants to CURSUB, the user-written subroutine
(r1[,...,r30])/ that computes the curve coordinates and derivatives (see the CURSUB
subroutine). The FUNCTION argument must be either the last
argument in the CURVE statement or it must be followed by a
backslash (\).
MATRIX=id Specifies a MATRIX statement that contains data for a curve. The
matrix contains the x, y, and z coordinates of the curve points. The
matrix should have a row for each point and three columns containing
the x-, y-, and z-coordinates of the points. You must supply at least four
curve points. The first and last points must be the same for a closed
curve.
44 Adams Solver
MAXPAR=r Specifies the maximum value of the curve parameter for a user-written
curve. Adams Solver (FORTRAN) uses this value when drawing a curve
graphic. The maximum parameter value is always 1.0 for curves you
define using CURVE_POINTS.
Default: 1.0
MINPAR=r Specifies the minimum value of the curve parameter for a user-written
curve. Adams Solver (FORTRAN) uses this value when drawing a curve
graphic. The minimum parameter value is always -1.0 for curves you
define using CURVE_POINTS.
Default: -1.0
OPEN Specifies that the curve does not meet at the ends. Adams Solver
(FORTRAN) does not allow a PTCV or CVCV contact point to move
beyond the end of the curve.
ORDER Specifies the order of the B-spline interpolating the curve. A
B-spline of order K means that it is made up of piecewise polynomial
segments of degree K-1. A cubic B-spline is order 4. A B-spline of order
2 is called a polyline because it is made up of straight line segments
between each of the CURVE_POINTS. It is important to note that a B-
spline of order K will have K-2 continuous derivatives. The
discontinuities appear where the polynomial segments join together.
Increasing the order of the B-spline arbitrarily may introduce unwanted
oscillation into the curve.
Default: 4
Range: ORDER > 2
ROUTINE=libname::subname Specifies an alternative library and name for the user subroutine CURSUB.
Extended Definition
The x, y, and z coordinates of a point on a parametric curve are functions of an independent parameter, u. As
u varies from its minimum to maximum value, the functions x(u), y(u), and z(u) sweep out points on the
curve. A simple example of a parametric curve is a helix defined by the following equations and illustrated in
the figure below:
x = cos(u)
y = sin(u)
z = u
Example of a Parametric Curve
CURVE 45
Adams Solver (FORTRAN) lets you create curves in two ways:

 Enter curve points to which Adams Solver (FORTRAN) matches a curve.
 Write a CURSUB evaluation subroutine with which Adams Solver (FORTRAN) computes curve
coordinates and derivatives.
A uniform B-spline is a piecewise polynomial spline used in many CAD (computer-aided design)
applications. A B-spline is defined by control points that form a polygon in space and a knot vector. Adams
Solver (FORTRAN) uses a non-uniform knot vector with quadruple multiplicity at both ends. The curve
starts at the first control point and ends at the last. In between, it is attracted to, but does not necessarily hit,
the intermediate control points. Adams Solver (FORTRAN) parameterizes a B-Spline starting at -1 and
ending at +1. The figure below shows a set of control points and the B-spline curve it defines.
Control Points and the Resulting B-Spline
46 Adams Solver
Adams Solver (FORTRAN) computes the control points internally from the curve points.
To use a different type of curve, or to model an analytically-defined curve such as a helix, you can write a
CURSUB user-written subroutine. When providing a CURSUB, you can also specify MINPAR and
MAXPAR to define the limits of the curve. These default to -1 and +1, respectively.
A curve is OPEN or CLOSED. A CLOSED curve meets at the ends, connecting the curve at minimum and
maximum parameter values. Adams Solver (FORTRAN) automatically moves a PTCV or CVCV contact
point across the closure of a CLOSED curve, if needed. For instance, you can model a cam profile as a
CLOSED curve, and Adams Solver (FORTRAN) allows the follower to move across the closure as the cam
rotates.
Caution: Adams Solver (FORTRAN) applies a force to prevent a PTCV or CVCV contact point from
moving off the end of an open curve. For an open curve that is referenced by a PTCV or
CVCV constraint, be sure to define an expected range of contact.
Examples
CURVE/5, OPEN, CURVE_POINTS, MATRIX=2
This statement creates an open curve using the curve point coordinates in MATRIX/2. Adams Solver
(FORTRAN) computes a B-spline curve to fit the points.
CURVE/7, CLOSED, CURVE_POINTS, MATRIX=1, ORDER=2
This statement creates a closed curve of order 2 (polyline) using the curve point coordinates in MATRIX/1.
Adams Solver (FORTRAN) computes a B-spline curve to fit the points.
Applications
The PTCV, CVCV, and GRAPHICS statements reference the CURVE statement:
 The PTCV uses a curve to define a point-curve constraint.
 The CVCV statement uses two curves to define a curve-curve constraint.
 The GRAPHICS statement generates a graphic depicting the curve.
In each case, you must specify a reference marker that identifies the part to which the curve attaches and the
coordinate system to which Adams Solver (FORTRAN) applies the curve coordinates. You can also reference
a curve in a function expression, much like the cubic or Akima splines (see the CURVE function).
COUPLER 47
COUPLER
A COUPLER statement relates the translational and/or the rotational motion of two or three joints.
Format
Arguments
FUNCTION=USER(r1[,...,r30]) Specifies up to thirty user-defined constants passed to the externally-

defined subroutine COUSUB, COUXX, COUXX2. These subroutines
define the coupler displacement constraint function, and provide its
first and second order partials, respectively (see the COUSUB, COUXX,
COUXX2 subroutines).
JOINTS=id1,id2[,id3] Specifies the identifiers of as many as three joints whose translational
and/or rotational displacements are to be coupled. You can only specify
identifiers of translational, revolute, and cylindrical joints.
48 Adams Solver
ROUTINE=lib1::cou1, Specifies alternative library and subroutine names for the user
lib2::cou2, lib3::cou3 subroutines COUSUB, COUXX, and COUXX2 respectively.

SCALES=[r1,]r2[,r3] Defines the relative motion of the joints specified with JOINTS. Adams
Solver (FORTRAN) uses the values in the SCALES argument to form
the equation:
(r1 * q1) + (r2 * q2) + (r3 * q3) = 0,
where r1, r2, and r3 are the scale factors for the three joints, and for each
joint, q1, q2, and q3 are the translational or rotational displacements of
the joint I marker with respect to the J marker. Suppose two joints are
being coupled, and SCALES=1,-2. The equation that relates the two
joints is:
(1 * q1) + (-2 * q2) = 0
or
q1 = 2 * q2.
The displacement (q1) of the I marker with respect to the J marker in

the first joint is twice that of the displacement (q2) of the I marker with
respect to the J marker in the second joint; the two displacements have
the same sign. If two joints are specified in the JOINTS argument, r2
must be specified. Adams Solver (FORTRAN) assumes r2 if only one
value is specified and uses the default value of 1 for r1.
If three joints are specified in the JOINT argument, you should either
specify three scale values r1,r2, and r3, or provide only two scale values.
In the latter case, the two values are assigned by the Solver to r2 and r3
(in this order) while r1 is given the default value 1.0.
Defaults: r1 (1); r2, r3 (none)

Range: non-zero real numbers
COUPLER 49
Indicates whether joints transfer translational or rotational motion. If

the coupler includes no cylindrical joints, do not use TYPE. However,
T  T  T 
TYPE =       if the coupler includes one or more cylindrical joints, TYPE must be
R  R  R  used. In that case, input T (translational) or R (rotational) for each joint
specified with JOINTS, even the translational or revolute joints.
Because Adams Solver assumes that translational joints transfer
translational motion and that revolute joints transfer rotational motion,
Adams Solver ignores T’s and R’s for translational and revolute joints;
they are place holders only. But because a cylindrical joint permits either
translational or rotational motion, Adams Solver needs a T or R for each
cylindrical joint to determine the type of motion on which the coupler
acts.
Extended Definition
The COUPLER statement relates the translational and/or rotational motion of two or three joints. This
statement lets you deliver or couple motion from one area of a mechanism to another. Components whose
behavior might be approximated with this statement are combinations of hydraulic generators, motors, and
pistons, and include flexible, rotational, transmission cables.
50 Adams Solver
Tip:  To measure translational motion, Adams Solver (FORTRAN) finds the displacement
of the I marker origin with respect to the J marker origin along the J marker z-axis.
Positive translations are along the positive z-axis of J, and negative translations are
along its negative z-axis.
 To measure rotational motion, Adams Solver (FORTRAN) finds the displacement of
the x-axis of the I marker with respect to the x-axis of the J marker about the common
z-axis of the I and the J markers. To determine the positive sense of rotation, apply the
right-hand rule to the z-axis.
 The COUPLER can relate any combination of translational and rotational motions.
A two-joint COUPLER, for example, can relate translational motion to translational
motion, rotational to rotational, or translational to rotational.
 The COUPLER is a constraint between joint degrees of freedom. Therefore, it
models only the reaction forces that are along or about the degrees of freedom that are
being coupled.
You can model a pair of mating spur gears as a COUPLER between two
REVOLUTE joints. If (I1, J1) are the I and J markers of the first joint and (I2, J2) are
the I and J markers of the second joint, the COUPLER constraint is:
AZ(I1,J1) * scale_1 + AZ(I2,J2) * scale_2 = 0
where scale_1 and scale_2 are the radii of the two gears.
The reaction forces generated by the COUPLER are the torques at the two joints
required to maintain the constraint shown above. The reaction on the first joint is the
torque about the z-axis of marker J1. The reaction on the second joint is the torque
about the z-axis of marker J2. You can compute the tooth force from these torques,
but Adams Solver (FORTRAN) does not explicitly solve for them.
You can also model a rack and pinion gear as a COUPLER relating the rotation in a
REVOLUTE joint, with the translation in a TRANSLATIONAL joint. If (I1, J1) are
the I and J markers of the REVOLUTE joint and (I2, J2) are the I and J markers of
the TRANSLATIONAL joint, the COUPLER constraint is:
AZ(I1,J1) * scale_1 + DZ(I2,J2,J2) * scale_2 = 0
where scale_1 is the pinion radius, and scale_2=1.
The COUPLER reaction on the REVOLUTE joint is a torque about the z-axis of
Marker J1, and the reaction on the TRANSLATIONAL joint is a force along the z-
axis of Marker J2.
COUPLER 51
Caution:  When measuring rotational motions in couplers, Adams Solver (FORTRAN) assumes
radians rather than degrees. Use a D after the value to indicate that the units are
degrees.
 When measuring translational motions in couplers, Adams Solver (FORTRAN) uses
the system units of translation.
 If one or more cylindrical joints for the coupler is specified, Adams Solver
(FORTRAN) requires you to input one or more entries for the TYPE argument,
depending on the order of the cylindrical joint(s) in the JOINTS argument list.
Adams Solver (FORTRAN) must have a type entry for every cylindrical joint and a
place holder entry for every joint entered before a cylindrical joint on the JOINTS
argument.
Examples
COUPLER/01, JOINTS=4,6, TYPE=T:R, SCALES=90D, -1
This COUPLER statement relates the translational motion at Joint 4 to the rotational motion at Joint 6. Joint
4 is either a translational or cylindrical joint, and Joint 6 is either a revolute or cylindrical joint. The SCALES
argument indicates the relationship:
(90D)q1 - q2 = 0
or
(90D)q1 = q2.
In other words, when q1 is a positive translation of one system unit, q2 is a positive rotation of 90 degrees.
Internal to Adams Solver (FORTRAN), all values entered in degrees are converted to radians for calculation
purposes. The figure below shows a coupler.
Coupler

52 Adams Solver
CVCV
The CVCV statement defines a curve-to-curve constraint that restricts a planar curve on one part that is to
be in contact with, and tangent to, a planar curve on a second part. The curves must lie in the same plane,
but the parts to which they are attached may undergo three-dimensional motion.
Format
CVCV 53
Arguments
ICURVE=id Specifies the identifier of a CURVE statement from which Adams Solver constructs the first
curve. The IRM marker specifies the coordinate system in which the x, y, z coordinates of
ICURVE are specified. The curve is attached rigidly to the part containing the IRM marker.
The z component of the curve must be zero. As a result, the curve lies in the x-y plane of the
IRM marker.
IDISP=x,y,z Specifies the initial point of contact on the first curve. Adams Solver (FORTRAN) uses a
point on the curve nearest to that specified if the point specified is not exactly on the curve.
By default, the contact point is specified in the IRM marker coordinate system. You may
supply the IICM argument and enter IDISP in IICM marker coordinates if another
coordinate system is more convenient.
Adams Solver (FORTRAN) assembles the system with the contact at the specified point on
the curve if you supply IDISP. Adams Solver (FORTRAN) assumes the initial contact is at
the point on the first curve closest to the second curve at the input configuration if you do
not supply IDISP. In this case, Adams Solver (FORTRAN) may adjust that contact point to
maintain other part or constraint initial conditions.
IFLOAT=id Specifies the identifier of a floating marker. Adams Solver (FORTRAN) positions the origin
of the IFLOAT marker to be at the instantaneous point of contact on the first curve, which
is also the global position of the JFLOAT marker on the second curve. Adams Solver
(FORTRAN) orients the IFLOAT marker so that its x-axis is along the tangent at the
instantaneous contact point, its y-axis is along the instantaneous normal, and its z-axis along
the resultant binormal. For a CVCV constraint, the binormal of ICURVE is always parallel
to the z-axis of the IRM marker. The IFLOAT and IRM markers must lie on the same part.
IICM=id Specifies the identifier of a fixed marker defining the coordinate system in which the values
for IDISP are defined. The IICM marker must be on the same part as the IRM marker.
Default: IRM marker

IRM=id Specifies the identifier of a fixed marker on the part containing ICURVE. The IRM marker
identifies not only the part that the ICURVE is attached to, but also identifies the coordinate
system in which the coordinates of ICURVE are specified. Adams Solver (FORTRAN)
constructs the ICURVE in the x-y plane of the IRM marker coordinate system. The IFLOAT
and IRM markers must lie on the same part.
54 Adams Solver
IVEL=r Specifies the magnitude of the initial velocity of the contact point relative to the part
containing ICURVE. This is the speed at which the contact point is initially moving tangent
to the curve. IVEL is negative if the contact point is moving towards the start of the curve,
positive if the contact point is moving toward the end of the curve, or zero if the contact
Adams Solver (FORTRAN) gives the contact point the specified initial speed along the first
curve if you supply IVEL. Adams Solver (FORTRAN) assumes the initial velocity is zero if
you do not supply IVEL, but may adjust the velocity to maintain other part or constraint
initial conditions.
Default: 0
JCURVE=id Specifies the identifier of a CURVE statement from which Adams Solver (FORTRAN)
constructs the second curve. The JRM marker specifies the coordinate system in which the
x, y, z coordinates of JCURVE are specified. The curve is attached rigidly to the part
containing the JRM marker. The z component of the CURVE must be zero. As a result, the
curve lies in the x-y plane of the JRM marker.
JDISP=x,y,z Specifies the initial point of contact on the second curve. Adams Solver (FORTRAN) uses a
point on the curve nearest to that specified if the point specified is not exactly on the curve.
By default, the contact point is specified in the JRM marker coordinate system. You may
supply the JICM argument and enter JDISP in JICM marker coordinates if another
coordinate system is more convenient.
Adams Solver (FORTRAN) assembles the system with the contact at the specified point on
the curve if you supply JDISP. Adams Solver (FORTRAN) assumes the initial contact is at a
point on the second curve closest to ICURVE in the input configuration if you do not supply
JDISP. In this case, Adams Solver (FORTRAN) may adjust that contact point to maintain
other part or constraint initial conditions.
Default: Closest point to ICURVE in the input configuration

JFLOAT=id Specifies the identifier of a floating marker. Adams Solver (FORTRAN) positions the origin
of the JFLOAT marker at the instantaneous point of contact on the second curve, which is
also the position of the IFLOAT marker on the first curve. Adams Solver (FORTRAN)
orients the JFLOAT marker so that its x-axis is along the tangent at the instantaneous contact
point, its y-axis is along the instantaneous normal, and its z-axis along the resultant bi-
normal. For a CVCV constraint, the bi-normal of JCURVE is always parallel to the z-axis of
the JRM marker. The JFLOAT and JRM markers must lie on the same part.
CVCV 55
JICM=id Specifies the identifier of a fixed marker defining the coordinate system in which the values
for JDISP are defined. The JICM marker must be on the same part as the JRM marker.
Default: JRM marker

JRM=id Specifies the identifier of a fixed marker on the part containing JCURVE. The JRM marker
identifies not only the part the JCURVE is attached to, but also the coordinate system in
which the coordinates of JCURVE are specified. Adams Solver (FORTRAN) constructs
JCURVE in the x-y plane of the JRM marker coordinate system. The JFLOAT and JRM
markers must lie on the same part.
JVEL=r Specifies the magnitude of the initial velocity of the contact point relative to the part
containing JCURVE. This is the speed at which the contact point is initially moving tangent
to the curve. JVEL is negative if the contact point is moving towards the start of the curve,
positive if the contact point is moving toward the end of the curve, and zero if the contact
Adams Solver (FORTRAN) gives the contact point the specified initial speed along the
second curve if you supply JVEL. Adams Solver (FORTRAN) assumes the initial velocity is
zero if you do not supply JVEL, but may adjust that velocity to maintain other part or
Default: 0
Extended Definition
The CVCV statement defines a curve-to-curve constraint that restricts a planar curve on one part to be in
contact with, and tangent to, a planar curve on a second part. The curves must lie in parallel planes.
Adams Solver (FORTRAN) constructs the first curve from the ICURVE curve and IRM marker, and the
second curve from the JCURVE curve and JRM marker. In both cases, the CURVE statement (ICURVE or
JCURVE) defines x and y coordinates along the curve as a function of an independent parameter (u). The z
coordinates of the curves must be zero. The reference marker (IRM or JRM) defines the part on which the
constraining curve is attached and the coordinate system in which Adams Solver (FORTRAN) applies the
coordinates from the CURVE statement.
Both ICURVE and JCURVE may be open or closed curves, defined analytically or as a set of discrete data
points. Figure 1 below shows a curve-to-curve constraint.
A CVCV statement removes two degrees-of-freedom from the system. Adams Solver restricts the motion of
the parts such that the curves are always in contact and the curves are tangent at the contact point. The first
curve may slide or roll on the second, but may not move perpendicular to the curve tangents at the contact.
Figure 1 Curve-To-Curve Constraint

56 Adams Solver
Tip: More than one CVCV statement can reference the same CURVE statement. You can enter one
CURVE statement if the mechanism contains several similar contacts and use it with several
CVCV constraints, each with a different IRM and JRM marker.
CVCV 57
Caution:  Adams Solver (FORTRAN) requires that the curves lie in the same plane, however,
this is not enforced by the CVCV statement. The CVCV statement simply enforces
that the two curves remain in contact. You must build the model so that the curves
are held in the same plane.
 IVEL and JVEL are specified relative to the body coordinate system (BCS) of the part
containing the IRM or JRM marker, respectively. In other words, IVEL is the speed
of the contact point relative to the part containing the first curve. This means if the
contact point is not moving relative to part, but the first curve is moving relative to
the ground, then IVEL is still nonzero.
 Adams Solver (FORTRAN) applies a force to prevent the contact point from moving
of the end of an open curve. For this reason, you may want to specify an open curve
that extends beyond the range of actual curve travel on both ends of the curve.
 The initial conditions arguments, IDISP, JDISP, IVEL, and JVEL, impose
constraints that are active only during an initial conditions analysis. Adams Solver
(FORTRAN) does not impose these initial conditions during subsequent analyses.
 For a kinematic analysis, the initial conditions are redundant. Do not use the IDISP,
JDISP, IVEL, or JVEL arguments on the CVCV statements for systems with zero
degrees of freedom. Adams Solver (FORTRAN) requires that there be a unique
contact point in the vicinity of the IFLOAT and JFLOAT markers during simulation.
If there is more than one contact point, Adams Solver may be unable to find the
correct contact point or may even jump from one contact point to the next.
One way to ensure that contact points are unique is to specify curve shapes that are
convex. Figure 2 below depicts two curves, the first is convex and the second
nonconvex. Note that for a convex curve, any line segment connecting two arbitrary
points on the curve lies in the domain of the curve (that is, it does not intersect the
curve). The same is not true for the nonconvex curve.
 It is easy to accidently over-constrain a system using the CVCV constraint. For
cylindrical joint, not a revolute joint. If the follower is held by a translational joint and
the cam by a cylindrical joint, the CVCV constraint between the follower and cam
prevents the cam from translating along the axis of rotation (that is, the axis of the
cylindrical joint). A revolute joint would add a redundant constraint in that direction.
Figure 2 Convex and Nonconvex Curves

58 Adams Solver
Examples
CVCV/20, IFLOAT=402, ICURVE=11, IRM=401, JFLOAT=502,
, JCURVE=12, JRM=501
This statement creates a curve-curve constraint between a curve on the part containing Markers 401 and 402
and a curve on the part containing Markers 501 and 502. CURVE/11 defines the first curve in the coordinate
system of Marker 401. CURVE/12 defines the second curve in the coordinate system of Marker 501.
Applications
The CVCV statement models one curve rolling or slipping along another, such as in a cam-follower
mechanism. Figure 3 illustrates a cam follower.
Adams Solver (FORTRAN) automatically moves the contact across the closure as needed when a closed curve
is specified in the CURVE statement. This means that the cam may rotate as many times as needed during
the simulation.
A point-to-curve constraint, PTCV statement, can be used if the follower is small and sharp enough to be
considered a point.
The curves always maintain contact, even when the dynamics of the system would actually lift one curve off
the other, because CVCV is a geometric spatial constraint. You can examine the constraint forces to determine
The CVCV statement models only one contact. Therefore, if the curves have contact at more than one point
you must enter a CVCV statement for each contact, each with a displacement initial condition (IDISP and
JDISP) near the appropriate point.
Figure 3 Cam-Follower Mechanism

CVCV 59

60 Adams Solver
DEBUG
The DEBUG statement outputs data that helps you debug a simulation.
Format
DEBUG 61
Arguments
62 Adams Solver
DOF Prints a degree-of-freedom table in the tabular output file. This table tells whether or not each of the six
components of motion (that is, translation along the x-axis, y-axis, and z-axis and rotation about the x-
axis, y-axis, and z-axis) is constrained for each part center of mass relative to the origin of the ground
coordinate system (GCS). These are the degrees of freedom as input.
Default: Off
DUMP Writes the internal representation of a dataset in the Tabular Output file after Adams Solver (FORTRAN)
reads and checks the input. This facility essentially maps the equations and variables in the system and
provides their numeric codes.
Default: Off
DEBUG 63
monitor the simulation process and locate the source of the error if there is a problem. Each step consists
of two phases: 1) a forward step in time (the predictor for dynamics) and 2) the solution of the equations
of motion (the corrector for dynamics). For the first phase, Adams Solver (FORTRAN) prints three or
four pieces of information. The information includes:
measure of how hard Adams Solver (FORTRAN) is working.
Solver (FORTRAN) uses to predict the solution at the end of the integration step.
For the second phase, Adams Solver (FORTRAN) prints out the cumulative number of iterations and a
table of information about the iterations. The cumulative number of iterations is a running count of the
computations Adams Solver (FORTRAN) is performing. The table contains information about the largest
equation imbalance (error) and maximum variable change for each iteration. For each iteration, Adams
Solver (FORTRAN) prints out seven or eight pieces of the following information:
Adams Solver (C++) converges to a solution or exceeds the maximum allowable number of
iterations.
 The absolute value of the largest equation residual error. Each equation should have an error
value close to zero. This number is an indicator of how far Adams Solver (FORTRAN) is from a
solution. This number should decrease after every iteration.
change variables very much. This number is an indicator of how aggressive Adams Solver
(FORTRAN) needs to change variables to approach a solution. This number should decrease
after every iteration.
 If Adams Solver (FORTRAN) has updated the Jacobian, YES appears under the new Jacobian
header.
Default: Off
JMDUMP Dumps the Jacobian matrix at each iteration.
Default: Off
64 Adams Solver
REQDUM Dumps the REQUEST and MREQUEST statement output at each iteration.
P
Default: Off
RHSDUM Dumps the YY array (state vector), RHS array (error terms), and DELTA array (increment to state vector)
P at each iteration.
Default: Off
Solver (FORTRAN) sends each diagnostic, explanations, and possible remedies (when available). When
you do not include the VERBOSE argument, Adams Solver (FORTRAN) outputs only the basic error
messages to the screen. In either case, Adams Solver (FORTRAN) outputs the information to the Message
file.
Default: Off
MATLAB When specified in conjunction with the RHSDUMP or JMDUMP flags it changes the output format to
be such that the debug information can be easily imported into Matlab. Importing for example the
Caution: An indiscriminate use of the arguments JMDUMP and RHSDUMP can result in an extremely
large tabular output file. If a dataset needs to be debugged, include these arguments in the
DEBUG statement and execute only a brief simulation.
Extended Definition
The DEBUG command section contains additional descriptions on the information returned by
DEBUG/EPRINT command.
Examples
DEBUG/EPRINT
This DEBUG statement generates the information in Figure 4 that appears in the message file.
In this example, Adams Solver (FORTRAN) is printing the information for the third step of a dynamic
analysis. For this step, Adams Solver (FORTRAN) uses a second-order polynomial to guess the solution.
Using a time step of 7.25694E-04, the integration step goes from 6.458333333E-04 to 1.371527778E-03.
After the first iteration, the z velocity equation of PART/245330 has the largest error: its absolute value is
2E+00. The z coordinate of PART/245330 changes the most during the first iteration. The absolute value of
the change is 8.E-04. Adams Solver (FORTRAN) updates the Jacobian before the first iteration, but not
before the second or third.
Figure 4 Sample EPRINT Information

DEBUG 65

66 Adams Solver
DIFF
describes it.
Format
DIFF 67
Arguments
Specifies an expression for a differential equation or defines the argument list

for the user-written subroutine that defines the differential equation. To
define the equation with an expression, follow FUNCTION with an equal
sign and the expression. To define the equation with a user-written
subroutine, follow FUNCTION with an equal sign, the character string
USER, and the argument list (r1[,...,r30]) of values and system variables to be
passed to the user-written subroutine DIFSUB. In a function expression, the
system variable DIF(i) is the value of the dependent variable defined by the
DIFF/i statement. DIF1(j) is the first derivative of the dependent variable
defined by the DIFF/j statement. Note that the FUNCTION argument must
either be the last argument in the DIFF statement or be followed by a
backslash (\).
IC=r1[,r2] Specifies the initial value of the user-defined variable and, optionally, an
approximate value of the initial time derivative. The value r1 is the value of
the user-defined variable at the start of the simulation. If you enter an implicit
equation, r2 may also need to be specified, which is an approximate value of
the time derivative of the user-defined variable at the start of the simulation.
Adams Solver (FORTRAN) might adjust the value of the time derivative
when it performs an initial conditions analysis. Entering an initial value for
the time derivative helps Adams Solver (FORTRAN) converge to a desired
initial conditions solution. You do not need to supply r2 when you enter a
explicit equation since Adams Solver (FORTRAN) can compute the initial
time derivative directly from the equation. Adams Solver (FORTRAN)
requires you to enter r1.
Default: 0
IMPLICIT Indicates that the function expression or DIFSUB subroutine defines the
implicit form of a differential equation. Adams Solver (FORTRAN) assumes
that either the expression or user-written subroutine defines the explicit form
of the equation if IMPLICIT is not specified. In this case, the time derivative
of the state variable is set to the value of FUNCTION.
ROUTINE=libname::subname Specifies an alternative library and name for the user subroutine DIFSUB.

STATIC_HOLD Indicates that the DIFF state is not permitted to change during static and
quasi-static analysis.
Extended Definition
describes it. The equation may be dependent on any Adams Solver (FORTRAN) state variable available in a
68 Adams Solver
function expression except PTCV and CVCV forces. You can create systems of differential equations by using
more than one DIFF statement or LSE and GSE statements.
Both function expressions and user-written subroutines can access the DIFF state variable and its derivative.
Function expressions access the value by using the function DIF(id1) and the derivative by using DIF1(id1)
(see DIF and DIF1 functions). In each case, i1 specifies the identifier of the DIFF statement that defines the
variable. User-written subroutines access the value and derivative by calling the subroutine SYSFNC (see the
SYSFNC subroutine).
The function can be defined by a function expression, or by providing a user-written subroutine. Because the
Solver typically handles a function expression more efficiently than a user-written subroutine, it is
recommended that you use a function expression whenever possible.
The DIFF may be defined in either explicit or implicit form. The following equation defines the explicit form
of a differential equation:
y· = f (y, u, t)
where y· is the time derivative of the user-defined state variable, y is the user-defined state variable itself, and
u is a vector of Adams Solver-defined state variables.
You need to use the implicit form if the first derivative of the state variable cannot be isolated. The following
equation defines the implicit form of a differential equation:
0 = F( y, y· , u, t)
Caution:  Although you can currently use a DIFF statement to define an implicit, algebraic
(rather then differential) equation, Adams Solver (FORTRAN) might not allow this
in the future. You should use VARIABLE statements to define algebraic equations
instead.
 During a static analysis, Adams Solver (FORTRAN) finds equilibrium values for
user-defined differential variables (DIFFs, GSEs, LSEs, and TFSISOs), as well as for
the displacement and force variables. This changes the initial conditions for a
subsequent analysis. Adams Solver (FORTRAN) sets the time derivatives of the user-
defined variables to zero if STATIC_HOLD is not specified during a static analysis,
and uses the user-supplied initial-condition values only as an initial guess for the static
solution. Generally, the final equilibrium values are not the same as the initial
condition values. Adams Solver (FORTRAN) then uses the equilibrium values of the
user-defined variables as the initial values for any subsequent analysis, just as with the
equilibrium displacement and force values.
However, the user-specified initial conditions are retained as the static equilibrium
values if STATIC_HOLD is specified. Thus, the final equilibrium values are the same
as the user-specified initial conditions. Note that this does not guarantee that the time
derivatives of the user-defined variable are zero after static analysis.
DIFF 69
Examples
DIFF/11, IC=1.75,
, FUNCTION = -2.0*DIF(11) + 4.0 + SIN(TIME)
DIFF/12, IC=1.75, IMPLICIT,
, FUNCTION = DIF1(12) + 2.0*DIF(12) - 4.0 - SIN(TIME)
These DIFF statements both define the following differential equation.
y· + 2y - 4 = sin (t), y(0) = 1.75

DIFF/11 defines the equation in explicit form, where the function expression computes y· as shown below.
y· = -2y + 4 + sin (t)
DIFF/12 defines the equation in implicit form, where Adams Solver equates the function expression to zero,
as shown below.
y· + 2y - 4 - sin (t) = 0
Applications
The DIFF statement defines a first order, linear or nonlinear, explicit or implicit, ordinary differential
equation for Adams Solver (FORTRAN) to integrate along with the dynamic simulation of a multibody
system. The equation may be independent of the rest of the problem or it may depend upon any variable in
the state vector. The solution to the differential equation can be used in the function expressions which define
a number of other elements in Adams Solver (FORTRAN) such as the SFORCE statement. Thus, you can
use Adams Solver (FORTRAN) to solve an independent initial value problem, or the differential equations
defined by DIFF statements may be fully coupled with the system of equations that governs the dynamics of
the problem.
DIFF statements are best for creating single equations or small sets of equations. Although you may create
sets of DIFF statements to represent higher order equations or large systems of equations, other Adams Solver
(FORTRAN) elements such as TFSISO, LSE, or GSE may be more convenient in these cases.
70 Adams Solver
END
An END delimiter indicates the end of a dataset. Although the file may contain additional data, Adams Solver
(FORTRAN) does not read any statements or comments that follow the END statement.
Format
END
See other Dataset delimiter available.
EQUILIBRIUM 71
EQUILIBRIUM
The EQUILIBRIUM statement specifies error tolerances and other parameters for static equilibrium and
quasi-static equilibrium analyses.
Format
72 Adams Solver
Arguments
ACCELERATION_ERROR=r Specifies the maximum acceleration error allowed during static

simulations performed using dynamic analyses.
Default: 1.0E-02
Range: ACCELERATION_ERROR > 0
ALIMIT=r Specifies the maximum angular increment allowed per iteration during
static or quasi-static equilibrium analysis. The default units for ALIMIT
are radians. To specify ALIMIT in degrees, add a D after the value.
Default: 0.17453 (10 D)

Range: ALIMIT > 0
DYNAMIC Specifies that Adams Solver perform static simulations using dynamic
analyses.
Default: STATIC
ERROR=r Specifies the relative correction convergence-threshold. The iterative
process carried out during the equilibrium analysis can not converge
prior to all relevant relative corrections being smaller than this value.
Default: 1.0E-04
Range: ERROR > 0
GLOBAL_DAMPING=r Specifies the coefficient for global damping applied to all bodies during
static simulations performed using dynamic analyses.
Default: 0
Range: GLOBAL_DAMPING > 0
IMBALANCE=r Specifies the equation imbalance convergence threshold. The iterative
process carried out during the equilibrium analysis can not converge
prior to each equation imbalance being smaller than this value.
Default: 1.0E-04
KINETIC_ENERGY_ERROR Specifies the maximum kinetic energy error allowed in static simulations
=r performed using dynamic analyses.
Default: 1.0E-02
Range: KINETIC_ENERGY_ERROR > 0

EQUILIBRIUM 73
equilibrium.
Default: 25
Range: MAXIT > 0
PATTERN=c1[:...:c10] This statement specifies as many as ten character strings that together
establish the pattern for evaluating the Jacobian matrix during the
modified Newton-Raphson iteration. For each iteration, T or TRUE
indicates that Adams Solver (FORTRAN) evaluates the Jacobian and F
or FALSE indicates that Adams Solver (FORTRAN) does not evaluate
the Jacobian. Thus, cj determines whether or not Adams Solver
(FORTRAN) evaluates the Jacobian at the jth iteration. If necessary,
Adams Solver (FORTRAN) repeats the pattern of evaluations until it
reaches the maximum number of iterations (MAXIT). The number of
Ts or TRUEs and Fs or FALSEs together must be at least one and no
more than ten.
Default: T:T:T:T:T:T:T:T:T:T, which evaluates the Jacobian at every

iteration (for example, the unmodified Newton-Raphson algorithm).
SETTLING_TIME=r Specifies the maximum time allowed to reach equilibrium during static
Default: 100
Range: SETTLING_TIME > 0
74 Adams Solver
equilibrium Jacobian matrix) Adams Solver adds to the stiffness matrix
(a subset of the equilibrium Jacobian matrix) during static simulations
performed using static analyses. Adding a fraction of the mass and
damping matrices to the stiffness matrix can stabilize the iteration
process and prevent the iteration from diverging. Often the stiffness
matrix is singular for a system because the system is neutrally stable (for
example, the system moves in certain directions without affecting the
potential energy). Adding a fraction of the mass and damping matrices
to the stiffness matrix removes this singularity and makes it possible to
solve for equilibrium positions. The value of STABILITY does not affect
the accuracy of the solution, but it does affect the rate of convergence of
the iteration process.
Default: 1.0E-05
Range: STABILITY > 0
STATIC Specifies that Adams Solver (FORTRAN) perform static simulations
using static analyses.
Default: STATIC
Default: 20
Range: TLIMIT > 0
Extended Definition
The EQUILIBRIUM statement specifies the use of static or dynamic analyses to find static and quasi-static
equilibria. The statement also specifies error tolerances and other parameters for static and quasi-static
equilibrium analyses, and dynamic analyses that are used to find static equilibria. You use this statement when
you want to change one or more of the tolerances or other parameters from the default values.
Use the SIMULATE command to request one of the following:
 Single static equilibrium analysis.
 Dynamic analysis for finding static equilibrium.
 Series of static equilibrium analyses over time, for example, a quasi-static equilibrium analysis.
A static or quasi-static equilibrium analysis is appropriate only when the system has one or more degrees of
freedom (degrees of freedom after Adams Solver (FORTRAN) has removed any redundant constraints).
Static and quasi-static equilibrium analyses solve for displacement and static forces, but not for velocity,
acceleration, or inertia forces which are all assumed to be zero. To perform a static equilibrium analysis,
Adams Solver (FORTRAN) finds the configuration and static forces for which all the static forces in the
system balance after being evaluated at the current simulation time. This process requires the solution of a set
of nonlinear algebraic equations. Adams Solver (FORTRAN) uses the modified Newton-Raphson iteration
to solve these equations.
EQUILIBRIUM 75
When you specify the DYNAMIC argument for an EQUILIBRIUM statement or command, and you issue
a SIMULATE/STATIC command, Adams Solver (FORTRAN) performs a dynamic analysis that is similar
to one it would perform if you issued the SIMULATE/DYNAMIC command, except for the following:
 The function-expression variable, TIME, whether accessed using function expressions or the TIME
variable passed to most user subroutines, is set to the starting time for the duration of the analysis.
This setting has the effect of freezing all time-dependent excitations.
 Body forces are applied to all rigid bodies (damping forces) that oppose motion relative to ground.
The magnitude of the forces depends on the velocity of the rigid bodies relative to ground and on
the GLOBAL_DAMPING argument used with the EQUILIBRIUM statement or command.
 The simulation time is reset to the starting time once the analysis is complete.
 The analysis terminates when one of the following occurs:
• A norm of the system acceleration falls below ACCELERATION_ERROR and the system
kinetic energy simultaneously falls below KINETIC_ENERGY_ERROR.
• The simulation time has advanced by SETTLING_TIME.
Because a dynamic analysis occurs here, the INTEGRATOR statement/command specifies the error
tolerances and other parameters normally associated with dynamic analyses.
If neither an EQUILIBRIUM command nor an EQUILIBRIUM statement is issued in an Adams Solver

session, to set the default values for ALIMIT, ERROR, IMBALANCE, MAXIT, PATTERN, STABILITY,
and TLIMIT,the Adams Solver (FORTRAN) uses their default values when performing a static equilibrium
or quasi-static equilibrium analysis.
Note: If the dynamic analysis will be followed by a static analysis, the goal of the dynamic analysis
is not to find equilibrium, but to allow the system to settle enough to permit the subsequent
analysis to be successful.
76 Adams Solver
Tip:  Using the PATTERN argument to request less frequent evaluations of the Jacobian
matrix may decrease the computation time. However, infrequent evaluations could
also be more expensive since the modified Newton-Raphson algorithm might require
more iterations due to the slower convergence rates.
 Use the ALIMIT and TLIMIT arguments to limit incrementing displacement
variables during an iteration for static equilibrium. Excessive incrementing could
prevent Adams Solver (FORTRAN) from finding a static equilibrium position.
 Use the IMBALANCE argument if the physical units of the problem are such that the
default imbalance of 1.0E0-4 is excessively large or excessively small. Changing from
an inappropriate to an appropriate value for IMBALANCE saves CPU time.
 If your model runs well dynamically, and will not find static equilibrium using a static
analysis, try using the EQUILIBRIUM/DYNAMIC option to find static equilibrium.
 Understanding how your model behaves in a standard SIMULATE/DYNAMIC
simulation is helpful before using dynamic analyses to find static equilibrium.
 When using a dynamic analysis to find static equilibrium, you may find it useful to
relax the INTEGRATOR/ERROR argument more than if you were performing a
standard dynamic analysis.
 A damped dynamic analysis can only approach a static equilibrium asymptotically.
Therefore, to find the equilibrium solution, consider following a dynamic analysis, or
a series of analyses, with a final static analysis.
 For dynamic analyses that are used to find static equilibrium, you should choose the
convergence criteria: ACCELERATION_ERROR, KINETIC_ENERGY_ERROR,
and SETTLING_TIME based on the units of the model, as well as the characteristics
of the simulation.
EQUILIBRIUM 77
Caution:  Setting STABILITY=0 results in a singularity if the system is neutrally stable. If the
system is neutrally stable, STABILITY must be greater than zero in order for Adams
Solver (FORTRAN) to compute static equilibrium.
 Static equilibrium, or quasi-static equilibrium analyses often have multiple
equilibrium solutions. Adams Solver (FORTRAN) makes no attempt to converge to a
stable position. For example, Adams Solver (FORTRAN) may converge to an
inverted pendulum position rather than the more common hanging pendulum. Items
such as the initial position of parts and the settings for ALIMIT, TLIMIT, and
STABILITY can all influence the solution to which Adams Solver (FORTRAN)
converges.
 Currently, ADAMSC++ /Solver can use only GSTIFF and GSTIFF variants to
perform dynamic analyses using static equilibrium.
 Only rigid bodies (PARTS) are considered when using dynamic analyses to find static
equilibrium (flexible bodies and point masses are ignored both when applying global
damping forces and when calculating system acceleration and kinetic energy). It is
possible to use the EQUILIBIUM/DYNAMIC option with flexible bodies and/or
point masses in the model. The results may or may not be useful.
Examples
EQUILIBRIUM/ STABILITY=0.01, TLIMIT=10
, IMBALANCE=1.0E-05
This EQUILIBRIUM statement instructs Adams Solver (FORTRAN) to use these values instead of the
defaults when performing a static or quasi-static equilibrium analysis. It adds 0.01 times the sum of the mass
and damping matrices to the stiffness matrix during an equilibrium iteration. It limits the translation in any
one iteration to 10 length units. The force imbalance in the system must be less than 1.0E-05 force units for
Adams Solver (FORTRAN) to consider the system to be in equilibrium.
EQUILIBRIUM/ DYNAMIC, SETTLING_TIME = 0.5, LIST
This EQUILIBRIUM statement instructs Adams Solver (FORTRAN) to perform dynamic analyses to find
static equilibria, and resets the value of the SETTLING_TIME parameter from the default to 0.5. It also
causes Adams Solver (FORTRAN) to list on your screen and in a message file (.msg) the current
EQUILIBRIUM settings.
78 Adams Solver
FEMDATA
The FEMDATA statement produces data files of component loads, deformations, stresses, or strains for input
to subsequent finite element or fatigue life analysis. You use the OUTPUT statement to specify the type of
file FEMDATA produces. Except for HOTSPOTS table and the old style (.fem) file, FEMDATA will not
output data to any files unless you specify the format in the OUTPUT statement.
Format
FEMDATA 79
Arguments
CRITERION = c Specifies the criterion or value of stress or strain in determining hot spots.
Supported criteria are one of: VON_MISES, MAX_PRIN, MIN_PRIN,
MAX_SHEAR, NORMAL_X, NORMAL_Y, NORMAL_Z, SHEAR_XY,
SHEAR_YZ, and SHEAR_XZ. Default criterion is VON_MISES.
DATUM = node_id Specifies a node ID of the flexible body to be the datum of the nodal
displacements. Adams Solver computes all nodal displacements relative to this
node ID. If you do not specify a datum node, Adams Solver generates an
arbitrary relative set of nodal displacements. It displays a warning message if
the specified node does not belong to the flexible body.
END = t2 Specifies the time, t2, at which to end the output of the data or the search of
a peak load.
Default: Output or search to the end of the simulation.

Range: t2 > t1
HOTSPOTS = n Specifies the number of hot spots to locate on the flexible body and output. A
search for the top n nodes that recorded the highest stress or strain during the
simulation will ensue. With the START, END or SKIP arguments,
FEMDATA only checks the time steps within those specifications for hot
spots. A text file containing a table of hot-spot data (node ID, maximum value,
time of maximum value, and location) will be output. The complete time
history of nodal stress or strain will be output as well for each hot spot, if the
STRAIN or STRESS option is specified in the OUTPUT statement.
FLEX_BODY = id Specifies the ID of the flexible body whose data FEMDATA outputs.
FEMDATA outputs the data in the FEM basic coordinate system that is
inherent to the flexible body, except in the case of STRAIN or STRESS with
the RM=id option.
FILE = name Specifies the output file name for the FEM data. You can specify an existing
directory, root name, and/or extension. By default, the file name will be
composed of the ADAMS run and body IDs according to the type of data and
file format that you specified in the OUTPUT statement.
LOADS Outputs all external forces (reaction and applied forces except gravity) acting
on the specified body and inertial forces of the specified body (angular
velocities and accelerations including effects of gravity) as a function of time.
Load data will be output in the simulation set of units.
MODAL_DEFORMATI Outputs modal deformations as a function of time of the specified flexible
ON body. FEMDATA will only export coordinates of the active modes in the
simulation.
NODAL_DEFORMATI Outputs nodal deformations as a function of time of the specified flexible.
ON FEMDATA writes the formations in the simulation set of units.
80 Adams Solver
NODE = id1 [,…,idn] Specifies the node numbers of a flexible body whose data is to be output. If
you do not specify a node list, FEMDATA exports nodal data at each
attachment point of the flexible body. Adams Solver issues a warning if a node
ID is specified that does not belong to the flexible body.
NOINERTIA Turns off the output of inertia loads. Inertia loads include linear acceleration,
angular acceleration, and angular velocity of the part or flexible body. Only
loads due to reaction and applied forces are output with this option. This
results in a load imbalance specification for the body, so you must employ a
technique, such as inertia relief, to recover the inertia loads from the external
loads in the finite element program.
PEAK_SLICE = Specifies that FEM load data are to be output only at those time steps where
FX:FY:FZ:FMAG:GMAG the specified peak load occurred in the simulation. With the START, END, or SKIP
: TX:TY:TZ:TMAG arguments, FEMDATA only checks the time steps within those specifications
for the peak load. You can specify one or more of FX, FY, FZ, FMAG, GMAG,
TX, TY, TZ, TMAG..
RADIUS = r Specifies a radius between hot spots. If specified, all nodes falling within a
sphere defined by radius r and centered about the node with the highest
stress/strain, will be considered one hot spot. A default value of zero means
that all nodes for the flexible body are candidates for hot spots.
RM = id Specifies the rigid body marker to be the reference coordinate system to output
loads. Because Adams Solver resolves all loads acting on the rigid body in the
coordinate system of the specified marker, the marker should represent the
FEA basic coordinate system of the part's finite element model (FEM).
If only RM is specified with no accompanying type (that is, LOADS or

STRESS or STRAIN), an old style .fem file is generated with loading
information for each rigid body that has a marker listed on this field.
For STRESS or STRAIN, optionally specifies the reference coordinate system

in which to output. If RM is not specified, stress/strain will be computed in
the flexible body’s LPRF. If specified, the stress/strain tensor will be
transformed relative to instantaneous coordinate system of marker ID. The
RM does not have to belong to the flexible body, but can be any marker in the
model. All six components of stress or strain (Sxx, Syy, Szz, Sxy, Syz, Szx) can
be affected by this coordinate transformation. This option can be useful when
correlating test results such as strain gauge data on a flexible component.
SKIP = n Specifies the number of output steps to skip when outputting the data.
Default: n=0 (every step is output).

FEMDATA 81
START = t1 Specifies the time at which to start outputting the data.
Default: Output at the start of the simulation.

Range: t1 > t2 (See END argument)
STRAIN Outputs strain information if strain modes are available in the modal neutral
file (MNF) of the specified flexible body. FEMDATA outputs all six
components of strain (normal-X, normal-Y, normal-Z, shear-XY, shear-YZ,
shear-ZX). It outputs strains in the basic FEA coordinate system of the flexible
body, unless the RM=id option is specified.
STRESS Outputs stress information if modal stresses are available in the MNF of the
flexible body. FEMDATA outputs all six components of stress (normal-X,
normal-Y, normal-Z, shear-XY, shear-YZ, shear-ZX). It outputs stresses
output in the simulation set of units in the basic FEA coordinate system of the
flexible body, unless the RM=id option is specified.
Extended Definition
Default File Naming Conventions
You can use the FILE argument to specify the directory, name, and/or extension (directory/name.extension)
for the output file. If you do not specify a directory, FEMDATA creates all its output files except DAC files
in the current working directory. Because several DAC files are typically generated for a FEMDATA
statement, FEMDATA creates them in a separate directory named after the body. It creates this directory in
the current working directory if it does not exist.
If a file name is not specified in the FILE argument, default file names are assigned according to the type of
FEM data and file format (which is specified in the OUTPUT statement) as shown in the table below.
FEMDATA Default File Names and Extensions

(none) (none) <run_name> .fem
Loads DAC <run_name>_<channel_id> .dac
NASTRAN <run_name>_<body_name> .dat
ABAQUS <run_name>_<body_name> .dat
ANSYS <run_name>_<body_name> .dat
RPC <run_name> .rsp
Modal Deformation DAC <run_name>_<channel_id> .dac
Generic <run_name>_<body_name .mdf
NASTRAN <run_name>_<body_name> .mdf
PUNCH <run_name>_<body_name> .mdf
ANSYS <run_name> .out
RPC <run_name> .rsp
82 Adams Solver

Nodal Deformation Generic <run_name>_<body_name> .ndf
NASTRAN <run_name>_<body_name> .spc
ANSYS <run_name>_<body_name> .inp
Strain DAC <run_name>_<node_id>e_<channel_id> .dac
Hotspots <run_name>_body_name>_hots .tab
Stress DAC <run_name>_<node_id>se_<channel_id> .dac
Hotspots <run_name>_<body_name>_hote .tab
*Specified in the OUTPUT statement

Old Style FEMDATA
An older version of the FEMDATA statement where one or more RM markers are specified with no data type
is still being supported. The format of this version of FEMDATA is:
FEMDATA/id, RM=id1[,...,id100]
In this case, a text file with extension .fem is generated. This file contains generic load specifications for the
parent body of each RM marker specified.
Format of .fem File
The .fem file contains information sufficient to define all forces (inertial and applied) acting on one or more
parts. The data in this file is intended to be converted to boundary conditions input to a finite element
program. This file is composed of the following lines:
Line1: <Header>
Line 2: <Title>
Lines repeated for every part:
Lines repeated for every output step:
<Record 1> (RM Displacement)
<Record 2> (CM Displacement)
<Record 3> (CM Velocity)
<Record 4> (CM Acceleration)
<Record 5> (Force Displacement)
<Record 6> (Force Values)
<Header> Definition
Output: File Version #, Date&Time, User ID, Job ID, Program ID
Format: 1X, A4, 4X, A18, 6X, 2I10, 2X, A2
<Title> Definition
Output: Title of ADAMS run
Format: A80
<Record 1> Definition - RM Location
Output: Part ID, Time, 1, X, Y, Z, <Euler Angles (radians)>, RM
ID
Format: I10, 1PE13.5, I2, 6(1PE13.5), I10
<Record 2> Definition - CM Location wrt RM
Output: Part ID, Time, 2, X, Y, Z, <Euler Angles (radians)>, CM
FEMDATA 83
ID
Format: I10, 1PE13.5, I2, 6(1PE13.5), I10
<Record 3> Definition - CM Velocity wrt RM
Output: Part ID, Time, 3, X’, Y’, Z’, Wx, Wy, Wz(radians/time),
CM ID
Format: I10, 1PE13.5, I2, 6(1PE13.5), I10
<Record 4> Definition - CM Acceleration wrt RM
Output: Part ID, Time, 4, X’’, Y’’, Z’’, Wx’, Wy’,
Wz’(radians/time**2), CM ID
Format: I10, 1PE13.5, I2, 6(1PE13.5), I10
<Record 5> Definition – External Force Location wrt RM
Output: Part ID, Time, 5, X, Y, Z, <Euler Angles (radians)>,
Marker ID
Format: I10, 1PE13.5, I2, 6(1PE13.5), I10
<Record 6> Definition – External Force Record wrt RM
Output: Part ID, Time, 3, Fx, Fy, Fz, Tx, Ty, Marker ID
Format: I10, 1PE13.5, I2, 6(1PE13.5), I10
Peak Loads
Except for FMAG, GMAG, and TMAG, each PEAK_SLICE load specification (FX, FY, FZ, TX, TY, TZ)
generates two output time steps for each marker force of the component, one for the maximum (peak) and
one for the minimum (valley). For FMAG and TMAG, only one time step is output for each marker force
since these quantities are load magnitudes and generate only positive values. With GMAG, only one time
step is output per body. If:
 Fm(t) represents the force acting on the body at Marker m.
 rˆ x, rˆ y, rˆ z represents the unit vector of the reference coordinate system of the rigid body (FEA
coordinate system of the flexible body).
 r(t) represents the position of the reference marker (RM) in that coordinate system.

ˆ ˆ ˆ
|| || represents taking the magnitude or length of a vector (that is, || ( r x, r y, r z ) || = 1)
Then the following conditions apply:
ˆ
 FX = Output loads at time t when F m ( t ) • r x ( t ) is a maximum and minimum for each marker
m.
ˆ
 FY = Output loads at time t when F m ( t ) • r y ( t ) is a maximum and minimum for each marker
m.
ˆ
 FZ = Output loads at time t when F m ( t ) • r z ( t ) is a maximum and minimum for each marker
m.
ˆ
 FMAG = Output loads at time t when F m ( t ) • r ( t ) is a maximum for each marker m.
84 Adams Solver
 GMAG = Output loads at time t when

MAX  Fm ( t ) • rx ( t ) , Fm ( t ) • ry ( t ) , Fm ( t ) • rz ( t ) .
m m m
Note: Similar expressions exist for TX, TY, TZ, and TMAG. The PEAK_SLICE argument is not
available when you specify a time history OUTPUT load format (DAC or RPC).
Modal Superposition
Nodal displacements, strains, and stresses are computed using the principal of modal superposition:
Here i are the respective mode shapes from FEA and {q(t)}are the modal displacements of the flexible body
that Adams Solver computes.
Coordinate Reference Transformation of Stress or Strain
Because stress and strain are second-order tensors, the following equation is used to transform these quantities
to a reference coordinate system:
[ S ]' = [ A g ] [ S ] [ A g ] T
Where [ A g ] is the skew-rotation matrix from the flexible body’s LPRF (FE origin) to the marker’s
coordinate reference, and [ S ] is the symmetric stress or strain tensor. That is:
S xx S xy S xz
[ S ] = S yx S yy S yz where S ij = S ji
S zx S zy S zz
Definition of Hot Spots
The figure below illustrates how the radius argument can affect the definition of a hot spot region. In this
figure, the top 7 hottest nodes (those with the largest stress) are listed. If the number 5 and no radius is
specified on HOTSPOTS, then only nodes 4, 5, 3, 6, and 2 would be output. If a radius of 0.5 mm is
specified, then only node 4 would be listed from this region and the other 4 hot spots would come from nodes
with the highest stress from other regions.
FEMDATA 85
Limitations
Using FEMDATA to output loads encounters the same limitations as exporting FEA Loads in Adams View.
See Limitations for Exporting FEA Loads for more information.
86 Adams Solver
Caution: Note that all FEMDATA are output in the Adams modeling units. This causes a problem when
the Adams units are inconsistent with those used in the finite element model, and the data that
is output will be included in a subsequent finite element analysis.
For example, when outputting FEMDATA of type LOADS to ANSYS or MSC.Nastran for
inclusion in the FE analysis, the Adams and FE modeling units must be consistent. This is also
true when outputting FEMDATA of type NODAL_DEFORMATION when the OUTPUT
format is ANSYS or MSC.Nastran and the data will be used as input to the FE analysis.
In the case of outputting FEMDATA of type MODAL_DEFORMATION, the only concern
for units is when MSC.Nastran (or PUNCH) has been specified as the OUTPUT format. This
is because rigid body motion is included in the output file along with the modal coordinates.
By definition, modal coordinates are unitless, so the modal stresses (or strains) will be recovered
correctly in MSC.Nastran irregardless of unit settings. However, in order for the overall
displacement of the component to be correctly recovered, the unit of length must be consistent
between models.
Examples
, HOTSPOTS = 7, CRITERION = MAX_PRIN
, RADIUS = 0.5, FILE = hotspots_101
OUTPUT/STRESS = DAC
These statements create a text file, named hotspots_101.tab containing hot spot information for flexible body
101. Seven hot spots with a radius of 0.5 based on maximum principal stress are requested. Also, a time
history of the stress for each node found to be a hot spot is output in DAC format. The names of the DAC
files are given the prefix “hotspots_101” as specified in the FILE argument.
FEMDATA/1, LOADS, RM=201
, PEAK_SLICE = GMAG
, FILE = peak201.nas
OUTPUT/LOADS = NASTRAN
These statements create a NASTRAN input file containing loads of the parent part of marker 201 in that
marker’s coordinate reference system. They output the loads for only one time step when the magnitude of
the global sum of all marker forces on the part is greatest in the simulation.
, PEAK_SLICE = FX:FY:FZ:FMAG
OUTPUT/LOADS = ANSYS
These statements create an ANSYS input file with .dat default extension containing loads acting on flexible
body 101 in the FEA coordinate system. If the flexible body has, say 4 attachments, you should expect (3*2
+ 1)*4 load cases (loads from 28 time steps) to be output, because FX, FY and FZ output loads for 2 time
steps per attachment, and FMAG will output 1 per attachment.
, FILE = conrod
OUTPUT/LOADS = RPC
FEMDATA 87
These statements create an RPC file, named conrod.rsp that contains the time history of loads for all load
channels acting on flexible body 101. A Nastran load map file is also generated, named conrod_lc.nas. This
file contains the unit loads definitions in Nastran input format that map to the load channels in the RPC file.
This file can be combined with the Nastran BDF that was used to define the flexible body’ mesh, and perform
a static solution in obtaining stress coefficients related to the unit loads. The stress coefficients can be
combined with the actual loads in the RPC file in a fatigue program such as FE-Fatigue or MSC.Fatigue to
perform a fatigue analysis based on linear superposition theory.
88 Adams Solver
FIELD
Format
FIELD 89
Arguments
CMATRIX=r1,...,r36 Defines a 6x6 matrix of viscous damping coefficients. The following matrix
shows the values to input.
r 1 r 7 r 13 r 19 r 25 r 31
r 2 r 8 r 14 r 20 r 26 r 32
r 3 r 9 r 15 r 21 r 27 r 33
r 4 r 10 r 16 r 22 r 28 r 34
r 5 r 11 r 17 r 23 r 29 r 35
r 6 r 12 r 18 r 24 r 30 r 36
Enter the elements by columns from top to bottom, then from left to right.
CMATRIX defaults to a matrix with thirty-six zero entries if you do not use
either CMATRIX or both CRATIO and KMATRIX. The units for the
translational and rotational components of CMATRIX should be force-
time per unit displacement and torque-time per radian, respectively.
CRATIO = r Defines the ratio of CMATRIX to KMATRIX. If you input CRATIO,
Adams Solver (FORTRAN) multiplies KMATRIX by CRATIO to obtain
CMATRIX. Do not use CRATIO without also using KMATRIX.
Default: 0
FORCE=r1,...r6 Defines three preload force components and three preload torque
components in the field element when the I and J markers are
separated/misaligned by the values specified in the LENGTH argument.
The terms r1,...,r6 are the force components along the x-, y-, and z-axis of
the J marker and the torque components about the x-, y-, and z-axis of the
J marker, respectively. FORCE is optional and defaults to six zero entries.
FUNCTION=USER(r1[,. Defines and passes constants to the user-written subroutine FIESUB to
..,r30]) define a nonlinear field. Follow FUNCTION with an equal sign, the
character string USER and the values (r1[,...,r30]) that Adams Solver
(FORTRAN) is to pass to FIESUB. For more information on the FIESUB
subroutine and nonlinear fields, click here. The FUNCTION argument
must either be the last argument in the FIELD statement or be followed by
a backslash (\).
90 Adams Solver
I=id, J=id Specifies the identifiers of two markers between which the force and torque
is to exert.
KMATRIX=r1,...,r36 Defines a 6x6 matrix of stiffness coefficients. The following matrix shows
the values to input.
r 1 r 7 r 13 r 19 r 25 r 31
r 2 r 8 r 14 r 20 r 26 r 32
r 3 r 9 r 15 r 21 r 27 r 33
r 4 r 10 r 16 r 22 r 28 r 34
r 5 r 11 r 17 r 23 r 29 r 35
r 6 r 12 r 18 r 24 r 30 r 36
Enter the elements by columns from top to bottom, then from left to right.
KMATRIX defaults to a matrix with thirty-six zero entries. The units for the
translational and rotational components of KMATRIX should be force per
unit displacement and torque per radian, respectively.
Adams Solver (FORTRAN) cannot calculate the damping coefficients if

you do not use both CRATIO and KMATRIX. In that case, CMATRIX
must be explicitly defined if you want to include damping coefficients in the
calculation of the field forces.
LENGTH=r1,...,r6 Defines six reference length angles. This is the nominal position of the I
marker with respect to the J marker, resolved in the J marker coordinate
system. The terms r1,...,r6 are the x, y, and z translational components
(specified in linear displacement units) of the displacement between the I
and J markers; and a, b, and c are rotational displacement of the axes of the
I marker with respect to the J marker, resolved in the J marker axes (specified
in radians). If the reference force is zero, LENGTH is the same as the free
length. LENGTH is optional and defaults to a six zero entry.
ROUTINE=libname::sub Specifies an alternative library and name for the user subroutine FIESUB.
name
FIELD 91
Extended Definition
To specify a linear field, use the arguments in the FIELD statement to specify constants for the six-by-six
stiffness matrix, a six reference lengths, and a six-by-six damping matrix. The stiffness and damping matrices
must be positive semidefinite, but need not be symmetric. To specify a nonlinear field, use the user-written
subroutine FIESUB to define the three force components and three torque components and use the argument
FUNCTION=USER(r1[,...,r30]) to pass constants to FIESUB.
The following constitutive equations define how Adams Solver (FORTRAN) uses the data for a linear field
to apply a force and a torque to the I marker depending on the displacement and velocity of the I marker
relative to the J marker.
Fx K 11 K 12 K 13 K 14 K 15 K 16 x – x 0 C 11 C 12 C 13 C 14 C 15 C 16 V x F1
Fy K 21 K 22 K 23 K 24 K 25 K 26 y – y 0 C 21 C 22 C 23 C 24 C 25 C 26 V y F2
Fz K 31 K 32 K 33 K 34 K 35 K 36 z – z 0 C 31 C 32 C 33 C 34 C 35 C 36 V z F3
= – – +
Tx K 41 K 42 K 43 K 44 K 45 K 46 a – a 0 C 41 C 42 C 43 C 44 C 45 C 46 ω x T1
Ty K 51 K 52 K 53 K 54 K 55 K 56 b – b 0 C 51 C 52 C 53 C 54 C 55 C 56 ω y T2
Tz K 61 K 62 K 63 K 64 K 65 K 66 c – c 0 C 61 C 62 C 63 C 64 C 65 C 66 ω z T3
For a nonlinear field, the following constitutive equations are defined in the FIESUB subroutine:
Fx = f1(x,y,z,a,b,c,Vx,Vy,Vz, ω x , ω y , ω z )
Fy = f2(x,y,z,a,b,c,Vx,Vy,Vz, ω x , ω y , ω z )
Fz = f3(x,y,z,a,b,c,Vx,Vy,Vz, ω x , ω y , ω z )
Tx = f4(x,y,z,a,b,c,Vx,Vy,Vz, ω x , ω y , ω z )
Ty = f5(x,y,z,a,b,c,Vx,Vy,Vz, ω x , ω y , ω z )
Tz = f6(x,y,z,a,b,c,Vx,Vy,Vz, ω x , ω y , ω z )
Adams Solver (FORTRAN) applies the defined forces and torques at the I marker. In the linear and nonlinear
equations:
 Fx, Fy, and Fz are the three translational force measure numbers.
 Tx, Ty, and Tz are the three rotational force measure numbers associated with unit vectors directed
along the x-, y-, and z-axis of the J marker.
 K is the stiffness matrix.
92 Adams Solver
 x0, y0, z0, a0, b0, and c0 are the free lengths.
 x, y, z, a, b, and c are the translational and the rotational displacements of the I marker with respect
to the J marker expressed in the coordinate system of the J marker.
 Vx,Vy,Vz, ω x , ω y , and ω z are the time derivatives of the deformation, respectively; C is the
damping matrix.
 F1, F2, F3, T1, T2, and T3 are the translational and the rotational pre-tensions.
All variables and time derivatives are computed in the J marker coordinate system.
Adams Solver (FORTRAN) applies an equilibrating force and torque at the J marker, as defined by the
following equations.
Fj = -Fi
Tj = -Ti - L x Fi
opposite to the force at the I marker, the torque is usually not equal and opposite, because of the displacement
vector L.
Tip:  A FIELD statement can define any six-component, action-reaction force. However,
when defining massless beams, you may want to use a BEAM statement. It requires
only six input values to compute the thirty-six values for the Kmatrix (see BEAM).
 Finite element analysis programs can give the values for CMATRIX and KMATRIX.
FIELD 93
Caution:  For the constitutive equations to be accurate, at least two of the rotations (a, b, c)
must be small. That is, two of the three values must remain smaller than 10 degrees.
In addition, if a becomes greater than 90 degrees, b becomes erratic. If b becomes
greater than 90 degrees, a becomes erratic. Only c can become greater than 90 degrees
without causing problems. For these reasons, it is best to define your field such that
angles a and b (not a and c and not b and c) remain small.
 The three rotational displacements (a, b, and c) that define the field are not Euler
angles. They are the projected angles of the I marker with respect to the J marker.
Adams Solver (FORTRAN) measures them about the x-, y-, and z-axis of the J
marker.
 Adams Solver (FORTRAN) applies the component translational and rotational forces
for a field to the I marker and imposes reaction forces on the J marker.

Similarly, the damping matrix may be adding energy to the system. Both of these situations are
uncommon. Adams Solver (FORTRAN) does not warn you if the C matrix, K matrix, or both
are not positive semidefinite. While Adams Solver (FORTRAN) does not require that these
matrices be symmetric, it is most realistic.
Examples
Consider a cantilever, semimonocoque wing structure like the figure below.
Cantilever , Semimonocoque Wing Structure
94 Adams Solver
In order to model the elastic freedoms at location I shown on the figure, the system stiffness matrix must first
be determined for the retained freedoms. A finite element super element analysis is one method for
determining the matrix. Assume that all other freedoms are either constrained or superfluous for this analysis.
The system stiffness matrix is:
X Z θy
X 0.198E+04 0.126E-01 -0.147E+04
Z 0.126E-01 0.208E+03 -0.933E-02
θy -0.147E+04 -0.933E-02 0.763E+07
Inserting these entries into a full six-by-six FIELD array yields:
X Y Z θx θy θz
X 0.198E+04 0 0.126E-01 0 -0.147E+04 0
Y 0 0 0 0 0 0
Z 0.126E-01 0 0.208E+03 0 -0.933E-02 0
θx 0 0 0 0 0 0
θy -0.147E+04 0 -0.933E-02 0 0.763E+07 0
θz 0 0 0 0 0 0
FIELD 95
The FIELD statement describing these elastic forces applied to Marker 100 due to displacement of Marker
100 relative to Marker 57 is:
FIELD/1, I=100, J=57, KMATRIX=0.198E+04
, 0, 0.126E-01, 0, -0.147E+04, 0,
, 0, 0, 0, 0, 0, 0,
, 0.126E-01, 0, 0.208E+03, 0, -0.933E-02, 0,
, 0, 0, 0, 0, 0, 0,
,-0.147E+04, 0, -0.933E-02, 0, 0.763E+07, 0,
, 0, 0, 0, 0, 0, 0
, LENGTH=0, 150, 0, 0, 0, 0
These entries must be made column by column. The distance between the I and J markers is zero except in
the y direction (where it is 150).
96 Adams Solver
FLEX_BODY
The FLEX_BODY statement defines a linear elastic body floating in space. The FLEX_BODY is capable of
undergoing large motion, characterized by six non-linear generalized coordinates for a floating body
coordinate system (BCS) relative to GROUND. The small, linear elastic deformations of the FLEX_BODY
relative to this BCS are described by a linear combination of mode shapes. The modal amplitudes from this
linear combination are additional generalized coordinates for the FLEX_BODY. The body can be connected
to the rest of the mechanical system through applied forces and kinematic constraints.
Format
FLEX_BODY 97
Arguments
Specify modal damping as a fraction of critical damping. You can specify

e modal damping using a function expression or a user-written subroutine. To
 
CRATIO =   define the modal damping with an expression, follow CRATIO with an equal
 user ( r 1 [ ,… ,r 30 ] )  sign and the expression. The FXFREQ and FXMODE function expression may be
useful here.
To define modal damping with a user-written subroutine, follow CRATIO

with an equal sign, the character string USER, and the values (r1[,...,r30] that
the Adams Solver (FORTRAN) is to pass to the DMPSUB user-written
subroutine. If the CRATIO argument is used, it must either be the last
argument in the FLEX_BODY statement, or be followed by a backslash (\).
If you omit CRATIO, Adams Solver (FORTRAN) applies default damping as

follows:

DMODE=a1,a2,...,an Specifies the initial values of the modal generalized coordinates.
Default: 0
Range: Real values
EXACT=c1:...:c6 Specifies as many as six rigid body coordinates of the BCS that Adams Solver
(FORTRAN) should not change as it iteratively solves for initial conditions
which satisfy all constraints. The six coordinates are below.
X - x coordinate
Y - y coordinate
Z - z coordinate
PSI - Psi coordinate
THETA - Theta coordinate
PHI - Phi coordinate
These coordinates can be entered in any order following EXACT. These are
not changed by Adams Solver (FORTRAN) unless the values specified are
inconsistent with initial conditions for a joint or motion.
Default: None
Range: X, Y, Z, Psi, Theta, or Phi
98 Adams Solver
INVARIANTS=c1:...:c9 Specifies a true and false pattern indicating which of the nine inertia invariants
Adams Solver (FORTRAN) should use to model inertia coupling of the
flexible and rigid body motion. The order of the patterns corresponds to the
nine successive inertia invariants. For more details on the inertia invariants,
see the Theory of Flexible Bodies in Adams Flex.
The following combinations have special significance:
T:T:F:F:T:T:T:T:T - Full inertia coupling of deformation and rigid body

motion.
T:T:F:F:F:T:T:T:F - Ignore second-order deformation corrections to the

inertia tensor, and the first-order corrections to the rotational and flexible
inertia coupling. This is also called partial coupling.
T:T:F:F:F:T:T:F:F - Neglect all deformation corrections to the mass matrix.
*:*:*:*:*:F:*:*:* - Disable all deformations.
The pattern T:T:F:F:F:T:T:T:F is the default, because although it potentially

sacrifices small levels of accuracy compared to the first pattern of full inertia
coupling, it does so with significant computational savings. If an MNF has six
rigidbody modes in it, theoretically, invariants 3 and 4 should be zero even
though there may be some non-zero entries in the MNF file due to numerical
errors. This is the reason that they are disabled by default. The pattern
T:T:F:F:F:T:T:F:F should be used with great care, because it only returns an
accurate answer when the flexible component is quite rigid. The pattern
*:*:*:*:*:F:*:*:*, where the * can be either T or F, offers a way to turn off all
flexibility in the structure, usually for debugging purposes. Note that even
with this last pattern, the FLEX_BODY statement does not function like a
PART statement, due to formulation differences.
It is hard to envision circumstances where it is appropriate to disable
invariants 1 (the total mass), 2 (the undeformed CM location), and 7 (the
undeformed inertia tensor). Disabling these normally causes a numerical
singularity.
Default: T:T:F:F:F:T:T:T:F
FLEX_BODY 99
MATRICES=id 1,...,idn Specifies identifiers of matrices that contain the properties of the
FLEX_BODY, such as inertia, node locations, mode shape information,
applied modal loads, and preloads. Each matrix is defined via a MATRIX
statement. Normally, these matrices are generated by a modal flexibility
preprocessor (MNF2MTX) which writes these matrices to a file. To learn
more about this process, see Translating an MNF or an MD DB into a Matrix File.
The FLEX_BODY recognizes the following matrix names. Their identifiers

can be specified in any order.
SELMOD: A list of selected modes and their natural frequency.

SELNOD: A list of selected nodes and their location.
GENSTIFF: The generalized stiffness matrix.
INVAR1: Invariant 1 - the total mass of the flexible body.
INVAR2: Invariant 2 - the mass scaled center of mass location.
INVAR3: Invariant 3.
INVAR6: Invariant 6 - the generalized mass.
INVAR7: Invariant 7 - the moment of inertia.
T_MODE: Translational mode shape of selected modes at selected notes.
R_MODE: Rotational mode shape of selected modes at selected nodes.
PRELOAD: The preload on the selected modes.
MODLOAD: The modal loadcases on the selected modes.
Default: None
Range: Adams identifiers

MEXACT=d1, d2, ..., dn Specifies as many as n modal body coordinates that Adams Solver
(FORTRAN) should not change as it iteratively solves for initial conditions
which satisfy all constraints. The variable n is the number of modes. The n
coordinates are below.
1 to n Modal generalized coordinates
Theses coordinates can be entered in any order following MEXACT. These

are not changed by Adams Solver (FORTRAN) unless the values specified are
inconsistent with initial conditions for a joint or motion.
Default: None
Range: Active mode numbers
100 Adams Solver
MNF_FILE=file_name Specifies the path to the Modal Neutral File that defines the detailed
properties of the flexible body. Note that this argument is not required by
Adams Solver (FORTRAN) (see MATRICES argument above), only by Adams
View.
QG=x,y,z Defines the Cartesian initial coordinates of the BCS with respect to the
ground coordinate system.
Default: 0.0, 0.0, 0.0

Range: Real values
REULER=a,b,c Defines the 3-1-3 Euler angles that Adams Solver (FORTRAN) uses to
establish the initial orientation of the body coordinate system (BCS) with
respect to the ground coordinate system. The a, b, and c rotations are in
radians and are, respectively, about the z-axis of ground, new x-axis, and new
z-axis of the BCS. To input Euler angles in degrees, you should add a D after
each value.
Default: 0.0, 0.0, 0.0 when REULER, XG, and ZG are omitted
Range: Real values
VM=id Specifies the identifier of the marker that specifies the direction of
translational velocity initial conditions (VX, VY, and VZ). VM defaults to
global orientation.
VMODE-a1,a2,...,an Specifies the initial values of the time rate of change of the modal generalized
coordinates.
Default: 0
Range: Real Values
VX=x,VY=y,VZ=z Specifies the initial translational velocities of the body coordinate system
(BCS) along the x-axis (VX), y-axis (VY), and z-axis (VZ) of the VM
coordinate system.
Default: 0
Range: Real values
angular velocity initial conditions (WX, WY, and WZ) are defined. WM
defaults to the BCS location and orientation. Furthermore, the origin of the
WM marker lies on the axis of rotation. This is most useful for rotating
systems.
WX=a,WY=b,WZ=c Specifies the initial rotational velocities of the body coordinate system (BCS)
along the x-axis (WX), y-axis (WY), and z-axis (WZ) of the WM coordinate
system.
Default: 0
Range: Real values
FLEX_BODY 101
Tip:  All of the locations corresponding to a constraint attachment should have the finite
element nodes associated with them. The nodal identifiers for these points are listed
in the NODE argument. This allows for accessing the nodal information in the .adm
file.
 The Modal Body Preprocessor provides the input matrices in the Adams Solver
matrix format. See the online help for Adams Flex.
 When the nodal list is empty, the modal body cannot be attached to any other
elements of Adams Solver (FORTRAN).
 The intrinsic variables FXMODE and FXFREQ are available so you can write
function expressions that define CRATIO as a function of mode number and/or
modal frequency (see FXMODE and FXFREQ functions).
 If your FLEX_BODY undergoes high-speed, rigid body rotations about a stationary
axis, significant solver performance can be realized by aligning the z-axis of the body
coordinate system (BCS) with the spin axis. Because the BCS of the FLEX_BODY is
defined by the basic coordinate system in the finite element model, re-orientating the
BCS with respect to the body requires you to re-orient the finite element model with
respect to its basic coordinate system. In MSC.Nastran, this can be done easily with
CORDxx Bulk Data entries.
102 Adams Solver
Caution:  When one of the following Joints or JPRIMS constrains a flexible body directly
Adams Solver (FORTRAN) creates a dummy part and a dummy fixed joint
connecting the dummy part to the flexible body at the location of the constraint, and
then moves the constraint to the dummy part.
Joints:
• CONVEL
• CYLINDRICAL
• PLANAR
• RACKPIN
• SCREW
• TRANSLATIONAL
• GEAR
• COUPLER
JPRIMS:
• INLINE
• INPLANE
 When one of the following forces is applied directly to a flexible body Adams Solver
(FORTRAN) creates a dummy part and a dummy fixed joint connecting the dummy
part to the flexible body at the location of the force, and moves the force to the
dummy part.
• BEAM
• BUSHING
• FIELD
• ROTATIONAL SFORCE
• ROTATIONAL SPRINGDAMPER
 Flexible body CONTACT is only supported when using Adams Solver (C++).
Examples
FLEX_BODY/1
, MATRICES=1,2,3,4,5,6,7,8,9,10,11,12,13,14
, CRATIO=0.0\
, DMODE=.0,.0,.0,.0
, VMODE=.0,.1,.0,.0
This statement defines a flexible body with a damping ratio of 0.0 on all modes. Zero initial modal
displacements are specified by the DMODE argument. The VMODE argument specifies an initial modal
velocity for mode 2 of 0.1.
FLEX_BODY 103
FLEX_BODY/1
, CRATIO = STEP(TIME, 0.1, 1.0, 1.2, STEP(FXFREQ, 3000, 0.02, 10000,
0.2))\
This example specifies modal damping that varies both with time and modal frequency, such that all modes
have 100% critical damping until t=0.1, after which:
 Modal damping decreases smoothly to between 2% and 20% of modal damping at time=1.2.
 Modes with modal frequencies less than 3,000 reach 2% modal damping.
 Modes with modal frequencies above 10,000 reach 20% modal damping.
 Modes with modal frequencies between 3,000 and 10,000 reach modal damping values smoothly
distributed between 2% and 20%.
FLEX_BODY/1,
, CRATIO = IF(FXFREQ-100:0.01,0.1,if(FXFREQ-1000:0.1,1.0,1.0)\
This example recreates the default modal damping scheme using nested IF function expressions.
See other Inertia and material data available.
104 Adams Solver
FRICTION
The FRICTION statement defines parameters for frictional forces on translational, revolute, cylindrical,
hooke, universal, and spherical joints.
Note: Frictional forces and torques are computed by Adams Solver (FORTRAN) using a friction
model that supports dynamic friction and stiction.
FRICTION 105
Format
106 Adams Solver
Arguments
BALL_RADIUS=Rb Defines the radius of the ball in a spherical joint for use in friction-force and torque
calculations.
Default: 1.0
BENDING_REACTION_ARM= Defines the effective moment arm use to compute the contribution of the bending
Rb moment on the net friction torque in revolute, hooke, and universal joints.
Default: 1.0
Range: BENDING_REACTION_ARM > 0
STICTION_TRANSITION_VE Defines the absolute velocity threshold for the transition from dynamic friction to
LOCITY=r static friction. If the absolute relative velocity of the joint marker is below
Default: 0.1 length units/unit time on the surface of contact in the joint.
Default: All
FRICTION_FORCE_PRELOAD Defines the joint’s preload frictional force, which is usually caused by mechanical
=r interference in the assembly of the joint.
Default: 0.0
FRICTION_ARM=Rn Defines the effective moment arm used to compute the axial component of the
friction torque in revolute, hooke, and universal joints.
Default: 1.0
Default: none
Range: Static
FRICTION 107
Default: 1000.0
[[PRELOAD: and joint-reaction force and moments are included. You can customize the friction-
REACTION_FORCE: force model by limiting the input forces you list in the statement.
BENDING_MOMENT:
TORSIONAL_MOMENT]]} ) Default: ALL
Joint Type: (Available inputs:)

TORSIONAL_MOMENT)

BENDING_MOMENT)

JOINT=id Identifies the joint to which frictional forces apply.
MAX_STICTION_DEFORMAT Defines the maximum creep that can occur in a joint during the stiction regime.
ION=r The creep allows Adams Solver (FORTRAN) to impose the Coulomb conditions
for stiction or static friction, for example:
Default: 0.01 length units

108 Adams Solver
MU_DYNAMIC=r Defines the coefficient of dynamic friction. During the sliding regime, the

joint.
Default: none
MU_STATIC=r Defines the coefficient of static friction in the joint. The magnitude of the frictional
force is the product of a function fo MU_STAT, MU_DYNAMIC, and the creep
times the magnitude of the normal force in the joint, for example:
where μ = f (MU_STATIC, MU_DYNAMIC, creep) and N = normal force

The static frictional force acts to oppose the net force or torque along the degrees of
freedom of the joint.
Default: none
OVERLAP_DELTA={INCREASE To define friction in a sliding joint (either a translational or a cylindrical joint),
, DECREASE, CONSTANT} Adams Solver (FORTRAN) computes the overlap of the joint. As the joint slides,
the overlap can increase, decrease, or remain constant. OVERLAP_DELTA is used
to define any change in overlap.
 INCREASE indicates that overlap increases as the

I marker translates in the positive direction along the
J marker; the slider moves to be within the joint.
 DECREASE indicates that the overlap decreases with positive translation
of the joint; the slider moves outside of the joint.
Default: CONSTANT
FRICTION 109
MAX_FRICTION_FORCE = r Defines the maximum of the friction force for use in translational or cylindrical
joint.
Default: 1.0E+40
Range: MAX_FRICTION_FORCE > 0
Note: When there is a preload friction force applied to the joint, the
MAX_FRICTION_FORCE is set to be:
FRICTION_FORCE_PRELOAD+MAX_FRICTION_FORCE.
MAX_FRICTION_TORQUE = r Defines the maximum of the friction torque for use in revolute, universal, hooke,
spherical, or cylindrical joint.
Default: 1.0E+40
Range: MAX_FRICTION_TORQUE > 0
Note: When there is a preload friction torque applied to the joint, the
MAX_FRICTION_TORQUE is set to be:
FRICTION_TORQUE_PRELOAD+MAX_FRICTION_TORQUE.
TRANSITION_VELOCITY_CO Defines the absolute velocity threshold for the transition from static friction to
EFFICIENT = r dynamic friction. If the absolute relative velocity of the joint marker is at or above
STICTION_TRANSITION_VELOCITY, then the dynamic friction coefficient
is applied. Between STICTION_TRANSITION_VELOCITY and
STICTION_TRANSITION_VELOCITY the coefficient of friction is
transitioning from the static coefficient of friction to the dynamic coefficient of
friction.
Default: 1.5
Range: TRANSITION_VELOCITY_COEFFICIENT > 1
PIN_RADIUS=Rp Defines the radius of the pin for a revolute, cylindrical, hooke, or universal joint.
Default: 1.0
110 Adams Solver
force.
Default: 1.0
FRICTION_TORQUE_PRELO Defines the preload friction torque in the joint, which is usually caused by
AD=r mechanical interference in the assembly of the joint.
Default: 0.0
I_YOKE J_YOKE I_YOKE and J_YOKE define the rotational constraint on which the FRICTION
statement acts. I_YOKE identifies the yoke to the I marker’s rotational constraint.
Likewise, J_YOKE identifies the yoke to the J marker’s rotational constraint. These
keywords are used with only hooke and universal joints.
Extended Definition
Application of Friction in Joints
This section provides graphical descriptions and block diagrams of the joints and friction regimes available
in the FRICTION statement.
To learn about block diagrams and friction regimes, see:

 Conventions in Block Diagrams
 Friction Regime Determination (FRD)
To find information on a particular joint, see:
 Translational Joint
 Revolute Joint
 Cylindrical Joint
 Universal/Hooke Joint
 Spherical Joint
Conventions in Block Diagrams
The following tables identify conventions used in the block diagrams:
 Table 1 identifies symbols in the diagrams.
 Table 2 describes the relationship between the INPUTS argument in the FRICTION statement and
the switches used in the block diagrams.
Table 1. Legend for Block Diagrams
FRICTION 111
Symbol: Description:
_________ Scalar quantity
Vector quantity
Summing junction:
c=a+b
Multiplication junction:
c=axb
MAG Magnitude of a vector quantity

ABS Absolute value of a scalar quantity
FRD Friction regime determination
Table 2. Relationship Between the INPUTS Argument and Switches Used in the Block Diagrams
Switch: INPUTS=: Symbol: Acceptable Values:

SW1 PRELOAD Fprfrc or Tprfc ON/OFF
SW2 REACTION FORCE F· or F ON/OFF
SW3 BENDING MOMENT Tr ON/OFF
SW4 TORSIONAL MOMENT Tn ON/OFF
ALL/NONE sets all applicable switches
ON/OFF, respectively
Friction Regime Determination (FRD)

Three friction regimes are permissible in Adams:
112 Adams Solver
Dynamic friction A joint is in dynamic friction if its joint velocity magnitude exceeds the value of the
transition velocity coefficient multiplied by the friction transition velocity. The
dynamic coefficient of friction (md) is used in the computation of frictional forces.
Transition between dynamic and If the joint velocity magnitude is between the value of the transition velocity
static friction coefficient multiplied by the stiction transition velocity and friction transition
velocity, the joint is considered to be transitioning between static and dynamic
friction. A STEP function transitions the coefficient of friction between the
dynamic (md) and static (ms) coefficients of friction.
Static friction A joint is in static friction when the joint velocity magnitude falls below the stiction
transition velocity. The effective coefficient of friction is computed using the joint
creep, joint velocity, and static coefficient of friction (ms).
The joint velocity determines the instantaneous friction regime for a joint. The figure below shows the block
diagram of the friction regimes available in Adams Solver (FORTRAN).
Caution: FRICTION cannot be applied to joints connected to flexible bodies or point masses.
FRICTION 113
Examples
FRICTION/102, JOINT=102, I_YOKE
, MU_Static=0.03, Mu_Dynamic=0.024
, Stiction_Transition _velocity=0.1
, Max_Stiction_Deformation=0.1
, Pin_Radius=12.25
, Friction_arm=8.2
, Effect=All
, Inputs=Reaction_force
This statement creates frictional forces about the rotational degree of freedom associated with the I marker’s
part of either a hooke or universal joint. The following items apply:
 We assume that the joint has a 12.25 length-unit-radius pin and an effective-friction-moment arm
that is at the end caps of 8.2 length units.
 The friction model includes dynamic- and stiction-friction effect. The static-friction coefficient is
.03 and the dynamic-friction coefficient is .024.
 When computing the frictional force, Adams Solver (FORTRAN) identifies only the joint-reaction
forces as force inputs.
 The transition from dynamic friction to stiction occurs when the relative angular velocity in the
joint falls below 0.1 rads/unit time. A maximum deflection of 0.1 length units is permitted when the
joint is stiction.
114 Adams Solver
GEAR
The GEAR statement defines a gear pair constraint. Examples include a spur, helical, planetary, bevel, and
rack-and-pinion gear pairs
Format
GEAR/id, JOINTS=id1,id2, CV=id
Arguments
CV=id Identifier of the marker that designates the point of contact and implicitly determines
the ratio of the two gears. The z-axis of the CV marker must point in the direction of
common velocity at the point of contact. The direction of common velocity is tangent
to both pitch circles and would be normal to the tooth surfaces of the gears if the
pressure angle was zero (Adams Solver (FORTRAN) always assumes a zero pressure
angle). The CV marker must belong to the carrier part that also hosts the J markers of
the joints.
JOINTS=id1,id2 Specifies the two joints whose relative motion is to be related with a gear. Each of these
two joints must be translational, revolute, or cylindrical. Note that both J markers of
these joints belong to a carrier part that must also host the CV marker.
Extended Definition
The GEAR statement uses the location of a common velocity marker to determine the point of contact of
the two gear pitch circles. The direction of the z-axis of the common velocity marker indicates the direction
of the common velocity of points on the gear teeth in contact. This is also the direction in which gear tooth
forces act. Note that the CV marker has constant position and orientation in the carrier body coordinate
system (BCS). The CV marker through its z-axis only provides a direction, and there is no need to be more
specific than this. In this context, there is no need to indicate things such as how the power flow occurs
through the gear.
The reaction force reported back to you for a GEAR element is the reaction force measured on the J marker
of the joint that is specified first in the GEAR definition. It is important to keep in mind that the J markers
for both joints associated with the GEAR element must belong to the carrier part (the part that hosts the CV
marker).
GEAR 115
Caution:  Gear reaction forces and torques are difficult to obtain from the Request file because
of the way Adams Solver (FORTRAN) generates REQUEST statement output. Both
joints associated with the gear resist the tooth force generated by the gear. Therefore,
the gear tooth reaction force appears in both joints. The reaction torques due to the
gear does not appear in the joints, but they can be calculated from the gear tooth
reaction force and the moment arms to the joints. The Results file explicitly gives the
gear tooth reaction force.
 A GEAR statement does not simulate the backlash and the other intermittent effects
that characterize actual gears.
Examples
The figure below illustrates the use of a GEAR statement to define a bevel gear pair.
Bevel Gear Pair
The GEAR statement for this gear pair is below.

GEAR/1, JOINTS=13,23, CV=303
This GEAR statement indicates that the gear pair relates the motions of Joints 13 and 23 and indicates the
common velocity marker. Below are the statements that work with this GEAR statement to communicate the
characteristics of the gear pair to Adams Solver (FORTRAN).
MARKER/303, PART=3, QP=-2, -2, 0
MARKER/101, PART=1, QP=-10, 0, 0
, REULER=0, -90D, 0
MARKER/301, PART=3, QP=-10, 0, 0
, REULER=0,-90D, 0
MARKER/202, PART=2, QP=0, -10, 0
116 Adams Solver
MARKER/302, PART=3, QP=0,-10,0

, REULER=90D,90D,0
From JOINT statements 13 and 23, Adams Solver (FORTRAN) can determine that the first gear is Part 1
and that it forms a revolute joint with the carrier, which is Part 3. Adams Solver (FORTRAN) can also
determine that the second gear is Part 2 and that it also forms a revolute joint with the carrier. MARKER
statement 303 defines the location of the common velocity marker.
Schematic of a Rack-and-Pinion Gear Pair
For this gear pair, the same GEAR statement is used as the one in the previous example, but a different set of
JOINT and MARKER statements communicate characteristics of the gear to Adams Solver. Those
statements are as follows:
JOINT/13, I=101, J=301, TRANSLATIONAL
, REULER=90D,90D,0
, REULER=90D,90D,0
In this example, JOINT statement 13 defines a translational joint rather than a revolute joint, and MARKER
statement 303, which defines the constant velocity marker, has the same position and orientation as the
GFORCE 117
GFORCE
The GFORCE statement defines a force element that consists of three orthogonal translational force
user-specified function expressions in the Adams Solver (FORTRAN) dataset or through user-written
subroutines.
Format
Arguments
FUNCTION=USER(r1[,...,r30) Specifies up to thirty user-defined constants to compute the force

FX=e Specifies the magnitude and sign of the x component of the GFORCE
translational force. Adams Solver (FORTRAN) applies this force
FY=e Specifies the magnitude and sign of the y component of the GFORCE
FZ=e Specifies the magnitude and sign of the z component of the GFORCE
I=id Specifies the marker at which Adams Solver (FORTRAN) applies the
forces and torques. You must ensure that the I marker is a fixed marker
and on a different part than the JFLOAT marker. Because I is a fixed
marker, Adams Solver (FORTRAN) always applies the force at a fixed
point on the part containing the I marker.
118 Adams Solver
JFLOAT=id Specifies the marker at which Adams Solver (FORTRAN) applies the
Solver (FORTRAN) moves the JFLOAT marker to keep it
superimposed on the I marker, meaning that the point of application of
the reaction force may move with respect to its part. Adams Solver
(FORTRAN) does not calculate reaction forces when the JFLOAT
marker is on the ground part.
RM=id Specifies the marker and therefore the coordinate system in which the
a fixed marker. RM can be the same as I and can be fixed on any part in
your system.
ROUTINE=libname::subname Specifies an alternative library and name for the user subroutine GFOSUB.

TX=e Specifies the magnitude and sign of the x component of the GFORCE
rotational torque. Adams Solver (FORTRAN) applies this torque
parallel to the x-axis of the RM marker in the sense of the right-hand
TY=e Specifies the magnitude and sign of the y component of the GFORCE
parallel to the y-axis of the RM marker in the sense of the right-hand
TZ=e Specifies the magnitude and sign of the z component of the GFORCE
parallel to the z-axis of the RM marker in the sense of the right-hand rule
(that is, a positive torque causes a counterclockwise rotation).
Extended Definition
A GFORCE statement defines a force element that consists of three mutually orthogonal translational force
user-specified function expressions in the Adams Solver (FORTRAN) dataset or through user-written
subroutines.
The element applies actions to the part to which the I marker belongs and corresponding reactions to the
part to which the JFLOAT marker belongs. The GFORCE statement internally establishes the position of
the JFLOAT marker. As the system moves, Adams Solver (FORTRAN) moves the JFLOAT marker on its
part to always keep the JFLOAT and I markers superimposed. Therefore, Adams Solver (FORTRAN) applies
the reaction force to the part containing the JFLOAT marker at the instantaneous position of the I marker.
The magnitude of the force depends on the expressions or subroutines you supply. You can specify these
functions with Adams Solver (FORTRAN) function expressions or user-written FORTRAN-77 subroutines.
GFORCE 119
The vector formed by the three user-defined component forces along the RM marker axes defines the
direction of the translational force action. The reaction is equal and opposite to the action.
The vector formed by the three component torques determines the direction of the rotational torque action.
You define these torques about the RM marker axes. The reaction is equal and opposite to the action.
Formulation
Action
Values
F a = FX xˆ rm + FY yˆ rm + FZ zˆ rm
T a = TX xˆ rm + TY yˆ rm + TZ zˆ rm
where:
 Fa is the translational action applied to the I marker.
 FX is the user-defined function for the x-component force magnitude.
 FY is the user-defined function for the y-component force magnitude.
 FZ is the user-defined function for the z-component force magnitude.
 Ta is the rotational action applied to the I marker.
 TX is the user-defined function for the x-component according to the right-hand rule.
 TY is the user-defined function for the y-component according to the right-hand rule.
 TZ is the user-defined function for the z-component according to the right-hand rule.
 xˆ rm is a unit vector along the + x-direction of the RM marker.
 yˆ rm is a unit vector along the + y-direction of the RM marker.
 ẑ rm is a unit vector along the + z-direction of the RM marker.

Reaction
Values:
Fr = -Fa
Tr = -Ta
where Fr and Tr are the translational and rotational reactions applied at the JFLOAT marker, respectively.
Tip: Depending on the nature of the desired force relationship, the RM marker may belong to the
same part as the I marker or JFLOAT marker, or to a third, unrelated part.
120 Adams Solver
Caution: The user-defined forces FX, FY, FZ, TX, TY, and TZ should be smooth, continuous, and
Examples
, FX = -20.*VX(310,9900,310)\
, FY = -20.*VY(310,9900,310)\
, FZ = -20.*VZ(310,9900,310)\
, TX = -6.*WX(310,9900,310)\
, TY = -6.*WY(310,9900,310)\
, TZ = -6.*WZ(310,9900,310)
This GFORCE statement defines a general, six-component force acting between fixed Marker 310 and
floating Marker 9910, which must belong to different parts. Expressions FX, FY, FZ, TX, TY, and TZ define
the force and torque components the x, y, and z axes of the reference marker, which is Marker 310. Adams
Solver (FORTRAN) superimposes floating Marker 9910 on Marker 310, and apply the reaction force and
torque at that point.
Applications
The GFORCE statement is most useful when you need to define a vector force and vector torque whose point
of application and/or direction is most easily formulated in a coordinate system which moves or is on a
different part than the parts containing the force application points. For example, a GFORCE statement
could be used to model the normal and friction force effects for a ball rolling down an inclined surface. See
the figure below.
Model of Ball Rolling Down Incline
For this application, the RM reference marker would be fixed to the surface and would supply the orientation
for the normal and friction forces and the torque about the ball center due to the friction.
When compared with the SFORCE (see SFORCE statement), the GFORCE statement can vary both its point
respect to the RM-marker). In these cases, a single GFORCE statement can represent the complete
GFORCE 121
force/torque condition at a point along with its reaction forces, whereas it would require six translational
SFORCEs and six rotational SFORCEs, with appropriately-oriented markers, to accomplish the same thing.
122 Adams Solver
GRAPHICS
The GRAPHICS statement creates:
 Two- or three-dimensional geometry for CONTACT. You always define the geometry with respect
to a reference marker.
 Three-dimensional graphic data that represents the parts, constraints, or forces in a system.
Note: The only graphic that can be defined on a flex body is a point.
Because there are two uses for geometry, one for contact and the second for the graphical display of objects,
we have divided the documentation into two separate sections:
 GRAPHICS for CONTACT
 GRAPHICS for Graphic Display of Objects
New types of graphics are available for representing a wide variety of geometries in contact. Adams Solver
does not write these new geometric entities (point, plane, ellipsoid, and external) to the graphics file, and
therefore, they cannot be displayed in standalone Adams Solver (FORTRAN). You can, however, view them
from Adams View.
Graphics for Contact
Format
,ARC, CM = id, RADIUS = r,RANGLE = r
,BOX, CORNER = id, X = x, Y = y, Z = z
,CIRCLE, CM = id, RADIUS = r
,CURVE, CID = id, CRM = id
,CYLINDER, CM = id, RADIUS = r, LENGTH = r, RANGLE = r
,FRUSTUM, CM = id, RADIUS = r, LENGTH = r, TOP = r, BOTTOM = r, [RANGLE = r]
GRAPHICS/id ,PO INT, RM=id
,PLANE, RM = id, XMIN = r, XMAX = r, YMIN = r, YMAX = r
,EL LIPSOID, CM = id, XSCALE = r, YSCALE = r, ZSCALE = r
,EXTERNAL, RM = id, {FILE = file_name, [ELEMENT = geometry_name]}
,EXTRUSION, CRM = id, GID = id, PID = id
,REVOLUTION, CRM = id, GID = id
,TORUS, CM = id, MINOR_RADIUS = r, MAJOR_RADIUS = r
{ } Select one item

GRAPHICS 123
Arguments
ARC Creates an arc. You use the following arguments to define the arc:
 CM to specify the center marker of the arc.

 RADIUS to define the radius of the arc.
 RANGLE to define the extent of the arc, with the arc always starting at the
x-axis of the CM marker.
 SEG to specify the number of line segments to use to display the arc.
BOTTOM=r Defines the bottom radius of a frustum.
BOX Creates a rectangular box. You use the following arguments to define the box:
 CORNER to specify the ID of a reference marker at one corner of the box.

 X, Y, and Z to define the extent of the box along the x-, y-, and z-axes of the
corner marker.
CID=id Specifies the identifier of the curve to be drawn.
CIRCLE Creates a circle. You use the following arguments to define the circle:
 CM to specify the center marker of the circle.

 RADIUS to specify the radius of the circle.
CM=id Defines the identifier of the marker at the center of an arc, circle, cylinder, frustum
or torus.
 For an arc, circle, or ellipsoid, the origin of the marker specifies the center.
 For a cylinder or frustum, the origin of the marker specifies the center of the
bottom circle. The bottom circle lies in the plane contained by the x- and y-
axes of the marker. The z-axis of the marker defines the centerline axis of
the cylinder or frustum.
 For a torus, the origin of the marker specifies the center of the torus. The z-
axis of the marker defines the axis of revolution.
CRM=id Defines the reference marker with respect to which the curve data points are
specified.
CORNER=id Defines a reference marker, which is at a corner of the box that is being created.
CURVE Creates a curve graphic based on a CURVE statement. You define the curve data with
respect to a reference marker (CRM). The CONTACTand CVCV modeling entities
require that the curve be planar. It must be in the plane defined by the x- and y-axes
of the RM marker, and must contain the origin of the marker.
124 Adams Solver
CYLINDER Creates a cylinder whose top and bottom are perpendicular to the cylinder central
axis. You use the following arguments to define the cylinder:
 CM to specify the center marker (CM) of the cylinder. The z-axis of the
CM marker defines the axis of the cylinder.
 RADIUS to define the radius of the cylinder.
 RANGLE to define the angular extent of the cylinder, with the arc always
 LENGTH to define the height of the cylinder.
ELEMENT = Used with external geometry.
geometry_name
Specifies the name of a geometric entity in a file that FILE identifies. The file can
contain multiple geometries. You use ELEMENT to select a particular geometry
from the file even when it contains just one geometry. You will need additional
GRAPHICS statements if you want to read multiple geometries from the same file.
ELLIPSOID Creates an ellipsoid. You use the following arguments to define the ellipsoid:
 CM to specify the center marker (CM) of the ellipsoid.

 XSCALE, YSCALE, and ZSCALE to specify the diameters along the x-, y-,
and z-axes of the CM marker. If the argument values are all equal (XSCALE
= YSCALE = ZSCALE), then Adams Solver (FORTRAN) creates a sphere.
EXTERNAL Specifies that a three-dimensional solid geometry is to be created. The data for the
geometries is in an external file that the geometry engine of Adams Solver
(FORTRAN) can read. It use the following arguments to define the geometry:
 RM to specify the marker that defines the reference coordinate system.

 FILE identifies the file to be read. This file is commonly generated by the
geometry engine being used.
 ELEMENT to specify the name of a geometric entity in a file that FILE
identifies.
Adams Solver (FORTRAN) uses the geometry package Parasolid 14.0 to understand
geometry. Parasolid input files have the extension .xmt_txt and .xmt_bin. Both are
supported, however, .xmt_bin files are not portable across platforms.
Parasolid can read in the geometry data and tell Adams Solver (FORTRAN):
 Whether or not two geometries are in contact.

 Where the contact points are located on each geometry.
 The outward normals at the calculated contact points.
GRAPHICS 125

FILE=file_name Specifies the name of a file containing one or more geometric entities. Adams Solver
(FORTRAN) can only read Parasolid files. Parasolids is an exact boundary
representation (b-rep) geometric modeler. This means that it represents solids (and
other types of geometry) by their boundaries. Other file formats (such as shell files)
must be converted to a boundary representation externally before the Adams Solver
(FORTRAN) Parasolid geometry engine can use them.
FRUSTUM Creates a frustum of a cone whose top and bottom are perpendicular to the cone
central axis. You use the following arguments to define the frustum:
 CM to specify the center marker (CM) of the frustum. The z-axis of the
CM marker defines the axis of the frustum.
 TOP and BOTTOM to define its top and bottom radii, respectively.
 RANGLE to define the angular extent of the frustum, with the arc always
 RADIUS to define the radius of the frustum cone.
 LENGTH to specify the height of the frustum.
GID=id Defines the id of the closed curve or circle graphic to be revolved or extruded.
LENGTH=r Defines the height for either a cylinder or frustum. The two circles at the ends of a
cylinder or frustum are both perpendicular to the z-axis of the CM marker.
Therefore, the circles are parallel. Adams Solver (FORTRAN) uses the value of
LENGTH to specify the z distance between the two circles. There is no limit on the
value of r. A positive value specifies a cylinder or frustum along the positive z-axis of
the CM marker, and a negative value specifies a cylinder or frustum along the
negative z-axis of the CM marker.
MAJOR_RADIUS Specifies the larger radius of the torus.
MINOR_RADIUS Specifies the smaller radius of the torus.
PID Defines the id of the curve, arc, or circle graphic to extrude along.
PLANE Creates a finite plane. You use the following arguments to create a plane:
 RM to specify a reference coordinate system for the plane. The plane lies in
the x-y plane of the RM marker (that is, the z-axis of the RM marker is
normal to the plane).
 XMIN, XMAX, YMIN, and YMAX to specify the extent of the plane.
The plane is a two-dimensional element, and, therefore, you can only use it when
defining contact with another two-dimensional element (point, arc, circle, curve).
126 Adams Solver
POINT Creates a graphic point at the origin of the RM marker.

RADIUS=r Defines the radius of a circle, arc, cylinder, or frustrum.
Range: Radius > 0

RANGLE=r Defines an angle measured positive (according to the right-hand rule) about the z-
axis of the CM marker. Adams Solver (FORTRAN) assumes RANGLE is in radians.
The angle starts at the positive x-axis of the CM marker and subtends the arc, the arc
of the cylinder, or the arc of the cone frustum.
Range: -2 π < RANGLE < 2 π

axis of the CMR marker is the axis of revolution.
RM=id Identifies the marker that defines the reference coordinate system for a point, plane,
or external geometric entity. Adams Solver (FORTRAN) defines the geometries in
this coordinate system.
TOP=r Defines the radius at the top of a frustum. The top is perpendicular to the CM
marker z-axis, and the center of the top is at the position on the CM marker z-axis
that LENGTH specifies. There is no limit on the value of r.
 CM to specify the id of the marker that defines the center of the torus. The z-
axis of the CM marker is the axis of revolution.
X=x, Y=y, Z=z Locates the vertex of the box that is diagonally opposite from the corner that the
argument CORNER defines. You must specify the values of X, Y, and Z with respect
to the marker coordinate system.
XMIN=r, XMAX = Specifies the boundary edges of a plane. XMIN, XMAX, YMIN, and YMAX are
y, YMIN = r, relative to the CM marker of the plane.
YMAX = r
Range: XMIN < XMAX
YMIN < YMAX
XCALE = r, Specifies the diameters along the x-, y-, and z-axes of an ellipsoid.
YSCALE = r,
ZSCALE = r Range: XSCALE > 0
YSCALE > 0
ZSCALE > 0
GRAPHICS 127
Examples for Content

, LENGTH=-2
negative z-axis of Marker 0201.
GRAPHICS/1297, EXTERNAL, RM=7921,
, FILE = GenevaWheel.xmt_txt
, ELEMENT = Geneva
This GRAPHICS statement creates a three-dimensional solid element. The data for this solid element is
contained in a Parasolid file, GenevaWheel.xmt_txt. Within this file, which contains several geometric
entities, the solid with a tag, Geneva, is to be extracted. The solid definition is specified with respect to Marker
7921.
The geometry associated with GenevaWheel.xmt_txt is shown next.
Geometry in Parasolid File GenevaWheel.xmt_txt
128 Adams Solver
Graphics for Graphic Display of Objects
Format
 OUTLINE = id1[,..., id2500] 
 
 BOX, CORNER = id, X = x, Y = y, Z = z 
 
 CIRCLE, CM = id {,RADIUS = r, RM = id} [ ,SEG = i ] 
 
 ARC, CM = id, RANGLE = r {,RADIUS = r, RM = id} [ ,SEG = i ] 
 
 CYLINDER, CM = id [ ,RANGLE = r], LENGTH = r [ ,SIDES = i] { ,RADIUS = r, RM = id} [ ,SEG = i ] 
 
 
 FRUSTUM, CM = id [ ,RANGLE = r], LENGTH = r [ ,SIDES = i] ,TOP = r, BOTTOM = r [ ,SEG = i ] 
 
 , DA = r, COILS = i 
 
 SPDP, I = id, J = id ,DB = r, LA = r, LC = r 
 
 ,DC = r, LB = r, LD= r 
 
  ETYPE = ALL, EMARKER = id  
   
  BEAM  
     
   BUSHING   
     
   FIELD   
GRAPHICS/id,      
   SFORCE   
   SPDP   
     
   VFORCE   
 FORCE,     
  ETYPE=  VTORQUE , EID= id, EMARKER = id  
     
   GFORCE   
   NFORCE   
     
   JOINT   
     
   JPRIM   
     
   PTCV   
   CVCV   
   
 
 CURVE, CID= id, CRM = id1 [ , ... , idn] [ , SEG = i ] 
 
 EXTRUSION, CRM = id, GID = id, PID = id 
 
 REVOLUTION, CRM = id, GID = id 
 
 TORUS, CM = id, MINOR_RADIUS = r, MAJOR_RADIUS = r 
 
{ } Select one item
GRAPHICS 129
Arguments
ARC Creates an arc.

BOTTOM=r Defines the bottom radius of a frustum of a cone. The bottom is perpendicular to
the center marker z-axis, and the center of the bottom is at the center marker origin.
BOX Creates a box with parallel edges and orthogonal vertices.
CID=id Specifies the identifier of the CURVE statement to be drawn. Adams Solver
(FORTRAN) generates a curve graphic in each marker reference frame you specify
with CRM.
CIRCLE Creates a circle.
CM=id Defines the identifier of the marker at the center of an arc, circle, cylinder, frustum,
or torus. If you are creating a circle or arc, orient the CM marker so that its z-axis is
normal to the plane of the circle or plane of the arc. Similarly, if you are defining a
cylinder or frustum, orient the CM marker so that its z-axis is normal to the bottom
plane of the cylinder or the frustum. For the torus the z-axis should be the axis of the
revolution.
COILS Defines the number of coils in the spring of a spring-damper (SPDP) graphic.
Default: 0
Range: 99,999 > COILS > 0
CORNER=id Defines a reference marker at a corner of the box to be created.
CRM=id 1[,...,idn] Specifies a list of up to 2,500 markers at which to draw the curve identified by CID.
Adams Solver generates a curve graphic in each marker reference frame specified.
CURVE Creates a curve graphic based on a CURVE statement.
CYLINDER Creates a cylinder whose top and bottom are perpendicular to the cylinder central
axis.
DA=r Defines the diameter of the spring in a spring-damper (see the spring-damper figure
below). There is no limit on the value of r.
Default: 0
DB=r Defines the diameter of the damper in a spring-damper at the I marker (see the
spring-damper figure below). There is no limit on the value of r.
Default: 0
DC=r Defines the diameter of the damper in a spring-damper at the J marker (see the
spring-damper figure below). There is no limit on the value of r.
Default: 0
130 Adams Solver
Spring-Damper
EID=id Specifies the identifier of the element whose force is to be displayed by the FORCE
graphic. You can not specify EID if ETYPE=ALL.
EMARKER=id Specifies the identifier of the marker where Adams Solver displays the force graphic.
If ETYPE=ALL, marker EMARKER must have at least one force applied to it. If you
enter a specific force type, and identifier EID, marker EMARKER must be one of
the markers upon which the specified force acts.
ETYPE = {ALL, Specifies the element type for which Adams Solver generates force graphics. In
BEAM, BUSHING, combination with EID, ETYPE specifies one force statement. If ETYPE=ALL, then
FIELD, SFORCE, Adams Solver sums all forces applied to the EMARKER.
SPDP, VFORCE,
VTORQUE,
GFORCE,
NFORCE, JOINT,
JPRIM, PTCV,
CVCV}

FORCE Creates an arrow whose direction is identical to the direction of a force and whose
length is proportional to the magnitude of a force.
FRUSTUM Creates a frustum of a cone whose top and bottom are perpendicular to the cone
central axis.
GID Specifies the id of the closed curve or circle graphic to extruded or revolved.
GRAPHICS 131
I=id, J=id Defines the I and J markers for creating a spring-damper graphic. The I and J
markers define the attachment points of the spring-damper.
LA=r Defines the distance between the I marker and the end of the damper to which it is
closest (see the spring-damper figure ). There is no limit on the value of r.
Default: 0
LB=r Defines the distance between the J marker and the end of the damper to which it is
closest (see the spring-damper figure). There is no limit on the value of r.
Default: 0
LC=r Defines the height of the damper at I. Adams Solver measures the height from the
Default: 0
LD=r Defines the height of the damper at J. Adams Solver measures the height from the
Default: 0
LENGTH=r Defines the height for either a cylinder or frustum. Because the two circles at the
ends of a cylinder or frustum are both perpendicular to the z-axis of the CM marker,
they are parallel. Adams Solver (FORTRAN) uses the value of LENGTH to specify
the z distance between the two circles. There is no limit on the value of r. A positive
value specifies a cylinder or frustum along the positive z-axis of the CM marker, and
a negative value specifies a cylinder or frustum along the negative z-axis of the CM
marker.
MAJOR_RADIUS Defines the larger radius of the torus.
MINOR_RADIUS Defines the smaller radius of the torus.
OUTLINE=id1[,...,i Creates visible and invisible line segments to connect at least two and not more than
d2500] 2,500 markers. The values id 1[,...,id 2500] are marker identifiers. They define an
outline of line segments that Adams Solver (FORTRAN) draws from one marker to
the next. A comma (,) between two marker identifiers causes Adams Solver
(FORTRAN) to draw a line segment between two markers. A comma and minus
sign (,-) between two marker identifiers causes Adams Solver (FORTRAN) to draw
an invisible line from the first marker to the second.
PID Specifies the id of the curve, arc, or circle graphic to extrude along.
RADIUS=r Defines the radius of a circle, arc, or cylinder. There is no limit on the value of r.
RANGLE=r Defines an angle measured positive (according to the right-hand rule) about the z-
axis of the CM. Adams Solver (FORTRAN) assumes RANGLE is in radians. The
angle starts at the positive x-axis of the CM marker and subtends the arc, the arc of
the cylinder, or the arc of the cone frustum. Adams Solver (FORTRAN) clips to -
2 π values of r less than -2 π and clips to 2 π values of r greater than 2 π .
Range: 2 π > r > -2 π
132 Adams Solver
axis of the CMR marker is the axis of revolution.
RM=id Defines the radius of a circle, arc, or cylinder. Adams Solver (FORTRAN) measures
the distance from the CM marker to the RM marker to determine the radius.
SEG=i Defines the number of straight line segments Adams Solver uses to draw a curve,
circle, an arc, or the two circles at the ends of a cylinder or a frustum.
Default: 20
Range: 99,999 > SEG > 0
SIDES=i Defines the number of straight line segments Adams Solver draws between the two
parallel circles of a cylinder or a frustum.
Default: 20
Range: 99,999 > SIDES > 0
SPDP Draws a spring-damper graphic representation (see the spring-damper figure). For
SPDP, use I and J. To draw just the spring, use DA and COILS. To draw just the
damper at the I marker, use DB, LA, and LC. To draw just the damper at the J
marker, use DC, LB, and LD. To draw the entire spring-damper, use all of the
arguments for SPDP. DA, DB, DC, LA, LB, LC, LD, and COILS are all optional,
but Adams Solver cannot draw anything unless you include (at a minimum) the
arguments for the spring or one of the dampers.
TOP=r Defines the radius at the top of a frustum. The top is perpendicular to the CM
marker z-axis, and the center of the top is at the position on the CM marker z-axis
that LENGTH specifies. There is no limit on the value of r.
 CM to specify the id of the marker that defines the center of the torus. The z-
axis of the CM marker is the axis of revolution.
X=x,Y=y,Z=z Locates the vertex of the box that is diagonally opposite from the corner defined by
CORNER. The values of X, Y, and Z must be specified with respect to the marker
coordinate system.
Extended Definition
The GRAPHICS statement creates three-dimensional graphic data for display on a graphics device. You can
use it to create line segments, boxes, curves, circles, arcs, cylinders, frustums of cones, and spring-dampers.
Combinations of these images are attached to parts (including ground) to approximate their appearance.
GRAPHICS 133
These images move with their respective parts to produce a graphic simulation of the mechanism behavior.
You can also use the GRAPHICS statement to create force vectors so that the forces in the system can be
displayed.
Examples for Graphic Display of Objects

negative z-axis of Marker 0201. Twenty sides define the body of the cylinder, and the circles at the top and
at the bottom of the cylinder are actually twenty-sided polygons.
GRAPHICS/0001, OUTLINE=1001,1002,-1003,1004
This GRAPHICS statement creates a line from Marker 1001 to Marker 1002 and creates a line from Marker
1003 to Marker 1004. Because a minus sign (-) precedes Marker 1003, the statement creates an invisible line
segment from Marker 1002 to Marker 1003.
134 Adams Solver
GSE
The GSE (General State Equation) statement lets you represent a subsystem that has well defined inputs (u),
internal states (x), and a set of well defined outputs (y).
The GSE is represented mathematically as:
x· c = f c ( x c, u, t ) xc ( t0 ) = xc (1)
x dn + 1 = f d ( x dn, u, t ) x d ( t o ) = x do (2)
y = g ( x c, x d, u, t ) (3)
It consists of continuous states xc, and discrete states xd. The continuous states xc are defined in Equations
(1) as explicit, first-order, ordinary differential equations. fc() is specified in a user-written subroutine, and is
assumed to be continuous everywhere. Integrators in Adams Solver (FORTRAN) evaluate fc() as needed.
The discrete states xd are defined in Equations (2) by the function fd(). fd() is specified in a second user-
written subroutine. Equations (2) are difference equations. A sampling period is associated with Equations (2),
and integrators only evaluate Equations (2) at the sample times. The discrete states, xd, are assumed to be
constant between sampling periods. In Equations 2, x d is the short form for xd(tn).
n
The output, y, is sampled continuously, and is defined by g(). g() is specified in a third user-written
subroutine. It may be discontinuous in nature. If the output is to be fed back into the mechanical system
through a force element, then it is customary to eliminate the discontinuities in y, by passing it through a
low-pass filter before feeding the signal into the force element. You can use the TFSISO element to define a
low-pass filter. Failure to eliminate discontinuities in y will cause significant integration difficulties.
If Equations (1) are not present, the GSE is classified as a purely discrete GSE. If Equations (2) are not present,
the GSE is classified as being purely continuous. If both Equations (1) and (2) are present, the GSE is classified
as a sampled system. When neither Equations (1) nor (2) are present, the GSE does not contain any internal
states.
GSE 135
Format
136 Adams Solver
Arguments
FUNCTION=USER(r1[,...,r30]) Specifies the parameters that are to be passed to the user-written

subroutines that define the constitutive equations of a GSE, viz.,
Equations (1), (2), and (3).
Three user subroutines are associated with a GSE.
 GSE_DERIV is called to evaluate fc() in Equations (1).

 GSE_UPDATE is called to evaluate fd() in Equations (2).
 GSE_OUTPUT is called to evaluate g() in Equations (3).
IC=id Identifies the ARRAY statement in the dataset that specifies the initial
conditions for the continuous states in the system.
This is an optional argument. When you use the IC argument, an

ARRAY statement with this identifier must be in the dataset, it must be
of the IC type, and it must have the number of elements specified in
the argument NS.
When you do not specify an IC array for a GSE statement, all the
continuous states are initialized to zero.
ICD=id Identifies the ARRAY statement in the dataset that specifies the initial
conditions for the discrete states in the system.
This is an optional argument. When you use the ICD argument, an

ARRAY statement with this identifier must be in the dataset, it must be
of the IC type, and it must have the number of elements specified in
the argument ND. When you do not specify an IC array for a GSE
statement, all the discrete states are initialized to zero.
INTERFACE=lib1::gse1, Specifies an alternative library and subroutine names for the user
lib2::gse2, lib3::gse3, lib4::gse4 subroutines GSE_DERIV, GSE_OUTPUT, GSE_UPDATE,
GSE_SAMP respectively. The rules for the INTERFACE argument are
the same as for the ROUTINE argument.

ND=i Specifies the number of discrete states in the GSE. Discrete states are
updated by calling the function GSE_UPDATE at the sample times.
ND defaults to zero when not specified.
NO=i A mandatory argument, NO, specifies the number of output equations
(algebraic variables) that are used in the definition of Equation (3). If
NO is greater than 0, you must also specify a Y array. GSE outputs are
evaluated by calling the user written subroutine GSE_OUTPUT.
GSE 137
NS=i Specifies number of continuous states in the GSE and is used in the
definition of Equations (1). If you do not specify NS, then the GSE is
classified as being a continuous GSE. NS must be set to zero for a
purely discrete GSE. The time derivatives of the continuous states of a
GSE are evaluated by calling the user-written subroutine GSE_DERIV.
NS defaults to zero when not specified.
ROUTINE=lib1::gse1, lib2::gse2, Specifies alternative library and subroutine names for the deprecated
lib3::gse3, lib4::gse4, lib5::gse5 user subroutines GSESUB, GSEXX, GSEXU, GSEYX, GSEYU
respectively.

SAMPLE_OFFSET=r Specifies the simulation time at which the sampling of the discrete
states is to start. All discrete states before SAMPLE_OFFSET are
defined to be at the initial condition specified. SAMPLE_OFFSET
defaults to zero when not specified.
SAMPLE_PERIOD=expression Specifies the sampling period associated with the discrete states of a
GSE. This tells Adams Solver (FORTRAN) to control its step size so
that the discrete states of the GSE are updated at:
last_sample_time + sample_period
In cases where an expression for SAMPLE_PERIOD is difficult to

write, you can specify it in a user-written subroutine GSE_SAMP(…).
Adams Solver (FORTRAN) will call this function at each sample time
to find out the next sample period.
STATIC_HOLD Indicates that the continuous GSE states are not permitted to change
during static and quasi-static simulations.
U=id Designates the ARRAY statement in the dataset that is used to define
the input variables for the GSE. The U argument is optional. When it
is not present in the GSE statement, there are no system inputs. When
you use the U argument an ARRAY with this identifier must be in the
dataset. The number of inputs to the GSE statement is inferred from
the number of VARIABLE statements in the U array.
138 Adams Solver
X=id Designates the ARRAY statement in the dataset that is used to define
the continuous states for the GSE. When you specify it, an ARRAY
statement with this identifier must be in the dataset, it must be of the
X type, and it may not be used in any other LSE, GSE, or TFSISO
statement. If you specify SIZE on the ARRAY statement, it must have
the same value as the argument NS.
Y=id Designates the ARRAY statement in the dataset that is used to define
the outputs of the GSE. When you specify it, an ARRAY statement
with this identifier must be in the dataset, it must be of the Y type, and
it may not be used in any other LSE, GSE, or TFSISO statement. If you
the argument NO.
XD=id Designates the ARRAY statement in the dataset that is used to access
the discrete states for the GSE. An ARRAY statement with this
identifier must be in the dataset, it must be of the X type, and it may
not be used in any other LSE, GSE, or TFSISO statement. If you
the argument ND.
Extended Definition
The GSE (General State Equation) statement defines the equations for modeling a nonlinear, time varying,
dynamic system. The statement is especially useful for importing nonlinear control laws developed manually
or with an independent software package. It can also be used to define an arbitrary system of coupled
differential and algebraic equations that can be expressed as:
x· c = f c ( x c, u, t ) xc ( t0 ) = xc (4)
y = g ( x c, x d, u, t ) (6)
The GSE allows you to implement four different kinds of systems. These are:
 Continuous Systems
 Discrete Systems
 Sampled Systems
 Feed-Forward Only System
Continuous Systems
Continuous systems can be represented in the state-space form as:
·
x c = f c (x c,u ,t) , x c ( t 0 ) = x c 0 (7)
GSE 139
y = g (x c,u ,t) (8)
xc is called the state of the system, and contains n elements for an nth-order system. In matrix notation, xc is
a column matrix of dimension nx1. u defines the inputs to the system. Its size is equal to the number of inputs
to the system being modeled. In this description, the system is assumed to have m inputs, consequently u is
a column matrix of size mx1. y defines the outputs from the system. If a system has p outputs, y is represented
with a column matrix of dimension px1.
Using this system description, a nonlinear, second-order differential equation, with input u, such as:
·· 2
y + 2ζω n yy· + ω n y = Ku (9)
can be written in a state-space form as:
   
 x· 1   x2 
  =   (10)
 x· 2   – 2ζω n x 1 x 2 – ω 2n x + Ku 
   
y = x1 (11)
The state Equations (7) or (10) are integrated by Adams Solver using its integrators. Therefore, it is necessary
that the functional relationship expressed in Equations (7) or (10) be continuous. That is a minimum
requirement for successfully integrating these equations. Similarly, if the output is to be fed back into a plant
model, such as a mechanical system, Equations (8)5 or (11) are also required to be continuous. A higher degree
of differentiability will help the integrators solve these equations more efficiently.
Discrete Systems
Discrete systems can be described by their difference equations. They are, therefore, represented in the state-
space form as:
y = g (x d,u ,t) (13)
xd is called the state of the system, and contains n elements for an nth-order system. In matrix notation, xd is
a column matrix of dimension nx1. u and y have the same meaning as for continuous systems.
The fundamental difference between continuous and discrete systems is that the discrete or digital system
operates on samples of the sensed plant data, rather than on the continuous signal. The dynamics of the
controller are represented by recursive algebraic equations, known as difference equations, that have the form
shown in Equations (12).
The sampling of any signal occurs repetitively at instants in time that are T seconds apart. T is called the
sampling period of the controller. In complex systems, the sampling period is not a constant, but is, instead,
a function of time and the instantaneous state of the controller. The signal being sampled is usually
140 Adams Solver
maintained at the sampled value in between sampling instances. This is called zero-order-hold (ZOH).
Determining an appropriate sampling period is a crucial design decision for discrete and sampled systems.
One major problem to avoid with sampling is aliasing. This is a phenomenon where a signal at a frequency
ω 0 produces a component at a different frequency ω 1 simply because the sampling is occurring too
infrequently. The general rule of thumb for such situations is as follows:
If you want to avoid aliasing in a signal with a maximum frequency of ω , the sampling frequency is
calculated from ω 2> 2 ω . This is a lower limit for ω s . If you want to obtain a reasonably smooth time
response, then 20 < ω s / ω < 40.
The sampling rate for sampling the states of a discrete system must follow the above criterion to avoid aliasing.
Note that when an Adams Solver output time and a GSE sample time coincide, the output of the GSE at that
time will be calculated using the values of the discrete states before the update takes place. This is true for
discrete states in discrete systems and sampled systems.
Sampled Systems
There are many systems that are neither continuous nor discrete. Some signals are sampled at discrete
intervals, while others are sampled continuously. These systems are called sampled systems and are
represented in the state-space for as:
x· c = f c ( x c, u, t ) x c ( t 0 ) = x co (14)
y = g ( x c, x d, u, t ) (16)
Equations (14) represent the dynamics associated with the continuous piece of the sampled system. States xc
are continuous and fc() is assumed to be continuous.
Equations (15) represent the dynamics associated with the discrete piece of the sampled system. The equations
are evaluated only at discrete points in time, the sample times for the sampled system. In between sample
times, the discrete states are assumed to be constant.
Equation (16) defines the outputs of the system. It is important to note that the ADAMS integrators evaluate
Equation (16) as often as necessary. In many problems, it is important to examine the output between
sampling instants. Often, for example, the maximum overshoot may occur not at a sampling point, but
between samples. This implementation allows for such observations to be made on the output.
Feed-Forward Only System
These are systems that have no independent states. The output of the system is an algebraic function of the
inputs. They can be represented as:
y = g (u,t) (17)
GSE 141
Caution:  The GSE statement provides a very general capability for modeling nonlinear systems.
However, the routines for solving the linear equations in Adams Solver (FORTRAN)
have been developed and refined to work particularly well with the sparse systems of
equations that come from the assembly of mechanical models. With the GSE
statement, you can create very dense sets of equations. If these equations form a large
portion of the completed model, Adams Solver (FORTRAN) may perform more
slowly than expected.
subsequent analysis. If STATIC_HOLD is not specified, during a static analysis,
Adams Solver (FORTRAN) sets the time derivatives of the user-defined variables to
zero, and uses the user-supplied initial-condition values only as an initial guess for the
static solution. Generally, the final equilibrium values are not the same as the initial
However, the user-specified initial conditions are retained as the static equilibrium
values when STATIC_HOLD is specified. Thus, the final equilibrium values are the
Examples
Modeling Continuous Control Systems
The example below demonstrates how you can use a GSE to define a continuous controller in ADAMS. The
plant consists of a block on a translational joint. A continuous control force is to be applied to the block so
that it translates exactly 150 mm from its initial position. The control system is defined as follows.
Inputs
 It has two inputs (u1 and u2).
Outputs
 It has one output, y.
States
 It has two continuous states (x1 and x2).
142 Adams Solver
Transfer Functions
Y ( s )-
------------- – 2e7 Y ( s )- – 1e3s – 1e7 -
= --------------------------------------
- ------------- = --------------------------------------
U1 ( s ) 2
s + 2e3s + 1e7 U2 ( s ) 2
s + 2e3s + 1e7
A GSE represents the controller. Standard ADAMS modeling elements PART, JOINT, and SFORCE
represent the block, translational joint, and the actuator, respectively.
Model Input File
units/force=newton, mass=kilogram, length=millimeter, time = second
part/1, ground
marker/3, part = 1, reuler = 90d, 90d, 0d
part/2, qg = 0, 0, -100, mass = 46, cm = 6, ip = 2e5, 5e5, 4e5

marker/2, part = 2, qp = 0, 0, 100, reuler = 90d, 90d, 0d
marker/6, part = 2, qp = 0, 0, 100
marker/7, part = 2, qp = -150, 0, 100
joint/1, trans, i = 2, j = 3
sforce/1, trans, i = 4, j = 5, actiononly, function = aryval(2,1)
variable/2, function = dx(7)

variable/3, function = vx(7)
array/1, u, size = 2, variables = 2, 3 !Inputs for the GSE

array/2, y, size = 1 !Outputs for the GSE
array/3, x, size = 2 !States for the GSE
gse/99, ns = 2, no = 1, x = 3, u = 1, y = 2, function = user(3,1)
accgrav/jgrav = -9806.65
results/formatted
END
Simulation Results
The figure below shows the time history of the location and velocity of the block. Notice the displacement
(red curve) starts at 0 mm, and stops moving when it reaches a value of 150 mm. Notice also the overshoot
in the displacement of the block, which is subsequently corrected by the controller.
GSE 143
applied on the block. Notice that the actuator signal changes sign when the block is about to overshoot its
target value.
Time History of Actuator Signal Output by the Controller
144 Adams Solver
User-Written Subroutines for the continuous controller modeled by GSE

SUBROUTINE GSE_DERIV(ID, TIME, PAR, NPAR, DFLAG, IFLAG, NS, XDOT)
C
C Inputs:
C
C
C Outputs:
C
DOUBLE PRECISION XDOT(*)
C
C Local Variables:
C
INTEGER AX(1), AU(1), NSS, NU
DOUBLE PRECISION A(2,2), B(2,2), X(2), U(2)
SAVE A, B
DATA A /-1.0e3, 0.0, -2.0e4, -1.0e3/
DATA B /0.0, 1.0, -1.0, 0.0/
C
C+-------------------------------------------------------------------
-*
C
C Define the function fc():
C
GSE 145
AU(1) = NINT(PAR(2))
CALL SYSARY ('ARRAY', AX, 1, X, NSS, LEFLAG)
CALL SYSARY ('ARRAY', AU, 1, U, NU, LEFLAG)
XDOT(1) = A(1,1)*X(1)+A(1,2)*X(2) + B(1,1)*U(1)+B(1,2)*U(2)
XDOT(2) = A(2,1)*X(1)+A(2,2)*X(2) + B(2,1)*U(1)+B(2,2)*U(2)
C
C
IF (PARFLG) THEN
CALL SYSPAR ('ARRAY', AX, 1, A, NSS*NSS, LEFLAG)
CALL SYSPAR ('ARRAY', AU, 1, B, NSS*NU , LEFLAG)
ENDIF
RETURN
END
C
C+===================================================================
=*
C
C
C Inputs:
C
C
C Outputs:
C
C
C Local Variables:
C
INTEGER AX(1), NS
DOUBLE PRECISION C(2), X(2)
SAVE C
DATA C/1.0e3, 0.0/
C
C+-------------------------------------------------------------------
-*
C
C Define the function g():
C
CALL SYSARY ('ARRAY', AX, 1, X, NS, LEFLAG)
Y(1) = C(1)*X(1) + C(2)*X(2)
C
C
IF (PARFLG) THEN
CALL SYSPAR ('ARRAY', AX, 1, C, NS, LEFLAG)
146 Adams Solver
ENDIF
C
C
RETURN
END
Purely Discrete GSE

The example below demonstrates how you can use a GSE to define a discrete controller in ADAMS. The
plant consists of a block on a translational joint. A discrete control force is applied to the block to move it
exactly 150 mm from its initial position. The controller has a sample time of 0.001 seconds. The control
system is defined as follows:
Inputs
 It has two inputs (u1 and u2).
Outputs
 It has one output, y.
States
 It has two discrete states (x1 and x2).
Y ( z )-
------------- – 5.285z – 2.707 Y(z) – 0.63212
= ------------------------------------------------------- -------------- = ---------------------------
U1 ( z ) 2
z – 0.73576z + 0.1353 U1 ( z ) z – 0.36788
A GSE represents the controller. Standard ADAMS modeling elements PART, JOINT, and SFORCE
represent the block, translational joint, and the actuator, respectively.
UNITS/FORCE=NEWTON, MASS=KILOGRAM, LENGTH=MILLIMETER, TIME=SECOND
PART/1, GROUND
MARKER/5, PART = 1, QP = -150, 0, 0, REULER = 90D, 90D, 0D
PART/2, QG = 0, 0, -100, MASS = 46, CM = 6, IP =2E5, 5E5, 4E5

MARKER/2, PART = 2, QP = 0, 0, 100, REULER = 90D, 90D, 0D
MARKER/4, PART = 2, QP = -150, 0, 100, REULER = 90D, 90D, 0D
MARKER/6, PART = 2, QP = 0, 0, 100
MARKER/7, PART = 2, QP = -150, 0, 100
JOINT/1, TRANS, I = 2, J = 3
GSE 147
SFORCE/1, TRANS, I = 4, J = 5, ACTIONONLY, FUNCTION = ARYVAL(2,1)
VARIABLE/2, FUNCTION = DX(7)

VARIABLE/3, FUNCTION = VX(7)
ARRAY/1, U, SIZE = 2, VARIABLES = 2, 3

ARRAY/2, Y, SIZE = 1
ARRAY/3, X, SIZE = 2
GSE/99, ND=2, NO = 1, XD = 3, U = 1, Y = 2
, Sample_Period = 0.001/
, FUNCTION = USER(3,1)/
ACCGRAV/JGRAV = -9806.65
RESULTS/FORMATTED
END
Simulation Results
The figure below below shows the time history of the location and velocity of the block. Notice the
displacement (red curve) starts at 0 mm, and stops moving when it reaches a value of 150 mm.
applied on the block. Zooming into the curve shows that the output of the controller is discrete. Because the
148 Adams Solver
sampling period of the controller is 0.001 seconds, output was requested every 0.0005 seconds in order to
see the discrete nature of the output. The states also show similar behavior.
Time History of Actuator Signal Output by the Discrete Controller
User Subroutines for the Discrete Controller Modeled by a GSE

C
C Inputs:
C
C
C Outputs:
C
C
C Local Variables:
C
LOGICAL LEFLAG
INTEGER AXD(1), ND
DOUBLE PRECISION C(2), XD(2)
SAVE C
DATA C/1.0e3, 0.0/
C
GSE 149
C+-------------------------------------------------------------------
--*
C
C Y = C*Xd
C
AXD(1) = NINT(PAR(1))
CALL SYSARY ('ARRAY', AXD, 1, XD, ND, LEFLAG)
Y(1) = C(1)*XD(1) + C(2)*XD(2)
C
C
RETURN
END
C
C+===================================================================
=*
C
SUBROUTINE GSE_UPDATE (ID, TIME, PAR, NPAR, DFLAG, IFLAG, ND,
* XDplus1)
C
C Inputs:
C
INTEGER ID, NPAR, ND
C
C Outputs:
C
DOUBLE PRECISION XDplus1(ND)
C
C Local Variables:
C
LOGICAL LEFLAG
INTEGER AXD(1), AU(1), NDD, NU
DOUBLE PRECISION A(2,2), B(2,2), XD(2), U(2)
SAVE A, B
DATA A/.36788, 0.0, -7.3576, .36788/
DATA B/-.0052848, 0.00063212, -.00063212, 0.0/
C
C+-------------------------------------------------------------------
--*
C
C Xd+1 = A*Xd + B*U
C
AXD(1) = NINT(PAR(1))
AU (1) = NINT(PAR(2))
CALL SYSARY ('ARRAY', AXD, 1, XD, NDD, LEFLAG)
CALL SYSARY ('ARRAY', AU , 1, U , NU, LEFLAG)
XDplus1(1) = A(1,1)*XD(1)+ A(1,2)*XD(2) + B(1,1)*U(1) +
B(1,2)*U(2)
XDplus1(2) = A(2,1)*XD(1)+ A(2,2)*XD(2) + B(2,1)*U(1) +
B(2,2)*U(2)
C
C
RETURN
150 Adams Solver
END
C
C+===================================================================
=*
C
Sampled GSE
The example below demonstrates how you can use a GSE to define a sampled controller in Adams. The plant
consists of a block on a translational joint. A sampled system controls the block to move it exactly 150 mm
from its initial position.
The controller is modeled in Simulink. Real Time Workshop (RTW) is then employed to generate the
governing equations for the GSE. An interface is then written between the code generated by RTW and the
GSE subroutines: GSE_DERIV, GSE_UPDATE, GSE_OUTPUT, and GSE_SAMP.
The block diagram for the sampled control system is shown below:
Block Diagram of the Sampled System Used to Control the Block
The control system is defined as follows:

Inputs
 It has two inputs (in1 and in2).
 The first input (in1) is the velocity of the block.
 The second input (in2) is the location of the block.
States
 The controller has two continuous states.
 It has three discrete states.
GSE 151
Outputs
 It has one output, out1.
 The output is an actuator signal, which is a function of the continuous and the discrete states of the
controller and the two inputs. A low pass filter, Fcn2, is employed to obtain a smooth output that
may be fed into the mechanical system.
The controller is represented in a GSE. The block, translational joint, and the actuator are represented using
the standard ADAMS modeling elements PART, JOINT, and SFORCE, respectively.
To see a representation of the model and a Simulink representation of the control system, see the Release
Notes.
Simulation Results
The figure below shows the time history of the control force on the block. Notice that the control force
changes sign when the block overshoots its desired position.
Time History of the Actuator Force on the Block

152 Adams Solver
IC
The IC statement specifies error tolerances and other parameters for the analysis of the initial conditions and
for reconciling integrator output.
Format
Arguments
AERROR=r Specifies the maximum acceleration error Adams Solver (FORTRAN) is to allow during
an initial conditions solution or for reconciling integrator acceleration output.
Default: 1.0E-4
Range: AERROR > 0
ALIMIT=r Specifies the maximum angular increment Adams Solver (FORTRAN) is to allow while
testing trial solutions for a set of consistent initial conditions that satisfy all system
constraints. The default units for ALIMIT are radians. To specify ALIMIT in degrees,
add a D after the value.
Default: 30D
Range: ALIMIT > 0
AMAXIT=i Specifies the maximum number of iterations Adams Solver (FORTRAN) is to allow for
finding accelerations during an initial conditions solution or for reconciling integrator
Default: 25
Range: AMAXIT > 0
IC 153
APATTERN=c1 Specifies as many as ten character strings that together establish the pattern for evaluating
[:...:c10] the Jacobian matrix during the modified Newton-Raphson solution for the
accelerations. For each iteration, T or TRUE indicates that Adams Solver (FORTRAN)
is to evaluate the Jacobian, and F or FALSE indicates that Adams Solver (FORTRAN) is
not to evaluate the Jacobian. Thus, cj determines whether or not Adams is to evaluate the
Jacobian at the jth iteration. If necessary, Adams Solver (FORTRAN) repeats the pattern
of evaluation until it reaches the maximum number of iterations (AMAXIT). The
number of T's or TRUE’s and F’s or FALSE’s together must be at least one and no more
than 10.

ERROR= Specifies the maximum displacement error Adams Solver (FORTRAN) is to allow for
the assembly process.
Default: 1.0E-10
Range: ERROR > 0
MAXIT=i Specifies the maximum number of iterations Adams Solver (FORTRAN) is to allow for
finding displacements during initial conditions, or when reconciling integrator
displacement output.
Default: 25
Range: MAXIT > 0
154 Adams Solver
PATTERN=ci[:. Specifies as many as ten character strings that together establish the pattern for evaluating
..:c10] the Jacobian matrix during the modified Newton-Raphson solution for the
displacements. For each iteration, T or TRUE indicates that Adams Solver (FORTRAN)
is to evaluate the Jacobian, and F or FALSE indicates that Adams Solver (FORTRAN) is
not to evaluate the Jacobian. Thus, cj determines whether or not ADAMS is to evaluate
the Jacobian at the jth iteration. If necessary, Adams Solver (FORTRAN) repeats the
pattern of evaluation until it reaches the maximum number of iterations (MAXIT). The
number of T’s or TRUE’s and F’s or FALSE’s together must be at least one and no more
than 10.

TLIMIT=r Specifies the maximum translational increment Adams Solver (FORTRAN) is to allow

Range: TLIMIT > 0
VERROR=r Specifies the maximum velocity error that Adams Solver (FORTRAN) is to ignore
during an initial conditions solution. Adams Solver (FORTRAN) issues a warning if the
value of VERROR is exceeded. Adams Solver (FORTRAN) issues an error if
PREFERENCES/SIMFAIL=STOPCF is chosen.
Default: 1.0E-4
Range: VERROR > 0
Extended Definition
The IC statement specifies error tolerances and other parameters for the analysis of initial conditions and for
reconciling integrator output. By default, ABAM and WSTIFF reconcile integrator results to be consistent
with constraints; GSTIFF does not, unless you set INTERPOLATE=ON.
This statement is used only when requesting a dynamic, static equilibrium, or quasi-static equilibrium
analysis, and when one or more of the tolerances and other parameters for the initial conditions analysis from
the default values is to be changed.
Use the SIMULATE command to request a dynamic, static equilibrium, or quasi-static equilibrium analysis.
Before performing one of these analyses, Adams Solver (FORTRAN) automatically does an initial conditions
analysis. An initial conditions analysis is not necessary when the system has zero degrees of freedom because
the kinematics of the system fully determine its configuration.
The initial conditions analysis ensures that the system satisfies all constraints within the system. If necessary,
Adams Solver (FORTRAN) moves parts until both parts of each joint are in contact. This analysis involves
three separate phases. First, Adams Solver (FORTRAN) makes the displacements between all parts and joints
in the system physically consistent. This requires the use of Newton-Raphson iteration to solve a set of
nonlinear algebraic equations. Once the displacements are consistent, Adams Solver (FORTRAN) makes the
velocities physically consistent. Since this requires solving a set of linear equations, iteration is not necessary.
IC 155
Finally, Adams Solver (FORTRAN) also calculates consistent accelerations and forces. This solution also
requires solving a set of nonlinear equations using Newton-Raphson iteration.
When reconciling, the integrator uses the initial conditions solution process at each output step to ensure that
velocities, accelerations, and forces are consistent with the system constraints. If you set
INTERPOLATE=ON, the integrator also uses the initial conditions solution at each output step to ensure
displacements are consistent with the constraints. The IC parameters control those solutions as well as the
If you issue neither the IC command nor statement in an Adams Solver (FORTRAN) session, Adams Solver
(FORTRAN) uses the default values for AERROR, ALIMIT, AMAXIT, APATTERN, ERROR, MAXIT,
PATTERN, TLIMIT, and VERROR when finding initial conditions and reconciling integrator output.
Tip: Use the ALIMIT and TLIMIT arguments to limit incrementing displacement variables and
thus the size of the position change on successive iterations. This tends to prevent Adams
Solver (FORTRAN) from assembling the mechanism in an undesirable configuration.
Examples
IC/ALIMIT=10D, ERROR=1.0E-6, MAXIT=45
This statement instructs Adams Solver (FORTRAN) to use these values instead of the defaults when
performing an initial conditions analysis. It limits the angular increment per iteration to 10 degrees, reduces
the displacement error to less than 1.0E-6, and limits the number of iterations to 45.
156 Adams Solver
INTEGRATOR
The INTEGRATOR statement lets you control the numerical integration of the equations of motion for a
dynamic analysis. You should use the INTEGRATOR statement when the default values for the numerical
solution parameters are not optimal for a particular simulation.
Format
INTEGRATOR 157
Arguments
ABAM Specifies that the ABAM (Adams-Bashforth-Adams-Moulton) integrator is to be used

for integrating the differential equations of motion. This integrator is suitable for
systems that are not stiff, that is, systems that are characterized by a undamped
transients.
Default: GSTIFF
ADAPTIVITY=r All of the BDF integrators GSTIFF, WSTIFF, and CONSTANT_BDF) use Newton-
Raphson iterations to solve the nonlinear Differential-Algebraic Equations (DAE) of
motion. This iteration process is referred to as correcting the solution. ADAPTIVITY
modifies the corrector error tolerance to include a term that is inversely proportional
to the integration step size. This is intended to loosen the corrector tolerance when the
step size gets small (many corrector failures occur because of small step size). If the
integration step size is equal to h, ADAPTIVITY/h is added to the corrector tolerance.
When using ADAPTIVITY, begin with a small number, such as ADAPTIVITY=1E-

8. Note that this relaxes the tolerance of the corrector, which can introduce additional
error into the dynamic solution. The corrector tolerance must be at least a factor of 10
stricter than the integration tolerance. The ratio advocated in the theoretical literature
ranges from .1 to .001 and is a function of the integrator order and step size. The ratio
that Adams Solver (FORTRAN) uses varies with the integrator chosen, but is within
the range specified above. If you use ADAPTIVITY to relax the corrector tolerances,
be sure to validate your results by running another simulation using a different
integration error tolerance.
ADAPTIVITY affects only the GSTIFF, WSTIFF, and CONSTANT_BDF

integrators.
ADAPTIVITY is typically required to overcome corrector convergence difficulties

and you should not use it in normal situations.
Default: 0
Range: ADAPTIVITY > 0

CONSTANT_BDF Specifies that the CONSTANT_BDF integrator is to be used for integrating the
Default: GSTIFF
158 Adams Solver
Specifies the corrector algorithm that is to be used with the stiff integrators GSTIFF,
 ORIGNAL  WSTIFF, or CONSTANT_BDF. The corrector in a stiff integrator ensures that all
CORRECTOR =   candidate solutions satisfy the equations of the system. The two algorithms, original
 MODIFIED 
and modified, differ primarily in the algorithm that they use to define when the
corrector iterations have converged.

previous releases of Adams Solver (FORTRAN) be used. This is the default.
This implementation of the corrector requires that at convergence, the error
in all solution variables be less than the corrector error tolerance.
 CORRECTOR=modified - Specifies that a modified corrector is to be used.
This implementation of the corrector requires that at convergence, the error
in only those variables for which integration error is being monitored, be less
than the corrector error tolerance. This is a slightly looser definition of
convergence, and you should use proper care when using this.
The CORRECTOR=modified setting is helpful for models containing
discontinuities in the forcing functions. Problems with contacts belong in
this category.
Default: corrector=original
ERROR=r Specifies the relative and absolute local integration error tolerances that the integrator
must satisfy at each step. For BDF integrators, Adams Solver (FORTRAN) monitors
the integration errors in the displacement and state variables that the other differential
equations (DIFFs, LSEs, GSEs, and TFSISOs) define. ABAM, SI1, and SI2
formulations also monitor errors in velocity variables. The larger the ERROR, the
greater the error/step in your solution.
Note that the value for ERROR is units-sensitive. For example, if a system is modeled
in mm-kg-s units, the units of length must be in mm.
Assuming that all the translational states are larger than 1mm, setting ERROR=1E-3
implies that the integrator monitors all changes of the order of 1 micron.
difference between the current predicted and corrected states, the past history of the
states, and the current integration order.
Default: 1E-3
Range: ERROR > 0

INTEGRATOR 159
Default: 1/20 of the output step

Default: When setting the argument INTERPOLATE = ON, the integration step size
is limited to the value specified for HMAX, but if HMAX is not defined, no limit is
placed on the integration step size. If INTERPOLATE = OFF, the
Note: HMAX is not applicable to RKF45.

Default: 1.0E-6*HMAX for GSTIFF and WSTIFF. Machine precision for ABAM,
SI1, and the SI2 formulation

Specifies that the integrator is not required to control its step size to hit an output
 ON  point. Therefore, when the integrator crosses an output point, it computes a
INTERPOLATE =   preliminary solution by interpolating to the output point. It then refines or reconciles
 OFF 
the solution to satisfy the equations of motion and constraint. INTERPOLATE=OFF
turns off interpolation for the chosen integrator.
Default: OFF for GSTIFF and WSTIFF;

ON for ABAM
Note: Interpolation is not supported for CONSTANT_BDF or RKF45.

I3 Specifies the Index-3 (I3) formulation be used. For more information, see Extended
Definition.
Default: I3
160 Adams Solver
refers to the order of the polynomials used in the solution. The integrator controls the
order of the integration and the step size, and thus, controls the local integration error
at each step so that it is less than the error tolerance specified.
Note: For problems involving discontinuities, such as contacts, setting KMAX=2

can improve the speed of the solution. However, we do not recommend
Any modification can adversely affect the integrators accuracy and
robustness.
Default: KMAX = 12 (ABAM);
KMAX = 6 (GSTIFF, WSTIFF, and CONSTANT_BDF)
Range: 1 < KMAX < 12 (ABAM);

1 < KMAX < 6 (GSTIFF, WSTIFF, and CONSTANT_BDF)
Note: KMAX is not applicable to RKF45.
iterations to converge to the solution of the nonlinear equations. The correctors in
GSTIFF and WSTIFF use the Newton-Raphson iterations. ABAM also uses Newton-
Raphson iterations to solve for the dependent coordinates.
MAXIT should not be set larger than 10. This is because round-off errors start
becoming large when a large number of iterations are taken. This can cause an error
in the solution.
Default: 10
Range: MAXIT > 0

Newton-Raphson. A value of true (T) indicates that Adams Solver (FORTRAN) is
evaluating a new Jacobian matrix for that iteration. A value of false (F) indicates that
Adams Solver (FORTRAN) is using the previously calculated Jacobian matrix as an
PATTERN accepts a sequence of at least one character string and not more than 10
character strings. Each string must be either TRUE or FALSE, which you can
Default: T:F:F:F:T:F:F:F:T:F
Note: A pattern setting of all false, implies that Adams Solver (FORTRAN) is to
not evaluate the Jacobian until it encounters a corrector failure. For
problems that are almost linear or are linear, this setting can improve
INTEGRATOR 161
RKF45 Specifies that a Runge-Kutta-Fehlberg (4,5) method be used to integrate the

differential equations governing the system being modeled. RKF45 is a single-step
method unlike the BDF methods (GSTIFF, WSTIFF, or CONSTANT_BDF) or
ABAM. It is primarily designed to solve non-stiff and mildly stiff differential
equations when derivative evaluations are not expensive. In general, you should not
use it to get highly accurate results nor answers at a great many specific points.
Internally, RKF45 uses the DDERKF integrator written by L.F. Shampine and H.A.
Watts. DDERKF attempts to discover when it is not suitable for the task posed.
For more information, see the Extended Definition.

SCALE=r1[,r2][,r3] SCALE applies to only WSTIFF and ABAM. It is not applicable to GSTIFF and
CONSTANT_BDF.
SCALE scales the sum of the relative and absolute error tolerances. If T is the sum of
the relative and absolute error tolerances applied to the state vector, then the following
tolerance is applied:
 r1 * T to the translational displacements

 r2 * T to the angular displacements
 r3 * T to the modal coordinates
Note: By default, error tolerance is uniformly applied to all of the displacement
and angular coordinates.
Default:
 WSTIFF, ABAM, and RKF45: SCALE = 1, 1, 1e-3
 GSTIFF and CONSTANT_BDF: You cannot control SCALE
Range: SCALE [i] > 0 where i = 1, 2, or 3
162 Adams Solver
GSTIFF, WSTIFF, or CONSTANT_BDF integrator, be used for formulating and
equations of motion. In addition, it monitors the integration error on the impulse of
the Lagrange Multipliers in the system. These additional safeguards enable the
integrators to monitor the integrator error in velocity variables and the impulse of the
Lagrange Multipliers. Simulations results are therefore very accurate. A positive side
effect of the SI1 formulation is that the Jacobian matrix remains stable at small step
sizes, which in turn increases the stability and robustness of the corrector at small step
sizes.
Default: I3
GSTIFF or CONSTANT_BDF integrator, be used for formulating and integrating
equations of motion. This process enables the GSTIFF integrator to monitor the
integration error of velocity variables, and, therefore, renders highly accurate
remains stable at small step sizes, which in turn increases the stability and robustness
of the corrector at small step sizes.
The SI2 formulation is available only with GSTIFF, WSTIFF, and

CONSTANT_BDF.
Default: I3
equations of motion. WSTIFF uses the BDF method that takes step sizes into account
when calculating the coefficients for any particular integration order.
Default: GSTIFF
Extended Definition
You use the INTEGRATOR statement to select an integrator when you choose to perform a dynamic
analysis. The dynamic analysis of a mechanical system consists essentially of numerically integrating the
nonlinear differential equations of motion.
INTEGRATOR 163
Ordinary differential equations (ODEs) can be characterized as being stiff or non-stiff. A set of ODEs is said
to be stiff when it has widely separated eigenvalues (low and high frequencies) with the high frequency
eigenvalues being overdamped. Therefore, while the system has the ability to vibrate at high frequencies, it
usually does not because of the associated high damping, which dissipates this mode of motion.
The stiffness ratio of a set of ODEs is defined as the highest inactive frequency divided by the highest active
frequency. Stiff ODEs typically have a stiffness ratio of 200 or higher. In contrast, non-stiff systems have a
stiffness ratio less than 20. This basically means that for a non-stiff system of ODEs, the higher frequencies
of the system are active. The system can and does vibrate at these frequencies.
An example of a stiff system is a flexible body in which the higher frequencies have been damped out
completely, leaving only the lower frequency vibration modes active.
The system above becomes non-stiff if the higher frequencies are excited by an external force. Nonlinear
ODEs can be stiff at some points in time and non-stiff at other points.
Stiff and Non-Stiff Integrators
Integrators are classified as stiff or non-stiff. A stiff integrator is one that can handle numerically stiff systems
efficiently. For stiff integrators, the integration step is limited by the inverse of the highest active frequency
in the system. For non-stiff integrators, the integration step is limited by the inverse of the highest frequency
(active or inactive) in the system. Thus, non-stiff integrators are notoriously inefficient for solving stiff
problems.
Because many mechanical systems are numerically stiff, the default integrator in Adams Solver (C++) is GSTIFF,
a stiff integrator that is based on the DIFSUB integrator developed by C.W. Gear. The DIFSUB integrator
by C.W. Gear is unrelated to the Adams Solver subroutine that is known by the same acronym. Adams Solver
(FORTRAN) also provides two additional stiff integrators: CONSTANT_BDF and WSTIFF. All of these integrators
are based on Backward-Difference Formulae (BDF) and are multi-step integrators. The solution for these
integrators occurs in two phases: a Prediction followed by a Correction.
Note: If you are not sure whether your model is numerically stiff, you should avoid using ABAM or
RKF45. Instead, select GSTIFF or WSTIFF. If you incorrectly select ABAM for a stiff system, the
numerical method fails or becomes extremely slow.
Prediction
When taking a new step, the integrator fits a polynomial of a given order through the past values of each
system state, and then extrapolates them to the current time to perform a prediction. Standard techniques
like Taylor's series (GSTIFF) or Newton Divided Differences (WSTIFF) are used to perform the prediction.
Prediction is an explicit process in which only past values are considered, and is based on the premise that
past values are a good indicator of the current values being computed. The predicted value does not guarantee
that it will satisfy the equations of motion or constraint. It is simply an initial guess for starting the correction,
which ensures that the governing equations are satisfied.
The degree of polynomial used for prediction is called the order of the predictor. For example, a predictor of
order 3 will fit a cubic polynomial that includes the past 4 values for each state. Clearly, if the governing
164 Adams Solver
equations are smooth, the prediction will be quite accurate. On the other hand, if the governing equations
are not smooth, the prediction can be quite inaccurate.
Correction
The corrector formulae are an implicit set of difference relationships (BDFs) that relate the derivative of the
states at the current time to the values of the states themselves. This relationship transforms the nonlinear
differential algebraic equations to a set of nonlinear, algebraic difference equations in the system states. The
Backward Euler integrator is an example of a first-order BDF. Given a set of ODEs of the form dy/dt = f (y,t),
the Backward Euler uses the difference relationship:
y n + 1 = y n + hy· n + 1 (18)
where:
 yn is the solution calculated at t = tn.
 h is the step size being attempted.
 yn+1 is the solution at = tn+1, which is being computed.
Notice that the subscript n+1 is on both sides of Equation (18). This is an implicit method.
Adams Solver (FORTRAN) uses an iterative, quasi-Newton-Raphson algorithm to solve the difference
equations and obtain the values of the state variables. This algorithm ensures that the system states satisfy the
equations of motion and constraint. The Newton-Raphson iterations require a matrix of the partial
derivatives of the equations being solved with respect to the solution variables. This matrix, known as the
Jacobian matrix, is used at each iteration to calculate the corrections to the states.
Assume that the equations of motion have the form:
F (y,y· ,t) = 0 (19)

where y represents all the states of the system.
k k
Linearization of Equation (19) about an operating y = y and y· = y·
k k ∂F k ∂F k
gives: F (y,y· ,t) = F (y ,y· ,t) + ------ ( y – y ) + -----·- ( y· – y· ) = 0
∂y k ·k
∂y k · k
y ,y y ,y
k
replacing y - yk with Δy and ( y· – y· ) with Δy· , you get:
k k ∂F ∂F
F (y ,y· ,t) + ------ Δy + -----·- Δy· = 0 (20)
∂y ·k
∂y
y ,y·
k k k
y ,y
From Equation (18), which is a first-order BDF, you can get the relationship:
1
Δy· = --- Δy (21)
h
INTEGRATOR 165
∂-----
F- 1 ∂F k k
+ --- -----·- Δy = – F (y ,y· ,t) (22)
∂y ·k
h ∂y
y ,y·
k k k
y ,y
A generalization of (22)to higher-order BDFs gives:
∂-----
F- 1 ∂F k k
+ --------- -----·- Δy = – F (y ,y· ,t) (23)
∂y ·k
hβ 0 ∂y
y ,y·
k k k
y ,y
where:
β0
 scalar that is characteristic to an integration order. For each integration order this scalar is
constant.
 The matrix on the left side of Equation (23) is the Jacobian matrix of F.
 Δy are the corrections.
 F is the residue of equations (equation imbalances).
The corrector is said to have converged when the residue F and the corrections Δy have become small.
After the corrector has converged to a solution, the integrator estimates the local integration error in the
solution. This is usually a function of the difference between the predicted value and the corrected value, the
step size, and the order of the integrator. If the estimated error is greater than the specified integration
ERROR, the integrator rejects the solution and takes a smaller time step. If the estimated error is less than
the specified local integration ERROR, the integrator accepts the solution and takes a new time step. The
integrator repeats the prediction-correction-error estimation process until it reaches the time specified in the
SIMULATE command.
Note: The premise for using predictions as an initial guess for the corrector is severely violated when
discontinuities occur or when large forces turn on or off in the model. Contact, friction, and
state transitions (as in hydraulics where a valve is suddenly closed or opened) are examples of
such phenomena. These kinds of models are difficult for multi-step integrators.
GSTIFF
GSTIFF is based on the DIFSUB integrator. GSTIFF is the most widely-used and tested integrator in Adams
Solver (FORTRAN). It is a variable-order, variable-step and multi-step integrator with a maximum
integration order of six. The BDF coefficients it uses are calculated by assuming that the step size of the model
is mostly constant. Thus, when the step size changes in this integrator, a small error is introduced in the
solution. This formulation offers the following benefits and limitations:
Characteristics of GSTIFF Integrator
166 Adams Solver
Benefits: Limitations:
 Velocities and especially accelerations can have errors. An
 High speed. easy way to minimize these errors is to control HMAX so
that the integrator runs at a constant step size and runs
 High accuracy of the system consistently at a high order (three or more).
displacements.
 You can encounter corrector failures at small step sizes.
 Robust in handling a variety of These occur because the Jacobian matrix is a function of
analysis problems. the inverse of the step size and becomes ill-conditioned at
small steps.
References
For more information on the GSTIFF integrator, see:
 Gear, C.W. (1971a). The Simultaneous Solution of Differential Algebraic Systems. IEEE Transactions
on Circuit Theory,
CT-18, No.1, 89-95.
 Gear, C.W. (1971b). Numerical Initial Value Problems in Ordinary Differential Equations. New
Jersey: Prentice-Hall.
CONSTANT_BDF
CONSTANT_BDF is a modification of the DIFSUB integrator, to make it behave like a stable, fixed-step
integrator. It is a variable-order, predominantly fixed-step, multi-step integrator, with a maximum order of
six. Because it is a BDF method, it is stiffly stable, that is, it can solve stiff problems efficiently without
becoming unstable.
The maximum integrator step size, HMAX, controls the integration error in CONSTANT_BDF.
CONSTANT_BDF does not attempt to calculate the local integration error. If the corrector has converged,
CONSTANT_BDF assumes that the solution is correct. The step size is fixed at HMAX. The integrator
order is gradually increased up to KMAX. In this regard, it is very much like a fixed-step integrator.
If the corrector fails to converge, CONSTANT_BDF reduces the step size until the corrector converges.
CONSTANT_BDF restores the step size to HMAX every 25 steps. CONSTANT_BDF works with both the
Index-3 (I3) and the Stabilized Index-2 (SI2) formulations. We recommend that you use the SI2 formulation
wherever possible because it is much more stable. Like GSTIFF, CONSTANT_BDF also works with the
modified corrector, which can handle discontinuities much more effectively. To use the modified corrector,
choose corrector=modified in the INTEGRATOR statement.
Unlike GSTIFF or WSTIFF, CONSTANT_BDF tends to run at the maximum allowable KMAX. A high
integration order implies greater accuracy. Coupled with explicit step size control, the use of a high integrator
order normally results in quite accurate solutions. If your answers do not seem to be accurate, decrease
HMAX. This will give you better answers. We recommend that you scale down HMAX gradually in factors
of two, because simulation times can increase when you reduce HMAX.
All integration control parameters available for GSTIFF are also available for CONSTANT_BDF.
The table below summarizes the benefits and limitations of the CONSTANT_BDF integrator.
INTEGRATOR 167
Characteristics of CONSTANT_BDF Integrator
Benefits: Limitations:
Is very robust and stable at small step sizes when Not as fast as GSTIFF or WSTIFF for many
used with the SI2 formulation. simulations.
Can solve problems where GSTIFF might fail. Too large of a value for HMAX results in inaccurate
answers.
Is not as susceptible to spikes in accelerations and Too small of a value for HMAX results in slow
forces as GSTIFF. simulations.
High accuracy in system displacements and 000
velocities.
SI2
SI2 (Stabilized-Index Two) is an equation formulation technique that can be used for equations describing
mechanical systems. Currently, this formulation is available only with GSTIFF, WSTIFF, and
CONSTANT_BDF.
To understand what the SI2 formulation does, you need to know what Differential Algebraic Equations
(DAE) are and understand the notions of Index of a DAE and stabilization of DAE. A brief summary is given
below. For more information, refer to:
 Brenan, K.E., Campbell, S.I., and Perzold, L.R. (1996). Numerical Solution of Initial Value Problems
in Differential-Algebraic Equations, Classics in Applied Mathematics.
ISBN: 0-89871-353-6 (pbk.)
ODEs Versus DAEs
E = y· – f ( y ,t ) = 0, y ( 0 ) = y 0 (24)
is defined to be a set of ODEs, because y· are explicit in Equation (24).
∂E
Notice that for ODEs, -----·-
= I , and is never singular.
∂y
In contrast, DAEs are usually written as:
E = F ( y· ,y ,t ) = 0, y ( 0 ) = y 0 (25)
∂E
It is an intrinsic property of DAE that the matrix -----·- is singular. Another way of stating this is that some of
∂y
the equations in a set of DAEs are not differential equations at all, they are algebraic equations of constraint.
In Adams Solver (C++), the equations of a mechanical system are formulated as:
T T
Mq·· + φ q λ – A F (q,q· ) = 0 (26)
168 Adams Solver
φ (q,t) = 0 (27)
where:
 M is the mass matrix of the system.
 q is the set of coordinates used to represent displacements.
 φ is the set of configuration and applied motion constraints.
 F is the set of applied forces and gyroscopic terms of the inertia forces.
 AT is the matrix that projects the applied forces in the direction q.
 φ q is the gradient of the constraints at any given state and can be thought of as the normal to the
constraint surface in configuration space.
Notice that Equation (26) is a second-order differential equation but Equation (27) is an algebraic equation.
Also notice the time derivatives of q are seen in Equations (26), but λ is not present in either Equation (26)
or (27).
These are typical characteristics of DAEs.

Index of a DAE
The index of a DAE is defined as the number of time derivatives required to convert a set of DAEs to Odes
Equations (26) can be converted to a set of ODE by first taking two time derivatives of the kinematic position
constraint equations in Eq.(27), to obtain the set of kinematic acceleration constraint equations. These
equations together with the equations of motion in Eq.(26) can be formally solved for the accelerations and
the Lagrange multipliers λ . By taking a third and last time derivative of the Lagrange multipliers, one is left
with a set of ODE in accelerations and the Lagrange multipliers.
Therefore, the Euler-Lagrange equations for mechanical systems are said to have an Index=3.
Solution of DAEs
Equations (26) are converted to first-order form, so that commercially available DAE integrators can solve
them. This is usually done by introducing a new variable, the velocity variable u, which is defined as:
u – q· = 0 (28)
T T
Mu· + φ q λ – A F = 0 (29)
u – q· = 0 (30)
φ = 0 (31)
These are the DAE (in first order form) for a mechanical system. Applying the BDF formula (like Equation
(21)), one obtains the Jacobian of Equation (29):
INTEGRATOR 169
M
--------- – A T F U T T
M q u· + φ qq λ – ( A F )
T
φq
hβ 0
I
I – --------- 0
hβ 0
0 φq 0
This matrix becomes ill conditioned as the integration step size h decreases, and becomes singular as h moves
closer to 0.
This is the reason why Index 3 formulations become unstable at small step sizes -- a very counter-intuitive
result.
Another important result for Index 3 formulations is that the integration error cannot be monitored on either
velocities, u, or reaction forces, λ .
Index reduction methods (IRM) are typically employed to make DAE more easily solvable by numerical
methods. The key benefit to using IRM is that the integration error can be monitored on velocities.
Index Reduction Methods
There are many ways to reduce the index of a DAE. In general, the lower the index of a DAE, the more
theoretically tractable it is to being numerically solved. So in general, it is a good idea to try to reduce the
index of a DAE.
One common approach is to replace Equation (31) with the time derivatives of the constraint. Every level of
differentiation reduces the index by one.
For example, you might be tempted to reduce the Index of Equation (29) to two by differentiating (31):
T T
Mu· + φ q λ – A F = 0
T
u – q· + φ q μ = 0 (32)
·
φ ( q ,u ,t ) = 0
φ (q,t) = 0
Solving Equations (32) numerically adds a new complication, however. The solution satisfies Equation (32),
but is not guaranteed to solve Equation (29), the original constraint.
If you were to formulate a simple pendulum using Equations (32) and solve them, you would notice that after
some time the pin-joint constraint is violated and the pendulum drifts off into space, grossly violating the
pin-joint, and the system Equation (32) is not aware.
Clearly, a means for considering Equation (31) along with Equations (32) to prevent drift-off is required. The
SI2 formulation does precisely this.
The SI2 Formulation
170 Adams Solver
Gear, Gupta, and Leimkuhler have shown that drift-off can be prevented by appending Equation (29) to (32)
and adding a new set of variable as follows:
T T
Mu· + φ q λ – A F = 0
T
u – q· + φ q μ = 0 (33)
·
φ ( q ,u ,t ) = 0
φ (q,t) = 0
·
The numerical solution of Equations (33) are guaranteed to satisfy both φ and φ . In this sense, the Equations
(33) are stabilized. Because the constraints φ have been differentiated once, Equation (33) has an Index = 2.
Equations (33) are called the Stabilized Index Two representation of Equations (30). It has been proven
rigorously that Equation (33) and Equation (30) have the same solution when μ = 0. This condition is
rigorously enforced by the SI2 formulation in Adams Solver (FORTRAN).
It can also be shown that the Jacobian of Equation (33) does not become ill-conditioned as h moves closer to
0. Furthermore, since Equation (33) has an Index of 2, the integrators can monitor integration error on both
u and q.
··
You can then, in principle, append the second time derivative of the constraints, φ ( q, u, u· , t ) = 0 to
Equation (33) and introduce yet another set of variables η to reduce the index of Equations (33) to one (SI1).
We have found this to be computationally very expensive and not much more accurate than the SI2
formulation.
There is, however, an alternative method for implementing the SI1 formulation that is promising.
Benefits and Limitations
The benefits and limitations of the S12 formulation are described in the following table:
Characteristics of the SI2 Formulation
INTEGRATOR 171
Benefits of the SI2 formulation: Limitations of the SI2 formulation:

 Gives very accurate results, especially for  Is typically 25% to 100% slower for most
velocities and accelerations. problems than regular GSTIFF, when run
 Usually allows an ERROR that is approximately with the same error.
10 to 100 times larger than regular GSTIFF to  Requires that all velocity inputs be
produce the same quality of results. differentiable. Therefore, you must define
 Is very robust and stable at small step sizes. your MOTIONS so that they are smooth
and twice differentiable. Non-smooth
 Corrector failures that small step sizes cause
motions, which theoretically cause
occur less frequently than with the Index-3
infinite accelerations, cause failures in the
GSTIFF formulation.
SI2 formulation. The I3 formulations can
 Singular matrices due to small step sizes occur sometimes handle such models.
less frequently than with the Index-3 GSTIFF
 Displacement MOTIONS cannot be
formulation.
functions of VARIABLES. When Adams
 Corrector failures are typically indicative of a Solver encounters models containing such
modeling problem and not of a numerical MOTIONS, it automatically switches to
deficiency in the Adams Solver software. the SI3 formulation (velocity- and
 Tracks high frequency oscillations very acceleration-based motions can be
accurately. functions of VARIABLES).
SI1 Formulation
The version of SI1 implemented in Adams Solver does not use the second-time derivative of the
··
constraints, φ ( q, u, u· , t ) = 0 , because this is computationally very expensive.
Instead, it uses a change of variables to reduce the index. The Lagrange Multipliers λ and μ in Equations
(33) are replaced by new variables
·
η = λ and ζ = μ . Therefore, Equations (33) with the new variables becomes:
T· T
Mu· + φ q η – A F = 0
T
u – q· + φ q ζ = 0 (34)
·
φ ( q ,u ,t ) = 0
φ (q,t) = 0
This change of variables has effectively reduced the index of Equations (34) to 1. This is because we only need
·
to differentiate the velocity constraint equation once to explicitly calculate expressions for η and ζ .
Using the SI1 formulation, you can now monitor the integration error in η and ζ . η and ζ are defined
as the impulse associated with λ and μ , respectively. That is:
172 Adams Solver
η =  λ dt (35)
ζ =  μ dt
Therefore, in the SI1 formulation, the integration error can be monitored on all states (q, u, η , and ζ ).
In this respect, the SI1 formulation is even more accurate than the SI2 formulation.
In practice, we have observed that, for most models, SI1 and SI2 give the same quality of answers. However,
system accelerations (that is ς ) tend to be more accurate with the SI1 formulation. The performance of the
SI1 formulation is also quite comparable to the SI2 formulation for many classes of models. The SI1
formulation is more sensitive and finicky for models containing significant contact or friction.
References
For more information on the SI1 and SI2 formulations, see:
 Brenan, K.E., Campbell, S.L, & Petzold, L.R. (1996). Numerical Solution of Initial-Value Problems
in Differential-Algebraic Equations (Classics in Applied Mathematics, 14). Society for Industrial &
Applied Mathematics; ISBN: 0898713536 (pbk).
 Gear, C.W., Leimkuhler, B., Gupta, G.K. Automatic Integration of Euler-Lagrange Equations with
Constaints. Journal of Computation and Applied Mathematics, 12 & 13, pp. 79-90, North-
Holland: 1985.
 Orlandea, N.V. A study of the effects of the lower index methods on ADAMS sparse tableau formulation
for the computational dynamics of multi-body mechanical systems, IMechE Proc Instn Mech Engrs V01
213 Part K: 1999 1-9
WSTIFF
WSTIFF is a stiffly stable, BDF-based, variable-order, variable-step, multi-step integrator. It has a maximum
order of six. The BDF coefficients it uses are a function of the integrator step size. Thus, when the step size
changes in this integrator, the BDF coefficients change. WSTIFF can change step size without any loss of
accuracy, which helps problems run more smoothly. The benefits and limitations of WSTIFF are the same as
those of GSTIFF and are listed in the Characteristics of GSTIFF Integrator table.
References
For information on the WSTIFF integrator, see the paper:
 Van Bokhoven, W.M.G. (1975, February). Linear Implicit Differentiation Formulas of Variable
Step and Order. IEEE Transactions on Circuits and Systems, 22 (2).
ABAM
ABAM (Adams Bashforth-Adams Moulton) is a non-stiff integrator based on a code originally written by
Laurence F. Shampine and Marilyn K. Gordon.
ABAM is a multi-step, variable-order, variable-step integrator that has a maximum order of 12. ABAM uses
a PECE (Predict-Evaluate-Correct-Evaluate) scheme to integrate a set of ordinary differential equations.
INTEGRATOR 173
ABAM may be better for simulating systems that undergo sudden changes (non-stiff systems) or for those
with active, high frequencies. The easiest way to know that your system is not numerically stiff is to check
that its high frequencies are underdamped. If they are, you can select ABAM. The command
LINEAR/EIGEN calculates the eigenvalues for any system at a given configuration.
ABAM uses coordinate partitioning, which is a method of eliminating constraint equations, such as the ones
induced by joints, from the equations of motion. This method reduces the entire system of differential
algebraic equations (DAEs) to a condensed set of ordinary differential equations (ODEs). It does so by
selecting the coordinates (degrees of freedom) that will change the most during the simulation as the
independent coordinates. Only these coordinates are integrated. All other dependent coordinates in the
system can be expressed as algebraic functions of the independent coordinates through the constraints. After
each successful integration step, the coordinate-partitioning algorithm computes the dependent
displacements, their time derivatives, and the accelerations and Lagrange multipliers (constraint reactions).
During this process, Adams Solver (FORTRAN) holds the independent coordinates constant and employs a
Newton-Raphson iteration scheme to find the dependent coordinates. After computing the dependent
velocities from the independent values, Adams Solver (FORTRAN) uses the Newton-Raphson algorithm
again to find the full set of accelerations and Lagrange multipliers (constraint forces).
The displacement solution for the full set of dependent and independent coordinates provides the
appropriate matrix for Adams Solver (FORTRAN) to explicitly solve for the velocities of the dependent
coordinates. When the integrator has a complete set of displacements, velocities, accelerations, and Lagrange
multipliers, it is ready to begin the next integration step.
GSTIFF, WSTIFF, and CONSTANT_BDF control only errors in displacements and user-defined variables
that are specified in differential equations. This solution method is guaranteed to satisfy the equations of
constraint and the equations of motion. It is not guaranteed to satisfy the first and second time derivatives of
the constraint equations. This solution method usually leads to acceptable accuracy in the velocity,
acceleration, and force results. However, you may find cases when the velocity, acceleration, or force results
are not acceptable, even when ERROR is set appropriately and the displacement results are accurate. In these
cases, you may improve accuracy by using the HMAX argument, which lets you directly limit the size of the
integration steps.
The SI2 formulation and ABAM control errors in all displacements, velocities, and user-defined variables that
are specified in differential equations. This solution method is guaranteed to satisfy the equations of motion,
and the equations of constraint and their first time derivative. ABAM also satisfies the second time derivative
of the equations of motion. This leads to increased accuracy in the velocity, acceleration, and force results,
but can slow down the simulation.
Caution: The ABAM integrator does not support the VELOCITY and ACCELERATION arguments
on the MOTION statement.
References
For more information on the methods used in the ABAM integrator, see:
 Shampine, L.F., Gordon, M.K. (1974). Computer Solutions of Ordinary Differential Equations. W.
H. Freeman and Co.
174 Adams Solver
For more information on coordinate partitioning and projection methods in general, see:
 Wehage, R.A. and Haug, E.J. (1982). Generalized Coordinate Partitioning for Dimension
Reduction in Analysis of Constrained Dynamic Systems. Journal of Mechanical Design, Vol. 104.
No. 1,247 - 255.
RKF45
RKF45 (Runge-Kutta-Fehlberg 4-5) is a single-step integrator that is based on DDERKF, originally
implemented by Lawrence F. Shampine and H.A. Watts.
The Runge-Kutta-Fehlberg (RKF) methods are an extension of the traditional Runge-Kutta (RK) methods.
The innovation of the RKF methods is that the local truncation error per step is computed by comparing the
calculated answer yn+1 (at t = tn+1) with the result of an associated higher-order RK formula.
Therefore, in a 4-5 method, the error in the fourth-order RK method is estimated by subtracting it from the
value obtained by a fifth-order RK method.
The method may be briefly summarized as follows:
Assume that we are trying to solve the differential equations:
y' = f ( x, y ), y ( x o ) = y o (36)
consieder the steps to be taken to proceed the integration from x = x n to x = x n + 1 . Let: (37)
 y n be the solution at x = x n
 h n be the integration step_size ( x n + 1 – x n )
Now define:
V 1 = f ( x n, y n )
 j–1 
V j = f x n + α j h, y n +  β ji V i

 
 i=1 
The fourth and fifth-order formulas are, respectivly:
5
yn + 1 = yn + h  γi Vi (order 4)
i=1
6
ˆ
ŷ n + 1 = y n + y n + 1  γ i V i (order 5)
i=1
INTEGRATOR 175
The truncation error in y n + 1 is approximated by:

6
trunc = ŷ n + 1 – y n + 1 = h  C j V j
j=1
·
The coefficients α j, β j, γ j, γ j and C j are property of the method and are known as prion.
RKF45 is primarily designed to solve non-stiff and mildly stiff differential equations, where the derivative
evaluations are not expensive (time consuming). In the formulation used in Adams Solver, the derivative
evaluation is expensive. Consequently, RKF45 is usually not very fast. In our testing, RKF45 is about five
times slower than ABAM for most models. RKF45 is a good addition to the suite of integrators in Adams,
because, unlike all the others, it is a single-step integrator, and therefore, fundamentally different.
RKF45 can only handle ordinary differential equations (ODE), and not DAE. Therefore, the DAE
corresponding to the model needs to be transformed to ODE.
Like ABAM, RKF45 uses coordinate partitioning to convert the DAE into ODE. For more information
about coordinate partitioning, see the third paragraph in the description of ABAM above.
References
For more information on the implementation of RKF45, see:
 SAND-79-2374, DEPAC - Design of a User Oriented Package of ODE Solvers, H.A. Watts and L.F.
Shampine, Sandia Laboratories, Albuquerque, New Mexico.
Error in Handling Simulations
The following sections include descriptions and work-arounds for common error conditions you might
encounter during a simulation. The sections include:
 Integration Failures
 Corrector Failures
 Integration Restarts
 Singular Matrices and Symbolic Refactorization
Integration Failures
An integration failure is the condition when the integrator calculates a solution, but then rejects it because it
does not meet the accuracy requirements you specified. Because all integrators attempt to take the largest time
step possible, failure is a fairly routine occurrence and is not cause for concern. Integrators can automatically
decrease the step size and/or integrator order and repeat the step. Integration failures in multi-step methods
are caused when the predictor and corrector give different answers. Such a situation can occur often when a
force is suddenly turned on or off, thus, causing a discontinuity in the solution. For this reason, past values
are not a good indicator of current values. The following tips can help you avoid integration failure:
 When modeling, be sure that all motion inputs, user-defined forces, and user-written differential
equations are both continuous and differentiable. The smoother a function is, the easier it is to
integrate. Always use a STEP or STEP5 function to switch a signal on or off, instead of using IF
logic.
176 Adams Solver
 Remember that cubic SPLINEs can only guarantee first-order differentiability. Inputting a SPLINE
through a displacement-based MOTION causes accelerations to be spiky. Therefore, input the
SPLINE in a velocity-based MOTION.
 For greater simulation control, use HMAX to control the maximum step size that the integrator can
take. HMAX enables the integrator to reach higher orders and maintain them consistently.
 Be careful when using non-differentiable intrinsic functions, such as IF, MIN, MAX, SIGN, MOD,
and DIM. These functions can give discontinuous answers and can cause integrator problems. The
integration failure diagnostic identifies the variable and its parent modeling element with the most
error in it. Examine the entities that connect to the parent modeling element to see if you can
identify the cause of the failure.
Corrector Failures
A corrector failure occurs when the Newton-Raphson iterations in the correction phase do not converge to a
solution. Corrector failure occurs if the predictor cannot provide a reasonable initial guess and the equations
themselves are not smooth, as the Newton-Raphson algorithm assumes. A corrector failure is a fairly severe
event that you should avoid by changing your model. Some tips to help avoid corrector failure are:
 As with preventing integrator failures, be sure that all motion inputs, user-defined forces, user-
written differential equations, and user-defined algebraic variables are both continuous and
differentiable. The smoother a function is, the easier it is to solve for it. Use a STEP or STEP5
function to switch a signal on or off instead of using IF logic.
 Use the ERROR keyword to loosen the integration error. Loosening the value for ERROR also
decreases the tolerance that the corrector is required to meet.
 Use the SI2 formulation and see if the failures go away.
 Use the new corrector. Set the environment variable MDI_ADAMS_NEWCOR to TRUE and re-
run your simulations.
 As a last resort, use the ADAPTIVITY keyword to force the system to loosen its corrector-error
tolerance.
 Here are some diagnostic techniques for identifying the cause of some failures:
 Examine the EPRINT output from DEBUG to identify the modeling entities that are having the
greatest difficulty converging.
 If the modeling element is a force:
• Make sure that the force law it obeys is smooth.
• Examine the stiffness of the force entity. Reduce it if necessary to overcome the failures.
• Examine the damping of the force entity. Damping is usually less than 5% of the stiffness. Large
values of damping can also cause failures.
• If the modeling element causing the corrector failures is an equation of force/torque balance for a
PART, POINT_MASS, or FLEX_BODY, try to identify the entities that may be applying
anomalous forces on the body.
Look at the accelerations of the body. A large acceleration in a certain direction is always caused
by a large force in that direction. Try to identify the modeling element that is causing the large
acceleration, examine how it is defined, and try to understand why it is applying a large force.
INTEGRATOR 177
• If the modeling element is a CONTACT, review the stiffness, damping, and frictional properties
of the contact. Reducing stiffness and damping helps. Similarly, increasing stiction and dynamic
friction transition velocities can help the integrator.
• If the modeling element is a FRICTION entity, increasing the stiction and dynamic friction
transition velocities usually helps. Evaluate the effect of reducing the friction coefficients and the
pre-load.
• If the modeling element is a DIFF or GSE, make sure that the derivatives you are defining have
reasonable values. Large derivatives cause problems. Make sure that the constitutive equations are
smooth (differentiable) and that they do not have any kinks.
• If the modeling element is a redundant constraint, this implies that Adams Solver is having
difficulty satisfying the constraint. The most likely cause for such a failure is an inconsistently
defined or ill-behaved model. Eliminate the inconsistency.
• If the modeling element is a constraint reaction, try to identify the applied force or torque that is
trying to break the constraint.
Integration Restarts
An integration restart is when the integrator fails to take a new step successfully. Adams Solver (FORTRAN)
calculates a new and consistent set of initial conditions at the point of failure and the solution progresses with
this new set of initial conditions. A restart occurs if the integrator encounters several consecutive integration
failures and/or corrector failures while attempting a new step. Integration restart is usually indicative of
discontinuous equations describing the system. To help avoid integration restart, you can:
 Increase ERROR value. Integration restarts sometimes occur simply because the value specified for
ERROR is too small.
 Identify modeling problems in your system. Typically, a single modeling element dominates an
integrator or corrector error. Identify that element and see why it may be causing problems.
Smoothen its definition if there is a function expression or user subroutine associated with it. For
more information on how to diagnose modeling problems, see Corrector Failures.
 Use the CONSTANT_BDF integrator, and see if the problem goes away. Step size change can
destabilize correctors that assume predominantly fixed step sizes, by introducing a small error in the
solution when the step size changes.
Singular Matrices and Symbolic Refactorization
A singular matrix condition occurs when the Jacobian matrix is not invertible. Recall that the corrector needs
to invert the Jacobian matrix during its iterations to solve a set of linearized algebraic equations. (See
Correction). A scalar analogy to a singular matrix is a divide-by-zero situation. Adams Solver (FORTRAN) does
not actually invert the matrix, but calculates the matrixes Lower and Upper triangular factors (LU factors).
This method of computation is very efficient and is equivalent to an inversion.
Given a Jacobian matrix, Adams Solver (FORTRAN) calculates and stores the LU factors in a symbolic form.
In other words, Adams Solver (FORTRAN) explicitly calculates the LU factors as a function of the values in
the Jacobian matrix. Adams Solver (FORTRAN) also assumes that the pivots are never zero. (Pivots are
chosen during the Gaussian elimination and are used to factorize the matrix.) Because the equations being
solved are nonlinear, it is likely that a set of pivots chosen earlier may not be optimal. Some of the pivots may
become small or even zero. This event is known as the singular matrix condition. When Adams Solver
178 Adams Solver
(FORTRAN) encounters this condition, it recalculates the symbolic LU factors for the Jacobian matrix using
the current values of the state variables. This process is known as symbolic refactorization.
Occasional occurrences with singular matrixes and symbolic refactorization are normal and are no cause for
alarm. However, if these events occur frequently, you should examine your model. The typical causes for
singular matrices are:
 A mass or inertia component is not specified.
 The system has reached a locked configuration, that is, it can no longer move without violating one
of its constraints.
 A large force or moment has been suddenly turned on or off.
 The integrator is forced to take an extremely small step because of a hidden discontinuity in an
element described in a user-written subroutine. IF statements, as well as non-differentiable intrinsic
functions, such as SIGN, MOD, MIN, MAX, and so on, can create non-differentiable or even
discontinuous descriptions of modeling elements. Be very careful when using these aspects of a
programming language.
Common causes for singular matrices or symbolic refactorization are:
 Large force suddenly turns on. The large force is usually associated with a high stiffness. A large
stiffness causes the Jacobian to become ill-conditioned.
 Your mechanical system may be in a lockup or bifurcation configuration.
 The integrator step size is too small for the I3 formulation. Switch to the SI2 formulation if you
notice this.
The Index-3 Jacobian matrix (see Equation 6) contains some terms that are inversely proportional to the step
size being taken. As the step size shrinks, these terms grow large. In fact, they grow so large that they eclipse
all other entries in the matrix. Computers typically have difficulty dealing with matrices that have entries
spanning a large range. The smaller numbers consequently get lost in round-off error, and, thus, cause
singular or ill-conditioned matrices to occur. The root cause for these problems is that the step size is very
small. The solution is to understand why the step size is so small, and modify the model accordingly.
Discontinuities are prime causes for problems related to small steps sizes. Eliminating the discontinuities
causes the integrator to take larger steps, and, therefore, avoid fatal singular matrix condition. Using the SI2
formulation can also help solve this problem.
Choosing and Integration Error
The integration ERROR is a key parameter that you need to specify for a simulation. The following are three
options for calculating a reasonable value for ERROR:
For I3 formulation with GSTIFF and WSTIFF:
ERROR = VEPS *(6*Nb + 3*Np + Nu + 2*Nm)
For SI2 formulation with GSTIFF:
ERROR= K * VEPS * (12*Nb + 6*Np + Nu + 2*Nm)
For ABAM:
ERROR= K * VEPS *(2*Ndof+Nu)
where:
INTEGRATOR 179
 VEPS is the desired error per variable per integration step.

 Nb is the number of rigid bodies in the model (excluding GROUND).
 Np is the number of point masses in the system.
 Nu is the number of user-defined differential equations in the system (DIFFs+LSEs+GSEs).
 Nm is the total number of modal coordinates in the system:
• K =10 (for smooth problems).
• K =100 (for impact and friction problems).
 Ndof = total number of mechanical degrees of freedom.
All integrators require that you input a value, referred to as ERROR in this guide, that specifies the degree of
accuracy you want to achieve in a simulation. ERROR is the maximum error allowed per integration step for
the entire system. This can be confusing in Adams Solver (FORTRAN) because some of the ERROR states
are displacements, some are velocities, and others may be user-defined states (for example, pressure, and
temperature).
In Adams Solver (FORTRAN), integration ERROR is the difference between the exact solution f(t) and the
approximate solution p(t) being calculated. The difference, f(t)-p(t), is the truncation error. The higher the
integrator order, the smaller the truncation error.
For displacement variables, the truncation error has units of length. For velocities, the truncation error has
units of velocities. For example, if you are working in millimeters, your maximum error tolerance would be
smaller than 1 micron. Then, for each variable, you would have an error of 0.001 mm.
You find the error per step by estimating the total number of integration steps, and then dividing the error
per variable by the estimated number. Thus, if you estimate that you need 100 integration steps, the error per
step, VEPS, is 0.00001 mm. This is always a conservative calculation (sometimes too conservative) because
errors tend to be random and typically cancel each other out. The calculation shown earlier assumes the worst
case scenario, where the errors are always additive. You should use the information shown here as a guide, not
as a rule, for setting ERROR.
Velocities must be treated in the same way as displacements. However, keep in mind that the errors in the
derivatives are higher, and, if you impose an error on the velocities that are identical to the errors on the
displacements, you force a larger number of iterations per step to occur, which increases the simulation time.
In general, if an error-control exists on velocities, such as in SI2 and ABAM, then the errors computed for
the displacements can be increased by a factor of 10 and can also be applied for velocities.
Modal coordinates have small values, and, therefore, to be able to accurately capture their effects, you may
need to tighten the ERROR parameter. Typically, when the rigid body displacements and velocities are
accurate, then the modal coordinates and velocities are also fairly accurate.
180 Adams Solver
Note: Setting the environment variable MSC_ADAMS_SOLVER_INTERPOLATE_ADAPTIVE

follows:

spaced times.
Tip:  GSTIFF and WSTIFF control errors specifically in displacements and user-defined
differential variables, and, therefore, yield acceptable accuracy in velocity,
acceleration, and force results. However, in some cases, the acceleration and force
results might not be acceptable, even when ERROR is set appropriately and the
displacement results are accurate. In these cases, use the HMAX argument to directly
limit the size of the integration steps.
 Using the PATTERN argument to request more frequent evaluations of the Jacobian
matrix can improve convergence rates. However, this can also increase the
computation time.
 For kinematic (zero-DOF) systems, a kinematic analysis is usually faster and less
expensive than a dynamic analysis. However, to force the integration of a kinematic
system, use GSTIFF or WSTIFF. Coordinate partitioning cannot be applied to a
kinematic system.
Caution: GSTIFF might introduce discontinuities in velocities and accelerations when the integration
step size changes. Most of the time, these discontinuities are within the error tolerance and
disappear quickly. Use the INTERPOLATE argument to eliminate these discontinuities.
Alternatively, you can control the step size using the HMAX argument, which helps make the
step sizes nearly constant.
Examples
INTEGRATOR/SI2, GSTIFF, ERROR=1.0E-4, HINIT=1.0E-6
INTEGRATOR 181
This integrator statement specifies that dynamic simulations be run using the SI2 equation formulation
combined with the GSTIFF integrator. This solution has an error limit of 1.0E-4. The integrator is to take
an initial step of 1.0E-6.
182 Adams Solver
JOINT
The JOINT statement describes a physically recognizable combination of constraints that are used to connect
bodies (rigid and flexible) together. Examples of joints include constant-velocity, cylindrical, fixed, Hooke,
planar, rack-and-pinion, revolute, screw, spherical, translational, and universal joints.
Format
JOINT 183
Arguments
CONVEL Indicates the joint is a two-degree-of-freedom joint that allows rotation about
two axes: the zi and zj axes (see the figure below).
For the CONVEL joint, Adams Solver (FORTRAN) superimposes the

origins of the I and J markers and constrains the rotation about the z-axis of
the I marker to be equal and opposite to the rotation about the z-axis of the J
marker. When connecting two shafts, the z-axes of the I and J markers should
point down the shafts, away from the center of the joint. Additionally, the
angle between the x-axis of the I marker and the y-axis of the J marker must
be the same as the angle between the y-axis of the I marker and the x-axis of
the J marker. The easiest way to ensure the x and y axes are properly aligned
is to make the I and J x-axes parallel, or the I and J y-axes parallel.
Convel Joint
CYLINDRICAL Indicates that the joint is a two-degree-of-freedom joint that allows both
relative translational and relative rotational displacement of one part with
respect to another (see the figure below). I marker translation along the zj axis
and rotation about the zj axis are permitted.
For the CYLINDRICAL joint, Adams Solver (FORTRAN) keeps the z-axis
of the I marker parallel to, and co-directed with, the z-axis of the J marker and
confines the origin of the I marker to the z-axis of the J marker so that the I
and J markers have a common z-axis. To determine translational motion,
Adams Solver (FORTRAN) measures the movement of the origin of the I
marker along the z-axis and with respect to the J marker. To determine
rotational motion, Adams Solver (FORTRAN) measures the rotation of the
x-axis of the I marker about the common z-axis and with respect to the x-axis
of the J marker.
184 Adams Solver
Cylindrical Joint
FIXED Indicates the joint is a zero-degree-of-freedom joint that completely locks the
I and J markers together (see the figure below).
For the FIXED joint, Adams Solver (FORTRAN) superimposes the origins
and the axes of the I and J markers, allowing no relative motion.
Fixed Joint
HOOKE Indicates the joint is a two-degree-of-freedom joint that allows rotation about
two axes: xi, the x-axis of the I marker and yj, the y-axis of the J marker (see
the figure below).
For the HOOKE joint, Adams Solver (FORTRAN) superimposes the origins
of the I and J markers and constraint markers. It also keeps the x-axis of the I
marker perpendicular to the y-axis of the J marker so they outline the
crosspiece of the joint. The origins of the I and J markers are at the center of
the cross. The HOOKE joint functions the same as the universal joint, but
uses different marker orientations.
JOINT 185
Hooke Joint
I=id, J=id Specifies the identifier of one fixed marker in each part the joint connects.
Adams Solver (FORTRAN) connects one part at the I marker to the other at
the J marker.
IC=r1,r2 Defines the initial conditions you want to impose on either a translational or
revolute joint. The value r1 is the velocity of the I marker with respect to the
J marker as seen by the J marker. The value r2 is the displacement of the I
marker with respect to the J marker. Adams Solver (FORTRAN) measures
both the rotational velocity and the rotation of the x-axis of the I marker about
the common z-axis of the I and J markers with respect to the x-axis of the J
marker.
The IC argument imposes a constraint that is active only during initial

conditions analysis (not at the time of the initial configuration). Adams Solver
(FORTRAN) does not impose initial conditions during subsequent analyses.
If the IC argument imposes initial conditions on the joint that are inconsistent
with those on one of the bodies the joint connects, the initial conditions on
For the initial conditions for a translational joint, velocity is in units of

translational displacement per unit of time and displacement is in units of
length. For the initial conditions for a revolute joint, velocity is in radians per
unit of time and displacement is in radians.
186 Adams Solver
ICROT=r1,r2 Defines the rotational initial conditions you want to impose on a cylindrical
joint.
The value r1 is the angular velocity of the I marker with respect to the J marker
(in radians per unit of time).
The value r2 is the rotation of the I marker with respect to the J marker (in
radians). Adams Solver (FORTRAN) measures both the rotational velocity
and the rotation of the x-axis of the I marker about the common z-axis of the
I and the J markers with respect to the x-axis of the J marker.
The ICROT argument imposes a constraint that is active only during initial
If the ICROT argument imposes initial conditions on the joint that are
inconsistent with those specified on one of the bodies the joint connects, the
initial conditions on the joint have precedence over those on the body.
ICTRAN=r1,r2 Defines the translational initial conditions you want to impose on a
cylindrical joint. The value r1 is the translational velocity of the I marker with
respect to the J marker (in units of length per unit of time). The value r2 is
the translation of the I marker with respect to the J marker (in units of length).
Adams Solver (FORTRAN) measures both translational velocity and
translation at the origin of the I marker along the common z-axis of I and J
and with respect to the J marker.
The ICTRAN argument imposes a constraint that is active only during initial
If the ICTRAN argument imposes initial conditions on the joint that are
inconsistent with those specified on one of the bodies the joint connects, the
initial conditions on the joint have precedence over those on the body.
PD=r Pitch diameter (PD) defines the pitch diameter of the pinion gear of a rack-
and-pinion joint. The pitch diameter relates the rotational motion of the
pinion to the translational motion of the rack. When the pinion turns in the
positive direction around the z-axis of the I marker, a positive pitch diameter
moves the rack in the positive direction along the z-axis of the J marker and a
negative pitch diameter moves the rack in the negative direction along the z-
PITCH=r Defines the translational displacement of a screw joint that corresponds to one
revolution of its rotational displacement. A positive pitch creates a right-hand
thread, and a negative pitch creates a left-hand thread.
JOINT 187
PLANAR Indicates that the joint is a three-degree-of-freedom joint that allows a plane
of one part to slide on a plane on a second part (see the figure below). The x
and y axis of the I and J markers of the joint define the planes on the two parts.
For the PLANAR joint, Adams Solver (FORTRAN) constrains the z-axis of
the I marker so that it remains parallel to, and co-directed with, the z-axis of
the J marker and does not allow the linear displacement with respect to the J
marker to have a z component.
Planar Joint
188 Adams Solver
RACKPIN Indicates that the joint is a five-degree-of-freedom joint that constrains the
rotational displacement of the I marker to the translational displacement of
the J marker and measures both displacements with respect to the J marker.
The I marker is at the center of the pinion, and the J marker is in the rack.
The figure below illustrates a rack-and-pinion joint.
For the RACKPIN joint, the z-axis of the pinion must be parallel to and co-
directed with the x-axis of the rack. The separation between the two axes
should be one-half the pitch diameter of the pinion. The rack-and-pinion
joint itself does not enforce the position and orientation it requires, but the
chain of both parts and joints that connects markers I and J should enforce
the position and orientation. A common approach for enforcing the position
and orientation is to support the rack with a translational joint and to support
the pinion with a revolute joint.
During simulation, the I marker displacement parallel to the J marker z-axis

is a function of the angle between the I marker x-axis and the J marker z-axis.
Adams Solver (FORTRAN) measures a positive rotation according to the
right-hand rule. For every full rotation, the distance the I marker moves
parallel to the z-axis of the J marker is equal to the value of PD times p. The
direction the I marker moves depends on the sign of PD. For a positive PD
and positive rotation, the I marker moves in the negative direction along the
z-axis of the J marker (and the J marker moves in the positive direction).
Rack and Pinion Joint (PD > 0)
REVOLUTE Indicates that the joint is a single-degree-of-freedom joint that allows rotation
of one part with respect to another about a common axis denoted as zi,j in the
figure below.
For the REVOLUTE joint, Adams Solver (FORTRAN) superimposes the

origins of the I and J markers and keeps their z-axes parallel. Relative motion
occurs about the common z-axes.
JOINT 189
Revolute Joint
SCREW Indicates that the joint is a five-degree-of-freedom joint that constrains the
translation of the I marker to its rotation (see the figure below).
For the SCREW joint, the z-axis of the I marker and the z-axis of the J marker
must always be parallel and co-directed. Although the SCREW joint does not
enforce this parallelism, the chain of parts and joints that connects the two
markers should. During simulation, the I marker displacement along the J
marker z-axis is a function of the relative angle of the x-axis of the I marker
with respect to the x-axis of the J marker. Adams Solver (FORTRAN)
measures a positive rotation according to the right-hand rule. For every full
rotation, the displacement of the I marker along the z-axis of the J marker is
equal to the value of PITCH. If φ is zero, the translational displacement may
be zero or any multiple of PITCH.
Screw Joint
190 Adams Solver
SPHERICAL Indicates that the joint is a three-degree-of-freedom joint (see the figure
below).
While permitting all three rotations, a SPHERICAL joint constrains the

origins of the I and the J markers to always be superimposed.
Spherical Joint
TRANSLATIONAL Indicates that the joint is a single-degree-of-freedom joint that allows

translational displacement of one part relative to another along the common
z axes, zi and zj, as shown in the figure below.
For the TRANSLATIONAL joint, Adams Solver (FORTRAN) keeps the axes
of the I and the J markers parallel and co-directed, and keeps the origin of the
I marker on the z-axis of the J marker so that the two markers have a common
z-axis. To determine the translational displacement of the I marker with
respect to the J marker, Adams Solver (FORTRAN) measures the origin of the
I marker with respect to the origin of the J marker along their common z-axis.
JOINT 191
Translational Joint
UNIVERSAL Indicates a two-degree-of-freedom joint that rotates about two axes: the z-axis
of the I marker and the z-axis of the J marker (see the figure below).
For the UNIVERSAL joint, Adams Solver (FORTRAN) superimposes the

origins of the I and J markers and keeps their z-axes perpendicular, so they
outline the crosspiece of the joint. The origins of the I and J markers are at the
center of the cross. The UNIVERSAL joint functions the same as the
HOOKE joint, but uses different marker orientations.
Universal Joint
Extended Definition
The JOINT statement describes a physically recognizable combination of constraints such as constant-
velocity, cylindrical, fixed, Hooke, planar, rack-and-pinion, revolute, screw joints, spherical, translational,
and universal (see the figure on the Summary of Joints and the table on joint constraints that follows).
192 Adams Solver
Summary of Joints
Joint Constraints
Removes Translational Removes Rotational Removes Total Number

This type of Joint: DOF: DOF: DOF:
Constant Velocity 3 1 4
Cylindrical 2 2 4
Fixed 3 3 6
Hooke 3 1 4
JOINT 193
Removes Translational Removes Rotational Removes Total Number

This type of Joint: DOF: DOF: DOF:
Planar 1 2 3
Revolute 3 2 5
Screw 0.5* 0.5* 1
Spherical 3 0 3
Translational 2 3 5
Universal 3 1 4
The reaction force on Part A always acts at the I marker. The reaction force on Part B acts at the instantaneous
location of the I marker; that is, the point of application may vary with time. The reaction force on Part B is
always equal and opposite to the reaction force on Part A.
 Joints can be superimposed. Because a joint connects exactly two parts, you can include a part
between any two joints you superimpose. In general, if combinations of constraints are to be defined
other than those available with the JOINT statement, it is usually simpler to define these
combinations with the JPRIM statement.
 The spherical joint that a JOINT statement imposes is identical to the atpoint joint that the JPRIM
statement imposes.
 In general, the GEAR statement is easier to use than the JOINT statement to define a rack-and-
pinion joint. In addition, the GEAR statement is more accurate. The current RACKPIN joint
applies a parasitic rotational force to the rack part. For some models the parasitic rotational force
could cause inaccurate results. Learn more information about the GEAR statement.
 The UNIVERSAL and HOOKE joints function identically. One may be more convenient to define
than the other, however, depending on the data you have available. If the joint is initially straight,
for instance, the HOOKE joint may be defined by two identical markers.
 Functionally, the constant-velocity joint is similar to the UNIVERSAL and HOOKE joints.
Connecting two shafts with a constant-velocity joint ensures that the shafts always spin at the same
rate, however, unlike the UNIVERSAL and HOOKE joints which cause some fluctuation as the
joint bends.
194 Adams Solver
Caution:  The two markers that define a joint must be in two different parts.
 Be careful when defining UNIVERSAL and HOOKE joints. In an actual universal
joint, if the spin axis of either part comes into alignment with either rotational axis of
the joint, the joint can no longer transmit rotational motion. The figure below shows
a universal joint in this singular position.
In Adams Solver (FORTRAN) the singular position allows the universal joint to spin
freely and usually causes simulation failure.
Universal Joint in the Singular Position
 Be careful when defining CONVEL joints. Whenever the z-axes of the I and J markers in a
CONVEL joint become colinear and codirected, the joint is in a singular position. The behavior of
the CONVEL joint in the singular position is unpredictable and may be incorrect.
 The screw joint relates the rotational motion of the I marker to the translational motion of the I
marker and measures both motions with respect to the J marker. However, the screw joint does not
model the backlash or slop that may occur in actual screw joints.
 For both the rack-and-pinion and screw joints, Adams Solver (FORTRAN) positions the I and the J
markers at the nearest pitch-multiple position that satisfies the constraint. Examples of pitch
multiples of a joint with a pitch value of 2.5 include -5.0, -2.5, 0.0, 2.5, 5.0, etc. Therefore, you
should be careful to ensure that the part, marker, and joint information that contributes to the initial
positioning of the I marker with respect to the J marker correctly describes the initial position of the
I marker.
 If the initial conditions are inconsistent with other conditions in the system, Adams Solver
(FORTRAN) varies the part initial positions through an iterative process to correct the
inconsistencies and then begins the simulation.
JOINT 195
 Use caution when using the initial conditions arguments (IC, ICTRAN, ICROT) in conjunction
with a MOTION statement on the same joint. If the MOTION statement and the initial
conditions argument(s) specify motion for the same degree of freedom, Adams Solver (FORTRAN)
uses the MOTION statement, ignores the initial conditions argument, and issues a warning
message.
 If the initial rotational displacement of a revolute or cylindrical joint (as specified by the IC or the
ICROT argument on the JOINT statement or by a MOTION statement) varies by anywhere from
5 to 60 degrees from the initial configuration of the joint as indicated by the input positions of the
two parts constituting the joint, Adams Solver (FORTRAN) issues a warning message and continues
execution. If the variation is greater than 60 degrees, Adams Solver (FORTRAN) issues an error
message and stops execution.
 The initial conditions arguments impose constraints that are active only during initial conditions
analysis. Adams Solver (FORTRAN) does not impose these initial conditions during subsequent
analyses.
 For a kinematic analysis, the initial conditions are redundant. Do not use initial condition
arguments on the JOINT statements for systems with zero degrees of freedom.
 Adams Solver (FORTRAN) checks whether axes that are constrained to be parallel or perpendicular
are actually close to parallel or perpendicular as input in the dataset. If you input joint markers such
that constrained axes are misaligned by more than 5 degrees, Adams Solver (FORTRAN) issues a
warning but continues the simulation. If you misalign constrained axes by more than 60 degrees,
Adams Solver (FORTRAN) issues an error and stops the simulation. You can input unconstrained
axes in any position. In a REVOLUTE joint, for example, Adams Solver (FORTRAN) issues a
warning if the angle between the z-axes of the I and J markers is greater than 5 degrees, and an error
if the angle is greater than 60 degrees. The x-axes, however, may be at any angle.
Examples
This JOINT statement indicates that Adams Solver (FORTRAN) is to connect one part at Marker 0406 to
another part at Marker 0306. Because the statement includes the argument UNIVERSAL, Adams Solver
(FORTRAN) uses a universal joint to make the connection.
196 Adams Solver
JPRIM
translational or rotational freedom. JPRIMs do not usually have a physical analogue and are predominantly
useful in enforcing standard geometric constraints.
Format
JPRIM 197
Arguments
198 Adams Solver
ATPOINT Indicates a three-degree-of-freedom primitive that allows only rotational motion of

one part with respect to another (see the figure below).
For an atpoint primitive, Adams Solver (FORTRAN) constrains all three
translational displacements so that the I and J markers are always superimposed.
Atpoint Primitive
I=id,J=id Specifies the identifier of one fixed marker in each part the primitive connects.
Adams Solver (FORTRAN) connects one part at the I marker to another at the J
marker.
INLINE Indicates a four-degree-of-freedom primitive that allows one translational and three
rotational motions of one part with respect to another (see the figure below).
For an inline primitive, Adams Solver (FORTRAN) imposes two translational

constraints, which confine the translational motion of the I marker to the line
defined by the z-axis of the J marker.
Inline Primitive
JPRIM 199
INPLANE Indicates a five-degree-of-freedom primitive that allows both translational and

For an inplane primitive, Adams Solver (FORTRAN) imposes one translational

constraint, which confines the translational motion of the I marker to the x-y plane
of the J marker.
Inplane Primitive
200 Adams Solver
ORIENTATION Indicates a three-degree-of-freedom primitive that allows only translational motion

of one part with respect to another (see the figure below).
For an orientation primitive, Adams Solver (FORTRAN) imposes three rotational

constraints to keep the orientation of the I marker identical to the orientation of the
J marker.
Orientation Primitive
PARALLEL_AXES Indicates a four-degree-of-freedom primitive that allows both translational and

For a parallel axes primitive, Adams C++Solver imposes two rotational constraints so
that the z-axis of the I marker stays parallel to the z-axis of the J marker. This
primitive permits relative rotation about the common z-axis of I and J and permits
all relative displacements.
Parallel Axes Primitive

JPRIM 201
PERPENDICULAR Indicates a five-degree-of-freedom primitive that allows both translational and

For a perpendicular primitive, Adams Solver (FORTRAN) imposes a single

rotational constraint on the I and the J markers so that their z-axes remain
perpendicular. This allows relative rotations about either z-axis, but does not allow
any relative rotation in the direction perpendicular to both z-axes.
Perpendicular Primitive
Extended Definition
translational or rotational freedom. The joint primitives, in general, do not have physical counterparts. The
next figure shows the degrees of freedom each joint primitive allows.
In these and subsequent joint primitive figures, thick solid arrows show permissible motions of the I marker
with respect to the J marker, thick dashed arrows show forbidden motions of the I marker with respect to the
J marker, and thin solid lines show the I marker. Ghost constructs suggest spatial relationships.
Summary of Joint Primitive
202 Adams Solver
The table below lists the number of translational or rotational constraints each joint primitive imposes.
Primitive Constraints
This type of Joint Removes No. Removes No. of Removes Total Number
Primitive: Translational DOF Rotational DOF DOF
Atpoint 3 0 3
Inline 2 0 2
Inplane 1 0 1
JPRIM 203
This type of Joint Removes No. Removes No. of Removes Total Number
Primitive: Translational DOF Rotational DOF DOF
Orientation 0 3 3
Parallel Axes 0 2 2
Perpendicular 0 1 1
The reaction force on the part containing the I marker always acts at the I marker. The reaction force on the
part containing the J marker acts at the instantaneous location of the I marker; that is, the point of application
can vary with time if the I and J markers translate with respect to one another. The reaction force on the part
containing the J marker is always equal and opposite to the reaction force on the part containing the I marker.
Joint primitives can be combined to define a complex constraint. In fact, they can be used to create any of
the recognizable joints (except for RACKPIN and SCREW). However, motions cannot be applied on joint
primitives as they can be on recognizable joints. For more information on recognizable joints, see JOINT.
Tip: The atpoint primitive is identical to the spherical joint
Caution: The two markers that define a joint primitive must be in two different parts.
Examples
JPRIM/0101, INLINE, I=0140, J=0240
This JPRIM statement indicates that Adams Solver (FORTRAN) is to use an inline joint primitive to connect
one part to another. This connects the first part at Marker 0140 to the second at Marker 0240.
204 Adams Solver
KINEMATICS
The KINEMATICS statement specifies error tolerances and other parameters for kinematic analyses.
Format
Arguments
AERROR Specifies the maximum acceleration error Adams Solver (FORTRAN) is to allow for
each time step.
Default: 1.0E-4
Range: AERROR > 0
ALIMIT=r Specifies the maximum angular increment Adams Solver (FORTRAN) is to allow per
iteration. The default units for ALIMIT are radians. To specify ALIMIT in degrees, add
a D after the value.
Default: 30D
Range: ALIMIT > 0
AMAXIT=i Specifies the maximum number of iterations Adams Solver (FORTRAN) is to allow for
finding accelerations at a point in time.
Default: 25
Range: AMAXIT > 0
KINEMATICS 205
APATTERN=c1[: Specifies as many as ten character strings that together establish the pattern for
...:c10] evaluating the Jacobian matrix during the modified Newton-Raphson solution for the
accelerations. For each iteration, T or TRUE indicates that Adams Solver (FORTRAN)
is to evaluate the Jacobian, and F or FALSE indicates that Adams Solver (FORTRAN)
is not to evaluate the Jacobian. Thus, cj determines whether or not Adams Solver is to
evaluate the Jacobian at the jth iteration. If necessary, Adams Solver (FORTRAN)
repeats the pattern of evaluations until it reaches the maximum number of iterations
(AMAXIT). The number of T’s or TRUE’s and F’s or FALSE’s together must be at least
one and no more than 10.
Default: T:T:T:T:T:T:T:T:T:T, that is, to evaluating the Jacobian at every iteration (that
is, the unmodified Newton-Raphson algorithm)
ERROR=r Specifies the maximum displacement error Adams Solver (FORTRAN) is to allow for
each time step.
Default: 1.0E-4
Range: ERROR > 0
HMAX=r Defines the maximum time step that the kinematics solver is allowed to take.
Default: The output step size.

MAXIT=i Specifies the maximum number of iterations Adams Solver (FORTRAN) is to allow for
finding the displacements at a point in time.
Default: 25
Range: MAXIT > 0
PATTERN=c1[:... Specifies as many as ten character strings that together establish the pattern for
:c10] evaluating the Jacobian matrix during the modified Newton-Raphson solution for the
displacements. For each iteration, T or TRUE indicates that Adams Solver
(FORTRAN) is to evaluate the Jacobian and F or FALSE indicates that Adams Solver
(FORTRAN) is not to evaluate the Jacobian. Thus cj determines whether or not Adams
Solver is to evaluate the Jacobian at the jth iteration. If necessary, Adams Solver
(FORTRAN) repeats the pattern of evaluations until it reaches the maximum number
of iterations (MAXIT). The number of T’s or TRUE’s and F’s or FALSE’s together must
be at least one and no more than ten.
Default: T:T:T:T:T:T:T:T:T:T, that is, to evaluating the Jacobian at every iteration (that
is., the unmodified Newton-Raphson algorithm)
TLIMIT=r Specifies the maximum translational increment Adams Solver (FORTRAN) is to allow
per iteration.

Range: TLIMIT > 0
206 Adams Solver
Extended Definition
The KINEMATICS statement specifies error tolerances and other parameters for kinematic analyses. This
statement would only be used when you are requesting a kinematic analysis and you want to change one or
more of the tolerances and parameters from the default values.
Use the SIMULATE command to request a series of kinematic analyses over time. A kinematic analysis is only
appropriate when a system has zero degrees of freedom. A kinematic analysis solves for the displacements,
velocities, accelerations, and forces (if any) at a series of points in time. To find the displacements, Adams
Solver (FORTRAN) uses Newton-Raphson iteration to solve a nonlinear set of algebraic equations.
After finding the displacements, Adams Solver (FORTRAN) solves a system of linear equations to find the
velocities, then solves another set of nonlinear equations to find accelerations and forces. Adams Solver
(FORTRAN) repeats this procedure at successively later times until it obtains results over the period of time
specified in a SIMULATE command.
If you issue neither a KINEMATICS command nor statement in an Adams Solver (FORTRAN) session,
Adams Solver (FORTRAN) uses the default values for AERROR, ALIMIT, AMAXIT, APATTERN,
ERROR, MAXIT, PATTERN, and TLIMIT when performing a kinematic analysis.
Tip:  Using a PATTERN argument to request less frequent evaluations of the Jacobian
matrix may decrease the computation time, decreasing the cost and improving the
response time. However, infrequent evaluations could also be more expensive since
the modified Newton-Raphson algorithm might require more iterations due to the
slower convergence rates.
 Use the ALIMIT and TLIMIT arguments to limit the increments in the displacement
variables and thus the size of the position change on successive iterations. This tends
to prevent Adams Solver (FORTRAN) from moving the mechanism to an
undesirable configuration.
Examples
KINEMATICS/TLIMIT=10, MAXIT=30
This KINEMATICS statement assigns new values to TLIMIT and MAXIT for a kinematic analysis. Thus,
the maximum translational increment allowed in each iteration of a kinematic analysis is 10 length units and
the number of iterations of the algorithm for the solution of the nonlinear equations is limited to 30.
LIST/NOLIST 207
LIST/NOLIST
The LIST and NOLIST statements allow and suppress writing of the input data to the tabular output file.
Combinations of LIST and NOLIST can be used to output any part of the input dataset. The portion of the
dataset following the LIST statement up to the NOLIST statement or through the end of the file is copied
to the tabular output file. If you include neither a LIST statement nor a NOLIST statement in the dataset,
Adams Solver (FORTRAN) assumes that you do not want to record any portion of the input dataset in the
tabular output file.
Format
LIST
or
NOLIST
208 Adams Solver
LSE
The LSE (Linear State Equation) statement defines the following linear system:
x· = A x + Bu
y = C x + Du
of first-order, explicit differential equations and algebraic equations in classical state-space form. The state
variables, x, the inputs, u, and the outputs, y, are specified by ARRAY statements. Use MATRIX statements
to define the coefficient matrices A, B, C, and D.
Format
LSE 209
Arguments
A=id Designates the MATRIX statement in the dataset that defines the state transition matrix
for the linear system. You must have a MATRIX statement with this identifier in the
dataset; it must be a square matrix (same number of rows and columns); and it must have
the same number of columns as the number of rows in the X array.
B=id Designates the MATRIX statement in the dataset that defines the control matrix for the
linear system. The B argument is optional. When it appears on the LSE statement, you
must also include the U argument. A MATRIX statement with the identifier id must be
of columns as the number of elements in the U array.
C=id Designates the MATRIX statement in the dataset that defines the output matrix for the
linear system. The C argument is optional. When it appears on the LSE statement, you
must also include the Y argument. A MATRIX statement with the identifier id must be
of rows as the number of elements in the Y array.
D=id Designates the MATRIX statement in your dataset that defines the feed forward matrix
for the linear system. When the D argument is used, you must also include both Y and U
arguments in the LSE definition. A MATRIX statement with this identifier must be in the
dataset; it must have the same number of rows as the number of elements in the Y array
and the same number of columns as the number of elements in the U array.
IC=id Designates the ARRAY statement in the dataset that defines the column matrix of initial
conditions for the linear system. The IC argument is optional. When it appears on the
LSE statement, you must have an ARRAY statement with the identifier id in the dataset;
and it must have the same number of elements as the X array (equal to the number of rows
in the A matrix). When no IC array is specified for an LSE, all states are initialized to zero.
STATIC_HOL Indicates that the LSE states are not permitted to change during static and quasi-static
D analyses.
210 Adams Solver
U=id Designates the ARRAY statement in the dataset that defines the input (or control) array
for the linear system. The U argument is optional. When it is used on the LSE statement,
there must be an ARRAY statement with the identifier id in the dataset; and it must be of
the U type. One or both of the B or D argument must appear along with the U argument
in the LSE statement. The corresponding MATRIX statements must have the same
number of columns as there are elements in the U array.
X=id Designates the ARRAY statement in the dataset that defines the state array for the linear
system. You must have an ARRAY statement with this identifier in the dataset; it must be
of the X type; and it may not be used in any other LSE, GSE, or TFSISO statement.
Y=id Designates the ARRAY statement in your dataset that defines the column matrix of output
variables for the linear system. The Y argument is optional. When it is used on the LSE
statement, an ARRAY statement with the identifier id must be in the dataset; it must be
of the Y type, and it may not be used in any other LSE, GSE or TFSISO statement. One
or both of the C or D arguments must appear along with the Y argument on the LSE
statement. The corresponding MATRIX statements must have the same number of rows
as there are elements in the Y array.
Extended Definition
The LSE (Linear State Equation) statement is used, along with associated ARRAY and MATRIX statements,
to define a system of constant coefficient, explicit, differential and algebraic equations in state-space form.
The system of equations describes a model for a linear, time-invariant dynamic system. The LSE, ARRAY,
and MATRIX statements provide the means for importing controllers developed manually or with other
software packages. It can also be used, however, to define an arbitrary set of coupled, constant-coefficient
differential and algebraic linear equations in the form
 x·  A B x 
   
y  C D u 
where at least the A matrix must be nonzero.
The LSE statement follows standard control systems terminology, where x is the state array, y is the output
array, u is the input array, and the initial conditions are defined for x(t=0). In the Adams Solver dataset, each
of these arrays is defined using an ARRAY statement. Similarly, A is the state matrix, B is the control matrix,
C is the output matrix, and D is the feedforward matrix. Each of these matrices is defined using a MATRIX
statement.
All MATRIX and ARRAY sizes must be conformable as required by the above equation. ARRAY statements
with zero-length and zero-sized matrices should not be defined; Adams Solver (FORTRAN) correctly
formulates the system equations based on the ARRAY and MATRIX statements included in the dataset.
LSE 211
Caution:  The LSE statement provides a very general capability for defining a linear element.
The Adams solvers, however, have been developed and refined for sparse systems of
equations that arise from the modeling of mechanical systems. With the LSE
statement, you can create very dense sets of equations. If these equations form a large
portion of your completed model, Adams Solver (FORTRAN) may perform more
slowly than expected.
 Note that, if the algebraic equations defined by the LSE statement have no solution or
Adams Solver (FORTRAN) most likely fails to converge or possibly converge to an
unexpected answer. To avoid this possibility, you should not reference the X (state) or
Y (output) ARRAY statements in the VARIABLE statements listed in the U (input)
array.
Examples
LSE/10, X=10, A=10, U=11, B=11, IC=12
ARRAY/10, X
ARRAY/12, IC, NUMBER=0.0,0.0
MATRIX/10, FULL=RORDER, ROW=2, COL=2,
, VALUE=0.0,1.0,-986.96,-6.2832
MATRIX/11, FULL=RORDER, ROW=2, COL=1, VALUE=0.0,1.0
VARIABLE/11, FUNCTION=5.0*SIN(PI*TIME**2)
These statements define the following set of linear state equations.
x· = 0 1 x + 0 5 sin ( πt 2 ) x(0) = 0
– 986.96 – 6.2832 1 0
 ARRAY/10 is the state array (x).

212 Adams Solver
 ARRAY/11 is the input array (u).

 ARRAY/12 is the initial condition array. The input is defined by VARIABLE/11.
 MATRIX/10 is the state matrix (A).
 MATRIX/11 is the control matrix (B). This LSE has no output, so there is no output array (y),
output matrix (C), or feedforward matrix (D) specified.
Applications
The LSE statement may be most useful for adding feedback control systems to an Adams Solver
(FORTRAN) model. The A, B, C and D matrices can be derived manually or imported directly from a
control system design program such as MATRIXx or MATLAB. Normally, the mechanical portion of the
model includes some kind of actuator that depends on one or more of the LSE statement outputs or states.
LSE statements can also be conveniently used in many cases to replace systems of coupled DIFF and
VARIABLE statements (for nonlinear equations, the GSE statement should be used). Examples of possible
dynamical system uses include unsteady aerodynamics and electrodynamics.
You can use the current values of LSE states and outputs in both function expressions and user-written
subroutines using the associated ARRAY facilities (see the ARYVAL function and the subroutines SYSARY and
SYSFNC). That is, instead of Adams Solver (FORTRAN) functions and FORTRAN callable subroutines
dedicated expressly to the LSE statement, the system states and outputs are accessed by offset referencing
through the appropriate ARRAY routines. This allows for consistent access to system states and outputs for
all three system modeling elements, the LSE, GSE, and TFSISO statements.
MARKER 213
MARKER
The MARKER statement defines a geometric point in space and a set of three mutually perpendicular
coordinate axes emanating from that point.
Format
214 Adams Solver
Arguments
FLOATING Defines the marker as one that moves relative to the part with which it is associated.
Without this argument, a marker is considered spatially fixed relative to the part
with which it is associated. A floating marker must be used with VTORQUE,
VFORCE, GFORCE, CVCV, and PTCV, and cannot exist without being
referenced by one of these statements.
FLEX_BODY=id Specifies the identifier of the flexible body to which the marker belongs. A
FLEX_BODY argument is not required in the MARKER statement if the
MARKER statement follows the associated FLEX_BODY statement with no
Default: ID of preceding FLEX_BODY, PART, or POINT_MASS
Range: Flexible body IDs

NODE=fem_node_id Specifies that a marker is to be created at a point on a structure where a finite
element node existed. The NODE argument can only be applied to a marker on a
FLEX_BODY. A FLEX_BODY argument is not required if the MARKER
statement follows the associated FLEX_BODY statement with no intervening
FLEX_BODY, PART, or POINT_MASS statement.
Default: None
Range: IDs of nodes on the FLEX_BODY

PART=id Specifies the identifier of the part to which the marker belongs. A PART argument
is not required in the MARKER statement if the MARKER statement follows the
associated PART statement with no intervening FLEX_BODY, PART, or
POINT_MASS statements.
Default: ID of preceeding FLEX_BODY, PART, or POINT_MASS
Range: Part IDs

POINT_MASS=id Specifies the identifier of the point mass to which the marker belongs. A
POINT_MASS argument is not required in the MARKER statement if the
MARKER statement follows the associated POINT_MASS statement with no
Default: ID of preceding FLEX_BODY, PART or POINT_MASS
Range: Point mass IDs

MARKER 215
QP=x,y,z Defines the x-, y-, and z-coordinates of the origin of the MARKER with respect to
the element on which it lies. The coordinates are specified in the body coordinate
system (BCS).
Range: Real numbers for x, y, and z

REULER=a,b,c Specifies the Euler angle 3-1-3 sequence rotation defining the spatial orientation of
the marker axes relative to the element on which it lies. The orientation is relative
to the body coordinate system (BCS).
The a, b, and c, values represent the set of body-fixed 3-1-3 Euler angles expressed
in radians. These angles can be interpreted by following the steps below.
To orient a marker:
1. Align the marker axes identical to the axes of the parent coordinate system
to which the orientation will be relative.
2. Perform a right-handed rotation of the marker x- and y-axes by a radians
about the positive z-axis of the marker.
3. Rotate the marker y- and z-axes by b radians about the current marker
positive x-axis.
4. Perform a right-handed rotation of the x- and y-axes of the marker by c
radians about the current z-axis of the marker.
To enter the Euler angles in degrees instead of radians, add a D after each value.
Range: Real numbers for a, b, and c

USEXP Causes the marker to be oriented with the x-axis lying on XP, and ZP lying in the
positive x-z plane, when using the x-point-z-point method of orientation. This is
useful for orienting markers used in BEAM statements. Examples of using the ZP, XP
and USEXP.
XP=x,y,z By default, defines the coordinates of any point in the positive x-z plane of the
marker, but not on the z-axis of the marker. A point on the positive x-axis may be
the most convenient. When used with USEXP, XP defines the BCS coordinates of
any point on the positive x-axis of the marker. Examples of using the ZP, XP and USEXP.
ZP=x,y,z By default, defines the coordinates of any point on the positive z-axis of the marker.
When used with USEXP, ZP defines the BCS coordinates of any point in the
positive x-z plane of the marker, but not on the x-axis of the marker. Examples of using
the ZP, XP and USEXP.
Extended Definition
The marker defines a geometric point in space and a set of three mutually perpendicular coordinate axes
emanating from the point. Markers are always associated with specific parts of a mechanism and can either
be fixed on the part or may float relative to the part. A MARKER statement identifies the location and
216 Adams Solver
orientation of a marker with respect to a BCS. Markers are the basic building blocks used to specify points
of: application for forces, connectivity for constraints, attachment for graphic elements, or interest in the
model. For more information on BCS, see Coordinate Systems and Local Versus Global Geometric Data.
In the online help, a reference to a marker without a type usually refers to a fixed marker. A floating marker
normally has the term floating associated with it in some way.
Requests for information pertaining to fixed and floating markers are easy to write (see REQUEST). However,
only information on fixed markers can be used in FUNCTION arguments that affect how the model
behaves. You may reference the position of a floating marker in a REQUEST statement or a REQSUB
evaluation subroutine, for instance, but not in an SFORCE statement or a SFOSUB evaluation subroutine
Tip:  Markers on parts can be positioned anywhere relative to a BCS.

 Markers on flexible bodies must be positioned on a finite-element node.
 For every fixed marker, you specify the element to which it belongs and define its
position and orientation. For every floating marker, you specify only the part to which
it belongs.
 Select one of the following three methods to define the position and orientation of the
marker:
• To select the Euler angles method, add QP and/or REULER.
• To select the x-point-z-point method using the ZP point to define a point on the
z-axis, add QP, ZP, and/or XP. It is often unnecessary to define XP.
• To select the x-point-z-point method using the XP point to define a point on the
x-axis, add QP, XP, and/or ZP, as well as USEXP. It is often unnecessary to define
ZP.
Caution: All markers must belong to an element.
If a MARKER statement is written without arguments to define its position and orientation,
Adams Solver (FORTRAN) defines a marker with the same position and orientation as the
BCS.
Note: In general, locate and orient a marker with respect to its parent BCS. If the marker is on the
ground part or is on a part whose BCS is coincident with the ground coordinate system (GCS)
at time zero, the marker can be positioned and oriented with respect to the GCS.
Examples
MARKER/0406, ZP=0,1,0, XP=0,0,1, PART=4
MARKER 217
This MARKER statement assigns Marker 0406 to Part 4 and defines the position and orientation of 0406
with respect to the BCS of Part 4 using the x-point-z-point method. QP defaults to QP=0,0,0, so Adams
Solver (FORTRAN) positions Marker 0406 at the origin of the BCS. The ZP values indicate that the marker
z-axis is parallel to the BCS y-axis and that the XP point lies on the BCS z-axis.
MARKER/0408, QP=2,0,0, REULER=90D,90D,0, PART=4
This MARKER statement, like the previous one, describes a marker on Part 4. Adams Solver (FORTRAN)
places the origin of Marker 0408 at coordinates 2,0,0 with respect to the BCS. To orient the marker, Adams
Solver (FORTRAN) aligns it with its BCS and then rotates the marker 90 degrees about its z-axis, 90 degrees
about its new x-axis, and 0 degrees about its new z-axis.
MARKER/1002, FLOATING, PART=2
This MARKER statement defines a floating marker named Marker 1002 on Part 2. A floating marker
requires the use of one of the following: VTORQUE, VFORCE, GFORCE, PTCV, or CVCV. The
statement referencing the floating marker determines the instantaneous location and orientation of this
marker.
MARKER/8007, XP=0,0,1, ZP=0.1,0,0.1, USEXP, PART=8
This MARKER statement defines Marker 8007 on Part 8. QP defaults to QP=0,0,0, so Adams Solver
(FORTRAN) positions Marker 8007 at the origin of the BCS. With USEXP active, the XP values indicate
that the marker x-axis passes through point 0,0,1, and the ZP values indicate the z-x plane passes through
BCS coordinates 0.1,0.0,0.1.
Applications
Use fixed markers to:
 Designate the center of mass in a part (see the PART statement).
 Indicate the position and orientation of the coordinate system with respect to which you specify the
part moments of inertia (see the PART statement).
 Define the position and orientation of a joint or joint-primitive connection point/direction. This
requires two markers, one in each part that the joint or the joint primitive connects (see the JOINT
and JPRIM statements).
 Denote force direction and action and reaction points (see the statements: BEAM, BUSHING, FIELD,
SFORCE, and SPRINGDAMPER).
 Specify points for request and graphics output (see the REQUEST and GRAPHICS statements).
 Provide coordinate system(s) other than the ground coordinate system(s) for resolving the
components of vector quantities such as velocities, accelerations, and forces (see the REQUEST
statement).
Use floating markers to:
 Denote reaction points that can change position on a part (see the statements: VFORCE, VTORQUE, and
GFORCE).
 Denote contact points in CVCV and PTCV constraints (see the CVCV and PTCV statements).
218 Adams Solver
MATRIX
The MATRIX statement provides the means for inputting a two-dimensional array of numerical values. It is
used primarily to support other statements such as CURVE, LSE, and NFORCE. The entries in the matrix can be
assigned values with the arguments on the MATRIX statement itself or the MATRIX statement can specify
the name of another data file from which the code reads the values. The data file can be in one of two formats:
the Adams Solver (FORTRAN) format or the standard FSAVE format supported by the MATRIXx software
package.
Format
MATRIX 219
Arguments
COLUMNS=i Specifies the number of columns (N) in the matrix.

FILE=c Specifies the name of a file containing the values of the matrix. The file name can
include the directory on operating systems that support path names, such as Linux.
You can use the FILE argument to read large matrices into Adams Solver
(FORTRAN). There is no limit on the size of an array read from a file.
The first record in the file contains an 80-character header of which the first seven
or eight characters are meaningful.
 If the first record begins with the characters ADAMSMAT or

ADAMSMAT2, then the file is assumed to be in a format used by the
Adams Solver (FORTRAN) code.
 If the first record begins with the characters MATRIXx, then the file is
assumed to be in the FSAVE format of the MATRIXx software package.
 If the first record begins with the characters MATSAVE, then the file is
assumed to be in the MATSAVE format of the MATRIXx software
package.
Note that the three specifications for the format of the data file are case sensitive.
Capital letters and a lower case x must be used to make the MATRIXx selection.
No other kinds of files are currently supported. However, the ADAMSMAT and
ADAMSMAT2 options are fairly general since the format for reading in the data is
specified within the file. See the example, Multiple Matrix Input Using the FILE Option, for
details on the structure of an ADAMSMAT file.
Because the FILE argument and value can be at most eighty characters long, the file
path and name are limited from seventy-five characters (if you do not abbreviate
FILE=) to seventy-seven characters (if you abbreviate FILE= to FI=).
FULL={RORDER,C Specifies a full-input format where all of the M x N entries are specified with the
ORDER} VALUES argument. RORDER indicates the values are listed by row in the
VALUES argument. CORDER indicates the values are listed by column.
I=i1,...,in Specifies the row position of each of the n entries in the VALUES argument for a
sparse matrix.
Range: 1 < ik < M, k = 1,...,n

J=i1,...,in Specifies the column position of each of the n entries in the VALUES argument for
a sparse matrix.
Range: 1 < ik < N, k = 1,...,n

220 Adams Solver
NAME=c Specifies the name of a matrix in the file identified by the FILE argument. All types
of files, ADAMSMAT, ADAMSMAT2, MATRIXx , and MATSAVE, can contain
data for more than one matrix. You use the NAME argument to select a particular
matrix from a file even if it contains just one. Additional MATRIX statements are
needed if multiple matrices are to be read from the same file.
Maximum Number of Characters: 8 (all on the same line)
ROWS=i Specifies the number of rows (M) in the matrix.
SPARSE Specifies that a SPARSE input format is used where the row position, column
position, and value are given, usually only for nonzero entry values.
VALUES=r1,...,rn If you select the FULL option, the VALUES argument specifies all of the m times
n entries in the matrix. The sequence depends on the value of the FULL argument.
If RORDER is specified, the values are listed row-by-row. If CORDER is specified,
the values are listed column-by-column.
If you select the SPARSE option, the VALUES argument specifies only the entries
that may be nonzero. That is, Adams Solver (FORTRAN) assumes all entries in the
M x N array not assigned values by the I, J, and VALUES arguments are equal to
zero. The kth entry in VALUES is assigned to the row identified by the kth entry in
I and to the column identified by the kth entry in J for k=1,...,n.
Each pair of I and J entries must specify a unique entry in the array; there can be
no duplicate entries for the same position in the matrix.
Extended Definition
The MATRIX statement defines a general M x N array that can be a rectangular or square two-dimensional
matrix or even a row or column matrix. You can enter the data in a FULL or SPARSE format. When the
matrix has approximately one-third or more of its entries nonzero, the FULL format is more efficient. When
the matrix is mostly empty and the labor associated with entering each nonzero entry’s row position, column
position, and value is less than entering all of the values, you should use the SPARSE format. In cases where
the matrix to be input is very large, you should use the FILE and NAME arguments to specify an external
file containing the matrix.
You can enter data for an M x N matrix into Adams Solver (FORTRAN) from a file specified by the FILE
argument on the MATRIX statement. The contents of the file can be in one of four formats: ADAMSMAT,
ADAMSMAT2, or either the standard FSAVE format or the optional MATSAVE format.
The first 7,8, or 9 characters in the header of the file must be MATRIXx, MATSAVE, ADAMSMAT, or
ADAMSMAT2 to identify the format of the data. Although the remaining content of an ADAMSMAT or
ADAMSMAT2 file (as well as all of an Adams Solver (FORTRAN) dataset) is case insensitive, the identifying
labels at the beginning of the first record in a matrix file must appear exactly as shown.
MATRIX 221
A file in the in the ADAMSMAT or ADAMSMAT2 format consists of variable-length records that must be
laid out as described in the following paragraphs. The example at the end, Table 1, and Table 2 illustrate the
details. The FSAVE and MATSAVE formats are described in MATRIXx literature.
To select the option, the header or first record must begin with the characters ADAMSMAT or
ADAMSMAT2. The remainder of the first record can be used as a title to identify the kind of data in the file.
The second record contains only an integer n right-justified within the first five spaces (the I5 FORTRAN
format). It tells how many matrices are contained in the file. The next several records (one or more) contain
the alphanumeric names (eight characters or less) of all of the matrices in the file. The names are listed
sequentially, four to a line, in eight-character fields separated by ten blanks. That is, the FORTRAN format
for the records containing the matrix names is A8, 10X, A8, 10X, A8, 10X, A8.
Sets of contiguous records define each matrix. Without any intervening blank lines, the blocks of records
begin immediately after the last line of matrix names. The first record in each block contains the name of the
matrix in the first eight characters of the line. The code searches through the file until it finds the block of
records corresponding to the NAME argument on the MATRIX statement.
The first record of the block contains the type of matrix (either FULL or SPARSE) within the second eight
spaces on the record. If the type is FULL, the next eight spaces (from 17 through 24) contain the string
CORDER or RORDER to indicate that the values are listed by column or by row, respectively. Otherwise,
if the type is SPARSE, the space is left blank.
The numerical values specified on the first record of the block include the:
 Number of rows M in the matrix
 Number of columns N
 Total number of entries to be assigned values from the file
If the matrix type is SPARSE, then the total number of entries must be less than or equal to
(generally much less than) M x N. If the matrix is FULL, the total number must be equal to M x N.
 For a matrix in the ADAMSMAT format, the values for M, N, and the total number of entries must
be right justified in the fields 25 to 29, 30 to 34, and 35 to 39, respectively.
 For a matrix in the ADAMSMAT2 format, the values for M, N, and the total number of entries
must be separated by spaces.
The final entry on the first line of the block of records defining each matrix is the format
specification for the records containing the values of the matrix. Beginning in column 40, 41 spaces
are allowed for the character string containing the FORTRAN format specification which must
include delimiting parentheses. The lines of data begin on the next record and continue with
successive records until the code has read into storage either M x N values in case the matrix is FULL
or the total number specified in case the matrix is SPARSE.
Table 1. Specifications for the ADAMSMAT Matrix File
222 Adams Solver

1 1 Header for the file ADAMSMAT A
{CORDER or RORDER if FULL or M,N, A8,
blank if SPARSE} number
Number of rows, columns, and total format 3I5
number of entries
or or
The indices and nonzero entries in the I,J, A(I,J) FORMAT
matrix if SPARSE
Table 2. Specifications for the ADAMSMAT12 Matrix File

1 1 Header for the file ADAMSMAT2 A
{CORDER or RORDER if FULL or M,N, A8,
blank if SPARSE} number
Number of rows, columns, and total Values separated
number of entries by spaces
format
or or
The indices and nonzero entries in the I,J, A(I,J) FORMAT
matrix if SPARSE
MATRIX 223
For a FULL matrix, the code simply reads matrix entries sequentially from the file. If the matrix is SPARSE,
the data have to be organized in triplets: Adams Solver (FORTRAN) reads the row and column indices
followed by the corresponding entry in the matrix. One triplet follows another until the specified total
number of values have been read into the storage arrays.
If another matrix is contained in the file, the block of records defining its structure and containing its values
must follow immediately after the last line of data for the previous matrix.
Tip: The largest square matrix that may be entered directly in the dataset is 48 48. In order to enter
a larger matrix, you must supply the matrix entries in a file using the FILE and NAME
arguments.
Caution: The file name must be on one line following the argument FILE =, which if abbreviated, limits
the identifier to about 75 characters.
Examples
Small Matrix Input
Assume that the following matrix is needed in an Adams Solver analysis:
1.364 0.000
TRF = 0.000 0.000
– 3.546 4.008
0.000 0.799
Because it is small in size, you will have little difficulty in entering the matrix directly into the Adams Solver
(FORTRAN) dataset.
 Version 1, FULL Format (row order):
MATRIX/1, FULL = RORDER, ROWS=4, COLUMNS=2,
, VALUES=1.364,0.000,0.000,0.000,-3.546,4.008,0.000,0.799
 Version 2, FULL Format (column order):
MATRIX/1, FULL = CORDER, ROWS=4, COLUMNS=2,
, VALUES= 1.364,0.000,-3.546,0.000,0.000,0.000,4.008,0.799
224 Adams Solver
 Version 3, SPARSE Format:
MATRIX/1, SPARSE, ROWS=4, COLUMNS=2,
, I=1,3,3,4,J=1,1,2,2,
, VALUES=1.364,-3.546,4.008,0.799
Multiple Matrix Input Using the FILE Option
Assume that in addition to the matrix above, there are two additional matrices you want to enter into Adams
Solver (FORTRAN).
1
1.97 0.00 – 3.44 1.698045 ×10
VALK = 0.00 4.52 6.02 1
– 2.307452 ×10
– 3.44 6.02 2.11 0
STL = 0.00 ×10
0
0.016390 ×10
0
0.044571 ×10
0
0.00 ×10
Assume that you want to use an external file to input the matrices and that all of the matrices are resident in
a file called prob.dat which is in the system subdirectory, /home/staff/demo. The Adams Solver (FORTRAN)
dataset entries would appear as the following:
MATRIX/1, File=/home/staff/demo/prob8.dat, Name= trf
MATRIX/2, File=/home/staff/demo/prob8.dat, Name= valk
MATRIX/3, File=/home/staff/demo/prob8.dat, Name= stl

The leading record of a matrix file is read as character data. The first seven or eight columns must contain
one of the three character strings: MATRIXx, MATSAVE, or ADAMSMAT.
In the current example, the prob.dat is in the directory, /home/staff/demo, and contains the following data:
1 2 3 4 5 6 7
8
123456789012345678901234567890123456789012345678901234567890123456789
01234567890
ADAMSMAT Floating platform example
3
TRF VALK STL
TRF FULL RORDER 4 2 8 ( 8F8.5 )
1.36400 0.00000 0.00000 0.00000 -3.54600 4.00800 0.00000
0.79900
VALK FULL CORDER 3 3 9 ( 3F6.3 )
1.970 0.000-3.440
MATRIX 225
0.000 4.510 6.020

-3.440 6.020 2.110
STL SPARSE 6 1 4 ( 2( 2I5,
E14.6 ) )
1 1 0.169805E+02 2 1 -0.230745E+02
4 1 0.016390E+00 5 1 0.011271E+00
The second and third records are read with format I5 and 4(A8,10X), respectively. Then, the first record of
each of the blocks corresponding to the three matrices TRF, VALK, and STL is read with the format 3A8,
3I5, A41. Finally, as can be seen in the copy of the file shown above between the two strings of 80 characters
that mark the columns (which, of course, are not part of the file), the single record of data for the matrix TRF
is read with the format 8F8.5; the three records for VALK are read with 3F6.3; and the two records for STL
with 2(2I5,E14.6).
Applications
The CURVE, LSE, and NFORCE statements refer to the MATRIX statement. The CURVE statement
specifies a MATRIX statement containing the coordinates of the points defining a general curve in space. For
the LSE statement (Linear State Equation), the MATRIX statement is used to store the system state matrices
(A, B, C, and D). For the NFORCE statement, the MATRIX statement is used to input the system stiffness
and damping matrices (K and C), as well as the free length (Lo) and the preload (Fo).
226 Adams Solver
MFORCE
The MFORCE statement applies a force directly to the modal coordinates and rigid-body degrees of freedom
of a FLEX_BODY.
Format
Arguments
FLEX_BODY=id Specifies the FLEX_BODY on which the modal load is applied. Multiple
MFORCE elements can reference the same FLEX_BODY.
JFLOAT=id Specifies the floating marker on which the reaction force is applied. If you do
not specify a floating marker, Adams Solver (FORTRAN) ignores the
reaction force.
CASE_INDEX=i Specifies the loadcase number that defines the MFORCE. The loadcases are
force distributions that have been predefined and stored in a modal neutral
file (MNF) for an associated FLEX_BODY. Specifically, CASE_INDEX
refers to a column in the MODLOAD matrix that is referenced in the
FLEX_BODY statement. The column contains the modal loads for the
modes selected for an Adams simulation. For more information about how
to generate modal loadcases, see Adams Flex online help.
Note: You can use the CASE_INDEX/SCALE combination of

arguments to define an MFORCE only if you have defined a
MODLOAD matrix for the associated FLEX_BODY.
MFORCE 227
ROUTINE=libname::subn Specifies an alternative library and name for the user subroutine MFOSUB.
ame
SCALE=e Specifies an expression for the scale factor to be applied to the loadcase
referenced by CASE_INDEX. The scale factor and the loadcase are used in
combination to define the modal load. If you use the SCALE argument, it
must be the last argument in the MFORCE statement, or it must be followed
by a backslash (\).
Note: You can use the CASE_INDEX/SCALE combination of

arguments to define an MFORCE only if you have defined a
MODLOAD matrix for the associated FLEX_BODY.
FUNCTION=USER(r1{r2 Specifies that the modal load will be evaluated by a user-written subroutine.
,...,r30}) Adams Solver (FORTRAN) passes the values (r1[,...,r30]) to the user-
written subroutine MFOSUB.
Extended Definition
The MFORCE statement allows you to apply any distributed load vector F to a FLEX_BODY. Such a load
vector is typically generated with a finite-element program. Examples of distributed loadcases include thermal
expansion or pressure loads. To help you understand how Adams handles distributed loads, the following
section discusses the equations of motion of a flexible body, starting with the physical coordinate form that
the finite-element program uses.
Equations
[ M ]x·· + [ K ]x = F
where [ M ] and [ K ] are the finite element mass and stiffness matrices for the flexible component; x is the
nodal coordinate vector; and F is the distributed load vector. This equation can be transformed into the
modal coordinates, q:
T T T
[ P ] [ M ] [ P ]q·· + [ P ] [ K ] [ P ]q = [ P ] F
where [ P ] is the matrix of mode shapes. The modal form simplifies to:
ˆ ˆ
[ M ]q·· + [ K ]q = f
ˆ ˆ
where [ M ] and [ K ] are the generalized mass and stiffness matrices, and f is a modal load case vector that
Adams uses to define the MFORCE element.
The projection of the nodal force vector on the modal coordinates:
T
f = [P] F
228 Adams Solver
This is a computationally expensive operation that poses a problem when F is a general function of time.
Adams circumvents this problem by assuming that the spatial dependency and time dependency can be
separated such that the load is a time varying linear combination of an arbitrary number of static loadcases:
F ( t ) = s1 ( t ) F1 + … + sn ( t ) Fn
Therefore, the expensive projection of the load to modal coordinates is performed only once during the
creation of the MNF, rather than repeatedly during the Adams simulation. Adams needs only to account for
the modal form of the load:
f ( t ) = s1 ( t ) f1 + … + sn ( t ) fn
where the vectors f1 to fn are n different loadcase vectors. Each of the loadcase vectors contains one entry for
each selected mode.
A more general definition of f allows it to have an explicit dependency on system response, which is denoted
as f(q,t), where q represents all the states of the system. The equation for the modal load is then:
f ( q, t ) = s 1 ( q, t ) f 1 + … + s n ( q, t ) f n
which allows the load on a flexible body to be a function of its proximity to another body, such as a heat
source, its velocity, or other.
General Definition of Modal Force
Adams Solver (FORTRAN) lets you define a modal load with the general definition in the last equation.
However, because of the definition’s comprehensiveness, you may find it cumbersome to use. Depending on
your needs, you may be able to use one of the more elementary versions, which are described next, beginning
with the simplest definition.
Definition 1:
If the FLEX_BODY receiving the load has the modal loadcases f1, f2,...,fn defined in its MNF, you can define
the MFORCE by referring to exactly one of the loadcases using the CASE_INDEX argument. The loadcase
is scaled using the SCALE argument, making the load a function of time and/or system response. This
corresponds to the load definition:
f ( q, t ) = s ( q, t ) f i
where CASE_INDEX=i and SCALE=s(q,t) is expressed as an Adams Solver (FORTRAN) function
expression.
Definition 2:
Alternatively, you can achieve the same effect using the MFOSUB user-written subroutine. The MFOSUB
references one of the loadcases and computes the scale factor:
f ( q, t ) = s ( q, t ) f i
where the dependency on q occurs through the use of SYSFNC or SYSARY in the user subroutine. This
method of MFORCE definition is strictly equivalent to the first one.
MFORCE 229
Definition 3:
Alternatively, you can use MFOSUB to combine the loadcases, f1,...,fn as follows:
f ( q, t ) = s ( q, t ) [ g 1 ( t ) f 1 + … + g n ( t ) f n ]
In this case, rather than referencing a single loadcase, the MFOSUB computes a new loadcase by combining
the existing loadcases in a time varying fashion. Adams Solver (FORTRAN) then scales the new loadcase by
a scale factor that is also computed by the MFOSUB. It is important to note that although the scale factor
can be a function of time and of system state, the new loadcase may be only a function of time. In other
words, using values obtained by calls to SYSFNC or SYSARY to define the functions gi(t) is not allowed.
Definition 4:
If the FLEX_BODY has no loadcases in the MNF, then MFOSUB can compute the loadcase. Again, the
loadcase vector may be a function of time only, while the scale factor that is applied to it may be a function
of both time and system state:
f ( q, t ) = s ( q, t ) f u ( t )
where s(q,t) is a user-defined scale factor and fu(t) is a user-defined load vector. This method of MFORCE
specification is primarily provided for completeness, and will be used primarily by very experienced users.
Definition 5:
The general force description:
f ( q, t ) = s 1 ( q, t ) f 1 + … + s n ( q, t ) f n
where each loadcase fi has its own response-dependent scale factor si(q,t) that can be achieved only through
the use of multiple MFORCE elements acting on the same flexible body.
Definition 6:
This is expanded definition of Definition 3 to allow you to indicate multiple scale factors. The force
description is same as Definition 3 as follows:
f ( q, t ) = s ( q, t ) [ g 1 ( t ) f 1 + … + g n ( t ) f n ]
The values of e(q,t) and g1(t), g2(t), … gn(t) are specified in MFOSUB instead of e(q,t) and the term of [ ]
in Definition 3. Note that the modeling is quite same as Definition 3 but this is useful for correct MFORCE
visualization in Adams PostProcessor.
For distributed loads that have an external resultant, portions of the load will project on the rigid body modes
of the flexible body. However, the rigid-body modes must be disabled because Adams Solver (FORTRAN)
will replace them with the nonlinear, large motion, generalized coordinates: X, Y, Z, Ψ , θ , and φ . In this
case, the load on the rigid-body modes are transferred to the large motion generalized coordinates.
Part of this transfer occurs during the MNF2MTX translation of the flexible body's MNF, and, consequently,
the MODLOAD matrix has a dimension that equals 6 plus the number of modes. The first 6 entries in each
column correspond to the external force and torque acting on the flexible body for this loadcase, expressed
230 Adams Solver
relative to the body coordinate system (BCS). When the loadcase is an internal force (as would be expected
in the case of a thermal load), this force and torque will be zero.
You should also be aware of the way modal truncation affects the application of modal load. When you define
a distributed load, it will be projected on the available modes. It is important to understand that the available
modes form an efficient but incomplete basis for the flexible component. Therefore, it is inevitable that some
portion of the load will be orthogonal to modal basis. This portion of the load will be irretrievably lost.
Furthermore, during mode selection within Adams, you should realize that a mode whose removal is being
considered may also have a significant modal load associated with it. In this case, the mode should not be
disabled.
Examples
MFORCE/1, FLEX_BODY = 1, CASE_INDEX = 1
, SCALE = SIN(TIME)*DX(1,4)
Using the first loadcase defined for FLEX_BODY/1, this example defines a modal load on FLEX_BODY/1
by scaling the values of the loadcase by the function expression SIN(TIME)*DX(1,4). The reaction force that
corresponds to this load is ignored.
, FUNCTION = USER(10,1e5,23.)
This example defines a modal load whose reaction resultant force acts on the parent part of floating marker
2. The magnitude and shape of the load is provided by the MFOSUB user-written subroutine, based on the user
parameters 10,1e5,23.
MOTION 231
MOTION
The MOTION statement specifies a system degree of freedom as an explicit function of time. The freedom
is specified by either:
 Specifying the joint and type of motion (translational or rotational).
 Identifying a specific translation or rotational displacement component between two markers
The time dependency can be described in either a function expression or user-written subroutine. The
motion inputs may be a displacement, velocity, or acceleration. Velocity and accelerations are numerically
integrated to provide the displacements, with the initial conditions providing the constants of integration.
Format
232 Adams Solver
Arguments
ACCELERATION Specifies that the FUNCTION argument defines a second time

integrated twice to calculate a corresponding displacement.
Notice, the provided expression may or may not define the
acceleration of a component in the model. For example, if using
the B2 option, the provided expression is the second time
derivative of B2 (Euler angle) which may need other terms to
define the angular acceleration of some component of the model.
B1 Specifies the first angle of the Body 1-2-3 Euler angle sequence as
a function of time. The 123 rotation sequence of the I marker
coordinate system is defined with respect to the J marker
coordinate system.
Range: None
Default: None
B2 Specifies the second angle of the Body 1-2-3 Euler angle sequence
coordinate system.
Range: None
Default: None
B3 Specifies the third angle of the Body 1-2-3 Euler angle sequence
coordinate system.
Range: None
Default: None
DISPLACEMENT Specifies that the FUNCTION argument defines the motion
MOTION 233
 e 
FUNCTION =   Specifies an expression or defines and constants to be passed to the
 USER ( r 1 [ , …, r 30 ] )  MOTSUB user-written subroutine to determine the motion. The
motion must be a function of time only and not a function of the
state variables. To determine the motion with an expression,
follow FUNCTION with an equal sign and the expression. To
determine the motion with a user-written subroutine, follow
the values (r1[,...,r30]) that you want Adams Solver (FORTRAN)
to pass to MOTSUB. If the FUNCTION argument is used, it must
either be the last argument in the MOTION statement or be
followed by a backslash (\).
ICDISP Specifies the initial displacement of the motion, when the motion
Default: 0
ICVEL Specifies the initial velocity of the motion, when the motion is
Default: 0
I=id, J=id Specifies the identifiers of the two markers whose displacement is
being controlled.

body
Default: None
JOINT=id Specifies the identifier of the joint to which the motion is
assigned. The joint must be either translational, revolute, or
cylindrical. If you specify a translational joint, Adams Solver
(FORTRAN) assumes you are assigning translational motion and
does not allow you to assign rotational motion. Similarly, if you
specify a revolute joint, Adams Solver (FORTRAN) assumes you
are assigning rotational motion and does not allow you to assign
translational motion. However, if a cylindrical joint is specified,
either translational or rotational motion can be specified with
TRANSLATION or ROTATION, respectively.
ROTATION Designates a rotational motion. This argument is necessary only
when rotational motion is being applied to a cylindrical joint.
MOTSUB.

TRANSLATION Designates a translational motion. This argument is necessary
only when translational motion is being applied to a cylindrical
joint.
234 Adams Solver
VELOCITY Specifies that the FUNCTION argument defines a time

integrated to calculate the corresponding displacement. This
expression may or may not define the velocity of a component in
the model. For example, if using the B2 option, the provided
expression is the time derivative of B2 (Euler angle) which may
need other terms to define the angular velocity of some
component in the model.
X Specifies DX(I,J,J) as a function of time. DX is the x component
of the displacement of the I marker with respect to the J marker
Range: None
Default: None
Y Specifies DY(I,J,J) as a function of time. DY is the y component
Range: None
Default: None
Z Specifies DZ(I,J,J) as a function of time. DZ is the z component
Range: None
Default: None
Extended Definition
The MOTION statement specifies a translational or rotational degree-of-freedom as a function of time. You
can apply MOTIONs to either joints or between a pair of markers. When a motion is applied on a joint, a
joint degree of freedom is controlled as a function of time. When a motion is applied between a pair of
markers, movement along a user-specified direction is controlled as a function of time. You can define the
value of the degree-of-freedom being controlled, either as a function expression or user-written subroutine.
Motions on Joints
Motions can be specified to act on joints. A translational motion is specified at either a translational or
cylindrical joint. A rotational motion is specified at either a revolute or cylindrical joint. The type of the joint
together with the markers of the joint specify the degree-of-freedom being controlled.
For a translational motion, Adams Solver (FORTRAN) moves the I marker along the z-axis of the J marker.
The J marker origin represents zero displacement while the z-axis of the J marker defines the positive
direction.
MOTION 235
For a rotational motion, Adams Solver (FORTRAN) rotates the I marker about the z-axis of the J marker.
The right-hand rule is used to determine the sign of the motion. The z-axis of the I marker must be colinear
with the z-axis of the J marker at all times. The angle is zero when the x-axis of the I marker is also collinear
with the x-axis of the J marker.
If options VELOCITY or ACCELERATION are used, then the FUNCTION expression does define a local
velocity or acceleration relative to the JOINT Markers.
Motions on Markers
Motions can also be specified to act directly between a pair of markers. No joint is needed when you use this
method. If I and J are the pair of markers between which a motion is specified, then any one of the following
six degrees of freedom may be directly controlled by the motion.
 DX(I,J,J) is the displacement of the origin of the I marker with respect to the origin of the J marker
along the x-axis of the J marker.
 DY(I,J,J) is the displacement of the origin of the I marker with respect to the origin of the J marker
along the y-axis of the J marker.
 DZ(I,J,J) is the displacement of the origin of the I marker with respect to the origin of the J marker
along the z-axis of the J marker.
 B1(I,J) is the first angle of a Body 1-2-3 Euler rotation sequence that measures the orientation of the
I marker with respect to the J marker.
 B2(I,J) is the second angle of a Body 1-2-3 Euler rotation sequence that measures the orientation of
 B3(I,J) is the third angle of a Body 1-2-3 Euler rotation sequence that measures the orientation of
If options VELOCITY or ACCELERATION are used, along with options X or Y or Z, then the
FUNCTION expression does defines either a local translational velocity or acceleration in the I Marker
reference frame. However, if using options VELOCITY or ACCELERATION with options B1 or B2 or B3,
then the FUNCTION expression may not define a local acceleration of a component in the model.
Tip:  If you want to determine the translational or rotational force a motion applies, use a
REQUEST statement with the FORCE argument.
 A MOTION statement can define zero motion with respect to time.
236 Adams Solver
Important: The FORTRAN Solver does not consider any change to MOTION function expression to
be a topology change. This is because the FORTRAN Solver assumes that MOTION
function expression will always be an explicit function of time.
The C++ Solver attempts to determine if a MOTION function expression is an explicit

function of time by analyzing it. If the C++ Solver determines that a MOTION function
expression that IS an explicit function of time has changed to a new expression that is also
an explicit function of time, then there is no change in model topology (which is equivalent
to the FORTRAN Solver).
However, if a MOTION function expression changes to something that IS NOT an explicit

function of time, then the C++ Solver concludes that a topology change has occurred and an
analysis separator will be added to the output files. This is different behavior from the
FORTRAN Solver because the FORTRAN Solver will never add separators to the output
files when a MOTION expression changes.
Caution:  The motion must be a function of only time, not displacements, forces, or any other
variables in the system. Otherwise, Adams Solver (FORTRAN) may have difficulty finding
a solution.
 Motion function expressions are required to have first and second time derivatives. Non-
smooth functions that do not have continuous first and second time derivatives can cause
severe numerical problems.
 Be careful when specifying multi-axial rotational motions between a pair of markers. B1,
B2, and B3 specify a Body 1-2-3 rotation sequence and are Euler angles. This implies that
the first rotation occurs about the x-axis of the J marker, the second rotation about an
intermediate y-axis and the last about the z-axis of the I marker. For example, if you are
measuring rotations between two markers in the sequence z, y, x, this corresponds to a
Body 3 -2 1 rotation sequence, you will have to convert this to a Body 1-2-3 rotation
sequence before specifying it in a MOTION.
 When using any of the following motion types: B1, B2, or B3, avoid situations where the
B2 angle is at +/- 90degrees or +/- 270 degrees. At these angles the Body 1-2-3 angles are
undefined. If this situation occurs, Adams Solver (FORTRAN) issues a warning and stops
the execution. There is no solution for this condition.
 Do not use an initial conditions argument, such as, IC, ICTRAN, or ICROT, on a JOINT
statement with a motion that acts in the same direction on the joint. If both are used,
Adams Solver (FORTRAN) uses the MOTION statement and ignores the initial
conditions argument(s) specifying motion in the same direction(s) specified by the JOINT
statement.
MOTION 237
 If the initial rotational displacement of a revolute or cylindrical joint (as specified by an IC

or ICROT argument on a JOINT statement or by a MOTION statement) varies by
anywhere from 5 to 60 degrees from the initial configuration of the joint as indicated by
the input positions of the two markers constituting the joint, Adams Solver (FORTRAN)
issues a warning message and continues execution. If the variation is greater than 60
degrees, Adams Solver (FORTRAN) issues an error message and stops execution.
 If a MOTION statement generates non-zero initial part accelerations, the Adams Solver
(FORTRAN) integrator may not produce reliable accelerations and velocities for the first
two or three internal integration steps. Adams Solver (FORTRAN) automatically corrects
for this, so that values returned at the first output step are accurate. However, a sensor that
depends on the accelerations or reaction forces due to this motion may trip unexpectedly
prior to the first output step, even though the solution appears correct when the sensor is
removed. If this occurs, you should modify the displacement function in the MOTION
 The ABAM integrator does not support the VELOCITY and ACCELERATION
arguments on the MOTION statement.
 Adams Solver (FORTRAN) cannot perform a kinematic analysis on a zero degree-of-
freedom model containing motions with VELOCITY and ACCELERATION arguments.
A dynamic analysis should be performed instead.
 A function expression for a MOTION statement can not use BISTOP and/or IMPACT
functions.
Examples
MOTION/101, JOINT=101, FUNCTION=10 * SIN(TIME)**2
This MOTION statement acts on the translational joint (101), which implies that the motion is
translational. The motion value as a function of time is 10 * SIN(TIME)**2.
The following MOTION statement is equivalent to the one mentioned above:
MOTION/101, I=1011, J=1012, Z, FUNCTION=10 * SIN(TIME)**2.
MOTION/201, JOINT=201, FUNCTION=POLY(TIME, 0, 0, 360D)
This MOTION statement acts on the revolute joint (201), which implies that the motion is rotational. The
motion value as a function of time is POLY(TIME,0,0,360D).
The following MOTION statement is equivalent to the one described above:
MOTION/201, I=2011, J=2013, B3,
MARKER/11, QP=1,2,3, REU=30D, 45D, 60D, PART=12
MARKER/12, QP=4,5,6, REU=45D, 60D, -34D, PART=23
MOTION/1, I=22, J=11, X, FU=30D*SIN(360D*TIME+30D)
MOTION/2, I=22, J=11, B3, FU=30D*COS(TIME)
This MOTION statement acts between a pair of markers (11 and 12). Two degrees of freedom are explicitly
specified as a function of time:
238 Adams Solver
 The displacement of the origin of Marker 11 with respect to the origin of Marker 12, along the x-
axis of Marker 12, is specified to be 30d*SIN(360D*TIME+30D).
 The rotation about the z-axis of Marker 11 (third angle of the Body 1-2-3 rotation sequence
between Markers 11 and 12) is specified to be 30D*COS(TIME).
MOTION/3014, I=3011, J=3012, B1
, FU=30D*SIN(360D*TIME+30D)
MOTION/3015, I=3011, J=3012, B2
, FU=-25D*SIN(360D*TIME-25D)
MOTION/3016, I=3011, J=3012, B3
, FU=45D*SIN(360D*TIME-57D)
These MOTION statements control the three rotational degrees-of-freedom in a spherical joint by specifying
the Body 1-2-3 angles between the I and J markers of the joint as functions of time.
JOINT/401, PLANAR, I=4011, J=4012
MOTION/4011, I=4011, J=4012, X
, FU=STEP5(TIME, 0.5, 0.0, 4.0, 1.0)*50
MOTION/4012, I=4011, J=4012, Y
, FU=-SHF(TIME, 0.0, 10/2, 2*PI, 90D, 10/2)
MOTION/4016, I=4011, J=4012, B3, FU=0D
 These MOTION statements control the three degrees-of-freedom in a planar joint:
x-axis of Marker 4012, is specified as 40*TIME-25.2.
y-axis of Marker 4012, is specified as -25*SIN(360D*TIME-25D).
 The rotation of Marker 4011 with respect to Marker 4012 about the z-axis of Marker 4011 is
specified to be zero.
MREQUEST 239
MREQUEST
The MREQUEST statement specifies multiple sets of data that you want Adams Solver (FORTRAN) to
write in the tabular output file and request file. You can request sets of displacements, velocities, accelerations,
or forces for system elements such as parts, joints, joint primitives, or applied forces in the system.
Format
240 Adams Solver
Arguments
MREQUEST 241
242 Adams Solver
ACCELERATION Generates acceleration requests that output the accelerations for the markers that
define part centers of mass, joints, joint primitives, or applied forces. This argument
generates nine headings and nine columns of output for each part, joint, joint
primitive, or applied force. The columns in the Tabular Output file include the time
(TIME), the translational magnitude (ACCM), the x component (ACCX), the y
component (ACCY) the z component (ACCZ), the rotational magnitude (WDTM),
the rotational x component (WDTX), the rotational y component (WDTY), and the
rotational z component (WDTZ). The same data without the magnitude are written
in the Request file.
 id1 [ ,…, id30 ] 

APPFORS =  
 ALL 
Indicates that you want to output displacements, velocities, accelerations, or forces for
as many as thirty BEAM, BUSHING, FIELD, GFORCE, NFORCE, SFORCE,
SPRINGDAMPER, VFORCE, and VTORQUE statements or for all of these
statements. For action-reaction forces, Adams Solver (FORTRAN) measures the force
that the J marker applies on the I marker. For action-only forces, Adams Solver
(FORTRAN) measures the external forces acting on the I marker. If a MREQUEST
statement is issued with an APPFORS argument that requests information for an
identifier that is used for two or more applied force statements, Adams Solver
(FORTRAN) outputs information for the first applied force statement with that
identifier. To avoid problems, you may want to use a different identifier for each
applied force statement in the dataset.
COMMENT=c Specifies a title for the top of each set of information the MREQUEST statement
outputs. The entire comment must be on one line. Because the COMMENT
argument can be only eighty characters long at most, the title can be from seventy-two
characters long (if you do not abbreviate COMMENT=) to seventy-eight characters
long (if you abbreviates COMMENT= to C=). Blank spaces and all alphanumeric
characters can be used. However, the comma (,), the semicolon (;), the ampersand
(&), and the exclamation point (!) cannot be used.
MREQUEST 243
DISPLACEMENT Generates displacement requests that output the displacements for the markers that
define part centers of mass, joints, joint primitives, or applied forces. This argument
generates eight headings and eight columns of output for each part, joint, joint
primitive, or applied force. The columns in the tabular output file include the time
(TIME), the translational magnitude (MAG), the x component (X), the y component
(Y), the z component (Z), the psi angle (PSI), the theta angle (THETA), and the phi
angle (PHI). The same data without the magnitude are written in the Request file. For
joints, joint primitives, and applied forces, the psi, theta, and phi angles are the Euler
angle displacements of the I marker with respect to the J marker. For parts, the psi,
theta, and phi angles are the Euler rotations of the part center-of-mass marker with
respect to the ground coordinate system (GCS) or with respect to a J marker you
specify.
FORCE Generates force requests that output the forces for the markers that define joints, joint
primitives, or applied forces. This argument generates nine headings and nine
columns of output for each joint, joint primitive, or applied force. The columns in the
Tabular Output file include the time (TIME), the translational force magnitude
(FM), the translational x component (FX), the translational y component (FY), the
translational z component (FZ), the rotational force magnitude (TM), the rotational
x component (TX), the rotational y component (TY), and the rotational z component
(TZ). The same data without the magnitudes are written to the Request file. The
FORCE argument cannot be used with the PARTS argument.
244 Adams Solver
J=id Specifies a single base marker for measuring the displacements, velocities, or
accelerations of the center-of-mass of the parts. Adams Solver (FORTRAN) makes all
measurements for parts on the center-of-mass marker on each part with respect to the
J marker you specify. The J marker defaults to the ground coordinate system (GCS).
 id1 [ ,…, id30 ] 

JOINTS =  
 ALL 
as many as thirty JOINT statements or for all JOINT statements. Adams Solver
(FORTRAN) makes these measurements on the I marker with respect to the J marker.
 id1 [ ,…, id30 ] 

JPRIMS =  
 ALL 
as many as thirty JPRIM statements or for all JPRIM statements. Adams Solver
(FORTRAN) makes these measurements on the I marker with respect to the J marker.
 id1 [ ,…, id30 ] 

PARTS =  
 ALL 
Indicates that you want to output displacements, velocities, or accelerations for as

many as thirty center-of-mass of parts in the model (to which the PART statement
identifiers refer) or for the centers of mass of all parts (except the ground part). Adams
Solver (FORTRAN) makes these measurements on the center-of-mass marker of the
part with respect to the marker specified by the J argument. The PARTS argument
cannot be used for massless parts. The PARTS argument cannot be used with the
FORCE argument.
VELOCITY Generates velocity requests that output the velocities for the markers that define part
centers of mass, joints, joint primitives, or applied forces. This argument generates
nine headings and nine columns of data for each part, joint, joint primitive, or applied
force. The columns in the tabular output file include the time (TIME), the
translational magnitude (VM), the x component (VX), the y component (VY), the z
component (VZ), the rotational magnitude (WM), the rotational x component
(WX), the rotational y component (WY), and the rotational z component (WZ). The
same data without the magnitudes are written in the request file.
MREQUEST 245
RM=id Identifies the reference marker with respect to which you want to resolve information.
RM defaults to zero, which causes Adams Solver (FORTRAN) to resolve components
in the ground coordinate system (GCS).
Extended Definition
The MREQUEST statement indicates multiple sets of data you want Adams Solver (FORTRAN) to write
in the tabular output file and request file. You can request sets of displacements, velocities, accelerations, or
forces for system elements such as parts, joints, joint primitives, or applied forces in the system.
Adams Solver (FORTRAN) calculates all time derivatives in the ground coordinate system (GCS), although
you can specify that the data be resolved in another reference frame. This is of no importance in the case of
force data, but it can be very important in the case of velocities and accelerations. For example, joint velocities
are actually translational and rotational velocity difference vectors of the joint I marker and the joint J marker
in ground. Joint accelerations are actually translational and rotational acceleration difference vectors of the
joint I marker in ground and the joint J marker in ground.
Because two markers (I and J) define each joint, joint primitive, and applied force, Adams Solver
(FORTRAN) measures the request information for one of these at the I marker with respect to the J marker.
Because a center-of-mass marker is the only marker that is necessary to define a part, Adams Solver
(FORTRAN) measures the request information for a part at its center-of-mass marker with respect to ground
or with respect to an alternative marker you specify. Regardless of the system information you want, a
reference marker (RM) can be used to resolve the component information into any coordinate system you
wish.
Caution:  Note that the units for rotational displacement data in the request output of the tabular output
file default to degrees. The units for all other angular output data default to radians.
 For any argument =ALL, Adams Solver (FORTRAN) ignores any invalid selections.
246 Adams Solver
 Applied forces and torques are those generated by beams, bushings, fields, general forces
(GFORCEs), n-component forces (NFORCEs), single-component forces (SFORCEs),
springdampers (SPRINGDAMPERs), vector forces (VFORCEs), and vector torques
(VTORQUEs). Adams Solver (FORTRAN) outputs the applied forces and torques acting at
the request I marker (which may be either the applied force I marker or the applied force J
marker).
The magnitude and point of force application on the part containing the applied force J
marker varies with the type and source of the force.
• For springdampers, action-reaction single-component forces, general forces, vector
forces, and vector torques, the forces and torques acting at the J marker are equal and
opposite to the forces and torques acting at the I marker.
• For action-only single-component forces, no force or torque acts at the applied force J
marker.
• For beams, fields, bushings, and multi-point forces, the forces acting at the applied
force J marker are equal and opposite to the forces acting at the applied force I marker.
As long as the applied force I marker and the applied force J marker are coincident, the torques
acting at the applied force J marker are equal and opposite to the torques acting at the applied
force I marker. If there is a finite separation distance between the I and J markers, the torques
acting at the applied force J marker are not necessarily opposite or equal, to the torques acting
at the applied force I marker.
 Reaction forces and torques are those generated by constraint-inducing elements. For revolute,
spherical, and universal joints and for atpoint, orientation, parallel axes, and perpendicular
joint primitives, Adams Solver (FORTRAN) outputs the reaction forces and torques acting at
the request I marker (which may be either the constraint I marker or the constraint J marker).
Depending on the type of constraint, some or all of the torques acting at the I marker are zero.
The force and torque acting at the request J marker are equal and opposite to the force and
torque acting at the request I marker.
 Determining reaction forces-and torques for cylindrical, planar, rack-and-pinion, screw, and
translational joints and for inline and inplane joint primitives is more complex. If the request I
marker corresponds to the constraint I marker, then Adams Solver (FORTRAN) outputs the
force and torque acting at the constraint I marker. If the request I marker corresponds to the
constraint J marker, then Adams Solver (FORTRAN) outputs the force and torque acting at
the instantaneous location of the constraint I marker, but on the part containing the constraint
J marker. The force translated to the constraint J marker is the same as computed above. If the
I and J markers are coincident, the torque translated to the constraint J marker is the same as
computed above. But if there is a finite separation between the I and J markers, the torque
translated to the constraint J marker is different from the one computed above (because of the
moments contributed by the reaction forces).
 The MREQUEST statement is not scheduled to be supported in Adams Solver (C++). You are
encouraged to migrate away from this statement and use the REQUEST statement instead.
MREQUEST 247
Examples
MREQUEST/01, DISPLACEMENT, PARTS=1014,1013,1012
This MREQUEST statement requests displacement data for Parts 1014, 1013, and 1012. For each of the
three parts, Adams Solver (FORTRAN) outputs eight headings and eight columns of data to the tabular
output file. The same information also goes to the request file. Because this statement does not supply
arguments J and RM, Adams Solver (FORTRAN) measures the displacements with respect to the ground
coordinate system (GCS), and resolves the displacements in the global coordinate system.
MREQUEST/04, FORCE, JOINTS=ALL
This MREQUEST statement requests the force data for all the joints in the dataset. For each joint, Adams
Solver (FORTRAN) outputs nine headings and nine columns of data to the tabular output file with the same
information going to the request file.
248 Adams Solver
NFORCE
The NFORCE statement creates a multi-point force element which establishes linear force-displacement
(stiffness) and/or force-velocity (damping) relationships between many markers (up to 351) in the model.
Format
Arguments
CMATRIX=id Specifies the identifier of the MATRIX that the NFORCE uses as its damping matrix.
The CMATRIX is a 6n · 6n matrix (n is the number of I markers) that defines the
linear relationships between the I marker velocities relative to the J marker and the
viscous forces generated by the NFORCE. The CMATRIX is derived in the J marker’s
coordinate system. If neither CMATRIX nor CRATIO is given, the NFORCE is
undamped. Marker translational and rotational velocities appear sequentially in Vx,
Vy, Vz, ω x , ω y , ω z order, while the markers appear in the same sequence as in the
IMARKER argument.
CRATIO=r Specifies the proportional damping ratio for the NFORCE. The elements of the
damping matrix are determined by multiplying the corresponding stiffness element
value by this number. If direct input of the damping properties is desired, the
CMATRIX may be used. If neither CMATRIX nor CRATIO is given, the NFORCE
is undamped.
FORCE Specifies the identifier of the MATRIX that contains the forces and torques that the
NFORCE would produce if all the I markers were at the positions given in LENGTH.
FORCE is a 6n · 1 matrix (n is the number of I markers) of forces and torques,
appearing sequentially for each marker in Fx, Fy, Fz, Tx, Ty, Tz order, while the markers
appear in the same sequence as in the IMARKER argument. The force and torque
components are expressed in the J marker’s coordinate system. When LENGTH is
used to specify the system’s free lengths, FORCE gives the preloads. If FORCE is not
given, the NFORCE acts as though a matrix of zeros are input.
NFORCE 249
IMARKERS=id1,.. Lists the markers (except for the J marker) between which the NFORCE forces and
.,idn torques act.
Number of values: 1 to 350

J=id Specifies the identifier of the marker that determines the reference frame in which the
relative velocities and all of the forces associated with the NFORCE are calculated and
the coordinate system in which all the components and LENGTHs are evaluated. The
NFORCE automatically applies the proper reaction forces at the J marker.
KMATRIX=id Specifies the identifier of the MATRIX that the NFORCE uses as its stiffness matrix.
The KMATRIX is a 6n · 6n matrix (n is the number of I markers) that defines the
linear relationships between the I marker displacements relative to the J marker and
elastic forces generated by the NFORCE. The KMATRIX is specified in the J marker’s
coordinate system. Marker translational and rotational displacements appear
sequentially in Dx, Dy, Dz, Ax, Ay, Az, order, while the markers appear in the same
sequence as in the IMARKER argument.
LENGTH=id Specifies the identifier of the MATRIX that defines a reference location for each of the
I markers with respect to the J marker, measured in the J marker’s coordinate system.
LENGTH is a 3n · 1 column matrix (n is the number of I markers) of translational
displacements only, in Dx, Dy, Dz order. Usually, LENGTH is used to specify the
system’s free (no internal force) lengths when they differ from the input positions. If
LENGTH is not given, the NFORCE assumes that the input positions of the I
markers are at the reference locations.
Extended Definition
The NFORCE creates a set of forces and torques which act between the I and J markers which appear in the
NFORCE statement. These forces and torques are linear functions of the relative displacements and velocities
of the markers, in a manner equivalent to the finite element method. For each NFORCE, one marker (J) is
used as the reference marker. The velocities are resolved into the J marker’s reference frame and expressed in
the J marker’s coordinate system. The force and torque components computed by the NFORCE are also
given in the J marker’s coordinate system.
The force-displacement and force-velocity relationships are specified using stiffness and damping matrices,
or by using a stiffness matrix and a proportional damping ratio. These matrices are defined using MATRIX
statements in the dataset. The stiffness and damping matrices that Adams Solver (FORTRAN) requires are
defined for the I markers only; that is, they should be derived normally using the 6(n+1) J marker and I
marker degrees-of-freedom, but are input using only the rows and columns corresponding to the I marker
degrees-of-freedom. This is equivalent, in finite element terminology, to applying fixed boundary conditions
at the J marker by simply removing the corresponding rows and columns from the matrices. Adams Solver
(FORTRAN) automatically computes and applies the correct reaction forces at the J marker.
Formulation
For n+1 points in the NFORCE system (n I markers and 1 J marker).
Action Forces (Forces on the I markers)
250 Adams Solver
FI = - KMATRIX (X - L) - CMATRIX X· + FORCE

where:
 FI is the 6n x 1 matrix of forces exerted on the I markers.
 KMATRIX is the 6n x 6n truncated stiffness matrix, created by striking out the rows and columns
 X is the 6n x 1 matrix of the translational and angular displacements of the I markers with respect to
the J marker, expressed in the J marker’s coordinate system.
 L is a 6n x 1 matrix of the reference displacements of the I markers with respect to the J marker,
expressed in the J marker’s coordinate system. The translational displacements in L are the elements
of LENGTH, while the angular reference displacements are always zero.
 CMATRIX is the 6n x 6n truncated damping matrix, created by striking out the rows and columns
 X· is the 6n x 1 matrix of the translational and linearized angular velocities of the I markers with
respect to the J marker, and expressed in the J marker’s coordinate system.
 FORCE is the 6n x 1 matrix of the reference forces on the I markers; that is, the forces on the I
markers when their displacements relative to the J marker are specified by L. When LENGTH
contains the free lengths, FORCE is the preload.
Reaction Forces (Forces on the J marker)
F jtrans = –  F i trans
i
F j rot = –  ( F i rot + X ji × F i trans )
i
where:
 trans denotes translational degrees-of-freedom
 =rot denotes rotational degrees-of-freedom
 Xji is the instantaneous vector from the J marker to each I marker.
NFORCE 251
Tip:  When importing stiffness and damping matrices that are developed using finite
element methods, the LENGTH and FORCE arguments are most easily thought of
as the system free lengths (zero internal stress) and preloads. You can, however, specify
any consistent set of reference lengths and resulting forces, just as for the
SPRINGDAMPER element.
 Physically meaningful NFORCES have positive semi-definite KMATRIX and
CMATRIX matrices. That is, the diaginal enteries of the matrices have positive value.
Adams Solver (FORTRAN) only accepts NFORCES having positive semi-definite
matrices.
Caution:  Like the BEAM, the NFORCE is a linear element, so that the forces computed are
generally valid only for small displacements. When the applied loading is such that
the small displacement limits are exceeded (a good estimate is ten percent of lengths
and less than 0.2 radian rotations), the NFORCE results may be less accurate. In cases
where the structure undergoes large overall deflections but remains linearly elastic
(small local deflections), you can use more NFORCE elements, so that each
NFORCE element remains locally within small displacement limits. Note that
because of the way that Adams Solver (FORTRAN) computes angular displacements,
the absolute magnitude of this inaccuracy due to overly large displacement may
depend on the instantaneous spatial orientation of the system.
 A two-point NFORCE is not identical to a field, although it is very similar. The
following differences make it difficult to create exactly equivalent NFORCEs and
FIELDs.
• The FIELD defaults reference lengths to zero, while the NFORCE assumes by
default that the input positions of the I markers are at the reference locations.
• The FIELD allows you to specify reference angles for the rotational displacements,
while the NFORCE assumes the reference angles are always zero.
Examples
The figure below illustrates a simple, planar, triangular truss attached to some large base body.
Simple, Planar, Triangular Truss
252 Adams Solver
The following NFORCE statement defines a 24 force components acting between Markers 10, 20, 30, and
40.
NFORCE/1234, J=10, I=20,30,40, KMATRIX=1234, CRATIO=0.02
Marker 10 is the J marker. This means Matrix 1234 is an 18-by-18 stiffness matrix relating forces to
displacements at Markers 20, 30 and 40. The forces and displacements are measured in the coordinate system
of Marker 10. Because the LENGTH argument is not included, Adams Solver (FORTRAN) measures the
displacements from the input position. Because the FORCE argument is not specified, there are no loads at
the reference position (in this case the input position). In other words, the truss has been input in the
unloaded, undeformed configuration. The damping matrix is .02 times the stiffness matrix.
Depending on the assumptions you make, the stiffness matrix for this structure could be quite elaborate. A
simple case, however, is to assume the ends of the truss members are pinned, and that the truss members only
transmit translational, in-plane forces.
Due to the simple geometry, this matrix can be determined by inspection, and is shown in the table shown
next.
Simple Stiffness Matrix
NFORCE 253
Because this matrix is mostly empty, the SPARSE option on the MATRIX statement is more convenient than
listing all the matrix entries. The following MATRIX statement defines this stiffness matrix.
MATRIX/1234, SPARSE, ROW=18, COL=18,
, I=1,1,1,1,2,2,2,2,7,7,7,7,7,8,8,8,8,8,13,13,13,13,14,14,14,14,
, J=1,2,7,8,1,2,7,8,1,2,7,13,14,1,2,8,13,14,7,8,13,14,7,8,13,14,
, VALUE=150,-50,-50,50,-50,50,50,-50,-50,50,100,-50,50,
, 50,-50,200,50,-50,-50,50,150,-50,50,-50,-50,50
Applications
The NFORCE statement may be most useful for importing finite element representations of flexible
structure into an Adams Solver (FORTRAN) model, but it may also be used whenever the forces between a
set of points in the system are linearly dependent on their relative displacements and velocities. If the set
includes only two points, it is easily use one of the simpler Adams Solver (FORTRAN) force elements,
SPRINGDAMPER, SFORCE, BEAM, BUSHING or FIELD, depending on the type of forces desired.
254 Adams Solver
However, whenever the set includes three or more points, you should use the NFORCE statement. (Note
that some of the other force elements do allow for nonlinear force relationships.)
You may develop the NFORCE statement stiffness and damping matrices in several ways. For simple
structures, you can derive the matrices analytically or compute them from standard formulas. For complex
cases, you can use finite element analysis (FEA) to approximate the stiffness and damping characteristics.
For example, the figure below illustrates a satellite deploying flexible panels. In this instance, the panels are
first modeled using a 6 6 finite element grid (36 elements), which are then reduced to a 3 3 grid using super-
element condensation before importing it into Adams Solver (FORTRAN) as an NFORCE. Because of
formulational differences between FEA and Adams’ multibody systems analysis, it is generally not possible to
have a one-to-one correspondence between Adams Solver (FORTRAN) PARTs and FEA nodes, unless the
FEA model is very small.
Flexible Satellite Panels

OUTPUT 255
OUTPUT
The OUTPUT statement controls the generation of request and graphics files. It also controls the form,
format, coordinates, filtering, and scaling of request data in the tabular output file (.out).
The OUTPUT statement has been extended to control generation and format of output files from
FEMDATA or REQUEST statements. For example, it lets you generate RPC III and DAC files of Adams
Solver (FORTRAN) request data.
256 Adams Solver
Format
OUTPUT 257
Arguments
ABAQUS Specifies the output of FEM data to an ABAQUS-readable format. Load data are
written out as ABAQUS input commands.
ANSYS Specifies the output of FEM data to an ANSYS-readable format. Load data or
nodal deformations are written out as ANSYS input commands. Modal
deformations are written out to a file format supported by the Adams MSR
ANSYS-customized macro, available in Adams Durability.
ASCALE=r1[,r2] Scales the translational and rotational accelerations Adams Solver (FORTRAN)
outputs. Define r1 to scale the translational accelerations and r2 to scale the
rotational accelerations. Both r1 and r2 default to 1.0.
AZERO=r Specifies that output accelerations less than r in magnitude are to be set equal to
zero. The value of r must be greater than zero. The value of r defaults to 1.0E-7
for output in scientific notation and to 0.001 for output in fixed-point notation.
CHART Produces x-y charts of the request data for the tabular output file. If you do not
specify CHART, Adams Solver (FORTRAN) does not produce charts of the
request data for the tabular output file.
DAC Specifies the output of FEM data to DAC files. DAC is a file format supported
by nCode/nSoft. A DAC file is generated for each component of load, stress or
strain, or modal coordinate.
DACSAVE Saves all request output in DAC format. If you do not specify DACSAVE, Adams
Solver (FORTRAN) does not save request data in DAC format.
DSCALE=r1[,r2] Scales the translational and rotational displacements Adams Solver (FORTRAN)
outputs. Define r1 to scale the translational displacements and r2 to scale the
rotational displacements. Both r1 and r2 default to 1.0.
DZERO Specifies that output displacements less than r in magnitude are to be set equal
to zero. The value of r must be greater than zero. The value of r defaults to 1.0E-
7 for output in scientific notation and to 0.001 for output in fixed-point
notation.
FIXED Formats numerical output in fixed-point notation. Any values that are too small
or too large for fixed-point notation are output in scientific notation. If you do
not specify FIXED, Adams Solver (FORTRAN) formats numerical output in
scientific notation.
FSCALE=r1[,r2] Scales the translational and rotational forces Adams Solver (FORTRAN)
outputs. Define r1 to scale the translational forces and r2 to scale the rotational
forces. Both r1 and r2 default to 1.0E0 in scientific notation and to 1.0 in fixed-
point notation.
FZERO Specifies that output forces less than r in magnitude are to be set equal to zero.
The value of r must be greater than zero. The value of r defaults to 1.0E-7 for
output in scientific notation and to 0.001 for output in fixed-point notation.
GENERIC Specifies the output of FEM data to a human readable (ASCII) text file.
258 Adams Solver
GRSAVE Saves graphics output in the graphics file so a postprocessor can be used to display
graphics. If neither GRSAVE nor GR521SAV is specified, Adams Solver
(FORTRAN) does not save graphics output in the graphics file.
GR521SAVE Saves graphics output in the graphics file in Adams 5.2.1 format. Graphics files
written by Adams 6.0 and later (when GRSAVE is specified) contain more
information than those written by Adams 5.2.1. Consequently, applications
written to use the older files may no longer work with 6.0 and later files. If the
application does not accept 6.0 and later files, you can specify GR521SAV to
create a 5.2.1 format file. A 5.2.1 graphics file does not contain curve graphics,
road surface graphics, or floating markers. If neither GRSAVE nor GR521SAV
is specified, Adams Solver (FORTRAN) does not save graphics output in the
graphics file.
LOADS Controls output of FEM data to the specified format. If you do not specify
LOADS, Adams Solver (FORTRAN) does not process any FEMDATA/LOADS
statements.
MODAL_DEFORMA Controls output of modal deformation data to the specified format. If you do not
TION specify MODAL_DEFORMATION, Adams Solver (FORTRAN) does not
process any FEMDATA/MODAL_DEFORMATION statements.
NASTRAN Specifies the output of FEM data to a NASTRAN readable format. Load data or
nodal deformations are written out as NASTRAN input commands. Modal
deformations are written out to NASTRAN OUTPUT2 (binary) format.
NODAL_DEFORMA Controls output of nodal deformation data to the specified format. If you do not
TION specify NODAL_DEFORMATION, Adams Solver (FORTRAN) does not
process any FEMDATA/NODAL_DEFORMATION statements.
NOPRINT Suppresses printing of all time-response-request tables. If you do not specify
NOPRINT, Adams Solver (FORTRAN) prints these tables (one table for each
request) in the tabular output file after the simulation is complete.
OUTPUT 259
NOSEPARATOR Specifies that Adams Solver (FORTRAN) is not to write separators to the
request, graphics, results, and tabular output files when you modify the model
topology in the middle of a simulation. You can change the model topology by
using interactive commands to activate an element, deactivate an element,
change a marker position, or change the type or point of application of a force or
constraint during a simulation.
When you change the model topology, by default, Adams Solver (FORTRAN)
writes a separator and new header to the request, graphics, results, and tabular
output files. Adams Solver (FORTRAN) then writes subsequent simulation
output after the new headers. This ensures that the changes are correctly reflected
in the output files, but it creates two sets of output that cannot be plotted or
animated continuously. The NOSEPARATOR argument prevents Adams Solver
(FORTRAN) from breaking up the files; instead it creates a continuous set of
output that can be plotted and animated from beginning to end.
Note: This output may be misleading because the graphics file does not
include the effects of any changes in marker, force, or constraint
positions during the simulation. While the part motions are correct,
the force, joint, and marker graphics remain in their original positions,
even if you move them during the simulation.
OSFORMAT Writes output-step-request (OS) tables to the tabular output file immediately
after completion of each output step for dynamic, kinematic, or quasi-static
equilibrium analysis. If OSFORMAT is specified, Adams Solver (FORTRAN)
outputs an OS table at each output time step during simulation. If OSFORMAT
is not specified, Adams Solver (FORTRAN) does not output request data in this
form for these analysis types. When a static equilibrium analysis is requested,
Adams Solver (FORTRAN) always outputs an OS table whether or not you
specify OSFORMAT.
Use OSFORMAT to view the values of all requests at a particular output time or
to provide printed output in cases where the simulation might not run to
completion. A simulation may not run to completion because the model or user-
written subroutines are not fully debugged. OSFORMAT might provide
information useful in debugging the model or user-written subroutines.
PUNCH Specifies modal deformations to be output to NASTRAN PUNCH (text file)
format.
REQSAVE Saves request output in the request file so that you can use a postprocessor to
display x-y plots. If you do not specify REQSAVE, Adams Solver (FORTRAN)
does not save the request output in the request file.
RPC Specifies the output of FEM data to an RPC III file. RPC III is a file format
supported by MTS. Each channel in the RPC file represents a load component
acting on the part.
260 Adams Solver
RPCSAVE Saves all request output in RPC III format. If you do not specify RPCSAVE,
Adams Solver (FORTRAN) does not save request data in RPC III format.
STRAIN Controls output of strain data to the specified format. If you do not specify
STRAIN, Adams Solver (FORTRAN) does not process any
FEMDATA/STRAIN statements.
Note: An Adams Durability license is required to output STRAIN.

STRESS Controls output of stress data to the specified format. If you do not specify
STRESS, Adams Solver (FORTRAN) does not process any
FEMDATA/STRESS statements.
Note: An Adams Durability license is required to output STRESS.

TELETYPE Indicates that Adams Solver (FORTRAN) is to format tabular output for
printers with 72 columns per line, rather than for printers with 132 columns per
line.
OUTPUT 261
VSCALE=r[,r2] Scales the translational and rotational velocities Adams Solver (FORTRAN)
outputs. Define r1 to scale the translational velocities, and define r2 to scale the
rotational velocities. Both r1 and r2 default to 1.0.
VZERO Specifies that output velocities less than VZERO in magnitude are to be set equal
to zero. The value of r must be greater than zero. VZERO defaults to 1.0E-7 in
scientific notation and to 0.001 in fixed-point notation.
YPR Outputs rotational displacement values in yaw, pitch, and roll coordinates, rather
than in psi, theta, and phi coordinates. Using dashed lines to represent original
orientations and using solid lines to represent new orientations, Figure 1 below
shows how these coordinates define a rotational orientation.
Figure 1. Successive Yaw, Pitch, and Roll Rotations
First, Adams Solver (FORTRAN) rotates about the z-axis. Next, it makes a
negative rotation about the new y-axis (y'), and then about the second new x-axis
(x"). If you do not specify YPR, Adams Solver (FORTRAN) outputs rotational
displacement values in psi, theta, and phi coordinates.
YPR only affects rotational displacement output. Adams Solver (FORTRAN)

always outputs angular velocities and accelerations as vectors, with orthogonal x,
y, and z components.
Extended Definition
The OUTPUT statement controls the generation of request and graphics files. In addition, it controls the
form, format, coordinates, filtering, and scaling of request data in the tabular output file. Also, the OUTPUT
statement controls the generation and format of REQUEST or FEM data. Specifically, the OUTPUT
statement controls the following:
 Forms of Request Data in the Tabular Output File
 Formats of Request Data in the Tabular Output File
 Numerical Notation of Request Data in the Tabular Output File
 Coordinates of Rotational Request Data in the Tabular Output File
262 Adams Solver
 Scales for Request Data in the Tabular Output File

 Filters for Request Data in the Tabular Output File
 Output of FEMDATA
 Output of Request Data in RPCIII and DAC Formats
Forms of Request Data in the Tabular Output File
X-Y charts of the request data for the tabular output file — the output is in the same order as the requests are
in the dataset. The information about each request (including those created by an MREQUEST
command/statement) is in two parts. The left side of the first part contains a table of simulation time and the
translational information output by the request, and the right side contains a plot of the translational
information against time. The left side of the second part contains a table of simulation time and the
rotational information output by the request, and the right side contains a plot of the rotational information
against time (see Figure 2). (The column titles may vary according to the type of request information and
other arguments on the OUTPUT command/statement.)
These plots differ in two important ways from the plots created with Adams Solver (FORTRAN) or most
postprocessors. First, time is along the vertical axis in the chart plots and request data is along the horizontal
axis. Second, the chart plots are normalized; that is, each curve is scaled independently of the others from the
highest value to the lowest value for that curve. Therefore, use care when comparing curves to one another.
You can compare the shapes but not the magnitudes of the curves.
 Time-response-request tables — A time-response-request table lists all values for a single request
throughout the simulation. One line appears in the table for each output time step; the lines are in
ascending order of time.
 Output-step-request (OS) table — An OS table lists the values of all requests at each output time step.
One line appears for each output time step, followed by one line per request.
Formats of Request Data in the Tabular Output File
Columns per line:
 72 columns
 132 columns
Numerical Notation of Request Data in the Tabular Output File
 Fixed-point - Fixed-point notation expresses a decimal or an integer number without an exponent.
 Scientific - Scientific notation expresses a number as a value between 1 and 10 (the mantissa)
multiplied by the appropriate power of 10 (the exponent). Adams Solver (FORTRAN) uses E
between the mantissa and exponent, and a decimal number as the value.
Coordinates of Rotational Request Data in the Tabular Output File
 Yaw, pitch, and roll angles
 Psi, theta, and phi angles
Scales for Request Data in the Tabular Output File
 Scale for displacements
 Scale for velocities
OUTPUT 263
 Scale for accelerations

 Scale for forces
Filters for Request Data in the Tabular Output File
 Zero filter for displacements
 Zero filter for velocities
 Zero filter for accelerations
 Zero filter for forces
Output of FEMDATA
With LOADS, the ABAQUS, ANSYS, or NASTRAN format option creates a text file of the input
commands of the respective FEA package (case control and bulk data in the case of NASTRAN) of all the
part forces.
With NODAL_DEFORMATION, the ANSYS or NASTRAN option creates a text file of input commands
for defining enforced displacements in the respective FEA package (for example, SPC* cards in the case of
NASTRAN).
With MODAL_DEFORMATION, the NASTRAN option produces an OUTPUT2 (NASTRAN binary)
file. This file can be imported by NASTRAN for stress recovery on the flexible body using the Adams
Durability Modal Stress Recovery. Note that this file format is machine dependent. NASTRAN will not be able
to read the file if it was created on a platform different than the one running NASTRAN.
Alternatively, the PUNCH format option for MODAL_DEFORMATIONS produces a text file that can be
imported by NASTRAN for stress recovery. This file format is not as compact as the OUTPUT2 format (see
NASTRAN option), but it is machine independent. If NASTRAN is run on a different platform than
Adams, the modal deformations can be transferred via this file format for subsequent NASTRAN runs.
Also, with MODAL_DEFORMATIONS, the ANSYS option produces a file of modal deformations. This
file can be processed by ANSYS using a custom macro provided by Adams Durability (Reading Modal
Deformations File (MDF)). Modal deformations can be combined with the modal stress shapes stored in the
ANSYS database to recover dynamic stresses in ANSYS using modal superposition.
Output of Request Data in RPCIII and DAC Formats
You can save request data in RPC III and DAC format.
 RPC III format- Adams Solver (FORTRAN) creates one RPC file of all data components specified
in the REQUEST statements.
The RPC III file is named according to the naming convention:
Prefix.rsp
where:
• Prefix is the prefix specified when you set up Adams results.
 DAC format - Adams Solver (FORTRAN) can only store one channel of data in a DAC file.
Therefore, Adams Solver (FORTRAN) creates six DAC files, one per request component. The files
are named according to the DAC file naming convention:
prefix_request name_component label.dac
264 Adams Solver
where
• prefix is the prefix you specified when you set up the Adams results.
• request name is the request name you specified when you created a new request.
• component label is the reserved label assigned to the six components of request data by Adams
(one of X, Y, Z, R1, R2, R3).
Caution:  TELETYPE or CHART cannot be used with OSFORMAT because OSFORMAT prints
records 132 characters wide and because CHART prints information next to a plot.
 The ICSAVE argument and .icf file have been discontinued. The SAVE and RELOAD
commands replace the OUTPUT/ICSAVE and EXECUTION/ICSTART arguments.
Examples
OUTPUT/GRSAVE, REQSAVE
This OUTPUT statement causes Adams Solver (FORTRAN) to save both graphics and request output.
, FILE=adams
, NODE=100, 200, 300
OUTPUT/STRESS=DAC
DAC files are created with the job name adams in the FLEX_BODY_201 subdirectory. Each DAC file
contains the time history of one of the six stress components (Sx, Sy, Sz, Txy, Tzx, Tyz) at a node. Since three
nodes are specified, a total of eighteen DAC files are created.
OUTPUT/MODAL=NASTRAN, NODAL=GENERIC
A NASTRAN binary file will be created of each FEMDATA statement with modal deformations. No output
files will be generated for loads, strain or stress since no OUTPUT specification was given for these types of
FEMDATA.
REQUEST/1, DISPLACEMENT, I=201, J= 103, TITLE=REQ01
OUTPUT/DACSAVE
This OUTPUT statement causes Adams Solver (FORTRAN) to save request output defined in the above
REQUEST statement to DAC files only. Adams Solver (FORTRAN) creates a total of six DAC files in the
current working directory with the following names:
adams_req01_x.dac
adams_req01_y.dac
adams_req01_z.dac
adams_req01_r1.dac
adams_req01_r2.dac
adams_req01_r3.dac
REQUEST/3 FORCE, I=203, J=105, TITLE=REQ03
OUTPUT, RPCSAVE
OUTPUT 265
This OUTPUT statement causes Adams Solver (FORTRAN) to save request output defined in the three
REQUEST statements to an RPC III file. Adams Solver (FORTRAN) creates one RPC III file named
Adams.rsp, containing 18 channels of data (six per REQUEST statement).
266 Adams Solver
PART
The PART statement defines the inertial properties of a rigid body and its initial position, orientation, and
velocity. Parts can have any shape or size and are the only model elements that can have mass, although they
may be massless under certain circumstances. Adams Solver (FORTRAN) assumes that all parts are rigid
bodies. The PART statement is also used to specify which part is used as the fixed inertial (or ground) global
coordinate system. Each movable part (that is, other than ground) can add up to 6 degrees of freedom (DOF)
to a system.
Format
PART 267
Arguments
CM=id Specifies the identifier of the marker that defines the location of the part center
of mass and, in the absence of the inertia marker, the orientation of the inertia
axes for the IP values.
EXACT=c1:...:c6 Specifies as many as six part coordinates that Adams Solver (FORTRAN) should
not change as it iteratively solves for initial conditions that satisfy all constraints.
The six coordinates are:
X - x coordinate
Y - y coordinate
Z - z coordinate
PSI - Psi angle
THETA - Theta angle
PHI - Phi angle
changed by Adams Solver (FORTRAN) unless the values specified are
inconsistent with initial conditions for a joint or for a defined motion.
GROUND Indicates the part being defined as the Newtonian reference frame. It is, by
definition, at absolute rest. Because there can be only one ground part in the
system, a dataset must never have more than one PART statement with the
GROUND argument.
IM=id Specifies the identifier of the marker about which you specify the moments of
inertia for the part. This marker can be any marker in the part. The IM marker
defaults to the CM marker.
268 Adams Solver
IP=xx,yy,zz[,xy,xz,yz] Specifies the mass-inertia tensor as computed about the origin of the IM marker,
expressed in the coordinate system of the IM marker.

2 2
Ixx =  (y + z ) dm
2 2
Iyy =  (x + z ) dm
2 2
Izz =  (x + y ) dm
Ixy =  xy dm
Ixz =  xz dm
Iyz =  yz dm
In the above formulae, x, y, and z are the components of the displacement of the
center of an infinitesimal volume of mass dm, measured from the origin of the
inertia marker in the coordinate system of the inertia marker. The integral is
performed over the entire volume of the body. If the inertia marker is not
specified, it defaults to the CM marker. In that case, these quantities are
computed about the origin of the CM marker in the coordinate system of the
CM marker.
Note: Adams Solver (FORTRAN) defines Ixy, Ixz, and Iyz as positive
integrals, as shown. Some references define these terms as the negative
of these integrals. You should be sure to compute these values as shown
above.
MASS=r Specifies the part mass.
QG=x,y,z Defines the Cartesian initial coordinates of the origin of the body coordinate
rotations are in radians and are, respectively, about the z-axis of ground, the new
x-axis, and the new z-axis of the BCS. To input Euler angles in degrees, you
should add a D after each value.
VM=id Specifies the identifier of the marker that specifies the direction of translational
velocity initial conditions (VX, VY, and VZ). VM defaults to global orientation.
ground coordinate system (GCS) along the x-axis (VX), the y-axis (VY), and the
z-axis (VZ) of the GCS.
PART 269
WM=id Specifies the identifier of the marker that specifies the axes about which angular
velocity initial conditions (WX, WY, and WZ) are defined. WM defaults to the
CM location and orientation. Furthermore, the origin of the WM marker lies on
the axis of rotation. This is most useful for rotating systems. A typical application
is a spinning flexible satellite model in space. In this case, you add a marker to
your system at the combined CG location of the system and orient the marker
such that one of its axes is along the spin axis of the satellite.
WX=a, WY=b, WZ=c Specifies the initial rotational velocities, in radians per second, of the part about
the x-axis (WX), the y-axis (WY), and the z-axis (WZ) of the CM marker
coordinate system.
XG=x,y,z Defines the coordinates, measured in the GCS, of any point in the positive x-z
plane of the part BCS, but not on the z-axis of the part BCS.
ZG=x,y,z Defines the coordinates measured in the GCS of any point on the positive z-axis
of the BCS.
270 Adams Solver
Tip:  If the part has no CM marker, as may be the case for some massless parts, Adams Solver
(C++) uses the part BCS to represent the position and orientation of the part internally.For
more information on BCS, see Coordinate Systems and Local Versus Global Geometric Data.
 Using a CM on a massless part can improve model robustness by removing large offsets
between the BCS and markers on the massless part, without repositioning all the markers
on the massless part. Do not be confused by the contradiction of specifying a center-of-
mass of a massless part. In this case the CM marker is simply suggesting an advantageous
choice of internal coordinate systems.
 If the part has mass, Adams Solver (FORTRAN) uses the position of the CM marker to
represent the translational position of the part internally and uses the principal axes of the
inertia tensor about the CM marker to represent the orientation of the part internally. This
internal coordinate system is commonly referred to as the part principal coordinate system.
 Due to a basic property of Euler angles, a singularity occurs when the principal z-axis of
the CM becomes parallel to the ground z-axis. Whenever the principal z-axis of the part
nearly parallels the ground z-axis, Adams Solver (FORTRAN) rotates the part principal
axes 90 degrees about the z-axis and then 90 degrees about the new x-axis to avoid the
singularity. Adams Solver (FORTRAN), however, does not change the marker locations
and orientations with respect to the BCS nor does it alter the BCS location or orientation
with respect to ground. (The principal axes of the inertia tensor of the CM are referred to
as the part principal axes.)
 The BCS for each part can have any position and orientation. In fact, the location of the
BCS does not have to be within the physical confines of the part. It may be at some
convenient point outside the actual part boundaries.
 To superimpose the BCS of a part on the GCS, define QG=0,0,0 and REULER=0,0,0 or
let QG and REULER default. The position and orientation data for the markers on the
part is now with respect to the GCS.
PART 271
Caution:  Each part defined with the PART statement, with the exception of ground, must have at
least one marker associated with it (see MARKER).
 For the argument IP, if one of the moments of inertia (xx, yy, or zz) is specified, the other
two must be specified. Similarly, if one of the products of inertia (xy, xz, or yz) is specified,
the other two must be specified.
 Make sure the units for mass moments of inertia and for mass products of inertia are
consistent with the units for the rest of the system.
 Parts that are not fully constrained (that is, they can move dynamically due to the effect of
forces) must have nonzero masses and/or inertias. You may assign or default zero mass to a
part whose six degrees of motion are fully constrained with respect to parts that do have
mass.
 EXACT, VX, VY, VZ, WX, WY, and WZ arguments ensure that the corresponding
displacements or velocities are maintained to an accuracy of six digits. Accuracy beyond six
digits is not guaranteed.
 Use the EXACT, VX, VY, VZ, WX, WY, and WZ arguments with caution. Do not specify
more initial displacements to be exact than the system has degrees of freedom. After you
are sure the system has zero or more degrees of freedom, look at the model and see if the
remaining set of part motions will permit Adams Solver (FORTRAN) to adjust the system
to satisfy all the initial conditions. Remember that IC, ICTRAN, and ICROT arguments
on the JOINT statement remove degrees of freedom from a system during initial conditions
analysis. Similarly, do not specify more initial velocities than the system has degrees of
freedom.
 A part without mass cannot have moments of inertia, or initial conditions on displacement
or velocity, or an IM marker.
 If you specify the mass for a part, you must also specify the CM marker for the part.
Examples
PART/01, GROUND
This PART statement indicates that Part 1 is the ground part.
PART/02, MASS=2, CM=0201, IP=5,6,10
This PART statement specifies the mass (2 units), the center-of-mass marker identifier (0201), and the
principal moments of inertia for Part 2 (Ixx = 5 units, Iyy = 6 units, Izz = 10 units). The principal moments
of inertia are about the x-axis (5), the y-axis (6), and the z-axis (10) of the center-of-mass marker. Because this
statement includes no arguments that define the orientation or position of Part 2, Adams Solver
(FORTRAN) superimposes Part 2 on the ground coordinate system (GCS). This statement identifies no IM
marker, so Adams Solver (FORTRAN) assumes that the inertias are defined with respect to the part CM
marker.
PART/04, MASS=.5, CM=0407, QG=10,0,0
This statement specifies the mass (.5 units), the center-of-mass marker identifier (0407), and the initial
position of the BCS (10,0,0) with respect to the ground coordinate system (GCS). This statement does not
272 Adams Solver
define the principal moments of inertia, so the inertia of the part is zero about each of the CM marker axes.
In addition, this statement has no arguments to indicate the orientation of Part 4, so Adams Solver
(FORTRAN) aligns the axes of the BCS of Part 4 with the axes of the ground coordinate system (GCS).
PINPUT 273
PINPUT
The PINPUT statement defines a list of VARIABLE statements that Adams Solver (FORTRAN) recognizes
as system input during a LINEAR/STATEMAT analysis (see the LINEAR command).
Format
PINPUT/id, VARIABLES=id1[,id2,...]
Arguments
VARIABLES=id1[,id2,...] Specifies the VARIABLE statements used as inputs by the Adams Solver
(FORTRAN) model.
Extended Definition
The PINPUT statement, along with a POUTPUT statement, is used with the LINEAR/STATEMAT
command. PINPUT defines a set of inputs to the mechanical system, and POUTPUT defines the set of
measured outputs from the system. The LINEAR/STATEMAT command linearizes the system equations to
the following form
X· = Ax + Bu
y = Cx + Du
where x is the linearized system state array, u is the array of system inputs defined by the PINPUT statement,
and y is the array of system outputs defined by the POUTPUT statement. This form is commonly referred
to as the state space form of the system equations in control theory. Adams Solver (FORTRAN) outputs the
A, B, C, and D matrices for use in a control-system design or any other linear system analysis software. If only
the A matrix is required, PINPUT and POUTPUT are not necessary.
When you run an analysis type other than LINEAR/STATEMAT, the PINPUT statement acts only as a
pointer to the list of the specified VARIABLE statements.
Both function expressions and user-written subroutines can access the PINPUT statement. Function
expressions access the values by using the internal Adams Solver (FORTRAN) function PINVAL(i1,i2) (see
the PINVAL function), where i1 specifies the PINPUT id, and i2 specifies the i2th VARIABLE in the PINPUT
statement list. Note that i2 is not the id of the VARIABLE statement.
User-written subroutines call the subroutine SYSFNC to access single elements of the PINPUT list and call
the subroutine SYSARY to access all values for a PINPUT (see the SYSARY and SYSFNC subroutines).
274 Adams Solver
Tip: VARIABLE statements may appear in more than one PINPUT statement. This allows you to
output two or more sets of state matrices at the same time.
Examples
PINPUT/3, VARIABLES=12,13,25
This PINPUT statement identifies VARIABLES 12, 13, and 25 as inputs to the mechanical system. These
variables might appear in expressions for computing actuating forces, for instance. You may refer to this
PINPUT in a LINEAR/STATEMAT command.
Applications
The PINPUT statement along with the POUTPUT, VARIABLE, ARRAY, TFSISO, LSE, and GSE
statements make up the interface between Adams Solver (FORTRAN) and control design and analysis
packages such as MATRIXx and MATLAB.
As shown in the figure below, PINPUT and POUTPUT act as sockets for input and output to your
controller, organizing the VARIABLE wires.
PINPUT and POUTPUT as Sockets
(FORTRAN) model using VARIABLE, ARRAY, TFSISO, LSE, or GSE statements. See the LINEAR
command.
POINT_MASS 275
POINT_MASS
The POINT_MASS statement defines a point mass. Point masses may have mass, position, and translational
velocities. They may also have orientation, but this orientation is constant during the course of a simulation.
Point masses, unlike parts, may not have inertias or angular velocities. Each POINT_MASS adds three
degrees of freedom to a system.
Similarly, translational forces that can be applied to point masses are limited to:
 ACCGRAV
 TRANSLATIONAL SFORCE
 TRANSLATIONAL SPRINGDAMPER
 VFORCE
Format
276 Adams Solver
Arguments
CM=id Specifies the identifier of the marker that defines the location of the point mass
relative to the local body coordinate system (BCS).
Default: None
Range: Valid fixed MARKER id’s
EXACT=c1:c2:c3 Specifies as many as three point mass coordinates that Adams Solver should not
change as it iteratively solves for initial conditions which satisfy all constraints. The
three coordinates are below.
x - x coordinate
y - y coordinate
z - z coordinate
changed by Adams Solver (FORTRAN) unless the values specified are inconsistent
with initial conditions for a joint or motion.
Default: None
Range: X, Y, or Z
MASS=r Specifies the magnitude of the mass.
Default: 0
Range: r > 0
QG=x,y,z Defines the Cartesian initial coordinates of the BCS with respect to the global
coordinate system.
Default: 0.0, 0.0, 0.0

rotations are in radians and are, respectively, about the z-axis of ground, the new x-
axis, and the new z-axis of the BCS. To input Euler angles in degrees, add a D after
each value.
Defaults: 0.0, 0.0, 0.0 when REULER, XG, and ZG are omitted
POINT_MASS 277
ground coordinate system (GCS) along the x-axis (VX), y-axis (VY), and z-axis (VZ)
of the global coordinate system.
Default: Inexact 0, 0, 0
XG=x,y,z Defines the coordinates, measured in the global coordinate system, of any point in
the positive x-z plane of the part BCS, but not on the z-axis of the part BCS.
Default: If ZG is omitted, XG is oriented like the global x-axis

ZG=x,y,z Defines the coordinates measured in the global coordinate system of any point on
the positive z-axis of the BCS.
Default: If XG is omitted, ZG is oriented like the global z-axis

Extended Definition
Although the point mass concept would normally suggest a particle, this is not how a point mass is
implemented in Adams. If a particle is subjected to a torque, a singularity ensues. This was not considered a
practical behavior for an element in Adams.
Rather than thinking of the point mass as a particle think of it as a rigid body with built-in angular constraints
removing any rotational degrees of freedom. It is legal to apply torques to a point mass, and such torques are
simply discarded. If one takes care not to apply a torque, the Adams point mass behaves exactly like a particle.
The point mass offers all the computational benefits of a particle without the complications which would
arise from forbidding the application of a torque.
278 Adams Solver
Tip:  All markers on a point mass that are involved in constraints or are at force application
points should be at the point mass CM. Otherwise, Adams Solver issues a warning.
Adams Solver does not generate moments due to offsets from CM.
 The CM can be offset from the BCS, but still the markers involved in constraints or at
force application points must be at the CM.
 Markers on a point mass to which no constraints or forces are applied (such as
markers for only graphics or requests), do not have to be on the CM.
 Function expressions may reference markers associated with point masses. However,
Adams Solver rejects expressions that should not refer to point mass markers, such as
TM, TX, TY, TZ, and NFORCE. You may use point mass markers in rotational
function expressions (such as AX, PSI, WY, and WDTZ), but remember that the
orientation of point mass markers is constant and their rotational velocities and
accelerations are always zero with respect to the ground coordinate system (GCS).
 Adams Solver permits you to request displacements, velocities, accelerations, and
forces between two point mass markers. However, the rotational displacements are
always constants, the rotational velocities are always zero, the rotational accelerations
are always zero, and the torques are zero.

POUTPUT 279
POUTPUT
The POUTPUT statement defines a list of VARIABLE statements that Adams Solver (FORTRAN)
recognizes as system output during a LINEAR/STATEMAT analysis (see the LINEAR command).
Format
POUTPUT/id, VARIABLES=id1[,id2,...]
Arguments
VARIABLES=id1[,id2,...] Specifies the VARIABLE statements that describes the outputs of the Adams
Solver (FORTRAN) model.
Extended Definition
The POUTPUT statement, along with a PINPUT statement, is used with the LINEAR/STATEMAT
command. POUTPUT defines the set of measured outputs from the system and PINPUT defines a set of
inputs to the mechanical system. The LINEAR command linearizes the system equations to the following
form:
X· = Ax + Bu
y = Cx + Du
where:
 x is the linearized system state array
Solver (FORTRAN) outputs the A, B, C, and D matrices for use in a control-system design or any other
linear system analysis software. If only the A matrix is required, PINPUT and POUTPUT are not necessary.
When you run an analysis type other than LINEAR, the POUTPUT statement acts only as a pointer to the
list of VARIABLE statements specified.
Both function expressions and user-written subroutines can access the POUTPUT statement. Function
expressions access the values by using the internal Adams Solver (FORTRAN) function POUVAL(i1,i2) (see
the PINVAL function), where i1 specifies the POUTPUT id , and i2 specifies the i2th VARIABLE in the
POUTPUT statement list. Note that i2 is not the id of the VARIABLE.
User-written subroutines access single elements of the POUTPUT list and call the subroutine SYSFNC to
access all values for a POUTPUT by calling the subroutine SYSARY (see the SYSARY and SYSFNC subroutines).
280 Adams Solver
Tip: VARIABLE statements may appear in more than one POUTPUT statement. This allows you
to output two or more sets of state matrices at the same time.
Examples
POUTPUT/4, VARIABLES=4,8,9,10
This POUTPUT statement identifies VARIABLES 4, 8, 9, and 10 as outputs from the mechanical system.
These variables might represent part displacements and velocities, for instance. You may refer to this
POUTPUT in a LINEAR/STATEMAT command.
Applications
The POUTPUT statement with the PINPUT, VARIABLE, ARRAY, TFSISO, LSE, and GSE statements
define the interface between Adams Solver (FORTRAN) and control design and analysis packages such as
MATRIXx and MATLAB.
As shown in the figure below, PINPUT and POUTPUT act as socket for input and output to your controller,
organizing the VARIABLE wires.
(FORTRAN) model using VARIABLE, ARRAY, TFSISO, LSE, or GSE statements. See the LINEAR
command.
PINPUT and POUTPUT as 'Sockets'

PREFERENCES 281
PREFERENCES
The PREFERENCES statement controls general options that apply to the model defined in the Adams
Solver (FORTRAN) dataset or the commands defined in the Adams Solver (FORTRAN) command file.
Format
282 Adams Solver
Arguments
Select the geometry library to be used for contact operations:
 Parasolid - Specifies the Parasolid geometry library to be used for

three-dimensional contact determination. Adams Solver
(FORTRAN) supports Parasolid version 28.1.238.
 Default_library - Specifies that the default geometry library to be
used for three-dimensional contact determination. The default
library is based on RAPID, a polygon-based interface detection
package developed at the University of North Carolina.
Currently, Adams Solver (FORTRAN) supports RAPID version
2.01.
For many models, the Default Library can substantially reduce
simulation time. Because it is polygon-based, however, it is not
always as accurate as the Parasolid geometry engine. Parasolid is an
exact boundary-representation geometric modeler, which makes it
highly accurate, but not as fast as a polygon-based engine. For these
reasons, you can switch from one to the other depending on your
needs.
solid geometries in the model. Contact kinematics are calculated by
intersecting the meshes corresponding to two solid geometries. A
finer mesh will result in more accurate contact calculations.
However, calculations may be slower, and computer memory
requirements will increase as the mesh resolution increases.
The faceting tolerance is defined as the maximum error between the

true surface and the surface of the faceted representation of the
geometry. The maximum error is guaranteed not to exceed (1/value)
* the minimum dimension of each geometry's bounding box.

cylinder, box, frustum, torus, surface of revolution, and extrusion) is
tessellated with a fixed tolerance when a faceting tolerance is
specified. Stl and shl files have fixed faceting that cannot be changed.
Examples
Using the Parasolid geometry provided by MSC:
PREFERENCES 283

284 Adams Solver
PTCV
The PTCV statement defines a point-to-curve constraint, which restricts a fixed point defined on one part
to lie on a curve defined on a second part. This is an instance of a higher pair constraint.
Format
Arguments
CURVE=id Specifies the identifier of a CURVE statement that defines the contour or shape on which the
fixed marker can move. The x, y, z values associated with the curve are the coordinates of
points lying on the curve and are calculated in the coordinate system of the RM marker.
DISP=x,y,z Specifies the initial point of contact on the curve. If the point specified is not exactly on the
curve, Adams Solver (FORTRAN) uses a point on the curve nearest to that specified. By
default, DISP is specified in the RM marker coordinate system. If another coordinate system
is more convenient, you may supply the ICM argument and enter DISP in ICM marker
coordinates.
If you supply DISP, Adams Solver (FORTRAN) assembles the system with the I marker at
the specified point on the curve. If you do not supply DISP, Adams Solver (FORTRAN)
assumes the initial contact is at the point on the curve closest to the initial I marker position.
However, it may adjust that contact point to maintain other part or constraint initial
conditions.
I=id Specifies the identifier of a fixed MARKER that Adams Solver (FORTRAN) constrains to lie
on the curve defined by CURVE and RM. The I and RM markers must belong to different
parts.
ICM=id Specifies the identifier of a fixed MARKER defining the coordinate system in which the
values for DISP are specified. The ICM marker must be on the same part as the RM marker.
PTCV 285
JFLOAT=id Specifies the identifier of a floating marker. Adams Solver (FORTRAN) positions the origin
of the JFLOAT marker at the instantaneous point of contact on the curve. Adams Solver
(FORTRAN) orients the JFLOAT marker such that the x-axis is tangent to the curve at the
contact point, the y-axis points outward from the curve's center of curvature at the contact
point, and the z-axis is along the binormal at the contact point.
RM=id Specifies the identifier of a fixed marker on the J part containing the curve on which the I
marker must move. The RM marker is used to associate the shape defined by the CURVE
identifier to the part on which the RM marker lies. The curve coordinates are therefore
specified in the coordinate system of the RM marker. The JFLOAT and RM markers must
belong to the same PART.
VEL=r Specifies the magnitude initial tangential velocity of the I marker with respect to the part
containing the curve. This is the speed at which the I marker is initially moving relative to
the curve. VEL is negative if the I marker is moving towards the start of the curve, positive if
the I marker is moving toward the end of the curve, and zero if the I marker is stationary on
the curve.
If you supply VEL, Adams Solver (FORTRAN) gives the I marker the specified initial
tangential speed along the curve. If you do not supply VEL, Adams Solver (FORTRAN)
assumes the initial tangential velocity is zero, but may adjust that velocity to maintain other
part or constraint initial conditions.
Default: 0
Extended Definition
The PTCV statement defines a point-to-curve constraint. The part containing the I marker is free to roll and
slide on the curve that is fixed to the second part. Lift-off is not allowed, that is, the I marker must always lie
on the curve.
is located at the contact point on the curve; its orientation is defined by the tangent, normal and binormal at
the contact point (see Figure 5).
Figure 6 shows a schematic of the point-to-curve constraint.
A PTCV statement removes two translational degrees-of-freedom from the system. Adams Solver
(FORTRAN) restricts the origin of the I marker to always lie on the curve. The I marker may translate only
in one direction relative to the curve, along the instantaneous tangent. The I marker is free to rotate in all
three directions.
Figure 5 Geometric Interpretation of the Orientation of the JFLOAT Marker

286 Adams Solver
Figure 6 Point-To-Curve Constraint

PTCV 287
Note: More than one PTCV statement may reference the same CURVE statement. If the mechanism
contains several similar contacts, you may enter just one CURVE statement, then use it with
several PTCV constraints, each with a different RM marker.
Caution:  VEL is specified relative to the part containing the RM marker. In other words, VEL
is the tangential speed of the I marker relative to the part containing the curve. This
means that if the I marker is stationary relative to ground, but the curve is moving
relative to ground, then VEL is still nonzero.
 Adams Solver (FORTRAN) applies a restoring force tangent to the curve at the
contact point if the contact point moves off the end of an open curve. The magnitude
of the force applied is defined as:
Force = COSH(MIN(200,500*DELTA)) - 1, if DELTA > 0

 where DELTA is a normalized penetration of the end of the curve, defined as:
DELTA = (ALPHA-MAXPAR)/ABS(MAXPAR-MINPAR), if ALPHA > MAXPAR
or
DELTA = -(ALPHA-MINPAR)/ABS(MAXPAR-MINPAR), if ALPHA < MINPAR
This force is intended to prevent solution problems when unexpected situations

occur, and should not be relied upon intentionally. You should make sure the
CURVE statement defines the curve over the expected range of motion.
• The initial conditions arguments, DISP and VEL, impose constraints that are
active only during an initial conditions analysis. Adams Solver (FORTRAN) does
not impose these initial conditions during subsequent analyses.
• For a kinematic analysis, the initial conditions are redundant. Do not use the DISP
or VEL arguments on the PTCV statements for systems with zero degrees of
freedom.
• It is easy to accidentally over-constrain a system using the PTCV constraint. For
cylindrical joint, not a revolute joint. If the follower is held by a translational joint
and the cam by a cylindrical joint, the PTCV constraint between the follower and
cam prevents the cam from moving along the axis of rotation (that is, the axis of
the cylindrical joint). A revolute joint would add a redundant constraint in that
direction.
Examples
PTCV/55, I=201, JFLOAT=301, CURVE=10, RM=302
288 Adams Solver
This statement creates a point-curve constraint between Marker 201 and a curve on the part containing
floating Marker 301 and fixed Marker 302. CURVE/10 defines the x, y, z coordinates curve in the coordinate
system of Marker 302. Because the statement does not specify initial conditions, Adams Solver (FORTRAN)
assumes that the initial position of the contact point on the curve is set to be the minimum distance between
the specified I marker and the curve. Adams Solver (FORTRAN) also assumes the velocity of Marker 201
with respect to the curve is zero, meaning it is initially stationary on the curve. Adams Solver (FORTRAN)
may adjust these assumed initial conditions in order to enforce other part or constraint initial conditions.
PTCV/55, I=201, JFLOAT=301, CURVE=10, RM=302,
, DISP=2.,3.,0., VEL=-5.
This statement is the same as the last example, except it contains initial conditions. Adams Solver assembles
the system with Marker 201 at the point on the curve nearest to coordinates (2.,3.,0.) in the Marker 302
coordinate system. Adams Solver imposes an initial speed of -5.0 on Marker 201 with respect to the curve,
meaning Marker 201 is moving towards the start of the curve.
Applications
The simplest point-curve constraint application is a pin-slot connection as illustrated in Figure 7 below.
Figure 7 Slot and Pin Reciprocating Mechanism
The point-curve constraint keeps the center of the pin in the center of the slot, while allowing it to move
freely along the slot and rotate in the slot. Note that the point-curve constraint does not stop the pin at the
end of the slot. If the travel of the pin must be restricted, a force element, such as an SFORCE with an
IMPACT function, must be used.
A point-curve constraint may also represent a point follower on a cam, where the follower has a very small
radius compared to the curvature of the cam. Figure 8 below illustrates a point follower on a cam.
If the CURVE statement specifies a closed curve, Adams Solver (FORTRAN) automatically moves the point
across the closure as needed. This means the cam may rotate as many times as needed during the simulation.
In some cases, the PTCV statement may be used to model a circular follower on a curve. This requires you
to construct a curve offset from the actual profile by a distance equal to the radius of the follower. Figure 9
illustrates the follower, original profile, and offset curve.
Figure 8 Point-Follower Mechanism

PTCV 289
Figure 9 Modeling a Circular Follower Using an Offset Curve
To model more complex cam-follower applications, see the CVCV statement. In the CVCV statement, both
the follower and cam can be represented as curves.
Because PTCV is a constraint, the point always maintains contact with the curve, even when the dynamics
of the system would actually lift the point off the profile. You may examine the constraint forces to determine
Unlike the CVCV statement, the PTCV statement is not restricted to planar curves. PTCV can model three-
dimensional slots and cams, as well as mechanisms riding on nonplanar tracks, or a robot end-effector
following a three-dimensional path in space.
290 Adams Solver
REQUEST
The REQUEST statement indicates a set of data you want Adams Solver (FORTRAN) to write in the tabular
output file, the request file, and the XML formatted results file. Using a REQUEST statement, you can
output a set of displacements, velocities, accelerations, or forces with respect to markers in the system.
FUNCTION keywords allow you to explicitly define the output variables or employ a user-written
subroutine REQSUB to define nonstandard output.
Format
REQUEST 291
Arguments
292 Adams Solver
ACCELERATION Outputs the acceleration of the I marker with respect to the J marker. This argument
generates nine headings and nine columns of output in the tabular output file. The
columns include the time (TIME), the magnitude of translational acceleration
(ACCM), the translational x component (ACCX), the translational y component
(ACCY), the translational z component (ACCZ), the magnitude of rotational
acceleration (WDTM), the rotational x component (WDTX), the rotational y
component (WDTY), and the rotational z component (WDTZ). The same data
without the magnitudes are written to the Request file. Adams Solver calculates this
acceleration data (the second derivative of the displacement of the I marker with
respect to the J marker) in the global coordinate system. If you specify RM, Adams
Solver (FORTRAN) resolves the translational x component, the translational y
component, the translational z component, the rotational x component, the
rotational y component, and the rotational z component in the coordinate system of
the RM marker.
CNAMES (Component Names) Sets one or more strings that identify the names of the result set
components produced by this REQUEST in XML results files.
For example, by default a result set for a request looks like:

<component name="mag" id="42">
<component name="x" id="43">
...
By default, there are 8 components per result set.
Specifying CNAMES=MG, X_comp, Y_comp, the XML results file will look like this
instead:

<component name="Mg" id="42"/>
<component name="X_comp" id="43"/>
Result set components can be deleted from storage in the database and in the XRF by
omitting them in the CNAMES argument. For example, the following CNAMES
argument will remove the first and fourth components from the result set:
CNAMES=””, X_Comp, Y_Comp, Z_Comp, ““, R1, R2, R3
This can be helpful if you want to reduce the memory overhead of the simulation
data.
REQUEST 293
COMMENT=c Specifies a title for the top of each set of information the REQUEST statement
outputs. The entire comment must be on one line. Because input lines can be only
eighty characters long at most, the comment can be from seventy-two characters long
(if you do not abbreviate COMMENT=) to seventy-eight characters long (if you
abbreviate COMMENT= to C=). Blank spaces and all alphanumeric characters can
be used. However, the comma (,), the semicolon (;), the ampersand (&), and the
exclamation point (!) cannot be used. The COMMENT data is printed in the request
file only.
CUNITS (Component Units) Sets one or more strings that identify the unit dimension of the
result set components in XML result files. If the CUNITS argument is omitted, then
the units of the components are predefined based upon standard request type (for
example, displacement, velocity, and acceleration) or they are considered user units
and no unit conversion will be performed.
The legal choices for the CUNITS parameter are:
MASS
AREA
TIME
VOLUME
FORCE
TORQUE
LENGTH
PRESSURE
VELOCITY
DENSITY
ACCELERATION
ENERGY
ANGLE
TORSION_STIFFNESS
ANGULAR_VELOCITY
TORSION_DAMPING
ANGULAR_ACCELERATION
FREQUENCY
INERTIA
AREA_INERTIA
STIFFNESS
FORCE_TIME
DAMPING
TORQUE_TIME
CLABELS (Component Labels) Sets one or more strings that identify the label to be used when
plotting the result set components. Labels may be strings that include white space.
However, quotes must be used to define the string if special characters or white space
are used. This option is only used with XML result files.
294 Adams Solver
DISPLACEMENT Outputs the displacement of the I marker with respect to the J marker. This argument
generates eight headings and eight columns of output in the tabular output file. The
columns include:
 time (TIME)
 translational magnitude (MAG)
 x component (X)
 y component (Y)
 z component (Z)
 psi angle (PSI)
 theta angle (THETA)
 the phi angle (PHI)
The same data without the magnitude are written to the request file. The psi, theta,
and phi angles are the Euler angle displacements of the I marker with respect to the J
marker. Adams Solver (FORTRAN) calculates this displacement data in the global
coordinate system. If you specify RM, Adams Solver (FORTRAN) resolves the
translational x-component, the translational y component, and the translational z-
component in the coordinate system of the RM marker. RM does not affect psi, theta,
and phi. If the YPR argument is placed in the OUTPUT statement, the psi, theta,
and phi rotations are converted to yaw, pitch, and roll rotations.
F1=e Defines the first component of the request that is being specified. If the F1 argument
is used, it must either be the last argument in the REQUEST statement or be followed
by a backslash (\) (not a comma). The value of the expression is written in the
corresponding column of the tabular output file.
F2=e Defines the second component of the request that is being specified. If the F2
argument is used, it must either be the last argument in the REQUEST statement or
be followed by a backslash (\) (not a comma). The value of the expression is written
in the corresponding column of the tabular output file. It is also sent to the request
file.
F3=e Defines the third component of the request that is being specified. If the F3 argument
corresponding column of the tabular output file. It is also sent to the request file.
F4=e Defines the fourth component of the request that is being specified. If the F4
file.
REQUEST 295
F5=e Defines the fifth component of the request that is being specified. If the F5 argument
corresponding column of the tabular output file.
F6=e Defines the sixth component of the request that is being specified. If the F6 argument
corresponding column of the tabular output file. It is also sent to the request file.
F7=e Defines the seventh component of the request that is being specified. If the F7
file.
F8=e Defines the eighth component of the request that is being specified. If the F8
file.
FORCE Outputs the force associated with the I and the J markers or, if the I marker and not
the J marker is given, outputs the action-only forces on the I marker. When both the
I and the J markers are given, Adams Solver (FORTRAN) sums the forces on the I
marker due to the forces associated with the I and the J markers. These forces can
include both applied forces (such as spring dampers and bushings) and reaction forces
from constraint elements (such as joints and motions).
When the I marker and not the J marker is given, Adams Solver (FORTRAN) sums
all of the action-only forces applied to the I marker. If RM is specified, Adams Solver
(FORTRAN) reports the components of the resulting vectors in the reference frame
of the RM marker. If RM is not specified, Adams Solver (FORTRAN) reports the
components in the ground coordinate system (GCS). The FORCE argument
generates nine columns of output in the tabular output file. The columns include the
time, the translational force magnitude, the three components of the translational
force, the rotational force (torque) magnitude, and the three components of the
torque. The same data without the magnitudes are written in the request file.
FUNCTION=USER{r1[,...,r30]} Defines and passes constants to the user-written subroutine REQSUB to define the
request. Follow FUNCTION with an equal sign, the character string USER, and the
values (r1[,...,r30]) that you want Adams Solver (FORTRAN) to pass to REQSUB.
If the FUNCTION argument is used, it must either be the last argument in the
REQUEST statement or be followed by a backslash (\). All eight columns of the data
that can be defined in a REQSUB are written in the tabular output file. Only columns
2, 3, and 4 and columns 6, 7, and 8 are written in the request file.
296 Adams Solver
I=id, J=id Identifies the fixed or floating marker(s) for which Adams Solver (FORTRAN)
outputs data. Both markers for DISPLACEMENT, VELOCITY, and
ACCELERATION must be identified. For force requests, the I marker and the J
marker must have on them either applied forces, such as bushings and sforces, or
constraints, such as joints and jprims, or both. You should identify both markers for
force unless you are outputting data for an action-only force. In the last case, only the
I marker needs to be identified.
RM=id Identifies the marker with respect to which you want to resolve information. Adams
Solver (FORTRAN) computes the data identified by the I marker and the J marker,
then reports the data as x, y, and z components in the reference frame of the RM
marker. Angular displacements, which are not vectors, are not affected by RM. RM
defaults to zero, which causes Adams Solver (FORTRAN) to resolve components in
the ground coordinate system (GCS).
RESULTS_NAME Specifies the name of the result set in which all result set components produced by
this request are placed when the result file is written in XML. If there is an existing
result set with this name, then the result set components are placed in that result set.
If there isn't an existing result set, then a new one is created and all the result set
components are placed there.
This is helpful if you wish to group the output from multiple requests into a single
result set. For example, you might have several different requests measuring driver
input for a vehicle, and you might wish to place them all within a result set named
Driver_Inputs for easier viewing in Adams PostProcessor.
ROUTINE=libname::subname Specifies an alternative library and name for the user subroutine REQSUB.

REQUEST 297
TITLE=c1:...:c8 Specifies up to eight alphanumeric headings for columns of request output. Each
heading can have as many as eight alphanumeric characters and underscores. (Use an
underscore to indicate a space.) The first character in each heading must be
alphabetic. All alphanumeric characters can be used. However, the comma (,), the
semicolon (;), the ampersand (&), and the exclamation point (!) cannot be used. If
the TITLE argument requires more than one line, it can be broken before a colon. In
this situation, put a comma with the colon (,:) on the next line to continue. As with
any argument, TITLE cannot lack values. Therefore, even if you do not wish to
specify a heading for a particular column, at least one alphanumeric character for each
heading in the argument must be used as a spaceholder between the colons. A value
before the first colon and after the last colon must also be assigned.
VARIABLES It identifies one or more VARIABLES that represent the components associated with
this REQUEST. The VARIABLES argument requires one or more VARIABLE id
references. This option is only used in XML result files.
VELOCITY Outputs the velocity of the I marker with respect to the J marker. This argument
generates nine headings and nine columns of data for velocity. The nine columns in
the tabular output file include:
 time (TIME)
 translational magnitude (VM)
 translational x component (VX)
 translational y component (VY)
 translational z component (VZ)
 rotational magnitude (WM)
 rotational x component (WX)
 rotational y component (WY)
 rotational z component (WZ)
The same data without the magnitudes are written in the request file. Adams Solver
(FORTRAN) calculates this velocity data (the first derivative of the displacement of
the I marker with respect to the J marker) in the global coordinate system. If you
specify RM, Adams Solver (FORTRAN) resolves the translational and rotational
velocities vector in the coordinate system of the RM marker.
Extended Definition
The REQUEST statement indicates a set of data you want Adams Solver (FORTRAN) to write in the request
file. REQUEST is also printed in the result file if the XRF option was selected in the RESULTS statement.
Using a REQUEST statement, you can output a set of displacements, velocities, accelerations, or forces with
respect to markers in the system. FUNCTION keywords allow you to explicitly define the output variables
or employ a user-written subroutine REQSUB to define nonstandard output.
Adams Solver (FORTRAN) calculates all time derivatives in the ground coordinate system (GCS), although
you can specify that the data be resolved in another reference frame. This is of no importance in the case of
298 Adams Solver
force data, but it can be very important in the case of velocities and accelerations. For example, joint velocities
are actually translational and rotational velocity difference vectors of the joint I marker and the joint J marker
in ground. Joint accelerations are actually translational and rotational acceleration difference vectors of the
joint I marker in ground and the joint J marker in ground. When requesting force information, you must
specify the identifiers of markers on which there are forces. The forces on these markers can be either applied
or reaction forces.
Adams Solver (FORTRAN) writes REQUEST data to the tabular output file. The OUTPUT statement contains
several options controlling the format of the output. If you include an OUTPUT statement with the
REQSAVE argument, Adams Solver (FORTRAN) also writes REQUEST data to the Request file. You may
load the request file into Adams PostProcessor and plot the request data.
Tip:  Note that the units for rotational displacement data in the request output of the tabular
output file default to degrees. The units for all other angular output data default to
radians.
 Adams Solver (FORTRAN) outputs UCON reaction forces only to the results file. If you
wish UCON forces information, you must include a RESULTS statement in the dataset.
 You only need to enter as many of the eight function expressions F1,...,F8 as required.
Adams Solver (FORTRAN) outputs zeros for any function left unspecified.
REQUEST 299
Caution:  Applied forces and torques are those generated by beams, bushings, fields, general forces
(GFORCEs), multi-point forces (NFORCEs), single-component forces (SFORCEs),
spring dampers (SPRINGDAMPERs), vector forces (VFORCEs), and vector torques
(VTORQUEs). Adams Solver outputs the applied forces and torques acting at the request
I marker (which may be either the applied force I marker or the applied force J marker).
The magnitude and point of force application on the part containing the applied force J
marker varies according to the type and source of the force.
For spring dampers, action-reaction single-component forces, general forces, vector forces,
and vector torques, the forces and torques acting at the J marker are equal and opposite to
the forces and torques acting at the I marker. For action-only single-component forces,
there is no force or torque acting at the applied force J marker. For beams, fields, bushings,
and multi-point forces, the forces acting at the applied force J marker are equal and
opposite to the forces acting at the applied force I marker. As long as the applied force I
marker and the applied force J marker are coincident, the torques acting at the applied
force J marker are equal and opposite to the torques acting at the applied force I marker. If
there is a finite separation between the I and the J markers, the torques acting at the
applied force J marker are calculated by solving the moment balance equation at the J
marker.
 Reaction forces and torques are those generated by constraint-inducing elements. For
revolute, spherical, and universal joints and for atpoint, orientation, parallel axes, and
perpendicular joint primitives, Adams Solver (FORTRAN) outputs the reaction forces and
torques acting at the request I marker (which may be either the constraint I marker or the
constraint J marker). The force and torque acting at the request J marker are equal and
opposite to the force and torque acting at the request I marker. Depending on the type of
constraint, some or all of the torques acting at the I marker are zero. Determining reaction
forces and torques for cylindrical, planar, rack-and-pinion, screw, and translational joints
and for inline and inplane joint primitives is more complex.
If the request I marker corresponds to the constraint I marker, then Adams Solver
(FORTRAN) outputs the force and torque acting at the constraint I marker. If the request
I marker corresponds to the constraint J marker, then Adams Solver (FORTRAN) outputs
the force and torque acting at the instantaneous location of the constraint I marker, but on
the part containing the constraint J marker. The force translated to the constraint J marker
is the same as computed above. If the I and the J markers are coincident, the torque
translated to the constraint J marker is the same as computed above. But if there is a finite
separation between the I and the J markers, the torque translated to the constraint J marker
is different from the one computed above (because of the moments contributed by the
reaction forces).
 Rotational displacement information differs from all other standard output. Whether this
information is in psi, theta, and phi coordinates or in yaw, pitch, and roll coordinates, the
rotation sequence is not a vector. As a result, no magnitude column is in the output. In
addition, the sequence of coordinates is independent of any frame external to the I and the
J markers. Therefore, the RM argument has no effect on the angular coordinates.
300 Adams Solver
 You must be careful when requesting a force with the I and the J markers reversed from
those specified in the force-producing element. Adams Solver (FORTRAN) reports the
force as if it were applied to the J marker of the force-producing element. The translational
force on the J marker of the force element is equal and opposite to the translational force
on the I marker of the force element if it is not action-only. The force is zero if it is action
only. The torque on the J marker of the force element has components that may have
significance. The torque is the sum of two contributions. The first contribution is the
opposite of the torque on the I marker. The second contribution is due to the force acting
across the separation between the I and the J markers. If the force acts along the line of
sight of the two markers, this extra torque is zero. To minimize misunderstandings, attach
the REQUEST markers in the same order as the markers on the force-producing element.
 When computing velocity and acceleration for a marker pair that includes a floating
marker, Adams Solver (FORTRAN) computes the velocity and acceleration as though the
floating marker were permanently attached to the part at its current position.
 Adams Solver (FORTRAN) does not write output for functions F1 and F5 to the request
file. To plot requests from the Request file, you should not use F1 or F5. Adams Solver
(FORTRAN) writes output for F1 and F5 to the tabular output file and the results file.
Examples
This REQUEST statement requests displacement data for Marker 0201 with respect to Marker 0103. Adams
Solver outputs the comment CRANK CENTER OF MASS DISPLACEMENT, eight headings, and eight
columns of data to the tabular output file. The information is duplicated in the request file.
This REQUEST statement requests data for an action-reaction force on Marker 0304 from Marker 0204.
Adams Solver outputs the comment ROD/CRANK REACTION, nine headings, and nine columns of data
to the tabular output file. The information is duplicated in the request file.
REQUEST/21, F2=VARVAL(1)/ F3=DIF1(1)*5/ F4=DX(2109,409)/
, TITLE=NULL:VAR 1:DERIV5:DISP:NULL:NULL:NULL:NULL
This REQUEST statement requests the value of VARIABLE/1 to be placed in the second column, the first
time derivative of DIFF/1 multiplied by five to be placed in the third column, and the x component of the
displacement of Marker 2109 relative to Marker 409 to be placed in the fourth column. The titles for the
eight columns from left to right are: NULL, VAR_1, DERIV5, DISP, NULL, NULL, NULL, NULL.
,CNAMES="", X_100, Y_100
,RESULTS_NAME=PQT
REQUST/2, DISPLACEMENT, I=200, J=202
,CNAMES="", X=200, Y=200
,RESULTS_NAME=PQT
If using XML, these two REQUEST statements generate a combined result set named "PQT" containing
only 4 channesl names X_100,Y_100, X_200 and Y_200. The result set would look as follows:
REQUEST 301
<entity name="PQT" objectId="25">

</entity>
Instead of generating 2 result sets with 8 channels each (default XML behaviour), only one result set with 4
channels is created.
Applications
Requests are used whenever a particular output is desired from Adams Solver (FORTRAN). The output
generated from the request can be in two forms: a tabular output file for tables and a request file that contains
data needed for plotting in a postprocessor. The writing of these files is controlled by the OUTPUT
statement.
When you are interested in a series of requests that are quite similar, MREQUEST may be easier to use. This
statement is very similar to the REQUEST statement, but allows a shorthand method of statement entry.
A third alternative is the RESULTS statement, which causes all the results for the analysis to be saved to a
results file (see RESULTS). This file can then be used in a postprocessor. The major drawbacks to using the
RESULTS statement is the size of the file, and having the data in a form that needs to be translated by a
postprocessor.
When using a REQUEST statement, you must also have an OUTPUT/REQSAV statement in order to
create a request file (.req). The request tables in the tabular output file (.out) are written regardless of the
existence of the OUTPUT statement.
Data from certain Adams Solver (FORTRAN) statements is accessible only through the request functions
(F1,...,F8). The statements include PINPUT, POUTPUT, VARIABLE, ARRAY, LSE, GSE, TFSISO, and
DIFF. To request information on PINPUT, POUTPUT, ARRAY, or VARIABLE, you should write the
function expression referencing PINVAL, POUVAL, ARYVAL, and VARVAL, respectively. To request
information on LSE, GSE, TFSISO, you should write the function expression referencing ARYVAL. To
request information on DIFF, you should write the function expression referencing DIF for the value of the
independent variable associated with a user-defined differential equation, and DIF1 for the value of the time
derivative of the independent variable of the user-defined differential equation.
302 Adams Solver
RESULTS
The RESULTS statement creates a results file that includes all the simulation output from Adams Solver
(FORTRAN). The results file can be either unformatted (binary) or formatted (ASCII).
Format
RESULTS 303
Arguments
COMMENT=c Specifies a title for the results file generated by a RESULTS statement.
The entire comment must be on one line. Because the COMMENT
argument can be only eighty characters long at most, the title can be
from seventy-two characters long (if you do not abbreviate
COMMENT=) to seventy-six characters long (if you abbreviate
COMMENT= to COM=). Blank spaces and all alphanumeric
characters can be used. However, the comma (,), the semicolon (;), the
ampersand (&), and the exclamation point (!) cannot be used.
COMMENT defaults to a blank line.
DECIMALPLACES=i This argument is only available with XRF.
Specifies how many digits are written after the decimal point for real
numbers. The default value is 17 decimal places (full precision for
recovery of double-precision numbers).
FORMATTED Specifies that the results file is to be a formatted (text) file. The default
is an unformatted (binary) file. The formatted results file contains
Adams Solver (FORTRAN) output in plain text that you can read. You
cannot examine an unformatted results file directly. Although the
unformatted results file is not user-readable, it is generally preferred for
several reasons. The unformatted file is smaller, contains more precise
data, and is much quicker for Adams Solver (FORTRAN) to write and
for a postprocessor to read. A formatted file is useful only when you wish
to examine the data directly, or when transferring the file between
computer systems with incompatible binary formats.
NOACCELERATIONS Specifies that the results file is not to include part accelerations. the
default is a results file that includes part accelerations.
NOAPPLIEDFORCES Specifies that the results file is not to include applied forces. The default
is a results file that includes applied forces.
NODATASTRUCTURES Specifies that the results file is not to include results from data structures
such as variables, plant inputs, plant outputs and user-defined requests.
The default is a results file that contains results from data structures.
NODISPLACEMENTS Specifies that the results file is not to include part displacements. The
default is a results file that includes part displacements.
NOFLOATINGMARKERS Specifies that the results file is not to include results for floating markers.
The default is a results file that contains results for floating markers.
NOLINEAR Specifies that the results file is not to include results from linear analyses.
The default is a results file that contains results from linear analyses.
NOREACTIONFORCES Specifies that the results file is not to include constraint reaction forces.
The default is a results file that includes constraint reaction forces.
304 Adams Solver
NOREQUESTS Specifies that the results file not include request output. The default is a
results file that includes user-defined request, in the case of a classic
results file, or all request data (in the case of an XML-formatted results
file (XRF)).
NOSYSTEMELEMENTS Specifies that the results file is not to include results for system modeling
elements such as user-defined differential equations, linear state
equations, general state equations, and transfer functions. The default is
a results file that contains results for system modeling elements.
NOTIRES Specifies that the results file is not to include results for tires. The default
is a results file that contains results for tires.
NOVELOCITIES Specifies that the results file is not to include part velocities. The default
is a results file that includes part velocities.
ROUNDOFF This argument is only available with XRF.
Enables the roundoff feature for real numbers (the default is disabled).
The SIGNIFICANTFIGURES argument controls the actual numbers
of digits retained during rounding off.
SCIENTIFICNOTATION=i1,i This argument is only available with XRF.
2
Specifies the boundaries at which the format for real numbers switches
from a fixed point format to scientific notation. The values are
exponents for the base ten. The default values are -4 and 5, meaning that
any number less than or equal to 1.0E-04 or greater than or equal to
1.0E+05 will be written in scientific notation.
SIGNIFICANTFIGURES=i This argument is only available with XRF.
Specifies how many significant figures of a real number are retained

during round off (when round off is enabled). The default is to use ten
significant figures.
This number is distinct from the number of places actually printed for a
real number, which the DECIMALPLACES argument controls.
Note: SIGNIFICANTFIGURES includes digits to the left and right

of the decimal point.
RESULTS 305
TRAILINGZEROS This argument is only available with XRF.
Specifies that trailing zeros are printed for real numbers. The default is
not to print trailing zeros. When enabled, all the digits after the decimal
point will be printed, whether they are zero or not. When disabled, any
zeros at the end of the fractional part of the number will be dropped,
leaving the last digit as a non-zero digit.
XRF Specifies the format of the results file to be XML. XML (Extensibile
Markup Language) is an industry-standard format facilitating structured
data representation and web communication.
XRF will produce an XML-formatted results file even if the

FORMATTED parameter has not been specified.
ZEROTHRESHOLD=r This argument is only available with XRF.
Specifies the zero threshold value for numbers being written to an output
file. If a number has an absolute value smaller than the zero threshold
value, then it will be written out as zero. This value is independent of
units.
Extended Definition
The RESULTS statement creates a results file that includes selections of output from an Adams Solver
(FORTRAN) simulation. This all-purpose file can contain all the simulation output from Adams Solver
(FORTRAN). The results file can contain any combination of the following information:
 Displacements - Displacements of the BCS with respect to ground and resolved in the ground
 Velocities - Velocities of the the BCS with respect to ground and resolved in the GCS.
 Accelerations - Accelerations of the BCS with respect to ground and resolved in the GCS.
 Reaction forces - Forces on the I marker required to enforce each constraint, resolved in the GCS.
 Applied forces - Forces on the I marker applied by Adams Solver (FORTRAN) force elements,
resolved in the GCS.
 Data structures - Values computed for data structures such as variables, plant inputs, plant outputs,
and requests defined by expressions in the dataset or by a user-written REQSUB.
 System elements - Inputs, outputs, state variables, and state derivatives defined by system modeling
elements such as user-written differential equations, linear state equations, general state equations,
and transfer functions.
 Tires - Displacements, velocities, accelerations, forces, and other information about tires.
 Floating markers - Displacements of floating markers.
 Linear - Eigenvectors, eigenvalues, and state matrices computed by a linear analysis invoked by the
LINEAR command.
306 Adams Solver
Tip:  The title specified in the COMMENT argument helps identify the results file. If you do
not include the COMMENT argument in the RESULTS statement, Adams Solver
(FORTRAN) uses a blank line for the title of the results file.
 Because results files can contain all the information generated by Adams Solver
(FORTRAN) during a simulation, they may become quite large. The NO... arguments
should be used to remove unwanted output and conserve disk space.
Caution: The NODATASTRUCTURES argument has superseded the old NOUSERRESULTS

argument and the NOSYSTEMELEMENTS argument has superseded the old NODIFF
argument.
Examples
RESULTS/FORMATTED, NODATASTRUCTURES, NOSYSTEMELEMENTS
RESULTS/NODISPLACEMENTS, NOVELOCITIES
,NOACCELERATIONS, NODATASTRUCTURES
,NOSYSTEMELEMENTS, NOLINEAR
,NOFLOATINGMARKERS, NOTIRES
SENSOR 307
SENSOR
The SENSOR statement is used to modify the simulation when a user-defined event occurs during run-time.
The event is defined by a logical expression which compares an expression to a target value. If the logical
expression becomes true during the simulation, the sensor modifies the simulation by the means described
below.
Format
308 Adams Solver
Arguments
CODGEN Generates a new pivot sequence for matrix factorization when the
event Adams Solver (FORTRAN) is monitoring becomes true. This
may help the integrator to produce more accurate data or to proceed
more smoothly at troublesome points in time. A pivot sequence for
matrix factorization is generated before the start of a simulation. A new
pivot sequence is not generated unless the CODGEN argument is
used or Adams Solver (FORTRAN) determines it is necessary to reach
convergence.
Default: Off
DT=r Redefines the time between consecutive output steps when the event
Adams Solver (FORTRAN) is monitoring becomes true.
Default: Time between output steps determined by SIMULATE

command
EQ Used to define the event logical expression. The event is true (active)
if the function expression (or user-written subroutine) minus VALUE
is equal or less than ERROR.
Default: EQ
ERROR=r Used to define the event logical expression. ERROR specifies the
absolute value of allowable error to be realized in VALUE.
Default: 0.001
e written subroutine that is evaluated when the event Adams Solver
 
EVALUATE =   (FORTRAN) is monitoring becomes true. The scalar value of the
 USER ( r 1 [ ,…, r 30 ] )  expression or the return value of the user-written subroutine can then
be obtained using the SENVAL function expression.
If you want to define the evaluated function with an expression,

EVALUATE must be followed with an equal sign and the expression.
If you want to define the evaluated function with a user-subroutine,
FUNCTION must be followed with an equal sign, the character
string USER, and the selected values (r1[,...,r30]) that Adams Solver
(FORTRAN) passes to the user-written subroutine SEVSUB.
If the EVALUATE argument is used, it must either be the last

argument in the SENSOR statement or be followed by a backslash (\).
SENSOR 309
EVALUATE_ROUTINE=libname::subname Specifies an alternative library and name for the user subroutine
SEVSUB.

e written subroutine to define the event logical expression. To define an
 
FUNCTION =   expression, follow FUNCTION with an equal sign and the expression
 USER ( r 1 [ ,…, r 30 ] )  (e). To define a user-written subroutine, follow FUNCTION with an
equal sign, the character string USER, and the values (r1[,...,r30]) that
you want Adams Solver (FORTRAN) to pass to the user-written
subroutine SENSUB. If the FUNCTION argument is used, it must
either be the last argument in the SENSOR statement, or be followed
by a backslash (\).
Default: None
Range: An expression or user-parameter list of 1 to 30 real values
GE Used to define the event logical expression. The event is true (active)
if the function or user-written subroutine is equal to or greater than
(VALUE-ERROR).
Default: EQ
HALT Terminates execution when the event Adams Solver (FORTRAN) is
monitoring becomes true (active).
Default: Off
LE Used to define the event logical expression. The event is true (active)
if the function or user-written subroutine is equal to or less than
(VALUE + ERROR).
Default: EQ
PRINT Writes data to the request, graphics, and output files when the event
Default: Off
RESTART Restarts the integration when the event Adams Solver (FORTRAN) is
monitoring becomes true. Adams Solver (FORTRAN) reduces the
integration order to one. If the SENSOR includes STEPSIZE, the
integration step size is reinitialized to the specified value. If you do not
specify STEPSIZE, Adams Solver (FORTRAN) reinitializes the
integration step size to HINIT.
Default: Off
310 Adams Solver
RETURN Stops the simulation and returns to the command level when the event
Default: Off
SENSUB.

STEPSIZE=r Redefines the trial integration step size when the event Adams Solver
(FORTRAN) is monitoring becomes true. This change is temporary
and lasts only for the next step.
Default: An integrator determined value except when the SENSOR

statement includes the RESTART argument. In this case, STEPSIZE
defaults to HINIT.
Range: STEPSIZE > 0

VALUE=r Specifies the value to be compared to the function expression (or
evaluation of the user-written subroutine). When using GE with
VALUE, the event logical expression is true only if the function
expression is equal or greater than (VALUE - ERROR). When using
EQ with VALUE, the event logical expression is true only if the
absolute value of the function expression minus VALUE is equal or less
than ERROR. When using LE with VALUE, the event logical
expression is true only if the function expression is less than (VALUE
+ ERROR).
Default: None
Range: Any real number

YYDUMP Dumps the state variable vector when the event Adams Solver
(FORTRAN) is monitoring becomes true.
Default: Off
Extended Definition
The SENSOR statement defines a user-defined event that affects a set of simulation controls when the event
occurs. The event is defined by a logical expression that compares a function expression (or evaluation of a
user-written subroutine) to a target value using a relational operator. If the logical expression becomes true
during the simulation, the sensor modifies a set of simulation controls, which include output and integration
step sizes, simulation end time, and the Jacobian pivot sequence. A sensor can also output diagnostic
information and store the value of a function expression for later recall.
SENSOR 311
The Adams Solver (FORTRAN) evaluates the logical expression after every successful integration step when
doing dynamic analysis and after every successful output step when doing other types of analyses. To define
the function, use a function expression or a user-written subroutine. More information on valid function expressions.
User-written subroutines and utility subroutines discuss the subroutines they can access.
Caution:  The SENSOR function must be continuous because Adams Solver (FORTRAN) tries to adjust
the step size to find the exact time when the sensor becomes active. This process is inaccurate
and time consuming when the function is discontinuous. For that reason, functions of time or
displacements work best for sensors; functions of velocities, accelerations, and forces are less
desirable.
 Adams Solver (FORTRAN) tests the sensor after every successful time step during dynamic
analyses and after every output step during other analyses. If the sensor becomes active, Adams
Solver (FORTRAN) modifies the simulation control accordingly and does not test the sensor
again until it has completed three time steps. Then, Adams Solver (FORTRAN) again tests the
sensor after every time step.
 If you want Adams Solver (FORTRAN) to take an action, make sure to include one of the
action arguments (CODGEN, DT, HALT, PRINT, RESTART, RETURN, STEPSIZE,
EVALUATE, and YYDUMP) in the SENSOR statement. The sensor can become active even if
one of the action arguments is not included. However, Adams Solver (FORTRAN) does not, of
course, take action unless one is specified.
 If a MOTION statement generates nonzero initial part accelerations, the Adams Solver
(FORTRAN) integrator may not produce reliable accelerations and velocities for the first two or
three internal integration steps. Adams Solver (FORTRAN) automatically corrects for this, so
that the values returned at the first output step are accurate. A SENSOR, however, that depends
on the accelerations or reaction forces due to this motion may trip unexpectedly prior to the first
output step, even though the solution appears correct when the SENSOR is removed. If this
occurs, you should modify the displacement function in the MOTION statement so that the
initial accelerations are zero.
312 Adams Solver
 In some cases, Adams Solver (FORTRAN) may not be able to use the specified STEPSIZE.
 If this step size gives poor convergence or generates too much error, Adams
Solver(FORTRAN) tries other step sizes.
 For those INTEGRATOR statements where you set INTERPOLATE=OFF, if the
specified step size steps past the next output step, Adams Solver (FORTRAN) reduces the
step size to reach the output step exactly.
 If the specified step size is larger than HMAX, Adams Solver (FORTRAN) uses HMAX.
 If the specified step size is smaller than HMIN, and you specify RESTART, the value of
HMIN overrides the value of STEPSIZE.
 Adams Solver (FORTRAN) may occasionally have difficulty enforcing an equality (EQ)
SENSOR, especially if the specified error is very small. In these cases, Adams Solver
(FORTRAN) may appear to pass through the sensed value without invoking the sensor action.
If this occurs, you should try increasing the error tolerance, if possible. An alternative is to
change to an inequality (GE or LE) sensor, then DEACTIVATE the sensor after it has triggered.
Examples
SENSOR/231, FUNCTION=DX(0201,0307)/
,VALUE=3.24, RETURN
This SENSOR statement senses the x-component for the displacement of Marker 0201 with respect to
Marker 0307 and resolves the displacement in the ground coordinate system (GCS). When the relative x
displacement equals 3.24 (+/_ 0.001), the statement stops the simulation and returns to the command level.
SFORCE 313
SFORCE
The SFORCE statement applies a single-component force or a torque to one or both of the parts it connects.
Format
314 Adams Solver
Arguments
ACTIONONLY Indicates that you are describing an action-only force rather than an
action-reaction force. Adams Solver (FORTRAN) applies no reaction
at the J marker.
e written subroutine to define the single-component force. To define
 
FUNCTION =   the force with an expression, follow FUNCTION with an equal sign
 USER ( r 1 [ ,…, r 30 ] )  and the expression. To define the force with a user-written
string USER, and the values (r1[,...,r30]) that Adams Solver
(FORTRAN) is to pass to the user-written evaluation subroutine
SFOSUB. If the FUNCTION argument is used, it must either be the
last argument in the SFORCE statement or be followed by a
backslash (\).
I=id, J=id Specifies the identifiers of two markers necessary to define the force.
If SFORCE defines a translational action-reaction force, I and J
specify the identifiers of the two markers between which you want to
exert the force. Adams Solver (FORTRAN) applies the translational
action-reaction force along the line of action defined by the line
segment connecting I and J. If SFORCE defines an action-only force,
I specifies the point of application, and the z-axis of J specifies the
direction of the force. If SFORCE defines a torque, the z-axis of the J
marker specifies the axis of rotation. In the case of action-reaction
torques, the z-axis of the J marker must be parallel to, and pointed in
the same direction as, the z-axis of the I marker.
Note: You can use the same marker for both the I and J markers
when you are specifying an action-only SFORCE. For
example, you would do this when specifying rocket thrust
forces.
ROTATION Designates a rotational force, that is, a torque. For an action-reaction
torque, the z-axes of the I and the J markers must be parallel and must
point in the same direction. Adams Solver (FORTRAN) applies a
torque about each z-axis. By definition, the right-hand rule defines a
positive torque.
SFOSUB.

TRANSLATION Designates a translational force. Adams Solver (FORTRAN) applies
the translational force between the I and the J markers.
SFORCE 315
Extended Definition
The SFORCE statement applies a force or torque to two parts. You specify a marker on each part for force
or torque application. The magnitude of the force may be defined as a function of any combination of
displacements, velocities, other applied forces, user-defined variables, and time. An SFORCE statement can
apply action-reaction forces or can apply action-only forces.
For translational action-reaction forces, Adams Solver (FORTRAN) applies an action and reaction force
along the line connecting the I and the J markers. The force exerted on I is directed from J toward I, while
the force exerted on J is directed from I toward J. The magnitude of each is specified in the FUNCTION
argument.
For translational action-only forces, Adams Solver (FORTRAN) applies the force on the I marker only. There
is no reaction on the J marker. The force on the I marker is directed along a vector parallel to and co-directed
with the z-axis of the J marker.
For rotational action-reaction forces, Adams Solver (FORTRAN) applies an action torque on the I marker
about the z-axes of the I marker and a reaction torque on the J marker about the z-axis of the J marker.
Furthermore, Adams Solver (FORTRAN) assumes that the z-axes of the I and the J markers are parallel.
For rotational action-only forces, Adams Solver (FORTRAN) applies the torque on the I marker only. There
is no reaction on the J marker. The torque on the I marker is applied about a vector parallel to and co-directed
with the z-axis of the J marker.
You write a function expression or a user-written subroutine (SFOSUB) to define the constitutive equation
for the force applied at the I marker. Adams Solver (FORTRAN) evaluates the reaction forces at the J marker.
Tip:  When an SFORCE statement defines a translational action-reaction force, Adams

Solver (FORTRAN) applies a translational force along the line connecting the I and
the J markers. But when an SFORCE statement defines a translational action-only
force, Adams applies the force to the I marker in the J marker z-axis direction.
 For action-reaction translational forces in Adams, a positive force (that is, positive
value of the FUNCTION argument) between two markers causes them to repel each
other and a negative force causes them to attract each other.
Caution: For rotational action-reaction SFORCEs, the z-axes of the I and the J markers must be parallel
and pointed in the same direction. If they are not, the results are unpredictable and may differ
between Adams Solver (C++) and Adams Solver (FORTRAN).
Examples
, FUNCTION=IF((DM(0409,0109)-10.0):
, -100.00*(DM(0409,0109)-10.0),0,0)
This SFORCE statement describes an action-reaction, compression-only force exerted on Marker 0409 by
Marker 0109. The argument TRANSLATION designates a translational force, and the argument
316 Adams Solver
FUNCTION gives the free length (10.0), establishes that the force is active only in compression, and defines
the force in terms of the displacement (DM) of the I marker with respect to the J marker.
In a second example, suppose you wish to model a translational spring that transmits a nonlinear, dissipative
force between two parts of a mechanical system. Let the following equations represent the magnitude of the
attracting force acting between the two connecting parts.
F= k0 + k1(x-1) + k2(x-1)2 + cx'
where k0 is a static preload, x is the instantaneous length of the translational spring, x' is the time derivative
of x, l is the natural, unstretched spring length, k1 and k2 are stiffness coefficients, and c is a damping
coefficient. This equation representing the force magnitude can be rewritten in the following polynomial
format:
2
j
F =  kj ( x – l ) + cx'
j=0
If k0 = -10.1, k1 = 15.2, k2 = 4.1, c = 1.5, and l = 3.142, then the Adams Solver (FORTRAN) statement that
represents this translational spring acting between two parts containing Markers 12 and 34, respectively,
appears as
, FUNCTION=-POLY(DM(12,34), 3.142, -10.1, 15.2, 4.1)
, VR(12,34) * 1.5
The DM function is used to calculate the instantaneous spring length x, the VR function is used to calculate
x', and the POLY function is used to simplify the input and computation of the nondissipative portion of the
force. Note that Adams Solver (FORTRAN) interprets the value of the FUNCTION argument as the
magnitude of the repelling force between two markers; hence, a negative sign was prepended to the attracting
force expression defined earlier.
SPLINE 317
SPLINE
The SPLINE statement defines discrete data that Adams Solver (FORTRAN) interpolates using the AKISPL
and CUBSPL function expressions and the AKISPL and CUBSPL data-access subroutines. A SPLINE
statement provides one or two independent variables and one dependent variable for each data point you
supply.
If you are licensed to use the Adams Durability plugin, the SPLINE statement includes arguments to perform
durability analyses. These arguments are explained in the following pages along with the standard arguments.
Format
SPLINE/id
,X = x1, x2, x3, x4 [, ..., xn]
,Y = y1, y2, y3, y4 [, ..., yn]
[, UNITS = string ]
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, y34 [, ..., y3n]
,Y = z4, y41, y42, y43, y44 [, ..., y4n]
[, ..., Y = zm, ym1, ym2, ym3, ym4 [, ..., ymn]]
[, ZUNITS = string ]
[, UNITS = string ]
or
SPLINE/id
, FILE = filename
[, BLOCK = blockname]
[ , CHANNEL = id ]
[, UNITS = string ]
318 Adams Solver
Arguments
BLOCK Specifies the use of a particular, named block within a file. The BLOCK
argument is optional, and requires the FILE argument.
CHANNEL For use with Adams Durability only.
Specifies the integer ID of a particular channel of data in the file referenced by

the SPLINE. This argument is used for files of type RPC III, which can contain
more than one channel of data. An error results if the specified file is of type RPC
and no CHANNEL argument is given or if the supplied channel ID does not
exist in the file. Adams Solver ignores this argument for files of type DAC, which
by definition contain only one channel of data.
Default: (none)
Range: 1 < n < 128
FILE Specifies the use of a file, rather than the X and Y arguments, to supply data for
the SPLINE. FILE causes Adams Solver (FORTRAN) to call the user-written
subroutine SPLINE_READ, which you must provide. The FILE argument and
the X and Y arguments are mutually exclusive.
If you are using FILE with Adams Durability, it specifies the name of the time
history file that supplies data for the the SPLINE. The file can be of type DAC
(nSoft format) or RPC III (MTS format).
For more on how to define a SPLINE using the FILE argument, see the example
in SPLINE_READ subroutine.
LINEAR_EXTRAPOL Causes Adams Solver (FORTRAN) to extrapolate a SPLINE that exceeds a
ATE defined range by applying linear function(s) tangent to the spline at the end(s)
of the defined range. By default, Adams Solver (FORTRAN) extrapolates a
SPLINE that exceeds a defined range by applying a parabolic function over the
first or last three data points.
X=x1,x2,x3,x4[ , . . . , Specifies at least four x values. The maximum number of x values, n, depends on
xn] whether you specify a single curve or a family of curves.
Values must be constants; Adams Solver (FORTRAN) does not allow

expressions.
Values must be in increasing order: x1 < x2 < x3, and so on.

Y=y1,y2,y3,y4 [ , . . . , Approximates a single curve by specifying the corresponding y value:
yn] y1,y2,y3,y4[, . . . ,yn] for each x value.
Values must be constants; Adams Solver (FORTRAN) does not allow

expressions.
SPLINE 319
Y=z1,y11,y12,y13,y14 [ Approximates a family of curves by specifying the corresponding y values:

, . . . , y1n] y1,y2,y3,y4[, . . . ,yn] for the x values at unique z values (z1[, . . . ,zm]).
,Y=z2,y21,y22,y23,y24
[ , . . . , y2n] Values must be constants; Adams Solver (FORTRAN) does not allow
,Y=z3,y31,y32,y33,y34 expressions.
[ ,ym1,ym2,ym3,ym4 [ ,
. . . , ymn]] Values for z must be in increasing order: z1 < z2 < z3, and so on.
UNITS For use with Adams Durability only.
Specifies the type of units to be used for all the sets of values. Valid values are:
"angle", "force", "frequency", "length", "mass", "time", "inertia", "velocity",
"acceleration", "angular_velocity", "angular_acceleration", "stiffness",
"damping", "torsion_stiffness", "torsion_damping", "area", "volume", "torque",
"pressure", "area_inertia", "density", "energy", "force_time", "torque_time",
Default: (none)
XUNITS Specify the type of units to be used for individual set of values (X, Y or Z
YUNITS respectively). In general X units will be “time” and Y units will be of type
ZUNITS “length”. Valid values are: "angle", "force", "frequency", "length", "mass",
"time", "inertia", "velocity", "acceleration", "angular_velocity",
"angular_acceleration", "stiffness", "damping", "torsion_stiffness",
"torsion_damping", "area", "volume", "torque", "pressure", "area_inertia",
"density", "energy", "force_time", "torque_time", "flowrate_pressure_d",
"flow_rate", "force_per_angle", "damping_per_angle".
Default: (none)
Extended Definition
Adams Solver (FORTRAN) applies curve-fitting techniques that interpolate between data points to create a
continuous function. If the SPLINE data has one independent variable, Adams Solver (FORTRAN) uses a
cubic polynomial to interpolate between points. If the SPLINE data has two independent variables, Adams
Solver (FORTRAN) uses a cubic method to interpolate between points of the first independent variable, and
then uses a linear method to interpolate between curves of the second independent variable.
The next sections explain more about using the SPLINE statement:
 Using the Spline Function
 Spline Function Interpolation Methods
 Using SPLINE with Adams Durability
Using the Spline Function
320 Adams Solver
To use discrete data input with a SPLINE statement, you must write either a function expression that includes
one of the two Adams Solver (FORTRAN) spline functions (AKISPL and CUBSPL) or a user-written
subroutine that calls one of the two spline data-access subroutines (AKISPL and CUBSPL).
Spline Function Interpolation Methods
The SPLINE functions and data-access subroutines use two different interpolation methods: the Akima
method and a traditional cubic interpolation method.
 The AKISPL function and the AKISPL subroutine use the Akima method of interpolation. This
method includes a local, cubic, curve-fitting technique.
 The CUBSPL function and the CUBSPL subroutine use the traditional cubic method of
interpolation. This method includes a global, cubic, curve-fitting technique.
Both the Akima method and the traditional cubic method use cubic polynomials to interpolate values that
fall between two adjacent points on a curve. Both provide closer approximations than other curve fitting
techniques (for example, Lagrange polynomials, difference tables, and Fourier series). For data with two
independent variables, Adams Solver (FORTRAN) uses linear interpolation to determine values that fall
between curves.For more information about these curve-fitting techniques, see AKISPL and CUBSPL functions.
Using Spline with Adams Durability
The Adams Durability SPLINE statement is an extension of the Adams Solver (FORTRAN) SPLINE
statement that supports the input of experimental test data from industry standard formats DAC and RPC
III. The DAC format comes from nCode/nSoft. The RPC III file format comes from MTS.
DAC or RPC III files do not have standard file extensions. To determine which of these file types is in use,
Adams Solver (FORTRAN) opens the file and reads a minimal amount of information contained in the file
head. If the specified file is not of type DAC or RPC III, Adams Solver (FORTRAN) assumes that the file is
a user-defined file format, and processes the SPLINE statement using a SPLINE_READ user-supplied
subroutine. For more on how to define a SPLINE using the FILE argument for user-defined file formats, see
the example in SPLINE_READ subroutine.
To use DAC or RPC III data that is specified in a SPLINE statement as input to Adams Solver (FORTRAN),
you must write a function expression that includes the INTERP function. For more on how to use the Adams
Durability INTERP function, see the INTERP function.
Tip: When selecting points to represent a curve or a surface:

 Crowd points in regions with high rates of change.
 Spread out points in regions with slow rates of change.
SPLINE 321
Caution: The x and z data must cover the anticipated range of values. However, the following situations
sometimes cause Adams Solver (FORTRAN) to evaluate a spline outside of its defined range:
 Adams Solver (FORTRAN) occasionally approximates partial derivatives using a
finite differencing algorithm.
 Adams Solver (FORTRAN) occasionally attempts an iteration that moves the
independent variable outside of its defined range. If this occurs, Adams Solver
(FORTRAN) issues a warning message and extrapolates the four closest spline points.
If the extrapolation is poor, Adams Solver (FORTRAN) may have difficulty reaching
convergence, which may affect the results.
To avoid these problems, try to use real points, and extend spline values 10 percent beyond the
total dynamic range.
Examples
The set of values in the table below relates the force in a spring to its deformation.
Data Relating Spring and Spring-Deflection Force
Deflection Force
-0.33 -38.5
-0.17 -27.1
-0.09 -15.0
0.0 0.0
0.10 10.0
025 30.0
0.40 43.5
0.70 67.4
From this table, you can determine force when deflection equals -0.33, and you can determine force when
deflection equals -0.17. However, what is the force when deflection equals -0.25?
To determine the force at any deflection value, Adams Solver (FORTRAN) creates a continuous function that
relates deflection and force. This continuous approximation can evaluate the value of the spring force at a
deflection of -0.25. If you input two sets of values (X and Y) with the SPLINE statement, then Adams Solver
can effectively define the function as a curve. The following example illustrates how the SPLINE statement
is used to store the discrete data in the table above.
SPLINE/01,
, X=-0.33, -0.17, -0.09, 0.0, 0.1, 0.25, 0.4, 0.7
, Y=-38.5, -27.1, -15.0, 0.0, 10.0, 30.0, 43.5, 67.4
, XUNITS = “length”
, YUNITS = “force”
322 Adams Solver
functions to fit a curve to the values. The curve allows Adams Solver (FORTRAN) to interpolate a value of
Y for any value of X. It also specifies that the X values are of type length and Y values are of type force.
The set of values in the table below details a set of nonlinear, force-deflection relationships of a spring at
various temperatures.
Data Relating Spring Force to Spring Deflections at Various Temperatures
Force at degrees Fahrenheit:

Deflection: 20° 30° 40° 50°
-0.33 -38.5 -36.0 -30.0 -25.1
-0.17 -27.1 -25.4 -21.7 -18.6
-0.09 -15.0 -13.1 -9.6 -4.4
0.0 0.0 0.0 0.0 0.0
0.1 10.0 9.1 7.5 4.6
0.25 30.0 26.4 21.3 17.8
0.40 43.5 37.9 34.1 27.1
0.70 67.4 60.3 53.2 46.3
From table above, you can determine force when deflection equals -0.33 and when temperature equals 20°.
You can also determine force when deflection equals -0.17 and when temperature equals 30°. However, what
is the force when deflection equals -0.25 and when temperature equals 25°?
To determine the force at any deflection and temperature, you need to define a set of continuous functions
that generally relate force to deflection and temperature. If deflection is the independent x value and
temperature is the independent z value, you can define a set of functions in a family of curves using the
SPLINE statement. The SPLINE statement for this example is shown next:
SPLINE/02,
, X=-0.33, -0.17, -0.09, 0.0, 0.10, 0.25, 0.40, 0.70
, Y=20, -38.5, -27.1, -15.0, 0.0, 10.0, 30.0, 43.5, 67.
, Y=30, -36.0, -25.4, -13.1, 0.0, 9.1, 26.4, 37.9, 60.3
, Y=40, -30.0, -21.7, -9.6, 0.0, 7.5, 21.3, 34.1, 53.2
, Y=50, -25.1, -18.6, -4.4, 0.0, 4.6, 17.8, 27.1, 46.3
functions to fit a curve to the y values at each set of x and z values.
Examples Using the SPLINE Statement with Adams Durability
The following examples require a licence for the Adams Durability plugin to Adams Solver (FORTRAN).
SPLINE/101,
FILE=test.dac
MOTION/6, I=401, J=402, B3
,FUNCTION=INTERP(TIME,3, 101)*DTOR
SPLINE 323
The SPLINE statement defines a spline using test data supplied from a DAC file named test.dac. The
MOTION statement controls the rotation of Marker 401 with respect to Marker 402 about the z-axis of
Marker 401 using a function expression.
The function expression for the MOTION statement references data from the SPLINE statement using the
INTERP function. The test data from the DAC file is known to be acquired in degrees, and since Adams
Solver (FORTRAN) expects rotational motion to be specified in radians, a conversion from degrees to radians
(factor DTOR) is also included in the function expression.
MOTION/1, I=401, J=402, X, FUNCTION=INTERP(TIME,3,201)
MOTION/2, I=401, J=402, Y, FUNCTION=INTERP(TIME,3,202)
MOTION/3, I=401, J=402, Z, FUNCTION=INTERP(TIME,3,203)
This example defines three splines that reference three different channels of test data from the same RPC III
file. Each of these splines supplies the test data to a MOTION statement using the INTERP function.
324 Adams Solver
SPRINGDAMPER
Format
Arguments
ANGLE=r Defines the reference angle for the torsional spring. If the reference torque of the
spring is zero, ANGLE equals the free angle. Adams Solver (FORTRAN) assumes
ANGLE is in radians unless a D is added after the value.
Default: 0
C=r Specifies the viscous damping coefficient for the force. The force due to damping is
zero when the system is at rest.
Range: C > 0
CT=r Specifies the viscous damping coefficient for the torque. The torque due to damping
is zero when the system is at rest. CT must be in units of torque per radian per unit
of time.
Range: CT > 0
FORCE=r Specifies the reference force at LENGTH.
Default: 0
SPRINGDAMPER 325
I=id, J=id Specifies the identifiers of the two markers between which the force or the torque is
to be exerted.
K=r Specifies the spring stiffness coefficient for the force.
Range: K > 0
KT=r Specifies the spring stiffness coefficient for the torque. KT must be in units of torque
per radian.
Range: KT > 0
LENGTH=r Defines the reference length for the spring. If the reference force of the spring is zero,
Range: LENGTH > 0

Default: 0
ROTATIONAL Designates a rotational springdamper.
TORQUE=r Specifies the reference torque of the torsional spring at ANGLE.
Default: 0
TRANSLATIONAL Designates a translational springdamper.
Extended Definition
For a rotational springdamper, the z-axis of the I marker and the z-axis of the J marker must be parallel and
must point in the same direction.
Because the springdamper force is always an action-reaction force, the direction of the translational force is
along the line segment connecting the I and the J markers. Thus, if the force is positive, the markers
experience a repelling force along this line, and if the force is negative, the markers experience an attracting
force. The magnitude of the translational force applied to the parts containing the two markers is linearly
dependent upon the relative displacement and velocity of the two markers. The following linear constitutive
equation describes the force applied at the I marker:
Fa = -C (db/dt) - K(b-LENGTH) + FORCE
The force value is the force on the I marker applied by the J marker; the force on the J marker is equal and
opposite. The term b is the distance between the I and the J markers. Adams Solver (FORTRAN) assumes
that b is always greater than zero. Adams Solver (FORTRAN) automatically computes the terms db/dt and b.
The following linear constitutive equation describes the torque applied at the I marker:
Ta = -CT (da/dt) - KT(a-ANGLE) + TORQUE
The torque value is applied to the I marker about the positive z-axis of the I marker; the torque on the J
marker is equal and opposite to the torque on the I marker. The right-hand rule defines a positive torque.
The term a is the angle of the I-marker x-axis relative to the J-marker x-axis, measured about the J-marker z-
326 Adams Solver
axis. Adams Solver (FORTRAN) takes into account the total number of complete rotations. Adams Solver
(FORTRAN) automatically computes the terms da/dt and a.
Caution:  If the z-axis of the I marker is not parallel to, and/or not pointed in the same direction
as, the z-axis of the J marker for a rotational springdamper, the results are
unpredictable.
 Since the line-of-sight method determines the direction of a translational
springdamper force, the I and the J markers cannot be coincident.
Examples
SPRINGDAMPER/012, I=25, J=30, K=5, C=.1, L=.01
, TRANSLATION
This SPRINGDAMPER statement describes a force that Marker 30 applies to Marker 25. Marker 25 also
applies a force of equal magnitude and opposite direction to Marker 30. The argument TRANSLATION
indicates that this is a translational springdamper, rather than a rotational one. Therefore, the magnitude of
the force is proportional to the spring free length, to the distance between the two markers, and to the time
rate of change of the distance between the two markers. The L argument indicates that the spring free length
is 0.01 length units (L is the free length because the FORCE argument defaults to zero). The spring constant
K is 5 force units per unit length, and the damping constant C is 0.1 force units-seconds per unit length.
STRING 327
STRING
The STRING statement defines a character string that may be referred to later in the execution of Adams
Solver. An interactive STRING command can be used to alter or review this character string. A GTSTRG
subroutine can be used to retrieve this character string in a user-written subroutine.
Format
STRING/id, STRING=c
Arguments
STRING=c Specifies the character string to be stored. You must include a character string and the
supplied string may be as long as 1024 characters. The STRING argument and value
must appear together on one line.
Caution: The following characters are not permitted in a STRING argument because they are delimiters
in the Adams Solver command language: comma (,), semicolon (;), ampersand (&), and
exclamation point (!). This is because the comma indicates that additional Adams Solver
arguments follow; the semicolon indicates that additional Adams Solver statements follow on
the same line; the ampersand indicates that the next line is a continuation of the statement on
this line; and the exclamation point indicates that Adams Solver is to stop reading the line.
Examples
STRING/101, STRING=MARKER=
This STRING statement enters the character string MARKER= for later reference. The GTSTRG
subroutine can retrieve this string.
328 Adams Solver
TFSISO
The TFSISO (Transfer Function, Single-Input, Single-Output) statement defines a single-input, single-
output transfer function as a ratio of two polynomials in the Laplace domain when used with the associated
ARRAY statements.
Format
Arguments
DENOMINATOR Specifies the coefficients of the polynomial in the denominator of the transfer
=a0[,...,a29] function. Coefficients are listed in order of ascending powers of s, starting with s to
the zero power, including any intermediate zero coefficients. The number of
coefficients for the denominator must be greater than or equal to the number of
coefficients for the numerator.
NUMERATOR=b0 Specifies the coefficients of the polynomial in the numerator of the transfer function.
[,...,b29] Coefficients are listed in order of ascending powers of s, starting with s to the zero
power, including any intermediate zero coefficients. The number of coefficients for the
numerator must be less than or equal to the number of coefficients for the
denominator.
STATIC_HOLD Indicates that the TFSISO states are not permitted to change during static and quasi-
static analysis.
TFSISO 329
U=id Designates the ARRAY statement in the dataset that is used to define the input (or
control) for the transfer function. You must have an ARRAY statement with this
identifier in the dataset and it must be of the U type. If you specify the SIZE of the U
ARRAY, it must be 1.
X=id Designates the ARRAY statement in the dataset that is used to define the state variable
array for the transfer function. You must have an ARRAY statement with this identifier
in the dataset; it must be of the X type; and it may not be used in any other LSE, GSE,
or TFSISO statement. If you specify the SIZE of the X ARRAY, it must be one less
than the number of coefficients in the denominator.
Y=id Designates the ARRAY statement in the dataset that is used to define the output for
the transfer function. You must have an ARRAY statement with this identifier in the
dataset; it must be of the Y type; and it may not be used in any other LSE, GSE, or
TFSISO statement. If you specify the SIZE of the Y ARRAY, it must be 1.
Extended Definition
The TFSISO (Transfer Function, Single-Input, Single-Output) statement is designed to model a linear, time-
invariant dynamic system defined in the Laplace domain, especially to facilitate the import of elements from
control-system block diagrams. It can also be used, however, to define an arbitrary set of constant-coefficient,
differential and algebraic equations which can be expressed in the Laplace domain as
y(s) b0 + b1 s1 + … + bm sm
G ( s ) = ---------- = -----------------------------------------------------
-
u(s) a0 + a1 s 1 + … + ak s k
where m < k
The TFSISO follows standard control systems terminology, where x is the state variable array, y is the output
variable, and u is the input variable. Initial conditions are assumed to be identically zero. In the Adams Solver
(FORTRAN) dataset, each of these arrays is defined using an ARRAY statement. The characteristic equation
for a single TFSISO statement, defined by the DENOMINATOR argument, can be a polynomial of degree
less than 30.
Internally to Adams Solver (FORTRAN), there is an algorithm to automatically convert the list of fixed
numerator and denominator coefficients to a canonical state-space form; that is, a set of coupled, linear,
constant-coefficient differential equations and a single algebraic equation.
When you reference only the output of the TFSISO, the details of the internal equations are unimportant.
In some cases, however, it may be useful to understand how Adams Solver (FORTRAN) constructs the
equations. When interpreting Adams Linear output or examining the values in the X ARRAY, for instance,
it may be necessary to determine what the internal states represent.
The conversion from transfer function to canonical state-space form is done in two steps. First, the numerator
and denominator are normalized by the coefficient of the largest power of s in the denominator.
q = [b0/ak,b1/ak,...,bm/ak,0,...,0,0]
p = [a0/ak,a1/ak,...,ak-1/ak,1]
330 Adams Solver
where array p is of length k+1. Array q is also of length k+1, padded with zeros, if necessary. The entries in
arrays p and q are labeled from 0 to k for the following analogous transfer function:
( s )-
y--------- q0 + q1 s 1 + … + qk s k
G(s) = = --------------------------------------------------
-
u(s) p0 + p1 s 1 + … + pk s k
The equivalent state space realization of this transfer function is:
 x·  A B x 
  =  
y  C D y 
where:
–pk – 1 1 0 . . . 0 0 qk – 1 – pk – 1 qk
–pk – 2 0 1 . . . 0 0 qk – 2 – pk – 2 qk
. . . 1 . . . . .
A = . . . . . . . . B = .
. . . . . . 1 . .
–p1 0 0 . . . 0 1 q1 – p1 qk
–po 0 0 . . . 0 0 qo – po qk
C = 100...00 D = qk
Note: Except in the specific case where the numerator and denominator are of equal orders, qk= 0.
Tip:  Keeping track of which ARRAY statements go with which system elements is easier if
all system elements are numbered uniquely and the ARRAY statements are numbered
consistently. For example, the X ARRAY that goes with TFSISO/100 could be
ARRAY/100; the U ARRAY would then be ARRAY/101, and the Y ARRAY would
be ARRAY/102.
 Often, transfer functions are needed where the order of the numerator is larger than
the denominator. The classic example of this is the pure differentiator. It is generally
possible to avoid this situation in Adams Solver (FORTRAN) by using the derivative
of the input, i.e., marker velocity or acceleration instead of displacement or velocity.
In other cases, you may need to algebraically incorporate another transfer function
into a system or subsystem such that the overall transfer function has a higher degree
denominator.
TFSISO 331
Caution:  Although the TFSISO statement allows for up to 30 numerator and denominator
coefficients in the transfer function, the conversion to the canonical state-space form
is typically not robust for higher-order systems. Such systems should be used only
when you are confident that the problem is well-posed. An alternate approach more
suited to Adams Solver (FORTRAN) would be to break up (factor) the large transfer
function into a series of smaller ones in separate TFSISO statements.
 Note that, if the output equation defined by the TFSISO statement has no solution or
Adams Solver (FORTRAN) most likely fails to converge or possibly converge to an
unexpected answer. You can avoid this possibility by not referencing the X (state) or Y
(output) ARRAYs in the definition of the VARIABLE in the U (input) ARRAY.
 You must be sure to list the coefficients in order of increasing powers of s. Some texts
and programs use the opposite convention, listing coefficients in order of decreasing
powers of s.
 Adams Solver (FORTRAN) does not check for pole-zero cancellation in the TFSISO
numerator and denominator. In this case, the canonical transform used in Adams
Solver leads to an unobservable but controllable state space realization. Adams Solver
(FORTRAN) models containing such elements when tested for observability in
control design software are indicated having some unobservable portions. You should
perform any pole-zero cancellation prior to defining the TFSISO data.
Examples
ARRAY/100, X
ARRAY/102, Y
VARIABLE/101, FUNCTION=ACCZ(5,99,5)
TFSISO/100, X=100, U=101, Y=102,
, NUMERATOR=1.0, DENOMINATOR=100.0,10.0,1.0
These statements define the following transfer function.
332 Adams Solver
1
G ( s ) = ----------------------------------
2
-
s + 10s + 100
ARRAY/100 is the state array. ARRAY/101 is the input array. ARRAY/102 is the output array.
VARIABLE/101 defines the input.
Applications
The TFSISO statement may be most useful for adding feedback controls to an Adams Solver (FORTRAN)
model. A series of TFSISO statements can be assembled to resemble any linear block diagram arrangement.
The transfer function can be derived manually or may be imported directly from a control system design
program such as MATRIXx or MATLAB. Normally, the mechanical portion of the model includes some kind
of actuator which depends on the TFSISO output.
TFSISO statements can also be conveniently used in many cases to replace systems of coupled DIFF and
VARIABLE statements (for nonlinear equations, the GSE statements should be used). Examples of possible
dynamics system uses include unsteady aerodynamics, hydraulics, power transmission, and electrodynamics.
You can use the current values of TFSISO state variables and outputs in both function expressions and user-
written subroutines via the associated ARRAY facilities (see the function expression ARYVAL, and the
subroutines: GTARAY, SYSARY, and SYSFNC). That is, instead of Adams Solver (FORTRAN) functions and
FORTRAN callable subroutines dedicated explicitly to the TFSISO statement, the system states and outputs
are accessed by offset referencing through the appropriate ARRAY routines. This method of referencing the
variables makes access to the system states and outputs consistent for all three system modeling elements, the
TFSISO statement, the GSE statement, and the LSE statement.
TITLE 333
TITLE
The TITLE delimiter is the entire first line in a dataset and describes the dataset. The title cannot be more
than 80 characters and must fit on one line. It may contain any printable ASCII characters and any number
of blank spaces. The title may be left blank.
Examples
•
•
•
(statements)
•
•
•
END
This example contains a TITLE delimiter and an END delimiter that indicates the end of the dataset. Adams
Solver writes out the TITLE delimiter for you in the output files. For example it appears in the message file
(.msg) as follows:
Adams Solver dataset Title:
See other Dataset delimiter available.
334 Adams Solver
UCON
The UCON statement defines a user-written constraint. With a UCON, it is possible to constrain the
configuration of the system as well as the motion of the system. Configuration constraints (that is, holonomic
constraints) can be:
 Explicit functions of time, in which case, they are referred to as rheonomic.
 Restricted to functions of system displacements, in which case, they are referred to as scleronomic.
Motion constraints (that is, nonholonomic constraints) may be defined in terms of a linear combination of
system velocities.
Format
UCON/id, FUNCTION=USER(r1[,...,r30])
Arguments
FUNCTION=USER(r1[,...,r30]) Defines and passes up to thirty constants to a UCOSUB user-written

subroutine. These can be part identifiers, variable codes, and other data
that the UCOSUB needs to define the constraint (see the UCOSUB
subroutine).
Extended Definition
The UCON statement defines a system constraint as a function of time and as many as thirty variables. Each
of these variables must be the displacement or the velocity of a part. For any part at any point in time, six
displacements define its position, and six velocities define its motion.
The six displacements are the x, y, and z translations and the three Euler angle rotations. The six velocities are
the x, y, and z translational speed and the time derivatives of the three Euler angles. Adams Solver
(FORTRAN) measures all of these displacements and velocities at the origin of the principal axes with respect
to the global coordinate system. The UCON statement should be used to define only a constraint that is not
available in any of the other constraint statements.
UCON 335
Tip:  The principal axes are located at the part center of mass. The principal axes of a part are the
axes about which products of inertia are zero, that is, for which the inertia matrix is
diagonal.
 Adams Solver (FORTRAN) imposes UCONs on the principal coordinate systems of the
parts to which they belong. If a part has mass, its principal coordinate system is at its center
of mass and is in alignment with the axes of its principal moments of inertia. If products of
inertia (xy, xz, or yz) are declared for the IP argument of a PART statement, the principal
axes may differ from the center-of-mass marker axes specified with the CM argument. This
is because Adams Solver (FORTRAN) changes the Euler angles of the principal axes until
the products of inertia disappear. In that case, the origin of the principal axes are located at
the origin of the center-of-mass marker axes, but the orientation of the principal axes differ
from the orientation of the center-of-mass marker axes. If a part has zero mass, its principal
coordinate system is the same as that of its body coordinate system (BCS).
Caution:  The UCON statement should be used only if you are very familiar with Adams Solver
(FORTRAN). Velocity-dependent constraints must be expressible in the following
form:
30
F ( q', q, t ) =  ai ( q, t )q'i + f ( t ) = 0
i=1
In this equation, the a coefficients must not be velocity dependent. The symbols q’i
and ai refer to the ith velocity variable and to its accompanying coefficient. The
coefficient can be functionally dependent on displacements and time, but it cannot be
dependent on velocities. Note that the equation includes no products involving one
velocity variable with another.
Caution:  Inequality constraints cannot be modeled with a UCON statement.
 Because Adams Solver (FORTRAN) applies UCONs to the principal axes of the part
and not to the center-of-mass marker, REQUEST statements or the SYSARY or
SYSFNC subroutines cannot be used to obtain UCON reaction forces.
336 Adams Solver
Caution:  Adams Solver (FORTRAN) does not warn you if the location of a BCS, as
determined by the initial configuration of the part, is inconsistent with the
constraint(s) imposed on the part by a UCON statement. Adams Solver
(FORTRAN) handles the inconsistency by overriding the initial part configuration
and moving the part to conform to the constraint(s) defined in the UCOSUB
evaluation subroutine. If you use a UCON statement in the model, you need to check
to see if, during initial conditions analysis, Adams Solver (FORTRAN) has altered the
location and/or orientation of the part(s) affected by the UCON. One way to do this
is to compare the tabular output file for the part(s) initial conditions with the initial
part(s) location(s) and/or orientation(s) as defined in the Adams Solver (FORTRAN)
dataset or by Adams Solver (FORTRAN) interactive commands.
Caution:  If you use the UCON statement for a velocity-dependent constraint and then use the
ABAM integrator to integrate the equations of motion, Adams Solver (FORTRAN)
prevents execution. Under these circumstances, use a BDF integrator to integrate the

UNITS 337
UNITS
The UNITS statement sets the appropriate units for an Adams Solver (FORTRAN) analysis. This ensures
that force computations, both on input and on output, correctly conforms to your choice of length, mass,
and time units.
Format
338 Adams Solver
Arguments
FORCE={DYNE,KILOGRAM_FORCE,K Selects a predefined unit for forces. Must be used in

NEWTON, conjunction with LENGTH, MASS, and TIME.
KPOUND_FORCE,NEWTON,POUND
_FORCE,OUNCE_FORCE}
LENGTH={CENTIMETER,FOOT,INCH Selects a predefined unit for lengths. Must be used in
,KILOMETER,METER, conjunction with FORCE, MASS, and TIME.
MILLIMETER,MILE}
MASS={GRAM,KILOGRAM,KPOUND_ Selects a predefined unit for masses. Must be used in
MASS,OUNCE_MASS, conjunction with FORCE, LENGTH, and TIME.
POUND_MASS,SLUG}
SYSTEM={CGS,FPS,IPS,MKS,NONE} Selects a predefined units system instead of selecting each
unit individually. MKS implies meter, kilogram, second
and newton. CGS implies centimeter, gram, second and
dyne. FPS implies foot, pound mass, second and pound
force. IPS implies inch, pound mass, second and pound
force. NONE implies that the dataset is written
nondimensionally and that Adams Solver (FORTRAN)
sets UCF to 1.0.
TIME={HOUR,MILLISECONDS,MINU Selects a predefined unit for time. Must be used in
TE,SECOND} conjunction with FORCE, LENGTH, and MASS.
UCF=r Specifies a Units Consistency Factor (UCF) when you
prefer to work in a system of units not covered by any of
the choices listed above. The UCF is the conversion
factor from model force units to inertial force units as
shown by the following equation.
Force • UCF = Mass • Acceleration
When using a system of units not covered by any of the

choices above, you should use the dimensional analysis
equation shown below to determine the correct UCF
value to specify.
Extended Definition
The UNITS statement sets the appropriate units for an Adams Solver (FORTRAN) analysis and allows
Adams View to account for your choice. This ensures that Adams Solver (FORTRAN) both interprets and
reports force values in the chosen force units.
UNITS 339
In most cases, you select a system of units using the SYSTEM argument or the FORCE, MASS, LENGTH,
and TIME arguments. For cases not covered by the predefined choices, specifying the appropriate UCF still
allows Adams Solver (FORTRAN) to interpret forces correctly. Adams Solver (FORTRAN) always uses
radians as the unit for angular measurements.
To determine the correct UCF, you must solve the following dimensional analysis equation.
For example, if you want to work in kiloNewtons (kN), kilograms (kg), meters (m) and seconds (s), you
would write the following equation:
1kg ⋅ 1m-
1kN = -------------------- ⋅ UCF
1s 2
given:
kg ⋅ m
1kN = 1000N and 1N = --------------
s2
You can substitute these into the equation to get:
1kg ⋅ 1m-
1kN = -------------------- ⋅ UCF
1s 2
1000N = 1N ⋅ UCF
UCF = 1000
If you want to work in tons_force (tf ), tons_mass (tm), yard (yd), and minute (min) units you would write
the following equation.
1tm ⋅ yd-
1tf = ------------------- ⋅ UCF
1min 2
given:
1tf = 2000lbf 1lbf = 1slug ⋅ ft ⁄ s 2 1yd = 3ft

1tm = 2000lbm 1lbm = 1slug ⋅ 1g 1min = 60s
let:
1g = 32.2ft ⁄ s 2
then:
340 Adams Solver
lbf
1lbm = ----------------------2-
32.2ft ⁄ s
You cna substitute these equations into the equation to get:
2000lbms ⋅ 3ft-
2000lbf = ----------------------------------- ⋅ UCF
( 60s ) 2
2000 ( lbfs 2 ⁄ 32.2ft ) ⋅ 3ft-
2000lbf = ---------------------------------------------------------- ⋅ UCF
( 60s ) 2
Then cancel common terms and solve for UCF:
3 ⁄ 32.2
1 = ----------------- ⋅ UCF
60 ⋅ 60
UCF = 38640.0
Tip: Using the UNITS statement with the individual unit arguments or the SYSTEM argument
allows Adams View to understand the model's units and give consistent output. Avoid using
UCF, if possible.
Examples
UNITS/FORCE=KILOGRAM_FORCE,
,MASS=KILOGRAM, LENGTH=MILLIMETER, TIME=SECOND
This UNITS statement selects force units of kilogram_force, mass units of kilograms, length units of
millimeters, and time units of seconds.
VARIABLE 341
VARIABLE
The VARIABLE statement defines a variable in terms of a scalar algebraic equation for independent use, or
as part of the PINPUT, POUTPUT, or ARRAY statement.
Format
Arguments
Specifies an expression or defines and passes constants to a

e user-written subroutine to define a variable. If you want to
 
FUNCTION =   define the variable with an expression, FUNCTION must be
 USER ( r 1 [ ,…, r 30 ] )  followed with an equal sign and the expression. If you want to
define the variable with a user-written subroutine,
that Adams Solver (FORTRAN) passes to the user-written
subroutine VARSUB.
IC=r Specifies an approximate initial value for the VARIABLE.
Adams Solver (FORTRAN) may adjust the value of IC when
it performs an initial condition analysis. Entering an accurate
value for IC may help Adams Solver (FORTRAN) converge
to the initial conditions solution.
subroutine VARSUB
Extended Definition
The VARIABLE statement creates a user-defined algebraic equation. The value of the VARIABLE statement
may depend on almost any Adams Solver (FORTRAN) system variable. Note that you cannot access reaction
forces from a UCON, and PTCV and CVCV reaction forces may only be accessed from REQUEST and
SENSOR expressions.
342 Adams Solver
You can define the value of the VARIABLE statement by either writing a function expression in the dataset
or by calling a VARSUB user-written subroutine. For more on user-written and utility subroutines, see User-
Written Subroutines on and Utility Subroutines.
Function expressions and user-written subroutines can access the value of the VARIABLE statement with the
Adams Solver (FORTRAN) function VARVAL(id) (see VARVAL) to represent the value, where id specifies the
user-selected identifier of the VARIABLE statement. User-written subroutines access single VARIABLE
statement values by calling the subroutine SYSFNC.
Caution:  Use caution when defining a VARIABLE statement that is dependent on another
VARIABLE statement or on an Adams Solver (FORTRAN) statement that contains
functions. If a defined system of equations does not have a stable solution,
convergence may fail for the entire Adams Solver (FORTRAN) model. The following
V=V+1.
However, when Adams Solver (FORTRAN) tries to solve this equation using the
Newton-Raphson iteration, the solution diverges and Adams Solver (FORTRAN)
displays a message on the screen indicating that the solution has failed to converge.
exception or lead Adams Solver (FORTRAN) away from the desired solution.
Examples
VARIABLE/4, FUNCTION = IMPACT(DZ(10,90),
, VZ(10,90), 1, 3E5, 1.2, 1,.05)
This VARIABLE statement defines an impact function. You may refer to this function as VARVAL(4) in
other function expressions. This may make the other expressions more concise and readable, and might avoid
repeated impact function calculations.
VFORCE 343
VFORCE
The VFORCE statement creates a translational vector force element that is specified using three orthogonal
components. You may define the VFORCE statement through user-specified function expressions in the
Adams Solver (FORTRAN) dataset or through user-written subroutines.
Format
Arguments
FX=e Specifies the magnitude and sign of the x component of the VFORCE
translational force. The direction of this component is parallel to the x-
axis of the RM marker.
FY=e Specifies the magnitude and sign of the y component of the VFORCE
translational force. The direction of this component is parallel to the y-
FZ=e Specifies the magnitude and sign of the z component of the VFORCE
translational force. The direction of this component is parallel to the z-
FUNCTION=USER(r1[,...,r30]) Specifies up to 30 user-defined constants for use in computing the force
components in a user-defined subroutine VFOSUB.
I=id Specifies the marker at which Adams Solver (FORTRAN) applies the
action force. You must ensure that the I marker is a fixed marker and on
Adams Solver (FORTRAN) always applies the force at a fixed point on
the part.
344 Adams Solver
JFLOAT=id Specifies the marker at which Adams Solver (FORTRAN) applies the
marker and on a different part than the I marker. Adams Solver
(FORTRAN) moves the JFLOAT marker to keep it superimposed on
the I marker, which means that the reaction force may move with
respect to the part. Adams Solver (FORTRAN) does not calculate
RM=id Specifies the marker which determines the orientation of the force
ROUTINE=libname::subname Specifies an alternative library and name for the user subroutine VFOSUB.
Extended Definition
The VFORCE statement creates an Adams Solver (FORTRAN) translational vector force element that
applies a three-component force between two parts of the system. The element applies an action force to the
part to which the I marker belongs and a corresponding reaction force to the part to which the JFLOAT
marker belongs. The VFORCE statement establishes the position of the JFLOAT marker. As the system
moves, Adams Solver (FORTRAN) moves the JFLOAT marker on its part to keep the JFLOAT and I markers
superimposed. Therefore, Adams Solver (FORTRAN) applies the reaction force to the JFLOAT marker’s part
at the instantaneous position of the I marker.
The total vector force depends on the vector sum of the individual force components that you specify. The
magnitude of the force is the square root of the sum of the squares of the magnitude of the three mutually-
orthogonal force components. You can specify the functions with function expressions (see Function
Expressions) or user-written FORTRAN subroutines (see User-Written Subroutines).
RM marker axes determine the direction of the force action. The reaction is equal and opposite to the action.
Formulation
Action
Values:
F a = FX xˆ rm + FY yˆ rm + FZ ẑ rm
where:
 Fa is the action applied to the I marker
 FX is the user-defined function defining the magnitude and sign of the x-component
 FY is the user-defined function defining the magnitude and sign of the y-component
 FZ is the user-defined function defining the magnitude and sign of the z-component
VFORCE 345

Reaction
Values:
Fr = -Fa
where Fr is the reaction applied to the JFLOAT marker
same part as the I marker, or the JFLOAT marker, or to a third, unrelated part.
Caution: The user-defined functions FX, FY, and FZ should be smooth, continuous, and single-valued.
These conditions make the solution process very effective.
Examples
, FX = -20.*VX(310,9900,310)\
, FY = -20.*VY(310,9900,310)\
, FZ = -20.*VZ(310,9900,310)
This VFORCE statement defines a vector force acting between fixed Marker 310 and floating Marker 9910.
Expressions FX, FY, and FZ define the magnitudes and signs of the force components along the x, y, and z
axes of the reference marker, which is also Marker 310. Adams Solver (FORTRAN) superimposes floating
Marker 9910 on Marker 310, and apply the reaction force at that point.
Applications
The VFORCE statement is most useful to define a vector force whose point of application and/or direction
is most easily formulated in a coordinate system that moves or is on a different part. You can use a VFORCE
statement to model a point mass sliding down an inclined cantilever for normal and frictional force effects
(see the figure below). The RM reference marker is fixed to the cantilever and supplies the orientation for the
normal and frictional forces.
Model of a Point Mass Sliding Down Incline
346 Adams Solver
You can also use the VFORCE statement to represent the tractive, cornering, and vertical tire forces associated
with the tire contact patch of a moving vehicle. In this instance, the RM reference marker would be fixed to
the vehicle at the approximate point where the tire contacts the ground. The global velocity of the contact
point, resolved onto the RM axes, would provide the velocity information necessary to compute the tractive
and cornering forces.
When compared with the SFORCE statement (see SFORCE), the VFORCE statement can vary both its point
respect to the RM marker).
If torque effects are important, you can use the VFORCE statement in conjunction with the VTORQUE
statement (see VTORQUE) to supply resultant moment components. Alternatively, you may employ a single
GFORCE statement (see GFORCE) to specify a unified six-component force set.
VTORQUE 347
VTORQUE
The VTORQUE statement defines a vector torque that consists of three orthogonal components. You can
define the VTORQUE statement through user-specified function expressions in the Adams Solver
(FORTRAN) dataset or through user-written subroutines.
Format
Arguments
FUNCTION=USER(r1[,...,r30]) Specifies up to thirty user-defined constants used to compute the torque

components in an externally-defined subroutine VTOSUB.
I=id Specifies the marker on the part to which Adams Solver (FORTRAN)
applies the action torque. You must ensure that the I marker is a fixed
marker and on a different part than the JFLOAT marker.
JFLOAT=id Specifies the marker on the part to which Adams Solver (FORTRAN)
applies the reaction torque. You must ensure that the JFLOAT marker
superimposed on the I marker. Adams Solver (FORTRAN) does not
calculate reaction forces when the JFLOAT marker is on the ground
part.
RM=id Specifies the marker which determines the orientation of the torque
ROUTINE=libname::subname Specifies an alternative library and name for the user subroutine VTOSUB.

348 Adams Solver
TX=e Specifies the magnitude and sign of the x component of the torque
rotation).
TY=e Specifies the magnitude and sign of the y component of the torque
component is parallel to the y-axis of the RM marker in the sense of the
rotation).
TZ=e Specifies the magnitude and sign of the z component of the torque
rotation).
Extended Definition
The VTORQUE statement creates an Adams Solver (FORTRAN) rotational force element that applies a
vector torque between two parts of the system. The element applies an action to the part to which the I
marker belongs and a corresponding reaction to the part to which the JFLOAT marker belongs. The
VTORQUE statement establishes the position of the JFLOAT marker. As the system moves, Adams Solver
(FORTRAN) moves the JFLOAT marker on its part to keep the JFLOAT and I markers superimposed. Thus,
Adams Solver (FORTRAN) applies the reaction torque to the JFLOAT marker’s part.
The components of the torque depend on expressions or subroutines that you supply. The magnitude of the
torque is the square root of the sum of the squares of the magnitudes of the three mutually orthogonal torque
components. You can specify these functions using function expressions (see Function Expressions) or user-
written FORTRAN subroutines (see User-Written Subroutines).
The direction of the torque action is determined by the resultant vector formed by the three component
torque you defined along the RM marker axes. The reaction is equal and opposite to the action.
Formulation
Action
Values:
ˆ
T a = TX xˆ rm + TY yˆ rm + TZ z rm
 Ta is the action applied to the I marker
 TX is the user-defined function defining the magnitude and sign of the x-component according to
the right-hand rule
VTORQUE 349
 TY is the user-defined function defining the magnitude and sign of the y-component according to
the right-hand rule
 TZ is the user-defined function defining the magnitude and sign of the z-component according to
the right-hand rule
 yˆ rm rm is a unit vector along the + y-direction of the RM marker

ˆ
 z rm is a unit vector along the + z-direction of the RM marker
Reaction
Values:
Tr = -Ta
where Tr is the reaction applied to the JFLOAT marker.
Tip: Depending on the nature of the desired torque relationship, the RM marker may belong to the
same part as the I marker or the JFLOAT marker, or to a third, unrelated part.
Caution: The user-defined functions TX, TY, and TZ should be smooth, continuous, and single-valued.
Examples
, TX = -6.*WX(310,9900,310)\
, TY = -6.*WY(310,9900,310)\
, TZ = -6.*WZ(310,9900,310)
This VTORQUE statement defines a vector torque acting between fixed Marker 310 and floating Marker
9911. Expressions TX, TY, and TZ define the magnitude and sign of the torque components about the x, y,
and z axes of the reference marker, which is also Marker 310. Adams Solver (FORTRAN) superimposes
floating Marker 9911 on Marker 310, and apply the reaction force at that point.
Applications
The VTORQUE statement is particularly useful when you need to define a vector torque whose point of
application and/or direction is most easily formulated in a coordinate system which moves or is on a different
part.
For example, the VTORQUE statement could be used to represent the yaw, pitch, and rolling moments on
a flight vehicle (see the figure below). In this instance, the RM marker would be fixed to the vehicle at its
aero-dynamic center. You can use a VFORCE statement (see VFORCE) to supply the remaining translational
forces, or the GFORCE statement (see GFORCE) to provide all six forces using a single entity. In any event, you
350 Adams Solver
can use the reference marker to resolve the aircraft inertial velocity onto aircraft axes for subsequent
calculation of aerodynamic forces.
Yaw, Pitch, and Rolling Moments on a Flight Vehicle
Another application where a VTORQUE would significantly simplify modeling and analysis is in
consideration of gravitational torques exerted on Earth-orbiting satellites. In this case the RM marker would
not be fixed in the satellite or the Earth, but would move with the rotating line segment extending between
the satellite and the Earth.
When compared with the SFORCE statement (see SFORCE ), the VTORQUE statement offers the advantage
that the resultant torque direction (with respect to the RM marker) can vary.
1
Adams Solver (FORTRAN) Functions

You use function expressions to define a wide variety of nonstandard phenomena in your model. A
comprehensive set of symbolic variables operators and functions are provided for this purpose. These can be
used to create complex expressions.
Below are the Adams Solver (FORTRAN) function expressions grouped according to their function. Detailed
information on each function expression can be found by following the links.
Type of Function: Function Name:

FORTRAN 77 ABS MAX
ACOS MIN
AINT MOD
ANINT SIGN
ASIN SIN
ATAN SINH
ATAN2 SQRT
COS TAN
COSH TANH
EXP
LOG
Simulation constants and variables TIME
MODE
PI
DTOR
RTOD
Displacement AX INCANG
AY ORIENT
AZ PHI
DM PITCH
DX PSI
DY ROLL
DZ THETA
YAW
Velocity VM WM
VR WX
VX WY
VY WZ
VZ
Acceleration ACCM WDTM
ACCX WDTX
ACCY WDTY
ACCZ WDTZ
2 Adams Solver
Type of Function: Function Name:

Generic force FM TM
FX TX
FY TY
FZ TZ
Element-specific applied force BEAM NFORCE
BUSH SFORCE
FIELD SPDP
FRICTION VFORCE
GFORCE VTORQ
Element-specific reaction force CVCV
JOINT
JPRIM
MOTION
PTCV
System element ARYVAL
DIF
DIF1
PINVAL
POUVAL
SENVAL
VARVAL
Arithmetic IF IF
Interpolation AKISPL
CUBSPL
CURVE
INTERP
General BISTOP INVPSD
CHEBY POLY
FORCOS SHF
FORSIN STEP
HAVSIN STEP5
IMPACT SWEEP
Flexible body constants FXFREQ
FXMODE
ABS 3
ABS
The ABS function returns the absolute value of the expression a.
Format
ABS(a)
Arguments
Examples
Variable/1, FUNCTION= ABS(DX(21,11)*VX(21,11)+DY(21,11)*VY(21,11)
+ DZ(21,11)*VZ(21,11))
This variable statement defines a new state variable. Its value is the absolute value of the radial velocity
between Markers 21 and 11.
See other FORTRAN 77 available.
4 Adams Solver
ACCM
The ACCM function calculates the magnitude of the second time derivative of the displacement vector of
marker i from marker j. The time derivatives are taken in the reference frame of marker l. Markers j and l
default to the global coordinate system and the global reference frame if they are not specified.
Format
ACCM(i[,j][,l])
Arguments

= 0 or omit the argument if you want the time derivatives to be calculated in the ground coordinate
system (GCS).
Extended Definition
Mathematically, ACCM is calculated as follows:
(l) 2 (l) 2 (l) 2 (l) 2

d d d d
ACCM ( i ,j ,l ) = Ri – Rj ⋅ Ri – Rj
dt2 d t2 dt2 d t2
Note that for any vector quantity p:
(A) (B)
d d
p≠ p
dt dt
Examples
This statement defines the second component of a user-defined request as the magnitude of translational
acceleration of Marker 21 with respect to Marker 11. Since the l marker is not specified, the derivatives are
taken in the inertial reference frame.
This statement defines the second component of a user-defined request as the magnitude of the translational
acceleration of Marker 21 with respect to Marker 11. Vector time derivatives taken in reference to Marker 32.
See other Acceleration available.
ACCX 5
ACCX
The ACCX function returns the x-component of the difference between the acceleration vector of marker i
Format
ACCX(i[,j][,k][,l])
Arguments

system.
system (GCS).
Extended Definition
Mathematically, ACCX is calculated as follows:
(l) 2 (l) 2
d d ˆ
ACCX ( i ,j ,k ,l ) = Ri – Rj ⋅ xk
dt2 dt 2
ˆ
where R i is the displacement of marker i in ground, R j is the displacement of marker j in ground, and x k
is the unit vector along the x-axis of marker k.
Examples
6 Adams Solver
ACCY 7
ACCY
The ACCY function returns the y-component of the difference between the acceleration vector of marker i
Format
ACCY(i[,j][,k][,l])
Arguments

system.
system (GCS).
Extended Definition
Mathematically, ACCY is calculated as follows:
(l) 2 (l) 2
d d ˆ
ACCY ( i ,j ,k ,l ) = Ri – Rj ⋅ yk
dt2 dt 2
ˆ
where R i is the displacement of marker i in ground, R j is the displacement of marker j in ground, and y k
is the unit vector along the y-axis of marker k.
Examples
8 Adams Solver
ACCZ 9
ACCZ
The ACCZ function returns the z-component of the difference between the acceleration vector of marker i
Format
ACCZ(i[,j][,k][,l])
Arguments

still specifying l, if you want the results to be calculated along the z-axis of the global coordinate
system.
l The reference frame in which the second-time derivative of the displacement vector is taken. Set l
system (GCS).
Extended Definition
Mathematically, ACCZ is calculated as follows:
(l) 2 (l) 2
d d ˆ
ACCZ ( i ,j ,k ,l ) = Ri – Rj ⋅ zk
dt2 dt 2
ˆ
where R i is the displacement of marker i in ground, R j is the displacement of marker j in ground, and z k
is the unit vector along the z-axis of marker k.
Examples
10 Adams Solver
ACOS 11
ACOS
The ACOS function calculates the arc cosine of an expression a. Expression a must evaluate to a value whose
absolute value is less than or equal to 1. The value returned by ACOS lies in the range [0, π ] (i.e., 0 <
ACOS(a) < π ).
Format
ACOS(a)
Arguments
Examples
VARIABLE/1, FU=ACOS((DX(21,11)*DX(31,41)+DY(21,11)*DY(31,41)
+ DZ(21,11)*DZ(31,41))/(DM(21,11)*DM(31,41))
This statement specifies a new user-defined state variable. Its value is the included angle of the lines joining
Markers 11 and 21 and Markers 41 and 31. The result is in radians.
12 Adams Solver
AINT
The AINT function returns the nearest integer whose magnitude is not larger than the integer value of the
expression a.
AINT(a) = 0 if ABS(a) < 1
AINT(a) = int(a) if ABS(a) > 1

then int(x) is equal to the nearest integer to x whose magnitude is not greater than the magnitude of x. Thus
int(-7.0) = -7, int(-4.8) = -4, and int(4.8) = 4.
Format
AINT(a)
Arguments
Caution: Note that AINT is not a differentiable function. Be careful when using this function in an
expression that defines a force or motion input to the system.
Examples
AINT(-6.5) = -6
AINT(4.6 ) = 4
AKISPL 13
AKISPL
The AKISPL function returns the iord derivative of the interpolated value of SPLINE/id at X=x and Z=z.
Format
AKISPL (x, z, id)
or
AKISPL (x,0,id [,iord])
Arguments
x A real variable that specifies the independent variable value along the x-axis of the AKISPL.
z A real variable that specifies the second independent variable value along the z-axis of the
surface being interpolated. Specify z = 0 if the SPLINE statement defines only one curve.
Adams Solver dataset.
iord An integer variable that specifies the order of the derivative to be taken at the interpolated point.
iord may not be specified when interpolating on a surface (for example, when z ≠ 0 ).
Default: 0
Range: 0 < iord < 2
Extended Definition
The AKISPL function uses the Akima method of interpolation to create a spline function across a set of data
points. The data points to be interpolated are defined by a SPLINE statement in the Adams Solver dataset.
The SPLINE that you define in the dataset may represent a curve (x-y points) or a surface (x-y-z points).
Interpolation in the y direction is cubic, and interpolation in the z direction is linear. To interpolate the values
specified in a curve, set z = 0.
AKISPL is very fast, since it uses local methods. It always produces good results for the value of the function
being approximated. AKISPL returns good estimates for the first derivative of the approximated function
when the data points are evenly spaced. In instances where the data points are unevenly spaced, the estimate
of the first derivative may be in error. In all cases, the second derivative of the function being approximated is
unreliable.
For more information on the Akima method of interpolation, see the references listed in Additional Publications.
14 Adams Solver
Tip: If you want to force a particular region of a spline function to be linear, you should know that
four consecutive points on a straight line will yield a linear section in the region between the
central two points, and, similarly, four consecutive points on a straight line at the end of a
spline will yield a linear fit from the second point onward.
Examples
, FUNCTION=AKISPL(TIME, 0, 1, 1)
This SFORCE statement defines a translational force that acts between Markers 409 and 109. The SPLINE
statement provides the discrete data used to generate the interpolation function using the Akima spline. Since
this SPLINE statement defines only one curve, the value of z is defined to be 0. AKISPL returns the first
derivative of the spline at the interpolated point since iord = 1.
See other Interpolation available.
ANINT 15
ANINT
The ANINT function calculates the nearest integer to a.
ANINT(a) = int(a + .5) if a > 0
ANINT(a) = int(a - .5) if a < 0
then int(x) is equal to the nearest integer to x whose magnitude is not greater than the magnitude of x.Thus:
int(-7.0) = -7, int(-4.8) = -4, and int(4.8) = 4.
Format
ANINT(a)
Arguments
Examples
ANINT(-4.6) = -5
ANINT(4.6) = 5
16 Adams Solver
ARYVAL
The ARYVAL function returns component comp of ARRAY/id. Depending on the definition of ARRAY/id,
this may be a constant that you defined in the Adams Solver (FORTRAN) dataset, an input to an LSE, GSE,
or TFSISO, a state variable defined by an LSE, GSE, or TFSISO, or an output from an LSE, GSE, or
TFSISO.
Format
ARYVAL (id, comp)
Arguments
id The identifier of the array whose data is being requested.

comp An integer that specifies the component of the array to be returned.
Examples
ARRAY/17, NUM=11.465,2.321
SFORCE/19, ROT, I=23, J=11
, FUNCTION=-ARYVAL(17,1)*(AZ(23,11)-ARYVAL(17,2))
This example illustrates how a value defined in an ARRAY statement can be accessed using the ARYVAL
function.
LSE/1, X=1, U=2, Y=3, A=11, B=12, C=13, D=14
This statement defines a set of linear state equations. The A, B, C, and D matrices for this LSE are defined
by matrices 11-14.
SFORCE/6, ROT, I=23, J=11, FUNCTION=ARYVAL(3,2)
The second output of the LSE is used to define a torque acting on the system.
See other System element available.
ASIN 17
ASIN
The ASIN function computes the arc sine of an expression a. ASIN is defined only when the absolute value
of a is less than or equal to 1. The range of ASIN is [- π /2, π /2] (that is, - π /2 < ASIN(a) < π /2).
Format
ASIN(a)
Arguments
Examples
DIFF/1, IC=1.05, FUNCTION=ASIN(DX(21,11)/DM(21,11))
This statement defines a user-specified differential equation. The initial value of the state variable is 1.05. The
time derivative of the state variable is the expression:
ASIN(DX(21,11)/DM(21,11))
18 Adams Solver
ATAN
The ATAN function returns the arc tangent of an expression a. The range of ATAN is [- π /2, π /2] (that is,
- π /2 < ATAN(a)< π /2).
Format
ATAN(a)
Arguments
Examples
SFORCE/1, ROTATIONAL, I=21, J=11
, FUNCTION=-10*ATAN(DY(42,33)/DX(42,33))
This SFORCE statement defines a torque acting between Markers 21 and 11. The value of the torque is the
spring constant (10) multiplied by the angle between the line joining Markers 33 and 42 and the global x-
axis as shown in the figure below.
Example Illustrating the Use of the ATAN Function

ATAN2 19
ATAN2
The ATAN2 function expression returns the arc tangent of the expression a1/a2. a1 and a2 themselves may
be expressions.
- π < ATAN2(a1,a2) < π

ATAN2(a1,a2) > 0 if a1 > 0
ATAN2(a1,a2) = 0 if a1 = 0, a2 > 0
ATAN2(a1,a2) = π if a1 = 0, a2 < 0
ATAN2(a1,a2) < 0 if a1 < 0
ABS(ATAN2(a1,a2))= π /2 if a2 = 0
ATAN2(a1,a2) undefined if a1 = 0, and a2 = 0
Format
ATAN2(a1,a2)
Arguments

Examples
VARIABLE/1,
, FUNCTION=ATAN2(DY(21,31,41), DX(21,31,41))
This VARIABLE statement defines an algebraically-determined, user-defined state variable in Adams Solver
(FORTRAN). Its value is specified by the expression containing ATAN2.
20 Adams Solver
AX
The AX function returns the rotational displacement (in radians) of marker i about the x-axis of marker j,
and accounts for angle wrapping.
assume that rotations about the other two axes (y- and z-axes) of marker j are zero. Then, AX is the angle
between the two y-axes (or the two z-axes). AX is measured in a counter-clockwise sense from the y-axis of
marker J to the y-axis of marker I (see the figure below).
Measurement of AX
Format
AX(i[,j])
Arguments

j The marker whose coordinate system is used as a reference to calculate the rotations of marker i.
When j is not specified, Adams Solver (FORTRAN) defaults to the global coordinate system.
Extended Definition
Mathematically, AX is calculated as:
AX = ATAN2 ( – zˆ i • yˆ j, zˆ i • zˆ j )
where:
 yˆ j is the y-azis of marker j

AX 21
Tip: If you want to change the AX function so it does not account for angle wrapping, use the
(MOD(AX(2,1) + PI, 2 * PI) - PI
Caution: For large rotations (greater than 10 degrees) about the y-axis or z-axis on Marker j, the AX
function becomes increasingly non-physical. Moreover, AX is undefined when both arguments
by the y and z-axis of the j marker.
Examples
, FX=-20*AX(43,32)
The value of the force is -20 times the angle between the y axes of Markers 43 and 32. The angle is measured
in a counterclockwise sense from the y-axis of Marker 32 to the y-axis of Marker 43.
See other Displacement available.
22 Adams Solver
AY
The AY function returns the rotational displacement (in radians) of marker i about the y-axis of marker j, and
Marker j defaults to the global coordinate system if it is not specified. The values are computed as follows:
assume rotations about the other two axes (x-, z-axes) of marker j are zero. Then AY is the angle between the
two x-axes (or the two z-axes). AY is measured counter-clockwise from the z-axis of the J marker to the z-axis
of the I marker (see the figure below).
Measurement of AY
Format
AY(i[,j])
Arguments

Extended Defintion
Mathematically, AY is calculated as:
AY = ATAN2 ( zˆ i • xˆ j, zˆ i • zˆ j )
where:

AY 23
Tip: If you want to change the AY function so it does not account for angle wrapping, use the MOD
function. For example, use the function:
(MOD(AY(2,1)+PI,2*PI)-PI)
Caution: For large rotations (greater than 10 degrees) about the x-axis or z-axis of marker j, the AY
function becomes increasingly non-physical. Moreover, AY is undefined when both arguments
by the x and z-axis of the j marker.
Examples
, FUNCTION=-4*(AY(46,57)**2)
This SFORCE statement applies a moment about the common z-axes of Markers 23 and 34. The torque acts
on Marker 23; the reaction torque acts on Marker 34.
The value of the torque being applied is -4 times the square of the angle between the z axes of Markers 46
and 57. The angle is measured in a counterclockwise sense from the z-axis of Marker 57 to the z-axis of
Marker 46.
24 Adams Solver
AZ
The AZ function returns the rotational displacement (in radians) of marker i about the z-axis of marker j, and
assume that rotations about the other two axes (x-, y-axes) of marker j are zero. Then AZ is the angle between
the two x-axes (or the two y-axes). AZ is measured in a counterclockwise sense from the x-axis of the J
marker to the x-axis of the I marker (see the figure below).
Measurement of AZ
Format
AZ(i [,j ])
Arguments

Extended Definition
Mathematically, AZ is calculated as:
AZ = ATAN2 ( xˆ i • yˆ j, xˆ i • xˆ j )
where:
 xˆ i is the x-axis of marker i
 yˆ j is the y-axis of marker j

AZ 25
Tip: If you want to change the AZ function so it does not account for angle wrapping, use the
(MOD(AZ(.model_1.PART_1.MAR_2, .model_1.ground.MAR_1)+PI,2*PI)-PI)
Caution: For large rotations (greater than 10 degrees) about the x-axis or y-axis of marker j, the AZ
function becomes increasingly non-physical. Moreover, AZ is undefined when both arguments
to ATAN2 are zero. This occurs when the x-axis of marker i is orthogonal to the plane defined
by the x and y-axis of the j marker.
Examples
VTORQUE/1, I=21, JFLOAT=31, RM=41
, TX=-10*(AX(21,32)-10D)/
, TY=-15*(AY(21,32)-15D)/
, TZ=-30*(AZ(21,32)-25D)
This VTORQUE statement applies a moment at Marker 21. The reaction moment is at the floating Marker
31. The torques are expressed in the coordinate system of Marker 41.
26 Adams Solver
BEAM
The BEAM function returns component comp of a force due to BEAM/id as calculated in the coordinate
BEAM. If jflag is set to 1, the value returned is that acting on the J marker. rm may be specified as zero if the
results are desired in the global coordinate system.
Format
BEAM (id, jflag, comp, rm)
Arguments
id An integer specifying the identification number of the beam.

jflag An integer flag specifying the beam connectivity marker at which the forces and torques are
computed.

comp An integer value that specifies the component of the beam force to be returned.

Examples
REQUEST/1
, F2=BEAM(1001,0,2,0)/
, F3=BEAM(1001,0,3,0)/
, F4=BEAM(1001,0,4,0)
This REQUEST statement stores the x-, y-, and z-component of the forces in BEAM/1001 in columns 2, 3,
coordinate system.
See other Element-specific applied force available.
BISTOP 27
BISTOP
The BISTOP function models a gap element (see Figure 1).
Format
· ,x1, x2, k, e, cmax, d)
BISTOP (x, x
Arguments
x The distance variable you want to use to compute the force. For example, if you want to use the
x displacement of Marker 0201 with respect to 0301, then x is DX(0201,0301,0301).
x· The time derivative of x to BISTOP. For example, if x is DX(0201,0301,301) then is
VX(0201,0301,0301,0301).
x1 The lower bound of x. If x is less than x1 Adams Solver (FORTRAN) calculates a positive value
for the force. The value of x1 must be less than the value of x2.
x2 The upper bound of x. If x is greater than x2 Adams Solver (FORTRAN) calculates a negative
value for the force. The value of x2 must be greater than the value of x1.
k A non-negative value that specifies the stiffness of the boundary surface interaction.
e A positive value that specifies the exponent of the force deformation characteristic. For a
cmax A non-negative variable that specifies the maximum damping coefficient.
d A positive real variable that specifies the penetration at which the full damping coefficient is
applied.
Extended Definition
The BISTOP function models a gap element. Figure 1 below illustrates the BISTOP force. The gap element
consists of a slot which defines the domain of motion of a Part I located in the slot. As long as Part I is inside
the slot and has no interference with the ends of the slot, it is free to move without forces acting on it. When
Part I tries to move beyond the physical definition of the slot, impact forces representing contact are created
by the BISTOP function. The created force tends to move Part I back into the slot.
The BISTOP force has two components: A stiffness component dependent on the penetration of Part I into
the restricting Part J and a damping or viscous component that may be used to model energy loss.
Figure 1 Example of the BISTOP Function

28 Adams Solver
To prevent a discontinuity in the damping force at zero penetration, the damping coefficient is defined as 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. Even though the points of
contact between the floating part and the restricting part may change as the system moves, Adams Solver
(FORTRAN) always exerts the force between the I and the J markers.
Caution: When e is < 1, the defined force contains a slope discontinuity that may casue difficulty for the
integrator.
Examples
You may model a slider in a slot with a BISTOP function as depicted in Figure 1. Assume a translational joint
constrains the slider to move in a slot. The line of translation is along the colinear z-axes of the I and the J
markers, I belonging to the slider and J to the part containing the slot. You can use an SFORCE statement
together with the BISTOP function to restrict the movement of the slider in the slot and model the gap.
In Figure 1:
 x is the instantaneous distance between the I and the J markers.
 N is the distance between the J marker and the left end of the slot.
BISTOP 29
 M1 is the distance between the I marker and the left edge of the floating part.
 L is the length of the slot.
 M2 is the distance between the I marker and the right edge of the floating part.
into contact with the left end of the slot.
into contact with the right end of the slot.
Therefore, the parameters for BISTOP for this example are:
x = DZ(I,J,J) and x· = VZ(I,J,J,J)

x= N + M1 for the left end of the slot and
x = N + L - M2 for the right end of the slot or
x1 = N + M1, and
x2 = N + L - M2
Note that when:
 x1 < x < x2, there is no penetration and the force is zero (penetration p = 0).
 x < x1 penetration occurs at the end closer to the J marker and the force is > 0 (penetration p = x1 -
x).
 x > x2 penetration occurs at the end farther away from the J marker, and the force is < 0 (penetration
p = x - x2).
Also note that when p < d the instantaneous damping coefficient is a cubic step function of the penetration,
p; when p > d the instantaneous damping coefficient is cmax.
The BISTOP function for this example is:
BISTOP(DZ(I,J,J,J), VZ(I,J,J,J), x1, x2, k, e, cmax, d)
The values of k, e, cmax, and d depend on the materials used in the two parts and on the shapes of the parts
and are used to define the contact force. The BISTOP force can be mathematically expressed as follows:
 Max ( k∗  x 1 – x – STEP  x, x 1 – d, c max, x 1, 0 ∗ x', 0 )

e x < x1 
 
BISTOP =  0 x1 ≤ x ≤ x2 
 
 Min ( – k∗  x – x 2 e – STEP  x, x 2, 0, x 2 + d, c max ∗ x', 0 ) x > x2 
See other General available.
30 Adams Solver
BUSH
The BUSH function returns component comp of a force due to BUSHING/id as calculated in the coordinate
BUSHING. If jflag is set to 1, the value returned is that acting on the J marker. rm may be specified as zero
Format
BUSH (id, jflag, comp, rm)
Arguments
id An integer specifying the identification number of the bushing.

jflag An integer flag specifying the bushing connectivity marker at which the forces and torques are
computed.

comp An integer value that specifies the component of the bushing force to be returned.

Examples
REQUEST/1
, F2=BUSH(1001,0,2,0)/
, F3=BUSH(1001,0,3,0)/
, F4=BUSH(1001,0,4,0)
This REQUEST statement stores the x-, y-, and z-component of the forces in BUSH/1001 in columns 2, 3,
coordinate system.
CHEBY 31
CHEBY
The CHEBY function evaluates a Chebyshev polynomial at a user specified value x.
Format
CHEBY (x, x0, a0, a1,..., a30)
Arguments
x An expression that specifies the independent variable. For example, if the independent
x0 The phase shift in the Chebyshev polynomial.
a0, a1,..., a30 The coefficients for the Chebyshev polynomial. A maximum of thirty-one coefficients
may be specified.
Extended Definition
The CHEBY function evaluates a Chebyshev polynomial at a user specified value x. x0, a0, a1,..., a30 are
parameters used to define the constants for the Chebyshev polynomial. The Chebyshev polynomial is defined
as:
C(x) = Σ aj Tj (x-x0)
where the functions Tj are recursively defined as:
Tj (x-x0) = 2 * (x-x0) * Tj-1 (x-x0) - Tj-2 (x-x0)
with T0 (x-x0) = 1, and T1 (x-x0) =x-x0.
The index “j” has a range from zero to “n”, where “n” is the number of terms in the series.
Note the following:
T2 (x-x0) = 2 * (x-x0)2 - 1
T3 (x-x0) = 4 * (x-x0)3 - 3 * (x-x0)
Examples
,FUNCTION = IF (TIME-2:CHEBY(TIME, 1, 1, 0, -1), 0, 0)
This MOTION statement defines a motion using a quadratic Chebyshev polynomial and the system variable
TIME. The arithmetic IF ensures that the function remains zero after 2 time units. When time is less than 2
time units, Adams Solver (FORTRAN) evaluates a Chebyshev polynomial to determine the motion. The
polynomial defined in the above example is:
Cheby = 1 + 0 * (time-1) - 1 * [2 (time-1)2 - 1]
= 2*time2 - 4*time
32 Adams Solver
CONTACT
The CONTACT function returns the component comp of the force in CONTACT/id in the coordinate
system of marker rm. If jflag is set to zero, Adams Solver (FORTRAN) returns the value of the force/torque
that acts on the I marker of CONTACT. If jflag is set to 1, Adams Solver (FORTRAN) returns the value that
acts on the J marker. To obtain results in the global coordinate system, you can specify rm as zero.
Format
CONTACT (id, jflag, comp, rm)
Arguments
id An integer specifying the identification number of the CONTACT.

jflag An integer flag specifying the CONTACT connectivity marker at which the forces and torques
are computed.

comp An integer value that specifies the component of the CONTACT to be returned:
 1 - Magnitude of the force applied by all incidents of contact ID

 2 - x-component of the force applied by all incidents of contact ID
 3 - y-component of the force applied by all incidents of contact ID
 4 - z-component of the force applied by all incidents of contact ID
 5 - Magnitude of the torque applied by all incidents of contact ID
 6 - x-component of the torque applied by all incidents of contact ID
 7 - y-component of the torque applied by all incidents of contact ID
 8 - z-component of the torque applied by all incidents of contact ID
Examples
REQUEST/1
, F2= CONTACT(11,0,2,0)/
, F3= CONTACT(11,0,3,0)/
, F4= CONTACT(11,0,4,0)/
, F6= CONTACT(11,0,6,0)/
, F7= CONTACT(11,0,7,0)/
, F8= CONTACT(11,0,8,0)
CONTACT/11. Because rm is specified as zero, all vectors are expressed in the global coordinate system.
COS 33
COS
The COS function returns the cosine of an expression a.
Format
COS(a)
Arguments
Examples
MOTION/2060, JOINT=2060, ROTATION,
, FUNCTION=20D+COS(2*PI*TIME)
This MOTION statement defines a rotational motion acting on JOINT/2060. The rotational degree of
freedom is specified to be 20D+COS(2*PI*TIME).
34 Adams Solver
COSH
The COSH function computes the hyperbolic cosine of an expression a. COSH(a) = (ea + e-a) / 2.0
Format
COSH(a)
Arguments
Examples
REQUEST/36,
, F2=COSH(DZ(21,11,11))
This REQUEST statement returns the hyperbolic cosine of the z-component of the displacement of Marker
21 with respect to Marker 11 in its second column. The result is computed in the coordinate system of
Marker 11.
CUBSPL 35
CUBSPL
The CUBSPL function returns the interpolated value of SPLINE/id at X=x and Z=z or returns the iord
derivative at the interpolated value of SPLINE/id at X=x, Z=0.
Format
CUBSPL (x, z, id)
or
CUBSPL (x, 0, id [,iord])
Arguments
x A real variable that specifies the independent variable value along the x-axis of the CUBSPL.
z A real variable that specifies the second independent variable value along the z-axis of the surface
being interpolated. If the SPLINE statement defines only one curve, Adams Solver (FORTRAN)
ignores this variable.
id An integer variable that specifies the identifier of a CUBSPL statement.
iord An optional integer that specifies the order of the derivative at the interpolate value to be
returned by CUBSPL.
Range: 0 < iord < 2
Extended Definition
The CUBSPL function uses the standard cubic method of interpolation to create a spline function across a
set of data points. The data points are defined in the SPLINE statement in Adams Solver (FORTRAN) data
deck. The SPLINE that you define in the Adams Solver dataset may represent a curve (x-y points) or a surface
(x-y-z points). Interpolation in the y direction is cubic and interpolation in the z direction is linear. To
interpolate the values specified in a curve, set z = 0.
CUBSPL, though not as fast as AKISPL, always produces good results for the value of the function being
approximated, its first and second derivatives. There is no requirement on the data points being evenly
spaced. This may be an important consideration when you use splines to define functions in Adams Solver
(FORTRAN). The solution process often requires estimates of derivatives of the functions being defined. The
smoother a derivative is, the easier it is for the solution process to converge.
If the spline data contains sudden changes in value, the CUBSPL function gives more oscillatory results for
the curve or surface than are given by the AKISPL function.
For more information on the cubic method of interpolation, see the references listed in Additional Publications.
36 Adams Solver
Examples
SPLINE/1,
, X= -3, -2, -1, 0, 1, 2, 3
, Y= -67.4, -48.6, -33.7, 4.8, 24.12, 37.6, 48.4
SFORCE/1, I=409, J=109, TRANSLATION,
, FUNCTION=CUBSPL(TIME, 0, 1)
This SFORCE statement defines the translational force acting between Markers 409 and 109. The SPLINE
statement provides the discrete data used to generate the interpolation function using the cubic spline. Since
the SPLINE statement defines only one curve, the value of z is defined to be 0.
CURVE 37
CURVE
The CURVE function evaluates a B-spline or user-written curve that is created with the CURVE statement.
Format
CURVE (alpha, iord, comp, id)
Arguments
alpha A real variable that identifies the value of the independent parameter, , at which the CURVE
function evaluates the curve. If the curve is a B-spline computed by the CURVE statement, alpha
must be in the domain -1 < < 1. If the curve is computed by a CURSUB, alpha must be in the
domain MINPAR < < MAXPAR (these are specified in the CURVE statement).
iord An integer variable that specifies the order of the derivative the CURVE function returns. The legal
values are:
0 - returns the curve coordinate
1 - returns the first derivative
2 - return the second derivative
comp An integer variable that specifies the component that the CURVE function returns. The legal
values are:
1 - returns the x coordinate or derivative
2 - returns the y coordinate or derivative
3 - returns the z coordinate or derivative
Parameters iord and icomp together allow you to request any one of the following nine return
values:
iord icomp = 1 icomp = 2 icomp = 3
0 x( α) y( α) z(α)
x ( α -)
d------------- y ( α -)
d------------- d z ( α )-
-------------
1
dα dα dα
d2x( α ) d2y( α ) d2z( α )
2 ----------------- ----------------- -----------------
dα 2 dα 2 dα 2
id An integer variable that specifies the identifier of the CURVE statement.
Examples
, FX=CURVE(.4*TIME - 1, 0, 1, 8)/
, FY=CURVE(.4*TIME - 1, 0, 2, 8)/
, FZ=CURVE(.4*TIME - 1, 0, 3, 8)
38 Adams Solver
This example applies to a VFORCE acting between Markers 101 and 201. The CURVE statement defines
the force components as a function of alpha, which varies from -1.0 to 1.0. The term 4*TIME-1 computes
the instantaneous value of alpha from the simulation time.
CVCV 39
CVCV
The CVCV function returns component comp of a force or torque due to CVCV/id as calculated in the
coordinate system of marker rm. If jflag is set to zero, the value returned is the force/torque acting on the
IFLOAT marker of the CVCV. If jflag is set to one, the value returned is that acting on the JFLOAT marker.
rm may be specified as zero if the results are desired in the global coordinate system.
Format
CVCV (id, jflag, comp, rm)
Arguments
id An integer specifying the identification number of a curve_curve constraint.

jflag An integer flag specifying the curve_curve constraint marker at which the forces and torques
are computed.
0 = forces and moments at the IFLOAT marker

1 = forces and moment at the JFLOAT marker
comp An integer value that specifies the component of the curve_curve constraint to be returned.

coordinate system, set rm = 0
Examples
REQUEST/18,
, F2=CVCV(210,0,2,0)/
, F3=CVCV(210,0,3,0)/
, F4=CVCV(210,0,4,0)/
, F6=CVCV(210,0,6,0)/
, F7=CVCV(210,0,7,0)/
, F8=CVCV(210,0,8,0)
This REQUEST statement returns all three components of the forces and moments acting at the IFLOAT
marker of CVCV Joint 210.
See other Element-specific reaction force available.
40 Adams Solver
DIF
The DIF function returns the value of the state associated with DIFF/id.
Format
DIF(id)
Arguments
Examples
, FUNCTION= -20*(AZ(21,11)-10)**1.5
, -5*WZ(21,11,11)
SPRING/1.
DIF1 41
DIF1
The DIF1 function returns the value of the time derivative of the state variable associated with DIFF/id. In
instances where DIFF/id is used to define an implicit algebraic equation, DIF1 returns an approximation of
the time derivative obtained by numerical differencing.
Format
DIF1(id)
Arguments
Examples
, FUNCTION= -20*(AZ(21,11)-10)**1.5
, -5*WZ(21,11,11)
SPRING/1.
42 Adams Solver
DIM
The DIM function calculates the positive difference of the instantaneous values of two expressions a1 and a2.
DIM(a1,a2) = 0 if a1 < a2
DIM(a1,a2) =a1-a2 if a1 > a2
Format
DIM(a1,a2)
Arguments

Caution: DIM is a discontinuous function and must be used with caution.

DM 43
DM
The DM function returns the magnitude of the translational displacement vector from marker j to marker i.
Marker j defaults to the global coordinate system if it is not specified. DM is the distance between markers i
and j and, by definition, is always non-negative.
Format
DM(i[,j])
Arguments

j The marker whose origin is the reference point for the displacement calculation.
Extended Definition
Mathematically, DM is calculated as follows:
DM = [ Ri – Rj ] • [ Ri – Rj ]
where R i is the displacement of marker i in the global coordinate system and R j is the displacement of
marker j in the global coordinate system.
Examples
, FUNCTION=-30*(DM(21,11)-25)**1.72
This SFORCE statement defines a nonlinear spring whose free length is 25. The stiffness is 30 force units per
unit deformation. DM(21,11)-25 represent the deformation in the spring. 1.72 is the exponent to which the
deformation is raised.
44 Adams Solver
DTOR
The DTOR variable returns degrees to radians conversion factor (PI/180).
Format
DTOR
Examples
VARIABLE/1, FUNCTION=30*DTOR*TIME
This VARIABLE statement specifies a user-defined, algebraically-determined state variable whose value is 30
degrees*time. The state variable is stored in radians.
See other Simulation constants and variables available.
DX 45
DX
The DX function returns the x-component of the translational displacement vector from marker j to marker
specified. Similarly, marker k defaults to ground if it is not specified.
Format
DX(i[,j][,k])
Arguments

k The marker that is referenced to calculate the x-component of the displacement vector. Set k = 0 if
you want the results to be calculated along the x-axis of the global coordinate system.
Extended Definition
Mathematically, DX is calculated as follows:
DX = [ R i – R j ] ⋅ xˆ k
where:

Examples
VARIABLE/1, FUNCTION=DX(21,11,32)**2
square of the x-displacement of Marker 21 with respect to Marker 11 as computed in the coordinate system
of Marker 32.
46 Adams Solver
DY
The DY function returns the y-component of the translational displacement vector from marker j to marker
specified. Similarly, marker k defaults to the global coordinate system if it is not specified.
Format
DY(i[,j][,k])
Arguments

k The coordinates of the marker that are referenced to calculate coordinates the y-component of the
displacement vector is being calculated. Set k = 0 if you want the results to be calculated along the
y-axis of the global coordinate system.
Extended Definition
Mathematically, DY is calculated as follows:
DY = [ R i – R j ] ⋅ yˆ k
where:

Examples
VARIABLE/1, FUNCTION=DY(21,11,32)**2
square of the y-displacement of Marker 21 with respect to Marker 11 as computed in the coordinate system
of Marker 32.
DZ 47
DZ
The DZ function returns the z-component of the translational displacement vector from marker j to marker
specified. Similarly marker k defaults to the global coordinate system if it is not specified.
Format
DZ(i[,j][,k])
Arguments

k The marker in whose coordinates the z-component of the displacement vector is being calculated.
Set k = 0 if you want the results to be calculated along the z-axis of the global coordinate system.
Extended Definition
Mathematically, DZ is calculated as follows:
DZ = [ R i – R j ] ⋅ zˆ k
where:

Examples
VARIABLE/1, FUNCTION=DZ(21,11,32)**2
square of the z-displacement of Marker 21 with respect to Marker 11 as computed in the coordinate system
of Marker 32.
48 Adams Solver
EXP
The EXP function computes the value ea, where a is any expression.
Format
EXP(a)
Arguments

Examples
REQUEST/10, F2=EXP(WDTX(21,11,11,31))
In its second column, REQUEST/10 stores the value:
eWDTX(21,11,11,31)
where WDTX (21,11,11,31) is the x-component of the accelerations of Marker 21 with respect to Marker
11 as expressed in the coordinate system of Marker 11. The time derivative is taken in the reference frame of
Marker 31.
FIELD 49
FIELD
The FIELD function returns component comp of a force due to FIELD/id as calculated in the coordinate
system of marker rm. If jflag is set to zero, the value that is returned is the force/torque acting on the I marker
of the FIELD. If jflag is set to 1, the value that is returned is the value acting on the J marker. For results that
are in the global coordinate system, you can specify rm as zero.
Format
FIELD (id, jflag, comp, rm)
Arguments
id An integer specifying the identification number of the FIELD.

jflag An integer flag specifying the FIELD connectivity marker at which the forces and torques are
computed.

comp An integer value that specifies the component of the FIELD force to be returned.

Examples
REQUEST/1
, F2=FIELD(1001,0,2,0)/
, F3=FIELD(1001,0,3,0)/
, F4=FIELD(1001,0,4,0)
This REQUEST statement stores the x-, y-, and z-component of the forces in FIELD/1001 in columns 2, 3,
and 4, respectively. Adams Solver (FORTRAN) calculates the forces at the I marker, and computes results in
the global coordinate system.
50 Adams Solver
FM
The FM function returns the magnitude of the net translational force acting at marker i. All force and
constraint elements between markers i and j are included in the calculation of the force, unless a force is an
action-only type. To return the magnitude of the action-only forces acting at marker i, you should omit the
specification of marker j or specify it to be zero.
Format
FM(i[,j])
Arguments
calculated.
j A second integer that specifies a marker identifier. All forces acting between the [i,j] pair are included
in the calculation. Set j = 0 or do not specify it if you are interested in action-only forces.
Examples
VARIABLE/1, FUNCTION=FM(23)
of all action-only forces acting at Marker 23.
VARIABLE/1, FUNCTION=FM(23,11)
of all the applied and constraint forces at Marker 23 and acting between Markers 23 and 11.
See other Generic force available.
FORCOS 51
FORCOS
The FORCOS function evaluates a Fourier Cosine series at a user-specified value x. The x0, a0, a1,...,a30 are
parameters used to define the constants for the Fourier Cosine series.
Format
FORCOS (x, x0, w, a0, a1,...,a30)
Arguments
x0 A real variable that specifies a shift in the Fourier Cosine series.
w A real variable that specifies the fundamental frequency of the series. Adams Solver
(FORTRAN) assumes w is in radians per unit of the independent variable unless you use a D
after the value.
a1,...,a30 The real variables that define as many as thirty-one coefficients for the Fourier Cosine series.
Extended Definition
The Fourier Cosine series is defined:
n
F ( x ) = ao +  aj × Tj ( x – xo )
j=1
T j ( x – x o ) = cos { j ⋅ ω ⋅ ( x – x o ) }
Examples
, FUNCTION=FORCOS(TIME, 0, 360D, 1, 2, 3, 4)
This MOTION statement defines a harmonic motion as a function of time. The motion has no shift, has a
fundamental frequency of 1 cycle (360D) per time unit, has a constant value of 1.0. The function defined is:
FORCOS = 1+2*COS(1*360D*TIME)
+3*COS(2*360D*TIME)
+4*COS(3*360D*TIME)
52 Adams Solver
Curve of a Harmonic Motion Defined by FORCOS

FORSIN 53
FORSIN
The FORSIN function evaluates a Fourier Sine series at a user specified value x. x0,a0,a1,...,a30 are parameters
used to define the constants for the Fourier Sine series.
Format
FORSIN (x, x0,w,a0,a1,...,a30)
Arguments
x A real variable that specifies the independent variable. For example, if the independent variable
in the function is time, x is the system variable TIME.
x0 A real variable that specifies a shift in the Fourier Sine series.
w A real variable that specifies the fundamental frequency of the series. Adams Solver
(FORTRAN) assumes ω is in radians per unit of the independent variable unless you use a
D after the value.
a1,...,a30 The real variables that define as many as thirty-one coefficients for the Fourier Sine series.
Extended Definition
The Fourier Sine series is defined:
n
F ( x ) = a0 +  a j∗ T j ( x – x 0 )
j=1
where the funtions Tj are defined as:
Tj (x-x0) = sin {j* ω *(x-x0)}

Examples
, FUNCTION=FORSIN(TIME,-0.25, PI, 0, 1, 2, 3)
This MOTION statement defines a harmonic motion as a function of time. The motion has a -0.25 second
shift, a fundamental frequency of 0.5 cycle ( π radians or 180 degrees) per time unit, and no constant value.
The function defined is:
FORSIN = 0+SIN( π *(TIME+0.25))
+2*SIN(2 π *(TIME+0.25))
+3*SIN(3 π *(TIME+0.25))
54 Adams Solver

Curve of a Harmonic Motioned Defined by FORSIN

FRICTION 55
FRICTION
The FRICTION function returns force and other friction data from the FRICTION statement. You can use
this function in only REQUEST and SENSOR function expressions.
Format
FRICTION (id, index)
Arguments
id An integer variable specifying the identification of a FRICTION statement from which

output data is requested.
INDEX An integer variable specifying the output component index to be returned. See the table below
for a list of component indices.
Friction Index

1 FFX Friction force along the x-axis of the JOINT’s J marker
2 FFY Friction force along the y-axis of the JOINT’s J marker
3 FFZ Friction force along the z-axis of the JOINT’s J marker
4 FTX Friction torque about the x-axis of the JOINT’s J marker
5 FTY Friction torque about the y-axis of the JOINT’s J marker
6 FTZ Friction torque about the z-axis of the JOINT’s J marker
7 x Friction coefficient along the x-axis of the JOINT’s J marker
8 y Friction coefficient along the y-axis of the JOINT’s J marker
9 z Friction coefficient along the z-axis of the JOINT’s J marker
10 rx Friction coefficient about the x-axis of the JOINT’s J marker
11 ry Friction coefficient about the y-axis of the JOINT’s J marker
12 rz Friction coefficient about the z-axis of the JOINT’s J marker
13 1 Effective friction coefficient at static friction (returns zero if sliding)
14 Vx Joint velocity at sliding surfaces along the x-axis of the JOINT’s J marker
15 Vy Joint velocity at sliding surfaces along the y-axis of the JOINT’s J marker
16 Vz Joint velocity at sliding surfaces along z-axis of the JOINT’s J marker
17 Wx Joint angular velocity about the x-axis of the JOINT’s J marker
18 Wy Joint angular velocity about the y-axis of the JOINT’s J marker
19 Wz Joint angular velocity about the z-axis of the JOINT’s J marker
56 Adams Solver

20 CREEP_X Static friction creep along the x-axis of the JOINT’s J marker
21 CREEP_Y Static friction creep along the y-axis of the JOINT’s J marker
22 CREEP_Z Static friction creep along the z-axis of the JOINT’s J marker
23 CREEP_RX Static friction creep about the x-axis of the JOINT’s J marker
24 CREEP_RY Static friction creep about the y-axis of the JOINT’s J marker
25 CREEP_RZ Static friction creep about the z-axis of the JOINT’s J marker
26 BETA Stiction transition factor
Examples
Request/101

This REQUEST statement defines a user REQUEST that returns the friction forces associated with the
statement FRICTION/2. The second component of the user request contains the X component of the
friction-force vector resolved in the associated J marker coordinate system of the JOINT.
Caution: The FRICTION function is accessible only through the REQUEST and SENSOR function
expressions.
The FRICTION function evaluates to zero if the index corresponds to a force or velocity
which is not used by the corresponding friction model. For example, if FRICTION/2 from
above is applied on a translational joint, then FRICTION (2,1) would be zero because the
friction force is applied along the z axes of the joint.

FX 57
FX
The FX function returns the x-component of the net translational force acting at marker i, as computed in
included in the calculation of the force, unless a force is an action-only type force. To return the x-component
of the action-only forces acting at marker i, you should omit specification of marker j or specify it to be zero.
Note that you can not specify marker k and omit marker j. In this case, you should specify marker j to be zero.
Format
FX(i[,j][,k])
Arguments
calculated.
included in the calculation. Set j = 0 or do not specify it if you are interested in action-only forces.
Examples
VARIABLE/1, FUNCTION=FX(23,0,432)
A user-defined state variable is specified by this VARIABLE statement. Its value is FX(23,0,432). This is the
x-component of the sum of all the action-only forces acting at Marker 23 as computed in the coordinate
system of Marker 32.
58 Adams Solver
FXFREQ
The FXFREQ function returns the modal frequency in cycles per user-defined time for the current mode of
the current FLEX_BODY when used in function expressions defining the CRATIO argument of a
FLEX_BODY. (Learn more about FLEX_BODY). FXFREQ returns zero when used in other expressions.
Format
FXFREQ
Extended Definition
Adams Solver (FORTRAN) evaluates each function expression used to define CRATIO of a FLEX_BODY
separately for each active mode of the FLEX_BODY (each mode has a CRATIO value). FXFREQ returns
the modal frequency of the mode for which CRATIO is being evaluated.
Examples
FLEX_BODY/1,
, CRATIO = IF(FXFREQ-100:0.01,0.1,if(FXFREQ-1000:0.1,1.0,1.0))
For a model using units of seconds for time, this example recreates the default modal damping scheme using
nested IF function expressions.
FXMODE 59
FXMODE
The FXMODE function returns the mode number of the current mode of the current FLEX_BODY when
used in function expressions defining the CRATIO argument of a FLEX_BODY. FXMODE returns zero
when used in other expressions. (Learn more on FLEX_BODY.)
Format
FXMODE
Extended Definition
Adams Solver (FORTRAN) evaluates each function expression used to define CRATIO of a FLEX_BODY
separately for each active mode of the FLEX_BODY (each mode has a CRATIO value). FXMODE returns
the mode number of the mode for which CRATIO is being evaluated.
Examples
FLEX_BODY/1
, CRATIO = STEP(TIME, 0.1, 1.0, 1.2, STEP(FXMODE, 5.0, 0.02, 10, 0.2))
This example specifies modal damping that varies both with time and mode number, such that all modes have
100% critical damping until
time = 0.1, after which:
 Modal damping decreases smoothly to between 2% and 20% of modal damping at time = 1.2.
 Mode numbers 1 through 5 reach 2% modal damping.
 Mode numbers 6 through 9 reach modal damping values smoothly distributed between 2% and
20%.
 Mode numbers 10 and up reach 20% modal damping.
60 Adams Solver
FY
The FY function returns the y-component of the net translational force acting at marker i, as computed in
included in the calculation of the force, unless a force is an action-only type force. To return the y-component
Format
FY(i[,j][,k])
Arguments
calculated.
k An integer that specifies the identifier of a marker (coordinate system) in which the y-component of
Examples
, FUNCTION=-0.3*FY(677,866)
This SFORCE statement defines a translation, action-only force acting at Marker 132. The force is directed
along the z-axis of Marker 234. The value of the force is -0.3 times the y-component of the net force along
the global y-axis, acting at Marker 677. All forces acting between Markers 677 and 866 are included in this
calculation.
FZ 61
FZ
The FZ function returns the z-component of the net translational force acting at marker i, as computed in
included in the calculation of the force, unless a force is an action-only type force. To return the z-component
Format
FZ(i[,j][,k])
Arguments
calculated.
Examples
, FUNCTION=STEP5(FX(34), -1.5, -200, 1.5, 200)
This SFORCE statement defines a translational, action-only, nonlinear force. The force is directed along the
z-axis of Marker 11. The value of the force is a 5th order step function (see STEP5). The independent variable
for the STEP5 function is FZ(34), the net force acting along the global z-axis at Marker 34. Since no j marker
is specified, only action-only forces acting at Marker 34 are included in the calculation of FZ().
62 Adams Solver
GFORCE
The GFORCE function returns the component comp of the force in GFORCE/id in the coordinate system
of marker rm. If jflag is set to zero, Adams Solver (FORTRAN) returns the value of the force/torque that acts
on the I marker of GFORCE/id. If jflag is set to 1, Adams Solver (FORTRAN) returns the value that acts on
the J marker. To obtain results in the global coordinate system, you can specify rm as zero.
Format
GFORCE (id, jflag, comp, rm)
Arguments
id An integer specifying the identification number of the GFORCE.

jflag An integer flag specifying the GFORCE connectivity marker at which the forces and torques
are computed.

comp An integer value that specifies the component of the GFORCE to be returned.

Examples
GFORCE/1, I=516, J=34, RM=23
, FX=-0.3*GFORCE(1,0,4,23)/
, FY=0/
, FZ=IMPACT(DZ(516,0,23),VZ(516,0,23,23),4.6,1e5,1.5,10,0.01)
This GFORCE statement defines a force acting at Marker 516. The components of the force are defined
along the x-, y-, z-axes of Marker 23.
The x-component of the force is -0.3 times the z-component of the force.
The z-component of the force is defined as an impact force (see IMPACT ) that is a function of the displacement
and velocity of Marker 516, as seen by Marker 23.
HAVSIN 63
HAVSIN
The HAVSIN function defines a haversine function. It is used most often to represent a smooth transition
between two functions.
Format
HAVSIN (x, x0, h0, x1, h1)
Arguments

x0 A real variable that specifies the x value at which the haversine function begins.
x1 A real variable that specifies the x value at which the haversine function ends.
h0 The initial value of the haversine function.
h1 The final value of the haversine function.
Extended Definition
The HAVSIN function is used most often to represent a smooth transition between two functions (see the
figure below). As an example, a HAVSIN may be used to smoothly ramp up the motion in a joint from h0
to some constant value h1.
Haversine Function
The equation defining HAVSIN is:

a = (h0 + h1)/2
b = (h1 - h0)/2
c = (x - x0)/(x1 - x0)
64 Adams Solver
 ho x ≤ x0 
 
 π 
HAVSIN =  a + b∗ sin  c∗ π – --- x0 < x < x1 
 2
 
 h1 x ≥ x1 
 
Tip: The HAVSIN function behavior is similar to the STEP function. It has a discontinuous second
derivative and therefore is not recommended for use in displacement level motions.
Examples
, FUNCTION=HAVSIN(TIME, 1, 0, 2, 1)
This MOTION statement defines a smooth transition in velocity from time 1 to time 2. Note that the
motion is specified in velocity rather than displacement.
IF 65
IF
IF (expression 1: expression 2, expression 3, expression 4)
Adams Solver (FORTRAN) evaluates expression 1.
 If the value of expression 1 is less than zero, the arithmetic IF is evaluated using expression 2.
 If the value of expression 1 is zero, the arithmetic IF is evaluated using expression 3.
 If the value of expression 1 is greater than zero, the arithmetic IF is evaluated using expression 4.
Format
IF (test : lt, eq, gt)
Arguments
test Any valid function expression. Adams Solver (FORTRAN) evaluated the test expression to
determine which branch of the arithmetic IF, lt, eq, or gt will be selected.
lt Any valid function expression. If the value of the test expression is less than zero, Adams Solver
(FORTRAN) evaluates the lt expression and the IF function takes the value of lt. Otherwise,
the lt expression is not evaluated.
eq Any valid function expression. If the value of the test expression is equal to zero, Adams Solver
(FORTRAN) evaluates the eq expression and the IF function takes the value of eq. Otherwise,
the eq expression is not evaluated.
gt Any valid function expression. If the value of the test expression is equal to zero, Adams Solver
(FORTRAN) evaluates the gt expression and the IF function takes the value of gt. Otherwise,
the gt expression is not evaluated.
Caution: When using an arithmetic IF function, ensure that the resulting function is continuous. If the
function is discontinuous, Adams Solver (FORTRAN) may fail to find a solution when it
encounters the discontinuity. Even the greater reliability can be achieved if continuity of the
first derivative can be ensured.
Much greater care is required when using an arithmetic IF function to define a MOTION
element. In this case, a continuous second derivative is also required. The use of arithmetic IF
functions to define MOTION is best avoided.
Examples
SFORCE/1, I=20, J=31,
, FUNCTION=-6*IF(VR(10,31): 0, 0, VR(10,31)**3)
66 Adams Solver
This function is interpreted as follows:

 If the radial velocity (see VR) between Markers 20 and 31 is less than or equal to zero, the value of
SFORCE/1 is zero.
 If the radial velocity between Markers 10 and 31 is greater than zero, the value of SFORCE/1 is -
6*VR(10,31)**3.
IMPACT 67
IMPACT
IThe IMPACT function models collisions.
Format
IMPACT (x, x· , x1, k, e, cmax, d)
Arguments
x An expression that specifies a distance variable used to compute the IMPACT function. For
example, if you use the x displacement of Marker 0201 with respect to Marker 0301, then x is
DX(0201,0301,0301). See DX.
x· An expression that specifies the time derivative of x to IMPACT. For example, if x is
DX(0201,0301), then x· is VX(0201,0301,0,0301).
x1 A positive real variable that specifies the free length of x. If x is less than x1, then Adams Solver
(FORTRAN) calculates a positive value for the force. Otherwise, the force value is zero. You can
define x1 as a real number, function, or variable.
k A non-negative real variable that specifies the stiffness of the boundary surface interaction.
e A positive real variable that specifies the exponent of the force deformation characteristic. For a
cmax A non-negative real variable that specifies the maximum damping coefficient.
d A positive real variable that specifies the boundary penetration at which Adams Solver
(FORTRAN) applies full damping.
Extended Definition
The IMPACT function activates when the distance between the I and the J markers falls below a nominal
free length (x1), that is, when two parts collide. As long as the distance between the I and J markers is greater
than x1, the force is zero. An example of a system you can model with the IMPACT function is a ball falling
towards the ground. Figure 3 below shows the free length value x1 at which the IMPACT force turns on.
The force has two components, a spring or stiffness component and a damping or viscous component. The
stiffness component is proportional to k, and is a function of the penetration of the I marker within the free
length distance from the J marker. 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.
Figure 3 Example Illustrating the IMPACT Function

68 Adams Solver
The equation defining IMPACT is:
 Max ( 0, k  x 1 – x e – STEP  x, x 1 – d, c max, x 1, 0 ∗ x· ) x < x1 

IMPACT =  
 0 x ≥ x1 
Note that when:
 x > x1, no penetration occurs and the force is zero (penetration p = 0)
 x < x1, penetration occurs at the end closer to the J marker, and the force is > 0 (penetration p = x1 -
x).
Also note that when p < d, the instantaneous damping coefficient is a cubic step function of the penetration p.
When p > d, the instantaneous damping coefficient is cmax.
Adams Solver (FORTRAN) never returns a negative force for IMPACT. If the above expression is negative,
Adams Solver (FORTRAN) returns a value of zero.
Figure 4 below is a plot of damping coefficient versus penetration.

IMPACT 69
Tip: Define the exponent value as: e > 2.1 for the contact modeling fu. According to design studies
models run better using this exponent value in the IMPACT function.
Caution:  For maximum performance, define e > 1. When e is < 1, the defined force contains a
slope discontinuity that may cause difficulty for the integrator.
dg
F n = k*(g ( **e)+ Step(g,0,0,d max, C max )*
dt
Example:
k = 3800 N/mm
e = 2.0
70 Adams Solver
Examples
, FUNCTION=IMPACT(DZ(11,21,21),
, VZ(11,21,21,21),1.0, 100, 1.5, 25, 0.1)
This statement defines an impact force when a ball penetrates another object such as a table. The force is a
single-component force at Marker 11 and along the z-axis of Marker 21. DZ(11,21,21) defines the
instantaneous displacement of Marker 11 with respect to Marker 21 along the z-axis of Marker 21.
VZ(11,21,21,21) defines the instantaneous velocity.
The free length is 1; that is, the radius of the ball is 1 unit. The stiffness is 100, and the exponent of
deformation is 1.5, the maximum damping coefficient is 25. The penetration at which Adams Solver
(FORTRAN) applies full damping is 0.1.
VFORCE/1, I=27, JFLOAT=25, RM=26
, FX=0/
, FY=IMPACT(DY(4,1,1), VY(4,1,1), 1-AKISPL(DX(4,1,1),
, DZ(4,1,1),3),le7, 1.01, le4,.25)/
, FZ=0
This statement defines an impact force when a ball penetrates a surface defined by a spline. The force is a
translational force at Marker 27. The DY(4,1,1) defines the y-component of the instantaneous displacement
of Marker 4 with respect to Marker 1. The VY(4,1,1) defines the y-component of the instantaneous velocity.
The free length is defined using spline 3, which represents the surface.
The independent variables in the spline are defined using the x-component and z-component of the
instantaneous displacement of Marker 4 with respect to Marker 1, DX(4,1,1) and DZ(4,1,1), respectively.
The stiffness is le7, the exponent of deformation is 1.01, the maximum damping coefficient is le4, and the
penetration at which Adams Solver (FORTRAN) applies full damping is 0.25.
INCANG 71
INCANG
The INCANG function computes the included angle between the line defined by markers i and j, and the
line defined by markers j and k. The three markers can be on separate parts.
Note: During the simulation, the first non-zero value is always positive.
Format
INCANG (i, j, k)
Arguments
i A marker on the first line.

j A marker on the first line.
k A marker on the second line.
Examples
Variable/1, Fun=INCANG(3,2,4)*RTOD/
The variable computes the angle between the line segments that markers 2 and 3, and markers 2 and 4, define.
72 Adams Solver
INTERP
IThe INTERP function returns the iord derivative of the interpolated value of SPLINE/id at time=x. The
INTERP function supports time-series splines, which are splines that include a FILE argument that specifies
a time history file of type DAC or RPC III.
Format
INTERP (x, method, id [,iord])
Arguments
x A real variable that specifies the value of time, the independent variable along the x-axis of the
time series spline that is being interpolated.
method An integer variable that specifies the method of interpolation, either linear or cubic
interpolation.
Range: method = 1 (linear interpolation)
method = 3 (cubic interpolation)

Adams Solver dataset. The SPLINE id must reference time series data from a DAC or RPC III
file.
iord An integer variable specifying the order of the derivative that Adams Solver takes at the
interpolated point, and then returns through INTERP.
Default: 0 (take no derivative)

Range: 0 < iord < 2
Extended Definition
The INTERP function uses linear or cubic interpolation to create a function across a set of data points. The
data points are defined in a SPLINE statement in the Adams Solver data deck. The SPLINE statement with
the FILE argument that you define in the Adams Solver dataset must reference a time series file of type DAC
or RPC III. For more information on these file types, see Adams Durability.
In general, the INTERP function with linear interpolation will not be a smooth function because, in almost
all cases, the function will be discontinuous in the first derivative. Therefore, the estimate of the first
derivative may be erroneous even though, by definition, the data points of a DAC or RPC time history file
are evenly spaced. In all cases, the second derivative of the function being approximated is unreliable with
linear interpolation.
On the other hand, with cubic interpolation, the INTERP function will be continuous to the second
derivative. Therefore, we recommend that you use cubic interpolation, especially if first or second derivatives
of the function will be evaluated.
INTERP 73
Examples
SPLINE/101
,FILE=test_data.rsp
,CHANNEL=9
,FUNCTION=INTERP(TIME,3,101)
The SFORCE statement defines a translational force that acts between Markers 409 and 109. The SPLINE
statement specifies that the discrete data used to interpolate the value of the SFORCE comes from
CHANNEL 9 of the RPC III file test_data.rsp.
The INTERP function references this spline, defines the independent variable to be simply, TIME, and
selects cubic as the method of interpolation.
74 Adams Solver
INVPSD
IThe INVPSD (Inverse Power Spectral Density) function regenerates a time signal from a power spectral
density description.
Format
INVPSD (x, id, fo, fi, nf, linlog, seed)
Arguments

id The id number of the spline containing the PSD versus frequency data.
f0 A real variable that specifies the lowest frequency to be regenerated.
f1 A real variable that specifies the highest frequency to be regenerated.
nf An integer that specifies the number of frequencies. This number is supposed to be larger than
1 and less than 200.
linlog An integer variable that acts as a flag indicating whether the PSD data points are interpolated
in the linear or logarithmic domain.
The legal values are:
 yes (0) - linear domain

 no (1) - logarithmic domain
seed A real variable that specifies a seed for a random number generator, used to calculate the phase
shifts. The seed is a real number that will be rounded to the nearest whole integer using the
NINT FORTRAN function. During a simulation, INVPSD can be called with up to a
maximum of 20 different integer seeds.
Extended Definition
Mathematically, INVPSD is calculated as follows:
nf
INVPSD =  ( Ai ⋅ sin ( 2πfi ⋅ x + ϕi ) )

i=1
The regenerated signal consists of a series of sinusoidal functions where the amplitudes, Ai, are determined
in such a way that the effective value for the PSD and the time signal are the same. The phase angle,
ϕ i ( 0 ≤ ϕ i ≤ 2π ) , is calculated by a pseudo-random number generator.
Using the same seed value will always result in the same set of phase angles.
INVPSD 75
Examples
For the power spectral density data shown in Figure 5, INVPSD(TIME, spline_1, 1, 10, 20, 0, 0) regenerates
the time signal shown in Figure 6.
Figure 5 PSD vs. Frequency in Log-Log Scale
Figure 6 Regenerated Time Signal

76 Adams Solver
JOINT
The JOINT function returns component comp of a force or torque due to JOINT/id as calculated in the
marker of the JOINT. If jflag is set to one, the value returned is that acting on the J marker. rm may be
Format
JOINT (id, jflag, comp, rm)
Arguments
id An integer specifying the identification number of the joint.

jflag An integer flag specifying the joint connectivity marker at which the forces and torques are
computed.
comp An integer value that specifies the component of the joint force to be returned.
Examples
, FUNCTION=-0.4*SIGN(1.0,WZ(46,23,23)*5.6*,
, (JOINT(1,0,1,23)-ABS(JOINT(1,0,4,23))))
This example illustrates how a simple dynamic friction force can be added to a revolute joint. JOINT/1 is the
revolute joint to which frictional effects are to be added. 0.4 is the coefficient of friction and 5.6 is the radius
of the sleeve defining the revolute joint. WZ(46,23,23) determines the direction of rotation and the negative
sign indicates that the frictional moment about the z-axis of Marker 23 opposes this motion.
JOINT(1,0,1,23) determines the magnitude of the reaction force at Marker 23. JOINT(1,0,4,23)
determines the component of the constraint force along the axis of the rotational of the joint.
JOINT(1,0,12)-ABS(JOINT(1,0,4,23)) defines the radial load in the revolute joint (i.e., the normal force).
JPRIM 77
JPRIM
JThe JPRIM function returns component comp of a force due to JPRIM/id as calculated in the coordinate
JPRIM. If jflag is set to one, the value returned is that acting on the J marker. rm may be specified as zero if
Format
JPRIM (id, jflag, comp, rm)
Arguments
id An integer specifying the identification number of the JPRIM.

jflag An integer flag specifying the JPRIM connectivity marker at which the forces and torques are
computed.

comp An integer value that specifies the component of the JPRIM force to be returned.

Examples
REQUEST/1
, F2=JPRIM(212,1,8,346)
In its second column, this REQUEST statement stores the z component of the torque acting at the J marker
of JPRIM 212. The torque component is calculated in the coordinate system of Marker 346.
78 Adams Solver
LOG
The LOG function returns the natural logarithm an expression a. If ex=a then LOG(a)=x. The LOG function
is defined only for positive values of a (that is, a > 0). It is undefined for all other values.
Format
LOG(a)
Arguments
Examples
DIFF/1, IC=3.6
, FUNCTION=LOG(1+VM(21,31,31))
MAX 79
MAX
The MAX function returns the maximum of two expressions a1 and a2.
MAX(a1,a2) = a1 if a1 > a2
MAX(a1,a2) = a2 if a2 > a1
Format
MAX(a1,a2)
Arguments

Caution: The MAX function is generally discontinuous. Use this function expression with care when
Examples
, FUNCTION=MAX(0,-3*(AZ(21,11)-25D))
Marker 11. The torque is defined to always be non-negative through the use of the MAX function. Thus, the
80 Adams Solver
MIN
The MIN function returns the minimum of two expressions a1 and a2.
MIN(a1,a2) = a1 if a1 < a2
MIN(a1,a2) = a2 if a2 < a1
Format
MIN(a1,a2)
Arguments

Caution: The MIN function is generally discontinuous. Use this function expression with care when
Examples
, FUNCTION=MIN(0,-3*(AZ(21,11)-25D))
Marker 11. The torque is defined to always be negative through the use of the MIN function. Thus, the
MOD 81
MOD
The MOD function returns the remainder when a1 is divided by a2.
MOD(a1,a2) = a1 - int(a1/a2) * a2
Format
MOD(a1,a2)
Arguments

a2 Any valid non-zero function expression.
Caution: The MOD function is generally discontinuous. Use this function expression with care when
Examples
MOD(45,16)=13
82 Adams Solver
MODE
The MODE function returns the current analysis mode. These are defined as:
1 = Kinematics
2 = Reserved
3 = Initial conditions
4 = Dynamics
5 = Statics
6 = Quasi-statics
7 = Linear analysis
Format
MODE
Caution: Use the MODE function with care if you use the STATICS argument on the SIMULATE
command to request a static or quasi-static simulation of a kinematic system, Adams Solver
(FORTRAN) performs a kinematic analysis and, consequently, returns a MODE analysis
constant of 1 (not 5 or 6).
Examples
, FUNCTION=IF(MODE-4:0,0,-4*(DM(21,11)-10.6))
This example defines a translational force that is active only during statics, quasi-static, and linear analysis
modes. For these analysis modes, the SFORCE acts as a simple spring. For all other analyses, the net force
applied by the SFORCE is zero.
MOTION 83
MOTION
The MOTION function returns component comp of a force due to MOTION/id as calculated in the
marker of the MOTION. If jflag is set to one, the value returned is that acting on the J marker. rm may be
Format
MOTION (id, jflag, comp, rm)
Arguments
id An integer specifying the identification number of the motion.

jflag An integer flag specifying the motion connectivity marker at which the forces and torques are
computed.

comp An integer value that specifies the component of the motion force to be returned.

Examples
MOTION/1, ROTATIONAL, JOINT=34, FUNCTION=TIME**2
DIFF/1, IC=0
, FUNCTION=WZ(21,11)*MOTION(1,0,8,11)
This DIFF statement defines a user defined state. Its derivative is the instantaneous power required to effect
the displacement specified by MOTION/1. Therefore, the value of the state is the total work done by
MOTION/1 during a simulation.
84 Adams Solver
NFORCE
The NFORCE function returns component comp of a force due to NFORCE/id acting at the marker,
at_marker, as calculated in the coordinate system of marker rm. The rm marker may be specified as zero if
the results are desired in the global coordinate system. The marker must be one of the I or J markers to which
NFORCE/id connects.
Format
NFORCE (id, at_marker, comp, rm)
Arguments
id An integer specifying the identification number of the NFORCE.

at_marker An integer marker identifier specifying the NFORCE connectivity marker at which the
forces and torques are computed.
comp An integer value that specifies the component of the NFORCE to be returned.

Cautions
Adams Solver (FORTRAN) Adams Solver (C++)

 The NFORCE function is  Unlike Adams Solver (FORTRAN), the NFORCE measure can appear
available only from in any function expression in the Adams Solver (C++) dataset.
REQUEST and SENSOR  Adams Solver (C++) does not have support for the NFORCE measure
statements. It is not from the SYSFNC utility subroutine. Instead, use the FX, FY, and FZ.
accessible from other measures. These can either be used to measure the sum of forces on a
statements. 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.
NFORCE 85

86 Adams Solver
ORIENT
The ORIENT function returns a scalar rotational value related to two Markers. The rotational value is
defined by specifying an orientation system and a specific component. The ORIENT function may be used
to compute Euler angles corresponding to rotation sequences other than the standard body-fixed 3-1-3 Euler
rotation sequence used by Adams Solver (FORTRAN). The exact meaning of the computed value depends
on the parameters supplied by the user.
Format
ORIENT(orientation_system, component, i [,j])
Arguments
orientation_system A value specifying the orientation system or convention. (See table below.)
component A value specifying the value to be computed. (See table below.)
i The first Marker.
j The second marker. When j is not specified, Adams Solver (FORTRAN) defaults
to the global coordinate system.
Orientation
ORIENT 87
Orientation
11 1, 2 or 3 First, second or third Euler angle of a body-fixed Standard Euler sequence used
3-1-3 Euler rotation sequence respectively. by Adams Solver
(FORTRAN). First angle is
PSI, second angle is THETA
and third angle is PHI.
13 1, 2 or 3 First, second or third Euler angle of a space-fixed
1-2-3 Euler rotation sequence
88 Adams Solver
Orientation
24 1, 2 or 3 First, second or third Euler angle of a space-fixed Not supported by Adams
3-2-3 Euler rotation sequence respectively. Solver (FORTRAN)
25 1, 2 or 3 AX(i, j), AY(i, j) or AZ(i, j) respectively.
26 1, 2 or 3 YAW(i, j), PITCH(i, j) or ROLL(i, j) respectively.
27 1, 2, 3, or 4 First, second, third or fourth Euler parameter
respectively.
28 1, 2, 3, or 4 First, second, third or fourth Rodriguez parameter Not supported by Adams
respectively. Solver (FORTRAN)
29 1, 2, 3, 4, 5, 6, Entry of the direction cosine matrix. The values
7, 8 or 9 are returned in row order, for example,
component 1 stands for entry a11, component 2
stands for entry a12, component 3 stands for entry
a13, component 4 stands for entry a2,1, and so
forth.
Caution: For large rotations (greater than 10 degrees) about the y-axis or z-axis on Marker j, the AX, AY
and AZ functions becomes increasingly non-physical. See documentation for AX, AY and AZ
functions.
Examples
, FX=-20*ORIENT(3, 2, 43, 32)
The value of the force is -20 times an angle between Markers 43 and 32. The angle is the second angle in a
body-fixed Euler 3-1-2 rotation sequence.
See other available Displacement functions.
PHI 89
PHI
The PHI function calculates the third angle (in radians) of a body-fixed-3-1-3 Euler rotation sequence
between markers i and j. Marker j defaults to the global coordinate system if it is not specified. See Figure 7
for a schematic description of the body-fixed-3-1-3 Euler rotation sequence.
Format
PHI(i[,j])
Arguments

Examples
REQUEST/1, F2=PHI(222,434)
This REQUEST statement output the phi angle between Markers 222 and 434 in its second column.
Figure 7 Body-fixed-3-1-3 Euler Angles

90 Adams Solver
The body-fixed-3-1-3 sequence is started by rotating

counterclockwise the initial system of axes, xyz, by
an angle Ψ about the z-axis. The resultant axes are
labeled ξηζ . (Notice that z coincides with ζ . )
In the second stage the intermediate axes, ξηζ , are

rotated counterclockwise about the ξ -axis by an
angle θ . The new resultant planes are labelled ξ '
η ' ζ '. The '- axis is at the intersection of the xy
and ξ ' η ' planes and is known as the line of nodes.
(Notice that ξ coincides with ξ '.)
In the final rotation, the ξ '- η '- z '- axes are rotated
counterclockwise by an angle φ about the ζ -axis to
produce the x' y' z' axes, which is the desired final
direction. (Notice that ζ coincides with ζ '.)
PI 91
PI
PI returns the ratio of the circumference of a circle to its diameter (3.14159...).
Format
PI
92 Adams Solver
PINVAL
The PINVAL function returns component comp of PINPUT/id.
Format
PINVAL (id, comp)
Arguments
id The identifier of the PINPUT whose data is being requested.

comp An integer that specifies the component of the PINPUT to be returned.
Examples
PINPUT/10, VARIABLES=21,22
, FUNCTION=-1.08*(PINVAL(10,2)-4.6)
PINVAL(10,2) is the second element in the VARIABLES list for PINPUT/10 (that is, VARIABLE/22).
PITCH 93
PITCH
Returns the negative value of the second angle of a body-fixed 3 2 1 yaw-pitch-roll rotation sequence between
marker i and marker j.
Note: Following automotive conventions, the PITCH function returns the negative value of the
second body-fixed 3 2 1 rotation sequence.
Format
PITCH(i[,j])
Arguments

Examples
REQUEST/2, F2=PITCH(143)
This REQUEST statement outputs the pitch angle (in radians) of Marker 143 relative to the global
coordinate system.
94 Adams Solver
POLY
The POLY function evaluates a standard polynomial at a user-specified value x.
Format
POLY (x, x0, a0, a1,..., a30)
Arguments
x0 A real variable that specifies a shift in the polynomial.
a0, a1,..., a30 The real variables that define as many as thirty-one coefficients for the polynomial series.
Extended Definition
The POLY function evaluates a standard polynomial at a user-specified value x. x0, a0, a1,..., a30 are
parameters used to define the constants for the polynomial. The standard polynomial is defined as:
n
P(x) =  aj ( x – x0 )j
j=0
= a 0 + a 1∗ ( x – x 0 ) + a 2∗ ( x – x 0 ) 2 + … + a n∗ ( x – x 0 ) n
The index j has a range from zero to n, where n is the number of terms in the series.
Examples
, FUNCTION=POLY(TIME, 0, 0, 0, 1)
This MOTION statement uses a quadratic polynomial function with respect to the system variable TIME
to define a motion. That expanded function is:
Poly = time2
, FUNCTION = IF(TIME-5: 0, 0, POLY(TIME, 5, 0, 10))
This MOTION statement uses an arithmetic IF in its function expression to switch between functions.
The expanded function is:
if (time > 5) then Poly=0
else Poly=10*time-5
POLY 95

, FUNCTION=-POLY(DM(10, 20), 10, 0, 25, 0, 0.75)
This SFORCE statement defines a force with a nonlinear force deformation characteristic. This relationship
is:
Poly=-25*[DM(10,20)-10]- 0.75*[DM(10,20)-10]3
where, DM(10,20) represents the magnitude of the displacement of Marker 10 with respect to Marker 20.
The free length of the spring is 10 units.
96 Adams Solver
POUVAL
The POUVAL function returns component comp of POUTPUT/id.
Format
POUVAL (id, comp)
Arguments
id The identifier of the POUTPUT whose data is being requested.

comp An integer that specifies the component of the POUTPUT to be returned.
Examples
POUTPUT/10, VARIABLES=21,22
, FUNCTION=-1.08*(POUVAL(10,2)-4.6)
POUVAL(10,2) is the second element in the VARIABLES list for POUTPUT/10 (that is, VARIABLE/22).
PSI 97
PSI
The PSI function expression calculates the first angle (in radians) of a body-fixed 3-1-3 Euler rotation
sequence between markers i and j. Marker j defaults to the global coordinate system if it is not specified. For
a schematic of the body-fixed-3-1-3 Euler angles, click here.
Format
PSI(i[,j])
Arguments

Examples
REQUEST/1, F2=PSI(222,434)
This REQUEST statement output the psi angle between Markers 222 and 434 in its second column.
98 Adams Solver
PTCV
The PTCV function returns component comp of a force due to PTCV/id as calculated in the coordinate
system of marker rm. If jflag is set to zero, the value returned is the force acting on the I marker of the PTCV.
If jflag is set to one, the value returned is that acting on the JFLOAT marker. rm may be specified as zero if
Format
PTCV (id, jflag, comp, rm)
Arguments
id An integer specifying the identification number of the point-to-curve constraint.

jflag An integer flag specifying the point-to-curve connectivity marker at which the forces and torques
are computed.

comp An integer value that specifies the component of the point-to-curve constraint to be returned.

Examples
REQUEST/1
, F2=PTCV(31,0,2,0)/
, F3=PTCV(31,0,3,0)/
, F4=PTCV(31,0,4,0)/
, F5=PTCV(31,0,5,0)/
, F6=PTCV(31,0,6,0)/
, F7=PTCV(31,0,7,0)/
, F8=PTCV(31,0,8,0)/
This REQUEST statement outputs the x-, y-, and z-components of the force and torque at the I marker of
PTCV/31. Since rm is specified as zero, all vectors are expressed in the global coordinate system.
ROLL 99
ROLL
The ROLL function calculates the third angle of a body-fixed 3 2 1 yaw-pitch-roll rotation sequence between
markers i and j. Marker j defaults to the global coordinate system if it is not specified. Note that roll is an
Euler angle.
Format
ROLL (i[,j])
Arguments

Examples
REQUEST/2, F2=ROLL(143)
This REQUEST statement outputs the roll angle (in radians) of Marker 143 relative to the global coordinate
system.
100 Adams Solver
RTOD
RTOD returns the radians to degrees conversion factor.
Format
RTOD
Examples
REQUEST/1, F2=ROLL(23,14)*RTOD
This REQUEST statement outputs the roll angle between Markers 23 and 14 in degrees.
SENVAL 101
SENVAL
The SENVAL function returns the last scored value from the function expression or user-written subroutine
associated with the EVALUATE argument on SENSOR/id. See the SENSOR statement for more information.
Format
SENVAL(id)
Arguments
id An integer specifying the identification number of the SENSOR.
Caution: If the SENSOR/id does not have the EVALUATE argument, SENVAL(id) returns zero.
Examples
VARIABLE/1, FUNCTION=SENVAL(100)
SENSOR/100, EQ, VALUE=0
, FUNCTION=AZ(22,11)-PI/2/
, EVALUATE=SENVAL(100) +1
This SENSOR statement counts the number of times function AZ(22,11) passes through /2. The
VARIABLE statement defines a variable equal to the count.
102 Adams Solver
SFORCE
The SFORCE function returns component comp of a force due to SFORCE/id as calculated in the
coordinate system of marker rm. If jflag is set to zero, the value returned is the force or torque acting on the
I marker of the SFORCE/id. If jflag is set to 1, the value returned is that which acts on the J marker. You can
specify rm as zero if you want the results to be returned in the global coordinate system.
Format
SFORCE (id, jflag, comp, rm)
Arguments
id An integer specifying the identification number of the SFORCE.

jflag An integer flag specifying the SFORCE connectivity marker at which the forces and torques are
computed.

comp An integer value that specifies the component of the SFORCE to be returned.

Examples
REQUEST/1
, F2=SFORCE(31,0,2,0)/
, F3=SFORCE(31,0,3,0)/
, F4=SFORCE(31,0,4,0)/
, F5=SFORCE(31,0,5,0)/
, F6=SFORCE(31,0,6,0)/
, F7=SFORCE(31,0,7,0)/
, F8=SFORCE(31,0,8,0)
SFORCE/31. Since rm is specified as zero, all vectors are expressed in the global coordinate system.
SHF 103
SHF
The SHF function evaluates a simple harmonic function. The following equation defines SHF:
SHF = a*sin( ω *(x-x0)-phi)+b
Format
SHF (x, x0, a, w, phi, b)
Arguments
x The independent variable in the function. It may be any valid expression. For example, if the
independent variable in the function is twice the current simulation time, x is the system variable
2*TIME.
x0 The offset in the independent variable x.
a The amplitude of the harmonic function.
ω The frequency of the harmonic function. Adams Solver assumes ω is in radians per unit of the
independent variable. Conversion to degrees per unit of the independent is achieved by
appending a D after the number specifying ω .
phi A phase shift in the harmonic function. Adams Solver assumes phi is in radians unless you use a
D after the value.
b The average value of displacement of the harmonic function.
Examples
, FUNCTION=SHF(TIME, 25D, PI, 360D, 0, 5)
This MOTION statement uses SHF to define the harmonic function:
SHF = 5+PI*sin(360D*(time-25D))
The motion has a shift of 25 degrees, has an amplitude of PI, has a frequency of 1 cycle (360D) per time unit,
has zero phase shift, and has an average value of displacement of 5 units.
104 Adams Solver
SIGN
The SIGN function transfers the sign of a2 to the magnitude of a1.
SIGN(a1,a2) = ABS(a1) if a2 > 0
SIGN(a1,a2) = -ABS(a1) if a2 < 0
Format
SIGN (a1,a2)
Arguments

Caution: The SIGN function is discontinuous. Use this function with care to avoid creating expressions
that are discontinuous.
Examples
VARIABLE/23, FUNCTION=10*SIGN(DM(24,33),VZ(24,33))
When VZ(24,33) >0, the value of VARIABLE/23 is +10*DM(24,33). When VZ(24,33) < 0, the value of
VARIABLE/23 is -10*DM(24,33).
SIN 105
SIN
The SIN function returns the sine of an expression a.
Format
SIN(a)
Arguments
Examples
, FUNCTION=SIN(10*TIME)
23 is defined to be SIN(10*TIME).
106 Adams Solver
SINH
The SINH function return the hyperbolic sine of an expression a.
SINH(a) = (ea - e-a) /2.0
Format
SINH(a)
Arguments
Examples
VARIABLE/1, FUNCTION=SINH(DX(21,32))
The value of VARIABLE/1 is the hyperbolic sine of the x-component of the displacement between Markers
21 and 32, as calculated in the global coordinate system.
SPDP 107
SPDP
The SPDP function returns the component comp of a force due to SPRINGDAMPER/id as calculated in
the coordinate system of marker rm. If jflag is set to zero, the value returned is the force/torque that acts on
the I marker of the SPRINGDAMPER. If jflag is set to 1, the value returned is the value that acts on the j
marker. To get results in the global coordinate system, you can specify rm as zero.
Format
SPDP (id, jflag, comp, rm)
Arguments
id An integer specifying the identification number of the SPDP.

jflag An integer flag specifying the SPDP connectivity marker at which the forces and torques are
computed.

comp An integer value that specifies the component of the SPDP force to be returned.

Examples
REQUEST/1
, F2=SPDP(31,0,2,0)/
, F3=SPDP(31,0,3,0)/
, F4=SPDP(31,0,4,0)/
, F5=SPDP(31,0,5,0)/
, F6=SPDP(31,0,6,0)/
, F7=SPDP(31,0,7,0)/
, F8=SPDP(31,0,8,0)
This REQUEST statement output the x-, y- and z-components of the force and torque at the I marker of
SPDP/31. Since rm is specified as zero, all vectors are expressed in the global coordinate system.
108 Adams Solver
SQRT
The SQRT function returns the square root of an expression a. The square root function is defined only for
non-negative values of the argument a.
Format
SQRT(a)
Arguments

Examples
VARIABLE/23,
, FUNCTION=SQRT (FX(23,11)**2+FY(23,11)**2)
A new state variable with a value equal to the square root of the sum of the squares of the global x- and y-
components of the net force acting between Markers 21 and 11.
STEP 109
STEP
The STEP function approximates the Heaviside step function with a cubic polynomial. It has continuous
first derivatives. Its second derivatives are discontinuous at x=x0 and x=x1.
Format
STEP (x, x0, h0, x1, h1)
Arguments
x The independent variable. It can be a function expression.

x0 A real variable that specifies the x value at which the STEP function begins.
x1 A real variable that specifies the x value at which the STEP function ends.
Extended Definition
The STEP function approximates the Heaviside step function with a cubic polynomial. The figure below
illustrates the STEP function.
Step Function
The equation defining the STEP function is:

110 Adams Solver
a = h1 – h0
Δ = ( x – x0 ) ⁄ ( x1 – x0 )
 h0 x ≤ x0 
 
STEP =  h 0 + a∗ Δ 2 ( 3 – 2Δ ) x0 < x < x1 
 
 h1 x ≥ x1 
Tip: HAVERSINE, STEP5, and TANH offer other approximations for the Heaviside step
function. These (except for HAVERSINE) have a higher degree of continuity and
differentiability, but may have larger derivatives.
The figure shown next compares the STEP, STEP5, HAVSIN, and TANH functions.
Comparisons of STEP, STEP5, HAVSIN, and TANH
The next figure shows the first derivatives of these four functions.
First Derivatives of STEP, STEP5, HAVSIN, and TANH
STEP 111
Examples
, FUNCTION=STEP(TIME, 1, 0, 2, 1)
This MOTION statement defines a smooth step function from time 1 to time 2 with a velocity from 0 to 1.
Note that the motion is specified at the velocity rather than the position level. This prevents the second-order
derivative to be invoked during acceleration computation, which is something that would happen if the
motion were defined as a displacement level motion.
112 Adams Solver
STEP5
The STEP5 function provides approximation to the Heaviside step function with a quintic polynomial. It
has continuous first and second derivatives. Its third derivative is discontinuous at x=x0 and x=x1.
Format
STEP5 (x, x0, h0, x1, h1)
Arguments

x0 A real variable that specifies the x value at which the STEP5 function begins.
x1 A real variable that specifies the x value at which the STEP5 function ends.
Extended Definition
The figure shown next illustrates the STEP5 function.
STEP5 Function
The equation defining the STEP5 function is:
α = h1 - h0
Δ = (x - x0)/(x1 - x0)
STEP5 113
 h0 x ≤ x0 
 
STEP5 =  h 0 + aΔ 3∗ [ 10 – 15Δ + 6Δ 2 ] x0 < x < x1 
 
 h1 x ≥ x1 
Examples
, FUNCTION=STEP5(TIME, 1, 0, 2, 1)
This MOTION statement defines a smooth step function from TIME=1 to TIME=2 with a displacement
from 0 to 1.
114 Adams Solver
SWEEP
The SWEEP function returns a constant amplitude sinusoidal function with linearly increasing
instantaneous frequency (linear chirp).
Format
SWEEP (x, a, x0, f0, x1, f1, dx)
Arguments

a The amplitude of the sinusoidal function.
x0 The value of the independent variable at which the SWEEP function begins.
f0 The initial instantaneous frequency (in Hz) of the sinusoidal function.
x1 The value of the independent variable value at which the SWEEP function ends
f1 The final instantaneous frequency (in Hz).
dx The interval in which the SWEEP function becomes fully active.
Note: Error message will be triggered if x 0 ≥ x1 .
Extended Definition
Mathematically, SWEEP is calculated as follows:
SWEEP 115
The SWEEP function is an implementation of a linear chirp function.

See details in section Mathematical background below.
Examples
The following example defines motion with a sinusoidal function with a rising frequency from 2 to 6Hz
during the time interval 0 to 5.
MOTION/1,JOINT=1
, FUNCTION=SWEEP(TIME, 1.0, 0.0, 2.0, 5.0, 6.0, 0.01)
116 Adams Solver
Figure 8 Example SWEEP function
Mathematical background
Given a waveform of type:
x ( t ) = sin ( ϕ ( t ) ) (1)
where t is time. The instantaneous frequency f(t) of this type of signal is defined as:
1 dϕ ( t )
f ( t ) = ------ ------------- (2)
2π dt
If function f(t) is a linear function, the waveform x(t) is called a linear chirp. The SWEEP function
implements a linear chirp as shown in Figure 9.
SWEEP 117
Figure 9 Linear chirp implemented in SWEEP function
For the case t 0 ≤ t ≤ t 1 we see that function f(t) takes the form:
f1 – f0
f ( t ) = f 0 + -------------- ( t – t 0 ) (3)
t1 – t0
Integrating Equation (2) we obtain:
t
ϕ ( t ) – ϕ ( t 0 ) = 2π  f ( t ) dt
t0
or
t
f1 – f0
ϕ ( t ) = 2π   f 0 + -------------- ( t – t 0 ) dt + ϕ ( t 0 )
t1 – t0
t0
Evaluating the integral we get:

2
 f1 – f0 ( t – t0 ) 
ϕ ( t ) = 2π ⋅  f 0 ( t – t 0 ) + -------------- -------------------  + ϕ ( t 0 )
 t1 – t0 2 
Rearranging this expression we obtain:
 ( f1 – f0 ) ⋅ ( t – 2 ⋅ t0 ) ( f1 – f0 ) ⋅ t0 ⋅ t0 
ϕ ( t ) = 2π ⋅   f 0 + ----------------------------------------------- t +  ------------------------------------  – 2π ⋅ f 0 t 0 + ϕ ( t 0 )
 2 ⋅ ( t1 – t0 ) 2 ⋅ ( t1 – t0 ) 
The last two constants terms can be arbitrarily dropped to obtain:

118 Adams Solver
 ( f1 – f0 ) ⋅ ( t – 2 ⋅ t0 ) ( f1 – f0 ) ⋅ t0 ⋅ t0 
ϕ ( t ) = 2π ⋅   f 0 + ----------------------------------------------- t +  ------------------------------------  (4)
 2 ⋅ ( t1 – t0 )   2 ⋅ ( t1 – t0 ) 
 
Notice that dropping the above constants, the time derivative of Equation (4) still matches Equation (3).
Using Equation (4) at times t0 and t1, the angular function ϕ ( t ) has these values:
ϕ ( t 0 ) = 2π ⋅ { ( f 0 )t 0 + ( 0 ) } (5)
and
ϕ ( t 1 ) = 2π ⋅ { ( f 1 )t 1 + ( 0.5 ⋅ ( f 0 – f 1 ) ( t 0 + t 1 ) ) } (6)
Finally, Equations (4), (5) and (6) are used to define functions h(x) and p(x) presented in the definition of the
SWEEP function above.
Notice the first argument to the SWEEP function is not limited to time.
For the case when t0 > 0 you may see a discontinuity in the value of ϕ ( t ) , hence you may want to set a non
zero value for dx (last argument of the SWEEP function) in order to ramp up the value of the angular function
starting from zero.
References
1. Chirp, https://en.wikipidia.org/wiki/Chirp
2. MATLAB, https://www.mathworks.com/help/signal/ref/chirp.html
See other available General functions.
TAN 119
TAN
The TAN function returns the tangent of an expression a.
Format
TAN(a)
Arguments

120 Adams Solver
TANH
The TANH function returns the hyperbolic tangent of an expression a.TANH(a) = (ea - e-a) / (ea + e-a)
Format
TANH(a)
Arguments
Extended Definition
The figure below illustrates the TANH function.
TANH Function
Examples
, FUNCTION=0.5(1+TANH(5*(TIME-1.5)))
This MOTION statement defines a smooth step function that transitions from a value of 0 to 1. The value
of the step function at time=1.5 is 0.5.
THETA 121
THETA
The THETA function calculates the second angle (in radians) of a body-two fixed 3-1-3 Euler rotation
sequence between markers i and j. Marker j defaults to the global coordinate system if it is not specified. View
a schematic of the body-fixed-3-1-3 Euler angles.
Format
THETA(i[,j])
Arguments

Examples
REQUEST/1, F2=THETA(222,434)
This REQUEST statement output the THETA angle between Markers 222 and 434 in its second column.
122 Adams Solver
TIME
The TIME variable returns the current simulation time.
Format
TIME
Examples
, FUNCTION=10*SIN(2*PI*TIME)
This SFORCE statement defines a translational force acting between the origins of Marker 21 and Marker
11. The value of the force is 10*SIN*(2*PI*TIME).
TM 123
TM
The TM function returns the magnitude of the net torque acting at marker i. All force and constraint
elements between markers i and j are included in the calculation of torque, unless it is an action-only type.
To return the torque magnitude of the action-only forces acting as marker i, you should omit specification of
marker j, or specify it to be zero.
Format
TM(i[j])
Arguments
be calculated.
j A second integer that specifies a marker identifier. All torques acting between the [i,j] pair are to be
included in the calculation. Set j = 0 or do not specify it if you are interested in action-only torques.
Examples
VARIABLE/31, FUNCTION=TM(32,44)
In this example a revolute joint and motion (through the joint) act between Marker 32 and 44. A new
algebraically determined state variable VARIABLE/31 is defined to have the magnitude of the net torque
between these two markers as its value.
The TM function returns the magnitude of the net torque acting at marker i. All force and constraint
elements between markers i and j are included in the calculation of torque, unless it is an action-only type.
To return the torque magnitude of the action-only forces acting as marker i, you should omit specification of
marker j, or specify it to be zero.
124 Adams Solver
TX
The TX function returns the x-component of the net torque acting at marker i, as computed in the coordinate
calculation of the torque, unless a force element is an action-only type force. To return the x-component of
the action-only torques acting at marker i, you should omit specification of marker j or specify it as zero. Note
that you can not specify marker k and omit marker j. In this case, you should specify marker j to be zero.
Format
TX(i[,j][,k])
Arguments
be calculated.
Examples
VARIABLE/31, FUNCTION=TX(32,44)
variable VARIABLE/31 is defined to have the x-component of the sum of all torques acting between markers
markers 32 and 44, their reaction torque will be included in the computation of TX().
TY 125
TY
The TY function returns the y-component of the net torque acting at marker i as computed in the coordinate
calculation of the torque, unless a force element is an action-only type force. To return the y-component of
Format
TY(i[,j][,k])
Arguments
be calculated.
k An integer that specifies the identifier of a marker (coordinate system) in which the y-component
Examples
VARIABLE/31, FUNCTION=TY(32,44)
variable VARIABLE/31 is defined to have the y-component of the sum of all torques acting between markers
markers 32 and 44, their reaction torque will be included in the computation of TY( ).
126 Adams Solver
TZ
The TZ function returns the z-component of the net torque acting at marker i as computed in the coordinate
calculation of the torque, unless a force element is an action-only type force. To return the z-component of
Format
TZ(i[,j][,k])
Arguments
be calculated.
the torque is to be returned. k defaults to the global coordinate system when it is not specified.
Examples
VARIABLE/31, FUNCTION=TZ(32,44)
In this example a revolute joint and motion (through the joint) act between Marker 32 and 44. A determined
state variable VARIABLE/31 is defined to have the z-component of the sum of all torques acting between
markers 32 and 44 as computed in the global coordinate system. Since joint 1 and motion 1 are defined
between markers 32 and 44, their reaction torque will be included in the computation of TZ().
VARVAL 127
VARVAL
The VARVAL function returns current value of VARIABLE/id.
Format
VARVAL (id)
Arguments
id The identifier of the VARIABLE whose data is being requested.
Examples
VARIABLE/10, FUNCTION=DX(21,32,43)
, FUNCTION=(VARVAL(10)-5)**2
In this example, VARIABLE/10 defines an algebraically determined user-specified state. SFORCE/20 is a
nonlinear translational spring whose force magnitude is a function of this variable.
128 Adams Solver
VFORCE
The VFORCE function returns the component comp of the force in VFORCE/id in the coordinate system
of marker rm. If jflag is set to zero, Adams Solver (FORTRAN) returns the value of force/torque that acts on
the I marker of VFORCE/id. If jflag is set to 1, Adams Solver (FORTRAN) returns the value that acts on the
J marker. To obtain results in the global coordinate system, you can specify rm as zero.
Format
VFORCE (id, jflag, comp, rm)
Arguments
id An integer specifying the identification number of the VFORCE.

jflag An integer flag specifying the VFORCE connectivity marker at which the forces and torques
are computed.

comp An integer value that specifies the component of the VFORCE that is returned.

Examples
,FX=-10*VX(236,168,168,168)/
,FY=-10*VY(236,168,168,168)/
,FZ=-10*VZ(236,168,168,168)
REQUEST/1
,F2=VFORCE(23,0,2,0)/s
This REQUEST statement contains the x-component of the force exerted by VFORCE/19 calculated in the
coordinate system of Marker 168.
VM 129
VM
The VM function calculates the magnitude of the first time derivative of the displacement vector of marker
i with respect to marker j. The vector time derivative is taken in the reference frame of marker l. Markers i
and j default to the global coordinate system if they are not specified.
Format
VM(i[,j][,l])
Arguments

l The reference frame in which the time derivative of the displacement vector is taken. Set l = 0 or
omit the argument if you want the time derivatives to be taken in the ground coordinate system
(GCS).
Extended Definition
Mathematically, VM is calculated as follows:
(l) 2 (l) 2 (l) 2 (l) 2

d d d d
VM ( i, j, l ) = Ri – Rj ⋅ Ri – Rj
dt2 dt2 dt2 dt2
where Ri is the displacement of marker i in ground and Rj is the displacement of marker j in ground.
Examples
DIFF/51, IC=-6.2, FUNCTION=VM(23,0,32)
A dynamically determined user state is defined by DIFF/51. The time derivative of the user-state is the
magnitude of the velocity of the origin of Marker 23 with respect to ground. The time derivative for the
velocity computation is taken in the reference frame of Marker 32.
VARIABLE/1, FUNCTION=VM(21,32,43)
This VARIABLE statement defines an algebraic, user-defined state whose instantaneous value is the
magnitude of the velocity vector between Markers 21 and 32, as seen by an observer at Marker 43.
See other Velocity available.
130 Adams Solver
VR
The VR function calculates the radial (separation) velocity of marker i with respect to marker j. The vector
time derivative is taken in the reference frame of marker l. Markers j and l default to the global coordinate
system if they are not specified.
Format
VR(i[,j][,l])
Arguments

j The marker with respect to which the velociy is being measured. Set j = 0, while still specifying l, if you
want j default to the global coordinate system.
l The reference frame in which the time derivative of the displacement vector is taken. Set l = 0 or omit
the argument if you want the time derivatives to be taken in the ground coordinate system (GCS).
Extended Definition
Mathematically, VR is calculated by projecting the velocity vector on a unit vector along the line of sight
between i and j, as follows:
(l) d (l) d
Ri – Rj ⋅ [ Ri – Rj ]
dt dt
VR ( i, j, l ) = -------------------------------------------------------------------- = VXYZ ⋅ UV ( DXYZ )
[ Ri – Rj ] ⋅ [ Ri – Rj ]
where:

As markers i and j separate from each other, VR is positive. VR is negative when markers i and j approach
each other.
Although the VR function accepts an l argument as the reference frame in which the time derivative is taken,
it is invariant of the coordinate system in which it is computed.
The VR function is actually the time derivative of the invariant DM function, which can be seen as follows:
DM ( i, j ) = [ Ri – Rj ] ⋅ [ Ri – Rj ]
VR 131
d-
---- d
R i – ----- R j ⋅ [ R i ⋅ R j ]
d- dt dt
---- DM ( i, j ) = --------------------------------------------------------- = VR ( i, j )
dt [ Ri – Rj ] ⋅ [ Ri – Rj ]
This is useful to know when using DM and VR together as the displacement and velocity terms in an
SFORCE. Please see the SFORCE statement for an example.
Examples
, FUNCTION=-10*VR(467,764)
! defines a translational damper with a damping constant of 10.
132 Adams Solver
VTORQ
The VTORQ function returns the component comp of force in VTORQUE/id in the coordinate system of
marker rm. If jflag is set to zero, Adams Solver (FORTRAN) returns the value of the torque that acts on the
I marker of VTORQUE/id. If jflag is set to 1, Adams Solver (FORTRAN) returns the value that acts on the
J marker. To obtain results in the global coordinate system, you can specify rm as zero.
Format
VTORQ (id, jflag, comp, rm)
Arguments
id An integer specifying the identification number of the VTORQ.

jflag An integer flag specifying the VTORQ connectivity marker at which the forces and torques
are computed.

comp An integer value that specifies the component of the VTORQ force to be returned.
1 = Magnitude of the force (which is zero for a VTORQUE)

2 = x component of the force (which is zero for a VTORQUE)
3 = y component of the force (which is zero for a VTORQUE)
4 = z component of the force (which is zero for a VTORQUE)
Set rm = 0 if you want the results returned in the global coordinate system.
Examples
VTORQUE/19, I=236, JFLOAT=169
,TX=-10*WX(236,168,168,168)/
,TY=-10*WY(236,168,168,168)/
,TZ=-10*WZ(236,168,168,168)
REQUEST/1
, F2=VTORQ(19,0,2,168)/
This REQUEST statement contains the x-component of the torque exerted by VTORQUE/19 calculated in
the coordinate system of Marker 168.
VX 133
VX
The VX function returns the x-component of the difference between the velocity vector of marker i and the
Format
VX(i[,j][,k][,l])
Arguments

specifying l, if you want the results to be calculated along the x-axis of the global coordinate system.
(GCS).
Extended Definition
Mathematically, VX is calculated as follows:
(l) (l)
d d
VX ( i, j, k, l ) = Ri – R j ⋅ xˆ k
dt dt
where:
 Ri is the displacement of marker i in ground.
 Rj is the displacement of marker j in ground.

(l)
d
dt
Examples
134 Adams Solver

,FX=-10*VX(236,168,168,168)/
,FY=-15*VY(236,168,168,168)/
,FZ=-20*VZ(236,168,168,168)
168.
VY 135
VY
The VY function returns the y-component of the difference between the velocity vector of marker i and the
Format
VY(i[,j][,k][,l])
Arguments

specifying l, if you want the results to be calculated along the y-axis of the global coordinate system.
(GCS).
Extended Defintion
Mathematically, VY is calculated as follows:
(l) (l)
d d
VY ( i, j, k, l ) = Ri – R j ⋅ yˆ k
dt dt
where:

(l)
d
dt
Examples
136 Adams Solver

,FX=-10*VX(236,168,168,168)/
,FY=-15*VY(236,168,168,168)/
,FZ=-20*VZ(236,168,168,168)
168.
VZ 137
VZ
The VZ function returns the z-component of the difference between the velocity vector of marker i and the
Format
VZ(i[,j][,k][,l])
Arguments

k The marker in whose coordinate system the velocity vector is expressed. Set k = 0, while still
specifying l, if you want the results to be calculated along the z-axis of the global coordinate system.
(GCS).
Extended Definition
Mathematically, VZ is calculated as follows:
(l) (l)
d d
VZ ( i, j, k, l ) = Ri – R j ⋅ zˆ k
dt dt
where:
 zˆ k is the unit vector along the y-axis of marker k.

(l)
d
dt
Examples
138 Adams Solver

,FX=-10*VX(236,168,168,168)/
,FY=-15*VY(236,168,168,168)/
,FZ=-20*VZ(236,168,168,168)
168.
WDTM 139
WDTM
The WDTM function returns the magnitude of the difference between the angular acceleration vector of
marker i in the reference frame of marker l and the angular acceleration of marker j in the reference frame of
marker l.
Format
WDTM(i[,j][,l])
Arguments

l, if you want j default to the global coordinate system.
l The reference frame in which the first time derivative of the angular velocity vector is taken. Set l =
0 if you want the time derivatives to be taken in the ground coordinate system (GCS).
Extended Definition
Mathematically, WDTM is calculated as follows:
(l) d (l) d (l) d (l) d

WDTM ( i, j, l ) = ωi – ωj ⋅ ωi – ωj
dt dt dt dt
where:
Examples
REQUEST/16
,F1=WDTM(1236,2169)/
,F2=WDTX(1236,2169,2169,2169)/
,F3=WDTY(1236,2169,2169,2169)/
,F4=WDTZ(1236,2169,2169,2169)
140 Adams Solver
In its first column REQUEST/16 contains the magnitude of the angular acceleration vector of Marker 1236
with respect to Marker 2169, as seen in the global coordinate system and measured in the ground coordinate
system (GCS).
WDTX 141
WDTX
The WDTX function returns the x-component of the difference between the angular acceleration vector of
frame of marker l, as computed in the coordinate system of marker k. Marker j defaults to global coordinate
system if it is not specified. Similarly, marker k and l default to global coordinate system if they are not
specified.
Format
WDTX(i[,j][,k][,l])
Arguments

system.
l The reference frame in which the first time derivative of the angular acceleration vector is taken.
Set l = 0 if you want the time derivatives to be taken in the ground coordinate system (GCS).
Extended Definition
Mathematically, WDTX is calculated as follows:
(l) (l)
d d
WDTX ( i, j, k, l ) = ωi – ω j ⋅ xˆ k
dt dt
where:
Examples
REQUEST/16
,F1=WDTM(1236,2169)/
,F2=WDTX(1236,2169,2169,2169)/
142 Adams Solver
,F3=WDTY(1236,2169,2169,2169)/
,F4=WDTZ(1236,2169,2169,2169)
In its second column REQUEST/16 contains the x-component of the angular acceleration vector of Marker
WDTY 143
WDTY
The WDTY function returns the y-component of the difference between the angular acceleration vector of
coordinate system if it is not specified. Similarly, marker k and l default to the global coordinate system if they
are not specified.
Format
WDTY(i[,j][,k][,l])
Arguments

system.
Extended Definition
Mathematically, WDTY is calculated as follows:
(l) (l)
d d
WDTY ( i, j, k, l ) = ωi – ω j ⋅ yˆ k
dt dt
where:
Examples
REQUEST/16
,F1=WDTM(1236,2169)/
144 Adams Solver
,F2=WDTX(1236,2169,2169,2169)/
,F3=WDTY(1236,2169,2169,2169)/
,F4=WDTZ(1236,2169,2169,2169)
In its third column REQUEST/16 contains the y-component of the angular acceleration vector of Marker
WDTZ 145
WDTZ
The WDTZ function returns the z-component of the difference between the angular acceleration vector of
coordinate system if it is not specified. Similarly, marker k and l default to the global coordinate if they are
not specified.
Format
WDTZ(i[,j][,k][,l])
Arguments

still specifying l, if you want the results to be calculated along the z-axis of the global coordinate
system.
Extended Definition
Mathematically, WDTZ is calculated as follows:
(l) (l)
d d
WDTZ ( i, j, k, l ) = ωi – ω j ⋅ zˆ k
dt dt
where:
Examples
REQUEST/16
,F1=WDTM(1236,2169)/
146 Adams Solver
,F2=WDTX(1236,2169,2169,2169)/
,F3=WDTY(1236,2169,2169,2169)/
,F4=WDTZ(1236,2169,2169,2169)
In its fourth column REQUEST/16 contains the z-component of the angular acceleration vector of Marker
WM 147
WM
The WM function returns the magnitude of the angular velocity vector of marker i with respect to marker j.
Marker j defaults to the global coordinate system if it is not specified.
Format
WM(i[,j])
Arguments

j The marker with respect to which the velocity is being measured. Set j = 0, while still
specifying l, if you want j to default to the global coordinate system.
Extended Definition
Mathematically, WM is calculated as follows:
WM ( i, j ) = [ ωi – ωj ] ⋅ [ ωi – ωj ]
where:
Examples
REQUEST/16
,F1=WM(1236,2169)/
,F2=WX(1236,2169,2169)/
,F3=WY(1236,2169,2169)/
,F4=WZ(1236,2169,2169)
In its first column, REQUEST/16 contains the magnitude of the angular velocity vector of Marker 1236 and
Marker 2169.
148 Adams Solver
WX
The WX function returns the x-component of the difference between the angular velocity vector of marker i
Format
WX(i[,j][,k])
Arguments

want the results to be calculated along the x-axis of the global coordinate system.
Extended Definition
Mathematically, WX is calculated as follows:
WX ( i, j, k ) = [ ω i – ω j ] ⋅ x̂ k
where:
Examples
REQUEST/16
,F1=WM(1236,2169)/
,F2=WX(1236,2169,2169)/
,F3=WY(1236,2169,2169)/
,F4=WZ(1236,2169,2169)
In its second column, REQUEST/16 contains the x-component of the angular velocity Markers 1236 and
2169 as measured in the coordinate system of Marker 2169. See other Velocity available.
WY 149
WY
The WY function returns the y-component of the difference between the angular velocity vector of marker i
Format
WY(i[,j][,k])
Arguments

the results to be calculated along the y-axis of the global coordinate system.
Extended Definition
Mathematically, WY is calculated as follows:
WY ( i, j, k ) = [ ω i – ω j ] ⋅ ŷ k
where:
Examples
REQUEST/16
,F1=WM(1236,2169)/
,F2=WX(1236,2169,2169)/
,F3=WY(1236,2169,2169)/
,F4=WZ(1236,2169,2169)
In its third column, REQUEST/16 contains the y-component of the angular velocity Markers 1236 and
150 Adams Solver
WZ
The WZ function returns the z-component of the difference between the angular velocity vector of marker i
Format
WZ(i[,j][,k])
Arguments

want the results to be calculated along the z-axis of the global coordinate system.
Extended Definition
Mathematically, WZ is calculated as follows:
WZ ( i, j, k ) = [ ω i – ω j ] ⋅ ẑ k
where:
Examples
REQUEST/16
,F1=WM(1236,2169)/
,F2=WX(1236,2169,2169)/
,F3=WY(1236,2169,2169)/
,F4=WZ(1236,2169,2169)
In its fourth column, REQUEST/16 contains the z-component of the angular velocity Markers 1236 and
YAW 151
YAW
The YAW function calculates the first angle of a body-fixed 3 2 1 yaw-pitch-roll rotation sequence between
markers i and j. Marker j defaults to the global coordinate system if it is not specified. Note that yaw is an
Euler angle.
Format
YAW(i[,j])
Arguments

Examples
REQUEST/1
,F2=YAW(21,11)/
,F3=PITCH(21,11)/
,F4=ROLL(21,11)
This REQUEST statement calculates the yaw, pitch, and roll angles between Markers 21 and 11 for output
purposes.
152 Adams Solver
1
Adams Solver (FORTRAN) Commands

You use commands to control the simulation. Commands allow you to modify statements, invoke and
control the simulations, and display simulation output and status information.
Below are the Adams Solver (FORTRAN) commands grouped according to their function. Detailed
information on each command can be found by following the links.

bordered MARKER
FLEX_BODY
Constraints JOINT
MOTION
UCON
Forces ACCGRAV
BEAM
BUSHING
FIELD
FRICTION
GFORCE
SFORCE
SPRINGDAMPER
VFORCE
VTORQUE
SPLINE
STRING
VARIABLE
EQUILIBRIUM
IC
INTEGRATOR
KINEMATICS
LSOLVER
SENSOR
2 Adams Solver

Output OUTPUT
REQUEST
Simulation ACTIVATE
CONTROL
DEACTIVATE
FILE
LINEAR
PREFERENCES
RELOAD
SAVE
SIMULATE
STOP
Information HELP
INFO
MENU
SHOW
TIME
ACCGRAV 3
ACCGRAV
The ACCGRAV command redefines and/or lists the data for a ACCGRAV statement.
Format
Arguments
IGRAV=r Respecifies the x component of gravitational acceleration with respect to the ground
JGRAV=r Respecifies the y component of gravitational acceleration with respect to the ground
KGRAV=r Respecifies the z component of gravitational acceleration with respect to the ground
LIST Lists the current values of the data in the ACCGRAV statement.
Examples
ACCGRAV/LIST
This ACCGRAV command lists all the data for the ACCGRAV statement in the dataset.
4 Adams Solver
ACTIVATE
The ACTIVATE command activates a statement that was previously turned off by the DEACTIVATE command.
Format
Arguments
BEAM Specifies that Adams Solver (FORTRAN) is to activate BEAM statements.

BUSHING Specifies that Adams Solver (FORTRAN) is to activate BUSHING statements.
FIELD Specifies that Adams Solver (FORTRAN) is to activate FIELD statements.
ID=id1[,...,id30] Lists up to 30 statement identifiers for statements that Adams Solver (FORTRAN)
activates. You may use the ID argument in conjunction with the RANGE argument.
JOINT Specifies that Adams Solver is to activate JOINT statements.
JPRIM Specifies that Adams Solver (FORTRAN) is to activate JPRIM statements.
LIST Indicates that Adams Solver (FORTRAN) is to display a list of all the existing
elements of the specified type, along with their current activity status.
MOTION Specifies that Adams Solver (FORTRAN) is to activate MOTION statements.
RANGE=id1,id2 Defines a range of statement identifiers for statements that Adams Solver
(FORTRAN) is to activate. Adams Solver (FORTRAN) activates all statements with
identifiers that are numerically between the given identifiers, inclusively. The range
may contain unused identifiers. You may use the RANGE argument in conjunction
with the ID argument.
Range: id1 < id2

ACTIVATE 5
SENSOR Specifies that Adams Solver (FORTRAN) is to activate SENSOR statements.

SFORCE Specifies that Adams Solver (FORTRAN) is to activate SFORCE statements.
SPRINGDAMPER Specifies that Adams Solver (FORTRAN) is to activate SPRINGDAMPER
statements.
Extended Defintion
The ACTIVATE command, used in conjunction with the DEACTIVATE command, switches Adams Solver
(FORTRAN) elements on and off. All Adams Solver (FORTRAN) elements are active by default in the input
dataset, but can be deactivated using the DEACTIVATE command. For simulation purposes, when Adams
Solver (FORTRAN) activates a statement, the statement appears as though it was always in the dataset. When
Adams Solver (FORTRAN) deactivates a statement, the statement effectively disappears from the model.
Both the ACTIVATE and DEACTIVATE commands take effect when you issue the next SIMULATE
command.
After the activation of any element, Adams Solver (FORTRAN) reprocesses the model at the next
SIMULATE command, as if it had just been read in from the dataset. During the reprocessing, Adams Solver
(FORTRAN) checks the entire model for consistency, reinitializes user subroutines, and recomputes initial
conditions.
While checking the entire model, Adams Solver (FORTRAN) verifies that the model is still valid when the
newly activated elements are included. For example, if an activated JOINT overconstrains a model resulting
in an immobile system, Adams Solver (FORTRAN) issues an error message.
Adams Solver (FORTRAN) also reinitializes all user subroutines to re-establish functional dependencies. For
each element that refers to a user-written subroutine, Adams Solver (FORTRAN) calls the user-written
subroutine with IFLAG set to true.
Prior to the actual simulation, Adams Solver (FORTRAN) computes initial conditions for the model. If this
is the first simulation, Adams Solver (FORTRAN) begins with the positions and velocities specified in the
dataset, and maintains any user-supplied joint initial-conditions and part positions specified as EXACT. If
you ran a previous simulation, Adams Solver (FORTRAN) begins with the final displacements and velocities.
Adams Solver (FORTRAN) then adjusts the initial conditions to ensure that they are consistent with the
model constraints.
If a constraint or force is activated in the middle of a simulation, by default Adams Solver (FORTRAN) splits
the tabular, request, graphics, and results output into two separate sets of output concatenated together. This
ensures that the output correctly reflects the new system topology.
The OUTPUT/NOSEPARATOR argument prevents Adams Solver (FORTRAN) from splitting the file.
This allows you to plot or animate the output continuously from beginning to end, but may result in
misleading graphics during postprocessing. See OUTPUT for more information on the NOSEPARATOR
argument.
Tip: Use the ACTIVATE and DEACTIVATE commands after a FILE or RELOAD command to
set up the model for a particular loadcase or configuration.
6 Adams Solver
Examples
ACTIVATE/SFORCE,ID=201,202
This ACTIVATE command activates SFORCEs 201 and 202.
ACTIVATE/JPRIM,RANGE=400,499
This ACTIVATE command activates JPRIMs 400 and 499, and all JPRIMs with identifiers between 400 and
499.
ARRAY 7
ARRAY
The ARRAY command redefines and/or lists the array of up to 1,200 real numbers for an IC-type ARRAY
statement.
Format
ARRAY/id [,NUMBERS=r1 [,r2,...]] [,LIST]
[ ]Optionally select the item
Arguments
LIST Lists the number(s) in storage.

NUMBERS=r1[,r2,...] Respecifies at least one real number to be stored.
Caution: You can use the ARRAY command on only an IC-type ARRAY statement (the default type).
Adams Solver (FORTRAN) issues an error message if you specify an X-, U-, or Y-type ARRAY
statement.
Example
ARRAY/12, NUMBERS=0.5,0.12, LIST
8 Adams Solver
BEAM
The BEAM command redefines and/or lists the data for a BEAM statement. Although you cannot redefine the
I and the J markers, you can redefine any of the other BEAM arguments.
Format
Arguments
AREA=r Respecifies the uniform area of the beam cross-section. The centroidal axis must
be orthogonal to this cross-section.
ASY=r Respecifies the correction factor for shear deflection in the y direction for
Timoshenko beams.
ASZ=r Respecifies the correction factor for shear deflection in the z direction for
Timoshenko beams.
CMATRIX=r1,...,r21 Respecifies the six-by-six damping matrix for the beam. Because this matrix is
symmetric, you need to specify only one-half of it, that is, twenty-one entries. The
units for the translational and rotational components of CMATRIX should be
force-time per displacement unit and torque-time per radian, respectively.
CRATIO=r Respecifies the ratio for calculating the structural damping matrix for the beam.
Adams Solver (FORTRAN) multiplies the stiffness matrix by the value of
CRATIO to obtain the damping matrix.
EMODULUS=r Respecifies Young’s modulus of elasticity for the beam material.
GMODULUS=r Respecifies the shear modulus of elasticity for the beam material.
BEAM 9
IXX=r Denotes the torsional constant. This is sometimes referred to as the torsional shape
factor or torsional stiffness coefficient. It is expressed as unit length to the fourth
power. For a solid circular section, Ixx is identical to the polar moment of inertia
. For thin-walled sections, open sections, and noncircular sections, you
should consult a handbook.
IYY=r,IZZ=r Denotes the area moments of inertia about the neutral axes of the beam cross
sectional area (y-y and z-z). These are sometimes referred to as the second moment
of area about a given axis. They are expressed as unit length to the fourth power.
For a solid circular section, Iyy=Izz= . For a thin-walled sections, open
sections, and noncircular sections, the user should consult a handbook.
LENGTH Respecifies the undeformed length of the beam along the x-axis of the J marker.
LIST Lists the current values of the data in the BEAM statement.

10 Adams Solver
BUSHING
The BUSHING command redefines and/or lists the data for a BUSHING statement. Although you cannot
define the I and J markers defining the bushing, you can redefine other characteristics of the bushing.
Format
Arguments
C=r1,r2,r3 Respecifies three viscous damping coefficients for the force transferred by the bushing.
CT=r1,r2,r3 Respecifies three viscous damping coefficients for the torque transferred by the
bushing.
FORCE=r1,r2,r3 Respecifies three constant force (preload) values.
K=r1,r2,r3 Respecifies three stiffness coefficients for the force transferred by the bushing.
KT=r1,r2,r3 Respecifies three stiffness coefficients for the torque transferred by the bushing.
LIST Lists the current values of the data in the BUSHING statement.
TORQUE=r1,r2,r Respecifies three constant torque (preload) values.
3
Caution: For the rotational constitutive equations to be accurate, at least two of the rotations (a, b, and
c) must be small. That is, two of the three values must remain smaller than 10 degrees. In
addition, if a becomes greater than 90 degrees, b becomes erratic. If b becomes greater than 90
degrees, a becomes erratic. Only c can become greater than 90 degrees without causing
problems. For these reasons, it is best to define your BUSHING such that angles a and b (not
a and c and not b and c) remain small.

CONTROL 11
CONTROL
The CONTROL command branches program control to the driver subroutine CONSUB. Adams Solver
(FORTRAN) passes parameter arguments to the command as an array. Upon completion of CONSUB,
Adams Solver (FORTRAN) prompts you for another command.
Format
CONTROL/[FUNCTION=USER(r1[,...,r30])[\]][ROUTINE=libname::subname]
Arguments
FUNCTION=USER(r1[,...,r30]) Specifies and passes up to thirty constants to a CONSUB driver

subroutine to regulate and control one or more Adams Solver
(FORTRAN) simulations. Follow FUNCTION with an equal sign,
the character string USER, and the real values (r1[,...,r30]) to be
passed to CONSUB.
CONSUB.
Tip: A CONSUB driver subroutine can be thought of as an Adams command file programmed in
the FORTRAN programming language. The FORTRAN facilities for control and logic may
be used in conjunction with Adams utility subroutines to drive the Adams simulation. In
particular, the MODIFY utility subroutine can be used to issue Adams commands.
Caution: Adams Solver (FORTRAN) issues an error message and ignores the entire command if a
CONTROL command is issued when no CONSUB driver subroutine is linked with Adams
Solver (FORTRAN).

12 Adams Solver
DEACTIVATE
The DEACTIVATE command turns off a statement that was previously turned on by the ACTIVATE
command, or that was active by default.
Format
Arguments
BEAM Indicates that Adams Solver (FORTRAN) is to deactivate BEAM statements.

BUSHING Indicates that Adams Solver (FORTRAN) is to deactivate BUSHING statements.
FIELD Indicates that Adams Solver (FORTRAN) is to deactivate FIELD statements.
ID=id1[,...,id30] Lists up to 30 statement identifiers for statements that Adams Solver (FORTRAN)
is to deactivate. You may use the ID argument in conjunction with the RANGE
argument.
JOINT Indicates that Adams Solver (FORTRAN) is to deactivate JOINT statements.
JPRIM Indicates that Adams Solver (FORTRAN) is to deactivate JPRIM statements.
LIST Indicates that Adams Solver (FORTRAN) is to display a list of all the existing
elements of the specified type, along with their current activity status.
MOTION Indicates that Adams Solver (FORTRAN) is to deactivate MOTION statements.
RANGE=id1, id2 Redefines a range of statement identifiers for statements that Adams Solver
(FORTRAN) is to deactivate. Adams Solver (FORTRAN) deactivates all statements
with identifiers that are numerically between the given identifiers, inclusively. The
range may contain unused identifiers. You may use the RANGE argument in
conjunction with the ID argument.
Range: id1 < id2

DEACTIVATE 13
SENSOR Indicates that Adams Solver (FORTRAN) is to deactivate SENSOR statements.

SFORCE Indicates that Adams Solver is to deactivate SFORCE statements.
SPRINGDAMPER Indicates that Adams Solver (FORTRAN) is to deactivate SPRINGDAMPER
statements.
Extended Definition
The DEACTIVATE command, used in conjunction with the ACTIVATE command, switches Adams Solver
(FORTRAN) elements off and on. All Adams Solver (FORTRAN) elements are active by default in the input
dataset, but some may be deactivated using the DEACTIVATE command. For simulation purposes, when
Adams Solver (FORTRAN) deactivates a statement, the statement effectively disappears from the model.
When a statement is activated, the statement appears as though it were always in the dataset. Both the
DEACTIVATE and ACTIVATE commands take effect when you issue the next SIMULATE command.
Once deactivated, a statement remains inactive until it is activated using an ACTIVATE command.
After the deactivation of any element, Adams Solver (FORTRAN) reprocesses the model at the next
SIMULATE command as if it had just been read in from the dataset. During the reprocessing, Adams Solver
conditions.
While checking, Adams Solver (FORTRAN) examines all active-element function expressions and arguments
for references to inactive elements. Adams Solver (FORTRAN) issues an error message if an active force,
constraint, or sensor refers to an inactive element just as if the inactive element did not exist. Adams Solver
(FORTRAN) reports zero forces for the inactive element if a force request or force graphic refers to an inactive
element.
dataset. If you ran a previous simulation, Adams Solver (FORTRAN) begins with the final displacements and
velocities. Adams Solver (FORTRAN) then adjusts the initial conditions to ensure that they are consistent
with the model constraints. If this is the first simulation, Adams Solver (FORTRAN) also maintains any user-
supplied joint initial-conditions and part positions specified as EXACT.
Adams Solver (FORTRAN) reports zero values in all output files for any forces associated with inactive
elements, including both applied forces and joint reaction forces. This includes force requests, force graphics,
and forces in the Results File.
Adams Solver (FORTRAN) continues to report displacements, velocities, and accelerations for all JOINT
and JPRIM MREQUESTs, even for JOINTs and JPRIMs that have been deactivated. MREQUEST creates
displacement, velocity, and acceleration requests for the markers associated with the specified JOINTs and
JPRIMs. Adams Solver (FORTRAN) continues to output the relative marker displacements, velocities, and
accelerations, even if you deactivated the original JOINT or JPRIM.
14 Adams Solver
If you deactivate a constraint or force in the middle of a simulation, by default Adams Solver (FORTRAN)
will split the tabular, request, graphics, and results output into two separate sets of output concatenated
together. This ensures that the output correctly reflects the new system topology.
argument.
Tip: Typically, you use DEACTIVATE and ACTIVATE to set up the model for a particular
loadcase or configuration after a FILE or RELOAD command.
Caution: Deactivating elements may produce strong discontinuities in the model causing convergence
difficulties and reduced integrator performance. It is important that you use these commands
carefully to avoid discontinuities.
Examples
DEACTIVATE/JOINT,ID=71,72,73
This DEACTIVATE command deactivates JOINTs 71, 72, and 73.
DEACTIVATE/SENSOR,RANGE=5,10
This DEACTIVATE command deactivates all SENSORs with identifiers between 5 and 10, including 5 and
10.
DEBUG 15
DEBUG
The DEBUG command redefines and/or lists the data for a DEBUG statement. See the DEBUG statement
for more information.
Format
Click the argument for a description
16 Adams Solver
Arguments
DEBUG 17
DUMP Writes the internal representation of a dataset in the Tabular Output File after Adams Solver reads and
checks the input. This facility essentially maps the equations and variables in the system and provides
their numeric codes.
Default: Off
monitor the simulation process and to locate the source of the error if there is a problem. Each step
consists of two phases: 1) a forward step in time (the predictor for dynamics) and 2) the solution of the
equations of motion (the corrector for dynamics). For the first phase, Adams Solver prints out the
following information:
measure of how hard Adams Solver is working.
Solver uses to predict the solution at the end of the integration step.
For the second phase, Adams Solver prints out the cumulative number of iterations and a table of
information about the iterations. The cumulative number of iterations is a running count of the
computations Adams Solver is performing. The table contains information about the maximum
equation error and maximum variable change for each iteration. For each iteration, Adams Solver
prints out the following information:
 The iteration number. This is one at the beginning of each step and increments by one until Adams
Solver converges to a solution or exceeds the maximum allowable number of iterations.
 The largest (in absolute value) equation residual. Each equation should have an error value close to
zero. This number is an indicator of how far Adams Solver is from a solution. This number should
decrease after every iteration.
 The absolute value of the largest change in a variable. The final iteration should not need to change
variables very much. This number is an indicator of how far Adams Solver needs to change
variables to approach a solution. This number should decrease after every iteration.
 If Adams Solver has updated the Jacobian, YES appears under the new Jacobian header.
Default: NOEPRINT
18 Adams Solver
JMDUMP Dumps the Jacobian matrix at each iteration. The Jacobian is dumped in the working directory in the
file with extension *.jac and root name equal to the one of the message file.
Default: NOJMDUMP
LIST Lists the current values of the data in the DEBUG statement.
NOEPRINT Suppresses the printing of three numbers at each integration step and five numbers at each corrector
iteration during an integration.
Default: NOEPRINT
NOJMDUMP Disables the dumping of the Jacobian matrix at each iteration.
Default: NOJMDUMP
NOREQDUM Disables the dumping of REQUEST and MREQUEST statement output at each iteration.
P
Default: NOREQDUMP
NORHSDUM Disables the dumping of the YY array (state vector), the RHS array (error terms), and the DELTA array
P (increment to state vector) at each iteration.
Default: NORHSDUMP
NOVERBOSE Deactivates the output of explanations and possible remedies and the output of the names of
subroutines from which Adams Solver sends diagnostics.
Default: NOVERBOSE
REQDUMP Enables the dumping of the REQUEST and the MREQUEST statement output at each iteration.
Default: NOREQDUMP
RHSDUMP Dumps the values of the right-hand-side vector and states in the solution of each AX=b linear problem.
The states and right-hand-side are dumped in the working directory in the file with extension *.rhs and
root name equal to the one of the message file.
Default: NORHSDUMP
Solver sends each diagnostic, explanations, and possible remedies (when available). If you do not
include the VERBOSE argument, Adams Solver outputs to the screen only basic error messages.
Whether or not you include the VERBOSE argument, Adams Solver outputs VERBOSE information
to the Message File.
Default: NOVERBOSE
MATLAB When specified in conjunction with the RHSDUMP or JMDUMP flags it changes the output format
to be such that the debug information can be easily imported into Matlab. Importing for example the
DEBUG 19
Extended Definition
Of all the arguments in the DEBUG command, EPRINT is perhaps the most useful. This section explains
the EPRINT argument in detail.
The kinematic, dynamic, and quasi-static analyses in Adams Solver involve the solution of the governing
equations of motion. Static analysis is the solution of the equilibrium and the initial conditions analysis solves
the assembly equations at a particular point in time.
The equations to be solved, for all these analyses, are non-linear algebraic or differential-algebraic equations.
The solution of these equations is an iterative process. The EPRINT argument enables Adams Solver to write
out the information pertaining to the solution process in a succinct and understandable format. All analyses
that march through time consist of two distinct phases: predictor phase and corrector phase.
Predictor Phase
In order to proceed efficiently from one time to the next, Adams Solver uses a predictor. The predictor is
simply a means of estimating the values of the system state by looking at the past values of the state and
extrapolating the data based on a simple curve fitting algorithm.
Consider a series of values yi defined at discrete times ti
where i=1...n. A simple first order predictor that may be used to predict the value yn+1 at tn+1 is:
where superscript p implies a predicted value. This is shown graphically in Figure 1.
Figure 1 First Order Predictor

20 Adams Solver
You can easily surmise from Figure 1, a first order predictor simply consists of connecting the points yn-1 and
yn with a straight line and extending it to time tn+1.
A second order predictor, similarly, can be thought of as constructing a parabola between the points (tn-2, yn-
2), (tn-1, yn-1) and (tn, yn) and extending the parabola to time tn+1. The predicted value of y at tn+1 is the
intersection of the vertical line t=tn+1 with this parabola. Predictors are typically polynomials (linear,
quadratic, cubic, etc.) and the order of the polynomial is frequently called the order of the solution method.
For kinematic analyses, Adams Solver employs a first or second order predictor. For quasi-statics, a first order
predictor is used. For dynamic analyses much higher order predictors are used. The BDF methods (GSTIFF
and WSTIFF) use up to six order predictors. ABAM on the other hand can use up to a 12th order predictor.
Sophisticated numerical analysis is employed to determine the most appropriate order of prediction to use at
any given step.
Furthermore, sophisticated curve fitting methods like Newton-Divided Difference tables are usually
employed to efficiently predict the system state. Figure 2 shows the format of the output produced by the
EPRINT argument and explains the data pertinent to the predictor phase of a dynamic analysis step.
The predictor polynomials used for the dynamic analyses interpolate previous values and the slope of the
variable at the current time to estimate the solution at the next time. Therefore, in Figure 5, a second order
polynomial that fits the solution at times t4 and t5 and the slope of the solution at time t5 is used to predict
the value of the solution at time t6.
Figure 2 A Successful Integration Step

DEBUG 21
Corrector Phase
Since all predictors simply look at past values to estimate the solution at the next time, the predicted values
almost never satisfy the governing equations. They simply constitute a good initial guess for the solution. The
refining of the predicted solution to one that satisfies the governing equations is called the correction. Since
the governing equations are usually non-linear, an iterative scheme like Newton-Raphson iterations are used.
This methodology is explained for the simplest case of one non-linear algebraic equation in one variable. Let
f(x) be a smooth function of a single variable x. Given an initial guess x=x0, a solution x=xc that satisfies f(x)=0
is desired for this simple example. The Newton-Raphson iterations may be expressed as:
for i=0 ... max_no_iterations. ε is a small user-defined number that specifies the convergence criterion.
2. If || err(xi) || < ε return xi as the solution

where err(xi) is the error measure being maintained during Newton Raphson iterations
3. Evaluate
Ji = ∂f
∂ x x = xi
4. Calculate
–1
Δx i = J i r i
5. Set x i = x i + Δx i

The quantity ri is frequently called the residual and is a measure of the accuracy of the solution. The quantity
Ji is the partial derivative of f with respect to x, evaluated at x=xi and is commonly known as the Jacobian.
The graph on the left side of Figure 3 illustrates the Newton-Raphson iterations for the one-dimensional
example discussed above.
22 Adams Solver
Figure 3 The Newton-Raphson Algorithm for a Single Nonlinear Equation
J0 is the slope of the curve f(x) at x=x0. Through simple trigonometry it can be seen that x0-x1 = r0/J0 (i.e.,
x1 = x0 - r0/J0).
DEBUG 23
Similarly,
The corrector in Adams Solver involves the solution of many variables simultaneously. The algorithm for one
dimension is easily extended to n dimensions as follows:
Let x = {x1, x2,... xn} be a set of n variables and f = {f1(x), f2(x),... fn(x)} be a set of n non-linear equations in
the variables x.
Define:
J= ,
where i=1,...,n and j=1,...,n. Then the Newton-Raphson iterations for the n-dimensional case becomes: given
an initial guess x = x0 = {x01, x02,... x0n} for i=0,...,max_no_interations. is a small user-defined number
that specifies the convergence criterion.
2. If || ri || < return x = xi as the solution
3. Calculate , where j=1,...,n and k=1,...,n
4. Evaluate
5. Set ,
For the n-dimensional case, evaluating the Jacobian Ji and its inverse at each iteration can be quite expensive
and is the most expensive part of the iteration process. In order to decrease the computational overhead, the
Jacobian Ji is not evaluated at each iteration. It is only updated periodically. This technique can dramatically
increase the overall speed of the corrector iterations and is termed Modified Newton-Raphson iterations.
The graph on the right side of Figure 3 demonstrates the use of the Modified Newton-Raphson iterations to
solve the one-dimensional problem f(x)=0. In this example, the initial Jacobian f’(x0) is re-used for the first 4
corrections before it is re-evaluated for iteration 5. The data are shown in Figure 4 for the modified Newton-
24 Adams Solver
Raphson iterations in a dynamic analysis. The numbers on the left are the values of the maximum residuals
at each iteration. The maximum corrections are on the right. In practice, the convergence rate of the iterations
is used to determine whether a Jacobian evaluation is to be performed or not.
Figure 4 The Modified Newton-Raphson Algorithm for a System of Non-linear Equations
Figure 5 Predictor Polynomial and Corrected Value
The DEBUG/EPRINT option generates a table of data on the action of Adams Solver for each of the iterative
algorithms in the various analyses. The iterative algorithm, or corrector, is used to evaluate the variables
governed by the system of non-linear equations. Table 1 contains the DEBUG/EPRINT information for the
variables associated with the mass-bearing elements (parts, point masses, and flexible bodies) and for the
corresponding equations. A combination of several equations is needed to define each joint and joint
primitive. Table 2 includes the variables for the various joint constraints and the corresponding equations.
DEBUG 25
Adams Solver uses a combination of equations to represent the different types of forces. While certain
equations are specific to a particular force, others are generic to all types. The combination of variables and
corresponding equations for the forces are included in Table 3. The DEBUG/EPRINT information for the
variables and corresponding equations that define the Adams system elements is contained in Table 4. Finally,
Table 5 includes the information on the variables and equations for the remaining miscellaneous elements in
an Adams system.
Table 1 Mass Bearing Elements Debug Descriptions
EQUATIONS VARIABLES
Element
Parts ··
mx Translational force, ·x Translational coordinate,
x-direction, GCS x-direction, GCS
m ··
y Translational force, y· Translational coordinate,
mz·· Translational force, z· Translational coordinate,
·
p Algebraic equation for the ψ Rotational rate, first component, 3-
ψ
ψ component of the 1-3 Euler angles, GCS
angular momentum
·
p Algebraic equation for the θ Rotational rate, second component,
θ
θ component of the 3-1-3 Euler angles, GCS
angular momentum
·
p Algebraic equation for the φ Rotational rate, third component, 3-
φ
φ component of the 1-3 Euler angles, GCS
angular momentum
p· ψ Torque, the ψ component p ψ component of the angular
ψ
momentum
p· θ Torque, the θ component p θ component of the angular
θ
momentum
p· φ Torque, the φ component p φ component of the angular
φ
momentum
vx Velocity equation, x Translational coordinate,
x-coordinate, GCS x-direction, GCS
vy Velocity equation, y Translational coordinate,
y-coordinate, GCS y-direction, GCS
vz Velocity equation, z Translational coordinate,
z-coordinate, GCS z-direction, GCS
26 Adams Solver
EQUATIONS VARIABLES
Element
Ψ Equation for the time- ψ Rotational coordinate, first
derivative of the ψ component, 3-1-3 Euler angles, GCS
coordinate
·
θ Equation for the time- θ Rotational coordinate, second
derivative of the component, 3-1-3 Euler angles, GCS
θ coordinate
·
φ Equation for the time- φ Rotational coordinate, third
φ coordinate
Flexible mx·· Translational force, x· Translational coordinate,
Bodies x-direction, GCS x-direction, GCS
m ··
y Translational force, y· Translational coordinate,
mz·· Translational force, z· Translational coordinate,
·
ωψ First of three equations of ψ Time-derivative of the ψ coordinate
motion for torque
· ·
ωθ Second of three equations θ Time-derivative of the θ coordinate
of motion for torque
· ·
ωφ Third of three equations of φ Time-derivative of the φ coordinate
motion for torque
··
M qj Inertial equations for modal q· j Time-derivatives of modal
coordinates for 1 ≤ j ≤ coordinates for 1 ≤ j ≤ number of
number of flexible modes flexible modes
vx Velocity equation, x Translational coordinate,
x-coordinate, GCS x-direction, GCS
vy Velocity equation, y Translational coordinate,
y-coordinate, GCS y-direction, GCS
vz Velocity equation, z Translational coordinate,
z-coordinate, GCS z-direction, GCS
Ψ Equation for the time- ψ Rotational coordinate, first
derivative of the ψ component, 3-1-3 Euler angles, GCS
coordinate
·
θ Equation for the time- θ Rotational coordinate, second
θ coordinate
DEBUG 27
EQUATIONS VARIABLES
Element
·
φ Equation for the time- φ Rotational coordinate, third
φ coordinate
q· j Equation for the time- qj Modal coordinates for 1 ≤ j ≤
derivatives of modal number of flexible modes
coordinates for 1 ≤ j ≤
number of flexible modes
Point mx·· Translational force, x· Translational velocity,
Masses x-direction, GCS x-direction, GCS
m ··
y Translational force, y· Translational velocity,
mz·· Translational force, z· Translational velocity,
Table 2 Joint and Joint Primitive Debug Descriptions
EQUATIONS VARIABLES
Joint Initial x At Point Constraint Reaction Force (x) 1
Condition, (x) xi − xj = 0
Translational y At Point Constraint y Force Reaction Force (y) 1
(y) yi − yj = 0
z At Point Constraint z Force Reaction Force (z) 1
(z) zi − zj = 0
Joint Initial xi • yj Angular Constraint (xi, xy Torque Reaction Torque (xi, 2
Condition, yj) xi • yj = 0 yj)
Rotational zi • xj Angular Constraint (zi, zx Torque Reaction Torque (zi, 2
zi • yj Angular Constraint (zi, zy Torque Reaction Torque (zi, 2
Cylindrical zi • xj Angular Constraint (zi, zx Torque Reaction Torque (zi, 2
s • xj Sliding Constraint (s, sx Force Reaction Force (s, xj) 3
xj) s • xj = 0
28 Adams Solver
EQUATIONS VARIABLES
s • yj Sliding Constraint(s, sy Force Reaction Force (s, yj) 3
yj) s • yj = 0
Convel Joint x At Point Constraint x Force Reaction Force (x) 2
(x) xi − xj = 0
y At Point Constraint y Force Reaction Force (y) 2
(y) yi − y j = 0
(z) zi − zj = 0
xi • yj Angular Constraint (xi, xy Torque Reaction Torque (xi, 3
Fixed Joint x At Point Constraint x Force Reaction Force (x) 1
(x) xi − xj = 0
y At Point y Force Reaction Force (y) 1
Constraint(y) yi − yj =
0
(z) zi − zj = 0
zi • xj Angular Constraint (zi, zx Torque Reaction Torque (zi, 2
Hooke Joint x At Point x Force Reaction Force (x) 2
Constraint(x) xi − xj =
0
(y) yi − y j = 0
(z) zi − zj = 0
Planar Joint zi • xj Angular Constraint (zi, zx Torque Reaction Torque (zi, 2
DEBUG 29
EQUATIONS VARIABLES
s • zj Sliding Constraint (s, sz Force Reaction Force (s, zj) 3
zj) s • zj = 0
Rack-&- α•P Rotation/Translation ap Force Reaction Force ( ) 4
Pinion Joint Dependency
Revolute Joint x At Point Constraint x Force Reaction Force (x) 1
(x) xi − xj = 0
(y) yi − yj = 0
(z) zi − zj = 0
zi • xj Angular Constraint (zi, zx Torque Reaction Torque (zi, 2
Screw Joint α•P Rotation/Translation ap Force Reaction Force ( ) 4
Dependency
Spherical Joint x At Point Constraint x Force Reaction Force (x) 1
(x) xi − xj = 0
(y) yi − yj = 0
(z) zi − zj = 0
Translational zi • xj Angular Constraint (zi, zx Torque Reaction Torque (zi, 2
s • xj Sliding Constraint (s, sx Force Reaction Force (s, xj) 3
xj) s • xj = 0
s • yj Sliding Constraint (s, sy Force Reaction Force (s, yj) 3
yj) s • yj = 0
Universal Joint x At Point Constraint x Force Reaction Force (x) 1
(x) xi − xj = 0
(y) yi − yj = 0
30 Adams Solver
EQUATIONS VARIABLES
(z) zi − zj = 0
zi • zj Angular Constraint (zi, zz Torque Reaction Torque (zi, 2
zj) zi • zj = 0 zj)
Atpoint Joint x At Point Constraint x Force Reaction Force (x) 1
Primitive (x) xi − xj = 0
(y) yi − y j = 0
(z) zi − zj = 0
Inline Joint xij Equivalent to Sliding ‘x’ Force Reaction Force (s, xj) 3
Primitive Constraint (s, xj) s • xj = 0
yij Equivalent to Sliding ‘y’ Force Reaction Force (s, yj) 3

Constraint (s, yj) s • yj = 0
Inplane Joint zij Equivalent to Sliding ‘z’ Force Reaction Force (s, zj) 3
Primitive Constraint (s, zj)
Orientation zi • xj Angular Constraint (zi, zx Torque Reaction Torque (zi, 2
Joint Primitive xj) zi • xj = 0 xj)
Parallel Joint zi • xj Angular Constraint (zi, zx Torque Reaction Torque (zi, 2
Primitive xj) zi • xj = 0 xj)
Perpendicular zi • zj Angular Constraint (zi, zz Torque Reaction Torque (zi, 2
Joint Primitive zj) zi • zj = 0 zj)
Notes
1. An At Point Constraint ensures that the origins of the two markers connected by this constraint
remain spatially collocated during the simulation. This constraint is made up of 3 equations for the
displacement between the two markers in the global X, Y and Z directions, respectively. For each of
the equations, a corresponding variable is introduced to represent the constraint reaction in the X, Y
and Z directions, respectively. In Table 3 a at point constraint equation in the n1 direction is denoted
by At_point_constraint(n1) and the corresponding reaction force by Reaction_force(n1).
DEBUG 31
The three At Point Constraint equations are: xi - xj = 0, yi - yj = 0, and zi - zj = 0.

2. An Angular Constraint ensures that two vectors fixed in separate mass bearing elements (PARTs,
POINT_MASSes, or FLEX_BODY) (MBE) remain mutually perpendicular during the simulation.
This constraint is represented by 1 equation. This equation requires the dot product of the two vectors
to be zero. Corresponding to this equation, a variable is introduced to represent the constraint
reaction torque. In Table 3, this constraint is denoted as Angular Constraint(v1,v2) and its reaction
torque as Reaction Torque(v1,v2).
An Angular Constraint is given as .
3. A Sliding constraint is a constraint between a spanning vector and a direction fixed in a MBE. A
spanning vector is defined as the spatial vector from the origin of marker i to the origin of marker j.
A sliding constraint ensures that a spanning vector remains perpendicular to the vector fixed in a
MBE. This constraint is enforced by 1 equation that sets the dot product between the spanning vector
and the fixed vector to zero. Introduction of this equation in a model causes a variable in the form of
a constraint reaction force to be included in the model. In Table 3, the equation for this constraint is
denoted as Sliding_constraint(s,v1) and the reaction force by Reaction_force(s,v1).
A Sliding constraint is given as .

4. A Rotation/Translation Dependency Constraint requires the angular displacement between two
markers with common z-axes to be a constant (pitch) times the translational displacement between
the origins of these markers. This constraint is represented by one equation and has a corresponding
reaction force. In Table 3, this constraint is represented as Rotation/Translation Dependency and the
reaction force as Reaction Force(). Equation for a Rotation/Translation Dependency Constraint is
given as , where s is the distance travelled along the z-axis, α is the angle of rotation,
and p is the user specified pitch.
Table 3 Force Debug Descriptions
EQUATIONS VARIABLES
Element
FIELD, Dx x-displacement equation Dx Element x-displacement 7
BEAM,
BUSHIN Dy y-displacement equation Dy Element y-displacement 7
G
Dz z-displacement equation Dz Element z-displacement 7
Theta x Equation for rotational Theta x Rotational displacement 7
displacement about x-axis about x-axis
Theta y Equation for rotational Theta y Rotational displacement 7
displacement about y-axis about y-axis
32 Adams Solver
EQUATIONS VARIABLES
Element
Theta z Equation for rotational Theta z Rotational displacement 7
displacement about z-axis about z-axis
Fx x-direction force equation Fx Force in the global-x 5
direction
Fy y-direction force equation Fy Force in the global-y 5
direction
Fz z-direction force equation Fz Force in the global-z 5
direction
Tx x-axis torque equation Tx Torque about the global x- 6
axis
Ty y-axis torque equation Ty Torque about the global y- 6
axis
Tz z-axis torque equation Tz Torque about the global z- 6
axis
GFORCE Fx x-force equation Fx Force in the x direction 5
Fy y-force equation Fy Force in the y direction 5
Fz z-force equation Fz Force in the z direction 5
Tx x-torque equation Tx Torque in the x direction 6
Ty y-torque equation Ty Torque in the y direction 6
Tz z-torque equation Tz Torque in the z direction 6
NFORCE Fx x-force equation Fx Force in x direction 5
Fy y-force equation Fy Force in y direction 5
Fz z-force equation Fz Force in z direction 5
Tx x-torque equation Tx Torque about x-axis 6
Ty y-torque equation Ty Torque about y-axis 6
Tz z-torque equation Tz Torque about z-axis 6
Translatio Length Equation for distance Length Distance between I and J 7
nal between I and J markers markers
SFORCE
Force Equation for element Force Force in element 7
force
Fx x-force equation Fx Force in x direction 5
DEBUG 33
EQUATIONS VARIABLES
Element
SFORCE
Translatio Length Equation for distance Length Distance between I and J 7
nal between I and J markers markers
Springda
mper
L Vel Equation for velocity in L Vel Element velocity 7
element
Fx x-force equation Fx Force in x direction 5
Springda
mper
VFORCE Fx x-force equation Fx Force about the x-direction
Fy y-force equation Fy Force about the y-direction
Fz z-force equation Fz Force about the z-direction
VTORQ Tx x-torque equation Tx Torque about the x-axis
UE
Ty y-torque equation Ty Torque about the y-axis
Tz z-torque equation Tz Torque about the z-axis
Notes
5. Force equations and variables: forces are defined via explicit force equations. These equations take the
general form of:
Force_variable - Force_expression = 0
where:
• Force_variable denotes the force in the x, y or z direction, respectively.
• Force_expression is an expression defining the force in terms of state variables and user defined
coefficients.
6. Torque equations are defined in a manner similar to force equations. These equations take the form
of:
Torque_variable - Torque_expression = 0
where:
34 Adams Solver
• Torque_variable denotes the torque in the element in the x, y, or z direction, respectively.

• Torque_expression defines the torque in term of state variables and user defined coefficients.
7. In addition to force and torque equations, element-specific equations and variables can be used to
define force elements. Typically these equations are to define intermediate kinematic quantities used
in force and torque computation.
Table 4 System Elements Debug Descriptions
EQUATIONS VARIABLES
Element
DIFF Differential Equation for the ODE User Variable for the solution of
Equation Variable the ODE
GSE States x· j General, first order state State xj Variables for the solution to
of states
Outputs yj Algebraic equations for 1 ≤ j ≤ Outputs yj Variables for the values of
number of outputs the output equations.
LSE States x· j First order linear state State xj Variables for the solution to
of states
Outputs yj Linear algebraic equations for Outputs yj Variables for the values of
1 ≤ j ≤ number of outputs the linear equations.
TFSISO State x· j Linear, first order, differential State x· j Values of the states for the
equations for the single-input, single-input, single-output
single-output transfer function transfer function.
x· = Ax + Bu for
1 ≤ j ≤ number of states.
Output y Linear equation y = Cx + Du in Output y Values of the output for the
terms of the states x and the transfer function.
input u.
VARIABLE Algebraic Equation for the variable Algebraic Value of the variable
Equation Variable
DEBUG 35
Table 5 Miscellaneous Elements Debug Descriptions
EQUATIONS VARIABLES
Element
COUPL f(γ1,γ2,γ3) Constraint relating joint l Reaction force
ER =0 displacements
CVCV x At point constraint (x) x Force Reaction force (x) 2
y At point constraint (y) y Force Reaction force (y) 2
z At point constraint (z) z Force Reaction force (z) 2
T i • Nj Constraint to force the tangent to TN Constraint torque
curve 1 to be perpendicular to Torque variable
normal to curve 2
Perpendicular constraint for curve 1 F-α Constraint force on
curve 1
Perpendicular constraint for curve 2 F-β Constraint force on
curve 2
a Equation for the parameter for a Parameter for curve
curve 1 1
b Equation for the parameter for b Parameter for curve
curve 2 2
· ·
α Equation for the first derivative of α First derivative of
the first curve parameter the first parameter
· ·
β Equation for the first derivative of β Second derivative of
the second curve parameter the first parameter
·· ··
α Equation for the second derivative α First derivative of
of the first curve parameter the second
parameter
·· ··
β Equation for the second derivative β Second derivative of
of the second curve parameter the second
parameter
GEAR f(γ1,γ2)=0 Constraint relating displacements l Reaction force
(γ) in two joints
MOTIO γ-f(t)=0 Joint displacement γ specified as a l Reaction force
N function of time
PTCV x At point constraint (x) x Force Reaction force (x) 2
y At point constraint (y) y Force Reaction force (y) 2
z At point constraint (z) z Force Reaction force (z) 2
Perpendicular constraint F-α Constraint force
36 Adams Solver
EQUATIONS VARIABLES
Element
a Equation for the curve a Curve parameter
· ·
α Equation for the first derivative α Derivative of the
curve parameter
·· ··
α Equation for the second derivative α Second derivative
UCON f(Q)=0 Constraint on system states Q l Associated reaction
force
JMDUMP Format
Adams Solver constantly needs to solve a linear problem JX=b where J stands for Jacobian matrix. Option
JMDUMP will send a representation of the Jacobian matrices to a file. The representation depends on
whether the MATLAB option is used or not. If the MATLAB option is used, then all Jacobian matrices will
be dumped using ready-to-use MATLAB code that can be copied and pasted. For example:
RC Analysis
Jacobian Matrix Statistics for the Pos. Constraints
=====================================================
J = zeros(5,6);
J( 1, 1) = 1;
J( 2, 2) = 1;
J( 3, 3) = 1;
J( 1, 4) = -10;
J( 3, 5) = 10;
J( 5, 5) = -1;
J( 4, 6) = 1;
The first two lines stand for the name of the analysis being done (in this example the Redundant Constraint
Analysis) and a brief description of the Jacobian. Next, the MATLAB representation of the matrix is printed.
Notice that only the nonzero entries are exported.
Usually matrices are square. However, the Redundant Constraint analysis uses a rectangular matrix and no
actual JX=b solution is needed.
In the case of transient simulations, the title has three lines to include the time at which the Jacobian is
exported. For example:
Time: 0.003
Gstiff Integrator...
Jacobian Matrix Statistics for the Corrector Stage
=====================================================
J = zeros(22,22);
J( 4, 6) = 1000;
J( 13, 6) = 1;
DEBUG 37
J( 5, 5) = 1000;
J( 15, 5) = 1;
J( 6, 4) = 1000;
J( 17, 4) = 1;
J( 3, 1) = 10000;
J( 6, 1) = -1;
J( 18, 1) = 1;
…
For Dynamic Analysis and other solutions, the Jacobian matrix is square as shown above.
In case the MATLAB option is not used, the format of the Jacobian is the following. First, a title section is
printed (similar as the case of using the MATLAB option) followed by the contributions of each modeling
element. The contribution of each modeling element starts with the name of the element and five columns.
The first column is labelled NP (standing for n-th position). The values of NP are 1 to the number of entries
into the Jacobian matrix the element is contributing to. For example:
Displacement solution for IC analysis

Jacobian Matrix Statistics for the Iteration: 1
=====================================================
NP NPOSR NPOSC
1 0 0 Part/2 X Force Part/2 X Disp
2 1 1 Part/2 Y Force Part/2 Y Disp
3 2 2 Part/2 Z Force Part/2 Z Disp
4 3 3 Part/2 Psi Torque Part/2 Psi Angle
5 4 4 Part/2 Phi Torque Part/2 Phi Angle
6 5 5 Part/2 Theta Torque Part/2 Theta Angle
NP NPOSR NPOSC
7 3 6 Part/2 Psi Torque RevJnt/1 LM X Delta
8 4 6 Part/2 Phi Torque RevJnt/1 LM X Delta
9 5 6 Part/2 Theta Torque RevJnt/1 LM X Delta
10 0 6 Part/2 X Force RevJnt/1 LM X Delta
11 6 3 RevJnt/1 X Delta Part/2 Psi Angle
12 6 4 RevJnt/1 X Delta Part/2 Phi Angle
13 6 5 RevJnt/1 X Delta Part/2 Theta Angle
14 6 0 RevJnt/1 X Delta Part/2 X Disp
…
Notice here that Part/2 contributes with 6 entries into the Jacobian matrix for Initial Conditions analysis.
The revolute joint RevJnt/1 contributes with another set of entries starting at NP equal to 7. The first column
NP is the index of a Jacobian entry. The second and third column show the row and column location of each
entry. The values of rows and columns is zero-based. Finally, the fourth and fifth columns display the name
of the equation the entry belongs to, and the name of the corresponding state of the solution.
After the maps for all elements are printed, the actual values of all entries follow. For each element a list of
entry-value is printed. For example:
38 Adams Solver
NP G(NP)
1 1.00000E+000 2 1.00000E+000 3 1.00000E+000 4 1.00000E+000
5 1.00000E+000 6 1.00000E+000
NP G(NP)
7-1.00000E+001 8 0.00000E+000 9 0.00000E+000 10 1.00000E+000
11-1.00000E+001 12 0.00000E+000 13 0.00000E+000 14 1.00000E+000
15 0.00000E+000 16 0.00000E+000 17 0.00000E+000 18 1.00000E+000
19 0.00000E+000 20 0.00000E+000 21 0.00000E+000 22 1.00000E+000
…
Notice subtitle ‘NP G(NP)’ stands for the n-th position (NP) and the corresponding G(NP) value for the
Jacobian entry.
There is fundamental difference between the default dump format and the dump using the MATLAB option.
In the default format, zero entries may be included in both the map and value tables. Moreover, the map and
value tables may include entries that contribute to the same position in the Jacobian matrix. The MATLAB
option only shows the total value at each entry and it does not print a mapping to show the individual
contributions of the modeling elements.
RHSDUMP Format
For analyses that require solving a linear problem JX=b, option RHSDUMP will send a representation of the
current state values, the actual right-hand side b in equation JX=b, and the value of X after the solution. This
information is printed at each iteration. For example, if using the MATLAB option, a typical output is as
follows:
Time: 0
====================================================
States
====================================================
x(1) = 0.000000000000E+000;
x(2) = -5.000000000000E+000;
x(3) = 0.000000000000E+000;
x(4) = 1.570796326795E+000;
x(5) = 0.000000000000E+000;
...

====================================================
Equations
====================================================
rhs(1) = 0.000000000000E+000;
rhs(2) = 0.000000000000E+000;
rhs(3) = 0.000000000000E+000;
rhs(4) = 0.000000000000E+000;
rhs(5) = 0.000000000000E+000;
...
DEBUG 39

====================================================
Equations
====================================================
rhs(1) = 2.514146621547E-016;
rhs(2) = -5.000000000000E+000;
rhs(3) = -6.123233995737E-016;
rhs(4) = -2.464849628968E-017;
rhs(5) = 1.224646799147E-016;
...
Notice, first the states value are printed in a MATLAB array x. Next, array rhs shows the values of b in
equation JX=b (hence the label RHS shown in the title for this array). Finally, the third set shows the solution
X reusing array rsh. Given that the actual solution X usually stands for an incremental correction to the states,
we use the label Delta in the title for this set.
If the MATLAB option is not used, the output looks similar. For example:
Time: 0
====================================================
States
====================================================
1 Part/2 X Disp 0.0000000000E+000
2 Part/2 Y Disp -5.0000000000E+000
3 Part/2 Z Disp 0.0000000000E+000
4 Part/2 Psi Angle 1.5707963268E+000
5 Part/2 Phi Angle 0.0000000000E+000
...

====================================================
Equations
====================================================
1 Part/2 X Force 0.000000000000E+000
2 Part/2 Y Force 0.000000000000E+000
3 Part/2 Z Force 0.000000000000E+000
4 Part/2 Psi Torque 0.000000000000E+000
5 Part/2 Phi Torque 0.000000000000E+000
...

====================================================
Equations
====================================================
1 Part/2 X Force 2.514146621547E-016
2 Part/2 Y Force -5.000000000000E+000
3 Part/2 Z Force -6.123233995737E-016
4 Part/2 Psi Torque -2.464849628968E-017
40 Adams Solver
5 Part/2 Phi Torque 1.224646799147E-016

...
In this case, each group of information shows three columns, the first column shows the index of the state or
the name of the corresponding equation, the second the name of the corresponding state or equation. The
third column shows the corresponding value.
EQUILIBRIUM 41
EQUILIBRIUM
An EQUILIBRIUM command redefines and/or lists the data for an EQUILIBRIUM statement. If an
EQUILIBRIUM statement is not included in the Adams Solver model and an EQUILIBRIUM command
is not issued prior to a static or quasi-static simulation, Adams Solver (FORTRAN) uses the default values
for ALIMIT, ERROR, IMBALANCE, MAXIT, PATTERN, STABILITY, and TLIMIT for the analysis.
Format
42 Adams Solver
Arguments
ACCELERATION_ERROR=r Specifies the maximum acceleration error allowed during static

Range: ACCELERATION_ERROR > 0

ALIMIT=r Specifies the maximum angular increment allowed per iteration
during static simulations performed using static analyses. The default
units for ALIMIT are radians. To specify ALIMIT in degrees, add a D
after the value.
Range: ALIMIT > 0

DEFAULT Resets all options to the default values specified in the EQUILIBRIUM
statement, namely:
STATIC
ALIMIT = 10D
ERROR = 1.0
IMBALANCE = 1.0E-4
MAXIT = 25
STABILITY = 1.0E-5
TLIMIT = 20
DYNAMIC Specifies that Adams Solver (FORTRAN) perform static simulations
using dynamic analyses.
ERROR=r Specifies the maximum relative displacement error during static
simulations performed using static analyses.
Range: ERROR > 0

GLOBAL_DAMPING=r Applies the coefficient for global damping to all bodies during static
Range: GLOBAL_DAMPING > 0

IMBALANCE=r Specifies the maximum force imbalance during static simulations
performed using static analyses.

KINETIC_ENERGY_ERROR=r Specifies the maximum kinetic energy error allowed in static
Range: KINETIC_ENERGY_ERROR > 0

EQUILIBRIUM 43
LIST Lists the current values of the data in the EQUILIBRIUM statement.
MAXIT=r Specifies the maximum number of iterations allowed for finding static
equilibrium during static simulations performed using static analyses.
Range: MAXIT > 0

PATTERN=c1[:...:c10] Specifes as many as ten character strings that together establish the
pattern for evaluating the Jacobian matrix during the modified
Newton-Raphson iteration. For each iteration, T or TRUE indicates
that Adams Solver (FORTRAN) evaluates the Jacobian and F or
FALSE indicates that Adams Solver (FORTRAN) does not evaluate
the Jacobian for static simulations performed using static analyses.
Thus, cj determines whether or not Adams Solver (FORTRAN)
evaluates the Jacobian at the jth iteration. If necessary, Adams Solver
(FORTRAN) repeats the pattern of evaluations until it reaches the
maximum number of iterations (MAXIT). The number of Ts or
TRUEs and Fs or FALSEs together must be at least one and no more
than ten.
SETTLING_TIME=r Specifies the maximum time allowed to reach equilibrium during
static simulations performed using dynamic analyses.
Range: SETTLING_TIME > 0

equilibrium Jacobian matrix) Adams Solver adds to the stiffness
matrix (a subset of the equilibrium Jacobian matrix) during static
simulations performed using static analyses. Adding a fraction of the
mass and damping matrices to the stiffness matrix can stabilize the
iteration process and prevent the iteration from diverging. Often the
stiffness matrix is singular for a system because the system is neutrally
stable (for example, the system moves in certain directions without
affecting the potential energy). Adding a fraction of the mass and
damping matrices to the stiffness matrix removes this singularity and
makes it possible to solve for equilibrium positions. The value of
STABILITY does not affect the accuracy of the solution, but it does
affect the rate of convergence of the iteration process.
Range: STABILITY > 0

STATIC Specifies that Adams Solver (FORTRAN) perform static simulations
using static analyses.
TLIMIT=r Specifies the maximum translational increment allowed per iteration
during static simulations performed using static analyses.
Range: TLIMIT > 0

44 Adams Solver
Extended Definition
For an extended definition on the EQUILIBRIUM command and corresponding tips, cautions, and
examples, refer to the EQUILIBRIUM statement.
FIELD 45
FIELD
The FIELD command redefines and/or lists the data for a FIELD statement. You cannot redefine the I and the
J markers, but you can redefine any other argument values.
Format
Arguments
CMATRIX=r1,...,r36 Respecifies the six-by-six matrix of viscous damping coefficients. Enter

The units for the translational and rotational components of
CMATRIX should be force-time per displacement unit and torque-
time per radian, respectively.
CRATIO=r Respecifies the ratio of CMATRIX to KMATRIX. Adams Solver
(FORTRAN) multiplies KMATRIX by CRATIO to obtain
CMATRIX.
FORCE=r1,...,r6 Respecifies three preload force components and three preload torque
components transferred by the FIELD element when the I and J
markers are separated/misaligned by the values specified in the
LENGTH argument. The terms r1,...,r6 are the force components
along the x-axis, the y-axis, and the z-axis of the J marker and the
torque components about the x-axis, the y-axis, and the z-axis of the J
marker, respectively. FORCE is optional.
46 Adams Solver
FUNCTION=USER(r1[,...,r30]) Respecifies the USER parenthetical list for a nonlinear field. Follow
FUNCTION with an equal sign, the character string USER, and the
values (r1[,...,r30]) that you want Adams Solver (FORTRAN) to pass
to the FIESUB user-written subroutine.The FUNCTION argument
is used, it must either be the last argument in the FIELD command or
be followed by a backslash (\).
KMATIX=r1,...r36 Respecifies the six-by-six matrix of stiffness coefficients. The units for
the translational and rotational components of KMATRIX should be
force per displacement unit and torque per radian, respectively. Enter
LENGTH=r1,...r6 Respecifies six reference length angles. This is the nominal position of
the I marker with respect to the J marker, resolved in the J marker
coordinate system. The terms r1,...,r6 are the x, y, and z translational
components (specified in linear displacement units) of the
displacement between the I and J markers; and a, b, and c are
rotational displacement of the axes of the I marker with respect to the
J marker, resolved in the J marker axes (specified in radians). If the
reference force is zero, LENGTH is the same as the free length.
LIST Lists the current values of the data in the FIELD statement.
FIESUB.
Tip: Finite element analysis programs can give the values for CMATRIX and KMATRIX.
FIELD 47
Caution:  The three rotational displacements (a, b, and c) that define the field are not Euler
angles. They are the projected angles of the I marker with respect to the J marker.
Adams Solver (FORTRAN) measures them about the x-, y-, and z-axis of the J
marker.
 For the constitutive equations to be accurate, at least two of the rotations (a, b, c)
must be small. That is, two of the three values must remain smaller than 10 degrees.
In addition, if a becomes greater than 90 degrees, b becomes erratic. If b becomes
greater than 90 degrees, a becomes erratic. Only c can become greater than 90 degrees
without causing convergence problems. For these reasons, it is best to define your
field such that angles a and b (not a and c and not b and c) remain small.
 Adams Solver (FORTRAN) applies the component translational and rotational forces
for a field to the I marker and imposes reaction forces on the J marker.
 The FIELD command allows you to define all six-component, action-reaction forces.
However, when massless beams are being defined, you may want to use the BEAM
command. It requires only six input values to compute the thirty-six values for the
KMATRIX argument (see the BEAM statement).
 The K and C matrices must be postitive semidefinite. In other words, xtK x > 0 for all
displacements x, and ytC y > 0 for all velocities y.
If this is not true, the stiffness matrix of the field may be removing energy from the
system. Similarly, the damping matrix may be adding energy to the system. Both of
these situations are uncommon. Adams Solver (FORTRAN) does not warn you if the
C matrix, K matrix, or both are not positive semidefinite. While Adams Solver
(FORTRAN) does not require that these matrices be symmetric, that is most realistic.

48 Adams Solver
FILE
The FILE command loads a new model from a dataset file, or executes commands from a Command file.
Format
FILE 49
Arguments
COMMAND=c Specifies the file name of a file that contains Adams Solver (FORTRAN)
commands. The file name may include the directory on operating systems that
support path names, such as Linux. Adams Solver (FORTRAN) assumes an .acf file
extension if you do not specify one. Because the COMMAND argument and value
can be at most eighty characters long, the file name and path name are limited from
seventy-two characters (if you do not abbreviate COMMAND=) to seventy-six
characters (if you abbreviate COMMAND= to COM=).
MODEL=c Specifies the file name of an Adams Solver (FORTRAN) model definition file.
The file name may include the directory on operating systems that support path
names, such as Linux. Adams Solver (FORTRAN) assumes an .adm file extension
if you do not specify one. Because the argument and value can be at most eighty
characters long, the file name and path are limited from seventy-three characters (if
you do not abbreviate MODEL=) to seventy-six characters (if you abbreviate
MODEL= to MOD=).
OUTPUT_PREFIX=c Optionally, specifies a new file base name for output files that Adams Solver
(FORTRAN) generates by subsequent simulations. The file extensions conform to
standard Adams Solver (FORTRAN) naming conventions. If you do not specify an
OUTPUT_PREFIX argument, Adams Solver (FORTRAN) defaults to the
basename of the MODEL argument. Because the OUTPUT_PREFIX argument
and value can be at most eighty characters long, the basename and path are limited
from sixty-six characters (if you do not abbreviate OUTPUT_PREFIX) to seventy-
six characters (if you abbreviate OUTPUT_PREFIX to OUT=).
Extended Definition
The FILE command either restarts Adams Solver (FORTRAN) with a new model, or a executes a set of
commands from a file.
The MODEL argument specifies a new dataset (.adm) file. Adams Solver (FORTRAN) closes any output
files from a previous simulation, and then completely restarts by setting the simulation time to zero and
reading the new model. Next, Adams Solver (FORTRAN) prompts you for a new command, just as if Adams
Solver (FORTRAN) had read the model when first started. By default, the output files use the same base
name as the model file. The optional OUTPUT_PREFIX argument specifies a different base name, if
needed.
The COMMAND argument specifies a file containing Adams Solver (FORTRAN) commands. Adams
Solver (FORTRAN) reads and executes the commands in the file. If the FILE command was interactive,
50 Adams Solver
Adams Solver (FORTRAN) returns to interactive input when the command file is exhausted. If the FILE
command was in a command file itself, Adams Solver (FORTRAN) returns to reading commands from that
file. Command files can contain other FILE commands, nested up to 10 files deep.
Tip:  The FILE/MODEL= command allows you to execute a series of simulations within
one Adams Solver (FORTRAN) run. This may be quicker and more convenient than
invoking Adams Solver (FORTRAN) separately for each simulation.
 Although the FILE command may be used to repeatedly reload the same model, the
SAVE and RELOAD combination is much quicker than rereading the original
dataset.
Caution: The COMMAND argument does not automatically load a new model, it executes commands
just as they appear in the specified file. Unlike a Command file used to start Adams Solver
(FORTRAN), a Command file read here must start with an Adams Solver (FORTRAN)
command, not input and output file names.
Examples
FILE/MODEL=TURN45
This FILE command loads dataset TURN45.ADM. The output files default to TURN45.REQ,
TURN45.GRA, etc.
FILE/MODEL=TURN45,OUTPUT_PREFIX=TEST2
This FILE command also loads dataset TURN45.ADM, but the output files are TEST2.REQ,
TEST2.GRA, etc.
FLEX_BODY 51
FLEX_BODY
The FLEX_BODY command redefines and/or lists the data for the FLEX_BODY statement that defines linear
elastic body.
Format
Arguments
Redefines modal damping as a fraction of critical damping. You can

e specify a function expression or USER and the values
 
CRATIO =   (r1[,..., r30]), which indicate a call to the DMPSUB user-written
 USER ( r 1 [ ,…, r 30 ] )  subroutine.
If you omit CRATIO, Adams Solver (FORTRAN) applies default

damping as follows:

LIST Lists the current values of the FLEX_BODY arguments and lists inertia
information about the FLEX_BODY to facilitate the replacement of it
with an equivalent PART.

52 Adams Solver
FRICTION
The FRICTION command defines parameters that enable joint friction forces on translational, revolute,
cylindrical, hooke, universal, and spherical joints.
Note: Frictional forces and torques are computed by Adams Solver (FORTRAN) using a friction
model that supports dynamic frictions and stiction.
Format
FRICTION 53
Arguments
BALL_RADIUS=Rb Defines the radius of the ball in a spherical joint for use in
friction-force and torque calculations.

STICTION_TRANSITION_VELOCITY Defines the absolute velocity threshold for the transition
=r from dynamic friction to static friction. If the absolute
relative velocity of the joint marker is below
STICTION_TRANSITION_VELOCITY, then static
friction or stiction acts to make the joint stick.

EFFECT={ALL[[STICTION, SLIDING]]} Defines the frictional effects included in the friction model.
Stiction is static-friction effect, while sliding is dynamic-
friction effect. Excluding stiction in simulations that don’t
require it can greatly improve simulation speed.
FRICTION_FORCE_PRELOAD=r Defines the joint’s preload frictional force, which is usually
caused by mechanical interference in the assembly of the
joint.

FRICTION_ARM=Rn, Defines the effective moment arm used to compute the axial
component of the friction torque in revolute, Hooke, and
universal joints.

INACTIVE=STATIC Specifies that frictional forces not be calculated for a static
or quasi-static solution.
Range: STATIC
INITIAL_OVERLAP=Xs0 Defines the initial overlap of the sliding parts in either a
translational or cylindrical joint. The joint's bending
moment is divided by overlap to compute the bending

54 Adams Solver
INPUTS=( {ALL, NONE [[PRELOAD: Defines the input forces to the friction model. By default,
REACTION_FORCE: all user-defined preloads and joint-reaction force and
BENDING_MOMENT: moments are included. You can customize the friction-force
TORSIONAL_MOMENT]]} ) model by limiting the input forces you list in the statement.
Joint type: (Available inputs:)
Translational (PRELOAD, REACTION_FORCE,

BENDING_MOMENT, TORSIONAL_MOMENT)
Cylindrical, Revolute, Universal, Hooke (PRELOAD,

REACTION_FORCE, BENDING_MOMENT)

JOINT=id Identifies the JOINT to which frictional forces apply.
MAX_STICTION_DEFORMATION=r Defines the maximum creep that can occur in a joint during
the stiction regime. The creep allows Adams Solver
(FORTRAN) to impose the Coulomb conditions for
Therefore, even at zero velocity, a finite stiction force is

applied if your system dynamics requires it.

MU_DYNAMIC=r Defines the coefficient of dynamic friction during the
sliding regime. The magnitude of the frictional force is the
product of MU_DYN and the magnitude of the normal
force in the joint, for example:
The dynamic frictional force acts in the opposite direction

of the velocity of the joint.

LIST Lists the current values of the FRICTION statement.
FRICTION 55
MU_STATIC=r Defines the coefficient of static friction in the joint. The

magnitude of the frictional force is the product of a function
of MU_STATIC, MU_DYNAMIC, and the creep, times
the magnitude of the normal force in the joint, for example:
Friction Force Magnitude, F= μN
where μ = ƒ (MU_STATIC, MU_DYNAMIC, creep) and

N = normal force
The static frictional force acts to oppose the net force or

torque along the degrees of freedom of the joint.

OVERLAP_DELTA={INCREASE, To define friction in a sliding joint (either a translational or
DECREASE, CONSTANT} a cylindrical joint), Adams Solver (FORTRAN) computes
the overlap of the joint. As the joint slides, the overlap can
increase, decrease, or remain constant. OVERLAP_DELTA
is used to define any change in overlap.
 INCREASE indicates that overlap increases as the I

Marker translates in the positive direction along the
J Marker; the slider moves to be within the joint.
 DECREASE indicates that the overlap decreases
with positive translation of the joint; the slider
moves outside of the joint.
 CONSTANT indicates that the amount of overlap
does not change as the joint slides; all of the slider
remains within the joint.
PIN_RADIUS=Rp Defines the radius of the pin for a revolute, cylindrical,
Hooke, or universal joint.

56 Adams Solver
REACTION_ARM=Rn Defines the effective moment arm of the joint-reaction

torque about the translational joint’s axial axis (the z-
direction of the joint’s J marker). This value is used to
compute the contribution of the torsional moment to the
net frictional force.

FRICTION_TORQUE_PRELOAD=r Defines the preload friction torque in the joint, which is
usually caused by mechanical interference in the assembly of
the joint.

I_YOKE I_YOKE and J_YOKE define the rotational constraint on
J_YOKE which the FRICTION statement acts. I_YOKE identifies
the yoke to the I marker’s rotational constraint. Likewise,
J_YOKE identifies the yoke to the J marker’s rotational
constraint. These keywords are used with only Hooke and
UNIVERSAL joints.
Extended Defintion
For an extended definition on the statement associated with this command, see the FRICTION statement.
Caution: You cannot apply friction to JOINTs that connect to FLEX-BODYs or POINT_MASSes.
Examples
FRICTION/102, INPUTS=NONE
This command turns off the friction calculations of FRICTION/102.
GFORCE 57
GFORCE
The GFORCE command redefines and/or list the data for a GFORCE statement that defines a force element
that consists of three orthogonal translational force components and three orthogonal torque components.
Format
Arguments
FUNCTION=USER(r1[,...,r30]) Respecifies up to thirty user-defined constants to compute the force

GFORCE translational force. Adams Solver (FORTRAN) applies this
force parallel to the x-axis of the RM marker.
force parallel to the y-axis of the RM marker.
force parallel to the z-axis of the RM marker.
58 Adams Solver
I=id Respecifies the marker at which Adams Solver (FORTRAN) applies the
forces and torques. You must ensure that the I marker is a fixed marker
and on a different part than the JFLOAT marker. Because I is a fixed
marker, Adams Solver (FORTRAN) always applies the force at a fixed
point on the part containing the I marker.
JFLOAT=id Respecifies the marker at which Adams Solver (FORTRAN) applies the
superimposed on the I marker, meaning the point of application of the
reaction force may move with respect to its part. Adams Solver
(FORTRAN) does not calculate reaction forces when the JFLOAT
marker is on the ground part.
LIST Lists the current values of the GFORCE arguments.
RM=id Respecifies the marker and therefore the coordinate system in which the
force and torque components are specified. You must ensure that RM
is a fixed marker. RM may be the same as I and may be fixed on any part
in your system.
GFOSUB.

TX=e Respecifies the magnitude and sign of the x component of the
GFORCE rotational torque. Adams Solver (FORTRAN) applies this
torque parallel to the x-axis of the RM marker in the sense of the right-
hand rule (that is, a positive torque causes a counterclockwise rotation).
TY=e Respecifies the magnitude and sign of the y component of the
torque parallel to the y-axis of the RM marker in the sense of the right-
TZ=e Respecifies the magnitude and sign of the z component of the
torque parallel to the z-axis of the RM marker in the sense of the right-
Extended Definition
The GFORCE command lists or redefines a force element that consists of three mutually orthogonal
translational force components and three orthogonal torque components. You can alter one or both points
of force and torque application, change the force reference marker, and change the force and torque function
expressions or the parameters passed to the GFOSUB user-written subroutine.
After a change to a GFORCE, Adams Solver (FORTRAN) reprocesses the model at the next SIMULATE
command, as if it had just been read in from the dataset. During the reprocessing, Adams Solver
GFORCE 59
conditions.
While checking, Adams Solver (FORTRAN) verifies that the model is still valid with the new GFORCE. If,
for example, the GFORCE function expression refers to an inactive element, Adams Solver (FORTRAN)
issues an error.
Adams Solver also reinitializes all user subroutines to re-establish functional dependencies. For each element
that refers to a user-written subroutine, Adams Solver calls the user-written subroutine with IFLAG set to
true.
Prior to the actual simulation, Adams Solver computes initial conditions for the model. If this is the first
simulation, Adams Solver begins with the positions and velocities specified in the dataset. If you ran a
previous simulation, Adams Solver begins with the final displacements and velocities. Adams Solver then
adjusts the initial conditions to ensure that they are consistent with the model constraints. If this is the first
simulation, Adams Solver also maintains any user supplied joint initial-conditions and positions specified as
EXACT.
If you change a GFORCE I marker, J marker, or type in the middle of a simulation, by default Adams Solver
(FORTRAN) splits the tabular, request, graphics, and results output into two separate sets of output
concatenated together. This ensures that the output correctly reflects the new system topology. Adams Solver
(FORTRAN) does not split the files if you change only the GFORCE function expression.
argument.
Caution: The user-defined functions FX, FY, FZ, TX, TY, and TZ should be smooth, continuous, and
Examples
FY = 0/ &
FZ = 0/ &
TY = 0/ &
TZ = 0
This GFORCE command redefines and lists the general, six-component force acting between fixed Marker
310 and floating Marker 9910. The force and torque components FY, FZ, TY, and TZ are set to zero along
the y and z axes of the reference marker, which is Marker 310. Adams Solver (FORTRAN) superimposes
floating Marker 9910 on Marker 310 and applies the FX and TX reaction force and torque at that point.
60 Adams Solver
HELP
The HELP command opens the online help for Adams Solver.
To navigate through the help:
 Select a topic from the left.
IC 61
IC
The IC command redefines and/or lists the data for an IC statement. If you issue neither the IC command
nor statement in an Adams Solver (FORTRAN) session, Adams Solver (FORTRAN) uses the default values
for AERROR, ALIMIT, AMAXIT, APATTERN, ERROR, MAXIT, PATTERN, TLIMIT, and VERROR
when finding initial conditions.
Format
Arguments
AERROR=r Respecifies the maximum acceleration error Adams Solver (FORTRAN) is to

allow during an initial conditions solution or for reconciling INTEGRATOR
Range: AERROR > 0

ALIMIT=r Respecifies the maximum angular increment Adams Solver (FORTRAN) is to
allow while testing trial solutions for a set of consistent initial conditions which
satisfy all system constraints. The default units for ALIMIT are radians. To
specify ALIMIT in degrees, add a D after the value.
Range: ALIMIT > 0

AMAXIT=i Respecifies the maximum number of iterations Adams Solver (FORTRAN) is
to allow for finding accelerations during an initial conditions solution or for
reconciling INTEGRATOR acceleration output.
Range: AMAXIT > 0

62 Adams Solver
Adams Solver (FORTRAN) is to evaluate the Jacobian, and F or FALSE
indicates that Adams Solver (FORTRAN) is not to evaluate the Jacobian.
Thus, cj determines whether or not ADAMS is to evaluate the Jacobian at the
jth iteration. If necessary, Adams Solver (FORTRAN) repeats the pattern of
evaluation until it reaches the maximum number of iterations (AMAXIT). The
number of T's or TRUE’s and F’s or FALSE’s together must be at least one and
no more than 10.
DEFAULT Resets all options to the default values specified in the IC statement, namely:
AERROR = 1.0E-4
ALIMIT = 30D
AMAXIT = 25
APATTERN = T:T:T:T:T:T:T:T:T:T
ERROR = 1.0E-10
MAXIT = 25
TLIMIT = 1.0E10
VERROR = 1.0E-4
ERROR Respecifies the maximum displacement error Adams Solver (FORTRAN) is to
allow for the assembly process.
Range: ERROR > 0

LIST Lists the current values of the data in the IC statement.
MAXIT=i Respecifies the maximum number of iterations Adams Solver (FORTRAN) is
to allow for finding displacements during initial conditions, or when
reconciling INTEGRATOR displacement output.
Range: MAXIT > 0

IC 63
indicates that Adams Solver (FORTRAN) is not to evaluate the Jacobian.
Thus, cj determines whether or not ADAMS is to evaluate the Jacobian at the
jth iteration. If necessary, Adams Solver (FORTRAN) repeats the pattern of
evaluation until it reaches the maximum number of iterations (MAXIT). The
number of T’s or TRUE’s and F’s or FALSE’s together must be at least one and
no more than 10.
TLIMIT=r Respecifies the maximum translational increment Adams Solver is to allow
Range: TLIMIT > 0

VERROR=r Respecifies the maximum velocity error that Adams Solver is to ignore during
an initial conditions solution. If the value of VERROR is exceeded, Adams
Solver (FORTRAN) issues a warning. If
PREFERENCES/SIMFAIL=STOPCF is chosen, Adams Solver issues an error.
Range: VERROR > 0
Tip: Use the ALIMIT and TLIMIT arguments to limit the increments of the displacement
variables if Adams Solver (FORTRAN) fails to converge to a solution or converges to an
undesirable configuration. This lessens the position change on successive iterations, and tends
to keep the solution closer to the initial configuration.

64 Adams Solver
INFO
The INFO command lists the vector components for the displacement, velocity, or acceleration of one
marker with respect to another or displays force values at the current simulation time. This command resolves
components in the ground coordinate system (GCS) or in another specified reference frame.
Format
Arguments
ACCELERATION Lists the accelerations of the I marker minus the accelerations of the J marker. Adams
Solver (FORTRAN) reports translational accelerations in units of displacement per
time squared and rotational accelerations in units of radians per time squared.
DISPLACEMENT Lists the x, y, z, psi, theta, and phi displacements of the I marker with respect to the
J marker. Adams Solver (FORTRAN) reports translational displacements in units of
displacement and rotational displacements in units of radians.
FORCE Lists the components for the force at the I marker. A BEAM, BUSHING, CVCV,
FIELD, GFORCE, JOINT, JPRIM, MOTION, NFORCE, PTCV, SFORCE,
SPRINGDAMPER, VFORCE, or VTORQUE statement can define the force. You
should include both the I and the J arguments to measure the action-reaction
force(s) between two markers (I, J). You should include the I argument and either
give zero as the J argument or omit the J argument altogether to measure the action-
only force(s) at a marker (I).
I=id Specifies the identifier of the fixed or floating marker for which Adams Solver
(FORTRAN) is to measure displacements, velocities, accelerations, or action forces.
INFO 65
J=id Specifies the identifier of the fixed or floating marker with respect to which Adams
Solver (FORTRAN) is to measure the displacements, velocities, or accelerations of
the I marker, or the identifier of the marker for which Adams Solver (FORTRAN)
is to measure reaction forces.
RM=id Specifies the identifier of the fixed or floating marker relative to which Adams Solver
(FORTRAN) resolves displacements, velocities, accelerations, or forces. If a value for
the RM argument is not set or if the RM argument is set equal to zero, Adams Solver
(FORTRAN) resolves the displacements, velocities, accelerations, or forces in the
VELOCITY Lists the velocities of the I marker minus the velocities of the J marker. Translational
velocities are given in units of displacement per time. Rotational displacements are
given in units of radians per time.
Examples
INFO/ DISP, I=10, J=15, RM=43
This INFO command lists the x, y, z, psi, theta, and phi displacements of Marker 10 with respect to Marker
15. Adams Solver (FORTRAN) measures x, y, and z in the Cartesian coordinates of Marker 43.
INFO/ ACC, I=12, J=100
This INFO command lists the x, y, and z translational and rotational accelerations of Marker 12 with respect
to Marker 100. Adams Solver (FORTRAN) measures x, y, and z in the Cartesian coordinates of the ground
66 Adams Solver
INTEGRATOR
The INTEGRATOR command lets you redefine data in the INTEGRATOR statement.
Format
INTEGRATOR 67
Arguments
ABAM Specifies that the ABAM (Adams-Bashforth-Adams-Moulton) integrator is to be

used for integrating the differential equations of motion. This integrator is suitable
for systems that are not stiff; that is, systems that are characterized by undamped
transients.
ADAPTIVITY=r All of the BDF integrators (GSTIFF, WSTIFF, and CONSTANT_BDF) use
Newton-Raphson iterations to solve the nonlinear Differential-Algebraic equations
of motion. This iteration process is referred to as correcting the solution.
ADAPTIVITY modifies the corrector error tolerance to include a term that is
inversely proportional to the integration step size. This is intended to loosen the
corrector tolerance when the step size gets small (many corrector failures occur
because of small step size). If the integration step size is equal to h, ADAPTIVITY/h
is added to the corrector tolerance.
When using ADAPTIVITY, begin with a small number, such as ADAPTIVITY=1E-

8. Note that this relaxes the tolerance of the corrector, which can introduce additional
error into the dynamic solution. The corrector tolerance must be at least a factor of
10 stricter than the integration tolerance. The ratio advocated in the theoretical
literature ranges from .1 to .001 and is a function of the integrator order and step size.
The ratio that Adams Solver (FORTRAN) uses varies with the integrator chosen, but
is within the range specified above. If you use ADAPTIVITY to relax the corrector
tolerances, be sure to validate your results by running another simulation using a
different integration error tolerance.
ADAPTIVITY affects only the GSTIFF, WSTIFF, and CONSTANT_BDF

integrators.
ADAPTIVITY is typically required to overcome corrector convergence difficulties.

You should not use it in normal situations.
Range: ADAPTIVITY > 0

CONSTANT_BDF Specifies that the CONSTANT_BDF integrator is to be used for integrating the
68 Adams Solver
Specifies the corrector algorithm that is to be used with the stiff integrators GSTIFF,
 ORIGNAL  WSTIFF, or CONSTANT_BDF. The corrector in a stiff integrator ensures that all
CORRECTOR =   candidate solutions satisfy the equations of the system. The two algorithms, original
 MODIFIED 
and modified, differ primarily in how they assess when the corrector iterations have
converged.

previous releases of Adams Solver. This is the default. This implementation
of the corrector requires that at convergence, the error in all solution
variables be less than the corrector error tolerance.
 CORRECTOR=modified - Specifies that a modified corrector. This
implementation of the corrector requires that at convergence, the error in
only those variables for which integration error is being monitored, be less
than the corrector error tolerance. Because this is a slightly looser definition
of convergence, use proper care when using this option.
The CORRECTOR=modified setting is helpful for models containing

discontinuities in the forcing functions. Problems with contacts belong in
this category.
statement.
DEFAULT Resets the integrator parameters. See the default values in the INTEGRATOR statement.
ERROR=r Specifies the relative and absolute local integration error tolerances that the integrator
must satisfy at each step. For BDF integrators, Adams Solver (FORTRAN) monitors
the integration errors in the displacement and state variables that the other
differential equations (DIFFs, LSEs, GSEs, and TFSISOs) define. ABAM, SI1, and
SI2 formulations also monitor errors in velocity variables. The larger the ERROR, the
greater the error/step in your solution.
Note that the value for ERROR is units-sensitive. For example, if a system is modeled
in mm-kg-s units, the units of length must be in mm.
Assuming that all the translational states are larger than 1mm, setting ERROR=1E-
3 implies that the integrator monitors all changes of the order of 1 micron.
difference between the current predicted and corrected states, the past history of the
states, and the current integration order.
Default: 1E-3
Range: ERROR > 0
INTEGRATOR 69

Default: When setting the argument INTERPOLATE = ON, the integration step
size is limited to the value specified for HMAX, but if HMAX is not defined, no limit
is placed on the integration step size. If INTERPOLATE = OFF, the


INTERPOLATE=ON specifies that the integrator is not required to control its step
 ON  size to hit an output point. Therefore, when the integrator crosses an output point,
INTERPOLATE =   it computes a preliminary solution by interpolating to the output point. It then
 OFF 
refines or reconciles the solution to satisfy the equations of motion and constraint.
INTERPOLATE=OFF turns off interpolation for the chosen integrator.
Interpolation is not supported for CONSTANT_BDF or RKF45.

I3 Specifies the Index-3 (I3) formulation be used.

statement.
refers to the order of the polynomials used in the solution. The integrator controls
the order of the integration and the step size, and therefore, controls the local
integration error at each step so that it is less than the error tolerance specified.
Note: For problems involving discontinuities, such as contacts, setting KMAX=2

can improve the speed of the solution. However, we do not recommend
Any modification can adversely affect the integrator’s accuracy and
robustness.
Range: 1 < KMAX < 12 (ABAM);
1 < KMAX < 6 (GSTIFF, WSTIFF, and CONSTANT_BDF)
Note: KMAX is not applicable to RKF45.
LIST Lists current values of the integrator arguments.
70 Adams Solver
iterations to converge to the solution of the nonlinear equations. The correctors in
GSTIFF and WSTIFF use the Newton-Raphson iterations. ABAM also uses
Newton-Raphson iterations to solve for the dependent coordinates.
MAXIT should not be set larger than 10. This is because round-off errors increase
when a large number of iterations are taken. This can cause an error in the solution.
Range: MAXIT > 0

Newton-Raphson. A value of true (T) indicates that Adams Solver (FORTRAN) is
evaluating a new Jacobian matrix for that iteration. A value of false (F) indicates that
Adams Solver (FORTRAN) is using the previously calculated Jacobian matrix as an
PATTERN accepts a sequence of at least 1 character string and not more than 10
character strings. Each string must be either TRUE or FALSE, which you can
Note: A pattern setting of all false, implies that Adams Solver (FORTRAN) is not
to evaluate the Jacobian until it encounters a corrector failure. For
problems that are linear or almost linear, this setting can improve
RKF45 Specifies that a Runge-Kutta-Fehlberg (4,5) method be used to integrate the
differential equations governing the system being modeled. RKF45 is a single-step
method unlike the BDF methods (GSTIFF, WSTIFF, or CONSTANT_BDF) or
ABAM. It is primarily designed to solve non-stiff and mildly stiff differential
equations when derivative evaluations are not expensive. In general, you should not
use it to get highly accurate results or answers at many specific points.
Internally, RKF45 uses the DDERKF integrator written by L.F. Shampine and H.A.
Watts. DDERKF attempts to discover when it is not suitable for the task posed.

statement.
INTEGRATOR 71
SCALE=r1[,r2][,r3] The SCALE parameter applies to only WSTIFF and ABAM. It is not applicable to
GSTIFF and CONSTANT_BDF.
SCALE scales the sum of the relative and absolute error tolerances. If T is the sum of
the relative and absolute error tolerances applied to the state vector, then the
following tolerance is applied:
 r1 * T to the translational displacements

 r2 * T to the angular displacements
 r3 * T to the modal coordinates
Note: By default, error tolerance is uniformly applied to all of the displacement
and angular coordinates.
Range: SCALE [i] > 0 where i = 1, 2, or 3
72 Adams Solver
GSTIFF, WSTIFF, or CONSTANT_BDF integrator, be used for formulating and
equations of motion. In addition, it monitors the integration error on the impulse of
the Lagrange Multipliers in the system. These additional safeguards enable the
integrators to monitor the integrator error in velocity variables and the impulse of the
Lagrange Multipliers. Simulation results are, therefore, very accurate. A positive side
effect of the SI1 formulation is that the Jacobian matrix remains stable at small step
sizes, which increases the stability and robustness of the corrector at small step sizes.

statement.
GSTIFF or CONSTANT_BDF integrator, be used for formulating and integrating
equations of motion. This process enables the GSTIFF integrator to monitor the
integration error of velocity variables, and therefore renders highly accurate
The SI2 formulation is available only with GSTIFF and CONSTANT_BDF.

statement.
differential equations of motion. WSTIFF uses the BDF method that takes step sizes
into account when calculating the coefficients for any particular integration order.
Extended Definition
For an extended definition, cautions, and tips, see the INTEGRATOR statement.
INTEGRATOR 73
Note: Setting the environment variable MSC_ADAMS_SOLVER_INTERPOLATE_ADAPTIVE

follows:

spaced times.
Examples
INTEGRATOR/SI2, GSTIFF, ERROR=1.0E-4, HINIT=1.0E-6, LIST
This command specifies a dynamic simulation using the SI2 equation formulation combined with the
GSTIFF integrator.
 The integrator has an error limit of 1.0E-4 and overrides the default value of 1.0E-3.
 HINIT= 1.0E-6 specifies an initial timestep of 1.0E-6, which overrides the default of 1/20th of the
output step.
 LIST prints all current settings of the INTEGRATOR to the screen and message file.
74 Adams Solver
JOINT
The JOINT command lists all the data for a JOINT statement.
Format
JOINT/id [,LIST]
Arguments
LIST Lists the current values of the data in the JOINT statement.
Examples
JOINT/10, LIST
This JOINT command lists all the data for Joint 10.
KINEMATICS 75
KINEMATICS
The KINEMATICS command redefines and/or lists the data for a KINEMATICS statement. If you issue neither
the KINEMATICS command nor statement in an Adams Solver (FORTRAN) session, Adams Solver
(FORTRAN) uses the default values for AERROR, ALIMIT, AMAXIT, APATTERN, ERROR, MAXIT,
PATTERN, and TLIMIT when performing a kinematic analysis.
Format
Arguments
AERROR=r Respecifies the maximum acceleration error Adams Solver (FORTRAN) is to

allow for each time step.
Range: AERROR > 0

ALIMIT=r Respecifies the maximum angular increment Adams Solver (FORTRAN) is to
allow per iteration. The default units for ALIMIT are radians. To specify
ALIMIT in degrees, add a D after the value.
Range: ALIMIT > 0

AMAXIT=i Respecifies the maximum number of iterations Adams Solver (FORTRAN) is
to allow for finding accelerations at a point in time.
Range: AMAXIT > 0

76 Adams Solver
indicates that Adams Solver (FORTRAN) is not to evaluate the Jacobian. Thus,
cj determines whether or not Adams Solver (FORTRAN) is to evaluate the
Jacobian at the jth iteration. If necessary, Adams Solver (FORTRAN) repeats the
(AMAXIT). The number of T’s or TRUE’s and F’s or FALSE’s together must be
at least one and no more than 10.
DEFAULT Resets the kinematic analysis simulation parameters to their default settings,
namely:
AERROR=1.0E-4
ALIMIT=30D
AMAXIT=25
APATTERN=T:T:T:T:T:T:T:T:T:T, (evaluate the acceleration Jacobian at every
iteration)
ERROR=1.0E-4
MAXIT=25
PATTERN=T:T:T:T:T:T:T:T:T:T, (evaluate the position Jacobian at every
iteration)
TLIMIT=1.0E10 (no limit)
ERROR=r Respecifies the maximum displacement error Adams Solver (FORTRAN) is to
allow for each time step.
Range: ERROR > 0

HMAX=r Defines the maximum time step that the KINEMATICS solution is allowed to
take.
When performing kinematic simulations on systems with parts that are rotating
at very high speeds (at or more than one revolution per time step), it is possible
for the kinematic to fail or provide inaccurate results because of lack of
information on the system between output step solutions. The HMAX value
can be used to limit the time between solution steps without having to specify a
large number of output steps.
LIST Lists the current values of the data in the KINEMATICS statement.
KINEMATICS 77
MAXIT=i Respecifies the maximum number of iterations Adams Solver (FORTRAN) is

to allow for finding the displacements at a point in time.
Range: MAXIT > 0

Adams Solver (FORTRAN) is to evaluate the Jacobian and F or FALSE
indicates that Adams Solver (FORTRAN) is not to evaluate the Jacobian. Thus
cj determines whether or not Adams Solver (FORTRAN) is to evaluate the
Jacobian at the jth iteration. If necessary, Adams Solver (FORTRAN) repeats the
(MAXIT). The number of T’s or TRUE’s and F’s or FALSE’s together must be
at least one and no more than ten.
TLIMIT=r Respecifies the maximum translational increment Adams Solver (FORTRAN)
is to allow per iteration.
Range: TLIMIT > 0
Tip:  Using the PATTERN argument to request less frequent evaluations of the Jacobian
matrix may decrease the computation time, thereby decreasing the cost and
improving the response time. However, it could also have the opposite effect since
more iterations may be required to reach the solution with a stale Jacobian matrix.
 Use the ALIMIT and TLIMIT arguments to limit the increments of the displacement
variables if Adams Solver (FORTRAN) fails to converge to a solution or converges to
an undesirable configuration. This lessens the position change on successive
iterations, and tends to keep the solution closer to the previous configuration.

78 Adams Solver
LINEAR
Note: Access to the LINEAR command in Adams Solver (FORTRAN) requires the purchase of an
Adams Linear license.
The LINEAR command is divided into the following sections:

 General
 Definition
 Format
 Arguments
 Extended Definition
 Examples
 Applications
 Appendix
1. General
You can use the LINEAR command to linearize Adams models. Linearized Adams models can be represented
by complex valued eigendata (eigenvalues, mode shapes) or by a state space representation in the form of real-
valued state matrices (A, B, C, and D). Adams uses a condensation scheme to reduce an Adams model to a
minimal realization linear form for efficient solution. (For more information, see Automatic Linearization of
Constrained Dynamical Systems, Sohoni, V.N. and J. Whitesell. ASME J. of Mechanisms, Transmissions and
Automation in Design, Sept. 1986, Vol. 108, No.3, pp.300-304.)
There are several applications where a linearized representation of the model can provide important insight
into the dynamical behavior of the model. Stability properties of the system have a direct relationship to the
real part of the complex eigenvalue. Eigenvalues with positive real parts represent unstable modes of the
system, while those with negative real parts represent stable modes. If bounded inputs to the system cause
excitation of an unstable mode, the system produces an unbounded response. On the other hand, bounded
excitation of a stable mode results in a bounded response. Eigenvalues computed by Adams Solver
(FORTRAN) can be plotted on a real-imaginary plot and the mode shapes then animated in Adams. In
addition to verifying stability, eigendata is used for validating implementation of models with eigendata from
other modeling approaches or experimental data. This is especially true if an elastic or control sub-system
model has been implemented in Adams Solver (FORTRAN).
Adams Linear outputs a state space representation in a form suitable for importation into matrix
manipulation and control design packages such as MATRIXx and MATLAB (for more information see the
Xmath Basics Guide, 1996, Integrated Systems Inc., Santa Clara, CA and Matlab User's Guide, The
MathWorks Inc., Natick, Massachusetts). A state space model representation is suitable for obtaining
frequency response of the Adams model, verifying model control properties (controllability and
observability), and designing feedback controllers for Adams models.
If you issue the LINEAR/EIGENSOL command in Adams Solver (FORTRAN), Adams Solver
(FORTRAN) computes model eigendata. Adams Solver (FORTRAN) reports the model eigenvalues to the
LINEAR 79
workstation screen or log (.log) file in a tabular form. The same table is also written to the tabular output
(.out) file.
If the results outputs are enabled, eigendata is also written into the results (.res) file, and may be taken to
Adams for further processing. If you issue the LINEAR/STATEMAT command, Adams Solver (FORTRAN)
computes the state matrices for the model and writes it to a user-specified file. If enabled, state matrices are
also written out to the Results file.
2. Definition
The LINEAR command invokes the Adams Linear option in Adams Solver (FORTRAN). The LINEAR
command linearizes the nonlinear system equations of motion and provides two basic capabilities, an
eigensolution or a state space matrix calculation. The eigensolution option determines natural frequencies
and mode shapes while the matrix calculation option computes the linear state space matrix that describes
the mechanical system. You may issue this command following initial conditions, a static or a transient
analysis. Depending on the options you specify, the results of the command are reported on the screen and
written to the Tabular Output file, the Results file, and, if required, the user-specified files.
3. Format
80 Adams Solver
4. Arguments
COORDS=i1[,i2] Specifies that a table of coordinates for mode numbers in the range i1 to i2 be
computed and output. If i2 is not specified, Adams Solver (FORTRAN)
produces the table of coordinates for mode number i1 only.
Range: i1 > 1, i2 > i1

EIGENSOL Specifies that Adams Solver (FORTRAN) perform an eigenanalysis of the Adams
model.
Type: Optional (either EIGENSOL or STATEMAT is required)

ENERGY=i1[,i2] Specifies that a table of modal energy distribution for mode numbers in the range
i1 to i2 be computed and output.
If i2 is not specified, Adams Solver (FORTRAN) produces the table of modal
energy distribution for mode number i1 only.
Range: i1 > 1, i2 > i1
Type: Optional with EIGENSOL; mutally exclusive with NOVECTOR

DISSIPAT=i1[,i2] Specifies that a table of dissipative energy distribution for mode numbers in the
range i1 to i2 be computed and output. If i2 is not specified, Adams Solver
(FORTRAN) produces the table of dissipative energy distribution for mode
number i1 only.
Range: i1 > 1, i2 > i1

FILE=c Specifies a file name to which Adams Solver (FORTRAN) writes the state
matrices. If the output is in the MATRIXX format, all matrices are written to this
file. For the MATLAB format, the file name is used as a base name. Each matrix
is written to a separate file, whose name Adams Solver (FORTRAN)
automatically constructs by appending the matrix name to the user-specified base
name. This argument is a qualifier for the STATEMAT argument.
Range: Valid file name up to 76 characters
Type: Required with STATEMAT

LINEAR 81
Specifies the name of the software in whose input format Adams Solver
(FORTRAN) is to output the state matrices. Presently, two software formats are
supported: MATRIXX (FSAVE format) and MATLAB (ASCII flat file format).
This argument is a qualifier for the STATEMAT argument.
Type: Optional with STATEMAT

KINETIC=i1[,i2] Specifies that a table of kinetic energy distribution for mode numbers in the range
i1 to i2 be computed and output.
If i2 is not specified, Adams Solver (FORTRAN) produces the table of kinetic
energy distribution for mode number i1 only.
Range: i1 > 1, i2 > i1

NODAMPIN Specifies that Adams Solver (FORTRAN) ignore damping while performing an
eigenanalysis for the Adams model. This argument affects only force statements
(such as SPRINGDAMPER, SFORCE, BEAM, BUSHING, and so on) and
VARIABLE statements whose definition includes velocity dependencies. This
argument is a qualifier to the EIGENSOL argument.

NOVECTOR Specifies that Adams Solver (FORTRAN) perform the eigenanalysis without
computation of mode shapes. This argument is a qualifier to the EIGENSOL
argument. This argument does not have any values.

PINPUT=id Specifies identifier of the PINPUT statement that Adams Solver (FORTRAN)
uses as plant inputs in the state matrices computation. If this argument is not
specified, the B and D matrices will not be output. This argument is a qualifier
for the STATEMAT argument.

82 Adams Solver
POUTPUT=id Specifies identifier of the POUTPUT statement that Adams Solver (FORTRAN)
uses as plant outputs in the state matrices computation. If this argument is not
specified, the C and D matrices will not be output. This argument is a qualifier
for the STATEMAT argument.

STATEMAT Specifies that Adams Solver (FORTRAN) calculates state matrices for the
ADAMS model.
Type: Optional (either STATEMAT or EIGENSOL is required)

STRAIN=i1[,i2] Specifies that a table of strain energy distribution for mode numbers in the range
i1 to i2 be computed and output. If i2 is not specified, Adams Solver
(FORTRAN) produces the table of strain energy distribution for mode number
i1 only.
5. Extended Definition
To linearize an Adams model about an operating point, issue the SIMULATE/STATIC,
STATIC/DYNAMIC, or SIMULATE/TRANSIENT commands and then issue the LINEAR command to
exercise linear analysis on the model.
The two principal functions of the LINEAR command are to compute the eigenvalues and mode shapes for
the Adams model and to compute the state matrices representation of the Adams model.
If you specify the EIGENSOL argument, Adams Solver (FORTRAN) performs eigenanalysis on an Adams
model. Eigendata results from the solution of a generalized eigenvalue problem of the form:
Kz= μ Mz
where:
 z is the eigenvector
 μ is the eigenvalue
 K and M are the constant coefficient matrices derived by Adams Solver (FORTRAN) from the
Adams model
The eigenvector is mapped to the mode shape prior to output to the results (.res) file.
If you specify the NODAMPIN argument, Adams Solver (FORTRAN) does not include the velocity-
dependent terms in forces nor does it include velocity-dependent terms in the VARIABLE statements in the
K and M matrices. Using this option may be beneficial in determining the underlying modes for a system
with critical or greater than critical damping.
If you specify the NOVECTOR argument, Adams Solver (FORTRAN) computes only the eigenvalues and
not the mode shapes. Adams Solver (FORTRAN) reports on the screen eigenvalues that result from the
eigensolution and writes this data to the tabular output file (.out). If you use the RESULTS statement to
LINEAR 83
enable output to the results file (.res) in the Adams Solver (FORTRAN) dataset, the eigenvalues and mode
shapes (if computed) will be written to this file. The results file may be taken to a postprocessor such as Adams
View for further processing.
All eigenvalues are normalized to be in cycles/second. The imaginary component of the eigenvalue represents
the oscillatory behavior of the mode and the real component, the damping characteristic.
The model eigenvalues are reported to the workstation screen or in a tabular form to the tabular output (.out)
file. In general, the eigenvalues are complex values, made up of real and imaginary components. The
imaginary component represents the 'damped' natural frequency, ω d. The damping ratio must be less than
1 in order to produce an imaginary component in the eigenvalue -- in other words, the damped natural
frequency is zero whenever the damping ratio is 1 or greater.
The undamped natural frequency and damping ratio obeys following equations:
ωn = ( λ r2 + λ i2 )
λr
ζ = ------
ωn
where:
 λ r = real part of eigenvalue.

 λ i = imaginary part of eigenvalues; also the damped natural frequency, ω d.
 ω n = undamped natural frequency.
 ζ =damping ratio ( ζ < 1).
The relationship between the damped natural frequency, ω d , and undamped natural frequency, ω n , is:
ωd = ωn ⋅ ( 1 – ζ 2 )
The damped natural frequency is the actual frequency at which the system is oscillating for that mode.
If you specify the COORDS, ENERGY, KINETIC, DISSIPAT, or STRAIN arguments, Adams Solver
(FORTRAN) computes tabular output and writes it to the output (.out) file. For each mode in the specified
range, this output could consist of up to five sections. The header section contains the mode number,
undamped natural frequency, damping ratio, generalized stiffness, generalized mass and model energy for the
mode. Generalized stiffness and generalized mass are in user-specified units dropping out the length
dimension because the computations are done using normalized mode shapes. Hence, the generalized
stiffness and the modal energy show units of User-mass/time^2.
The second section is a table of coordinates if the COORDS argument is specified. This section is not output
if the COORDS argument is not specified or if the particular mode number is not within the range specified
on the COORDS argument. Each part in the Adams Solver (FORTRAN) model has one row in this table.
The part translational coordinates in columns labeled (x,y,z), represent the small translational displacements
84 Adams Solver
of the part center-of-mass (cm) marker in the global reference frame. The part rotational coordinates, in
columns labeled (RX, RY, RZ), represent the small rotational displacements of the part about the global x, y
and z axes, respectively. Each coordinates in this table is represented by a magnitude and a phase. The mode
is normalized so that the largest component in the mode has a value of 1.0 and a phase angle of 0 degrees.
Magnitude and phase of all other components in the mode are reported relative to this largest component.
Phase angles are represented in the range 0 to 355 degrees. Phase angles in the range 175 to 185 degrees are
reported as 180 degrees. Phase angles in the range 355 to 360 degrees as well as phase angles in the range zero
to five degrees are reported as zero degrees. States of elements resulting in user supplied differential equations
are also represented in the coordinate table. All components with zero magnitude are also reported as having
zero phase angles.
The third section is a table of modal kinetic energy distribution if the ENERGY or KINETIC arguments are
specified. This section is not present in the output for a particular mode if the mode number is not within
the range of the modes specified on the ENERGY or KINETIC arguments. Each part is represented by a
single row in this table. Each entry in this table represents the percentage of the total modal kinetic energy
for that part in a particular direction. Translational directions in which the modal kinetic energy distribution
is computed are x, y and z displacement of the part center-of-mass (cm) in the global reference frame.
Rotational directions are denoted by RXX, RYY, and RZZ; these represent the small displacement rotations
of the part about the global x, y and z axes, respectively. The cross rotations are represented as RXY, RYZ, and
RXZ. The sum of all values in a modal energy distribution table should be 100.0. Elements resulting in user-
supplied differential equations are not considered in the computation for this table.
The fourth section is a table of modal strain energy distribution if the STRAIN argument is specified. This
section is not present in the output for a particular mode if the mode number is not within the range of the
modes specified on the STRAIN argument. Each force element is represented by one or more rows in this
table. The table below shows the contribution of various element types to this table. Computation of strain
energy accounts for the direct and indirect dependence of the force on PART displacements. The indirect
dependence on PART displacements may be through dependence of the force on other FORCEs,
VARIABLEs, or algebraic DIFFs that may be directly or indirectly dependent on PART displacements.
Table 1. Elements Contributing to Table for Dissipative and Strain Energy Computations
BEAM X X X X X X X
BUSHING X X X X X X X
FIELD X X X X X X X
GFORCE X X X X X X X
NFORCE for marker 1 X X X X X X X
... X X X X X X X
for marker n X X X X X X X
SFORCE (translational) X X X X
SFORCE (rotational) X
LINEAR 85
SPRINGDAMPER X X X X
(translational)
SPRINGDAMPER X
(rotational)
VFORCE X X X X
VTORQUE X X X X
In the table, X, Y, and Z refer to translation components along the global x, y and z directions and RX, RY,
and RZ refer to rotational components about the global x, y and z directions. x indicates locations for
contributions for individual elements. The column labeled Total contains a summation of the
strain/dissipative energy contribution due to the element in various directions.
The fifth section is a table of modal dissipative energy distribution if the DISSIPAT argument is specified.
This section is not present in the output for a particular mode if the mode number is not within the range of
the modes specified on the DISSIPAT argument. Each force element is represented by one or more rows in
this table. The table shows the contribution of elements to this table. Computation of dissipative energy
accounts for the direct and indirect dependence of the force on PART velocities. The indirect dependence on
PART velocities may be through dependence of the force on other FORCEs, VARIABLEs, or algebraic
DIFFs that may be directly or indirectly dependent on PART velocities.
If you specify the STATEMAT argument, Adams Solver (FORTRAN) computes the state matrices
representation for an Adams model. The linearized Adams model is represented as:
x· =A x + B u
y=Cx+Du
where:
 x· represents the state variables of the plant model.

 u represents the inputs of the plant model.
 y represents the outputs from the plant model.
 A, B, C, and D are state matrices representing the plant.
You can specify the definition of plant inputs with the PINPUT argument value. Similarly, plant outputs are
specified by the POUTPUT argument. Plant states are automatically determined by Adams Solver
(FORTRAN) and result in the best numerical conditioning of the state matrices. While several PINPUT
statements and POUTPUT statements may be present in an Adams model, you can specify only one of each
on the LINEAR command.
Corresponding to each VARIABLE id specified on the PINPUT statement, a column exists in the B and D
matrices. Similarly, for each VARIABLE id specified on the POUTPUT statement, a row exists in the C and
D matrices. In effect, each VARIABLE id specified on the PINPUT or POUTPUT statement specifies an
input or output channel, respectively.
86 Adams Solver
Open-loop/closed-loop input channels are important in the computation of state matrices. If a VARIABLE
statement whose id is specified on a PINPUT statement is defined as:
VARIABLE/id, FUNCTION = constant
or
VARIABLE/id, FUNCTION = function_of_time
then it is designated as an open-loop input channel. However, if the VARIABLE is of the form:
VARIABLE/id, FUNCTION=function_of_ADAMS-model-states
it is designated as a closed-loop input channel with feedback. This distinction is reflected in the A, B, and D
matrices. Columns in the B and D matrices corresponding to a closed-loop input channel will have all zero
values. Effects of the feedback loop due to these inputs is reflected in the A matrix. This implies that external
inputs on these channels are not permitted.
Consider a system of the following form:
x· =A x + B u
y=Cx
Partitioning the plant input into two groups called u1 and u2, the plant model becomes:
x· =A x + B1u1 + B2u2
y=Cx
where B1 and B2 are sub-matrices of B, corresponding to u1 and u2, respectively; and u1 and u2 are the closed-
loop and open-loop input channels, respectively.
If the input u1 represents the closed-loop input channels defined by the feedback loop:
u1 = -G y
where G is the feedback gain matrix, the plant model can then be represented as:
x· = [ A - B1 G C ] x + [0] u1 + B2 u2
y=Cx
Adams Solver (FORTRAN) computes the state matrices for a model with this combination of inputs and
outputs as:
Ã = [ A – B 1 KC ]
B̃ = [ 0 B 2 ]
C̃ = C
LINEAR 87
The effects of the closed-loop channels are reflected in the Ã matrix. Columns of the B̃ matrix
corresponding to the closed-loop channel are zero. In other words, the PINPUT or POUTPUT id
specification that you choose on the LINEAR command affects the structure of the A, B, C, and D matrices.
Tip:  To reduce computing time, specify the NOVECTOR argument with the
EIGENSOL argument if mode shapes are not desired.
 Specify the LINEAR command to assess stability of Adams models by computing its
eigenvalues. Eigenvalues with positive real parts correspond to unstable modes of the
system.
 If you specify the PINPUT and the POUTPUT arguments for state matrices output,
Adams Solver (FORTRAN) produces all four matrices (A, B, C, and D). If you do
not specify the PINPUT argument, Adams Solver (FORTRAN) does not produce the
B or D matrices. Similarly, if you do not specify the POUTPUT argument, Adams
Solver (FORTRAN) will not produce the C or D matrices. If you do not specify
either the PINPUT or POUTPUT arguments, Adams Solver (FORTRAN) produces
only the A matrix.
 You may define several PINPUT and POUTPUT statements in an Adams Solver
(FORTRAN) dataset, however, a LINEAR command allows only one PINPUT and
one POUTPUT statement to be specified at a time. If you issue a series of LINEAR
commands, Adams Solver (FORTRAN) computes alternate state matrix descriptions
at the same operating point with different combinations of PINPUT and POUTPUT
identifiers. Changes in the PINPUT and POUTPUT descriptions are reflected in the
A, B, C, and D matrices.
88 Adams Solver
Caution:  The LINEAR command may only be issued following a STATIC, DYNAMIC, or
TRANSIENT analysis.
 Dependence of function expressions on joint reaction forces is ignored for
linearization.
 Adams models containing nonholonomic UCONs cannot be linearized.
 Since the eigensolution and state matrices characterize behavior of the nonlinear
Adams model in a neighborhood of the operating point, you should assess if an
operating point is at a suitable point about which to linearize the system equations. A
model can always be linearized about its static position.
Decide whether or not to linearize models undergoing motion. Three situations to
consider are listed below.
• All or some parts in the Adams model have translational but no angular velocities.
It is acceptable to linearize models at such operating points.
• In addition to translation velocities, all or some parts in the Adams model have
angular velocities. If the angular velocity vector passes through the center of mass
of the respective parts, it is acceptable to linearize such models. An example of such
a system would be a vehicle moving in a straight line with its wheels rotating about
their axes.
• If, however, the angular velocity vector does not pass through the center of mass of
the respective part, the system should not be linearized. This is especially true if the
angular velocity magnitudes are large. An example of this would be a spinning,
articulated structure containing a center hub with articulated outboard parts. The
spin axes of the outboard parts do not pass through the center of mass of the parts.
Linearization of such models may produce spurious results.
• Applying MOTION to a JOINT restricts the respective degree-of-freedom. As a
result, during state matrices output, any PINPUT applied to a part constrained by
such a MOTION results in a zero column for the B matrix.
Advanced eigensolution issues

In case you need to compare the computed eigensolution with results from another software package, you
may export the linearization matrices using the LINEAR/STATEMAT option. The exported [A] matrix is
the one we send to the eigensolver.
In general, the issues affecting the quality of the eigensolution are the following:
a. Models in singular configurations. Models in singular configuration may report spurious modes
and frequencies or they may report different values (with a sign reverse) under small perturbations.
LINEAR 89
For instance, the beam shown in the figure above is at an unstable equilibrium position. A small
perturbation moving the tip downward will cause the torque to restore the previous equilibrium
position (complex eigenvalue). However, a small perturbation moving the tip upward will case
the system to move away from the horizontal position (real eigenvalue). At exactly the horizontal
position the eigenvalues are zero. Solving a complex system with the same overall topology may
results in spurious eigenvalues.
b. Accelerating models. Accelerating or rotating components usually involve mode shapes involving
velocity states and may show strange mode shapes.
c. Multiple rigid body modes. If the model has the potential to experiment rigid body motion, the
eigensolver may show up with noisy frequencies instead of a zero value. This depends on the size
of the model. Moreover, if the model has DIFFs or LSEs or GSEs or TFSISOs objects, then some
modes will be related to the differential states with almost no coupling with overall motion of the
system. Those modes will show no animation.
d. Overdamped models. Damping may create spurious modes that create clutter and make difficult
to find the modes of interest. Since the damping is hard to estimate, we recommend also running
the eigensolution with the NODAMP option to gain perspective on the interesting modes.
Damping can be added afterward to estimate its influence in the solution.
e. Friction in stiction regime. If the model has FRICTION objects running in the stiction mode,
you may get spurious frequencies and mode shapes due to the stiffness of the force element added
to model the stiction.
f. Numerical limitations. In general, the linearization matrix [A] is non-symmetric, ill-conditioned
and sparse. In addition, there is a natural limitation in the precision of the arithmetic operations
of the computer. The end results may be that frequencies and mode shapes may include noisy
results especially in both the lower end of the real eigenvalues (real-only eigenvalues with small
values) and in the lower imaginary spectrum (complex eigenvalues with small imaginary part).
Higher real-only eigenvalues and higher imaginary eigenvalues are usually better extracted.
6. Examples
LINEAR/EIGENSOL
This command computes an eigenanalysis for the Adams model. Adams Solver (FORTRAN) writes the
eigenvalues and mode shapes to the Results file where they can be read and displayed by a postprocessor such
as Adams View.
LINEAR/STATEMAT, PINPUT=10, POUTPUT=20
, FORMAT=MATRIXX FILE=STATES.MAT
This command computes state matrices for the Adams model, using PINPUT/10 as inputs and
POUTPUT/20 as outputs. The state matrices are written to file STATES.MAT in MATRIXX format.
90 Adams Solver
7. Applications
Eigensolutions provide you with information that may be used in assessing stability of the Adams model. If
you import control systems descriptions or distributed elasticity data from external sources, you can verify
the stability of their Adams models.
1. Eigendata computed by Adams Solver (FORTRAN) can be used to validate Adams models against
eigendata from external sources.
2. State matrices descriptions can be used in designing control systems for Adams models. This
description is suitable for computing frequency response data in matrix manipulation software
packages (see the PINPUT, POUTPUT, and VARIABLE statements).
3. State matrices output by Adams Solver (FORTRAN) in the MATRIXX format are suitable for being
read into a second Adams model with a MATRIX statement. These matrices can form the definition
of a dynamical system defined by an LSE statement in the second Adams model.
7.1 Eigenanalysis Application

Consider a model of an inverted pendulum on a sliding cart as shown in Figure 6 below. The listing of the
Adams Solver (FORTRAN) dataset for this model is shown in Listing 1.
Figure 6 Inverted Pendulum on Sliding Cart Model
The sliding cart in this model is represented by PART/1 and the inverted pendulum is represented by
PART/2. PART/1 slides along the global x axis in translational joint, JOINT/1, while PART/2 can rotate
about the axis of revolute joint, JOINT/2. PART/1 is connected to ground by a SPRINGDAMPER/1.
TFSISO/1 represents an actuator connected between PART/1 and PART/2. Force generated by this actuator
is applied on the two parts by SFORCE/1. No input is applied to the actuator for the present. To assess
stability of this model, execution of Adams Solver (FORTRAN) is initiated. Once Adams Solver
(FORTRAN) verifies that the model data is syntactically correct, issue the SIMULATE/STATIC command.
On achieving static equilibrium, issue the LINEAR/EIGEN command. Eigenvalues reported by Adams
Solver (FORTRAN) are shown in Table 2 below.
Table 2. Model Eigenvalues
LINEAR 91
EIGENVALUES
1 5.00909210E-02 0.00000000E+00
2 -5.00924580E-02 0.00000000E+00
3 -3.18309800E+01 0.00000000E+00
4 -3.17994185E-01 +/- 6.36188992E-01
The table shows that the system has three stable and one unstable mode. To determine the cause of this
instability, use the data produced by Adams Solver (FORTRAN) (.res, .adm, and so on) in Adams to display
the deformed mode shapes of the model.
Figure 7 (a) and (b) show mode shapes for mode 1, which is unstable, and mode 4, which is stable.
Figure 7 Deformed Mode Shape 1(a) and Deformed Mode Shape 4 (b)
Figure 7 (a) shows that PART/1 is essentially stationary while PART/2 is moving. You can conclude that
PART/2 is the cause of the instability in this model. This is an expected result for this model, since the
inverted pendulum is at an unstable operating point. It is obvious that disturbing the pendulum will cause it
to swing about the revolute joint axis.
As illustrated by this example, viewing mode shapes in a graphical display can provide very significant insight
into the dynamic behavior of the model. In complicated Adams models, this insight is vital in understanding
the model dynamics. In Example 2: State Matrices Output below, based on the state matrices computed for
this model, a feedback control law will be designed to stabilize this model.
92 Adams Solver
7.2 State Matrices Output

Design and implementation of a control system for an Adams model is described in this example. The plant
model used in this example is identical to the Adams model described in Example 1. The purpose of the
control design exercise is to design a feedback controller to attempt to stabilize the inverted pendulum Adams
model described in Example 1. For control design purposes, the state matrix representation of the Adams
model is required and is generated by the LINEAR/STATEMAT command.
Stabilization of this model requires that PART/2 maintain its inverted vertical position despite external
disturbances applied on it. External disturbances considered here are gravity acting vertically downwards and
an external force applied to the pendulum in the x-direction. On sensing a deviation of the pendulum from
the desired position, the control law determines an appropriate signal to apply to actuator TFSISO/1 to
restore PART/2 to its desired position. The control law operates on the basis of measuring output signals from
the plant and then computes a signal to apply to the actuator.
As shown in Figure 8 for the present model, 3 signals are output by the plant. VARIABLE/10 is a measurement
of the relative x displacement between PART/1 and PART/2. VARIABLE/20 is a measurement of the relative
x velocities between the two parts. VARIABLE/30 is the integral of the relative x displacements between the
two parts. These 3 signals are designated as outputs from the plant by POUTPUT/1.
Input to the plant, that is, input signal to the actuator, is defined as VARIABLE/2. This is designated as input
to the plant by PINPUT/1. Adams Solver (FORTRAN) implementation of the input/output structure and
the external disturbances is shown in Listing 2: Plant Input/output Specification . This implementation, when
combined with the plant model as shown in dataset 1 in FILE=c results in the open-loop model. When the
open-loop model is complete, an Adams Solver (FORTRAN) execution session is initiated.
Figure 8 Open-Loop Model
The model is read into Adams Solver (FORTRAN). After Adams Solver (FORTRAN) verifies the model data
syntax, issue the SIMULATE/STATIC command to determine the equilibrium position. On achieving the
equilibrium position, issue the LINEAR/EIGEN, NOVECTOR command to verify the eigenvalues of the
model. The next table shows the eigenvalues for the open-loop model.
Table 3. Open-Loop Eigenvalues
EIGENVALUES
1 -2.66440631E-17 0.00000000E+00
2 5.00909210E-02 0.00000000E+00
LINEAR 93
3 -5.00924580E-02 0.00000000E+00
4 -3.18309800E+01 0.00000000E+00
5 -3.17994185E-01 +/- 6.36188992E-01
The table shows that the open-loop model has one eigenvalue more than the model in Example 1: Eigenanalysis
Application This is due to the introduction of the relative displacement integrator TFSISO/2 in the open-loop
model. To linearize the model and compute the state matrices, issue the LINEAR/STATEMAT, PINPUT=1,
POUTPUT=1, file=adams.mat command. Adams Solver (FORTRAN) linearizes the model and writes the
state matrices in the default format to adams.mat file. Contents of the ADAMS.MAT file are in Listing 3: State
Matrices (FSAVE Format) for the Open-Loop Model. The Adams Solver (FORTRAN) session then terminates. You
may design a controller by reading the ADAMS.MAT file into the control design package exercising various
control design methodologies. The description of the control design step is beyond the scope of the present
document. A text on this subject or documentation for control design software packages should be consulted
for further details.
Now that the feedback control has been designed, it needs to be implemented in Adams Solver (FORTRAN)
for a closed-loop simulation. The controller designed for this example is a dynamic compensator. As shown
in Figure 4 below, this is implemented in Adams Solver (FORTRAN) as LSE/1. The A, B and C matrices
associated with this LSE are defined by MATRIX/100, 200, and 300, respectively. Adams Solver
(FORTRAN) reads the data for these matrices from a file named incomp.dat. To connect this feedback
compensator to the plant model, inputs to LSE/1, ARRAY/303 are connected to outputs from the plant
model. Also, ARRAY/1, which is input to the actuator, TFSISO/1, is now defined as the output from the
compensator, VARIABLE/2. This completes the closed-loop Adams model. The complete Adams Solver
(FORTRAN) dataset for this model is shown in dataset 3 and dataset 4.
Figure 9 Closed-Loop Model
To verify and simulate the closed-loop model, an Adams Solver (FORTRAN) simulation is initiated. The
closed-loop model is first equilibrated in its static position. The eigenvalues for this model are computed and
represented in Table 4 shown next.
94 Adams Solver
Table 4. Closed-Loop Eigenvalues
EIGENVALUES
1 -5.35233760E-01 0.00000000E+00
2 -3.18270747E+01 0.00000000E+00
3 -2.37397000E-01 +/- 7.54488218E-02
4 -7.37798519E-03 +/- 1.51611302E-01
5 -5.47796070E-01 +/- 5.12745191E-01
6 -2.43466412E-01 +/- 5.71313964E-01
7 -2.46528313E+01 +/- 1.00614794E+01
Table 4 above shows that the closed-loop model is stable. The closed-loop model has more eigenvalues than
the open-loop model. This is due to the dynamical state variables introduced by LSE/1. Eigenvalues for the
closed-loop Adams model can be compared with the closed-loop eigenvalues computed in the control design
package. Now that the stability properties of the closed-loop Adams model have been verified, it can be
simulated to obtain its dynamic response. The time profile of the external disturbance is as shown in Figure 10.
The closed-loop model response to external disturbance is as shown in Figure 11. As illustrated in this figure,
the closed-loop model provides complete disturbance rejection for displacement of PART/2.
Figure 10 Time Profile of External Disturbance

LINEAR 95
Figure 11 Closed-Loop System Response
The input signal applied to the actuator and the force generated by the actuator are shown in Figure 12 and
Figure 13, respectively.
Figure 12 Input Signal to Actuator

96 Adams Solver
Figure 13 Force Generated by Actuator
The process of control design and simulation is an iterative one. If the closed-loop system does not perform
as expected, the control design specifications may have to be changed and a new controller designed to
achieve better performance.
7.2.1 State Matrices Output Format

MATRIXX Format
State matrices output by Adams Solver (FORTRAN) in the MATRIXX format conforms to the MATRIXx
FSAVE ASCII file specification. These specifications are given in the Xmath Basics Guide, 1996, Integrated
Systems Inc., Santa Clara, CA.
More than one matrix may be present in a single file. The Adams Solver (FORTRAN) state matrices file can
have up to seven matrices. The first four matrices are the A, B, C, and D state matrices. The next three
matrices are STATES, PINPUT, and POUTPUT. The contents and format of these matrices are explained
in Contents of the STATES, PINPUT, and POUTPUT Matrices.
MATLAB Format
State matrices output by Adams Solver (FORTRAN) in the MATLAB format conform to the ASCII flat file
format. This format requires that all entries in a row of the matrix be written in a single record. Successive
values in a row are separated by a single space. A file is allowed to contain only one matrix. Therefore, Adams
Solver (FORTRAN) may create up to seven output files, one each for the A, B, C, and D matrices, one for
STATES, one for PINPUT, and one for POUTPUT. The contents and format of the last three matrices are
as shown in Contents of the STATES, PINPUT, and POUTPUT Matrices. The file name you specify is used as a base
name and is appended with the matrix name to write the matrix of the appropriate type. The file names used
for the seven matrices are as given in Table 5 below.
Table 5. File Names Used for MATLAB State Matrices Output
LINEAR 97
Matrix name File Name

A "base_name" "a"
B "base_name" "b"
C "base_name" "c"
D "base_name" "d"
STATES "base_name" "st"
PINPUT "base_name" "pi"
POUTPUT "base_name" "po"
7.2.2 Contents of the STATES, PINPUT, and POUTPUT Matrices

STATES Matrix
The STATES matrix contains information regarding states that Adams Solver (FORTRAN) has chosen for
the state matrices representation. For each state, one record exists in this matrix. The following information
is contained in each record:
Type_of_element Element_identifier Element_coordinate
Type_of_element
Type_of_element can take on the following values:
1. Part coordinates
2. States in a LSE element
3. States in a TFSISO element
4. States in a GSE element
5. Diff variable
6. Coordinate for a PTCV element
7. Coordinates for a CVCV element
8. FLEX_BODY element
9. POINT_MASS element
Element_identifier
Element_identifier is the eight-digit Adams Solver (FORTRAN) identifier of the element.
Element_coordinate
1. x-displacement
2. y-displacement
98 Adams Solver
3. z-displacement
4. Ψ angle of part principal axis
5. θ angle of part principal axis
6. φ angle of angle of part principal axis
7. x·
8. y·
9. z·
10. Ψ
·
11. θ
·
12. φ
For Type_of_element=2 to 5, Element_coordinate is the sequence number in the set of states defining that
element.
For Type_of_element=6, the only permissible value for Element_coordinate is 1, that is, the alpha parameter
value that defines the contact point on the curve.
For Type_of_element=7, Element_coordinate may take on the value of 1 or 2, representing the parameter
values for the first (I) or second (J) curve in a CVCV statement that defines the contact point on the curve.
4 x·
5 y·
6 z·
In the MATRIXX format, this data is organized in column order form so that the STATES matrix contains
three rows and number of columns is equal to the number of states in the model. In the MATLAB format,
this data is organized in the row order form. Therefore, the STATES file contains data organized in the three
columns and the number of rows is equal to the number of states in the model.
LINEAR 99
7.2.3 PINPUT and POUTPUT Matrices

The first record in the PINPUT/POUTPUT data contains the Adams Solver (FORTRAN) identifier of the
PINPUT/POUTPUT statement, respectively, that was used on the LINEAR command to generate these
state matrices. Subsequent records contain the Adams Solver (FORTRAN) identifiers of the VARIABLE
statement identifiers used on these statements. In the MATRIXX as well as the MATLAB format, this data
is organized as a matrix with 1 column and number of rows equal to one plus the number of variables on the
PINPUT or POUTPUT statement.
All data for the STATES, PINPUT, and POUTPUT matrices is written as floating point data.
8. Appendix
Listing 1: Inverted Pendulum Model
ADAMS Inverted pendulum model.
!
pa/99, ground
ma/99,qp=0,0,0, zp =1,0,0
!
pa/1,ma=10,ip=10,10,10,cm=10
ma/14,qp=5,0,12
!
pa/2,ma=1,cm=20, ip=1,1,1
!
!
!
gra/4, cylind,cm=24, l=8.5, r=0.25,seg=10,side=10
gra/5, box, corn=12, x=9, y=4, z=4
!
!
100 Adams Solver
,u=1,x=2,y=3
!
!
! ===>Input to Actuator<===
vari/2,fun=0
!
accgrav/kg=-1
result/format
!
end
Listing 2: Plant Input/output Specification

! -------------------
!
var/1,fun=dx(20,14)
,u=20,x=21,y=22
array/20, U, VAR=1
array/21, X
array/22, Y
!
! ===> Outputs <===
!
!
pinput/1,var=2
!
!
Listing 3:State Matrices (FSAVE Format) for the Open-Loop Model

FSAVE
A 6 6B 6 1C 3 6D 3 1
STATES 3 6PINPUT 2 1POUTPUT 4 1
A 6 6 0(3(1PE25.17))
-3.99604352126607320E+00 1.00000000000000000E+00 -3.95647873392680550E-02
0.00000000000000000E+00 0.00000000000000000E+00 0.00000000000000000E+00
-1.99703264094955490E+01 0.00000000000000000E+00 -2.96735905044510420E-01
0.00000000000000000E+00 0.00000000000000000E+00 -9.99999999962142390E-01
0.00000000000000000E+00 0.00000000000000000E+00 0.00000000000000000E+00
1.00000000000000000E+00 0.00000000000000000E+00 0.00000000000000000E+00
LINEAR 101
-9.89119683481701380E-03 0.00000000000000000E+00 9.89119683481701210E-02

0.00000000000000000E+00 0.00000000000000000E+00 9.99999999962142390E-01
4.02439896739235910E-02 0.00000000000000000E+00 -4.02439896739235860E-01
0.00000000000000000E+00 -2.00000000000000000E+02 0.00000000000000000E+00
0.00000000000000000E+00 0.00000000000000000E+00 0.00000000000000000E+00
0.00000000000000000E+00 0.00000000000000000E+00 0.00000000000000000E+00
B 6 1 0(3(1PE25.17)
0.00000000000000000E+00 0.00000000000000000E+00 0.00000000000000000E+00
0.00000000000000000E+00 2.00000000000000000E+03 0.00000000000000000E+00
C 3 6 0(3(1PE25.17))
0.00000000000000000E+00 -1.00000000000000000E+00 0.00000000000000000E+00
-9.99999999962142390E-01 0.00000000000000000E+00 0.00000000000000000E+00
0.00000000000000000E+00 1.00000000000000000E+00 0.00000000000000000E+00
9.99999999962142390E-01 0.00000000000000000E+00 0.00000000000000000E+00
0.00000000000000000E+00 0.00000000000000000E+00 0.00000000000000000E+00
0.00000000000000000E+00 0.00000000000000000E+00 1.00000000000000000E+00
D 3 1 0(3(1PE25.17))
0.00000000000000000E+00 0.00000000000000000E+00 0.00000000000000000E+00
STATES 3 6 0(3(1PE25.17))
1.00000000000000000E+00 1.00000000000000000E+00 7.00000000000000000E+00
1.00000000000000000E+00 1.00000000000000000E+00 1.00000000000000000E+00
1.00000000000000000E+00 2.00000000000000000E+00 7.00000000000000000E+00
1.00000000000000000E+00 2.00000000000000000E+00 1.00000000000000000E+00
3.00000000000000000E+00 1.00000000000000000E+00 1.00000000000000000E+00
3.00000000000000000E+00 2.00000000000000000E+00 1.00000000000000000E+00
PINPUT 2 1 0(3(1PE25.17))
1.00000000000000000E+00 2.00000000000000000E+00
POUTPUT 4 1 0(3(1PE25.17))
1.00000000000000000E+00 1.00000000000000000E+01 2.00000000000000000E+01
3.00000000000000000E+01
Listing 4: Closed-Loop Model

ADAMS Inverted pendulum closed-loop model.
!
pa/99, ground
ma/99,qp=0,0,0, zp =1,0,0
!
pa/1,ma=10,ip=10,10,10,cm=10
ma/14,qp=5,0,12
!
pa/2,ma=1,cm=20, ip=1,1,1
!
!
102 Adams Solver
!
gra/4, cylind,cm=24, l=8, r=0.5,seg=10,side=10
gra/5, box, corn=12, x=9, y=4, z=4
!
!
,u=1,x=2,y=3
!
!
!
! -------------------
!
var/1,fun=dx(20,14)
,u=20,x=21,y=22
array/20, u, var=1
array/21, x
array/22, y
!
! ===> Outputs <===
!
!
pinput/1,var=2
!
!
! ===>Feedback compensator<===
! --------------------
!
lse/1,a=100, b=200, c=300,
,x=101,y=202,u=303,ic=404
!
array/101, x ! compensator state
array/202, y ! compensator output
array/303, u, var= 10, 20, 30 ! compensator input
array/404, ic, num=0,0,0,0,0,0
!
matrix/100,
,file=incomp.mat, name=ac
matrix/200,
,file=incomp.mat, name=bc
LINEAR 103
matrix/300,
,file=incomp.mat, name=cc1
!
! ===> Feedback signal from compensator to actuator <===
variable/2, fun=-aryval(202,1)
!
accgrav/kg=-1
result/format
!
end
Listing 5: "incomp.mat" Input Data file
MATRIXx VERSION 700 3 04-OCT-91 15:27
AC 6 6BC 6 3CC1 1 6
AC 6 6 0(1P3E25.17)
-1.00799962154710574E+01 9.75162440467575053E-01 9.98460749273361898E+01
9.61406957584617916E-01 3.11437948419828955E-03 -1.78574044858736743E+04
-8.50683303123077716E-01 -4.98921809045884790E-01 1.01587769607181722E+00
1.14325442554075640E+00 -4.49484043101296749E-01 -1.69576019090885748E+04
9.98009512743940519E+00 2.48375595324249708E-02 -9.98470640470196713E+01
3.85930424153820839E-02 -3.11437948419828955E-03 1.79036593612407414E+04
-1.48327577193440696E-01 4.98921809045884790E-01 -1.02576889290663420E+00
-1.14325442554075640E+00 4.49484043101296749E-01 1.74318979368853470E+04
-1.20450308829068348E-01 7.73595535159733033E-02 -1.23564688768258060E-01
-4.73156382486152438E-01 -1.34087821455120393E+00 2.82840625758381648E+04
4.02439896739235914E-02 0.00000000000000000E+00 -4.02439896739235858E-01
0.00000000000000000E+00 0.00000000000000000E+00 -2.09248210623341492E+02
BC 6 3 0(1P3E25.17)
1.38436380363864547E-01 -4.98921809064772792E-01 1.12468086129738198E+00
1.14325442558403734E+00 5.50515956881686863E-01 -9.30005800767228163E-01
-9.98009512743940519E+00 -2.48375595324249708E-02 9.98470640470196713E+01
9.61406957584617916E-01 3.11437948419828955E-03 -1.36246052474731605E+04
1.20450308829068348E-01 -7.73595535159733033E-02 1.23564688768258060E-01
4.73156382486152438E-01 1.34087821455120393E+00 2.08671855656208993E-01
CC1 1 6 0(1P3E25.17)
2.11639961920025588E+00 8.47833595164392051E+00 -2.13952705688378986E+00
-8.71548396554230820E+00 -1.41421356238469098E+01 4.62410531167074812E-03

104 Adams Solver
LSOLVER
The LSOLVER command allows the user to change the linear solver used by the Adams Solver (FORTRAN).
The linear solver is invoked multiple times throughout the simulation to compute corrections in the system
state.
Format
Arguments
CALAHAN Specifies that Adams Solver (FORTRAN) is to use the CALAHAN solver exclusively.
The Calahan solver is usually faster than the Harwell solver, but it cannot analyze
systems with redundant constraints.
HARWELL Specifies that Adams Solver (FORTRAN) is to use the HARWELL solver exclusively.
The Harwell solver can analyze systems with redundant constraints, but it is usually
slower than the Calahan solver.
Tip: The CALAHAN and HARWELL solvers use somewhat different strategies for picking pivots
during the linear solution. If one solver is experiencing difficulties solving an ill-conditioned
model, you may try the other solver. One may work better on a particular model than the
other.
Caution: Even though you deactivate all your redundant constraints, Adams Solver (FORTRAN) does
not allow you to use the Calahan solver. If (under these circumstances) you issue the
LSOLVER/CALAHAN command, Adams Solver (FORTRAN) returns the message:
Changing to the CALAHAN solver is not allowed for this model due to the presence of
redundant constraints.
To avoid this problem, deactivate all your redundant constraints, run a short simulation, and
then issue the LSOLVER/CALAHAN command.

MARKER 105
MARKER
The MARKER command moves and/or reorients an existing fixed Adams Solver (FORTRAN) marker. (See
the MARKER statement for more information). You may also list information about the position of the marker.
Format
Arguments
LIST Lists the current values of the MARKER data. The data is with respect to the body
coordinate system (BCS) coordinates.
QP=x,y,z Redefines the the x-, y-, and z-coordinates of the origin of the MARKER with respect to
the PART on which it lies. The coordinates are specified in the body coordinate system
(BCS) of the element to which it belongs.
REULER=a,b,c Redefines the three-dimensional spatial orientation of the marker axes relative to the axes
of the BCS. The a, b, and c values represent a set of body-fixed 3-1-3 Euler angles
expressed in radians. These angles can be interpreted as follows:
 To orient a marker, first align the marker axes identically to the BCS axes.
 Perform a right-handed rotation of the marker x- and y-axes by a radians about
the positive z-axis of the marker.
 Rotate the marker y- and z-axes by b radians about the current marker positive x-
axis.
 Perform a right-handed rotation of the x- and y-axes of the marker by c radians
about the current z-axis of the marker.
This technique can be used to define any arbitrary orientation of the marker relative to
the part BCS. To enter the Euler angles in degrees instead of radians, add a D after each
value.
106 Adams Solver
RM=id Redefines a reference marker on the same part with respect to which Adams Solver
(FORTRAN) interprets QP, XP, ZP, and REULER.
USEXP When using the x-point-z-point method of orientation, USEXP causes the marker to be
oriented with the x-axis lying on XP and ZP lying in the positive x-z plane. This is useful
to orient markers for use in BEAM statements. See Examples of using the ZP, XP and USEXP.
XP=x,y,z By default, redefines the BCS coordinates of any point in the positive x-z plane of the
marker, but not on the z-axis of the marker. A point on the positive x-axis may be the most
convenient. When used with USEXP, XP defines the BCS coordinates of any point on the
positive x-axis of the marker. See Examples of using the ZP, XP and USEXP.
ZP=x,y,z By default, redefines the BCS coordinates of any point in the positive z-axis of the marker.
When used with USEXP, ZP defines the BCS coordinates of any point in the positive x-
z plane of the marker, but not on the x-axis of the marker.See Examples of using the ZP, XP
and USEXP.
Extended Definition
The MARKER command allows you to reposition and/or reorient a fixed marker with respect to the body
coordinate system (BCS) of the element to which the marker is attached, or to another nonfloating marker
on the same element. You may use any of the standard Adams Solver (FORTRAN) methods to specify the
location and orientation of the marker. Floating markers may not be moved, but their current information
may be listed. For more information on BCS, see Coordinate Systems and Local Versus Global Geometric Data.
After a change to a MARKER, Adams Solver (FORTRAN) reprocesses the model at the next SIMULATE
conditions.
While checking, Adams Solver (FORTRAN) verifies that the model is still valid with the new MARKER
positions. If a JOINT is now misaligned, for instance, Adams Solver (FORTRAN) issues a warning or error.
Adams Solver (FORTRAN) also reinitializes user subroutines to re-establish functional dependencies. For
dataset. If you have run a previous simulation, Adams Solver (FORTRAN) begins with the final
displacements and velocities. Adams Solver (FORTRAN) then adjusts the initial conditions to ensure that
they are consistent with the model constraints. If this is the first simulation, Adams Solver (FORTRAN) also
maintains any user supplied joint initial-conditions and positions specified as EXACT.
If you change a MARKER in the middle of a simulation, by default Adams Solver (FORTRAN) splits the
tabular, request, graphics, and results output into two separate sets of output concatenated together. This
ensures that the output correctly reflects the new system geometry.
MARKER 107
misleading graphics during postprocessing. See the OUTPUT statement for more information on the
NOSEPARATOR argument.
Tip: You can use the QP argument to translate the marker while maintaining the existing
orientation. If you use only the REULER argument, Adams Solver (FORTRAN) reorients the
marker while maintaining the existing position.
Caution:  When reorienting a marker, you should completely specify the necessary information
for the selected orientation method. Adams Solver (FORTRAN) uses the new
orientation information; it does not try to combine it with old information from the
dataset statement or a previous command. For example, if you supply ZP but not XP,
Adams Solver (FORTRAN) uses a default position for the x-axis. Adams Solver
(FORTRAN) does not use a value of XP from the statement or an earlier command.
 The MARKER command cannot be used to shift a marker from one part to another.
You should ensure that the RM marker is on the same part as the marker being
moved.
 When you change a marker, Adams Solver (FORTRAN) updates all elements that
depend upon that marker. Moving a marker may have subtle effects since many
Adams Solver (FORTRAN) elements rely on them. Be careful when moving markers
not to cause unintended side effects (for example, moving both a joint and force that
share a common marker).
Examples
MARKER/10,REULER=15D,0,0
This MARKER command reorients marker 10.
MARKER/10,QP=2,15,0
This MARKER command relocates marker 10.
MARKER/10,QP=2,15,0,ZP=3,15,0
This MARKER command relocates and reorients marker 10.
MARKER/18, QP=0,0,0, REULER=0d,0d,0d, RM=8
This MARKER command repositions/reorients Marker 18 so that it has the same location and orientation
as Marker 8.
See other bordered commands available.
108 Adams Solver
MENU
The MENU command lists all of the Adams Solver (FORTRAN) interactive commands. As you progress
through the menu, Adams Solver (FORTRAN) repeatedly issues the prompt, More?. To respond, you should
enter an upper- or lower-case y or yes or press RETURN to view more about the commands. To get another
Enter Command prompt, you should enter an upper- or lower-case n or no. Adams Solver (FORTRAN) does
not prompt, More?, if the MENU command comes from a command file.
Format
MENU
MOTION 109
MOTION
The MOTION command redefines and/or lists the characteristics of a MOTION statement which specifies
a system degree of freedom as an explicitly function of time. For more information, see the MOTION statement.
Format
Arguments
ACCELERATION Respecifies that the FUNCTION argument defines the motion

acceleration as a function of time.
B1 Respecifies the first angle of the Body 1-2-3 Euler angle sequence as
a function of time.
Range: None
B2 Respecifies the second angle of the Body 1-2-3 Euler angle sequence
as a function of time.
Range: None
110 Adams Solver
B3 Respecifies the third angle of the Body 1-2-3 Euler angle sequence as
a function of time.
Range: None
DISPLACEMENT Respecifies that the FUNCTION argument defines the motion
Respecifies an expression or redefines and passes constants to a user-
e written subroutine to determine the motion. The motion must be a
 
FUNCTION =   function of time only and not a function of the state variables.
 USER ( r 1 [ ,…, r 30 ] ) 
ICDISP Respecifies the initial displacement of the motion, when the motion
ICVEL Respecifies the initial velocity of the motion, when the motion is
I=id, J=id Respecifies the identifiers of the two markers whose displacement is
being controlled.

body
JOINT Respecifies the identifier of the joint to which the motion is assigned.
The joint must be translational, revolute, or cylindrical.
LIST Lists the current values of the data in the MOTION statement.
ROTATION Respecifies that Adams Solver is to apply a rotational motion. The
type of motion is ambiguous for cylindrical joints only.
MOTSUB.

TRANSLATION Respecifies that Adams Solver is to apply a translational motion. The
type of motion is ambiguous for cylindrical joints only.
VELOCITY Respecifies that the FUNCTION argument defines the motion
velocity.
MOTION 111
X Respecifies DX(I,J,J) as a function of time.
Range: None
Y Respecifies DY(I,J,J) as a function of time.
Range: None
Z Respecifies DZ(I,J,J) as a function of time.
Range: None
Extended Definition
The MOTION command allows you to list or modify the characteristics of an existing MOTION statement.
You can change the motion definition, change the joint to which the motion is being applied, and/or change
the type of motion on a cylindrical joint.
After a change to a MOTION, Adams Solver (FORTRAN) reprocesses the model at the next SIMULATE
conditions.
While checking, Adams Solver (FORTRAN) verifies that the model is still valid with the new MOTION. If,
for example, the new MOTION conflicts with another MOTION at the same joint, Adams Solver
(FORTRAN) issues an error.
with the model constraints. If this is the first simulation, Adams Solver (FORTRAN) also maintains any user-
supplied joint initial-conditions and part positions specified as EXACT.
If you change a MOTION joint or type in the middle of a simulation, by default Adams Solver (FORTRAN)
splits the tabular, request, graphics, and results output into two separate sets of output concatenated together
with different headers. This ensures that the output correctly reflects the new system topology. Adams Solver
(FORTRAN) does not split the files if you change only the MOTION function expression.
misleading graphics during postprocessing. See the OUTPUT statement for more information on the
NOSEPARATOR argument.
112 Adams Solver
Caution: If you specify the VELOCITY or ACCELERATION argument on the MOTION command
and then use the ABAM (Adams-Bashforth and Adams-Moulton) integrator to integrate the
equations of motion, Adams Solver (FORTRAN) prevents execution. Under these
circumstances, use a Backward-Differentiation-Formula (BDF) integrator to integrate the
Examples
MOTION/3,JOINT=21
This MOTION command applies Motion 3 to Joint 21.
MOTION/11, FUNCTION=5+2*TIME
This MOTION command specifies, as a function of time, the translation or rotation for Motion 11.
OUTPUT 113
OUTPUT
The OUTPUT command redefines and/or lists the data for an OUTPUT statement.
Format
Arguments
ASCALE=r1[,r2] Rescales the translational and the rotational accelerations Adams Solver (FORTRAN)
outputs. Define r1 to scale the translational accelerations, and define r2 to scale the
rotational accelerations. Both r1 and r2 default to 1.0.
AZERO Respecifies that output accelerations less than r in magnitude are to be set equal to zero.
The value of r must be greater than zero. The value of r defaults to 1.0E-7 for output in
scientific notation and to 0.001 for output in fixed-point notation.
CHART Reproduces x-y charts of the request data for the Tabular Output file.
114 Adams Solver
DSCALE=r1[,r2] Rescales the translational and the rotational displacements Adams Solver (FORTRAN)
outputs. Define r1 to scale the translational displacements, and define r2 to scale the
rotational displacements. Both r1 and r2 default to 1.0.
DZERO Respecifies that output displacements less than r in magnitude are to be set equal to zero.
The value of r must be greater than zero. The value of r defaults to 1.0E-7 for output in
FIXED Reformats numerical output in fixed-point notation. Any values that are too small or
too large for fixed-point notation are output in scientific notation.
FSCALE=r1[,r2] Rescales the translational and the rotational forces Adams Solver (FORTRAN) outputs.
Define r1 to scale the translational forces, and define r2 to scale the rotational forces.
Both r1 and r2 default to 1.0.
FZERO Respecifies that output forces less than r in magnitude are to be set equal to zero. The
value of r must be greater than zero. The value of r defaults to 1.0E-7 for output in
GRSAVE Resaves graphics output in the Graphics file so that you can use a postprocessor to
display graphics.
LIST Lists the current values of the data in the OUTPUT statement.
NOCHART Stops producing x-y charts of the request data for the Tabular
Output file.
NOFIXED Reformats numerical output in scientific notation.
NOGRSAVE Stops saving graphics output in the Graphics file.
NOOSFORMAT Stops writing output-step-request tables to the Tabular Output file during a dynamic,
kinematic, or quasi-static equilibrium analysis. If you specify OSFORMAT, Adams
Solver (FORTRAN) outputs an output-step-request table at each output time step.
Whether you specify NOOSFORMAT or OSFORMAT, Adams Solver (FORTRAN)
always outputs an output step request table when a static equilibrium analysis is
requested.
NOPRINT Suppresses printing of all time-response-request tables. If you specify PRINT, Adams
Solver (FORTRAN) prints these tables (one table for each request) in the Tabular
Output file after the simulation is complete.
NOREQSAVE Stops saving request output in the Request file.
OUTPUT 115
NOSEPARATOR Respecifies that Adams Solver (FORTRAN) is not to write separators to the request,
graphics, results, and tabular output files when you modify the model topology in the
middle of a simulation. You can change the model topology by using interactive
commands to activate an element, deactivate an element, change a marker position, or
change the type or point of application of a force or constraint during a simulation.
When this happens, by default Adams Solver (FORTRAN) writes a separator and new
header to the request, graphics, results, and tabular output files. Adams Solver
(FORTRAN) then writes subsequent simulation output after the new headers. This
ensures that the changes are correctly reflected in the output files, but it creates two sets
of output that cannot be plotted or animated continuously. The NOSEPARATOR
argument prevents Adams Solver (FORTRAN) from breaking up the files by creating a
continuous set of output that can be plotted and animated from beginning to end.
Note: This output may be misleading because the Graphics file does not include the
effects of any changes in marker, force, or constraint positions during the
simulation. While the part motions are correct, the force, joint, and marker
graphics remain in their original positions, even if you move them during the
simulation.
NOTELETYPE Indicates that Adams Solver (FORTRAN) is to format tabular output for printers with
132 columns per line, rather than for printers with 72 columns per inch.
NOYPR Restarts outputting rotational values in psi, theta, and phi coordinates, rather than in
yaw, pitch, and roll coordinates. If during the course of a simulation this argument is
used on an OUTPUT command after using the YPR argument on the OUTPUT
command/statement, the output is part in yaw, pitch, and roll coordinates and part in
psi, theta, and phi coordinates. Output in mixed coordinates is confusing and is not
recommended.
OSFORMAT Rewrites output-step-request (OS) tables to the tabular output file immediately after
completion of each output step for dynamic, kinematic, or quasi-static equilibrium
simulation. If OSFORMAT is specified, Adams Solver (FORTRAN) outputs an OS
table at each output time step during simulation. When a static equilibrium analysis is
requested, Adams Solver (FORTRAN) always outputs an OS table whether
NOOSFORMAT or OSFORMAT is specified. Use OSFORMAT to view the values of
all requests at a particular output time or to provide printed output in cases where the
simulation might not run to completion. A simulation may not run to completion
because the model or user-written subroutines are not fully debugged. OSFORMAT
might provide information useful in debugging the model or the user-written
subroutines.
PRINT Reprints time-response-request tables (one table for each request) in the tabular output
file after the simulation is complete. Time-response-request tables list all of the values
for a single request. There is one line in the table for each output time step; the lines are
in ascending order of time.
REQSAVE Resaves the request output in the Request file so you can use a postprocessor to display
x-y plots.
116 Adams Solver
SEPARATOR Respecifies that Adams Solver (FORTRAN) is to write separators to the Request,
Graphics, Results, and Tabular Output files when you modify the model topology in the
middle of a simulation. SEPARATOR is the default. See NOSEPARATOR for the
effects of removing the separators.
TELETYPE Indicates that Adams Solver (FORTRAN) is to format tabular output for printers with
72 columns per line rather than for printers with 132 columns per line.
VSCALE=r1[,r2] Rescales the translational and the rotational velocities Adams Solver (FORTRAN)
outputs. Define r1 to scale the translational velocities, and define r2 to scale the
rotational velocities. Both r1 and r2 default to 1.0.
VZERO Respecifies that output velocities less than VZERO in magnitude are to be set equal to
zero. The value of r must be greater than zero. The value of r defaults to 1.0E-7 for
output in scientific notation and to 0.001 for output in fixed-point notation.
YPR Outputs rotational values in yaw, pitch, and roll coordinates, rather than in psi, theta,
and phi coordinates (Euler angles). NOYPR is the default. If during the course of a
simulation this argument is used on an OUTPUT command after using an OUTPUT
command/statement without the YPR argument or after using an OUTPUT command
with the NOYPR argument, the output is part in psi, theta, and phi coordinates and
part in yaw, pitch, and roll coordinates.
Extended Definition
Like the OUTPUT statement, the OUTPUT command controls the generation of the request file and
graphics file, in addition to the form, format, coordinates, filtering, and scaling of request data in the tabular
output file.
 X-y charts of the request data for the tabular output file - The output is in the same order as the
requests are in the dataset. The information about each request (including those created by an
MREQUEST command/statement) is in two parts.The left side of the first part contains a table of
simulation time and the translational information output by the request, and the right side contains
a plot of the translational information against time. The left side of the second part contains a table
of simulation time and the rotational information output by the request, and the right side contains
a plot of the rotational information against time. (The column titles can vary according to the type
of request information and other arguments on the OUTPUT command/statement.)
These plots differ in two important ways from plots created with Adams Solver (FORTRAN) or
most postprocessors. First, time is along the vertical axis in the chart plots and request data is along
the horizontal axis. Second, the chart plots are normalized; that is, each curve is scaled independently
of the others from the highest value to the lowest value for that curve. Therefore, use care when
comparing curves to one another. You can compare the shapes but not the magnitudes of the curves.
 Time-response-request tables - A time-response-request table lists all values for a single request
throughout the simulation. There is one line in the table for each output time step; the lines are in
ascending order of time.
OUTPUT 117
 Output-step-request (OS) table — An OS table lists the values of all requests at each output time
step. There is a line for each output time step, followed by one line for each request.
 Columns per line
• 72 columns
• 132 columns
• Numerical notation of request data in the Tabular Output file
 Fixed-point - Fixed-point notation expresses a decimal or an integer number without an exponent.
 Scientific - Scientific notation expresses a number as a value between 1 and 10 (the mantissa)
multiplied by the appropriate power of 10 (the exponent). Adams Solver (FORTRAN) uses E
between the mantissa and the exponent, and may use a decimal number as the value.
Coordinates of Rotational Request Data in the Tabular Output File
 Yaw, pitch, and roll angles
 Psi, theta, and phi angles
Scales for Request Data in the Tabular Output File
 Scale for displacements
 Scale for velocities
 Scale for accelerations
 Scale for forces
Filters for Request Data in the Tabular Output File
 Zero filter for displacements
 Zero filter for velocities
 Zero filter for accelerations
 Zero filter for forces
Caution:  TELETYPE or CHART cannot be used in conjunction with the OSFORMAT argument
because the OSFORMAT argument prints records 132 characters wide and because
CHART prints information next to a plot.
 The ICSAVE and NOICSAVE arguments and the .icf file have been discontinued. The
SAVE and RELOAD commands replace the OUTPUT/ICSAVE and
EXECUTION/ICSTART arguments.

118 Adams Solver
PART
The PART command redefines and/or lists the data for a PART statement. Although you cannot redefine the
center-of-mass marker, the inertia marker, the part orientation, or the part initial conditions, you can redefine
the part mass and the part principal moments of inertia about the x-, y-, and z-axis of the principal axis
coordinate system.
Format
PART/id [,MASS=r] [,IP=xx,yy,zz] [,LIST]
Arguments
IP=xx,yy,zz Respecifies the principal moments of inertia about the x-axis, the y-axis, and the z-axis of
the principal axis coordinate system.
LIST Lists the current values of the data in the PART statement.
MASS=r Respecifies the part mass.
Caution:  Do not respecify the IP argument if the PART statement IP argument includes products of
inertia (that is, xy, xz, and yz) and/or if the PART statement defines an inertia marker (IM)
different from the center-of-mass marker (CM). This is because the IP argument values
(xx, yy, and zz) are with respect to the part principal axis coordinate system. The principal
axes of a part are the coordinate axes about which mass moments are zero, that is, for
which the inertia matrix is diagonal.
 Part velocities do not change if you use the PART command to alter the mass or the
principal moments of inertia. Adams Solver (FORTRAN) applies no conservation of
momentum constraints.
Examples
PART/2, MASS=10
This PART command respecifies the mass of Part 2.
PART/5, IP=0,3,6, LIST
This PART command respecifies the principal moments of inertia of Part 5 about the x-, y-, and z-axis of the
principal axis coordinate system and lists all the data for Part 5.
PREFERENCES 119
PREFERENCES
The PREFERENCES command controls general options that apply to the model defined in the Adams
Solver (FORTRAN) dataset or the commands defined in the Adams Solver (FORTRAN) command file.
Format
120 Adams Solver
Arguments
Specifies the geometry library to be used to 3D contact

determination:
 Parasolid - Specifies the Parasolid geometry library to be

used for 3D contact determination.
 Default_library - Specifies that the default geometry library
to be used for 3D contact determination.
For more on the different libraries, see the PREFERENCES statement.
solid geometries in the model. Contact kinematics are calculated by
intersecting the meshes corresponding to two solid geometries. A
finer mesh will result in more accurate contact calculations.
However, calculations may be slower, and computer memory
requirements will increase as the mesh resolution increases.
The faceting tolerance is defined as the maximum error between the

true surface and the surface of the faceted representation of the
geometry. The maximum error is guaranteed not to exceed (1/value)
* the minimum dimension of each geometry's bounding box.

cylinder, box, frustum, torus, surface of revolution, and extrusion) is
tessellated with a fixed tolerance when a faceting tolerance is
specified. Stl and shl files have fixed faceting that cannot be changed.
PREFERENCES 121
Specifies whether or not to stop command-file execution when a

simulation fails.
 STOPCF 
SIMFAIL =  
 NOSTOPCF  A value of STOPCF indicates that Adams Solver (FORTRAN)
should stop if a static, quasi-static, kinematic, or dynamic analysis
fails to find a solution or reach the specified end time. Adams Solver
(FORTRAN) finishes writing output and exit, just as if a STOP
command were the next command in the command file.
A value of NOSTOPCF indicates that Adams Solver (FORTRAN)

should continue to process commands from a command file even
after a simulation fails.
When you run Adams Solver, this specifies which version of Adams
Solver to run: C++ (Cxx), FORTRAN (F77), or none. Adams Solver
 CXX 
  only runs the version if it supports your model. For example, the
SOLVERBIAS =  F77  Adams Solver (FORTRAN) supports some statements that are not
  supported in Adams Solver (C++). If "none" is selected, Adams
 NONE  Solver uses the default solver.
If the simulation is being run with an command file (.acf ) and the
.acf file has a Preferences/SolverBias={Cxx,F77,none} command in
it, Adams Solver runs with the specified solver. If more than one
Preferences/SolverBias commands is present, it uses the first
command it finds. Issuing this command during a simulation has no
effect. This argument is only useful when executing Adams Solver
from a command file.
When you are running Adams Solver (FORTRAN), and issue

Preferences/SolverBias=Cxx, Adams Solver returns the following
warning:
---- WARNING ----

Once the Solver session is executing it is not possible
to change to the Cxx Solver. Solverbias=cxx is being
ignored, and the simulation is proceeding with the F77
Solver.
If you are running Adams Solver C++, and issue

Preferences/SolverBias=F77, Adams Solver ignores the command.
LIST Lists the current values of the PREFERENCES statement.
Examples
Using the Parasolid geometry library provided by MSC:
122 Adams Solver
Caution: CONTACT_GEOMETRY_LIBRARY and CONTACT_FACETING_TOLERANCE

parameters are accepted only at the start of the simulation. Once the simulation starts changing
these parameters will not affect the simulation.

RELOAD 123
RELOAD
The RELOAD command restarts a simulation from a previously saved model or simulation state.
Format
Arguments
FILE=c Specifies the complete name of a file you created with the SAVE command. The
file name may include the directory on operating systems that support path names,
such as Linux. There is no default extension for this file. Because the FILE
argument and value can be at most eighty characters long, the file name and path
name are limited from seventy-five characters (if you do not abbreviate FILE=) to
seventy-six characters (if you abbreviate FILE= to FIL=).
OUTPUT_PREFIX=c Optionally specifies a new base (root) name for output files (.req, .res, .gra, .out,
and so on) from simulations which follow this RELOAD command. If you do not
specify the OUTPUT_PREFIX argument, Adams Solver (FORTRAN) appends
the output to the currently-open output files after writing a special delimiter line
into the file. Because the OUTPUT_PREFIX argument and value can be at most
eighty characters long, the basename and path are limited from sixty-six characters
(if you do not abbreviate OUTPUT_PREFIX) to seventy-six characters (if you
abbreviate OUTPUT_PREFIX to OUT=).
124 Adams Solver
STATES Specifies Adams Solver (FORTRAN) reloads just the saved simulation time and
state values (displacements, velocities, force values, user-defined variable values,
and so on), while maintaining the existing model definition.
SYSTEM Specifies Adams Solver (FORTRAN) reloads the entire saved system, including
the model definition (parts, markers, joints, and so on), simulation time and state
on) and solver data (integrator parameters, state derivatives, and so on). This
completely replaces the existing model and simulation conditions with the saved
TITLE=c Optionally specifies a new title for the model in output from simulations which
follow this RELOAD command. The title string may not contain any special
Adams Solver (FORTRAN) characters and must fit on a single line (no
continuations). If not the last argument, the title is terminated by the last non-
blank prior to the following comma. Because the TITLE argument and value can
be at most eighty characters long, the file name and path name are limited from
seventy-four characters (if you do not abbreviate TITLE=) to seventy-six
characters (if you abbreviate TITLE= to TIT=).
Extended Definition
Using the RELOAD command with the STATES argument allows you to reload the saved simulation time
and state values, including displacements, velocities, force values, and user-defined variable values. Adams
Solver (FORTRAN) resets the simulation time to the saved values, and uses the saved states as initial
conditions for the next simulation.
Using the RELOAD command with the SYSTEM argument allows you to reload the entire saved system,
including the model definition (parts, markers, joints, and so on), simulation time and state values
(displacements, velocities, force values, user-defined variable values, and so on) and solver data (integrator
parameters, state derivatives, etc.). Adams Solver (FORTRAN) completely resets all model, simulation, and
solver data to that stored in the file. Except for interactive plotting, Adams Solver (FORTRAN) responds to
subsequent commands just as it would have at the time the file was saved. (Since past simulation results are
not stored in the Save file, they cannot be plotted when the file is restored.)
Tip: Except for the leading delimiter line, the appended sections of the output files are complete
(that is, they may be extracted with any editor, renamed, and handled like any other Adams
Solver (FORTRAN) output).
RELOAD 125
across platforms or between versions of Adams Solver (FORTRAN).
 Results are unpredictable if saved STATES arguments are reloaded to different models
from those that existed at the time of the save.
 The OUTPUT/ICSAVE-EXEC/ICSTART combination is now obsolete and is removed
from a future version of Adams Solver (FORTRAN).
command.
Examples
RELOAD/SYSTEM,FILE=TCT1.SAV,TITLE=TEST#2
This RELOAD command reloads the model and simulation states saved in file TCT1.SAV. Adams Solver
(FORTRAN) appends subsequent output to the currently open output files with the new title TEST#2.
RELOAD/STATES,FILE=BASE.SAV,OUTPUT_PREFIX=RUN2
This RELOAD command reloads the simulation states saved in file BASE.SAV. Adams Solver (FORTRAN)
creates a new set of output files RUN2.REQ, RUN2.GRA, and so on.
The SAVE and RELOAD commands can help simulate several versions of the same model when used with
other interactive Adams Solver (FORTRAN) commands. SAVE/SYSTEM creates a baseline configuration
that you can then reload and simulate repeatedly without leaving Adams Solver (FORTRAN). After each
RELOAD/SYSTEM, you may modify the model, and use the ACTIVATE and DEACTIVATE commands
to switch sets of loads on and off, for example.
file loads example.adm, the original model, that contains three sets of forces. After deactivating all the forces
example
case1
dea/sfo,id=101,102,201,202,301 !Deactivate all forces
,302
sim/static !Find static equilbrium
save/system, file=ex.sav ! Save system at static, no
forces
sim/dyn, end=.25, steps=100 !Simulate
126 Adams Solver
rel/system, file=ex.sav, ! Reload(now back at static,no

out=case2 forces)
rel/system, file=ex.sav, ! Reload(now back at static,no
out=case3 forces)
stop

REQUEST 127
REQUEST
The REQUEST command redefines and/or lists the data for a REQUEST statement, and/or redefines the
function expressions for a REQUEST statement.
Format
Arguments
F1=e Redefines the first component of the request that is being specified. If the F1
argument is used, it must either be the last argument in the REQUEST
statement or be followed by a backslash (\) (not a comma). Adams Solver
(FORTRAN) writes the expression value to the corresponding column of the
tabular output file, but not to the request file.
F2=e Redefines the second component of the request that is being specified. If the
F2 argument is used, it must either be the last argument in the REQUEST
tabular output file and to the request file.
F3=e Redefines the third component of the request that is being specified. If the F3
128 Adams Solver
F4=e Redefines the fourth component of the request that is being specified. If the
F5=e Redefines the fifth component of the request that is being specified. If the F5
tabular output file, but not to the request file.
F6=e Redefines the sixth component of the request that is being specified. If the F6
F7=e Redefines the seventh component of the request that is being specified. If the
F8=e Redefines the eighth component of the request that is being specified. If the
FUNCTION=USER(r1[, Redefines and passes constants (r1[,...,r30]) to the user-written subroutine
...,r30])[/] REQSUB to define the request (see REQSUB Using Adams Solver Subroutines).
If the FUNCTION argument is used, it must either be the last argument in
the REQUEST statement or be followed by a backslash (\). All eight columns
of the data that can be defined in a REQSUB are written in the tabular output
file. Only columns 2, 3, and 4 and columns 6, 7, and 8 are written in the
request file.
LIST Lists the current values of the data in the REQUEST statement.
ROUTINE=libname::sub Specifies an alternative library and name for the user subroutine REQSUB.
name
Examples
REQUEST/21, F4=DX(2110, 409)/F8=DX(2115, 409)
This REQUEST command changes the fourth and eighth expressions for REQUEST/21. The other
function expressions remain as they were.
SAVE 129
SAVE
The SAVE command stores the current Adams Solver (FORTRAN) model and simulation conditions or only
the current simulation states. This allows you to return to the model or states at a later time using the RELOAD
command.
Format
Arguments
AUTOSAVE=i Indicates that Adams Solver (FORTRAN) is to save the simulation states every i
output steps. Each subsequent SAVE command overwrites the previous one.
Setting AUTOSAVE to zero turns AUTOSAVE off.
Range: i > 0
FILE=C Specifies the complete file name where Adams Solver (FORTRAN) writes the
SAVE command information. The file name may include the directory on
operating systems that support such path names, such as Linux. There is no default
extension for this file.
STATES Specifies Adams Solver (FORTRAN) to save just the current simulation time and
state values (displacements, velocities, force values, user-defined variable values,
etc.). The RELOAD/STATES command can later reload these states to restart the
simulation from this point.
SYSTEM Specifies Adams Solver (FORTRAN) to save the entire current system, including
the model definition (parts, markers, joints, and so on), simulation time and state
on) and solver data (integrator parameters, state derivatives, and so on). SYSTEM
creates a complete record of the current model and simulation conditions. The
RELOAD/SYSTEM command can later reload this record to return to these
Extended Definition
You can use the SAVE command with the STATES argument to save the current simulation time and state
values, including displacements, velocities, force values, and user-defined variable values. You can later restart
130 Adams Solver
a simulation from this point by reloading the states with the RELOAD/STATES command. When you reload
this file, Adams Solver (FORTRAN) resets the simulation time to the saved value and uses the saved states as
initial conditions for the next simulation.
You may use the SAVE command with the SYSTEM argument to save the entire current system, including
the model definition (parts, markers, joints, and so on), simulation time and state values (displacements,
velocities, force values, user-defined variable values, and so on), and solver data (integrator parameters, state
derivatives, and so on). SAVE/SYSTEM creates a complete record of the current model and simulation
conditions. You can later return to this point by reloading the conditions using the RELOAD/SYSTEM
command.
When you reload a system file, Adams Solver (FORTRAN) completely resets all model, simulation, and
solver data to that stored in the file. Except for interactive plotting, Adams Solver (FORTRAN) responds to
subsequent commands just as it would have at the time the file was saved. (Since past simulation results are
not stored in the save file, they cannot be plotted when the file is restored.)
Tip: You can use the AUTOSAVE=i argument feature to “checkpoint” a difficult simulation at the
specified interval. If the simulation fails, you can debug it by restarting the simulation from
the last saved step. This is very similar to the OUTPUT/ICSAVE-EXEC/ICSTART capability
which the SAVE/RELOAD command now supersedes.
Caution:  The AUTOSAVE=i argument function continually overwrites the information in the
specified file. Therefore, this file contains only one set of states. For multiple files, you
need to specify multiple times with different file names with the SAVE command.
 Files are saved in a machine- and code-dependent binary format. They are not
portable across platforms or between versions of Adams Solver (FORTRAN).
 Results are unpredictable if saved states are restored to different models from those
that existed at the time of the save.
 The OUTPUT/ICSAVE-EXEC/ICSTART combination is now obsolete and is
removed from a future version of Adams Solver (FORTRAN).
 Adams Solver (FORTRAN) turns AUTOSAVE off if you ACTIVATE an element,
DEACTIVATE an element, or modify an SFORCE, MARKER, or MOTION.
 Models containing nonlinear flexible bodies are not supported by the
[SAVE/RELOAD] command.
Examples
SAVE/SYSTEM,FILE=BASE1.SAV
This SAVE command saves the current model and simulation information in file BASE1SAV. When this file
is reloaded with the RELOAD command, Adams Solver (FORTRAN) returns to this exact configuration.
SAVE/STATES,AUTOSAVE=10,FILE=AS.SAV
This SAVE command saves the simulation states in file AS.SAV at every tenth output step. When this file is
reloaded, Adams Solver (FORTRAN) resets the current model with the saved states.
SAVE 131
Used with other interactive Adams Solver (FORTRAN) commands, SAVE and RELOAD can help simulate
several versions of the same model. SAVE/SYSTEM creates a baseline configuration which you can then
reload and simulate repeatedly without leaving Adams Solver (FORTRAN). After each RELOAD/SYSTEM,
you may modify the model. This can be done by using the ACTIVATE and DEACTIVATE commands to
switch sets of loads on and off, for example.
file loads example.adm, the original model, which contains three sets of forces. After deactivating all the forces
example
case1
dea/sfo,id=101,102,201,202,301,302 ! Deactivate all forces
sim/static ! Find static equilibrium
stop

132 Adams Solver
SENSOR
The SENSOR command lists the data for a SENSOR statement, and/or redefines the function expression.
Format
Arguments
EVALUATE_ROUTINE=libname::subname Specifies an alternative library and name for the user subroutine
SEVSUB.

Respecifies an expression or defines and passes constants to a user-
e written subroutine to define the sensor. To define the sensor with
 
FUNCTION =   an expression, follow FUNCTION with an equal sign and the
 USER ( r 1 [ ,…, r 30 ] )  expression (e).
To define the sensor with a user-written subroutine, follow

the values (r1[,...,r30]) that you want Adams Solver (FORTRAN)
to pass to the user-written subroutine SENSUB. If the
FUNCTION argument is used, it must either be the last argument
in the SENSOR statement or be followed by a backslash (\).
Range: An expression or a user parameter list of 1 to 30 real values

LIST Lists the current values of the data in the SENSOR statement.
SENSUB.
Examples
SENSOR/231, FUNCTION=DX(0202,0307)
This SENSOR command changes the function for SENSOR/231 to DX(0202,0307).
SENSOR 133

134 Adams Solver
SFORCE
The SFORCE command lists or changes the characteristics of an SFORCE statement.
Format
SFORCE 135
Arguments
ACTIONONLY Respecifies an action-only force. Adams Solver (FORTRAN) applies

no reaction at the J marker.
Respecifies an expression or redefines and passes constants to a user-
e written subroutine to redefine a single-component force. To redefine
 
FUNCTION =   the force with an expression, follow FUNCTION with an equal sign
 USER ( r 1 [ ,…, r 30 ] )  and the expression. To redefine the force with a user-written
string USER, and the values (r1[,...,r30]) that you want Adams
Solver (FORTRAN) to pass to the user-written evaluation
subroutine SFOSUB. If the FUNCTION argument is used, it must
either be the last argument in the SFORCE statement or be followed
by a backslash (\). The force function may be changed from an
expression to the subroutine or the reverse. If neither argument is
given, the force definition does not change. FUNCTION must
either be the last argument given, or be followed by a backslash (\).
I=id,J=id Respecifies the identifiers of two markers necessary to define the
force. If the SFORCE command defines a translational action-
reaction force, I and J specify the identifiers of the two markers
between which you want to exert the force. Adams Solver
(FORTRAN) applies the translational action-reaction force along
the line of action defined by the line segment connecting I and J. If
the SFORCE command defines an action-only force, I specifies the
point of application, and the z-axis of J specifies the direction of the
force. If SFORCE defines a torque, the z-axis of the J marker specifies
the axis of rotation. In the case of action-reaction torques, the z-axis
of the J marker must be parallel to, and pointed in the same direction,
as the z-axis of the I marker.
LIST Lists the current values of the data in the SFORCE statement.
REACTION Respecifies an action-reaction force. Adams Solver (FORTRAN)
applies reaction forces or torques at the J marker.
TRANSLATION Respecifies a translational SFORCE.
ROTATION Respecifies a rotational SFORCE.
SFOSUB.
Extended Defintion
The SFORCE command lists or changes the characteristics of an existing SFORCE element. You can alter
one or both points of force application, change the force from ACTIONONLY to ACTION-REACTION,
136 Adams Solver
or the reverse, or change the force from TRANSLATION to ROTATION, or the reverse. In addition, you
can change the force definition function expression or SFOSUB parameter list, or switch the definition
between function expression and subroutine.
After a change to an SFORCE, Adams Solver (FORTRAN) reprocesses the model at the next SIMULATE
conditions.
While checking, Adams Solver (FORTRAN) verifies that the model is still valid with the new SFORCE. If,
for example, the SFORCE function expression refers to an inactive element, Adams Solver (FORTRAN)
issues an error.
each element that refers to a user-written subroutine, Adams Solver calls the user-written subroutine with
IFLAG set to true.
with the model constraints. If this is the first simulation, Adams Solver (FORTRAN) also maintains any user
supplied joint initial-conditions and positions specified as EXACT.
If you change an SFORCE I marker, J marker, or type in the middle of a simulation, by default Adams Solver
(FORTRAN) splits the tabular, request, graphics, and results output into two separate sets of output
concatenated together. This ensures that the output correctly reflects the new system topology. Adams Solver
(FORTRAN) does not split the files if you change only the SFORCE function expression.
misleading graphics during postprocessing. For more information on the NOSEPARATOR argument, see
OUTPUT.
Examples
SFORCE/201,FUNCTION=-10.*VR(101,201)
This SFORCE command changes the force definition for SFORCE 201.
SFORCE/6,I=28
This SFORCE command applies SFORCE 6 to Marker 28, leaving the J marker unchanged.
SHOW 137
SHOW
The SHOW command lists statistics for any of these topics: CPU time, graphics options, status, and time.
Format
Arguments
CPUTIME Lists the current total use of CPU time for the execution.
GROPTIONS Lists the options controlling graphics display.
Lists the statistics for each GRAPHICS statement, the statistics for
each REQUEST statement, or the statistics for the simulation, or
all of these statistics.
TIME Lists the current time and date.

138 Adams Solver
SIMULATE
The SIMULATE command specifies the type of simulation you want Adams Solver (FORTRAN) to run. It
also defines the run time and the number or size of the output steps.
Format
Arguments
ACCELERATION Specifies that initial displacement, velocity, and acceleration analyses of the
mechanism are to be performed if such analyses have not already been
performed at the current time step and with the current model.
DISPLACEMENT Specifies that an initial displacement analysis of the mechanism is to be
performed if such an analysis has not already been performed at the current
time step and with the current model.
DTOUT=r Specifies the size of the output step for the analysis in model time units.
Range: DTOUT > 0

DURATION Specifies the duration of the analysis in model time units.
Range: DURATION > 0

SIMULATE 139
DYNAMICS Specifies that Adams Solver (FORTRAN) is to integrate the dynamics

equations. If a dynamic analysis is requested for a system with zero degrees of
freedom, Adams Solver (FORTRAN) issues a warning message and integrates
the equations instead of using kinematic analysis. Kinematic analysis is faster.
END Specifies the end time for a dynamic, a kinematic, or a quasi-static equilibrium
analysis.
Range: END > Begin Time > 0

INITIAL_CONDITION Specifies that an initial-conditions analysis of the mechanism is to be
S performed. All three initial-conditions analyses are performed if 1) no
DISPLACEMENT, VELOCITY, or ACCELERATION argument or if 2) the
ACCELERATION argument is specified and no initial condition analyses
have been performed at the current time step with the current model.
Displacement and velocity initial conditions are performed if the VELOCITY
argument is specified and no initial condition analyses have been performed at
the current time step with the current model. Displacement initial conditions
are performed if the DISPLACEMENT argument is specified and no initial-
conditions analyses have been performed at the current time step with the
current model.
KINEMATICS Specifies that Adams Solver (FORTRAN) is to run a kinematic analysis. If a
kinematic analysis is requested for a system with one or more degrees of
freedom, Adams Solver (FORTRAN) issues an error message and ignores the
entire command.
STATICS Specifies that Adams Solver (FORTRAN) perform either a static equilibruim
simulation or a quasi-static equilibrium simulation. Adams Solver
(FORTRAN):
 Performs a static equilibrium simulation at the current time if you use

the STATICS argument and you do not specify an end time or steps.
 Performs a quasi-static equilibrium simulation if you use the
STATICS argument and specify an end time and steps.
 Uses kinematic analyses to perform static simulations for models that
have zero degrees of freedom. If you request a quasi-static simulation
on a model that has zero degrees of freedom, Adams Solver
(FORTRAN) computes the same motion as in a kinematic analysis,
but ignores (set to zero) velocities and accelerations.
 Uses dynamic analyses to perform static simulations when you issue
the EQUILIBRIUM/DYNAMIC statement/command. See the
EQUILIBRIUM statement.
140 Adams Solver
STEPS=i Specifies the number of output steps wanted for the analysis.
Range: STEPS > 1

TRANSIENT Specifies that Adams Solver (FORTRAN) is to run a kinematic analysis if the
system has zero degrees of freedom or a dynamic analysis if the system has one
or more degrees of freedom.
VELOCITY Specifies that initial displacement and velocity analyses of the mechanism are
to be performed if such analyses have not already been performed at the
current time step and with the current model.
Extended Definition
Adams Solver (FORTRAN) allows you to do one or more analyses on the same dataset until the STOP
command is issued. These analyses can be different types as long as they meet the degree-of-freedom
requirements for that type of analysis. For example, it is often useful or necessary to do a static equilibrium
analysis on a model to establish equilibrium conditions before doing a dynamic analysis.
Tip: Note the distinction between END and DURATION. At time zero, a SIMULATE command
with END=1 or DURATION=1 indicates an end time of one second. At time one second, a
SIMULATE command with END=1.5 indicates an end time of 1.5 seconds; a SIMULATE
command with DURATION=1.5 indicates an end time of 2.5 seconds.
SIMULATE 141
Caution:  Before a dynamic simulation that follows a static simulation, Adams Solver (FORTRAN)
computes the velocity and acceleration initial conditions even if they were computed prior to
the static simulation. This ensures that the velocity and acceleration initial conditions are
consistent with the displacements from the static simulation.
 When you use END and STEPS parameters with the SIM/STAT command, time
increments past time = 0. As such, initial velocities are no longer valid and are not considered
in subsequent dynamic analyses.
 If a static simulation directly follows a dynamic simulation, Adams Solver (FORTRAN) sets
the velocities and accelerations (except gravity) to zero and repeats the displacement initial
conditions.
 For a zero-degree-of-freedom model, Adams Solver (FORTRAN) solves the kinematic
equations during a static simulation. This means that, even though it is a static simulation,
Adams Solver (FORTRAN) uses the parameters from the KINEMATICS statement or
command (not the EQUILIBRIUM statement or command) and sets the MODE analysis
constant to 1 (not 5 or 6).
 Adams Solver (FORTRAN) automatically performs a dynamic analysis for kinematic
systems that include DIFFs and sets the MODE analysis constant to 4 (not 1).
 The STEPS and DTOUT arguments can indirectly affect the accuracy of the results
computed by the integrator. Under these circumstances, Adams Solver (FORTRAN)
controls solution error by adjusting the integration time step to meet the error tolerance
specified by the integrator or default values. These integrators do not use a time step greater
than the interval to the next output time, however. The output times are determined by
STEPS or DTOUT in combination with END or DURATION. Specifying a smaller
output step than the integrators would ordinarily take results in more integrator steps than
actually required to meet the error tolerance. In this case, varying the output step may vary
the accuracy of the computed results, although all results are within the specified error
tolerance. If the computed solution changes greatly when you change STEPS or DTOUT,
the error tolerance is too large. You should reduce the error tolerance. If you set the error
tolerance properly, the number of output steps should have very little effect on the
computed results.
 Adams Solver (FORTRAN) may internally construct one or more differential elements in
order to handle velocity and acceleration constraints. In those cases, the model will never be
kinematical. Hence, attempts to run SIMULATE/KINEMATICS will trigger the dynamic
solver to run the simulation.
Examples
SIMULATE / KINEMATICS, END=5, STEPS=200
This SIMULATE command instructs Adams Solver (FORTRAN) to perform a kinematic analysis from the
begin time to 5 time units with 200 output steps. If this is the first analysis on this dataset in this session, the
begin time is 0 time units. Adams Solver (FORTRAN) can execute this command only if the system has zero
degrees of freedom.
SIMULATE / KINEMATICS, DURATION=2, DTOUT=.025
142 Adams Solver
This SIMULATE command instructs Adams Solver (FORTRAN) to perform a kinematic analysis for 2 time
units with one output step every .025 time units.
SPLINE 143
SPLINE
The SPLINE command modifies or lists an existing SPLINE statement. You can change the values of the
SPLINE data, and in the process increase or decrease the number of X data or the number of curve families.
You cannot change the extrapolation method, nor can you read data from a file.
 For information on the corresponding statement, see the SPLINE statement.
 For information on the corresponding subroutine, see the SPLINE_READ subroutine.
Format
SPLINE/id
, X=x1, x2, x3, x4 [, . . . , xn]
, Y=y1, y2, y3, y4 [, . . . , yn]
, LIST
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, y34 [, . . . ,y4n]
, Y=z4, y41, y42, y43, y44 [, . . . ,y4n]
[, . . . , Y=zm, ym1, ym2, ym3, ym4,[, . . . ,ymn]]
, LIST

144 Adams Solver
Arguments
X=x1,x2,x3,x4[ , . . . , xn]  Specifies at least four x values. The maximum number of x

values, n, depends on whether you specify a single curve or
a family of curves.
 Values must be constants; Adams Solver (FORTRAN)
does not allow expressions.
 Values must be in increasing order: x1< x2 < x3, and so
on.
Y=y1,y2,y3,y4 [ , . . . , yn]  Approximates a single curve by specifying the
corresponding y value: y1,y2,y3,y4[, . . . ,yn] for each x
value.
 Values must be constants; Adams Solver (FORTRAN)
does not allow expressions.
Y=z1,y11,y12,y13,y14 [ , . . . , y1n]  Approximates a family of curves by specifying the
,Y=z2,y21,y22,y23,y24 [ , . . . , y2n] corresponding y values, y1,y2,y3,y4[, . . . ,yn], for the x
,Y=z3,y31,y32,y33,y34 [ , . . . , y3n] values at unique z values (z1[, . . . ,zm]).
,Y=z4,y41,y42,y43,y44 [ , . . . , y4n]  Values must be constants; Adams Solver (FORTRAN)
[ ,...,Y=zm,ym1,ym2,ym3,ym4 [ , . . . , does not allow expressions.
ymn]]
 Values for z must be in increasing order: z1 < z2 < z3, and
so on.
LIST Lists the current SPLINE data.

SPRINGDAMPER 145
SPRINGDAMPER
The SPRINGDAMPER command redefines and/or lists the data for a SPRINGDAMPER statement. You cannot
redefine the I and J marker defining the springdamper or the translational/rotational characteristic, but you
can redefine other characteristics.
Format
Arguments
ANGLE=r Respecifies the reference angle for the torsional spring. If the reference torque of the spring is
zero, ANGLE equals the free angle. Adams Solver (FORTRAN) assumes ANGLE is in
radians unless a D is added after the value.
C=r Respecifies the viscous damping coefficient for the force. The force due to damping is zero
when the system is at rest. C must be greater than or equal to zero.
CT=r Respecifies the viscous damping coefficient for the torque. The torque due to damping is zero
when the system is at rest. CT must be in units of torque per radian per unit of time.
Range: CT > 0
FORCE=r Respecifies the reference force at LENGTH.
K=r Respecifies the spring stiffness coefficient for the force.
Range: K > 0
KT=r Respecifies the spring stiffness coefficient for the torque. KT must be in units of torque per
radian.
Range: KT > 0
146 Adams Solver
LENGTH=r Respecifies the reference LENGTH for the spring. If the reference force of the spring is zero,
Range: LENGTH > 0

LIST Lists the current values of the data in the SPRINGDAMPER statement.
TORQUE=r Respecifies the reference torque of the torsional spring at ANGLE.

STOP 147
STOP
The STOP command terminates execution of Adams Solver (FORTRAN) in the interactive mode and
returns control to the operating system.
Format
STOP
148 Adams Solver
STRING
The STRING command redefines and/or lists the data for a STRING statement.
Format
STRING/id [,STRING=c] [,LIST]
Arguments
STRING=c Respecifies the string to be stored. The STRING argument and value must appear
together on one 80-character line. If STRING is abbreviated to S and starts a line, the
supplied string can be as long as 1024 characters.
LIST Lists the string in storage.
Caution: The following characters are not permitted in a STRING argument because they are delimiters
in the Adams Solver (FORTRAN) command language: comma (,), semicolon (;), ampersand
(&), and exclamation point (!). This is because the comma indicates that additional Adams
Solver (FORTRAN) arguments follow, the semicolon indicates that additional Adams Solver
(FORTRAN) statements follow on the same line, the ampersand indicates that the next line is
a continuation of the statement on this line, and the exclamation point indicates that Adams
Solver (FORTRAN) is to stop reading the line.

TIME 149
TIME
The TIME command shows the simulation time, integration step size, number of function evaluations
completed, and number of integration steps completed.
Format
TIME
Examples
TIME
Current Simulation Time = 5.0E-02

Current Integration Step Size = 1.0E-03
Number of Function Evaluations = 133
Number of Integration Steps = 59

150 Adams Solver
UCON
The UCON command redefines and/or lists the parameters for a UCON statement.
Format
UCON/id [,FUNCTION=USER(r1[,...,r30)[/]] [,LIST]
Arguments
FUNCTION=USER(r1[,...,r30]) Respecifies and passes up to thirty constants to the UCOSUB user-

written subroutine. These can be part identifiers, variable codes, and
other data that the UCOSUB user-written subroutine needs to define
the constraint. If the FUNCTION argument is used, it must be either
the last argument in the UCON command or be followed by a
backslash (\).
LIST Lists the current values of the data in the UCON statement.
Caution: If you use the UCON command for a velocity-dependent constraint and then use the Adams-
Bashforth and Adams-Moulton (ABAM) integrator to integrate the equations of motion,
Adams Solver (FORTRAN) prevents execution. Under these circumstances, use a Backward-
Differentiation-Formula (BDF) integrator to integrate the equations of motion.

VARIABLE 151
VARIABLE
A VARIABLE command redefines or lists data for a VARIABLE statement that defines a variable in terms of a
scalar algebraic equation. The variable can be either independently used, or as part of the PINPUT,
POUTPUT, or ARRAY statement.
Format
Arguments
Respecifies an expression or redefines and passes constants to

e a user-written subroutine to define a variable. If you want to
 
FUNCTION =   define the variable with an expression, FUNCTION must
 USER ( r 1 [ ,…, r 30 ] )  be followed with an equal sign and the expression. If you
want to define the variable with a user-written subroutine,
that Adams Solver (FORTRAN) passes to the user-written
subroutine VARSUB.
IC=r Respecifies an approximate initial value for the VARIABLE.
Adams Solver (FORTRAN) may adjust the value of IC when
it performs an initial condition analysis. Entering an
accurate value for IC may help Adams Solver (FORTRAN)
converge to the initial conditions solution.
LIST Lists the current values of the VARIABLE arguments.
subroutine VARSUB.
Extended Definition
The VARIABLE command redefines or lists a user-defined algebraic equation and its initial value.
After a change to a variable, Adams Solver (FORTRAN) reprocesses the model at the next SIMULATE
152 Adams Solver
conditions.
subroutine with the IFLAG argument set to true.
Tip: Consider using ARRAY instead of VARIABLE if the function is a constant value.
Caution:  Caution should be used when defining a VARIABLE statement that is dependent on
another VARIABLE statement or on an Adams Solver (FORTRAN) statement that
contains functions. If a defined system of equations does not have a stable solution,
convergence may fail for the entire Adams Solver (FORTRAN) model. The following
V=V+1.
However, when Adams Solver (FORTRAN) tries to solve this equation using the
Newton-Raphson iteration, the solution diverges and a message appears on the screen
indicating that the solution has failed to converge.
 The IC argument can be altered only prior to a simulation. If you run a simulation
and then try to alter IC, Adams Solver (FORTRAN) rejects the entire VARIABLE
command.
exception or lead Adams Solver (FORTRAN) away from the desired solution.

VFORCE 153
VFORCE
The VFORCE command redefines and/or lists the data for a VFORCE statement that defines a translational
vector force element as specified using three orthogonal components.
Format
Arguments

FUNCTION=USER(r1[,...,r30]) Respecifies up to 30 user-defined constants for use in computing the
force components in a user-defined subroutine VFOSUB.
I=id Respecifies the marker at which Adams Solver (FORTRAN) applies the
action force. You must ensure that the I marker is a fixed marker and on
Adams Solver (FORTRAN) always applies the force at a fixed point on
the part.
154 Adams Solver
JFLOAT=id Respecifies the marker at which Adams Solver (FORTRAN) applies the
marker and on a different part than the I marker. Adams Solver
(FORTRAN) moves the JFLOAT marker to keep it superimposed on
the I marker, which means that the reaction force may move with
respect to the part. Adams Solver (FORTRAN) does not calculate
LIST Lists the current values of the VFORCE arguments.
RM=id Respecifies the marker that determines the orientation of the force
ROUTINE=libname::subname Specifies an alternative library and name for the user subroutine VFOSUB.
Extended Definition
The VFORCE statement lists or redefines a force element that consists of three mutually orthogonal
translational force components. You can alter one or both points of force application, change the force
reference marker, and change the force function expressions or the parameters passed to the VFOSUB user-
written subroutine.
After a change to a VFORCE, Adams Solver (FORTRAN) reprocesses the model at the next SIMULATE
conditions.
While checking, Adams Solver (FORTRAN) verifies that the model is still valid with the new VFORCE. If,
for example, the VFORCE function expression refers to an inactive element, Adams Solver (FORTRAN)
issues an error.
If you change a VFORCE I marker, J marker, or type in the middle of a simulation, by default Adams Solver
(FORTRAN) splits the tabular, request, graphics, and results output into two separate sets of output that are
concatenated. This ensures that the output correctly reflects the new system topology. Adams Solver
(FORTRAN) does not split the files if you change only the VFORCE function expression or use the LIST
arguments.
VFORCE 155
argument.
same part as the I marker, or the JFLOAT marker, or to a third, unrelated part.
Caution: The user-defined functions FX, FY, and FZ should be smooth, continuous, and single-valued.

156 Adams Solver
VTORQUE
The VTORQUE command redefines and/or lists the data for a VTORQUE statement that defines a vector
torque that consists of three orthogonal components.
Format
Arguments
FUNCTION=USER(r1[,...,r30]) Respecifies up to thirty user-defined constants used to compute the

torque components in an externally-defined subroutine VTOSUB.
JFLOAT=id Respecifies the marker on the part to which Adams Solver
(FORTRAN) applies the reaction torque. You must ensure that the
JFLOAT marker is a floating marker and on a different part than the I
marker. Adams Solver (FORTRAN) moves the JFLOAT marker to
keep it superimposed on the I marker. Adams Solver (FORTRAN)
does not calculate reaction forces when the JFLOAT marker is on the
ground part.
I=id Respecifies the marker on the part to which Adams Solver
(FORTRAN) applies the action torque. You must ensure that the I
marker is a fixed marker and on a different part than the JFLOAT
marker.
LIST Lists the current values of the VTORQUE arguments.
RM=id Respecifies the marker that determines the orientation of the torque
VTOSUB.

VTORQUE 157
TX=e Respecifies the magnitude and sign of the x component of the torque
right-hand rule (i.e., a positive torque causes a counterclockwise
rotation).
TY=e Respecifies the magnitude and sign of the y component of the torque
component is parallel to the y-axis of the RM marker in the sense of
the right-hand rule (that is, a positive torque causes a counterclockwise
rotation).
TZ=e Respecifies the magnitude and sign of the z component of the torque
rotation).
Extended Definition
The VTORQUE command lists or redefines a force element that consists of three mutually orthogonal
translational torque components. You can alter one or both points of torque application, change the torque
reference marker, and change the torque function expressions or the parameters passed to the VTOSUB user-
written subroutine.
After a change to a VTORQUE, Adams Solver (FORTRAN) reprocesses the model at the next SIMULATE
conditions.
While checking, Adams Solver (FORTRAN) verifies that the model is still valid with the new VTORQUE.
If, for example, the VTORQUE function expression refers to an inactive element, Adams Solver
(FORTRAN) issues an error.
If you change a VTORQUE I marker, J marker, or type in the middle of a simulation, by default Adams
Solver (FORTRAN) splits the tabular, request, graphics, and results output into two separate sets of output
that are concatenated. This ensures that the output correctly reflects the new system topology. Adams Solver
(FORTRAN) does not split the files if you change only the VTORQUE function expression.
158 Adams Solver
misleading graphics during postprocessing.
Tip: Depending on the nature of the desired torque relationship, the RM marker may belong to the
Caution: The user-defined functions TX, TY, and TZ should be smooth, continuous, and single-valued.

Welcome to Adams Solver Subroutines 1
Conventions, Requirements and Types
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 Welcome to the FORTRAN Version of Adams Solver. For information on the C++ version,
see Welcome to the C++ Version of Adams Solver.
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:
i Integer
r Real
c Character string (alphanumeric)
e Function expression
v Varying type (integer, real or alphanumeric)
id Identifier
x,y,z Cartesian coordinate (real)
a,b,c 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.
2 Adams Solver
This type of style: Indicates:

[[ ]] That you can select any combination of the items.
A A two-dimensional matrix.
a A one-dimensional matrix.
R A vector.
x̂ Unit vectors.
Important: Subroutine names are often modified by the compiling/linking process. Adams Solver looks
at the final function names and tries to determine, if the subroutine was written in C or
FORTRAN. How function names are modified is dependent on the compilers and the
Operating System that are in use.
A general rule that works across all platforms is this:
 FORTRAN: subroutine names should be upper case. For example, SFOSUB,

GFOSUB and so on.
 C: subroutine names should be mixed case. For example, Sfosub, Gfosub and so on.
System Requirements
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:
Utility Subroutines
 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

MSC no longer supports callable subroutines. If you have questions on callable subroutines, please refer to:
 Knowledge Base (http://simcompanion.mscsoftware.com/)
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
4 Adams Solver
Utility Subroutines
 Serialization 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.
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.
Data Access Subroutines

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:

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.
c_sysfn2 Used to register a scalar measure
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.
Utility Subroutines

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.
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.
6 Adams Solver
Utility Subroutines

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.
Serialization Subroutines
The serialization subroutines are used as an alternative to the SAVSUB and RELSUB user subroutines to save
and restore static data, stored in user subroutines, when issuing SAVE/RELOAD commands. During
executing Save and Reload command Adams Solver calls all user subroutines with IFAG=7, and IFLAG=9
respectively. Through branching on the IFLAG values your user subroutines can save and restore data.

SERIALIZE_CHARACTERS Uses to serialize character data.
SERIALIZE_DOUBLES Uses to serialize double-precision data.
SERIALIZE_INTEGERS Uses to serialize integer data.
UNSERIALIZE_CHARACTERS Uses to un-serialize character data.
UNSERIALIZE_DOUBLES Uses to un-serialize double-precision data.
UNSERIALIZE_INTEGERS Uses to un-serialize integer data.
Unsupported 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:
Unsupported Subroutines and Their Alternates
Instead of: Use:

DEQINF SYSFNC
FNCDEP SYSARY; SYSFNC
INFO SYSARY; SYSFNC
SPLINE AKISPL; CUBSPL
ANLMOD GETMOD
ADAMS_DECLARE_THREADSAFE 7
Utility Subroutines
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
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 user-written subroutine and
its dependants are threadsafe. If so, the user-written subroutine can indicate this with a call to
ADAMS_DECLARE_THREADSAFE. If the user-written subroutine making the call is written in
FORTRAN and the input parameter IFLAG is declared LOGICAL, then the call to
ADAMS_DECLARE_THREADSAFE must be done when IFLAG is TRUE. If the input parameter is
declared INTEGER, then the call to ADAMS_DECLARE_THREADSAFE should be made both when
IFLAG=1 (initialization) and IFLAG=3 (mapping). If the user-written subroutine making the call is written
in C/C++, the input parameter IFLAG is declared as int (integer) and the call to
8 Adams Solver
Utility Subroutines
ADAMS_DECLARE_THREADSAFE should be done both when IFLAG==1 (initialization) and

IFLAG==3 (mapping). If a user-written subroutine makes a call to ADAMS_DECLARE_THREADSAFE,
then Adams Solver (C++) 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 user-written 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).
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.
ADAMS_DECLARE_THREADSAFE 9
Utility Subroutines
Notes: There is no way to specify, ensure, or verify that any modeling element be evaluated by any
particular thread.
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.
Argument IFLAG should be declared of type INTEGER when using FORTRAN.
The calls to ADAMS_DECLARE_THREADSAFE takes effect only if the value of

NTHREADS is bigger than one. See the PREFERENCES statement.
10 Adams Solver
Utility Subroutines
ADAMS_NEEDS_PARTIALS
ADAMS_NEEDS_PARTIALS returns a logical value that when true indicates Adams Solver is calculating
partial derivatives for the calling user subroutine. It is used in conjunction with SYSPAR to identify when to
call SYSPAR.
Use
Called by
CONSUB, DIFSUB, GFOSUB, GSE_DERIV, GSE_OUTPUT, REQSUB, SENSUB, SFOSUB,
VARSUB, VFOSUB, MFOSUB, and VTOSUB
Prerequisite
None
Calling Sequence
CALL ADAMS_NEEDS_PARTIALS (value)
Output Argument
Value a logical variable that when returned true indicates SYSPAR should be called.
ADAMS_SMP_GROUP 11
Utility Subroutines
ADAMS_SMP_GROUP
A call to the ADAMS_SMP_GROUP subroutine informs Adams Solver (C++) that, if the user-written
subroutine is executed in parallel, it must be executed in the same thread as other subroutines with the same
ADAMS_SMP_GROUP id. Note that this applies to each use of the user-written subroutine.
Use
Called By
Any user-written subroutine. However, this utility subroutine only has an effect when both a) the model is
being run in parallel (with preferences/nthreads=n, where n>1) and b) the user-written subroutine has also
made a call to ADAMS_DECLARE_THREADSAFE such that it can be executed in parallel.
Prerequisite
None
Calling Sequence
CALL ADAMS_SMP_GROUP ( groupId )
Input Arguments
groupId An integer variable giving the smp group id. All user-written subroutines with the same
group id will be executed in the same thread.
Valid group ids are any nonzero positive integer.
A group id of zero explicitly states that this user-written subroutine is not part of an smp
group and, if executed in parallel, can be executed by any available thread. This is the
default case.
Output Arguments
None
Extended Definition
If the user-written subroutine making the call is written in FORTRAN and the input parameter IFLAG is
declared LOGICAL, then the call to ADAMS_SMP_GROUP must be done when IFLAG is TRUE. If the
input parameter is declared INTEGER, then the call to ADAMS_SMP_GROUP should be made both when
IFLAG=1 (initialization) and IFLAG=3 (mapping). If the user-written subroutine making the call is written
in C/C++, the input parameter IFLAG is declared as int (integer) and the call to ADAMS_SMP_GROUP
should be done both when IFLAG==1 (initialization) and IFLAG==3 (mapping). A call to
ADAMS_SMP_GROUP is not enough to guarantee the subroutine will be executed in parallel; a call to
12 Adams Solver
Utility Subroutines
ADAMS_SMP_GROUP must be accompanied by a call to ADAMS_DECLARE_THREADSAFE. For

example, a threadsafe SFOSUB might include the following code snippet:
SUBROUTINE SFOSUB(ID,. . .
. . .
C Mapping dependencies
IF (IFLAG.EQ.3) THEN
CALL ADAMS_SMP_GROUP(37)
CALL ADAMS_DECLARE_THREADSAFE()
ENDIF
C
. . .
In this example the user makes the call to have all objects using this subroutine join a group labeled as 37.
A large amount of user-written subroutines exist for use with Adams solvers. Many of these user-written
subroutines are not threadsafe and thus cannot take advantage of the parallelism in Adams. However, it is
often the case that the non-threadsafe character of these user-written subroutines is only in relation to a few
specific other user-written subroutines, or a few specific user-written subroutines that are referenced by
specific Adams modeling elements. Consequently, by identifying a ‘group’ of user-written subroutines which
must be executed in the same thread, some threadsafety issues can be avoided such that these non-threadsafe
user-written subroutines can still take advantage of parallel execution.
For example, a complex user-defined bushing might make use of several user-written subroutines which are
not threadsafe. However, it is possible that if there are multiple bushings in the model and all user-written
subroutines that affect a particular bushing are run in the same thread, that the non-threadsafe issues can be
avoided. The ADAMS_SMP_GROUP utility subroutine would permit parallelism in this case if each use of
the user-written subroutines gave the bushing id as its group id.
Within each SMP group, the user-written subroutines are evaluated in the order that they would have been
evaluated if the model were run serially.
It is not recommended that this be used as a substitute to writing completely threadsafe user subroutines.
User-written subroutines which are completely threadsafe will be able to take more effective advantage of
parallelism in Adams.
Notes: Argument IFLAG should be declared of type INTEGER when using FORTRAN.
A call to ADAMS_SMP_GROUP must be complemented by a call to

ADAMS_DECLARE_THREADSAFE.
Calls to ADAMS_SMP_GROUP take effect only if the value of NTHREADS is bigger than
one. See the PREFERENCES statement.
ADD_MASS_PROPERTY 13
Utility Subroutines
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
Calling Sequence
CALL ADD_MASS_PROPERTY (cm1, mass1, ip1, cm2, mass2, ip2)
Input Arguments
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.
ip2 A double-precision array of length 6 giving the 6 independent terms in the inertia tensor 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.
14 Adams Solver
Utility Subroutines
Output Arguments
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.
Extended Definition
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
IMPLICIT NONE
C
C Inputs:
C
INTEGER ID, NPAR, IBODY
INTEGER 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
ADD_MASS_PROPERTY 15
Utility Subroutines
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)
RESULT(2) = IP(2)
RESULT(3) = IP(3)
RESULT(4) = IP(4)
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)
RETURN
END
16 Adams Solver
Utility Subroutines
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
Calling Sequence
CALL AKISPL (xval, zval, id, iord, array, errflg)
Input Arguments
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.
AKISPL 17
Utility Subroutines
Output Arguments
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
----- and ∂----y- , respectively. If iord equals two, array returns:
∂x ∂z
2 2 2
∂ y- ----------
------- ∂ y- ∂y
, , and -------- , respectively.
∂ x ∂x ∂z
2 2
∂ z
2 2
∂ y-
---------- ∂y
Note that: = -----------
∂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.
Extended Definition
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.
 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) 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.
18 Adams Solver
Utility Subroutines
ANALYS
The ANALYS subroutine performs the analysis requested of it.
Use
Called By
CONSUB
Prerequisite
None
Calling Sequence
CALL ANALYS (antype, cid, timbeg, timend, init, istat)
Input Arguments
antype One of the character strings, DYNAMICS, KINEMATI, STATICS, QSTATICS,

INITIALC or TRANSIEN, 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.
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.
ANALYS 19
Utility Subroutines
Output Argument
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 not a valid character string
istat = -9 timbeg is not equal to the current simulation time.
istat =-10 timend is less than timbeg.
Extended Definition
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.

 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.
20 Adams Solver
Utility Subroutines
BISTOP
BISTOP evaluates a BISTOP function (C++ or FORTRAN).
Use
Called By
Prerequisite
None
Calling Sequence
CALL BISTOP (x, x', x1, x2, k, e, cmax, d, iord, vector, errflg)
Input Arguments
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 force-deformation 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.
BISTOP 21
Utility Subroutines
Output Arguments
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.
Vector returns: For iord value:
0 1 2
(1)
F ( x, x' )
∂ F ( x, x' ) 2
∂ F ( x, x' )
∂x 2
∂x
(2) 0
∂ F ( x, x' ) 2
∂ F ( x, x' )
∂ x' ∂ x' ∂x
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.
Extended Definition
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,
22 Adams Solver
Utility Subroutines
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:
e
 Min ( k ⋅ ( x 1 – x ) – STEP ( x, x 1 – d, c max, x 1 0 ) ⋅ x′, 0 ) x < x1

BISTOP =  0 x1 ≤ x ≤ x2
 e
 Max ( – k ⋅ ( x – x 2 ) – STEP ( x, x 2, 0, x 2 + d, c max ) ⋅ x′, 0 ) x > x 2
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 23
Utility Subroutines
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.
Use
Called By
Any of a REQSUB, SENSUB, SEVSUB or CONSUB.
Prerequisite
None
Calling Sequence
CALL BODY_MASS_PROPERTY (type, id, cm, mass, ip)
Input Arguments
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.
Output Arguments
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.
24 Adams Solver
Utility Subroutines
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 25
Utility Subroutines
CHEBY
The CHEBY subroutine evaluates a Chebyshev polynomial.
Use
Called By
Prerequisites
None
Calling Sequence
CALL CHEBY (x, x0, par, npar, iord, value, errflg)
Input Arguments
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.
26 Adams Solver
Utility Subroutines
Output Arguments
value A double-precision value the subroutine returns. The table below summarizes the value it
returns:
IORD: Value:
0 F(x)
1 ∂F (x)
--------------
∂x
2 2
∂----------------
F ( x -)
2
∂x
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
Extended Definition
CHEBY evaluates a Chebyshev polynomial. The following equation defines CHEBY:
n
 aj Tj ( x – x0 )
j=0
where:
Tj ( x – x0 ) = 2 ⋅ ( x – x0 ) ⋅ Tj – 1 ( x – x0 ) ⋅ Tj – 2 ( x – x0 )
T0 ( x – x0 ) = 1
and:
T1 ( x – x0 ) = x – x0
c_sysfn2 27
Utility Subroutines
c_sysfn2
The c_sysfn2() utility subroutine is exclusively used inside a FEloadsub user-written subroutine. The sole
purpose of the c_sysfn2 utility subroutine is to register a scalar measure, for example, a position or a velocity
component, needed for the desired computation. The c_sysfn2() subroutine has a C/C++ only
implementation; there is no FORTRAN equivalent. The c_sysfn2() utility subroutine is supported only by
Adams Solver C++.
The c_sysfn2() utility subroutine and associated FEloadsub user-written subroutine both implement a new
paradigm. Users need to register the measures to be used by the subroutine only once when Adams Solver
C++ calls the FEloadsub with the value of IFLAG equal to 1. When IFLAG is equal to 0 (normal evaluation
call), all registered measures are evaluated by Adams Solver C++ and passed to the subroutine inside a data
structure; see more details in FEloadsub.
There is strong similarity between c_sysfn2() and c_sysfnc() (and the FORTRAN version SYSFNC). The
main difference is that c_sysfn2() does not evaluate the requested measure but just registers the measure.
Adams Solver C++ will keep an associated data structure with all registered measures and compute the values
of all the registered measures before calling the FEloadsub. The main similarity is in the use of parameters
"fncnam", "ipar" and "nsize" as explained below.
Use
Called By
FEloadsub exclusively.
Function Prototype
void c_sysfn2(const void *beam, const char *fncnam, const int *ipar,
int nsize, int *index, int *errflg);
Calling Sequence
c_sysfn2( beam, fncnam, ipar, nsize, &index, &errflag );
28 Adams Solver
Utility Subroutines
Input Arguments
beam Pointer to a data structure passed to the FEloadsub. See examples in FEloadsub documentation.
This pointer is passed to the user when Adams Solver C++ calls a FEloadsub.
c_sysfn2 29
Utility Subroutines
fncnam A character variable specifying the name of the function (measure) whose data is being
requested to be passed to the subroutine on subsequent calls. For example:
c_sysfn2( beam, "DX", ipar, nsize, &index, &errflg );
Per C/C++ standards, the name of the measure (function) requires double quotes. All of the
measure names permitted by a SYSFNC call are also permitted by the c_sysfn2(). The
following measure names are allowed:
ipar An integer array containing the parameter list for fncnam. It consists of any valid list of
parameters used in the associated Adams Solver measure (function), just as they would appear
in a dataset FUNCTION=expression.
nsize An integer variable specifying the number of values in array ipar.
30 Adams Solver
Utility Subroutines
Output Arguments
index An integer pointer containing the index number of the registered measure (function). The
index is zero-based. The returned index may be ignored. See example below on how the index
may help writing more robust and easier-to-read code.
errflg An integer pointer containing either a 0 or 1. A value 0 signals no problems. A value o 1 signals
a wrong specification of the registering measure.
Extended Definition
The c_sysfnc2() subroutine registers a system-state value (such as displacement, velocities, non-dimensional
arc length along a beam and so on.) to be used inside a FEloadsub user-written subroutine. Adams Solver
C++ creates a list of all registered measures (the registration process takes place when IFLAG=1) and assigns
an index to all registered measures. The index is 0-based and is based on the order in which the calls to
c_sysfn2() are made. During normal evaluation (IFLAG=0), Adams Solver C++ computes the values of all
registered measures and passes the computed values to the FEloadsub subroutine. See FEloadsub subroutine
for more details and examples.
Although c_sysfn2() is similar to c_sysfnc() (or FORTRAN equivalent SYSFNC), the main difference is that
users must call it only when IFLAG=1. This new architecture increases performance by eliminating
continuous checks done on every call to SYSFNC; for example, during normal evaluation calls to user-written
subroutines, every call to the utility subroutine SYSFNC requires a construction of the requested measure
and a mandatory check to make sure the measure was registered. When using the c_sysfn2() utility, no
constructions, no checks are needed during normal calls to the FEloadsub.
Cautions
Calls to c_sysfn2() must be made only during the initialization stage (IFLAG=1).
Example 1
In this example we present a code snippet where two measures (DX(2,8) and SD(3)) are registered.
#include "slv_c_utils.h"
extern "C"
void FEloadsub( struct sAdamsANCF3DBeamDistrForce* sBeam, double TIME, int
DFLAG, int IFLAG, double *RESULT )
{
if( IFLAG==1 )
{
// Initialization. Registration of measures used by this subroutine
int index, errflg, npar, par[3];
npar = 2;
par[0] = 2;
par[1] = 8;
c_sysfn2( sBeam, "DX", par, npar, &index, &errflg ); // DX(2,8)
npar = 1;
par[0] = 3;
c_sysfn2( sBeam, "SD", par, npar, &index, &errflg ); // SD(3)
}
c_sysfn2 31
Utility Subroutines
// Rest of code not shown.

}
Example 2
In this complete example, four calls are made to c_sysfn2() in order to register the measures SD(2), SD(4),
SD(5) and SD(6). The index is not used by the author of the subroutine.
#include <math.h>
extern "C"
{
const double PI = 3.14159265358979323846;
if( IFLAG==1 )
{
npar = 1;
par[0] = 2;
c_sysfn2( sBeam, "SD", par, npar, &index, &errflg ); // SD(2) - y
position
par[0] = 4;
c_sysfn2( sBeam, "SD", par, npar, &index, &errflg ); // SD(4) - Psi
par[0] = 5;
c_sysfn2( sBeam, "SD", par, npar, &index, &errflg ); // SD(5) - Theta
par[0] = 6;
c_sysfn2( sBeam, "SD", par, npar, &index, &errflg ); // SD(6) - Phi
}
else if( IFLAG==3 )
{
// Mapping dependencies
sBeam->depend_Fx[0] = 1.0;
sBeam->depend_Fy[0] = 1.0;
}
else if( IFLAG==0 )
{
// Normal function evaluation. Get values of parameters and measures
double C = sBeam->PAR[0];
double y = sBeam->mea_values[0];
double Psi = sBeam->mea_values[1];
double Theta = sBeam->mea_values[2];
double Phi = sBeam->mea_values[3];
// Compute the pressure

RESULT[0] = -C*pow(y,4)*(-cos(Psi)*sin(Phi) -
sin(Psi)*cos(Theta)*cos(Phi));
RESULT[1] = -C*pow(y,4)*(-sin(Psi)*sin(Phi) +
cos(Psi)*cos(Theta)*cos(Phi));
32 Adams Solver
Utility Subroutines
// Partial derivatives
if( DFLAG==1 )
{
sBeam->depend_Fx[0] = -C*4.*pow(y,3)*(-cos(Psi)*sin(Phi) -
sBeam->depend_Fx[1] = -C*pow(y,4)*(sin(Psi)*sin(Phi) -
sBeam->depend_Fx[2] = -C*pow(y,4)*(sin(Psi)*sin(Theta)*cos(Phi));
sBeam->depend_Fx[3] = -C*pow(y,4)*(-cos(Psi)*cos(Phi) +
sin(Psi)*cos(Theta)*sin(Phi));
sBeam->depend_Fy[0] = -C*4.*pow(y,3)*(-sin(Psi)*sin(Phi) +
sBeam->depend_Fy[1] = -C*pow(y,4)*(-cos(Psi)*sin(Phi) -
sBeam->depend_Fy[2] = -C*pow(y,4)*(-cos(Psi)*sin(Theta)*cos(Phi));
sBeam->depend_Fy[3] = -C*pow(y,4)*(-sin(Psi)*cos(Phi) -
cos(Psi)*cos(Theta)*sin(Phi));
}
}
}
Example 3
This example is computational identical to the previous example; in this case the returned index from
c_sysfn2() is used to make the code easier to understand.
#include <math.h>
extern "C"
{
const double PI = 3.14159265358979323846;
// Make this variables 'static' so their values are kept between function
calls
static int y_idx, Psi_idx, Theta_idx, Phi_idx;
if( IFLAG==1 )
{
int errflg, npar, par[3];
npar = 1;
par[0] = 2;
c_sysfn2( sBeam, "SD", par, npar, &y_idx, &errflg ); // SD(2) - y
position
par[0] = 4;
c_sysfn2( sBeam, "SD", par, npar, &Psi_idx, &errflg ); // SD(4) - Psi
par[0] = 5;
c_sysfn2( sBeam, "SD", par, npar, &Theta_idx, &errflg ); // SD(5) -
Theta
par[0] = 6;
c_sysfn2( sBeam, "SD", par, npar, &Phi_idx, &errflg ); // SD(6) - Phi
}
else if( IFLAG==3 )
{
c_sysfn2 33
Utility Subroutines
sBeam->depend_Fx[y_idx] = 1.0;
sBeam->depend_Fx[Psi_idx] = 1.0;
sBeam->depend_Fx[Theta_idx] = 1.0;
sBeam->depend_Fx[Phi_idx] = 1.0;
sBeam->depend_Fy[y_idx] = 1.0;
sBeam->depend_Fy[Psi_idx] = 1.0;
sBeam->depend_Fy[Theta_idx] = 1.0;
sBeam->depend_Fy[Phi_idx] = 1.0;
}
else if( IFLAG==0 )
{
double y = sBeam->mea_values[y_idx];
double Psi = sBeam->mea_values[Psi_idx];
double Theta = sBeam->mea_values[Theta_idx];
double Phi = sBeam->mea_values[Phi_idx];

if( DFLAG==1 )
{
sBeam->depend_Fx[y_idx] = -C*4.*pow(y,3)*(-cos(Psi)*sin(Phi) -
sBeam->depend_Fx[Psi_idx] = -C*pow(y,4)*(sin(Psi)*sin(Phi) -
sBeam->depend_Fx[Theta_idx] = -
C*pow(y,4)*(sin(Psi)*sin(Theta)*cos(Phi));
sBeam->depend_Fx[Phi_idx] = -C*pow(y,4)*(-cos(Psi)*cos(Phi) +
sBeam->depend_Fy[y_idx] = -C*4.*pow(y,3)*(-sin(Psi)*sin(Phi) +
sBeam->depend_Fy[Psi_idx] = -C*pow(y,4)*(-cos(Psi)*sin(Phi) -
sBeam->depend_Fy[Theta_idx] = -C*pow(y,4)*(-
cos(Psi)*sin(Theta)*cos(Phi));
sBeam->depend_Fy[Phi_idx] = -C*pow(y,4)*(-sin(Psi)*cos(Phi) -
}
}
}
34 Adams Solver
Utility Subroutines
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
Calling Sequence
CALL CUBSPL (xval, zval, id, iord, array, errflg)
Input Arguments
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 SPLINE statement.
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.
CUBSPL 35
Utility Subroutines
Output Arguments
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
∂y
1 The first partial derivatives of y Array(1) =
∂y
with respect to x and z Array(2) = ∂ x
Array(3) = 0∂ z2
∂ 2y
2 The second partial derivatives Array(1) =
∂ 2y2
of y with respect to x and z Array(2) = ∂∂ xy
Array(3) = ∂ x ∂z
2
Note that: ∂z
2 2
∂y ∂y
=
∂ z ∂x ∂ x ∂z
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.
Extended Definition
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).
 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
36 Adams Solver
Utility Subroutines
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 37
Utility Subroutines
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
Calling Sequence
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.
Extended Definition
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.
38 Adams Solver
Utility Subroutines
ERRMES
ERRMES provides the facility for outputting error messages from user-written subroutines.
Use
Called By
Prerequisite
None
Calling Sequence
CALL ERRMES (errflg, mesage, id, endflg)
Input Arguments
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 1024 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.
Extended Definition
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.
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 39
Utility Subroutines
FORCOS
FORCOS evaluates a Fourier cosine series.
Use
Called By
Prerequisite
None
Calling Sequence
CALL FORCOS (x, x0, w, par, npar, iord, value, errflg)
Input Arguments

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 to return. IORD can
be zero, one, or two.
40 Adams Solver
Utility Subroutines
Output Arguments
errflg A logical (true or false) variable that FORCOS returns to the calling subroutine. If FORCOS
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.
F(x)
1 Partial derivative of the FORCOS ∂F
function with respect to the ------
independent variable, x. ∂x
2 Second partial derivative of the 2

FORCOS function with respect to ∂--------
F-
2
the independent variable, x. ∂ x
Extended Definition
FORCOS evaluates a Fourier cosine series. The following equation defines FORCOS:
n
 aj Tj ( x – x0 )
j=0
where:
T j ( x – x 0 ) = cos ( j ⋅ w ⋅ ( x – x 0 ) )
For an example of a MOTSUB evaluation subroutine that calls FORCOS, see MOTSUB.
FORSIN 41
Utility Subroutines
FORSIN
FORSIN evaluates a Fourier sine series.
Use
Called By
Prerequisite
None
Calling Sequence
CALL FORSIN (x, x0, w, par, npar, iord, value, errflg)
Input Arguments
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 to return. IORD can
be zero, one, or two.
42 Adams Solver
Utility Subroutines
Output Arguments
errflg A logical (true or false) variable that FORSIN returns to the calling subroutine. If FORSIN
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.
F(x)
1 Partial derivative of the FORSIN ∂F
function with respect to the ------
independent variable, x. ∂x
2 Second partial derivative of the 2

∂ F
FORSIN function with respect to the ---------
2
independent variable, x. ∂ x
Extended Definition
FORSIN evaluates a Fourier sine series. The following equation defines FORSIN:
 aj Tj ( x – x0 )
j=0
where:
T j ( x – x 0 ) = sin ( j ⋅ w ⋅ ( x – x 0 ) )
GET_FULL_MATRIX_DATA 43
Utility Subroutines
GET_FULL_MATRIX_DATA
Returns the values entered in a dataset MATRIX statement (C++ or FORTRAN) of type full, given the
statement identifier.
Use
Called By
Prerequisite
MATRIX statement in the dataset
Calling Sequence
GET_FULL_MATRIX_DATA(id, vals, size, ierr)
Input Arguments
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.
Output Arguments
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:
 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
Extended Definition
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.
Tip: Call GET_MATRIX_INFO to get the size and type of the MATRIX.
44 Adams Solver
Utility Subroutines
GET_GRAVITY
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
Calling Sequence
CALL GET_GRAVITY (GX, GY, GX)
Input Arguments
None
Output Arguments
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 acceleration
with respect to the ground coordinate system (GCS) in model units.
GZ A double-precision variable containing the zcomponent of gravitational acceleration
with respect to the ground coordinate system (GCS) in model units.
GET_MATRIX_INFO 45
Utility Subroutines
GET_MATRIX_INFO
Returns information about a dataset MATRIX statement given the statement identifier (C++ or
FORTRAN).
Use
Called By
Prerequisite
Calling Sequence
GET_MATRIX_INFO(id, type, nrows, ncols, size, ierr)
Input Arguments
Output Arguments
type An integer value that indicates the MATRIX type as stored by Adams Solver.
 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
Extended Definition
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
46 Adams Solver
Utility Subroutines
 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_NTHREAD 47
Utility Subroutines
GET_NTHREAD
A call to the GET_NTHREAD utility subroutine returns either the value of NTHREADS in the
PREFERENCES statement, or the value one (1).
If the returned value is one (1), it means the user did not set the NTHREAD option in the PREFERENCES
statement (the code will therefore run serially.)
If the environment variable MDI_ADAMS_FORCE_NTHREAD is set, then GET_NTHREAD will
return the value of the environment variable. (The environment variable
MDI_ADAMS_FORCE_NTHREAD overrides the option in the PREFERENCES statement.)
The GET_NTHREAD utility subroutine may be used from within any user-written subroutine. However,
if the call is made from within a CBKSUB, the returned value will be equal to one (1) during the event
ev_MODEL_INPUT_BEG. The reason is that the event ev_MODEL_INPUT_BEG signals the start of
parsing the model data from the database, hence no information about threading is available at that time.
The correct value of NTHREADS (or the value of the environment variable above) will be returned at any
other event.
Use
Called By
Any user-written subroutine. Calls from within a CBKSUB shall not be made at event
ev_MODEL_INPUT_BEG.
Calling Sequence in FORTRAN

INTEGER N
CALL GET_NTHREAD(N)
Function Prototype (C/C++)

void c_get_nthread( int *n);
Input Arguments
None
Output Arguments
N (or n) An INTEGER (or a pointer to int) that returns the value of the NTHREAD option in the
PREFERENCES statement.
If the environment variable MDI_ADAMS_FORCE_NTHREAD is set, the utility will return

the value of the environment variable.
48 Adams Solver
Utility Subroutines
Extended Definition
Calls to GET_NTHREAD may allow the user to write a more efficient parallel code or may allow
parallelizing existing serial code. The typical scenario is the case of initializations for user-written subroutines
running in parallel. Those initializations can be safely done within a CBKSUB during the event
ev_MODEL_INPUT_END.
Note: Avoid making a call to GET_NTHREAD from a CBKSUB during the event
ev_MODEL_INPUT_BEG.
Example 1 (FORTRAN)
SUBROUTINE CBKSUB(TIME, EVENT, MODE)

C
include 'slv_cbksub.inc'
C Callback subroutine
INTEGER EVENT, MODE(3)
DOUBLE PRECISION TIME
C
C Work variables
INTEGER NTHREADS
CHARACTER*200 MESSAGE
C
C Case of event ev_MODEL_INPUT_END
IF( EVENT.EQ.ev_MODEL_INPUT_END ) THEN
CALL GET_NTHREAD(NTHREADS)
WRITE(MESSAGE, '(A,I5)') 'NTHREADS is ', NTHREADS
CALL USRMES(.TRUE.,MESSAGE, 0, 'INFO')
C Initializations
….
ENDIF
C
…
Example 2 (C/C++)
void Cbksub(const struct sAdamsCbksub *sos, double Time, int Event,
int *Info)
{
char buffer[1024];
int nthreads;
if (Event == ev_MODEL_INPUT_END)
{
/* Get the number of threads */
c_get_nthread(&nthreads);
GET_NTHREAD 49
Utility Subroutines
sprintf(buffer, "\n\nThe number of threads read is %d\n",

nthreads);
c_usrmes(1, buffer, 0, "INFO");
/* Initialize data for each thread */

....
}
....
50 Adams Solver
Utility Subroutines
GET_SOLVER
A call to the GET_SOLVER utility subroutine returns either one (1) or zero (0). The returned value is one
(1) if the call is made by the Adams Solver (C++) executable. The returned value is zero (0) if the call is made
by the Adams Solver (FORTRAN) executable.
Use
Called By

INTEGER N
CALL GET_SOLVER(N)

void c_get_solver( int *n);
Input Arguments
None
Output Arguments
N (or n) An INTEGER (or a pointer to int) equal to either one (1) or zero (0). The returned value is
one (1) if the call is made by the Adams Solver (C++) executable. The function returns zero (0)
if the call is made by the Adams Solver (FORTRAN.)
Example 1 (FORTRAN)
SUBROUTINE CBKSUB(TIME, EVENT, MODE)

C
C Callback subroutine
INTEGER EVENT, MODE(3)
C
C Work variables
INTEGER SOLVER
C
C Case of event ev_MODEL_INPUT_BEG
IF( EVENT.EQ.ev_MODEL_INPUT_BEG ) THEN
CALL GET_SOLVER(SOLVER)
WRITE(MESSAGE, '(A,I5)') SOLVER is ', SOLVER
GET_SOLVER 51
Utility Subroutines
….
ENDIF
C
…
Example 2 (C/C++)
void Cbksub(const struct sAdamsCbksub *sos, double Time, int Event,
int *Info)
{
char buffer[1024];
int solver;
if (Event == ev_MODEL_INPUT_BEG)
{
/* Get the running solver */
c_get_solver(&solver);
sprintf(buffer, "The solver is %s", (solver==1 ? "C++" :
"FORTRAN"));
c_usrmes(1, buffer, 0, "INFO");
....
}
....
52 Adams Solver
Utility Subroutines
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
Calling Sequence
GET_SPARSE_MATRIX_DATA(id, rows, cols, vals, size, ierr)
Input Arguments

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.
Output Arguments
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:
 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
Extended Definition
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.
GET_SPARSE_MATRIX_DATA 53
Utility Subroutines
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.
Tip: Call GET_MATRIX_INFO to get the size and type of the MATRIX.
54 Adams Solver
Utility Subroutines
GET_THREAD_INDEX
A call to the GET_THREAD_INDEX utility subroutine returns the index of the parallel thread currently
making the call, or zero when the main thread executes the call.
The returned value may be zero (0) or a value in the range 1 to NTHREADS, where NTHREADS is the
value set in the PREFERENCES statement. When the returned value is zero (0) it means the main thread
(the main process) executes the call. If the value of NTHREADS is bigger than 1, and the code making the
call to this utility is being executed in parallel, the returned value is in the range 1 to NTHREADS.
Notice that even in case when the value of NTHREADS is bigger than 1, the call to this utility subroutine
may return zero (0). For example, placing the call to GET_NTHREAD_INDEX inside a VARSUB, the call
may return zero (0) during the mapping of dependencies because the main execution thread does the
mapping of dependencies serially.
Also, notice that a value of NTHREADS=1 means no parallel threads are used in the Adams Solver (C++)
simulation. Parallel threads are used only if the value of NTHREADS is bigger than 1. When NTHREADS
is set to 1, GET_THREAD_INDEX will always return zero (0).
Use
Called By

INTEGER N
CALL GET_THREAD_INDEX(N)

void c_get_thread_index( int *n);
Input Arguments
None
Output Arguments
N (or n) An INTEGER (or a pointer to int) that returns the index of the thread making the call. If
the returned value is zero (0), it means the call is made by the main thread (main process).
Otherwise the index is in the range 1 to NTHREADS (NTHREADS is the value set in the
PREFERENCES statement.)
Extended Definition
Calls to GET_THREAD_INDEX may allow the user to write a more efficient parallel code or may allow
parallelizing existing serial code. The returned value is zero (0) whenever the main execution thread (main
process) makes the call; this can happen for operations done by the main thread, for example, mapping
GET_THREAD_INDEX 55
Utility Subroutines
dependencies. If a parallel thread makes the call to GET_THREAD_INDEX, the returned value is in the
range 1 to NTHREADS, where NTHREADS is the value set in the PREFERENCES statement.
Note: Make sure your subroutine makes the call to the utility subroutine
ADAMS_DECLARE_THREADSAFE or c_adams_declare_threadsafe() to have it
running in parallel.
Example 1 (FORTRAN)
SUBROUTINE VARSUB(ID, TIME, PAR, NPAR, DFLAG, INITFL, VALUE)

C
INTEGER ID, I, TINDEX
INTEGER NPAR, NSIZE, IPAR(4), NSTATES
DOUBLE PRECISION PAR(*)
DOUBLE PRECISION VALUE
LOGICAL INITFL
LOGICAL DFLAG
DOUBLE PRECISION STATE, STATES(6)
LOGICAL ERROR
CHARACTER*10 MID, MINDEX
C Make sure this subroutine runs in parallel

CALL ADAMS_DECLARE_THREADSAFE()
C Print the ID of the VARIABLE into a string

WRITE(MID, 20) ID
20 FORMAT(I4)
C Get the thread index and print it into a string

CALL GET_THREAD_INDEX(TINDEX)
WRITE(MINDEX, 20) TINDEX
C Print the strings above

CALL USRMES(.TRUE., 'VARSUB '//MID//' THREAD '//MINDEX, 0,
& 'INFO')
…
Example 2 (C/C++)
void Varsub(const struct sAdamsVariable* variable, double TIME, int
DFLAG, int IFLAG, double* VALUE)
{
double state, states[6];
int i, tindex, nthread, solver;
char buffer[512];
int nsize, ipar[4];
int id, error;
/* ID of the VARIABLE*/
id = variable->ID;
56 Adams Solver
Utility Subroutines
/* Make sure this subroutine runs in parallel */

c_adams_declare_threadsafe();
/* Get the thread index */

c_get_thread_index(&tindex);
/* Print the ID and the thread index */

sprintf(buffer, "VARSUB %5d THREAD %5d", id, tindex);
c_usrmes(1, buffer, id, "INFO");
…
GETCPU 57
Utility Subroutines
GETCPU
GETCPU retrieves CPU time used so far.
Use
Called by
Prerequisite
None
Calling Sequence
CALL GETCPU (value)
Output Argument
value Double-precision variable that contains the current CPU time.

58 Adams Solver
Utility Subroutines
GETINM
The GETINM reports whether the current Adams Solver command input mode is interactive or command
file-driven.
Use
Called by
Prerequisite
None
Calling Sequence
CALL GETINM (value)
Output Argument
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 59
Utility Subroutines
GETINT
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, FSI_GSTIFF, FSI_GSTIFF_SI2,
FSI_HHT, GSTIFF, GSTIFF_SI2, GSTIFF_SI1, HHT, WSTIFF, WSTIFF_SI2 and WSTIFF_SI1.
Use
Called by
Prerequisite
None
Calling Sequence
CALL GETINT (value)
Output Argument
value A character variable of fourteen characters containing the integrator type.
Extended Definition
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
 FSI_GSTIFF - The fixed step integrator using GSTIFF index three equation formulation
 FSI_GSTIFF_SI2 - The fixed step integrator using GSTIFF index two equation formulation
 FSI_HHT - The fixed step integrator using HHT index three equation formulation
 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
 HHT - The Hilber-Hughes-Taylor integrator using index three 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
60 Adams Solver
Utility Subroutines
 UNDEF - The integrator is undefined
Caution: Value is meaningful only during a simulation, that is, after you have issued a SIMULATE
command.
GETMOD 61
Utility Subroutines
GETMOD
GETMOD returns the current analysis mode.
Use
Called By
Calling Sequence
CALL GETMOD (mode)
Output Argument
mode An integer variable that specifies the current analysis mode.
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
mode=8 Steady State
mode=9 Compliance
Caution: GETMOD should be called from a user-written subroutine only when iflag is zero. (That is,
GETMOD should not be called during the subroutine initialization.) Calls to GETMOD
when iflag is not zero can result in erroneous mode information.
62 Adams Solver
Utility Subroutines
GETSLV
GETSLV returns the name of the active solver, either HARWELL or CALAHAN.
Use
Called by
Prerequisite
None
Calling Sequence
CALL GETSLV (value)
Output Argument
value A character*7 variable containing the name of the solver; HARWELL for the
Harwell solver or CALAHAN for the Calahan solver.
command.
GETSTM 63
Utility Subroutines
GETSTM
GETSTM returns the current simulation time.
Use
Called by
Prerequisite
None
Calling Sequence
CALL GETSTM (VALUE)
Output Argument
value A double-precision variable containing the current simulation time.
command.
64 Adams Solver
Utility Subroutines
GETVER
GETVER returns the current Adams Solver version number as it appears in the Adams Solver banner.
Use
Called by
Prerequisite
None
Calling Sequence
CALL GETVER (value)
Output Argument
value A character*10 variable that contains the Adams Solver version number.
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.
GSE 65
Utility Subroutines
GSE
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_XD, GSE_U)
 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.
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
Calling Sequence
CALL GSE_NS(NS)
CALL GSE_ND(ND)
CALL GSE_NI(NI)
CALL GSE_NO(NO)
66 Adams Solver
Utility Subroutines
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.
Calling Sequence
CALL GSE_X(X,NS)
CALL GSE_XDOT(XDOT,ND)
CALL GSE_XD(XD,ND)
CALL GSE_U(U,NI)
Input Arguments
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)
GSE 67
Utility Subroutines
Output Arguments
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, GSEPAR_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
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
Prerequisite
Calls may be dependent on calls made to GSEMAP utility subroutines when IFLAG was set.
Calling Sequence
CALL GSEPAR_X(D,N)
CALL GSEPAR_XDOT(D,N)
CALL GSEPAR_U(D,N)
68 Adams Solver
Utility Subroutines
Input Arguments
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.
Partial derivative mapping utility subroutines: GSEMAP_X, GSEMAP_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
Prerequisite
None
Calling Sequence
CALL GSEMAP_X(I,J)
CALL GSEMAP_XDOT(I,J)
CALL GSEMAP_U(I,J)
GSE 69
Utility Subroutines
Input Arguments
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)
70 Adams Solver
Utility Subroutines
GSE_OUTPUT_ICS
A call to GSE_OUTPUT_ICS utility subroutine triggers a call to the utility subroutine GSE_OUTPUT for
a given GSE. This utility is required in cases the user needs to refresh the values of the output states of a GSE
object.
Use
Called by
This utility may be called only from a CONSUB or a CBKSUB user-written subroutine.
Prerequisite
None

INTEGER ID
CALL GSE_OUTPUT_ICS(ID)
Calling Sequence (C/C++)

void c_gse_output_ics( int *id);
Input Arguments
ID (or id) is an integer variable that specifies the Adams ID of the GSE element.
Output Arguments
None
Extended Definition
In some particular instances, users need to refresh the values of the output states of a given GSE object before
the solution proceeds.
The call is ignored if the GSE does not have output states.
This utility subroutine is supported by the Adams Solver C++ only.
GTARAY 71
Utility Subroutines
GTARAY
GTARAY returns the double-precision numbers stored by an IC-type ARRAY statement (C++ or
FORTRAN).
Use
Called By
Prerequisite
ARRAY statement in dataset
Calling Sequence
CALL GTARAY (id, array, number, istat)
Input Argument
id An integer variable that specifies the ID of the ARRAY statement.
Output Arguments
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.
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.
number A variable that indicates the number of values returned in the array.
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.
72 Adams Solver
Utility Subroutines
GTCMAT
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
Calling Sequence
CALL GTCMAT (nmid, mid, ndim, c, istat)
Input Arguments
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).
GTCMAT 73
Utility Subroutines
Output Arguments
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.
Extended Definition
The compliance matrix for a system, C, is defined as the partial derivatives of displacements with respect to
applied forces:
∂x
C =
∂f
74 Adams Solver
Utility Subroutines
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: Δx = C Δf
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 x 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:
X· = AX + BU
y = CX
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, C, see the LINEAR command.
2. Solving for X we find that
X = A X· – A BU
–1 –1
Putting this result into the equation for y we obtain:

GTCMAT 75
Utility Subroutines
y = [ – CA B ]U + [ – CA X· ]
–1 –1
3. The compliance matrix C is given by the expression:
–1
C = [ – CA B ]
–1 ·
Notice that the term [ – CA X ] 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.
76 Adams Solver
Utility Subroutines
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
Calling Sequence
CALL GTCURV (id, alpha, iord, array, istat)
Input Arguments
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 B-spline 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 α .
 2 - Returns the second derivative with respect to α .
GTCURV 77
Utility Subroutines
Output Arguments
array A double-precision array of length three which contains the returned values of x, y, z.
iord array(1) array(2) array(3)
0
x( α) y(α) z( α )
1
dx ( α )- dy ( α -) dz ( α -)
-------------
-------------- --------------
dα dα dα
2
2 2 2
d x ( α -) d y ( α )- d z ( α )-
----------------
---------------- ---------------- 2
2 2
dα dα dα
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.
Extended Definition
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.
78 Adams Solver
Utility Subroutines
GTSTRG
GTSTRG returns the character string stored in a STRING statement.
Use
Called By
Prerequisite
STRING statement in dataset
Calling Sequence
CALL GTSTRG (id, string, nchars, istat)
Input Argument
id An integer variable that specifies the ID of the STRING statement.
Output Arguments
istat An integer that indicates the success or failure of the call to GTSTRG.
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.
nchars The number of characters in the returned string. Trailing blank spaces are ignored.
string The requested string.
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).
GTUNTS 79
Utility Subroutines
GTUNTS
GTUNTS returns model unit information from Adams Solver.
Use
Called By
Prerequisite
None
Calling Sequence
CALL GTUNTS (exist, scales, units)
Output Arguments
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)
80 Adams Solver
Utility Subroutines
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:
 exist = FALSE
 scales = 1.0, 1.0, 1.0, 1.0
 units = US
HAVSIN 81
Utility Subroutines
HAVSIN
The HAVSIN general subroutine evaluates a haversine function.
Use
Called By
Prerequisites
None
Calling Sequence
CALL HAVSIN (x, x0, h0, x1, h1, iord, value, errflg)
Input Arguments
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.
82 Adams Solver
Utility Subroutines
Output Arguments
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:
IORD: Value:
0 F(x)
1 ∂F (x)
--------------
∂x
2
2 ∂F ( x )-
----------------
2
∂x
Extended Definition
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:
HAVSIN 83
Utility Subroutines
( h0 + h1 )
a = ----------------------
2
( h1 – h0 )
b = ---------------------
2
( x – x0 )
c = ---------------------
( x1 – x0 )
 h0 ;x ≤ x 0 
 
 π 
HAVSIN =  a + b ⋅ sin  c ⋅ π – --- ;x 0 < x < x 2
 2
 
 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.
84 Adams Solver
Utility Subroutines
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
Called By
Prerequisite
None
Calling Sequence
CALL IMPACT (x, x', x1, k, e, cmax, d, iord, vector, errflg)
Input Arguments
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.
IMPACT 85
Utility Subroutines
Output Arguments
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.
vector
returns: For iord values:
0 1 2
(1) 2
∂F ( x, x′ )- ∂------------------------
F ( x, x′ )
F ( x, x′ ) ---------------------
∂x ∂x
2
(2) 0
2
∂F ( x, x′ )-
--------------------- ∂------------------------
F ( x, x′ )
∂x′ ∂x′∂x
(3) 0 0 0
Extended Definition
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.
 When x < x1, force is positive.
 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.
The following equation defines IMPACT:
86 Adams Solver
Utility Subroutines
e
 Max ( 0, k ( x 1 – x ) – STEP ( x, x 1 – d, cmax, x 1, 0 ) ⋅ x ) : x < x1 
IMPACT =  
 0 : x ≥ x1 
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.
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.
ISTRNG 87
Utility Subroutines
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
Calling Sequence
CALL ISTRNG (number, string, length, istat)
Input Argument
number An integer variable that specifies the integer to be converted.
Output Arguments
istat An integer variable indicating the success or the reason for the failure of the call
to ISTRNG.
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).
Extended Definition
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.
88 Adams Solver
Utility Subroutines
Tip: If the dimension of the string is CHARACTER*12 or longer, the string can hold any integer
defined on a 32-bit machine.
MODIFY 89
Utility Subroutines
MODIFY
The MODIFY allows execution of any Adams Solver command except CONTROL, STOP, from a
CONSUB.
Use
Called By
CONSUB
Prerequisite
None
Calling Sequence
CALL MODIFY (comand, istat)
Input Argument
comand A character string or variable that corresponds to the command to be executed.
Output Argument
istat An integer variable that indicates whether or not the call to MODIFY was successful.
If istat = 0, the call to MODIFY was successful.
Extended Definition
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.
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.
90 Adams Solver
Utility Subroutines
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
Calling Sequence
CALL MODINF (id, mode, freq, errflg)
Input Argument
id An integer variable that specifies the ID of the FLEX_BODY statement.
Output Argument
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.
 Flag errflg will be true when there is no FLEX_BODY with the given id or when there are
no active modes for the given FLEX_BODY.
 When errflg is true, the values of mode and freq may be wrong.
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.
MODINF 91
Utility Subroutines
 For Linux, in the directory /install_dir/solver/samples, where install_dir is the directory in which
you installed your Adams software.
• sysary_sample.acf
• sysary_sample.adm
• sysary_sample.f
• sysary_sample.mtx
92 Adams Solver
Utility Subroutines
N_CONTACT_INCIDENTS
A call to the N_CONTACT_INCIDENTS utility subroutine returns the integer number of incidents
currently active in the specified CONTACT (C++ Solver only).
Use
Called By

CALL N_CONTACT_INCIDENTS (id, n, errflg)

void c_get_n_contact_incidents(int id, int *n, int *errflg)
Input Argument
id An integer variable that provides the identifier of the CONTACT statement for which the
number is incidents is requested.
Output Argument
n An integer variable that provides the identifier of the CONTACT statement for which the
number is incidents is requested.
errflg An integer variable that indicates if Adams successfully finds the number of incidents. If
N_CONTACT_INCIDENTS detects an error, it sets errflg to a non-zero value before it
returns to the calling subroutine.
Extended Definition
The User-Written Subroutines CNFSUB and CFFSUB are called once for each incident in a CONTACT.
Users may wish to scale or modify the computed force based on the total number of incidents. This utility
function provides such capability. Users may also wish to access the number of incidents in other user
subroutines such as REQSUB.
Note: Calling this function from the F77 Solver will generate an Error message.
N_CONTACT_INCIDENTS 93
Utility Subroutines
Example 1 (FORTRAN)
SUBROUTINE CNFSUB(ID, TIME, PAR, NPAR, LOCI, NI, LOCJ, NJ,
& GAP, GAPDOT, GAPDOTDOT, AREA, DFLAG, IFLAG, FORCE)
C
C === Type and dimension statements ===================
C
INTEGER ID, NPAR
DOUBLE PRECISION PAR( * )
DOUBLE PRECISION LOCI(3)
DOUBLE PRECISION NI(3)
DOUBLE PRECISION LOCJ(3)
DOUBLE PRECISION NJ(3)
DOUBLE PRECISION GAP
DOUBLE PRECISION GAPDOT
DOUBLE PRECISION GAPDOTDOT
DOUBLE PRECISION AREA
LOGICAL DFLAG
LOGICAL IFLAG
DOUBLE PRECISION FORCE(3)
C
INTEGER ERRFLG
C
C ===Executable code ==================================
C
ERRFLG = 0
IF ( .NOT. IFLAG ) THEN

C Get number of incidents for this contact
C
CALL N_CONTACT_INCIDENTS(ID, INCIDENTS, ERRFLG)
ENDIF
…
RETURN
END
Example 2 (C/C++)
void Cnfsub(const struct sAdamsContactFriction* cnf, double TIME, const
double* LOCI,
const double* NI, const double* LOCJ, const double* NJ, double GAP,
double GAPDOT, double GAPDOTDOT, double AREA, DFLAG, int IFLAG,
double* FORCE)
{
int Id = cnf->contact.ID;
int incidents = 0;
int errflg = 0;
if (!IFLAG)
{
// get number of incidents for this contact
c_get_n_contact_incidents(Id, &incidents, &errflg);
}
…
}
94 Adams Solver
Utility Subroutines
NANINF
NANINF browses and input array (or a single value) and informs you whether there is a NaN or an infinite
value in the given array.
A NaN (Not A Number) is a floating-point data type introduced by the IEEE 754 standard to signal invalid
real values resulting from operations like 0/0 or asin(3). The standard also provides floating-point
representations for infinity quantities resulting from operations like 1/0.
Use
Called By
Prerequisite
None
Calling Sequence
CALL NANINF (values, n, answer, pos)
Input Argument
values A real input array of any size.

n An integer that indicates the size of the input array.
Output Argument
answer An integer value signaling the outcome of the browsing action. A value 0 indicates all entries
in the array are real numbers. A value of 1 indicates there is one NaN in the array. A value of
2 indicates there is an infinite value in the array.
pos If 'answer' returns a value 1 or 2, then 'pos' returns the 1-based index into the array with the
offending value.
Extended Definition
Subroutine NANINF is useful to check values passed to Adams Solver from within user-written subroutines.
This subroutine should be used only while debugging.
Passing a NaN will cause an integrator failure because NaNs propagate through all data structures. Due to
performance issues, Adams Solver does not check whether NaNs or infinite values are passed to it by user-
written subroutines.
NANINF 95
Utility Subroutines
FORTRAN - Prototype
Subroutine NANINF is defined as follows.
SUBROUTINE NANINF(VALUES, N, ANSWER, POS)
C
C
INTEGER N, ANSWER, POS
DOUBLE PRECISION VALUES(*)
C Style - Prototype
Function c_naninf is defined as follows.
void c_naninf( const double *values, const int *n, int *answer, int *pos )
Caution: When using the C-Style function, argument 'pos' returns a 1-based index of the offending
value if any.
Example
For example, from within a VFOSUB, you could write:
SUBROUTINE VTOSUB(ID, TIME, PAR, NPAR, DFLAG,

& IFLAG, RESULT)
C
C
INTEGER ID
INTEGER NPAR
LOGICAL DFLAG
INTEGER IFLAG
INTEGER N, ANSWER, IDX
C Compute values in RESULT
……
C Check values
N = 3
CALL NANINF( RESULT, N, ANSWER, IDX )
IF(ANSWER.EQ.1) THEN
C Print value of IDX and stop. Review the code
WRITE(*,*) 'Value NaN found at IDX = `, IDX
STOP
ENDIF
C
RETURN
END
96 Adams Solver
Utility Subroutines
NMODES
NMODES returns the number of active modal generalized coordinates associated with a FLEX_BODY
statement (C++ or FORTRAN).
Use
Called By
Prerequisite
FLEX_BODY statement in dataset
Calling Sequence
CALL NMODES (id, nq, errflg)
Input Argument
id An integer variable containing the identifier of the FLEX_BODY statement for which the
number of active modal generalized coordinates should be retrieved.
Output Argument
nq An integer that indicates the number of active 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 if the FLEX_BODY has no active modal coordinates; that is
the case of rigitized FLEX_BODYs.
 Flag errflg will return true if there is no active FLEX_BODY corresponding to id.
 The value of nq is not changed when errflag is true.
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 installed your Adams software.
 For Linux, in the directory /install_dir/solver/samples, where install_dir is the directory in which
you installed your Adams software.
NMODES 97
Utility Subroutines
• sysary_sample.acf
• sysary_sample.adm
• sysary_sample.f
• sysary_sample.mtx
98 Adams Solver
Utility Subroutines
POLY
The POLY general subroutine evaluates a polynomial.
Use
Called By
Prerequisite
None
Calling Sequence
CALL POLY (x, x0, par, npar, iord, value, errflg)
Input Arguments
iord An integer variable that defines the order of the derivative that POLY is to return. The order is
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.
POLY 99
Utility Subroutines
Output Arguments
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 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:
IORD: Value:
0 F(x)
1 ∂F (x)
--------------
∂x
2
2 ∂F ( x -)
----------------
2
∂x
Extended Definition
A POLY general subroutine evaluates a polynomial. The following equation defines POLY:
a
j
 aj ( x – x0 )
j=0
100 Adams Solver
Utility Subroutines
PUT_SPLINE
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
Calling Sequence
CALL PUT_SPLINE (id, nx, nz, x, y, z, errflg)
Input Argument
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.
Output Argument
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.
Extended Definition
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.
PUT_SPLINE 101
Utility Subroutines
 The z array is not used when nz = 1. The value of z is irrelevant in this case; however, z must exist.
 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.
102 Adams Solver
Utility Subroutines
RCNVRT
RCNVRT converts rotational coordinates from one representation to another.
Use
Called By
Prerequisite
None
Calling Sequence
CALL RCNVRT (sys1, coord1, sys2, coord2, istat)
RCNVRT 103
Utility Subroutines
Input Arguments
104 Adams Solver
Utility Subroutines
RCNVRT 105
Utility Subroutines
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
106 Adams Solver
Utility Subroutines
`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.
RCNVRT 107
Utility Subroutines
Output Arguments
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,
not right-handed triads.
Extended Definition
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.
108 Adams Solver
Utility Subroutines
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.
Tip
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 row order in coord2.
RSTRNG 109
Utility Subroutines
RSTRNG
RSTRNG converts a double-precision variable to a character string.
Use
Called By
Prerequisite
None
Calling Sequence
CALL RSTRNG (reel, string, length, istat)
Input Argument
reel The double-precision number to be converted.
Output Arguments
istat An integer variable indicating the success or the reason for the failure of the call to RSTRNG.
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.
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.
Extended Definition
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.
110 Adams Solver
Utility Subroutines
Tip: If the dimension of the string is CHARACTER*12 or longer, the string can hold any real
number.
SERIALIZE_CHARACTERS 111
Utility Subroutines
SERIALIZE_CHARACTERS
SERIALIZE_CHARACTERS allows you to save character static data from your user subroutines when
Solver is executing a SAVE/ command to be used later when reloading an analysis.
Use
Called By
Prerequisite
The user subroutine is being called to serialize data.
Calling Sequence
CALL SERIALIZE_CHARACTERS (c_array, n)
Input Argument
c_array A character array containing the data to be serialized.

n An integer variable that specifies the number of values contained in c_array.
Example
F77:
IF(IFLAG .EQ. 3)THEN
... Make calls to sysfnc and sysary to set up dependencies ...
ELSEIF (IFLAG .EQ. 7)THEN
CALL SERIALIZE_CHARACTERS(C_DATA, LEN(C_DATA))
CALL UNSERIALIZE_CHARACTERS(C_DATA, LEN(C_DATA))
ENDIF
CXX:
switch(IFLAG){
case 3:
... Make calls to c_sysfnc and c_sysary to set up dependencies ...
break;
case 7:
c_dataSize = strlen(c_data)+1;
c_adams_serialize_integers(&c_dataSize, 1);
c_adams_serialize_characters(c_data, c_dataSize);
break;
case 9:
if(c_data)free(c_data);
c_adams_unserialize_integers(&c_dataSize, 1);
c_data = (char*) malloc(sizeof(char)*c_dataSize);
112 Adams Solver
Utility Subroutines
c_adams_unserialize_characters(c_data, c_dataSize);
break;
}
SERIALIZE_DOUBLES 113
Utility Subroutines
SERIALIZE_DOUBLES
SERIALIZE_DOUBLES allows you to save static double precision data from your user subroutines when
Solver is executing a SAVE/ command to be used later when reloading an analysis.
Use
Called By
Prerequisite
Calling Sequence
CALL SERIALIZE_DOUBLES (d_array, n)
Input Argument
d_array A double-precision array containing the data to be serialized.

n An integer variable that specifies the number of values contained in d_array.
Example
F77:
CALL SERIALIZE_DOUBLES(DP_DATA, N_DP_DATA)
CALL UNSERIALIZE_DOUBLES(DP_DATA, N_DP_DATA)
ENDIF
CXX:
switch(IFLAG){
case 3:
case 7:
c_adams_serialize_integers(&d_dataSize, 1);
c_adams_serialize_doubles(d_data, d_dataSize);
break;
case 9:
c_adams_unserialize_integers(&d_dataSize, 1);
if( d_data )free(d_data);
d_data= (double*) malloc(sizeof(double)*d_dataSize);
c_adams_unserialize_doubles(d_data, d_dataSize);
break;
}
114 Adams Solver
Utility Subroutines
SERIALIZE_INTEGERS
SERIALIZE_INTEGERS allows you to save static integer data from your user subroutines when Solver is
executing a SAVE/ command to be used later when reloading an analysis.
Use
Called By
Prerequisite
Calling Sequence
CALL SERIALIZE_INTEGERS (i_array, n)
Input Argument
i_array An integer array containing the data to be serialized.

n An integer variable that specifies the number of values contained in i_array.
Example
F77:
CALL SERIALIZE_INTEGERS(I_DATA, N_I_DATA)
CALL UNSERIALIZE_INTEGERS(I_DATA, N_I_DATA)
ENDIF
CXX:
switch(IFLAG){
case 3:
case 7:
c_adams_serialize_integers(&i_dataSize, 1);
c_adams_serialize_integers(i_data, i_dataSize);
break;
case 9:
c_adams_unserialize_integers(&i_dataSize, 1);
if( i_data )free(i_data);
d_data= (int*) malloc(sizeof(int)*i_dataSize);
c_adams_unserialize_integers(i_data, i_dataSize);
break;
}
SET_DGSE_TYPE 115
Utility Subroutines
SET_DGSE_TYPE
Subroutine SET_DGSE_TYPE is used to force Adams Solver C++ or Adams Solver FORTRAN to call a
GSE's GSE_UPDATE subroutine at the end of each successful integration step or at the regular defined
calling interval defined by the SAMPLE_PERIOD option.
Use
Called By
Subroutine GSE_UPDATE.
Prerequisite
GSE statement in dataset with discrete states.
Calling Sequence
CALL SET_DGSE_TYPE (id, type)
Input Arguments
id An integer variable that specifies the ID of a discrete GSE object. A discrete GSE object is created
by a GSE statement that has discrete states (for example, XD option).
type Set this value to 1 if you need the GSE_UPDATE function to be called at each successful
integration type step. Set this value to 0 when the standard behavior is required (GSE_UPDATE
is called according to the SAMPLE_PERIOD option in the GSE statement).
Output Argument
No output arguments
Caution: Call this function from within a GSE_UPDATE subroutine when IFLAG is not zero.
Example
SUBROUTINE GSE_UPDATE (ID, TIME, PAR, NPAR, DFLAG, IFLAG, ND,
* XDplus1)
C
C Inputs:
C
INTEGER ID, NPAR, ND
INTEGER IFLAG, DFLAG
C
C Outputs:
DOUBLE PRECISION XDplus1(ND)
C
116 Adams Solver
Utility Subroutines
IF( IFLAG ) THEN

CALL SET_DGSE_TYPE(1)
ENDIF
C
C User code here.
RETURN
END
SHF 117
Utility Subroutines
SHF
SHF evaluates a simple harmonic function.
Use
Called By
Prerequisite
None
Calling Sequence
CALL SHF (x, x0, a, w, phi, b, iord, value, errflg)
Input Arguments

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
118 Adams Solver
Utility Subroutines
Output Arguments
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
IORD: Value:
0 Value of the function. F(x)
1 Partial derivative of the function with respect to
∂F
------
x.
∂x
2 Second partial derivative of the function with
2
respect to x. ∂--------
F-
2
∂x
Extended Definition
The following equation defines SHF:
a ⋅ sin ( w ⋅ ( x – x0 ) – phi ) + b
STEP 119
Utility Subroutines
STEP
STEP approximates a step function with a cubic polynomial.
Use
Called By
Prerequisite
None
Calling Sequence
CALL STEP (x, x0, h0, x1, h1, iord, value, errflg)
Input Arguments

x0 A double-precision variable that specifies the x value at which the step function begins.
h0 A double-precision variable that specifies the value of the function before the step.
x1 A double-precision variable that specifies the x value at which the step function ends.
h1 A double-precision variable that specifies the value of the function after the step.
iord An integer variable that defines the order of the derivative that STEP is to return. The order is
120 Adams Solver
Utility Subroutines
Output Arguments
errflg A logical (true or false) variable that STEP returns to the calling subroutine. If STEP detects
calling subroutine.
follows:
IORD: Value:
∂F
------
x.
∂x
2
respect to x. ∂--------
F-
2
∂x
Extended Definition
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
Figure 1. Step Function
STEP 121
Utility Subroutines
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.
 h0 ;x ≤ x 0 
 
 ( x – x0 ) 2 ( x – x0 )  
- ⋅ 3 –  2 ⋅ --------------------
STEP =  h 0 + ( h 1 – h 0 ) ⋅ -------------------- - ;x 0 < x < x 1
 ( x1 – x0 )  ( x1 – x0 )  
 
 h1 ;x ≥ x 1 
For an example of a SENSUB evaluation subroutine that calls STEP, see SENSUB.
Caution: The value x1 must not equal x0. Equal values of x1 and x0 imply a discontinuous step, which
STEP cannot fit.
122 Adams Solver
Utility Subroutines
STEP5
STEP5 approximates a step function with a quintic polynomial.
Use
Called By
Prerequisite
None
Calling Sequence
CALL STEP5 (x, x0, h0, x1, h1, iord, value, errflg)
Input Arguments

x0 A double-precision variable that specifies the x value at which the step function begins.
h0 A double-precision variable that specifies the value of the function before the step.
x1 A double-precision variable that specifies the x value at which the step function ends.
h1 A double-precision variable that specifies the value of the function after the step.
iord An integer variable that defines the order of the derivative that STEP5 is to return. The order is
STEP5 123
Utility Subroutines
Output Arguments
errflg A logical (true or false) variable that STEP5 returns to the calling subroutine. If STEP5 detects
calling subroutine.
follows:
IORD: Value:
∂F
------
x.
∂x
respect to x. 2
∂--------
F-
2
∂x
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
Figure 1. STEP5 Function

124 Adams Solver
Utility Subroutines
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 )
 
 h0 ;x ≤ x 0 
 
STEP5 =  h + a ( Δ 3 ⋅ [ 10 – 15Δ + 6Δ 2 ] ) ;x 0 < x < x 1
 0 
 h1 ;x ≥ x 1 
 
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 125
Utility Subroutines
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
Calling Sequence
CALL SUBTRACT_MASS_PROPERTY (cm1, mass1, ip1, cm2, mass2, ip2)
Input Arguments
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.
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.
ip2 A double-precision array of length 6 giving the 6 independent terms in the inertia tensor 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.
Output Arguments
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.
126 Adams Solver
Utility Subroutines
Extended Definition
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 127
Utility Subroutines
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
Calling Sequence
CALL SYSARY (fncnam, ipar, nsize, states, nstates, errflg)
Input Arguments
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 marker I in the coordinate
system of marker J.
UVZ Returns the direction cosines of the z-axis of marker I in the coordinate
system of marker J.
DC Returns the direction cosines of the x-, y-, and z-axes of marker I in the
coordinate system of marker J.
128 Adams Solver
Utility Subroutines
SYSARY 129
Utility Subroutines
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.
Flexible Body Functions:

FXTDISP Returns three values of the global position of the BCS of a FLEX_BODY.
FXDC Returns nine values of the global direction cosines of the BCS of a
FLEX_BODY.
FXTVEL Returns three values of the global translational velocity of the BCS of a
FLEX_BODY.
FXRVEL Returns three values of the global angular velocity of the BCS of a
FLEX_BODY.
130 Adams Solver
Utility Subroutines
ipar An integer array of size nsize that contains the parameter list for function fncnam. The table
below 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 below for the number of parameters
that function fncnam requires.
Output Arguments
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. The
value returned in this variable is as defined in the table below.
Note: An integer variable, not a constant, must be used here to prevent a programing
memory violation error.
states A double-precision array whose size depends on the fncnam (see the table below) 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.
Extended Definition
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
SYSARY 131
Utility Subroutines
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.
For the case of FXTDISP, FXDC, FXTVEL and FXRVEL, the first input parameter in the ipar array must
be equal to the Adams Solver ID of the FLEX_BODY and the nsize parameter must be equal to one (1).
Notice that the values returned using FXTDISP, FXDC, FXTVEL and FXRVEL are only available using
SYSARY; they are not available as standard Adams Solver functions.
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])
states(2) = THETA(i1[,i2])
states(3) = PHI(i1[,i2])
Q 1 NMODES* --
UVX** 2 3 --
UVY** 2 3 --
UVZ** 2 3 --
DC** 2 9 --
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])
states(2) = WY(i1[,i2,i3])
states(3) = WZ(i1[,i2,i3])
QDOT 1 NMODES* --
132 Adams Solver
Utility Subroutines

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])
states(2) = WDTY(i1[,i2,i3,i4])
states(3) = WDTZ(i1[,i2,i3,i4])
QDDOT 1 NMODES*
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])
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)
SYSARY 133
Utility Subroutines

ARRAY 1 n*** states(1) = ARYVAL(i1,1)
states(2) = ARYVAL(i1,2)
states(3) = ARYVAL(i1,3)
.
.
.
states(n) = ARYVAL(i1,n)
FXTDISP 1 3 states(1) to states(3) return the x, y
and z components (respectively) of
the global position of the BCS of a
FLEX_BODY.
FXDC 1 9 states(1) to states(9) return the
direction cosine matrix of the BCS
of a FLEX_BODY. The values are
returned in column order (for
example, the first three values are
the entries of the first column.)
FXTVEL 1 3 states(1) to states(3) return the x, y
the global translational velocity of
the BCS of a FLEX_BODY.
FXRVEL 1 3 states(1) to states(3) return the x, y
the global angular velocity of the
BCS of a FLEX_BODY.
*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.
The iflag is an integer variable that Adams Solver sets to indicate why the routine is being called:
Value Description
0 Normal function evaluation
1 Expression construction (Adams Solver C++ only)
3 Mapping dependencies
134 Adams Solver
Utility Subroutines
Value Description
5 Expression destruction (Adams Solver C++ only)
7 Expression serialization
9 Expression un-serialization
When the iflag argument in the user subroutine is 3, 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 argument is 0,
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.
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.
SYSARY 135
Utility Subroutines
Caution: When the iflag argument is 1 or 3, 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 = 1 or 3) or for a function evaluation (iflag = 0). 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 1 or 3. Adams Solver uses this
information to construct the correct Jacobian matrix. User-written subroutines should not
call SYSARY when iflag = 5, 7 or 9.
When unit vectors ('UVX', 'UVY', 'UVZ') are requested, it is possible, due to numerical
roundoff, that the vectors are not of exactly unit length. It is up to the author of the user-
written subroutine to ensure that these roundoff differences do not cause errors. For example,
the term sqrt(1.0-UVX(1)^2-UVX(2)^2) can fail due to a negative argument for the sqrt()
function.
Similarly, the direction cosine matrix ('DC') may not be perfectly orthogonal.
Examples
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, IFLAG
DOUBLE PRECISION TIME, PAR(*)
LOGICAL DFLAG
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
136 Adams Solver
Utility Subroutines
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
C --- External variable definitions -------------------
C
INTEGER ID
INTEGER NPAR
LOGICAL DFLAG
INTEGER IFLAG
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)
SYSARY 137
Utility Subroutines
DOUBLE PRECISION FREQ(MAXQ)

INTEGER FBDYID,IPAR(NARG),NQ,I
INTEGER OMODE(MAXQ)
LOGICAL ERRFLG
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
138 Adams Solver
Utility Subroutines

40 CONTINUE
C
RETURN
END
For other examples that use the SYSARY data access subroutine, see the evaluation subroutines VFOSUB and
VTOSUB.
SYSFNC 139
Utility Subroutines
SYSFNC
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
CFFSUB, CNFSUB, CONSUB, DIFSUB, GFOSUB, REQSUB, SENSUB, SFOSUB, VARSUB,
VFOSUB, and VTOSUB
Calling Sequence
CALL SYSFNC (fncnam, ipar, nsize, state, errflg)
140 Adams Solver
Utility Subroutines
Input Arguments
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
Element-specific BEAM, BUSH, CONTACT, FIELD, SPDP, SFORCE, VFORCE,
force VTORQ, GFORCE, NFORCE*, JOINT, JPRIM, MOTION,
CVCV, PTCV
System element ARYVAL, DIF, DIF1, PINVAL, POUVAL, SENVAL, VARVAL
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.
SYSFNC 141
Utility Subroutines
Output Arguments
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 not zero in the user-written subroutine, or when input errors are found.
Extended Definition
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.
The iflag is an integer variable that Adams Solver sets to indicate why the routine is being called:
Value Description
When the iflag argument in the user subroutine is 3, 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 0, SYSFNC
returns the instantaneous values of the system states.
142 Adams Solver
Utility Subroutines
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 1 or 3, 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 = 1 or 3) or for a function evaluation (iflag = 0). 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 1 or 3. Adams Solver uses this
information to construct the correct Jacobian matrix. User-written subroutines should not
call SYSFNC when iflag = 5, 7 or 9.
Examples
For examples using the SYSFNC data access subroutine, see the evaluation subroutines SFOSUB and
VARSUB.
SYSPAR 143
Utility Subroutines
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.
Use
Called By
Any user subroutine that can call SYSFNC and SYSARY.
Calling Sequence
CALL SYSPAR (fncname, iparam, nparam, partl, npartl, errflg)
Input Arguments
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.
144 Adams Solver
Utility Subroutines
Output Arguments
errflg A logical variable that returns true if an error has occurred during your call to SYSPAR.
Extended Definition
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(M1(q), M2 (q), ..., MN (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
∂F
------ , of the function relative to the system-generalized
purpose, Adams Solver requires the partial derivatives,
∂q
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 F ( qi + Δ ) – F ( qi )
------ = -----------------------------------------
-
∂q Δ
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:
SYSPAR 145
Utility Subroutines
N N
∂F ∂M j
∂F -------- F ( M j + Δ ) – F ( M j ) ∂M j
-------
∂q i
=  ---------
∂M j ∂q i
- =  ---------------------------------------------- ---------
Δ ∂q i
j=1 j=1
Note that in keeping with the observation that F is a black box, Adams Solver continues to rely on
∂F-
--------
finite differencing to compute , where Mj is well known and its partial derivatives can be
∂M j
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.
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 quantities,
∂F-
--------
Mi, computing may be straightforward. Adams Solver (C++) provides SYSPAR: an interface
∂M j
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.
∂F
---------
When F and M have dimension greater than 1, the partial matrix, should be stored in partl in
∂M j
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)
146 Adams Solver
Utility Subroutines
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.
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.
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.
Examples
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 = M1 M2
where M1 = DX(1,2) and M2 = VZ(1,2). Consequently:
∂F
---------- = VZ ( 1, 2 )
∂M 1
and
∂F
---------- = DX ( 1, 2 )
∂M 2
The SFOSUB implementation follows:
SUBROUTINE SFOSUB (ID, TIME, PAR, NPAR, DFLAG, IFLAG, VALUE)
INTEGER ID
INTEGER NPAR
LOGICAL DFLAG
INTEGER IFLAG
SYSPAR 147
Utility Subroutines
DOUBLE PRECISION DX, VZ

INTEGER NUM, IPAR(2)
LOGICAL ERRFLG
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-M1,-M2)
where M1 = DM(12,9) and M2 = VR(12,9). Here, you must rely on the ability of the IMPACT utility
function to provide partial derivatives of its arguments.
∂F-
--------- ∂IMPACT
= -------------------------- ( 400 – M 1′ – M 2 ) ( – 1 )
∂M 1 ∂M 1
∂F
---------- ∂IMPACT
= -------------------------- ( 400 – M 1′ – M 2 ) ( – 1 )
∂M 2 ∂M 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
INTEGER IFLAG
148 Adams Solver
Utility Subroutines
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 )
IF(PARFLG) THEN
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).
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
INTEGER 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
SYSPAR 149
Utility Subroutines
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 )
IF(PARFLG) THEN
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
150 Adams Solver
Utility Subroutines
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)
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.
SYSPAR 151
Utility Subroutines
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.
152 Adams Solver
Utility Subroutines
TCNVRT
TCNVRT converts translational coordinates from one representation to another.
Use
Called By
Prerequisite
None
Calling Sequence
CALL TCNVRT (sys1, coord1, sys2, coord2, istat)
Input Arguments
sys1 A character string specifying the system in which the values passed in coord1 were
determined. The possible character strings and their meanings are:
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.
TCNVRT 153
Utility Subroutines
Output Arguments
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.
Extended Definition
MOTSUB, REQSUB, or SFOSUB can call TCNVRT to change the Cartesian coordinates used to specify a
displacement vector to cylindrical coordinates.
154 Adams Solver
Utility Subroutines
TIMGET
TIMGET returns the simulation time corresponding to the last successful simulation step.
Use
Called By
Calling Sequence
CALL TIMGET (time)
Output Argument
time A double-precision scalar that contains the simulation time at the end of the last successful step.
Extended Definition
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.
UNSERIALIZE_CHARACTERS 155
Utility Subroutines
UNSERIALIZE_CHARACTERS
UNSERIALIZE_CHARACTERS allows you to reload character data into your user subroutines when Solver
is executing a RELOAD/ command.
Use
Called By
Prerequisite
The user subroutine is being called to unserialize data.
Calling Sequence
CALL UNSERIALIZE_CHARACTERS (c_array, n)
Input Argument
n An integer variable that specifies the number of values to un-serialize.
Output Argument
c_array A character array to receive the serialized data.
Example
F77
CALL SERIALIZE_CHARACTERS(C_DATA, LEN(C_DATA))
CALL UNSERIALIZE_CHARACTERS(C_DATA, LEN(C_DATA))
ENDIF
CXX:
switch(IFLAG){
case 3:
break;
case 7:
c_dataSize = strlen(c_data)+1;
c_adams_serialize_integers(&c_dataSize, 1);
c_adams_serialize_characters(c_data, c_dataSize);
156 Adams Solver
Utility Subroutines
break;
case 9:
if(c_data)free(c_data);
c_adams_unserialize_integers(&c_dataSize, 1);
c_data = (char*) malloc(sizeof(char)*c_dataSize);
c_adams_unserialize_characters(c_data, c_dataSize);
break;
}
UNSERIALIZE_DOUBLES 157
Utility Subroutines
UNSERIALIZE_DOUBLES
UNSERIALIZE_DOUBLES allows you to reload double precision data into your user subroutines when
Solver is executing a RELOAD/ command.
Use
Called By
Prerequisite
Calling Sequence
CALL UNSERIALIZE_DOUBLES (d_array, n)
Input Argument
Output Argument
d_array A double-precision array to receive the serialized data.
Example
F77:
CALL SERIALIZE_DOUBLES(DP_DATA, N_DP_DATA)
CALL UNSERIALIZE_DOUBLES(DP_DATA, N_DP_DATA)
ENDIF
CXX:
switch(IFLAG){
case 3:
case 7:
c_adams_serialize_integers(&d_dataSize, 1);
c_adams_serialize_doubles(d_data, d_dataSize);
break;
case 9:
c_adams_unserialize_integers(&d_dataSize, 1);
158 Adams Solver
Utility Subroutines
if( d_data )free(d_data);

d_data= (double*) malloc(sizeof(double)*d_dataSize);
c_adams_unserialize_doubles(d_data, d_dataSize);
break;
}
UNSERIALIZE_INTEGERS 159
Utility Subroutines
UNSERIALIZE_INTEGERS
UNSERIALIZE_INTEGERS allows you to reload integer data into your user subroutines when Solver is
executing a RELOAD/ command.
Use
Called By
Prerequisite
Calling Sequence
CALL UNSERIALIZE_INTEGERS (i_array, n)
Input Argument
Output Argument
i_array An integer array to receive the serialized data.
Example
F77:
CALL SERIALIZE_INTEGERS(I_DATA, N_I_DATA)
CALL UNSERIALIZE_INTEGERS(I_DATA, N_I_DATA)
ENDIF
CXX:
switch(IFLAG){
case 3:
... Make calls to c_sysfnc and c_sysary to set up dependencies
...
case 7:
c_adams_serialize_integers(&i_dataSize, 1);
c_adams_serialize_integers(i_data, i_dataSize);
break;
160 Adams Solver
Utility Subroutines
case 9:
c_adams_unserialize_integers(&i_dataSize, 1);
if( i_data )free(i_data);
d_data= (int*) malloc(sizeof(int)*i_dataSize);
c_adams_unserialize_integers(i_data, i_dataSize);
break;
}
UCOVAR 161
Utility Subroutines
UCOVAR
UCOVAR is used with UCOSUB, to tell Adams Solver the part states that are used in the user-defined
constraint.
Use
Called By
UCOSUB
Prerequisite
UCOSUB iflag parameter equals is not zero.
Calling Sequence
CALL UCOVAR (id, nparts, lparts, nvars, lvars)
Input Arguments
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.
162 Adams Solver
Utility Subroutines
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
respect to ground
13 Z displacement of the part center-of-mass with
respect to ground
14 Psi Euler rotation of part principle axis with respect
to ground
15 Theta Euler rotation of part principle axis with
respect to ground
16 Phi Euler rotation of part principle axis with respect
to ground
21 X velocity of the part center-of-mass with respect to
ground
22 Y velocity of the part center-of-mass with respect to
ground
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 163
Utility Subroutines
Extended Definition
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.
 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.
164 Adams Solver
Utility Subroutines
USRMES
USRMES allows you to output messages for information or for documenting errors that occur in user-written
subroutines.
Use
Called By
Prerequisite
None
Calling Sequence
CALL USRMES (msgflg, mesage, id, msgtyp)
Input Arguments
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 1024 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 165
User-Written Subroutines
Extended Definition
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, 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.
166 Adams Solver
Basics
Types of User-Written Subroutines

The user-written subroutines are divided into three categories, based on their functionality:
 Driver Subroutine
 Evaluation Subroutines
 Restart Subroutines
Driver Subroutine
The driver subroutine, CONSUB, drives Adams Solver. It lets you further automate the analysis and
modification of Adams Solver models by defining your own sequence of events or data flow within a
simulation. It is a very powerful tool, so you will probably not need to use it unless you are an advanced
Adams Solver user.
With CONSUB you can issue commands to request, regulate, and vary one or more Adams Solver
simulations. Using a CONSUB, you can issue interactive commands to modify a dataset and/or run many
different analyses. The most common modes for running Adams Solver simulations are interactive or batch
processing, involving a single analysis at a time. Using CONSUB, you can, for example, perform a dynamic
analysis of a dataset, vary a statement, and repeat the dynamic analysis.
Evaluation Subroutines
The evaluation subroutines allow you to tailor Adams modeling elements to individual applications.
Evaluation subroutines are user-defined elements. Many Adams Solver statements allow you to write
subroutines to evaluate nonstandard or complex values for statements (see the table below).
The following table lists the names and definitions for the evaluation subroutines:
Adams Solver
Statement/Command: Subroutines: Do the following:
CONTROL CONSUB Controls an Adams simulation.
COUPLER COUSUB, COUXX, Defines a user-defined COUPLER.
COUXX2,
CURVE CURSUB Computes curve coordinates and their derivatives for a
CURVE statement.
DIFF DIFSUB Defines a user-defined differential-equation value in
Adams.
FLEX_BODY DMPSUB Computes the modal damping ratios for a
FLEX_BODY statement.
FIELD FIESUB Computes the force and torque components and their
derivatives for a FIELD statement.
Basics 167
Adams Solver
Statement/Command: Subroutines: Do the following:
GFORCE GFOSUB Computes a set of values for a GFORCE statement.
GSE GSE_DERIV, Used with the GSE statement to compute the current
GSE_OUTPUT, values of the necessary partial derivatives of the states
GSE_UPDATE, and outputs.
GSE_SAMP
MFORCE MFOSUB Computes the modal force applied by an MFORCE
statement.
MOTION MOTSUB Computes the joint displacement, velocity, and
acceleration for a MOTION statement.
RELOAD RELSUB Allows you to reload any information needed to restart
user-written subroutines.
REQUEST REQSUB Computes the output values for a REQUEST
statement.
SAVE SAVSUB Allows you to store any information needed to later
restart user-written subroutines.
SENSOR SENSUB Computes a sensed value for a SENSOR statement.
SFORCE SFOSUB Computes the force magnitude for an SFORCE
statement.
UCON UCOSUB Computes a constraint value and its derivatives for a
UCON statement.
VARIABLE VARSUB Computes an algebraic value for a VARIABLE
statement.
VFORCE VFOSUB Computes force components for a VFORCE
statement.
VTORQUE VTOSUB Computes torque components for a VTORQUE
statement.
Restart Subroutines
The two restart subroutines, SAVSUB and RELSUB, allow you to save and reload any data that might be
necessary to restart or reinitialize other user-written subroutines following a RESTART command. You only
need to use them if other user-written subroutines store data internally from call to call. Unless you use
RELSUB and SAVSUB, the internal data is lost when you save a simulation and then later reload it into an
Adams Solver run.
The SAVE command allows you to save model and simulation data to a save file. You can then restart a
simulation from the saved point, by reloading the save file using the RELOAD command. The SAVE and
RELOAD commands do not, however, take any special action to restart user-written subroutines. After a
RELOAD, Adams Solver continues calling user-written subroutines just as it would have at the time you
saved the file.
168 Adams Solver
For example, if an SFOSUB computes force coefficients when first called and then stores them for later use,
they can be lost during a SAVE and RELOAD. You could write a SAVSUB to save the coefficients in the save
file and a RELSUB to re-read them, or you could write only a RELSUB to recompute the coefficients. Either
way, when you issue a RELOAD command, the SFOSUB regains the proper coefficients.
If, however, an SFOSUB uses only the information that Adams Solver passes through the PAR array and
information from utility subroutines, then a SAVSUB and RELSUB are not required because the SFOSUB
is not relying on any past data.
Guidelines
The following sections provide general guidelines for writing user-written subroutines:
 Subroutine Arguments
 Declaring Variables
 Using Parameters to Make Subroutines More General
 Avoiding Discontinuities
 FORTRAN Input/Output Units
Subroutine Arguments
User-written subroutines have two types of arguments: input and output.
 Input arguments provide you with the values Adams Solver assigns from information in the
corresponding command or statement, or from calculations indicating the current system state. Do
not change the values of these input arguments.
 Output arguments provide Adams Solver with information you have derived. Unless explicitly stated
otherwise, you should always supply values for output arguments.
Input and output arguments are in lowercase letters to indicate that you can choose any legal FORTRAN
variable for the argument name. Input arguments are listed first, followed by output arguments. Because
FORTRAN uses argument order to distinguish between arguments, you must not change the order of
arguments when passing them to, or when receiving them from, subroutines. Also, for each argument, use a
variable of the proper type and dimension. For information on variables, see the next section.
Declaring Variables
To ensure that values are properly transferred between your subroutines and Adams Solver subroutines, you
need to declare your subroutine arguments with the same type that Adams Solver uses.
Floating Point Variables
On 32-bit machines (most Linux and Windows machines), Adams Solver uses DOUBLE PRECISION
floating-point variables. Because an untyped floating-point variable usually defaults to single-precision (that
is, REAL), you must explicitly declare all your floating-point variables to be DOUBLE PRECISION.
Integers
On 32-bit machines, Adams uses 32 bits (integer * 4) to represent integers.
Basics 169
Using Parameters to Make Subroutines More General

Adams Solver always supplies to user-written subroutines the parameter values from the
FUNCTION=USER() argument on the corresponding statement or command. If you use
FUNCTION=USER (4.0, 5.0, 6.0), for example, Adams Solver passes a PAR array containing the values 4.0,
5.0, and 6.0, and passes NPAR containing the value of 3.
You can use this feature to make your subroutines more flexible. If your calculations depend on the distance
between markers 101 and 201, for example, you could write these identifiers directly in your subroutine. If,
however, you wanted to change the marker identifiers or use the subroutine with a different model, you would
have to edit the FORTRAN file, recompile, and then relink with Adams Solver.
You can avoid these time-consuming changes by putting the marker identifiers in the FUNCTION=USER()
argument and then using them as variables in your subroutine. If you want to change them, you only need
to change the FUNCTION=USER() argument in your statement or command, then re-run Adams Solver
with the same library.
Avoiding Discontinuities
As with run-time expressions, when using a subroutine to define motions, sensors, forces, or state equations
in a model, you must ensure that these functions are continuous. Furthermore, when defining displacement-
based motions, these functions are expected to be twice differentiable.
Discontinuous functions are difficult to handle because most numerical integration schemes require, and
therefore assume, that system equations are inherently continuous. If you violate this rule, Adams Solver
could produce unexpected results such as integration failure at the discontinuity. Discontinuous functions are
created most often when using IF statements to piece together separate functions. To ensure that the complete
function is indeed continuous, be very careful when using this type of logic.
Other discontinuous functions available in the FORTRAN language:
 MIN
 MAX
 DIM
 SIGN
 MOD
Use caution when using these intrinsic functions.
FORTRAN Input/Output Units

If you need to read or write files from your user-written subroutines, use FORTRAN units 90 and above.
Adams Solver reserves these units for your use.
Writing Subroutines
To help you create your own user-written subroutines, we have provided subroutine templates in the directory
/install_dir/Adams/<Release>solver/usersubs (install_dir is the directory where the
Adams products are installed). If you can't find this directory, please contact your system administrator.
170 Adams Solver
User subroutines written in C are also supported. Examples are included in the directory
/install_dir/Adams/<Release>solver/samples.
To write a user-written subroutine:

1. Determine which user-written subroutine you need to use. For example, if you have a GFORCE
statement, you need to create a GFOSUB user-written subroutine.
2. Determine what you need to calculate, and what the input parameters are. This information
determines the information you pass from the FUNCTION=USER() argument in the statement to
the subroutine.
3. Copy the appropriate user-written subroutine template from the installation directory to your local
directory. The template directory contains all the subroutine templates you might need to use.
4. View the user-written subroutine template using a text editor.
5. Modify the user-written subroutine as desired. You can call a utility subroutine or other FORTRAN
or C subroutines from within the user-written subroutine.
6. Save your user-written subroutine. Give the file a descriptive name because you may want to use the
same subroutine for different models.
Creating a User Library

There are three steps for using your own subroutines with Adams:
1. Write your own subroutines and make sure they follow Adams naming and calling sequence
conventions.
2. Compile and link in your custom subroutines with the standard Adams library of routines to create
a new, dynamically linked, dynamically loaded library (.dll on Windows; .sl, .so on Linux).
3. Use your user library to run your simulations.
Basics 171
Standard
Adams Solver
Executable
User-written User-written
Adams Generic
Subroutine #1 Subroutine #1
User-written
Adams
Subroutine #2
Pre-defined
Adams Library
User-written User-written
Adams Generic
Subroutine #N Subroutine #N
Standard
Adams Solver Custom Library
Executable (.dll)
Your Custom Solver
Subroutine Arguments
Each Adams subroutine has specific arguments. Some arguments are common to many subroutines. For
example:
SUBROUTINE SFOSUB (id, time, par, npar, dflag, iflag, value)
where:
 id - Adams Solver identification number of the statement calling the subroutine (for example,
SFORCE/2). Common to all.
 time - Current simulation time. Common to all.
172 Adams Solver
 par - Array of passed parameters. Common to all.

 npar - Number of parameters passed in par. Common to all.
 dflag - Differencing flag indicating that Adams Solver is calling the subroutine to perform numeric
differencing (logical variable set to true); typically used for debugging or more advanced
management of numeric differencing
 iflag - An integer variable that Adams Solver sets to indicate why the routine is being called:
Value Description
When iflag is 0 Adams Solver calling to compute the value of the user-written variable. When iflag is
set to 1 or 3 do any initializations that your subroutine requires.
When your user-defined subroutine has static data that needs to be saved and restored to support the
Adams Solver commands Save and Reload, then call the serialization functions for your data when
iflag is set to 7, and the un-serialization functions when iflag is set to 9. For more information, see
REQUEST, SYSFNC, and SYSARAY Subroutines.
Note: In simple subroutines where serializing data is not needed, you can declare iflag as a
logical variable. In this case you can do any initializations when Adams Solver sets iflag
to true, and compute the subroutine's value when Adams Solver sets iflag to false.
 value - Result(s) returned by the subroutine. Common to all.
Note: The actual names of the arguments do not matter. For example, value could be called
result. It is the order of the arguments that is important.
Basics 173
Using Multiple Subroutines

You can use multiple subroutines with Adams by linking them together into one user library.
To use multiple subroutines:

1. Create your Adams subroutines.
2. Compile each subroutine individually with the flags specified by Adams, as specified in Compiling
Subroutines.
Note: If source code is supplied, the script will automatically compile the files for you.
3. Link all object files into one user library. For example:
• On Windows: adams2021_0_2 cr-user myvarsub.obj yourreqsub.obj –n my_lib.dll
• On Linux: adams2021_0_2 –c cr-user myvarsub.f yourreqsub.f –n my_lib.so
Here, both object files are linked into one library, my_lib.[dll,so].
Working with Multiple Subroutines of the Same Type

You can use multiple subroutines of the same type with the ROUTINE Argument.
Note: The template-based (vertical) products, which include Adams Car, and Adams Driveline, use
a special dispatcher subroutine that automatically branches for you. The template-based
products require different subroutine naming, using numbers in the name (for example,
VAR001.f, VAR134.f ). The dispatcher subroutine branches based on the name of the
subroutine.
Example
Note the BRANCH_ID indicated in red.

& IFLAG, VALUE)
C
C
C
INTEGER ID
INTEGER NPAR
174 Adams Solver
LOGICAL DFLAG
INTEGER IFLAG
C
C TIME Current time
C
C --- Local variables ---------------------------------
C
DOUBLE PRECISION DISP_TRIG, STIFF_COEFF, STIFF_EXP,
& DAMP_COEFF, PEN_DEPTH, IMPARY(3),
& DISP_Y, VEL_Y, MU, VEL_X, OMEGA_Z,
& SLIP, EPSILON, H0, H1, STPVAL,
& NEG_EPSILON
INTEGER I_MAR, J_MAR, IORD, IPAR(3), NSIZE,
& BRANCH_ID
LOGICAL ERRFLG
C
C
DISP_TRIG = PAR(1)
STIFF_COEFF = PAR(2)
STIFF_EXP = PAR(3)
DAMP_COEFF = PAR(4)
PEN_DEPTH = PAR(5)
I_MAR = PAR(6)
J_MAR = PAR(7)
MU = PAR(8)
BRANCH_ID = PAR(9)
IORD = 0
EPSILON = 0.1
NEG_EPSILON = -1.0*EPSILON
H0 = 1
H1 = -1
C
IPAR(1) = I_MAR
IPAR(2) = J_MAR
IPAR(3) = J_MAR
NSIZE = 3
CALL SYSFNC('DY', IPAR, NSIZE, DISP_Y, ERRFLG)
CALL SYSFNC('VY', IPAR, NSIZE, VEL_Y, ERRFLG)
CALL SYSFNC('VX', IPAR, NSIZE, VEL_X, ERRFLG)
CALL SYSFNC('WZ', IPAR, NSIZE, OMEGA_Z, ERRFLG)
C
CALL IMPACT(DISP_Y, VEL_Y, DISP_TRIG, STIFF_COEFF, STIFF_EXP,
& DAMP_COEFF, PEN_DEPTH, IORD, IMPARY, ERRFLG )
C
IF (BRANCH_ID .EQ. 1) THEN
C
Basics 175
VALUE = IMPARY(1)
C
ELSEIF (BRANCH_ID .EQ. 2) THEN
C
SLIP = VEL_X+OMEGA_Z*DISP_TRIG
CALL STEP(SLIP, NEG_EPSILON, H0, EPSILON, H1, IORD,
& STPVAL, ERRFLG)
VALUE = MU*IMPARY(1)*STPVAL
C
ELSEIF (BRANCH_ID .EQ. 3) THEN
C
SLIP = VEL_X+OMEGA_Z*DISP_TRIG
CALL STEP(SLIP, NEG_EPSILON, H0, EPSILON, H1, IORD,
& STPVAL, ERRFLG)
VALUE = MU*IMPARY(1)*STPVAL*DISP_TRIG
C
ENDIF
C
RETURN
END
Invoking Subroutines
Some modeling elements allow you to use subroutines to define their behavior. You can invoke user-written
subroutines from statements or commands. You have to use pre-assigned names for your custom subroutines
so that Adams Solver knows which ones to call, and when.
The table below lists the statements or commands that can reference user-written subroutines and the name
of the user-written subroutine(s) they can reference.
To invoke the subroutine: Use the statement/command:

CFFSUB, CNFSUB FRICTION
CONSUB CONTROL
COUSUB, COUXX, COUXX2 COUPLER
CURSUB CURVE
DIFSUB DIFF
FIESUB FIELD
GFOSUB GFORCE
GSE_DERIV, GSE_UPDATE, GSE_OUTPUT, GSE_SAMP GSE
MOTSUB MOTION
RELSUB RELOAD
REQSUB REQUEST
176 Adams Solver
To invoke the subroutine: Use the statement/command:

SAVSUB , SEVSUB SAVE
SENSUB SENSOR
SFOSUB SFORCE
UCOSUB UCON
VARSUB VARIABLE
VFOSUB VFORCE
VTOSUB VTORQUE
You can call utility subroutines from your user-written subroutine. Utility Subroutines can provide
information about the current state of the system to the user-written subroutine.
Compiling, Linking, and Running Libraries

After writing your custom subroutine, you must compile it and link it to Adams to create an Adams Solver
user library. Then you can run Adams Solver with that library.
You must have a FORTRAN compiler, since a compiler is not supplied with Adams.
For more information on how to compile and link user subroutines, see Running and Configuring Adams.
Debugging Custom Libraries

If your library does not work as expected, you must debug it. For more information:
 For Windows, see Running and Configuring Adams.
 For Linux or Windows, see the MSC Simcompanion Knowledge Base
(http://simcompanion.mscsoftware.com/).
Example - Specifying a User-Written Subroutine

To help you become more familiar with subroutines, we've provided an example involving the GFOSUB
subroutine. You can find additional examples in the Adams installation in the subdirectories /solver/usersubs
and /solver/samples.
From your dataset, you can refer to user-written subroutines using the FUNCTION=USER argument in a
statement. For example, let's assume that you have a GFORCE statement with function expressions that
represent the three translational and three rotational vector components of a load at a point. If the force and
torque expressions become lengthy and awkward, you can use a GFOSUB user-written subroutine instead of
an expression in the GFORCE statement.
Your statement, using function expressions, might look like the following:
, FX = - 20.0*VX(310,9900,310)/
Basics 177
, FY = - 20.0*VY(310,9900,310)/
, FZ = - 20.0*VZ(310,9900,310)/
, TX = -500.0*WX(310,9900,310)/
, TY = -500.0*WY(310,9900,310)/
, TZ = -500.0*WZ(310,9900,310)
You can replace the above statement with the following statement that requires a user-written subroutine
GFOSUB to evaluate the force expressions. Notice how marker IDs are being passed through the parameter
list to make the subroutine generic.
, FUNCTION=USER(20, 500, 310, 9900)
You can then create a GFOSUB user-written subroutine that looks like the following:
SUBROUTINE GFOSUB(ID, TIME, PAR, NPAR, DFLAG,
& IFLAG, RESULT)
C
C
C
C - External variable definitions ------------
C
INTEGER ID
INTEGER NPAR
LOGICAL DFLAG
INTEGER IFLAG
C
C ID Identifier of calling GFORCE statement
C TIME Current time
C PAR Array containing passed parameters
C IFLAG Initial pass flag
C RESULT Array (dimension 6) of computed GFORCE
C components returned to ADAMS
C
C - Local variable and parameter definitions ------
C
DOUBLE PRECISION CT, CR, VEL(6)
INTEGER IPAR(3), IM, JM, NSTATES
LOGICAL ERRFLG
C
C
C Assign readable variable names to passed parameters
C
CT = PAR(1)
CR = PAR(2)
IM = PAR(3)
JM = PAR(4)
C
178 Adams Solver
C Call SYSARY to collect information for the

C calculations below. Note: if IFLAG is not zero, this
C call is actually setting functional dependencies.
C
C - Use VEL to get marker translational and rotational
C velocities
C
IPAR(1) = IM
IPAR(2) = JM
IPAR(3) = IM
CALL SYSARY('VEL', IPAR, 3, VEL, NSTATES, ERRFLG)
C
C - Check SYSARY call through ERRMES utility routine
C
CALL ERRMES(ERRFLG, 'Error calling SYSARY for VEL',
& ID, 'STOP')
C
C - Evaluate GFORCE components -------------
C
RESULT(1) = -CT * VEL(1)
RESULT(4) = -CR * VEL(4)
C
RETURN
END
Alternatively you can create a "C" GFOSUB user-written subroutine that looks like the following:
/*
* Using a function typedef from slv_c_utils.h, please declare your
* user subroutine before defining it. This will allow a compiler to
* perform type checking for your subroutine arguments.
*/
adams_c_Gfosub Gfosub;
/*
* Define a subroutine named 'Gfosub'. Any name is allowed,
* as long as it is mixed case and the name is specified in
* the ADAMS input file using the ROUTINE= keyword.
*
* Adams distinguishes between FORTRAN and C subroutines by looking
* up the function name in the library. If it finds a mixed case
* name then it assumes that the function is a C function. Otherwise
* it assumes Fortran.
*/
void Gfosub(const struct sAdamsGforce* gfo, double time, int dflag,

int iflag, double* result)
{
Basics 179
double ct = gfo->PAR[0];
double cr = gfo->PAR[1];
int im = (int)gfo->PAR[2];
int jm = (int)gfo->PAR[3];
double vel[6];
int ipar[3];
int nstates;
int errflg;
/*
Call SYSARY to collect information for the
calculations below. Note: if IFLAG is not zero, this
call is actually setting functional dependencies.
--- Use VEL to get marker translational and rotational

velocities
*/
ipar[0] = im;
ipar[1] = jm;
ipar[2] = im;
c_sysary("VEL", ipar, 3, vel, &nstates, &errflg);
/*
--- Check SYSARY call through ERRMES utility routine
*/
c_errmes(errflg,"Error calling SYSARY for VEL", gfo->ID, "STOP");
/*
--- Evaluate GFORCE components -------------------------
*/
result[0] = -ct*vel[0];
}
Unsupported Subroutines
Although Adams Solver continues to recognize many unsupported subroutines, new subroutines have made
some of them obsolete. The use of unsupported subroutines is discouraged as they may be removed from
future Adams Solver releases without notice.
This release of Adams Solver no longer supports the following subroutines available in previous releases:
GSESUB
GSEXX, GSEXU, GSEYX, GSEYU
180 Adams Solver
CBKSUB
The CBKSUB subroutine is an optional user-written subroutine that Adams Solver C++ calls at a predefined
set of events during the code execution. The CBKSUB only passes input values announcing the type of event,
the current simulation time, and a data array.
An event can be seen as a milestone reached during the code execution. An event is triggered when certain
conditions occur, for example, a SENSOR triggers or an error condition is detected. Most of the time a
milestone is reached naturally by the code, for example, a simulation command is about to be executed, a
corrector iteration is about to start and so on.
The CBKSUB is a true callback function designed for advanced users only.
Note: Use mixed case names for the Adams subroutine names when using the C style interface. For
the default subroutine name capitalize the first letter and have the remaining letters lower
case; Cbksub for example. Doing this ensures that Adams Solver correctly distinguishes a C
style subroutine from Fortran and calls with the appropriate interface.
Use
FORTRAN Calling Sequence

include 'slv_cbksub_util.inc'
SUBROUTINE CBKSUB ( time, event, data )
DOUBLE PRECISION time
INTEGER event, data(3)
C Calling Sequence
include "slv_cbksub.h"
include "slv_cbksub_util.h"
void Cbksub( const struct sAdamsCbksub *cbk, double time, int event, int *data )
C++ Calling Sequence

include "slv_cbksub.h"
include "slv_cbksub_util.h"
extern "C" void Cbksub( const struct sAdamsCbksub *cbk, double time, int event, int *data )
CBKSUB 181
Input Arguments
data An integer array with context dependent values. The values depend on the
type of event.
event An integer value identifying the type of event for which the call is being made.
As of now 39 events have been implemented.
time The current simulation time.
cbk Structure containing callback data (see below)
struct sAdamsCbksub
{
int ID;
int NPAR;
const double* PAR;
void *reserved;
};
Output Argument
The CBKSUB does not have output arguments.
Extended Definition
Currently, only the Adams Solver C++ supports the CBKSUB.
The overhead (CPU time) is negligible.
Providing this subroutine is optional.
All utility subroutines are allowed to be called from within the CBKSUB except
ADAMS_DECLARE_THREADSAFE, ANALYS, DATOUT, GTCMAT, MODIFY, PUT_SPLINE and
UCOVAR. Calling any of these subroutines makes the behavior of the Adams Solver C++ undefined. No
guards have been implemented.
None of the user-written subroutines are allowed to be called. The forbidden set includes CFFSUB,
CNFSUB, CONSUB, COUSUB, COUXX, COUXX2, CURSUB, DIFSUB, DMPSUB, FIESUB,
GFOSUB, GSE_DERIV, GSE_UPDATE, GSE_OUTPUT, GSE_SAMP, MFSUB, MOTSUB, RELSUB,
REQSUB, SAVSUB, SENSUB, SEVSUB, SFOSUB, SPLINE_READ, SURSUB, TIRSUB, VARSUB,
VFOSUB and VTOSUB. Calling forbidden subroutines makes the behavior of the Adams Solver C++
undefined. No guards have been implemented.
Both SYSFNC and SYSARY are allowed to be called from within the CBKSUB. Notice however, that no
dependencies are registered. This feature makes possible to compute some desired quantities without creating
dependencies. Usually, users will compute and cache values at specific events.
182 Adams Solver
Events
Thirty nine (39) events have been implemented. Below is the list of current supported events.
1=ev_INITIALIZE Triggered right after the library containing user-written subroutines

has been loaded. The data set defining the model has not been
processed. Input array data is undefined.
2=ev_TERMINATE Triggered before the model is going to be deleted. All user-written
subroutines will be called for the last time. First entry of input array
data contains the solver status. Other entries are undefined.
3=ev_SENSOR Triggered after a SENSOR has triggered. First entry of input array data
is the ID of the SENSOR. Second entry is an integer defining the type
of SENSOR:
1=sn_CODGEN
2=sn_DT
3=sn_HALT
4=sn_PRINT
5=sn_RESTART
6=sn_RETURN
7=sn_STEPSIZE
8=sn_YYDUMP
9=sn_EVALUATE
The third entry of input array data is ignored. Notice the SENSOR
must have an action associated with it (for example, HALT). If the
SENSOR has no action, no event will be triggered.
4=ev_ITERATION_BEG Triggered before the Jacobian and/or right-hand side evaluation is
about to start. First entry of input array data is the current simulation
mode. Second entry is the current analysis mode. The third entry is 1
if a Jacobian evaluation is requested, 0 otherwise.
5=ev_ITERATION_END Triggered after the Jacobian and/or right-hand side evaluation is
finished. First entry of input array data is the current simulation mode.
Second entry is the current analysis mode. The third entry is ignored.
6=ev_BODY_ROTATION Triggered before a body rotation is to take place. First entry of input
array data is the current simulation mode. Second entry is the current
analysis mode. The third entry is ignored.
7=ev_OUTPUT_STEP_REQ Triggered to request output generation. First entry of input array data
is the current simulation mode. Second entry is the current analysis
mode. The third entry is ignored.
CBKSUB 183
8=ev_OUTPUT_STEP_BEG Triggered when output generation is about to start. First entry of input
9=ev_OUTPUT_STEP_END Triggered after output generation is finished. First entry of input array
data is the current simulation mode. Second entry is the current
10=ev_TIME_STEP_BEG Triggered at the beginning of a time step. First entry of input array data
is the current simulation mode. Second entry is the current analysis
mode. The third entry is ignored.
11=ev_TIME_STEP_FAILE Triggered when the integration error can not be achieved and a
reduction of the time step is to be performed. First entry of input array
12=ev_TIME_STEP_END Triggered at the end of a successful time step. First entry of input array
13=ev_MODEL_INPUT_BEG Triggered right before the model will be read. Input array data is
undefined.
14=ev_MODEL_INPUT_END Triggered right after the model has been read. Input array data is
undefined.
15=ev_DIS_IC_BEG Triggered when a displacement initial conditions is about to start. First
entry of input array data is the current simulation mode. Second entry
is the current analysis mode. The third entry is ignored.
16=ev_DIS_IC_END Triggered after a displacement initial conditions has ended. First entry
of input array data is the current simulation mode. Second entry is the
current analysis mode. The third entry is ignored.
17=ev_VEL_IC_BEG Triggered when a velocity initial conditions is about to start. First entry
18=ev_VEL_IC_END Triggered after a velocity initial conditions has ended. First entry of
input array data is the current simulation mode. Second entry is the
19=ev_ACC_IC_BEG Triggered when an acceleration initial conditions is about to start. First
entry of input array data is the current simulation mode. Second entry
is the current analysis mode. The third entry is ignored.
20=ev_ACC_IC_END Triggered after an acceleration initial conditions has ended. First entry
184 Adams Solver
21=ev_STATICS_BEG Triggered when a static simulation is about to start. First entry of input
22=ev_STATICS_END Triggered when a static simulation has ended. First entry of input array
analysis mode. The third entry is zero (0) if the statics simulation was
successful or one (1) if the static simulation failed.
23=ev_STEADY_STATE_BEG Triggered when a steady-state simulation is about to start. First entry
24=ev_STEAD_STATE_END Triggered when a steady-state simulation has ended. First entry of

25=ev_KINEMATICS_BEG Triggered when a kinematics simulation is about to start. First entry of

26=ev_KINEMATICS_END Triggered when a kinematics simulation has ended. First entry of input
27=ev_DYNAMICS_BEG Triggered when a dynamics simulation is about to start. First entry of

28=ev_DYNAMICS_END Triggered when a dynamics simulation has ended. First entry of input
29=ev_LINEAR_BEG Triggered when a linear simulation is about to start. First entry of input
30=ev_LINEAR_END Triggered when a linear simulation has ended. First entry of input array
31=ev_QSTATICS_BEG Triggered when a quasi-statics simulation is about to start. First entry

32=ev_QSTATICS_END Triggered when a quasi-statics simulation has ended. First entry of

CBKSUB 185
33=ev_SAVE_BEG Triggered when a SAVE job is about to start. Input array data is
undefined.
34=ev_SAVE_END Triggered when a SAVE job has ended. Input array data is undefined.
35=ev_RELOAD_BEG Triggered when a RELOAD job is about to start. Input array data is
undefined.
36=ev_RELOAD_END Triggered when a RELOAD job has ended. Input array data is
undefined.
37=ev_TRAN_SIM_BEG Triggered when a transient simulation is about to start. Input array
data is undefined.
38=ev_TRAN_SIM_END Triggered when a transient simulation has ended. Input array data is
undefined.
39=ev_COMMAND Triggered when Adams Solver C++ is about to start processing a

command. First entry of input array data is an integer identifying the
command (see Table 2 below). The second entry is a 1 if the command
is requested by a CONSUB, 0 otherwise.
Simulation mode, analysis mode

Most of the events shown above provide the current simulation mode and analysis mode stored in the input
array data. The current simulation mode is the main simulation being executed as a response to a simulation
command. The value of the simulation mode is the same value obtained making calls to the GETMOD
utility subroutine or the value computed with the MODE function.
The analysis mode is a temporary numerical solution required to honor the simulation requested by the user.
For example, when Adams Solver C++ starts a dynamic simulation it first checks whether an initial conditions
is required. If the initial-conditions job is required, an ev_ITERATION_BEG event will provide “Dynamics”
and “Initial conditions” as the simulation mode and analysis mode respectively if the iteration is performed
from within the temporary initial-conditions job.
Table 1 below shows the simulation/analysis modes provided in the input array data.
Table 1 Simulation/analysis modes.

0=am_UNDEFINED Undefined.
1=am_KINEMATICS Kinematics simulation.
2=am_RESERVED Not used.
3=am_INITIAL_CONDITIONS Initial conditions.
4=am_DYNAMICS Dynamics simulation.
186 Adams Solver
Table 1 Simulation/analysis modes.

5=am_STATICS Statics simulation.
6=am_QUASI_STATICS Quasi-statics simulation.
7=am_LINEAR Linearization, eigensolution, state-matrices.
8=am_STEADY_STATE Steady-state simulation.
9=am_COMPLIANCE Compliance computation.
Table 2 Command identifiers.

1=cm_ACCGRAV
2=cm_ACTIVATE
3=cm_ARRAY
4=cm_BEAM
5=cm_BUSHING
6=cm_CONTROL
7=cm_COUPLER
8=cm_CPAPAR
9=cm_DEACTIVATE
10=cm_DEBUG
11=cm_DIFF
12=cm_ENVIRONMENT
13=cm_EQUILIBRIUM
14=cm_FIELD
15=cm_FILE
16=cm_FLEX_BODY
17=cm_FRICTION
18=cm_GCON
19=cm_GEAR
20=cm_GFORCE
21=cm_GSTIFF
22=cm_HELP
23=cm_HOTLINE
24=cm_IC
25=cm_INFO
CBKSUB 187
Table 2 Command identifiers.

26=cm_INTEGRATOR
27=cm_JOINT
28=cm_JPRIM
29=cm_KINEMATICS
30=cm_LINEAR
31=cm_LPARAM
32=cm_LSOLVER
33=cm_LTABLEPARAM
34=cm_MARKER
35=cm_MENU
36=cm_MOTION
37=cm_OUTPUT
38=cm_PART
39=cm_PREFERENCES
40=cm_RELOAD
41=cm_REQUEST
42=cm_RETURN
43=cm_SAVE
44=cm_SENSOR
45=cm_SFORCE
46=cm_SHOW
47=cm_SIMULATE
48=cm_SPLINE
49=cm_SPRINGDAMPER
50=cm_STOP
51=cm_STRING
52=cm_TIME
53=cm_VARIABLE
54=cm_VFORCE
55=cm_VTORQUE
56=cm_WSTIFF
188 Adams Solver
Tip: All integers defining events, SENSOR types, simulation/analysis modes, and command
types are defined in file slv_cbksub.inc which is included in the software distribution. File
slv_cbksub_utils.inc has usefuld routines. File slv_cbksub.h and slv_cbksub_utils.h are also
provided for C/C++ coding.
Calling sequence in dynamic simulations

This section describes a simplified CBKSUB call sequence during a dynamic simulation. The call sequence
for other simulations is similar.
When executing a dynamic simulation, Adams Solver C++ divides the time span between the current
simulation time and the final simulation time into a number of so called "output steps". The state of the
system is advanced up to the end of each output step at which a request for output generation is triggered
from within the innermost code layer. However, to reach the end of each output step, the solver may require
to perform a set of smaller "time steps" in order to reach the end of the current output step. Figure 1 and
Figure 2 depict a simplified version of the overall program flow showing the calls to the CBKSUB subroutine.
Highlights related to Figure 1 are the following. First, the block labeled "Process SIM/DYN command" stands
for the code where the input parameters of the simulation command are read. The command information is
used to determine the number of output steps required to be made by the solver. Also notice that in case an
initial conditions job is required, no details of the calling sequence to the CBKSUB are presented.
Finally, the block corresponding to the function output_step() is presented in Figure 2.
The flowchart presented in Figure 2 consists of two loops. The outer loop controls the number of "time steps"
made by the dynamic integration until an "output step" is reached. The inner loop controls the number of
corrector iterations required to advance the state of the simulation.
Figure 1 and Figure 2 are simplified versions of the calling sequence of the CBKSUB subroutine. For the sake
of clarity, several calls have been omitted.
CBKSUB 189
Figure 1 Calling sequence of CBKSUB during a dynamic simulation (1).

190 Adams Solver
Figure 2 Calling sequence of CBKSUB during a dynamic simulation (2).

CBKSUB 191
Example
Basic strategy
Let’s assume an Adams model has a set of VFORCEs defined by VFOSUB subroutines. Let’s assume the
function expression for these VFORCEs is very complex and requires several SYSFNC or SYSARY calls in
order to properly compute the magnitude of each component. For example, the x component of the forces
couold have this expression:
3
F x = K ( q 1, q 2, q 3 )v 1
where K ( q 1, q 2, q 3 ) is a non linear function and q 1, q 2, q 3 and v 1 are measurable states of the model
that can be computed with the help of SYSFNC and SYSARY calls. If the computation of K ( q 1, q 2, q 3 )
is common to all VFORCEs then it is possible to cache the value of C c = K ( q 1, q 2, q 3 ) at the
beginning of each corrector iteration and then return the value:
3
Fx = Cc v1
At every subsequent VFOSUB call. This can be done safely by creating a CBKSUB where the
ITERATION_BEG event is monitored to compute the cache value and set an internal flag ON. Both the
cache and the flag will be defined in a COMMON block which the VFOSUBs share. For all other events,
the flag is turned OFF.
Running without a CBKSUB

Listings nocallback.acf, nocallback.adm and nocallback.f (see Appendix) correspond to a simple model with
a VFOSUB. The model is a spring-mass system shown in Figure 3. A VFOSUB computes the value of
DX(16,1,1) and applies it to one of the masses. A dynamic simulation is run for 5.0 seconds.
192 Adams Solver
Figure 3 Simple model used for comparisons.
A partial listing of the message file is shown below.

command: FILE/MODEL=ttcs/nocallback, OUTPUT_PREFIX=results/nocallback
--------------------------------------------------------------------------------------
| Model Title |
|====================================================================================|
| |
| Test model without a CBKSUB |
| |
-------------------------------------------------------------------------------------
command:
command: integrator/error=1.e-04
command: sim/dyn, end=5, step=200
Begin Simulation
****** Performing Dynamic Simulation using Gstiff I3 Integrator ******

The system is modelled with INDEX-3 DAEs.
The integrator is GSTIFF, CORRECTOR = original
Integration error = 1.000000E-04
Simulation Step Function Cumulative Integration CPU

Time Size Evaluations Steps Taken Order time
___________ ___________ ___________ ___________ _________ ________
0.00000E+00 1.25000E-03 0 0 1 0.02
5.00000E-01 1.87099E-02 96 45 5 0.05
1.00000E+00 2.34734E-02 176 85 5 0.06
1.50000E+00 1.25000E-02 242 115 5 0.06
2.00000E+00 2.50000E-02 310 149 6 0.06
…
CBKSUB 193
Running with a CBKSUB

Listings yescallback.acf, yescallback.adm and yescallback.f correspond to the same model shown above.
However, this time a CBKSUB is included. The CBKSUB prints a message at every event announcing the
event, the simulation mode, the analysis mode, and the current time when available.
The CBKSUB is interested only in the ev_ITERATION_BEG event at which a FLAG is raisde and a cache
VALUE is computed to be used in the subsequent VFOSUB calls. The same dynamic simulation is run and
Figure 4 shows the plots of the results comparing the runs with and without a CBKSUB. A partial listing of
the message file when using a CBKSUB is shown below. Notice the CBKSUB prints a a message every time
an iteration begins.
command: FILE/MODEL=ttcs/yescallback, OUTPUT_PREFIX=results/yescallback
---------------------------------------------------------------------------
| Model Title
|
|==========================================================================|
| |
| Test model with a CBKSUB user-written subroutine
| |
| |
----------------------------------------------------------------------------
command:
command: integrator/error=1.e-04
command: sim/dyn, end=5, step=200
Begin Simulation
****** Performing Dynamic Simulation using Gstiff I3 Integrator ******

The system is modelled with INDEX-3 DAEs.
The integrator is GSTIFF, CORRECTOR = original
Integration error = 1.000000E-04
Event ev_ITERATION_BEG am_DYNAMICS am_INITIAL_CONDITI 0.000E+00

Event ev_ITERATION_BEG am_DYNAMICS am_DYNAMICS 0.125E-02
...
194 Adams Solver
Figure 4 Comparison of results with and without CBKSUB.
Discussion
The fundamental question concerns the quality of the results. For the particular example presented above,
the results with and without a CBKSUB will differ depending on the error tolerance set by the
INTEGRATOR statement/command. In this case, using an error tolerance of 1.0E-04 shows
indistinguisable results. If usinng a default INTEGRATION settings (error tolerance 1.0E-03) some
differences appear but below the prescribed integration error nonetheless.
In general, using the strategy presented above ought to provide correct results (errors are under the prescribed
integration error tolerance). However, the speed of convergence may be affected.
Appendix
nocallback.adm
Test model without a CBKSUB

!
!-------------------------------- SYSTEM UNITS ------------------------------
!
UNITS/
, FORCE = NEWTON
, MASS = KILOGRAM
, LENGTH = METER
, TIME = SECOND
!
!----------------------------------- PARTS ----------------------------------
!
!----------------------------------- Ground ---------------------------------
!
CBKSUB 195
PART/1
, GROUND
!
MARKER/1
, PART = 1
, QP = 0, 0.5, 0
!
MARKER/2
, PART = 1
, QP = 0, 3.5, 0
!
MARKER/6
, PART = 1
, QP = 0, 3.2, 0
, REULER = 0D, 90D, 0D
!
MARKER/8
, PART = 1
, QP = 0, 1, 0
, REULER = 180D, 90D, 180D
!
MARKER/10
, PART = 1
, QP = 0, 0.5, 0
!
MARKER/13
, PART = 1
, QP = 0, 3.5, 0
!
MARKER/17
, PART = 1
, FLOATING
!
!------------------------------------ Part ----------------------------------
!
PART/2
, MASS = 1.0
, CM = 15
, IP = 1.0, 1.0, 1.0
!
MARKER/3
, PART = 2
, QP = 0, 1.6, 0
!
MARKER/7
, PART = 2
, QP = 0, 1, 0
, REULER = 180D, 90D, 180D
!
196 Adams Solver
MARKER/9
, PART = 2
, QP = 0, 1.6, 0
!
MARKER/12
, PART = 2
, QP = 0, 1.6, 0
!
MARKER/15
, PART = 2
, QP = 0, 1.6, 0
!
! adams_view_name='ELLIPSOID_1'
GRAPHICS/7
, ELLIPSOID
, CM = 3
, XSCALE = 0.2828427124
, YSCALE = 0.2828427124
, ZSCALE = 0.2828427124
!
!------------------------------------ Part ----------------------------------
!
PART/3
, MASS = 1.0
, CM = 16
, IP = 1.0, 1.0, 1.0
!
MARKER/4
, PART = 3
, QP = 0, 2.7, 0
!
MARKER/5
, PART = 3
, QP = 0, 3.2, 0
!
MARKER/11
, PART = 3
, QP = 0, 2.7, 0
!
MARKER/14
, PART = 3
, QP = 0, 2.7, 0
!
MARKER/16
, PART = 3
, QP = 0, 2.7, 0
, REULER = 90D, 90D, 0D
!
CBKSUB 197
GRAPHICS/8
, ELLIPSOID
, CM = 4
, XSCALE = 0.2828427124
, YSCALE = 0.2828427124
, ZSCALE = 0.2828427124
!
!------------------------------ DYNAMIC GRAPHICS ----------------------------
!
GRAPHICS/1
, FORCE
, ETYPE = SFORCE
, EID = 1
, EMARKER = 9
!
GRAPHICS/2
, FORCE
, ETYPE = SFORCE
, EID = 1
, EMARKER = 10
!
GRAPHICS/3
, FORCE
, ETYPE = SFORCE
, EID = 2
, EMARKER = 11
!
GRAPHICS/4
, FORCE
, ETYPE = SFORCE
, EID = 2
, EMARKER = 12
!
GRAPHICS/5
, FORCE
, ETYPE = SFORCE
, EID = 3
, EMARKER = 13
!
GRAPHICS/6
, FORCE
, ETYPE = SFORCE
, EID = 3
, EMARKER = 14
!
GRAPHICS/9
, SPDP
, I = 9
, J = 10
, COILS = 10
, DA = 0.22
!
198 Adams Solver
GRAPHICS/11
, SPDP
, I = 11
, J = 12
, COILS = 10
, DA = 0.22
!
GRAPHICS/13
, SPDP
, I = 13
, J = 14
, COILS = 10
, DA = 0.16
!
!-------------------------------- CONSTRAINTS -------------------------------
!
JOINT/1
, TRANSLATIONAL
, I = 5
, J = 6
!
JOINT/2
, TRANSLATIONAL
, I = 7
, J = 8
!
!----------------------------------- FORCES ---------------------------------
!
SFORCE/1
, TRANSLATIONAL
, I = 9
, J = 10
, FUNCTION = - 100.0*(dm(9,10)-1.0)
, - 0.0*vr(9,10)
, + 0.0
!
SFORCE/2
, TRANSLATIONAL
, I = 11
, J = 12
, FUNCTION = - 100.0*(dm(11,12)-1.0)
, - 0.0*vr(11,12)
, + 0.0
!
SFORCE/3
, TRANSLATIONAL
, I = 13
, J = 14
, FUNCTION = - 100.0*(dm(13,14)-1.0)
, - 0.0*vr(13,14)
, + 0.0
!
! adams_view_name='SFORCE_4'
SFORCE/4
CBKSUB 199
, TRANSLATIONAL
, I = 15
, J = 1
, FUNCTION = 4.0
!
! adams_view_name='VFORCE_1'
VFORCE/1
, I = 16
, J = 17
, RM = 16
, FUNCTION = USER(1)
!
!----------------------------- ANALYSIS SETTINGS ----------------------------
!
RESULTS/
, XRF
!
END
nocallback.acf
nocallback
nocallback
integrator/error=1.e-04
sim/dyn, end=5, step=200
stop
nocallback.f
C----------------------------------------------------------------------
C Test model without a CBKSUB
C----------------------------------------------------------------------
C
C----------------------------------------------------------------------
C VFOSUB
C----------------------------------------------------------------------
SUBROUTINE VFOSUB(id, time, par, npar, dflag, iflag, result)
C
C Vforce function expression
IMPLICIT NONE
INTEGER id
DOUBLE PRECISION par(*)
INTEGER npar
LOGICAL dflag
INTEGER iflag
DOUBLE PRECISION result(3)
C
C Local variable and parameter definitions
LOGICAL errflg
CHARACTER*80 mesage
INTEGER IPAR(3)
INTEGER NV
DOUBLE PRECISION DATINF(6)
INTEGER FLAG
200 Adams Solver

C
C Program starts
ERRFLG = .FALSE.
IPAR(1) = 16
IPAR(2) = 1
IPAR(3) = 1
mesage='Error while reading from SYSARY in VFOSUB'
CALL SYSARY('DISP', IPAR, 3, DATINF, NV, errflg)
IF (errflg) CALL STOPERR(101, mesage)
result(1) = -DATINF(2)*30
result(2) = 0.0D0
result(3) = 0.0D0
C
RETURN
END
C
C----------------------------------------------------------------------
C STOPERR
C----------------------------------------------------------------------
SUBROUTINE STOPERR(id, mesage)
C
C Routine to call ADAMS Error Message routine and end program simulation
LOGICAL errflg
CHARACTER*(*) mesage
CHARACTER*4 endflg
INTEGER id
errflg=.TRUE.
endflg='STOP'
CALL ERRMES(errflg, mesage, id, endflg)
RETURN
END
yescallback.adm
Test model with a CBKSUB user-written subroutine

!
!-------------------------------- SYSTEM UNITS ------------------------------
---
!
UNITS/
, FORCE = NEWTON
, MASS = KILOGRAM
, LENGTH = METER
, TIME = SECOND
!
!----------------------------------- PARTS ----------------------------------
---
!
!----------------------------------- Ground ---------------------------------
---
!
PART/1
, GROUND
!
MARKER/1
CBKSUB 201
, PART = 1
, QP = 0, 0.5, 0
!
MARKER/2
, PART = 1
, QP = 0, 3.5, 0
!
MARKER/6
, PART = 1
, QP = 0, 3.2, 0
!
MARKER/8
, PART = 1
, QP = 0, 1, 0
, REULER = 180D, 90D, 180D
!
MARKER/10
, PART = 1
, QP = 0, 0.5, 0
!
MARKER/13
, PART = 1
, QP = 0, 3.5, 0
!
MARKER/17
, PART = 1
, FLOATING
!
!------------------------------------ Part ----------------------------------
---
!
PART/2
, MASS = 1.0
, CM = 15
, IP = 1.0, 1.0, 1.0
!
MARKER/3
, PART = 2
, QP = 0, 1.6, 0
!
MARKER/7
, PART = 2
, QP = 0, 1, 0
, REULER = 180D, 90D, 180D
!
MARKER/9
, PART = 2
, QP = 0, 1.6, 0
!
202 Adams Solver
MARKER/12
, PART = 2
, QP = 0, 1.6, 0
!
MARKER/15
, PART = 2
, QP = 0, 1.6, 0
!
GRAPHICS/7
, ELLIPSOID
, CM = 3
, XSCALE = 0.2828427124
, YSCALE = 0.2828427124
, ZSCALE = 0.2828427124
!
!------------------------------------ Part ----------------------------------
---
!
PART/3
, MASS = 1.0
, CM = 16
, IP = 1.0, 1.0, 1.0
!
MARKER/4
, PART = 3
, QP = 0, 2.7, 0
!
MARKER/5
, PART = 3
, QP = 0, 3.2, 0
!
MARKER/11
, PART = 3
, QP = 0, 2.7, 0
!
MARKER/14
, PART = 3
, QP = 0, 2.7, 0
!
MARKER/16
, PART = 3
, QP = 0, 2.7, 0
, REULER = 90D, 90D, 0D
!
GRAPHICS/8
, ELLIPSOID
, CM = 4
, XSCALE = 0.2828427124
CBKSUB 203
, YSCALE = 0.2828427124
, ZSCALE = 0.2828427124
!
!------------------------------ DYNAMIC GRAPHICS ----------------------------
---
!
GRAPHICS/1
, FORCE
, ETYPE = SFORCE
, EID = 1
, EMARKER = 9
!
GRAPHICS/2
, FORCE
, ETYPE = SFORCE
, EID = 1
, EMARKER = 10
!
GRAPHICS/3
, FORCE
, ETYPE = SFORCE
, EID = 2
, EMARKER = 11
!
GRAPHICS/4
, FORCE
, ETYPE = SFORCE
, EID = 2
, EMARKER = 12
!
GRAPHICS/5
, FORCE
, ETYPE = SFORCE
, EID = 3
, EMARKER = 13
!
GRAPHICS/6
, FORCE
, ETYPE = SFORCE
, EID = 3
, EMARKER = 14
!
GRAPHICS/9
, SPDP
, I = 9
, J = 10
, COILS = 10
, DA = 0.22
!
GRAPHICS/11
, SPDP
, I = 11
204 Adams Solver
, J = 12
, COILS = 10
, DA = 0.22
!
GRAPHICS/13
, SPDP
, I = 13
, J = 14
, COILS = 10
, DA = 0.16
!
!-------------------------------- CONSTRAINTS -------------------------------
!
JOINT/1
, TRANSLATIONAL
, I = 5
, J = 6
!
JOINT/2
, TRANSLATIONAL
, I = 7
, J = 8
!
!----------------------------------- FORCES ---------------------------------
!
SFORCE/1
, TRANSLATIONAL
, I = 9
, J = 10
, FUNCTION = - 100.0*(dm(9,10)-1.0)
, - 0.0*vr(9,10)
, + 0.0
!
SFORCE/2
, TRANSLATIONAL
, I = 11
, J = 12
, FUNCTION = - 100.0*(dm(11,12)-1.0)
, - 0.0*vr(11,12)
, + 0.0
!
SFORCE/3
, TRANSLATIONAL
, I = 13
, J = 14
, FUNCTION = - 100.0*(dm(13,14)-1.0)
, - 0.0*vr(13,14)
, + 0.0
!
! adams_view_name='SFORCE_4'
SFORCE/4
, TRANSLATIONAL
, I = 15
, J = 1
CBKSUB 205
, FUNCTION = 4.0
!
! adams_view_name='VFORCE_1'
VFORCE/1
, I = 16
, J = 17
, RM = 16
, FUNCTION = USER(1)
!
!------------------------------ DATA STRUCTURES -----------------------------
!
CBKSUB/1
, PRIORITY = 1
, FUNCTION = USER(0)\
, ROUTINE = yescallback::
!
!----------------------------- ANALYSIS SETTINGS ----------------------------
!
RESULTS/
, XRF
!
END
yescallback.acf
yescallback
yescallback
integrator/error=1.e-04
sim/dyn, end=5, step=200
stop
yescallback.f
C----------------------------------------------------------------------
C Test model with a CBKSUB user-written subroutine
C----------------------------------------------------------------------
include 'slv_cbksub_util.inc'
C
C----------------------------------------------------------------------
C VFOSUB
C----------------------------------------------------------------------
SUBROUTINE VFOSUB(id, time, par, npar, dflag, iflag, result)
C
C Vforce function expression
IMPLICIT NONE
INTEGER id
DOUBLE PRECISION par(*)
INTEGER npar
LOGICAL dflag
INTEGER iflag
DOUBLE PRECISION result(3)
C
206 Adams Solver
LOGICAL errflg
CHARACTER*80 mesage
INTEGER IPAR(3)
INTEGER NV
INTEGER FLAG
C
C Common data
C VALUE is the cache computed by the CBKSUB soubroutine
C FLAG=0 means no cache.
C FLAG=1 means cache is available.
COMMON/ FORCES/ VALUE, FLAG
C
C If the solver is numerically differencing or no cache is available,
C return the value computed using SYSARY.
C Do not change the value of FLAG because this may be a call made by
C the evaluator of output results.
IF(dflag.eq..TRUE..OR.FLAG.EQ.0) THEN
errflg = .FALSE.
IPAR(1) = 16
IPAR(2) = 1
IPAR(3) = 1
mesage='Error while reading from SYSARY in VFOSUB'
CALL SYSARY('DISP', IPAR, 3, DATINF, NV, errflg)
IF (errflg) CALL STOPERR(101, mesage)
result(1) = -DATINF(2)*30
result(2) = 0.0D0
result(3) = 0.0D0
return
END IF
C
C Cached VALUE is available
result(1) = VALUE
result(2) = 0.0D0
result(3) = 0.0D0
C
RETURN
END
C
C----------------------------------------------------------------------
C STOPERR
C----------------------------------------------------------------------
SUBROUTINE STOPERR(id, mesage)
C
C Routine to call ADAMS Error Message routine and end program simulation
LOGICAL errflg
CHARACTER*(*) mesage
CHARACTER*4 endflg
INTEGER id
errflg=.TRUE.
endflg='STOP'
CALL ERRMES(errflg, mesage, id, endflg)
RETURN
END
C
C----------------------------------------------------------------------
C CBKSUB
C----------------------------------------------------------------------
SUBROUTINE CBKSUB(time, event, data)
CBKSUB 207
C
C
C Input parameters
INTEGER event, data(3)
C
C Event and mode names
CHARACTER*16 EVTNAME
CHARACTER*18 ANLYMOD
C
C Used in the SYSARY call
INTEGER IPAR(3)
INTEGER NV
LOGICAL ERRFLG
INTEGER FLAG
C
C Common data
C VALUE is the cache computed by the CBKSUB soubroutine
C FLAG = 0 means no cache.
C FLAG = 1 means cache is available.
COMMON/ FORCES/ VALUE, FLAG
C
C Set the flag to 'no cache available'
FLAG = 0
C
C Compute cache if this is an ev_ITERATION_BEG event
IF( event.eq.ev_ITERATION_BEG ) THEN
C
C This is a ev_ITERATION_BEG event.
WRITE(MESSAGE,'(A,A,A,A,A,A,e10.3)') 'Event ', EVTNAME(event),
* ' ', ANLYMOD(data(1)), ' ', ANLYMOD(data(2)), time
C
C Call SYSARY and update the cache
FLAG = 1
IPAR(1) = 16
IPAR(2) = 1
IPAR(3) = 1
CALL SYSARY('DISP', IPAR, 3, DATINF, NV, ERRFLG)
VALUE = -DATINF(2)*30
ENDIF
C
RETURN
END
208 Adams Solver
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.
case; Cffsub for example. Doing this ensures that Adams Solver correctly distinguishes a C
Use
Calling Sequence
SUBROUTINE CFFSUB (id, time, par, npar, loci, locj, x, xdot, nforce, area, dflag, iflag, result)
Input Arguments
area A double-precision variable that specifies the value of the contact area.
dflag A logical variable that Adams Solver sets to true when it calls CFFSUB to evaluate the partial
derivatives of the specified functions. Otherwise, Adams Solver sets the dflag argument to
false.
id An integer variable that provides the identifier of the CONTACT statement requesting
information from CFFSUB. From the identifier, Adams Solver automatically recognizes
other information (such as the par argument) that is available in the corresponding statement.
CFFSUB 209
iflag An integer variable that Adams Solver sets to indicate why the routine is being called:
Value Description
Adams Solver sets iflag to 3 when it needs the functional dependency of the user-defined
variable. The functional dependencies are set with the same calls to the SYSARY and
SYSFNC utility subroutines that are made to compute the value of the user-defined variable.
If iflag is 0, Adams Solver computes the value of the user-written variable.
When your user-defined subroutine has static data that needs to be saved and restored to
support the Adams Solver commands Save and Reload, then call the serialization functions
for your data when iflag is set to 7, and the un-serialization functions when iflag is set to 9.
logical variable. In this case you declare your dependencies when Adams Solver sets
iflag to true, and compute the subroutine's value when Adams Solver sets iflag to
false.
loci A double-precision array that specifies the vector from the reference marker of the
CONTACT I Geometry (IGEOM) to the contact point on IGEOM. Expressed in the
coordinate system of the reference marker of IGEOM.
Note: In Flex Body Contact, loci is a node location on the Flex Body. There can be
multiple nodes in each incident. The subroutine will be called for each node.
locj A double-precision array that specifies the vector from the reference marker of the
CONTACT J Geometry (JGEOM) to the contact point on JGEOM. Expressed in the
coordinate system of the reference marker of JGEOM.
Note: In Flex Body Contact, locj is a node location on the Flex Body. There can be
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.
210 Adams Solver
time A double-precision variable through which Adams Solver conveys the current simulation
time.
x A double-precision array that specifies the values of the contact deformation.
(1) - Translational deformation since the beginning of contact along the x-axis of the contact
I incident marker.
(2) - Translational deformation since the beginning of contact along the y-axis of the contact
I incident marker.
(3) - Rotational deformation since the beginning of contact about the z-axis of the contact I
incident marker.
xdot A double-precision array that specifies the slip velocities at the contact point.
(1) - Translational slip velocity along the x-axis of the contact

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

I incident marker.
(3) - Relative angular velocity of contacting surfaces about the

z-axis of the contact I incident marker.
Note: The contact incident I-marker is always oriented such that the x-axis is in the
direction of slip. This means that the marker orientation is changing as the
direction of slip changes. Therefore, the velocity along the y-axis (which is
XDOT(2)) will always be zero.
Output Argument
result A double-precision array that returns the three components of the friction force.
(1) - Translational force along the x-axis of the contact I incident marker.
(2) - Translational force along the y-axis of the contact I incident marker.
(3) - Rotational torque about the z-axis of the contact I incident marker.
Extended Definition
The default friction model in the CONTACT statement can only model simple dynamic friction. This
means that to produce a friction force, contacting bodies must be sliding at the point of contact. Effects such
as static friction and frictional torque are not modeled.
If you require another force model, you can use a CFFSUB. If the algorithms use or consist of already-existing
FORTRAN-77 subroutines, CFFSUB can be made to call them. You can call utility subroutines, such as
CFFSUB 211
AKISPL, CUBSPL, SYSARY, and SYSFNC from CFFSUB, to obtain information about system variables,
user-defined variables, and splines.
The SYSARY and SYSFNC utility subroutines set functional dependencies when the CFFSUB argument
iflag is not zero. To compute solutions efficiently, Adams Solver must know the other variables on which each
user-defined variable depends. Adams Solver determines these functional dependencies at the beginning of
the simulation by calling CFFSUB with the argument iflag set to not zero. Adams Solver does this once for
each CONTACT statement with a FRICTION_FUNCTION=USER() argument.
During each call to CFFSUB, Adams Solver records which calls you make to SYSARY and SYSFNC. Adams
Solver assumes that the CONTACT components depend on those Adams Solver variables that are accessed
through SYSARY and SYSFNC.
Using the DFLAG Variable

The use of the DFLAG variable is optional. Its purpose is to simply let you know that CFFSUB is being called
to evaluate a partial derivative. One of the states on which the CFFSUB depends has been perturbed very
slightly. In many situations, it is likely that major calculations in the CFFSUB are insensitive to small changes
in state, and therefore, need not be recalculated. In such situations, you can structure the CFFSUB not to
redo these calculations.
Tip: If the SYSARY or SYSFNC subroutines are called to access angular displacements, the values
returned by CFFSUB may contain discontinuities. Discontinuities occur if there is an Euler
singularity. To avoid the Euler singularity (and thus the discontinuities), use the RCNVRT
utility subroutine to convert the rotational angles from Euler angles to some other coordinate
system that does not encounter a singularity.
 If the calculations always use the same SYSARY and SYSFNC calls through the whole
simulation, and you have no initialization to do, you do not need to check the flag
argument at all. You can just call SYSARY and/or SYSFNC, compute the user-
defined variable value, and return to Adams Solver (FORTRAN)
Caution: When the iflag argument is not zero:
 You must make all the calls to SYSARY and SYSFNC as they are made to compute
the component values of the CONTACT statement. This ensures that Adams Solver
has the proper functional dependencies. In general, failure to account for
dependencies in the CONTACT statement components can make it difficult for
Adams Solver to converge to a solution and/or can force Adams Solver to take small
integration steps, potentially causing large increases in execution time.
 SYSARY and SYSFNC return zero values for system and user-defined variables.
When you use Adams Solver, computations that divide by these values result in fatal
errors. You should check for nonzero values, or ensure the iflag argument is set to
zero, before dividing by these values.
212 Adams Solver
Fortran - Prototype
A sample structure for CFFSUB is shown next. The comments explain how the subroutine works.
SUBROUTINE CFFSUB(ID, TIME, PAR, NPAR, LOCI, LOCJ, X, XDOT,
& NFORCE, AREA, DFLAG, IFLAG, FORCE)
C
IMPLICIT NONE
INTEGER ID
INTEGER NPAR
DOUBLE PRECISION X(3)
DOUBLE PRECISION XDOT(3)
DOUBLE PRECISION NFORCE
LOGICAL DFLAG
INTEGER IFLAG
C
C Input parameters
C
C ID Identifier of calling CONTACT statement
C TIME Current time
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 AREA area of contact
C
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
DOUBLE PRECISION US
DOUBLE PRECISION UD
DOUBLE PRECISION VS
DOUBLE PRECISION VD
DOUBLE PRECISION H0, H1, X0, X1, TEMP1, TEMP2
LOGICAL ERRFLG
C
CFFSUB 213

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;
214 Adams Solver
int NPAR;
const double* PAR;
};
CNFSUB 215
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.
case; Cnfsub for example. Doing this ensures that Adams Solver correctly distinguishes a C
Use
Calling Sequence
SUBROUTINE CNFSUB (id, time, par, npar, loci, ni, locj, nj, gap, gapdot, gapdotdot, area, dflag, iflag,
result)
Input Arguments
area A double-precision variable that specifies the value of the contact area.
dflag A logical variable that Adams Solver sets to true when it calls CNFSUB to evaluate the
partial derivatives of the specified functions. Otherwise, Adams Solver sets the dflag
argument to false.
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 automatically recognizes
other information (such as the par argument) that is available in the corresponding
statement.
216 Adams Solver
Value Description
SYSFNC utility subroutines that are made to compute the value of the user-defined
variable. If iflag is 0, Adams Solver computes the value of the user-written variable.
support the Adams Solver commands Save and Reload, then call the serialization
functions for your data when iflag is set to 7, and the un-serialization functions when iflag
is set to 9.
Note: In simple subroutines where serializing data is not needed, you can declare iflag
as a logical variable. In this case you declare your dependencies when Adams
Solver sets iflag to true, and compute the subroutine's value when Adams
Solver sets iflag to false.
loci A double-precision array that specifies the vector from the reference marker of the
CONTACT I Geometry (IGEOM) to the contact point on IGEOM. Expressed in the
coordinate system of the reference marker of IGEOM.
Note: In Flex Body Contact, loci is a node location on the Flex Body. There can be
locj A double-precision array that specifies the vector from the reference marker of the
CONTACT J Geometry (JGEOM) to the contact point on JGEOM. Expressed in the
coordinate system of the reference marker of JGEOM.
Note: In Flex Body Contact, locj is a node location on the Flex Body. There can be
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.
CNFSUB 217
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.
Output Argument
result A double-precision array that returns the value of the normal force.
Only the first value in the array is used by Adams Solver.
Extended Definition
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 not zero. To compute solutions efficiently, Adams Solver must know the other variables on which each
user-defined variable depends. Adams Solver determines these functional dependencies at the beginning of
the simulation by calling CNFSUB with the argument iflag set to not zero. 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

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.
218 Adams Solver
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 RCNVRT
utility subroutine to convert the rotational angles from Euler angles to some other coordinate
system that does not encounter a singularity. If the calculations always use the same SYSARY
and SYSFNC calls through the whole simulation, and you have no initialization to do, you
do not need to check the 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 not zero
 You must make all the calls to SYSARY and SYSFNC as they are made to compute
the component values of the CONTACT statement. This ensures that Adams Solver
has the proper functional dependencies. In general, failure to account for
dependencies in the CONTACT statement components can make it difficult for
Adams Solver to converge to a solution and/or can force Adams Solver (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
zero, before dividing by these values.
FORTRAN - Prototype
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, FORCE)
C
C
IMPLICIT NONE
INTEGER ID
INTEGER NPAR
DOUBLE PRECISION NI(3)
DOUBLE PRECISION NJ(3)
DOUBLE PRECISION GAP
DOUBLE PRECISION GAPDOT
DOUBLE PRECISION GAPDOTDOT
LOGICAL DFLAG
INTEGER IFLAG
C
CNFSUB 219
C Input parameters
C
C ID Identifier of calling CONTACT statement
C TIME Current time
C LOCI contact point location on I in I coordinates
C NI contact normal on I in I coordinates
C LOCJ 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
C AREA contact area
C
C
C FORCE Array (dimension 3) of computed normal force
C FORCE(1) Normal force
C FORCE(2) not used
C FORCE(3) not used
C
C ---Local variable and parameter definitions ------
C ...
C
C
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
C Check SYSFNC call through ERRMES utility routine
C
CALL ERRMES (...)
C
C Repeat for all required SYSFNC or SYSARY calls
C
...
C
IF (IFLAG) THEN
C
C - Subroutine initialization -------------
C
...
C
ENDIF
C
C - Evaluate Normal Force components -------------
C
C Your algorithms
C
...
C
C Assign values to the FORCE array
220 Adams Solver
C
FORCE(1) = ...
FORCE(2) = 0
FORCE(3) = 0
C
RETURN
END
C Style - Prototype
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;
const double* PAR;
};
CONSUB 221
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.
case; Consub for example. Doing this ensures that Adams Solver correctly distinguishes a C
Use
Corresponding Command
CONTROL/ [FUNCTION=USER(r1[,...,r30])[/]]
Calling Sequence
SUBROUTINE CONSUB (par, npar)
Input Arguments
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.
Extended Definition
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.
222 Adams Solver
Caution: When program control passes to CONSUB, automatic generation of output stops. If you
want to create output, call the DATOUT utility subroutine.
FORTRAN - Prototype
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
C Style - Prototype
typedef void adams_c_CONSUB(const struct sAdamsControl* con);
/*
* CONTROL
*/
struct sAdamsControl
{
int NPAR;
const double* PAR;
};
Cautions
Calls to the utility functions SYSFNC and SYSARY are permitted from within a CONSUB. As long as the
model is at a consistent state, calls to SYSFNC/SYSARY will return consistent values (correct values).
At the end of every dynamic, static, quasi-static, settle and linear simulations Adams Solver will set the model
at a consistent state by solving the corresponding governing equations. After an initial condition
displacements, all displacements are at a consistent state. After an initial condition velocities, all velocities and
CONSUB 223
displacements are at a consistent state. After an initial conditions acceleration, all forces and reaction forces
(due to the constraints in the model) will be at a consistent state.
However, you may issue simulation commands that can set the model temporarily at an inconsistent state.
For example, the following commands modify the model topology and immediately make a call to a
CONSUB:
SIM/DYN, END=1, STEPS=10
MARKER/99, QP=1,3.3,3.9
DEACTIVATE/JOINT, ID=8
CONTROL/FUNCTION=USER(55,5,99)
After the dynamic simulation is completed, the model is at a consistent state. The MARKER command and
the DEACTIVATE will set the model temporarily at an inconsistent state; the model is being changed. The
next simulation command, if any, will set the model back to a consistent state. Nevertheless, if the CONSUB
above makes calls to SYSFNC and SYSARY before a simulation command, then the returned values are in
general not consistent (incorrect). If the CONSUB makes calls to SYSFNC and SYSARY, users should
explicitly issue a simulation command before making the calls to SYSFNC/SYSARY. For example:
SIM/DYN, END=1, STEPS=10
MARKER/99, QP=1,3.3,3.9
DEACTIVATE/JOINT, ID=8
SIM/INITIAL_CONDITIONS
CONTROL/FUNCTION=USER(55,5,99)
The initial conditions command will set the model at a consistent state. The initial conditions command is
not required if an explicit simulation command follows before making the calls to SYSFNC/SYSARY within
the consub subroutine.
Examples
For an example of this subroutine, see consub.f.
224 Adams Solver
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.
case; Cousub for example. Doing this ensures that Adams Solver correctly distinguishes a C
Use
Calling Sequence
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)
Input Arguments
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.
COUSUB, COUXX, COUXX2 225
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.
Value Description
When iflag is 0 Adams Solver calling to compute the value of the user-written variable. When
iflag is set to 1 or 3 do any initializations that your subroutine requires.
logical variable. In this case you can do any initializations when Adams Solver sets
false.
Output Arguments
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 ⁄ ∂disp ( i )
dfda2 A double-precision array of dimensions ndisp that contains the second partials derivatives of
phi with respect to disp.
2
Therefore, dfda2 ( i ) = ( α φ ) ⁄ ( ( ∂disp ( i ) ) ∂disp ( i ) )
226 Adams Solver
Extended Definition
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.
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.
FORTRAN - Prototype
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
INTEGER NPAR
DOUBLE PRECISION DISP(*)
INTEGER NDISP
INTEGER IFLAG
C
C Outputs:
C
DOUBLE PRECISION DFDA(*)
C
C Local Variables:
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) = ...
DFDA(2) = ...
...
C
ENDIF
C
C
228 Adams Solver
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 Local Variables:
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 second partial
C
derivatives of the coupler constraint
C+----------------------------------------------------*
C
...
...
DFDA2(1) = ...
DFDA2(2) = ...
...
...
C
ENDIF
C
C
RETURN
END
C Style - Prototype
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;
const double* PAR;
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.
Now assume that the variables s and a are related by the following equation:
s = 10 * Cos (a)
Figure 1. Simple Mechanical System Consisting of a Coupler
230 Adams Solver
The dataset for this model is:

!Part/1, Ground
Marker/11
Marker/12
Part/2, Mass=10, Ip=10,10,10, Cm=21
Marker/21, Qp=0,-5,0, REU=90d,90d,0
Marker/22, REU=90d,0,0
Part/3, Mass=25, Ip=75,75,150, Cm=31
Marker/31, Qp=10,20,0, REU=90d,90d,0
Marker/32
Joint/1, Revolute, I=22, J=11
Joint/2, Translational, I=32, J=12
Motion/1, Joint=2, Function = 10*Time
Coupler/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
INTEGER IFLAG
C
C Outputs:
C
DOUBLE PRECISION PHI
C
C Local Variables:
C
DOUBLE PRECISION LENGTH, S, ALPHA
C
C+----------------------------------------------------*
C
Executable Code
C+----------------------------------------------------*
C
IF (IFLAG) THEN
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
232 Adams Solver
INTEGER IFLAG
C
C Outputs:
C
DOUBLE PRECISION DFDA(*)
C
C Local Variables:
C
DOUBLE PRECISION LENGTH, S, ALPHA
C
C+----------------------------------------------------*
C
Executable Code
C+----------------------------------------------------*C
IF (IFLAG) THEN
C
C
there are no variables to initialize in this example
C
ELSE
C
C+----------------------------------------------------*
C
Evaluation pass: Define the partial derivatives
C
of the coupler constraint
C+----------------------------------------------------*
C
LENGTH = PAR(1)
ALPHA = DISP(1)
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
INTEGER IFLAG
C
C Outputs:
C
DOUBLE PRECISION DFDA2(NDISP)

C
C Local Variables:
C
DOUBLE PRECISION LENGTH, ALPHA, S
C
C+----------------------------------------------------*
C
Executable Code
C+----------------------------------------------------*
C
IF (IFLAG) THEN
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
LENGTH = PAR(1)
ALPHA = DISP(1)
S = DISP(2)
DFDA2(1) = LENGTH * COS(ALPHA)
DFDA2(2) = 0.0
C
ENDIF
C
RETURN
END
234 Adams Solver
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.
case; Cursub for example. Doing this ensures that Adams Solver correctly distinguishes a C
Use
Corresponding Statement
Calling Sequence
SUBROUTINE CURSUB (id, par, npar, alpha, iord, iflag, values)
CURSUB 235
Input Arguments
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.
Value Description
false.
236 Adams Solver
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 alpha)
two (return second derivatives with respect to alpha).

npar An integer variable that indicates the number of constants specified in the 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.
Output Arguments
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:
iord: values (1): values (2): values (3):
0 x( α) y(α) z( α)
1
d x(α ) d y(α ) d z(α)

dα dα dα
2 2 2
d x( α) d y( α) d z( α)
2 2 2
dα dα dα
CURSUB 237
Extended Definition
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.
Caution: Define the curve only as a function of α. Don't make calls to the SYSARY and SYSFNC
utility subroutines to access other system variables.
FORTRAN - Prototype
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
INTEGER ID
INTEGER NPAR
DOUBLE PRECISION ALPHA
INTEGER IORD
INTEGER 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
238 Adams Solver
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 Your algorithm
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 Your algorithm
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
C Style - Prototype
typedef void adams_c_CURSUB(const struct sAdamsCurve* crv, double
ALPHA, int IORD, int IFLAG, double* VALUES );
/*
* CURVE
*/
struct sAdamsCurve
{
int ID;
int NPAR;
const double* PAR;
int CLOSED;
int ORDER;
double MINPAR;
double MAXPAR;
CURSUB 239
};
Examples
For an example of this subroutine, see cursub.f
240 Adams Solver
DIFSUB
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.
case; Difsub for example. Doing this ensures that Adams Solver correctly distinguishes a C
Use
Calling Sequence
SUBROUTINE DIFSUB (id, time, par, npar, dflag, iflag, value)
DIFSUB 241
Input Arguments
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.
Value Description
variable. The functional dependencies are set with the same calls to the SYSARY and SYSFNC
utility subroutines that are made to compute the value of the user-defined variable. If iflag is
0, Adams Solver computes the value of the user-written variable.
false.
parenthetical list. The primary purpose of npar is to provide the DIFSUB evaluation
par A double-precision array of constants taken in order from the USER parenthetical list of the
DIFF statement.
time.
242 Adams Solver
Output Argument
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.
Extended Definition
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.
 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 not zero. 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 not zero. 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.
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.
DIFSUB 243
Caution:  When the iflag argument is not zero, 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 not zero, 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 zero, before dividing by these values.
FORTRAN - Prototype
A sample structure for DIFSUB is shown next. The comments explain how the subroutine works.
SUBROUTINE DIFSUB ( ID, TIME, PAR, NPAR, DFLAG,
& IFLAG, VALUE )
C
C === Type and dimension statements ==================
C
C
INTEGER ID
INTEGER NPAR
LOGICAL DFLAG
INTEGER IFLAG
C
C ID Identifier of calling DIFF statement
C TIME Current time
C VALUE Computed value of DIFF returned to ADAMS
C
C - Local variables and parameters definitions ---
C
...
C
C === Executable code ================================
C
C
...
C
244 Adams Solver

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
C
C - Evaluate differential equation ---------
C
C Your algorithms
C
...
C
C Assign a value to the variable VALUE
C
VALUE = ...
C
RETURN
END
C Style - Prototype
typedef void adams_c_DIFSUB(const struct sAdamsDiff* diff, double
TIME, int DFLAG, int IFLAG, double* RESULT);
struct sAdamsDiff
{
int ID;
int NPAR;
const double* PAR;
int STATIC_HOLD;
int IMPLICIT;
double IC_R1;
double IC_R2;
};
Examples
For an example of this subroutine, see difsub.f
DIFSUB 245
246 Adams Solver
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.
case; Dmpsub for example. Doing this ensures that Adams Solver correctly distinguishes a C
Use
DMPSUB 247
Calling Sequence
SUBROUTINE DMPSUB (id, time, par, npar, freq, nmode, h, cratios)
Input Arguments
id An integer variable that provides the identifier of the FLEX_BODY statement requesting
information from the DMPSUB. From the identifier, Adams Solver automatically knows
other information (such as the par argument) available in the corresponding statement.
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.
parenthetical list. The primary purpose of npar is to provide the DMPSUB evaluation
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.
Output Argument
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
248 Adams Solver
C Style - Prototype
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;
const double* PAR;
};
FEloadsub 249
FEloadsub
The FEloadsub evaluation subroutine computes a set of three distributed forces per unit length and three
distributed torques per unit length acting on a 3D beam modelled with a FE_PART. The six distributed loads
per unit length are named Fx, Fy, Fz, Tx, Ty and Tz. These values are relative to the RM Marker in the
FE_LOAD statement. The Fx, Fy, Fz, Tx, Ty and Tz components act relative to the optional RM Marker. If
no RM Marker is specified, they are relative to the GROUND origin.
For the case of 2D beam modelled with a FE_PART, the FEloadsub only supports the Fx and Fy distributed
force per unit length. Here Fx and Fy are the distributed force per length acting along the XY axes for
2DBEAMXY type. For the case of 2DBEAMYZ, Fx and Fy correspond to the loading along the Y and Z axes
respectively. For the case of 2DBEAMZX, Fx and Fy correspond to the loading along the Z and X axes
respectively.
You only need to use a FEloadsub if you don't want to use function expressions in the FE_LOAD statement.
You may use a FEloadsub when the functions describing the applied distributed loads are too complex to
enter as expressions in a FE_LOAD statement.
Specifications
1. Users need to define only one FE_LOAD per FE_PART, regardless of the element subdivision.
Changing the number of elements in the FE_PART usually requires no changes in the corresponding
FE_LOAD statement. The FE_LOAD expressions (or the FEloadsub code) treat the FE_PART as a
single object and apply the load across element boundaries regardless of the element subdivision.
Both FE_PART and FE_LOAD are supported by the Adams/Solver C++ only.
2. The FEloadsub subroutine can only be written in C/C++ code. A FORTRAN version is not
supported. To compile a FEloadsub subroutine, follow the standard process used to compile any
other supported user-written subroutine.
Important new conventions

To improve the performance of this new type of user-written subroutine, important new conventions were
designed and implemented:
1. No numerical perturbation is performed in order to compute the required partial derivatives that
Adams Solver C++ needs to carry the simulation. In that regard, the user must provide the partial
derivatives when DFLAG=1. To facilitate this task, Adams Solver C++ will call the subroutine passing
a data structure named sBeam that can be filled with the corresponding partial derivatives.
2. When IFLAG=1, users must make a call to a new utility function c_sysfn2() for each of the measures
needed to compute the distributed loads. Function c_sysfn2() was implemented to register the
dependencies.
a. Each call to c_sysfn2() will register a measure and it will return an index for the registered
measure.
b. No calls to c_sysfn2() are permitted when IFLAG is different than 1. Adams Solver C++ will
compute the values of the registered measures and pass them to your subroutine inside a data
structure (see Calling Sequence below).
250 Adams Solver
c. No calls to c_sysfnc() nor c_sysary() are permitted.

For example, assume your distributed loads depend on the following three measures: DX(2), S and
SD(1). Assume also you make the following calls in this order:
// Make these calls only when IFLAG=1 (initialization and measure

registration)
c_sysfn2( sBeam, "DX", PAR, NPAR, &index, &ERRFLG);
…
c_sysfn2( sBeam, "S", PAR, NPAR, &index, &ERRFLG);
…
c_sysfn2( sBeam, "SD", PAR, NPAR, &index, &ERRFLG);
The index for the measures DX, S and SD will be 0, 1 and 2 respectively, Adams Solver C++ keeps
an internal counter. The data structure sBeam is passed to you when Adams Solver C++ calls your
subroutine.
3. When IFLAG=3, users must return a map of dependencies for each component. For example, assume
your Fx and Fy components have the following expressions:
Therefore, when IFLAG=3, you must make the following assignments:

// Make these calls only when IFLAG=3 (mapping of Jacobian
dependencies)
sBeam->depend_Fx[0] = 1;
sBeam->depend_Fx[1] = 1;
…
sBeam->depend_Fy[0] = 1;
sBeam->depend_Fy[2] = 1;
…
These settings tell Adams Solver C++ that Fx depends only on the DX measure (index 0) and on the
S measure (index 1); similarly this code tells that Fy depends only on the DX measure (index 0) and
on the SD measure (index 2).
4. When IFLAG=0, users must return the computed values of the six distributed values Fx, Fy, Fz, Tx,
Ty and Tz in the RESULT array. RESULT[0] corresponds to Fx, RESULT[1] corresponds to Fy and
so on. Adams Solver C++ will pass the values of all registered measures already computed for you (no
need to make calls to c_sysfn2() anymore). The values of the computed measures are passed in the
array sBeam->mea_values. For the example above you would do:
// Make this calls only when IFLAG=0 (evaluation)
RESULT[0] = sBeam->mea_values[0]*sBeam->mea_values[1];
RESULT[1] = sBeam->mea_values[0]*sBeam-
>mea_values[0]*sin(PI*sBeam->mea_values[2]);
…
5. When DFLAG=1, users must return the partial derivatives of each distributed load. Continuing the
example above, the corresponding partial derivatives are:
FEloadsub 251
Therefore, the user must code the following:
// Make this calls only when DFLAG=1

sBeam->depend_Fx[0] = sBeam->mea_values[1];
sBeam->depend_Fx[1] = sBeam->mea_values[0];
…
sBeam->depend_Fy[0] = 2.*sBeam->mea_values[0]*sin(PI*sBeam-
>mea_values[2]);
sBeam->depend_Fy[2] = sBeam->mea_values[0]*sBeam-
>mea_values[0]*cos(PI*sBeam->mea_values[2])*PI;
…
6. The subroutine FEloadsub can be written in either C or C++. However, if using C++ the subroutine
header must be qualified with a leading extern "C" specification. See examples below.
Theoretical background
See documentation on the FE_LOAD for a theoretical background on how the distributed loads are computed
and processed by Adams Solver C++.
Use Corresponding Statement
Calling Sequence
If using C:
void FEloadsub( struct sAdamsANCF3DBeamDistrForce *sBeam, double TIME, int
252 Adams Solver
If using C++:
extern "C"
void FEloadsub( struct sAdamsANCF3DBeamDistrForce *sBeam, double TIME, int
The sAdamsANCF3DbeamDistrForce data structure has the following data members:
struct sAdamsANCF3DBeamDistrForce
{
int ID;
int NPAR;
const double* PAR;
double curr_S;
double *mea_values;
double* depend_Fx;
double* depend_Fy;
double* depend_Fz;
double* depend_Tx;
double* depend_Ty;
double* depend_Tz;
// More data not shown
}
This data structure is passed to the user at every call with the corresponding values of all registered measures
(mea_values), the Adams ID of the corresponding FE_LOAD statement (ID), the number of parameters in
the USER option (NPAR), the values of all parameters (PAR), the current value of the S location (0<S<1)
where the subroutine is being evaluated (curr_S). The other data members are used to pass dependencies and
partial derivatives. All of these data members can be accessed in your subroutine code.
Input arguments
sBeam A pointer to a C++ structure with information about the FE_PART this load
is acting upon. File slv_c_utils.h provided more for information about the
definition of this data structure. The internal data of this struct is managed
entirely by Adams Solver C++.
This pointer can be used to (a) retrieve the ID of the FE_PART; (b) find the
parameters defined in the USER option of the FE_LOAD statement; (c)
register dependencies; (d) get the values of the registered measures; (e) map
dependencies.
FEloadsub 253
TIME A double-precision variable containing the current simulation time. This

variable should be ignored except when IFLAG is 0 or DFLAG is 1.
DFLAG An integer variable that Adams Solver C++ sets to 1 when the partial
derivatives of the six expressions are requested. Structure sBeam provides the
tools to pass the partial derivatives.
IFLAG An integer variable that Adams Solver C++ sets to indicate why the routine is
being called.
When IFLAG is 1 (expression construction) the user must use the sBeam
pointer to "register" the measures the distributed load depends on. Each
registration is made by making a call to function c_sysfn2(). Each registered
measures is assigned a 0-based index. If the x component of the force depends
on 3 measures, the z component of torque depends on 2 components, while
the other 4 components of the distributed load are zero, then the user need to
register a total of 5 measures. If two or more components depend on the same
measure, the measure needs to be registered only once.
When IFLG is 3 (expression mapping), the user must provide a map of the
partial derivatives of the components relative to the registered measures. If one
component of the distributed load (say the x component) depend on the
second, fourth and fifth registered measures, then the user should set to 1 the
values of the second, fourth and fifth entries of an array provided by the sBeam
pointer.
When IFLAG is equal to 0, the user should return the value of the distributed
force per unit length in array RESULT. Adams Solver C++ passes the values of
all registered measures, there is no need to call functions to evaluate the
measures. All registered measures can be retrieved from the sBeam pointer.
254 Adams Solver
Output arguments
RESULT A double precision array that returns the six values of the distributed force.
This array is used only if IFLAG is equal to 0.
sBeam Depending on the values of IFLAG and DFLAG, this data structure needs to
include additional data explained above.
Extended Definition
The FE_LOAD statement version using explicit expression is usually adequate for defining functions that
represent the three distributed forces per unit length and three distributed torque per unit length. However,
if the force and torque expressions are lengthy or complicated, you can use a FEloadsub.
The FEloadsub user-written subroutine requires the user to provide the partial derivatives of the loading with
respect to the registered measures. However, in case the loading is complex or no explicit partial derivative
expression exists, you may use your own numerical perturbation to approximate the required partial
derivatives. See Example 3 and Example 4 below for details.
Example 1
Figure 5 below shows a simple cantilever beam with a sinusoidal distributed loading. The beam has an
undeformed length L equal to 6 meters. The left end of the beam is located on the GROUND origin.
Figure 5 Simple sinusoidal distributed loading.
This loading can be easily defined using a function expression as follows:
FE_LOAD/1
, FE_PART=3
, FX= 0\
, FY= -SIN(PI * SD(1) / 6) \
, FZ= 0\
, TX= 0\
, TY= 0\
FEloadsub 255
, TZ= 0
Function SD(1) returns the value of the x coordinate (in global frame) of the point along the beam where the
loading function is evaluated. An equivalent user-written subroutine for this loading would be as follows:
#include <math.h>
extern "C"
void FEloadsub( struct sAdamsANCF3DBeamDistrForce* sBeam, double
TIME, int DFLAG, int IFLAG, double *RESULT )
{
const double PI = 3.14159265358979323846;
if( IFLAG==1 )
{
int index, ERRFLG, NPAR, PAR[1];
// Registration of measures used by this subroutine

NPAR = 1;
PAR[0] = 1;
c_sysfn2( sBeam, "SD", PAR, NPAR, &index, &ERRFLG );
}
else if( IFLAG==3 )
{
}
else if( IFLAG==0 )
{
// Normal function evaluation
RESULT[1] = - sin( PI * sBeam->mea_values[0] / 6 );
if( DFLAG==1 )
{
// Returning partial derivatives
sBeam->depend_Fy[0] = - PI * cos( PI * sBeam->mea_values[0] /
6 )/6;
}
}
}
When IFLAG=1 we make the call to c_sysfn2() registering the measure SD(1). When IFLAG=3 we tell
Adams Solver the component FY of the loading depends on the SD(1) measure (the index of the SD(1)
measure is zero). When IFLAG=0 we return the value for FY. Notice the value of the SD(1) measure is already
pre-computed by Adams Solver C++ and passed to the subroutine inside the sBeam->mea_values array. When
DFLAG=1 we return the value of the partial derivative of FY with respect to SD(1); notice we use the sBeam-
>depend_Fy array in order to do so.
256 Adams Solver
Example 2
Given the FE_LOAD statement below, we show a user-written subroutine to perform the computation.
FE_LOAD/1
, FE_PART=3
, FX= COS(SV(3))*SD(2)\
, FY= 2.*SD(1)\
, FZ= 0\
, TX= SD(1)*COS(SD(2))\
, TY= 0\
, TZ= DX(4)*DY(4)
Notice the six components of the FE_LOAD depend on a total of 5 measures: SD(1), SD(2), SV(3), DX(4)
and DY(4). Hence, an equivalent subroutine must have a "registration" code as follows:
if( IFLAG==1 )
{
int index;
int ERRFLG;
int PAR[1];
PAR[0] = 1;
c_sysfn2( sBeam, "SD", PAR, 1, &index, &ERRFLG ); // SD(1)
PAR[0] = 2;
PAR[0] = 3;
c_sysfn2( sBeam, "SV", PAR, 1, &index, &ERRFLG ); // SV(3)
PAR[0] = 4;
c_sysfn2( sBeam, "DX", PAR, 1, &index, &ERRFLG ); // DX(4)
c_sysfn2( sBeam, "DY", PAR, 1, &index, &ERRFLG ); // DY(4)
return;
}
Notice the index variable is not used by the user who wrote this subroutine. If you check the return value of
variable index you will notice that measure SD(1) will get a value 0 for the index, SD(2) will get a 1, and so
forth. Similarly, for clarity, the ERRFLG is not checked for errors coming from the solver.
During the mapping process (IFLAG=3), the user needs to tell Adams Solver C++ what are the dependencies
of each component with respect to the registered measures. For example, if the Fx component depends on
measures with index 1 and 2, then the user must set the value 1.0 on the corresponding values in the sBeam
data structure. For this example, the registration code would be as follows:
if( IFLAG==3 )
{
sBeam->depend_Fx[1] = 1.0; // Fx depends on SD(2)
sBeam->depend_Fx[2] = 1.0; // Fx depends on SV(3)
sBeam->depend_Fy[0] = 1.0; // Fy depends on SD(1)
sBeam->depend_Tx[0] = 1.0; // Tx depends on SD(1)
sBeam->depend_Tx[1] = 1.0; // Tx depends on SD(2)
sBeam->depend_Tz[3] = 1.0; // Tz depends on DX(4)
FEloadsub 257
sBeam->depend_Tz[4] = 1.0; // Tz depends on DY(4)

return;
}
Notice arrays depend_FX, depend_FY, depend_FZ, depend_TX, depend_TY and depend_TZ are used to
set the dependencies. All entries of those arrays are set to zero before calling the subroutine. Upon returning
from the subroutine, Adams Solver C++ will remember those dependencies and expects the partial derivatives
are returned on the very same locations when DFLAG is equal to 1.
During normal evaluations (IFLAG equal to 0) the corresponding code should be:
if (IFLAG == 0)
{
// Fx=cos(SV(3))*SD(2)
RESULT[0] = cos(sBeam->mea_values[2])*(sBeam->mea_values[1]);
// Fy=2*SD(1)
RESULT[1] = 2.0*(sBeam->mea_values[0]);
// Tx=SD(1)*cos(SD(2))
RESULT[3] = (sBeam->mea_values[0])*cos(sBeam->mea_values[1]);
// Tz=DX(4)*DY(4)
RESULT[5] = (sBeam->mea_values[3])*(sBeam->mea_values[4]);
return;
}
Notice the mea_values array returns the values of all the "registered" measures.
During partial derivatives calculations (DFLAG equal to 1) the required partial derivatives can be computed
using the mea_values array. The complete example code is as follow:
extern "C"
void ANCFbeamsub_two( struct sAdamsANCF3DBeamDistrForce* sBeam,

double TIME, int DFLAG, int IFLAG, double *RESULT )
{
if( IFLAG==1 )
{
int index;
int ERRFLG;
int PAR[1];
PAR[0] = 1;
PAR[0] = 2;
PAR[0] = 3;
c_sysfn2( sBeam, "SV", PAR, 1, &index, &ERRFLG ); // SV(3)
PAR[0] = 4;
c_sysfn2( sBeam, "DX", PAR, 1, &index, &ERRFLG ); // DX(4)
c_sysfn2( sBeam, "DY", PAR, 1, &index, &ERRFLG ); // DY(4)
return;
}
258 Adams Solver
if( IFLAG==3 )
{
sBeam->depend_Tx[0] = 1.0;
sBeam->depend_Tx[1] = 1.0;
sBeam->depend_Tz[3] = 1.0;
sBeam->depend_Tz[4] = 1.0;
return;
}
if (IFLAG == 0)
{
// Fx=cos(SV(3))*SD(2)
RESULT[0] = cos(sBeam->mea_values[2])*(sBeam->mea_values[1]);
// Fy=2*SD(1)
RESULT[1] = 2.0*(sBeam->mea_values[0]);
// Tx=SD(1)*cos(SD(2))
RESULT[3] = (sBeam->mea_values[0])*cos(sBeam->mea_values[1]);
// Tz=DX(4)*DY(4)
RESULT[5] = (sBeam->mea_values[3])*(sBeam->mea_values[4]);
return;
}
if( DFLAG==1 )
{
// Returning partial derivatives
sBeam->depend_Fx[1] = cos(sBeam->mea_values[2]);
sBeam->depend_Fx[2] = -sin(sBeam->mea_values[2])*(sBeam->
mea_values[1]);
sBeam->depend_Tx[0] = cos(sBeam->mea_values[1]);
sBeam->depend_Tx[1] = -sBeam->mea_values[0]*sin(sBeam->
mea_values[1]);
sBeam->depend_Tz[3] = sBeam->mea_values[4];
sBeam->depend_Tz[4] = sBeam->mea_values[3];
return;
}
}
Example 3
Figure 6 below shows a slender cantilever column subject to distributed load due to wind pressure.
FEloadsub 259
Figure 6 Slender cantilever column.
The distributed load on a beam is specified using components FX, FY, FZ, TX, TY and TZ relative to either
GROUND or an RM Marker specified in the FE_LOAD statement. However, in this example we show how we
can apply a distributed load normal to the current configuration of the beam.
Let's assume the velocity field and the normal pressure have the following expression:
Hence the pressure to apply is:
The pressure p depends on the value of the y coordinate which is returned by the SD(2) measure. You also
need the Euler angles corresponding to the beam's deformed configuration at the point where the distributed
force is evaluated (see the local frame x'y' in Figure 6). The Euler 3-1-3 angles of that frame are returned by
the SD(4), SD(5) and SD(6) which correspond to the ψ , θ and ϕ respectively. With the values of the Euler
angles, the instantaneous rotation matrix A has the following expression:
260 Adams Solver
For clarity only the entries corresponding to the local y' axis are shown (center column). The first and third
columns define the orientation of the local x' and z' axes respectively. However, those components are no
needed in this example. A local pressure p acting in the negative direction y' has the following components
in the global reference frame:
Hence, ignoring the Fz component (assuming the column does not twist), the distributed load has the
Or
Assume parameter C has a value 0.2 specified in the FE_LOAD statement as follows:
FE_LOAD/7
, FE_PART = 1
, FUNCTION = USER(0.2)
Then the corresponding FEloadsub code for this loading is the following (no RM Marker implies loading is
parallel to global origin):
#include <math.h>
extern "C"
{
const double PI = 3.14159265358979323846;
FEloadsub 261
if( IFLAG==1 )
{
npar = 1;
par[0] = 2;
position
par[0] = 4;
par[0] = 5;
par[0] = 6;
}
else if( IFLAG==3 )
{
}
else if( IFLAG==0 )
{

if( DFLAG==1 )
{
sBeam->depend_Fx[0] = -C*4.*pow(y,3)*(-cos(Psi)*sin(Phi) -
sBeam->depend_Fx[1] = -C*pow(y,4)*(sin(Psi)*sin(Phi) -
sBeam->depend_Fx[2] = -C*pow(y,4)*(sin(Psi)*sin(Theta)*cos(Phi));
sBeam->depend_Fx[3] = -C*pow(y,4)*(-cos(Psi)*cos(Phi) +
sBeam->depend_Fy[0] = -C*4.*pow(y,3)*(-sin(Psi)*sin(Phi) +
sBeam->depend_Fy[1] = -C*pow(y,4)*(-cos(Psi)*sin(Phi) -
sBeam->depend_Fy[2] = -C*pow(y,4)*(-cos(Psi)*sin(Theta)*cos(Phi));
262 Adams Solver
sBeam->depend_Fy[3] = -C*pow(y,4)*(-sin(Psi)*cos(Phi) -
}
}
}
Notice the computation of the partial derivatives. Next example discusses the case when the computation of
the partial derivatives is done using a simple forward numerical perturbation.
Example 4
This example is based on the previous example. The computation of the required partial derivatives may be
time consuming or difficult in some cases. In that regard, you may compute the partial derivatives doing your
own numerical perturbation as the following code shows. For example, you could write the following
functions to compute Fx and Fy (compare with Example 3 above):
double myFx( double C, double y, double Psi, double Theta, double Phi )
{
return -C*pow(y,4)*(-cos(Psi)*sin(Phi) - sin(Psi)*cos(Theta)*cos(Phi));
}
double myFy( double C, double y, double Psi, double Theta, double Phi )
{
return -C*pow(y,4)*(-sin(Psi)*sin(Phi) + cos(Psi)*cos(Theta)*cos(Phi));
}
Also, a perturbation parameter H is defined with the value 0.0001. The user-written subroutine can now be
written as follows:
extern "C"
{
const double PI = 3.14159265358979323846;
const double H = 0.0001;
if( IFLAG==1 )
{
npar = 1;
par[0] = 2;
position
par[0] = 4;
par[0] = 5;
par[0] = 6;
}
else if( IFLAG==3 )
{
FEloadsub 263
}
else if( IFLAG==0 )
{

RESULT[0] = myFx( C, y, Psi, Theta, Phi );
RESULT[1] = myFy( C, y, Psi, Theta, Phi );
// Partial derivatives computed numerically

if( DFLAG==1 )
{
sBeam->depend_Fx[0] = (myFx(C, y+H, Psi, Theta, Phi)-myFx(C, y, Psi,
Theta, Phi))/H;
sBeam->depend_Fx[1] = (myFx(C, y, Psi+H, Theta, Phi)-myFx(C, y, Psi,
Theta, Phi))/H;
sBeam->depend_Fx[2] = (myFx(C, y, Psi, Theta+H, Phi)-myFx(C, y, Psi,
Theta, Phi))/H;
sBeam->depend_Fx[3] = (myFx(C, y, Psi, Theta, Phi+H)-myFx(C, y, Psi,
Theta, Phi))/H;
sBeam->depend_Fy[0] = (myFy(C, y+H, Psi, Theta, Phi)-myFy(C, y, Psi,

Theta, Phi))/H;
sBeam->depend_Fy[1] = (myFy(C, y, Psi+H, Theta, Phi)-myFy(C, y, Psi,
Theta, Phi))/H;
sBeam->depend_Fy[2] = (myFy(C, y, Psi, Theta+H, Phi)-myFy(C, y, Psi,
Theta, Phi))/H;
sBeam->depend_Fy[3] = (myFy(C, y, Psi, Theta, Phi+H)-myFy(C, y, Psi,
Theta, Phi))/H;
}
}
}
The computation of the partial derivatives does not need to be exact. Adams Solver C++ uses a Newton-
Raphson algorithm to solve the nonlinear governing equations. In that regard, the partial derivatives provided
to the Solver may be simplified. In some case you may choose to ignore computing partial derivatives.
264 Adams Solver
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.
case; Fiesub for example. Doing this ensures that Adams Solver correctly distinguishes a C
Use
Calling Sequence
SUBROUTINE FIESUB (id, time, par, npar, disp, velo,& dflag, iflag, field, dfddis, dfdvel)
FIESUB 265
Input Arguments
id An integer variable that provides the identifier of the FIELD statement requesting information
from FIESUB. From the identifier, Adams Solver automatically knows other information
time A double-precision variable through which Adams Solver conveys the current simulation time.
par A double-precision array of constants taken, in order, from the USER parenthetical list of the
FIELD statement.
npar An integer variable that indicates the number of constants specified in the USER parenthetical
list. The primary purpose of npar is to provide FIESUB with the number of values stored in
the par array.
disp A six-element, double-precision array that provides the x, y, and z translational displacements
and the AX, AY, and AZ rotational displacements that Adams Solver measures at the I marker
with respect to the J marker, resolved in the coordinate system of the J marker. For more
information, see AX function (C++ or FORTRAN), AY function (C++ or FORTRAN), and
AZ function (C++ or FORTRAN).
266 Adams Solver
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.
Value Description
support the Adams Solver commands Save and Reload, then call the serialization functions for
your data when iflag is set to 7, and the un-serialization functions when iflag is set to 9.
In simple subroutines where serializing data is not needed, you can declare iflag as a
logical variable. In this case you can do any initializations when Adams Solver sets iflag
to true, and compute the subroutine's value when Adams Solver sets iflag to false.
Output Arguments
field A six-element, double-precision array that returns the x, y, and z translational forces and the
x, y, and z rotational forces that Adams Solver applies at the I marker with respect to the J
marker, resolved in the coordinate system of the J marker.
dfddis A six-by-six, double-precision array that returns the derivatives of the six field components
with respect to the six displacement values in the disp array. For example, the derivative of the
fourth FIELD component (TX) with respect to the second displacement variable (y) is dfddis
(4,2). You only need to define dfddis when dflag is set to true.
dfdvel A six-by-six, double-precision array of the derivatives of the six field components with respect
to the six velocity values in the velo array. For example, the derivative of the first FIELD
component (FX) with respect to the sixth velocity variable (WZ) is dfdvel(1,6). You need to
define dfdvel only when dflag is set to true.
FIESUB 267
Extended Definition
The FIELD statement with KMATRIX and CMATRIX/CRATIO arguments specified may be used for
defining six-component forces whose stiffness and damping matrices have constant entries. If, however, the
force components are nonlinear functions of the relative displacements and the relative velocities of the
FIELD I and J markers, then use a FIELD statement with FUNCTION=USER() and write a FIESUB to
calculate the six FIELD components. These components and their derivatives can be functions of time and
of the FIELD I marker component displacements and component velocities, with respect to the J marker.
Adams Solver resolves the components in the J marker coordinate system.
FIESUB output must be strictly a function of the values in arrays disp and velo. Consequently, FIESUB may
not call the SYSARY or SYSFNC utility subroutine. FIESUB may call other utility subroutines, such as
AKISPL, and CUBSPL, that do not introduce a dependency on Solver states.
Caution:  The dfddis and dfdvel arrays must always be positive semidefinite. Adams Solver does not
warn you if the dfddis array, the dfdvel array, or both, are not positive semidefinite. An
array A is positive semidefinite if xT A x > 0 for all x not equal to 0.
 Don't attempt to make any of the six field components dependent on system variables
other than those FIESUB passes through the arguments disp, velo, and time. This rule
prohibits calls to the utility subroutines SYSARY and SYSFNC. Failure to comply with
this rule does not produce error messages, but greatly reduces the integration step sizes,
increases the CPU time, and decreases the probability of convergence to a solution.
 If FIESUB returns the six field components without their correct derivatives, simulation
times may correspondingly increase, and the probability of convergence to a solution
decreases.
 If AKISPL, CUBSPL, or any of the Adams Solver utility subroutines are used, don't forget
to involve the derivatives returned by these subroutines when the FIESUB derivatives are
evaluated.
 Field components with continuous derivatives are desirable. Discontinuous derivatives
cause a reduction of integration step size at the discontinuity, and may cause Adams Solver
to fail to converge to a solution.
 When the iflag argument is not zero, Adams Solver sets the disp and velo arguments to
zeros. When you execute Adams Solver, computations that divide by these values result in
fatal errors. You should check for nonzero values, or ensure the iflag argument is zero,
before dividing by disp or velo values.
FORTRAN - Prototype
A sample structure for FIESUB is shown next. The comments explain how the subroutine works.
SUBROUTINE FIESUB (ID, TIME, PAR, NPAR, DISP,
& VELO, DFLAG, IFLAG, FIELD,
& DFDDIS, DFDVEL )
C
C
268 Adams Solver

C
INTEGER ID
INTEGER NPAR
DOUBLE PRECISION DISP( 6 )
DOUBLE PRECISION VELO( 6 )
LOGICAL DFLAG
INTEGER IFLAG
DOUBLE PRECISION FIELD( 6 )
DOUBLE PRECISION DFDDIS( 6, 6 )
DOUBLE PRECISION DFDVEL( 6, 6 )
C
C ID Identifier of calling FIELD statement
C TIME Current time
C 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
IF ( IFLAG ) THEN
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) = ...
FIESUB 269
C
C - Calculate field component torques -------
C
C X rotational field torque
C
...
FIELD(4) = ...
C
C Y rotational field torque
C
...
FIELD(5) = ...
C
C Z rotational field torque
C
...
FIELD(6) = ...
C
C - Assign returned partial derivatives if this --
C is a differencing pass (DFLAG=.TRUE.)
C
IF ( DFLAG ) THEN
C
C Assign displacement partials for X force
C
DFDDIS(1,1) = ...
...
DFDDIS(1,6) = ...
C
C Assign displacement partials for Y force
C
DFDDIS(2,1) = ...
...
DFDDIS(2,6) = ...
C
C Assign displacement partials for Z force
C
DFDDIS(3,1) = ...
...
DFDDIS(3,6) = ...
C
C Assign displacement partials for X torque
C
DFDDIS(4,1) = ...
...
DFDDIS(4,6) = ...
C
C Assign displacement partials for Y torque
C
DFDDIS(5,1) = ...
...
DFDDIS(5,6) = ...
C
C Assign displacement partials for Z torque
C
DFDDIS(6,1) = ...
...
DFDDIS(6,6) = ...
C
C Assign velocity partials for X force
270 Adams Solver
C
DFDVEL(1,1) = ...
...
DFDVEL(1,6) = ...
C
C Assign velocity partials for Y force
C
DFDVEL(2,1) = ...
...
DFDVEL(2,6) = ...
C
C Assign velocity partials for Z force
C
DFDVEL(3,1) = ...
...
DFDVEL(3,6) = ...
C
C Assign velocity partials for X torque
C
DFDVEL(4,1) = ...
...
DFDVEL(4,6) = ...
C
C Assign velocity partials for Y torque
C
DFDVEL(5,1) = ...
...
DFDVEL(5,6) = ...
C
C Assign velocity partials for Z torque
C
DFDVEL(6,1) = ...
...
DFDVEL(6,6) = ...
C
ENDIF
C
RETURN
END
C Style - Prototype
typedef void adams_c_FIESUB(const struct sAdamsField* fie, double
TIME, double* DISP, double* VELO, int DFLAG, int IFLAG, double*
FIELD, double* DFDDIS, double* DFDVEL);
/*
* FIELD -------------------------------------------------
----------------
*/
struct sAdamsField
{
int ID;
int NPAR;
const double* PAR;
int I;
int J;
};
FIESUB 271
Examples
For an example of this subroutine, see fiesub.f
272 Adams Solver
GSE_SET_IMPLICIT
This subroutine is used to specify the implicit/explicit character of the equations governing the GSE.
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 INTERFACE= attribute). If GSE_SET_IMPLICIT is
present, then during initialization of the GSE this subroutine will be called.
Notes:  The value returned by GSE_SET_IMPLICIT will override any IMPLICIT attribute
setting that is specified in the GSE statement.
 Use mixed case names for the Adams subroutine names when using the C style interface.
For the default subroutine name capitalize the first letter and have the remaining letters
lower case. Doing this ensures that Adams Solver correctly distinguishes a C style
subroutine from Fortran and calls with the appropriate interface.
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)
Input Arguments
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.
Output Arguments
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:
GSE_SET_IMPLICIT 273
C
INTEGER ID
C
C Outputs:
C
INTEGER IMPLICIT
C
C This GSE is formulated implicitly.
IMPLICIT = 1
RETURN
END
C
C+===============================================================*
C
274 Adams Solver
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 INTERFACE= attribute). If GSE_SET_ND is found, then during
initialization of the GSE this subroutine will be called.
Notes:  The value, ND, returned by GSE_SET_ND will override any value of ND that is specified
in the GSE statement.
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)
Input Arguments
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.
Output Arguments
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
GSE_SET_ND 275
C Inputs:
C
INTEGER ID
C
C Outputs:
C
INTEGER ND
C
C This GSE has two discrete internal states.
ND = 2
RETURN
END
C
C+=================================================================*
C
276 Adams Solver
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 INTERFACE= attribute). If GSE_SET_NS is found, then during
initialization of the GSE this subroutine will be called.
Notes:  The value, NS, returned by GSE_SET_NS will override any value of NS that is specified
in the GSE statement.
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)
Input Arguments
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
Output Arguments
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
GSE_SET_NS 277
C Outputs:
C
INTEGER NS
C
C This GSE has two internal states.
NS = 2
RETURN
END
C
C+=================================================================*
C
278 Adams Solver
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 INTERFACE= attribute). If
GSE_SET_SAMPLE_OFFSET is present, then during initialization of the GSE this subroutine will be
called.
Notes:  The value returned by GSE_SET_SAMPLE_OFFSET will override any

SAMPLE_OFFSET 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 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)
Input Arguments
from the GSE subroutine.
Output Arguments
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:
GSE_SET_SAMPLE_OFFSET 279
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
280 Adams Solver
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 INTERFACE= attribute). If
GSE_SET_STATIC_HOLD is present, then during initialization of the GSE this subroutine will be called.
Notes:  The value returned by GSE_SET_STATIC_HOLD will override any STATIC_HOLD

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 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)
Input Arguments
from the GSE subroutine.
Output Arguments
STATIC_HOL An integer specifying whether the GSE formulation has the STATIC_HOLD attribute
D 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
GSE_SET_STATIC_HOLD 281
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
282 Adams Solver
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.
case; Gfosub for example. Doing this ensures that Adams Solver correctly distinguishes a C
Use
Calling Sequence
SUBROUTINE GFOSUB(id, time, par, npar, dflag, iflag, result)
Input Arguments
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.
GFORCE statement.
GFOSUB 283
parenthetical list. This variable provides the GFOSUB evaluation subroutine with the
dflag A logical variable that Adams Solver sets to true when it calls GFOSUB to evaluate the
argument to false.
Value Description
SYSFNC utility subroutines that are made to compute the value of the user-defined variable.
If iflag is 0, Adams Solver computes the value of the user-written variable.
Note: In simple subroutines where serializing data is not needed, you can declare iflag as
a logical variable. In this case you declare your dependencies when Adams Solver
sets iflag to true, and compute the subroutine's value when Adams Solver sets iflag
to false.
Output Argument
result A double-precision array that returns the six values of the GFORCE components.
Extended Definition
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.
284 Adams Solver
The SYSARY and SYSFNC utility subroutines set up functional dependencies when the GFOSUB argument
iflag is not zero. 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 not zero. 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 not zero, 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.
 When the iflag argument is not zero, SYSARY and SYSFNC return zero values for 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 zero,
before dividing by these values.
FORTRAN - Prototype
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 - External variable definitions -----------
C
GFOSUB 285
INTEGER ID
INTEGER NPAR
LOGICAL DFLAG
INTEGER IFLAG
DOUBLE PRECISION RESULT( 6 )
C
C ID Identifier of calling GFORCE statement
C TIME Current time
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
CALL SYSFNC (...)
C
C
CALL ERRMES (...)
C
C
...
C
IF (IFLAG) THEN
C
C
...
C
ENDIF
C
C - Evaluate GFORCE components -------------
C
C Your algorithms
C
286 Adams Solver
...
C
C Assign values to the RESULT array
C
RESULT(1) = ...
RESULT(2) = ...
RESULT(3) = ...
RESULT(4) = ...
RESULT(5) = ...
RESULT(6) = ...
C
RETURN
END
C Style - Prototype
typedef void adams_c_GFOSUB(const struct sAdamsGforce* gfo, double
/*
* GFORCE
*/
struct sAdamsGforce
{
int ID;
int NPAR;
const double* PAR;
int I;
int RM;
int JFLOAT;
};
Examples
For an example of this subroutine, see gfosub.f
GSE_DERIV, GSE_OUTPUT, GSE_UPDATE, GSE_SAMP 287
GSE_DERIV, GSE_OUTPUT, GSE_UPDATE, 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 explicit form:
x· c = f c ( x c, u, t ) xc ( t0 ) = xc (1)
y = g ( x c, x d, u, t ) (3)
and in implicit form equations (1) and (3) are replaced by equations (4) and (5), respectively, below:
·
0 = f c ( x c, x c, u, t ) xc ( t0 ) = xc0 (4)
·
y = g ( x c, x c, x d, u, t ) (5)
 GSE_DERIV defines the function fc(), shown in Equation (1) or (4) above. In the explicit case
GSE_DERIV need to provide the partial derivatives:
∂ f ( ) , ∂ (f ( ))
∂ xc c ∂u c
and in implicit case following three partial derivatives should be provided:
∂ f ( ), ∂ f ( ) , ∂ (f ( ))
· c ∂ xc c ∂u c
∂ xc
 GSE_OUTPUT defines the function g(), shown in Equation (3) or (5) above. In the explicit case
GSE_OUTPUT need to provide the partial derivatives:
∂ g ( ), ∂ g ( )
∂ xc ∂u
and in the implicit case following three partial derivatives should be provided:
∂ g ( ), ∂ g ( ), ∂ g ( )
· ∂ xc ∂u
∂ xc
 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_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.
288 Adams Solver
case. Doing this ensures that Adams Solver correctly distinguishes a C style subroutine from
Fortran and calls with the appropriate interface.
Use
GSE_DERIV

SUBROUTINE GSE_DERIV (ID, TIME, PAR, NPAR, DFLAG, IFLAG, NS, XDOT)
Input Arguments
id An integer variable containing the ID 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.
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 The DFLAG argument should be ignored. It is present only to provide backward
compatibility for the GSE API. Do not use this argument as a logical flag for computing
partial derivatives. Instead, always use the utility subroutine ADAMS_NEEDS_PARTIALS.
Using DFLAG will give incorrect results.
Value Description
When iflag is 0 Adams Solver calling to compute the value of the user-written variable.
When iflag is set to 1 or 3 do any initializations that your subroutine requires.
a logical variable. In this case you can do any initializations when Adams Solver
to false.
ns An integer variable containing the number of continuous states in the GSE; taken from the
NS argument to the GSE statement.
290 Adams Solver
Output Arguments
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
Calling Sequence
SUBROUTINE GSE_UPDATE (ID, TIME, PAR, NPAR, DFLAG, IFLAG, ND, XDplus1)
Input Arguments
information (such as the PAR argument) that is associated with that GSE statement.
parenthetical list in the GSE statement. The primary purpose is to provide the subroutine
with the number of entries in the Par array.
compatibility for the GSE API.
Value Description
false.
nd An integer variable containing the number of discrete states in the GSE; taken from the ND
argument to the GSE statement.
Output Arguments
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

292 Adams Solver
Input Arguments
information (such as the par argument) that is associated with that GSE statement.
parenthetical list in the GSE statement. The primary purpose is to provide the subroutine with
the number of entries in the PAR array.
compatibility for the GSE API. Do not use this argument as a logical flag for computing
partial derivatives. Instead, always use the utility subroutine ADAMS_NEEDS_PARTIALS.
Using DFLAG will give incorrect results.
Value Description
false.
no An integer variable containing the number of outputs in the GSE; taken from the NO
argument to the GSE statement.
Output Arguments
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)
Input Arguments
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
294 Adams Solver
The primary purpose is to provide the subroutine with the number of entries in the Par array.
Value Description
false.
Output Arguments
sample_step A double-precision scalar, containing the sample step (that is, the difference between
the next sample time, and the current simulation).
Calling schedule of GSE_UPDATE and GSE_SAMP subroutines

GSE objects defining discrete states must be defined with a GSE_UPDATE subroutine that defines Equation
(2) above. Moreover, either a SAMPLE_PERIOD expression or a GSE_SAMP subroutine must be included
to define the sampling times, for example, the times when the call to GSE_UPDATE is made (see GSE
statement for more details). Adams Solver (C++) will call GSE_UPDATE only when time is increasing and
the current simulation time coincides with the current sampling time. Therefore, no calls to GSE_UPDATE
are made during simulations where the simulation time does not change. In other words, calls to
GSE_UPDATE are made only when the simulation mode is 4 or 6 (see GETMOD utility.)
If the SAMPLE_OFFSET is bigger than zero, the calling sequence is as follows. Adams Solver (C++) will start
simulating the model up to the SAMPLE_OFFSET time. Notice that no calls to the GSE_UPDATE
subroutine are made while the simulation time is smaller than SAMPLE_OFFSET. Upon reaching the
SAMPLE_OFFSET time, Adams Solver (C++) will either evaluate the SAMPLE_PERIOD expression or it
will make the first call to the GSE_SAMP subroutine to determine the time of the first sampling time, before
proceeding with the simulation. Upon reaching the first sampling time, the first call to GSE_UPDATE is
made. At this point, the next sampling time is computed by either computing the value of the
SAMPLE_PERIOD expression or the getting the next value from the GSE_SAMP subroutine. With the next
sampling time computed, Adams Solver (C++) will simulate the model up to that time, it will call
GSE_UPDATE, it will compute the next sampling time, and so on.
If the SAMPLE_OFFSET is zero, Adams Solver (C++) will evaluate the first sampling time by evaluating the
SAMPLE_PERIOD expression or by making a call to the GSE_SAMP subroutine. The simulation then will
proceed up to the first sampling time. Upon reaching the first sampling time, the first call to GSE_UPDATE
is made. Also at this point, the next sampling time is computed (by evaluating the SAMPLE_PERIOD
expression or by calling GSE_SAMP), and so on.
Example
For an example of this subroutine, see gse_samp.f.
C Style - Prototype
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,
typedef void adams_c_GSEYX(const struct sAdamsGSE* gse, double TIME,
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
296 Adams Solver
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;
const double* PAR;
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 297
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.
case; Mfosub for example. Doing this ensures that Adams Solver correctly distinguishes a C
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.
Calling Sequence
SUBROUTINE MFOSUB (id, time, par, npar, dflag, iflag,$
modloads, nmodes, ncases,$
scale, case, loadvec)
298 Adams Solver
Input Arguments
id An integer variable that provides the identifier of the MFORCE statement that is requesting
information from the MFOSUB.
MFORCE statement.
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 to evaluate the partial
derivatives of the specified functions. Otherwise, Adams Solver sets dflag to false.
Value Description
false.
MFOSUB 299
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.
300 Adams Solver
Output Arguments
MFOSUB 301
scale A double-precision array of dimension scale(ncases + 1). A double-precision single variable

is also applicable.
If MFOSUB is called with the FUNCTION form:
If case > 0, then 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 case = -1, then the output
arguments contain the series of scale factors, scale(n + 1) to be applied to nth modal load
vector and they can depend on time only, where n is 1 to ncases. scale(1) contains the global
scale factor that can depend on the values Adams Solver calls from SYSFNC and SYSARY.
If MFOSUB is called with the FORCE form:
Adams Solver ignores this output argument.

case An integer, in the range -1 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. If case = -1, then multiple scale
factors for each modal load vector can be defined by the scale output arguments.
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.
302 Adams Solver
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.
SUBROUTINE MFOSUB(ID, TIME, PAR, NPAR, DFLAG, IFLAG,
$ MODLOADS, NMODES, NCASES,
$ SCALE, CASE, LOADVEC)
C
INTEGER ID, NPAR, NMODES, NCASES
LOGICAL DFLAG
LOGICAL ERRFLG
INTEGER IFLAG
DOUBLE PRECISION TIME, PAR(NPAR), MODLOADS(6+NMODES, NCASES)
C
INTEGER CASE
DOUBLE PRECISION SCALE, LOADVEC(6+NMODES)
C
CASE = 3
SCALE = 10.
ERRFLG = NCASES.LT.CASE
CALL ERRMES(ERRFLG, 'Trying to use an invalid load case.',
& ID, 'STOP' )
RETURN
END
For an example of this subroutine see mfosub.f.

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
INTEGER IFLAG
DOUBLE PRECISION PAR(NPAR)
DOUBLE PRECISION MODLOADS(6+NMODS, NCASES)
C
C... RETURNS
C
INTEGER CASE
DOUBLE PRECISION SCALE, LOADVEC(6+NMODS)
MFOSUB 303
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
LOGICAL ERRFLG
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
LOADVEC(I+6) = -TWO * DSQRT(GSTF * GMAS) * QDOT(I)
END DO
C
RETURN
END
304 Adams Solver
For an example of this subroutine see mfosub2.f.
C Style - Prototype
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;
const double* PAR;
int JFLOAT;
};
MOTSUB 305
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.
case; Motsub for example. Doing this ensures that Adams Solver correctly distinguishes a C
Use
Calling Sequence
SUBROUTINE MOTSUB(id, time, par, npar, iord, iflag,value)
306 Adams Solver
Input Arguments
id An integer variable that provides the identifier of the MOTION statement requesting
information from MOTSUB. From the identifier, Adams Solver automatically knows other
information (such as the par argument) available in the corresponding statement.
Value Description
When iflag is set to 1 or 3 do any initializations that your subroutine requires.
to false.
iord An input integer variable indicating the order of the time derivative that Adams Solver
requires at different points in the analysis.
When the motion is a displacement, Adams Solver, at various times, calls MOTSUB with
IORD set to 0, 1, or 2, requesting the displacement value and its first and second time
derivatives, respectively.
When the motion is a velocity, Adams Solver only calls MOTSUB with IORD set to 0 or 1,
and returns the velocity value and its time derivative, respectively. The second time
derivative, a velocity motion, is never required.
When the motion is an acceleration, Adams Solver only uses IORD set to 0. No time
derivatives of the function used in the MOTSUB for an acceleration motion are needed.
MOTSUB 307
parenthetical list. The primary purpose of npar is to provide MOTSUB with the number of
MOTION statement.
time.
Output Arguments
value A double-precision variable that returns the zeroth, first, or second derivative of the motion of
the I marker with respect to the J marker. These derivatives represent the displacement,
velocity, and acceleration of the motion, respectively. The value of IORD indicates which
derivative of motion value must return.
Extended Definition
In most cases, the MOTION statement with a function expression is adequate for defining the motion input.
However, if the expression becomes lengthy and awkward, you should use the FUNCTION=USER()
argument in the MOTION statement, and write a MOTSUB to calculate the displacement.
MOTSUB measures translational displacements from the origin of the J marker to the origin of the I marker.
The positive z-axis of the J marker defines the positive direction. MOTSUB measures rotational
displacements from the x-axis of the J marker to the x-axis of the I marker. The right-hand rule defines a
positive angle with respect to the positive z-axis of the J marker.
MOTSUB output must be strictly a function of time. Consequently, MOTSUB must not call the SYSARY
and SYSFNC utility subroutines. To describe discrete time-dependent functions, MOTSUB may call the
CUBSPL utility subroutine.
Caution:  Define the motion only as a function of time. Don't make calls to the SYSARY and
SYSFNC utility subroutines to access other system variables or to access user-defined
variables.
 Make sure the first and second derivatives MOTSUB returns for displacement are correct.
 If the CUBSPL utility subroutine or any of the Adams Solver utility subroutines are used,
do not forget to involve the derivatives returned by these subroutines when the MOTSUB
derivatives are evaluated.
 Avoid conditional branching that results in discontinuous accelerations, velocities, or
displacements.
 Make sure MOTSUB uses length units to define translational displacements and their
derivatives, and radians to define rotational displacements and their derivatives.
308 Adams Solver
FORTRAN - Prototype
A sample structure for MOTSUB is shown next. The comments explain how the subroutine works.
SUBROUTINE MOTSUB ( ID, TIME, PAR, NPAR, IORD,
& IFLAG, VALUE )
C
C
C
INTEGER ID
INTEGER NPAR
INTEGER IORD
INTEGER IFLAG
C
C ID Identifier of calling MOTION statement
C TIME Current time
C VALUE Derivative value of MOTION returned to ADAMS
C
C - Local variable and parameter definitions ----
C
...
C
C
C
...
C
IF ( IFLAG ) THEN
C
C
...
C
ENDIF
C
C - Compute and assign the motion displacement ---
C
C
C Your algorithm
C
...
C
C Assign a value to VALUE for the motion displacement
C
VALUE = ...
C
C - Compute and assign the motion velocity -----
C
ELSE IF ( IORD .EQ. 1 ) THEN
C
MOTSUB 309
C Your algorithm
C
...
C
C Assign a value to VALUE for the motion velocity
C
VALUE = ...
C
C - Compute and assign the motion acceleration ---
C
ELSE
C
C Your algorithm
C
...
C
C Assign a value to VALUE for the motion acceleration
C
VALUE = ...
C
ENDIF
C
RETURN
END
C Style - Protoype
typedef void adams_c_MOTSUB(const struct sAdamsMotion* motion, double
TIME, int IORD, int IFLAG, double* RESULT);
/*
* MOTION
*/
struct sAdamsMotion
{
int ID;
int NPAR;
const double* PAR;
int JOINT;
const char* Type;
int I;
int J;
char Which[2];
const char* DVA;
};
The sAdamsMotion struct provides additional information related to the corresponding MOTION object.
Member Type is either ROTATIONAL or TRANSLATIONAL, member DVA is either DISPLACEMENT,
VELOCITY or ACCELERATION. For the translational case, member Which[0] stores a 'X' or a 'Y' or a
'Z'; Which[1] is ignored. For the rotational case, member Which[0] stores a 'B' and Which[1] stores a
'1' or a '2' or a '3'.
Examples
For an example of this subroutine, see motsub.f.
310 Adams Solver
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.
case; Relsub for example. Doing this ensures that Adams Solver correctly distinguishes a C
Use
Calling Sequence
SUBROUTINE RELSUB(iunit, errflg)
Input Argument
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.
Output Argument
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.
RELSUB 311
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.
Structure
A sample structure for RELSUB is shown next. The comments describe how the subroutine works.
SUBROUTINE RELSUB(IUNIT, ERRFLG)
C
C
C
INTEGER IUNIT
LOGICAL ERRFLG
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 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.
312 Adams Solver
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.
case; Reqsub for example. Doing this ensures that Adams Solver correctly distinguishes a C
Use
REQSUB 313
Calling Sequence
SUBROUTINE REQSUB (id, time, par, npar, iflag, result)
Input Arguments
id An integer variable that provides the identifier of the REQUEST statement requesting
information from REQSUB. From the identifier, Adams Solver automatically knows other
information (such as the par argument) available in the corresponding statement.
Value Description
false.
parenthetical list. The primary purpose of npar is to provide REQSUB with the number of
REQUEST statement.
time.
314 Adams Solver
Output Argument
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.
Extended Definition
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,
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
set of rotational coordinates that does not encounter a singularity.
FORTRAN - Prototype
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
INTEGER IFLAG
DOUBLE PRECISION RESULT( 8 )
REQSUB 315
C
C ID Identifier of calling REQUEST statement
C TIME Current time
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 Your algorithms
C
...
C
C Assign values to the result array
C
RESULT(1) = ...
...
RESULT(8) = ...
C
RETURN
END
C Style - Prototype
typedef void adams_c_REQSUB(const struct sAdamsRequest* req, double
/*
* REQUEST -------------------------------------------------
----------------
*/
struct sAdamsRequest
{
int ID;
int NPAR;
const double* PAR;
const char* COMMENT;
const char* TITLE[8];
};
316 Adams Solver
Examples
For an example of this subroutine, see reqsub.f.
SAVSUB 317
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.
case; Savsub for example. Doing this ensures that Adams Solver correctly distinguishes a C
Use
Calling Sequence
SUBROUTINE SAVSUB(iunit, errflg)
Input Arguments
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.
Output Argument
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.
318 Adams Solver
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
LOGICAL ERRFLG
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 319
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.
case; Sensub for example. Doing this ensures that Adams Solver correctly distinguishes a C
Use
Calling Sequence
SUBROUTINE SENSUB (id, time, par, npar, iflag, value)
320 Adams Solver
Input Arguments
id An integer variable that contains the ID of the SENSOR statement that requests information
from SENSUB. From the identifier, Adams Solver automatically knows other information
time A double-precision variable through which Adams Solver conveys the current simulation time
to SENSUB.
SENSOR statement.
list. The primary purpose of npar is to provide SENSUB with the number of values stored in
the par array.
Value Description
utility subroutines that are made to compute the value of the user-defined variable. If iflag is 0,
Adams Solver computes the value of the user-written variable.
false.
Output Argument
value A double-precision variable that contains the value of the function that SENSUB evaluates.
SENSUB 321
Extended Definition
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, the
rotational representation that does not encounter a singularity.
FORTRAN - Prototype
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
C
INTEGER ID
INTEGER NPAR
INTEGER IFLAG
C
C ID Identifier of calling SENSOR statement
C TIME Current time
C VALUE The returned value of the sensor
C
C
...
C
C
C Assign parameter values to readable variables
C
...
C
IF( IFLAG ) THEN
C
C
...
C
ENDIFCC - Evaluate sensor ----------------
322 Adams Solver
C
C Your algorithm
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 -------------------------------------------------
----------------
struct sAdamsSensorEval
{
int NPAR;
const double* PAR;
};
*/
struct sAdamsSensor
{
int ID;
int NPAR;
const double* PAR;
double VALUE;
double Error;
char Logic[2];
/* struct sAdamsSensorEval Eval; */
};
Examples
For an example of this subroutine, see sensub.f.
SEVSUB 323
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.
case; Sevsub for example. Doing this ensures that Adams Solver correctly distinguishes a C
Use
Calling Sequence
SUBROUTINE SEVSUB (id, time, par, npar, iflag, result)
324 Adams Solver
Input Arguments
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) available in the corresponding statement.
time A double-precision variable through which Adams Solver conveys the current simulation time
to SEVSUB.
SENSOR statement.
list. The primary purpose of npar is to provide SEVSUB with the number of values stored in
the par array.
Value Description
utility subroutines that are made to compute the value of the user-defined variable. If iflag is 0,
Adams Solver computes the value of the user-written variable.
false.
Output Argument
result A double-precision variable that returns the value of the EVALUATE function for the
SENSOR.
SEVSUB 325
Extended Definition
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.
FORTRAN - Prototype
A sample structure for SEVSUB is shown next. The comments explain how the subroutine works.
SUBROUTINE SEVSUB ( ID, TIME, PAR, NPAR, IFLAG,
& RESULT )
C
C
C
C
INTEGER ID
INTEGER NPAR
INTEGER IFLAG
DOUBLE PRECISION RESULT
C
C ID Identifier of calling SENSOR statement
C TIME Current time
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
326 Adams Solver
C --- Compute the result

C
C Your algorithm
C
...
C
C --- Assign the return value
C
RESULT = ...
C
RETURN
END
C Style - Prototype
typedef void adams_c_SEVSUB(const struct sAdamsSensor* sensor, double
/*
* SENSOR
struct sAdamsSensorEval
{
int NPAR;
const double* PAR;
};
*/
struct sAdamsSensor
{
int ID;
int NPAR;
const double* PAR;
double VALUE;
double Error;
char Logic[2];
/* struct sAdamsSensorEval Eval; */
};
Examples
For an example of this subroutine, see sevsub.f.
SFOSUB 327
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).
case; Sfosub for example. Doing this ensures that Adams Solver correctly distinguishes a C
Use
Calling Sequence
SUBROUTINE SFOSUB (id, time, par, npar, dflag, iflag, value)
Input Arguments
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
time.
SFORCE statement.
328 Adams Solver
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.
list. The primary purpose of npar is to provide SFOSUB with the number of values stored in
the par array.
Value Description
false.
Output Argument
value A double-precision variable that contains the force value that SFOSUB computes.
Extended Definition
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 329
The SYSARY and SYSFNC utility subroutines automatically set functional dependencies when the SFOSUB
argument iflag is not zero. 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 not zero. 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.
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 not zero, 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.
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 zero, before dividing by these values.
FORTRAN - Prototype
A sample structure for SFOSUB is shown next. The comments explain how the subroutine works.
SUBROUTINE SFOSUB ( ID, TIME, PAR, NPAR, DFLAG,
& IFLAG, VALUE )
C
C
C
INTEGER ID
330 Adams Solver
INTEGER NPAR
LOGICAL DFLAG
INTEGER IFLAG
C
C ID Identifier of calling SFORCE statement
C TIME Current time
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
CALL ERRMES ( ... )
C
C Repeat for all required SYSFN
C or SYSARY calls
C
...
C
IF( IFLAG ) THEN
C
C
...
C
ENDIF
C
C - Evaluate force -----------------
C
C Your algorithm
C
...
C
C
VALUE = ...
C
RETURN
END
SFOSUB 331
C Style - Prototype
typedef void adams_c_SFOSUB(const struct sAdamsSforce* sforce, double
/*
* SFORCE
*/
struct sAdamsSforce
{
int ID;
int NPAR;
const double* PAR;
int I;
int J;
int ACTION_ONLY;
const char* Type;
};
Examples
For an example of this subroutine, see sfosub.f.
332 Adams Solver
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]]
or
SPLINE/id
, FILE=filename
[, BLOCK=blockname]
[, LINEAR_EXTRAPOLATE] SPLINE/id
[, ROUTINE=libname::subname]
Calling Sequence
SUBROUTINE SPLINE_READ (id, file_name, block_name, status)
SPLINE_READ 333
Input Arguments
id An integer variable that indicates the identifier of the corresponding

SPLINE statement.
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
SPLINE statement.
LINEAR_EXTRAPOLATE Causes Adams Solver to extrapolate a SPLINE that exceeds a defined
range by applying linear function(s) tangent to the spline at the end(s)
of the defined range. By default, Adams Solver extrapolates a SPLINE
that exceeds a defined range by applying a cubic function over the first
or last three data points.
SPLINE_READ.
Output Argument
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.
Extended Definition
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).
FORTRAN - Prototype
A sample structure for the SPLINE_READ subroutine follows next. The comments explain the activities that
the subroutine performs.
334 Adams Solver
SUBROUTINE SPLINE_READ (ID, FILE_NAME, BLOCK_NAME, STATUS)

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
C Style - Prototype
typedef void adams_c_SPLINE_READ(const struct sAdamsSpline* spline,
int* IERR);
/*
* SPLINE -------------------------------------------------
----------------
*/
struct sAdamsSpline
{
int ID;
const char* FILENAME;
const char* BLOCKNAME;
};
SPLINE_READ 335
Caution:  When using FORTRAN subroutines, you may need to use FORTRAN's SAVE statement
if the declared arrays are large. When not using the SAVE statement, declared arrays are
allocated on the operating system stack. If arrays are too large, a stack overflow may occur
stopping the program execution.
 When ROUTINE is specified, the CHANNEL argument (if supplied) in the SPLINE
statement is ignored by Adams Solver.
Examples
For an example of this subroutine, see spline_read.f.
336 Adams Solver
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.
case; Sursub for example. Doing this ensures that Adams Solver correctly distinguishes a C
Use
Calling Sequence
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)
SURSUB 337
Input Arguments
id An integer variable that provides the identifier of the SURFACE statement that is being defined
by SURSUB.
Value Description
false.
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.

list. The purpose of npar is to provide SURSUB with the number of values stored in the par
array.
338 Adams Solver
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).
SURSUB 339
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=1, IORD=2
IORD=0, IORD=0, IERR=0 or IERR=0 or
IERR=0 IERR=1 IERR=1 IERR=1
 x ( u, v )  x ( u, v ) ∂x ∂x
2 2 2
  ∂x ∂x ∂x
   y ( u, v )  ∂u ∂v
 y ( u, v )    ∂ u ∂u ∂ u ∂v ∂ v ∂v
   z ( u, v )  ∂y ∂y 2 2 2
 z ( u, v )    ∂y ∂y ∂y
 u*  ∂u ∂v
 v*  ∂ u ∂u ∂ u ∂v ∂ v ∂v
∂z ∂z 2 2 2
∂u ∂v ∂z ∂z ∂z
∂ u ∂u ∂ u ∂v ∂ v ∂v
3x1 array 5x1 array 3x2 array 3x3 array
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.
Extended Definition
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.
340 Adams Solver
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.
FORTRAN - Prototype
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
INTEGER IFLAG
C
C Outputs:
C
DOUBLE PRECISION VALUES( * )
INTEGER IERR
C
C+---------------------------------------------------------------*
SURSUB 341
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 Local Variables:
C
...
C
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
IF ( IFLAG ) THEN
C
C
Initialization call:
C
...
<perform initialization operations>
<opening files, calculating constants etc.>
...
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
...
<extrapolate surface>
<calculate x-y-z-coordinates corresponding to [u,v]
<calculate [u*,v*] on surface, closest to [u,v]>
...
C
C
Set IERR, and VALUES:
C
IERR = 1
VALUES(1) = x....
VALUES(2) = y....
VALUES(3) = z....
342 Adams Solver
VALUES(4) = u*...
VALUES(5) = v*...
ELSE
...
<calculate x-y-z-coordinates corresponding to [u,v]
<calculate [u*,v*] on surface, closes to [u,v>]
...
C
C
Set IERR, and VALUES:
C
VALUES(1) = x...
VALUES(2) = y...
VALUES(3) = z...
ENDIF
ELSEIF ( IORD .EQ. 1 ) THEN
C
C
Need matrix of 1st partial derivatives wrt. Parameters u,v:
C
...
<calculate partials of x-y-z-coordinates wrt to [u,v]>
...
C
C
Return the 3x2 matrix of partials, sorted by column
C
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
C
C
Need matrix of 2nd partial derivatives wrt. Parameters u,v:
C
...
<calculate 2nd partials of x-y-z-coordinates wrt to [u,v]>
...
C
C
Return the 3x3 matrix of partials, sorted by column
C
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:
C
CALL ERMESS (...)
ENDIF
C
RETURN
END
SURSUB 343
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
*/
struct sAdamsSurface
{
int ID;
int NPAR;
const double* PAR;
/* 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.

344 Adams Solver
UCOSUB
The UCOSUB evaluation subroutine computes a constraint value and its derivatives for a UCON statement
(f77). You must write a UCOSUB whenever one or more UCON statements are used in a dataset.
Use
UCON/id, FUNCTION=USER(r1[,...,r30])
Calling Sequence
SUBROUTINE UCOSUB (id, time, q, par, npar, idrsel,
& iflag, scalar, array, xmatrx)
Input Arguments
id An integer variable that contains the ID of the UCON statement requesting information
from UCOSUB. From the identifier, Adams Solver automatically knows other information
time.
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.
UCON statement; r1[,...,r30].
UCOSUB 345
parenthetical list. The primary purpose of npar is to provide UCOSUB with the number of
idrsel A three-element integer array containing control values for returning the proper information
through scalar, array, and xmatrx.
Value Description
When iflag is set to 3 call UCOVAR for initial definition of the principal axes variables and
do any initializations that your subroutine requires.
to false.
346 Adams Solver
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: 0 array is : No evaluation
If idresel (2) is: 1 array is : array(m) = ∂ F ( q, t )

∂ qm
2
If idresel (2) is: 2 array is : array(m) = ∂ F ( q, t )
∂ t ∂q m
If any of the elements of array are symbolically zero, they don't need to be defined.
scalar A double-precision variable for returning the residue (the error relative to zero) of the implicit
constraint expression, the nonprincipal axes variable-dependent 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.
If idresel (1) is: (scalar is: )
0 (No evaluation )
1 (scalar = F(q,t))
2 (scalar = ∂ F ( q, t ) )
∂t
2
3 (scalar = ∂ F ( q, t )
2
∂t
4 (scalar = f(t))
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):
If idresel (3) is: (xmatrx is: )
0 (No evaluation )
2
∂
1 (xmatrx(m,n) = F 9 ( q, t ) )
∂ q n ∂q m
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.
UCOSUB 347
Extended Definition
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 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).
348 Adams Solver
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.
 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 not zero, 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 zero.
Structure
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 )
INTEGER IFLAG
DOUBLE PRECISION SCALAR
DOUBLE PRECISION ARRAY( 30 )
DOUBLE PRECISION XMATRX( 30, 30 )
C
C ID Identifier of calling UCON statement
C TIME Current time
C Q Array of part state variables
C IDRSEL UCON values selection control flag
UCOSUB 349

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
IF( IFLAG ) THEN
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 Your algorithm
C
...
C
C Assign scalar
C
SCALAR = ...
C
C - First time derivative of constraint relation --
C
ELSE IF ( IDRSEL(1) .EQ. 2 ) THEN
C
C Your algorithm
C
...
C
C Assign first time derivative to scalar
C
SCALAR = ...
C
C - Second time derivative of constraint ------
C
relation
C
350 Adams Solver
C
C Your algorithm
C
...
C
C Assign second time derivative to scalar
C
SCALAR = ...
C
C - Nonprincipal-axes-dependent portion of ----
C
constraint relation
C
C
C Your algorithm
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 Your algorithm
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 Your algorithm
C
...
C
C Assign array values
C
ARRAY(1) = ...
...
UCOSUB 351
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 Your algorithm
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.
352 Adams Solver
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.
case; Varsub for example. Doing this ensures that Adams Solver correctly distinguishes a C
Use
Calling Sequence
CALL VARSUB(id, time, par, npar, dflag, iflag, value)
VARSUB 353
Input Arguments
id An integer variable that contains the ID of the VARIABLE statement requesting information
from VARSUB. From the identifier, Adams Solver automatically recognizes other
information (such as the par argument) that is available in the corresponding statement.
time.
VARIABLE statement.
parenthetical list. The primary purpose of the npar argument is to provide VARSUB with the
dflag A logical variable that Adams Solver sets to true when it calls VARSUB to evaluate the partial
false.
Value Description
false.
Output Arguments
354 Adams Solver
value A double-precision variable that returns the value of the variable.
Extended Definition
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).
The SYSARY and SYSFNC utility subroutines automatically set functional dependencies when the VARSUB
argument iflag is not zero. To compute solutions efficiently, Adams Solver must know the other variables on
which each user-defined variable depends. Adams Solver determines these functional dependencies at the
beginning of the simulation by calling 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.
VARSUB 355
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 user-defined VARIABLE statement. These results
usually cause large increases in execution time.
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 zero 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
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.
FORTRAN - Prototype
A sample structure for VARSUB is shown next. The comments explain how the subroutine works.
& IFLAG, VALUE )
C
C
C
C
INTEGER ID
INTEGER NPAR
LOGICAL DFLAG
INTEGER IFLAG
C
C TIME Current time
356 Adams Solver

C
C
...
C
C
C
...
C
C calculations below. Note: if IFLAG is true, these
C
CALL SYSFNC ( ... )
C
CALL ERRMES ( ... )
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 Your algorithm
C
...
C
C
VALUE = ...
C
RETURN
END
C Style - Prototype
typedef void adams_c_VARSUB(const struct sAdamsVariable* variable,
double TIME, int DFLAG, int IFLAG, double* RESULT);
/*
VARSUB 357
* VARIABLE
*/
struct sAdamsVariable
{
int ID;
int NPAR;
const double* PAR;
double IC;
};
Examples
For an example of this subroutine, see varsub.f.
358 Adams Solver
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.
case; Vfosub for example. Doing this ensures that Adams Solver correctly distinguishes a C
Use
Calling Sequence
SUBROUTINE VFOSUB (id, time, par, npar,dflag, iflag, result)
Input Arguments
id An integer variable that contains the ID of the VFORCE statement requesting information
from VFOSUB. From the identifier, Adams Solver automatically recognizes other
time.
par A double-precision array of constants taken in order from the USER parenthetical list of
the VFORCE statement.
VFOSUB 359
parenthetical list. The primary purpose of the npar argument is to provide to VFOSUB the
dflag A logical variable that Adams Solver sets to true when it calls VFOSUB to evaluate the
argument to false. See Using the DFLAG Variable.
Value Description
SYSFNC utility subroutines that are made to compute the value of the user-defined
variable. If iflag is 0, Adams Solver computes the value of the user-written variable.
Note: In simple subroutines where serializing data is not needed, you can declare iflag
as a logical variable. In this case you declare your dependencies when Adams
Solver sets iflag to true, and compute the subroutine's value when Adams Solver
sets iflag to false.
Output Arguments
result A double-precision array that returns the three values of the VFORCE components, in x-y-z
order.
Extended Definition
You can usually use the VFORCE statement with function expressions to define the three components of a
translational vector force at a point. However, if the force expressions become lengthy and awkward or require
external computations, it may be necessary to use a VFOSUB. If the algorithms use or consist of already-
existing FORTRAN-77 subroutines, VFOSUB can be made to call them.
360 Adams Solver
You can call utility subroutines, such as AKISPL, CUBSPL, SYSARY, and SYSFNC, from VFOSUB to
obtain information about system variables, user-defined variables, and splines. (See AKISPL, CUBSPL,
SYSARY, and SYSFNC).
The SYSARY and SYSFNC utility subroutines automatically set functional dependencies when the VFOSUB
argument iflag is not zero. For Adams Solver to compute solutions efficiently, it must know on which other
variables each user-defined variable depends directly. Adams Solver determines these functional dependencies
at the beginning of the simulation by calling VFOSUB with the argument iflag set to not zero. During each
call to VFOSUB, Adams Solver records which calls you make to SYSARY and SYSFNC and assumes that the
resulting values are dependent only on those Adams Solver variables accessed through the SYSARY and
SYSFNC calls.
Caution:  When the iflag argument is not zero, you must make all the calls to SYSARY and SYSFNC
as are made to compute the component values of the VFORCE. This ensures that Adams
Solver has the proper functional dependencies. In general, failure to account for
dependencies in the VFORCE components can make it difficult for Adams Solver to
converge to a solution and/or can force Adams Solver to take small integration steps. Both
of these effects usually cause large increases in execution time.
 When the iflag argument is not zero, SYSARY and SYSFNC return zero values.
Computations that divide by these values result in fatal errors when you execute Adams
Solver. You should check for nonzero values or ensure that the iflag argument is set to zero
before dividing by these values.
FORTRAN - Prototype
A sample structure for VFOSUB is shown next. The comments explain how the subroutine works.
SUBROUTINE VFOSUB(ID, TIME, PAR, NPAR, DFLAG,
& IFLAG, RESULT)
C
C
C
INTEGER ID
INTEGER NPAR
LOGICAL DFLAG
INTEGER IFLAG
VFOSUB 361
C
C ID Identifier of calling VFORCE statement
C TIME Current time
C RESULT Array (dimension 3) of computed VFORCE
C
C ...
C
C
C
...
C
C the calculations below. Note: if IFLAG is true, these
C
CALL SYSFNC (...)
C
C
CALL ERRMES (...)
C
C
...
C
IF (IFLAG) THEN
C
C
...
C
ENDIF
C
C - Evaluate VFORCE components ------------
C
C Your algorithms
C
...
C
C
RESULT(1) = ...
RESULT(2) = ...
RESULT(3) = ...
C
362 Adams Solver
RETURN
END
C Style - Prototype
typedef void adams_c_VFOSUB(const struct sAdamsVforce* vfo, double
/*
* VFORCE -------------------------------------------------
----------------
*/
struct sAdamsVforce
{
int ID;
int NPAR;
const double* PAR;
int I;
int JFLOAT;
int RM;
};
Examples
For an example of this subroutine, see vfosub.f.
VTOSUB 363
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.
case; Vtosub for example. Doing this ensures that Adams Solver correctly distinguishes a C
Use
Calling Sequence
SUBROUTINE VTOSUB(id, time, par, npar, dflag, iflag, result)
Input Arguments
id An integer variable that contains the ID of the VTORQUE statement requesting information
from VTOSUB. From the identifier, Adams Solver automatically recognizes other
VTORQUE statement.
364 Adams Solver
parenthetical list. The primary purpose of the npar argument is to provide VTOSUB with the
dflag A logical variable that Adams Solver sets to true when it calls VTOSUB to evaluate the partial
false.
Value Description
false.
Output Arguments
result A double-precision array of length 3 that returns the x-, y-, and z-components of the
VTORQUE.
Extended Definition
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.
VTOSUB 365
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.
The SYSARY and SYSFNC utility subroutines automatically set functional dependencies when the
VTOSUB argument iflag is not zero. 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 not zero. 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.
values returned by these may contain discontinuities. To avoid the discontinuities, use the
coordinate system that does not encounter a singularity.
Caution:  When the iflag argument is not zero, 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 execution time.
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 zero before dividing by these values.
FORTRAN - Prototype
A sample structure for VTOSUB is shown next. The comments explain how the subroutine works.
SUBROUTINE VTOSUB(ID, TIME, PAR, NPAR, DFLAG,
& IFLAG, RESULT)
C
C
C
INTEGER ID
INTEGER NPAR
366 Adams Solver
LOGICAL DFLAG
INTEGER IFLAG
C
C ID Identifier of calling VTORQUE statement
C TIME Current time
C RESULT Array (dimension 3) of computed VTORQUE
C
C
...
C
C
C
...
C
C the following calculations. Note: if IFLAG is true, these
C
CALL SYSFNC (...)
C
C
CALL ERRMES (...)
C
C
...
C
IF (IFLAG) THEN
C
C
...
C
ENDIF
C
C - Evaluate VTORQUE components ------------
C
C Your algorithms
C
...
C
C
RESULT(1) = ...
VTOSUB 367
RESULT(2) = ...
RESULT(3) = ...
C
RETURN
END
C Style - Prototype
typedef void adams_c_VTOSUB(const struct sAdamsVtorque* vto, double
/*
* VTORQUE -------------------------------------------------
----------------
*/
struct sAdamsVtorque
{
int ID;
int NPAR;
const double* PAR;
int I;
int JFLOAT;
int RM;
};
Examples
For an example of this subroutine, see vtosub.f.
368 Adams Solver
Adams Solver Examples 1
Adams Solver Examples

The following examples are available:
 For examples of Adams Solver features, see Simcompanion Knowledge Base Article KB8015965.
 To see the Adams Verification Guide, refer to Simcompanion Knowledge Base Article KB8018831.
2 Adams Solver
Adams Solver C++ vs. FORTRAN 1
Introduction
Adams Solver C++ vs. FORTRAN

Introduction
This document presents a comparison of Adams Solver C++ with Adams Solver FORTRAN. The first section
highlights the advantages (in modeling and simulation) of the C++ version over the FORTRAN version. The
second section presents a set of tables with a side-to-side comparison of statements, commands, functions and
utility subroutines. The final section briefly describes some special topics about the C++ version.
 Advantages of Adams Solver C++
 Side-to-side C++/FORTRAN comparison
 Special Topics about the Adams Solver C++
The Adams Solver C++ solver was built by following a modern object-oriented view. The C++ code was not
built by following a direct translation from the FORTRAN code; it was designed by following the same
algorithms and enhancing some existing data structures used by the FORTRAN solver.
Advantages of Adams Solver C++

Overall, the Adams Solver C++ provides almost identical modeling and simulation capabilities found in the
FORTRAN solver. Minor differences are described in this section.
However, Adams Solver C++ provides several additional modeling and simulation capabilities not found in
Adams Solver FORTRAN.
Modeling capabilities found only in the Adams Solver C++

This is partial list of the most important modeling capabilities found only in the C++ solver.
1. BEAM and FIELD objects.
These forcing massless objects support an optional geometrically non-linear formulation. This option
improves the numerical results when the objects experience large axial loads.
2. Flexible body contact.
Flexible-rigid and flexible-flexible contact are supported.
3. Flexible body dynamic limit.
This option stabilizes the simulation by ignoring high frequency modes.
4. Multiple-node and no node location for MARKERs on flexible bodies.
MARKERs on flexible bodies can be located at arbitrary positions with multiple node IDs or no node
ID specified. A marker with no node ID undergoes only rigid body motion of the flex body. A marker
with multiple node IDs undergoes motion that is a weighted average of the motion on the nodes. The
weight is based on the proximity of the marker position to the node.
5. Floating MARKER support on flexible bodies.
2 Adams Solver
J floating markers from force elements can be specified on flexible bodies.

6. More general MFORCE definition.
FORTRAN solver only allows linear expressions.
7. Generalized constraints.
GCONs allow creating user-defined constraint equations easily.
8. Curve and Surface MARKERs.
New MARKER definitions on Curves and Surfaces allow crating complex constraint equations.
9. Richer set of symbolic expressions.
Three-dimensional expressions, AO expressions, unit vectors, delay expressions, clearance expressions
and so on, are supported.
10. Exact partial derivatives in user-written subroutines.
Users may provide exact partial derivatives to speed up the simulation and improve the numerical
results. FORTRAN solver only supports numerical differencing.
11. Implicit GSEs.
Users may specify implicit equations in GSE objects. FORTRAN solver only support explicit
equations in GSE objects.
12. MOTION expressions depending on any state.
This feature allows creating a richer set of expressions for constraints.
13. DELAY function.
The DELAY function allow user to define delay differential equations in their models.
14. Clearance measures.
A set of functions for creating expressions to observe the gap between to geometric bodies during the
simulation.
15. Native finite elements.
The FE_PART statement defines finite element beam elements using the ANCF formulation. These
beam elements have distributed mass and contribute to the equations of motion.
16. Co-simulation Modeling
A co-simulation modeling interface is available to connect Adams model to external models from
other simulation products like Marc, EDEM and so on. using co-simulation techniques.
Simulation capabilities found only in Adams Solver C++

This is a partial list of the main simulation capabilities found only in the C++ solver.
1. Exact linearization algorithm.
The C++ solver implements a state-of-the-art exact linearization algorithm that uses no numerical
differentiation but a closed-form algorithm to find the minimal state-space representation putting the
equations of motion into an ODE form. This algorithm was extended to support user-defined
linearization states. This algorithm works in static and dynamics cases as well. The FORTRAN solver
implements an algorithm with no user-defined states support and provides good results only in static
cases.
2. Exact GTCMAT computations.
Based on an exact linearization algorithm, the GTCMAT computation in the C++ solver computes
results also during a dynamic simulation.
3. Adams Controls.
When using Adams Controls, the C++ solver offers an additional bisection method in the System
Import option.
4. SIMULATE/SETTLE.
The C++ solver offers a settle simulation. The settle simulation command solves for all differential
states (keeping all other states constant) to find all time derivatives (of the differential states) equal to
zero. In a few words, given:
T
Mq·· + Φ q λ = f
Φ = 0
z· = g ( z, q, t )
find z (keeping q constant) such that
z· = 0
5. Delay differential equations.
Using the DELAY function, users can create and simulate Delay Differential Equations. Users can
define variable delays depending on any state. For example:
T
Mq·· + Φ q λ = f
Φ = 0
z· = g ( z, z ( t – τ ), q, t )
τ = τ ( q, z, t ) ≥ 0
6. HHT and NEWMARK integrators.
The C++ solver offers two integrators with proven efficiency for a class of models. Model having large
flexible bodies usually benefit from these two integrators.
7. Activation and deactivation extensions.
A wider set of objects can be activated or deactivated using the C++ solver.
4 Adams Solver
Side-to-side C++/FORTRAN comparison
8. UMF package.
The C++ solver has options to use the UMF linear algebra package. This option is especially useful
with large models.
9. SAVE/RELOAD extensions.
The C++ solver offers the option to save to a buffer in memory.
10. Multithreaded execution.
Three multithreaded subsystem are available: the Jacobian evaluation, the LU numeric factorization,
and the results generation. The Jacobian evaluation is triggered by using the NTHREAD option in
the PREFERENCES statement. The parallel LU factorization is triggered by setting the environment
variable MSC_ADAMS_PARALLEL_CALAHAN. The parallel results generation is standard in the
stand-alone version only.
11. Multithreaded execution of user-written subroutines.
Users have utilities to set parallel execution of user-written subroutines.
12. CBKSUB user-written subroutine.
The callback subroutine (CBKSUB) is meant for advanced users writing numeric-intensive user-
written subroutines.
13. Adams-to-Nastran export.
The Adams-to-Nastran export is chaining tool that creates an equivalent MSC Nastran linear model
at any operating point. The exported files are fully editable and ready for SOL107 and SOL108,
14. Co-simulation
A tool called Adams Co-Simulation Interface (ACSI) and MSC COSIM are available to setup and
co-simulate Adams models with external simulation codes like MSC Marc and EDEM.
15. Real Time Simulation with Fixed Step Integrator
Real time simulations with fixed step integrator performed on real time operating systems.

The following tables show a side-to-side comparison of statements, commands, functions and subroutine
options available only in one code.
Statements comparison
STATEMENT C++ FORTRAN

BEAM Geometrically nonlinear formulation available N/A
CONTACT Flexible-flexible contact available N/A
CLEARANCE Distance between two or more geometries N/A
ENVIRONMENT Utility to set environment variables N/A
STATEMENT C++ FORTRAN

EQUILIBRIUM N/A Dynamic option to find static
equilibrium
FE_PART Finite element beam elements natively N/A
supported
FIELD Geometrically nonlinear formulation available N/A
GSE Implicit equations support N/A
FLEX_BODY Dynamic limit, stability, DB_FILE, N/A
representation, and BDF_FILE, number of
threads, FEA_MEM_SETTINGS,
BUFFER_SIZE and
COMPUTE_RESOURCE for nonlinear finite
element simulations.
GCON Generalized user-defined constraint N/A
INTEGRATOR HHT, NEWMARK options. N/A
FIXIT, HRATIO and MAXERR options for N/A
fixed step integration.
N/A CONSTANT_BDF, ABAM,
RKF45
LSOLVER UMF package support N/A
MARKER Support for curve and surface MARKERs N/A
Support for specifying multiple or no N/A
NODE_ID.
MFORCE Nonlinear definitions available N/A
MOTION Function depending on any state N/A
PART Support for 2D PARTs N/A
PREFERENCES Additional options N/A
PSTATE Support for defining user-defined linearization N/A
states
SURFACE Surface definition N/A
UCON N/A User-defined constraint
6 Adams Solver
Commands comparison
COMMAND C++ FORTRAN

ACTIVATE More options available N/A
DEACTIVATE More options available N/A
ENVIRONMENT Utility to set environment variables N/A
GCON User-defined constraints N/A
LINEAR More options like RM, PSTATE, N/A
EXPORT
LSOLVER Option to select UMF
PART Option to set the products of inertia N/A
RELOAD Option to reload from a buffer in memory N/A
SAVE Option to save to a buffer in memory N/A
SIMULATE Settle simulation option N/A
UCON N/A Option to redefine a user-defined
constraint
Function comparison
FUNCTION C++ FORTRAN

ACCXYZ 3D acceleration N/A
AO Isolates expression from reaction force in N/A
GCON
*CLEAR* Set of measures for CLEARANCE N/A
statement
DELAY Defines a delay differential equation N/A
DXYZ 3D position N/A
FXYZ 3D force N/A
NJAC Utility. Number of Jacobian evaluations N/A
NRHS Utility. Number of right-hand side N/A
evaluations
ORDER Utility. Returns current integration order. N/A
Q Modal position N/A
QDDOT Modal acceleration N/A
QDOT Modal velocity N/A
FUNCTION C++ FORTRAN

TXYZ 3D torque N/A
UV Unit vector N/A
UVX X component of unit vector N/A
UVY Y component of unit vector N/A
UVZ Z component of unit vector N/A
VXYZ 3D velocity N/A
WDTXYZ 3D angular acceleration N/A
WXYZ 3D angular velocity N/A
Utility subroutines comparison
UTILITY SUBROUTINE C++ FORTRAN

ADAMS_DECLARE_THREAD_ Allows multiple threads to access N/A
SAFE user-written subroutines
ADAMS_SMP_GROUP Allows multiple threads to access N/A
user-written subroutines
CBKSUB Callback subroutine. Informs user N/A
about milestones.
GTCMAT Allowed to be called from all Limited to static/quasistatic
simulation types simulations.
SYSPAR Provides analytical partials from Limited to GSE only.
within user-written subroutines
UCOVAR N/A Used by UCOSUB
GSE_SET_IMPLICIT Allows defining implicit GSE N/A
UCOSUB N/A Used to define user-written
subroutines.
Other differences
Other differences include:
1. The C++ solver computes the Jacobian and right-hand-entries of all matrices using symbolic
computer algebra. The FORTRAN solver uses numerical differencing.
2. PART command in the C++ solver will generate a Jacobian refactorization.
3. FLEX_BODY's invar2 and invar3 are identically zero in the C++ solver. This means the formulation
of the equations of motion for flexible bodies are different.
8 Adams Solver
Special Topics about the Adams Solver C++
4. YPR and Euler measures in results may be different in both solvers but they define the same
orientation.
5. The C++ solver does not generate an *.out file.
6. There are differences in the wording and structure of the *.msg file.
7. The LINEAR command behaves differently. History rules have been relaxed to provide a more
analytical approach in the C++ solver.
8. Velocity reconciliation is done iteratively in the C++ solver. Given that GCONs can be used to create
velocity constraints, the reconciliation solution is no longer a linear problem, hence the solution is
iterative.
9. In the C++ solver, numerical differencing of user-written subroutines is done by perturbing the
measures and using the chain rule. The FORTRAN solver perturbs the states when computing partial
derivatives.
10. The C++ solver accepts a new signature in all use-written subroutines where the IFLAG parameter is
of type INTEGER (FORTRAN) or int (C++) instead of BOOLEAN (F77).
11. The solution sequences implemented in the C++ solver are in general not identical to the ones
implemented in the FORTRAN solver. One such difference is related to the number of equations in
the assembly of the equations of motion for the dynamic simulations. In dynamic simulations, the
FORTRAN solver defines additional equations labelled momenta equations in order to make the
system sparser. The C++ solver does not create momenta equations by default. Users may set the
environment variable MSC_ADAMS_USE_MOMENTA to mimic the FORTRAN solver's
behavior.

This section provides another view of the Adams Solver C++ highlighting special features not found in Adams
Solver FORTRAN.
Linearization
Linearization in the C++ solver is implemented using an exact algorithm that requires no numerical
differencing. The linearization is exact in the sense that no simplifications are done on the equations of
motion. All nonlinear effects of the motion (gyroscopic effects, Coriollis effects) due to velocities are taken
into account exactly. The linearization can be done at any operating point.
Historical rules have been modified a bit. For example, when using the FORTRAN solver, the following
simulation commands at time t=0:
simulate/statics
linear/eigensolution
will trigger the following behavior. First, after the statics simulation is finished (at time t=0), the velocities
found in the *.adm file (the dataset file) will be restored. Second, the ongoing linearization command will
reuse the Jacobian from the previous static simulation.
On the other hand, when using the C++ solver, the user has the option to stop restoring the velocities at time
t=0. Moreover, the linearization does not reuse an old Jacobian but it will trigger a reconciliation if necessary.
This reconciliation done by the C++ solver is required to bring the model to a consistent state. Typically, the
reconciliation is done if the velocities were restored or if there were differential states having the
STATIC_HOLD option.
Probably the main feature of the linearization in the C++ solver is the ability to linearize the system in terms
of user defined states.
Figure 1 A rotor-stator model and topology diagram.
The model shown in Figure 1 is simple rotor-stator model where the Base object is fixed to GROUND. Figure 2
shows a plot of the eigenvalues versus the rotational speed of the rotor. The plot on the left was made using
global linearization coordinates while the plot on the right was created using relative coordinates (using a
PSTATE or RM options in the LINEAR command).
10 Adams Solver
Figure 2 Eigenvalues versus rotational speed computed using global and relative coordinates.
While the values in Figure 2 can be verified either analytically or by building a physical prototype, a numerical
approach is feasible by instrumenting the numerical model as shown in Figure 3 below.
Figure 3 Instrumented numerical model
The instrumented numerical model is then subject to a dynamic simulation and the signals DX(4,1,1),
AY(4,1) and DX(2,4) shown in Figure 3 can be obtained and post processed using an FFT tool.
Figure 4 FFT plots compared with LINEAR results
Figure 4 shows the FFT results where an exact match between numerical and LINEAR results match.
12 Adams Solver
Flexible Body Contact

Flexible body contact in the C++ solver implements a native flexible-to-flexible contact algorithm. There is
no need to create MFORCE to model contact interactions. All the required information to handle the contact
is obtained from the Modal Neutral File (MNF); this information includes the geometric information
required to handle the geometry intersections.
The flexible-to-flexible contact implementation supports both solids and shell elements.
GCONs
The GCON statement in the C++ solver permits the creation of user-defined constraint equations. GCONs
can be used to mimic standard joints or to create special constraint equations not supported by the
MOTION, JOINT and JPRIM statements.
All the existing constraint objects in the C++ solver are implemented as GCONs. For example a SPHERICAL
JOINT will create three GCONs equations automatically.
GCONs can be used to create non holonomic constraints.
CBKSUB
The CBKSUB (callback subroutine) was created for advanced users to help optimizing the execution of user-
written subroutines. The CBKSUB is optional. If the user defines a CBKSUB, then Adams Solver C++ will
call the provided subroutine at specified milestones during the code execution.
Milestones examples are: the end of reading the model, the start of an iteration, the start of a new time step,
the end of a dynamic simulation, the shutdown process and so on.
The main feature of the CBKSUB is to allow the user have a clear control of the code execution in order to
allocate memory in his/her user-written subroutines. Another important use of the CBKSUB is to use it as
place to cache intermediate results.
The CBKSUB allows the user to make calls to SYSFNC and SYSARY subroutines without creating
dependencies.
Figure 5 and Figure 6 below show a simplified architecture of the calling sequence of the CBKSUB.
Figure 5 Architecture without CBKSUB.

14 Adams Solver
Figure 6 Architecture with the CBKSUB.
Notice that Figure 5 and Figure 6 show a simplified version of the Adams Solver code. Also, not all milestones
are shown. Profiling tests show that the overhead of calling the CBKSUB is negligible.
Adams-to-Nastran Export
The Adams-to-Nastran utility is available under the LINEAR command. The tool generates and exports a
fully editable Nastran data deck equivalent to the Adams model. Figure 7 below shows such a translation.
Figure 7 Adams-to-Nastran example
The Nastran model shown on the right of Figure 7 is created automatically and it is ready for a SOL107
solution in Nastran. Tests show eigenvalues computed by Nastran and Adams match surprisingly well (see
Figure 8 below).
16 Adams Solver
Figure 8 Eigenvalues comparison Adams versus Nastran.
In general, Adams-to-Nastran export can save considerable man power when chain simulations are required.
FE_PART
Starting version Adams 2014, Adams Solver C++ implements natively (fully implemented in Adams) finite
elements with distributed mass. Some of the main features of this element are:
1. Elements use ANCF technology mixed with Timoshenko beam theory.
2. Geometrically large displacements are supported.
3. Contact support.
4. Allows user to put MARKERs on the elements and attach forces or constraints.
5. Full pre and post processing support
6. Curve isoparametric formulation.
7. Variable twisting cross section properties.

8. Support for defining distributed loads.
9. Linear material implementation supporting elastic, orthotropic and anisotropic options.
High Performance Computing

The C++ solver has a set of subsystems implementing High Performance Computing (HPC) using
multithreading (SMP). The multithreading code is written using the Pthreads API (POSIX) and OpenMP.
Among the parallelized subsystem there is the parallel Jacobian evaluation, parallel linear algebra and parallel
results generation. Other subsystem use threading pools for other chores.
Thread Affinity Settings in Adams

Overview
There is no consensus on a standard nomenclature regarding hardware components found in common
desktop computers used in research and engineering. Therefore, in this section, terms like CPU, PU, core,
socket, node, logical CPU, will follow the nomenclature used by the Portable Hardware Locality (hwloc)
software package [1].
This section will cover a diverse set of subjects like hardware architecture, operating system scheduler, thread
affinity, sockets, hyperthreading and so on, all of which are required in order to make the best decision
regarding affinity settings for a simulation job. Brief notes on thread priorities are also included.
Since 2005, Adams Solver C++ supports the PREFERENCES/NTHREAD option to define the number of
parallel threads (multithreading) to be used for the numerical simulations. Multithreading algorithms were
designed and implemented to execute diverse tasks like the assembly of the equations, matrix manipulations,
asynchronous output and so on. However, Adams Solver C++ relied completely on the operating system's
scheduler for the thread affinities. Thread affinity is defined as the location (the CPU) where the thread is
running. The operating system's scheduler is a module that has the task of assigning the affinity of all running
threads in the machine. (Among other chores, the scheduler decides which thread runs when.)
By default, if there is no software or user intervention, the OS scheduler will completely determine the affinity
of a running thread. Notice the affinity may be a single CPU or it may be a set of CPUs (an affinity set);
moreover, the thread's actual affinity may be changing in time. The scheduler is free to change the location
of a thread at any time. Notice most operating systems do provide tools for the user to intervene and define
the affinity set of a running application. See, for example, the taskset command in linux. If there is
intervention, the scheduler will confine a thread to a single CPU or to a defined set of CPUs depending on
the commands issued by the user.
Regardless whether there was user intervention or not, the affinity of each thread will in general depend on
the whims of the scheduler (the actual algorithm used by the OS), the load on the machine (for example,
network traffic), and the thread priority.
The thread priority can be one of two main types: normal priority and real time priority. All operating systems
provide variations of those two main types. If there is no intervention, all applications and their running
threads will run using a default priority managed by the operating system. Some applications, for example,
18 Adams Solver
Simulation Workbench [2], run using real time priorities, and they do launch other applications (for
example, Adams Solver C++) with real time priorities as well. Users need nothing to do regarding thread
priorities when using Adams Solver C++ in real time simulations and in most standard cases.
Adams Solver C++ does not provide tools to set the priority of its threads. You may, however, run Adams
Solver C++ using real time priorities in any standard computer environment provided you have the
permissions and the operating system support. For example, see the chrt command in linux for more details.
Adams Solver C++ does provide a way to define the affinity set for the Adams process via an environment
variable or FMU fixed parameter. It requires a basic knowledge of the machine architecture and some basic
concepts of the operating system. More details on these are found later in this section. Using this variable or
parameter, Adams Solver C++ will intervene at the software level to modify the affinity of its threads.
Hyperthreading and Logical CPUs

Before circa 2001, desktop computers had only one Central Processing Unit (CPU) and the terms CPU and
core were used interchangeably. Figure 9 shows a basic diagram of a CPU at that time. The Arithmetic Logic
Unit (ALU) and the Registers interact with the Bus interface that connects the CPU with the rest of the
computer, for example, the memory.
Figure 9 Before circa 2001. CPU and core are synonyms.
Although desktop computers at that time were equipped with a single CPU, multithreading was already
enabled and popular. Graphical interfaces were already blooming due to the operating system's capability to
support multiple execution threads. The job of the scheduler was to manage all running threads to provide
them with a time allocation to run on the single available resource. However, around 2001, a new chip design
allowed a CPU to have two sets of Registers sharing the same ALU as shown in Figure 10. Using this new
technology, two threads (or processes) could be running almost independently provided one thread was not
using the ALU.
Figure 10 Hyperthreading enabled chip (circa 2001).
Notice however, the performance of hyperthreading is small or negligible for heavy computational tasks that
require frequent use of the ALU, for example, numerical simulations. For other types of applications,
hyperthreading does provide a clear performance gain, for example, graphical interfaces.
Hyperthreading required the creation of the term logical CPU. A logical CPU, a.k.a. Processor Unit (PU), is
the current definition used to refer to an execution capable unit. A logical CPU is the smallest entity that can
run an execution thread. Besides the creation of the term logical CPU (or PU), the term core was redefined
as a set of either 1 or 2 logical CPUs, depending whether hyperthreading is enabled or not. Figure 11 shows a
core with hyperthreading enabled. Notice logical CPUs started to be numbered.
Figure 11 Logical CPU or PU.
Users should keep in mind that hyperthreading is a configurable feature. A hyperthreading capable computer
can be re-configured (at the BIOS level) to disable the hyperthreading capability.
20 Adams Solver
Multicore Machines
Around circa 2002, new desktop computers began to include several cores (multicore machines). Suitably,
the term socket was introduced to mean a set of cores. The term core continued to define a set of 1 or 2 logical
CPUs. Cores started to be numbered as well. Figure 12 shows on the left the case of a multicore machine with
4 cores and hyperthreading enabled; on the right we observe the case of machine with hyperthreading
disabled.
Figure 12 Two multicore machines.
There are two important facts to remember. The first one is that operating system tools use the term CPU to
mean logical CPUs. Second, the logical numbering of the CPUs (for example, PU#0, PU#1 and so on) is
completely arbitrary and depends on both the OS and the BIOS. For example, Figure 13 shows a computer
that has PU#0 and PU#1 not located on the same core; compare it with the computer shown in Figure 12 (a)
which has PU#0 and PU#1 located on the same core.
Figure 13 Logical CPUs have arbitrary numbering.

The arbitrary numbering of logical CPUs is of outmost importance when selecting the affinity set to run
Adams Solver C++. For example, assuming the user runs Adams Solver C++ with 4 threads using the machine
shown in Figure 12 (a), an optimal affinity set would be "0, 2, 4, 6". That selection guarantees that only one
thread runs per core. Running the same model on the machine shown in Figure 13, an optimal set would be
"0, 1, 4, 5". Clearly, the arbitrary numbering of logical CPUs is not an issue if hyperthreading is disabled. See
next section for other issues related to affinity sets in machines with multiple sockets.
The fact that hyperthreading is not beneficial for heavy computational tasks, can also be observed when using
third party tools like the Intel MKL Pardiso (numerical algebra solver tool) [3]. Pardiso will ignore
hyperthreading and will cap the number of threads to the number of cores.
NUMA Controllers
Following a natural progression, after circa 2002, multi socket computers were introduced in the market.
Figure 14 shows one such a computer having two sockets. Sockets started to be numbered. Each socket has a
NUMA controller (a.k.a. NUMA node). NUMA controllers are the interface of each socket with the main
memory of the machine.
Figure 14 A machine with 2 sockets, 4 cores per socket and hyperthreading enabled.
A most important fact for users is that threads have lower latency accessing memory data managed by the
corresponding NUMA node than accessing memory data managed by another NUMA node. For example,
referring to Figure 14, a thread running on PU#6 will get a faster response for memory allocated by NUMA#0
than for memory allocated by NUMA#1. Therefore, the optimal affinity set for Adams Solver C++ is a set of
logical CPUs belonging to the same NUMA node.
Recapitulating, affinity settings allow users to define the set of logical CPUs where the Adams Solver C++ will
run its threads. For optimal performance, that set must be carefully defined to have one logical CPU per core,
22 Adams Solver
and the set must belong to the same socket. You still may define additional CPUs from other sockets, but the
performance gain may not be as expected.
Moreover, not all sockets run equally fast. Other third-party software vendors have confirmed this same
observation: running a process in one socket may be 3% slower than running the same process in another
socket. A possible explanation is the asymmetry of the hardware or that the load of the operating system favors
one socket more than the other.
Tools to Examine Hardware Topology

All operating systems offer tools to examine the machine's topology. For example, the command lscpu in linux
Red Hat 7.3 prints a report as shown in Figure 15.
Figure 15 Tools to examine the hardware topology
Here, CPU(s) stand for the number of logical CPUs. The number of logical CPUs per core is reported as
Thread(s) per core because it is equivalent to the number of threads that can be run on one core. Accordingly,
the value is either 1 or 2. If the value is 2, hyperthreading is enabled. The command also displays the number
of cores per socket and the number of sockets in the machine.
The Portable Hardware Locality (hwloc) is a free tool including utilities that can display the machine's
topology in a graphical form (hwloc comes included in some linux distributions). Figure 16 shows the
graphical output of hwloc's lstopo on a small Windows laptop. Notice the machine has 1 socket, 4 cores per
socket, and 2 logical CPUs per core (hyperthreading enabled). The operating system of this machine reports
a total of 8 CPUs (logical CPUs).
Figure 16 lstopo output for a small laptop computer.
Figure 17 shows the lstopo graphical output on a small linux desktop computer. That computer has 2 sockets,
6 cores per socket, and 1 logical CPU per core (hyperthreading disabled). The operating system of this
machine reports a total of 12 CPUs (logical CPUs).
24 Adams Solver
Figure 17 lstopo output for a small desktop computer.
Figure 17 also shows an interesting fact: some cores may be disabled. Notice cores 1-5 and 7-8 are not displayed
in the topology view of the machine. Regardless of disabled cores, the numbering of the logical CPUs is
always consecutive and starting at zero.
Terminology and Important Facts for Adams Affinity Settings

Setting the affinity for Adams Solver C++ requires the user to know the basis of hardware topology and to
have a basic understanding of the role of the operating system. To help in that regard, Table 1 below lists basic
terminology used in this document.
Table 1 Useful hardware and OS terminology
Term Definition
Computer As set on NUMA nodes (or sockets)
NUMA node Memory controller for a socket
Socket A set of cores
Core A set of 1 or 2 logical CPUs. A core has 1 Arithmetic Logic Unit (ALU) and 2
Processing Units (PUs). See Figure 11.
Logical CPU Smallest processing unit (PU) capable to run a thread of execution. Operating
systems call them just CPUs.
Hyperthreading Configurable feature to run two execution threads in a single core.
Term Definition
Scheduler Operating system module in charge of determining when a thread (or process)
runs, and where it runs.
Affinity The logical CPU where a thread (or process) runs. If there is no user
intervention, the affinity of a thread may change at run time at the whims of
the scheduler.
Affinity set A set of logical CPUs. Adams Solver C++ allows users to define a set of logical
CPUs for the process. The operating system provides tools to set the affinity.
Table 2 lists a set of important facts related to affinity settings.
Table 2 Useful facts regarding affinity settings
Context Important fact

Hyperthreading It is configurable, it can be disabled at the hardware level.
Hyperthreading Provides a performance boost in many cases except in heavy numerical
computations.
Affinity set For optimal performance, if hyperthreading is enabled, select one logical CPU
per core.
Affinity set For optimal performance, the logical CPUs must belong to the same socket.
Affinity set You may select logical CPUs from different sockets, but performance would
not be as good as if all CPUs belong to the same socket.
Affinity set All logical CPUs are numbered consecutively starting at zero. Numbering of
physical units is arbitrary.
Socket Running a process in one socket may be slower than running the same process
in another socket.
Socket Some sockets may have disabled cores.
Affinity Settings in FMI Real Time Environments

FMI real time environments are becoming the default standard for users to run real time simulations. Adams
Solver C++ allows creating FMU models to run in FMI real time environments like Simulation Workbench
[3] or SCALEXIO [4]. Real time environments have restrictions on CPU usage hence there is the
requirement to set the affinity of running processes.
Given that real time environments make exclusive use of some logical CPUs for the OS to work, it is the user's
responsibility to setup the affinity set for each running application in such a way that reserved CPUs are not
used by his/her applications.
Given that the running Adams FMUs are launched by the real time environment, there is no practical way
to use the operating system commands to define the affinity set of the Adams process. To overcome this issue,
the Adams FMU has an FMU parameter named thread_affinity_set0 that can be used to set the affinity set
for the Adams FMU. The value for this parameter is two integers separated by a hyphen. In other words, we
26 Adams Solver
can only define a consecutive set of CPUs. Fortunately, most of real time environments have hyperthreading
disabled.
As an alternative, you may define the affinity set for the Adams FMU using an environment variable. The
format (name and value) are as follows:
Name: MSC_ADAMS_THREAD_AFFINITY_SET0
Value: A comma separated list of CPU numbers or ranges (two digits separated by a hyphen)
Example (linux):
%> setenv MSC_ADAMS_THREAD_AFFINITY_SET0 "1, 2, 5-6"
Instead of using the OS to set the environment variable, you may use the ENVIRONMENT statement in
your Adams data set as follows.
Example:
ENVIRONMENT/NAME=MSC_ADAMS_THREAD_AFFINITY_SET0, VALUE="1, 2, 0-5"
In real time environments the size of the affinity set (the number of logical CPUs listed) must match the
number of threads being set for the model (for example, PREFERENCES/NTHREAD). If the size of the set is
smaller than the number of threads, Adams Solver will place more than one thread on the same CPUs
affecting performance. If the size of the affinity set is smaller than the number of threads, the CPUs with
larger index will be ignored.
Affinity Settings in Standard Environments

Regarding thread priorities, operating systems do allow a superuser to run applications with real time
priorities in standard laptops, desktops, and servers. One advantage of using real time priorities is that the
process will run uninterrupted. Adams Solver C++ does not provide tools to launch an Adams process using
real time priorities. For that endeavor, users ought to use the operating system tools. An additional boost may
be obtained using the concept of shielding. Consult the operating system documentation for more
information on shielding.
Regarding affinity settings, most of the time there is no need to set the affinity set for an Adams simulation
running in a standard setting. If the machine is not heavily loaded with multiple applications running at the
same time, the scheduler will be smart enough to provide performance with multithreading, even in case of
running multiple Adams jobs at the same time.
However, not all schedulers are equally smart. We have observed the scheduler in some SUSE distribution to
cluster all the threads of multiple Adams jobs on a small set of CPUs. The solution to this issue was to launch
each Adams job with a different affinity setting. This way, the performance of running multiple Adams jobs
on the same machine was comparable as the performance of running a single Adams job. The most practical
solution is to modify the scripts that launch the jobs using the operating system commands.
Caution: You may need to set affinities for multiple Adams job running at the same time on the
same computer.
Option ALL
The environment variable MSC_ADAMS_THREAD_AFFINITY_SET0 has an additional option ALL that will
set the affinity of Adams threads in a one-to-all fashion. By default, the affinity settings are one-to-one as shown
in Figure 18. In the default case, each thread is assigned a single CPU from the set. In this case, the scheduler
will bind each thread to a unique CPU.
Figure 18 Default affinity settings, one-to-one.
Alternatively, using the ALL option, the affinity for each thread is set using a one-to-all fashion, as shown in
Figure 19. In this case, Adams Solver C++ will assign the complete set of CPUs for each thread. The scheduler
will be allowed to run each thread on any of the CPUs in the set.
Figure 19 Using option ALL, one-to-all.

28 Adams Solver
Option ALL may provide additional performance gains in some architectures, or in cases when the number
of threads is larger than the size of the affinity set.
References
1. Portable Hardware Locality. https://www.open-mpi.org/projects/hwloc/
2. Simulation Workbench. https://www.concurrent-rt.com/products/simulation-workbench/
3. Intel MKL Pardiso. https://software.intel.com/en-us/node/470282
4. Scalexio. https://www.dspace.com/en/inc/home.cfm

Adams 2021.0.2 Adams Solver User Guide

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Adams 2021.0.2 Adams Solver User Guide

Uploaded by

Copyright:

Available Formats

Adams 2021.0.

About Adams Solver

c= Character string (alphanumeric)

v =Varying type (integer, real, or alphanumeric)

x,y,z =Cartesian coordinate (real)

a,b,c =Angular coordinate (real)

Guidelines for Solver Selection and Settings

Benefits Cautions Model Content

Benefits Cautions Model Content

 Extend the range of spline data beyond the range of need.

To learn about: See:

To learn about: See:

Adams Solver Glossary

Using Adams Solver

Creating an Adams Solver Command File

First line is empty

Command File Syntax

Modeling and Simulating Process

Building Your Model

Testing Your Model

Reviewing the Results

Figure 1 Plot of Translational Joint Reaction Force

Figure 2 Superimposed Frames from the Animation of a Robot Arm

Improving Your Model

Working with Adams Solver Datasets

Organizing the Dataset

!****** PARTS AND THEIR MARKERS ****************************

!****** CONSTRAINTS ****************************************

, FUNCTION=1422.0 * DM(0409, 0109) ** (-1.4) - 185.4

!********PART MODULES *************************************

MARKER/21, PART=04, QP=12,0,0 PISTON MARKER

!********** SOLUTION AND OUTPUT PARAMETERS*******************

Using Statements to Define Your Model

Understanding Statement Syntax

Blanks and Tabs

REULER = 1.5708, 3.1416, 4.714

Understanding Adams Solver Modeling Concepts

In Adams Solver, you use coordinate systems to define:

Global Coordinate System

Body Coordinate Systems

You have two types of markers in Adams Solver:

Rotation Sequence Method

Local Versus Global Geometric Data

An example of local versus global data

 Removing Degrees of Freedom

Removing Degrees of Freedom

Table 1 Number and Types of DOF Removed by Joints

Table 1 Number and Types of DOF Removed by Joints

Table 2 Number and Types of DOF removed by Joint Primitives

Table 3 Number and Types of DOF removed by other constraints

Table 3 Number and Types of DOF removed by other constraints

Calculating Degrees of Freedom Using the Gruebler Equation

Checking for Redundant Constraints

Force Direction and Application

Action-Only, Single-Component Forces

Figure 3 Translational, Action-Only, Single-Component Force

Figure 4 Rotational, Action-Only, Single-Component Torque

Action-Reaction, Single-Component Forces

Figure 5 Translational, Action-Reaction, Single-Component Force

Figure 6 Rotational, Action-Reaction, Single-Component Torque

Figure 7 Three-Component, Action-Reaction Force

Figure 8 Three-Component, Action-Reaction Torque

Figure 9 Six-Component, Action-Reaction Force/Torque

Statement/Command Default User Subroutine

! PARTS AND THEIR MARKERS **********************

! CONSTRAINTS **********************************

!PART MODULES *****************************

! SOLUTION AND OUTPUT PARAMETERS*********