About Adams/Solver
Adams/Solver
Conventions
2
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 Twodimensional matrices
a Onedimensional matrices
Vectors
Unit vectors
R
1
x
ˆ
3 About Adams/Solver
Conventions
Best Practices
This section contains general tips on advanced modeling with Adams/Solver.
• Discontinuities
• Units
• Dummy Parts
• Joints
• Motions
• Forces
• Contacts
• Subroutines
• Simulation/Integrators
• 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.
Adams/Solver
Conventions
4
• 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 1e20.
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 Knowledge Base Article 7902).
• When possible, create a FIXED joint at the centerofmass (cm) of the lightest part, to minimize
the reaction forces/torques.
• 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 Knowledge Base Article 9752 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 Knowledge Base Article 7534 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 ^
5 About Adams/Solver
Conventions
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 Knowledge Base
Article 10170 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.
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.
• 1520 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 fixedstep 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 313 rotation sequence (psi, theta, phi). Theta=0d (or 180d) is bad
(Euler singularity). If the zaxis of part cm is parallel to zaxis 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 roundoff) errors accumulate when you let MAXIT go larger than 6. The theory
of GSTIFF says 23 iterations is desirable; it breaks down if it uses more than 4 or 5.
Debugging
• Try to understand mechanism from a physical standpoint.
Adams/Solver
Conventions
6
• Use building blocks of concepts that worked in the past. Add enhancements to the model using
crawlwalkrun 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 1e20.
• 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.
• 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 nonsmooth function). Instead, try 2.2 for the exponent.
Additional Publications
You might find it helpful to refer to the following resources when modeling mechanical systems.
7 About Adams/Solver
Conventions
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. 589602, New York:
JACM, October, 1970.
BDF Integration Algorithm Brayton, R. K., F. G. Gustavson, and G. D. Hatchel. A New Efficient
Algorithm for Solving DifferentialAlgebraic Systems using Implicit
Backward Differentiation Formulas. Proceedings of the IEEE, Vol.
60, No. 1, pp. 98108. 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: PrenticeHall, Inc.,
1977.
DASSL Computer Code Gear, W.C. Numerical Initial Value Problems in Ordinary
Differential Equations. Englewood Cliffs: PrenticeHall. 1971; and
Brenan, K.E., S.L. Campbell, and L.R. Petzold, Numerical Solution
of InitialValue Problems in DifferentialAlgebraic Equations. New
York: Elsevier Science, 1989.
Gear Stiff Gear, W.C. Simultaneous Numerical solution of Differential
algebraic Equations. IEEE Transactions on Circuit Theory, Vol. CT
18, No. 1, pp. 8995. 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. 369378. 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: McGrawHill
Book Company, 1983.
Standard Beam Stiffness Matrix Przemieniecki, J. S. Theory of Matrix Structural Analysis, p. 79.
New York: McGrawHill, 1968.
Timoshenko Beams Oden, J. T., and E. A. Ripperger. Mechanics of Elastic Structures,
Second Edition, p. 351. New York: McGrawHill, 1981.
Vehicle Technology Vehicle Dynamics Terminology, SAEJ670e. Warrendale, PA:
Society of Automotive Engineers, Inc., 1978.
Adams/Solver
Conventions
8
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
ActionOnly Force
A force that has one point of action and has no points of reaction.
ActionReaction 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.
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:
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
9 About Adams/Solver
Conventions
• Gear, C.W. Numerical Initial Value Problems in Ordinary Differential Equations. New Jersey:
PrenticeHall.
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.
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
Adams/Solver
Conventions
10
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.
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
userwritten 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.
11 About Adams/Solver
Conventions
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
QuasiStatic Equilibrium Analysis
An analysis that finds the change in displacement over time without considering velocities or
accelerations.
R
RightHand Rule
A rule for determining the direction of a positive rotation about any axis in a righthanded 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 userwritten subroutine.
Statement
Adams/Solver
Conventions
12
Any executable line in the Adams/Solve data set. Adams/Solver associates one statement with each
element in the model.
State Vector
The onedimensional 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.
13 Using Adams/Solver
Conventions
Using Adams/Solver
Adams/Solver
Command File
14
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:
• 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.
Sample Adams/Solver command file.
! This is my simulation script.
compressor.adm
run1
output/noseparator
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 turn
off the separators between the different simulations in the output files, performs a transient simulation,
the motion is deactivated, and then performs another transient simulation. 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
15 Using Adams/Solver
Command File
• Continuations
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.
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.
Adams/Solver
Modeling and Simulating Process
16
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 crawlwalkrun approach.
Learn more about:
• Build
• Test
• Review
• Improve
17 Using Adams/Solver
Modeling and Simulating Process
Adams/Solver
Modeling and Simulating Process
18
19 Using Adams/Solver
Modeling and Simulating Process
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 quasistatic 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, userdefined variables, generic system elements, as well as system modeling
Adams/Solver
Modeling and Simulating Process
20
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 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.
21 Using Adams/Solver
Modeling and Simulating Process
Figure 2 Superimposed Frames from the Animation of a Robot Arm
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.
Adams/Solver
Datasets
22
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:
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 modification. This section suggests two methods for organizing datasets and discusses the
implications of each.
The following sample structure shows a dataset for a pistoncrank mechanical system. The geometric
information in the dataset describes the model in the top deadcenter 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
• DIFF
• GFORCE
• MOTION
• REQUEST
• SENSOR
• SFORCE
• VARIABLE
• VFORCE
• VTORQUE
23 Using Adams/Solver
Datasets
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
MARKER/0407, QP=1,0,0 CENTER OF MASS
, 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
, 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
REQUEST/03, DISPLACEMENT, I=0305, J=0103
, COMMENT=ROD CENTER OF MASS DISPLACEMENT
REQUEST/04, ACCELERATION, I=0305, J=0103
, COMMENT=ROD CENTER OF MASS ACCELERATION
REQUEST/05, DISPLACEMENT, I=0407, J=0103
, COMMENT=PISTON CENTER OF MASS DISPLACEMENT
REQUEST/06, ACCELERATION, I=0407, J=0103
, COMMENT=PISTON CENTER OF MASS ACCELERATION
Adams/Solver
Datasets
24
REQUEST/07, FORCE, I=0202, J=0102
, COMMENT=CRANK/GROUND REACTION
REQUEST/08, FORCE, I=0304, J=0204
, COMMENT=ROD/CRANK REACTION
REQUEST/09, FORCE, I=0406, J=0306
, COMMENT=PISTON/ROD REACTION
REQUEST/10, FORCE, I=0408, J=0108
, COMMENT=PISTON/GROUND REACTION
REQUEST/11, FORCE, I=0408, J=0109
, COMMENT=PISTON VISCOUS DAMPING
REQUEST/12, FORCE, I=0409, J=0109
, 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
, LENGTH=1, SIDES=20, SEG=20
!****** 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
• 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.
25 Using Adams/Solver
Datasets
The following sample structure is an alternate organization scheme for the pistoncrank 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
REQUEST/01, DISPLACEMENT, I=02, J=01
, COMMENT=CRANK CG DISPLACEMENT
REQUEST/02, ACCELERATION, I=02, J=01
, 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
MARKER/05, QP=2,0,0 GRAPHICS MARKER
PART  (03) ROD
PART/03, MASS=1, CM=06, IP=1.5, 1.6, 3
MARKER/06, QP=6,0,0 CENTER OF MASS
REQUESTS
REQUEST/03, DISPLACEMENT, I=06, J=01
, COMMENT=ROD CENTER OF MASS DISPLACEMENT
REQUEST/04, ACCELERATION, I=06, J=01
, COMMENT=ROD CENTER OF MASS ACCELERATION
GRAPHICS
GRAPHICS/03, OUTLINE=07,08 ROD OUTLINE
MARKER/07, QP=2,0,0 GRAPHICS MARKER
MARKER/08, QP=10,0,0 GRAPHICS MARKER
PART  (04) PISTON
PART/04, MASS=.5, CM=09
MARKER/09, QP=11,0,0 CENTER OF MASS
REQUESTS
REQUEST/05, DISPLACEMENT, I=09, J=01
, COMMENT=PISTON CENTER OF MASS DISPLACEMENT
REQUEST/06, ACCELERATION, I=09, J=01
, 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
MARKER/10, QP=11,0,0 GRAPHICS MARKER
, REULER=90D,90D,0
Adams/Solver
Datasets
26
!**********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
REQUEST/07, FORCE, I=11, J=12
, 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
REQUEST/08, FORCE, I=13, J=14
, COMMENT=ROD/CRANK REACTION
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
REQUEST/09, FORCE, I=15, J=16
, COMMENT=PISTON/ROD REACTION
CONSTRAINT  (TRANSLATIONAL) PISTON ON GROUND
JOINT/04, TRANSLATIONAL, I=17, J=18
MARKER/17, PART=04, QP=12,0,0 PISTON MARKER
, REULER=90D,90D,0
MARKER/18, PART=01, QP=12,0,0 GROUND MARKER
, REULER=90D,90D,0
REQUEST/10, FORCE, I=17, J=18
, 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/19, PART=04, QP=12,0,0 PISTON MARKER
MARKER/20, PART=01, QP=12.286,0,0 GROUND MARKER
REQUEST/11, FORCE, I=19, J=20
, COMMENT=PISTON VISCOUS DAMPING
FORCE  (SFO) ISENTROPIC GAS PRESSURE FORCE
SFORCE/02, I=21, J=22, TRANSLATION
, FUNCTION=1422.0 * DM(21, 22) ** (1.4)  185.4
MARKER/21, PART=04, QP=12,0,0 PISTON MARKER
MARKER/22, PART=01, QP=12.286,0,0 GROUND MARKER
REQUEST/12, FORCE, I=22, J=21
, 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
27 Using Adams/Solver
Datasets
• 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.
Adams/Solver
Using Statements to Define Your Model
28
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.
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
29 Using Adams/Solver
Using Statements to Define Your Model
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, FORCE, I=0304, J=0204
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
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, lowercase 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
Adams/Solver
Using Statements to Define Your Model
30
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 centerofmass marker.
• IP indicates the three principal mass moments of inertia of the part about the part centerofmass
marker location.
• 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 FORTRANlike expression in the dataset or with
an external userwritten subroutine are called functionexpression 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 functionexpression arguments:
• Define an expression (e).
• Pass constants to a userwritten evaluation subroutine (USER=).
The following are examples of the two types of functionexpression arguments:
• The MOTION statement below, includes a functionexpression argument that uses an expression
to compute a MOTION.
MOTION/0201, JOINT=0201, FUNCTION=POLY(TIME,0,0,360D)
• The statement below includes a functionexpression argument that defines constants
Adams/Solver is to pass to the userwritten 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 userwritten subroutine as done in the second example. To find out more about user
written subroutines and the Adams/Solver utilities you can access from userwritten 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
31 Using Adams/Solver
Using Statements to Define Your Model
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
• 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.E3D
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 .
• 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.
t 180
Adams/Solver
Using Statements to Define Your Model
32
• 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.
• 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.
33 Using Adams/Solver
Using Statements to Define Your Model
• 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
functionexpression argument. Within a functionexpression 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.
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 functionexpression 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.
Adams/Solver
Using Statements to Define Your Model
34
• 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 functionexpression 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.
• 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 execution at the end of the input phase:
• 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 32bit machines.
35 Using Adams/Solver
Using Statements to Define Your Model
• 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 2
31
1 and less than +2
31
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. On the VAX/VMS, exponents must be integers greater than 38 and less than
+38. The following are examples of numbers with valid exponents:
.314159E1
314159E01
314.159E02
314159E+2
• Internally, Adams/Solver uses radians for angular units. Adams/Solver includes a degreesto
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 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 execution at the end of the input phase:
• 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.
t 180
Adams/Solver
Using Statements to Define Your Model
36
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 seventyninth 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 lowercase 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 execution at the end of the input phase:
• You do not include all required arguments in a statement.
• You put two or more statements on the same line without semicolons separating them.
• 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.
37 Using Adams/Solver
Understanding Adams/Solver Modeling Concepts
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.
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 mutuallyperpendicular unit
Adams/Solver
Understanding Adams/Solver Modeling Concepts
38
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 mutuallyperpendicular unit vectors,
, , and , 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 , , and
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.
x
ˆ
y
ˆ
z
ˆ
x
ˆ
G
y
ˆ
G
z
ˆ
G
39 Using Adams/Solver
Understanding Adams/Solver Modeling Concepts
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.
Adams/Solver
Understanding Adams/Solver Modeling Concepts
40
• 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 sixcomponent force, three
component force, threecomponent torque, curvetocurve constraint, and pointtocurve 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
41 Using Adams/Solver
Understanding Adams/Solver Modeling Concepts
use. In this section, the local coordinate system that you are either locating or orienting is referred to as
the positioned coordinate system 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.
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 , , and 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 threepoint 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
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.
x
ˆ
y
ˆ
z
ˆ
Adams/Solver
Understanding Adams/Solver Modeling Concepts
42
available, Adams/Solver uses only the bodyfixed 313 (or zx´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 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 (BodyFixed 313 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 zaxis +90 degrees. This
repositions the x and yaxes (5b).
• The second Euler angle rotates the positioned coordinate system about its new xaxis (x´) 90
degrees, to reposition the new yaxis and the zaxis (5c).
• The third Euler angle rotates the positioned coordinate system about its new zaxis (z´´) +90
degrees, to reposition the new xaxis (x´´) and the second new yaxis (y´´).
Together and in sequence, these rotations define the orientation of the positioned coordinate system (5d).
The righthand rule defines the direction of positive rotation about each axis. For example, if you look
down the initial zaxis, positive rotations are counterclockwise and negative rotations are clockwise.
Example of the Rotation Sequence Method (BodyFixed 313 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 90degree increments. When orienting a
coordinate system that requires a complex combination of rotations, you may find it easier to use the
threepoint orientation method, as described next.
ThreePoint Method
You can use the threepoint method to specify the orientation (in direction cosines) of the positioned
coordinate system relative to the base coordinate system. When you use the threepoint 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.
43 Using Adams/Solver
Understanding Adams/Solver Modeling Concepts
• Cartesian coordinates of a point on the primary axis of the positioned coordinate system (point
2). You can specify either the z or xaxis as the primary axis of the positioned coordinate
system. If you do not specify a primary axis, the
zaxis is used by default. When it is important to exactly specify the zaxis of the positioned
coordinate system, provide the Cartesian coordinates of a point on the zaxis. When it is
important to exactly specify the xaxis of the positioned coordinate system, provide the
Cartesian coordinates of a point on the xaxis.
• Cartesian coordinates of a point that is in the xz 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 ThreePoint Method below shows the points of the positioned coordinate system with
respect to the base coordinate system. Point 2 in the figure specifies the zaxis of the positioned
coordinate system and point 3 defines a point in the xz plane of the positioned coordinate system. Note
that in this example, point 3 is placed directly on the xaxis of the positioned coordinate system but only
needs to be in the xz plane.
By default, Adams/Solver assumes that defines the the exact location of the coordinate system origin
and defines a point on the zaxis. Because the third point ( by default) does not necessarily lie on
an axis but happens to in this example, Adams/Solver determines the vector cross product of vectors
and to form an orthogonal yaxis. Then, Adams/Solver determines the vector cross product of the
new yaxis and the exact axis (the zaxis by default) to produce the orientation of the remaining axis (by
default, the xaxis). By calculating and , you can verify that the third point is in the xz plane
and that the three points are not collinear.
R
1
R
2
R
3
R
2
R
3
v
1
v
2
Adams/Solver
Understanding Adams/Solver Modeling Concepts
44
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 ballandsocket 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
45 Using Adams/Solver
Understanding Adams/Solver Modeling Concepts
seriously affect the solution process. For two markers whose positions are not reasonably close,
Adams/Solver might 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 quasistatic equilibrium
analysis or settles during a subsequent static equilibrium analysis, the BCS move with their bodies with
respect to the stationary GCS.
Adams/Solver
Understanding Adams/Solver Modeling Concepts
46
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.
47 Using Adams/Solver
Understanding Adams/Solver Modeling Concepts
• 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 threedimensional 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
This joint type:
Removes number
translational DOF:
Removes number
rotational DOF:
Removes total
number DOF:
Constant velocity 3 1 4
Cylindrical 2 2 4
Fixed 3 3 6
Hooke 3 1 4
Planar 1 2 3
Rackandpinion 0.5* 0.5* 1
Revolute 3 2 5
Adams/Solver
Understanding Adams/Solver Modeling Concepts
48
* The rackandpinion 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.
Screw 0.5* 0.5* 1
Spherical 3 0 3
Translational 2 3 5
Universal 3 1 4
Table 2 Number and Types of DOF removed by Joint Primitives
This type of joint
primitive:
Removes Number
translational DOF:
Removes number
rotational DOF:
Removes total
number of 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
This type of
constraint
Removes
number
trans. DOF:
Removes
number
rotational
DOF:
Removes
number mixed
translational &
rotational DOF:
Removes
number
new
generalized
DOF:
Removes
total number
DOF:
Coupler   1  1
Curveto
curve
   2 2
Gear   1  1
Table 1 Number and Types of DOF Removed by Joints
This joint type:
Removes number
translational DOF:
Removes number
rotational DOF:
Removes total
number DOF:
49 Using Adams/Solver
Understanding Adams/Solver Modeling Concepts
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.
Translational
motion
1    1
Rotational
motion
 1   1
Pointtocurve    2 2
Userdefined
constraint
  1  1
Table 3 Number and Types of DOF removed by other constraints
This type of
constraint
Removes
number
trans. DOF:
Removes
number
rotational
DOF:
Removes
number mixed
translational &
rotational DOF:
Removes
number
new
generalized
DOF:
Removes
total number
DOF:
Adams/Solver
Understanding Adams/Solver Modeling Concepts
50
Checking for Redundant Constraints
You can construct a legal and welldefined 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 jointplay 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
51 Using Adams/Solver
Understanding Adams/Solver Modeling Concepts
Adams/Solver tries to solves your model, you can find out how many and which redundant constraints
are being removed.
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.
• SingleComponent Forces
• MultiComponent Forces
SingleComponent Forces
You can use two types of singlecomponent forces in Adams/Solver:
• ActionOnly, SingleComponent Forces
• ActionReaction, SingleComponent Forces
ActionOnly, SingleComponent Forces
An actiononly, singlecomponent 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 actiononly force (that is, one with no reaction). Therefore, the body reacting to the
actiononly force in Adams/Solver is automatically defined as ground and shows no visible effect in your
model.
You can apply either a translational or rotational actiononly, singlecomponent force to a body in your
model. Note that a rotational force is a pure torque in Adams/Solver. For both translational and rotational
actiononly, singlecomponent 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 zaxis 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 zaxis of the
direction marker. If the force is positive and rotational (Figure 4), it acts in the positive direction about
the zaxis of the direction marker. The righthand rule defines the positive direction.
Note: You may find the actionreaction, multicomponent forces more intuitive to use than the
actiononly, singlecomponent force. If you want to apply force to only one body, you can
use the actionreaction, multicomponent forces and specify the reaction marker on ground.
Adams/Solver
Understanding Adams/Solver Modeling Concepts
52
Figure 3 Translational, ActionOnly, SingleComponent Force
Figure 4 Rotational, ActionOnly, SingleComponent Torque
ActionReaction, SingleComponent Forces
An actionreaction 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) actionreaction, singlecomponent force to your model.
• For translational, actionreaction, singlecomponent 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.
53 Using Adams/Solver
Understanding Adams/Solver Modeling Concepts
• For rotational, actionreaction, singlecomponent 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 zaxis of the reaction marker specifies the axis about which the torque is applied. If the
torque is positive, the action marker tends to move counterclockwise to the reaction marker. If
the torque is negative, the action marker tends to move clockwise to the reaction marker.
Figure 5 Translational, ActionReaction, SingleComponent Force
Figure 6 Rotational, ActionReaction, SingleComponent Torque
MultiComponent Forces
Adams/Solver also allows you to define multicomponent translational and rotational force vectors. For
each of the multicomponent 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.
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 multicomponent force to be applied to the
Adams/Solver
Understanding Adams/Solver Modeling Concepts
54
action marker, even if some are zero. Equal and opposite forces are automatically applied to the reaction
(floating) marker.
Figure 7 ThreeComponent, ActionReaction Force
Figure 8 ThreeComponent, ActionReaction Torque
55 Using Adams/Solver
Understanding Adams/Solver Modeling Concepts
Figure 9 SixComponent, ActionReaction Force/Torque
Adams/Solver
ROUTINE Argument
56
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 runuser mode), you should write:
ROUTINE=mysfo
or
ROUTINE=::mysfo
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
57 Using Adams/Solver
ROUTINE Argument
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:
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 builtin searchrules 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 HPUX platform and .so on other UNIX
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,
CURVE CURSUB
SURFACE SURSUB
CONTROL CONSUB
COUPLER See the COUPLER and GSE section below.
GSE See the COUPLER and GSE section below.
Statement/Command Default User Subroutine
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.
Adams/Solver
ROUTINE Argument
58
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 39 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.
59 Using Adams/Solver
Joint types
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.
Adams/Solver
Joint types
60
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.
Note: Adams/Solver (C++) computes DZ0 (the initial joint displacement) after the first
successful assembly of the model (initial conditions or first static simulation.
61 Using Adams/Solver
Joint types
Adams/Solver
Joint types
62
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.
63 Using Adams/Solver
Joint types
Adams/Solver
Joint types
64
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.
65 Using Adams/Solver
Joint types
Adams/Solver
Error Codes
66
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
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
1 Welcome to the C++ Version of Adams/Solver
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
Adams/Solver (C++) FAQs
2
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 builtin 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++):
Q: Why is the UCON userdefined 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 userfriendly userdefined 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++?
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.
• ACENTER
• AINIT
• AUTOSCALE
• BACKUP
• CENTER
• CLEAR
• DISPLAY
• DRAW
• DT
• ERASE
• EXECUTION
• PLOT
• RETURN
• SET
3 Welcome to the C++ Version of Adams/Solver
Operators
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, ss, s*s, s/s, s, +s
Power (scalars only):
s**s
Vector summation, subtraction, unary minus and unary plus:
v+v, vv, +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
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
Adams/Solver
Operators
4
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.
5 Welcome to the C++ Version of Adams/Solver
C++ Statements
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:
Type of Statement Statement Name
Dataset delimiter END
TITLE
Inertia and material data PART
FLEX_BODY
POINT_MASS
Geometry GRAPHICS
MARKER
Constraints COUPLER
CVCV
GEAR
GCON
JOINT
JPRIM
MOTION
PTCV
Forces ACCGRAV
BEAM
BUSHING
CONTACT
FIELD
FRICTION
GFORCE
MFORCE
NFORCE
SFORCE
SPRINGDAMPER
VFORCE
VTORQUE
Generic systems modeling DIFF
GSE
LSE
TFSISO
VARIABLE
Adams/Solver
C++ Statements
6
Reference data ARRAY
CURVE
MATRIX
PINPUT
POUTPUT
SPLINE
STRING
SURFACE
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
Type of Statement Statement Name
7 ACCGRAV
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
Examples
ACCGRAV/JGRAV=386.088
This ACCGRAV statement defines the gravitational constant of 386.088, acting along the yaxis of the
ground coordinate system (GCS) in the negative direction.
See other Forces available.
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
Adams/Solver
C++ Statements
8
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 userwritten subroutines.
Format
Arguments
IC Creates a onedimensional array of real numbers that can be accessed in userwritten
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 onedimensional 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 (C++)
calculates the SIZE differently from the SIZE that you supply, Adams/Solver (C++)
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
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.
9 ARRAY
C++ Statements
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 userwritten 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 inputfile 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 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.
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.
Adams/Solver
C++ Statements
10
Both function expressions and userwritten 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.
11 BEAM
C++ Statements
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 either linear Timoshenko beam theory or the
nonlinear EulerBernoulli theory.
By default, the nonlinear EulerBernoulli formulation is used. See the release notes on how to revert the
formulation to the linear Timoshenko beam theory used in previous Adams/Solver (C++) versions.
Format
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.
where Q
y
is the first moment of crosssectional area to be sheared by a force in the z
direction, and I
z
is the cross section dimension in the z direction.
If you want to neglect the deflection due to ydirection shear, ASY does not need to be
included in a BEAM statement.
Defaults: 0
ASY
A
I
y
2

Q
y
l
z

\ .
 
2
A d
A
í
=
Adams/Solver
C++ Statements
12
ASZ=r Specifies the correction factor (that is, the shear area ratio) for shear deflection in the z
direction for Timoshenko beams.
where Q
z
is the first moment of crosssectional area to be sheared by a force in the y
direction, and I
y
is the cross section dimension in the y direction.
If you want to neglect the deflection due to zdirection shear, ASZ does not need to be
included in a BEAM statement.
Defaults: 0
Commonly encountered values for the shear area ratio are:
See also “Roark’s Formulas for Stress and Strain,” Young, Warren C., Sixth Edition, page
201. New York:McGraw Hill, 1989.
CMATRIX=r1,...,r21 Establishes a sixbysix damping matrix for the beam. Because this matrix is symmetric,
only onehalf 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 thirtysix 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
ASZ
A
I
z
2

Q
z
l
y

\ .
 
2
A d
A
í
=
Crosssection: (Shear area ratio)
Solid rectangular (6/5)
Solid circular (10/9)
Thin wall hollow circular (2)
13 BEAM
C++ Statements
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 xaxis of the J marker defines the centroidal axis of the beam. The yaxis and zaxis of the J marker
are the principal axes of the cross section. They are perpendicular to the xaxis 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 xaxis of the J marker a distance LENGTH away.
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 where r is the
radius of the crosssection. For thinwalled 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
(yy and zz). 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 crosssection. For thinwalled sections, open
sections, and noncircular sections, you should consult a handbook.
LENGTH=r Defines the underformed length of the beam along the xaxis of the J marker.
J
tr
4
2
 =
tr
4
4

Adams/Solver
C++ Statements
14
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 yaxis and zaxis (s5, s6, s11, and s12)
• Twisting moments about the xaxis (s4 and s10)
• Shear forces (s2, s3, s8, and s9)
Linear theory
When using the Timoshenko beam theory, Adams/Solver (C++) uses a linear translational and linear
rotational actionreaction 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.
where:
• F
x
, F
y
, and F
z
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.
F
x
F
y
F
z
T
x
T
y
T
z
K
11
0 0 0 0 0
0 K
22
0 0 0 K
26
0 0 K
33
0 K
35
0
0 0 0 K
44
0 0
0 0 K
53
0 K
55
0
0 K
62
0 0 0 K
66
x L –
y
z
a
b
c
– =
c
11
c
21
c
31
c
41
c
51
c
61
c
21
c
22
c
32
c
42
c
52
c
62
c
31
c
32
c
33
c
43
c
53
c
63
c
41
c
42
c
43
c
44
c
54
c
64
c
51
c
52
c
53
c
54
c
55
c
65
c
61
c
62
c
63
c
64
c
65
c
66
V
x
V
y
V
z
e
x
e
y
e
z
–
15 BEAM
C++ Statements
• V
x
, V
y
, and V
z
are the time derivatives of x, y, and z, respectively.
• T
x
, T
y
, and T
z
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 zaxis, respectively, of the J marker.
• , , and 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.
• C
ij
are the entries of the damping matrix either specified by the CMATRIX option or computed
by using the CRATIO option. All C
ij
entries default to zero.
Note that both matrices, C
ij
and K
ij
, are symmetric, that is, C
ij
=C
ji
and K
ij
=K
ji
. You define the twenty
one unique damping coefficients when the BEAM statement is written. Adams/Solver (C++) defines
each K
ij
as follows:
Adams/Solver (C++) applies an equilibrating force and torque at the J marker, as defined by the following
equations:
F
j
=  F
i
T
j
=  T
i
 L x F
i
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.
e
x
e
y
e
z
Adams/Solver
C++ Statements
16
Non linear theory.
When using the EulerBernoulli formulation, Adams/Solver (C++) uses the following constitutive
equations to apply a force and a torque to the I marker.
Where corresponds to the Timoshenko's constitutive equations shown above, and N is the axial
force on the beam computed as:
The term d corresponds to the axial viscous forces if any. See reference [2] for more information.
The non linear EulerBernoulli formulation is the default model for the BEAM statement because it
provides better results in simulations where BEAM objects are subject to axial forces.
{ }
¦
¦
¦
¦
)
¦
¦
¦
¦
`
¹
¦
¦
¦
¦
¹
¦
¦
¦
¦
´
¦ ÷
÷
÷
÷
÷
÷ =
¦
¦
¦
¦
)
¦
¦
¦
¦
`
¹
¦
¦
¦
¦
¹
¦
¦
¦
¦
´
¦
c
b
a
z
y
L x
/ L /
/ L /
/ L /
/ L /
N F
T
T
T
F
F
F
o
z
y
x
z
y
x
15 2 0 0 0 10 1 0
0 15 2 0 10 1 0 0
0 0 0 0 0 0
0 10 1 0 5 6 0 0
10 1 0 0 0 5 6 0
0 0 0 0 0 0
} F {
o
d ) L x ( K N + ÷ =
11
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 (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 xaxis of the Adams/Solver (C++) beam on
the shear center axis of the beam being modeled.
17 BEAM
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 xaxes 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 xaxis of the J marker. (This is
unlike most other Adams/Solver force statements, for which the zaxis 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.
Adams/Solver
C++ Statements
18
Examples
A cantilevered stainless steel beam is to be modeled with a circular cross section that has the loading
shown in the figure below.
A weight of 17.4533 lbf at the free end of the beam with a 100inch 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 inch
4
; its principal area moments of inertia about the yaxis is 50 inch
4
, and about the z
axis is 50 inch
4
; its crosssectional area is 25.0663 inch
2
; 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: McGrawHill Book
Company, 1968
See other Forces available.
19 BUSHING
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 zaxis 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 forcetime per unit displacement.
Default: 0,0,0
Range:
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 zaxis 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 torquetime per radian.
Default: 0,0,0
Range:
FORCE=r1,r2,r3 Specifies three constant force (preload) values. Constant values indicate the force
components along the x, y, and zaxis 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.
C 0 >
CT 0 >
Adams/Solver
C++ Statements
20
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 xaxis
direction, one in the yaxis direction, and one in the zaxis direction.
Likewise each torque consists of three components in the coordinate system of the J marker: one about
the xaxis, one about the yaxis, and one about the zaxis. 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.
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 zaxis of the J
marker. K must be specified in terms of force per unit of deformation.
Default: 0,0,0
Range:
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 zaxis of
the J marker. KT must be in units of torque per radian.
Default: 0,0,0
Range:
TORQUE=r1,r2,r3 Specifies three constant torque (preload) values. Constant values indicate the
torque components about the x, y, and zaxis 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
K 0 >
KT 0 >
21 BUSHING
C++ Statements
A BUSHING statement has the same constitutive relation form as a FIELD statement. The primary
difference between the two statements is that certain coefficients (K
ij
and C
ij
, where i j) are zero for
the BUSHING statement. Only the diagonal coefficients (K
ii
and C
ii
) are defined for a BUSHING.
F
x
, F
y
, and F
z
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 V
x
, V
y
, and V
z
are the time
derivatives of x, y, and z, respectively. The terms F
1
, F
2
, and F
3
represent the measure numbers of any
constant preload force components in the coordinate system of the J marker.
T
x
, T
y
, and T
z
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 zaxis, respectively, of the J marker. The terms , , and 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 T
1
, T
2
, and T
3
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:
F
j
=F
i
T
j
=  T
i
 x F
i
F
x
F
y
F
z
T
x
T
y
T
z
K
11
0 0 0 0 0
0 K
22
0 0 0 0
0 0 K
33
0 0 0
0 0 0 K
44
0 0
0 0 0 0 K
55
0
0 0 0 0 0 K
66
x
y
z
a
b
c
– =
c
11
0 0 0 0 0
0 c
22
0 0 0 0
0 0 c
33
0 0 0
0 0 0 c
44
0 0
0 0 0 0 c
55
0
0 0 0 0 0 c
66
V
x
V
y
V
z
e
x
e
y
e
z
–
F
1
F
2
F
3
T
1
T
2
T
3
+
e
x
e
y
e
z
o
Adams/Solver
C++ Statements
22
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.
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 yaxis directions of Marker 22 and of 2000 units in the zaxis direction of Marker 22. The
corresponding damping rates for the force are 5 units in both the x and yaxis directions of Marker 22
and 2 units in the zaxis direction of Marker 22. The rotational spring rates are 50000 units about the x
and yaxis of Marker 22. The corresponding damping rates for the torque are 50 units in both the x and
yaxis directions of Marker 22 and zero units in the zaxis direction of Marker 22. Since the z components
of KT and CT are zero, the I marker can rotate about the zaxis 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.
See other Forces available.
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.
23 CONTACT
C++ Statements
CONTACT
The CONTACT statement lets you define a two or threedimensional 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 threedimensional solid geometries
• Contact between twodimensional geometries
It does not support nonsolid threedimensional geometries, such as shells that do not encompass a
volume and sheets. It also does not support contact between a twodimensional and a threedimensional
geometry.
Adams/Solver (C++) has two geometry engines that it uses for threedimensional 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.
For twodimensional contacts, Adams/Solver (C++) uses an internally developed geometry engine.
Currently, Adams/Solver (C++) supports Parasolid 14.0. 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.
The following table shows the legal combinations of geometry for the CONTACT statement. If you use
unsupported geometry combinations, you will receive an error.
Note: You can only define twodimensional 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 runtime error, when the bodies go out of plane
during a simulation.
Adams/Solver
C++ Statements
24
Supported Geometry Combinations
* FlexBody edges are considered to be curves. They may contact any other 2D geometry.
Arc Circle Curve Point Plane Box Cylinder Frustum Ellipsoid External FlexBody
Arc X X X X X
Circle X X X X X
Curve X X X X X *
Point X X X X
Plane X X X X X(Sphere
Only)
Box X X X X X X
Cylinder X X X X X X
Frustum X X X X X X
Ellipsoid X X X X X X
External X X X X X X
FlexBody X X X X X X
Note: You can set the default geometry library. See the PREFERENCES statement.
25 CONTACT
C++ Statements
Format
CONTACT/id IGEOM=id1[ ,..., idn] ,
JGEOM=id2[ ,..., idn] ,
IMPACT
STIFFNESS=r ,
EXPONENT=r ,
DAMPING=r ,
DMAX=r ,
POISSON
PENALTY=r ,
RESTITUTION_COEFFICIENT=r , ¹ )
¦ ¦
¦ ¦
¦ ¦
¦ ¦
¦ ¦
¦ ¦
¦ ¦
´ `
¦ ¦
¦ ¦
¦ ¦
¦ ¦
¦ ¦
¦ ¦
¦ ¦
¦ ¹
,
COULOMB_FRICTION={On/Off}
MU_STATIC=r ,
MU_DYNAMIC=r ,
STICTION_TRANSITION_VELOCITY=r ,
FRICTION_TRANSITION_VELOCITY=r ,
,
IFLIP_GEOM=ida,...,idr
JFLIP_GEOM=idb,...,ids
NORMAL_ROUTINE=lib::func
FRICTION_ROUTINE=lib::func
NORMAL_FUNCTION=USER(r1 ,[ ,..., r30])
FRICTION_FUNCTION=USER(r1 ,[ ,..., r30])
IFLEX=id1 ,
IEDGE=id2 ,
JGEOM=id3 ,
IFLEX=id1 ,
JEDGE=id2 ,
JFLEX=id3 ,
JEDGE=id4 ,
IMP , ACT
STIFFNESS=r ,
EXPONENT=r ,
DAMPING=r ,
DMAX=r ,
COULOMB_FRICTION={On/Off}
MU_STATIC=r ,
MU_DYNAMIC=r ,
STICTION_TRANSITION_VELOCITY=r ,
FRICTION_TRANSITION_VELOCITY=r , ¹ )
¦ ¦
¦ ¦
¦ ¦
¦ ¦
¦ ¦
¦ ¦
¦ ¦
¦ ¦
¦ ¦
´ `
¦ ¦
¦ ¦
¦ ¦
¦ ¦
¦ ¦
¦ ¦
¦ ¦
¦ ¦
¦ ¦
¦ ¹
Adams/Solver
C++ Statements
26
Arguments
{ } Select one item
[ ] Optionally select one item
COULOMB_FRICTION = off/on Models friction effects at the contact locations using the Coulomb 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 (C++) models normal force as a nonlinear springdamper. 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
27 CONTACT
C++ Statements
FRICTION_TRANSITION_VELO
CITY = r
Used in the COULOMB_FRICTION model for calculating frictional forces
at 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 1E3.
Range:
FRICTION_TRANSITION_VELOCITY >
STICTION_TRANSITION_VELOCITY > 0
FRICTION_FUNCTION=USER(r
1[,...,r30])
Specifies up to 30 userdefined constants to compute the contact friction force
components in a userdefined subroutine, CNFSUB.
FRICTION_ROUTINE =
library::function
Specifies a library and a userwritten subroutine in that library that calculates
the contact friction force.
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.
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.
Adams/Solver
C++ Statements
28
IFLIP_GEOMETRY =
id1,id2,...,idN
Specifies a list of GRAPHICS IDs associated with the IGEOM objects to be
reversed in direction (flipped). Use IFLIP_GEOMETRY only with two
dimensional geometries (for example, curves, arcs, and circles). You can also
use IFLIP_GEOMETRY when defining contact between two spheres
(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 =
id1,id2,...,idN
Specifies a list of GRAPHICS IDs associated with the JGEOM objects to be
reversed in direction (flipped). Use JFLIP_GEOMETRY only with two
dimensional geometries (for example, curves, arcs, and circles). You can also
use JFLIP_GEOMETRY when defining contact between two spheres
(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.
Range: MU_STATIC > 0
NORMAL_FUNCTION =
USER(r1,[,...,r30])
Specifies up to 30 userdefined constants to compute the contact normal force
components in a userdefined subroutine, CNFSUB.
NORMAL_ROUTINE =
library::function
Specifies a library and a userwritten subroutine in that library that calculates
the 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 Kgmmsec. 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.
29 CONTACT
C++ Statements
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
RESTITUTION_COEFFICIENT =
r
The coefficient of restitution models the energy loss during contact. A 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_VELO
CITY = r
Used in the COULOMB_FRICTION model for calculating frictional forces
at 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
1E3.
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.
Adams/Solver
C++ Statements
30
• Contacts and Analysis Mode Issues
• Flexible Bodies
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 threedimensional geometry.
• Twodimensional or planar contact between POINT, PLANE, CIRCLE, ARC, and CURVE
geometries.
• Threedimensional contact between CYLINDER, ELLIPSOID, BOX, FRUSTUM, and
EXTERNAL geometries.
Currently, Adams/Solver (C++) does not support contact between two and threedimensional
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 threedimensional 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 threedimensional 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 wellrecognized, stateoftheart 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 threedimensional solids, which are closed by definition, the outward normal is implicit in the
geometry description, and there is no ambiguity in its definition.
For twodimensional 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.
31 CONTACT
C++ Statements
The figure below shows an open curve with eight points defined in the coordinate system of the reference
marker (RM). The zaxis of the RM marker is directed out of the plane of the paper. This defines the bi
normal for the curve, denoted as .
The curve points are created in the sequence 1 through 8.
The tangent at point 3 points towards point 4, and is denoted by . The outward normals are defined as
follows:
IFLIP_NORMAL and JFLIP_NORMAL simply reverse the direction of .
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.
b
ˆ
t
ˆ
n
ˆ
t
ˆ
b
ˆ
× =
n
ˆ
Adams/Solver
C++ Statements
32
• 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
33 CONTACT
C++ Statements
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.
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:
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
displacementdependent, 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.
g 0 >
F
n
0 >
F
n
g · 0 =
F
n
dg
dt
 · 0 =
F
n
k*(g**e) =
Adams/Solver
C++ Statements
34
• is the penetration velocity at the contact point.
• e is a positive real value denoting the force exponent.
• d
max
is a positive real value specifying the boundary penetration to apply the maximum damping
coefficient c
max
.
Clearly, for c
max
= 0 and e = 1, the original penalization is recovered. The POISSON force model is
derived from the persistency condition, F
n
* = 0. A penalty regularization of the fourth contact
constraint yields:
F
n
= p *
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:
Here, is coefficient of restitution, and the subscripts (·) and (·)+ denote values immediately before and
after contact.
See Learning More about the Contact Detection Algorithm.
Contact Friction Force Calculation
Adams/Solver (C++) uses a relatively simple velocitybased friction model for contacts. Specifying the
frictional behavior is optional. The figure below shows how the coefficient of friction varies with slip
velocity.
dg
dt

dg
dt

dg
dt

F
n
p c 1 – ( )
dg
dt

\ .
 
=
c
35 CONTACT
C++ Statements
In this simple model:
• (v
s
) =
s
• (v
s
) = 
s
• (0) = 0
• (v
d
) =
d
• (v
d
) = 
d
• (v) = sign(v).
d
for v >v
d
• (v) = step(v,v
d
, d,v
s
,
s
) . sign(v) for v
s
<v<v
d
• (v) = step(v,v
s
, s,v
s
,
s
) for v
s
< v < v
s
where:
• V: Slip velocity at contact point
• v
s
: STICTION_TRANSITION_VELOCITY
u u
u u
u
u u
u u
u u
u u u
u u u
Adams/Solver
C++ Statements
36
• v
d
: 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:
Where R is the radius of the contact area (which is assumed to be circular). The coefficient comes from
Marks' Standard Handbook for Mechanical Engineers.
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 (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.
u
u
T
2
3
RF =
2
3

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.
37 CONTACT
C++ Statements
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 quasistatic equilibrium analysis modes use NewtonRaphson (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 contactforcesensing 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 quasidynamic 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.
• See Best Practices for Working with Contacts for more information.
Adams/Solver
C++ Statements
38
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 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. Lowerorder
integrators are more stable than higherorder 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.
39 CONTACT
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.
Adams/Solver
C++ Statements
40
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 stepsize 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.
41 CONTACT
C++ Statements
Tip: If you notice that energy is dissipated during contact events, note the following:
• Impact method  A threedimensional 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 threedimensional 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.
Adams/Solver
C++ Statements
42
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
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
43 CONTACT
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 predictorinduced 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 predictorcorrector 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.
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
Material 1: Material 2: Mu static: Mu dynamic: Restitution coefficient:
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 stepsize and the quality of the
solution.
Adams/Solver
C++ Statements
44
• 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.
• Contact order  Sometimes the relative velocities and complexity of the two geometries
participating in a contact can provide better numerical condition based on their order. If a model
is performing poorly, in some cases, changing the order of the geometries (IGEOM  JGEOM)
can improve the simulation performance. If the answer is different, it should be within error
tolerance and tightening error tolerance should converge the results if they are different.
• 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.
• 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 pointtocurve, curvetocurve, or use the
IMPACT function defined in a SFORCE, VFORCE, or GFORCE element.
• 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 threedimensional 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.
45 CONTACT
C++ Statements
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
!
MARKER/30028, PART = 1004
GRAPHICS/12,
, EXTERNAL,
, FILE = star_geneva.xmt_txt,
, ELEMENT = SOLID3,
, RM = 30028
An impacttype contact would be defined as:
CONTACT/1,
, IGEOM=11,
, JGEOM=12,
, IMPACT,
, STIFFNESS = 1E6,
, DAMPING = 10,
, DMAX = 0.1,
, EXPONENT = 2.2
A POISSONtype contact would be defined as:
CONTACT/1,
, IGEOM=11,
, JGEOM=12,
, POISSON,
, 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 userwritten 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
Adams/Solver
C++ Statements
46
, 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 twodimensional geometries:
MARKER/30027, PART = 1005
GRAPHICS/11, CURVE, RM = 30027, CID = 147
!
MARKER/30028, PART = 1004
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
47 CONTACT
C++ Statements
, IEDGE = 2
, JGEOM = 1
, IMPACT
, STIFFNESS = 1.0E+005
, DAMPING = 10
, DMAX = 0.1
, EXPONENT = 2.2
See other Forces statements available.
Adams/Solver
C++ Statements
48
COUPLER
A COUPLER statement relates the translational and/or the rotational motion of two or three joints.
Format
Arguments
FUNCTION=USER(r1[,...,r3
0])
Specifies up to thirty userdefined 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.
ROUTINE=lib1::cou1,
lib2::cou2, lib3::cou3
Specifies alternative library and subroutine names for the user
subroutines COUSUB, COUXX, and COUXX2 respectively.
Learn more about the ROUTINE Argument.
49 COUPLER
C++ Statements
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: nonzero real numbers
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.
Adams/Solver
C++ Statements
50
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
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 zaxis.
Positive translations are along the positive zaxis of J, and negative translations are
along its negative zaxis.
• To measure rotational motion, Adams/Solver (C++) finds the displacement of the
xaxis of the I marker with respect to the xaxis of the J marker about the common
zaxis of the I and the J markers. To determine the positive sense of rotation, apply
the righthand rule to the zaxis.
• The COUPLER can relate any combination of translational and rotational motions.
A twojoint 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 zaxis of marker J1. The reaction on the second joint is the
torque about the zaxis 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 zaxis of
Marker J1, and the reaction on the TRANSLATIONAL joint is a force along the z
axis of Marker J2.
51 COUPLER
C++ Statements
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.
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.
Adams/Solver
C++ Statements
52
CURVE
The CURVE statement defines a threedimensional 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
(r1[,...,r30])/
Defines and passes constants to CURSUB, the userwritten subroutine 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 zcoordinates
of the points. You must supply at least four curve points. The first and last points
must be the same for a closed curve.
53 CURVE
C++ Statements
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
MAXPAR=r Specifies the maximum value of the curve parameter for a userwritten 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 userwritten 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 Bspline interpolating the curve. A
Bspline of order K means that it is made up of piecewise polynomial segments
of degree K1. A cubic Bspline is order 4. A Bspline 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 Bspline of order K will have
K2 continuous derivatives. The discontinuities appear where the polynomial
segments join together. Increasing the order of the Bspline 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.
Learn more about the ROUTINE Argument.
Adams/Solver
C++ Statements
54
Example of a Parametric Curve
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 Bspline is a piecewise polynomial spline used in many CAD (computeraided design)
applications. A Bspline is defined by control points that form a polygon in space and a knot vector.
Adams/Solver (FORTRAN) uses a nonuniform 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 BSpline
starting at 1 and ending at +1. The figure below shows a set of control points and the Bspline curve it
defines.
55 CURVE
C++ Statements
Control Points and the Resulting BSpline
Adams/Solver (C++) computes the control points internally from the curve points.
To use a different type of curve, or to model an analyticallydefined curve such as a helix, you can write
a CURSUB userwritten 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.
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 Bspline 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 Bspline curve to fit the points.
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.
Adams/Solver
C++ Statements
56
Applications
The PTCV, CVCV, and GRAPHICS statements reference the CURVE statement:
• The PTCV uses a curve to define a pointcurve constraint.
• The CVCV statement uses two curves to define a curvecurve 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).
See other Reference data available.
57 CVCV
C++ Statements
CVCV
The CVCV statement defines a curvetocurve 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 threedimensional motion.
Format
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 xy 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.
Adams/Solver
C++ Statements
58
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 xaxis is along the tangent at the
instantaneous contact point, its yaxis is along the instantaneous normal, and its zaxis
along the resultant binormal. For a CVCV constraint, the binormal of ICURVE is always
parallel to the zaxis 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 xy plane of the IRM marker coordinate system. The
IFLOAT and IRM markers must lie on the same part.
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 xy plane of the JRM marker.
59 CVCV
C++ Statements
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 constraint initial conditions.
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 xaxis is along the tangent at the instantaneous contact
point, its yaxis is along the instantaneous normal, and its zaxis along the resultant bi
normal. For a CVCV constraint, the binormal of JCURVE is always parallel to the zaxis
of the JRM marker. The JFLOAT and JRM markers must lie on the same part.
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 xy 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 point is stationary on the curve.
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
Adams/Solver
C++ Statements
60
Extended Definition
The CVCV statement defines a curvetocurve 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 1 below shows a curvetocurve constraint.
A CVCV statement removes two degreesoffreedom 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 CurveToCurve Constraint
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.
61 CVCV
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 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 overconstrain a system using the CVCV constraint. For
instance, in a camfollower 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.
Adams/Solver
C++ Statements
62
Figure 2 Convex and Nonconvex Curves
Examples
CVCV/20, IFLOAT=402, ICURVE=11, IRM=401, JFLOAT=502,
, JCURVE=12, JRM=501
This statement creates a curvecurve 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 camfollower
mechanism. Figure 3 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 pointtocurve 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 liftoff 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.
63 CVCV
C++ Statements
Figure 3 CamFollower Mechanism
See other Constraints available.
Adams/Solver
C++ Statements
64
DEBUG
The DEBUG statement outputs data that helps you debug a simulation.
Format
DEBUG/ EPRINT
JMDUMP ,
RHSDUMP ,
, MATLAB
[ ] Optionally select the item
[[ ]] Optionally select an item combination
65 DEBUG
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
Adams/Solver
C++ Statements
66
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 (C++) is printing the information for the third step of a dynamic analysis.
For this step, Adams/Solver (C++) uses a secondorder polynomial to guess the solution. Using a time
step of 7.25694E04, the integration step goes from 6.458333333E04 to 1.371527778E03.
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.E04. Adams/Solver (C++) updates the Jacobian before the first iteration, but not
before the second or third.
JMDUMP Dumps the Jacobian matrix at each iteration. The Jacobian is dumped in the working directory in the
file jac.dmp.
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, etc.
RHSDUMP Dumps the state vector, RHS array (error terms), and DELTA array (increment to state vector) at each
iteration. The data is dumped into the file rhs.dmp in the working directory.
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.
67 DEBUG
C++ Statements
Figure 4 Sample EPRINT Information
See other Analysis parameters available.
Adams/Solver
C++ Statements
68
DIFF
The DIFF statement creates a userdefined state variable and defines a firstorder differential equation
that describes it.
Format
69 DIFF
C++ Statements
Argument
Specifies an expression for a differential equation or defines the
argument list for the userwritten 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 userwritten 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 userwritten 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 userdefined variable and,
optionally, an approximate value of the initial time derivative.
The value r1 is the value of the userdefined 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 userdefined 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.
ROUTINE=libname::subname Specifies an alternative library and name for the user subroutine
DIFSUB.
Learn more about the ROUTINE Argument.
STATIC_HOLD Indicates that the DIFF state is not permitted to change during
static and quasistatic analysis.
Adams/Solver
C++ Statements
70
Extended Definition
The DIFF statement creates a userdefined state variable and defines a firstorder differential equation
that 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 userwritten 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. Userwritten 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 userwritten subroutine. Because
Adams/Solver (C++) typically handles a function expression more efficiently than a userwritten
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:
= f (y, u, t)
where:
• is the time derivative of the userdefined state variable
• y is the userdefined state variable itself
• u is a vector of Adams/Solverdefined 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, , u, t)
y
·
y
·
y
·
71 DIFF
C++ Statements
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.
+ 2y  4 = sin (t), y(0) = 1.75
DIFF/11 defines the equation in explicit form, where the function expression computes as shown
below.
= 2y + 4 + sin (t)
DIFF/12 defines the equation in implicit form, where Adams/Solver equates the function expression to
zero, as shown below.
+ 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
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 usersupplied initialcondition 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 userdefined variables as the initial values for any subsequent analysis, just
as with the equilibrium displacement and force values.
However, the userspecified initial conditions are retained as the static equilibrium
values if STATIC_HOLD is specified. Thus, the final equilibrium values are the
same as the userspecified initial conditions. Note that this does not guarantee that
the time derivatives of the userdefined variable are zero after static analysis.
y
·
y
·
y
·
y
·
Adams/Solver
C++ Statements
72
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.
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.
73 END
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.
Adams/Solver
C++ Statements
74
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
Arguments
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
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.
ENVIRONMENT NAME c
ENVIRONMENT NAME c VALUE . = c
ENVIRONMENT NAME c UNSET . =
=
=
75 ENVIRONMENT
C++ Statements
variables used by vertical applications or other products are not included in the Adams/Solver (C++)
runtime environment.
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 Userenvironment 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:
Adams/Solver
C++ Statements
76
List of Userenvironment 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.
* 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.
See other Analysis parameters available.
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.
77 EQUILIBRIUM
C++ Statements
EQUILIBRIUM
The EQUILIBRIUM statement specifies error tolerances and other parameters for static equilibrium and
quasistatic equilibrium analyses.
Format
Arguments
ALIMIT=r Specifies the maximum angular increment allowed per iteration during a static
or quasistatic 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.0E04
Range: ERROR > 0
EQUILIBRIUM/
ALIMIT = r
ERROR = r ,
IMBALANCE = r ,
MAXIT = i ,
PATTERN = c1 [:...: c10] ,
STABILITY = r ,
TLIMIT = r ,
METHOD =i ,
ATOL = r ,
RTOL = r ,
MAXITL = i ,
ETAMAX = r ,
ETA = r ,
¹ )
¦ ¦
¦ ¦
¦ ¦
¦ ¦
¦ ¦
¦ ¦
¦ ¦
¦ ¦
¦ ¦
¦ ¦
¦ ¦
¦ ¦
¦ ¦
´ `
¦ ¦
¦ ¦
¦ ¦
¦ ¦
¦ ¦
¦ ¦
¦ ¦
¦ ¦
¦ ¦
¦ ¦
¦ ¦
¦ ¦
¦ ¦
¦ ¹
{ } Select one item
    Optionally select an item combination
Adams/Solver
C++ Statements
78
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.0E04
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 NewtonRaphson algorithm).
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.0E05
Range: STABILITY >0
TLIMIT=r Specifies the maximum translational increment allowed per iteration.
Default: 20
Range: TLIMIT > 0
79 EQUILIBRIUM
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. TensorKrylov block3
f. TensorKrylov block2+
3. AGGRESSIVE, runs, in order, the following methods until one shows
progress:
a. ORIGINAL
b. ORIGINAL+Krylov
c. ORIGINAL+UMF
d. Newton+Krylov
e. TensorKrylov block3
f. TensorKrylov block2+
g. BroydenArmijo
h. TrustRegion
4. ALL, runs, in order, all the available methods, until one shows
progress:
a. ORIGINAL
b. ORIGINAL+Krylov
c. ORIGINAL+UMF
d. Newton+Krylov
e. TensorKrylov block3
f. TensorKrylov block2+
g. BroydenArmijo
h. TrustRegion
i. HookeJeeves
Default: ORIGINAL
Adams/Solver
C++ Statements
80
ATOL Specifies the absolute tolerance value
Default: 1.0e6
Range: 0.0 < ATOL < 1.0
RTOL Specifies the relative tolerance value
For all solvers, except ORIGINAL and ORIGINAL+Krylov, the tolerance is
defined as : TOL=ATOL+x
IC
*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 HookeJeeves 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 TensorKrylov 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
EisenstatWalker 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 TensorKrylov 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.0e4
Range: 0.0 < ETA < 1.0
Specifies the dimensionless radius of the trustregion for Trustregion method.
The smaller the value, the more the refinement of Trustregion solution (hence
more work).
Range: 0.0 < ETA < 0.25
81 EQUILIBRIUM
C++ Statements
Extended Definition
The EQUILIBRIUM statement specifies error tolerances and other parameters for static and quasistatic
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:
• Single static equilibrium analysis.
• Series of static equilibrium analyses over time, for example, a quasistatic equilibrium analysis.
Static and quasistatic 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 NewtonRaphson 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 quasistatic 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. TensorKrylov block 3 solver uses TensorKrylov method [2.], flavor block 3.
5. TensorKrylov block 2+ solver uses TensorKrylov method [2.], flavor block 2+.
6. BroydenArmijo solver uses Broyden method [1.] with an Armijo linesearch [1.] to account for
global strategies.
7. TrustRegion method Solver uses the Trust Region optimization algorithm [3.].
8. HookeJeeves solver uses the HookeJeeves optimization method [4.].
Adams/Solver
C++ Statements
82
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 NewtonRaphson 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.0E04 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 bitmask with 9 bits, corresponding to the eight solvers above in the
order: ORIGINAL (bit0), ORIGINAL+Krylov (bit1), ORIGINAL+UMF
(bit2), Newton+Krylov (bit3), TensorKrylov block3 (bit4), TensorKrylov
block2+ (bit5), BroydenArmijo (bit6), TrustRegion (bit7), HookeJeeves
(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, BroydenArmijo, and TrustRegion
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, i.e.,
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 quasistatic 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 nonzero value, then its value
overrides the METHOD setting.
83 EQUILIBRIUM
C++ Statements
Examples
EQUILIBRIUM/ STABILITY=0.01, TLIMIT=10
, IMBALANCE=1.0E05
This EQUILIBRIUM statement instructs Adams/Solver (C++) to use these values instead of the defaults
when performing a static or quasistatic 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.0E05 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. TensorKrylov Methods for Solving LargeScale 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.
See other Analysis parameters available.
Adams/Solver
C++ Statements
84
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
85 FEMDATA
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, 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 hotspot 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
ON
Outputs modal deformations as a function of time of the specified flexible
body. FEMDATA will only export coordinates of the active modes in the
simulation.
NODAL_DEFORMATI
ON
Outputs nodal deformations as a function of time of the specified flexible.
FEMDATA writes the formations in the simulation set of units.
Adams/Solver
C++ Statements
86
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 =
FX:FY:FZ:FMAG:GMA
G: TX:TY:TZ:TMAG
Specifies that FEM load data are to be output only at those time steps where
the specified peak load occurred in the simulation. With the START, END, or
SKIP 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).
87 FEMDATA
C++ Statements
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
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 (normalX, normalY, normalZ, shearXY, shearYZ,
shearZX). 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 (normalX,
normalY, normalZ, shearXY, shearYZ, shearZX). 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.
Type of data: Format:* File name: Extension:
(none) (none) <run_name> .fem
Loads DAC
NASTRAN
ABAQUS
ANSYS
RPC
<run_name>_<channel_id>
<run_name>_<body_name>
<run_name>_<body_name>
<run_name>_<body_name>
<run_name>
.dac
.dat
.dat
.dat
.rsp
Modal Deformation DAC
Generic
NASTRAN
PUNCH
ANSYS
RPC
<run_name>_<channel_id>
<run_name>_<body_name
<run_name>_<body_name>
<run_name>_<body_name>
<run_name>
<run_name>
.dac
.mdf
.mdf
.mdf
.out
.rsp
Adams/Solver
C++ Statements
88
*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
Nodal Deformation Generic
NASTRAN
ANSYS
<run_name>_<body_name>
<run_name>_<body_name>
<run_name>_<body_name>
.ndf
.spc
.inp
Strain DAC
Generic
<run_name>_<node_id>e_<channel_id>
<run_name>_<body_name>
.dac
.nsf
Hotspots <run_name>_body_name>_hots .tab
Stress DAC
Generic
<run_name>_<node_id>se_<channel_id>
<run_name>_<body_name>
.dac
.nsf
Hotspots <run_name>_<body_name>_hote .tab
Type of data: Format:* File name: Extension:
89 FEMDATA
C++ Statements
<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
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:
• F
m
(t) represents the force acting on the body at Marker m.
• 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,  ( )  = 1)
Then the following conditions apply:
• FX = Output loads at time t when is a maximum and minimum for each marker
m.
r
ˆ
x
r
ˆ
y
r
ˆ
z
. .
r
ˆ
x
r
ˆ
y
r
ˆ
z
. .
F
m
t ( )
r
ˆ
x t ( ) ·
Adams/Solver
C++ Statements
90
• FY = Output loads at time t when is a maximum and minimum for each marker
m.
• FZ = Output loads at time t when is a maximum and minimum for each marker
m.
• FMAG = Output loads at time t when is a maximum for each marker m.
• GMAG = Output loads at time t when
• .
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 secondorder tensors, the following equation is used to transform these
quantities to a reference coordinate system:
Where is the skewrotation matrix from the flexible body’s LPRF (FE origin) to the marker’s
coordinate reference, and is the symmetric stress or strain tensor. That is:
F
m
t ( )
r
ˆ
y t ( ) ·
F
m
t ( )
r
ˆ
z t ( ) ·
F
m
t ( ) r
ˆ
t ( ) ·
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).
o
A
R
S
91 FEMDATA
C++ Statements
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.
S  
S
xx
S
xy
S
xz
S
yx
S
yy
S
yz
S
zx
S
zy
S
zz
= where S
ij
S
ji
=
Adams/Solver
C++ Statements
92
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.
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
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.
93 FEMDATA
C++ Statements
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.
FEMDATA/100, LOADS, FLEX_BODY=101
, FILE = conrod
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.
Adams/Solver
C++ Statements
94
FIELD
The FIELD statement applies a translational and rotational actionreaction force between two markers.
Format
95 FIELD
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 thirtysix 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 forcetime
per unit displacement and torquetime 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 zaxis of the J marker and the torque
components about the x, y, and zaxis of the J marker, respectively. FORCE
is optional and defaults to six zero entries.
FUNCTION=USER(r
1[,...,r30])
Defines and passes constants to the userwritten subroutine FIESUB to define
a nonlinear 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.
Adams/Solver
C++ Statements
96
Extended Definition
The FIELD statement applies a translational and rotational actionreaction force between two markers.
To specify a linear field, use the arguments in the FIELD statement to specify constants for the sixby
six stiffness matrix,a preload force, a six reference lengths, and a sixbysix damping matrix. The
stiffness and damping matrices must be positive semidefinite, but need not be symmetric. To specify a
nonlinear field, use the userwritten 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.
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 thirtysix 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::
subname
Specifies an alternative library and name for the user subroutine FIESUB.
Learn more about the ROUTINE Argument.
97 FIELD
C++ Statements
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.
For a nonlinear field, the following constitutive equations are defined in the FIESUB subroutine:
Adams/Solver (C++) applies the defined forces and torques at the I marker. In the linear and nonlinear
equations:
• F
x
, F
y
, and F
z
are the three translational force measure numbers.
• T
x
, T
y
, and T
z
are the three rotational force measure numbers associated with unit vectors
directed along the x, y, and zaxis of the J marker.
• K is the stiffness matrix.
• x
0
, y
0
, z
0
, a
0
, b
0
, and c
0
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.
• V
x
,V
y
,V
z
, , , and are the time derivatives of the deformation, respectively; C is the
damping matrix.
• F
1
, F
2
, F
3
, T
1
, T
2
, and T
3
are the translational and the rotational pretensions.
F
x
F
y
F
z
T
x
T
y
T
z
K
11
K
12
K
13
K
14
K
15
K
16
K
21
K
22
K
23
K
24
K
25
K
26
K
31
K
32
K
33
K
34
K
35
K
36
K
41
K
42
K
43
K
44
K
45
K
46
K
51
K
52
K
53
K
54
K
55
K
56
K
61
K
62
K
63
K
64
K
65
K
66
–
x x
0
–
y y
0
–
z z
0
–
a a
0
–
b b
0
–
c c
0
–
C
11
C
12
C
13
C
14
C
15
C
16
C
21
C
22
C
23
C
24
C
25
C
26
C
31
C
32
C
33
C
34
C
35
C
36
C
41
C
42
C
43
C
44
C
45
C
46
C
51
C
52
C
53
C
54
C
55
C
56
C
61
C
62
C
63
C
64
C
65
C
66
V
x
V
y
V
z
e
x
e
y
e
z
F
1
F
2
F
3
T
1
T
2
T
3
+ – =
F
x
f
1
x y z a b c V
x
V
y
V
z
e
x
e
y
e
z
. . . . . . . . . . . ( ) =
F
y
f
2
x y z a b c V
x
V
y
V
z
e
x
e
y
e
z
. . . . . . . . . . . ( ) =
F
z
f
3
x y z a b c V
x
V
y
V
z
e
x
e
y
e
z
. . . . . . . . . . . ( ) =
T
x
f
4
x y z a b c V
x
V
y
V
z
e
x
e
y
e
z
. . . . . . . . . . . ( ) =
T
y
f
5
x y z a b c V
x
V
y
V
z
e
x
e
y
e
z
. . . . . . . . . . . ( ) =
T
z
f
6
x y z a b c V
x
V
y
V
z
e
x
e
y
e
z
. . . . . . . . . . . ( ) =
e
x
e
y
e
z
Adams/Solver
C++ Statements
98
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.
F
j
= F
i
T
j
= T
i
 L x F
i
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.
Tip: • A FIELD statement can define any sixcomponent, actionreaction force.
However, when defining massless beams, you may want to use a BEAM
statement. It requires only six input values to compute the thirtysix values for the
Kmatrix (see BEAM).
• Finite element analysis programs can give the values for CMATRIX and
KMATRIX.
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 zaxis 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:
x
t
K x > 0 for all nonzero displacements x, and
y
t
C y > 0 for all nonzero 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.
99 FIELD
C++ Statements
Examples
Consider a cantilever, semimonocoque wing structure like the figure below.
Cantilever, Semimonocoque Wing Structure
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:
Inserting these entries into a full sixbysix FIELD array yields:
X Z y
X 0.198E+04 0.126E01 0.147E+04
Z 0.126E01 0.208E+03 0.933E02
y 0.147E+04 0.933E02 0.763E+07
X Y Z x y z
X 0.198E+04 0 0.126E01 0 0.147E+04 0
Y 0 0 0 0 0 0
Z 0.126E01 0 0.208E+03 0 0.933E02 0
x 0 0 0 0 0 0
u
u
u u u
u
Adams/Solver
C++ Statements
100
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.126E01, 0, 0.147E+04, 0,
, 0, 0, 0, 0, 0, 0,
, 0.126E01, 0, 0.208E+03, 0, 0.933E02, 0,
, 0, 0, 0, 0, 0, 0,
,0.147E+04, 0, 0.933E02, 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).
See other Forces available.
y 0.147E+04 0 0.933E02 0 0.763E+07 0
z 0 0 0 0 0 0
u
u
101 FLEX_BODY
C++ Statements
FLEX_BODY
The FLEX_BODY statement defines a linear elastic body. The FLEX_BODY is capable of undergoing
large motion, 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.
Format
FLEX_BODY/id ,MATRICES= id1 , ... , idn
[[,QG=x,y,z, REULER=a,b,c]]
[,INVARIANTS=c1, ..., c9]
CRATIO=
e
USER(r1, [ r2, ..., r30])
¹ )
´ `
¦ ¹
\ ,
GDAMP =
OFF
FULL
INTERNAL_ONLY
¹ )
¦ ¦
´ `
¦ ¦
¦ ¹
,
VX=x ,
VY=y ,
VZ=z ,
WX=x ,
WY=y ,
WZ=z ,
DMODE=a1, a2, ..., an ,
VMODE=a1, a2, ..., an ,
[,VM=id] [,WM=id]
[ ,EXACT=c1, ..., c6] [ ,MEXACT=d1, ..., dn]
[ ,MNF_FILE=file_name]
[ ,DB_FILE=file_name] [ ,INDEX=index]
[ ,CHAR_LEN=c_len]
[ ,DYNAMIC_LIMIT=d]
[ ,STABILITY_FACTOR=s]
Adams/Solver
C++ Statements
102
{ } Select one item
[ ] Optionally select the item
[[ ]] Optionally select an item combination
103 FLEX_BODY
C++ Statements
Arguments
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 userwritten
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 userwritten 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 userwritten 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.
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.
This is one of the two ways to specify the detailed properties of a
flexible body (See MNF_FILE for the alternative). Note that this
argument (or MNF_FILE) is not required by Adams/Solver (C++)
unless flexible body contact is defined, but is required by
Adams/View.
Adams/Solver
C++ Statements
104
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, i.e., the dynamic effects ( and terms) are ignored in
dynamic simulation. So for quasistatic mode, the equation of motion
is just , 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 highfrequency modes.
The damping specified by CRATIO or GDAMP will be ignored for
quasistatic modes. Please refer to STABILITY_FACTOR on how to
specify damping on quasistatic modes.
Default: +
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
q
··
q
·
Kq F =
·
105 FLEX_BODY
C++ Statements
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
Adams/Solver
C++ Statements
106
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 secondorder deformation corrections to
the inertia tensor, and the firstorder 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 nonzero 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
107 FLEX_BODY
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.
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.
INVAR4: Invariant 4.
INVAR5: Invariant 5.
INVAR6: Invariant 6  the generalized mass.
INVAR7: Invariant 7  the moment of inertia.
INVAR8: Invariant 8.
INVAR9: Invariant 9.
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
Adams/Solver
C++ Statements
108
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.
This is one of the two ways to specify the detailed properties of a
flexible body (See DB_FILE for the alternative). Note that this
argument( or DB_FILE) is not required by Adams/Solver (C++)
unless flexible body contact is defined, but is required 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 313 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 zaxis of ground, new xaxis, and new zaxis
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
109 FLEX_BODY
C++ Statements
STABILITY_FACTOR=s Specifies the stability factor for quasistatic modes when the dynamic
limit feature is enabled on this flexible body. If the modal force acting
on quasistatic 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 quasistatic mode will be
, where is the frequency of the mode.
Default: 10.0
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=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 xaxis (VX), yaxis (VY), and zaxis (VZ) of
the VM coordinate system.
Default: 0
Range: Real values
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 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 xaxis
(WX), yaxis (WY), and zaxis (WZ) of the WM coordinate system.
Default: 0
Range: Real values
2seq
·
Kq + F = e
Adams/Solver
C++ Statements
110
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
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).
• If your FLEX_BODY undergoes highspeed, 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, reorientating the BCS with respect to the body requires you to reorient the
finite element model with respect to its basic coordinate system. In MSC.Nastran,
this can be done easily with CORDxx Bulk Data entries.
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++).
• The FLEX_BODY does not support floating markers. Consequently, the reaction
forces from a GFORCE, VFORCE, or VTORQUE cannot act on a FLEX_BODY.
• 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.
111 FLEX_BODY
C++ Statements
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(FXFREQ100:0.01,0.1,if(FXFREQ1000: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.
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, 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 quasistatic 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 quasistatic mode. No damping is applied to the quasistatic modes (Note
that solution may become unstable if there is high frequency excitation).
Adams/Solver
C++ Statements
112
See other Inertia and material data statement available.
113 FRICTION
C++ Statements
FRICTION
The FRICTION statement defines parameters for frictional forces on translational, revolute, cylindrical,
hooke, universal, and spherical joints.
Format
Note: Frictional forces and torques are computed by Adams/Solver (C++) using a friction model
that supports dynamic friction and stiction.
Adams/Solver
C++ Statements
114
Arguments
BALL_RADIUS=Rb Defines the radius of the ball in a spherical joint for use in frictionforce and
torque calculations.
Default: 1.0
Range: BALL_RADIUS > 0
BENDING_REACTIO
N_ARM=Rb
Defines the effective moment arm use to compute the contribution of the
bending moment on the net friction torque in revolute, hooke, and universal
joints.
Default: 1.0
Range: BENDING_REACTION_ARM > 0
STICTION_TRANSITI
ON_VELOCITY=r
Defines the absolute velocity threshold for the transition 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.
Default: 0.1 length units/unit time on the surface of contact in the joint.
Range: STICTION_TRANSITION_VELOCITY > 0
EFFECT={ALL[[STIC
TION, SLIDING]]}
Defines the frictional effects included in the friction model. Stiction is static
friction effect, while sliding is dynamicfriction effect. Excluding stiction in
simulations that don’t require it can greatly improve simulation speed.
Default: All
FRICTION_FORCE_P
RELOAD=r
Defines the joint’s preload frictional force, which is usually caused by
mechanical 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 quasistatic
solution.
Default: none
Range: Static
115 FRICTION
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 [[PRELOAD:
REACTION_FORCE:
BENDING_MOMENT:
TORSIONAL_MOMEN
T]]} )
Defines the input forces to the friction model. By default, all userdefined
preloads and jointreaction force and moments are included. You can
customize the frictionforce model by limiting the input forces you list in the
statement.
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_DEF
ORMATION=r
Defines the maximum creep that can occur in a joint during the stiction
regime. 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
Adams/Solver
C++ Statements
116
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
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
Range: MU_STATIC > 0
OVERLAP_DELTA={I
NCREASE,
DECREASE,
CONSTANT}
To define friction in a sliding joint (either a translational or a cylindrical
joint), 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
PIN_RADIUS=Rp Defines the radius of the pin for a revolute, cylindrical, hooke, or universal
joint.
Default: 1.0
Range: PIN_RADIUS > 0
117 FRICTION
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.
REACTION_ARM=Rn Defines the effective moment arm of the jointreaction torque about the
translational joint’s axial axis (the zdirection 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_
PRELOAD=r
Defines the preload friction torque in the joint, which is usually caused by
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.
Adams/Solver
C++ Statements
118
Table 1 Legend for Block Diagrams
Table 2 Relationship Between the INPUTS Argument and Switches Used in the
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
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
119 FRICTION
C++ Statements
Friction Regime Determination (FRD)
Three friction regimes are permissible in Adams:
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++).
Dynamic friction A joint is in dynamic friction if its joint velocity magnitude exceeds
1.5 times the stiction transition velocity. The dynamic coefficient of
friction (md) is used in the computation of frictional forces.
Transition between dynamic
and static friction
If the joint velocity magnitude is between 1 and 1.5 times the stiction
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).
Adams/Solver
C++ Statements
120
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 lengthunitradius pin and an effectivefrictionmoment arm
that is at the end caps of 8.2 length units.
• The friction model includes dynamic and stictionfriction effect. The staticfriction coefficient
is .03 and the dynamicfriction coefficient is .024.
• When computing the frictional force, Adams/Solver (C++) identifies only the jointreaction
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.
See other Forces available.
121 GCON
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 nonholonomic constraints.
Format
GCON/id [, I=id], FUNCTION=exp
Arguments
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 nonholonomic constraints. Holonomic
constraints only depend on position measures, like GCON/111 through GCON/113 above. A constraint
is nonholonomic if (a) its expression exp
1
contains velocity measures, and (b) there is no expression exp
2
that is the time integral of exp
1
. An example of a nonholonomic 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 nonholonomic 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 an expression that does not depend on velocity quantities. The previous
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, GCOND 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.
Adams/Solver
C++ Statements
122
GCON is therefore in Pfaffian form, since , and , which makes
the FUNC linear in velocity quantities.
Another example of a Pfaffian nonholonomic 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 nonPfaffian 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)
For this example, , which is an expression that depends on
the 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.
FUNC c
VX 2 ( ) c
 1 =
FUNC c
WZ 2 ( ) c
 DX 2 ( ) – =
FU c
VX 2 3 ( , ) ( ) c
 2 VX 2 3 ( , ) DX 2 1 ( , ) · · =
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
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.
123 GCON
C++ Statements
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
JOINT/2, REVOLUTE, I = 7, J = 8
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 zaxis 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
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 positionlevel GCON, the FUNCTION must be at least three times
differentiable. If the GCON introduces a velocitylevel 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.
Adams/Solver
C++ Statements
124
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/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 nonholonomic 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 zaxis of marker 10, and the ’%’ corresponds to the cross
product. Likewise, DXYZ(10,6) represents the threedimensional 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 degreeoffreedom and become
a dynamic model. This is because one displacement constraint has been eliminated and replaced with a
velocity constraint.
Applications
The userdefined 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.
125 GCON
C++ Statements
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 steadystate 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 userdefined motions that relate time and various position and
velocity measures.
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 velocitylevel 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.
• GCON is a new modeling element only available in the Adams/Solver (C++). Currently there is
no support for defining GCON through Adams/View, so you need to edit the .adm file to add
userdefined constraints. Adams/View correctly imports the edited .adm file, and the internal
Adams/Solver (C++) from within Adams/View correctly handles the simulation of the model.
• If you use GCON to constrain the values of DIFF, LSE, 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.
See other Constraints available.
Adams/Solver
C++ Statements
126
GEAR
The GEAR statement defines a gear pair constraint. Examples include a spur, helical, planetary, bevel,
and rackandpinion gear pairs.
Format
GEAR/id, JOINTS=id1,id2, CV=id
Arguments
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 zaxis 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 zaxis 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
CV=id Identifier of the marker that designates the point of contact and implicitly
determines the ratio of the two gears. The zaxis 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.
127 GEAR
C++ Statements
J markers for both joints associated with the GEAR element must belong to the carrier part (the part that
hosts the CV marker).
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
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.
Adams/Solver
C++ Statements
128
, REULER=0, 90D, 0
MARKER/301, PART=3, QP=10, 0, 0
, REULER=0,90D, 0
JOINT/23, I=202, J=302, REVOLUTE
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 rackandpinion gear pair.
RackandPinion Gear Par
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
MARKER/101, PART=1, QP=0,0,0
MARKER/301, PART=3, QP=0,0,0
JOINT/23, I=202, J=302, REVOLUTE
MARKER/202, PART=2, QP=0,10,0
, REULER=90D,90D,0
MARKER/302, PART=3, QP=0,10,0
, REULER=90D,90D,0
129 GEAR
C++ Statements
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).
See other Constraints available.
Adams/Solver
C++ Statements
130
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
userspecified function expressions in the Adams/Solver (C++) dataset or through userwritten
subroutines.
Format
Arguments
FUNCTION=USER(r1[,...,r30) Specifies up to thirty userdefined constants to compute the force
components in a userdefined 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 xaxis of the RM marker.
FY=e Specifies the magnitude and sign of the y component of the GFORCE
translational force. Adams/Solver (C++) applies this force parallel to
the yaxis of the RM marker.
FZ=e Specifies the magnitude and sign of the z component of the GFORCE
translational force. Adams/Solver (C++) applies this force parallel to
the zaxis of the RM marker.
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.
131 GFORCE
C++ Statements
Extended Definition
A GFORCE statement defines a force element that consists of three mutually orthogonal translational
force components and three orthogonal torque components. You may define the GFORCE statement
through userspecified function expressions in the Adams/Solver (C++) dataset or through userwritten
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.
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 userwritten FORTRAN77 subroutines.
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.
ROUTINE=libname::subname Specifies an alternative library and name for the user subroutine
GFOSUB.
Learn more about the ROUTINE Argument.
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 xaxis of the RM marker in the sense of the righthand rule (that
is, a positive torque causes a counterclockwise rotation).
TY=e Specifies the magnitude and sign of the y component of the GFORCE
rotational torque. Adams/Solver (C++) applies this torque parallel to
the yaxis of the RM marker in the sense of the righthand rule (that
is, a positive torque causes a counterclockwise rotation).
TZ=e Specifies the magnitude and sign of the z component of the GFORCE
rotational torque. Adams/Solver (C++) applies this torque parallel to
the zaxis of the RM marker in the sense of the righthand rule (that
is, a positive torque causes a counterclockwise rotation).
Adams/Solver
C++ Statements
132
The vector formed by the three userdefined 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
where:
• F
a
is the translational action applied to the I marker.
• FX is the userdefined function for the xcomponent force magnitude.
• FY is the userdefined function for the ycomponent force magnitude.
• FZ is the userdefined function for the zcomponent force magnitude.
• T
a
is the rotational action applied to the I marker.
• TX is the userdefined function for the xcomponent according to the righthand rule.
• TY is the userdefined function for the ycomponent according to the righthand rule.
• TZ is the userdefined function for the zcomponent according to the righthand rule.
• is a unit vector along the + xdirection of the RM marker.
• is a unit vector along the + ydirection of the RM marker.
• is a unit vector along the + zdirection of the RM marker.
Reaction
Applied to: JFLOAT marker
Values:
F
r
= F
a
T
r
= T
a
F
a
FXx
ˆ
rm
FYy
ˆ
rm
FZz
ˆ
rm
+ + =
T
a
TXx
ˆ
rm
TYy
ˆ
rm
TZz
ˆ
rm
+ + =
x
ˆ
rm
y
ˆ
rm
z
ˆ
rm
133 GFORCE
C++ Statements
where F
r
and T
r
are the translational and rotational reactions applied at the JFLOAT marker, respectively.
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, sixcomponent 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.
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.
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 userdefined forces FX, FY, FZ, TX, TY, and TZ should be smooth, continuous, and
singlevalued. These conditions make the solution process very effective.
Adams/Solver
C++ Statements
134
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 of application (with respect to the part containing the JFLOAT marker) and its resultant direction
(with respect to the RMmarker). 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 appropriatelyoriented markers, to accomplish the same
thing.
See other Forces available.
135 GRAPHICS
C++ Statements
GRAPHICS
The GRAPHICS statement creates:
• Two or threedimensional geometry for CONTACT. You always define the geometry with
respect to a reference marker.
• Threedimensional 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
GRAPHICS/id
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] ,
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
[ ] Optionally select the item
Adams/Solver
C++ Statements
136
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
xaxis 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 zaxes 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 zaxis 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 yaxes
of the RM marker, and must contain the origin of the marker.
137 GRAPHICS
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 zaxis 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 xaxis 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 zaxes 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 threedimensional 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.
Adams/Solver
C++ Statements
138
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
(brep) 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 zaxis 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
starting at the xaxis of the CM marker.
• 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 zaxis 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 zaxis of the CM marker, and
a negative value specifies a cylinder or frustum along the negative zaxis of the CM
marker.
MAJOR_RADI
US
Specifies the larger radius of the torus.
MINOR_RADI
US
Specifies the smaller radius of the torus.
PID Defines the id of the curve, arc, or circle graphic to extrude along.
139 GRAPHICS
C++ Statements
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 xy plane of the RM marker (that is, the zaxis 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 twodimensional element, and, therefore, you can only use it when
defining contact with another twodimensional 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 righthand rule) about the z
axis of the CM marker. Adams/Solver (C++) assumes RANGLE is in radians. The
angle starts at the positive xaxis 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 CMR marker is the axis of revolution.
• GID to specify the id of the closed curve or circle graphic to be revolved.
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
zaxis, and the center of the top is at the position on the CM marker zaxis 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 zaxis
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.
t t
Adams/Solver
C++ Statements
140
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 crosssection, which has a radius of two. The cylinder has a length of two along the
negative zaxis of Marker 0201.
GRAPHICS/1297, EXTERNAL, RM=7921,
, FILE = GenevaWheel.xmt_txt
, ELEMENT = Geneva
This GRAPHICS statement creates a threedimensional 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.
XMIN=r,
XMAX = y,
YMIN = r,
YMAX = r
Specifies the boundary edges of a plane. XMIN, XMAX, YMIN, and YMAX are
relative to the CM marker of the plane.
Range: XMIN < XMAX
YMIN < YMAX
XCALE = r,
YSCALE = r,
ZSCALE = r
Specifies the diameters along the x, y, and zaxes of an ellipsoid.
Range: XSCALE > 0
YSCALE > 0
ZSCALE > 0
141 GRAPHICS
C++ Statements
Geometry in Parasolid File GenevaWheel.xmt_txt
Adams/Solver
C++ Statements
142
Graphics for Graphic Display of Objects
Format
GRAPHICS/id,
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 ]
SPDP, I = id, J = id
DA = r, , COILS = i
DB = r, LA = r, LC = r ,
DC = r, LB = r, LD= r ,
FORCE,
ETYPE = ALL, EMARKER = id
ETYPE=
BEAM
BUSHING
FIELD
SFORCE
SPDP
VFORCE
VTORQUE
GFORCE
NFORCE
JOINT
JPRIM
PTCV
CVCV
¹ )
¦ ¦
¦ ¦
¦ ¦
¦ ¦
¦ ¦
¦ ¦
¦ ¦
¦ ¦
¦ ¦
´ `
¦ ¦
¦ ¦
¦ ¦
¦ ¦
¦ ¦
¦ ¦
¦ ¦
¦ ¦
¦ ¦
¦ ¹
, EID= id, EMARKER = id
¹ )
¦ ¦
¦ ¦
¦ ¦
¦ ¦
¦ ¦
¦ ¦
¦ ¦
¦ ¦
¦ ¦
¦ ¦
¦ ¦
´ `
¦ ¦
¦ ¦
¦ ¦
¦ ¦
¦ ¦
¦ ¦
¦ ¦
¦ ¦
¦ ¦
¦ ¦
¦ ¦
¦ ¹
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
[ ] Optionally select the item
[[ ]] Optionally select an item combination
143 GRAPHICS
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 zaxis, 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 zaxis 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 zaxis is normal to the bottom
plane of the cylinder or the frustum. For the torus the zaxis should be the axis of
the revolution.
COILS Defines the number of coils in the spring of a springdamper (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 springdamper (see the springdamper figure
below). There is no limit on the value of r.
Default: 0
DB=r Defines the diameter of the damper in a springdamper at the I marker (see the
springdamper figure below). There is no limit on the value of r.
Default: 0
DC=r Defines the diameter of the damper in a springdamper at the J marker (see the
springdamper figure below). There is no limit on the value of r.
Default: 0
Adams/Solver
C++ Statements
144
SpringDamper
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,
BEAM,
BUSHING,
FIELD,
SFORCE, SPDP,
VFORCE,
VTORQUE,
GFORCE,
NFORCE,
JOINT, JPRIM,
PTCV, CVCV}
Specifies the element type for which Adams/Solver generates force graphics. In
combination with EID, ETYPE specifies one force statement. If ETYPE=ALL, then
Adams/Solver sums all forces applied to the EMARKER.
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.
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.
145 GRAPHICS
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 springdamper graphic. The I and J
markers define the attachment points of the springdamper.
LA=r Defines the distance between the I marker and the end of the damper to which it is
closest (see the SpringDamper 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 springdamper 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
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
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 zaxis 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 zaxis of the CM marker, and a
negative value specifies a cylinder or frustum along the negative zaxis of the CM
marker.
MAJOR_RADI
US
Defines the larger radius of the torus.
MINOR_RADIU
S
Defines the smaller radius of the torus.
OUTLINE=id1[,
...,id2500]
Creates visible and invisible line segments to connect at least two and not more than
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.
Adams/Solver
C++ Statements
146
RANGLE=r Defines an angle measured positive (according to the righthand rule) about the z
axis of the CM. Adams/Solver (C++) assumes RANGLE is in radians. The angle
starts at the positive xaxis 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
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 CMR marker is the axis of revolution.
• GID to specify the id of the closed curve or circle graphic to be revolved.
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 springdamper graphic representation (see the springdamper 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 springdamper, 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
zaxis, and the center of the top is at the position on the CM marker zaxis that
LENGTH specifies. There is no limit on the value of r.
t t t t
t t
147 GRAPHICS
C++ Statements
Extended Definition
The GRAPHICS statement creates threedimensional 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
GRAPHICS/0202, CYLINDER, CM=0201, RADIUS=2
, LENGTH=2, SIDES=20, SEG=20
This GRAPHICS statement creates a cylinder with its base at Marker 0201. Marker 0201 is located at the
center of the circular crosssection, which has a radius of two. The cylinder has a length of two along the
negative zaxis 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 twentysided 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.
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 zaxis
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 defined by
CORNER. The values of X, Y, and Z must be specified with respect to the marker
coordinate system.
Adams/Solver
C++ Statements
148
GSE
The GSE (General State Equation) statement lets you represent a subsystem that has arrays of input
variables (u), internal continuous states (x
c
), internal discrete states (x
d
), 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:
(1)
(2)
(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 x
c
are
defined in Equation (1) as explicit, firstorder, ordinary differential equations. The function f
c
(x
c
, u, t) is
specified in a userwritten subroutine, and is assumed to be continuous everywhere. (The names of this
and other userwritten subroutines are specified by the user via the ROUTINE or INTERFACE attributes
of the GSE statement.) Integrators in Adams/Solver (C++) evaluate f
c
(x
c
, u, t) as needed.
The states x
d
are defined in Equation (2) by the function f
d
(x
d(n)
, u, t
n
). This function is specified in a
second userwritten 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 x
d
are
assumed to be constant between sampling periods. In Equation (2), x
d(n)
is the short form for x
d
(t
n
).
The outputs y are defined in Equation (3) by g(x
c
, x
d
, u, t), and are sampled continuously. This function
is specified in a third userwritten 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 lowpass filter before feeding
those signals into the force element. You can use the TFSISO element to define a lowpass filter. Failure
to eliminate discontinuities in y is likely to cause significant numericalintegration difficulties.
The second way (mentioned above) of representing a GSE mathematically is described by replacing
Equation (1) above with (4) below:
(4)
This representation permits the modeling of implicitlydefined 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()
x
c
·
f
c
x
c
u t . . ( ) = x
c
t
0
( ) x
c0
=
x
d n 1 + ( )
f
d
x
d n ( )
u t
n
. . ( ) = x
d
t
0
( ) x
d0
=
y g x
c
x
d
u t . . . ( ) =
0 f
c
x
c
·
x
c
u t . . . ( ) = x
c
t
0
( ) x
c0
=
149 GSE
C++ Statements
to obtain the values of repectively, because the SYSARY subroutine does not
support access to this 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
with respect to , repectively.
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
x
·
c
x
c
x
d
and u . . .
f
c
x
c
·
x
c
u t . . . ( ) x
·
c
x
c
and u . .
Adams/Solver
C++ Statements
150
Arguments
FUNCTION=USER(r1[,...,r30]) Specifies the parameters that are to be passed to the userwritten
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 3 if IMPLICIT).
• GSE_OUTPUT is called to evaluate g() in Equation 2.
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 3.
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 statespace form as
given by Equation 1 (and the user is permitted to use any of the
available utility subroutines).
INTERFACE=
lib1::gse_deriv,
lib2::gse_update,
lib3::gse_output,
lib4::gse_samp,
lib5::gse_set_ns,
lib6::gse_set_nd,
lib7::gse_set_implicit,
lib8::gse_set_static_hold,
lib9::gse_set_sample_offset
Specifies an alternative library and subroutine names for the user
subroutines GSE_DERIV, GSE_UPDATE, GSE_OUTPUT,
GSE_SAMP, GSE_SET_NS, GSE_SET_ND,
GSE_SET_IMPLICIT, GSE_SET_STATIC_HOLD,
GSE_SET_SAMPLE_OFFSET respectively. The rules for the
INTERFACE argument are the same as for the ROUTINE argument.
Learn more about 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.
151 GSE
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 3 if IMPLICIT). The time derivatives of
the states of a GSE are evaluated by calling the userwritten
subroutine GSE_DERIV. NS defaults to zero when not specified.
ROUTINE=lib1::gse1,
lib2::gse2, lib3::gse3, lib4::gse4,
lib5::gse5
Specifies alternative library and subroutine names for the
deprecated user subroutines GSESUB, GSEXX, GSEXU, GSEYX,
GSEYU respectively.
Learn more about the ROUTINE Argument.
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 userwritten 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 quasistatic 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.
Adams/Solver
C++ Statements
152
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 two different kinds of systems. These are:
• Continuous Systems
• Discrete Systems
• Sampled Systems
• FeedForward Only System
Continuous Systems
Continuous systems can be represented either explicitly or implicitly. The explicit case is written in state
space form as:
(5)
(6)
where x
c
is called the state of the system, and contains n elements for an n
th
order system. In matrix
notation, x
c
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, 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.
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 specify SIZE on the ARRAY statement, it must have the same
value as the argument ND.
x
c
·
f
c
x
c
u t . . ( ) = x
c
t
0
( ) x
c0
=
y g x
c
u t , ( , ) =
153 GSE
C++ Statements
Using this system description, a nonlinear, secondorder differential equation, with a single input u, such
as:
(7)
can be written in a statespace form as:
(8)
(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:
(10)
(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:
(12)
The major advantage of the implicit representation is that a more general set of equations can be solved
because the dependence on the 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:
(13)
y
··
2.e
n
yy
·
e
n
2
y + + Ku =
x
·
1
x
·
2
¹ )
¦ ¦
´ `
¦ ¦
¦ ¹
x
2
2.e
n
x
1
x
2
– e
n
2
x
1
– Ku +
¹ )
¦ ¦
´ `
¦ ¦
¦ ¹
=
y x
1
=
0 f
c
x
c
·
x
c
u t . . . ( ) = x
c
t
0
( ) x
c0
=
y g x
c
u , t , ( ) =
x
·
1
x
2
–
x
2
·
2.e
n
x
1
x
2
e
n
2
x
1
Ku – + +
0
0
=
x
c
·
x
d n 1 + ( )
f
d
x
d n ( )
u t
n
. . ( ) = x
d
t
0
( ) x
d0
=
Adams/Solver
C++ Statements
154
(14)
x
d
is called the state of the system, and contains n elements for an n
th
order system. In matrix notation,
x
d
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 zeroorderhold.
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 produces a component at a different frequency 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 is calculated from . This is an extreme lower limit for . If you want
to obtain a reasonably smooth time response, then choose such that .
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 statespace form as:
(15)
(16)
(17)
y g x
d
u , t , ( ) =
t t
e
0
e
1
e
e
s
( ) e
s
2e > e
e 20
e
s
e
 40 < <
x
c
·
f
c
x
c
u t . . ( ) = x
c
t
0
( ) x
c0
=
0 f
c
x
c
·
x
c
u t . . . ( ) = x
c
t
0
( ) x
c0
=
x
d n 1 + ( )
f
d
x
d n ( )
u t
n
. . ( ) = x
d
t
0
( ) x
d0
=
155 GSE
C++ Statements
(18)
where either the explicit form (15) or implicit form (16) is chosen for the representation.
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.
FeedForward Only System
FeedForward 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:
(19)
y g x
c
x
d
u t . . . ( ) =
y g u t ( , ) =
Adams/Solver
C++ Statements
156
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
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.
• 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. If STATIC_HOLD is not specified, during a static analysis,
Adams/Solver (C++) sets the time derivatives of the userdefined variables to zero,
and uses the usersupplied initialcondition 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 userdefined variables as the initial values for any subsequent analysis, just as
with the equilibrium displacement and force values.
However, the userspecified initial conditions are retained as the static equilibrium
values when STATIC_HOLD is specified. Thus, the final equilibrium values are
the same as the userspecified initial conditions. Note that this does not guarantee
that the time derivatives of the userdefined variable are zero after static analysis.
157 GSE
C++ Statements
• The output is an actuator signal.
States
• The controller is a linear PID controller.
• It has two continuous states (x1 and x2).
Transfer Functions
The transfer functions of the controller are:
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/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
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.
Y s ( )
U
1
s ( )

2e7 –
s
2
2e3s 1e7 + +

Y s ( )
U
2
s ( )

1e3s – 1e7 –
s
2
2e3s 1e7 + +
 = , =
Adams/Solver
C++ Statements
158
Time History of the Block Location
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.
159 GSE
C++ Statements
Time History of Actuator Signal Output by the Controller
UserWritten 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
Adams/Solver
C++ Statements
160
AX(1) = NINT(PAR(1))
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 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
DOUBLE PRECISION PAR(*), TIME
LOGICAL IFLAG, DFLAG
C
C Outputs:
C
DOUBLE PRECISION Y(NO)
C
C Local Variables:
C
LOGICAL LEFLAG, PARFLG
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
AX(1) = NINT(PAR(1))
CALL SYSARY ('ARRAY', AX, 1, X, NS, LEFLAG)
Y(1) = C(1)*X(1) + C(2)*X(2)
C
C Return the partial derivatives to ADAMS:
C
CALL ADAMS_NEEDS_PARTIALS (PARFLG)
IF (PARFLG) THEN
CALL SYSPAR ('ARRAY', AX, 1, C, NS, LEFLAG)
ENDIF
C
161 GSE
C++ Statements
C
RETURN
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 usersupplied 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
INTEGER ID, NPAR, NS
DOUBLE PRECISION PAR(*), TIME
LOGICAL IFLAG, DFLAG
C
C Outputs:
C
DOUBLE PRECISION F(*)
C
C Local Variables:
C
LOGICAL LEFLAG, PARFLG
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.
Adams/Solver
C++ Statements
162
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) + E(i,j)*Xdot(j)
ENDDO
ENDDO
C
C Return the partial derivatives to ADAMS:
C
CALL ADAMS_NEEDS_PARTIALS (PARFLG)
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.
The only change to the previous example is in the GSE_DERIV usersupplied subroutine. In this case it
looks like:
SUBROUTINE GSE_DERIV(ID, TIME, PAR, NPAR, DFLAG, IFLAG, NS, F)
C
C Inputs:
C
INTEGER ID, NPAR, NS
DOUBLE PRECISION PAR(*), TIME
LOGICAL IFLAG, DFLAG
C
Note: 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 nonsparse representations can be mixed. As in this example, the E
matrix can be represented sparsely while the others are represented as full.
163 GSE
C++ Statements
C Outputs:
C
DOUBLE PRECISION F(*)
C
C Local Variables:
C
LOGICAL LEFLAG, PARFLG
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 Return the partial derivatives to ADAMS:
C
CALL ADAMS_NEEDS_PARTIALS (PARFLG)
IF (PARFLG) THEN
Adams/Solver
C++ Statements
164
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.
See other Generic systems modeling available.
165 IC
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.0E4
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
Adams/Solver
C++ Statements
166
APATTERN=c1[:
...:c10]
Specifies as many as ten character strings that together establish the pattern for
evaluating the Jacobian matrix during the modified NewtonRaphson 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, c
j
determines whether or not
ADAMS is to evaluate the Jacobian at the j
th
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.0E10
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
PATTERN=ci[:...:
c10]
Specifies as many as ten character strings that together establish the pattern for
evaluating the Jacobian matrix during the modified NewtonRaphson 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, c
j
determines whether
or not ADAMS is to evaluate the Jacobian at the j
th
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.
Default: T:T:T:T:T:T:T:T:T:T, that is, to evaluating the Jacobian at every
iteration.
167 IC
C++ Statements
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 quasistatic 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 quasistatic 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 NewtonRaphson 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 (C++) also calculates consistent accelerations and forces. This solution
also requires solving a set of nonlinear equations using NewtonRaphson 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.
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.0E4
Range: VERROR > 0
Adams/Solver
C++ Statements
168
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.
Examples
IC/ALIMIT=10D, ERROR=1.0E6, 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.0E6, and limits the number of iterations to 45.
See other Analysis parameters available.
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.
169 INTEGRATOR
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
Adams/Solver
C++ Statements
170
Arguments
ALPHA=r Defining coefficient for the HHT method. Learn more about HHT.
Default value: 0.3
Range: 0.3 < 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.
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. 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 additional information, see the Extended Definition. Note that
for HHT and Newmark, you cannot invoke this attribute, because
the original corrector is available for these two integrators.
Default: corrector=original

¸
1
2
 +
\ .
 
2
4
 >
CORRECTOR
ORIGINAL
MODIFIED ¹ )
´ `
¦ ¹
=
171 INTEGRATOR
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 unitssensitive. For example, if a
system is modeled in mmkgs units, the units of length must be in
mm.
Assuming that all the translational states are larger than 1 mm,
setting ERROR=1E3 implies that the integrator monitors all
changes of the order of 1 micron.
The error tolerances (e) are enforced as:
Y
c
 Y < MAX (e, e * Y)
where Y
c
is the column matrix of computed values for the
unknowns, Y. The symbol  .  indicates the rootmeansquare of the
array of numbers.
A slightly different integration ERROR definition is used for HHT
and Newmark integrators. For these two integrators, the default is
1E5. For more information, see Remarks.
Defaults:
• HHT and Newmark: 1E5
• All other integrators: 1E3
Range: ERROR > 0
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

¸
1
2
 +
\ .
 
2
4
 >
Adams/Solver
C++ Statements
172
GSTIFF Specifies that the GSTIFF (Gear) integrator is to be used for
integrating the differential equations of motion.
HHT Specifies that the HHT (HilberHughesTaylor) 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.
Range: 0 < HMIN < HINIT < HMAX
HMIN=r Defines the minimum time step that the integrator is allowed to
take.
Default:
• 1.0E6*HMAX for GSTIFF, WSTIFF, and I3
• Machine precision for GSTIFF, WSTIFF, SI2, and for HHT
and Newmark
Range: 0 < HMIN < HINIT < HMAX
173 INTEGRATOR
C++ Statements
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 inbetween 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 Index3 (I3) formulation be used. For more
information, see Extended Definition.
Default for GSTIFF/WSTIFF/HHT
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
INTERPOLATE
ON
OFF ¹ )
´ `
¦ ¹
=
Adams/Solver
C++ Statements
174
MAXIT=i Specifies the maximum number of iterations allowed for the
NewtonRaphson iterations to converge to the solution of the
corrector nonlinear equations.
Typically, MAXIT should not be set larger than 10. This is because
roundoff 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.
PATTERN=c1[:...:c10] Indicates the pattern of trues and falses for reevaluating the
Jacobian matrix for NewtonRaphson. 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)
Default: F (HHT/Newmark)
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.
175 INTEGRATOR
C++ Statements
SI2 Specifies that the Stabilized Index2 (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.
For additional information, see the Extended Definition.
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.
SI1 Specifies that the Stabilized Index1 (SI1) formulation, in
conjunction with the HASTIFF integrator, be used for formulating
and integrating differential equations of motion.
The SI1 formulation takes into account constraint derivatives when
solving for 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.
Adams/Solver
C++ Statements
176
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 nonstiff. 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, nonstiff
systems have a stiffness ratio less than 20. This basically means that for a nonstiff 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 nonstiff if the higher frequencies are excited by an external force. Nonlinear
ODEs can be stiff at some points in time and nonstiff at other points.
Learn more about:
• Stiff and NonStiff Integrators
• Prediction
• Correction
• GSTIFF
• SI2
• ODE versus DAE
• WSTIFF
• The HHT and Newmark Integrators
• HASTIFF
Stiff and NonStiff Integrators
Integrators are classified as stiff or nonstiff. 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 nonstiff integrators, the integration step is limited by the inverse of the
highest frequency (active or inactive) in the system. Thus, nonstiff 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
177 INTEGRATOR
C++ Statements
integrators are based on BackwardDifference Formulae (BDF) and are multistep 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 firstorder BDF. Given a set of ODEs of
the form dy/dt = f (y,t), the Backward Euler uses the difference relationship:
(20)
where:
• y
n
is the solution calculated at t = t
n
.
• h is the step size being attempted.
• y
n+1
is the solution at = T
N+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, quasiNewtonRaphson 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 NewtonRaphson 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:
(21)
where y represents all the states of the system.
y
n 1 +
y
n
hy
·
n 1 +
+ =
F y y
·
t , ( , ) 0 =
Adams/Solver
C++ Statements
178
Linearization of Equation (21) about an operating and gives:
replacing y  y
k
with and with , you get:
(22)
From Equation (20), which is a firstorder BDF, you can get the relationship:
(23)
Substituting Equation (23) into (22), you get:
(24)
A generalization of (24)to higherorder BDFs gives:
(25)
where:
• 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.
• 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
y y
k
= y
·
y
·
k
=
F y y
·
t , ( , ) F y
k
y
·
k
t , ( , )
F c
y c

y
k
y
·
k
,
y y
k
– ( )
F c
y
·
c

y
k
y
·
k
,
y
·
y
·
k
– ( ) 0 = + + =
Ay y
·
y
·
k
– ( ) y
·
A
F y
k
y
·
k
t , ( , )
F c
y c

y
k
y
·
k
,
y A
F c
y
·
c

y
k
y
·
k
,
y
·
A + + 0 =
y
·
A
1
h
 y A =
y
k
y
·
k
,
1
h

F c
y
·
c

y
k
y
·
k
,
+ y F y
k
( – = A
y
k
y
·
k
,
1
h
0

F c
y
·
c

y
k
y
·
k
,
+ y F y
k
( – = A

0
Ay
A
179 INTEGRATOR
C++ Statements
integrator repeats the predictioncorrectionerror estimation process until it reaches the time specified in
the SIMULATE command.
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:
Error control of HHT and Newmark integrators:
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 multistep
integrators.
Integrator and formulation Original Corrector Modified corrector
GSTIFF I3, WSTIFF I3 Error control on displacements,
velocities of body equations,
flex modes, flex mode
velocities, applied forces, and
state variables from differential
equations (DIFFs); i.e., all
states except Lagrange
multipliers, Lagrange multiplier
velocities, and contact forces.
Error control on displacements
of body equations, flex modes,
and state variables from
differential equations (DIFFs).
GSTIFF SI2, WSTIFF SI2,
HASTIFF SI1/SI2
Error control on displacements
and velocities of body equations,
flex modes, flex mode
velocities, and state variables
from differential equations
(DIFFs).
GSTIFF SI1, WSTIFF SI1,
CONSTANT_BDF SI1, SI2,
and I3
Not Supported in the Adams/Solver (C++)
HHT Newmark Error control on accelerations of body equations, flex mode accelerations,
and state variables from differential equations (DIFFs).
Adams/Solver
C++ Statements
180
GSTIFF
GSTIFF is based on the DIFSUB integrator. GSTIFF is the most widelyused and tested integrator in
Adams/Solver (C++). It is a variableorder, variablestep, multistep 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
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,
CT18, No.1, 8995.
• Gear, C.W. (1971b). Numerical Initial Value Problems in Ordinary Differential Equations. New
Jersey: PrenticeHall.
SI2
SI2 (StabilizedIndex 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:
• Brenan, K.E., Campbell, S.I., and Petzold, L.R. (1996). Numerical Solution of Initial Value
Problems in DifferentialAlgebraic Equations, Classics in Applied Mathematics.
ISBN: 0898713536 (pbk.)
Benefits Limitations
• High speed.
• High accuracy of the system
displacements.
• Robust in handling a variety of
analysis problems.
• Velocities and especially accelerations can have
errors. An easy way to minimize these errors is to
control HMAX so that the integrator runs at a
constant 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
illconditioned at small steps.
181 INTEGRATOR
C++ Statements
ODEs Versus DAEs
(26)
is defined to be a set of ODEs, because are explicit in Equation (26).
Notice that for ODEs, , and is never singular.
In contrast, DAEs are usually written as:
(27)
It is an intrinsic property of DAE that the matrix is singular. Another way of stating this is that some
of 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:
(28)
(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.
• A
T
is the matrix that projects the applied forces in the direction 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 secondorder differential equation but Equation (29) is an algebraic
equation. Also notice the time derivatives of q are seen in Equations (28) and (29), but is 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.
E y
·
f y t , ( ) – ÷ 0 y 0 ( ) . y
0
= =
y
·
E c
y
·
c
 I =
E F y
·
y t , , ( ) ÷ 0 y 0 ( ) . y
0
= =
E c
y
·
c

Mq
··
o
q
T
ì A
T
F q q
·
( , ) 0 = – +
o q t ( , ) 0 =
o
o
q
ì
·
Adams/Solver
C++ Statements
182
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 EulerLagrange equations for mechanical systems are said to have an Index=3.
Solution of DAEs
Equations (28) and (29)are converted to firstorder 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:
(30)
Substituting Equation (30) into (28), you get:
(31)
(32)
(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):
(34)
This matrix becomes illconditioned 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
ì
u q
·
– 0 =
Mu
·
o
q
T
ì A
T
F 0 = – +
u q
·
– 0 =
o 0 =
M
h
0
 A
T
F
U
– M
q
u
·
o
qq
T
ì A
T
F ( ) – + o
q
T
I
I
h
0
 – 0
0 o
q
0
ì
183 INTEGRATOR
C++ Statements
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.
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):
(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 pinjoint constraint is violated and the pendulum drifts off into
space, grossly violating the pinjoint, 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 driftoff can be prevented by appending Equation (33) to
(31) and adding a new set of variable as follows:
(36)
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 illconditioned 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.
There is, however, an alternative method for implementing the SI1 formulation that is promising.
o
·
q u , ( ) 0 =
Mu
·
o
q
T
ì A
T
F 0 = – +
u q
·
– o
q
T
u + 0 =
o
·
q u t , , ( ) 0 =
o q t ( , ) 0 =
o o
·
o
u
Adams/Solver
C++ Statements
184
Benefits and Limitations
The benefits and limitations of the SI2 formulation are described in the following table:
Characteristics of the SI2 Formulation
WSTIFF
WSTIFF is a stiffly stable, BDFbased, variableorder, variablestep, multistep 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).
Benefits of the SI2 formulation: Limitations of the SI2 formulation:
• Gives very accurate results, especially for
velocities and accelerations.
• Usually allows an ERROR that is
approximately 10 to 100 times larger than
regular GSTIFF to produce the same quality of
results.
• Is very robust and stable at small step sizes.
• Corrector failures that small step sizes cause
occur less frequently than with the Index3
GSTIFF formulation.
• Singular matrices due to small step sizes occur
less frequently than with the Index3 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.
• Is typically 25% to 100% slower for
most problems than regular GSTIFF,
when run with the same error.
• Requires that all velocity inputs be
differentiable. Therefore, you must
define your MOTIONS so that they
are smooth and twice differentiable.
Nonsmooth motions, which
theoretically cause infinite
accelerations, cause failures in the
SI2 formulation. The I3 formulations
can sometimes handle such models.
185 INTEGRATOR
C++ Statements
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:
(37)
The mass, damping, and stiffness matrices, M, C, and K, respectively, are constant, and the force F
depends on time.
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 .
(38)
(39)
In the Newmark formulation, these formulas are used to discretize the equations of motion (37)
(40)
where a
n+1
, v
n+1
, and q
n+1
are numerical approximations for , , and
respectively.
The Newmark method is implicit and Astability (stability in the whole left plane) is guaranteed as soon
as:
(41)
(42)
The Newmark method is an order one integration method, unless and , which makes
the Newmark method same as the trapezoidal rule, which is a secondorder 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
o
o
Mq
··
Cq
·
Kq F t ( ) – + +
o
 ¸
q
n 1 +
q
n
hv
n
h
2
2
 1 2 – ( )a
n
2a
n 1 +
+   + + =
v
n 1 +
v
n
– h 1 ¸ – ( )a
n
¸a
n 1 +
+   –
Ma
n 1 +
Cv
n 1 +
Kq
n 1 +
F
n 1 +
= + +
q
··
t
n 1 +
( ) q
·
t
n 1 +
( ) q t
n 1 +
( )
¸
1
2
 >

¸
1
2
 +
\ .
 
2
4
 >

1
4
 = ¸
1
2
 =
Adams/Solver
C++ Statements
186
• Parasitic oscillations that are a byproduct of the finite element discretization process
The method came as an improvement as it preserved the Astability of the Newmark formulas, while
achieving secondorder accuracy when used with the secondorder 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:
(43)
where
(44)
The equations of motion associated with multibody dynamics simulation in Adams are:
(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:
(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 the equations of motion in the multibody formulation, the force is computed as
; (that is, everything that is not explicitly depending on acceleration ). Therefore, in
relation to the original HHT formulation, the discretization of the multibody dynamics equations of
motion is:
(47)
From an implementation standpoint it is more advantageous to scale the equation above by (1 + ) and
obtain the equivalent form:
(48)
The second set of equations that must be satisfied at time t
n+1
are the position kinematic constraint
equations:
(49)
o
Ma
n 1 +
1 o + ( )Cv
n 1 +
oCv
n
– 1 o + ( )Kq
n 1 +
oKq
n
– + + F t
˜
n 1 +
( ) =
t
˜
n 1 +
t
n
1 o + ( )h + =
Mq
··
u
q
T
ì + F q
·
q , t , ( ) =
u q t , ( ) 0 =
o
o
o
u
q
T
ì F q
·
q , t , ( ) – q
··
Mq
··
( )
n 1 +
1 o + ( ) u
q
T
ì F – ( )
n 1 +
o u
q
T
ì F – ( )
n
– + 0 =
o
1
1 o +
 Mq
··
( )
n 1 +
u
q
T
ì F – ( )
n 1 +
o
1 o +
 u
q
T
ì F – ( )
n
– + 0 =
u q
n 1 +
( ) 0 =
187 INTEGRATOR
C++ Statements
Using the notation:
the simulation is advanced from time tn to tn+1, by finding the solution of the nonlinear system:
(50)
The unknowns solved for are and . Note that although q and appear in equation (50), they are
expressed in terms of based on the formulas of equations (38) and (39) (the notation used there was v
for , and a for ). These integration formulas define linear relationships of the form
and . It is easy to see that based on equations (38) and (39)
The Jacobian of the nonlinear system of equation (50) is given by:
Using the notation:
(51)
one correction in the quasiNewton algorithm is computed as the solution of the linear system:
e
1
q
··
q
·
, ì , ( )
1
1 o +
 Mq
··
( )
n 1 +
u
q
T
ì F – ( )
n 1 +
o
1 o +
 u
q
T
ì F – ( )
n
– + ÷
e
2
q t . ( ) u ÷ q
n 1 +
t
n 1 +
, ( )
+ q
··
ì . ( )
e
1
q
··
ì . ( )
e
2
q t . ( )
¹ )
¦ ¦
´ `
¦ ¦
¦ ¹
=
q
··
ì q
·
q
··
q
·
q
··
q
n 1 +
f
1
q
··
n 1 +
( ) = q
·
n 1 +
f
2
q
··
n 1 +
( ) =
q c
q
··
c
 h
2
=
q
·
c
q
··
c
 ¸h =
e
1
c
q
··
c

1
1 o +
M
F c
q
·
c
h¸ –
1
1 o +
 Mq
··
( )
q
u
q
T
ì ( )
q
F c
q
··
c
h
2
– + =
e
1
c
ì c
 u
q
T
ì =
e
2
c
q
··
c
 u
q
h
2
· =
e
2
c
ì c
 0 =
M
ˆ
1
1 o +
M
F c
q
·
c
h¸ –
1
1 o +
 Mq
··
( )
q
u
q
T
ì ( )
q
F c
q
··
c
 – + h
2
+ =
Adams/Solver
C++ Statements
188
(52)
To balance the coefficient matrix in the previous linear system, the last row is scaled by :
(53)
The correction at iteration k is then applied as:
(54)
(55)
and the corresponding and are computed using the new value and equations
(41) and (42), respectively.
The role of the corrector is to calculate the quantities 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 userspecified
error tolerance. If the local integration error is less than the userspecified error the integration step is
accepted; otherwise, it is rejected and a new smaller step size is tried.
For more information on errorestimation stepsize selection and correctorstopping criteria, refer to
Knowledge Base Article 12299.
Remarks:
• The following explains how the HHT and Newmark integrators are more efficient than the
default GSTIFF integrator:
1. The most timeconsuming 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 stepsize, the HHT integrator employs a different approach, where certain values are
multiplied (never divided) by the stepsize 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 timesteps.
M
ˆ
u
q
T
u
q
h
2
· 0
q
··
c
¸ c
e
1
–
e
2
–
=
1
h
2

M
ˆ
u
q
T
u
q
0
q
··
c
¸ c
e
1
–
e
2
h
2
 –
=
q
··
k 1 + ( )
q
··
k ( )
q
··
k
o + =
ì
k 1 + ( )
ì
k ( )
ì
k
o + =
q
k 1 + ( )
q
·
k 1 + ( )
q
··
k 1 + ( )
q
··
ì
189 INTEGRATOR
C++ Statements
2. When compared with the BDFbased approach, the resulting HHT Jacobian is numerically better
conditioned, which leads to more reliable corrections in the Newtonlike 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 stepsize, or the square
of the stepsize 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 stepsize 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/stepsize choice puts the BDF integrator outside the
stability region. These integration timesteps are typically rejected, and smaller stepsizes 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 onestep integration formula that further gives it a small edge over multistep
methods, such as highorder BDFtype integrators.
• 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:
• 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 secondorder
differential equations. To have these formulas accommodate DIFF's for example, these are first
converted from first into secondorder 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 stepsizes. 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.
o o
 ¸
¸
1 2o –
2
 = 
1 o – ( )
2
4
 =
o
 ¸ ¸ 
Adams/Solver
C++ Statements
190
• The default ERROR for HHT and Newmark is 1.E5. This tighter default value is intended to
counterbalance the different stepsize 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.E3. GSTIFF and ERROR=1.E3 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.E3 (associated with GSTIFF)
will be inherited. The correct command to issue would be INTEGRATOR/HHT, DEFAULTS, if
the goal were to run HHT with its default ERROR setting, that is ERROR=1.E5. Learn more in
the INTEGRATOR command.
References
• 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.
• D. Negrut. On the implementation of HHT and Newmark integrators in MSC. ADAMS.
Knowledge Base Article 12299.
• N. M. Newmark. A method of computation for structural dynamics. Journal of the Engineering
Mechanics Division, ASCE, pages 6794, 1959.
Benefits of the HHT and Newmark
Integrators
Limitations of the HHT and Newmark
Integrators
• Expected to result in a smaller number of
Jacobian evaluations.
• Unlike BDFtype formulas, behaves like a
low pass filter; it cuts high frequency
spurious oscillations, while accurately
preserving low frequency oscillations.
• Can control the cutoff frequency by
adjusting ; the smaller value (that is,
closer to 0.3, the lower the cutoff
threshold).
• Stable at small value of the integration
step size.
• Because of the reduced order, the
acceleration and reaction forces obtained
with this I3 formulation are going to be
more spiky.
• The numerical damping associated with
HHT is smaller than the one produced by
BDF integrators used by the GSTIFF
family.
• If a BDFbased integrator manages to run
a simulation at order 4 or higher, it will
take step sizes significantly larger than
HHT. This is because HHT is a loworder
integrator and it needs to limit the step
size based on accuracy characteristics.
o
191 INTEGRATOR
C++ Statements
HASTIFF
solving for y’ (y discretized as a function of y’):
HASTIFF is the integrator in Adams/Solver (C++). It is a variableorder, variablestep, multistep
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=stepssize, is the BDF coefficient that multiplies y’).
4. The formulation is Stabilized Index1: an index1 formulation is preferable because it’s more
stable numerically, hence it potentially allows for bigger and fewer steps to reach the endtime.
5. Stabilized Index1 (SI1) and Stabilized Index2 (SI2) are available for HASTIFF. SI1 is the
default for HASTIFF.
J
y'
hF
y
F
y'
+ =
J
y' HA .
M hS
u
1
– h M q t . ( )u' u
q
T
v' S
1
q u t . . ( ) – + ( )
q
u
q
T
0
hI – ( ) I h u
q
T
;' ( )
q
– 0 u
q
T
–
0 u
q
0 0
u
q
u
q
u ( )
q
u
q t .
+ 0 0
\ .






 
=
y u
T
q
T
v
T
;
T
( )
T
=
F y y' t . . ( )
Mu' u
q
T
v' S
1
q u t . . ( ) – +
q' u – u
q
T
v' –
1
h
u q t . ( )
1
h
 u
q
u ut + ( )
\ .








 
0 = =
y
n 1 +
o y
n
..., y
n k –
. ( ) hy'
n 1 +
+ =
F o hy' y' t . . + ( ) 0 =
 
Adams/Solver
C++ Statements
192
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 secondtime
derivatives.
3. Monitors integration error only in system displacements and velocities.
4. Is as fast as GSTIFF SI2.
5. The Jacobian matrix *cannot* become illconditioned 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:
• 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 multistep 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, userdefined forces, and userwritten 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 secondorder differentiability. Inputting a
SPLINE through a displacementbased MOTION causes accelerations to be spiky. Therefore,
input the SPLINE in a velocitybased 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.
193 INTEGRATOR
C++ Statements
• Be careful when using nondifferentiable 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 NewtonRaphson 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 NewtonRaphson 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, userdefined forces, user
written differential equations, and userdefined 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.
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
preload.
Adams/Solver
C++ Statements
194
• 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 illbehaved 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.
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 dividebyzero 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.
195 INTEGRATOR
C++ Statements
• 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 userwritten subroutine. IF statements, as well as nondifferentiable
intrinsic functions, such as SIGN, MOD, MIN, MAX, and so on, can create nondifferentiable or
even discontinuous descriptions of modeling elements. Be very careful when using these aspects
of a programming language.
The Index3 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 roundoff error, and, therefore, cause singular or illconditioned 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*N
b
+ 3*N
p
+ N
u
+ 2*N
m
)
• For SI2 formulation with GSTIFF and WSTIFF:
ERROR= K * VEPS * (12*N
b
+ 6*N
p
+ N
u
+ 2*N
m
)
where:
VEPS is the desired error per variable per integration step.
N
b
is the number of rigid bodies in the model (excluding GROUND).
N
p
is the number of point masses in the system.
N
u
is the number of userdefined differential equations in the system (DIFFs+LSEs+GSEs).
N
m
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
.
Adams/Solver
C++ Statements
196
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 userdefined 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 errorcontrol 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.
Tip: GSTIFF and WSTIFF control errors specifically in displacements and userdefined
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. Note that the
PATTERN argument is not available for HHT and Newmark, because these integrators
evaluate the Jacobian as needed.
For kinematic (zeroDOF) 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.
197 INTEGRATOR
C++ Statements
Examples
• INTEGRATOR/SI2, GSTIFF, ERROR=1.0E4, HINIT=1.0E6
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.0E4.
• The integrator is to take an initial step of 1.0E6.
• INTEGRATOR/HHT, ERROR=5.0E6, PATTERN=F, HMAX=1e3
This integrator statement specifies that dynamic simulations be run using the HHT integrator
with the adaptive jacobian pattern.
• This solution has an error limit of 5.0E6.
• The maximum step size the integrator is to take is 1.0E3.
See other Analysis parameters available.
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.
Adams/Solver
C++ Statements
198
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 constantvelocity, cylindrical,
fixed, Hooke, planar, rackandpinion, revolute, screw, spherical, translational, and universal joints.
Format
199 JOINT
C++ Statements
Arguments
CONVEL Indicates the joint is a twodegreeoffreedom 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 zaxis of the I marker to be equal
and opposite to the rotation about the zaxis of the J marker. When connecting two
shafts, the zaxes of the I and J markers should point down the shafts, away from
the center of the joint. Additionally, the angle between the xaxis of the I marker
and the yaxis of the J marker must be the same as the angle between the yaxis of
the I marker and the xaxis of the J marker. The easiest way to ensure the x and y
axes are properly aligned is to make the I and J xaxes parallel, or the I and J yaxes
parallel.
Convel Joint
CYLINDRICAL Indicates that the joint is a twodegreeoffreedom 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 zaxis of the I
marker parallel to, and codirected with, the zaxis of the J marker and confines the
origin of the I marker to the zaxis of the J marker so that the I and J markers have
a common zaxis. To determine translational motion, Adams/Solver (C++)
measures the movement of the origin of the I marker along the zaxis and with
respect to the J marker. To determine rotational motion, Adams/Solver (C++)
measures the rotation of the xaxis of the I marker about the common zaxis and
with respect to the xaxis of the J marker.
Adams/Solver
C++ Statements
200
Cylindrical Joint
FIXED Indicates the joint is a zerodegreeoffreedom 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 twodegreeoffreedom joint that allows rotation about two
axes: xi, the xaxis of the I marker and yj, the yaxis 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 xaxis of the I marker
perpendicular to the yaxis 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.
201 JOINT
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 xaxis of the I marker about the common zaxis of
the I and J markers with respect to the xaxis 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.
Adams/Solver
C++ Statements
202
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
xaxis of the I marker about the common zaxis of the I and the J markers with
respect to the xaxis 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 zaxis 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 the joint have precedence over those on the body.
PD=r Pitch diameter (PD) defines the pitch diameter of the pinion gear of a rackand
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 zaxis of the I marker, a positive pitch diameter moves the rack in the
positive direction along the zaxis of the J marker and a negative pitch diameter
moves the rack in the negative direction along the zaxis 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 righthand
thread, and a negative pitch creates a lefthand thread.
203 JOINT
C++ Statements
PLANAR Indicates that the joint is a threedegreeoffreedom 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 zaxis of the I marker
so that it remains parallel to, and codirected with, the zaxis of the J marker and
does not allow the linear displacement with respect to the J marker to have a z
component.
Planar Joint
Adams/Solver
C++ Statements
204
RACKPIN Indicates that the joint is a fivedegreeoffreedom 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 rackandpinion joint.
For the RACKPIN joint, the zaxis of the pinion must be parallel to and codirected
with the xaxis of the rack. The separation between the two axes should be onehalf
the pitch diameter of the pinion. The rackandpinion 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 zaxis is a
function of the angle between the I marker xaxis and the J marker zaxis.
Adams/Solver (C++) measures a positive rotation according to the righthand rule.
For every full rotation, the distance the I marker moves parallel to the zaxis 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 zaxis 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 singledegreeoffreedom 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 zaxes parallel. Relative motion occurs about the
common zaxes.
205 JOINT
C++ Statements
Revolute Joint
SCREW Indicates that the joint is a fivedegreeoffreedom joint that constrains the
translation of the I marker to its rotation (see the figure below).
For the SCREW joint, the zaxis of the I marker and the zaxis of the J marker must
always be parallel and codirected. 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 zaxis is a
function of the relative angle of the xaxis of the I marker with respect to the xaxis
of the J marker. Adams/Solver (C++) measures a positive rotation according to the
righthand rule. For every full rotation, the displacement of the I marker along the
zaxis 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
Adams/Solver
C++ Statements
206
SPHERICAL Indicates that the joint is a threedegreeoffreedom 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
TRANSLATION
AL
Indicates that the joint is a singledegreeoffreedom 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 (C++) keeps the axes of the I and
the J markers parallel and codirected, and keeps the origin of the I marker on the
zaxis of the J marker so that the two markers have a common zaxis. 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 zaxis.
207 JOINT
C++ Statements
Translational Joint
UNIVERSAL Indicates a twodegreeoffreedom joint that rotates about two axes: the zaxis of
the I marker and the zaxis 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 zaxes 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
Adams/Solver
C++ Statements
208
Extended Definition
The JOINT statement describes a physically recognizable combination of constraints such as constant
velocity, cylindrical, fixed, Hooke, planar, rackandpinion, 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
209 JOINT
C++ Statements
Joint Constraints
* The rackandpinion 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.
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 rackand
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.
This type of
Joint:
Removes
Translational
DOF:
Removes
Rotational DOF:
Removes Total
Number DOF:
Constant Velocity 3 1 4
Cylindrical 2 2 4
Fixed 3 3 6
Hooke 3 1 4
Planar 1 2 3
Rackandpinion 0.5* 0.5* 1
Revolute 3 2 5
Screw 0.5* 0.5* 1
Spherical 3 0 3
Translational 2 3 5
Universal 3 1 4
Adams/Solver
C++ Statements
210
• Functionally, the constantvelocity joint is similar to the UNIVERSAL and HOOKE joints.
Connecting two shafts with a constantvelocity 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.
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 zaxes 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 rackandpinion and screw joints, Adams/Solver (C++) positions the I
and J markers at the nearest pitchmultiple 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.
211 JOINT
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 zaxes of the I and J markers is greater than 5
degrees, and an error if the angle is greater than 60 degrees. The xaxes, however,
may be at any angle.
Adams/Solver
C++ Statements
212
Examples
JOINT/0403, UNIVERSAL, I=0406, J=0306
• 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 forcemoment pair (F
i
, M
i
) at marker I will cause a
reaction forcemoment pair (F
j
, M
j
) at marker J according to:
F
j
= F
i
M
j
= M
i
 r x F
i
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 antiparallel (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 antiparallel
axes has been very low. However, with the advent of curvemarkers, 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 antiparallel assembly of JOINT
axes and enforce this at runtime, 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 antiparallel, 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
antiparallel axes will be prevented.
213 JOINT
C++ Statements
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.
See other Constraints available.
Adams/Solver
C++ Statements
214
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
Arguments
ATPOINT Indicates a threedegreeoffreedom 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.
215 JPRIM
C++ Statements
INLINE Indicates a fourdegreeoffreedom 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 zaxis of the J marker.
Inline Primitive
INPLANE Indicates a fivedegreeoffreedom 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 xy
plane of the J marker.
Inplane Primitive
Adams/Solver
C++ Statements
216
ORIENTATION Indicates a threedegreeoffreedom 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
PARALLEL_AXES Indicates a fourdegreeoffreedom primitive that allows both translational and
rotational motion of one part with respect to another (see the figure below).
For a parallel axes primitive, Adams/Solver (C++) imposes two rotational
constraints so that the zaxis of the I marker stays parallel to the zaxis of the J
marker. This primitive permits relative rotation about the common zaxis of I
and J and permits all relative displacements.
Parallel Axes Primitive
217 JPRIM
C++ Statements
Extended Definition
The JPRIM statement describes a joint primitive, which constrains one, two, or three degrees of either
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.
PERPENDICULAR Indicates a fivedegreeoffreedom primitive that allows both translational and
rotational motion of one part with respect to another (see the figure below).
For a perpendicular primitive, Adams/Solver (C++) imposes a single rotational
constraint on the I and the J markers so that their zaxes remain perpendicular.
This allows relative rotations about either zaxis, but does not allow any relative
rotation in the direction perpendicular to both zaxes.
Perpendicular Primitive
Adams/Solver
C++ Statements
218
Summary of Joint Primitive
The table below lists the number of translational or rotational constraints each joint primitive imposes.
Primitive Constraints
This type of Joint
Primitive:
Removes No.
Translational DOF
Removes No. of
Rotational DOF
Removes Total
Number DOF
Atpoint 3 0 3
Inline 2 0 2
Inplane 1 0 1
219 JPRIM
C++ Statements
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.
Orientation 0 3 3
Parallel Axes 0 2 2
Perpendicular 0 1 1
This type of Joint
Primitive:
Removes No.
Translational DOF
Removes No. of
Rotational DOF
Removes Total
Number DOF
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
nonnegative. 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.
Adams/Solver
C++ Statements
220
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 forcemoment pair (F
i
, M
i
) at marker I
will cause a reaction forcemoment pair (F
j
, M
j
) at marker J according to:
F
j
= F
i
M
j
= M
i
 r x F
i
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 zaxis 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 antiparallel (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 antiparallel
axes has been very low. However, with the advent of curvemarkers, 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 antiparallel assembly of JPRIM
axes and enforce this at runtime, 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 antiparallel, 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
antiparallel axes will be prevented.
221 JPRIM
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.
See other Constraints available.
Adams/Solver
C++ Statements
222
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.0E4
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
223 KINEMATICS
C++ Statements
APATTERN=c
1[:...:c10]
Specifies as many as ten character strings that together establish the pattern for
evaluating the Jacobian matrix during the modified NewtonRaphson 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 NewtonRaphson algorithm)
ERROR=r Specifies the maximum displacement error Adams/Solver (C++) is to allow for each
time step.
Default: 1.0E4
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
[:...:c10]
Specifies as many as ten character strings that together establish the pattern for
evaluating the Jacobian matrix during the modified NewtonRaphson 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 NewtonRaphson algorithm)
TLIMIT=r Specifies the maximum translational increment Adams/Solver (C++) is to allow per
iteration.
Default: 1.0E10 (no limit)
Range: TLIMIT > 0
Adams/Solver
C++ Statements
224
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 NewtonRaphson 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 NewtonRaphson 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 selfreferencing 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.
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.
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.
225 KINEMATICS
C++ Statements
See other Analysis parameters available.
Adams/Solver
C++ Statements
226
LSE
The LSE (Linear State Equation) statement defines the following linear system:
of firstorder, explicit differential equations and algebraic equations in classical statespace 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
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.
x
·
Ax Bu + =
y Cx Du + =
227 LSE
C++ Statements
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
statespace form. The system of equations describes a model for a linear, timeinvariant dynamic system.
The LSE, ARRAY, and MATRIX statements provide the means for importing controllers developed
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
in the dataset; it must have the same number of rows as the A matrix and the same
number 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_HOLD Indicates that the LSE states are not permitted to change during static and quasistatic
analyses.
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.
Adams/Solver
C++ Statements
228
manually or with other software packages. It can also be used, however, to define an arbitrary set of
coupled, constantcoefficient differential and algebraic linear equations in the form
where at least the 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 zerolength and zerosized matrices should not be defined; Adams/Solver (C++)
correctly formulates the system equations based on the ARRAY and MATRIX statements included in the
dataset.
x
·
y
¹ )
´ `
¦ ¹ A B
C D
x
u
¹ )
´ `
¦ ¹
A
229 LSE
C++ Statements
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.
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.
• 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. If STATIC_HOLD is not specified, during a static analysis,
Adams/Solver (C++) sets the time derivatives of the userdefined variables to zero,
and uses the usersupplied initialcondition 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 userdefined 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 userspecified initial conditions are
retained as the static equilibrium values. Thus, the final equilibrium values are the
same as the userspecified initial conditions. Note that this does not guarantee that
the time derivatives of the userdefined variable are zero after static analysis.
x
· 0 1
956.96 – 6.2832 –
x
0
1
5 tt
2
( ) sin + =
x
0 ( ) .
0
0
=
Adams/Solver
C++ Statements
230
• 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).
• 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 userwritten
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.
See other Generic systems modeling available.
231 LSOLVER
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
Prior to MD Adams 2010, the Calahan solver was the default solver for all Adams models. This solver
performs a symbolic factorization of the linear system and is consequently very fast and accurate and for
all models except those that are very large.
The UMF solver (Unstructured MultiFrontal) 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. Very
generally, the UMF solver begins to show an advantage over the Calahan solver when the number of
degrees of freedom in the model exceeds 5,000. 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
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 MultiFrontal sparse
matrix solver. This solver is faster for very large models.
Adams/Solver
C++ Statements
232
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.
See other Analysis parameters available.
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 Unix 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.
233 MARKER
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, CURVE, SURFACE, or
GROUND.
Format
Adams/Solver
C++ Statements
234
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
NODE=n1,
[n2,...,nn]
Specifies that a marker is to be attached, not necessarily positioned, to the points
on 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
235 MARKER
C++ Statements
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 zcoordinates of the origin of the MARKER with respect
to the element on which it lies. If the marker is associated with a FLEX_BODY
or PART, the coordinates are specified in the body coordinate system (BCS). For
a marker on a 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
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.
Adams/Solver
C++ Statements
236
REULER=a,b,c Specifies the Euler angle 313 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 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 maker relative to
the natural coordinate system is defined by the Euler angle 313 sequence a,b,c.
The a, b, and c, values represent the set of bodyfixed 313 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 righthanded rotation of the marker x and yaxes by a radians
about the positive zaxis of the marker.
3. Rotate the marker y and zaxes by b radians about the current marker
positive xaxis.
4. Perform a righthanded rotation of the x and yaxes of the marker by c
radian about the current zaxis 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 xpointzpoint method of orientation, USEXP causes the
marker to be oriented with the xaxis lying on XP, and ZP lying in the positive
xz plane. This is useful for orienting markers that are used in BEAM statements.
Examples of using the ZP, XP and USEXP
237 MARKER
C++ Statements
XP=x,y,z By default, defines the coordinates of any point in the positive xz plane of the
marker, but not on the zaxis of the marker. A point on the positive xaxis may
be the most convenient. When used with USEXP, XP defines the coordinates of
any point on the positive xaxis 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 zcoordinates 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, defines the coordinates of any point on the positive zaxis of the
marker. When used with USEXP, ZP defines the coordinates of any point in the
positive xz plane of the marker, but not on the xaxis 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 zcoordinates 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
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.
Adams/Solver
C++ Statements
238
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 maker 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:
where:
VX=x, VY=y, VZ=z For a marker on a CURVE or SURFACE, this argument specifies the initial
translational velocity of the maker along the xaxis (VX), yaxis (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 twodimensional surface
parameterization.
x X A
o
s u
i
A
i
I – ( )r
c
+ ( )w
i
i 1 =
n
¯
+ + =
239 MARKER
C++ Statements
x = Position vector of marker, resolved in the ground coordinate system (GCS)
X = Position vector of BCS, resolved in the GCS
A
o
= Transformation matrix from BCS to GCS
n = Number of attachment nodes
s = Initial position of marker relative to BCS, resolved in the BCS
u
i
= Displacement vector of node i relative to BCS, resolved in the BCS
r
c
= Initial position of marker relative to the centroid of the attachment nodes, resolved in the BCS
A
i
= Small rotation transformation from frame fixed to node i during deformation back to the BCS
r
i
= Initial position of node i relative to BCS, resolved in the BCS
I = 3 x 3 identity matrix
w
i
= Weighting parameter
where wi satisfies,
and the sum of w
i
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.
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, w
1
=1, r
c
=0)
The position of the marker is then given by x = X + A
o
[s + u
1
]
2. Marker positioned off node, attached to a single node (n=1, w
1
=1, r
c
=r
1
)
The position of the marker is then given by x = X + A
o
(r
1
+ u
1
+ A
1
(s  r
1
))
w
i
1
r
i
r
c
–

1
r
j
r
c
–

j 1 =
n
¯
 =
w
i
1 > for all i
1 = for r
i
r
c
=
0 = when there exists a k, not equal to i where r
k
r
c
=
¹
¦
´
¦
¦
=
Adams/Solver
C++ Statements
240
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 + A
o
s
Markers on Curves
The orientation (natural coordinate system) of curve markers is defined by the following convention:
• The xaxis of the curve marker will point along the curve tangent vector at the marker location.
• The yaxis 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 zaxis of the curve marker will point along the curve BInormal vector at the marker
location. The curve BInormal 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 xaxis of the surface marker will point along the surface u (alpha) tangent vector at the
marker location.
• The zaxis of the surface marker will point along the surface v (beta) tangent vector at the marker
location.
• The yaxis 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 xpointzpoint 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 xpointzpoint 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
241 MARKER
C++ Statements
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 xpointzpoint 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 zaxis is parallel to the BCS yaxis and that the XP point lies on the BCS zaxis.
MARKER/040, 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 (C++)
places the origin of Marker 0408 at coordinates 2,0,0 with respect to the BCS. To orient the marker,
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 yaxis 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 userwritten
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.
Adams/Solver
C++ Statements
242
Adams/Solver (C++) aligns it with its BCS and then rotates the marker 90 degrees about its zaxis, 90
degrees about its new xaxis, and 0 degrees about its new zaxis.
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 xaxis passes through point 0,0,1, and the ZP values indicate the zx 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 maker 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.
243 MARKER
C++ Statements
The solver will compute the unit vectors doing these operations (notice vector x is redefined):
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.
z ZP QP
x
–
XP QP
y
–
z x ×
x y z ×
=
=
=
=
Adams/Solver
C++ Statements
244
In this case the operations are (here vector z is redefined).:
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.
z ZP QP
x
–
XP QP
y
–
z x ×
z x y ×
=
=
=
=
245 MARKER
C++ Statements
The computed operations to obtain XP are:
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.
z ZP QP – a
x
a
y
a
z
. . ( )
XP a
y
a
x
0 . . – ( )
= =
=
Adams/Solver
C++ Statements
246
The operations to compute ZP are:
The rest of operations are the same as in Case 2.
Applications
Use markers on PARTs to:
• Designate the center of mass of a part (see the PART statement).
• 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 jointprimitive 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)
x XP QP – a
x
a
y
a
z
. . ( )
ZP 0 a
z
a
y
. – . ( )
= =
=
247 MARKER
C++ 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 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:
• 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.
Use markers on surfaces 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 other Geometry statement available.
Adams/Solver
C++ Statements
248
MATRIX
The MATRIX statement provides the means for inputting a twodimensional 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
249 MATRIX
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 UNIX.
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 80character 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 seventyfive characters (if you do not abbreviate
FILE=) to seventyseven characters (if you abbreviate FILE= to FI=).
Range: All printable characters except '!', ';', ',', and '&'
FULL={RORDE
R,CORDER}
Specifies a fullinput format where all of the M x N entries are specified with the
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
Adams/Solver
C++ Statements
250
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 onethird 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.
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.
Range: All printable characters except '!', ';', ',', and '&'
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 rowbyrow. If CORDER is specified,
the values are listed columnbycolumn.
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.
251 MATRIX
C++ Statements
A file in the in the ADAMSMAT or ADAMSMAT2 format consists of variablelength 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 rightjustified 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 eightcharacter 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.
Adams/Solver
C++ Statements
252
Table 3 Specifications for the ADAMSMAT Matrix File
Table 4 Specifications for the ADAMSMAT12 Matrix File
Item:
Number of
records: Contents:
Argument or
symbol:
FORTRAN
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
{FULL or SPARSE}
{CORDER or RORDER if FULL
or blank if SPARSE}
Number of rows, columns, and
total number of entries
FORTRAN format specification
NAME
M,N,
number
format
A8,
A8,
A8,
3I5
A41
5 variable All entries in the matrix if FULL
or
The indices and nonzero entries in
the matrix if SPARSE
A(I,J)
or
I,J, A(I,J)
FORMAT
FORMAT
Note: Items 4 and 5 have to be repeated n times, once for each matrix named in Item 3.
Item:
Number of
records: Contents:
Argument or
symbol:
FORTRAN
format:
1 1 Header for the file ADAMSMAT2 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
{FULL or SPARSE}
{CORDER or RORDER if FULL
or blank if SPARSE}
Number of rows, columns, and
total number of entries
FORTRAN format specification
NAME
M,N,
number
format
A8,
A8,
A8,
Values
separated by
spaces
A41
5 variable All entries in the matrix if FULL
or
The indices and nonzero entries in
the matrix if SPARSE
A(I,J)
or
I,J, A(I,J)
FORMAT
FORMAT
Note: Items 4 and 5 have to be repeated n times, once for each matrix named in Item 3.
253 MATRIX
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.
Examples
Small Matrix Input
Assume that the following matrix is needed in an Adams/Solver analysis:
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
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.
TRF
1.364 0.000
0.000 0.000
3.546 – 4.008
0.000 0.799
=
Adams/Solver
C++ Statements
254
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 (C++).
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.0003.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
VALK
1.97 0.00 3.44 –
0.00 4.52 6.02
3.44 – 6.02 2.11
=
STL
1.698045
01
×10
2.307452
01
×10 –
0.000000
0
×10
0.016390
0
×10
0.011271
0
×10
0.000000
0
×10
=
255 MATRIX
C++ Statements
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 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.
See other Reference data available.
Adams/Solver
C++ Statements
256
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.
257 MFORCE
C++ Statements
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
where and 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:
where is the matrix of mode shapes. The modal form simplifies to:
where and 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:
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.
ROUTINE=libna
me::subname
Specifies an alternative library and name for the user subroutine MFOSUB.
Learn more about the ROUTINE Argument.
FORCE=USER(r
1{r2,...,r30})
Specifies up to thirty userdefined constants that Adams/Solver (C++) passes to a
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
ER(r1{r2,...,r30})
Specifies up to thirty userdefined constants the Adams/Solver (C++) passes to a
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.
M  x
··
K  x + F =
M   K  
P  
T
M   P  q
··
P  
T
K   P  q + P  
T
F =
P  
M
ˆ
 q
··
K
ˆ
 q + f =
M
ˆ
  K
ˆ
 
f P  
T
F =
Adams/Solver
C++ Statements
258
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 the Adams simulation. The MNF can store several modal load cases, which are denoted
here as f
1
, f
2
,…, f
n
. From the modal load cases, a total modal force f
T
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
f
T
(q,t) = e(q,t) f
i
is then applied to the FLEX_BODY, where CASE_INDEX = i references load case f
i
in the MNF, and
SCALE = e defines the statedependent 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 userwritten 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:
f
T
(q,t) = e(q,t) f
i
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, f
1
,...,f
n
as follows:
f
T
(q,t) = e(q,t) [ g
1
(t) f
1
+ g
2
(t) f
2
+ … tgn(t) f
n
]
where g
1
(t), g
2
(t), … g
n
(t) are scalar functions of time only. The MFORCE is specified the same way as
Definition 2, namely:
MFORCE/id, FLEX_BODY = id [,JFLOAT=id], FUNCTION = USER(r1,[r2,…r30])
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 timevarying 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
259 MFORCE
C++ Statements
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 g
i
(t) is not allowed.
Definition 4: Computing Modal Load Case
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:
MFORCE/id, FLEX_BODY = id [,JFLOAT=id], FUNCTION = USER(r1,[r2,…r30])
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:
f
T
(q,t) = e(q,t) f
u
(t)
where e(q,t) is the userdefined scale factor and f
u
(t) is the userdefined 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:
f
T
(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 userwritten 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.
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 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
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.
v u
o
Adams/Solver
C++ Statements
260
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 userwritten 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 userwritten subroutine, and only the scale
function is assumed to depend on state.
MFORCE/2, FLEX_BODY = 2, JFLOAT = 4
, 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 userwritten subroutine, and any component of the
load case can depend on state or time.
See other Forces available.
261 MOTION
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 userwritten 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
Adams/Solver
C++ Statements
262
Arguments
ACCELERATION Specifies that the FUNCTION argument defines the motion
acceleration as a function of time. The acceleration expression is
integrated twice to calculate the corresponding displacement.
Default: DISPLACEMENT
B1 Specifies the first angle of the Body 123 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 123 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
B3 Specifies the third angle of the Body 123 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
DISPLACEMENT Specifies that the FUNCTION argument defines the motion
displacement. This is the default.
Specifies an expression or defines and constants to be passed to
the MOTSUB userwritten 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 userwritten 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 (\).
FUNCTION
e
USER r1 ,... ,r30   ( )
¹ )
´ `
¦ ¹
=
263 MOTION
C++ Statements
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 nonfloating 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.
ROUTINE=libname::subname Specifies an alternative library and name for the user subroutine
MOTSUB.
Learn more about the ROUTINE Argument.
TRANSLATION Designates a translational motion. This argument is necessary
only when translational motion is being applied to a cylindrical
joint.
VELOCITY Specifies that the FUNCTION argument defines the motion
velocity.
Default: DISPLACEMENT
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
Adams/Solver
C++ Statements
264
Extended Definition
The MOTION statement specifies a translational or rotational degreeoffreedom 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 userspecified direction is controlled as a function of time. You can
define the value of the degreeoffreedom being controlled, either as a function expression or userwritten
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 degreeoffreedom being controlled.
For a translational motion, Adams/Solver (C++) moves the I marker along the zaxis of the J marker. The
J marker origin represents zero displacement while the zaxis of the J marker defines the positive
direction.
For a rotational motion, Adams/Solver (C++) rotates the I marker about the zaxis of the J marker. The
righthand rule is used to determine the sign of the motion. The zaxis of the I marker must be collinear
with the zaxis of the J marker at all times. The angle is zero when the xaxis of the I marker is also
collinear with the xaxis of the J marker.
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 xaxis 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 yaxis of the J marker.
Y Specifies DY(I,J,J) as a function of time. DY is the y 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
Z Specifies DZ(I,J,J) as a function of time. DZ is the z 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
265 MOTION
C++ Statements
• 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 zaxis of the J marker.
• B1(I,J) is the first angle of a Body 123 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 123 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 123 Euler rotation sequence that measures the orientation of
the I marker with respect to the J marker.
For the velocity and acceleration motions, Adams/Solver (C++) numerically integrates the velocity or
acceleration signal to obtains corresponding displacement signal of the motion.
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).
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. Nonsmooth functions that do not have continuous first and
second time derivatives can cause severe numerical problems.
• Be careful when specifying multiaxial rotational motions between a pair of
markers. B1, B2, and B3 specify a Body 123 rotation sequence and are Euler
angles. This implies that the first rotation occurs about the xaxis of the J
marker, the second rotation about an intermediate yaxis and the last about the
zaxis 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 123 rotation sequence
before specifying it in a MOTION.
Adams/Solver
C++ Statements
266
Examples
JOINT/101, TRANSLATIONAL, I=1011, J=1012
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:
• 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 123 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.
• 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 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 degreeoffreedom 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.
267 MOTION
C++ Statements
MOTION/101, I=1011, J=1012, Z, FUNCTION=10 * SIN(TIME)**2.
JOINT/201, REVOLUTE, I=2011, J=2012
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=2012, B3,
, FUNCTION=POLY(TIME, 0, 0, 360D)
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 zaxis of Marker 11 (third angle of the Body 123 rotation sequence
between Markers 11 and 12) is specified to be 30D*COS(TIME).
JOINT/301, SPHERICAL, I=3011, J=3012
MOTION/3014, I=3011, J=3012, B1
, FU=30D*SIN(360D*TIME+30D)
MOTION/3015, I=3011, J=3012, B2
, FU=25D*SIN(360D*TIME25D)
MOTION/3016, I=3011, J=3012, B3
, FU=45D*SIN(360D*TIME57D)
These MOTION statements control the three rotational degreesoffreedom in a spherical joint by
specifying the Body 123 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 degreesoffreedom in a planar joint:
• The displacement of the origin of Marker 4011 with respect to the origin of Marker 4012, along
the xaxis of Marker 4012, is specified as 40*TIME25.2.
• The displacement of the origin of Marker 4011 with respect to the origin of Marker 4012, along
the yaxis of Marker 4012, is specified as 25*SIN(360D*TIME25D).
• The rotation of Marker 4011 with respect to Marker 4012 about the zaxis of Marker 4011 is
specified to be zero.
See other Constraints available.
Adams/Solver
C++ Statements
268
NFORCE
The NFORCE statement creates a multipoint force element which establishes linear forcedisplacement
(stiffness) and/or forcevelocity (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 V
x
, V
y
, V
z
,
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 F
x
, F
y
, F
z
, T
x
, T
y
, T
z
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.
e e e
269 NFORCE
C++ Statements
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 forcedisplacement and forcevelocity 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 degreesoffreedom, but are input using only the rows and columns
corresponding to the I marker degreesoffreedom. 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.
IMARKERS=id1,...,i
dn
Lists the markers (except for the J marker) between which the NFORCE forces
and 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.
Adams/Solver
C++ Statements
270
Formulation
For n+1 points in the NFORCE system (n I markers and 1 J marker).
Action Forces (Forces on the I markers)
F
I
=  KMATRIX (X  L)  CMATRIX + FORCE
where:
• F
I
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 degreesoffreedom.
• 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 associated with the J marker’s degreesoffreedom.
• 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)
where:
• trans denotes translational degreesoffreedom
• =rot denotes rotational degreesoffreedom
• X
ji
is the instantaneous vector from the J marker to each I marker.
X
·
X
·
F
j
trans
F
i
trans
i
¯
– =
F
j
rot
F
i
rot
X
ji
F
i
trans
+ + ( )
i
¯
– =
271 NFORCE
C++ Statements
Examples
The figure below illustrates a simple, planar, triangular truss attached to some large base body.
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 semidefinite 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 twopoint 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.
Adams/Solver
C++ Statements
272
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 18by18 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, inplane forces.
Due to the simple geometry, this matrix can be determined by inspection, and is shown in the table shown
next.
273 NFORCE
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 (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
Adams/Solver
C++ Statements
274
elements, SPRINGDAMPER, SFORCE, 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
superelement 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 onetoone correspondence between Adams/Solver (FORTRAN) PARTs
and FEA nodes, unless the FEA model is very small.
Flexible Satellite Panels
See other Forces available.
275 OUTPUT
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
OUTPUT/
REQSAVE
GRS , AVE
NOSEPARATOR ,   YPR ,  
DACSAVE
RPCSAVE
LOADS =
ABAQUS
ANSYS
DAC
NASTRAN
RPC
¹ )
¦ ¦
¦ ¦
´ `
¦ ¦
¦ ¦
¦ ¹
,
MODAL_DEFORMATION
ABAQUS
DAC
GENERIC
NASTRAN
PUNCH
¹ )
¦ ¦
¦ ¦
´ `
¦ ¦
¦ ¦
¦ ¹
= ,
NODAL_DEFORMATION
ANSYS
GENERIC
NASTRAN
¹ )
¦ ¦
´ `
¦ ¦
¦ ¹
= ,
STRAIN
DAC
GENERIC
¹ )
´ `
¦ ¹
= ,
STRESS
DAC
GENERIC
¹ )
´ `
¦ ¹
= ,
,
{ } Select one item
[ ] Optionally select the item
[[ ]] Optionally select an item combination
Adams/Solver
C++ Statements
276
Arguments
ABAQUS Specifies the output of FEM data to an ABAQUSreadable format. Load
data are written out as ABAQUS input commands.
ANSYS Specifies the output of FEM data to an ANSYSreadable 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 ANSYScustomized macro, available in Adams/Durability
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 humanreadable (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_DEFORMATION Controls output of modal deformation data to the specified format. If you
do not specify MODAL_DEFORMATION, Adams/Solver (C++) does
not process any FEMDATA/MODAL_DEFORMATION statements.
NASTRAN Specifies the output of FEM data to a NASTRANreadable format. Load
data or nodal deformations are written out as NASTRAN input
commands. Modal deformations are written out to NASTRAN
OUTPUT2 (binary) format.
NODAL_DEFORMATION Controls output of nodal deformation data to the specified format. If you
do not specify NODAL_DEFORMATION, Adams/Solver (C++) does
not process any FEMDATA/NODAL_DEFORMATION statements.
277 OUTPUT
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 xy plots. If you do not specify REQSAVE,
Adams/Solver (C++) does not save the request output in the request file.
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.
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.
Adams/Solver
C++ Statements
278
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 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.
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 zaxis. Next, it makes a
negative rotation about the new yaxis (y'), and then about the second
new xaxis (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.
279 OUTPUT
C++ Statements
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).
Examples
OUTPUT/GRSAVE, REQSAVE
This OUTPUT statement causes Adams/Solver (C++) to save both graphics and request output.
Adams/Solver
C++ Statements
280
FEMDATA/1, STRESS, FLEX_BODY=201
, 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/2, FORCE, I=202, J=104, TITLE=REQ02
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).
See other Output available.
281 PART
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
Adams/Solver
C++ Statements
282
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:
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.
X x coordinate
Y y coordinate
Z z coordinate
PSI Psi angle
THETA Theta angle
PHI Phi angle
283 PART
C++ Statements
IP=xx,yy,zz[,xy,x
z,yz]
Specifies the massinertia tensor as computed about the origin of the IM marker,
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.
MASS=r Specifies the part mass.
MATERIAL=mat
_name
Specifies the material type for the part. You define the different material types in the
MATERIAL statement.
Range: Material type as defined in the MATERIAL statement
Default: Steel
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 as a regular 3D part with a builtin planar joint.
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).
Ixx y
2
z
2
+ ( ) m d
í
=
Iyy x
2
z
2
+ ( ) m d
í
=
Izz x
2
y
2
+ ( ) m d
í
=
Ixy xy m d
í
=
Ixz xz m d
í
=
Iyz yz m d
í
=
Adams/Solver
C++ Statements
284
REULER=a,b,c Defines the 313 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 zaxis of ground, the new x
axis, and the new zaxis 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,
VZ=z
Specifies the initial translational velocities of the CM marker with respect to the
ground coordinate system (GCS) along the xaxis (VX), the yaxis (VY), and the z
axis (VZ) of the GCS.
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,
WZ=c
Specifies the initial rotational velocities, in radians per second, of the part about the
xaxis (WX), the yaxis (WY), and the zaxis (WZ) of the CM marker coordinate
system.
XG=x,y,z Defines the coordinates, measured in the GCS, of any point in the positive xz plane
of the part BCS, but not on the zaxis 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 zaxis 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.
285 PART
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 centerofmass 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 zaxis of the CM becomes parallel to the ground zaxis. Whenever the
principal zaxis of the part nearly parallels the ground zaxis, Adams/Solver (C++)
rotates the part principal axes 90 degrees about the zaxis and then 90 degrees
about the new xaxis 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 builtin
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 index3 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.
Adams/Solver
C++ Statements
286
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 centerofmass marker identifier (0201), and
the principal moments of inertia for Part 2:
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.
287 PART
C++ Statements
• Ixx = 5 units
• Iyy = 6 units
• Izz = 10 units
The principal moments of inertia are about the xaxis (5), the yaxis (6), and the zaxis (10) of the center
ofmass 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)
• Centerofmass 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.
See other Inertia and material data statement available.
Adams/Solver
C++ Statements
288
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
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
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 controlsystem 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 userwritten 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.
[ ] Optionally select the item
VARIABLES=id1[,id2,...] Specifies the VARIABLE statements used as inputs by the
Adams/Solver (C++) model.
x
·
Ax Bu + =
y Cx Du + =
289 PINPUT
C++ Statements
Userwritten 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).
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 MATRIX
x
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.
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.
Adams/Solver
C++ Statements
290
See other Reference data available.
291 POINT_MASS
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
Adams/Solver
C++ Statements
292
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.
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 313 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 zaxis of ground, the
new xaxis, and the new zaxis 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
Range: Any real values
x x coordinate
y y coordinate
z z coordinate
293 POINT_MASS
C++ Statements
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 builtin 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.
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 xaxis (VX), yaxis (VY), and
zaxis (VZ) of the global coordinate system.
Default: Inexact 0, 0, 0
Range: Any real values
XG=x,y,z Defines the coordinates, measured in the global coordinate system, of any point
in the positive xz plane of the part BCS, but not on the zaxis of the part BCS.
Default: If ZG is omitted, XG is oriented like the global xaxis
Range: Any real values
ZG=x,y,z Defines the coordinates measured in the global coordinate system of any point
on the positive zaxis of the BCS.
Default: If XG is omitted, ZG is oriented like the global zaxis
Range: Any real values
Adams/Solver
C++ Statements
294
The point mass offers all the computational benefits of a particle without the complications which would
arise from forbidding the application of a torque.
See other Inertia and material data statement available.
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.
295 POUTPUT
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
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:
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 controlsystem 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 userwritten 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.
[ ] Optionally select the item
VARIABLES=id1id1[,id2,...] Specifies the VARIABLE statements that describes the outputs of the
Adams/Solver (C++) model.
x
·
Ax Bu + =
y Cx Du + =
Adams/Solver
C++ Statements
296
Userwritten 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).
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.
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. See the
LINEAR command.
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.
297 POUTPUT
C++ Statements
PINPUT and POUTPUT as 'Sockets'
See other Reference data available.
Adams/Solver
C++ Statements
298
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
299 PREFERENCES
C++ Statements
Arguments
Select the geometry library to be used for contact
operations:
• Parasolid  Specifies the Parasolid geometry
library be used for threedimensional contact
determination. Adams/Solver (C++) supports
Parasolid version 19.0.17.
• 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
polygonbased, however, it is not always as accurate
as the Parasolid geometry engine. Parasolid is an
exact boundaryrepresentation geometric modeler,
which makes it highly accurate, but not as fast as a
polygonbased engine. For these reasons, you can
switch from one to the other depending on your needs.
CONTACT_FACETING_TOLERANCE=valu
e
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.
The faceting tolerance has no effect on inherently
polygonal surfaces such as boxes.
Adams/Solver
C++ Statements
300
LIBPATH=dir1:dir2:... Specifies a colonseparated list of directories which
are to be searched for user subroutine plugin libraries
before searching in the default locations. See the
ROUTINE Argument for more information.
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 8. 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.
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.
301 PREFERENCES
C++ Statements
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
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 userwritten subroutines will not see the full benefit of parallelization unless the
userwritten subroutines declare themselves as threadsafe. See the utility subroutine,
ADAMS_DECLARE_THREADSAFE, for more information.
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,
RETURN, MESSAGE_ONLY}
Specifies what action Adams/Solver (C++) should
take if a flexible 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).
Adams/Solver
C++ Statements
302
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:
VARSUB/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.
See other Analysis parameters available.
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 runtime.
303 PSTATE
C++ Statements
PSTATE
The PSTATE statement defines a set of userdefined coordinates to be used during a LINEAR analysis
(see the LINEAR command).
You can specify as many states as there are degreesoffreedom. 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 Knowledge Base Article 12721.
For an example of using PSTATE, see Knowledge Base Article 12663.
Format
PSTATE/id, VARIABLES=id1[,id2,...]
Arguments
Extended Definition
The PSTATE statement is used with the LINEAR/STATEMAT or LINEAR/EIGENSOL or
LINEAR/MKB command. PSTATE defines a set of userdefined coordinates. The LINEAR/STATEMAT
command linearizes the system equations to the following form:
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.
[ ] Optionally select the item
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 userdefined
coordinates to be used during a linearization or eigensolution
computation.
x
·
Ax Bu + =
y Cx Du + =
Adams/Solver
C++ Statements
304
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 controlsystem 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 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:
where the system state array s is the set of userdefined 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
degreesoffreedom 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)
s
·
A' s B' u + =
y C' s Du' + =
305 PSTATE
C++ Statements
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 userdefined coordinate if there is already an equivalent
default definition.
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.
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.
Adams/Solver
C++ Statements
306
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 userdefined
coordinates found in the VARIABLEs belonging to the PSTATE/2 object.
307 PTCV
C++ Statements
PTCV
The PTCV statement defines a pointtocurve 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
Click the argument for a description.
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.
Adams/Solver
C++ Statements
308
Extended Definition
The PTCV statement defines a pointtocurve constraint. The part containing the I marker is free to roll
and slide on the curve that is fixed to the second part. Liftoff 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 pointtocurve constraint.
A PTCV statement removes two translational degreesoffreedom 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.
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 xaxis is tangent to the curve at the
contact point, the yaxis points outward from the curve's center of curvature at the
contact point, and the zaxis is along the binormal at the contact point.
RM=id Specifies the identifier of a fixed maker 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
309 PTCV
C++ Statements
Figure 5 Geometric Interpretation of the Orientation of the JFLOAT Marker
Adams/Solver
C++ Statements
310
Figure 6 PointToCurve Constraint
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.
311 PTCV
C++ Statements
Examples
PTCV/55, I=201, JFLOAT=301, CURVE=10, RM=302>
This statement creates a pointcurve 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,
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 = (ALPHAMAXPAR)/ABS(MAXPARMINPAR), if ALPHA >
MAXPAR
or
DELTA = (ALPHAMINPAR)/ABS(MAXPARMINPAR), 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 overconstrain a system using the PTCV constraint. For
instance, in a camfollower 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.
Adams/Solver
C++ Statements
312
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 pointcurve constraint application is a pinslot connection as illustrated in Figure 7 below.
Figure 7 Slot and Pin Reciprocating Mechanism
The pointcurve 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 pointcurve 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 pointcurve 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 (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 9 illustrates the follower, original profile, and offset curve.
313 PTCV
C++ Statements
Figure 8 PointFollower Mechanism
Figure 9 Modeling a Circular Follower Using an Offset Curve
To model more complex camfollower 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 if liftoff should have occurred. If an accurate simulation of intermittent contact is
required, you should model the contact forces directly using a VFORCE.
Unlike the CVCV statement, the PTCV statement is not restricted to planar curves. PTCV can model
threedimensional slots and cams, as well as mechanisms riding on nonplanar tracks, or a robot end
effector following a threedimensional path in space.
See other Constraints available.
Adams/Solver
C++ Statements
314
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 userwritten subroutine
REQSUB to define nonstandard output.
Format
315 REQUEST
C++ Statements
Arguments
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:
<entity name="REQUST_1" objectId="11">
<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.
Adams/Solver
C++ Statements
316
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 seventytwo
characters long (if you do not abbreviate COMMENT=) to seventyeight
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 CLABEL argument.
The legal choices for the CUNITS parameter are:
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.
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
317 REQUEST
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 xcomponent, the translational y component, and the
translational zcomponent 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.
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).
F3=e Defines a component of the request that is being specified. If the F3 argument is
used, it must either be the last argument in the REQUEST statement or be
followed by a backslash (\) (not a comma).
F4=e Defines a component of the request that is being specified. If the F4 argument is
used, it must either be the last argument in the REQUEST statement or be
followed by a backslash (\) (not a comma).
F6=e Defines a component of the request that is being specified. If the F6 argument is
used, it must either be the last argument in the REQUEST statement or be
followed by a backslash (\) (not a comma).
F7=e Defines a component of the request that is being specified. If the F7 argument is
used, it must either be the last argument in the REQUEST statement or be
followed by a backslash (\) (not a comma).
F8=e Defines a component of the request that is being specified. If the F8 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
C++ Statements
318
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 actiononly 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 actiononly 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
{r1[,...,r30]}
Defines and passes constants to the userwritten 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 (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 actiononly 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).
319 REQUEST
C++ Statements
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 userwritten 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
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.
Learn more about the ROUTINE Argument.
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.
Adams/Solver
C++ Statements
320
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.
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.
321 REQUEST
C++ Statements
Caution: • Applied forces and torques are those generated by beams, bushings, fields, general
forces (GFORCEs), singlecomponent 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, actionreaction singlecomponent 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 actiononly
singlecomponent forces, there is no force or torque acting at the applied force J
marker. For beams, fields, bushings, and multipoint 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 constraintinducing 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, rackandpinion, 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).
Adams/Solver
C++ Statements
322
Examples
REQUEST/01, DISPLACEMENT, I=0201, J=0103
, COMMENT=CRANK CENTER OF MASS DISPLACEMENT
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.
REQUEST/08, FORCE, I=0304, J=0204
, COMMENT=ROD/CRANK REACTION
This REQUEST statement requests data for an actionreaction 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.
REQUEST/1, DISPLACEMENT, I=100, J=102
,CNAMES="", X_100, Y_100
,RESULTS_NAME=PQT
REQUEST/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 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"/>
<component name="X_200" id="69"/>
Caution: • You must be careful when requesting a force with the I and the J markers reversed
from those specified in the forceproducing element. Adams/Solver (C++) reports
the force as if it were applied to the J marker of the forceproducing 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 actiononly. 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 forceproducing 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.
323 REQUEST
C++ Statements
<component name="Y_200" id="70"/>
</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 (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 userdefined differential equation, and DIF1 for the value of
the time derivative of the independent variable of the userdefined differential equation.
See other Output available.
Adams/Solver
C++ Statements
324
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
* The following arguments are only available with XRF.
RESULTS/[FORMATTED][XRF]
NOACCELERATIONS ,
NOAPPLIEDFORCES ,
NODATASTRUCTURES ,
NODISPLACEMENTS ,
NOFLOATINGMARKERS ,
NOLINEAR ,
NOREACTIONFORCES ,
NOREQUESTS ,
NOSYSTEMELEMENTS ,
NOVELOCITIES ,
NOCONTACTS ,
NODE_INCIDENTS ,
RESULTS/[XRF]
DECIMALPLACES = i ,
ROUNDOFF ,
SCIENTIFICATION = i1, i2 ,
SIGINIFICANTFIGURES = i ,
TRAILINGZEROES ,
ZEROTHRESHOLD = r ,
[ ] Optionally select the item
[[ ]] Optionally select an item combination
325 RESULTS
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 doubleprecision 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 userreadable, 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.
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 and plant outputs. 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 userdefined request, in the case of a classic results
file, or all request data (in the case of an XMLformatted results file
(XRF)).
NOSYSTEMELEMENTS Specifies that the results file is not to include results for system modeling
elements such as userdefined differential equations, linear state equations,
general state equations, and transfer functions. The default is a results file
that contains results for system modeling elements.
Adams/Solver
C++ Statements
326
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=i
1,i2
This argument is only available with XRF.
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.0E04 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.
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 nonzero digit.
327 RESULTS
C++ Statements
Extended Definition
The RESULTS statement creates a results file that includes selections of output from an Adams/Solver
(C++) simulation. This allpurpose 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
coordinate system (GCS).
• 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 userwritten REQSUB.
• System elements  Inputs, outputs, state variables, and state derivatives defined by system
modeling elements such as userwritten 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.
XRF Specifies the format of the results file to be XML. XML (Extensibile
Markup Language) is an industrystandard format facilitating structured
data representation and web communication.
XRF will produce an XMLformatted 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.
Adams/Solver
C++ Statements
328
• Node incidents  Values computed for Flex Body nodes on Flex Bodies in contact.
Examples
RESULTS/FORMATTED, NODATASTRUCTURES, NOSYSTEMELEMENTS
RESULTS/NODISPLACEMENTS, NOVELOCITIES
,NOACCELERATIONS, NODATASTRUCTURES
,NOSYSTEMELEMENTS, NOFLOATINGMARKERS
See other Output available.
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.
329 SENSOR
C++ Statements
SENSOR
The SENSOR statement is used to modify the simulation when a userdefined 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
Adams/Solver
C++ Statements
330
Arguments
BISECTION Specifies that a bisection search algorithm will be used
to isolate the activation time of the sensor.
When not present the default, secanttype rootfinding
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
when the event Adams/Solver (C++) 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
331 SENSOR
C++ Statements
Specifies an expression or defines and passes constants
to a userwritten 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 userwritten 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 usersubroutine, 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 userwritten
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.
Learn more about the ROUTINE Argument.
Specifies an expression or defines and passes constants
to a userwritten subroutine to define the event logical
expression. To define an expression, follow
FUNCTION with an equal sign and the expression (e).
To define a userwritten 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 userwritten
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 userparameter list of 1 to 30
real values
GE Used to define the event logical expression. The event
is true (active) if the function or userwritten subroutine
is equal to or greater than (VALUEERROR).
Default: EQ
Adams/Solver
C++ Statements
332
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 userwritten 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
when the event Adams/Solver (C++) is monitoring
becomes true.
Default: Off
ROUTINE=libname::subname Specifies an alternative library and name for the user
subroutine SENSUB.
Learn more about the ROUTINE Argument.
STEPSIZE=r Redefines the trial integration step size when the event
Adams/Solver (C++) is monitoring because 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
333 SENSOR
C++ Statements
Extended Definition
The SENSOR statement defines a userdefined 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 userwritten 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 userwritten subroutine. Userwritten 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. Timebased method
TERROR Specifies the temporal error with which the activation
time of the sensor is isolated.
Default: 1e6
VALUE=r Specifies the value to be compared to the function
expression (or evaluation of the userwritten
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
Adams/Solver
C++ Statements
334
3. Secant method
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 timebased 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.
Caution: • When using the default search algorithm in Adams/Solver (C++), the SENSOR
function must be continuous. The secanttype 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.
• 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.
335 SENSOR
C++ Statements
Examples
SENSOR/231, FUNCTION=DX(0201,0307)/
,VALUE=3.24, RETURN
This SENSOR statement senses the xcomponent 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.
See other Analysis parameters available.
• 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 statement so that the initial accelerations are zero.
• 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.
Adams/Solver
C++ Statements
336
SFORCE
The SFORCE statement applies a singlecomponent force or a torque to one or both of the parts it
connects.
Format
Arguments
ACTIONONLY Indicates that you are describing an actiononly force rather than
an actionreaction force. Adams/Solver (C++) applies no
reaction at the J marker.
Specifies an expression or defines and passes constants to a
userwritten subroutine to define the singlecomponent 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 userwritten 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 (\).
337 SFORCE
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, userdefined variables, and time. An SFORCE statement
can apply actionreaction forces or can apply actiononly forces.
For translational actionreaction 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 actiononly 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 zaxis of the J marker.
I=id, J=id Specifies the identifiers of two markers necessary to define the
force. If SFORCE defines a translational actionreaction 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 actionreaction force along the line of action
defined by the line segment connecting I and J. If SFORCE
defines an actiononly force, I specifies the point of application,
and the zaxis of J specifies the direction of the force. If
SFORCE defines a torque, the zaxis of the J marker specifies
the axis of rotation. In the case of actionreaction torques, the z
axis of the J marker must be parallel to, and pointed in the same
direction as, the zaxis of the I marker.
Note: You can use the same marker for both the I and J
markers when you are specifying an actiononly
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 zaxes 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 zaxis. By definition, the
righthand rule defines a positive torque.
ROUTINE=libname::subname Specifies an alternative library and name for the user subroutine
SFOSUB.
Learn more about the ROUTINE Argument.
TRANSLATION Designates a translational force. Adams/Solver (C++) applies
the translational force between the I and the J markers.
Adams/Solver
C++ Statements
338
For rotational actionreaction forces, Adams/Solver (C++) applies an action torque on the I marker about
the zaxes of the I marker and a reaction torque on the J marker about the zaxis of the J marker.
Furthermore, Adams/Solver (C++) assumes that the zaxes of the I and the J markers are parallel.
For rotational actiononly 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 zaxis of the J marker.
You write a function expression or a userwritten 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.
Examples
SFORCE/0104, I=0409, J=0109, TRANSLATION
, FUNCTION=IF((DM(0409,0109)10.0):
, 100.00*(DM(0409,0109)10.0),0,0)
This SFORCE statement describes an actionreaction, compressiononly force exerted on Marker 0409
by Marker 0109. The argument TRANSLATION designates a translational force, and the argument
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= k
0
+ k
1
(x1) + k
2
(x1)
2
+ cx'
where k
0
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, k
1
and k
2
are stiffness coefficients, and c is a
damping coefficient. This equation representing the force magnitude can be rewritten in the following
polynomial format:
Tip: • When an SFORCE statement defines a translational actionreaction 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 zaxis direction.
• For actionreaction 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 actionreaction SFORCEs, the zaxes 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 bewteen the Adams/Solver (C++) and Adams/Solver (FORTRAN).
339 SFORCE
C++ Statements
If k
0
= 10.1, k
1
= 15.2, k
2
= 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
SFORCE/123, I=12, J=34, TRANSLATION
, 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.
See other Forces available.
F K
j
x l – ( )
j
cx' +
j 0 =
2
¯
=
Adams/Solver
C++ Statements
340
SPLINE
The SPLINE statement defines discrete data that Adams/Solver (C++) interpolates using the AKISPL
and CUBSPL function expressions and the AKISPL and CUBSPL dataaccess 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
or
or
SPLINE/id
X = x1, x2, x3, x4 [, ..., xn] ,
Y = y1, y2, y3, y4 [, ..., yn] ,
[, XUNITS = string ]
[, YUNITS = string ]
[, UNITS = string ]
[, LINEAR_EXTRAPOLATE]
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]]
[, XUNITS = string ]
[, YUNITS = string ]
[, ZUNITS = string ]
[, UNITS = string ]
[, LINEAR_EXTRAPOLATE]
341 SPLINE
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 userwritten
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
OLATE
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.
SPLINE/id
FILE = filename ,
[, BLOCK = blockname]
, CHANNEL = id  
[, XUNITS = string ]
[, YUNITS = string ]
[, UNITS = string ]
[, LINEAR_EXTRAPOLATE]
Adams/Solver
C++ Statements
342
Extended Definition
Adams/Solver (C++) applies curvefitting 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,
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,y
14 [ , . . . , y1n]
,Y=z2,y21,y22,y23,
y24 [ , . . . , y2n]
,Y=z3,y31,y32,y33,
y34 [
,ym1,ym2,ym3,ym4
[ , . . . , ymn]]
Approximates a family of curves by specifying the corresponding y values:
y1,y2,y3,y4[, . . . ,yn] for the x values at unique z values
(z1[, . . . ,zm]).
Values must be constants; Adams/Solver (C++) does not allow expressions.
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",
"flowrate_pressure_d", "flow_rate", "force_per_angle", "damping_per_angle".
Default: (none)
XUNITS
YUNITS
ZUNITS
Specify the type of units to be used for individual set of values (X, Y or Z
respectively). In general X units will be “time” and Y units will be of type
“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)
343 SPLINE
C++ Statements
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
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 userwritten
subroutine that calls one of the two spline dataaccess subroutines (AKISPL and CUBSPL).
Spline Function Interpolation Methods
The SPLINE functions and dataaccess 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, curvefitting technique.
• The CUBSPL function and the CUBSPL subroutine use the traditional cubic method of
interpolation. This method includes a global, cubic, curvefitting 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 curvefitting 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
userdefined file format, and processes the SPLINE statement using a SPLINE_READ usersupplied
subroutine. For more on how to define a SPLINE using the FILE argument for userdefined file formats,
see the example in SPLINE_READ subroutine.
Adams/Solver
C++ Statements
344
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.
Examples
The set of values in the table below relates the force in a spring to its deformation.
Data Relating Spring and SpringDeflection Force
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.
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.
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
345 SPLINE
C++ Statements
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”
, 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, forcedeflection relationships of a spring at
various temperatures.
Data Relating Spring Force to Spring Deflections at Various Temperatures
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:
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
Adams/Solver
C++ Statements
346
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
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 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
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 zaxis 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
SPLINE/202,FILE=test.rpc,CHANNEL=2
SPLINE/203,FILE=test.rpc,CHANNEL=3
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.
See other Reference data available.
347 SPRINGDAMPER
C++ Statements
SPRINGDAMPER
The SPRINGDAMPER statement applies a rotational or a translational springdamper between two
markers.
Format
Click the argument for a description.
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
Adams/Solver
C++ Statements
348
Extended Definition
The SPRINGDAMPER statement applies a rotational or a translational springdamper between two
markers. For a rotational springdamper, the zaxis of the I marker and the zaxis of the J marker must be
parallel and must point in the same direction.
Because the springdamper force is always an actionreaction 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:
F
a
= C (db/dt)  K(bLENGTH) + 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:
T
a
= CT (da/dt)  KT(aANGLE) + TORQUE
The torque value is applied to the I marker about the positive zaxis of the I marker; the torque on the J
marker is equal and opposite to the torque on the I marker. The righthand rule defines a positive torque.
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.
349 SPRINGDAMPER
C++ Statements
The term a is the angle of the Imarker xaxis relative to the Jmarker xaxis, measured about the Jmarker
zaxis. Adams/Solver (C++) takes into account the total number of complete rotations. Adams/Solver
(C++) automatically computes the terms da/dt and a.
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 unitsseconds
per unit length.
See other Forces available.
Caution: • If the zaxis of the I marker is not parallel to, and/or not pointed in the same
direction as, the zaxis of the J marker for a rotational springdamper, the results are
unpredictable.
• Since the lineofsight method determines the direction of a translational
springdamper force, the I and the J markers cannot be coincident.
Adams/Solver
C++ Statements
350
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 userwritten subroutine.
Format
STRING/id, STRING=c
Arguments
Examples
STRING/101, STRING=MARKER=
This STRING statement enters the character string MARKER= for later reference. The GTSTRG
subroutine can retrieve this string.
See other Reference data available.
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.
351 SURFACE
C++ Statements
SURFACE
The SURFACE statement defines a threedimensional 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
(r1[,...,r30])/
Defines constants that are passed to SURSUB, the userwritten
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 userwritten 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 userwritten surface. If a file is specified, the file is queried for
the MINPAR values.
Default: (1.0, 1.0)
Adams/Solver
C++ Statements
352
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( u
2
+ v
2
)
ROUTINE=libname::subname Specifies an alternative library and name for the user subroutine
SURSUB.
Learn more about the ROUTINE Argument.
UCLOSED Specifies that a userwritten 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 userwritten 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
353 SURFACE
C++ Statements
Example of a Parametric Surface
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 userwritten
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
Adams/Solver
C++ Statements
354
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 (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 userwritten 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 * [(uu*)
2
+ (vv*)
2
]
K = 10
8
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 userwritten 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 higherpair 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 endeffector executing a specific workpath while orienting the endeffector 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.
See other Reference data available.
355 TFSISO
C++ Statements
TFSISO
The TFSISO (Transfer Function, SingleInput, SingleOutput) statement defines a singleinput, 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 quasistatic analysis.
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.
Adams/Solver
C++ Statements
356
Extended Definition
The TFSISO (Transfer Function, SingleInput, SingleOutput) statement is designed to model a linear,
timeinvariant dynamic system defined in the Laplace domain, especially to facilitate the import of
elements from controlsystem block diagrams. It can also be used, however, to define an arbitrary set of
constantcoefficient, differential and algebraic equations which can be expressed in the Laplace domain
as
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 statespace form; that is, a set of coupled, linear,
constantcoefficient 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 statespace 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 = [b
0
/a
k
,b
1
/a
k
,...,b
m
/a
k
,0,...,0,0]
p = [a
0
/a
k
,a
1
/a
k
,...,a
k1
/a
k
,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.
G s ( )
y s ( )
u s ( )

b
o
b
1
s
1
. b
m
s
m
+ + +
a
o
a
1
s
1
. a
k
s
k
+ + +
 = =
357 TFSISO
C++ Statements
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:
The equivalent state space realization of this transfer function is:
where:
G s ( )
y s ( )
u s ( )

q
o
q
1
s
1
. q
k
s
k
+ + +
p
o
ps
1
. p
k
s
k
+ + +
 = =
x
·
y
¹ )
´ `
¦ ¹
A B
C D
x
u
¹ )
´ `
¦ ¹
=
A
p
k 1 –
– 1 0 . . . 0 0
p
k 2 –
– 0 1 . . . 0 0
. . . 1 . . . .
. . . . . . . .
. . . . . . 1 .
p
1
– 0 0 . . . 0 1
p
o
– 0 0 . . . 0 0
= B
q
k 1 –
p
k 1 –
q
k
–
q
k 2 –
p
k 2 –
q
k
–
.
.
.
q
1
p
1
q
k
–
q
o
p
o
q
k
–
=
C
1 0 0 . . . 0 0
= D
q
k
=
Note: Except in the specific case where the numerator and denominator are of equal orders, q
k
= 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, 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.
Adams/Solver
C++ Statements
358
Examples
ARRAY/100, X
ARRAY/101, U, VARIABLE=101
ARRAY/102, Y
VARIABLE/101, FUNCTION=ACCZ(5,99,5)
Caution: • Although the TFSISO statement allows for up to 30 numerator and denominator
coefficients in the transfer function, the conversion to the canonical statespace
form is typically not robust for higherorder systems. Such systems should be used
only when you are confident that the problem is wellposed. 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 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. 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 polezero 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 polezero cancellation prior to defining the
TFSISO data.
• 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. If STATIC_HOLD is not specified, during a static analysis,
Adams/Solver (C++) sets the time derivatives of the userdefined variables to zero,
and uses the usersupplied initialcondition 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 userdefined 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 userspecified initial conditions are
retained as the static equilibrium values. Thus, the final equilibrium values are the
same as the userspecified initial conditions. Note that this does not guarantee that
the time derivatives of the userdefined variable are zero after static analysis.
359 TFSISO
C++ Statements
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.
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
userwritten 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.
See other Generic systems modeling available.
G s ( )
1
s
2
10s 100 + +
 =
Adams/Solver
C++ Statements
360
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:
Satellite with Flexible Panels: Deployment Study #13, 05/98
See other Dataset delimiter statement available.
361 UNITS
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
Adams/Solver
C++ Statements
362
Arguments
FORCE = {CENTINEWTON, DYNE,
KILOGRAM_FORCE, KNEWTON,
KPOUND_FORCE, MEGANEWTON,
MICRONEWTON, MILLINEWTON,
NANONEWTON, NEWTON,
OUNCE_FORCE, POUND_FORCE,
POUNDAL}
Selects a predefined unit for forces. Must be used in
conjunction with LENGTH, MASS, and TIME.
LENGTH = {ANGSTROM,
CENTIMETER, FOOT, KILOMETER,
INCH, METER, MICROINCH,
MICROMETER, MILE, MILLIMETER,
MILS, NANOMETER, YARD}
Selects a predefined unit for lengths. Must be used in
conjunction with FORCE, MASS, and TIME.
MASS = {GRAM, KILOGRAM,
KPOUND_MASS, MILLIGRAM,
MICROGRAM, NANOGRAM,
OUNCE_MASS, POUND_MASS,
SLINCH, SLUG, TONNE, US_TON}
Selects a predefined unit for masses. Must be used in
conjunction with FORCE, LENGTH, and TIME.
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,
MILLISECONDS, MINUTE,
NANOSECOND, SECOND}
Selects a predefined unit for time. Must be used in
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 mass units to dynamical mass units as
shown by the following equation:
Examples of how to calculate the UCF for your choice of
units are given below in the Extended Definition of the
UNITS statement.
Force
Mass
UCF
 Acceleration =
363 UNITS
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.
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
2
nd
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 2
nd
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 s
F
, s
M
, s
L
, and s
T
:
s
F
F' = F (2)
s
M
M' = M (3)
s
L
L' = L (4)
s
T
T' = T (5)
Equation (4) and Equation (5) imply that acceleration expressed in model units is related to acceleration
in dynamical units by
Adams/Solver
C++ Statements
364
(6)
Using Equation (2), Equation (3), and Equation (6) to substitute F, M, and A, and into Equation (1) gives
(7)
By defining the UCF as
(8)
to combine the four scale factors into one, Equation (7) can then be rewritten as
(9)
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 postprocessing, such as
for switching unit systems (even for angles) prior to sending a model to Adams/Solver (C++) for analysis,
and for putting unitlabels 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.
s
L
s
T
2
A' A =
F' M' A'
s
M
s
L
s
F
s
T
2
 =
UCF
s
F
s
T
2
s
M
s
L
 =
F'
M'
UCF
A' =
365 UNITS
C++ Statements
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 s
F
, s
M
, s
L
, and s
T
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 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,
(10)
(11)
(12)
(13)
When these values are substituted into Equation (8), the result is UCF = 38608.858267716525. Note that
s
F
, s
M
, s
L
, and s
T
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: (s
T
, s
L
, s
F
, s
M
)).
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 s
F
, s
M
, s
L
, and s
T
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
s
F
8896.443230521
NEWTON
TON FORCE
 =
s
M
907.18474
KILOGRAM
US TON
 =
s
L
0.9144
METER
YARD
 =
s
T
60
SECOND
MINUTE
 =
Adams/Solver
C++ Statements
366
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.
Table 1 Force Conversion Factors
‡ Depends on the definition 1 lbm = 0.45359237 kg, exactly.
§ Depends on the definition standard gravity = 9.80665 m/s
2
, exactly.
¶ It may seem that S
F
is approximate for the OUNCE_FORCE, but it turns out that 17 digits are just enough to represent it exactly.
(Value in model units) * S
F
= (Value in Newtons)
Model Units S
F
CENTINEWTON 0.01
DYNE 1.0e5
KILOGRAM_FORCE 9.80665 (§)
KNEWTON 1000
KPOUND_FORCE 4448.2216152605 (‡, §)
MEGANEWTON 1.0e6
MICRONEWTON 1.0e6
MILLINEWTON 0.001
NANONEWTON 1.0e9
OUNCE_FORCE 0.27801385095378125 (‡, §, ¶)
POUND_FORCE 4.4482216152605 (‡, §)
POUNDAL 0.138254954376 (‡, §)
367 UNITS
C++ Statements
Table 2 Mass Conversion Factors
‡ Depends on the definition 1 lbm = 0.45359237 kg, exactly.
§ Depends on the definition standard gravity = 9.80665 m/s
2
, exactly.
¶ Approximate to 17 digits.
Table 3 Length Conversion Factors
(Value in model units) * S
M
= (Value in kilograms)
Model Units S
M
GRAM 0.001
KPOUND_MASS 453.59237 (‡)
MILLIGRAM 1.0e6
MICROGRAM 1.0e9
NANOGRAM 1.0e12
OUNCE_MASS 0.028349523125 (‡)
POUND_MASS 0.45359237 (‡)
SLINCH 175.12683524647638 (¶, ‡, §)
SLUG 14.593902937206365 (¶, ‡, §)
TONNE 1000
US_TON 907.18474 (‡)
(Value in model units) * S
L
= (Value in meters)
Model Units S
L
ANGSTROM 1.0e10
CENTIMETER 0.01
FOOT 0.3048
KILOMETER 1000
INCH 0.0254
MICROINCH 2.54e08
MICROMETER 1.0e6
MILE 1609.344
MILLIMETER 0.001
MILS 2.54e05
NANOMETER 1.0e9
YARD 0.9144
Adams/Solver
C++ Statements
368
Table 4 Time Conversion Factors
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 illconditioned. 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 temporalerror
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.
See other Analysis parameters available.
(Value in model units) * S
T
= (Value in seconds)
Model Units S
T
DAY 86400
HOUR 3600
MICROSECOND 1.0e6
MILLISECOND 0.001
MINUTE 60
NANOSECOND 1.0e9
369 VARIABLE
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
Extended Definition
The VARIABLE statement creates a userdefined 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 userwritten subroutine. Learn more on UserWritten Subroutines and
Utility Subroutines.
Specifies an expression or defines and passes constants to a
userwritten 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 userwritten 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 userwritten
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
initial conditions solution.
ROUTINE = libname::subname Specifies an alternative library and name for the user
subroutine VARSUB.
Learn more about the ROUTINE Argument.
Adams/Solver
C++ Statements
370
Function expressions and userwritten 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 userselected identifier of the VARIABLE statement. Userwritten subroutines access single
VARIABLE statement values by calling the subroutine SYSFNC.
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.
See other Generic systems modeling available.
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
NewtonRaphson 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.
371 VFORCE
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 userspecified function
expressions in the Adams/Solver (C++) dataset or through userwritten 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 xaxis 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 yaxis of the RM marker.
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 zaxis of the RM marker.
FUNCTION=USER(r1[,...,r30]) Specifies up to 30 userdefined constants for use in computing the
force components in a userdefined 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 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.
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.
Adams/Solver
C++ Statements
372
Extended Definition
The VFORCE statement creates an Adams/Solver (C++) translational vector force element that applies
a threecomponent 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
mutuallyorthogonal force components. You can specify the functions with function expressions (see
C++ Functions) or userwritten FORTRAN subroutines (see UserWritten 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:
where:
• F
a
is the action applied to the I marker
• FX is the userdefined function defining the magnitude and sign of the xcomponent
• FY is the userdefined function defining the magnitude and sign of the ycomponent
• FZ is the userdefined function defining the magnitude and sign of the zcomponent
• is a unit vector along the + xdirection of the RM marker
• is a unit vector along the + ydirection of the RM marker
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.
ROUTINE=libname::subname Specifies an alternative library and name for the user subroutine
VFOSUB.
Learn more about the ROUTINE Argument.
F
a
FXx
ˆ
rm
FYy
ˆ
rm
FZz
ˆ
rm
+ + =
x
ˆ
rm
y
ˆ
rm
373 VFORCE
C++ Statements
• is a unit vector along the + zdirection of the RM marker
Reaction
Applied to: JFLOAT marker
Values:
F
r
= F
a
where F
r
is the reaction applied to the JFLOAT marker.
Examples
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.
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.
z
ˆ
rm
Tip: Depending on the nature of the desired force 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 userdefined functions FX, FY, and FZ should be smooth, continuous, and single
valued. These conditions make the solution process very effective.
Adams/Solver
C++ Statements
374
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 of application (with respect to the part containing the JFLOAT marker) and its resultant direction
(with 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 sixcomponent force set.
See other Forces available.
375 VTORQUE
C++ Statements
VTORQUE
The VTORQUE statement defines a vector torque that consists of three orthogonal components. You can
define the VTORQUE statement through userspecified function expressions in the Adams/Solver (C++)
dataset or through userwritten subroutines.
Format
Arguments
FUNCTION=USER(r1[,...,r30]) Specifies up to thirty userdefined constants used to compute the
torque components in an externallydefined 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 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. 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
components. You must ensure that RM is a fixed marker. RM may
be the same as I and on any part in the system.
ROUTINE=libname::subname Specifies an alternative library and name for the user subroutine
VTOSUB.
Learn more about the ROUTINE Argument.
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 xaxis of the RM marker in the sense of
the righthand rule (that is, a positive torque causes a
counterclockwise rotation).
Adams/Solver
C++ Statements
376
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
userwritten FORTRAN subroutines (see UserWritten Subroutines).
The direction of the torque action is determined by the resultant 376 of 710vector formed by the three
component torque you defined along the RM marker axes. The reaction is equal and opposite to the
action.
Formulation
Action
Applied to: I marker
Values:
where:
• T
a
is the action applied to the I marker
• TX is the userdefined function defining the magnitude and sign of the xcomponent according
to the righthand rule
• TY is the userdefined function defining the magnitude and sign of the ycomponent according
to the righthand rule
TY=e Specifies the magnitude and sign of the y component of the torque
exerted by the VTORQUE element. The direction of this torque
component is parallel to the yaxis of the RM marker in the sense of
the righthand rule (that is, a positive torque causes a
counterclockwise rotation).
TZ=e Specifies the magnitude and sign of the z component of the torque
exerted by the VTORQUE element. The direction of this torque
component is parallel to the zaxis of the RM marker in the sense of
the righthand rule (that is, a positive torque causes a
counterclockwise rotation).
T
a
TXx
ˆ
rm
TYy
ˆ
rm
TZz
ˆ
rm
+ + =
377 VTORQUE
C++ Statements
• TZ is the userdefined function defining the magnitude and sign of the zcomponent according to
the righthand rule
• is a unit vector along the + xdirection of the RM marker
• is a unit vector along the + ydirection of the RM marker
• is a unit vector along the + zdirection of the RM marker
Reaction
Applied to: JFLOAT marker
Values:
T
r
= T
a
where T
r
is the reaction applied to the JFLOAT marker.
Examples
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.
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 aerodynamic center. You can use a VFORCE statement (see VFORCE) to supply the remaining
x
ˆ
rm
y
ˆ
rm
z
ˆ
rm
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 userdefined functions TX, TY, and TZ should be smooth, continuous, and single
valued. These conditions make the solution process very effective.
Adams/Solver
C++ Statements
378
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 Earthorbiting 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.
See other Forces available.
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
ACOS
AINT
ANINT
ASIN
ATAN
ATAN2
COS
COSH
EXP
LOG
LOG10
MAX
MIN
MOD
SIGN
SIN
SINH
SQRT
TAN
TANH
Simulation parameters and constants CPU
HSIZE
TIME
MODE
NJAC
NRHS
ORDER
PI
DTOR
RTOD
Displacement measures AX
AY
AZ
DM
DX
DXYZ
DY
DZ
INCANG
PHI
PITCH
PSI
ROLL
THETA
YAW
Velocity measures VM
VR
VX
VXYZ
VY
VZ
WM
WX
WY
WZ
Acceleration measures ACCM
ACCX
ACCY
ACCZ
WDTM
WDTX
WDTY
WDTZ
Adams/Solver
C++ Functions
2
Generic force measures FM
FX
FY
FZ
TM
TX
TY
TZ
Elementspecific applied force measures BEAM
BUSH
FIELD
FRICTION
GFORCE
SFORCE
SPDP
VFORCE
VTORQ
Elementspecific reaction force measures CVCV
JOINT
JPRIM
MOTION
PTCV
System element measures ARYVAL
DIF
DIF1
PINVAL
POUVAL
SENVAL
VARVAL
Arithmetic IF IF
Action Only Constraint Function AO
Interpolation functions AKISPL
CUBSPL
CURVE
INTERP
Miscellaneous Adams intrinsic functions BISTOP
CHEBY
DELAY
FORCOS
FORSIN
HAVSIN
IMPACT
INVPSD
POLY
SHF
STEP
STEP5
SWEEP
Flexible body constants FXFREQ
FXMODE
Vector measures ACCXYZ
DXYZ
FXYZ
TXYZ
UVX
UVY
UVZ
VXYZ
WXYZ
WDTXYZ
Vector functions UV
MAG
TRANS
Category Name
3 ABS
C++ Functions
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 intrinsic functions available.
a Any valid function expression.
Number of Arguments: 1
Adams/Solver
C++ Functions
4
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
Extended Definition
Mathematically, ACCM is calculated as follows:
where is the displacement of marker i in ground and is the displacement of marker j in ground.
Note that for any vector quantity :
Examples
REQUEST/10, F2=ACCM(21,11)
This statement defines the second component of a userdefined 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)
This statement defines the second component of a userdefined 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.
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
coordinate system (GCS).
ACCM i j , l , ( )
t
2
2
d
d
Ri
l ( )
t
2
2
d
d
Rj
l ( )
–
t
2
2
d
d
Ri
l ( )
t
2
2
d
d
Rj
l ( )
– · =
Ri Rj
p
t d
d
A ( )
p
t d
d
B ( )
p =
5 ACCM
C++ Functions
See other Acceleration measures available.
Adams/Solver
C++ Functions
6
ACCX
The ACCX function returns the xcomponent 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
Extended Definition
Mathematically, ACCX is calculated as follows:
where is the displacement of marker i in ground, is the displacement of marker j in ground, and
is the unit vector along the xaxis of marker k.
Examples
DIFF/1, IC=0, FUNCTION=ACCX(21,11)
This statement defines a userspecified differential equation. The time derivative of the state is specified
to be the xcomponent 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)
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.
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 xaxis 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).
ACCX i j , k , l , ( )
t
2
2
d
d
Ri
l ( )
t
2
2
d
d
Rj
l ( )
– x
ˆ
k
· =
Ri Rj
x
ˆ
k
7 ACCX
C++ Functions
This statement defines a userspecified differential equation. The time derivative of the state is specified
to be the xcomponent of the acceleration vector of Marker 21 with respect to the global origin. The
vector is 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.
See other Acceleration measures available.
Adams/Solver
C++ Functions
8
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
Extended Definition
Mathematically, ACCXYZ is calculated as follows:
where:
• is the displacement of marker i with respect to the global origin.
• is the displacement of marker j with respect to the global origin.
i The marker whose acceleration is being measured.
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.
ACCXYZ i j , k , l , ( )
t
2
2
d
d
Ri
l ( )
t
2
2
d
d
Rj
l ( )
– x
ˆ
k
·
t
2
2
d
d
Ri
l ( )
t
2
2
d
d
Rj
l ( )
– y
ˆ
k
·
t
2
2
d
d
Ri
l ( )
t
2
2
d
d
Rj
l ( )
– z
ˆ
k
·
¹ )
¦ ¦
¦ ¦
¦ ¦
¦ ¦
´ `
¦ ¦
¦ ¦
¦ ¦
¦ ¦
¦ ¹
ACCX
ACCY
ACCZ
¹ )
¦ ¦
´ `
¦ ¦
¦ ¹
= =
Ri
Rj
9 ACCXYZ
C++ Functions
• denotes two time differentiations in the reference frame of the l marker.
• ACCX is the ACCX measure.
• ACCY is the ACCY measure.
• ACCZ is the ACCZ measure.
• is the unit vector along the xaxis of marker k.
• is the unit vector along the yaxis of marker k.
• is the unit vector along the zaxis 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.
t
2
2
d
d
l ( )
x
ˆ
k
y
ˆ
k
z
ˆ
k
Adams/Solver
C++ Functions
10
ACCY
The ACCY function returns the ycomponent 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
ACCY(i[,j][,k][,l])
Arguments
Extended Definition
Mathematically, ACCY is calculated as follows:
where is the displacement of marker i in ground, is the displacement of marker j in ground, and
is the unit vector along the yaxis of marker k.
Examples
DIFF/1, IC=0, FUNCTION=ACCX(21,11)
This statement defines a userspecified differential equation. The time derivative of the state is specified
to be the xcomponent 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)
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.
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 yaxis 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).
ACCY i j , k , l , ( )
t
2
2
d
d
Ri
l ( )
t
2
2
d
d
Rj
l ( )
– y
ˆ
k
· =
Ri Rj
y
ˆ
k
11 ACCY
C++ Functions
This statement defines a userspecified differential equation. The time derivative of the state is specified
to be the xcomponent of the acceleration vector of Marker 21 with respect to the global origin. The
vector is 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.
See other Acceleration measures available.
Adams/Solver
C++ Functions
12
ACCZ
The ACCZ function returns the zcomponent 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
ACCZ(i[,j][,k][,l])
Arguments
Extended Definition
Mathematically, ACCZ is calculated as follows:
where is the displacement of marker i in ground, is the displacement of marker j in ground, and
is the unit vector along the zaxis of marker k.
Examples
DIFF/1, IC=0, FUNCTION=ACCX(21,11)
This statement defines a userspecified differential equation. The time derivative of the state is specified
to be the xcomponent 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
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.
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 zaxis of the global coordinate system.
l The reference frame in which the secondtime 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).
ACCZ i j , k , l , ( )
t
2
2
d
d
Ri
l ( )
t
2
2
d
d
Rj
l ( )
– z
ˆ
k
· =
Ri Rj
z
ˆ
k
13 ACCZ
C++ Functions
This statement defines a userspecified differential equation. The time derivative of the state is specified
to be the xcomponent of the acceleration vector of Marker 21 with respect to the global origin. The
vector is 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.
See other Acceleration measures available.
Adams/Solver
C++ Functions
14
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 userdefined 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.
See other FORTRAN 77 intrinsic functions available.
a Any valid function expression.
Number of Arguments: 1
t
t
15 AINT
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
Examples
AINT(6.5) = 6
AINT(4.6 ) = 4
See other FORTRAN 77 intrinsic functions available.
a Any valid function expression.
Number of Arguments: 1
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.
Adams/Solver
C++ Functions
16
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
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 (xy points) or a surface (xy
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.
x A real variable that specifies the independent variable value along the xaxis of the AKISPL.
z A real variable that specifies the second independent variable value along the zaxis 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
17 AKISPL
C++ Functions
For more information on the Akima method of interpolation, see the references listed in Additional
Publications.
Examples
SFORCE/1, I=409, J=109, TRANSLATION
, 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.
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.
Adams/Solver
C++ Functions
18
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
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
ANINT(a)
Arguments
Examples
ANINT(4.6) = 5
ANINT(4.6) = 5
See other FORTRAN 77 intrinsic functions available.
a Any valid function expression.
Number of arguments: 1
19 AO
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
Extended Definition
To understand the purpose of the AO function, it is best to examine Lagrange's equations for a
constrained system:
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
exp The subexpression which is to be isolated from a reaction force.
t d
d
q
·
c
cL
\ .
 
q c
cL
– ì
T
C
q
+ 0
T
=
C q t , ( ) 0 =
ì
Adams/Solver
C++ Functions
20
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.
21 ARYVAL
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
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 1114.
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.
id The identifier of the array whose data is being requested.
comp An integer that specifies the component of the array to be returned.
Adams/Solver
C++ Functions
22
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 userspecified 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))
See other FORTRAN 77 intrinsic functions available.
a Any valid function expression.
Number of arguments: 1
t t t t
23 ATAN
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
xaxis as shown in the figure below.
Example Illustrating the Use of the ATAN Function
See other FORTRAN 77 intrinsic functions available.
a Any valid function expression.
Number of arguments: 1
t t
t t
Adams/Solver
C++ Functions
24
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 algebraicallydetermined, userdefined state variable in
Adams/Solver (C++). Its value is specified by the expression containing ATAN2.
See other FORTRAN 77 intrinsic functions available.
a1 Any valid function expression.
a2 Any valid function expression.
t t
t
t
25 AX
C++ Functions
AX
The AX function returns the rotational displacement of marker i about the xaxis 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 zaxes) of marker j are zero. Then, AX is the angle
between the two yaxes (or the two zaxes). AX is measured in a counterclockwise sense from the yaxis
of marker J to the yaxis of marker I (see the figure below).
Measurement of AX
Format
AX(i[,j])
Arguments
Extended Definition
Mathematically, AX is calculated as:
where:
• is the zaxis of marker i
• is the yazis of marker j
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.
AX ATAN2 z
ˆ
i
– y
ˆ
j
z
ˆ
i
. z
ˆ
j
  ( ) =
z
ˆ
i
y
ˆ
j
Adams/Solver
C++ Functions
26
• is the zaxis of marker j
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 xaxis 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 yaxis of Marker 32 to the yaxis of Marker 43.
See other Displacement measures available.
z
ˆ
j
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 yaxis or zaxis on Marker j, the AX
function becomes increasingly nonphysical. Moreover, AX is undefined when both
arguments to ATAN2 are zero. This occurs when the zaxis of marker i is orthogonal to the
plane defined by the y and zaxis of the j marker.
27 AY
C++ Functions
AY
The AY function returns the rotational displacement of marker i about the yaxis 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, zaxes) of marker j are zero. Then AY is the angle
between the two xaxes (or the two zaxes). AY is measured counterclockwise from the zaxis of the J
marker to the zaxis of the I marker (see the figure below).
Measurement of AY
Format
AY(i[,j])
Arguments
Extended Defintion
Mathematically, AY is calculated as:
where:
• is the zaxis of marker i
• is the xazis of marker j
i The marker whose rotations are being sought.
j The marker with respect to which the rotations are being measured.
AY ATAN2 z
ˆ
i
x
ˆ
j
z
ˆ
i
. z
ˆ
j
  ( ) =
z
ˆ
i
x
ˆ
j
Adams/Solver
C++ Functions
28
• is the zaxis of marker j
Examples
SFORCE/10, ROTATION, I=23, J=34
, FUNCTION=4*(AY(46,57)**2)
This SFORCE statement applies a moment about the common zaxes 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 zaxis of Marker 57 to the zaxis
of Marker 46.
See other Displacement measures available.
z
ˆ
j
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)
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 xaxis or zaxis of marker j, the AY
function becomes increasingly nonphysical. Moreover, AY is undefined when both
arguments to ATAN2 are zero. This occurs when the zaxis of marker i is orthogonal to the
plane defined by the x and zaxis of the j marker.
29 AZ
C++ Functions
AZ
The AZ function returns the rotational displacement of marker i about the zaxis 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 (x, yaxes) of marker j are zero. Then AZ is the angle
between the two xaxes (or the two yaxes). AZ is measured in a counter clockwise sense from the x
axis of the J marker to the xaxis of the I marker (see the figure below).
Measurement of AZ
Format
AZ(i [,j ])
Arguments
Extended Definition
Mathematically, AZ is calculated as:
where:
• is the xaxis of marker i
• is the xazis of marker j
i The marker whose rotations are being sought.
j The marker with respect to which the rotations are being measured.
AZ ATAN2 x
ˆ
i
y
ˆ
j
 x
ˆ
i
x
ˆ
j
 . ( ) =
x
ˆ
i
x
ˆ
j
Adams/Solver
C++ Functions
30
• is the yaxis of marker j
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.
See other Displacement measures available.
y
ˆ
j
Tip: If you want to change the AZ function so it does not account for angle wrapping, use the
MOD function. For example, use the function:
(MOD(AZ(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 xaxis or yaxis of marker j, the AZ
function becomes increasingly nonphysical. Moreover, AZ is undefined when both
arguments to ATAN2 are zero. This occurs when the xaxis of marker i is orthogonal to the
plane defined by the x and yaxis of the j marker.
31 BEAM
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
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 zcomponent 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 Elementspecific applied force measures available.
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.
Adams/Solver
C++ Functions
32
BISTOP
The BISTOP function models a gap element (see Figure 1).
Format
BISTOP (x, , x1, x2, k, e, c
max
, d)
Arguments
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.
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).
The time derivative of x to BISTOP. For example, if x is DX(0201,0301,301) then is
VX(0201,0301,0301,0301).
x
1
The lower bound of x. If x is less than x
1
Adams/Solver (C++) calculates a positive value for
the force. The value of x
1
must be less than the value of x
2
.
x
2
The upper bound of x. If x is greater than x
2
Adams/Solver (C++) calculates a negative value
for the force. The value of x
2
must be greater than the value of x
1
.
k A nonnegative 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.
c
max
A nonnegative variable that specifies the maximum damping coefficient.
d A positive real variable that specifies the penetration at which the full damping coefficient is
applied.
x
·
x
·
33 BISTOP
C++ Functions
Figure 1 Example of the BISTOP Function
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, c
max
, at a userdefined 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
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 zaxes 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.
Caution: When e is < 1, the defined force contains a slope discontinuity that may casue difficulty for
the integrator.
Adams/Solver
C++ Functions
34
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.
• 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.
• x2 is the instantaneous distance between the I and the J markers when the floating part first
comes into contact with the right end of the slot.
Therefore, the parameters for BISTOP for this example are:
x = DZ(I,J,J) and = 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, c
max,
d)
The values of k, e, c
max
, 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:
See other Miscellaneous Adams intrinsic functions available.
x
·
BISTOP
Max k x
1
x – ( )
e
STEP x x
1
d c
max
x
1
0 . . . – . ( ) x' 0 . · – · ( ): x x
1
<
0
: x
1
x x
2
s s
Min k – x x
2
– ( )
e
STEP x x
2
0 x
2
d c
max
. + . . . ( ) x' 0 . · – · ( ): x x
2
>
¹ )
¦ ¦
´ `
¦ ¦
¦ ¹
=
35 BUSH
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 if the results are desired in the global coordinate system.
Format
BUSH (id, jflag, comp, rm)
Arguments
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 zcomponent of the forces in BUSH/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 Elementspecific applied force measures available.
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.
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 bushing 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.
Adams/Solver
C++ Functions
36
CHEBY
The CHEBY function evaluates a Chebyshev polynomial at a user specified value x.
Format
CHEBY (x, x0, a0, a1,..., a30)
Arguments
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 T
j
(xx0)
where the functions Tj are recursively defined as:
T
j
(xx0) = 2 * (xx0) * T
j1
(xx0)  T
j2
(xx0)
with T
0
(xx0) = 1, and T
1
(xx0) =xx0.
The index “j” has a range from zero to “n”, where “n” is the number of terms in the series.
Note the following:
T
2
(xx0) = 2 * (xx0)
2
 1
T
3
(xx0) = 4 * (xx0)
3
 3 * (xx0)
Examples
MOTION/1, JOINT=21, TRANSLATION,
,FUNCTION = IF (TIME2: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 * (time1)  1 * [2 (time1)
2
 1]= 2*time
2
+4*time
See other Miscellaneous Adams intrinsic functions available.
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 thirtyone coefficients
may be specified.
¯
37 CONTACT
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
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 zcomponents 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.
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  xcomponent of the force applied by all incidents of contact ID
• 3  ycomponent of the force applied by all incidents of contact ID
• 4  zcomponent of the force applied by all incidents of contact ID
• 5  Magnitude of the torque applied by all incidents of contact ID
• 6  xcomponent of the torque applied by all incidents of contact ID
• 7  ycomponent of the torque applied by all incidents of contact ID
• 8  zcomponent of the torque applied by all incidents of contact ID
rm The coordinate system in which the results are expressed. To return the results in the global
coordinate system, set rm = 0.
Adams/Solver
C++ Functions
38
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).
See other FORTRAN 77 intrinsic functions available.
a Any valid function expression.
Number of Arguments: 1
39 COSH
C++ Functions
COSH
The COSH function computes the hyperbolic cosine of an expression a.COSH(a) = (e
a
+ 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 zcomponent 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.
See other FORTRAN 77 intrinsic functions available.
a Any valid function expression.
Number of Arguments: 1
Adams/Solver
C++ Functions
40
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.
41 CUBSPL
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
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 (xy points) or a
surface (xyz 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.
x A real variable that specifies the independent variable value along the xaxis of the CUBSPL.
A real variable that specifies the second independent variable value along the zaxis 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
Adams/Solver
C++ Functions
42
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.
See other Interpolation functions available.
43 CURVE
C++ Functions
CURVE
The CURVE function evaluates a Bspline or userwritten curve that is created with the CURVE
statement.
Format
CURVE (alpha, iord, comp, id)
Arguments
Examples
VFORCE/1, I=101, JFLOAT=201, RM=99,
, FX=CURVE(.4*TIME  1, 0, 1, 8)/
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 Bspline 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:
id An integer variable that specifies the identifier of the CURVE statement.
o
o
o
iord icomp 1 = icomp 2 = icomp 3 =
0 x o ( ) y o ( ) z o ( )
1
x o ( ) d
o d

y o ( ) d
o d

z o ( ) d
o d

2
d
2
x o ( )
o
2
d

d
2
y o ( )
o
2
d

d
2
z o ( )
o
2
d

Adams/Solver
C++ Functions
44
, FY=CURVE(.4*TIME  1, 0, 2, 8)/
, FZ=CURVE(.4*TIME  1, 0, 3, 8)
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*TIME1 computes
the instantaneous value of alpha from the simulation time.
See other Interpolation functions available.
45 CVCV
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
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 Elementspecific reaction force measures available.
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.
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
Adams/Solver
C++ Functions
46
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 variablesize buffer
automatically.
Format
DELAY (e_delayed, e_delay, e_history [, id])
Arguments
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 t/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
e_delayed Adams expression to be delayed.
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.
R t t
l
/ t > ÷
47 DELAY
C++ Functions
are stored in the history of the expression. In the above expression, t is the current time, t
l
is the last point
in the stored history, and t 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 t /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.
Examples
1. A simple DDE system.
The equations below define a typical DDE system with a statedependent delay expression:
The expression to delay (e_delayed) is x
2
, the delay expression (e_delay) is t, 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)
2. A simple massspringdamper system.
Figure below shows a MATLAB model to study the dynamics of a simple massspringdamper
system governed by the following equation:
where the delay t is given by the following expression:
) 0 t ( 95 . 0 ) t ( x
0 x 3 x
) t ( x ) t ( x 3 ) t ( x
) t ( x 5 ) t ( x
2
2 1
2 1 2
2 1
< =
> ÷ =
÷ = '
÷ = '
t
t
t
mx
··
kx t t – ( ) cx
·
+ + 0 =
Adams/Solver
C++ Functions
48
and zero initial history ( x(t)=0 for t<0 ) and . System properties are m=1, k=30 and
c=2.
The corresponding Adams model is the following:
Simple springdamper 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
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
t 0.01 0.05 x
·
0.035 < + =
x
·
0 ( ) 1 =
49 DELAY
C++ Functions
!
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
!
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)
Adams/Solver
C++ Functions
50
!
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
and
sim/kin, end=2, step=20
stop
The results are presented in the figure below.
51 DELAY
C++ Functions
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
sim/kin, end=2, step=20
stop
The new solution is presented in figure below.
See other Miscellaneous Adams intrinsic functions available.
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 the last example.
Adams/Solver
C++ Functions
52
DIF
The DIF function returns the value of the state associated with DIFF/id.
Format
DIF(id)
Arguments
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)
his 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.
See other System element measures available.
id An integer variable that specifies the identifier of a DIFF statement.
53 DIF1
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
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.
See other System element measures available.
id An integer variable that specifies the identifier of a DIFF statement.
Adams/Solver
C++ Functions
54
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) =a1a2 if a1 > a2
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)
Caution: DIM is a discontinuous function and must be used with caution.
a1 Any valid function expression.
a2 Any valid function expression.
55 DM
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 nonnegative.
Format
DM(i[,j])
Arguments
Extended Definition
Mathematically, DM is calculated as follows:
where is the displacement of marker i in the global coordinate system and is the displacement of
marker j in the global coordinate system.
Examples
SFORCE/1, I=21, J=11, TRANSLATION
, 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.
See other Displacement measures available.
i The marker whose origin is being measured.
j The marker whose origin is the reference point for the displacement calculation.
DM R
i
R
j
–   R
i
R
j
–    =
R
i
R
j
Adams/Solver
C++ Functions
56
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 userdefined, algebraicallydetermined state variable whose value
is 30 degrees*time. The state variable is stored in radians.
See other Simulation parameters and constants available.
57 DX
C++ Functions
DX
The DX function returns the xcomponent 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
Extended Definition
Mathematically, DX is calculated as follows:
where:
• is the displacement of marker i in the global coordinate system.
• is the displacement of marker j in the global coordinate system.
• is the unit vector along the xaxis of marker k.
Examples
VARIABLE/1, FUNCTION=DX(21,11,32)**2
This VARIABLE statement specifies a userdefined, algebraicallydetermined state variable. Its value is
the square of the xdisplacement of Marker 21 with respect to Marker 11 as computed in the coordinate
system of Marker 32.
See other Displacement measures available.
i The marker whose origin is being measured.
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 xcomponent of the displacement vector. Set k =
0 if you want the results to be calculated along the xaxis of the global coordinate system.
DX R
i
R
j
–   x
ˆ
k
· =
R
i
R
j
x
ˆ
k
Adams/Solver
C++ Functions
58
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
Extended Definition
where:
• is the displacement of marker i with respect to the global origin.
• is the displacement of marker j with respect to the global origin.
• DX is theDX measure.
• DY is the DY measure.
• DZ is the DZ measure.
• is the unit vector along the xaxis of marker k.
• is the unit vector along the yaxis of marker k.
• is the unit vector along the zaxis of marker k.
i The marker whose origin is being measured.
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 k.
k The marker in whose coordinate system the displacement vector is being expressed. If not
specified, k defaults to the global coordinate system.
DXYZ
R
i
R
j
–   x
ˆ
k
·
R
i
R
j
–   y
ˆ
k
·
R
i
R
j
–   z
ˆ
k
·
¹ )
¦ ¦
´ `
¦ ¦
¦ ¹
DX
DY
DZ
¹ )
¦ ¦
´ `
¦ ¦
¦ ¹
= =
R
i
R
j
x
ˆ
k
y
ˆ
k
z
ˆ
k
59 DXYZ
C++ Functions
Examples
The following statement:
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).
See other Vector measures available.
Adams/Solver
C++ Functions
60
DY
The DY function returns the ycomponent 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 the global coordinate system if it is not
specified.
Format
DY(i[,j][,k])
Arguments
Extended Definition
Mathematically, DY is calculated as follows:
where:
• is the displacement of marker i in the global coordinate system.
• is the displacement of marker j in the global coordinate system.
• is the unit vector along the yaxis of marker k.
Examples
VARIABLE/1, FUNCTION=DY(21,11,32)**2
This VARIABLE statement specifies a userdefined, algebraicallydetermined state variable. Its value is
the square of the ydisplacement of Marker 21 with respect to Marker 11 as computed in the coordinate
system of Marker 32.
See other Displacement measures available.
i The marker whose origin is being measured.
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 k.
k The coordinates of the marker that are referenced to calculate coordinates the ycomponent of
the displacement vector is being calculated. Set k = 0 if you want the results to be calculated
along the yaxis of the global coordinate system.
DY R
i
R
j
–   y
ˆ
k
· =
R
i
R
j
y
ˆ
k
61 DZ
C++ Functions
DZ
The DZ function returns the zcomponent 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 the global coordinate system if it is not
specified.
Format
DZ(i[,j][,k])
Arguments
Extended Definition
Mathematically, DZ is calculated as follows:
where:
• is the displacement of marker i in the global coordinate system.
• is the displacement of marker j in the global coordinate system.
• is the unit vector along the zaxis of marker k.
Examples
VARIABLE/1, FUNCTION=DZ(21,11,32)**2
This VARIABLE statement specifies a userdefined, algebraicallydetermined state variable. Its value is
the square of the zdisplacement of Marker 21 with respect to Marker 11 as computed in the coordinate
system of Marker 32.
See other Displacement measures available.
i The marker whose origin is being measured.
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 in whose coordinates the zcomponent of the displacement vector is being
calculated. Set k = 0 if you want the results to be calculated along the zaxis of the global
coordinate system.
DZ R
i
R
j
–   z
ˆ
k
· =
R
i
R
j
z
ˆ
k
Adams/Solver
C++ Functions
62
EXP
The EXP function computes the value e
a
, 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:
e
WDTX(21,11,11,31)
where WDTX (21,11,11,31) is the xcomponent 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.
See other FORTRAN 77 intrinsic functions available.
a Any valid function expression.
Number of arguments: 1
63 FIELD
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
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 zcomponent 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.
See other Elementspecific applied force measures available.
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.
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 FIELD 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.
Adams/Solver
C++ Functions
64
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
Examples
VARIABLE/1, FUNCTION=FM(23)
A userdefined state variable is specified by this VARIABLE statement. Its value is the magnitude of the
sum of all actiononly forces acting at Marker 23.
VARIABLE/1, FUNCTION=FM(23,11)
A userdefined state variable is specified by this VARIABLE statement. Its value is the magnitude of the
sum of all the applied and constraint forces at Marker 23 and acting between Markers 23 and 11.
See other Generic force measures available.
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.
65 FORCOS
C++ Functions
FORCOS
The FORCOS function evaluates a Fourier Cosine series at a userspecified value x. The x
0
, a
0
, a
1
,...,a
30
are parameters used to define the constants for the Fourier Cosine series.
Format
FORCOS (x, x
0
, w, a
0
, a
1
,...,a
30
)
Arguments
Extended Definition
The Fourier Cosine series is defined:
where the function are defined as:
The index j has a range from 1 to n, where n is the number of terms in the series.
Examples
MOTION/1, JOINT=21, TRANSLATION,
, 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:
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.
x
0
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.
a
0
A real variable that defines the constant bias term for the function.
a
1
,...,a
30
The real variables that define as many as thirtyone coefficients for the Fourier Cosine
series.
F x ( ) a
o
a
j
T
j
x x
o
– ( ) +
j 1 =
n
¯
+ =
T
j
T
j
x x
o
– ( ) j e x x
o
– ( ) · · { } cos =
Adams/Solver
C++ Functions
66
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
See other Miscellaneous Adams intrinsic functions available.
67 FORSIN
C++ Functions
FORSIN
The FORSIN function evaluates a Fourier Sine series at a user specified value x. x
0
,a
0
,a
1
,...,a
30
are
parameters used to define the constants for the Fourier Sine series.
Format
FORSIN (x, x
0
,w,a
0
,a
1
,...,a
30
)
Arguments
Extended Definition
The Fourier Sine series is defined:
where the function are defined as:
The index j has a range from 1 to n, where n is the number of terms in the series.
Examples
MOTION/1, JOINT=21, TRANSLATION,
, 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:
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.
x
0
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.
a
0
A real variable that defines the constant bias term for the function.
a
1
,...,a
30
The real variables that define as many as thirtyone coefficients for the Fourier Sine
series.
e
F x ( ) a
o
a
j
T
j
x x
o
– ( ) +
j 1 =
n
¯
+ =
T
j
T
j
x x
o
– ( ) j e x x
o
– ( ) · · { } sin =
t
Adams/Solver
C++ Functions
68
FORSIN = 0+SIN( *(TIME+0.25))
+2*SIN(2 *(TIME+0.25))
+3*SIN(3 *(TIME+0.25))
The curve is shown next.
Curve of a Harmonic Motioned Defined by FORSIN
See other Miscellaneous Adams intrinsic functions available.
t
t
69 FRICTION
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
Friction Index
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.
Index: Name: Description:
1 FFX Friction force along the xaxis of the JOINT’s J marker
2 FFY Friction force along the yaxis of the JOINT’s J marker
3 FFZ Friction force along the zaxis of the JOINT’s J marker
4 FTX Friction torque about the xaxis of the JOINT’s J marker
5 FTY Friction torque about the yaxis of the JOINT’s J marker
6 FTZ Friction torque about the zaxis of the JOINT’s J marker
7 Friction coefficient along the xaxis of the JOINT’s J marker
8 Friction coefficient along the yaxis of the JOINT’s J marker
9 Friction coefficient along the zaxis of the JOINT’s J marker
10 Friction coefficient about the xaxis of the JOINT’s J marker
11 Friction coefficient about the yaxis of the JOINT’s J marker
12 Friction coefficient about the zaxis of the JOINT’s J marker
13 Effective friction coefficient at static friction (returns zero if sliding)
14 V
x
Joint velocity at sliding surfaces along the xaxis of the JOINT’s J marker
15 V
y
Joint velocity at sliding surfaces along the yaxis of the JOINT’s J marker
16 V
z
Joint velocity at sliding surfaces along zaxis of the JOINT’s J marker
17 W
x
Joint angular velocity about the xaxis of the JOINT’s J marker
18 W
y
Joint angular velocity about the yaxis of the JOINT’s J marker
19 W
z
Joint angular velocity about the zaxis of the JOINT’s J marker
u
x
u
y
u
z
u
rx
u
ry
u
rz
u
1
Adams/Solver
C++ Functions
70
Examples
Request/101
,F2=FRICTION (2,1)/, F3=FRICTION (2,2)/, F4=FRICTION (2,3)/
,F6=FRICTION (2,4)/, F7=FRICTION (2,5)/, F8=FRICTION (2,6)/
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
frictionforce vector resolved in the associated J marker coordinate system of the JOINT.
See other Elementspecific applied force measures available.
20 CREEP_X Static friction creep along the xaxis of the JOINT’s J marker
21 CREEP_Y Static friction creep along the yaxis of the JOINT’s J marker
22 CREEP_Z Static friction creep along the zaxis of the JOINT’s J marker
23 CREEP_RX Static friction creep about the xaxis of the JOINT’s J marker
24 CREEP_RY Static friction creep about the yaxis of the JOINT’s J marker
25 CREEP_RZ Static friction creep about the zaxis of the JOINT’s J marker
26 BETA Stiction transition factor
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.
71 FX
C++ Functions
FX
The FX measure returns the xcomponent 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
Examples
VARIABLE/1, FUNCTION=FX(23,0,432)
A userdefined state variable is specified by this VARIABLE statement. Its value is FX(23,0,432). This
is the xcomponent of the sum of all the actiononly forces acting at Marker 23 as computed in the
coordinate system of Marker 32.
See other Generic force measures available.
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.
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.
Adams/Solver
C++ Functions
72
FXFREQ
The FXFREQ function returns the modal frequency in cycles per userdefined time for 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
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(FXFREQ100:0.01,0.1,IF(FXFREQ1000: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.
73 FXMODE
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.
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.
See other Flexible body constants available.
Adams/Solver
C++ Functions
74
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
Extended Definition
Mathematically, FXYZ is calculated as:
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))
See other Vector measures available.
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.
k An integer that specifies the identifier of a marker (coordinate system) in which the xcomponent
of the force is to be returned. k defaults to the global coordinate system when it is not specified.
FXYZ i j , k , ( )
FX
FY
FZ
¹ )
¦ ¦
´ `
¦ ¦
¦ ¹
=
75 FY
C++ Functions
FY
The FY measure returns the ycomponent 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, 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
Examples
SFORCE/1, I=132, J=234, TRANSLATION, ACTIONONLY
, FUNCTION=0.3*FY(677,866)
This SFORCE statement defines a translation, actiononly force acting at Marker 132. The force is
directed along the zaxis of Marker 234. The value of the force is 0.3 times the ycomponent of the net
force along the global yaxis, acting at Marker 677. All forces acting between Markers 677 and 866 are
included in this calculation.
See other Generic force measures available.
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.
k An integer that specifies the identifier of a marker (coordinate system) in which the y
component of the force is to be returned. k defaults to the global coordinate system when it is
not specified.
Adams/Solver
C++ Functions
76
FZ
The FZ measure returns the zcomponent 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, 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
Examples
SFORCE/1, I=23, J=11, TRANSLATION, ACTIONONLY
, FUNCTION=STEP5(FZ(34), 1.5, 200, 1.5, 200)
This SFORCE statement defines a translational, actiononly, nonlinear force. The force is directed along
the zaxis 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 zaxis at Marker 34. Since
no j marker is specified, only actiononly forces acting at Marker 34 are included in the calculation of
FZ().
See other Generic force measures available.
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.
k An integer that specifies the identifier of a marker (coordinate system) in which the zcomponent
of the force is to be returned. k defaults to the global coordinate system when it is not specified.
77 GFORCE
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
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, zaxes of Marker 23.
The xcomponent of the force is 0.3 times the zcomponent of the force.
The zcomponent 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.
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.
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 GFORCE 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.
Adams/Solver
C++ Functions
78
See other Elementspecific applied force measures available.
79 HAVSIN
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, x
0
, h
0
, x
1
, h
1
)
Arguments
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 = (h
0
+ h
1
)/2
b = (h
1
 h
0
)/2
c = (x  x
0
)/(x
1
 x
0
)
x The independent variable.
x
0
A real variable that specifies the x value at which the haversine function begins.
x
1
A real variable that specifies the x value at which the haversine function ends.
h
0
The initial value of the haversine function.
h
1
The final value of the haversine function.
Adams/Solver
C++ Functions
80
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.
See other Miscellaneous Adams intrinsic functions available.
BISTOP
h
0
: x x
0
s ( )
a b c t t 2 – · ( ) sin · + : x
o
x x
1
< <
h
1
: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.
81 HSIZE
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=1e4
, ERR=1e5
, 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 1e4. Note that a STEP
function is used to delay the sensor to avoid the startup condition of a step size0.0, and to accommodate
HMIN and allow the integrator to start.
See other Simulation parameters and constants available.
Adams/Solver
C++ Functions
82
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.
The arithmetic IF function allows you to conditionally define a function expression.
Format
IF (test : lt, eq, gt)
Arguments
Examples
SFORCE/1, I=20, J=31,
, FUNCTION=6*IF(VR(10,31): 0, 0, VR(10,31)**3)
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 expression is not evaluated.
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 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 (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.
83 IF
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.
Adams/Solver
C++ Functions
84
IMPACT
The IMPACT function models collisions.
Format
IMPACT (x, , x
1
, k, e, c
max
, d)
Arguments
Extended Definition
The IMPACT function activates when the distance between the I and J markers falls below a nominal
free length (x
1
), that is, when two parts collide. As long as the distance between the I and J markers is
greater than x
1
; 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 x
1
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 freelength 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, c
max
, at a user
defined penetration, d.
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).
Expression that specifies the time derivative of x to IMPACT. For example, if x is
DX(0201,0301), then is VX(0201,0301,0,0301).
x
1
Positive real variable that specifies the free length of x. If x is less than x
1
, then
Adams/Solver (C++) calculates a positive value for the force. Otherwise, the force value is
zero. You can define x
1
as a real number, function, or variable.
k Nonnegative 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 stiffening spring characteristic, e > 1.0. For a softening spring characteristic, 0 < e < 1.0.
c
max
Nonnegative 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.
x
·
x
·
x
·
85 IMPACT
C++ Functions
Figure 3 Example Illustrating the IMPACT Function
The equation defining IMPACT is:
Note that when:
• x > x
1
, no penetration occurs and the force is zero (penetration p = 0)
• x < x
1
, penetration occurs at the end closer to the J marker, and the force is > 0 (penetration p =
x
1
 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 c
max
.
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.
IMPACT
Max 0 k x
1
x – ( )
e
STEP x x
1
d c
max
x
1
0 . . . – . ( ) x
·
· – . ( ) : x x
1
<
0 : x x
1
>
¹ )
´ `
¦ ¹
=
Adams/Solver
C++ Functions
86
Figure 4 Damping Coefficient versus Penetration
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:
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.
F
n
k* (g**e) =
87 IMPACT
C++ Functions
Examples
SFORCE/1, I=11, J=21, TRANSLATION, ACTIONONLY
, 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 singlecomponent force at Marker 11 and along the zaxis of Marker 21. DZ(11,21,21) defines the
instantaneous displacement of Marker 11 with respect to Marker 21 along the zaxis 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), 1AKISPL(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 ycomponent of the instantaneous
displacement of Marker 4 with respect to Marker 1. The VY(4,1,1) defines the ycomponent 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 zcomponents 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.
See other Miscellaneous Adams intrinsic functions available.
Adams/Solver
C++ Functions
88
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.
Format
INCANG (i, j, k)
Arguments
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.
See other Displacement measures available.
Note: During the simulation, the first nonzero value is always positive.
i A marker on the first line.
j A marker on the first line.
k A marker on the second line.
89 INTERP
C++ Functions
INTERP
The INTERP function returns the iord derivative of the interpolated value of SPLINE/id at time=x. The
INTERP function supports timeseries 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
Extended Definition
The INTERP function uses a BSpline 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.
x A real variable that specifies the value of time, the independent variable along the xaxis 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
id An integer variable that specifies the identifier of a SPLINE statement that you define in the
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
Adams/Solver
C++ Functions
90
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.
Examples
SPLINE/101
,FILE=test_data.rsp
,CHANNEL=9
SFORCE/1, I=409, J=109, TRANSLATION
,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.
See other Interpolation functions available.
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.
91 INVPSD
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
Extended Definition
Mathematically, INVPSD is calculated as follows:
The regenerated signal consists of a series of sinusoidal functions where the amplitudes, A
i
, are
determined in such a way that the effective value for the PSD and the time signal are the same. The phase
angle, , is calculated by a pseudorandom number generator.
Using the same seed value will always result in the same set of phase angles.
x The independent variable.
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. During a simulation, PSD can be called with up to a maximum of 20 different
seeds.
INVPSD A
i
2tf
i
x m
i
+ · ( ) sin · ( )
i 1 =
n
f
¯
=
m
i
0 m
i
2t s s ( )
Adams/Solver
C++ Functions
92
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 LogLog Scale
Figure 6 Regenerated Time Signal
See other Miscellaneous Adams intrinsic functions available.
93 JOINT
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
Examples
JOINT/1, REVOLUTE, I=46, J=23
SFORCE/1, ROTATION, I=46, J=23
, 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 zaxis 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).
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.
0 = forces and moments at the I marker
1 = forces and moments at the J marker
comp An integer value that specifies the component of the joint 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.
Adams/Solver
C++ Functions
94
See other Elementspecific reaction force measures available.
95 JPRIM
C++ Functions
JPRIM
The JPRIM function returns component comp of a force due to JPRIM/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 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
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.
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.
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 JPRIM 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.
Adams/Solver
C++ Functions
96
See other Elementspecific reaction force measures available.
97 LOG
C++ Functions
LOG
The LOG function returns the natural logarithm an expression a. If e
x
=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))
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).
See other FORTRAN 77 intrinsic functions available.
a Any valid function expression that returns a positive value during a simulation.
Number of Arguments: 1
Adams/Solver
C++ Functions
98
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))
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).
See other FORTRAN 77 intrinsic functions available.
a Any valid function expression that returns a positive value during a simulation.
Number of Arguments: 1
99 MAG
C++ Functions
MAG
The MAG function returns the magnitude of an arbitrary vector function expression.
Format
MAG(exp)
Arguments
Extended Definition
Mathematically, MAG is calculated as:
where 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.
exp An arbitrary vector function expression.
MAG exp ( ) exp exp · =
exp
Adams/Solver
C++ Functions
100
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
Examples
SFORCE/1, ROTATIONAL, ACTIONONLY, I=21, J=11
, FUNCTION=MAX(0,3*(AZ(21,11)25D))
This SFORCE statement defines an actiononly torque that acts at Marker 21 and acts along the zaxis of
Marker 11. The torque is defined to always be nonnegative 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).
See other FORTRAN 77 intrinsic functions available.
a1 Any valid function expression.
a2 Any valid function expression.
Caution: The MAX function is generally discontinuous. Use this function expression with care when
you are specifying force or motion input.
101 MIN
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
Examples
SFORCE/1, ROTATIONAL, ACTIONONLY, I=21, J=11
, FUNCTION=MIN(0,3*(AZ(21,11)25D))
This SFORCE statement defines an actiononly torque that acts at Marker 21 and acts along the zaxis of
Marker 11. The torque is defined to always be negative through the use of the MIN function. Thus, the
torque can only act to decrease the AZ rotation of Marker 21 with respect to Marker 11 (see AZ).
See other FORTRAN 77 intrinsic functions available.
a1 Any valid function expression.
a2 Any valid function expression.
Caution: The MIN function is generally discontinuous. Use this function expression with care when
you are specifying force or motion input.
Adams/Solver
C++ Functions
102
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
Examples
MOD(45,16)=13
See other FORTRAN 77 intrinsic functions available.
a1 Any valid function expression.
a2 Any valid nonzero function expression.
Caution: The MOD function is generally discontinuous. Use this function expression with care when
you are specifying force or motion input.
103 MODE
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 = Quasistatics
7 = Linear analysis
Format
MODE
Examples
SFORCE/1, TRANSLATION, I=21, J=11
, FUNCTION=IF(MODE4:0,0,4*(DM(21,11)10.6)
This example defines a translational force that is active only during statics, quasistatic, 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.
See other Simulation parameters and constants available.
Caution: Use the MODE function with care if you use the STATICS argument on the SIMULATE
command to request a static or quasistatic 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).
Adams/Solver
C++ Functions
104
MOTION
The MOTION function returns component comp of a force due to MOTION/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 MOTION. 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
MOTION (id, jflag, comp, rm)
Arguments
Examples
JOINT/34, REVOLUTE, I=21, J=11
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.
See other Elementspecific reaction force measures available.
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.
0 = forces and moments at the I marker
1 = forces and moments at the J marker
comp An integer value that specifies the component of the motion 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.
105 NJAC
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
See other Simulation parameters and constants available.
Adams/Solver
C++ Functions
106
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
See other Simulation parameters and constants available.
107 ORDER
C++ Functions
ORDER
The current order of a variableorder integrator.
Example
!
! adams_view_name='FUNCTION_MEA_ORDER'
VARIABLE/2
, FUNCTION = ORDER
See other Simulation parameters and constants available.
Adams/Solver
C++ Functions
108
PHI
The PHI function calculates the third angle (in radians) of a bodyfixed313 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 bodyfixed313 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.
See other Displacement measures available.
Figure 7 Bodyfixed313 Euler Angles
i The marker whose rotations are being sought.
j The marker with respect to which the rotations are being measured.
109 PHI
C++ Functions
The bodyfixed313 sequence is started by rotating
counterclockwise the initial system of axes, xyz, by
an angle about the zaxis. 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'.)
+
cn. .
cn.
c
u
c' n' .' c'
c' n'
c c'
c – ' n – ' . – '
o .
.'
Adams/Solver
C++ Functions
110
PI
PI returns the ratio of the circumference of a circle to its diameter (3.14159...).
Format
PI
See other Simulation parameters and constants available.
111 PINVAL
C++ Functions
PINVAL
The PINVAL function returns component comp of PINPUT/id.
Format
PINVAL (id, comp)
Arguments
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).
See other System element measures available.
id The identifier of the PINPUT whose data is being requested.
comp An integer that specifies the component of the PINPUT to be returned.
Adams/Solver
C++ Functions
112
PITCH
Calculates the second angle of a bodyfixed 3 2 1 yawpitchroll rotation sequence between marker i and
j. Marker j defaults to the global coordinate system if it is not specified. Note that pitch is an Euler angle.
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.
See other Displacement measures available.
i The marker whose rotations are being sought.
j The marker with respect to which the rotations are being measured.
113 POLY
C++ Functions
POLY
The POLY function evaluates a standard polynomial at a userspecified value x.
Format
POLY (x, x
0
, a
0
, a
1
,..., a
30
)
Arguments
Extended Definition
The POLY function evaluates a standard polynomial at a userspecified value x. x
0
, a
0
, a
1
,..., a
30
are
parameters used to define the constants for the polynomial. The standard polynomial is defined as:
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
MOTION/1, JOINT=21, TRANSLATION
, FUNCTION = IF(TIME5: 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*time5
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.
x
0
A real variable that specifies a shift in the polynomial.
a
0
, a
1
,..., a
30
The real variables that define as many as thirtyone coefficients for the polynomial
series.
P x ( ) a
j
x x
o
– ( )j
j 0 =
n
¯
=
a
o
a
1
x x
o
– ( ) a
2
x x
o
– ( )
2
. · a
n
x x
o
– ( )
n
· + + · + =
Adams/Solver
C++ Functions
114
SFORCE/3, I=10, J=20, TRANSLATION
, 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.
See other Miscellaneous Adams intrinsic functions available.
115 POUVAL
C++ Functions
POUVAL
The POUVAL function returns component comp of POUTPUT/id.
Format
POUVAL (id, comp)
Arguments
Examples
VARIABLE/21, FUNCTION=10*SIN(2.4*TIME)+3.5
VARIABLE/22, FUNCTION=DZ(21,11,32)
POUTPUT/10, VARIABLES=21,22
SFORCE/1, TRANSLATIONAL, I=62, J=47
, FUNCTION=1.08*(POUVAL(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. POUVAL(10,2) is the second element in the VARIABLES list for POUTPUT/10 (that is,
VARIABLE/22).
See other System element measures available.
id The identifier of the POUTPUT whose data is being requested.
comp An integer that specifies the component of the POUTPUT to be returned.
Adams/Solver
C++ Functions
116
PSI
The PSI function expression calculates the first angle (in radians) of a bodyfixed313 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 bodyfixed313 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.
See other Displacement measures available.
i The marker whose rotations are being sought.
j The marker with respect to which the rotations are being measured.
117 PTCV
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 the results are desired in the global coordinate system.
Format
PTCV (id, jflag, comp, rm)
Arguments
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 zcomponents 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.
See other Elementspecific reaction force measures available.
id An integer specifying the identification number of the pointtocurve constraint.
jflag An integer flag specifying the pointtocurve 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 pointtocurve constraint 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.
Adams/Solver
C++ Functions
118
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
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.
id The identifier of the FLEX_BODY.
mode_number The mode whose modal coordinate data is requested.
119 QDDOT
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 corresponding to mode number 10 on FLEX_BODY/5, is defined.
id The identifier of the FLEX_BODY.
mode_number The mode whose modal coordinate data is requested.
Adams/Solver
C++ Functions
120
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 corresponding to mode number 10 on FLEX_BODY/5, is defined.
id The identifier of the FLEX_BODY.
mode_number The mode whose modal coordinate data is requested.
121 ROLL
C++ Functions
ROLL
The ROLL function calculates the third angle of a bodyfixed 3 2 1 yawpitchroll 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.
See other Displacement measures available.
i The marker whose rotations are being sought.
j The marker with respect to which the rotations are being measured.
Adams/Solver
C++ Functions
122
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.
See other Simulation parameters and constants available.
123 SENVAL
C++ Functions
SENVAL
The SENVAL function returns the last scored value from the function expression or userwritten
subroutine associated with the EVALUATE argument on SENSOR/id. See the SENSOR statement for
more information.
Format
SENVAL(id)
Arguments
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.
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.
t
Adams/Solver
C++ Functions
124
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
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)
This REQUEST statement outputs the x, y and zcomponents of the force and torque at the I marker of
SFORCE/31. Since rm is specified as zero, all vectors are expressed in the global coordinate system.
See other Elementspecific applied force measures available.
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.
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 SFORCE 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.
Set rm = 0 if you want to return the results in the global coordinate system.
125 SHF
C++ Functions
SHF
The SHF function evaluates a simple harmonic function. The following equation defines SHF:
SHF = a*sin( *(xx
0
)phi)+b
Format
SHF (x, x
0
, a, w, phi, b)
Arguments
Examples
MOTION/1, JOINT=21, TRANSLATION
, FUNCTION=SHF(TIME, 25D, PI, 360D, 0, 5)
This MOTION statement uses SHF to define the harmonic function:
SHF = 5+PI*sin(360D*(time25D))
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.
See other Miscellaneous Adams intrinsic functions available.
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.
x
0
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.
e
e e
e
Adams/Solver
C++ Functions
126
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
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).
See other FORTRAN 77 intrinsic functions available.
a1 Any valid function expression.
a2 Any valid function expression.
Caution: The SIGN function is discontinuous. Use this function with care to avoid creating
expressions that are discontinuous.
127 SIN
C++ Functions
SIN
The SIN function returns the sine of an expression a.
Format
SIN(a)
Arguments
Examples
SFORCE/1, TRANSLATION, I=23, J=34
, 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).
See other FORTRAN 77 intrinsic functions available.
a Any valid function expression.
Number of Arguments: 1
Adams/Solver
C++ Functions
128
SINH
The SINH function return the hyperbolic sine of an expression a.
SINH(a) = (e
a
 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 xcomponent of the displacement between
Markers 21 and 32, as calculated in the global coordinate system.
See other FORTRAN 77 intrinsic functions available.
a Any valid function expression.
Number of Arguments: 1
129 SPDP
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
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 zcomponents 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.
See other Elementspecific applied force measures available.
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.
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 SPDP 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.
Set rm = 0 if you want to return the results in the global coordinate system.
Adams/Solver
C++ Functions
130
SQRT
The SQRT function returns the square root of an expression a. The square root function is defined only
for nonnegative 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.
See other FORTRAN 77 intrinsic functions available.
a Any valid function expression.
Number of Arguments: 1
131 STEP
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=x
0
and x=x
1
.
Format
STEP (x, x
0
, h
0
, x
1
, h
1
)
Arguments
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:
x The independent variable. It can be a function expression.
x
0
A real variable that specifies the x value at which the STEP function begins.
x
1
A real variable that specifies the x value at which the STEP function ends.
h
0
The initial value of the step.
h
1
The final value of the step.
a h
1
h
0
– =
A x x
0
– ( ) x
1
x
0
– ( ) =
Adams/Solver
C++ Functions
132
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.
STEP
h
0
: x x
0
s
h
0
a A
2
3 2A – ( ) · + : x
0
x x
1
< <
h
1
: x x
1
>
¹ )
¦ ¦
´ `
¦ ¦
¦ ¹
=
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.
133 STEP
C++ Functions
First Derivatives of STEP, STEP5, HAVSIN, and TANH
Examples
MOTION/1, JOINT=21, VELOCITY
, 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.
See other Miscellaneous Adams intrinsic functions available.
Adams/Solver
C++ Functions
134
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=x
0
and x=x
1
.
Format
STEP5 (x, x
0
, h
0
, x
1
, h
1
)
Arguments
Extended Definition
The figure shown next illustrates the STEP5 function.
STEP5 Function
The equation defining the STEP5 function is:
x The independent variable.
x
0
A real variable that specifies the x value at which the STEP5 function begins.
x
1
A real variable that specifies the x value at which the STEP5 function ends.
h
0
The initial value of the step.
h
1
The final value of the step.
o h
1
h
0
– =
A x x
0
– ( ) x
1
x
0
– ( ) =
135 STEP5
C++ Functions
Examples
MOTION/1, JOINT=21, TRANSLATION
, 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.
See other Miscellaneous Adams intrinsic functions available.
STEP5
h
0
: x x
0
s
h
0
a A
3
10 15A – 6A
2
+   · + : x
0
x x
1
< <
h
1
: x x
1
>
¹ )
¦ ¦
´ `
¦ ¦
¦ ¹
=
Adams/Solver
C++ Functions
136
SWEEP
The SWEEP function returns a constant amplitude sinusoidal function with linearly increasing
frequency.
Format
SWEEP (x, a, x
0
, f
0
, x
1
, f
1
, dx)
Arguments
Extended Definition
Mathematically, SWEEP is calculated as follows:
where:
x The independent variable.
a The amplitude of the sinusoidal function.
x
0
The value of the independent variable at which the SWEEP function begins.
f
0
The initial frequency of the sinusoidal function.
x
1
The value of the independent variable value at which the SWEEP function ends
f
1
The final frequency.
dx The interval in which the SWEEP function becomes fully active.
SWEEP STEP5 x x
0
f
0
dx f
1
. . . . ( ) a 2t freq x ( ) x d
í
· ( ) sin · · =
freq x ( )
f
0
: x x
0
<
f
0
f
1
f
2
–
x
0
x
1
+

\ .
 
x · + : x
0
x x
1
< <
f
1
: x
1
x <
¹ )
¦ ¦
¦ ¦
´ `
¦ ¦
¦ ¦
¦ ¹
=
137 SWEEP
C++ Functions
The figure below illustrates the SWEEP function.
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.
f
í
req x ( )dx
f
0
x · : x x
0
<
f
0
x x
0
– ( )
f
1
f
0
– ( )
2 x
1
x
0
– ( )
 x x
0
– ( )
2
f
0
x
0
· + + · : x
0
x x
1
< <
f
1
x x
1
– ( ) f
0
x
0
f
0
x
1
x
0
– ( )
f
1
f
0
– ( )
2 x
1
x
0
– ( )
 x
1
x
0
– ( )
2
+ · + · + · : x x
0
<
¹ )
¦ ¦
¦ ¦
¦ ¦
´ `
¦ ¦
¦ ¦
¦ ¦
¦ ¹
=
Adams/Solver
C++ Functions
138
MOTION/1,JOINT=1
, FUNCTION=SWEEP(TIME, 1.0, 0.0, 2.0, 5.0, 6.0, 0.01)
See other Miscellaneous Adams intrinsic functions available.
139 TAN
C++ Functions
TAN
The TAN function returns the tangent of an expression a.
Format
TAN(a)
Arguments
Examples
SFORCE/1, TRANSLATION, I=23, J=34
, FUNCTION=TAN(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 TAN(10*TIME).
See other FORTRAN 77 intrinsic functions available.
a Any valid function expression.
Number of arguments: 1
Adams/Solver
C++ Functions
140
TANH
The TANH function returns the hyperbolic tangent of an expression a.
TANH(a) = (e
a
 e
a
) / (e
a
+ e
a
)
Format
TANH(a)
Arguments
Extended Definition
The figure below illustrates the TANH function.
TANH Function
Example
MOTION/1, JOINT=21, TRANSLATION
, FUNCTION=0.5(1+TANH(5*(TIME1.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.
See other FORTRAN 77 intrinsic functions available.
a Any valid function expression.
Number of arguments: 1
141 THETA
C++ Functions
THETA
The THETA function calculates the second angle (in radians) of a bodyfixed313 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 bodyfixed313 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.
See other Displacement measures available.
i The marker whose rotations are being sought.
j The marker with respect to which the rotations are being measured.
Adams/Solver
C++ Functions
142
TIME
The TIME variable returns the current simulation time.
Format
TIME
Examples
SFORCE/1, TRANSLATION, I=21, J=32
, 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).
See other Simulation parameters and constants available.
143 TM
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
Examples
JOINT/1, REVOLUTE, I=32, J=44
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.
See other Generic force measures available.
i An integer that specifies the identifier of the marker at which the magnitude of the net torque
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.
Adams/Solver
C++ Functions
144
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
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.
See other Vector functions available.
exp An arbitrary vector function expression.
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.
145 TX
C++ Functions
TX
The TX measure returns the xcomponent 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
Examples
JOINT/1, REVOLUTE, I=32, J=44
MOTION/1, ROTATION, JOINT=1, FUNCTION=10*TIME
VARIABLE/31, FUNCTION=TX(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 xcomponent 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().
See other Generic force measures available.
i An integer that specifies the identifier of the marker at which the magnitude of the net torque 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.
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.
Adams/Solver
C++ Functions
146
TXYZ
The TXYZ measure returns the net translational torque 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 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
Extended Definition
Mathematically, TXYZ is calculated as:
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 xaxis of marker 4.
VARIABLE/1, FUN=TXYZ(5)*UVX(4)
which is alternatively available as TX(5,0,4).
i An integer that specifies the identifier of the marker at which the magnitude of the net torque 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.
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.
TXYZ i j k , , ( )
TX
TY
TZ
¹ )
¦ ¦
´ `
¦ ¦
¦ ¹
=
147 TXYZ
C++ Functions
See other Vector measures available.
Adams/Solver
C++ Functions
148
TY
The TY measure returns the ycomponent 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, TY 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
TY(i[,j][,k])
Arguments
Examples
JOINT/1, REVOLUTE, I=32, J=44
MOTION/1, ROTATION, JOINT=1, FUNCTION=10*TIME
VARIABLE/31, FUNCTION=TY(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 ycomponent 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().
See other Generic force measures available.
i An integer that specifies the identifier of the marker at which the magnitude of the net torque
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.
k An integer that specifies the identifier of a marker (coordinate system) in which the y
component of the torque is to be returned. k defaults to the global coordinate system when it is
not specified.
149 TZ
C++ Functions
TZ
The TZ measure returns the zcomponent 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, TZ 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
TZ(i[,j][,k])
Arguments
Examples
JOINT/1, REVOLUTE, I=32, J=44
MOTION/1, ROTATION, JOINT=1, FUNCTION=10*TIME
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 zcomponent 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( ).
See other Generic force measures available.
i An integer that specifies the identifier of the marker at which the magnitude of the net torque 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.
k An integer that specifies the identifier of a marker (coordinate system) in which the z
component of the torque is to be returned. k defaults to the global coordinate system when it is
not specified.
Adams/Solver
C++ Functions
150
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:
where 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.
See other Vector functions available.
exp An arbitrary vector function expression.
UV exp ( )
exp
exp exp ·
 =
exp
151 UVX
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
Extended Definition
Mathematically, UVX is calculated as:
where:
• is the unit vector along the xaxis of marker i.
• is the unit vector along the xaxis of marker k.
• is the unit vector along the yaxis of marker k.
• is the unit vector along the zaxis of marker k.
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 xaxis of marker k.
See other Vector measures available.
i The marker whose xaxis 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.
UVX i k . ( )
x
ˆ
i
x
ˆ
k
·
x
ˆ
i
y
ˆ
k
·
x
ˆ
i
z
ˆ
k
·
¹ )
¦ ¦
´ `
¦ ¦
¦ ¹
=
x
ˆ
i
x
ˆ
k
y
ˆ
k
z
ˆ
k
Adams/Solver
C++ Functions
152
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
Extended Definition
Mathematically, UVY is calculated as:
where:
• is the unit vector along the yaxis of marker i.
• is the unit vector along the xaxis of marker k.
• is the unit vector along the yaxis of marker k.
• is the unit vector along the zaxis of marker k.
Examples
VARIABLE/1, FUN=DXYZ(i,j)*UVY(k)
VARIABLE/2, FUN=DY(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 yaxis of marker k.
See other Vector measures available.
i The marker whose yaxis 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.
UVY i k . ( )
y
ˆ
i
x
ˆ
k
·
y
ˆ
i
y
ˆ
k
·
y
ˆ
i
z
ˆ
k
·
¹ )
¦ ¦
´ `
¦ ¦
¦ ¹
=
y
ˆ
i
x
ˆ
i
y
ˆ
k
z
ˆ
k
153 UVZ
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
Extended Definition
Mathematically, UVZ is calculated as:
where:
• is the unit vector along the zaxis of marker i.
• is the unit vector along the xaxis of marker k.
• is the unit vector along the yaxis of marker k.
• is the unit vector along the zaxis of marker k.
Examples
VARIABLE/1, FUN=DXYZ(i,j)*UVZ(k)
VARIABLE/2, FUN=DZ(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 zaxis of marker k.
See other Vector measures available.
i The marker whose zaxis 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.
UVZ i k . ( )
z
ˆ
i
x
ˆ
k
·
z
ˆ
i
y
ˆ
k
·
z
ˆ
i
z
ˆ
k
·
¹ )
¦ ¦
´ `
¦ ¦
¦ ¹
=
z
ˆ
i
x
ˆ
k
y
ˆ
k
z
ˆ
k
Adams/Solver
C++ Functions
154
VARVAL
The VARVAL function returns current value of VARIABLE/id.
Format
VARVAL (id)
Arguments
Examples
VARIABLE/10, FUNCTION=DX(21,32,43)
SFORCE/20, TRANSLATION, I=346, J=567
, FUNCTION=(VARVAL(10)5)**2
In this example, VARIABLE/10 defines an algebraically determined userspecified state. SFORCE/20 is
a nonlinear translational spring whose force magnitude is a function of this variable.
See other System element measures available.
id The identifier of the VARIABLE whose data is being requested.
155 VFORCE
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
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 xcomponent of the force exerted by VFORCE/19 calculated in
the coordinate system of Marker 168.
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.
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 VFORCE that is 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.
Set rm = 0 if you want to return the results in the global coordinate system.
Adams/Solver
C++ Functions
156
See other Elementspecific applied force measures available.
157 VM
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
Extended Definition
Mathematically, VM is calculated as follows:
where is the displacement of marker i in ground and 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 userstate 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, userdefined 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.
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).
VM i j l . . ( )
t d
d
Ri
l ( )
t d
d
Rj
l ( )
–
t d
d
Ri
l ( )
t d
d
Rj
l ( )
– · =
Ri Rj
Adams/Solver
C++ Functions
158
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
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:
where:
• is the displacement of marker i with respect to the global origin.
• is the displacement of marker j with respect to the global origin.
As markers i and j separate from each other, VR is positive. VR is negative when markers i and j approach
each other.
Examples
SFORCE/1, TRANSLATION, I=467, J=764
, FUNCTION=10*VR(467,764)
This SFORCE statement defines a translational damper with a damping constant of 10.
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).
VR i j l . . ( )
t d
d
Ri
l ( )
t d
d
Rj
l ( )
– Ri Rj –   ·
Ri Rj –   Ri Rj –   ·
 VXYZ UV DXYZ ( ) · = =
Ri
Rj
159 VR
C++ Functions
See other Velocity measures available.
Adams/Solver
C++ Functions
160
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
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
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 xcomponent of the torque exerted by VTORQUE/19 calculated
in the coordinate system of Marker 168.
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.
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 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)
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.
Set rm = 0 if you want the results returned in the global coordinate system.
161 VTORQ
C++ Functions
See other Elementspecific applied force measures available.
Adams/Solver
C++ Functions
162
VX
The VX function returns the xcomponent 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
Extended Definition
Mathematically, VX is calculated as follows:
where:
• is the displacement of marker i in ground.
• is the displacement of marker j in ground.
• is the unit vector along the xaxis of marker k.
• denotes time differentiation in the reference frame of the l marker.
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.
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 xaxis 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).
Vx i j k , l . . ( )
t d
d
Ri
l ( )
t d
d
Rj
l ( )
– x
ˆ
k
· =
Ri
Rj
x
ˆ
k
t d
d
l ( )
163 VX
C++ Functions
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/236, I=236, JFLOAT=169
,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.
See other Velocity measures available.
Adams/Solver
C++ Functions
164
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
Extended Definition
Mathematically, VXYZ is calculated as follows:
where:
• is the displacement of marker i in ground.
• is the displacement of marker j in ground.
• VX is the VX measure.
• VY is the VY measure.
• VZ is the VZ measure.
i The marker whose origin is being measured.
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 firsttime 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.
VXYZ i j , k , l , ( )
t d
d
Ri
l ( )
t d
d
Rj
l ( )
– x
ˆ
k
·
t d
d
Ri
l ( )
t d
d
Rj
l ( )
– y
ˆ
k
·
t d
d
Ri
l ( )
t d
d
Rj
l ( )
– z
ˆ
k
·
¹ )
¦ ¦
¦ ¦
¦ ¦
´ `
¦ ¦
¦ ¦
¦ ¦
¦ ¹
VX
VY
VZ
¹ )
¦ ¦
´ `
¦ ¦
¦ ¹
= =
Ri
Rj
165 VXYZ
C++ Functions
• denotes time differentiation in the reference frame of the l marker.
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)
See other Vector measures available.
t d
d
l ( )
Adams/Solver
C++ Functions
166
VY
The VY function returns the ycomponent 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
VY(i[,j][,k][,l])
Arguments
Extended Defintion
Mathematically, VY is calculated as follows:
where:
• is the displacement of marker i in ground.
• is the displacement of marker j in ground.
• is the unit vector along the yaxis of marker k.
• denotes time differentiation in the reference frame of the l marker.
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
i, if you want j to default to the global coordinate system.
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 yaxis 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).
VY i j , k , l , ( )
t d
d
Ri
l ( )
t d
d
Rj
l ( )
– y
ˆ
k
· =
Ri
Rj
y
ˆ
k
t d
d
l ( )
167 VY
C++ Functions
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/236, I=236, JFLOAT=169
,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.
See other Velocity measures available.
Adams/Solver
C++ Functions
168
VZ
The VZ function returns the zcomponent 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
VZ(i[,j][,k][,l])
Arguments
Extended Definition
Mathematically, VZ is calculated as follows:
where:
• is the displacement of marker i in ground.
• is the displacement of marker j in ground.
• is the unit vector along the zaxis of marker k.
• denotes time differentiation in the reference frame of the l marker.
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.
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 zaxis 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).
VZ i j , k , l , ( )
t d
d
Ri
l ( )
t d
d
Rj
l ( )
– z
ˆ
k
· =
Ri
Rj
z
ˆ
k
t d
d
l ( )
169 VZ
C++ Functions
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/236, I=236, JFLOAT=169
,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.
See other Velocity measures available.
Adams/Solver
C++ Functions
170
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
Extended Definition
Mathematically, WDTM is calculated as follows:
where:
• is the angular velocity vector of marker i in ground.
• 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.
See other Acceleration measures available.
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 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.
WDTM i j , l . ( )
t d
d
ei
l ( )
t d
d
ej
l ( )
–
t d
d
ei
l ( )
t d
d
ej
l ( )
– · =
ei
ej
171 WDTX
C++ Functions
WDTX
The WDTX function returns the xcomponent 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
Extended Definition
Mathematically, WDTX is calculated as follows:
where:
• is the angular velocity vector of marker i in ground.
• is the angular velocity vector of marker j in ground.
• is the unit vector along the xaxis of marker k.
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)/
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 i, 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 i, if you want the results to be calculated along the xaxis 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).
WDTX i j k , l , , ( )
t d
d
ei
l ( )
t d
d
ej
l ( )
– x
ˆ
k
· =
ei
ej
x
ˆ
k
Adams/Solver
C++ Functions
172
,F3=WDTY(1236,2169,2169,2169)/
,F4=WDTZ(1236,2169,2169,2169)
In its second column REQUEST/16 contains the xcomponent 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.
See other Acceleration measures available.
173 WDTXYZ
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
Extended Definition
Mathematica