About Adams/Solver
2 Adams/Solver
Conventions
Throughout the help, the following type styles are used as visual cues.
Style:
Name
Indicates:
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
PART
{}
[]
[[ ]]
Two-dimensional matrices
One-dimensional matrices
R1
x
Vectors
Unit vectors
About Adams/Solver
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.
4 Adams/Solver
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,
Joints
Avoid using FIXED joints. A FIXED joint adds equations to your system that arent 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
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 center-of-mass (cm) of the lightest part, to minimize
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 theyre 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.
Dont 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 --^
About Adams/Solver
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 theyre 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.
15-20 static iterations is suspect.
If GSTIFF won't start, its most likely a problem with initial conditions.
Don't let the integrator step over important events. Short duration events like an impulse can be
captured by setting maximum time step, HMAX, to value less than impulse width.
Use HMAX so that Adams/Solver acts as a fixed-step integrator.
Spikes in results output may come from changes in step size. Reduce HMAX or try setting
(Euler singularity). If the z-axis of part cm is parallel to z-axis of ground, there will be a Euler
singularity.
For Euler Singularities, Theta=90D will have good pivots. Models will run better, and won't act
of GSTIFF says 2-3 iterations is desirable; it breaks down if it uses more than 4 or 5.
Debugging
Try to understand mechanism from a physical standpoint.
6 Adams/Solver
Use building blocks of concepts that worked in the past. Add enhancements to the model using
crawl-walk-run approach.
Test with a small model to isolate problems.
Have graphics for visualizing motion.
Look at damping terms as a source of errors. Incorrect sign and missing terms are typical
mistakes.
Turn on DEBUG/EPRINT.
Turn gravity off, since it can accentuate modeling errors.
Models should have no warnings during simulation (for example, redundant constraints, splines,
and so on).
Understand numerical methods (for example, understand your integrator).
Look for results which become very large in magnitude; this could indicate a discontinuity.
Miscellaneous Tips
Avoid very large numbers and very small numbers. Be wary when your model contains numbers
like 1e+23 or 1e-20.
Choose the right set of units. Length units of millimeters may not be appropriate if youre
milliseconds units.
Extend the range of spline data beyond the range of need.
Dont write function expressions that can potentially divide by zero (for example, use the MAX
Additional Publications
You might find it helpful to refer to the following resources when modeling mechanical systems.
About Adams/Solver
Recommended Publications:
To learn about:
See:
Akima Method
Chebyshev Polynomial
Gear Stiff
Gear, W.C. Simultaneous Numerical solution of Differentialalgebraic Equations. IEEE Transactions on Circuit Theory, Vol. CT18, No. 1, pp. 89-95. New York: Institute of Electrical and
Electronics Engineers, 1971.
Numerical Stiffness
Rotational Coordinates
Standard Beam Stiffness Matrix Przemieniecki, J. S. Theory of Matrix Structural Analysis, p. 79.
New York: McGraw-Hill, 1968.
Timoshenko Beams
Vehicle Technology
8 Adams/Solver
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
A
Action-Only Force
A force that has one point of action and has no points of reaction.
Action-Reaction Force
A force that causes equal and opposite forces at its points of attachment
B
Base Frame
A reference frame with respect to which you position and orient another reference frame. For example,
if you define the position and orientation of a marker with respect to a body coordinate system (BCS),
the BCS is the base frame.
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:
About Adams/Solver
Gear, C.W. Numerical Initial Value Problems in Ordinary Differential Equations. New Jersey:
Prentice-Hall.
Discrete Function
A function that you define with a set of data points rather than with a continuous equation.
Dynamic Analysis
An analysis, performed over time, of a system that relies on inertial effects to determine motion.
E
Euler Singularity
A singular matrix that results when the second Euler angle is zero. Therefore, the first and third Euler
angles are not uniquely defined, and this results in a singular Jacobian matrix.
F
Force
An effect that has magnitude and direction and that causes motion of a rigid part when there is no other
external effect on the rigid part. In Adams/Solver, force sometimes refers to both translational and
rotational forces.
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
10 Adams/Solver
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
user-written subroutine.
O
ODE
Ordinary Differential Equation
Output Step
A step at which you request output. Adams/Solver varies the integration step size (see above), but writes
request information at the output steps you specify. The output step is nearly always larger than the
integration step.
About Adams/Solver
P
Positioned Frame
A reference frame you position and orient with respect to another reference frame. For example, if you
define the position and orientation of a marker with respect to a BCS, the marker is the positioned frame.
Positive Semidefinite
A mathematical characteristic of a matrix. For example, the matrix K is positive semidefinite if, for any
x, transpose (x)Kx is greater than or equal to zero.
Principal Coordinate System
The coordinate system whose origin is at the part center of mass and whose axes have the same alignment
and direction as the axes of the principal moments of inertia. The part products of inertia associated with
the principal coordinate system are zero.
Program Abort
Program aborts (sometimes loosely referred to as FORTRAN crashes) occur when Adams/Solver is
unable to reasonably prevent or protect against errors that cause problems for the operating system; the
operating system then responds to the error by prematurely aborting (stopping) Adams/Solver execution.
Q
Quasi-Static Equilibrium Analysis
An analysis that finds the change in displacement over time without considering velocities or
accelerations.
R
Right-Hand Rule
A rule for determining the direction of a positive rotation about any axis in a right-handed reference
frame. If you point the right thumb in the positive direction along any axis, the curled fingers indicate
the direction of the positive rotation about that axis.
Rotational Force
A torque; that is, a force that causes rotation of a rigid part about the vector defining the rotational force
when there is no other external effect on the rigid part.
S
Standard System Element
A system element you describe with an Adams/Solver statement that does not define and pass constants
to a user-written subroutine.
Statement
11
12 Adams/Solver
Any executable line in the Adams/Solve data set. Adams/Solver associates one statement with each
element in the model.
State Vector
The one-dimensional array of system variables defined by the equation set.
Static Equilibrium Analysis
An analysis of a mechanical system at the configuration at which all forces are equilibrated and all
velocities and accelerations are zero.
System Element
A mechanical characteristic of the system that you describe with an Adams/Solver statement.
Symbolic Factorization
The map of the elements of a matrix, A, onto its lower and upper triangular factors, L and U. Once this
map has been computed, it can be stored for multiple uses for other matrices with identical structures but
with different numerical values.
Symbolic Refactorization
The process of redefining the symbolic factorization of a matrix after a previous factorization has resulted
in a singular matrix.
T
Translational Force
A force that causes rectilinear translation of a rigid part in the same direction as the translational force
when there is no other external effect on the rigid part.
Using Adams/Solver
Using Adams/Solver
13
14 Adams/Solver
Command File
Creating an Adams/Solver Command File
This section explains how to create a command file. Learn about Command File Syntax.
Using a text editor, enter the commands you want to use to control your simulation, using the following
guidelines:
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
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.
Using Adams/Solver
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.
15
16 Adams/Solver
Using Adams/Solver
17
18 Adams/Solver
Using Adams/Solver
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.
19
20 Adams/Solver
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
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.
Using Adams/Solver
Figure 2
21
22 Adams/Solver
Datasets
Working with Adams/Solver Datasets
After you create an idealized model on paper and determine the units you want to work in, you are ready
to create your model in Adams/Solver by entering statements and function expressions in the dataset.
Most statements define a model element. These include the specification of mass and inertia properties,
geometry, and connectivity, as well as analysis control and output specification. Each function
expression, in general, evaluates a mathematical equation and returns that value to the statement.
The following statements allow you to use the function expressions as part of the element definition:
DIFF
SFORCE
GFORCE
VARIABLE
MOTION
VFORCE
REQUEST
VTORQUE
SENSOR
If you can develop an equation describing the desired characteristic and are familiar with FORTRAN
syntax, you have the knowledge to write a correct Adams/Solver function expression.
You use a text editor to enter the statements and function expressions in a file. The file is called the Adams
model definition file or the dataset. Each statement consists of an identifier and a set of keywords that
qualify the statement. You can specify most system properties and data in the dataset.
Using Adams/Solver
23
24 Adams/Solver
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.
Using Adams/Solver
The following sample structure is an alternate organization scheme for the piston-crank mechanical
system. This structure emphasizes a relational organization of data.
PISTON COMPRESSOR SAMPLE dataset
!********PART MODULES *************************************
PART - (01) GROUND
PART/01,GROUND
MARKER/01
GLOBAL REQUEST REFERENCE
PART - (02) CRANK
PART/02, MASS=2, CM=02
, IP=5, 6, 10
MARKER/02, QP=0,0,-3
CENTER OF MASS
REQUESTS
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
25
26 Adams/Solver
!**********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
Using Adams/Solver
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.
27
28 Adams/Solver
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)
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
Using Adams/Solver
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, lower-case terms indicate the types of values that are to follow the argument key
word. The types of values can be:
Identifiers (id1,...,idn)
Cartesian coordinates (x, y, z)
Angular values (a, b, c)
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
29
30 Adams/Solver
colon must separate character strings. You may break assignment arguments for a statement before any
comma or colon. If you break the argument before a comma, do not retain the separating comma.
The following PART statement includes the assignment arguments MASS, CM, IP, and QG:
PART/03, MASS=1, CM=0305
,IP=1.5,1.6,3, QG=2,0,0
Here, the value or values following indicate:
MASS keyword indicates the value of the mass of the part.
CM indicates the identifier of the part center-of-mass marker.
IP indicates the three principal mass moments of inertia of the part about the part center-of-mass
marker location.
QG indicates the initial coordinates of the BCS of the part with respect to the global coordinate
system.
Function Arguments
Arguments that allow you to define their values with a FORTRAN-like expression in the dataset or with
an external user-written subroutine are called function-expression arguments. Each of these arguments
consists of the argument, an equal sign, and an expression that Adams/Solver can evaluate.
There are two types of function-expression arguments:
Define an expression (e).
Pass constants to a user-written evaluation subroutine (USER=).
to compute a MOTION.
MOTION/0201, JOINT=0201, FUNCTION=POLY(TIME,0,0,360D)
The statement below includes a function-expression argument that defines constants
Using Adams/Solver
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.E-3D
D does not specify double precision in Adams/Solver as it does in FORTRAN. In Adams/Solver,
a D after a number indicates that the number is to be scaled by the factor
180 .
All output angular data defaults to radians, except for the rotational displacement data in the
tabular output file. If you want to scale angular displacement output from degrees to radians, use
the DSCALE argument on the OUTPUT command or statement.
Arguments
Each argument indicates a condition, assigns a value, or evaluates an expression. Adams/Solver
has three basic types of arguments, described in Formatting Statements.
31
32 Adams/Solver
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
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.
of statements.
You can have as many blank lines as you want in an Adams/Solver dataset.
Using Adams/Solver
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
(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
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.
33
34 Adams/Solver
Comma - Separates arguments within a command and separates multiple integer values
(i1,...,in) and multiple real values (r1,...,rn) within multiple valued arguments.
Backslash - Instead of the comma, separates a function-expression argument from any
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
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
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
Using Adams/Solver
If a number does not contain either a decimal point or an exponent, Adams/Solver interprets it as
an integer. You may assign an integer value when Adams/Solver expects a real argument.
However, if you do this, Adams/Solver converts the integer to a real number before storing it.
Integer values input to Adams/Solver must be greater than -231 -1 and less than +231 -1.
You can assign a real number value when Adams/Solver expects an integer if the fractional part
of the real number is zero. If you do this, Adams/Solver converts the real number to an integer
before storing it.
You can input exponents for real numbers and integers you assign to real arguments. The
exponent indicates an integer power of ten by which Adams/Solver is to multiply the mantissa.
To indicate the exponent, immediately follow the number with an E (this is consistent with the E
in FORTRAN). Then, follow the E with the positive or negative integer exponent. The allowable
range for exponents depends on the particular computer on which you are running
Adams/Solver. 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.159E-02
314159E+2
Internally, Adams/Solver uses radians for angular units. Adams/Solver includes a degrees-to-
radians conversion factor to allow for easy conversion of degree quantities to radian quantities.
Put a D immediately following a number that you want Adams/Solver to scale by that
conversion factor. Adams/Solver multiplies the number by
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
argument value.
You include a blank or a comma in a number.
35
36 Adams/Solver
Statements
A statement must begin in one of the first five columns of the line. If it does not, Adams/Solver
treats it as a comment and does not read it.
Statements can be defined only between column 1 and column 80.
To continue a statement that is longer than eighty columns, use an ampersand (&) after the last
statement character in the line to be continued or use a comma as the first character in all
continuation lines (see Continuations). If you use the ampersand, the last statement character can
be in the seventy-ninth column at most because the ampersand would then have to be in the
eightieth column.
Adams/Solver can read two or more statements on the same line if they are separated by
semicolons.
You can abbreviate statement names. Underscores in statement formats, indicate minimum
allowable abbreviations. See C++ Statements.
Adams/Solver accepts both upper- and lower-case letters for statement names.
Because the TITLE statement is read but not executed, it can include any combination of
Using Adams/Solver
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 mutually-perpendicular unit
37
38 Adams/Solver
vectors that specify three directions. Associated with each of these directions is a scale that permits
measurement of quantities with respect to that coordinate system. You can specify all kinematic and
kinetic vector quantities as projections of the vector along three mutually-perpendicular unit vectors,
,
The example below illustrates a vector, R, that is defined as the displacement of point P with respect to
, y , and
point O. For example, R x, R y, and R z are defined as the measure numbers of R along the x
G
G
z G axes, respectively, of the global coordinate system.
Example of a Coordinate System and Vector
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.
Using Adams/Solver
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.
39
40 Adams/Solver
A reference point for defining where you want graphical entities anchored.
An initial location of a constraint you want to use to connect bodies together.
A point where you want force applied to a body.
All points where you want to measure displacement, velocity, acceleration, or force.
You can also use markers to define directions in a mechanical system such as:
The axes about which you specify a body's mass moments of inertia.
A direction you want to use when you specify a constrain.
A direction you want to use when you specify a force.
A direction you want to use when you specify graphical dimensions.
The axes along which you want to measure displacement, velocity, acceleration, or force.
marker on a body, you must specify its location and orientation with respect to the BCS.
Floating markers - You use a floating marker to specify sites for applying certain forces or
constraints to bodies. The force or constraint dictates the location and orientation of the floating
marker. Therefore, you do not specify a position for a floating marker. This allows the floating
marker's location and orientation to change with respect to its BCS during the simulation, as
dictated by the force or constraint.
Adams/Solver forces and constraints that use floating markers include the six-component force, threecomponent force, three-component torque, curve-to-curve constraint, and point-to-curve constraint.
Positioning Methods
You can tell Adams/Solver the position of a local coordinate system by indicating its location and
orientation. There is only one way to locate a local coordinate system but two ways to orient it. A local
coordinate system's location is always defined the same way, regardless of the orientation method you
Using Adams/Solver
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.
Note:
When you locate and orient coordinate systems, remember that the BCS is always defined with
respect to the GCS and a marker is always defined with respect to the BCS of the body that
owns it.
The next sections explain the Adams/Solver location and orientation positioning methods.
Location Method
Adams/Solver uses Cartesian coordinates to define the location of the origin of the positioned coordinate
system with respect to the base coordinate system. Cartesian coordinates are the distances to the point
you are defining, measured from the origin and along the
system. The example of the Cartesian Coordinates Location Method below shows an example of using
Cartesian coordinates to define the location of a positioned coordinate system.
Example of the Cartesian Coordinates Location Method
Orientation Methods
For orienting any BCS with respect to the GCS or any marker with respect to its BCS, you can use the
rotation sequence method or the three-point method (also known as the direction cosines method) as
explained next.
Rotation Sequence Method
The rotation sequence method used by Adams/Solver to orient a local coordinate system uses rotation
angles associated with a particular sequence. Although there are 24 possible rotation sequences
41
42 Adams/Solver
available, Adams/Solver uses only the body-fixed 3-1-3 (or z-x-z) rotation sequence. The rotation
angles associated with this sequence are often referred to as Euler angles. When you use the Euler angles
method to orient a positioned coordinate system, you need to define the orientation of the positioned
coordinate system with respect to the base coordinate system.
The example below of the Rotation Sequence Method (Body-Fixed 3-1-3 Euler Angles) shows how
successive rotations of Euler angles incrementally orient the axes of the positioned frame. Initially, the
positioned coordinate system has the same orientation as the base coordinate system (5a).
The first Euler angle rotates the positioned coordinate system about its z-axis +90 degrees. This
degrees, to reposition the new x-axis (x) and the second new y-axis (y).
Together and in sequence, these rotations define the orientation of the positioned coordinate system (5d).
The right-hand rule defines the direction of positive rotation about each axis. For example, if you look
down the initial z-axis, positive rotations are counterclockwise and negative rotations are clockwise.
Example of the Rotation Sequence Method (Body-Fixed 3-1-3 Euler Angles)
Because Euler angle rotations cumulatively define the orientation, you may find it difficult to imagine
orientations that involve rotations of other than 0, 45, or 90-degree increments. When orienting a
coordinate system that requires a complex combination of rotations, you may find it easier to use the
three-point orientation method, as described next.
Three-Point Method
You can use the three-point method to specify the orientation (in direction cosines) of the positioned
coordinate system relative to the base coordinate system. When you use the three-point method to orient
a positioned coordinate system, provide the following geometric data with respect to the base coordinate
system:
Cartesian coordinates of the positioned coordinate system origin (point 1). You must specify this
Using Adams/Solver
Cartesian coordinates of a point on the primary axis of the positioned coordinate system (point
2). You can specify either the z- or x-axis as the primary axis of the positioned coordinate
system. If you do not specify a primary axis, the
z-axis is used by default. When it is important to exactly specify the z-axis of the positioned
coordinate system, provide the Cartesian coordinates of a point on the z-axis. When it is
important to exactly specify the x-axis of the positioned coordinate system, provide the
Cartesian coordinates of a point on the x-axis.
Cartesian coordinates of a point that is in the x-z plane of the positioned coordinate system
(point 3). Since three points in a straight line do not uniquely define a plane, you must make sure
that point 3 does not lie on the line defined by points 1 and 2. If the three points are collinear,
Adams/Solver returns an error.
The example of the Three-Point Method below shows the points of the positioned coordinate system with
respect to the base coordinate system. Point 2 in the figure specifies the z-axis of the positioned
coordinate system and point 3 defines a point in the x-z plane of the positioned coordinate system. Note
that in this example, point 3 is placed directly on the x-axis of the positioned coordinate system but only
needs to be in the x-z plane.
By default, Adams/Solver assumes that R 1 defines the the exact location of the coordinate system origin
and
R 2 defines a point on the z-axis. Because the third point ( R 3 by default) does not necessarily lie on
an axis but happens to in this example, Adams/Solver determines the vector cross product of vectors
and
R2
R 3 to form an orthogonal y-axis. Then, Adams/Solver determines the vector cross product of the
new y-axis and the exact axis (the z-axis by default) to produce the orientation of the remaining axis (by
default, the x-axis). By calculating
v 1 and v 2 , you can verify that the third point is in the x-z plane
43
44 Adams/Solver
Using Adams/Solver
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, its possible to superimpose all of the BCS on the GCS. When you
do this, the initial marker position with respect to the BCS is the same as the marker position with respect
to the GCS. Under these circumstances, the BCS positions are all zero. Because they default to zero if
left unspecified, this approach reduces the amount of data that you must provide.
In addition, even though you input the markers positions with respect to their different BCS, all markers
occupying the same position in space have identical position with respect to the GCS. In general, this
approach greatly simplifies the summation process for superimposing marker positions. When using this
approach, keep in mind that Adams/Solver superimposes the disparate BCS on the GCS only at time
zero. As the model articulates during a subsequent dynamic, kinematic, or quasi-static equilibrium
analysis or settles during a subsequent static equilibrium analysis, the BCS move with their bodies with
respect to the stationary GCS.
45
46 Adams/Solver
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.
Using Adams/Solver
Removes number
rotational DOF:
Removes total
number DOF:
Constant velocity
Cylindrical
Fixed
Hooke
Planar
Rack-and-pinion
0.5*
0.5*
Revolute
47
48 Adams/Solver
Table 1
Removes number
rotational DOF:
Removes total
number DOF:
Screw
0.5*
0.5*
Spherical
Translational
Universal
* The rack-and-pinion and screw joints are shown as half translational and half rotational because they
relate a translational motion to a rotational motion. They each create one constraint, but the constraint is
neither purely translational nor purely rotational.
Table 2
Removes Number
translational DOF:
Removes number
rotational DOF:
Removes total
number of DOF:
Atpoint
Inline
Inplane
Orientation
Parallel Axes
Perpendicular
Table 3
Removes
number mixed
translational &
rotational DOF:
Removes
number
new
generalized
DOF:
Removes
total number
DOF:
This type of
constraint
Removes
number
trans. DOF:
Coupler
--
--
--
Curve-tocurve
--
--
--
Gear
--
--
--
Using Adams/Solver
Table 3
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:
Translational
motion
--
--
--
Rotational
motion
--
--
--
Point-to-curve --
--
--
User-defined
constraint
--
--
--
49
50 Adams/Solver
Using Adams/Solver
Adams/Solver tries to solves your model, you can find out how many and which redundant constraints
are being removed.
Single-Component Forces
You can use two types of single-component forces in Adams/Solver:
Action-Only, Single-Component Forces
Action-Reaction, Single-Component Forces
Action-Only, Single-Component Forces
An action-only, single-component force is an external force or torque applied to a single body in a model
that acts along a specified fixed axis. As you know from Newtons third law, however, in nature there is
no such thing as an action-only force (that is, one with no reaction). Therefore, the body reacting to the
action-only force in Adams/Solver is automatically defined as ground and shows no visible effect in your
model.
Note:
You may find the action-reaction, multi-component forces more intuitive to use than the
action-only, single-component force. If you want to apply force to only one body, you can
use the action-reaction, multi-component forces and specify the reaction marker on ground.
You can apply either a translational or rotational action-only, single-component force to a body in your
model. Note that a rotational force is a pure torque in Adams/Solver. For both translational and rotational
action-only, single-component forces, you provide Adams/Solver with two markers: action and
direction. The action marker declares the point of application for the force.
For a rotational force, or pure torque, the location of the action marker is irrelevant; only the body to
which it belongs is important. The z-axis of the direction marker specifies the direction of the force.
Adams/Solver evaluates the signed magnitude and applies it to the action marker.
If the force is positive and translational (Figure 3), it acts in the positive direction along the z-axis of the
direction marker. If the force is positive and rotational (Figure 4), it acts in the positive direction about
the z-axis of the direction marker. The right-hand rule defines the positive direction.
51
52 Adams/Solver
Figure 3
Figure 4
An action-reaction force is a force applied to one body producing a reaction force on a second body that
is equal and opposite to the action force on the first body. You can apply either a translational or rotational
(torque) action-reaction, single-component force to your model.
For translational, action-reaction, single-component forces (Figure 5), you provide
Adams/Solver with two fixed markers: action and reaction. These markers specify the points of
force application and the line along which the instantaneous forces act, therefore no direction
marker is needed. If the force applied to the action marker is positive, the action marker is
pushed away from the reaction marker. If the force applied to the action marker is negative, the
action marker is pulled towards the reaction marker.
Using Adams/Solver
For rotational, action-reaction, single-component torques (Figure 6), you provide Adams/Solver
with two fixed markers: action and reaction. These markers only specify the body affected by
the torque not a location on the body itself, because pure torques are independent of location.
The z-axis of the reaction marker specifies the axis about which the torque is applied. If the
torque is positive, the action marker tends to move counter-clockwise to the reaction marker. If
the torque is negative, the action marker tends to move clockwise to the reaction marker.
Figure 5
Figure 6
Multi-Component Forces
Adams/Solver also allows you to define multi-component translational and rotational force vectors. For
each of the multi-component forces, you provide Adams/Solver with two fixed and one floating marker:
action (fixed), reaction (floating), and direction (fixed). The action and reaction markers always remain
coincident. The axes of the direction marker define the directions of the vector components. You specify
the x, y, z measure numbers of the force components to define them with respect to the direction marker
axes.
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 righthand rule. You should specify all of the components of each multi-component force to be applied to the
53
54 Adams/Solver
action marker, even if some are zero. Equal and opposite forces are automatically applied to the reaction
(floating) marker.
Figure 7
Figure 8
Using Adams/Solver
Figure 9
55
56 Adams/Solver
ROUTINE Argument
Many Adams/Solver statements and commands feature the construct FUNCTION=USER(r1,r2,...,r30),
which specifies that Adams/Solver is to obtain element characteristics by loading and calling a specific
user subroutine from a specific library of user subroutines. For example, Adams/Solver calls the
SFOSUB subroutine for the SFORCE statement.
The ROUTINE argument allows you to optionally specify an alternative library and user subroutine
name for some or all elements.
The ROUTINE argument takes a string argument:
ROUTINE=libname::subname
The delimiter, ::, is required to separate the library name from the subroutine name. Both the libname and
the subname are optional, but the :: delimiter is required to distinguish the library name. For example, to
specify that a different subroutine name, mysfo, is to be loaded from the default subroutine library (the
library that was mentioned when Adams/Solver was run in run-user mode), you should write:
ROUTINE=mysfo
or
ROUTINE=::mysfo
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
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
Using Adams/Solver
Statement/Command
CURVE
CURSUB
SURFACE
SURSUB
CONTROL
CONSUB
COUPLER
GSE
Note:
The subroutine specified by the ROUTINE argument must have the same argument list as
the default subroutine. Only the name is changed. A failure to satisfy this requirement
results in unpredictable runtime failure.
Just like many elements of a particular type can share the default user subroutine, many elements may
share an alternative user subroutine. In other words, a group of your SFORCE elements may use the
SFOSUB in the default library while a different group of SFORCE elements is using mylib::mysfo.
You can either fully qualify the name and location of the library or rely on Adams/Solver to search for
the library using predefined rules. For example, ROUTINE argument can specify absolute paths:
ROUTINE=/home/jdoe/mylibs/libsforces.so::sfo312
or relative paths with abbreviated library names:
ROUTINE=mylibs/sforces::sfo312
In the latter case, you would be relying on Adams/Solver knowing to search in /home/jdoe (see the
PREFERENCES statement for details about the library search path) and built-in search-rules that first
look for the specified name, and failing that, try to prepend the lib prefix and an architecture specific
suffix (.dll on the Microsoft Windows platform, .sl on the HP-UX platform and .so on other 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,
57
58 Adams/Solver
Using Adams/Solver
Joint types
Translational Joint
Joint reaction force (F), bending moment (Tm), torsional moment (Tn), and force preload (Fprfrc) are
used to compute the frictional force in a translational joint. You can individually turn off the force effects
using switches SW1 through SW4. The bending moment (Tm) is converted into an equivalent force
using the Xs block. Similarly, torsional moment is converted into an equivalent joint force using the
friction arm (Rn). Frictional force (Ffrict) is applied along the axis of translation in the direction that the
FRD block computes. For more information, see the Block Diagram of the Translational Joint.
59
60 Adams/Solver
Note:
Adams/Solver (C++) computes DZ0 (the initial joint displacement) after the first
successful assembly of the model (initial conditions or first static simulation.
Revolute Joint
Joint reactions (Fa and Fr), bending moment (Tr), and torque preload (Tprfrc) determine the frictional
torque in a revolute joint. You can turn off one or more of these force effects using switches SW1 through
SW3. The joint reactions (Fa and Fr) are converted into equivalent torques using the respective friction
arm (Rn) and pin radius (Rp). The joint bending moment (Tr) is converted into an equivalent torque using
pin radius (Rp) divided by bending reaction arm (Rb). The frictional torque (Tfrict) is applied along the
axis of rotation in the direction that the FRD block computes. See the Block Diagram of the Revolute
Joint.
Using Adams/Solver
61
62 Adams/Solver
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.
Using Adams/Solver
63
64 Adams/Solver
Universal/Hooke Joint
The universal/hooke joint contains two yokes (I_YOKE and J_YOKE) that are modeled independently.
An equivalent revolute joint represents each yoke. Frictional torques are applied along the axes of
rotation of the two yokes. See the Block Diagram of the Universal/Hooke Joint.
Spherical Joint
The reaction force (F) and the preload frictional torque (Tprfrc) are the two forcing effects used in
computing the frictional torque on a Spherical joint. The ball radius is used to compute an equivalent
frictional torque. The FRD block determines the direction of the frictional torque. See the Block Diagram
of the Spherical Joint.
Using Adams/Solver
65
66 Adams/Solver
Error Codes
Adams/Solver issues "Simulate status" or "Termination status" codes when a simulation ends, along with
a verbose error message description. The following table details the meanings of the numeric codes
issued by Solver:
Parameter Value
Description
NOERRS
No errors
INPERR
-101
BADSIT
-102
ERINPT
-105
ERVRFY
-117
ERMEMO
-118
ERRVRS
-119
ERRDIM
-120
ERRLCK
-121
Lockup detected
BADMEM
-122
BADAMD
-123
ERRSML
-124
NOTCXX
-125
TRMRCR
-993
SNHALT
-994
ERTERM
-995
PRFLER
-996
INPTRM
-997
TERMNT
-998
2 Adams/Solver
CLEAR
EXECUTION
AINIT
DISPLAY
PLOT
AUTOSCALE
DRAW
RETURN
BACKUP
DT
SET
CENTER
ERASE
Q: Why is the UCON user-defined constraint element not supported in Adams/Solver (C++)?
A: The UCON element was always an extremely difficult element for users to use and only expert users
derived a benefit from this element. The C++ version of Solver, with its analytical derivative capability,
has replaced UCON with an extremely user-friendly user-defined constraint element (see the GCON
statement and command), which does not require the user to write user subroutines containing the partial
derivatives of the constraint equations. Instead, the user provides a function expression which is to
constrained to the value zero.
Adams/Solver (C++) computes all the required derivatives.
As a result, the UCON command and the UCON statement are not supported in Adams/Solver (C++).
Q: Why are the LIST/NOLIST statements not supported in C++?
A: These statements are not supported because Adams/Solver (C++) does not generate a tabular output
file.
Q: Why is the tabular output file (.out) not supported in C++?
A: The tabular output file was an early attempt at reporting results from Adams/Solver. Due to, among
other things, a lack of machine readability, later versions of Adams added more robust output file formats,
such as the .res and .req file.
The tabular output file is considered obsolete and supporting it in the Adams/Solver (C++) was not
deemed necessary. At the same time, it is recognized that the tabular output file contained valuable
information not reported elsewhere. Work on determining this information and where to report it is work
in progress.
Operators
Function expressions consist of scalar or vector measures and functions, combined with a set of
arithmetic and grouping operators. The operators closely resemble those of the FORTRAN programming
language, with extensions for vector expressions.
Accepted Combinations
The following combinations are accepted. The symbol s represents a scalar subexpression and v
represents a vector subexpression.
Parentheses grouping to override operator precedence (vector and scalar):
(v), (s)
Vector construction from scalar expressions:
[s,s,s]
Simple scalar arithmetic, including unary plus and unary minus:
s+s, s-s, s*s, s/s, -s, +s
Power (scalars only):
s**s
Vector summation, subtraction, unary minus and unary plus:
v+v, v-v, +v, -v
Scaling of a vector by a scalar:
s*v, v*s, v/s
Note that division by a vector is not supported.
Inner product (dot product):
v*v
Cross product:
v%v
Operators Precedence
Furthermore, in evaluating the arithmetic expressions, the following order of precedence is used:
*, /, %
Intermediate precedence
+, -
4 Adams/Solver
Operators
Operators of equal precedence are applied from left to right, with the following exceptions for the power
and unary operators:
A**B**C is interpreted as A**(B**C), not (A**B)**C
** binds tighter than unary operators to its left and looser than unary operators to its right. For example:
-A**-B = -(A**(-B))
and
-A**-B**-C = -(A**(-(B**(-C))))
In some cases parentheses must be used to group scalar and vector quantities such that the expression is
not nonsensical. For example, v*v%v may need to be written as v*(v%v).
Vector subexpressions can appear in expressions where the final value is a scalar, and vice versa, for
example:
VARIABLE/1, FUN=DXYZ(1,2)*VXYZ(1,2) + TIME
where a dot product of two vector measures results in a scalar quantity.
There are only two contexts in the current Adams language where a vector quantity is expected. These
are the recently added FXYZ and TXYZ arguments of the VFORCE, VTORQUE and GFORCE
statement which can be used instead of the FX, FY, FZ, TX, TY and TZ arguments to specify force and
torque laws. In all other contexts, the expression must evaluate to a scalar quantity.
C++ Statements
You use statements to define the elements of your model, request output from the simulation, and,
optionally, set analysis parameters to use during the simulation. Note that you can use the C++ version
of Adams/Solver C++ Commands to set analysis parameters, which is often a better approach. Below are
the Adams/Solver (C++) statements grouped according to their function. Detailed information on each
statements can be found by following the links:
Type of Statement
Statement Name
Dataset delimiter
END
TITLE
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
6 Adams/Solver
C++ Statements
Type of Statement
Statement Name
Reference data
ARRAY
CURVE
MATRIX
PINPUT
POUTPUT
SPLINE
STRING
SURFACE
Analysis parameters
DEBUG
ENVIRONMENT
EQUILIBRIUM
IC
INTEGRATOR
KINEMATICS
LSOLVER
PREFERENCES
SENSOR
UNITS
Output
FEMDATA
Unsupported statements
UCON
LIST/NOLIST
ACCGRAV 7
C++ Statements
ACCGRAV
The ACCGRAV statement specifies the magnitude and direction of the acceleration of gravity. In
conjunction with the part masses, the gravitational field defines a body force at the center of gravity in
each part.
Format
Arguments
IGRAV
Defines the x component of gravitational acceleration with respect to the ground coordinate
system.
Default: 0
JGRAV
Defines the y component of gravitational acceleration with respect to the ground coordinate
system.
Default: 0
KGRAV
Defines the z component of gravitational acceleration with respect to the ground coordinate
system.
Default: 0
Examples
ACCGRAV/JGRAV=-386.088
This ACCGRAV statement defines the gravitational constant of 386.088, acting along the y-axis of the
ground coordinate system (GCS) in the negative direction.
See other Forces available.
8 Adams/Solver
C++ Statements
ARRAY
The ARRAY statement defines a list of input variables (U), state variables (X), output variables (Y), or
initial conditions (IC) associated with system modeling elements such as GSE, LSE, and TFSISO (see
GSE, LSE and TFSISO). IC ARRAY's or ARRAY's without a type can also be used to define a list of
constants. These values may be accessed in function expressions or user-written subroutines.
Format
Arguments
IC
NUMBERS= Allows you to enter a one-dimensional array of real numbers when using the IC array.
r1[,r2,...,]
SIZE=i
Allows you to define the size of the array. In cases where Adams/Solver (C++)
calculates the SIZE differently from the SIZE that you supply, Adams/Solver (C++)
returns an error or warning message.
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 dont specify SIZE, the associated systems
element automatically sets the size.
ARRAY 9
C++ Statements
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.
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 dont specify SIZE, the associated systems element
automatically sets it.
Extended Definition
The ARRAY statement defines a list of input variables (U), state variables (X), output variables (Y), and
initial conditions (IC) associated with system modeling elements such as GSE, LSE, and TFSISO.
ARRAY may also be used to define a list of constants. These values may be accessed in function
expressions or user-written subroutines.
There are three basic variations of the ARRAY statement:
The X and Y arrays designate the state and output variable arrays for a systems element.
For the X and Y arrays, the corresponding systems modeling element automatically determines the size
of the array and checks it against the ARRAY statements SIZE value (if given).
The IC and SIZE parameters are optional. Adams/Solver (C++) determines the actual size of the array
during input-file parsing as it counts the NUMBERS argument. However, if you provide a value for
SIZE, Adams/Solver (C++) checks the count for consistency.
For X and Y arrays, you should reference the array as the state variable array or output variable array of
one of the system elements in the dataset, either LSE, GSE, or TFSISO. U and IC arrays may exist
independently. Grouping VARIABLES in a U array does not offer any computational advantage,
although it might have a convenience value.
The SIZE argument, if used, should match the number of entries in the VARIABLES or NUMBERS
arguments or the size needed for the associated element. Adams/Solver (C++) provides the SIZE
argument mainly for your convenience in dataset creation. For LSE arrays, the X size is the row
dimension of the A and B matrix, and the Y size is the row dimension of the C and D matrix. For TFSISO
arrays, the transformation 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.
10 Adams/Solver
C++ Statements
Both function expressions and user-written subroutines can access the array values. Function expressions
use the function ARYVAL (id, nseq ) (see ARYVAL) to access the values. The id specifies the identifier
of the ARRAY, and nseq specifies the position of the desired value in the ARRAY statement. To access
all the elements of an array from a user written subroutine, you should call the subroutine SYSARY (see
the SYSARY subroutine). To access one element of an ARRAY in a subroutine, you should call the
subroutine SYSFNC (see the SYSFNC subroutine).
Examples
The following are three simple examples of the ARRAY statement.
ARRAY/1, X
ARRAY/2, U, VARIABLES=2
ARRAY/3, IC, NUMBERS= 0.0, 0.0
See other Reference data available.
BEAM 11
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
non-linear Euler-Bernoulli theory.
By default, the non-linear Euler-Bernoulli 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.
A Qy 2
ASY = ---2- ------ dA
Iy A lz
12 Adams/Solver
C++ Statements
ASZ=r
Specifies the correction factor (that is, the shear area ratio) for shear deflection in the z
direction for Timoshenko beams.
A Qz 2
ASZ = ---2- ------ dA
Iz A ly
Solid rectangular
(6/5)
Solid circular
(10/9)
(2)
See also Roarks Formulas for Stress and Strain, Young, Warren C., Sixth Edition, page
201. New York:McGraw Hill, 1989.
CMATRIX=r1,...,r21 Establishes a six-by-six damping matrix for the beam. Because this matrix is symmetric,
only one-half of it needs to be specified. The following matrix shows the values to input:
Enter the elements by columns from top to bottom, then by rows from left to right. If you do
not use either CMATRIX or CRATIO, CMATRIX defaults to a matrix with thirty-six zero
entries; that is, r1 through r21 each default to zero.
CRATIO=R
Establishes a ratio for calculating the damping matrix for the beam. Adams/Solver multiplies
the stiffness matrix by the value of CRATIO to obtain the damping matrix.
Defaults: 0
BEAM 13
C++ Statements
EMODULUS=r
GMODULUS=r
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 4power. For a solid
r
circular section, Ixx is identical to the polar moment of inertia J = -------- where r is the
radius of the cross-section. For thin-walled sections, open sections, and 2noncircular sections,
you should consult a handbook.
IYY=r,IZZ=r
Denote the area moments of inertia about the neutral axes of the beam cross sectional areas
(y-y and z-z). These are sometimes referred to as the second moment of area about a given
axis. They are4 expressed as unit length to the fourth power. For a solid circular section,
r
Iyy=Izz= -------- where r is the radius of the cross-section. For thin-walled sections, open
4 noncircular sections, you should consult a handbook.
sections, and
LENGTH=r
Defines the underformed length of the beam along the x-axis of the J marker.
Extended Definition
The figure below shows the two markers (I and J) that define the extremities of the beam and indicates
the twelve forces (s1 to s12) it produces.
The x-axis of the J marker defines the centroidal axis of the beam. The y-axis and z-axis of the J marker
are the principal axes of the cross section. They are perpendicular to the x-axis and to each other. When
the beam is in an undeflected position, the I marker has the same angular orientation as the J marker, and
the I marker lies on the x-axis of the J marker a distance LENGTH away.
14 Adams/Solver
C++ Statements
The beam statement applies the following forces to the I marker in response to the relative motion of the
I marker with respect to the J marker:
Axial forces (s1 and s7)
Bending moments about the y-axis and z-axis (s5, s6, s11, and s12)
Twisting moments about the x-axis (s4 and s10)
Shear forces (s2, s3, s8, and s9)
Linear theory
When using the Timoshenko beam theory, Adams/Solver (C++) uses a linear translational and linear
rotational action-reaction force between the two markers I and J. The forces the beam produces are
linearly dependent on the displacements, rotations, and corresponding velocities between the markers at
its endpoints.
The following constitutive equations define how Adams/Solver applies a force and a torque to the I
marker depending on the displacement rotation and velocity of the I marker relative to the J marker.
Fx
K 11 0
Fy
Fz
0 K 22 0
0 K 26
0 K 33 0 K 35 0
Ty
0 K 53 0 K 55 0
Tz
0 K 62 0
Tx
0 K 44 0
0
0 K 66
xL
y
z
a
b
c
c 11 c 21 c 31 c 41 c 51 c 61 V x
c 21 c 22 c 32 c 42 c 52 c 62 V y
c 31 c 32 c 33 c 43 c 53 c 63 V z
c 41 c 42 c 43 c 44 c 54 c 64 x
c 51 c 52 c 53 c 54 c 55 c 65 y
c 61 c 62 c 63 c 64 c 65 c 66 z
where:
Fx, Fy, and Fz are the measure numbers of the translational force components in the coordinate
BEAM 15
C++ Statements
marker, as seen by the J marker and measured in the J marker coordinate system.
Cij are the entries of the damping matrix either specified by the CMATRIX option or computed
Adams/Solver (C++) applies an equilibrating force and torque at the J marker, as defined by the following
equations:
Fj = - Fi
Tj = - Ti - L x Fi
L is the instantaneous vector from the J marker to the I marker. While the force at the J marker is equal
and opposite to the force at the I marker, the torque is usually not equal and opposite, because of vector L.
The BEAM statement implements a force in the same way the FIELD statement does, but the BEAM
statement requires you to input only the values of the beams physical properties, which Adams/Solver
(C++) uses to calculate the matrix entries.
16 Adams/Solver
C++ Statements
When using the Euler-Bernoulli formulation, Adams/Solver (C++) uses the following constitutive
equations to apply a force and a torque to the I marker.
0
0
Fx
0
F
0 6 / 5 L
0
y
Fz
0
0
6 / 5L
= {Fo } N
0
0
0
Tx
0
T y
0
1 / 10
0
0 1 / 10
Tz
x L
0
0
1 / 10 y
0 1 / 10
0 z
0
0
0 a
0 2 L / 15
0 b
0
0
2 L / 15 c
0
{ Fo }
Where
corresponds to the Timoshenko's constitutive equations shown above, and N is the axial
force on the beam computed as:
N = K11( x L ) + d
The term d corresponds to the axial viscous forces if any. See reference [2] for more information.
The non linear Euler-Bernoulli formulation is the default model for the BEAM statement because it
provides better results in simulations where BEAM objects are subject to axial forces.
Tip:
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-
BEAM 17
C++ Statements
Caution:
The K1 and K2 terms used by MSC.NASTRAN for defining the beam properties
using PBEAM are inverse of the ASY and ASZ used by Adams/Solver (C++).
When the x-axes of the markers defining a beam are not collinear, the beam
unlike most other Adams/Solver force statements, for which the z-axis is the
significant axis.) Therefore, the I marker must have a positive x displacement with
respect to the J marker when viewed from the J marker. In its undeformed
configuration, the orientation of the I and the J markers must be the same.
The damping matrix that CMATRIX specifies should be positive semidefinite.
This ensures that damping does not feed energy into the system. Adams/Solver
(C++) does not warn you if CMATRIX is not positive semidefinite.
When the beam element angular deflections are small, the stiffness matrix
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.
18 Adams/Solver
C++ Statements
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 100-inch axial offset in the negative y direction
causes torsion to the beam as shown in the figure above. The following statement defines this beam:
BEAM/0201, I=0010, J=0020, LENGTH=100
, IXX=100, IYY=50, IZZ=50, AREA=25.0663
, ASY=1.11, ASZ=1.11, EMOD=28E6, GMOD=10.6E6,
, CRATIO=0.0001
The beam lies between Marker 0010 and Marker 0020. The length of the beam is 100 inches; its torsional
constant is 100 inch4; its principal area moments of inertia about the y-axis is 50 inch4, and about the zaxis is 50 inch4; its cross-sectional area is 25.0663 inch2; its shear area ratio in the y direction is 1.11; its
shear area ratio in the z direction is 1.11; its modulus of elasticity is 28E6 psi; its shear modulus is 10.6
psi; and its damping ratio relative to the stiffness matrix Adams/Solver (C++) calculates is 0.0001. Note
that the beam ends belong to different parts.
References
1. Roark's Formulas for Stress and Strain, Young, Warren C., Sixth Edition, page 201. New York:
McGraw Hill, 1989.
2. J.S. Przemieniecki, Theory of Matrix Structural Analysis. New York: McGraw-Hill Book
Company, 1968
See other Forces available.
BUSHING 19
C++ Statements
BUSHING
The BUSHING statement defines a massless bushing with linear stiffness and damping properties.
Format
Arguments
C=r1,r2,r3
Specifies three viscous damping coefficients for the force transferred by the
bushing. The three coefficients multiply the relative translational velocity
components of the I marker with respect to the J marker as seen by the J marker
and along the x-, y-, and z-axis of the J marker. The force due to damping is zero
when there is no relative translational velocity between the two markers. C must be
in units of force-time per unit displacement.
Default: 0,0,0
Range: C 0
CT=r1,r2,r3
Specifies three viscous damping coefficients for the torque transferred by the
bushing. The three coefficients multiply the components of the relative angular
velocity of the part containing the I marker with respect to the part containing the
J marker as expressed in the x-, y-, and z-axis of the J marker. The torque due to
damping is zero when there is no relative angular velocity between the two
markers. CT must be in units torque-time per radian.
Default: 0,0,0
Range: CT 0
FORCE=r1,r2,r3
Specifies three constant force (preload) values. Constant values indicate the force
components along the x-, y-, and z-axis of the J marker when both the relative
displacement and the relative velocity of the I and J markers are zero.
Default: 0,0,0
I=id, J=id
Specifies the identifiers of the two markers between which the bushing is placed.
20 Adams/Solver
C++ Statements
K=r1,r2,r3
Specifies three stiffness coefficients for the force transferred by the bushing. The
three coefficients multiply the three translational displacement components of the
I marker with respect to the J marker as expressed in the x-, y-, and z-axis of the J
marker. K must be specified in terms of force per unit of deformation.
Default: 0,0,0
Range: K 0
KT=r1,r2,r3
Specifies three stiffness coefficients for the torque transferred by the bushing. The
three coefficients multiply the three rotational displacement components of the I
marker axes relative to the J marker axes as expressed in the x-, y-, and z-axis of
the J marker. KT must be in units of torque per radian.
Default: 0,0,0
Range: KT 0
TORQUE=r1,r2,r3 Specifies three constant torque (preload) values. Constant values indicate the
torque components about the x-, y-, and z-axis of the J marker when both the
relative displacement and the relative velocity of the I and the J markers are zero.
Default: 0,0,0
Extended Definition
The BUSHING statement defines a massless bushing with linear stiffness and damping properties. The
BUSHING statement applies a force and torque to two parts. You specify a marker on each part for force
and/or torque application.
Each force consists of three components in the coordinate system of the J marker, one in the x-axis
direction, one in the y-axis direction, and one in the z-axis direction.
Likewise each torque consists of three components in the coordinate system of the J marker: one about
the x-axis, one about the y-axis, and one about the z-axis. The force is linearly dependent upon the
relative displacement and the relative velocity of the two markers. The torque is dependent upon the
relative angle of rotation and the relative rotational velocity of the parts containing the specified markers.
BUSHING 21
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 (Kij and Cij, where i j) are zero for
the BUSHING statement. Only the diagonal coefficients (Kii and Cii) are defined for a BUSHING.
Fx
K 11 0
0 K 22 0
0 K 33 0
0 K 44 0
Ty
0 K 55 0
Tz
Fy
Fz
Tx
Vx
F1
0 c 22 0
Vy
F2
0 c 33 0
Vz
0 c 44 0
0 c 55 0
T2
0 c 66 z
T3
c 11 0
0 K 66
x
y
z
a
b
c
F3
T1
Fx, Fy, and Fz are the measure numbers of the translational force components in the coordinate system of
the J marker. The terms x, y, and z are the translational displacements of the I marker with respect to the
J marker measured in the coordinate system of the J marker. The terms Vx, Vy, and Vz are the time
derivatives of x, y, and z, respectively. The terms F1, F2, and F3 represent the measure numbers of any
constant preload force components in the coordinate system of the J marker.
Tx, Ty, and Tz are the rotational force components in the coordinate system of the J marker. The terms a,
b, and c are the relative rotational displacements of the I marker with respect to the J marker as expressed
in the x-, y-, and z-axis, respectively, of the J marker. The terms x , y , and z are the angular velocity
components of the I marker with respect to the J marker, measured in the coordinate system of the J
marker. The terms T1, T2, and T3 are the measure numbers of any constant torque in the coordinate
system of the J marker.
Adams/Solver (C++) applies an equilibrating force and torque to the J marker, as defined by the
following equations:
Fj=-Fi
Tj = - Ti -
x Fi
22 Adams/Solver
C++ Statements
is the instantaneous deformation vector from the J marker to the I marker. While the force at the J
marker is equal and opposite to the force at the I marker, the torque at the J marker is usually not equal
to the torque at the I marker because of the deformation.
The BUSHING only models linear bushings. The GFORCE or FIELD (with a FIESUB) may be used
to model nonlinear bushings.
Caution:
For the rotational constitutive equations to be accurate, at least two of the rotations (a, b,
c) must be small. That is, two of the three values must remain smaller than 10 degrees. In
addition, if a becomes greater than 90 degrees, b becomes erratic. If b becomes greater than
90 degrees, a becomes erratic. Only c can become greater than 90 degrees without causing
convergence problems. For these reasons, it is best to define your bushing such that angles
a and b (not a and c and not b and c) remain small.
Examples
BUSHING/1022, I=10, J=22, K=5000,5000,2000, C=5,5,2
, KT=50000,50000,0, CT=50,50,0
This BUSHING statement describes a bushing with translational spring rates of 5000 units in both the xaxis and the y-axis directions of Marker 22 and of 2000 units in the z-axis direction of Marker 22. The
corresponding damping rates for the force are 5 units in both the x- and y-axis directions of Marker 22
and 2 units in the z-axis direction of Marker 22. The rotational spring rates are 50000 units about the xand y-axis of Marker 22. The corresponding damping rates for the torque are 50 units in both the x- and
y-axis directions of Marker 22 and zero units in the z-axis direction of Marker 22. Since the z components
of KT and CT are zero, the I marker can rotate about the z-axis of the J marker without generating any
torque. There are no FORCE or TORQUE values because there is no initial load (preload) associated with
the input positions of the markers.
See other Forces available.
CONTACT 23
C++ Statements
CONTACT
The CONTACT statement lets you define a two- or three-dimensional contact between a pair of
geometric objects. Adams/Solver (C++) models the contact as a unilateral constraint, that is, as a force
that has zero value when no penetration exists between the specified geometries, and a force that has a
positive value when penetration exists between two geometries.
The CONTACT statement supports:
Multiple contacts
Dynamic friction
Contact between three-dimensional solid geometries
Contact between two-dimensional geometries
It does not support non-solid three-dimensional geometries, such as shells that do not encompass a
volume and sheets. It also does not support contact between a two-dimensional and a three-dimensional
geometry.
Adams/Solver (C++) has two geometry engines that it uses for three-dimensional contacts. It uses
Parasolid, a geometry toolkit from EDS/Unigraphics, and RAPID. Currently, RAPID is the default and
Adams/Solver (C++) supports version 2.01.
For two-dimensional 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.
Note:
You can only define two-dimensional contacts between bodies that are constrained to be in
the same plane. This is usually done with planar or revolute joints or an equivalent set of
constraints that enforce the planarity.
Failure to enforce planarity will result in a run-time error, when the bodies go out of plane
during a simulation.
The following table shows the legal combinations of geometry for the CONTACT statement. If you use
unsupported geometry combinations, you will receive an error.
24 Adams/Solver
C++ Statements
Arc
Circle
Curve
Point
Plane
X
X
X(Sphere
Only)
Box
Cylinder
Frustum
Ellipsoid
External
FlexBody
* FlexBody edges are considered to be curves. They may contact any other 2D geometry.
Note:
You can set the default geometry library. See the PREFERENCES statement.
CONTACT 25
C++ Statements
Format
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
NORMAL_ROUTINE=lib::func
IFLIP_GEOM=ida,...,idr
JFLIP_GEOM=idb,...,ids
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
26 Adams/Solver
C++ Statements
Arguments
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
Used when you specify the IMPACT model for calculating normal forces.
DAMPING defines the damping properties of the contacting material. You
should set the damping coefficient is about one percent of the stiffness
coefficient.
Range: DAMPING >0
DMAX = r
Used when you specify the IMPACT model for calculating normal forces.
DMAX defines the penetration at which Adams/Solver turns on full damping.
Adams/Solver uses a cubic STEP function to increase the damping coefficient
from zero, at zero penetration, to full damping when the penetration is
DMAX. A reasonable value for this parameter is 0.01 mm. For more
information, refer to the IMPACT function.
Range: DMAX > 0
EXPONENT=r
Used when you specify the IMPACT model for calculating normal forces.
Adams/Solver (C++) models normal force as a nonlinear spring-damper. If
PEN is the instantaneous penetration between the contacting geometry,
Adams/Solver calculates the contribution of the material stiffness to the
instantaneous normal forces as STIFFNESS * (PENALTY)**EXPONENT.
For more information, see the IMPACT function.
Exponent should normally be set to 1.5 or higher.
Range: 0 < EXPONENT
CONTACT 27
C++ Statements
FRICTION_ROUTINE =
library::function
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
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.
28 Adams/Solver
C++ Statements
IFLIP_GEOMETRY =
id1,id2,...,idN
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
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])
NORMAL_ROUTINE =
library::function
PENALTY=r
Used when you specify a restitution model for calculating normal forces.
PENALTY defines the local stiffness properties between the contacting
material. A large value of PENALTY ensures that the penetration, of one
geometry into another, will be small. Large values, however, will cause
numerical integration difficulties. A value of 1E6 is appropriate for systems
modeled in Kg-mm-sec. For more information on how to specify this value,
see Extended Definition.
Range: PENALTY > 0
POISSON
CONTACT 29
C++ Statements
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
STICTION_TRANSITION_VELOCITY> 5 ERROR
where ERROR is the accuracy requested of the integrator. Its default value is
1E-3.
Range: 0 < STICTION_TRANSITION_VELOCITY <
FRICTION_TRANSITION_VELOCITY
STIFFNESS=r
Specifies a material stiffness that you can use to calculate the normal force for
the impact model.
In general, the higher the STIFFNESS, the more rigid or hard the bodies in
contact are. Also note that the higher the STIFFNESS is, the harder it is for an
integrator to solve through the contact event.
Extended Definition
For more information on the key issues about the CONTACT statement, click a link below.
Contact Kinematics
Outward Normal Definition
Contact Kinetics
Contact Normal Force Calculation
Contact Friction Force Calculation
Contact Friction Torque Calculation
Contact Prediction
30 Adams/Solver
C++ Statements
The CONTACT statement lets you define contact between two geometry objects that you specify in
GRAPHICS entities in an Adams dataset (see the GRAPHICS statement). Adams/Solver (C++) supports:
Both two- and three-dimensional geometry.
Two-dimensional or planar contact between POINT, PLANE, CIRCLE, ARC, and CURVE
geometries.
Three-dimensional contact between CYLINDER, ELLIPSOID, BOX, FRUSTUM, and
EXTERNAL geometries.
Currently, Adams/Solver (C++) does not support contact between two- and three-dimensional
geometries.
The CURVE and the EXTERNAL graphics types are the generic geometry modeling entities. These
provide you with a way to specify arbitrarily complex two- and three-dimensional geometric shapes,
respectively. For both of these entities, the data is in files, which are usually generated by a geometry
modeling system. The CURVE object is specified as a series of x, y, and z points that are a function of
an independent curve parameter. The three-dimensional EXTERNAL object is more complex, and is
specified in the format of the geometry modeling system. Parasolid from Unigraphics is the default
geometry modeling system in Adams/Solver (C++). This is a well-recognized, state-of-the-art geometry
modeling system that is used in many CAD systems. Parasolid geometry files typically have the
extension xmt_txt.
During a simulation, the first step is to find out if the contact is occurring between the geometry pairs
identified in the CONTACT statements. If there is no contact, there is no force. If contact exists, the
geometry modeling system calculates the location of the individual contact points and the outward
normals to the two geometries at the contact point. Adams/Solver (C++) calculates the normal and slip
velocities of the contact point from this information. Adams/Solver (C++) then uses the velocities to
calculate the contact force at each individual contact.
Outward Normal Definition
The calculation of the outward normal for geometry is important because it defines where the material
lies and, therefore, determines the direction of the contact normal force.
For three-dimensional solids, which are closed by definition, the outward normal is implicit in the
geometry description, and there is no ambiguity in its definition.
For two-dimensional geometries, especially open curves, there is an ambiguity in calculating the outward
normal. Adams/Solver (C++) uses the specified geometry to calculate a default outward normal, but
allows the user to reverse this direction using the IFLIP_NORMAL and JFLIP_NORMAL arguments.
CONTACT 31
C++ Statements
The figure below shows an open curve with eight points defined in the coordinate system of the reference
marker (RM). The z-axis of the RM marker is directed out of the plane of the paper. This defines the binormal for the curve, denoted as
b.
The tangent at point 3 points towards point 4, and is denoted by t . The outward normals are defined as
follows:
n = tb
IFLIP_NORMAL and JFLIP_NORMAL simply reverse the direction of
n.
IFLIP_NORMAL and JFLIP_NORMAL only apply when a single ID is specified in IGEOM and
JGEOM. When lists of geometries are specified by IGEOM and JGEOM, use IFLIP_GEOMETRY and
JFLIP_GEOMETRY to flip normals.
Contact Kinetics
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.
32 Adams/Solver
C++ Statements
Persistent contact - Is characterized by contact for relatively long periods of time. External
forces acting between the two bodies serve to maintain continuous contact. Persistent contact is
modeled as a nonlinear spring damper, the stiffness modeling the elasticity of the surfaces of
contact, and the damping modeling the dissipation of energy. Two bodies are said to be in
persistent contact when the separation velocity, after a collision event, is close to zero. The
bodies, therefore, cannot separate after the contact.
Contact forces are calculated at each individual contact point. Individual contributions are summed up to
compute the net response of the system to the contact event.
Contact Normal Force Calculation
Two models for normal force calculations are available in Adams/Solver (C++):
IMPACT function model
Coefficient of restitution or the POISSON model
Both force models result from a penalty regularization of the normal contact constraints. Penalty
regularization is a modeling technique in mechanics, in which a constraint is enforced mathematically by
applying forces along the gradient of the constraint. The force magnitude is a function of the constraint
violation.
Contact between rigid bodies theoretically requires that the two bodies not penetrate each other. This can
be expressed as a unilateral (inequality) constraint. The contact force is the force associated with
enforcing this constraint. Handling these auxiliary constraint conditions is usually accomplished in one
of two ways, either through introduction of Lagrange multipliers or by penalty regularization.
For contact problems, the latter technique has the advantage of simplicity; no additional equations or
variables are introduced. This is particularly useful when treating intermittent contact and algorithmically
managing active and inactive conditions associated with unilateral constraints. Additionally, a penalty
formulation is easily interpreted from a physical standpoint. For example, the magnitude of the contact
reaction force is equal to the product of material stiffness and penetration between contacting bodies,
similar to a spring force. For these reasons, Adams/Solver (C++) uses a penalty regularization to enforce
all contact constraints. The disadvantage of the penalty regularization, however, is that you are
responsible for setting an appropriate penalty parameter, that is, the material stiffness. Furthermore, a
large value for the material stiffness or penalty parameter can cause integration difficulties.
Before presenting the contact normal force models in Adams/Solver (C++), it is helpful to clearly define
the contact constraints and associated kinematic and kinetic quantities. First, impenetrability of two
approaching bodies is measured with a gap function g, where a positive value of g indicates penetration.
Next, we denote the normal contact force magnitude as Fn, where a positive value indicates a separation
CONTACT 33
C++ Statements
force between the contacting bodies. With this notation in hand, the auxiliary contact constraints are
defined as:
g0
Fn > 0
Fn g = 0
dg
F n ------ = 0
dt
The first three equations reflect:
The impenetrability constraint
Separating, normal force constraint
Requirement that the normal force be nonzero only when contact occurs.
The fourth condition is called the persistency condition and it specifies that the normal force is nonzero
only when the rate of separation between the two bodies is zero. The last constraint is particularly
important when you are interested in energy conservation or energy dissipation.
You obtain the IMPACT force model by replacing the first three auxiliary contact conditions with the
following expression:
F n = k*(g**e)
where k (stiffness) is a scalar penalty parameter. The penalization becomes exact as k approaches infinity,
but otherwise allows small violation of the impenetrability constraint. It is important to note that ill
conditioning of the governing equations, and ultimately an integrator failure, will result as the stiffness
becomes excessively large. Therefore, you must appropriately select k while preserving the stability of
the solution.
You can also approximate the compliance of a body by correlating k to the bodies material and geometric
parameters; however, in doing so, you should recall the earlier remark concerning ill conditioning. In an
effort to incorporate general material constitutive relationships for the contacting bodies, as well as
facilitate time integration, Adams/Solver (C++) augments the previous expression with nonlinear
displacement-dependent, viscous damping terms. The general form of the IMPACT force function is then
given by:
where:
g represents the penetration of one geometry into another.
34 Adams/Solver
C++ Statements
dg
------ is the penetration velocity at the contact point.
dt
coefficient cmax.
Clearly, for cmax = 0 and e = 1, the original penalization is recovered. The POISSON force model is
dg
dt
derived from the persistency condition, Fn * ------ = 0. A penalty regularization of the fourth contact
constraint yields:
dg
dt
Fn = 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:
dg
F n = p ( 1 ) ------
dt
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 velocity-based friction model for contacts. Specifying the
frictional behavior is optional. The figure below shows how the coefficient of friction varies with slip
velocity.
CONTACT 35
C++ Statements
(-vs) = s
(vs) = - s
(0) = 0
(-vd) = d
(vd) = - d
where:
V: Slip velocity at contact point
vs: STICTION_TRANSITION_VELOCITY
36 Adams/Solver
C++ Statements
vd: FRICTION_TRANSITION_VELOCITY
s: MU_STATIC
d: MU_DYNAMIC
If Adams/Solver detects an angular velocity about the contact normal axis, it will apply a torque
proportional to the friction force. The reason for this is that the contact friction force, by itself, cannot
retard relative rotation between bodies; it can only retard relative translation.
The magnitude of the contact friction torque is given by the formula:
2
T = --- RF
3
2
Where R is the radius of the contact area (which is assumed to be circular). The coefficient --- comes from
3
If you need some other formulation of the friction torque, the only alternative is to write
your own friction force subroutine (CFFSUB). An example is given at the end of this
section.
Contact Prediction
Contact is fundamentally a discontinuous event. When two geometries come into contact:
A large normal force or an impulse is generated.
The velocities of the bodies change sign.
The accelerations are almost discontinuous, and have a large spike. This spike represents the
CONTACT 37
C++ Statements
This section explains how the various analysis modes deal with contact, and provides modeling tips on
how to successfully negotiate difficult contact events.
Contacts and Static Equilibrium
Both the static and quasi-static equilibrium analysis modes use Newton-Raphson (NR) iterations to solve
the nonlinear algebraic equations of force balance. The Jacobian matrix of first partial derivatives and the
residue of the equations of motion are used to set up an iterative scheme that normally converges to the
solution.
The Jacobian matrix is a measure of the stiffness matrix of the system. The inverse of the Jacobian is,
therefore, the compliance in the system. The NR algorithm ensures that the system solution moves in the
direction of most compliance (least stiffness). When a contact is active, the stiffness in the direction of
the normal force is high, so the NR algorithm modifies the system states to decrease this force. If a contact
is inactive, there is no stiffness in the direction of increasing contact. The NR algorithm will likely
compute a large movement in this direction, leading to excessive penetration. During the very next
iteration, since the contact force may turn on, a large stiffness is detected in this direction, and the
algorithm will change the system to dramatically reduce the amount of penetration. It is not uncommon
for the algorithm to overreact to this stiffness and move the system sufficiently to deactivate the contact.
The algorithm may never be able to resolve this discontinuity in the system.
Adams/Solver (C++) anticipates this situation and uses a contact-force-sensing mechanism to avoid
excessive contact. You can further enhance this method, however, by choosing the correct equilibrium
parameters.
Here are some modeling tips for aiding equilibrium (static) analysis (for more information on equilibrium
analysis, see the EQUILIBRIUM statement):
Use EQUILIBRIUM/DYNAMICS to specify that a quasi-dynamic algorithm is to be used to
find static equilibrium. For more information, see the EQUILIBRIUM statement.
If possible, make sure that all contacts are active, and each contact penetration is small. This will
ensure that the contact forces are small, and the system is aware of the contacts.
Set TLIMIT and ALIMIT small enough so gross contact violations are avoided.
Increase the maximum number of iterations, MAXIT, so that you can get to convergence in spite
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.
38 Adams/Solver
C++ Statements
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
and may solve the problem where the standard GSTIFF failed.
Always run a model without contact friction first, and refine the functioning model by adding
friction later.
CONTACT 39
C++ Statements
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.
40 Adams/Solver
C++ Statements
Caution:
An artificially low value of stiffness or penalty will not generate the necessary contact
If your model uses different length units than the stiffness properties you would like to
use, you need to scale the stiffness by:
length conversion factor**exponent
The reason for this is that the contact force due to penetration is defined as:
Adams/View will do this conversion for you if you change the units under Settings.
However, you will need to do it if you enter the parameters in different units.
Example:
k = 3800 N/mm
e = 2.0
current model units: force = N, length = m
stiffness to enter for contact = 3800*(1000**2) = 3.8e9
Also note that only length is raised to the exponent, so if you have a different force unit,
you would only scale it by the force conversion factor.
Contact cannot be defined between a Flexible Body and a list of 3D geometries
FLIP cannot be used with flexible bodies
The edges used in flexible body contact are modeled as 2D polylines. Higher order
interpolation is not allowed. Because they are 2D geometry, they may contact any other
2D geometry (rigid or flexible). They cannot be used in contact with 3D geometry.
The thickness of shell elements is ignored in flexible body contact.
CONTACT 41
C++ Statements
Tip:
If you notice that energy is dissipated during contact events, note the following:
Impact method - A three-dimensional contact with zero damping can exhibit
some dissipation of energy during the impact. The dissipation is due to the
numerics of the integration algorithm. To reduce the dissipation, reduce the time
step or tighten (decrease) the error tolerance.
Restitution method - A three-dimensional contact with coefficient of restitution
set to one should conserve energy. If you notice some dissipation, try increasing
the PENALTY argument. Recall that the larger the PENALTY argument, the more
exact the contact constraint will be enforced. In the case of intermittent contact and
a restitution coefficient set to one, a larger penalty parameter more exactly
enforces the conservation of momentum during the contact event.
The PENALTY argument is analogous to the stiffness in the IMPACT function.
The larger the stiffness, the smaller the penetration.
42 Adams/Solver
C++ Statements
The table below shows material types and their commonly used values for the dynamic coefficient of
friction and restitution.
Material 1:
Material 2:
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
0.30
0.20
0.85
0.23
0.16
0.85
0.30
0.20
0.85
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
0.15
0.70
Acrylic
Acrylic
0.20
0.15
0.70
Nylon
Dry aluminium
0.10
0.06
0.70
Nylon
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
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
CONTACT 43
C++ Statements
Material 1:
Material 2:
Greasy rubber
0.56
0.95
Greasy rubber
Acrylic
0.63
0.56
0.95
Greasy rubber
Nylon
0.63
0.56
0.95
Greasy rubber
Dry rubber
0.63
0.56
0.95
Greasy rubber
Greasy rubber
0.63
0.56
0.95
Caution:
An artificially low value of stiffness or penalty will not generate the necessary contact
forces. You may see a loss of energy when none is expected.
If you find that your model response changes as the number of output steps is modified,
use INTEGRATOR/HMAX=value to control the integrator step-size and the quality of the
solution.
modeling techniques, such as making sure that the objects expected to be in contact at
equilibrium are initially in contact in the input configuration. If this is not feasible, make sure
that the objects expected to be in contact are very close so that the contacts can be detected
during equilibrium iterations. It will also help to consider the appropriate TLIM and ALIM to
help limit the perturbations for finding equilibrium. Use dynamic equilibrium for models that
have difficulty finding static equilibrium.
Thin shells - During one solution step, Adams may take several integrator steps in order to
satisfy predictor-corrector requirements. If input geometry is very thin, there is a possibility that
one geometry may completely pass through another, resulting in invalid volume of intersection
calculations. This can result in missed contacts, passthroughs, or generation of unusually high
contact force. Reducing hmax can help prevent this problem.
Friction - Friction calculations are highly discontinuous and can cause numerical convergence
problems, especially at low relative velocities. The friction difficulties compound the already
difficult contact evaluations. Whenever possible, run a model without contact friction first, and
refine the functioning model by adding friction later. If the addition of frictional forces causes
numerical difficulties or simulation slowdowns, gradually increase the values for
STICTION_TRANSITION_VELOCITY and FRICTION_TRANSITION_VELOCITY. Also
reduce the coefficients of friction, which usually helps the integrator.
44 Adams/Solver
C++ Statements
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 point-to-curve, curve-to-curve, 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 three-dimensional geometries.
star_geneva.xmt_txt is a geometry file that was generated by Parasolid. Adams/View or any CAD
package using Parasolid as its geometry package can generate this file. It contains two geometries,
SOLID4 and SOLID3. Contact is to be defined between these two geometries.
CONTACT 45
C++ Statements
Below is an example of lists of geometry. Geometries 11 and 12 must belong to one part. Geometries 13,
14, and 15 must all be on one part. Geometries 12, 13, and 15 are flipped.
CONTACT/1,
, IGEOM = 11, 12
, JGEOM = 13, 14, 15
, IFLIP_GEOMETRY = 12
, JFLIP_GEOMETRY = 13, 15
, IMPACT,
, STIFFNESS = 1E6,
, DAMPING = 10,
, DMAX = 0.1,
, EXPONENT = 2.2
Below is an example of user-written subroutines in contacts. The normal force subroutine (CNFSUB)
and the friction force subroutine (CFFSUB) are in the same library (cnforc1).
CONTACT/1
, IGEOM = 7
, JGEOM = 6
46 Adams/Solver
C++ Statements
,
,
,
,
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 example below demonstrates how to specify contact between two two-dimensional 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
CONTACT 47
C++ Statements
,
,
,
,
,
,
,
IEDGE = 2
JGEOM = 1
IMPACT
STIFFNESS = 1.0E+005
DAMPING = 10
DMAX = 0.1
EXPONENT = 2.2
48 Adams/Solver
C++ Statements
COUPLER
A COUPLER statement relates the translational and/or the rotational motion of two or three joints.
Format
Arguments
ROUTINE=lib1::cou1,
lib2::cou2, lib3::cou3
COUPLER 49
C++ Statements
SCALES=[r1,]r2[,r3]
50 Adams/Solver
C++ Statements
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:
the I marker origin with respect to the J marker origin along the J marker z-axis.
Positive translations are along the positive z-axis of J, and negative translations are
along its negative z-axis.
To measure rotational motion, Adams/Solver (C++) finds the displacement of the
x-axis of the I marker with respect to the x-axis of the J marker about the common
z-axis of the I and the J markers. To determine the positive sense of rotation, apply
the right-hand rule to the z-axis.
The COUPLER can relate any combination of translational and rotational motions.
models only the reaction forces that are along or about the degrees of freedom that
are being coupled.
You can model a pair of mating spur gears as a COUPLER between two
REVOLUTE joints. If (I1, J1) are the I and J markers of the first joint and (I2, J2)
are the I and J markers of the second joint, the COUPLER constraint is:
AZ(I1,J1) * scale_1 + AZ(I2,J2) * scale_2 = 0
where scale_1 and scale_2 are the radii of the two gears.
The reaction forces generated by the COUPLER are the torques at the two joints
required to maintain the constraint shown above. The reaction on the first joint is
the torque about the z-axis of marker J1. The reaction on the second joint is the
torque about the z-axis of marker J2. You can compute the tooth force from these
torques, but Adams/Solver (C++) does not explicitly solve for them.
You can also model a rack and pinion gear as a COUPLER relating the rotation in
a REVOLUTE joint, with the translation in a TRANSLATIONAL joint. If (I1, J1)
are the I and J markers of the REVOLUTE joint and (I2, J2) are the I and J markers
of the TRANSLATIONAL joint, the COUPLER constraint is:
AZ(I1,J1) * scale_1 + DZ(I2,J2,J2) * scale_2 = 0
where scale_1 is the pinion radius, and scale_2=1.
The COUPLER reaction on the REVOLUTE joint is a torque about the z-axis of
Marker J1, and the reaction on the TRANSLATIONAL joint is a force along the zaxis of Marker J2.
COUPLER 51
C++ Statements
Caution:
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
requires you to input one or more entries for the TYPE argument, depending on the
order of the cylindrical joint(s) in the JOINTS argument list. Adams/Solver (C++)
must have a type entry for every cylindrical joint and a place holder entry for every
joint entered before a cylindrical joint on the JOINTS argument.
Examples
COUPLER/01, JOINTS=4,6, TYPE=T:R, SCALES=90D, -1
This COUPLER statement relates the translational motion at Joint 4 to the rotational motion at Joint 6.
Joint 4 is either a translational or cylindrical joint, and Joint 6 is either a revolute or cylindrical joint. The
SCALES argument indicates the relationship:
(90D)q1 - q2 = 0
or
(90D)q1 = q2.
In other words, when q1 is a positive translation of one system unit, q2 is a positive rotation of 90 degrees.
Internal to Adams/Solver (C++), all values entered in degrees are converted to radians for calculation
purposes. The figure below shows a coupler.
Coupler
52 Adams/Solver
C++ Statements
CURVE
The CURVE statement defines a three-dimensional parametric curve that you can reference using PTCV,
CVCV, GRAPHICS statements, and function expressions.
Format
Arguments
CLOSED
Specifies that the curve meets at the ends. If you specify CURVE_POINTS,
Adams/Solver (C++) attempts to compute a curve that meets at the ends and has
continuous first and second derivatives across the closure. If you specify
FUNCTION, you must ensure that the defined curve meets at the ends and has
continuous first and second derivatives across the closure. If the curve is closed,
the first and last control or curve points must be the same. During a simulation,
Adams/Solver (C++) moves a PTCV or CVCV contact point across the closure,
if necessary.
CURVE_POINTS
FUNCTION=USER
(r1[,...,r30])/
MATRIX=id
Specifies a MATRIX statement that contains data for a curve. The matrix
contains the x, y, and z coordinates of the curve points. The matrix should have
a row for each point and three columns containing the x-, y-, and z-coordinates
of the points. You must supply at least four curve points. The first and last points
must be the same for a closed curve.
CURVE 53
C++ Statements
MAXPAR=r
Specifies the maximum value of the curve parameter for a user-written curve.
Adams/Solver (C++) uses this value when drawing a curve graphic. The
maximum parameter value is always 1.0 for curves you define using
CURVE_POINTS.
Default: 1.0
MINPAR=r
Specifies the minimum value of the curve parameter for a user-written curve.
Adams/Solver (C++) uses this value when drawing a curve graphic. The
minimum parameter value is always -1.0 for curves you define using
CURVE_POINTS.
Default: -1.0
OPEN
Specifies that the curve does not meet at the ends. Adams/Solver (C++) does not
allow a PTCV or CVCV contact point to move beyond the end of the curve.
ORDER
ROUTINE=libname
::subname
Specifies an alternative library and name for the user subroutine CURSUB.
Learn more about the ROUTINE Argument.
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
54 Adams/Solver
C++ Statements
CURVE 55
C++ Statements
Adams/Solver (C++) computes the control points internally from the curve points.
To use a different type of curve, or to model an analytically-defined curve such as a helix, you can write
a CURSUB user-written subroutine. When providing a CURSUB, you can also specify MINPAR and
MAXPAR to define the limits of the curve. These default to -1 and +1, respectively.
A curve is OPEN or CLOSED. A CLOSED curve meets at the ends, connecting the curve at minimum
and maximum parameter values. Adams/Solver (C++) automatically moves a PTCV or CVCV contact
point across the closure of a CLOSED curve, if needed. For instance, you can model a cam profile as a
CLOSED curve, and Adams/Solver (C++) allows the follower to move across the closure as the cam
rotates.
Caution:
Adams/Solver (C++) applies a force to prevent a PTCV or CVCV contact point from
moving off the end of an open curve. For an open curve that is referenced by a PTCV or
CVCV constraint, be sure to define an expected range of contact.
Examples
CURVE/5, OPEN, CURVE_POINTS, MATRIX=2
This statement creates an open curve using the curve point coordinates in MATRIX/2. Adams/Solver
(C++) computes a B-spline curve to fit the points.
CURVE/7, CLOSED, CURVE_POINTS, MATRIX=1, ORDER=2
This statement creates a closed curve of order 2 (polyline) using the curve point coordinates in
MATRIX/1. Adams/Solver (C++) computes a B-spline curve to fit the points.
56 Adams/Solver
C++ Statements
Applications
The PTCV, CVCV, and GRAPHICS statements reference the CURVE statement:
The PTCV uses a curve to define a point-curve constraint.
The CVCV statement uses two curves to define a curve-curve constraint.
The GRAPHICS statement generates a graphic depicting the curve.
In each case, you must specify a reference marker that identifies the part to which the curve attaches and
the coordinate system to which Adams/Solver (C++) applies the curve coordinates. You can also
reference a curve in a function expression, much like the cubic or Akima splines (see the CURVE
function).
See other Reference data available.
CVCV 57
C++ Statements
CVCV
The CVCV statement defines a curve-to-curve constraint that restricts a planar curve on one part that is
to be in contact with, and tangent to, a planar curve on a second part. The curves must lie in the same
plane, but the parts to which they are attached may undergo three-dimensional motion.
Format
Arguments
ICURVE=id Specifies the identifier of a CURVE statement from which Adams/Solver constructs the
first curve. The IRM marker specifies the coordinate system in which the x, y, z
coordinates of ICURVE are specified. The curve is attached rigidly to the part containing
the IRM marker. The z component of the curve must be zero. As a result, the curve lies
in the x-y plane of the IRM marker.
IDISP=x,y,z Specifies the initial point of contact on the first curve. Adams/Solver (C++) uses a point
on the curve nearest to that specified if the point specified is not exactly on the curve. By
default, the contact point is specified in the IRM marker coordinate system. You may
supply the IICM argument and enter IDISP in IICM marker coordinates if another
coordinate system is more convenient.
Adams/Solver (C++) assembles the system with the contact at the specified point on the
curve if you supply IDISP. Adams/Solver (C++) assumes the initial contact is at the point
on the first curve closest to the second curve at the input configuration if you do not
supply IDISP. In this case, Adams/Solver (C++) may adjust that contact point to maintain
other part or constraint initial conditions.
58 Adams/Solver
C++ Statements
IFLOAT=id
Specifies the identifier of a floating marker. Adams/Solver (C++) positions the origin of
the IFLOAT marker to be at the instantaneous point of contact on the first curve, which
is also the global position of the JFLOAT marker on the second curve. Adams/Solver
(C++) orients the IFLOAT marker so that its x-axis is along the tangent at the
instantaneous contact point, its y-axis is along the instantaneous normal, and its z-axis
along the resultant binormal. For a CVCV constraint, the binormal of ICURVE is always
parallel to the z-axis of the IRM marker. The IFLOAT and IRM markers must lie on the
same part.
IICM=id
Specifies the identifier of a fixed marker defining the coordinate system in which the
values for IDISP are defined. The IICM marker must be on the same part as the IRM
marker.
Default: IRM marker
IRM=id
Specifies the identifier of a fixed marker on the part containing ICURVE. The IRM
marker identifies not only the part that the ICURVE is attached to, but also identifies the
coordinate system in which the coordinates of ICURVE are specified. Adams/Solver
(C++) constructs the ICURVE in the x-y plane of the IRM marker coordinate system. The
IFLOAT and IRM markers must lie on the same part.
IVEL=r
Specifies the magnitude of the initial velocity of the contact point relative to the part
containing ICURVE. This is the speed at which the contact point is initially moving
tangent to the curve. IVEL is negative if the contact point is moving towards the start of
the curve, positive if the contact point is moving toward the end of the curve, or zero if
the contact point is stationary on the curve.
Adams/Solver (C++) gives the contact point the specified initial speed along the first
curve if you supply IVEL. Adams/Solver (C++) assumes the initial velocity is zero if you
do not supply IVEL, but may adjust the velocity to maintain other part or constraint initial
conditions.
Default: 0
JCURVE=id Specifies the identifier of a CURVE statement from which Adams/Solver (C++)
constructs the second curve. The JRM marker specifies the coordinate system in which
the x, y, z coordinates of JCURVE are specified. The curve is attached rigidly to the part
containing the JRM marker. The z component of the CURVE must be zero. As a result,
the curve lies in the x-y plane of the JRM marker.
CVCV 59
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 x-axis is along the tangent at the instantaneous contact
point, its y-axis is along the instantaneous normal, and its z-axis along the resultant binormal. For a CVCV constraint, the bi-normal of JCURVE is always parallel to the z-axis
of the JRM marker. The JFLOAT and JRM markers must lie on the same part.
JICM=id
Specifies the identifier of a fixed marker defining the coordinate system in which the
values for JDISP are defined. The JICM marker must be on the same part as the JRM
marker.
Default: JRM marker
JRM=id
Specifies the identifier of a fixed marker on the part containing JCURVE. The JRM
marker identifies not only the part the JCURVE is attached to, but also the coordinate
system in which the coordinates of JCURVE are specified. Adams/Solver (C++)
constructs JCURVE in the x-y plane of the JRM marker coordinate system. The JFLOAT
and JRM markers must lie on the same part.
JVEL=r
Specifies the magnitude of the initial velocity of the contact point relative to the part
containing JCURVE. This is the speed at which the contact point is initially moving
tangent to the curve. JVEL is negative if the contact point is moving towards the start of
the curve, positive if the contact point is moving toward the end of the curve, and zero if
the contact 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
60 Adams/Solver
C++ Statements
Extended Definition
The CVCV statement defines a curve-to-curve constraint that restricts a planar curve on one part to be in
contact with, and tangent to, a planar curve on a second part. The curves must lie in parallel planes.
Adams/Solver (C++) constructs the first curve from the ICURVE curve and IRM marker, and the second
curve from the JCURVE curve and JRM marker. In both cases, the CURVE statement (ICURVE or
JCURVE) defines x and y coordinates along the curve as a function of an independent parameter (u). The
z coordinates of the curves must be zero. The reference marker (IRM or JRM) defines the part on which
the constraining curve is attached and the coordinate system in which Adams/Solver (C++) applies the
coordinates from the CURVE statement.
Both ICURVE and JCURVE may be open or closed curves, defined analytically or as a set of discrete
data points. Figure 1 below shows a curve-to-curve constraint.
A CVCV statement removes two degrees-of-freedom from the system. Adams/Solver restricts the
motion of the parts such that the curves are always in contact and the curves are tangent at the contact
point. The first curve may slide or roll on the second, but may not move perpendicular to the curve
tangents at the contact.
Figure 1
Tip:
Curve-To-Curve Constraint
More than one CVCV statement can reference the same CURVE statement. You can enter
one CURVE statement if the mechanism contains several similar contacts and use it with
several CVCV constraints, each with a different IRM and JRM marker.
CVCV 61
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 over-constrain a system using the CVCV constraint. For
62 Adams/Solver
C++ Statements
Figure 2
Examples
CVCV/20, IFLOAT=402, ICURVE=11, IRM=401, JFLOAT=502,
, JCURVE=12, JRM=501
This statement creates a curve-curve constraint between a curve on the part containing Markers 401 and
402 and a curve on the part containing Markers 501 and 502. CURVE/11 defines the first curve in the
coordinate system of Marker 401. CURVE/12 defines the second curve in the coordinate system of
Marker 501.
Applications
The CVCV statement models one curve rolling or slipping along another, such as in a cam-follower
mechanism. Figure 3 illustrates a cam follower.
Adams/Solver (C++) automatically moves the contact across the closure as needed when a closed curve
is specified in the CURVE statement. This means that the cam may rotate as many times as needed during
the simulation.
A point-to-curve constraint, PTCV statement, can be used if the follower is small and sharp enough to be
considered a point.
The curves always maintain contact, even when the dynamics of the system would actually lift one curve
off the other, because CVCV is a geometric spatial constraint. You can examine the constraint forces to
determine if lift-off should have occurred. If an accurate simulation of intermittent contact is required,
you should model the contact forces directly using a VFORCE.
The CVCV statement models only one contact. Therefore, if the curves have contact at more than one
point you must enter a CVCV statement for each contact, each with a displacement initial condition
(IDISP and JDISP) near the appropriate point.
CVCV 63
C++ Statements
Figure 3
Cam-Follower Mechanism
64 Adams/Solver
C++ Statements
DEBUG
The DEBUG statement outputs data that helps you debug a simulation.
Format
DEBUG/ EPRINT
[]
[[ ]]
,JMDUMP
,RHSDUMP
, MATLAB
DEBUG 65
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
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
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
66 Adams/Solver
C++ Statements
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:
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 second-order polynomial to guess the solution. Using a time
step of 7.25694E-04, the integration step goes from 6.458333333E-04 to 1.371527778E-03.
After the first iteration, the z velocity equation of PART/245330 has the largest error: its absolute value
is 2E+00. The z coordinate of PART/245330 changes the most during the first iteration. The absolute
value of the change is 8.E-04. Adams/Solver (C++) updates the Jacobian before the first iteration, but not
before the second or third.
DEBUG 67
C++ Statements
Figure 4
68 Adams/Solver
C++ Statements
DIFF
The DIFF statement creates a user-defined state variable and defines a first-order differential equation
that describes it.
Format
DIFF 69
C++ Statements
Argument
IMPLICIT
ROUTINE=libname::subname
70 Adams/Solver
C++ Statements
Extended Definition
The DIFF statement creates a user-defined state variable and defines a first-order 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 user-written subroutines can access the DIFF state variable and its
derivative. Function expressions access the value by using the function DIF(id) and the derivative by
using DIF1(id) (see DIF and DIF1 functions). In each case, id specifies the identifier of the DIFF
statement that defines the variable. User-written subroutines access the value and derivative by calling
the subroutine SYSFNC (see the SYSFNC subroutine).
The function can be defined by a function expression, or by providing a user-written subroutine. Because
Adams/Solver (C++) typically handles a function expression more efficiently than a user-written
subroutine, it is recommended that you use a function expression whenever possible.
The DIFF may be defined in either explicit or implicit form. The following equation defines the explicit
form of a differential equation:
y = f (y, u, t)
where:
You need to use the implicit form if the first derivative of the state variable cannot be isolated. The
following equation defines the implicit form of a differential equation:
0 = F( y,
y , u, t)
DIFF 71
C++ Statements
Caution:
Although you can currently use a DIFF statement to define an implicit, algebraic
(rather then differential) equation, Adams/Solver (C++) might not allow this in the
future. You should use VARIABLE statements to define algebraic equations
instead.
During a static analysis, Adams/Solver (C++) finds equilibrium values for user-
defined differential variables (DIFFs, GSEs, LSEs, and TFSISOs), as well as for
the displacement and force variables. This changes the initial conditions for a
subsequent analysis. Adams/Solver (C++) sets the time derivatives of the userdefined variables to zero if STATIC_HOLD is not specified during a static
analysis, and uses the user-supplied initial-condition values only as an initial guess
for the static solution. Generally, the final equilibrium values are not the same as
the initial condition values. Adams/Solver (C++) then uses the equilibrium values
of the user-defined variables as the initial values for any subsequent analysis, just
as with the equilibrium displacement and force values.
However, the user-specified initial conditions are retained as the static equilibrium
values if STATIC_HOLD is specified. Thus, the final equilibrium values are the
same as the user-specified initial conditions. Note that this does not guarantee that
the time derivatives of the user-defined variable are zero after static analysis.
Examples
DIFF/11, IC=1.75,
, FUNCTION = -2.0*DIF(11) + 4.0 + SIN(TIME)
DIFF/12, IC=1.75, IMPLICIT,
, FUNCTION = DIF1(12) + 2.0*DIF(12) - 4.0 - SIN(TIME)
y as shown
y + 2y - 4 - sin (t) = 0
Applications
The DIFF statement defines a first order, linear or nonlinear, explicit or implicit, ordinary differential
equation for Adams/Solver (C++) to integrate along with the dynamic simulation of a multibody system.
The equation may be independent of the rest of the problem or it may depend upon any variable in the
72 Adams/Solver
C++ Statements
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.
END 73
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.
74 Adams/Solver
C++ Statements
ENVIRONMENT
Using the ENVIRONMENT statement is an alternative way of setting an Adams/Solver (C++) runtime
environment variable. For example, rather than using the setenv command when working with the
Linux operating system, one may use the ENVIRONMENT statement instead.
One feature of the ENVIRONMENT statement is the following, the execution of this statement does not
modify the operating system environment; it only affects the Adams/Solver (C++) runtime environment
for the model being run. When the simulations are finished, the original operating system environment
is left intact.
A second feature is related to the collection of environment variables one may set. Only environment
variables related to the Adams/Solver (C++) may be set. For example, you may not use this statement to
set an environment variable used by other products.
Format
ENVIRONMENT NAME = c
ENVIRONMENT NAME = c, VALUE = c
ENVIRONMENT NAME = c, UNSET
Arguments
NAME=c
VALUE=c
UNSET
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
ENVIRONMENT 75
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 User-environment variables defined in data/command files
--------------------------------------------------------------MSC_ADAMS_SOLVER_BEAM_MODEL=NONLINEAR
Enforces Adams/Solver C++ to use a different beam model.
Options are LINEAR, STRING, NONLINEAR.
Observe Adams/Solver prints a brief description of the environment variable. Notice you do not
need to modify the operating system environment.
2. Let's assume you define the following environment variable from a Linux shell:
% setenv MSC_ADAMS_SOLVER_BEAM_MODEL=LINEAR
This environment variable specifies using a linear model for the BEAM formulation. Next, you
run a model defined by an ADM dataset including the following statement:
ENV/
, NAME=MSC_ADAMS_SOLVER_BEAM_MODEL,
, VALUE=NONLINEAR
Notice the intent is to overwrite any previous definition of the variable. Running the model,
Adams/Solver (C++) will print the following message:
76 Adams/Solver
C++ Statements
Observe Adams/Solver prints the note "Overwrites a previous definition" indicating that the
ENVIRONMENT statement overwrote the value of the environment variable set in the operating
system.
3. In this example we use the ENVIRONMENT statement to unset any previous definition of an
environment variable.
ENV/
, NAME=MSC_ADAMS_SOLVER_BEAM_MODEL, UNSET
If the environment variable was not defined, the statement is ignored with a warning message.
Caution:
EQUILIBRIUM 77
C++ Statements
EQUILIBRIUM
The EQUILIBRIUM statement specifies error tolerances and other parameters for static equilibrium and
quasi-static equilibrium analyses.
Format
EQUILIBRIUM/
{}
[[ ]]
,ERROR = r
,IMBALANCE = r
,MAXIT = i
,STABILITY = r
,TLIMIT = r
,METHOD =i
,ATOL = r
,RTOL = r
,MAXITL = i
,ETAMAX = r
,ETA = r
ALIMIT = r
Arguments
ALIMIT=r
Specifies the maximum angular increment allowed per iteration during a static
or quasi-static equilibrium analysis. The default units for ALIMIT are radians.
To specify ALIMIT in degrees, add a D after the value.
Default: 0.17453 (10 D)
Range: ALIMIT > 0
ERROR=r
78 Adams/Solver
C++ Statements
IMBALANCE=r
MAXIT=i
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 NewtonRaphson iteration. For each iteration, T or TRUE indicates that Adams/Solver
(C++) evaluates the Jacobian and F or FALSE indicates that Adams/Solver
(C++) does not evaluate the Jacobian. Thus, cj determines whether or not
Adams/Solver (C++) evaluates the Jacobian at the jth iteration. If necessary,
Adams/Solver (C++) repeats the pattern of evaluations until it reaches the
maximum number of iterations (MAXIT). The number of Ts or TRUEs and Fs
or FALSEs together must be at least one and no more than ten.
Default: T:T:T:T:T:T:T:T:T:T, which evaluates the Jacobian at every iteration
(for example, the unmodified Newton-Raphson algorithm).
STABILITY=r
Specifies the fraction of the mass and damping matrices (subsets of the
equilibrium Jacobian matrix) Adams/Solver (C++) adds to the stiffness matrix
(a subset of the equilibrium Jacobian matrix) during static simulations
performed using static analyses. Adding a fraction of the mass and damping
matrices to the stiffness matrix can stabilize the iteration process and prevent
the iteration from diverging. Often the stiffness matrix is singular for a system
because the system is neutrally stable (for example, the system moves in
certain directions without affecting the potential energy). Adding a fraction of
the mass and damping matrices to the stiffness matrix removes this singularity
and makes it possible to solve for equilibrium positions. The value of
STABILITY does not affect the accuracy of the solution, but it does affect the
rate of convergence of the iteration process.
Default: 1.0E-05
Range: STABILITY >0
TLIMIT=r
EQUILIBRIUM 79
C++ Statements
METHOD=i
Specifies the option which determines the static solver method to be used for
equilibrium solution.
1. ORIGINAL, for running only the ORIGINAL Solver
2. ADVANCED, runs, in order, the following methods until one shows
progress:
a. ORIGINAL
b. ORIGINAL+Krylov
c. ORIGINAL+UMF
d. Newton+Krylov
e. Tensor-Krylov block-3
f. Tensor-Krylov block-2+
3. AGGRESSIVE, runs, in order, the following methods until one shows
progress:
a. ORIGINAL
b. ORIGINAL+Krylov
c. ORIGINAL+UMF
d. Newton+Krylov
e. Tensor-Krylov block-3
f. Tensor-Krylov block-2+
g. Broyden-Armijo
h. Trust-Region
4. ALL, runs, in order, all the available methods, until one shows
progress:
a. ORIGINAL
b. ORIGINAL+Krylov
c. ORIGINAL+UMF
d. Newton+Krylov
e. Tensor-Krylov block-3
f. Tensor-Krylov block-2+
g. Broyden-Armijo
h. Trust-Region
i. Hooke-Jeeves
Default: ORIGINAL
80 Adams/Solver
C++ Statements
ATOL
RTOL
MAXITL
Specifies the maximum number of allowed inner loops in all the solvers.
ORIGINAL, ORIGINAL+Krylov and ORIGINAL+UMF solver methods
ignore this parameter. For Hooke-Jeeves method, allowed budget of function
evaluations is set to MAXITL*N, where N is the size of the problem (number
of unknowns).
Default: 40
Range: > 0
ETAMAX
Specifies the maximum threshold for the error tolerance of the linear Krylov
solver (for Newton+Krylov and Tensor-Krylov methods) that solves the linear
systems required by Krylov algorithm. Maximum error tolerance for residual
in inner iteration. The inner iteration terminates when the relative linear
residual is smaller than eta*| F(x_c) |. eta is determined by the modified
Eisenstat-Walker formula if etamax > 0. If etamax < 0, then eta = |etamax| for
the entire iteration.
Default: 0.9
Range: 0.0 < ETAMAX < 1.0
ETA
Specifies the initial residual tolerance for the linear Krylov Solver for
Tensor_Krylov method. The Tensor-Krylov ETA parameter is maintained
adaptively by the Krylov algorithm but ETA is the indicated starting value,
while ETAMAX is the maximum threshold for ETA.
Default: 1.0e-4
Range: 0.0 < ETA < 1.0
Specifies the dimensionless radius of the trust-region for Trust-region method.
The smaller the value, the more the refinement of Trust-region solution (hence
more work).
Range: 0.0 < ETA < 0.25
EQUILIBRIUM 81
C++ Statements
Extended Definition
The EQUILIBRIUM statement specifies error tolerances and other parameters for static and quasi-static
equilibrium analyses. This statement is used when you want to change one or more of the tolerances or
other parameters from the default values.
Use the SIMULATE command to request one of the following:
Single static equilibrium analysis.
Series of static equilibrium analyses over time, for example, a quasi-static equilibrium analysis.
Static and quasi-static equilibrium analyses solve for displacement and static forces, but not for velocity,
acceleration, or inertia forces which are all assumed to be zero. To perform a static equilibrium analysis,
Adams/Solver (C++) finds the configuration and static forces for which all the static forces in the system
balance after being evaluated at the current simulation time. This process requires the solution of a set of
nonlinear algebraic equations. Adams/Solver (C++) uses the modified Newton-Raphson iteration to
solve these equations.
If neither an EQUILIBRIUM command nor an EQUILIBRIUM statement is issued in an Adams/Solver
session, the default values for ALIMIT, ERROR, IMBALANCE, MAXIT, PATTERN, STABILITY, and
TLIMITare used when performing a static equilibrium or quasi-static equilibrium analysis.
Currently, there are 8 different types of solvers in addition to the Static Solver that was originally in the
code (ORIGINAL solver). ORIGINAL Solver used the Sparse linear solver:
1. ORIGINAL+Krylov has the same logic flow as the ORIGINAL but uses linear GMRES
algorithm [1.].
2. ORIGINAL + UMF has the same logic flow as the ORIGINAL but uses linear UMF algorithm
[6.].
3. Newton+Krylov nonlinear solver uses a Newton + GMRES algorithm [1.].
4. Tensor-Krylov block 3 solver uses Tensor-Krylov method [2.], flavor block 3.
5. Tensor-Krylov block 2+ solver uses Tensor-Krylov method [2.], flavor block 2+.
6. Broyden-Armijo solver uses Broyden method [1.] with an Armijo line-search [1.] to account for
global strategies.
7. Trust-Region method Solver uses the Trust Region optimization algorithm [3.].
8. Hooke-Jeeves solver uses the Hooke-Jeeves optimization method [4.].
82 Adams/Solver
C++ Statements
Tip:
Using the PATTERN argument to request less frequent evaluations of the Jacobian
matrix may decrease the computation time. However, infrequent evaluations could
also be more expensive since the modified Newton-Raphson algorithm might
require more iterations due to the slower convergence rates.
Use the ALIMIT and TLIMIT arguments to limit incrementing displacement
specify a particular method to be used for equilibrium solution. The variable works
as an integer bit-mask with 9 bits, corresponding to the eight solvers above in the
order: ORIGINAL (bit0), ORIGINAL+Krylov (bit1), ORIGINAL+UMF
(bit2), Newton+Krylov (bit3), Tensor-Krylov block-3 (bit4), Tensor-Krylov
block-2+ (bit5), Broyden-Armijo (bit6), Trust-Region (bit7), Hooke-Jeeves
(bit8). The lowest order bit, if set to 1, means ORIGINAL solver will be used. The
highest order bit, if set to 1, means Continuation method will be used.
For example if the user wants to enforce the exclusive use of only
ORIGINAL+Krylov, ORIGINAL+UMF, Broyden-Armijo, and Trust-Region
solvers, then the bits that must be set are bit1, bit2, bit5, and bit7. Hence, the
binary value of MSC_USE_ALTERNATE_SOLVERS is 10100110, i.e.,
MSC_USE_ALTERNATE_SOLVERS=2^7+2^5+2^2+2^1=128+32+4+2=166.
Caution:
the system is neutrally stable, STABILITY must be greater than zero in order for
Adams/Solver (C++) to compute static equilibrium.
Static equilibrium, or quasi-static equilibrium analyses often have multiple
EQUILIBRIUM 83
C++ Statements
Examples
EQUILIBRIUM/ STABILITY=0.01, TLIMIT=10
, IMBALANCE=1.0E-05
This EQUILIBRIUM statement instructs Adams/Solver (C++) to use these values instead of the defaults
when performing a static or quasi-static equilibrium analysis. It adds 0.01 times the sum of the mass and
damping matrices to the stiffness matrix during an equilibrium iteration. It limits the translation in any
one iteration to 10 length units. The force imbalance in the system must be less than 1.0E-05 force units
for Adams/Solver (C++) to consider the system to be in equilibrium.
Bibliography:
1. Iterative Methods for Linear and Nonlinear Equations C.T. Kelley, SIAM 1995
2. Tensor-Krylov Methods for Solving Large-Scale Systems of Nonlinear Equations Brett W. Bader,
Ph.D. Thesis, 2003
3. Numerical Optimization Jorge Nocedal, Stephen J. Wright, Springer 1999
4. Iterative Methods for Optimization C.T. Kelley, SIAM 1999
5. Introduction to Numerical Continuation Method E.L. Allgower and K. Georg, 1990
6. MD Nastran Quick Reference Guide.
See other Analysis parameters available.
84 Adams/Solver
C++ Statements
FEMDATA
The FEMDATA statement produces data files of component loads, deformations, stresses, or strains for
input to subsequent finite element or fatigue life analysis. You use the OUTPUT statement to specify the
type of file FEMDATA produces. Except for HOTSPOTS table and the old style (.fem) file, FEMDATA
will not output data to any files unless you specify the format in the OUTPUT statement.
Format
FEMDATA 85
C++ Statements
Arguments
CRITERION = c
DATUM = node_id
END = t2
Specifies the time, t2, at which to end the output of the data or the search of
a peak load.
Default: Output or search to the end of the simulation.
Range: t2 > t1
HOTSPOTS = n
Specifies the number of hot spots to locate on the flexible body and output.
A search for the top n nodes that recorded the highest stress or strain during
the simulation will ensue. With the START, END or SKIP arguments,
FEMDATA only checks the time steps within those specifications for hot
spots. A text file containing a table of hot-spot data (node ID, maximum
value, time of maximum value, and location) will be output. The complete
time history of nodal stress or strain will be output as well for each hot spot,
if the STRAIN or STRESS option is specified in the OUTPUT statement.
FLEX_BODY = id
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.
86 Adams/Solver
C++ Statements
NOINERTIA
Turns off the output of inertia loads. Inertia loads include linear acceleration,
angular acceleration, and angular velocity of the part or flexible body. Only
loads due to reaction and applied forces are output with this option. This
results in a load imbalance specification for the body, so you must employ a
technique, such as inertia relief, to recover the inertia loads from the external
loads in the finite element program.
PEAK_SLICE =
Specifies that FEM load data are to be output only at those time steps where
FX:FY:FZ:FMAG:GMA the specified peak load occurred in the simulation. With the START, END, or
G: TX:TY:TZ:TMAG
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
SKIP = n
Specifies the number of output steps to skip when outputting the data.
Default: n=0 (every step is output).
FEMDATA 87
C++ Statements
START = t1
STRAIN
Outputs strain information if strain modes are available in the modal neutral
file (MNF) of the specified flexible body. FEMDATA outputs all six
components of strain (normal-X, normal-Y, normal-Z, shear-XY, shear-YZ,
shear-ZX). It outputs strains in the basic FEA coordinate system of the
flexible body, unless the RM=id option is specified.
STRESS
Outputs stress information if modal stresses are available in the MNF of the
flexible body. FEMDATA outputs all six components of stress (normal-X,
normal-Y, normal-Z, shear-XY, shear-YZ, shear-ZX). It outputs stresses
output in the simulation set of units in the basic FEA coordinate system of the
flexible body, unless the RM=id option is specified.
Extended Definition
Default File Naming Conventions
You can use the FILE argument to specify the directory, name, and/or extension
(directory/name.extension) for the output file. If you do not specify a directory, FEMDATA creates all its
output files except DAC files in the current working directory. Because several DAC files are typically
generated for a FEMDATA statement, FEMDATA creates them in a separate directory named after the
body. It creates this directory in the current working directory if it does not exist.
If a file name is not specified in the FILE argument, default file names are assigned according to the type
of FEM data and file format (which is specified in the OUTPUT statement) as shown in the table below.
FEMDATA Default File Names and Extensions
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
<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
88 Adams/Solver
C++ Statements
Type of data:
Format:*
File name:
Extension:
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
<run_name>_body_name>_hots
.tab
Hotspots
Stress
DAC
Generic
Hotspots
<run_name>_<node_id>se_<channel_id> .dac
<run_name>_<body_name>
.nsf
<run_name>_<body_name>_hote
.tab
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
FEMDATA 89
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:
Fm(t) represents the force acting on the body at Marker m.
r x, r y, r z represents the unit vector of the reference coordinate system of the rigid body (FEA
coordinate system of the flexible body).
r(t) represents the position of the reference marker (RM) in that coordinate system.
m.
90 Adams/Solver
C++ Statements
m.
FZ = Output loads at time t when
m.
FMAG = Output loads at time t when
Note:
MAX F m ( t ) r x ( t ), F m ( t ) r y ( t ), F m ( t ) r z ( t ) .
m
m
m
Similar expressions exist for TX, TY, TZ, and TMAG. The PEAK_SLICE argument is not
available when you specify a time history OUTPUT load format (DAC or RPC).
Modal Superposition
Nodal displacements, strains, and stresses are computed using the principal of modal superposition:
Here i are the respective mode shapes from FEA and {q(t)}are the modal displacements of the flexible
body that Adams/Solver computes.
Coordinate Reference Transformation of Stress or Strain
Because stress and strain are second-order tensors, the following equation is used to transform these
quantities to a reference coordinate system:
Where
A R is the skew-rotation matrix from the flexible bodys LPRF (FE origin) to the markers
FEMDATA 91
C++ Statements
S xx S xy S xz
[ S ] = S yx S yy S yz
where
S ij = S ji
S zx S zy S zz
Definition of Hot Spots
The figure below illustrates how the radius argument can affect the definition of a hot spot region. In this
figure, the top 7 hottest nodes (those with the largest stress) are listed. If the number 5 and no radius is
specified on HOTSPOTS, then only nodes 4, 5, 3, 6, and 2 would be output. If a radius of 0.5 mm is
specified, then only node 4 would be listed from this region and the other 4 hot spots would come from
nodes with the highest stress from other regions.
92 Adams/Solver
C++ Statements
Limitations
Using FEMDATA to output loads encounters the same limitations as exporting FEA Loads in
Adams/View. See Limitations for Exporting FEA Loads for more information.
Caution:
Note that all FEMDATA are output in the Adams modeling units. This causes a problem
when the Adams units are inconsistent with those used in the finite element model, and the
data that is output will be included in a subsequent finite element analysis.
For example, when outputting FEMDATA of type LOADS to ANSYS or MSC.Nastran for
inclusion in the FE analysis, the Adams and FE modeling units must be consistent. This is
also true when outputting FEMDATA of type NODAL_DEFORMATION when the
OUTPUT format is ANSYS or MSC.Nastran and the data will be used as input to the FE
analysis.
In the case of outputting FEMDATA of type MODAL_DEFORMATION, the only concern
for units is when MSC.Nastran (or PUNCH) has been specified as the OUTPUT format.
This is because rigid body motion is included in the output file along with the modal
coordinates. By definition, modal coordinates are unitless, so the modal stresses (or strains)
will be recovered correctly in MSC.Nastran irregardless of unit settings. However, in order
for the overall displacement of the component to be correctly recovered, the unit of length
must be consistent between models.
Examples
FEMDATA/100, STRESS, FLEX_BODY=101
, HOTSPOTS = 7, CRITERION = MAX_PRIN
, RADIUS = 0.5, FILE = hotspots_101
OUTPUT/STRESS = DAC
These statements create a text file, named hotspots_101.tab containing hot spot information for flexible
body 101. Seven hot spots with a radius of 0.5 based on maximum principal stress are requested. Also, a
time history of the stress for each node found to be a hot spot is output in DAC format. The names of the
DAC files are given the prefix hotspots_101 as specified in the FILE argument.
FEMDATA/1, LOADS, RM=201
, PEAK_SLICE = GMAG
, FILE = peak201.nas
OUTPUT/LOADS = NASTRAN
These statements create a NASTRAN input file containing loads of the parent part of marker 201 in that
markers 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
FEMDATA 93
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 FEFatigue or MSC.Fatigue to perform a fatigue analysis based on linear superposition theory.
See other Output available.
94 Adams/Solver
C++ Statements
FIELD
The FIELD statement applies a translational and rotational action-reaction force between two markers.
Format
FIELD 95
C++ Statements
Arguments
CMATRIX=r1,...,r36
Enter the elements by columns from top to bottom, then from left to right.
CMATRIX defaults to a matrix with thirty-six zero entries if you do not use
either CMATRIX or both CRATIO and KMATRIX. The units for the
translational and rotational components of CMATRIX should be force-time
per unit displacement and torque-time per radian, respectively.
CRATIO = r
FORCE=r1,...r6
Defines three preload force components and three preload torque components
in the field element when the I and J markers are separated/misaligned by the
values specified in the LENGTH argument. The terms r1,...,r6 are the force
components along the x-, y-, and z-axis of the J marker and the torque
components about the x-, y-, and z-axis of the J marker, respectively. FORCE
is optional and defaults to six zero entries.
FUNCTION=USER(r Defines and passes constants to the user-written subroutine FIESUB to define
1[,...,r30])
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.
96 Adams/Solver
C++ Statements
KMATRIX=r1,...,r36
Defines a 6x6 matrix of stiffness coefficients. The following matrix shows the
values to input.
Enter the elements by columns from top to bottom, then from left to right.
KMATRIX defaults to a matrix with thirty-six zero entries. The units for the
translational and rotational components of KMATRIX should be force per
unit displacement and torque per radian, respectively.
Adams/Solver (C++) cannot calculate the damping coefficients if you do not
use both CRATIO and KMATRIX. In that case, CMATRIX must be explicitly
defined if you want to include damping coefficients in the calculation of the
field forces.
LENGTH=r1,...,r6
Defines six reference length angles. This is the nominal position of the I
marker with respect to the J marker, resolved in the J marker coordinate
system. The terms r1,...,r6 are the x, y, and z translational components
(specified in linear displacement units) of the displacement between the I and
J markers; and a, b, and c are rotational displacement of the axes of the I
marker with respect to the J marker, resolved in the J marker axes (specified
in radians). If the reference force is zero, LENGTH is the same as the free
length. LENGTH is optional and defaults to a six zero entry.
ROUTINE=libname::
subname
Specifies an alternative library and name for the user subroutine FIESUB.
Learn more about the ROUTINE Argument.
Extended Definition
The FIELD statement applies a translational and rotational action-reaction force between two markers.
To specify a linear field, use the arguments in the FIELD statement to specify constants for the six-bysix stiffness matrix,a preload force, a six reference lengths, and a six-by-six damping matrix. The
stiffness and damping matrices must be positive semidefinite, but need not be symmetric. To specify a
nonlinear field, use the user-written subroutine FIESUB to define the three force components and three
torque components and use the argument FUNCTION=USER(r1[,...,r30]) to pass constants to FIESUB.
FIELD 97
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.
Fx
K 11 K 12 K 13 K 14 K 15 K 16 x x 0
C 11 C 12 C 13 C 14 C 15 C 16 V x
F1
Fy
K 21 K 22 K 23 K 24 K 25 K 26 y y 0
C 21 C 22 C 23 C 24 C 25 C 26 V y
F2
Fz
Tx
K 31 K 32 K 33 K 34 K 35 K 36 z z 0
K 41 K 42 K 43 K 44 K 45 K 46 a a 0
C 31 C 32 C 33 C 34 C 35 C 36 V z
C 41 C 42 C 43 C 44 C 45 C 46 x
F3
T1
Ty
K 51 K 52 K 53 K 54 K 55 K 56 b b 0
C 51 C 52 C 53 C 54 C 55 C 56 y
T2
Tz
K 61 K 62 K 63 K 64 K 65 K 66 c c 0
C 61 C 62 C 63 C 64 C 65 C 66 z
T3
For a nonlinear field, the following constitutive equations are defined in the FIESUB subroutine:
F x = f 1 ( x, y, z, a, b, c, V x, V y, V z, x, y, z )
F y = f 2 ( x, y, z, a, b, c, V x, V y, V z, x, y, z )
F z = f 3 ( x, y, z, a, b, c, V x, V y, V z, x, y, z )
T x = f 4 ( x, y, z, a, b, c, V x, V y, V z, x, y, z )
T y = f 5 ( x, y, z, a, b, c, V x, V y, V z, x, y, z )
T z = f 6 ( x, y, z, a, b, c, V x, V y, V z, x, y, z )
Adams/Solver (C++) applies the defined forces and torques at the I marker. In the linear and nonlinear
equations:
Fx, Fy, and Fz are the three translational force measure numbers.
Tx, Ty, and Tz are the three rotational force measure numbers associated with unit vectors
damping matrix.
F1, F2, F3, T1, T2, and T3 are the translational and the rotational pre-tensions.
98 Adams/Solver
C++ Statements
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
Tj = -Ti - L x Fi
L is the instantaneous vector from the J marker to the I marker. While the force at the J marker is equal
and opposite to the force at the I marker, the torque is usually not equal and opposite, because of vector L.
Tip:
However, when defining massless beams, you may want to use a BEAM
statement. It requires only six input values to compute the thirty-six values for the
Kmatrix (see BEAM).
Finite element analysis programs can give the values for CMATRIX and
KMATRIX.
Caution:
For the constitutive equations to be accurate, at least two of the rotations (a, b, c)
must be small. That is, two of the three values must remain smaller than 10
degrees. In addition, if a becomes greater than 90 degrees, b becomes erratic. If b
becomes greater than 90 degrees, a becomes erratic. Only c can become greater
than 90 degrees without causing problems. For these reasons, it is best to define
your field such that angles a and b (not a and c and not b and c) remain small.
The three rotational displacements (a, b, and c) that define the field are not Euler
angles. They are the projected angles of the I marker with respect to the J marker.
Adams/Solver (C++) measures them about the x-, y-, and z-axis of the J marker.
Adams/Solver (C++) applies the component translational and rotational forces for
FIELD 99
C++ Statements
Examples
In order to model the elastic freedoms at location I shown in the figure, the system stiffness matrix must
first be determined for the retained degrees of freedom. A finite element super element analysis is one
method for determining the matrix. Assume that all other degrees of freedom are either constrained or
superfluous for this analysis. The system stiffness matrix is:
X
0.198E+04
0.126E-01
-0.147E+04
0.126E-01
0.208E+03
-0.933E-02
-0.147E+04
-0.933E-02
0.763E+07
0.198E+04
0.126E-01
-0.147E+04
0.126E-01
0.208E+03
-0.933E-02
100 Adams/Solver
C++ Statements
y
z
-0.147E+04
-0.933E-02
0.763E+07
The FIELD statement describing these elastic forces applied to Marker 100 due to displacement of
Marker 100 relative to Marker 57 is:
FIELD/1, I=100, J=57, KMATRIX=0.198E+04
, 0, 0.126E-01, 0, -0.147E+04, 0,
, 0, 0, 0, 0, 0, 0,
, 0.126E-01, 0, 0.208E+03, 0, -0.933E-02, 0,
, 0, 0, 0, 0, 0, 0,
,-0.147E+04, 0, -0.933E-02, 0, 0.763E+07, 0,
, 0, 0, 0, 0, 0, 0
, LENGTH=0, 150, 0, 0, 0, 0
These entries must be made column by column. The distance between the I and J markers is zero except
in the y direction (where it is 150).
See other Forces available.
FLEX_BODY 101
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]
e
,CRATIO=
\
USER(r1,
[
r2,
...,
r30])
OFF
,GDAMP = 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]
102 Adams/Solver
C++ Statements
FLEX_BODY 103
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 user-written
subroutine. To define the modal damping with an expression, follow
CRATIO with an equal sign and the expression. The FXFREQ and
FXMODE function expression may be useful here.
To define modal damping with a user-written subroutine, follow
CRATIO with an equal sign, the character string USER, and the
values (r1[,...,r30] that the Adams/Solver (C++) is to pass to the
DMPSUB user-written subroutine. If the CRATIO argument is used, it
must either be the last argument in the FLEX_BODY statement, or be
followed by a backslash (\).
If you omit CRATIO, Adams/Solver (C++) applies default damping
as follows:
1% to modes under 100 Hz
10% to modes under 1 kHz
Full critical damping to modes over 1 kHz
104 Adams/Solver
C++ Statements
DMODE=a1,a2,...,an
DYNAMIC_LIMIT=d
EXACT=c1:...:c6
FLEX_BODY 105
C++ Statements
INDEX=index
106 Adams/Solver
C++ Statements
INVARIANTS=c1:...:c9
Specifies a true and false pattern indicating which of the nine inertia
invariants Adams/Solver (C++) should use to model inertia coupling
of the flexible and rigid body motion. The order of the patterns
corresponds to the nine successive inertia invariants. For more details
on the inertia invariants, see the Theory of Flexible Bodies in
Adams/Flex.
The following combinations have special significance:
T:T:F:F:T:T:T:T:T - Full inertia coupling of deformation and rigid
body motion.
T:T:F:F:F:T:T:T:F - Ignore second-order deformation corrections to
the inertia tensor, and the first-order corrections to the rotational and
flexible inertia coupling. This is also called partial coupling.
T:T:F:F:F:T:T:F:F - Neglect all deformation corrections to the mass
matrix.
*:*:*:*:*:F:*:*:* - Disable all deformations.
The pattern T:T:F:F:F:T:T:T:F is the default, because although it
potentially sacrifices small levels of accuracy compared to the first
pattern of full inertia coupling, it does so with significant
computational savings. If an MNF has six rigidbody modes in it,
theoretically, invariants 3 and 4 should be zero even though there may
be some non-zero entries in the MNF file due to numerical errors. This
is the reason that they are disabled by default. The pattern
T:T:F:F:F:T:T:F:F should be used with great care, because it only
returns an accurate answer when the flexible component is quite rigid.
The pattern *:*:*:*:*:F:*:*:*, where the * can be either T or F, offers
a way to turn off all flexibility in the structure, usually for debugging
purposes. Note that even with this last pattern, the FLEX_BODY
statement does not function like a PART statement, due to formulation
differences.
It is hard to envision circumstances where it is appropriate to disable
invariants 1 (the total mass), 2 (the undeformed CM location), and 7
(the undeformed inertia tensor). Disabling these normally causes a
numerical singularity.
Default: T:T:F:F:F:T:T:T:F
FLEX_BODY 107
C++ Statements
MATRICES=id1,...,idn
108 Adams/Solver
C++ Statements
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
REULER=a,b,c
FLEX_BODY 109
C++ Statements
STABILITY_FACTOR=s
Specifies the stability factor for quasi-static modes when the dynamic
limit feature is enabled on this flexible body. If the modal force acting
on quasi-static mode has high frequency component, it may affect the
convergence of dynamic simulation. In this case, user can specify
artificial damping to stabilize the solution using this argument.
The damping added to the mode will be s times of critical damping.
So the equation of motion of quasi-static mode will be
2sq + Kq = F , where is the frequency of the mode.
Default: 10.0
VM=id
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
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 x-axis
(WX), y-axis (WY), and z-axis (WZ) of the WM coordinate system.
Default: 0
Range: Real values
110 Adams/Solver
C++ Statements
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
stationary axis, significant solver performance can be realized by aligning the zaxis of the body coordinate system (BCS) with the spin axis. Because the BCS of
the FLEX_BODY is defined by the basic coordinate system in the finite element
model, re-orientating the BCS with respect to the body requires you to re-orient the
finite element model with respect to its basic coordinate system. In MSC.Nastran,
this can be done easily with CORDxx Bulk Data entries.
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,
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
FLEX_BODY 111
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
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 quasi-static mode. A damping of 10 times the critical damping will be applied
to these modes.
FLEX_BODY/1,
, MATRICES = 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14
, DYNAMIC_LIMIT=1.0e3
, STABILITY_FACTOR=0.0
This statement defines a flexible body with a dynamic limit of 1000.0 Hz. Any mode that is higher than
1000.0 Hz will be treated as quasi-static mode. No damping is applied to the quasi-static modes (Note
that solution may become unstable if there is high frequency excitation).
112 Adams/Solver
C++ Statements
FRICTION 113
C++ Statements
FRICTION
The FRICTION statement defines parameters for frictional forces on translational, revolute, cylindrical,
hooke, universal, and spherical joints.
Note:
Format
Frictional forces and torques are computed by Adams/Solver (C++) using a friction model
that supports dynamic friction and stiction.
114 Adams/Solver
C++ Statements
Arguments
BALL_RADIUS=Rb
Defines the radius of the ball in a spherical joint for use in friction-force and
torque calculations.
Default: 1.0
Range: BALL_RADIUS > 0
BENDING_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 staticfriction effect, while sliding is dynamic-friction effect. Excluding stiction in
simulations that dont require it can greatly improve simulation speed.
Default: All
FRICTION_FORCE_P
RELOAD=r
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
FRICTION 115
C++ Statements
INITIAL_OVERLAP=
Xs0
INPUTS=( {ALL,
NONE [[PRELOAD:
REACTION_FORCE:
BENDING_MOMENT:
TORSIONAL_MOMEN
T]]} )
Defines the input forces to the friction model. By default, all user-defined
preloads and joint-reaction force and moments are included. You can
customize the friction-force 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
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
116 Adams/Solver
C++ Statements
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}
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
FRICTION 117
C++ Statements
REACTION_ARM=Rn
Defines the effective moment arm of the joint-reaction torque about the
translational joints axial axis (the z-direction of the joints 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
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)
118 Adams/Solver
C++ Statements
Table 1
Symbol:
Description:
_________
Scalar quantity
Vector quantity
Summing junction:
c=a+b
Multiplication junction:
c=axb
MAG
ABS
FRD
Table 2
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
FRICTION 119
C++ Statements
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
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++).
120 Adams/Solver
C++ Statements
Examples
FRICTION/102, JOINT=102, I_YOKE
, Mu_Static=0.03, Mu_Dynamic=0.024
, Stiction_Transition_Velocity=0.1
, Max_Stiction_Deformation=0.15
, Pin_Radius=12.25
, Friction_Arm=8.2
, Effect=All
, Inputs=Reaction_Force
This statement creates frictional forces about the rotational degree of freedom associated with the I
markers part of either a hooke or universal joint. The following items apply:
We assume that the joint has a 12.25 length-unit-radius pin and an effective-friction-moment arm
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.
GCON 121
C++ Statements
GCON
The GCON statement introduces a constraint equation that must be satisfied by Adams/Solver (C++)
during the simulation. This allows you to specify both holonomic and non-holonomic constraints.
Format
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.
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
The GCON statement allows you to define both holonomic and non-holonomic constraints. Holonomic
constraints only depend on position measures, like GCON/111 through GCON/113 above. A constraint
is non-holonomic if (a) its expression exp1 contains velocity measures, and (b) there is no expression exp2
that is the time integral of exp1. An example of a non-holonomic constraint is a roll without slip condition
GCON/34, FUNC=VX(2) - WZ(2)*DY(2)
The GCON statement introduces a constraint to Adams/Solver (C++) that is guaranteed to be handled
correctly as long as the FUNCTION is in Pfaffian form. In this context, note that any holonomic
expression is automatically in Pfaffian form. In the case of non-holonomic constraints, a Pfaffian
constraint requires that the FUNCTION is limited to expressions that are linear in velocity quantities. In
other words, if there are velocity quantities in the definition of the FUNCTION (as is the case in the
previous GCON), a partial derivative of the FUNCTION with respect to any velocity quantity present in
its definition should lead to an expression that does not depend on velocity quantities. The previous
122 Adams/Solver
C++ Statements
FUNC
FUNC
-------------------- = 1 , and -------------------- = DX ( 2 ) , which makes
VX ( 2 )
WZ ( 2 )
that indicates that the velocity V(2,3) is orthogonal to the distance vector between markers I=2 and J=1.
An example of a non-Pfaffian GCON is
GCON/25,FU=VX(2,3)*VX(2,3)*DX(2,1)+VY(2,3)*DY(2,1)+ VZ(2,3)*DZ(2,1)
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.
GCON 123
C++ Statements
Caution:
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.
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 z-axis of marker 8 to
be identical to the same rotation angle for marker 6. The latter is the marker on which motion 17 acts. As
a result, this motion will actually drive both pendulums. Consequently, the torque applied to induce the
prescribed motion is going to be larger than when GCON 23 is not present in the model, because the
motion effectively drives both pendulums.
The situation described above, namely the extra torque required to make the second pendulum follow the
first pendulum, might not be what you want to see. In this case, the function AO, from Action Only, can
124 Adams/Solver
C++ Statements
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
The example also previews a 3D expression language extension wherein the UVZ(10) measure refers to
a Unit Vector (UV) in the direction of the z-axis of marker 10, and the % corresponds to the cross
product. Likewise, DXYZ(10,6) represents the three-dimensional distance vector between markers 10
and 6, while WXYZ(8,9) is the angular velocity of marker 8 with respect to marker 9. The 3D extensions
cannot yet be used with statements other than GCON and is not documented elsewhere.
Note that if the GEAR statement was changed to a GCON statement in a kinematically determinate
model, that is, a zero degree of freedom model, the model would gain one degree-of-freedom and become
a dynamic model. This is because one displacement constraint has been eliminated and replaced with a
velocity constraint.
Applications
The user-defined constraint is intended to be used to prescribe simple algebraic equations in position and
velocity measures that must be satisfied by Adams/Solver (C++). The statement is a new feature added
in Adams/Solver (C++). Due to its complexity and extremely general nature, it is highly probable that
not all possible applications have been anticipated and tested. Although models which exceed the
capabilities of the system will, in most cases, be detected, this can not be completely guaranteed. It is
advisable to use the GCON statement with a degree of caution. Some of the known limitations are listed
below.
GCON 125
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 steady-state motion to the whole car. Note that the user
constraints can be activated and deactivated through the Adams command language. Another possible
use of GCON is to specify arbitrary user-defined motions that relate time and various position and
velocity measures.
Known Limitations
Currently, there is no redundancy check for user constraints defined at the velocity level.
Therefore, you can impose constraints that are not redundant at the position level, but lead to a
set of redundant constraints when their time derivative is considered with other velocity level
constraints during the velocity Initial Conditions (IC) analysis. Consider the situation when two
constraints are defined as GCON/1, FU=DX(1,2), and GCON/2, FU=VX(1,2). Because the
redundant constraint analysis only includes position level constraints, Adams/Solver (C++) will
not identify that a velocity-level constraint (GCON/2) induces a redundant constraint during the
velocity computation. As a result, a model that contains these two user constraints will fail
during the velocity analysis with a singular Jacobian error.
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
user-defined 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.
126 Adams/Solver
C++ Statements
GEAR
The GEAR statement defines a gear pair constraint. Examples include a spur, helical, planetary, bevel,
and rack-and-pinion gear pairs.
Format
CV=id
Identifier of the marker that designates the point of contact and implicitly
determines the ratio of the two gears. The z-axis of the CV marker must point in
the direction of common velocity at the point of contact. The direction of common
velocity is tangent to both pitch circles and would be normal to the tooth surfaces
of the gears if the pressure angle was zero (Adams/Solver (C++) always assumes
a zero pressure angle). The CV marker must belong to the carrier part that also
hosts the J markers of the joints.
JOINTS=id1,id2 Specifies the two joints whose relative motion is to be related with a gear. Each of
these two joints must be translational, revolute, or cylindrical. Note that both J
markers of these joints belong to a carrier part that must also host the CV marker.
Extended Definition
The GEAR statement uses the location of a common velocity CV marker to determine the point of
contact of the two gear pitch circles. The direction of the z-axis of the common velocity marker indicates
the direction of the common velocity of points on the gear teeth in contact. This is also the direction in
which gear tooth forces act. Note that the CV marker has constant position and orientation in the carrier
body coordinate system (BCS). The CV marker through its z-axis only provides a direction, and there is
no need to be more specific than this. In this context, there is no need to indicate things such as how the
power flow occurs through the gear.
The reaction force reported back to you for a GEAR element is the reaction force measured on the J
marker of the joint that is specified first in the GEAR definition. It is important to keep in mind that the
GEAR 127
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).
Caution:
Gear reaction forces and torques are difficult to obtain from the Request file
The figure below illustrates the use of a GEAR statement to define a bevel gear pair.
Bevel Gear Pair
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
128 Adams/Solver
C++ Statements
, 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 rack-and-pinion gear pair.
Rack-and-Pinion 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
GEAR 129
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.
130 Adams/Solver
C++ Statements
GFORCE
The GFORCE statement defines a force element that consists of three orthogonal translational force
components and three orthogonal torque components. You may define the GFORCE statement through
user-specified function expressions in the Adams/Solver (C++) dataset or through user-written
subroutines.
Format
Arguments
FY=e
FZ=e
I=id
GFORCE 131
C++ Statements
JFLOAT=id
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
TY=e
TZ=e
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 user-specified function expressions in the Adams/Solver (C++) dataset or through user-written
subroutines.
The element applies actions to the part to which the I marker belongs and corresponding reactions to the
part to which the JFLOAT marker belongs. The GFORCE statement internally establishes the position of
the JFLOAT marker. As the system moves, Adams/Solver (C++) moves the JFLOAT marker on its part
to always keep the JFLOAT and I markers superimposed. Therefore, Adams/Solver (C++) applies the
reaction force to the part containing the JFLOAT marker at the instantaneous position of the I marker.
The magnitude of the force depends on the expressions or subroutines you supply. You can specify these
functions with Adams/Solver (C++) function expressions or user-written FORTRAN-77 subroutines.
132 Adams/Solver
C++ Statements
The vector formed by the three user-defined component forces along the RM marker axes defines the
direction of the translational force action. The reaction is equal and opposite to the action.
The vector formed by the three component torques determines the direction of the rotational torque
action. You define these torques about the RM marker axes. The reaction is equal and opposite to the
action.
Formulation
Action
Values
Reaction
GFORCE 133
C++ Statements
where Fr and Tr are the translational and rotational reactions applied at the JFLOAT marker, respectively.
Tip:
Depending on the nature of the desired force relationship, the RM marker may belong to
the same part as the I marker or JFLOAT marker, or to a third, unrelated part.
Caution:
The user-defined forces FX, FY, FZ, TX, TY, and TZ should be smooth, continuous, and
single-valued. These conditions make the solution process very effective.
Examples
GFORCE/1, I=310, JFLOAT=9910, RM=310,
, FX = -20.*VX(310,9900,310)\
, FY = -20.*VY(310,9900,310)\
, FZ = -20.*VZ(310,9900,310)\
, TX = -6.*WX(310,9900,310)\
, TY = -6.*WY(310,9900,310)\
, TZ = -6.*WZ(310,9900,310)
This GFORCE statement defines a general, six-component force acting between fixed Marker 310 and
floating Marker 9910, which must belong to different parts. Expressions FX, FY, FZ, TX, TY, and TZ
define the force and torque components the x, y, and z axes of the reference marker, which is Marker 310.
Adams/Solver (C++) superimposes floating Marker 9910 on Marker 310, and apply the reaction force
and torque at that point.
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.
134 Adams/Solver
C++ Statements
For this application, the RM reference marker would be fixed to the surface and would supply the
orientation for the normal and friction forces and the torque about the ball center due to the friction.
When compared with the SFORCE (see SFORCE statement), the GFORCE statement can vary both its
point of application (with respect to the part containing the JFLOAT marker) and its resultant direction
(with respect to the RM-marker). In these cases, a single GFORCE statement can represent the complete
force/torque condition at a point along with its reaction forces, whereas it would require six translational
SFORCEs and six rotational SFORCEs, with appropriately-oriented markers, to accomplish the same
thing.
See other Forces available.
GRAPHICS 135
C++ Statements
GRAPHICS
The GRAPHICS statement creates:
Two- or three-dimensional geometry for CONTACT. You always define the geometry with
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
,ARC, CM = id, RADIUS = r,RANGLE = r
,BOX, CORNER = id, X = x, Y = y, Z = z
,CIRCLE, CM = id, RADIUS = r
,CURVE, CID = id, CRM = id
,CYLINDER, CM = id, RADIUS = r, LENGTH = r, RANGLE = r
,FRUSTUM, CM = id, RADIUS = r, LENGTH = r, TOP = r, BOTTOM = r, [RANGLE = r]
GRAPHICS/id ,PO INT, RM=id
,PLANE, RM = id, XMIN = r, XMAX = r, YMIN = r, YMAX = r
,EL LIPSOID, CM = id, XSCALE = r, YSCALE = r, ZSCALE = r
,EXTERNAL, RM = id, {FILE = file_name, [ELEMENT = geometry_name]}
,EXTRUSION, CRM = id, GID = id, PID = id
,REVOLUTION, CRM = id, GID = id
,TORUS, CM = id, MINOR_RADIUS = r, MAJOR_RADIUS = r
{ } Select one item
[ ] Optionally select the item
136 Adams/Solver
C++ Statements
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
BOTTOM=r
BOX
Creates a rectangular box. You use the following arguments to define the box:
CORNER to specify the ID of a reference marker at one corner of the box.
X, Y, and Z to define the extent of the box along the x-, y-, and z-axes of the
corner marker.
CID=id
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 yaxes of the marker. The z-axis of the marker defines the centerline axis of the
cylinder or frustum.
For a torus, the origin of the marker specifies the center of the torus. The z-
Defines the reference marker with respect to which the curve data points are
specified.
CORNER=id
Defines a reference marker, which is at a corner of the box that is being created.
CURVE
Creates a curve graphic based on a CURVE statement. You define the curve data with
respect to a reference marker (CRM). The CONTACT and CVCV modeling entities
require that the curve be planar. It must be in the plane defined by the x- and y-axes
of the RM marker, and must contain the origin of the marker.
GRAPHICS 137
C++ Statements
CYLINDER
Creates a cylinder whose top and bottom are perpendicular to the cylinder central
axis. You use the following arguments to define the cylinder:
CM to specify the center marker (CM) of the cylinder. The z-axis of the CM
ELEMENT =
geometry_name
ELLIPSOID
Creates an ellipsoid. You use the following arguments to define the ellipsoid:
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.
and z-axes of the CM marker. If the argument values are all equal (XSCALE
= YSCALE = ZSCALE), then Adams/Solver (C++) creates a sphere.
EXTERNAL
Specifies that a three-dimensional solid geometry is to be created. The data for the
geometries is in an external file that the geometry engine of Adams/Solver (C++) can
read. It use the following arguments to define the geometry:
RM to specify the marker that defines the reference coordinate system.
FILE identifies the file to be read. This file is commonly generated by the
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.
138 Adams/Solver
C++ Statements
EXTRUSION
FILE=file_name Specifies the name of a file containing one or more geometric entities. Adams/Solver
(C++) can only read Parasolid files. Parasolids is an exact boundary representation
(b-rep) geometric modeler. This means that it represents solids (and other types of
geometry) by their boundaries. Other file formats (such as shell files) must be
converted to a boundary representation externally before the Adams/Solver (C++)
Parasolid geometry engine can use them.
FRUSTUM
Creates a frustum of a cone whose top and bottom are perpendicular to the cone
central axis. You use the following arguments to define the frustum:
CM to specify the center marker (CM) of the frustum. The z-axis of the CM
GID=id
LENGTH=r
Defines the height for either a cylinder or frustum. The two circles at the ends of a
cylinder or frustum are both perpendicular to the z-axis of the CM marker. Therefore,
the circles are parallel. Adams/Solver (C++) uses the value of LENGTH to specify
the z distance between the two circles. There is no limit on the value of r. A positive
value specifies a cylinder or frustum along the positive z-axis of the CM marker, and
a negative value specifies a cylinder or frustum along the negative z-axis of the CM
marker.
MAJOR_RADI
US
MINOR_RADI
US
PID
GRAPHICS 139
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 x-y plane of the RM marker (that is, the z-axis of the RM marker is
normal to the plane).
XMIN, XMAX, YMIN, and YMAX to specify the extent of the plane.
The plane is a two-dimensional element, and, therefore, you can only use it when
defining contact with another two-dimensional element (point, arc, circle, curve).
POINT
RADIUS=r
RANGLE=r
Defines an angle measured positive (according to the right-hand rule) about the zaxis of the CM marker. Adams/Solver (C++) assumes RANGLE is in radians. The
angle starts at the positive x-axis of the CM marker and subtends the arc, the arc of
the cylinder, or the arc of the cone frustum.
Range: -2 < RANGLE < 2
REVOLUTION
RM=id
Identifies the marker that defines the reference coordinate system for a point, plane,
or external geometric entity. Adams/Solver (C++) defines the geometries in this
coordinate system.
TOP=r
Defines the radius at the top of a frustum. The top is perpendicular to the CM marker
z-axis, and the center of the top is at the position on the CM marker z-axis that
LENGTH specifies. There is no limit on the value of r.
TORUS
Creates a torus graphic. You use the following arguments to create a torus:
CM to specify the id of the marker that defines the center of the torus. The z-axis
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.
140 Adams/Solver
C++ Statements
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.
XCALE = r,
YSCALE = r,
ZSCALE = r
Specifies the diameters along the x-, y-, and z-axes of an ellipsoid.
This GRAPHICS statement creates a cylinder with its base at Marker 0201. Marker 0201 is located at the
center of the circular cross-section, which has a radius of two. The cylinder has a length of two along the
negative z-axis of Marker 0201.
GRAPHICS/1297, EXTERNAL, RM=7921,
, FILE = GenevaWheel.xmt_txt
, ELEMENT = Geneva
This GRAPHICS statement creates a three-dimensional solid element. The data for this solid element is
contained in a Parasolid file, GenevaWheel.xmt_txt. Within this file, which contains several geometric
entities, the solid with a tag, Geneva, is to be extracted. The solid definition is specified with respect to
Marker 7921.
The geometry associated with GenevaWheel.xmt_txt is shown next.
GRAPHICS 141
C++ Statements
142 Adams/Solver
C++ Statements
,DA = r, COILS = i
SPDP,
I
=
id,
J
=
id
,DB = r, LA = r, LC = r
,
DC
=
r,
LB
=
r,
LD=
r
BEAM
BUSHING
FIELD
GRAPHICS/id,
SFORCE
SPDP
VFORCE
FORCE,
ETYPE=
,
EID=
id,
EMARKER
=
id
VTORQUE
GFORCE
NFORCE
JOINT
JPRIM
PTCV
CVCV
GRAPHICS 143
C++ Statements
Arguments
ARC
Creates an arc.
BOTTOM=r
Defines the bottom radius of a frustum of a cone. The bottom is perpendicular to the
center marker z-axis, and the center of the bottom is at the center marker origin.
There is no limit on the value of r.
BOX
CID=id
CIRCLE
Creates a circle.
CM=id
Defines the identifier of the marker at the center of an arc, circle, cylinder, frustum,
or torus. If you are creating a circle or arc, orient the CM marker so that its z-axis is
normal to the plane of the circle or plane of the arc. Similarly, if you are defining a
cylinder or frustum, orient the CM marker so that its z-axis is normal to the bottom
plane of the cylinder or the frustum. For the torus the z-axis should be the axis of
the revolution.
COILS
CORNER=id
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
CYLINDER
Creates a cylinder whose top and bottom are perpendicular to the cylinder central
axis.
DA=r
Defines the diameter of the spring in a spring-damper (see the spring-damper figure
below). There is no limit on the value of r.
Default: 0
DB=r
Defines the diameter of the damper in a spring-damper at the I marker (see the
spring-damper figure below). There is no limit on the value of r.
Default: 0
DC=r
Defines the diameter of the damper in a spring-damper at the J marker (see the
spring-damper figure below). There is no limit on the value of r.
Default: 0
144 Adams/Solver
C++ Statements
Spring-Damper
EID=id
Specifies the identifier of the element whose force is to be displayed by the FORCE
graphic. You can not specify EID if ETYPE=ALL.
EMARKER=id
Specifies the identifier of the marker where Adams/Solver displays the force
graphic. If ETYPE=ALL, marker EMARKER must have at least one force applied
to it. If you enter a specific force type, and identifier EID, marker EMARKER must
be one of the markers upon which the specified force acts.
ETYPE = {ALL,
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
FORCE
Creates an arrow whose direction is identical to the direction of a force and whose
length is proportional to the magnitude of a force.
FRUSTUM
Creates a frustum of a cone whose top and bottom are perpendicular to the cone
central axis.
GRAPHICS 145
C++ Statements
GID
I=id, J=id
Defines the I and J markers for creating a spring-damper graphic. The I and J
markers define the attachment points of the spring-damper.
LA=r
Defines the distance between the I marker and the end of the damper to which it is
closest (see the Spring-Damper figure). There is no limit on the value of r.
Default: 0
LB=r
Defines the distance between the J marker and the end of the damper to which it is
closest (see the spring-damper figure). There is no limit on the value of r.
Default: 0
LC=r
Defines the height of the damper at I. Adams/Solver measures the height from the
bottom of the damper to its top along the line segment between the I and J marker.
There is no limit on the value of r.
Default: 0
LD=r
Defines the height of the damper at J. Adams/Solver measures the height from the
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 z-axis of the CM marker,
they are parallel. Adams/Solver (C++) uses the value of LENGTH to specify the z
distance between the two circles. There is no limit on the value of r. A positive value
specifies a cylinder or frustum along the positive z-axis of the CM marker, and a
negative value specifies a cylinder or frustum along the negative z-axis of the CM
marker.
MAJOR_RADI
US
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
RADIUS=r
Defines the radius of a circle, arc, or cylinder. There is no limit on the value of r.
146 Adams/Solver
C++ Statements
RANGLE=r
Defines an angle measured positive (according to the right-hand rule) about the zaxis of the CM. Adams/Solver (C++) assumes RANGLE is in radians. The angle
starts at the positive x-axis of the CM marker and subtends the arc, the arc of the
cylinder, or the arc of the cone frustum, or the arc of the Torus. Adams/Solver (C++)
clips to -2 values of r less than -2 and clips to 2 values of r greater than 2 .
Range: 2 > r > -2
REVOLUTION
RM=id
Defines the radius of a circle, arc, or cylinder. Adams/Solver (C++) measures the
distance from the CM marker to the RM marker to determine the radius.
SEG=i
Defines the number of straight line segments Adams/Solver uses to draw a curve,
circle, an arc, or the two circles at the ends of a cylinder or a frustum, or the arc of
the Torus.
Default: 20
Range: 99,999 > SEG >0
SIDES=i
Defines the number of straight line segments Adams/Solver draws between the two
parallel circles of a cylinder or a frustum, or the arc of the Torus.
Default: 20
Range: 99,999 > SIDES > 0
SPDP
TOP=r
Defines the radius at the top of a frustum. The top is perpendicular to the CM marker
z-axis, and the center of the top is at the position on the CM marker z-axis that
LENGTH specifies. There is no limit on the value of r.
GRAPHICS 147
C++ Statements
TORUS
Creates a torus graphic. You use the following arguments to create a torus:
CM to specify the id of the marker that defines the center of the torus. The z-axis
X=x,Y=y,Z=z
Locates the vertex of the box that is diagonally opposite from the corner defined by
CORNER. The values of X, Y, and Z must be specified with respect to the marker
coordinate system.
Extended Definition
The GRAPHICS statement creates three-dimensional graphic data for display on a graphics device. You
can use it to create line segments, boxes, curves, circles, arcs, cylinders, frustums of cones, and springdampers. 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 cross-section, which has a radius of two. The cylinder has a length of two along the
negative z-axis of Marker 0201. Twenty sides define the body of the cylinder, and the circles at the top
and at the bottom of the cylinder are actually twenty-sided polygons.
GRAPHICS/0001, OUTLINE=1001,1002,-1003,1004
This GRAPHICS statement creates a line from Marker 1001 to Marker 1002 and creates a line from
Marker 1003 to Marker 1004. Because a minus sign (-) precedes Marker 1003, the statement creates an
invisible line segment from Marker 1002 to Marker 1003.
See other Geometry statement available.
148 Adams/Solver
C++ Statements
GSE
The GSE (General State Equation) statement lets you represent a subsystem that has arrays of input
variables (u), internal continuous states (xc), internal discrete states (xd), and output variables (y).
The GSE is represented mathematically in one of two ways. The first is described by Equations (1), (2),
and (3) below. It is for systems in which the time derivative of the continuous states can be written
explicitly, and it is thus known as an explicit GSE:
x c = f c ( x c, u, t )
x c ( t 0 ) = x c0
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 )
(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 xc are
defined in Equation (1) as explicit, first-order, ordinary differential equations. The function fc(xc, u, t) is
specified in a user-written subroutine, and is assumed to be continuous everywhere. (The names of this
and other user-written subroutines are specified by the user via the ROUTINE or INTERFACE attributes
of the GSE statement.) Integrators in Adams/Solver (C++) evaluate fc(xc, u, t) as needed.
The states xd are defined in Equation (2) by the function fd(xd(n), u, tn). This function is specified in a
second user-written subroutine. Equation (2) is a difference equation. A sampling period is associated
with Equation (2), and integrators only evaluate Equation (2) at the sample times. The states xd are
assumed to be constant between sampling periods. In Equation (2), xd(n) is the short form for xd(tn).
The outputs y are defined in Equation (3) by g(xc, xd, u, t), and are sampled continuously. This function
is specified in a third user-written subroutine. It may be discontinuous in nature. If the outputs are to be
fed back into the mechanical system through a force element, then it is customary to eliminate the
discontinuities in y by passing the appropriate output variables through a low-pass filter before feeding
those signals into the force element. You can use the TFSISO element to define a low-pass filter. Failure
to eliminate discontinuities in y is likely to cause significant numerical-integration difficulties.
The second way (mentioned above) of representing a GSE mathematically is described by replacing
Equation (1) above with (4) below:
0 = f c ( x c, x c, u , t )
x c ( t 0 ) = x c0
(4)
This representation permits the modeling of implicitly-defined states a more general capability than
what is possible with the default representation of Equation (1). This representation is thus known as an
implicit GSE, and its use requires the inclusion of the IMPLICIT attribute of the GSE statement.
Equations (2) and (3) are the same for explicit and implicit GSEs.
Note that the use (that is, interface) of the implicit form is more restricted than in the default case.
Specifically, you must call the Array query utility subroutines: GSE_X, GSE_XDOT, GSE_XD, GSE_U()
GSE 149
C++ Statements
to obtain the values of x c, x c, x d, and u respectively, 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
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
150 Adams/Solver
C++ Statements
Arguments
FUNCTION=USER(r1[,...,r30])
IC=id
IMPLICIT
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
ND=i
GSE 151
C++ Statements
NO=i
NS=i
ROUTINE=lib1::gse1,
Specifies alternative library and subroutine names for the
lib2::gse2, lib3::gse3, lib4::gse4, deprecated user subroutines GSESUB, GSEXX, GSEXU, GSEYX,
lib5::gse5
GSEYU respectively.
Learn more about the ROUTINE Argument.
SAMPLE_OFFSET=r
SAMPLE_PERIOD=expression
STATIC_HOLD
Indicates that the continuous GSE states are not permitted to change
during static and quasi-static simulations.
U=id
X=id
152 Adams/Solver
C++ Statements
Y=id
XD=id
Extended Definition
The GSE (General State Equation) statement defines the equations for modeling a nonlinear, time
varying, dynamic system. The statement is especially useful for importing nonlinear control laws
developed manually or with an independent software package. It can also be used to define an arbitrary
system of coupled differential and algebraic equations:
The GSE allows you to implement four different kinds of systems. These are:
Continuous Systems
Discrete Systems
Sampled Systems
Feed-Forward Only System
Continuous Systems
Continuous systems can be represented either explicitly or implicitly. The explicit case is written in statespace form as:
x c = f c ( x c, u, t )
y = g (x c,u ,t)
x c ( t 0 ) = x c0
(5)
(6)
where xc is called the state of the system, and contains n elements for an nth-order system. In matrix
notation, xc is a column matrix of dimension n x 1. u defines the inputs to the system. Its size is equal to
the number of inputs to the system being modeled. In this description, the system is assumed to have m
inputs, 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.
GSE 153
C++ Statements
Using this system description, a nonlinear, second-order differential equation, with a single input u, such
as:
2
y + 2 n yy + n y = Ku
(7)
x2
x 1
x 2
2 n x 1 x 2 2n x 1 + Ku
y = x1
(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:
0 = f c ( x c, x c, u, t )
x c ( t 0 ) = x c0
y = g ( x c ,u ,t )
(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:
x 1 x 2
0
=
2
0
x 2 + 2 n x 1 x 2 + n x 1 Ku
(12)
The major advantage of the implicit representation is that a more general set of equations can be solved
because the dependence on the x c terms can be nonlinear. A second advantage is that derivation of the
state equations for a dynamical system in implicit rather than explicit form is usually easier, and the
required partial derivatives of the state equations are usually much simpler expressions.
Discrete Systems
Discrete systems can be described by their difference equations. They are, therefore, represented in statespace form as:
x d ( n + 1 ) = f d ( x d ( n ), u, t n )
x d ( t 0 ) = x d0
(13)
154 Adams/Solver
C++ Statements
y = g ( x d ,u ,t )
(14)
xd is called the state of the system, and contains n elements for an nth-order system. In matrix notation,
xd is a column matrix of dimension n x 1. u and y have the same meaning as for continuous systems.
The fundamental difference between continuous and discrete systems is that the discrete or digital system
operates on samples of the sensed plant data, rather than on the continuous signal. The dynamics of the
controller are represented by recursive algebraic equations, known as difference equations, that have the
form of Equation (13).
The sampling of any signal occurs repetitively at instants in time that are seconds apart. is called
the sampling period of the controller. In complex systems, the sampling period is not a constant, but is,
instead, a function of time and the instantaneous state of the controller. The signal being sampled is
usually maintained at the sampled value in between sampling instances. This is called zero-order-hold.
Determining an appropriate sampling period is a crucial design decision for discrete and sampled
systems.
One major problem to avoid with sampling is aliasing. This is a phenomenon where a signal at a
frequency
0 produces a component at a different frequency 1 only because the sampling occurs too
, the sampling
frequency ( s ) is calculated from s 2 . This is an extreme lower limit for . If you want
If you want to avoid aliasing in a signal with a maximum frequency of
s
such that 20 < ------ < 40 .
The sampling rate for sampling the states of a discrete system must follow the above criterion to avoid
aliasing.
Note that when an Adams/Solver output time and a GSE sample time coincide, the output of the GSE at
that time will be calculated using the values of the discrete states before the update takes place. This is
true for discrete states in discrete systems and sampled systems.
Sampled Systems
There are many systems that are neither continuous nor discrete. Some signals are sampled at discrete
intervals, while others are sampled continuously. These systems are called sampled systems and are
represented in state-space form as:
x c = f c ( x c, u, t )
0 = f c ( x c, x c, u , t )
x c ( t 0 ) = x c0
x c ( t 0 ) = x c0
x d ( n + 1 ) = f d ( x d ( n ), u, t n )
x d ( t 0 ) = x d0
(15)
(16)
(17)
GSE 155
C++ Statements
y = g ( x c, x d, u, t )
(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.
Feed-Forward Only System
Feed-Forward Only Systems are systems that have no internal states. The output of the system is an
algebraic function of the inputs. They can be represented as:
y = g (u,t)
(19)
156 Adams/Solver
C++ Statements
Caution:
The GSE statement provides a very general capability for modeling nonlinear
systems. However, the routines for solving the linear equations in Adams/Solver
(C++) have been developed and refined to work particularly well with the sparse
systems of equations that come from the assembly of mechanical models. With the
GSE statement, you can create very dense sets of equations. If these equations
form a large portion of the completed model, Adams/Solver (C++) may perform
more slowly than expected.
To improve the performance of Adams/Solver (C++), any arrays of partial
derivatives which are not full can be represented in sparse form. This sparse form
can substantially reduce the effort required by the integrator. To represent the
partials in sparse form, use the GSEMAP_* utility subroutines, when calling
GSE_DERIV with IFLAG=1, to define the sparsity. Then, use the GSEPAR_*
utility subroutines to pass the sparse partial arrays to the integrator.
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 user-defined variables to zero,
and uses the user-supplied initial-condition values only as an initial guess for the
static solution. Generally, the final equilibrium values are not the same as the
initial condition values. Adams/Solver (C++) then uses the equilibrium values of
the user-defined variables as the initial values for any subsequent analysis, just as
with the equilibrium displacement and force values.
However, the user-specified initial conditions are retained as the static equilibrium
values when STATIC_HOLD is specified. Thus, the final equilibrium values are
the same as the user-specified initial conditions. Note that this does not guarantee
that the time derivatives of the user-defined variable are zero after static analysis.
Examples
Modeling Control Systems
The example below demonstrates how you can use a GSE to define a controller in Adams. The plant
consists of a block on a translational joint. A control force is to be applied to the block so that it translates
exactly 150 mm from its initial position. The control system is defined as follows.
Inputs
The first input (u1) is the location of the block.
The second input (u2) is the velocity of the block.
Outputs
GSE 157
C++ Statements
States
The controller is a linear PID controller.
It has two continuous states (x1 and x2).
Transfer Functions
Y(s)
2e7
-------------- = --------------------------------------- ,
2
U1 ( s )
s + 2e3s + 1e7
Y(s)
1e3s 1e7
---------------- = --------------------------------------U 2 ( s ) s 2 + 2e3s + 1e7
A GSE represents the controller. Standard Adams modeling elements PART, JOINT, and SFORCE
represent the block, translational joint, and the actuator, respectively.
Model Input File
GSE Test: Continuous states=2, Discrete states=0, Outputs=1
units/force=newton, mass=kilogram, length=millimeter, time = second
part/1, ground
marker/3, part = 1, reuler = 90d, 90d, 0d
marker/5, part = 1, qp = -150, 0, 0, reuler = 90d, 90d, 0d
part/2, qg = 0, 0, -100, mass = 46, cm = 6, ip = 2e5, 5e5, 4e5
marker/2, part = 2, qp = 0, 0, 100, reuler = 90d, 90d, 0d
marker/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.
158 Adams/Solver
C++ Statements
The next figure shows the time history of the actuator signal computed by the controller. This is the force
applied on the block. Notice that the actuator signal changes sign when the block is about to overshoot
its target value.
GSE 159
C++ Statements
160 Adams/Solver
C++ Statements
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
GSE 161
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 user-supplied subroutine needs to be changed as follows (note
comments included in the code):
SUBROUTINE GSE_DERIV(ID, TIME, PAR, NPAR, DFLAG, IFLAG, NS, F)
C
C Inputs:
C
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.
162 Adams/Solver
C++ Statements
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.
Note:
The only change to the previous example is in the GSE_DERIV user-supplied subroutine. In this case it
looks like:
SUBROUTINE GSE_DERIV(ID, TIME, PAR, NPAR, DFLAG, IFLAG, NS, F)
C
C Inputs:
C
INTEGER ID, NPAR, NS
DOUBLE PRECISION PAR(*), TIME
LOGICAL IFLAG, DFLAG
C
GSE 163
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
164 Adams/Solver
C++ Statements
Again, the results are identical to the previous two examples to within roundoff error.
See other Generic systems modeling available.
IC 165
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
ALIMIT=r
AMAXIT=i
166 Adams/Solver
C++ Statements
APATTERN=c1[: Specifies as many as ten character strings that together establish the pattern for
...:c10]
evaluating the Jacobian matrix during the modified Newton-Raphson solution
for the accelerations. For each iteration, T or TRUE indicates that Adams/Solver
(C++) is to evaluate the Jacobian, and F or FALSE indicates that Adams/Solver
(C++) is not to evaluate the Jacobian. Thus, cj determines whether or not
ADAMS is to evaluate the Jacobian at the jth iteration. If necessary,
Adams/Solver (C++) repeats the pattern of evaluation until it reaches the
maximum number of iterations (AMAXIT). The number of T's or TRUEs and
Fs or FALSEs 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
MAXIT=i
PATTERN=ci[:...: Specifies as many as ten character strings that together establish the pattern for
c10]
evaluating the Jacobian matrix during the modified Newton-Raphson solution
for the displacements. For each iteration, T or TRUE indicates that
Adams/Solver (C++) is to evaluate the Jacobian, and F or FALSE indicates that
Adams/Solver (C++) is not to evaluate the Jacobian. Thus, cj determines whether
or not ADAMS is to evaluate the Jacobian at the jth iteration. If necessary,
Adams/Solver (C++) repeats the pattern of evaluation until it reaches the
maximum number of iterations (MAXIT). The number of Ts or TRUEs and Fs
or FALSEs 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.
IC 167
C++ Statements
TLIMIT=r
VERROR=r
Extended Definition
The IC statement specifies error tolerances and other parameters for the analysis of initial conditions and
for reconciling integrator output. By default, WSTIFF reconciles integrator results to be consistent with
constraints; GSTIFF does not, unless you set INTERPOLATE=ON.
This statement is used only when requesting a dynamic, static equilibrium, or quasi-static equilibrium
analysis, and when one or more of the tolerances and other parameters for the initial conditions analysis
from the default values is to be changed.
Use the SIMULATE command to request a dynamic, static equilibrium, or quasi-static equilibrium
analysis. Before performing one of these analyses, Adams/Solver (C++) automatically does an initial
conditions analysis. An initial conditions analysis is not necessary when the system has zero degrees of
freedom because the kinematics of the system fully determine its configuration.
The initial conditions analysis ensures that the system satisfies all constraints within the system. If
necessary, Adams/Solver (C++) moves parts until both parts of each joint are in contact. This analysis
involves three separate phases. First, Adams/Solver (C++) makes the displacements between all parts and
joints in the system physically consistent. This requires the use of Newton-Raphson iteration to solve a
set of nonlinear algebraic equations. Once the displacements are consistent, Adams/Solver (C++) makes
the velocities physically consistent. Since this requires solving a set of linear equations, iteration is not
necessary. Finally, Adams/Solver (C++) also calculates consistent accelerations and forces. This solution
also requires solving a set of nonlinear equations using Newton-Raphson iteration.
When reconciling, the integrator uses the initial conditions solution process at each output step to ensure
that velocities, accelerations, and forces are consistent with the system constraints. If you set
INTERPOLATE=ON, the integrator also uses the initial conditions solution at each output step to ensure
displacements are consistent with the constraints. The IC parameters control those solutions as well as
the initial conditions solution.
168 Adams/Solver
C++ Statements
If you issue neither the IC command nor statement in an Adams/Solver (C++) session, the solver uses the
default values for AERROR, ALIMIT, AMAXIT, APATTERN, ERROR, MAXIT, PATTERN, TLIMIT,
and VERROR when finding initial conditions and reconciling integrator output.
Tip:
Use the ALIMIT and TLIMIT arguments to limit incrementing displacement variables and
thus the size of the position change on successive iterations. This tends to prevent
Adams/Solver (C++) from assembling the mechanism in an undesirable configuration.
Examples
IC/ALIMIT=10D, ERROR=1.0E-6, MAXIT=45
This statement instructs Adams/Solver (C++) to use these values instead of the defaults when performing
an initial conditions analysis. It limits the angular increment per iteration to 10 degrees, reduces the
displacement error to 1.0E-6, and limits the number of iterations to 45.
See other Analysis parameters available.
INTEGRATOR 169
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
170 Adams/Solver
C++ Statements
Arguments
ALPHA=r
Defining coefficient for the HHT method. Learn more about HHT.
Default value: -0.3
Range: -0.3 < ALPHA < 0
BETA=r
2
-------------------4
INTEGRATOR 171
C++ Statements
ERROR=r
2
-------------------4
172 Adams/Solver
C++ Statements
GSTIFF
HHT
HINIT=r
HMAX=r
and Newmark
Range: 0 < HMIN < HINIT < HMAX
INTEGRATOR 173
C++ Statements
INTERPOLATE = ON
OFF
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:
I3
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,
174 Adams/Solver
C++ Statements
MAXIT=i
NEWMARK
PATTERN=c1[:...:c10]
INTEGRATOR 175
C++ Statements
SI2
WSTIFF
HASTIFF
SI1
176 Adams/Solver
C++ Statements
Extended Definition
You use the INTEGRATOR statement to select an integrator when you choose to perform a dynamic
analysis. The dynamic analysis of a mechanical system consists essentially of numerically integrating the
nonlinear differential equations of motion.
Ordinary differential equations (ODEs) can be characterized as being stiff or non-stiff. A set of ODEs is
said to be stiff when it has widely separated eigenvalues (low and high frequencies) with the high
frequency eigenvalues being overdamped. Therefore, while the system has the ability to vibrate at high
frequencies, it usually does not because of the associated high damping, which dissipates this mode of
motion.
The stiffness ratio of a set of ODEs is defined as the highest inactive frequency divided by the highest
active frequency. Stiff ODEs typically have a stiffness ratio of 200 or higher. In contrast, non-stiff
systems have a stiffness ratio less than 20. This basically means that for a non-stiff system of ODEs, the
higher frequencies of the system are active. The system can and does vibrate at these frequencies.
An example of a stiff system is a flexible body in which the higher frequencies have been damped out
completely, leaving only the lower frequency vibration modes active.
The system above becomes non-stiff if the higher frequencies are excited by an external force. Nonlinear
ODEs can be stiff at some points in time and non-stiff at other points.
Learn more about:
Stiff and Non-Stiff Integrators
Prediction
Correction
GSTIFF
SI2
ODE versus DAE
WSTIFF
The HHT and Newmark Integrators
HASTIFF
Stiff and Non-Stiff Integrators
Integrators are classified as stiff or non-stiff. A stiff integrator is one that can handle numerically stiff
systems efficiently. For stiff integrators, the integration step is limited by the inverse of the highest active
frequency in the system. For non-stiff integrators, the integration step is limited by the inverse of the
highest frequency (active or inactive) in the system. Thus, non-stiff integrators are notoriously inefficient
for solving stiff problems.
Because many mechanical systems are numerically stiff, the default integrator in Adams/Solver (C++) is
GSTIFF, a stiff integrator that is based on the DIFSUB integrator developed by C.W. Gear. Gear's
DIFSUB integrator is unrelated to the Adams/Solver subroutine that is known by the same name.
WSTIFF is another stiff integrator available in Adams/Solver (C++). Both GSTIFF and WSTIFF
INTEGRATOR 177
C++ Statements
integrators are based on Backward-Difference Formulae (BDF) and are multi-step integrators. The
solution for these integrators occurs in two phases: a Prediction followed by a Correction.
Prediction
When taking a new step, the integrator fits a polynomial of a given order through the past values of each
system state, and then extrapolates them to the current time to perform a prediction. Standard techniques
like Taylor's series (GSTIFF) or Newton Divided Differences (WSTIFF) are used to perform the
prediction.
Prediction is an explicit process in which only past values are considered, and is based on the premise
that past values are a good indicator of the current values being computed. The predicted value does not
guarantee that it will satisfy the equations of motion or constraint. It is simply an initial guess for starting
the correction, which ensures that the governing equations are satisfied.
The degree of polynomial used for prediction is called the order of the predictor. For example, a predictor
of order 3 will fit a cubic polynomial that includes the past 4 values for each state. Clearly, if the
governing equations are smooth, the prediction will be quite accurate. On the other hand, if the governing
equations are not smooth, the prediction can be quite inaccurate.
Correction
The corrector formulae are an implicit set of difference relationships (BDFs) that relate the derivative of
the states at the current time to the values of the states themselves. This relationship transforms the
nonlinear differential algebraic equations to a set of nonlinear, algebraic difference equations in the
system states. The Backward Euler integrator is an example of a first-order BDF. Given a set of ODEs of
the form dy/dt = f (y,t), the Backward Euler uses the difference relationship:
y n + 1 = y n + hy n + 1
(20)
where:
yn is the solution calculated at t = tn.
h is the step size being attempted.
yn+1 is the solution at = TN+1, which is being computed.
Notice that the subscript n+1 is on both sides of Equation (20). This is an implicit method.
Adams/Solver (C++) uses an iterative, quasi-Newton-Raphson algorithm to solve the difference
equations and obtain the values of the state variables. This algorithm ensures that the system states satisfy
the equations of motion and constraint. The Newton-Raphson iterations require a matrix of the partial
derivatives of the equations being solved with respect to the solution variables. This matrix, known as
the Jacobian matrix, is used at each iteration to calculate the corrections to the states.
Assume that the equations of motion have the form:
F (y,y ,t) = 0
where y represents all the states of the system.
(21)
178 Adams/Solver
C++ Statements
F
k k
F (y,y ,t) = F (y ,y ,t) + -----y
k
k
= y and y = y gives:
F
k
( y y ) + -----y
k
y ,y
k
( y y ) = 0
k k
y ,y
replacing y - yk with
F
k k
F (y ,y ,t) + -----y
F
y + -----y
k
y ,y
y = 0
(22)
k
y ,y
k
From Equation (20), which is a first-order BDF, you can get the relationship:
1
y = --- y
h
(23)
1 F
+ --- -----h y
k
y ,y
y = F (y
y ,y
k
(24)
1 F
+ --------- -----h 0 y
k
y ,y
y = F (y
(25)
k
y ,y
k
where:
0 is a scalar that is characteristic to an integration order. This scalar is constant for each
integration order.
The matrix on the left side of Equation (25) is the Jacobian matrix of F.
The corrector is said to have converged when the residue F and the corrections
After the corrector has converged to a solution, the integrator estimates the local integration error in the
solution. This is usually a function of the difference between the predicted value and the corrected value,
the step size, and the order of the integrator. If the estimated error is greater than the specified integration
ERROR, the integrator rejects the solution and takes a smaller time step. If the estimated error is less than
the specified local integration ERROR, the integrator accepts the solution and takes a new time step. The
INTEGRATOR 179
C++ Statements
integrator repeats the prediction-correction-error estimation process until it reaches the time specified in
the SIMULATE command.
Note:
The premise for using predictions as an initial guess for the corrector is severely violated
when discontinuities occur or when large forces turn on or off in the model. Contact,
friction, and state transitions (as in hydraulics where a valve is suddenly closed or opened)
are examples of such phenomena. These kinds of models are difficult for multi-step
integrators.
The corrector in a stiff integrator ensures that all candidate solutions satisfy the equations of the system.
The two algorithms, original and modified, differ primarily in the strategy that they use to define when
the corrector iterations have converged.
The CORRECTOR=modified setting is helpful for models containing discontinuities in the forcing
functions. Problems with contacts belong in this category.
Correction summary tables:
Original Corrector
Modified corrector
180 Adams/Solver
C++ Statements
GSTIFF
GSTIFF is based on the DIFSUB integrator. GSTIFF is the most widely-used and tested integrator in
Adams/Solver (C++). It is a variable-order, variable-step, multi-step integrator with a maximum
integration order of six. The BDF coefficients it uses are calculated by assuming that the step size of the
model is mostly constant. Thus, when the step size changes in this integrator, a small error is introduced
in the solution. This formulation offers the following benefits and limitations:
Characteristics of GSTIFF Integrator
Benefits
High speed.
High accuracy of the system
displacements.
Robust in handling a variety of
analysis problems.
Limitations
Velocities and especially accelerations can have
Jersey: Prentice-Hall.
SI2
SI2 (Stabilized-Index Two) is an equation formulation technique that can be used for equations
describing mechanical systems. This formulation is available with both GSTIFF and WSTIFF
integrators.
To understand what the SI2 formulation does, you need to know what Differential Algebraic Equations
(DAE) are and understand the notions of Index of a DAE and stabilization of DAE. A brief summary is
given below. For more information, refer to:
Brenan, K.E., Campbell, S.I., and Petzold, L.R. (1996). Numerical Solution of Initial Value
INTEGRATOR 181
C++ Statements
E y f ( y ,t ) = 0, y ( 0 ) = y 0
is defined to be a set of ODEs, because
(26)
E
= I , and is never singular.
y
E F ( y ,y ,t ) = 0, y ( 0 ) = y 0
(27)
E
y
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:
T
T
Mq + q A F (q,q ) = 0
(28)
(q,t) = 0
(29)
where:
M is the mass matrix of the system.
q is the set of coordinates used to represent displacements.
F is the set of applied forces and gyroscopic terms of the inertia forces.
AT is the matrix that projects the applied forces in the direction q.
q is the gradient of the constraints at any given state and can be thought of as the normal to the
constraint surface in the configuration space.
Notice that Equation (28) is a second-order differential equation but Equation (29) is an algebraic
equation. Also notice the time derivatives of q are seen in Equations (28) and (29), but
in either Equation (28) or (29).
is not present
The index of a DAE is defined as the number of time derivatives required to convert a set of DAEs to
ODEs.
182 Adams/Solver
C++ Statements
Equations (28) and (29) can be converted to a set of ODE by first taking two time derivatives of the
kinematic position constraint equations in Eq. (29), to obtain the set of kinematic acceleration constraint
equations. These equations together with the equations of motion in Eq. (28) can be formally solved for
the accelerations and the Lagrange multipliers . By taking a third and last time derivative of the
Lagrange multipliers, you are left with a set of ODE in accelerations and the Lagrange multipliers.
Therefore, the Euler-Lagrange equations for mechanical systems are said to have an Index=3.
Solution of DAEs
Equations (28) and (29)are converted to first-order form, so that commercially available DAE integrators
can solve them. This is usually done by introducing a new variable, the velocity variable u, which is
defined as:
u q = 0
(30)
(31)
u q = 0
(32)
= 0
(33)
These are the DAE (in first order form) for a mechanical system. Applying the BDF formula (like
Equation (23), one obtains the Jacobian of Equation (31):
MT
------- A FU
h 0
M q u + qq ( A F )
I
--------h 0
(34)
This matrix becomes ill-conditioned as the integration step size h decreases, and becomes singular as h
moves closer to 0.
This is the reason why Index 3 formulations become unstable at small step sizes -- a very counterintuitive 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
INTEGRATOR 183
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):
( q ,u ) = 0
(35)
Solving Equations (31), (32), and (35) numerically adds a new complication, however. The solution
satisfies Equation (35), but is not guaranteed to solve Equation (33), the original constraint.
If you were to formulate a simple pendulum using Equations (31), (32), and (35) and solve them, you
would notice that after some time the pin-joint constraint is violated and the pendulum drifts off into
space, grossly violating the pin-joint, and the system Equation (31) is not aware.
Clearly, a means for considering Equation (33) along with Equations (31), (32), and (35) to prevent driftoff is required. The SI2 formulation does precisely this.
The SI2 Formulation
Gear, Gupta, and Leimkuhler have shown that drift-off can be prevented by appending Equation (33) to
(31) and adding a new set of variable as follows:
T
T
Mu + q A F = 0
T
u q + q = 0
( q ,u ,t ) = 0
(q,t) = 0
(36)
Equations (36) are stabilized. Because the constraints have been differentiated once, Equation (36) has
an Index = 2.
Equations (36) are called the Stabilized Index Two representation of Equations (31), (32), and (33). It has
been proven that Equation (36) and Equation (31), (32), and (33) have the same solution when = 0. This
condition is rigorously enforced by the SI2 formulation in Adams/Solver (C++).
It can also be shown that the Jacobian of Equation (36) does not become ill-conditioned as h moves closer
to 0. Furthermore, since Equation (36) has an Index of 2, the integrators can monitor integration error on
both u and q.
There is, however, an alternative method for implementing the SI1 formulation that is promising.
184 Adams/Solver
C++ Statements
The benefits and limitations of the SI2 formulation are described in the following table:
Characteristics of the SI2 Formulation
Benefits of the SI2 formulation:
Gives very accurate results, especially for
accurately.
WSTIFF
INTEGRATOR 185
C++ Statements
The HHT integrator is based on the -method proposed by H.M. Hilber, T.J.R. Hughes, and R.L. Taylor
[1]. The -method is widely used in the structural dynamics community for the numerical integration
of second order ordinary differential equations that are obtained at the end of finite element
discretization. If the finite element approach is linear, the equations assume the form:
Mq + Cq + Kq F ( t )
(37)
The mass, damping, and stiffness matrices, M, C, and K, respectively, are constant, and the force F
depends on time.
-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 .
The
qn + 1
h
= q n + hv n + ----- [ ( 1 2 )a n + 2a n + 1 ]
2
(38)
v n + 1 v n h [ ( 1 )a n + a n + 1 ]
(39)
In the Newmark formulation, these formulas are used to discretize the equations of motion (37)
Ma n + 1 + Cv n + 1 + Kq n + 1 = F n + 1
where an+1, vn+1, and qn+1 are numerical approximations for
(40)
q ( t n + 1 ) , q ( t n + 1 ) , and q ( t n + 1 )
respectively.
The Newmark method is implicit and A-stability (stability in the whole left plane) is guaranteed as soon
as:
1
--2
2
+ 1---
2
-------------------4
(41)
(42)
1
1
= --- and = --- , which makes
4
2
the Newmark method same as the trapezoidal rule, which is a second-order method. The drawback of the
trapezoidal rule is that it has poor damping properties, which is unacceptable for problems that have
either:
High oscillations that are of no interest
186 Adams/Solver
C++ Statements
Parasitic oscillations that are a byproduct of the finite element discretization process
The -method came as an improvement as it preserved the A-stability of the Newmark formulas, while
achieving second-order accuracy when used with the second-order linear ODE problem of Equation (37).
The change to obtain this improvement does not pertain to the formulas proposed by Newmark, but rather
the form of the discretized equations of motion in (40). The new equation in which the integration
formulas of equations (38) and (39) are substituted is:
Ma n + 1 + ( 1 + )Cv n + 1 Cv n + ( 1 + )Kq n + 1 Kq n = F ( t n + 1 )
(43)
where
t n + 1 = t + ( 1 + )h
n
(44)
The equations of motion associated with multi-body dynamics simulation in Adams are:
T
Mq + q = F ( q ,q ,t )
(45)
These equations are neither linear, nor ordinary differential as is the case in equation (37), because the
solution q(t) must also satisfy the kinematic constraint equations:
( q ,t ) = 0
Looking at equation (43), the idea behind the HHT discretization is that the
(46)
-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 multi-body formulation, the force is computed as
T
q F ( q ,q ,t ) ; (that is, everything that is not explicitly depending on acceleration q ). Therefore, in
relation to the original HHT formulation, the discretization of the multi-body dynamics equations of
motion is:
T
T
( Mq ) n + 1 + ( 1 + ) ( q F ) n + 1 ( q F ) n = 0
(47)
) and
1 -
T
T
-----------( Mq )
+ ( q F ) n + 1 ------------- ( q F ) n = 0
1+
1+
n+1
(48)
The second set of equations that must be satisfied at time tn+1 are the position kinematic constraint
equations:
( qn + 1 ) = 0
(49)
INTEGRATOR 187
C++ Statements
T
T
e 1 ( q ,q , ) ------------- ( Mq ) n + 1 + ( q F ) n + 1 ------------- ( q F ) n
1+
1+
e 2 ( q, t ) ( q n + 1 ,t n + 1 )
the simulation is advanced from time tn to tn+1, by finding the solution of the nonlinear system:
e ( q, )
( q, ) = 1
e 2 ( q, t )
(50)
q and . Note that although q and q appear in equation (50), they are
q based on the formulas of equations (38) and (39) (the notation used there was v
q , and a for q ). These integration formulas define linear relationships of the form
q n + 1 = f 1 ( q n + 1 ) and q n + 1 = f 2 ( q n + 1 ) . It is easy to see that based on equations (38) and (39)
for
q
----- = h 2
q
q
----- = h
q
e 1
1 F
1
F 2
T
------- = -----------M ------ h + ------------- ( Mq ) q ( q ) q ------ h
q 1 +
q
1+
q
e 1
-------- = Tq
e 2
------- = q h 2
q
e 2
-------- = 0
1
F
1
F
2
T
M = ------------- M ------ h + ------------- ( Mq ) q + ( q ) q ------ h
1+
q
1+
q
one correction in the quasi-Newton algorithm is computed as the solution of the linear system:
(51)
188 Adams/Solver
C++ Statements
e1
q q
=
2
e2
q h 0
(52)
To balance the coefficient matrix in the previous linear system, the last row is scaled by
1-------:
2
h
e1
T
M q q =
e2
--------2 q 0
h
(53)
(k + 1)
(k)
(54)
k
(k + 1)
(55)
and
(k + 1)
(k + 1)
are computed using the new value q
and equations
q
The role of the corrector is to calculate the quantities q and at the new time step tn+1. After these
quantities are computed the accuracy of the results at the current step is verified against the user-specified
error tolerance. If the local integration error is less than the user-specified error the integration step is
accepted; otherwise, it is rejected and a new smaller step size is tried.
For more information on error-estimation step-size selection and corrector-stopping criteria, refer to
Knowledge Base Article 12299.
Remarks:
The following explains how the HHT and Newmark integrators are more efficient than the
INTEGRATOR 189
C++ Statements
2. When compared with the BDF-based approach, the resulting HHT Jacobian is numerically better
conditioned, which leads to more reliable corrections in the Newton-like iterative approach for
large problems. Typically, at each integration step, this results in a smaller number of corrector
iterations. In addition, because certain partial derivatives are scaled by the step-size, or the square
of the step-size before populating the Jacobian, small errors in the partial derivatives computation
will have a lesser negative effect on the overall quality of the Jacobian.
3. The BDF formulas of order higher than 1 contain regions of instability in the left plane. The higher
the order, the smaller the region of stability. In addition, BDF is intrinsically designed to
maximize the order and step-size of the integration. Because of these two conflicting attributes,
particularly for models that are mechanically stiff (models with stiff springs, flexible bodies),
there are many instances when a order/step-size choice puts the BDF integrator outside the
stability region. These integration time-steps are typically rejected, and smaller step-sizes are
required to advance the simulation. This is not an issue with the HHT integrator, which is a fixed
low order method (second order for HHT, mostly first order for Newmark).
4. The HHT is a one-step integration formula that further gives it a small edge over multi-step
methods, such as high-order BDF-type integrators.
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:
1 2
= ---------------2
(1 )
= -------------------4
The priority of the HHT and Newmark integrator is speed rather than accuracy. If accuracy is of
concern, the current integrators available in Adams historically are very accurate and serve the
purpose well.
The HHT and Newmark error control for DIFF, TFSISO, LSE, and GSE elements is
significantly more lax than the one carried out for these elements by the other integrators
available in Adams/Solver (C++) (such as GSTIFF, WSTIFF, and so on). This is related to the
nature of the HHT and Newmark integration formulas, which deal exclusively with second-order
differential equations. To have these formulas accommodate DIFF's for example, these are first
converted from first- into second-order differential equations. The consequence of this
transformation is that error control is now performed on the integrals of the DIFF states, rather
than on the actual states. As far as smoothness is concerned, it is well known that an integral of a
quantity is better behaved than the quantity itself. Consequently, the HHT and Newmark
integrators are typically more optimistic in selecting integration step-sizes. While these stepsizes 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.
190 Adams/Solver
C++ Statements
The default ERROR for HHT and Newmark is 1.E-5. This tighter default value is intended to
counterbalance the different step-size selection strategy employed by these integrators, and can
be regarded as a calibration procedure. The goal is that working with the corresponding default
values of the ERROR attribute both the HHT and GSTIFF integrators will produce results of
similar quality.
Note that the default integrator in Adams/Solver (C++) is GSTIFF, and, therefore, the default
ERROR associated with a simulation is 1.E-3. GSTIFF and ERROR=1.E-3 are the settings that
are provided to the solver if in the .adm file you do not explicitly sets these attributes through the
INTEGRATOR statement.It is important to understand that under these circumstances, if you
later change the integrator to HHT through a command issued in the .acf file, unless the
command explicitly specifies otherwise, the ERROR value of 1.E-3 (associated with GSTIFF)
will be inherited. The correct command to issue would be INTEGRATOR/HHT, DEFAULTS, if
the goal were to run HHT with its default ERROR setting, that is ERROR=1.E-5. Learn more in
the INTEGRATOR command.
Benefits of the HHT and Newmark
Integrators
Expected to result in a smaller number of
Jacobian evaluations.
Unlike BDF-type formulas, behaves like a
step size.
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
INTEGRATOR 191
C++ Statements
HASTIFF
y'
= hF y + F y'
y', HA
y= (u
1
T
T
M hS u 1
h ( M ( q, t )u' + q ' S ( q, u, t ) ) q
q
T
T
( hI )
I h ( q ' ) q
0
q
=
0
q
0
0
q
( q u ) q + q, t
0
0
T T
Mu' + Tq ' S 1 ( q, u, t )
q' u q '
= 0
F ( y, y', t ) =
1
---- ( q, t )
----(
u
+
t
)
h q
solving for y (y discretized as a function of y):
y n + 1 = ( y n, ..., y n k ) + hy' n + 1
F ( + hy', y', t ) = 0
HASTIFF is the integrator in Adams/Solver (C++). It is a variable-order, variable-step, multi-step
integrator with a maximum integration order of six. The BDF coefficients it uses are calculated by
assuming that the step size of the model is mostly constant.
Characteristics of HASTIFF(Hiller - Anantharaman ) integrator
192 Adams/Solver
C++ Statements
The following sections include descriptions and work-arounds for common error conditions you might
encounter during a simulation. The sections include:
Integration Failures
Corrector Failures
Integration Restarts
Singular Matrices and Symbolic Refactorization
Integration Failures
An integration failure is the condition when the integrator calculates a solution, but then rejects it because
it does not meet the accuracy requirements you specified. Because all integrators attempt to take the
largest time step possible, failure is a fairly routine occurrence and is not cause for concern. Integrators
can automatically decrease the step size and/or integrator order and repeat the step. Integration failures
in multi-step methods are caused when the predictor and corrector lead to vastly different configurations.
Such a situation can occur often when a force is suddenly turned on or off, thus, causing a discontinuity
in the solution. For this reason, past values are not a good indicator of current values. The following tips
can help you avoid integration failure:
When modeling, be sure that all motion inputs, user-defined forces, and user-written differential
equations are both continuous and differentiable. The smoother a function is, the easier it is to
integrate. Always use a STEP or, better yet, the STEP5 function to switch a signal on or off,
instead of using IF logic.
Remember that cubic SPLINEs can only guarantee second-order differentiability. Inputting a
can take. HMAX enables the integrator to reach higher orders and maintain them consistently.
INTEGRATOR 193
C++ Statements
Be careful when using non-differentiable intrinsic functions, such as IF, MIN, MAX, SIGN,
MOD, and DIM. These functions can give discontinuous answers and can cause integrator
problems. The integration failure diagnostic identifies the variable and its parent modeling
element with the largest error. Examine the entities that connect to the parent modeling element
to see if you can identify the cause of the failure.
Corrector Failures
A corrector failure occurs when the Newton-Raphson iterations in the correction phase do not converge
to a solution. Corrector failure occurs if the predictor cannot provide a reasonable initial guess and the
equations themselves are not smooth, as the Newton-Raphson algorithm assumes. A corrector failure is
a fairly severe event that you should avoid by changing your model. Some tips to help avoid corrector
failure are:
As with preventing integrator failures, be sure that all motion inputs, user-defined forces, user-
written differential equations, and user-defined algebraic variables are both continuous and
differentiable. The smoother a function is, the easier it is to solve for it. Use a STEP or STEP5
function to switch a signal on or off instead of using IF logic.
Use the ERROR keyword to loosen the integration error. Loosening the value for ERROR also
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
PART, POINT_MASS, or FLEX_BODY, try to identify the entities that may be applying
anomalous forces on the body. Look at the accelerations of the body. A large acceleration in a
certain direction is always caused by a large force in that direction. Try to identify the modeling
element that is causing the large acceleration, examine how it is defined, and try to understand
why it is applying a large force.
If the modeling element is a CONTACT, review the stiffness, damping, and frictional properties
of the contact. Reducing stiffness and damping helps. Similarly, increasing stiction and dynamic
friction transition velocities can help the integrator.
If the modeling element is a FRICTION entity, increasing the stiction and dynamic friction
transition velocities usually helps. Evaluate the effect of reducing the friction coefficients and the
pre-load.
194 Adams/Solver
C++ Statements
If the modeling element is a DIFF or GSE, make sure that the derivatives you are defining have
reasonable values. Large derivatives cause problems. Make sure that the constitutive equations
are smooth (differentiable) and that they do not have any kinks.
If the modeling element is a redundant constraint, this implies that Adams/Solver is having
difficulty satisfying the constraint. The most likely cause for such a failure is an inconsistently
defined or ill-behaved model. Eliminate the inconsistency.
If the modeling element is a constraint reaction, try to identify the applied force or torque that is
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
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 divide-by-zero situation. Adams/Solver (C++)
does not actually invert the matrix, but calculates the matrixs Lower and Upper triangular factors (LU
factors). This method of computation is very efficient and is equivalent to an inversion.
Given a Jacobian matrix, Adams/Solver (C++) calculates and stores the LU factors in a symbolic form.
In other words, Adams/Solver (C++) explicitly calculates the LU factors as a function of the values in
the Jacobian matrix. Adams/Solver (C++) also assumes that the pivots are never zero. (Pivots are chosen
during the Gaussian elimination and are used to factorize the matrix.) Because the equations being solved
are nonlinear, it is likely that a set of pivots chosen earlier may not be optimal. Some of the pivots may
become small or even zero. This event is known as the singular matrix condition. When Adams/Solver
(C++) encounters this condition, it recalculates the symbolic LU factors for the Jacobian matrix using the
current values of the state variables. This process is known as symbolic refactorization.
Occasional occurrences with singular matrices and symbolic refactorization are normal and are no cause
for alarm. However, if these events occur frequently, you should examine your model. The typical causes
for singular matrices are:
A mass or inertia component is not specified.
INTEGRATOR 195
C++ Statements
The system has reached a locked configuration, that is, it can no longer move without violating
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:
196 Adams/Solver
C++ Statements
All integrators require that you input a value, referred to as ERROR in the online help, that specifies the
degree of accuracy you want to achieve in a simulation. ERROR is the maximum error allowed per
integration step for the entire system. This can be confusing in Adams/Solver (C++) because some of the
ERROR states are displacements, some are velocities, and others may be user-defined states (for
example, pressure, and temperature).
In Adams/Solver (C++), integration ERROR is the difference between the exact solution f(t) and the
approximate solution p(t) being calculated. The difference, f(t)-p(t), is the truncation error.
For displacement variables, the truncation error has units of length. For velocities, the truncation error
has units of velocities. For example, if you are working in millimeters, your maximum error tolerance
would be smaller than 1 micron. Then, for each variable, you would have an error of 0.001 mm.
You find the error per step by estimating the total number of integration steps, and then dividing the error
per variable by the estimated number. Thus, if you estimate that you need 100 integration steps, the error
per step, VEPS, is 0.00001 mm. This is always a conservative calculation (sometimes too conservative)
because errors tend to be random and typically cancel each other out. The calculation shown earlier
assumes the worst case scenario, where the errors are always additive. You should use the information
shown here as a guide, not as a rule, for setting ERROR.
Velocities must be treated in the same way as displacements. However, keep in mind that the errors in the
derivatives are higher, and, if you impose an error on the velocities that are identical to the errors on the
displacements, you force a larger number of iterations per step to occur, which increases the simulation
time. In general, if an error-control exists on velocities, such as in SI2 and ABAM, then the errors
computed for the displacements can be increased by a factor of 10 and can also be applied for velocities.
Modal coordinates have small values, and, therefore, to be able to accurately capture their effects, you
may need to tighten the ERROR parameter. Typically, when the rigid body displacements and velocities
are accurate, then the modal coordinates and velocities are also fairly accurate.
Tip:
INTEGRATOR 197
C++ Statements
Caution:
GSTIFF, HHT, and Newmark may introduce discontinuities in velocities and accelerations
when the integration step size changes. Most of the time, these discontinuities are within
the error tolerance and disappear quickly. The use of the INTERPOLATE argument can
sometimes eliminate these discontinuities. Alternatively, you can control the step size
using the HMAX argument, which helps make the step sizes nearly constant.
The HHT integrator is incompatible with restitution (POISSON) contact.
Examples
INTEGRATOR/SI2, GSTIFF, ERROR=1.0E-4, HINIT=1.0E-6
This integrator statement specifies that dynamic simulations be run using the SI2 equation
formulation combined with the GSTIFF integrator.
This solution has an error limit of 1.0E-4.
The integrator is to take an initial step of 1.0E-6.
INTEGRATOR/HHT, ERROR=5.0E-6, PATTERN=F, HMAX=1e-3
This integrator statement specifies that dynamic simulations be run using the HHT integrator
with the adaptive jacobian pattern.
This solution has an error limit of 5.0E-6.
The maximum step size the integrator is to take is 1.0E-3.
198 Adams/Solver
C++ Statements
JOINT
The JOINT statement describes a physically recognizable combination of constraints that are used to
connect bodies (rigid and flexible) together. Examples of joints include constant-velocity, cylindrical,
fixed, Hooke, planar, rack-and-pinion, revolute, screw, spherical, translational, and universal joints.
Format
JOINT 199
C++ Statements
Arguments
CONVEL
Indicates the joint is a two-degree-of-freedom joint that allows rotation about two
axes: the zi and zj axes (see the figure below).
For the CONVEL joint, Adams/Solver (C++) superimposes the origins of the I and
J markers and constrains the rotation about the z-axis of the I marker to be equal
and opposite to the rotation about the z-axis of the J marker. When connecting two
shafts, the z-axes of the I and J markers should point down the shafts, away from
the center of the joint. Additionally, the angle between the x-axis of the I marker
and the y-axis of the J marker must be the same as the angle between the y-axis of
the I marker and the x-axis of the J marker. The easiest way to ensure the x and y
axes are properly aligned is to make the I and J x-axes parallel, or the I and J y-axes
parallel.
Convel Joint
CYLINDRICAL
Indicates that the joint is a two-degree-of-freedom joint that allows both relative
translational and relative rotational displacement of one part with respect to another
(see the figure below). I marker translation along the zj axis and rotation about the
zj axis are permitted.
For the CYLINDRICAL joint, Adams/Solver (C++) keeps the z-axis of the I
marker parallel to, and co-directed with, the z-axis of the J marker and confines the
origin of the I marker to the z-axis of the J marker so that the I and J markers have
a common z-axis. To determine translational motion, Adams/Solver (C++)
measures the movement of the origin of the I marker along the z-axis and with
respect to the J marker. To determine rotational motion, Adams/Solver (C++)
measures the rotation of the x-axis of the I marker about the common z-axis and
with respect to the x-axis of the J marker.
200 Adams/Solver
C++ Statements
Cylindrical Joint
FIXED
Indicates the joint is a zero-degree-of-freedom joint that completely locks the I and
J markers together (see the figure below).
For the FIXED joint, Adams/Solver (C++) superimposes the origins and the axes
of the I and J markers, allowing no relative motion.
Fixed Joint
HOOKE
Indicates the joint is a two-degree-of-freedom joint that allows rotation about two
axes: xi, the x-axis of the I marker and yj, the y-axis of the J marker (see the figure
below).
For the HOOKE joint, Adams/Solver (C++) superimposes the origins of the I and
J markers and constraint markers. It also keeps the x-axis of the I marker
perpendicular to the y-axis of the J marker so they outline the crosspiece of the
joint. The origins of the I and J markers are at the center of the cross. The HOOKE
joint functions the same as the universal joint, but uses different marker
orientations.
JOINT 201
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
202 Adams/Solver
C++ Statements
ICROT=r1,r2
Defines the rotational initial conditions you want to impose on a cylindrical joint.
The value r1 is the angular velocity of the I marker with respect to the J marker (in
radians per unit of time).
The value r2 is the rotation of the I marker with respect to the J marker (in radians).
Adams/Solver (C++) measures both the rotational velocity and the rotation of the
x-axis of the I marker about the common z-axis of the I and the J markers with
respect to the x-axis of the J marker.
The ICROT argument imposes a constraint that is active only during initial
conditions analysis (not at the time of the initial configuration). Adams/Solver
(C++) does not impose initial conditions during subsequent analyses.
If the ICROT argument imposes initial conditions on the joint that are inconsistent
with those specified on one of the bodies the joint connects, the initial conditions
on the joint have precedence over those on the body.
ICTRAN=r1,r2
PD=r
Pitch diameter (PD) defines the pitch diameter of the pinion gear of a rack-andpinion joint. The pitch diameter relates the rotational motion of the pinion to the
translational motion of the rack. When the pinion turns in the positive direction
around the z-axis of the I marker, a positive pitch diameter moves the rack in the
positive direction along the z-axis of the J marker and a negative pitch diameter
moves the rack in the negative direction along the z-axis of the J marker.
PITCH=r
JOINT 203
C++ Statements
PLANAR
Indicates that the joint is a three-degree-of-freedom joint that allows a plane of one
part to slide on a plane on a second part (see the figure below). The x and y axis of
the I and J markers of the joint define the planes on the two parts.
For the PLANAR joint, Adams/Solver (C++) constrains the z-axis of the I marker
so that it remains parallel to, and co-directed with, the z-axis of the J marker and
does not allow the linear displacement with respect to the J marker to have a z
component.
Planar Joint
204 Adams/Solver
C++ Statements
RACKPIN
REVOLUTE
JOINT 205
C++ Statements
Revolute Joint
SCREW
206 Adams/Solver
C++ Statements
SPHERICAL
Indicates that the joint is a three-degree-of-freedom joint (see the figure below).
While permitting all three rotations, a SPHERICAL joint constrains the origins of
the I and the J markers to always be superimposed.
Spherical Joint
TRANSLATION
AL
JOINT 207
C++ Statements
Translational Joint
UNIVERSAL
Indicates a two-degree-of-freedom joint that rotates about two axes: the z-axis of
the I marker and the z-axis of the J marker (see the figure below).
For the UNIVERSAL joint, Adams/Solver (C++) superimposes the origins of the I
and J markers and keeps their z-axes perpendicular, so they outline the crosspiece
of the joint. The origins of the I and J markers are at the center of the cross. The
UNIVERSAL joint functions the same as the HOOKE joint, but uses different
marker orientations.
Universal Joint
208 Adams/Solver
C++ Statements
Extended Definition
The JOINT statement describes a physically recognizable combination of constraints such as constantvelocity, cylindrical, fixed, Hooke, planar, rack-and-pinion, revolute, screw joints, spherical,
translational, and universal (see the figure on the Summary of Joints and the table on joint constraints that
follows).
Summary of Joints
JOINT 209
C++ Statements
Joint Constraints
Removes
Translational
DOF:
This type of
Joint:
Removes
Rotational DOF:
Removes Total
Number DOF:
Constant Velocity
Cylindrical
Fixed
Hooke
Planar
Rack-and-pinion
0.5*
0.5*
Revolute
Screw
0.5*
0.5*
Spherical
Translational
Universal
* The rack-and-pinion and screw joints are shown as half translational and half rotational because they
relate a translational motion to a rotational motion. They each create one constraint, but the constraint is
neither purely translational nor purely rotational.
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
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.
210 Adams/Solver
C++ Statements
Functionally, the constant-velocity joint is similar to the UNIVERSAL and HOOKE joints.
Connecting two shafts with a constant-velocity joint ensures that the shafts always spin at the
same rate, however, unlike the UNIVERSAL and HOOKE joints which cause some fluctuation
as the joint bends.
Caution:
The two markers that define a joint must be in two different parts.
Be careful when defining UNIVERSAL and HOOKE joints. In an actual universal
joint, if the spin axis of either part comes into alignment with either rotational axis
of the joint, the joint can no longer transmit rotational motion. The figure below
shows a universal joint in this singular position.
Universal Joint in the Singular Position
In Adams/Solver (C++), the singular position allows the universal joint to spin
freely and usually causes simulation failure.
Be careful when defining CONVEL joints. Whenever the z-axes of the I and J
motion of the I marker and measures both motions with respect to the J marker.
However, the screw joint does not model the backlash or slope that may occur in
actual screw joints.
For both the rack-and-pinion and screw joints, Adams/Solver (C++) positions the I
and J markers at the nearest pitch-multiple position that satisfies the constraint.
Examples of pitch multiples of a joint with a pitch value of 2.5 include -5.0, -2.5,
0.0, 2.5, 5.0, and so on. Therefore, you should ensure that the part, marker, and
joint information that contributes to the initial positioning of the I marker with
respect to the J marker correctly describes the initial position of the I marker.
JOINT 211
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
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
212 Adams/Solver
C++ Statements
point in the same direction. In actuality, the JOINT only guarantees that the axes
are either parallel or anti-parallel (pointing in the opposite direction). Because the
parallel orientation is verified during model input, and because markers are very
unlikely to instantaneously to flip by 180 degrees, the likelihood of anti-parallel
axes has been very low. However, with the advent of curve-markers, which will
experience an orientation flip when passing through an inflection point, the
situation has become a possibility.
Although it would have been possible to forbid anti-parallel assembly of JOINT
axes and enforce this at run-time, the overhead of such checking would not be
justifiable, given the low probability of the occurrence. Furthermore, because the
only recourse would be to stop the simulation, it is not clear that this check would
be very useful.
If the user requires that two axes (for example, the Z axes) remain parallel, as
opposed to anti-parallel, we recommend that the following GCON be added to the
model:
GCON/id, FUN=UVZ(i)*UVZ(j)-1
(replace UVZ with UVX or UVY for X and Y axes, respectively). The GCON will
be flagged as a redundant constraint, but since Adams/Solver (C++) stops as soon
as a redundant constraint becomes a conflicting constraint, a solution involving
anti-parallel axes will be prevented.
Examples
JOINT 213
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.
214 Adams/Solver
C++ Statements
JPRIM
The JPRIM statement describes a joint primitive, which constrains one, two, or three degrees of either
translational or rotational freedom. JPRIMs do not usually have a physical analogue and are
predominantly useful in enforcing standard geometric constraints.
Format
Arguments
ATPOINT
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.
JPRIM 215
C++ Statements
INLINE
INPLANE
216 Adams/Solver
C++ Statements
ORIENTATION
JPRIM 217
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.
218 Adams/Solver
C++ Statements
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
Inline
Inplane
JPRIM 219
C++ Statements
Removes No.
Translational DOF
Removes No. of
Rotational DOF
Removes Total
Number DOF
Orientation
Parallel Axes
Perpendicular
The reaction force on the part containing the I marker always acts at the I marker. The reaction force on
the part containing the J marker acts at the instantaneous location of the I marker; that is, the point of
application can vary with time if the I and J markers translate with respect to one another. The reaction
force on the part containing the J marker is always equal and opposite to the reaction force on the part
containing the I marker.
Joint primitives can be combined to define a complex constraint. In fact, they can be used to create any
of the recognizable joints (except for RACKPIN and SCREW). However, motions cannot be applied on
joint primitives as they can be on recognizable joints. For more information on recognizable joints, see
JOINT.
Tip:
220 Adams/Solver
C++ Statements
Caution:
The two markers that define a joint primitive must be in two different parts.
point in the same direction. In actuality, the JPRIM only guarantees that the axes
are either parallel or anti-parallel (pointing in the opposite direction). Because the
parallel orientation is verified during model input, and because markers are very
unlikely to instantaneously to flip by 180 degrees, the likelihood of anti-parallel
axes has been very low. However, with the advent of curve-markers, which will
experience an orientation flip when passing through an inflection point, the
situation has become a possibility.
Although it would have been possible to forbid anti-parallel assembly of JPRIM
axes and enforce this at run-time, the overhead of such checking would not be
justifiable, given the low probability of the occurrence. Furthermore, because the
only recourse would be to stop the simulation, it is not clear that this check would
be very useful.
If the user requires that two axes (for example, the Z axes) remain parallel, as
opposed to anti-parallel, we recommend that the following GCON be added to the
model:
GCON/id, FUN=UVZ(i)*UVZ(j)-1
(replace UVZ with UVX or UVY for X and Y axes, respectively). The GCON will
be flagged as a redundant constraint, but since Adams/Solver (C++) stops as soon
as a redundant constraint becomes a conflicting constraint, a solution involving
anti-parallel axes will be prevented.
JPRIM 221
C++ Statements
Examples
222 Adams/Solver
C++ Statements
KINEMATICS
The KINEMATICS statement specifies error tolerances and other parameters for kinematic analyses.
Format
Arguments
AERROR
Specifies the maximum acceleration error Adams/Solver (C++) is to allow for each
time step.
Default: 1.0E-4
Range: AERROR > 0
ALIMIT=r
AMAXIT=i
KINEMATICS 223
C++ Statements
APATTERN=c Specifies as many as ten character strings that together establish the pattern for
1[:...:c10]
evaluating the Jacobian matrix during the modified Newton-Raphson solution for the
accelerations. For each iteration, T or TRUE indicates that Adams/Solver (C++) is to
evaluate the Jacobian, and F or FALSE indicates that Adams/Solver (C++) is not to
evaluate the Jacobian. Thus, cj determines whether or not Adams/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 Ts or TRUEs and Fs or FALSEs together must be at least one and no more
than 10.
Default: T:T:T:T:T:T:T:T:T:T, that is, to evaluating the Jacobian at every iteration (that
is, the unmodified Newton-Raphson algorithm)
ERROR=r
Specifies the maximum displacement error Adams/Solver (C++) is to allow for each
time step.
Default: 1.0E-4
Range: ERROR > 0
HMAX=r
Defines the maximum time step that the kinematics solver is allowed to take.
Default: The output step size.
MAXIT=i
PATTERN=c1
[:...:c10]
Specifies as many as ten character strings that together establish the pattern for
evaluating the Jacobian matrix during the modified Newton-Raphson 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 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, that is, to evaluating the Jacobian at every iteration (that
is., the unmodified Newton-Raphson algorithm)
TLIMIT=r
224 Adams/Solver
C++ Statements
Extended Definition
The KINEMATICS statement specifies error tolerances and other parameters for kinematic analyses.
This statement would only be used when you are requesting a kinematic analysis and you want to change
one or more of the tolerances and parameters from the default values.
Use the SIMULATE command to request a series of kinematic analyses over time. A kinematic analysis
is only appropriate when a system has zero degrees of freedom. A kinematic analysis solves for the
displacements, velocities, accelerations, and forces (if any) at a series of points in time. To find the
displacements, Adams/Solver (C++) uses Newton-Raphson iteration to solve a nonlinear set of algebraic
equations.
After finding the displacements, Adams/Solver (C++) solves a system of linear equations to find the
velocities, then solves another set of nonlinear equations to find accelerations and forces. Adams/Solver
(C++) repeats this procedure at successively later times until it obtains results over the period of time
specified in a SIMULATE command.
Unlike the Adams/Solver (FORTRAN), the Adams/Solver (C++) uses a Newton-Raphson iteration to
solve the linear equations for velocity, rather than a direct method. In spite of this change, the
KINEMATICS statement does not offer any controls over the iterative velocity solution. The
modification is required because in Adams/Solver (C++), VARIABLE elements can influence the
velocity analysis and such elements can be self referencing. For example:
VARIABLE/1, FUN= (DX(1)+VARVAL(1))/2
A linear set of equations involving such self-referencing elements must be iteratively solved.
If you issue neither a KINEMATICS command nor statement in an Adams/Solver (C++) session,
Adams/Solver (C++) uses the default values for AERROR, ALIMIT, AMAXIT, APATTERN, ERROR,
MAXIT, PATTERN, and TLIMIT when performing a kinematic analysis.
Tip:
Using a PATTERN argument to request less frequent evaluations of the Jacobian matrix
may decrease the computation time, decreasing the cost and improving the response time.
However, infrequent evaluations could also be more expensive since the modified NewtonRaphson algorithm might require more iterations due to the slower convergence rates.
Use the ALIMIT and TLIMIT arguments to limit the increments in the displacement
variables and thus the size of the position change on successive iterations. This tends to
prevent Adams/Solver (C++) from moving the mechanism to an undesirable configuration.
Examples
KINEMATICS/TLIMIT=10, MAXIT=30
This KINEMATICS statement assigns new values to TLIMIT and MAXIT for a kinematic analysis.
Thus, the maximum translational increment allowed in each iteration of a kinematic analysis is 10 length
units and the number of iterations of the algorithm for the solution of the nonlinear equations is limited
to 30.
KINEMATICS 225
C++ Statements
226 Adams/Solver
C++ Statements
LSE
The LSE (Linear State Equation) statement defines the following linear system:
x = Ax + Bu
y = Cx + Du
of first-order, explicit differential equations and algebraic equations in classical state-space form. The
state variables, x, the inputs, u, and the outputs, y, are specified by ARRAY statements. Use MATRIX
statements to define the coefficient matrices A, B, C, and D.
Format
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.
LSE 227
C++ Statements
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 quasi-static
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.
Extended Definition
The LSE (Linear State Equation) statement is used, along with associated ARRAY and MATRIX
statements, to define a system of constant coefficient, explicit, differential and algebraic equations in
state-space form. The system of equations describes a model for a linear, time-invariant dynamic system.
The LSE, ARRAY, and MATRIX statements provide the means for importing controllers developed
228 Adams/Solver
C++ Statements
manually or with other software packages. It can also be used, however, to define an arbitrary set of
coupled, constant-coefficient differential and algebraic linear equations in the form
x A
y C
B x
D u
The LSE statement follows standard control systems terminology, where x is the state array, y is the
output array, u is the input array, and the initial conditions are defined for x(t=0). In the Adams/Solver
dataset, each of these arrays is defined using an ARRAY statement. Similarly, A is the state matrix, B is
the control matrix, C is the output matrix, and D is the feedforward matrix. Each of these matrices is
defined using a MATRIX statement.
All MATRIX and ARRAY sizes must be conformable as required by the above equation. ARRAY
statements with zero-length and zero-sized matrices should not be defined; Adams/Solver (C++)
correctly formulates the system equations based on the ARRAY and MATRIX statements included in the
dataset.
LSE 229
C++ Statements
Caution:
The LSE statement provides a very general capability for defining a linear
element. The Adams solvers, however, have been developed and refined for sparse
systems of equations that arise from the modeling of mechanical systems. With the
LSE statement, you can create very dense sets of equations. If these equations
form a large portion of your completed model, Adams/Solver (C++) may perform
more slowly than expected.
Note that, if the algebraic equations defined by the LSE statement have no solution
or multiple solutions (this is possible because of the general nature of the input
ARRAY), Adams/Solver (C++) most likely fails to converge or possibly converge
to an unexpected answer. To avoid this possibility, you should not reference the X
(state) or Y (output) ARRAY statements in the VARIABLE statements listed in the
U (input) array.
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 user-defined variables to zero,
and uses the user-supplied initial-condition values only as an initial guess for the
static solution. Generally, the final equilibrium values are not the same as the
initial condition values. Adams/Solver (C++) then uses the equilibrium values of
the user-defined variables as the initial values for any subsequent analysis, just as
with the equilibrium displacement and force values.
However, if STATIC_HOLD is specified, the user-specified initial conditions are
retained as the static equilibrium values. Thus, the final equilibrium values are the
same as the user-specified initial conditions. Note that this does not guarantee that
the time derivatives of the user-defined variable are zero after static analysis.
Examples
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)
x =
2
0
1
x + 0 5 sin ( t ) , x ( 0 ) = 0
956.96 6.2832
1
0
230 Adams/Solver
C++ Statements
The LSE statement may be most useful for adding feedback control systems to an Adams/Solver (C++)
model. The A, B, C and D matrices can be derived manually or imported directly from a control system
design program such as MATRIXx or MATLAB. Normally, the mechanical portion of the model includes
some kind of actuator that depends on one or more of the LSE statement outputs or states.
LSE statements can also be conveniently used in many cases to replace systems of coupled DIFF and
VARIABLE statements (for nonlinear equations, the GSE statement should be used). Examples of
possible dynamical system uses include unsteady aerodynamics and electrodynamics.
You can use the current values of LSE states and outputs in both function expressions and user-written
subroutines using the associated ARRAY facilities (see the ARYVAL function and SYSARY and SYSFNC
subroutines). That is, instead of Adams/Solver (C++) functions and FORTRAN callable subroutines
dedicated expressly to the LSE statement, the system states and outputs are accessed by offset referencing
through the appropriate ARRAY routines. This allows for consistent access to system states and outputs
for all three system modeling elements, the LSE, GSE, and TFSISO statements.
See other Generic systems modeling available.
LSOLVER 231
C++ Statements
LSOLVER
The LSOLVER statements allows the user to change the linear solver used by the Adams/Solver (C++).
The linear solver is invoked multiple times throughout the simulation to compute corrections in the
system state.
Format
Arguments
AUTO
CALAHAN Specifies that Adams/Solver (C++) is to use the CALAHAN solver exclusively. The
Calahan solver is usually fastest for most models.
UMF
Specifies that the Adams/Solver (C++) is to use the Unstructured Multi-Frontal sparse
matrix solver. This solver is faster for very large models.
Prior to MSC 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 Multi-Frontal) uses a very different solution technique than the Calahan
solver. The advantages of the UMF solver are 1) reduced memory use for large models, 2) better
performance for large models and 3) ability to use SMP parallelism for the linear system solution. 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 simplyconnected 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
232 Adams/Solver
C++ Statements
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.
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.
MARKER 233
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
234 Adams/Solver
C++ Statements
Arguments
CURVE=id
Specifies the identifier of the CURVE along which the marker will move.
Range: Curve IDs
FLOATING
Defines the marker as ones that moves relative to the PART with which it is
associated. A floating marker must be used with VTORQUE, VFORCE,
GFORCE, CVCV, and PTCV, and cannot exist without being referenced by one
of these statements.
FLEX_BODY=id
Specifies the identifier of the flexible body to which the marker belongs. A
FLEX_BODY argument is not required in the MARKER statement if the
MARKER statement follows the associated FLEX_BODY statement with no
intervening FLEX_BODY or PART statements.
Default: ID of preceding PART or FLEX_BODY
Range: Flexible body IDs
NODE=n1,
[n2,...,nn]
MARKER 235
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 z-coordinates 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.
236 Adams/Solver
C++ Statements
REULER=a,b,c
Specifies the Euler angle 3-1-3 sequence rotation defining the spatial orientation
of the marker axes relative to the element on which it lies. If the marker is
associated with a 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 3-1-3 sequence a,b,c.
The a, b, and c, values represent the set of body-fixed 3-1-3 Euler angles
expressed in radians. These angles can be interpreted by following the steps
below.
To orient a marker:
1. Align the marker axes identical to the axes of the parent coordinate
system to which the orientation will be relative.
2. Perform a right-handed rotation of the marker x- and y-axes by a radians
about the positive z-axis of the marker.
3. Rotate the marker y- and z-axes by b radians about the current marker
positive x-axis.
4. Perform a right-handed rotation of the x- and y-axes of the marker by c
radian about the current z-axis of the marker.
To enter the Euler angles in degrees instead of radians, add a D after each value.
Range: Real numbers for a, b, and c
SURFACE=id
Specifies the identifier of the SURFACE along which the marker will move.
Range: Surface IDs
USEXP
MARKER 237
C++ Statements
XP=x,y,z
By default, defines the coordinates of any point in the positive x-z plane of the
marker, but not on the z-axis of the marker. A point on the positive x-axis may
be the most convenient. When used with USEXP, XP defines the coordinates of
any point on the positive x-axis of the marker.
If the marker is associated with a FLEX_BODY or PART, the x-, y-, and zcoordinates are specified in the body coordinate system (BCS). For markers
associated with CURVES and SURFACES, the x-, y-, and z-coordinates are
specified in the natural coordinate system of the CURVE or SURFACE.
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 z-axis of the
marker. When used with USEXP, ZP defines the coordinates of any point in the
positive x-z plane of the marker, but not on the x-axis of the marker.
If the marker is associated with a FLEX_BODY or PART, the x-, y-, and zcoordinates are specified in the body coordinate system (BCS). For markers
associated with CURVES and SURFACES, the x-,y- and z-coordinates are
specified in the natural coordinate system of the CURVE or SURFACE.
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.
238 Adams/Solver
C++ Statements
V1=r1, V2=r2
For a marker associated with a SURFACE, V1=r1, and V2=r2 define the initial
velocity of the marker on the surface along the two-dimensional surface
parameterization.
Extended Definition
The MARKER statement defines a geometric point in space and a set of three mutually perpendicular
coordinate axes emanating from that point. MARKERs are the basic building blocks for specifying
applied forces, constraints, or simply points of interest in the model.
MARKERs are always associated with a specific element in the model (for example, PART,
FLEX_BODY, CURVE, or SURFACE) and could be fixed on the element or move relative to it.
Markers on Parts
A marker on a PART can either be fixed or it may float relative to the PART. A MARKER statement
identifies the location and orientation of a marker with respect to the body coordinate system (BCS).(For
more information on BCS, see Coordinate Systems and Local Versus Global Geometric Data.) Requests
for information pertaining to fixed and floating markers are easy to write (see REQUEST). However, only
information on fixed markers can be used in function arguments that affect how the model behaves. You
may reference the position of a floating marker in a REQUEST statement or a REQSUB evaluation
subroutine, for example, but not in an SFORCE statement or a SFOSUB evaluation subroutine.
Markers on Flexible Bodies
Adams/Solver (C++) distinguishes between positioning a marker on a flexible body and attaching a
marker to a flexible body. Positioning the marker using arguments QP, REULER, ZP, and XP defines the
initial position and orientation relative to the BCS of the flexible body. Attaching defines the interaction
between the marker and the flexible body; namely, how forces acting on the 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:
n
x = X + Ao s +
( ui + ( Ai I )rc )wi
i=1
where:
x = Position vector of marker, resolved in the ground coordinate system (GCS)
MARKER 239
C++ Statements
wi = Weighting parameter
1 -----------------ri rc
w i = ---------------------------n
1 -----------------rj rc
j=1
where wi satisfies,
wi = = 1
= 0
for all i
for r i = r c
when there exists a k, not equal to i where
rk = rc
and the sum of wi equals one. Therefore, the position of a marker relative to BCS is a least square
weighted average of the relative position of the attachment nodes in their deformed configuration.
Furthermore, the kinematics of the marker are more strongly influenced by attachment nodes closer to
the centroid of the attachment nodes.
Several marker attachment configurations can be obtained from the general form given above:
1. Marker positioned on a node, attached to the same node (n=1, w1=1, rc=0)
The position of the marker is then given by x = X + Ao [s + u1]
2. Marker positioned off node, attached to a single node (n=1, w1=1, rc=r1)
The position of the marker is then given by x = X + Ao (r1 + u1 + A1 (s - r1))
Note that the marker is not required to be on the flexible body. It is attached to the node by a rigid
lever.
240 Adams/Solver
C++ Statements
3. Marker positioned anywhere on or off the flexible body and attached to multiple nodes. This is
the general case given above.
4. Marker positioned anywhere on or off the body and attached to no node (n=0). This is an
exception case. Here, the position of the marker is given by standard rigid body marker
kinematics: x = X + Aos
Markers on Curves
The orientation (natural coordinate system) of curve markers is defined by the following convention:
The x-axis of the curve marker will point along the curve tangent vector at the marker location.
The y-axis of the curve marker will point along the curve normal vector at the marker location.
The curve normal vector points from the marker location toward the center of curvature (if
known).
The z-axis of the curve marker will point along the curve BI-normal vector at the marker
location. The curve BI-normal is defined as the cross product of the curve tangent and normal
vectors.
Markers on Surfaces
The orientation (natural coordinate system) of surface markers is slightly more complex than curve
markers because parameterized surfaces have two linearly independent tangent vectors.
The x-axis of the surface marker will point along the surface u (alpha) tangent vector at the
marker location.
The z-axis of the surface marker will point along the surface v (beta) tangent vector at the marker
location.
The y-axis of the surface marker will point along the surface normal vector at the marker
location.
Tip:
Select one of the following three methods to define the position and orientation of the
marker.
Note:
In general, locate and orient a marker with respect to its parent BCS. If the
marker is on the ground part or is on a part whose BCS is superimposed on the
ground coordinate system (GCS) at time zero, the marker can be positioned and
oriented with respect to the ground coordinate system (GCS).
axis, add QP, ZP, and/or XP. It is often unnecessary to define XP.
To select the x-point-z-point method using the XP point to define a point on the z-
axis, add QP, ZP, and/or ZP as well as USEXP. It is often unnecessary to define ZP
MARKER 241
C++ Statements
Caution:
If a curve is a straight line, or it has inflection points, the center of curvature will not be
uniquely defined at all of the curve points. In these situations, Adams/Solver (C++) will
still determine a normal, but it is just one possibility from an infinite set of normal vectors.
It is also possible for the curve marker normal to jump discontinuously as it goes through
an inflection point. In most situations, this will not cause a simulation to fail, but you
should be aware that it can happen.The REULER arguments for curve and surface markers
are relative to the curve/surface natural coordinate system. This is different from the usual
REULER convention for rigid markers where the transformation is always relative to the
part BCS. If the REULER arguments are at their default value (0,0,0) for a curve/surface
marker, then the marker will coincide with the natural coordinate system.
Rotational constraints applied to curve/surface markers must be done with care. For
example, if you want to create a fixed joint between a curve marker on one part and a rigid
marker on another part, it is imperative that the curve marker axes are close to parallel with
the corresponding rigid marker axes. The REULER arguments may have to be set for the
curve marker or the rigid marker to ensure this condition. If the REULER arguments are
incompatible with the curve/surface natural coordinate system and the constraints, the
model may fail to assemble.
Applying rotational constraints to surface markers is even more problematic than with
curve markers, because you usually have no idea how the surface will be parameterized. If
the surface was created using a CAD package, the CAD package will perform the
parameterization of the surface automatically. All that you can be sure of is that the surface
marker y-axis will be normal to the surface. For this reason, extreme care must be taken
when applying any type of rotational constraint to a surface marker. The REULER
arguments should not be used for surface markers if rotational constraints are being applied
and the parameterization is unknown. It is possible to define surfaces using a user-written
subroutine SURSUB. This is the best solution if you need precise control over how a
surface is parameterized.
If a MARKER statement for a PART or FLEX_BODY is written without arguments to
define its position and orientation, Adams/Solver (C++) defines a marker with the same
position and orientation as the BCS.
Examples
MARKER/0406, ZP=0,1,0, XP=0,0,1, PART=4
This MARKER statement assigns Marker 0406 to Part 4 and defines the position and orientation of 0406
with respect to the BCS of Part 4 using the x-point-z-point method. QP defaults to QP=0, 0, 0, so
Adams/Solver (C++) positions Marker 0406 at the origin of the BCS. The ZP values indicate that the
marker z-axis is parallel to the BCS y-axis and that the XP point lies on the BCS z-axis.
MARKER/040, QP=2,0,0, REULER=90D, 90D, 0, PART=4
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,
242 Adams/Solver
C++ Statements
Adams/Solver (C++) aligns it with its BCS and then rotates the marker 90 degrees about its z-axis, 90
degrees about its new x-axis, and 0 degrees about its new z-axis.
MARKER/1002, FLOATING, PART=2
This MARKER statement defines a floating marker named Marker 1002 on Part 2. A floating marker
requires the use of one of the following: VFORCE, VTORQUE, GFORCE, PTCV, or CVCV. The
statement referencing the floating marker determines the instantaneous location and orientation of this
marker.
MARKER/8007, XP=0,0,1, ZP=0.1,0,0.1, USEXP, PART=8
This MARKER statement defines Marker 8007 on Part 8. QP defaults to QP=0,0,0, so Adams/Solver
(C++) positions Marker 8007 at the origin of the BCS. With USEXP active, the XP values indicate that
the marker x-axis passes through point 0,0,1, and the ZP values indicate the z-x plane passes through BCS
coordinates 0.1, 0.0, 0.1.
Below is an example of a curve marker:
MARKER/2002, CURVE = 11, RM = 20, QP = 4, 0, 0, VEL =10
The MARKER statement above defines a curve marker that moves along curve 11. Marker 20 is the
reference marker for this curve. This means that the data for curve 11 is relative to the RM marker. QP is
the initial displacement of the curve marker relative to the RM marker. Adams/Solver (C++) may modify
this value to enforce the requirement that the curve marker remains on curve 11. VEL is the initial
velocity of the curve marker along the curve.
The following is an example of a surface marker:
MARKER/1001, SURFACE = 7, RM = 10, QP = 0,0,3, V1 = -1, V2 = 3
This MARKER statement defines a surface 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
MARKER 243
C++ Statements
The solver will compute the unit vectors doing these operations (notice vector x is redefined):
z
x
y
x
=
=
=
=
ZP QP
XP QP
zx
yz
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
244 Adams/Solver
C++ Statements
=
=
=
=
ZP QP
XP QP
zx
xy
MARKER 245
C++ Statements
246 Adams/Solver
C++ Statements
statements:
BUSHING
FIELD
SFORCE
SPRINGDAMPER
Specify points for requests and graphics output (see the REQUEST and GRAPHICS statements)
MARKER 247
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.
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.
248 Adams/Solver
C++ Statements
MATRIX
The MATRIX statement provides the means for inputting a two-dimensional array of numerical values.
It is used primarily to support other statements such as CURVE, LSE, and FLEX_BODY. The entries in
the matrix can be assigned values with the arguments on the MATRIX statement itself or the MATRIX
statement can specify the name of another data file from which the code reads the values. The data file
can be in one of two formats: the Adams/Solver (C++) format or the standard FSAVE format supported
by the MATRIXx software package.
Format
MATRIX 249
C++ Statements
Arguments
COLUMNS=i
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 80-character header of which the first seven
or eight characters are meaningful.
If the first record begins with the characters ADAMSMAT or
Specifies a full-input 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
250 Adams/Solver
C++ Statements
NAME=c
Specifies the name of a matrix in the file identified by the FILE argument. All types
of files, ADAMSMAT, ADAMSMAT2, MATRIXx , and MATSAVE, can contain
data for more than one matrix. You use the NAME argument to select a particular
matrix from a file even if it contains just one. Additional MATRIX statements are
needed if multiple matrices are to be read from the same file.
Range: All printable characters except '!', ';', ',', and '&'
Maximum Number of Characters: 8 (all on the same line)
ROWS=i
SPARSE
Specifies that a SPARSE input format is used where the row position, column
position, and value are given, usually only for nonzero entry values.
VALUES=r1,...,rn If you select the FULL option, the VALUES argument specifies all of the m times n
entries in the matrix. The sequence depends on the value of the FULL argument. If
RORDER is specified, the values are listed row-by-row. If CORDER is specified,
the values are listed column-by-column.
If you select the SPARSE option, the VALUES argument specifies only the entries
that may be nonzero. That is, Adams/Solver (C++) assumes all entries in the M x N
array not assigned values by the I, J, and VALUES arguments are equal to zero. The
kth entry in VALUES is assigned to the row identified by the kth entry in I and to
the column identified by the kth entry in J for k=1,...,n.
Each pair of I and J entries must specify a unique entry in the array; there can be no
duplicate entries for the same position in the matrix.
Extended Definition
The MATRIX statement defines a general M x N array that can be a rectangular or square twodimensional matrix or even a row or column matrix. You can enter the data in a FULL or SPARSE format.
When the matrix has approximately one-third or more of its entries nonzero, the FULL format is more
efficient. When the matrix is mostly empty and the labor associated with entering each nonzero entrys
row position, column position, and value is less than entering all of the values, you should use the
SPARSE format. In cases where the matrix to be input is very large, you should use the FILE and NAME
arguments to specify an external file containing the matrix.
You can enter data for an M x N matrix into Adams/Solver (C++) from a file specified by the FILE
argument on the MATRIX statement. The contents of the file can be in one of four formats:
ADAMSMAT, ADAMSMAT2, or either the standard FSAVE format or the optional MATSAVE format.
The first 7,8, or 9 characters in the header of the file must be MATRIXx, MATSAVE, ADAMSMAT, or
ADAMSMAT2 to identify the format of the data. Although the remaining content of an ADAMSMAT
or ADAMSMAT2 file (as well as all of an Adams/Solver (C++) dataset) is case insensitive, the
identifying labels at the beginning of the first record in a matrix file must appear exactly as shown.
MATRIX 251
C++ Statements
A file in the in the ADAMSMAT or ADAMSMAT2 format consists of variable-length records that must
be laid out as described in the following paragraphs. The example at the end, Table 3, and Table 4
illustrate the details. The FSAVE and MATSAVE formats are described in MATRIXx literature.
To select the option, the header or first record must begin with the characters ADAMSMAT or
ADAMSMAT2. The remainder of the first record can be used as a title to identify the kind of data in the
file.
The second record contains only an integer n right-justified within the first five spaces (the I5 FORTRAN
format). It tells how many matrices are contained in the file. The next several records (one or more)
contain the alphanumeric names (eight characters or less) of all of the matrices in the file. The names are
listed sequentially, four to a line, in eight-character fields separated by ten blanks. That is, the FORTRAN
format for the records containing the matrix names is A8, 10X, A8, 10X, A8, 10X, A8.
Sets of contiguous records define each matrix. Without any intervening blank lines, the blocks of records
begin immediately after the last line of matrix names. The first record in each block contains the name
of the matrix in the first eight characters of the line. The code searches through the file until it finds the
block of records corresponding to the NAME argument on the MATRIX statement.
The first record of the block contains the type of matrix (either FULL or SPARSE) within the second
eight spaces on the record. If the type is FULL, the next eight spaces (from 17 through 24) contain the
string CORDER or RORDER to indicate that the values are listed by column or by row, respectively.
Otherwise, if the type is SPARSE, the space is left blank.
The numerical values specified on the first record of the block include the:
Number of rows M in the matrix
Number of columns N
Total number of entries to be assigned values from the file
If the matrix type is SPARSE, then the total number of entries must be less than or equal to
(generally much less than) M x N. If the matrix is FULL, the total number must be equal to M x
N.
For a matrix in the ADAMSMAT format, the values for M, N, and the total number of entries
must be right justified in the fields 25 to 29, 30 to 34, and 35 to 39, respectively.
For a matrix in the ADAMSMAT2 format, the values for M, N, and the total number of entries
252 Adams/Solver
C++ Statements
Table 3
Item:
Argument or
symbol:
Contents:
FORTRAN
format:
ADAMSMAT
I5
(n+3)/4
NAME
4 (8A,10X)
NAME
A8,
A8,
A8,
A(I,J)
or
I,J, A(I,J)
Note:
variable
3I5
A41
FORMAT
FORMAT
Items 4 and 5 have to be repeated n times, once for each matrix named in Item 3.
Table 4
Item:
M,N,
number
format
Argument or
symbol:
Contents:
FORTRAN
format:
ADAMSMAT2
I5
(n+3)/4
NAME
4 (8A,10X)
NAME
A8,
A8,
A8,
M,N,
number
format
5
Note:
variable
A(I,J)
or
I,J, A(I,J)
Values
separated by
spaces
A41
FORMAT
FORMAT
Items 4 and 5 have to be repeated n times, once for each matrix named in Item 3.
MATRIX 253
C++ Statements
For a FULL matrix, the code simply reads matrix entries sequentially from the file. If the matrix is
SPARSE, the data have to be organized in triplets: Adams/Solver (C++) reads the row and column indices
followed by the corresponding entry in the matrix. One triplet follows another until the specified total
number of values have been read into the storage arrays.
If another matrix is contained in the file, the block of records defining its structure and containing its
values must follow immediately after the last line of data for the previous matrix.
Tip:
The largest square matrix that may be entered directly in the dataset is 48 48. In order to
enter a larger matrix, you must supply the matrix entries in a file using the FILE and NAME
arguments.
Caution:
The file name must be on one line following the argument FILE =, which if abbreviated,
limits the identifier to about 75 characters.
Examples
Small Matrix Input
TRF =
1.364
0.000
3.546
0.000
0.000
0.000
4.008
0.799
Because it is small in size, you will have little difficulty in entering the matrix directly into the
Adams/Solver (C++) dataset.
Version 1, FULL Format (row order):
254 Adams/Solver
C++ Statements
Assume that in addition to the matrix above, there are two additional matrices you want to enter into
Adams/Solver (C++).
VALK =
1.698045 10
2.307452 10
STL =
01
0.000000 10
0.016390 10
0.011271 10
0.000000 10
Assume that you want to use an external file to input the matrices and that all of the matrices are resident
in a file called prob.dat which is in the system subdirectory, /home/staff/demo. The Adams/Solver (C++)
dataset entries would appear as the following:
MATRIX/1, File=/home/staff/demo/prob8.dat, Name= trf
MATRIX/2, File=/home/staff/demo/prob8.dat, Name= valk
MATRIX/3, File=/home/staff/demo/prob8.dat, Name= stl
The leading record of a matrix file is read as character data. The first seven or eight columns must contain
one of the three character strings: MATRIXx, MATSAVE, or ADAMSMAT.
In the current example, the prob.dat is in the directory, /home/staff/demo, and contains the following data:
1 2 3 4 5 6 7
8123456789012345678901234567890123456789012345678901234567890123456789012345
67890
ADAMSMAT Floating platform example
3
TRF VALK STL
TRF FULL RORDER 4 2 8 ( 8F8.5 )
1.36400 0.00000 0.00000 0.00000 -3.54600 4.00800 0.00000 0.79900
VALK FULL CORDER 3 3 9 ( 3F6.3 )
1.970 0.000-3.440
0.000 4.510 6.020
-3.440 6.020 2.110
STL SPARSE 6 1 4 ( 2( 2I5, E14.6 ) )
1 1 0.169805E+02 2 1 -0.230745E+02
4 1 0.016390E+00 5 1 0.011271E+00
MATRIX 255
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.
256 Adams/Solver
C++ Statements
MFORCE
The MFORCE statement applies a force directly to the modal coordinates and rigid body degrees of
freedom of a FLEX_BODY.
Format
Arguments
FLEX_BODY=id
Specifies the FLEX_BODY on which the modal load is applied. Multiple MFORCE
elements can reference the same FLEX_BODY.
JFLOAT=id
Specifies the floating marker on which the reaction force is applied. If you do not
specify a floating marker, Adams/Solver (C++) ignores the reaction force.
CASE_INDEX=i
Specifies the modal load case number that defines the MFORCE. The modal load
cases are force distributions that have been predefined and stored in a modal neutral
file (MNF) for an associated FLEX_BODY. Specifically, CASE_INDEX refers to
a column in the MODLOAD matrix that is referenced in the FLEX_BODY
statement. The column contains the modal loads for the modes selected for an
Adams simulation. For more information about how to generate modal load cases,
see the Adams/Flex Help.
Note:
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:
MFORCE 257
C++ Statements
ROUTINE=libna
me::subname
Specifies an alternative library and name for the user subroutine MFOSUB.
FORCE=USER(r
1{r2,...,r30})
FUNCTION=US
ER(r1{r2,...,r30})
Extended Definition
The MFORCE statement allows you to apply any distributed load vector F to a FLEX_BODY. Such a
load vector is typically generated with a finite element program. Examples of distributed load cases
include thermal expansion or pressure loads. To help you understand how Adams handles distributed
loads, the following section discusses the equations of motion of a flexible body, starting with the
physical coordinate form that the finite element program uses.
Equations
[ M ]x + [ K ]x = F
where [ M ] and [ K ] are the finite element mass and stiffness matrices for the flexible component; x is
the nodal coordinate vector; and F is the distributed load vector. This equation can be transformed into
the modal coordinates, q:
T
[ P ] [ M ] [ P ]q + [ P ] [ K ] [ P ]q = [ P ] F
where
[ M ]q + [ K ]q = f
where[ M ] and [ K ] are the generalized mass and stiffness matrices, and f is a modal load case vector that
Adams uses to define the MFORCE element.
The projection of the nodal force vector on the modal coordinates:
T
f = [P] F
is computationally expensive and is typically undertaken by a finite element program when the modal
neutral file (MNF) is created. The modal load case f is then stored in the MNF and available to optionally
define a modal force on a FLEX_BODY in Adams.
258 Adams/Solver
C++ Statements
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 f1, f2,, fn. From the modal load cases, a total modal force fT can be applied to the FLEX_BODY
by defining an MFORCE element in one of the following five ways.
Definition 1: Specifying Scalar Function and Modal Load Case
The easiest way to construct an MFORCE is to specify a scalar function expression using the SCALE
argument and a single modal load case using the CASE_INDEX argument:
MFORCE/id, FLEX_BODY = id [,JFLOAT=id], CASE_INDEX = i
, SCALE = e
is then applied to the FLEX_BODY, where CASE_INDEX = i references load case fi in the MNF, and
SCALE = e defines the state-dependent scalar function e(q,t).
Definition 2: Defining MFOSUB Subroutine
If the scalar function expression is too complicated to define using the Adams/Solver (C++) function
expression language, you can use the MFOSUB user-written subroutine interface and specify the
MFORCE as follows:
MFORCE/id, FLEX_BODY = id [,JFLOAT=id], FUNCTION = USER(r1,[r2,r30])
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 userwritten subroutine.
Definition 3: Combining Modal Load Cases
Alternatively, you can use an MFOSUB to combine the modal load cases, f1,...,fn as follows:
fT(q,t) = e(q,t) [ g1(t) f1 + g2(t) f2 + tgn(t) fn ]
where g1(t), g2(t), gn(t) are scalar functions of time only. The MFORCE is specified the same way as
Definition 2, namely:
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 time-varying way. Adams/Solver (C++) then scales the
new modal load case by a scale factor that is also computed by the MFOSUB. The resulting modal force
is then applied to the FLEX_BODY. It is important to note that although the scale factor can be a function
MFORCE 259
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 gi(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:
fT(q,t) = e(q,t) fu(t)
where e(q,t) is the user-defined scale factor and fu(t) is the user-defined load vector. This method of
specifiying an MFORCE is primarily provided for completeness, and will be used primarily by very
experienced users.
Definition 5: Using the Force Form
where each component of f(q,t) depends independently on time and system state can only be achieved
through the MFOSUB interface and the following MFORCE specification
MFORCE/id, FLEX_BODY = id [,JFLOAT=id], FORCE = USER(r1,[r2,r30])
Note that the keyword FORCE is used instead of FUNCTION. This instructs Adams/Solver (C++) to
ignore the scale function returned from the user-written subroutine and apply the load case defined in the
subroutine directly to the FLEX_BODY. Furthermore, calls to SYSFNC and SYSARY establish state
dependencies in the individual modal force components, not just the scalar function. An MFORCE
defined in this way is more general, but less efficient than the previous forms. Therefore, it should only
be used if your application does not allow for the previous definitions.
Resultant Forces
For distributed loads that have an external resultant, portions of the load will project on the rigid body
modes of the flexible body. However, the rigid body modes must be disabled because Adams/Solver
(C++) will replace them with the non-linear, large motion, generalized coordinates: X, Y, Z,
, , and
. In this case, the load on the rigid body modes are transferred to the large motion generalized
coordinates.
Part of this transfer occurs during the MNF2MTX translation of the flexible body's MNF, and,
consequently, the MODLOAD matrix has a dimension that equals 6 plus the number of modes. The first
6 entries in each column correspond to the external force and torque acting on the flexible body for this
modal load case, expressed relative to the body coordinate system (BCS). When the modal load case is
an internal force (as would be expected in the case of a thermal load), this force and torque will be zero.
260 Adams/Solver
C++ Statements
You should also be aware of the way modal truncation affects the application of modal loads. When you
define a distributed load, it will be projected on the available modes. It is important to understand that
the available modes form an efficient but incomplete basis for the flexible component. Therefore, it is
inevitable that some portion of the load will be orthogonal to the modal basis. This portion of the load
will be irretrievably lost. Furthermore, during mode selection within Adams, you should realize that a
mode whose removal is being considered may also have a significant modal load associated with it. In
this case, the mode should not be disabled.
Examples
MFORCE/1, FLEX_BODY = 1, CASE_INDEX = 1
, SCALE = SIN(TIME)*DX(1,4)
Using the first load case defined for FLEX_BODY/1, this example defines a modal load on
FLEX_BODY/1 by scaling the values of the load case by the function expression SIN(TIME)*DX(1,4).
The reaction force that corresponds to this load is ignored.
MFORCE/2, FLEX_BODY = 2, JFLOAT = 4
, FUNCTION = USER(10,1e5,23.)
This example defines a modal load whose reaction resultant force acts on the parent part of floating
marker 2. The magnitude and shape of the load is provided by the MFOSUB user-written subroutine,
based on the user parameters 10,1e5,23. Furthermore, Adams/Solver (C++) builds the applied modal
force by multiplying the scale and load case returned from the user-written subroutine, and only the scale
function is assumed to depend on state.
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 user-written subroutine, and any component of the
load case can depend on state or time.
See other Forces available.
MOTION 261
C++ Statements
MOTION
The MOTION statement specifies a system degree of freedom as an explicit function of time. The
freedom is specified by either:
Specifying the joint and type of motion (translational or rotational).
Identifying a specific translation or rotational displacement component between two markers
The time dependency can be described in either a function expression or user-written subroutine. The
motion inputs may be a displacement, velocity, or acceleration. Velocity and accelerations are
numerically integrated to provide the displacements, with the initial conditions providing the constants
of integration.
Format
262 Adams/Solver
C++ Statements
Arguments
ACCELERATION
B1
Specifies the first angle of the Body 1-2-3 Euler angle sequence
as a function of time. The 123 rotation sequence of the I marker
coordinate system is defined with respect to the J marker
coordinate system.
Range: None
Default: None
B2
B3
Specifies the third angle of the Body 1-2-3 Euler angle sequence
as a function of time. The 123 rotation sequence of the I marker
coordinate system is defined with respect to the J marker
coordinate system.
Range: None
Default: None
DISPLACEMENT
MOTION 263
C++ Statements
ICDISP
ICVEL
I=id, J=id
JOINT=id
ROTATION
ROUTINE=libname::subname
VELOCITY
264 Adams/Solver
C++ Statements
Extended Definition
Motions can be specified to act on joints. A translational motion is specified at either a translational or
cylindrical joint. A rotational motion is specified at either a revolute or cylindrical joint. The type of the
joint together with the markers of the joint specify the degree-of-freedom being controlled.
For a translational motion, Adams/Solver (C++) moves the I marker along the z-axis of the J marker. The
J marker origin represents zero displacement while the z-axis of the J marker defines the positive
direction.
For a rotational motion, Adams/Solver (C++) rotates the I marker about the z-axis of the J marker. The
right-hand rule is used to determine the sign of the motion. The z-axis of the I marker must be collinear
with the z-axis of the J marker at all times. The angle is zero when the x-axis of the I marker is also
collinear with the x-axis of the J marker.
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
MOTION 265
C++ Statements
DZ(I,J,J) is the displacement of the origin of the I marker with respect to the origin of the J
If you want to determine the translational or rotational force a motion applies, use
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
markers. B1, B2, and B3 specify a Body 1-2-3 rotation sequence and are Euler
angles. This implies that the first rotation occurs about the x-axis of the J
marker, the second rotation about an intermediate y-axis and the last about the
z-axis of the I marker. For example, if you are measuring rotations between
two markers in the sequence z, y, x, this corresponds to a Body 3 -2 1 rotation
sequence, you will have to convert this to a Body 1-2-3 rotation sequence
before specifying it in a MOTION.
266 Adams/Solver
C++ Statements
When using any of the following motion types: B1, B2, or B3, avoid situations
where the B2 angle is at +/- 90degrees or +/- 270 degrees. At these angles the
Body 1-2-3 angles are undefined. If this situation occurs, Adams/Solver (C++)
issues a warning and stops the execution. There is no solution for this
condition.
Do not use an initial conditions argument, such as, IC, ICTRAN, or ICROT,
on a JOINT statement with a motion that acts in the same direction on the
joint. If both are used, Adams/Solver (C++) uses the MOTION statement and
ignores the initial conditions argument(s) specifying motion in the same
direction(s) specified by the JOINT statement.
If the initial rotational displacement of a revolute or cylindrical joint (as
IMPACT functions.
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:
MOTION 267
C++ Statements
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-
These MOTION statements control the three rotational degrees-of-freedom in a spherical joint by
specifying the Body 1-2-3 angles between the I and J markers of the joint as functions of time.
JOINT/401, PLANAR, I=4011, J=4012
MOTION/4011, I=4011, J=4012, X
, FU=STEP5(TIME, 0.5, 0.0, 4.0, 1.0)*50
MOTION/4012, I=4011, J=4012, Y
, FU=-SHF(TIME, 0.0, 10/2, 2*PI, 90D, 10/2)
MOTION/4016, I=4011, J=4012, B3, FU=0D
These MOTION statements control the three degrees-of-freedom in a planar joint:
The displacement of the origin of Marker 4011 with respect to the origin of Marker 4012, along
specified to be zero.
See other Constraints available.
268 Adams/Solver
C++ Statements
NFORCE
The NFORCE statement creates a multi-point force element which establishes linear force-displacement
(stiffness) and/or force-velocity (damping) relationships between many markers (up to 351) in the model.
Format
Arguments
CMATRIX=id
Specifies the identifier of the MATRIX that the NFORCE uses as its damping
matrix. The CMATRIX is a 6n 6n matrix (n is the number of I markers) that
defines the linear relationships between the I marker velocities relative to the J
marker and the viscous forces generated by the NFORCE. The CMATRIX is
derived in the J markers coordinate system. If neither CMATRIX nor CRATIO
is given, the NFORCE is undamped. Marker translational and rotational
velocities appear sequentially in Vx, Vy, Vz, x, y, z order, while the
markers appear in the same sequence as in the IMARKER argument.
CRATIO=r
Specifies the proportional damping ratio for the NFORCE. The elements of the
damping matrix are determined by multiplying the corresponding stiffness
element value by this number. If direct input of the damping properties is
desired, the CMATRIX may be used. If neither CMATRIX nor CRATIO is
given, the NFORCE is undamped.
FORCE
Specifies the identifier of the MATRIX that contains the forces and torques that
the NFORCE would produce if all the I markers were at the positions given in
LENGTH. FORCE is a 6n 1 matrix (n is the number of I markers) of forces and
torques, appearing sequentially for each marker in Fx, Fy, Fz, Tx, Ty, Tz order,
while the markers appear in the same sequence as in the IMARKER argument.
The force and torque components are expressed in the J markers coordinate
system. When LENGTH is used to specify the systems free lengths, FORCE
gives the preloads. If FORCE is not given, the NFORCE acts as though a matrix
of zeros are input.
NFORCE 269
C++ Statements
IMARKERS=id1,...,i Lists the markers (except for the J marker) between which the NFORCE forces
dn
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 markers 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 markers
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 systems free (no internal force) lengths when
they differ from the input positions. If LENGTH is not given, the NFORCE
assumes that the input positions of the I markers are at the reference locations.
Extended Definition
The NFORCE creates a set of forces and torques which act between the I and J markers which appear in
the NFORCE statement. These forces and torques are linear functions of the relative displacements and
velocities of the markers, in a manner equivalent to the finite element method. For each NFORCE, one
marker (J) is used as the reference marker. The velocities are resolved into the J markers reference frame
and expressed in the J markers coordinate system. The force and torque components computed by the
NFORCE are also given in the J markers coordinate system.
The force-displacement and force-velocity relationships are specified using stiffness and damping
matrices, or by using a stiffness matrix and a proportional damping ratio. These matrices are defined
using MATRIX statements in the dataset. The stiffness and damping matrices that Adams/Solver
(FORTRAN) requires are defined for the I markers only; that is, they should be derived normally using
the 6(n+1) J marker and I marker degrees-of-freedom, but are input using only the rows and columns
corresponding to the I marker degrees-of-freedom. This is equivalent, in finite element terminology, to
applying fixed boundary conditions at the J marker by simply removing the corresponding rows and
columns from the matrices. Adams/Solver (FORTRAN) automatically computes and applies the correct
reaction forces at the J marker.
270 Adams/Solver
C++ Statements
Formulation
FI = - KMATRIX (X - L) - CMATRIX
X + FORCE
where:
FI is the 6n x 1 matrix of forces exerted on the I markers.
KMATRIX is the 6n x 6n truncated stiffness matrix, created by striking out the rows and
expressed in the J markers 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
X is the 6n x 1 matrix of the translational and linearized angular velocities of the I markers with
respect to the J marker, and expressed in the J markers coordinate system.
FORCE is the 6n x 1 matrix of the reference forces on the I markers; that is, the forces on the I
markers when their displacements relative to the J marker are specified by L. When LENGTH
contains the free lengths, FORCE is the preload.
Reaction Forces (Forces on the J marker)
F jtrans = F itrans
i
where:
trans denotes translational degrees-of-freedom
=rot denotes rotational degrees-of-freedom
Xji is the instantaneous vector from the J marker to each I marker.
NFORCE 271
C++ Statements
Tip:
When importing stiffness and damping matrices that are developed using finite
element methods, the LENGTH and FORCE arguments are most easily thought of
as the system free lengths (zero internal stress) and preloads. You can, however,
specify any consistent set of reference lengths and resulting forces, just as for the
SPRINGDAMPER element.
Physically meaningful NFORCES have positive semi-definite KMATRIX and
CMATRIX matrices. That is, the diaginal enteries of the matrices have positive
value. Adams/Solver (FORTRAN) only accepts NFORCES having positive semidefinite matrices.
Caution:
Like the BEAM, the NFORCE is a linear element, so that the forces computed are
generally valid only for small displacements. When the applied loading is such that
the small displacement limits are exceeded (a good estimate is ten percent of
lengths and less than 0.2 radian rotations), the NFORCE results may be less
accurate. In cases where the structure undergoes large overall deflections but
remains linearly elastic (small local deflections), you can use more NFORCE
elements, so that each NFORCE element remains locally within small
displacement limits. Note that because of the way that Adams/Solver (FORTRAN)
computes angular displacements, the absolute magnitude of this inaccuracy due to
overly large displacement may depend on the instantaneous spatial orientation of
the system.
A two-point NFORCE is not identical to a field, although it is very similar. The
default that the input positions of the I markers are at the reference locations.
The FIELD allows you to specify reference angles for the rotational
displacements, while the NFORCE assumes the reference angles are always
zero.
Examples
The figure below illustrates a simple, planar, triangular truss attached to some large base body.
272 Adams/Solver
C++ Statements
The following NFORCE statement defines a 24 force components acting between Markers 10, 20, 30,
and 40.
NFORCE/1234, J=10, I=20,30,40, KMATRIX=1234, CRATIO=0.02
Marker 10 is the J marker. This means Matrix 1234 is an 18-by-18 stiffness matrix relating forces to
displacements at Markers 20, 30 and 40. The forces and displacements are measured in the coordinate
system of Marker 10. Because the LENGTH argument is not included, Adams/Solver (FORTRAN)
measures the displacements from the input position. Because the FORCE argument is not specified, there
are no loads at the reference position (in this case the input position). In other words, the truss has been
input in the unloaded, undeformed configuration. The damping matrix is .02 times the stiffness matrix.
Depending on the assumptions you make, the stiffness matrix for this structure could be quite elaborate.
A simple case, however, is to assume the ends of the truss members are pinned, and that the truss
members only transmit translational, in-plane forces.
Due to the simple geometry, this matrix can be determined by inspection, and is shown in the table shown
next.
NFORCE 273
C++ Statements
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
274 Adams/Solver
C++ Statements
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
super-element condensation before importing it into Adams/Solver (FORTRAN) as an NFORCE.
Because of formulational differences between FEA and Adams multibody systems analysis, it is
generally not possible to have a one-to-one correspondence between Adams/Solver (FORTRAN) PARTs
and FEA nodes, unless the FEA model is very small.
Flexible Satellite Panels
OUTPUT 275
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
[ ,NOSEPARATOR ] [ ,YPR ]
,GRS AVE
ABAQUS
ANSYS
,LOADS = DAC
NASTRAN
RPC
DACSAVE
RPCSAVE
ABAQUS
DAC
,MODAL_DEFORMATION = GENERIC
NASTRAN
,
PUNCH
ANSYS
,NODAL_DEFORMATION = GENERIC
NASTRAN
DAC
,STRAIN =
GENERIC
DAC
,STRESS =
GENERIC
276 Adams/Solver
C++ Statements
Arguments
ABAQUS
ANSYS
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
GENERIC
GRSAVE
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
NODAL_DEFORMATION
OUTPUT 277
C++ Statements
NOSEPARATOR
PUNCH
REQSAVE
Saves request output in the request file so that you can use a
postprocessor to display x-y plots. If you do not specify REQSAVE,
Adams/Solver (C++) does not save the request output in the request file.
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
278 Adams/Solver
C++ Statements
STRESS
YPR
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.
OUTPUT 279
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
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
This OUTPUT statement causes Adams/Solver (C++) to save both graphics and request output.
280 Adams/Solver
C++ Statements
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.
PART 281
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
282 Adams/Solver
C++ Statements
Arguments
CM=id
Specifies the identifier of the marker that defines the location of the part center of
mass and, in the absence of the inertia marker, the orientation of the inertia axes for
the IP values.
EXACT=c1:...:c6 Specifies as many as six part coordinates that Adams/Solver (C++) should not
change as it iteratively solves for initial conditions that satisfy all constraints. The
six coordinates are:
x coordinate
y coordinate
z coordinate
PSI
Psi angle
THETA
Theta angle
PHI
Phi angle
Indicates the part being defined as the Newtonian reference frame. It is, by
definition, at absolute rest. Because there can be only one ground part in the system,
a dataset must never have more than one PART statement with the GROUND
argument.
IM=id
Specifies the identifier of the marker about which you specify the moments of
inertia for the part. This marker can be any marker in the part. The IM marker
defaults to the CM marker.
PART 283
C++ Statements
IP=xx,yy,zz[,xy,x Specifies the mass-inertia tensor as computed about the origin of the IM marker,
z,yz]
expressed in the coordinate system of the IM marker.
You can compute the individual terms of the IP argument as:
Ixx =
( y 2 + z 2 ) dm
Iyy =
( x 2 + z 2 ) dm
Izz =
( x 2 + y 2 ) dm
Ixy =
xy dm
Ixz =
xz dm
Iyz =
yz dm
In the above formulae, x, y, and z are the components of the displacement of the
center of an infinitesimal volume of mass dm, measured from the origin of the
inertia marker in the coordinate system of the inertia marker. The integral is
performed over the entire volume of the body. If the inertia marker 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:
MASS=r
MATERIAL=mat Specifies the material type for the part. You define the different material types in the
_name
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 built-in 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).
284 Adams/Solver
C++ Statements
REULER=a,b,c
Defines the 3-1-3 Euler angles that Adams/Solver (C++) uses to establish the initial
orientation of the BCS with respect to the coordinate system. The a, b, and c
rotations are in radians and are, respectively, about the z-axis of ground, the new xaxis, and the new z-axis of the BCS. To input Euler angles in degrees, add a D after
each value.
VM=id
Specifies the identifier of the marker that specifies the direction of translational
velocity initial conditions (VX, VY, and VZ). VM defaults to global orientation.
VX=x, VY=y,
VZ=z
Specifies the initial translational velocities of the CM marker with respect to the
ground coordinate system (GCS) along the x-axis (VX), the y-axis (VY), and the zaxis (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
x-axis (WX), the y-axis (WY), and the z-axis (WZ) of the CM marker coordinate
system.
XG=x,y,z
Defines the coordinates, measured in the GCS, of any point in the positive x-z plane
of the part BCS, but not on the z-axis of the part BCS.
XY
Specifies that a planar part will move in the global xy plane. The argument can only
appear with the PLANAR argument and is the default.
YZ
Specifies that a planar part will move in the global yz plane. The argument can only
appear with the PLANAR argument. If it is not provided, the planar part will move
in the global xy plane.
ZG=x,y,z
Defines the coordinates measured in the GCS of any point on the positive z-axis of
the BCS.
ZX
Specifies that a planar part will move in the global zx plane. The argument can only
appear with the PLANAR argument. If it is not provided, the planar part will move
in the global xy plane.
PART 285
C++ Statements
Tip:
If the part has no CM marker, as may be the case for some massless parts,
Adams/Solver (C++) uses the part BCS to represent the position and orientation of
the part internally. For more information on BCS, see Coordinate Systems and
Local Versus Global Geometric Data.
Using a CM on a massless part can improve model robustness by removing large
offsets between the BCS and markers on the massless part, without repositioning
all the markers on the massless part. Do not be confused by the contradiction of
specifying a center-of-mass on a massless part. In this case, the CM marker is
simply suggesting an advantageous choice of internal coordinate systems.
If the part has mass, Adams/Solver (C++) uses the position of the CM marker to
represent the translational position of the part internally and uses the principal axes
of the inertia tensor about the CM marker to represent the orientation of the part
internally. This internal coordinate system is commonly referred to as the part
principal coordinate system.
Because of a basic property of Euler angles, a singularity occurs when the
principal z-axis of the CM becomes parallel to the ground z-axis. Whenever the
principal z-axis of the part nearly parallels the ground z-axis, Adams/Solver (C++)
rotates the part principal axes 90 degrees about the z-axis and then 90 degrees
about the new x-axis to avoid the singularity. Adams/Solver (C++), however, does
not change the marker locations and orientations with respect to the BCS nor does
it alter the BCS location or orientation with respect to ground. (The principal axes
of the inertia tensor of the CM are referred to as the part principal axes.)
The BCS for each part can have any position and orientation. In fact, the location
of the BCS does not have to be within the physical confines of the part. It may be
at some convenient point outside the actual part boundaries.
To superimpose the BCS of a part on the GCS, define QG=0,0,0 and
REULER=0,0,0 or let QG and REULER default. The position and orientation data
for the markers on the part is now with respect to the GCS.
As stated earlier, the planar can be viewed as a normal 3D part with a built-in
planar joint. This is a combination of elements often found in certain models that
contain 2D subsystems. Unlike a part and a planar joint pair that combine to add
18 equations to an index-3 dynamic analysis in Adams/Solver, the planar part only
adds 6 equations.
This is not an attempt to create a 2D version of Adams. Because the planar part can
be contained in a full 3D Adams model and coexist with, and be connected to, 3D
part elements, performance will not compare with a 2D dynamics analysis
software.
286 Adams/Solver
C++ Statements
Caution:
Each part defined with the PART statement, with the exception of ground, must
have at least one marker associated with it (see MARKER).
For the argument IP, if you specify one of the moments of inertia (xx, yy, or zz),
you must also specify the other two. Similarly, if you specify one of the products
of inertia (xy, xz, or yz), you much also specify the other two.
Make sure the units for mass moments of inertia and for mass products of inertia
are consistent with the units for the rest of the system.
Parts that are not fully constrained (that is, they can move dynamically because of
the effect of forces) must have nonzero masses and/or inertias. You may assign a
default zero mass to a part whose six degrees of motion are fully constrained with
respect to parts that do have mass.
EXACT, VX, VY, VZ, WX, WY, and WZ arguments ensure that the corresponding
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
part.
A planar part is implicitly constrained to move in a plane at a fixed global value of
Z. Any force applied to the planar part in the global Z direction will be discarded.
The same applies to torques about the global X and Y axes. It is not possible to
measure the reaction forces required to constrain the planar part to stay in plane. If
such forces are desired, the equivalent part and planar joint combination must be
substituted.
Examples
PART/01, GROUND
The PART statement above indicates that Part 1 is the ground part.
PART/02, MASS=2, CM=0201, IP=5,6,10
The PART statement above specifies the mass (2 units), the center-of-mass marker identifier (0201), and
the principal moments of inertia for Part 2:
PART 287
C++ Statements
Ixx = 5 units
Iyy = 6 units
Izz = 10 units
The principal moments of inertia are about the x-axis (5), the y-axis (6), and the z-axis (10) of the centerof-mass marker. Because this statement includes no arguments that define the orientation or position of
Part 2, Adams/Solver (C++) superimposes Part 2 on the ground coordinate system (GCS). This statement
identifies no IM marker, so Adams/Solver (C++) assumes that the inertias are defined with respect to the
part CM marker.
PART/04, MASS=.5, CM=0407, QG=10,0,0
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.
288 Adams/Solver
C++ Statements
PINPUT
The PINPUT statement defines a list of VARIABLE statements that Adams/Solver (C++) recognizes as
system input during a LINEAR/STATEMAT analysis (see the LINEAR command).
Format
PINPUT/id, VARIABLES=id1[,id2,...]
[ ] Optionally select the item
Arguments
VARIABLES=id1[,id2,...]
Extended Definition
The PINPUT statement, along with a POUTPUT statement, is used with the LINEAR/STATEMAT
command. PINPUT defines a set of inputs to the mechanical system, and POUTPUT defines the set of
measured outputs from the system. The LINEAR/STATEMAT command linearizes the system equations
to the following form
x = Ax + Bu
y = Cx + Du
where x is the linearized system state array, u is the array of system inputs defined by the PINPUT
statement, and y is the array of system outputs defined by the POUTPUT statement. This form is
commonly referred to as the state space form of the system equations in control theory. Adams/Solver
(C++) outputs the A, B, C, and D matrices for use in a control-system design or any other linear system
analysis software. If only the A matrix is required, PINPUT and POUTPUT are not necessary.
When you run an analysis type other than LINEAR/STATEMAT, the PINPUT statement acts only as a
pointer to the list of the specified VARIABLE statements.
Both function expressions and user-written subroutines can access the PINPUT statement. Function
expressions access the values by using the internal Adams/Solver (C++) function PINVAL(i1,i2) (see the
PINVAL function), where i1 specifies the PINPUT id, and i2 specifies the i2th VARIABLE in the
PINPUT statement list. Note that i2 is not the id of the VARIABLE statement.
PINPUT 289
C++ Statements
User-written subroutines call the subroutine SYSFNC to access single elements of the PINPUT list and
call the subroutine SYSARY to access all values for a PINPUT (see SYSARY and SYSFNC subroutines).
Tip:
VARIABLE statements may appear in more than one PINPUT statement. This allows you
to output two or more sets of state matrices at the same time.
Examples
PINPUT/3, VARIABLES=12,13,25
This PINPUT statement identifies VARIABLES 12, 13, and 25 as inputs to the mechanical system. These
variables might appear in expressions for computing actuating forces, for instance. You may refer to this
PINPUT in a LINEAR/STATEMAT command.
Applications
The PINPUT statement along with the POUTPUT, VARIABLE, ARRAY, TFSISO, LSE, and GSE
statements make up the interface between Adams/Solver (C++) and control design and analysis packages
such as MATRIXx and MATLAB.
As shown in the figure below, PINPUT and POUTPUT act as sockets for input and output to your
controller, organizing the VARIABLE wires.
PINPUT and POUTPUT as Sockets
The LINEAR command uses PINPUT and POUTPUT statements to identify which variables to consider
system inputs and outputs when generating state matrices. A control design program can use these
matrices to design a controller for the system. The resulting controller may then be included in the
Adams/Solver (C++) model using VARIABLE, ARRAY, TFSISO, LSE, or GSE statements.
290 Adams/Solver
C++ Statements
POINT_MASS 291
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
292 Adams/Solver
C++ Statements
Arguments
CM=id
Specifies the identifier of the marker that defines the location of the point mass
relative to the local body coordinate system (BCS).
Default: None
Range: Valid fixed MARKER ids
EXACT=c1:c2:c3
x coordinate
y coordinate
z coordinate
These coordinates can be entered in any order following EXACT. These are not
changed by Adams/Solver (FORTRAN) unless the values specified are
inconsistent with initial conditions for a joint or motion.
Default: None
Range: X, Y, or Z
MASS=r
QG=x,y,z
Defines the Cartesian initial coordinates of the BCS with respect to the global
coordinate system.
Default: 0.0, 0.0, 0.0
Range: Any real values
REULER=a,b,c
Defines the 3-1-3 Euler angles that Adams/Solver uses to establish the initial
orientation of the BCS with respect to the coordinate system. The a, b, and c
rotations are in radians and are, respectively, about the z-axis of ground, the
new x-axis, and the new z-axis of the BCS. To input Euler angles in degrees,
add a D after each value.
Defaults: 0.0, 0.0, 0.0 when REULER, XG, and ZG are omitted
Range: Any real values
POINT_MASS 293
C++ Statements
VX=x, VY=y,
VZ=z
XG=x,y,z
Defines the coordinates, measured in the global coordinate system, of any point
in the positive x-z plane of the part BCS, but not on the z-axis of the part BCS.
Default: If ZG is omitted, XG is oriented like the global x-axis
Range: Any real values
ZG=x,y,z
Defines the coordinates measured in the global coordinate system of any point
on the positive z-axis of the BCS.
Default: If XG is omitted, ZG is oriented like the global z-axis
Range: Any real values
Extended Definition
Although the point mass concept would normally suggest a particle, this is not how a point mass is
implemented in Adams. If a particle is subjected to a torque, a singularity ensues. This was not considered
a practical behavior for an element in Adams.
Rather than thinking of the point mass as a particle think of it as a rigid body with built-in angular
constraints removing any rotational degrees of freedom. It is legal to apply torques to a point mass, and
such torques are simply discarded. If one takes care not to apply a torque, the Adams point mass behaves
exactly like a particle.
294 Adams/Solver
C++ Statements
The point mass offers all the computational benefits of a particle without the complications which would
arise from forbidding the application of a torque.
Tip:
All markers on a point mass that are involved in constraints or are at force
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.
See other Inertia and material data statement available.
POUTPUT 295
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,...]
[ ] Optionally select the item
Arguments
VARIABLES=id1id1[,id2,...]
Extended Definition
The POUTPUT statement, along with a PINPUT statement, is used with the LINEAR/STATEMAT
command. POUTPUT defines the set of measured outputs from the system and PINPUT defines a set of
inputs to the mechanical system. The LINEAR command linearizes the system equations to the following
form:
x = Ax + Bu
y = Cx + Du
where:
x is the linearized system state array
u is the array of system inputs defined by the PINPUT statement.
y is the array of system outputs defined by the POUTPUT statement.
This form is commonly referred to as the state space form of the system equations in control theory.
Adams/Solver (C++) outputs the A, B, C, and D matrices for use in a control-system design or any other
linear system analysis software. If only the A matrix is required, PINPUT and POUTPUT are not
necessary.
When you run an analysis type other than LINEAR, the POUTPUT statement acts only as a pointer to
the list of VARIABLE statements specified.
Both function expressions and user-written subroutines can access the POUTPUT statement. Function
expressions access the values by using the internal Adams/Solver (C++) function POUVAL(i1,i2) (see
the PINVAL function), where i1 specifies the POUTPUT id , and i2 specifies the i2th VARIABLE in the
POUTPUT statement list. Note that i2 is not the id of the VARIABLE.
296 Adams/Solver
C++ Statements
User-written subroutines access single elements of the POUTPUT list and call the subroutine SYSFNC
to access all values for a POUTPUT by calling the subroutine SYSARY (see the SYSARY and SYSFNC
subroutines).
Tip:
VARIABLE statements may appear in more than one POUTPUT statement. This allows
you to output two or more sets of state matrices at the same time.
Examples
POUTPUT/4, VARIABLES=4,8,9,10
This POUTPUT statement identifies VARIABLES 4, 8, 9, and 10 as outputs from the mechanical system.
These variables might represent part displacements and velocities, for instance. You may refer to this
POUTPUT in a LINEAR/STATEMAT command.
Applications
The POUTPUT statement with the PINPUT, VARIABLE, ARRAY, TFSISO, LSE, and GSE statements
define the interface between Adams/Solver (C++) and control design and analysis packages such as
MATRIXx and MATLAB.
As shown in the figure below, PINPUT and POUTPUT act as socket for input and output to your
controller, organizing the VARIABLE wires.
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.
POUTPUT 297
C++ Statements
298 Adams/Solver
C++ Statements
PREFERENCES
The PREFERENCES statement controls general options that apply to the model defined in the
Adams/Solver (C++) dataset or the commands defined in the Adams/Solver (C++) command file.
Format
PREFERENCES 299
C++ Statements
Arguments
300 Adams/Solver
C++ Statements
LIBPATH=dir1:dir2:...
NTHREADS=n
STATUS_MESSAGE
PREFERENCES 301
C++ Statements
FLEX_LIMIT_CHECK={skin, SELNOD}
Adams/Solver (C++).
RETURN - Stops the simulation and returns
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 user-written subroutines will not see the full benefit of parallelization unless the
user-written subroutines declare themselves as threadsafe. See the utility subroutine,
ADAMS_DECLARE_THREADSAFE, for more information.
302 Adams/Solver
C++ Statements
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
Adams/Solver (C++) searches for a user subroutine named BAR in a dynamically loaded library named
libfoo.so (see documentation for ROUTINE Argument for more information about library name rules) in
the directories /home/joe/plugins and /usr/projects/lifters, before searching in the default plugin
directories.
Caution:
The LIBPATH argument only influences the search for the highest level plugin library. For
example, if a plugin library, libA.so, depends on another library, libB.so, and this library is
located in a directory specified by LIBPATH, then libB.so will not be found, unless the
DT_RPATH or DT_RUNPATH attributes are present on libA.so, as specified (often with
an -rpath option) during the creation of libA.so. This shortcoming of LIBPATH is
unavoidable, because the dependency on libB.so is resolved by the underlying runtime
loader, whose search paths cannot be altered at run-time.
PSTATE 303
C++ Statements
PSTATE
The PSTATE statement defines a set of user-defined coordinates to be used during a LINEAR analysis
(see the LINEAR command).
You can specify as many states as there are degrees-of-freedom. If a smaller set of states are provided,
then the system will "fill in" by choosing a set of internally available states for the ones that were not
explicitly specified. If too many states are specified, Adams/Solver (C++) identifies and discards the
redundant states.
For theoretical details, see the white paper in Knowledge Base Article 12721.
For an example of using PSTATE, see Knowledge Base Article 12663.
Format
PSTATE/id, VARIABLES=id1[,id2,...]
[ ] Optionally select the item
Arguments
VARIABLES=id1[,id2,...]
Extended Definition
x = Ax + Bu
y = Cx + Du
where:
x is the linearized system state array.
u is the array of system inputs defined by the PINPUT statement.
y is the array of system outputs defined by the POUTPUT statement.
304 Adams/Solver
C++ Statements
This form is commonly referred to as the state space form of the system equations in control theory.
Adams/Solver (C++) outputs the A, B, C, and D matrices for use in a control-system design or any other
linear system analysis software.
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:
s = A's + B'u
y = C's + Du'
where the system state array s is the set of user-defined coordinates.
Use the following guidelines when creating PSTATE objects and their associated VARIABLEs' function
expressions:
1. Function expressions must be define a nonconstant displacement or angular measure.
Example
VARIABLE/2, FU=DX(10,7)
VARIABLE/3, FU=PSI(8,7)
PSTATE/33, VAR=2, 3
If the function expression is a constant or it is not a displacement, the code will reject the
definition.
2. The displacement or angular measures can be global or relative.
Example
! Defining a relative coordinate
VARIABLE/2, FU=DX(10,5,7)
PSTATE/33, VAR=2
3. The number of VARIABLES in the PSTATE statement can be less than the number of degrees of
freedom of the model. Adams/Solver (C++) completes the state array using coordinates taken
from the set of default system coordinates.
4. The number of VARIABLES in the PSTATE statement can be greater than the number of
degrees-of-freedom of the model. Adams/Solver (C++) selects the required number of userdefined coordinates and ignores the rest.
5. Adams/Solver (C++) rejects redundant definitions.
Example
! Redundant definitions
VARIABLE/7, FU=DX(10,2)
PSTATE 305
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 user-defined coordinate if there is already an equivalent
default definition.
Tip:
command.
Examples
The model shown in the figure below is a simple rigid helicopter blade.
Assuming that MARKER/10 is located on the CM of the blade, by default, Adams/Solver (C++) will
linearize the model using the rotation AZ(10). If you want to linearize the model using the displacement
'y' shown in the figure, then add the following objects to the data set:
VARIABLE/1, FU=DY(10)
PSTATE/1, VAR=1
In 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.
306 Adams/Solver
C++ Statements
Theory shows that in a rotating (or accelerating) system, the eigenvalues depend on the choice of
coordinates used to linearize the model.
For example,
LINEAR/EIGENSOL, PSTATE=2
forces Adams/Solver (C++) to linearize and compute eigenvalues of a model in terms of the user-defined
coordinates found in the VARIABLEs belonging to the PSTATE/2 object.
PTCV 307
C++ Statements
PTCV
The PTCV statement defines a point-to-curve constraint, which restricts a fixed point defined on one part
to lie on a curve defined on a second part. This is an instance of a higher pair constraint.
Format
Arguments
CURVE=id
Specifies the identifier of a CURVE statement that defines the contour or shape on which
the fixed marker can move. The x, y, z values associated with the curve are the
coordinates of points lying on the curve and are calculated in the coordinate system of
the RM marker.
DISP=x,y,z
Specifies the initial point of contact on the curve. If the point specified is not exactly on
the curve, Adams/Solver (C++) uses a point on the curve nearest to that specified. By
default, DISP is specified in the RM marker coordinate system. If another coordinate
system is more convenient, you may supply the ICM argument and enter DISP in ICM
marker coordinates.
If you supply DISP, Adams/Solver (C++) assembles the system with the I marker at the
specified point on the curve. If you do not supply DISP, Adams/Solver (C++) assumes
the initial contact is at the point on the curve closest to the initial I marker position.
However, it may adjust that contact point to maintain other part or constraint initial
conditions.
I=id
Specifies the identifier of a fixed MARKER that Adams/Solver (C++) constrains to lie
on the curve defined by CURVE and RM. The I and RM markers must belong to
different parts.
ICM=id
Specifies the identifier of a fixed MARKER defining the coordinate system in which the
values for DISP are specified. The ICM marker must be on the same part as the RM
marker.
308 Adams/Solver
C++ Statements
JFLOAT=id Specifies the identifier of a floating marker. Adams/Solver (C++) positions the origin of
the JFLOAT marker at the instantaneous point of contact on the curve. Adams/Solver
(C++) orients the JFLOAT marker such that the x-axis is tangent to the curve at the
contact point, the y-axis points outward from the curve's center of curvature at the
contact point, and the z-axis is along the binormal at the contact point.
RM=id
Specifies the identifier of a fixed 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
Extended Definition
The PTCV statement defines a point-to-curve constraint. The part containing the I marker is free to roll
and slide on the curve that is fixed to the second part. Lift-off is not allowed, that is, the I marker must
always lie on the curve.
Is located at the contact point on the curve; its orientation is defined by the tangent, normal and binormal
at the contact point (see Figure 5).
Figure 6 shows a schematic of the point-to-curve constraint.
A PTCV statement removes two translational degrees-of-freedom from the system. Adams/Solver (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.
PTCV 309
C++ Statements
Figure 5
310 Adams/Solver
C++ Statements
Figure 6
Tip:
Point-To-Curve Constraint
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.
PTCV 311
C++ Statements
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:
active only during an initial conditions analysis. Adams/Solver (C++) does not
impose these initial conditions during subsequent analyses.
For a kinematic analysis, the initial conditions are redundant. Do not use the DISP
or VEL arguments on the PTCV statements for systems with zero degrees of
freedom.
It is easy to accidentally over-constrain a system using the PTCV constraint. For
This statement creates a point-curve constraint between Marker 201 and a curve on the part containing
floating Marker 301 and fixed Marker 302. CURVE/10 defines the x, y, z coordinates curve in the
coordinate system of Marker 302. Because the statement does not specify initial conditions,
312 Adams/Solver
C++ Statements
Adams/Solver (C++) assumes that the initial position of the contact point on the curve is set to be the
minimum distance between the specified I marker and the curve. Adams/Solver (C++) also assumes the
velocity of Marker 201 with respect to the curve is zero, meaning it is initially stationary on the curve.
Adams/Solver (C++) may adjust these assumed initial conditions in order to enforce other part or
constraint initial conditions.
PTCV/55, I=201, JFLOAT=301, CURVE=10, RM=302,
, DISP=2.,3.,0., VEL=-5.
This statement is the same as the last example, except it contains initial conditions. Adams/Solver
assembles the system with Marker 201 at the point on the curve nearest to coordinates (2.,3.,0.) in the
Marker 302 coordinate system. Adams/Solver imposes an initial speed of -5.0 on Marker 201 with
respect to the curve, meaning Marker 201 is moving towards the start of the curve.
Applications
The simplest point-curve constraint application is a pin-slot connection as illustrated in Figure 7 below.
Figure 7
The point-curve constraint keeps the center of the pin in the center of the slot, while allowing it to move
freely along the slot and rotate in the slot. Note that the point-curve constraint does not stop the pin at the
end of the slot. If the travel of the pin must be restricted, a force element, such as an SFORCE with an
IMPACT function, must be used.
A point-curve constraint may also represent a point follower on a cam, where the follower has a very
small radius compared to the curvature of the cam. Figure 8 below illustrates a point follower on a cam.
If the CURVE statement specifies a closed curve, Adams/Solver (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.
PTCV 313
C++ Statements
Figure 8
Point-Follower Mechanism
Figure 9
To model more complex cam-follower applications, see the CVCV statement. In the CVCV statement,
both the follower and cam can be represented as curves.
Because PTCV is a constraint, the point always maintains contact with the curve, even when the
dynamics of the system would actually lift the point off the profile. You may examine the constraint
forces to determine if lift-off should have occurred. If an accurate simulation of intermittent contact is
required, you should model the contact forces directly using a VFORCE.
Unlike the CVCV statement, the PTCV statement is not restricted to planar curves. PTCV can model
three-dimensional slots and cams, as well as mechanisms riding on nonplanar tracks, or a robot endeffector following a three-dimensional path in space.
See other Constraints available.
314 Adams/Solver
C++ Statements
REQUEST
The REQUEST statement indicates a set of data you want Adams/Solver (C++) to write in the request
file, and the XML formatted results file. Using a REQUEST statement, you can output a set of
displacements, velocities, accelerations, or forces with respect to markers in the system. FUNCTION
keywords allow you to explicitly define the output variables or employ a user-written subroutine
REQSUB to define nonstandard output.
Format
REQUEST 315
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.
316 Adams/Solver
C++ Statements
COMMENT=c
Specifies a title for the top of each set of information the REQUEST statement
outputs. The entire comment must be on one line. Because input lines can be
only eighty characters long at most, the comment can be from seventy-two
characters long (if you do not abbreviate COMMENT=) to seventy-eight
characters long (if you abbreviate COMMENT= to C=). Blank spaces and all
alphanumeric characters can be used. However, the comma (,), the semicolon
(;), the ampersand (&), and the exclamation point (!) cannot be used. The
COMMENT data is printed in the request file only.
CUNITS
(Component Units) Sets one or more strings that identify the unit dimension of
the result set components in XML result files. If the CUNITS argument is
omitted, then the units of the components are predefined based upon standard
request type (e.g. displacement, velocity, and acceleration) or they are
considered user units and no unit conversion will be performed. This argument
is mutually exclusive with the CLABEL argument.
The legal choices for the CUNITS parameter are:
CLABELS
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
(Component Labels) Sets one or more strings that identify the label to be used
when plotting the result set components. This argument is mutually exclusive
with the CUNITS parameter. Labels may be strings that include white space.
However, quotes must be used to define the string if special characters or white
space are used. This option is only used with XML result files.
REQUEST 317
C++ Statements
DISPLACEMENT
Outputs the displacement of the I marker with respect to the J marker. The
output data includes:
x component (X)
y component (Y)
z component (Z)
psi angle (PSI)
theta angle (THETA)
the phi angle (PHI)
The psi, theta, and phi angles are the Euler angle displacements of the I marker
with respect to the J marker. Adams/Solver (C++) calculates this displacement
data in the global coordinate system. If you specify RM, Adams/Solver (C++)
resolves the translational x-component, the translational y component, and the
translational z-component in the coordinate system of the RM marker. RM does
not affect psi, theta, and phi. If the YPR argument is placed in the OUTPUT
statement, the psi, theta, and phi rotations are converted to yaw, pitch, and roll
rotations.
F2=e
F3=e
F4=e
F6=e
F7=e
F8=e
318 Adams/Solver
C++ Statements
FORCE
Outputs the force associated with the I and the J markers or, if the I marker and
not the J marker is given, outputs the action-only forces on the I marker. When
both the I and the J markers are given, Adams/Solver (C++) sums the forces on
the I marker due to the forces associated with the I and the J markers. These
forces can include both applied forces (such as spring dampers and bushings)
and reaction forces from constraint elements (such as joints and motions).
When the I marker and not the J marker is given, Adams/Solver (C++) sums all
of the action-only forces applied to the I marker. If RM is specified,
Adams/Solver (C++) reports the components of the resulting vectors in the
reference frame of the RM marker. If RM is not specified, Adams/Solver (C++)
reports the components in the ground coordinate system (GCS). The output data
includes the time, the three components of the translational force, and the three
components of the torque.
FUNCTION=USER Defines and passes constants to the user-written subroutine REQSUB to define
{r1[,...,r30]}
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 action-only force. In the last case, only the I
marker needs to be identified.
RM=id
Identifies the marker with respect to which you want to resolve information.
Adams/Solver (C++) computes the data identified by the I marker and the J
marker, then reports the data as x, y, and z components in the reference frame of
the RM marker. Angular displacements, which are not vectors, are not affected
by RM. RM defaults to zero, which causes Adams/Solver (C++) to resolve
components in the ground coordinate system (GCS).
REQUEST 319
C++ Statements
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 Specifies an alternative library and name for the user subroutine REQSUB.
::subname
Learn more about the ROUTINE Argument.
VARIABLES
VELOCITY
Outputs the velocity of the I marker with respect to the J marker. The output data
includes:
translational x component (VX)
translational y component (VY)
translational z component (VZ)
rotational x component (WX)
rotational y component (WY)
rotational z component (WZ)
Adams/Solver (C++) calculates this velocity data (the first derivative of the
displacement of the I marker with respect to the J marker) in the global
coordinate system. If you specify RM, Adams/Solver (C++) resolves the
translational and rotational velocities vector in the coordinate system of the RM
marker.
Extended Definition
The REQUEST statement indicates a set of data you want Adams/Solver (C++) to write in the request
file. Using a REQUEST statement, you can output a set of displacements, velocities, accelerations, or
forces with respect to markers in the system. FUNCTION keywords allow you to explicitly define the
output variables or employ a user-written subroutine REQSUB to define nonstandard output.
Adams/Solver (C++) calculates all time derivatives in the ground coordinate system (GCS), although you
can specify that the data be resolved in another reference frame. This is of no importance in the case of
force data, but it can be very important in the case of velocities and accelerations. For example, joint
velocities are actually translational and rotational velocity difference vectors of the joint I marker and the
320 Adams/Solver
C++ Statements
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.
REQUEST 321
C++ Statements
Caution:
Applied forces and torques are those generated by beams, bushings, fields, general
For revolute, spherical, and universal joints and for atpoint, orientation, parallel
axes, and perpendicular joint primitives, Adams/Solver (C++) outputs the reaction
forces and torques acting at the request I marker (which may be either the
constraint I marker or the constraint J marker). The force and torque acting at the
request J marker are equal and opposite to the force and torque acting at the
request I marker. Depending on the type of constraint, some or all of the torques
acting at the I marker are zero. Determining reaction forces and torques for
cylindrical, planar, rack-and-pinion, screw, and translational joints and for inline
and inplane joint primitives is more complex.
If the request I marker corresponds to the constraint I marker, then Adams/Solver
(C++) outputs the force and torque acting at the constraint I marker. If the request I
marker corresponds to the constraint J marker, then Adams/Solver (C++) outputs
the force and torque acting at the instantaneous location of the constraint I marker,
but on the part containing the constraint J marker. The force translated to the
constraint J marker is the same as computed above. If the I and the J markers are
coincident, the torque translated to the constraint J marker is the same as computed
above. But if there is a finite separation between the I and the J markers, the torque
translated to the constraint J marker is different from the one computed above
(because of the moments contributed by the reaction forces).
322 Adams/Solver
C++ Statements
Caution:
You must be careful when requesting a force with the I and the J markers reversed
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 action-reaction force on Marker 0304 from Marker 0204.
Adams/Solver outputs the comment ROD/CRANK REACTION, to the request file.
REQUEST/21, F2=VARVAL(1)/ F3=DIF1(1)*5/ F4=DX(2109,409)
This REQUEST statement requests the value of VARIABLE/1, the first time derivative of DIFF/1
multiplied by five, and the x component of the displacement of Marker 2109 relative to Marker 409.
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"/>
REQUEST 323
C++ Statements
Requests are used whenever a particular output is desired from Adams/Solver (C++). The output
generated from the request contains data needed for plotting in a postprocessor. The writing of this files
is controlled by the OUTPUT statement.
An alternative to the use of REQUESTS is the RESULTS statement, which causes all the results for the
analysis to be saved to a results file. This file can then be used in a postprocessor. The major drawbacks
to using the RESULTS statement is the size of the file, and having the data in a form that needs to be
translated by a postprocessor.
When using a REQUEST statement, you must also have an OUTPUT/REQSAV statement in order to
create a request file (.req).
Data from certain Adams/Solver (C++) statements is accessible only through the request functions
(F2,...,F8). The statements include PINPUT, POUTPUT, VARIABLE, ARRAY, LSE, GSE, TFSISO, and
DIFF. To request information on PINPUT, POUTPUT, ARRAY, or VARIABLE, you should write the
function expression referencing PINVAL, POUVAL, ARYVAL, and VARVAL, respectively. To request
information on LSE, GSE, TFSISO, you should write the function expression referencing ARYVAL. To
request information on DIFF, you should write the function expression referencing DIF for the value of
the independent variable associated with a user-defined differential equation, and DIF1 for the value of
the time derivative of the independent variable of the user-defined differential equation.
See other Output available.
324 Adams/Solver
C++ Statements
RESULTS
The RESULTS statement creates a results file that includes all the simulation output from Adams/Solver
(C++). The results file can be either unformatted (binary) or formatted (ASCII).
Format
,NOACCELERATIONS
,NOAPPLIEDFORCES
,NODATASTRUCTURES
,NODISPLACEMENTS
,NOFLOATINGMARKERS
RESULTS/[FORMATTED][XRF]
,NOLINEAR
,NOREACTIONFORCES
,NOREQUESTS
,NOSYSTEMELEMENTS
,NOVELOCITIES
,NOCONTACTS
,NODE_INCIDENTS
,SCIENTIFICATION = i1, i2
,SIGINIFICANTFIGURES = i
,TRAILINGZEROES
,ZEROTHRESHOLD = r
RESULTS 325
C++ Statements
Arguments
DECIMALPLACES=i
FORMATTED
Specifies that the results file is to be a formatted (text) file. The default is
an unformatted (binary) file. The formatted results file contains
Adams/Solver (C++) output in plain text that you can read. You cannot
examine an unformatted results file directly. Although the unformatted
results file is not user-readable, it is generally preferred for several reasons.
The unformatted file is smaller, contains more precise data, and is much
quicker for Adams/Solver (C++) to write and for a postprocessor to read.
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 user-defined request, in the case of a classic results
file, or all request data (in the case of an XML-formatted results file
(XRF)).
NOSYSTEMELEMENTS
Specifies that the results file is not to include results for system modeling
elements such as user-defined differential equations, linear state equations,
general state equations, and transfer functions. The default is a results file
that contains results for system modeling elements.
326 Adams/Solver
C++ Statements
NOVELOCITIES
Specifies that the results file is not to include part velocities. The default is
a results file that includes part velocities.
NOCONTACTS
Specifies that the results file does not include contact incidents. The
default is a results file that includes contact incidents.
NODE_INCIDENTS
Specifies that the results file includes node incidents for contact on Flex
Bodies. The default is a results file that does not include node incidents.
ROUNDOFF
TRAILINGZEROS
RESULTS 327
C++ Statements
XRF
ZEROTHRESHOLD=r
Extended Definition
The RESULTS statement creates a results file that includes selections of output from an Adams/Solver
(C++) simulation. This all-purpose file can contain all the simulation output from Adams/Solver (C++).
The results file can contain any combination of the following information:
Displacements - Displacements of the BCS with respect to ground and resolved in the ground
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
modeling elements such as user-written differential equations, linear state equations, general
state equations, and transfer functions.
Tires - Displacements, velocities, accelerations, forces, and other information about tires.
Floating markers - Displacements of floating markers.
Linear - Eigenvectors, eigenvalues, and state matrices computed by a linear analysis invoked by
contact.
328 Adams/Solver
C++ Statements
Node incidents - Values computed for Flex Body nodes on Flex Bodies in contact.
Tip:
The title specified in the COMMENT argument helps identify the results file. If you do not
include the COMMENT argument in the RESULTS statement, Adams/Solver (C++) uses
a blank line for the title of the results file.
Because results files can contain all the information generated by Adams/Solver (C++)
during a simulation, they may become quite large. The NO... arguments should be used to
remove unwanted output and conserve disk space.
Caution:
Examples
RESULTS/FORMATTED, NODATASTRUCTURES, NOSYSTEMELEMENTS
RESULTS/NODISPLACEMENTS, NOVELOCITIES
,NOACCELERATIONS, NODATASTRUCTURES
,NOSYSTEMELEMENTS, NOFLOATINGMARKERS
SENSOR 329
C++ Statements
SENSOR
The SENSOR statement is used to modify the simulation when a user-defined event occurs during runtime. 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
330 Adams/Solver
C++ Statements
Arguments
BISECTION
CODGEN
DT=r
EQ
ERROR=r
SENSOR 331
C++ Statements
332 Adams/Solver
C++ Statements
HALT
LE
RESTART
RETURN
ROUTINE=libname::subname
STEPSIZE=r
SENSOR 333
C++ Statements
TERROR
VALUE=r
YYDUMP
Extended Definition
The SENSOR statement defines a user-defined event that affects a set of simulation controls when the
event occurs. The event is defined by a logical expression that compares a function expression (or
evaluation of a user-written subroutine) to a target value using a relational operator. If the logical
expression becomes true during the simulation, the sensor modifies a set of simulation controls, which
include output and integration step sizes, simulation end time, and the Jacobian pivot sequence. A sensor
can also output diagnostic information and store the value of a function expression for later recall.
Adams/Solver (C++) evaluates the logical expression after every successful integration step when doing
dynamic analysis and after every successful output step when doing other types of analyses. To define
the function, use a function expression or a user-written subroutine. User-written subroutines and utility
subroutines discuss the subroutines they can access.
Adams/Solver(C++) uses a different algorithm for sensor detection from the one used by
Adams/Solver(FORTRAN). Adams/Solver(FORTRAN) uses a prediction to try to pick an integration
step that will detect the sensor. Adams/Solver(C++) uses three methods of search algorithms for sensor
detection:
1. Bisection method (primarily meant for discrete signals)
2. Time-based method
334 Adams/Solver
C++ Statements
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 time-based algorithm to predict exactly
when the sensor value is hit.
If the sensor function depends on Adams states, or uses a SENSUB, then it uses a secant algorithm for
sensor detection. This method will determine if the current and last values of the sensor function have
crossed the trigger values, and if so, will use the secant method to attempt to refine to the trigger value.
Finally, it will then determine if the sensor function is within the ERROR specified and trigger the sensor
if this is true. This method behaves differently to the bisection method in that it will trigger the sensor
even if the current and last sensor values do not fall within the sensor ERROR. However, if there are even
roots in the sensor function, the sensor may miss this case unless a smaller integrator step is used.
Caution:
When using the default search algorithm in Adams/Solver (C++), the SENSOR
function must be continuous. The secant-type search algorithm is inaccurate and time
consuming when the function is discontinuous. For that reason, functions of time or
displacements work best for sensors; functions of velocities, accelerations, and forces
are less desirable.
Use the BISECTION attribute when discontinuous SENSOR functions must be used,
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
SENSOR 335
C++ Statements
(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,
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
SENSOR, especially if the specified error is very small. In these cases, Adams/Solver
(C++) may appear to pass through the sensed value without invoking the sensor action.
If this occurs, you should try increasing the error tolerance, if possible. An alternative
is to change to an inequality (GE or LE) sensor, then DEACTIVATE the sensor after it
has triggered.
Examples
SENSOR/231, FUNCTION=DX(0201,0307)/
,VALUE=3.24, RETURN
This SENSOR statement senses the x-component for the displacement of Marker 0201 with respect to
Marker 0307 and resolves the displacement in the ground coordinate system (GCS). When the relative x
displacement equals 3.24 (+/- 0.001), the statement stops the simulation and returns to the command
level.
See other Analysis parameters available.
336 Adams/Solver
C++ Statements
SFORCE
The SFORCE statement applies a single-component force or a torque to one or both of the parts it
connects.
Format
Arguments
ACTIONONLY
SFORCE 337
C++ Statements
I=id, J=id
ROTATION
ROUTINE=libname::subname
You can use the same marker for both the I and J
markers when you are specifying an action-only
SFORCE. For example, you would do this when
specifying rocket thrust forces.
Designates a rotational force, that is, a torque. For an actionreaction torque, the z-axes of the I and the J markers must be
parallel and must point in the same direction. Adams/Solver
(C++) applies a torque about each z-axis. By definition, the
right-hand rule defines a positive torque.
Specifies an alternative library and name for the user subroutine
SFOSUB.
Extended Definition
The SFORCE statement applies a force or torque to two parts. You specify a marker on each part for force
or torque application. The magnitude of the force may be defined as a function of any combination of
displacements, velocities, other applied forces, user-defined variables, and time. An SFORCE statement
can apply action-reaction forces or can apply action-only forces.
For translational action-reaction forces, Adams/Solver (C++) applies an action and reaction force along
the line connecting the I and the J markers. The force exerted on I is directed from J toward I, while the
force exerted on J is directed from I toward J. The magnitude of each is specified in the FUNCTION
argument.
For translational action-only forces, Adams/Solver (C++) applies the force on the I marker only. There
is no reaction on the J marker. The force on the I marker is directed along a vector parallel to and codirected with the z-axis of the J marker.
338 Adams/Solver
C++ Statements
For rotational action-reaction forces, Adams/Solver (C++) applies an action torque on the I marker about
the z-axes of the I marker and a reaction torque on the J marker about the z-axis of the J marker.
Furthermore, Adams/Solver (C++) assumes that the z-axes of the I and the J markers are parallel.
For rotational action-only forces, Adams/Solver (C++) applies the torque on the I marker only. There is
no reaction on the J marker. The torque on the I marker is applied about a vector parallel to and codirected with the z-axis of the J marker.
You write a function expression or a user-written subroutine (SFOSUB) to define the constitutive
equation for the force applied at the I marker. Adams/Solver (C++) evaluates the reaction forces at the J
marker.
Tip:
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 actiononly force, Adams applies the force to the I marker in the J marker z-axis direction.
For action-reaction translational forces in Adams, a positive force (that is, positive
value of the FUNCTION argument) between two markers causes them to repel
each other and a negative force causes them to attract each other.
Caution:
For rotational action-reaction SFORCEs, the z-axes of the I and the J markers must be
parallel and pointed in the same direction. If they are not, the results are unpredictable and
may differ bewteen the Adams/Solver (C++) and Adams/Solver (FORTRAN).
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 action-reaction, compression-only 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.
SFORCE 339
C++ Statements
F =
Kj ( x l ) j + cx'
j=0
If k0 = -10.1, k1 = 15.2, k2 = 4.1, c = 1.5, and l = 3.142, then the Adams/Solver (C++) statement that
represents this translational spring acting between two parts containing Markers 12 and 34, respectively,
appears as
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.
340 Adams/Solver
C++ Statements
SPLINE
The SPLINE statement defines discrete data that Adams/Solver (C++) interpolates using the AKISPL
and CUBSPL function expressions and the AKISPL and CUBSPL data-access subroutines. A SPLINE
statement provides one or two independent variables and one dependent variable for each data point you
supply.
If you are licensed to use the Adams/Durability plugin, the SPLINE statement includes arguments to
perform durability analyses. These arguments are explained in the following pages along with the
standard arguments.
Format
SPLINE/id
,X = x1, x2, x3, x4 [, ..., xn]
,Y = y1, y2, y3, y4 [, ..., yn]
[, XUNITS = string ]
[, YUNITS = string ]
[, UNITS = string ]
[, LINEAR_EXTRAPOLATE]
or
SPLINE/id
,X = x1, x2, x3, x4 [, ..., xn]
,Y = z1, y11, y12, y13, y14 [, ..., y1n]
,Y = z2, y21, y22, y23, y24 [, ..., y2n]
,Y = z3, y31, y32, y33, y34 [, ..., y3n]
,Y = z4, y41, y42, y43, y44 [, ..., y4n]
[, ..., Y = zm, ym1, ym2, ym3, ym4 [, ..., ymn]]
[, XUNITS = string ]
[, YUNITS = string ]
[, ZUNITS = string ]
[, UNITS = string ]
[, LINEAR_EXTRAPOLATE]
or
SPLINE 341
C++ Statements
SPLINE/id
, FILE = filename
[, BLOCK = blockname]
[ , CHANNEL = id ]
[, XUNITS = string ]
[, YUNITS = string ]
[, UNITS = string ]
[, LINEAR_EXTRAPOLATE]
Arguments
BLOCK
Specifies the use of a particular, named block within a file. The BLOCK
argument is optional, and requires the FILE argument.
CHANNEL
FILE
Specifies the use of a file, rather than the X and Y arguments, to supply data for
the SPLINE. FILE causes Adams/Solver (C++) to call the user-written
subroutine SPLINE_READ, which you must provide. The FILE argument and
the X and Y arguments are mutually exclusive.
If you are using FILE with Adams/Durability, it specifies the name of the time
history file that supplies data for the SPLINE. The file can be of type DAC
(nSoft format) or RPC III (MTS format).
For more on how to define a SPLINE using the FILE argument, see the example
in SPLINE_READ subroutine.
LINEAR_EXTRAP
OLATE
342 Adams/Solver
C++ Statements
X=x1,x2,x3,x4[ , . . . Specifies at least four x values. The maximum number of x values, n, depends
, xn]
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]
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]]
UNITS
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)
Extended Definition
Adams/Solver (C++) applies curve-fitting techniques that interpolate between data points to create a
continuous function. If the SPLINE data has one independent variable, Adams/Solver (C++) uses a cubic
polynomial to interpolate between points. If the SPLINE data has two independent variables,
SPLINE 343
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
To use discrete data input with a SPLINE statement, you must write either a function expression that
includes one of the two Adams/Solver (C++) spline functions (AKISPL and CUBSPL) or a user-written
subroutine that calls one of the two spline data-access subroutines (AKISPL and CUBSPL).
Spline Function Interpolation Methods
The SPLINE functions and data-access subroutines use two different interpolation methods: the Akima
method and a traditional cubic interpolation method.
The AKISPL function and the AKISPL subroutine use the Akima method of interpolation. This
The Adams/Durability SPLINE statement is an extension of the Adams/Solver (C++) SPLINE statement
that supports the input of experimental test data from industry standard formats DAC and RPC III. The
DAC format comes from nCode/nSoft. The RPC III file format comes from MTS.
DAC or RPC III files do not have standard file extensions. To determine which of these file types is in
use, Adams/Solver (C++) opens the file and reads a minimal amount of information contained in the file
head. If the specified file is not of type DAC or RPC III, Adams/Solver (C++) assumes that the file is a
user-defined file format, and processes the SPLINE statement using a SPLINE_READ user-supplied
subroutine. For more on how to define a SPLINE using the FILE argument for user-defined file formats,
see the example in SPLINE_READ subroutine.
344 Adams/Solver
C++ Statements
To use DAC or RPC III data that is specified in a SPLINE statement as input to Adams/Solver (C++),
you must write a function expression that includes the INTERP function. For more on how to use the
Adams/Durability INTERP function, see the INTERP function.
Tip:
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
The set of values in the table below relates the force in a spring to its deformation.
Data Relating Spring and Spring-Deflection Force
Deflection Force
-0.33
-38.5
-0.17
-27.1
-0.09
-15.0
0.0
0.0
0.10
10.0
025
30.0
0.40
43.5
0.70
67.4
SPLINE 345
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,
, Y=-38.5,
, XUNITS =
, YUNITS =
This SPLINE statement passes the data in the table above to a subroutine or function that uses cubic
spline functions to fit a curve to the values. The curve allows Adams/Solver (C++) to interpolate a value
of Y for any value of X. It also specifies that the X values are of type length and Y values are of type
force.
The set of values in the table below details a set of nonlinear, force-deflection relationships of a spring at
various temperatures.
Data Relating Spring Force to Spring Deflections at Various Temperatures
Force at degrees Fahrenheit:
Deflection:
20
30
40
50
-0.33
-38.5
-36.0
-30.0
-25.1
-0.17
-27.1
-25.4
-21.7
-18.6
-0.09
-15.0
-13.1
-9.6
-4.4
0.0
0.0
0.0
0.0
0.0
0.1
10.0
9.1
7.5
4.6
0.25
30.0
26.4
21.3
17.8
0.40
43.5
37.9
34.1
27.1
0.70
67.4
60.3
53.2
46.3
From table above, you can determine force when deflection equals -0.33 and when temperature equals
20. You can also determine force when deflection equals -0.17 and when temperature equals 30.
However, what is the force when deflection equals -0.25 and when temperature equals 25?
To determine the force at any deflection and temperature, you need to define a set of continuous functions
that generally relate force to deflection and temperature. If deflection is the independent x value and
temperature is the independent z value, you can define a set of functions in a family of curves using the
SPLINE statement. The SPLINE statement for this example is shown next:
346 Adams/Solver
C++ Statements
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 z-axis of
Marker 401 using a function expression.
The function expression for the MOTION statement references data from the SPLINE statement using
the INTERP function. The test data from the DAC file is known to be acquired in degrees, and since
Adams/Solver (C++) expects rotational motion to be specified in radians, a conversion from degrees to
radians (factor DTOR) is also included in the function expression.
SPLINE/201,FILE=test.rpc,CHANNEL=1
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.
SPRINGDAMPER 347
C++ Statements
SPRINGDAMPER
The SPRINGDAMPER statement applies a rotational or a translational springdamper between two
markers.
Format
Arguments
ANGLE=r
Defines the reference angle for the torsional spring. If the reference torque of
the spring is zero, ANGLE equals the free angle. Adams/Solver (C++) assumes
ANGLE is in radians unless a D is added after the value.
Default: 0
C=r
Specifies the viscous damping coefficient for the force. The force due to
damping is zero when the system is at rest.
Range: C > 0
CT=r
Specifies the viscous damping coefficient for the torque. The torque due to
damping is zero when the system is at rest. CT must be in units of torque per
radian per unit of time.
Range: CT > 0
FORCE=r
348 Adams/Solver
C++ Statements
I=id, J=id
Specifies the identifiers of the two markers between which the force or the
torque is to be exerted.
K=r
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
TORQUE=r
TRANSLATIONAL
Extended Definition
The force value is the force on the I marker applied by the J marker; the force on the J marker is equal
and opposite. The term b is the distance between the I and the J markers. Adams/Solver (C++) assumes
that b is always greater than zero. Adams/Solver (C++) automatically computes the terms db/dt and b.
The following linear constitutive equation describes the torque applied at the I marker:
Ta = -CT (da/dt) - KT(a-ANGLE) + TORQUE
The torque value is applied to the I marker about the positive z-axis of the I marker; the torque on the J
marker is equal and opposite to the torque on the I marker. The right-hand rule defines a positive torque.
SPRINGDAMPER 349
C++ Statements
The term a is the angle of the I-marker x-axis relative to the J-marker x-axis, measured about the J-marker
z-axis. Adams/Solver (C++) takes into account the total number of complete rotations. Adams/Solver
(C++) automatically computes the terms da/dt and a.
Caution:
If the z-axis of the I marker is not parallel to, and/or not pointed in the same
direction as, the z-axis of the J marker for a rotational springdamper, the results are
unpredictable.
Since the line-of-sight method determines the direction of a translational
This SPRINGDAMPER statement describes a force that Marker 30 applies to Marker 25. Marker 25 also
applies a force of equal magnitude and opposite direction to Marker 30. The argument TRANSLATION
indicates that this is a translational springdamper, rather than a rotational one. Therefore, the magnitude
of the force is proportional to the spring free length, to the distance between the two markers, and to the
time rate of change of the distance between the two markers. The L argument indicates that the spring
free length is 0.01 length units (L is the free length because the FORCE argument defaults to zero). The
spring constant K is 5 force units per unit length, and the damping constant C is 0.1 force units-seconds
per unit length.
See other Forces available.
350 Adams/Solver
C++ Statements
STRING
The STRING statement defines a character string that may be referred to later in the execution of
Adams/Solver. An interactive STRING command can be used to alter or review this character string. A
GTSTRG subroutine can be used to retrieve this character string in a user-written subroutine.
Format
STRING/id, STRING=c
Arguments
STRING=c
Caution:
The following characters are not permitted in a STRING argument because they are
delimiters in the Adams/Solver command language: comma (,), semicolon (;), ampersand
(&), and exclamation point (!). This is because the comma indicates that additional
Adams/Solver arguments follow; the semicolon indicates that additional Adams/Solver
statements follow on the same line; the ampersand indicates that the next line is a
continuation of the statement on this line; and the exclamation point indicates that
Adams/Solver is to stop reading the line.
Examples
STRING/101, STRING=MARKER=
This STRING statement enters the character string MARKER= for later reference. The GTSTRG
subroutine can retrieve this string.
See other Reference data available.
SURFACE 351
C++ Statements
SURFACE
The SURFACE statement defines a three-dimensional parametric surface that you can reference using
the MARKER statement.
Format
Arguments
FILE=file_name
FUNCTION=USER
(r1[,...,r30])/
MAXPAR=r1, r2
MINPAR=r1, r2
352 Adams/Solver
C++ Statements
ROUTINE=libname::subname
VCLOSED
Extended Definition
The x, y, and z coordinates of a point on a parametric surface are functions of independent parameters,
(u,v). As (u,v) vary from their minimum to maximum values, the functions x(u,v), y(u,v), and z(u,v)
sweep out points on the surface. A simple example of a parametric surface is defined by the following
equations and illustrated in the figure below:
x=u
y=v
z = cos( u2 + v2)
SURFACE 353
C++ Statements
354 Adams/Solver
C++ Statements
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 user-written subroutine. See SURSUB for more details.
If [u,v] are the parameters corresponding to the current point on the surface, and [u*, v*] are the
parameters for the closest material point on the surface to [u,v], the penalty force that is applied in the
[u,v] domain is:
F = -K * [(u-u*)2 + (v-v*)2]
K = 108
At this time, users have no control over the stiffness parameter, K.
Examples
SURFACE/2, UCLOSED, MINPAR=0,0, MAXPAR=6.2832, 0.5
, FUNCTION=USER(0.2)
This statement creates a user-written surface closed in u and open in v. The range of u is (0, 6.2832). The
range of v is (0, 0.5).
SURFACE /8, FILE=hemisphere.xmt_txt
This statement creates a surface from a Parasolid geometry file. The file must contain a single face of a
sheet body.
Applications
Each SURFACE is always associated with a surface marker. Surface markers, in turn, can be used to
create a variety of higher-pair constraints. Typical examples include:
A point sliding on a surface (spherical joint connecting a surface marker to an ordinary marker
on a different body).
Two surfaces sliding on each other (revolute joint connecting two surface markers).
A robot end-effector executing a specific work-path while orienting the end-effector to be
always normal to the surface of the work path (a fixed joint connecting a surface marker on one
part to an ordinary marker on a second part).
The SURFACE statement can only be referenced by a MARKER statement. See the MARKER statement
for more information.
See other Reference data available.
TFSISO 355
C++ Statements
TFSISO
The TFSISO (Transfer Function, Single-Input, Single-Output) statement defines a single-input, singleoutput transfer function as a ratio of two polynomials in the Laplace domain when used with the
associated ARRAY statements.
Format
Arguments
STATIC_HOLD
Indicates that the TFSISO states are not permitted to change during
static and quasi-static analysis.
U=id
356 Adams/Solver
C++ Statements
X=id
Y=id
Extended Definition
The TFSISO (Transfer Function, Single-Input, Single-Output) statement is designed to model a linear,
time-invariant dynamic system defined in the Laplace domain, especially to facilitate the import of
elements from control-system block diagrams. It can also be used, however, to define an arbitrary set of
constant-coefficient, differential and algebraic equations which can be expressed in the Laplace domain
as
bo + b1 s 1 + + bm s m
y--------( s )= ----------------------------------------------------G(s) =
u(s)
ao + a1 s 1 + + ak s k
where m < k
The TFSISO follows standard control systems terminology, where x is the state variable array, y is the
output variable, and u is the input variable. Initial conditions are assumed to be identically zero. In the
Adams/Solver (C++) dataset, each of these arrays is defined using an ARRAY statement. The
characteristic equation for a single TFSISO statement, defined by the DENOMINATOR argument, can
be a polynomial of degree less than 30.
Internally to Adams/Solver (C++), there is an algorithm to automatically convert the list of fixed
numerator and denominator coefficients to a canonical state-space form; that is, a set of coupled, linear,
constant-coefficient differential equations and a single algebraic equation.
When you reference only the output of the TFSISO, the details of the internal equations are unimportant.
In some cases, however, it may be useful to understand how Adams/Solver (C++) constructs the
equations. When interpreting Adams/Linear output or examining the values in the X ARRAY, for
instance, it may be necessary to determine what the internal states represent.
The conversion from transfer function to canonical state-space form is done in two steps. First, the
numerator and denominator are normalized by the coefficient of the largest power of s in the
denominator.
q = [b0/ak,b1/ak,...,bm/ak,0,...,0,0]
p = [a0/ak,a1/ak,...,ak-1/ak,1]
TFSISO 357
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:
qo + q1 s1 + + qk sk
y(s)
G ( s ) = ---------- = -------------------------------------------------u(s)
p o + ps 1 + + p k s k
The equivalent state space realization of this transfer function is:
x
A B x
=
C D u
y
where:
A =
pk 1 1 0 . . . 0 0
qk 1 pk 1 qk
pk 2 0 1 . . . 0 0
qk 2 pk 2 qk
.
.
.
.
.
.
p1 0
.
.
.
0
1
.
.
.
.
.
.
.
.
.
.
.
.
.
1
0
.
.
.
1
B =
po 0 0 . . . 0 0
C =
Note:
Tip:
1 0 0 . . . 0 0
.
.
.
q1 p1 qk
qo po qk
D =
qk
Except in the specific case where the numerator and denominator are of equal orders, qk= 0.
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.
358 Adams/Solver
C++ Statements
Caution:
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 pole-zero cancellation in the TFSISO
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 user-defined variables to zero,
and uses the user-supplied initial-condition values only as an initial guess for the
static solution. Generally, the final equilibrium values are not the same as the
initial condition values. Adams/Solver (C++) then uses the equilibrium values of
the user-defined variables as the initial values for any subsequent analysis, just as
with the equilibrium displacement and force values.
However, if STATIC_HOLD is specified, the user-specified initial conditions are
retained as the static equilibrium values. Thus, the final equilibrium values are the
same as the user-specified initial conditions. Note that this does not guarantee that
the time derivatives of the user-defined variable are zero after static analysis.
Examples
ARRAY/100, X
ARRAY/101, U, VARIABLE=101
ARRAY/102, Y
VARIABLE/101, FUNCTION=ACCZ(5,99,5)
TFSISO 359
C++ Statements
1
G ( s ) = ---------------------------------2
s + 10s + 100
ARRAY/100 is the state array. ARRAY/101 is the input array. ARRAY/102 is the output array.
VARIABLE/101 defines the input.
Applications
The TFSISO statement may be most useful for adding feedback controls to an Adams/Solver (C++)
model. A series of TFSISO statements can be assembled to resemble any linear block diagram
arrangement. The transfer function can be derived manually or may be imported directly from a control
system design program such as MATRIXx or MATLAB. Normally, the mechanical portion of the model
includes some kind of actuator which depends on the TFSISO output.
TFSISO statements can also be conveniently used in many cases to replace systems of coupled DIFF and
VARIABLE statements (for nonlinear equations, the GSE statements should be used). Examples of
possible dynamics system uses include unsteady aerodynamics, hydraulics, power transmission, and
electrodynamics.
You can use the current values of TFSISO state variables and outputs in both function expressions and
user-written subroutines via the associated ARRAY facilities (see the function expression ARYVAL, and
the subroutines: GTARAY, SYSARY, and SYSFNC). That is, instead of Adams/Solver (C++) functions
and FORTRAN callable subroutines dedicated explicitly to the TFSISO statement, the system states and
outputs are accessed by offset referencing through the appropriate ARRAY routines. This method of
referencing the variables makes access to the system states and outputs consistent for all three system
modeling elements, the TFSISO statement, the GSE statement, and the LSE statement.
See other Generic systems modeling available.
360 Adams/Solver
C++ Statements
TITLE
The TITLE delimiter is the entire first line in a dataset and describes the dataset. The title cannot be more
than 80 characters and must fit on one line. It may contain any printable ASCII characters and any
number of blank spaces. The title may be left blank.
Examples
(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.
UNITS 361
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
362 Adams/Solver
C++ Statements
Arguments
LENGTH = {ANGSTROM,
CENTIMETER, FOOT, KILOMETER,
INCH, METER, MICROINCH,
MICROMETER, MILE, MILLIMETER,
MILS, NANOMETER, YARD}
UCF = r
Mass
Force = ------------- Acceleration
UCF
Examples of how to calculate the UCF for your choice of
units are given below in the Extended Definition of the
UNITS statement.
UNITS 363
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
2nd law (for a particle in one dimension)
F = MA
(1)
is true when written using that choice of units. The CGS and MKS options for the SYSTEM argument
of the UNITS statement are dynamical units. Model units may be dynamical units, but that is not a
requirement.
To work with model units that are not dynamical units, the UCF is defined to make Newton's 2nd law
valid with that choice of model units by dividing the inertia values by the UCF to account for the
inconsistency of the model units. To see why this is legitimate, consider a system of model units (denoted
by the "primes") F', M', L', and T', and any valid system of dynamical units F, M, L, and T, where the
model units are related to the dynamical units by the scale factors sF, sM, sL, and sT:
sFF' = F
(2)
sMM' = M
(3)
sLL' = L
(4)
sTT' = T
(5)
Equation (4) and Equation (5) imply that acceleration expressed in model units is related to acceleration
in dynamical units by
364 Adams/Solver
C++ Statements
s
-----L-2 A' = A
sT
(6)
Using Equation (2), Equation (3), and Equation (6) to substitute F, M, and A, and into Equation (1) gives
sM sL
F' = M'A' ------------2
sF sT
(7)
sF s T2
UCF = -----------sM sL
(8)
to combine the four scale factors into one, Equation (7) can then be rewritten as
M'
F' = ------------ A'
UCF
(9)
UNITS 365
C++ Statements
There are at least three reasons that you might need to calculate the UCF. One is if the available choice
of units supported by the UNITS statement does not suit you needs. Say, for example, you want to work
in model units of TON_FORCE, US_TON, YARD, and MINUTE. You would calculate the UCF
according to Equation (8), taking note that the scale factors sF, sM, sL, and sT are the numbers by which
you multiply numerical values expressed in model units to convert them to dynamical units. It does not
matter with respect to what system of dynamical units the scale factors are expressed. (Adams/Solver
(C++) always expresses them with respect to the MKS system when it calculates the UCF when the
SYSTEM (for FPS and IPS) or the FORCE, MASS, LENGTH, and TIME arguments of the UNITS
statement are used.) In our example,
NEWTON
s F = 8896.443230521 -----------------------------------TON FORCE
(10)
KILOGRAM
s M = 907.18474 -------------------------------US TON
(11)
METER
s L = 0.9144 -------------------YARD
(12)
SECOND
s T = 60 ------------------------MINUTE
(13)
When these values are substituted into Equation (8), the result is UCF = 38608.858267716525. Note that
sF, sM, sL, and sT are the same as the values in the scales array argument of the utility subroutine
GTUNTS (although they are returned in scales in the order: (sT, sL, sF, sM)).
A second reason that you might need to calculate the UCF, even if you do not specify it explicitly with
the UNITS statement, is if you write an expression that uses the numerical value of an inertia property,
in model units, of a PART, FLEX_BODY, or POINT_MASS. If you use such an expression for the
definition of a VARIABLE, as for example, a component of the angular momentum of a PART with
respect to a fixed point, you must be aware of your use of this variable. If it is to be used such that it will
play a role in the system dynamics (that is, not just for output purposes such as plot or charts), be sure to
write the expression with the value of the inertia (in model units) divided by the UCF. Otherwise it will
have the wrong scaling and the solution will be incorrect. However, this is not a concern when using the
utility subroutine BODY_MASS_PROPERTY: it returns inertia properties in model units. That is, it
multiplies Adams/Solver (C++)'s internal values of the inertias by the UCF before returning them to the
caller.
A third reason you might need to calculate the UCF is to see how it will affect the scaling of your
problem, particularly with regard to the timescale over which you are simulating. This is discussed in a
subsequent subsection.
The scale factors sF, sM, sL, and sT used by Adams Solver (C++) to calculate the UCF are listed in Tables
1 to 4. These are exact values in all cases except for the mass units of slinch and slug, which are
366 Adams/Solver
C++ Statements
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
SF
CENTINEWTON
0.01
DYNE
1.0e-5
KILOGRAM_FORCE
9.80665 ()
KNEWTON
1000
KPOUND_FORCE
4448.2216152605 (, )
MEGANEWTON
1.0e6
MICRONEWTON
1.0e-6
MILLINEWTON
0.001
NANONEWTON
1.0e-9
OUNCE_FORCE
0.27801385095378125 (, , )
POUND_FORCE
4.4482216152605 (, )
POUNDAL
0.138254954376 (, )
UNITS 367
C++ Statements
Table 2
SM
GRAM
0.001
KPOUND_MASS
453.59237 ()
MILLIGRAM
1.0e-6
MICROGRAM
1.0e-9
NANOGRAM
1.0e-12
OUNCE_MASS
0.028349523125 ()
POUND_MASS
0.45359237 ()
SLINCH
175.12683524647638 (, , )
SLUG
14.593902937206365 (, , )
TONNE
1000
US_TON
907.18474 ()
Table 3
SL
ANGSTROM
1.0e-10
CENTIMETER
0.01
FOOT
0.3048
KILOMETER
1000
INCH
0.0254
MICROINCH
2.54e-08
MICROMETER
1.0e-6
MILE
1609.344
MILLIMETER
0.001
MILS
2.54e-05
NANOMETER
1.0e-9
YARD
0.9144
368 Adams/Solver
C++ Statements
Table 4
ST
DAY
86400
HOUR
3600
MICROSECOND
1.0e-6
MILLISECOND
0.001
MINUTE
60
NANOSECOND
1.0e-9
Choosing units appropriate for the timescale of the problem you are analyzing can sometimes be critical.
One example of this is related to the choice of units of time. If your model is to be simulated over very
short durations, choosing time units that are smaller than the second is worth considering. One reason for
this is because several of the numerical integrators in Adams/Solver (C++) use the reciprocal of the
integration time step to calculate some terms of the Jacobian matrix it must form and solve as part of a
linear system of equations. If the time step is very small, its reciprocal will be very large, causing this
matrix to be ill-conditioned. This can lead to more required iterations to find a solution, a less accurate
solution, and in the worst case, the inability to find a solution.
Additionally, modeling elements that depend on time for updates, such as the dependence of a GSE with
discrete states on its sample time, can benefit from using time units smaller that the second. This is
because Adams/Solver (C++) determines whether a sample time is hit within a temporal-error
tolerance. For very small sample times, using smaller time units can improve the accuracy of the behavior
of such modeling elements.
Examples
UNITS/FORCE=KILOGRAM_FORCE,
,MASS=KILOGRAM, LENGTH=MILLIMETER, TIME=SECOND
The UNITS statement selects force units of KILOGRAM _FORCE, mass units of KILOGRAM, length
units of MILLIMETER, and time units of SECOND.
See other Analysis parameters available.
VARIABLE 369
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
ROUTINE = libname::subname
Extended Definition
The VARIABLE statement creates a user-defined algebraic equation. The value of the VARIABLE
statement may depend on almost any Adams/Solver (C++) system variable.
You can define the value of the VARIABLE statement by either writing a function expression in the
dataset or by calling a VARSUB user-written subroutine. Learn more on User-Written Subroutines and
Utility Subroutines.
370 Adams/Solver
C++ Statements
Function expressions and user-written subroutines can access the value of the VARIABLE statement with
the Adams/Solver (C++) function VARVAL(id) (see VARVAL) to represent the value, where id specifies
the user-selected identifier of the VARIABLE statement. User-written subroutines access single
VARIABLE statement values by calling the subroutine SYSFNC.
Caution:
point exception or lead Adams/Solver (C++) away from the desired solution.
Examples
VARIABLE/4, FUNCTION = IMPACT(DZ(10,90),
, VZ(10,90), 1, 3E5, 1.2, 1,.05)
This VARIABLE statement defines an impact function. You may refer to this function as VARVAL(4) in
other function expressions. This may make the other expressions more concise and readable, and might
avoid repeated impact function calculations.
See other Generic systems modeling available.
VFORCE 371
C++ Statements
VFORCE
The VFORCE statement creates a translational vector force element that is specified using three
orthogonal components. You may define the VFORCE statement through user-specified function
expressions in the Adams/Solver (C++) dataset or through user-written subroutines.
Format
Arguments
FX=e
FY=e
FZ=e
JFLOAT=id
372 Adams/Solver
C++ Statements
RM=id
ROUTINE=libname::subname
The VFORCE statement creates an Adams/Solver (C++) translational vector force element that applies
a three-component force between two parts of the system. The element applies an action force to the part
to which the I marker belongs and a corresponding reaction force to the part to which the JFLOAT marker
belongs. The VFORCE statement establishes the position of the JFLOAT marker. As the system moves,
Adams/Solver (C++) moves the JFLOAT marker on its part to keep the JFLOAT and I markers
superimposed. Therefore, Adams/Solver (C++) applies the reaction force to the JFLOAT markers part
at the instantaneous position of the I marker.
The total vector force depends on the vector sum of the individual force components that you specify.
The magnitude of the force is the square root of the sum of the squares of the magnitude of the three
mutually-orthogonal force components. You can specify the functions with function expressions (see
C++ Functions) or user-written FORTRAN subroutines (see User-Written Subroutines).
RM marker axes determine the direction of the force action. The reaction is equal and opposite to the
action.
Formulation
Action
VFORCE 373
C++ Statements
Reaction
Applied to: JFLOAT marker
Values:
Fr = -Fa
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 user-defined functions FX, FY, and FZ should be smooth, continuous, and singlevalued. These conditions make the solution process very effective.
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.
374 Adams/Solver
C++ Statements
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 six-component force set.
See other Forces available.
VTORQUE 375
C++ Statements
VTORQUE
The VTORQUE statement defines a vector torque that consists of three orthogonal components. You can
define the VTORQUE statement through user-specified function expressions in the Adams/Solver (C++)
dataset or through user-written subroutines.
Format
Arguments
JFLOAT=id
RM=id
ROUTINE=libname::subname
TX=e
376 Adams/Solver
C++ Statements
TY=e
TZ=e
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 markers part.
The components of the torque depend on expressions or subroutines that you supply. The magnitude of
the torque is the square root of the sum of the squares of the magnitudes of the three mutually orthogonal
torque components. You can specify these functions using function expressions (see C++ Functions) or
user-written FORTRAN subroutines (see User-Written Subroutines).
The direction of the torque action is determined by the resultant 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
VTORQUE 377
C++ Statements
TZ is the user-defined function defining the magnitude and sign of the z-component according to
Reaction
Depending on the nature of the desired torque relationship, the RM marker may belong to
the same part as the I marker or the JFLOAT marker, or to a third, unrelated part.
Caution:
The user-defined functions TX, TY, and TZ should be smooth, continuous, and singlevalued. These conditions make the solution process very effective.
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 aero-dynamic center. You can use a VFORCE statement (see VFORCE) to supply the remaining
378 Adams/Solver
C++ Statements
translational forces, or the GFORCE statement (see GFORCE) to provide all six forces using a single
entity. In any event, you can use the reference marker to resolve the aircraft inertial velocity onto aircraft
axes for subsequent calculation of aerodynamic forces.
Yaw, Pitch, and Rolling Moments on a Flight Vehicle
Another application where a VTORQUE would significantly simplify modeling and analysis is in
consideration of gravitational torques exerted on Earth-orbiting satellites. In this case the RM marker
would not be fixed in the satellite or the Earth, but would move with the rotating line segment extending
between the satellite and the Earth.
When compared with the SFORCE statement (see SFORCE), the VTORQUE statement offers the
advantage that the resultant torque direction (with respect to the RM marker) can vary.
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
ABS
ACOS
AINT
ANINT
ASIN
ATAN
ATAN2
COS
COSH
EXP
LOG
LOG10
MAX
MIN
MOD
SIGN
SIN
SINH
SQRT
TAN
TANH
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
2 Adams/Solver
C++ Functions
Category
Name
FM
FX
FY
FZ
TM
TX
TY
TZ
BEAM
BUSH
FIELD
FRICTION
GFORCE
SFORCE
SPDP
VFORCE
VTORQ
ARYVAL
DIF
DIF1
PINVAL
Arithmetic IF
IF
AO
Interpolation functions
AKISPL
CUBSPL
CURVE
INTERP
BISTOP
CHEBY
DELAY
FORCOS
FORSIN
HAVSIN
IMPACT
FXFREQ
FXMODE
Vector measures
ACCXYZ
DXYZ
FXYZ
TXYZ
UVX
Vector functions
UV
MAG
TRANS
MOTION
PTCV
POUVAL
SENVAL
VARVAL
INVPSD
POLY
SHF
STEP
STEP5
SWEEP
UVY
UVZ
VXYZ
WXYZ
WDTXYZ
ABS 3
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.
4 Adams/Solver
C++ Functions
ACCM
The ACCM function calculates the magnitude of the second time derivative of the displacement vector
of marker i from marker j. The time derivatives are taken in the reference frame of marker l. Markers j
and l default to the global coordinate system and the global reference frame if they are not specified.
Format
ACCM(i[,j][,l])
Arguments
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.
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).
Extended Definition
ACCM ( i ,j ,l ) =
where
(l)
d
Ri
dt2
dt
d
Rj
d t2
(l)
d
Ri
dt2
(l)
d
Rj
d t2
(l)
(B) d
dt
p:
Examples
REQUEST/10, F2=ACCM(21,11)
This statement defines the second component of a user-defined request as the magnitude of translational
acceleration of Marker 21 with respect to Marker 11. Since the l marker is not specified, the derivatives
are taken in the inertial reference frame.
REQUEST/10, F2=ACCM(21,11)
This statement defines the second component of a user-defined request as the magnitude of the
translational acceleration of Marker 21 with respect to Marker 11. Vector time derivatives taken in
reference to Marker 32.
ACCM 5
C++ Functions
6 Adams/Solver
C++ Functions
ACCX
The ACCX function returns the x-component of the difference between the acceleration vector of marker
i and the acceleration vector of marker j as computed in the coordinate system of marker k. All vector
time derivatives are taken in the reference frame of marker l. Marker j defaults to the global coordinate
system if it is not specified. Similarly, markers k and l default to the global coordinate system and the
global reference frame if they are not specified.
Format
ACCX(i[,j][,k][,l])
Arguments
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.
The marker in whose coordinate system the acceleration vector is being expressed. Set k = 0,
while still specifying l, if you want the results to be calculated along the x-axis of the global
coordinate system.
The reference frame in which the second time derivative of the displacement vector is taken.
Set l = 0 or omit the argument if you want the time derivatives to be taken in the ground
coordinate system (GCS).
Extended Definition
ACCX ( i ,j ,k ,l ) =
where
(l)
d
Ri
dt2
(l)
Rj xk
2
dt
This statement defines a user-specified differential equation. The time derivative of the state is specified
to be the x-component of the acceleration of Marker 21 with respect to Marker 11. The coordinate system
for calculating the component, and for referencing the frame that takes time derivatives, defaults to
ground.
DIFF/2, IC=1, FUNCTION=ACCX(21,0,31)
ACCX 7
C++ Functions
This statement defines a user-specified differential equation. The time derivative of the state is specified
to be the x-component 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.
8 Adams/Solver
C++ Functions
ACCXYZ
The ACCXYZ measure returns the difference between the acceleration vector of marker i and the
acceleration vector of marker j resolved in the coordinate system of marker k. All vector time derivatives
are taken in the reference frame of marker l.
Format
ACCXYZ(i[,j][,k][,l])
Arguments
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.
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.
The reference frame in which the second time derivative of the displacement vector is taken. Set
l = 0 or omit the argument if you want the time derivative to be taken in the global reference
frame.
Extended Definition
ACCXYZ ( i ,j ,k ,l ) =
2
d
R
j xk
dt2
ACCX
(l) 2
(l) 2
d
d
= ACCY
Ri
Rj yk
dt2
dt2
ACCZ
(l) 2
(l) 2
d
d
Ri
Rj zk
2
2
dt
dt
(l)
d
Ri
dt2
(l)
where:
ACCXYZ 9
C++ Functions
(l)
d
denotes two time differentiations in the reference frame of the l marker.
dt2
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))
10 Adams/Solver
C++ Functions
ACCY
The ACCY function returns the y-component of the difference between the acceleration vector of marker
i and the acceleration vector of marker j as computed in the coordinate system of marker k. All vector
time derivatives are taken in the reference frame of marker l. Marker j defaults to the global coordinate
system if it is not specified. Similarly, markers k and l default to the global coordinate system and the
global reference frame if they are not specified.
Format
ACCY(i[,j][,k][,l])
Arguments
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.
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 y-axis of the global
coordinate system.
The reference frame in which the second time derivative of the displacement vector is taken. Set
l = 0 or omit the argument if you want the time derivatives to be taken in the ground coordinate
system (GCS).
Extended Definition
ACCY ( i ,j ,k ,l ) =
where
(l)
d
Ri
dt2
(l)
Rj yk
2
dt
This statement defines a user-specified differential equation. The time derivative of the state is specified
to be the x-component of the acceleration of Marker 21 with respect to Marker 11. The coordinate system
for calculating the component, and for referencing the frame that takes time derivatives, defaults to
ground.
DIFF/2, IC=1, FUNCTION=ACCX(21,0,31)
ACCY 11
C++ Functions
This statement defines a user-specified differential equation. The time derivative of the state is specified
to be the x-component 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.
12 Adams/Solver
C++ Functions
ACCZ
The ACCZ function returns the z-component of the difference between the acceleration vector of marker
i and the acceleration vector of marker j as computed in the coordinate system of marker k. All vector
time derivatives are taken in the reference frame of marker l. Marker j defaults to the global coordinate
system if it is not specified. Similarly, markers k and l default to the global coordinate system and the
global reference frame if they are not specified.
Format
ACCZ(i[,j][,k][,l])
Arguments
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.
The marker in whose coordinate system the acceleration vector is being expressed. Set k = 0 if
you want the results to be calculated along the z-axis of the global coordinate system.
The reference frame in which the second-time derivative of the displacement vector is taken.
Set l = 0, or omit the argument, if you want the time derivatives to be taken in the ground
coordinate system (GCS).
Extended Definition
ACCZ ( i ,j ,k ,l ) =
where
(l)
d
Ri
dt2
(l)
Rj zk
2
dt
This statement defines a user-specified differential equation. The time derivative of the state is specified
to be the x-component of the acceleration of Marker 21 with respect to Marker 11. The coordinate system
for calculating the component, and for referencing the frame that takes time derivatives, defaults to
ground.
DIFF/2, IC=1, FUNCTION=ACCX(21,0,31
ACCZ 13
C++ Functions
This statement defines a user-specified differential equation. The time derivative of the state is specified
to be the x-component 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.
14 Adams/Solver
C++ Functions
ACOS
The ACOS function calculates the arc cosine of an expression a. Expression a must evaluate to a value
whose absolute value is less than or equal to 1. The value returned by ACOS lies in the range [0, ] (i.e.,
0 < ACOS(a) <
).
Format
ACOS(a)
Arguments
Examples
VARIABLE/1, FU=ACOS((DX(21,11)*DX(31,41)+DY(21,11)*DY(31,41)
+ DZ(21,11)*DZ(31,41))/(DM(21,11)*DM(31,41))
This statement specifies a new user-defined state variable. Its value is the included angle of the lines
joining Markers 11 and 21 and Markers 41 and 31. The result is in radians.
See other FORTRAN 77 intrinsic functions available.
AINT 15
C++ Functions
AINT
The AINT function returns the nearest integer whose magnitude is not larger than the integer value of the
expression a.
AINT(a)= 0 if ABS(a)< 1
AINT(a)=int(a) if ABS(a) > 1
The value of the mathematical function int of a variable x is equal to x if x is an integer. If x is not an
integer, then int(x) is equal to the nearest integer to x whose magnitude is not greater than the magnitude
of x. Thus:
int(-7.0) = -7, int(-4.8) = -4, and int(4.8) = 4.
Format
AINT(a)
Arguments
Caution:
Note that AINT is not a differentiable function. Be careful when using this function in an
expression that defines a force or motion input to the system.
Examples
AINT(-6.5) = -6
AINT(4.6 ) = 4
16 Adams/Solver
C++ Functions
AKISPL
The AKISPL function returns the iord derivative of the interpolated value of SPLINE/id at X=x and Z=z.
Format
A real variable that specifies the independent variable value along the x-axis of the AKISPL.
A real variable that specifies the second independent variable value along the z-axis of the
surface being interpolated. Specify z = 0 if the SPLINE statement defines only one curve.
id
An integer variable that specifies the identifier of a SPLINE statement that you define in the
Adams/Solver dataset.
iord
An integer variable that specifies the order of the derivative to be taken at the interpolated
point. iord may not be specified when interpolating on a surface (for example, when z = 0).
Default: 0
Range: 0 < iord < 2
Extended Definition
The AKISPL function uses the Akima method of interpolation to create a spline function across a set of
data points. The data points to be interpolated are defined by a SPLINE statement in the Adams/Solver
dataset. The SPLINE that you define in the dataset may represent a curve (x-y points) or a surface (x-yz 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.
AKISPL 17
C++ Functions
For more information on the Akima method of interpolation, see the references listed in Additional
Publications.
Tip:
If you want to force a particular region of a spline function to be linear, you should know
that four consecutive points on a straight line will yield a linear section in the region
between the central two points, and, similarly, four consecutive points on a straight line at
the end of a spline will yield a linear fit from the second point onward.
Examples
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.
18 Adams/Solver
C++ Functions
ANINT
The ANINT function calculates the nearest integer to a.
ANINT(a) = int(a + .5) if a > 0
ANINT(a) = int(a - .5) if a < 0
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
AO 19
C++ Functions
AO
The AO (Action Only) function isolates certain portions of a scalar expression from a reaction force when
the expression appears in the context of a general constraint (GCON). The AO function has no effect in
expressions that are not constraint expressions.
Format
AO(exp)
Arguments
exp
Extended Definition
To understand the purpose of the AO function, it is best to examine Lagrange's equations for a
constrained system:
d L L
+ T Cq = 0 T
d t q q
C ( q ,t ) = 0
where L is the system Lagrangian, q are the generalized coordinates, C are the constraints, and
Lagrange multipliers.
are the
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
20 Adams/Solver
C++ Functions
Note:
Excessive use of AO may lead to systems which are impossible to solve. For example, the
following constraints:
GCON/1, FUN=AO(DX(1,2))
GCON/2, FUN=AO(DY(1,2))
GCON/3, FUN=AO(DZ(1,2))
instruct Adams/Solver (C++) to keep markers 1 and 2 coincident, but render it powerless
to do so. Because a constraint force will not be applied to either marker, the constraint is
unlikely to be satisfied and a convergence failure will occur.
ARYVAL 21
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
id
comp
Examples
ARRAY/17, NUM=11.465,2.321
SFORCE/19, ROT, I=23, J=11
, FUNCTION=-ARYVAL(17,1)*(AZ(23,11)-ARYVAL(17,2))
This example illustrates how a value defined in an ARRAY statement can be accessed using the
ARYVAL function.
LSE/1, X=1, U=2, Y=3, A=11, B=12, C=13, D=14
This statement defines a set of linear state equations. The A, B, C, and D matrices for this LSE are defined
by matrices 11-14.
SFORCE/6, ROT, I=23, J=11, FUNCTION=ARYVAL(3,2)
The second output of the LSE is used to define a torque acting on the system.
See other System element measures available.
22 Adams/Solver
C++ Functions
ASIN
The ASIN function computes the arc sine of an expression a. ASIN is defined only when the absolute
value of a is less than or equal to 1. The range of ASIN is [- /2, /2] (that is, - /2 < ASIN(a) <
/2).
Format
ASIN(a)
Arguments
Examples
DIFF/1, IC=1.05, FUNCTION=ASIN(DX(21,11)/DM(21,11))
This statement defines a user-specified differential equation. The initial value of the state variable is 1.05.
The time derivative of the state variable is the expression:
ASIN(DX(21,11)/DM(21,11))
ATAN 23
C++ Functions
ATAN
The ATAN function returns the arc tangent of an expression a. The range of ATAN is [- /2,
is, - /2 < ATAN(a)<
/2] (that
/2).
Format
ATAN(a)
Arguments
Examples
SFORCE/1, ROTATIONAL, I=21, J=11
, FUNCTION=-10*ATAN(DY(42,33)/DX(42,33))
This SFORCE statement defines a torque acting between Markers 21 and 11. The value of the torque is
the spring constant (10) multiplied by the angle between the line joining Markers 33 and 42 and the global
x-axis as shown in the figure below.
Example Illustrating the Use of the ATAN Function
24 Adams/Solver
C++ Functions
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
a1
a2
Examples
VARIABLE/1,
, FUNCTION=ATAN2(DY(21,31,41), DX(21,31,41))
AX 25
C++ Functions
AX
The AX function returns the rotational displacement of marker i about the x-axis of marker j, and
accounts for angle wrapping.
Marker j defaults to the global coordinate system if it is not specified. This value is computed as follows:
assume that rotations about the other two axes (y- and z-axes) of marker j are zero. Then, AX is the angle
between the two y-axes (or the two z-axes). AX is measured in a counter-clockwise sense from the y-axis
of marker J to the y-axis of marker I (see the figure below).
Measurement of AX
Format
AX(i[,j])
Arguments
The marker whose coordinate system is used as a reference to calculate the rotations of marker
i. When j is not specified, Adams/Solver (C++) defaults to the global coordinate system.
Extended Definition
AX = ATAN2 ( z i y j, z i z j )
where:
26 Adams/Solver
C++ Functions
Tip:
If you want to change the AX function so it does not account for angle wrapping, use the
MOD function. For example, use the function:
(MOD(AX(2,1) + PI, 2 * PI) - PI
The MOD function achieves the cyclic effect and the +PI and -PI shift the curve
accordingly.
Caution:
For large rotations (greater than 10 degrees) about the y-axis or z-axis on Marker j, the AX
function becomes increasingly non-physical. Moreover, AX is undefined when both
arguments to ATAN2 are zero. This occurs when the z-axis of marker i is orthogonal to the
plane defined by the y and z-axis of the j marker.
Examples
GFORCE/1, I=21, JFLOAT=31, RM=41
, FX=-20*AX(43,32)
This GFORCE statement applies a force at the origin of Marker 21 along the x-axis of Marker 41. The
reaction force is on floating Marker 31. The floating Marker 31 can belong to another part but its location
is always the same as Marker 21.
The value of the force is -20 times the angle between the y axes of Markers 43 and 32. The angle is
measured in a counterclockwise sense from the y-axis of Marker 32 to the y-axis of Marker 43.
See other Displacement measures available.
AY 27
C++ Functions
AY
The AY function returns the rotational displacement of marker i about the y-axis of marker j, and
accounts for angle wrapping.
Marker j defaults to the global coordinate system if it is not specified. The values are computed as
follows: assume rotations about the other two axes (x-, z-axes) of marker j are zero. Then AY is the angle
between the two x-axes (or the two z-axes). AY is measured counter-clockwise from the z-axis of the J
marker to the z-axis of the I marker (see the figure below).
Measurement of AY
Format
AY(i[,j])
Arguments
The marker with respect to which the rotations are being measured.
Extended Defintion
AY = ATAN2 ( z i x j, z i z j )
where:
28 Adams/Solver
C++ Functions
Tip:
If you want to change the AY function so it does not account for angle wrapping, use the
MOD function. For example, use the function:
(MOD(AY(2,1)+PI,2*PI)-PI)
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 x-axis or z-axis of marker j, the AY
function becomes increasingly non-physical. Moreover, AY is undefined when both
arguments to ATAN2 are zero. This occurs when the z-axis of marker i is orthogonal to the
plane defined by the x and z-axis of the j marker.
Examples
SFORCE/10, ROTATION, I=23, J=34
, FUNCTION=-4*(AY(46,57)**2)
This SFORCE statement applies a moment about the common z-axes of Markers 23 and 34. The torque
acts on Marker 23; the reaction torque acts on Marker 34.
The value of the torque being applied is -4 times the square of the angle between the z axes of Markers
46 and 57. The angle is measured in a counterclockwise sense from the z-axis of Marker 57 to the z-axis
of Marker 46.
See other Displacement measures available.
AZ 29
C++ Functions
AZ
The AZ function returns the rotational displacement of marker i about the z-axis of marker j, and accounts
for angle wrapping.
Marker j defaults to the global coordinate system if it is not specified. This value is computed as follows:
assume that rotations about the other two axes (x-, y-axes) of marker j are zero. Then AZ is the angle
between the two x-axes (or the two y-axes). AZ is measured in a counter- clockwise sense from the xaxis of the J marker to the x-axis of the I marker (see the figure below).
Measurement of AZ
Format
AZ(i [,j ])
Arguments
The marker with respect to which the rotations are being measured.
Extended Definition
AZ = ATAN2 ( x i y j, x i x j )
where:
30 Adams/Solver
C++ Functions
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 x-axis or y-axis of marker j, the AZ
function becomes increasingly non-physical. Moreover, AZ is undefined when both
arguments to ATAN2 are zero. This occurs when the x-axis of marker i is orthogonal to the
plane defined by the x and y-axis of the j marker.
Examples
VTORQUE/1, I=21, JFLOAT=31, RM=41
, TX=-10*(AX(21,32)-10D)/
, TY=-15*(AY(21,32)-15D)/
, TZ=-30*(AZ(21,32)-25D)
This VTORQUE statement applies a moment at Marker 21. The reaction moment is at the floating
Marker 31. The torques are expressed in the coordinate system of Marker 41.
See other Displacement measures available.
BEAM 31
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
id
jflag
An integer flag specifying the beam connectivity marker at which the forces and torques are
computed.
0 = forces and moments at the I marker
1 = forces and moment at the J marker
comp
An integer value that specifies the component of the beam force to be returned.
1 = Magnitude of the force
2 = x component of the force
3 = y component of the force
4 = z component of the force
5 = Magnitude of the torque
6 = x component of the torque
7 = y component of the torque
8 = z component of the torque
rm
The coordinate system in which the results are expressed. To return the results in the global
coordinate system, set rm = 0.
Examples
REQUEST/1
, F2=BEAM(1001,0,2,0)/
, F3=BEAM(1001,0,3,0)/
, F4=BEAM(1001,0,4,0)
This REQUEST statement stores the x-, y-, and z-component of the forces in BEAM/1001 in columns 2,
3, and 4, respectively. The forces are calculated at the I marker. The results are computed in the global
coordinate system.
See other Element-specific applied force measures available.
32 Adams/Solver
C++ Functions
BISTOP
The BISTOP function models a gap element (see Figure 1).
Format
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).
x1
The lower bound of x. If x is less than x1 Adams/Solver (C++) calculates a positive value for
the force. The value of x1 must be less than the value of x2.
x2
The upper bound of x. If x is greater than x2 Adams/Solver (C++) calculates a negative value
for the force. The value of x2 must be greater than the value of x1.
A non-negative value that specifies the stiffness of the boundary surface interaction.
A positive value that specifies the exponent of the force deformation characteristic. For a
stiffening spring characteristic, e > 1.0. For a softening spring characteristic, 0 < e < 1.0.
cmax
A positive real variable that specifies the penetration at which the full damping coefficient is
applied.
Extended Definition
The BISTOP function models a gap element. Figure 1 below illustrates the BISTOP force. The gap
element consists of a slot which defines the domain of motion of a Part I located in the slot. As long as
Part I is inside the slot and has no interference with the ends of the slot, it is free to move without forces
acting on it. When Part I tries to move beyond the physical definition of the slot, impact forces
representing contact are created by the BISTOP function. The created force tends to move Part I back
into the slot.
The BISTOP force has two components: A stiffness component dependent on the penetration of Part I
into the restricting Part J and a damping or viscous component that may be used to model energy loss.
BISTOP 33
C++ Functions
Figure 1
To prevent a discontinuity in the damping force at zero penetration, the damping coefficient is defined as
a cubic step function of the penetration. Thus at zero penetration, the damping coefficient is always zero.
The damping coefficient achieves a maximum, cmax, at a user-defined penetration, d. Even though the
points of contact between the floating part and the restricting part may change as the system moves,
Adams/Solver (C++) always exerts the force between the I and the J markers.
Figure 2
Caution:
When e is < 1, the defined force contains a slope discontinuity that may casue difficulty for
the integrator.
Examples
You may model a slider in a slot with a BISTOP function as depicted in Figure 1. Assume a translational
joint constrains the slider to move in a slot. The line of translation is along the colinear z-axes of the I
and the J markers, I belonging to the slider and J to the part containing the slot. You can use an SFORCE
statement together with the BISTOP function to restrict the movement of the slider in the slot and model
the gap.
34 Adams/Solver
C++ Functions
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
- x).
x > x2 penetration occurs at the end farther away from the J marker, and the force is < 0
(penetration p = x - x2).
Also note that when p < d the instantaneous damping coefficient is a cubic step function of the
penetration, p; when p > d the instantaneous damping coefficient is cmax.
The BISTOP function for this example is:
BISTOP(DZ(I,J,J,J), VZ(I,J,J,J), x1, x2, k, e, cmax, d)
The values of k, e, cmax, and d depend on the materials used in the two parts and on the shapes of the parts
and are used to define the contact force.
: x1 x x2
BISTOP = 0
x > x2
Min ( k ( x x 2 ) e STEP ( x, x 2, 0, x 2 + d, c max ) x', 0 ):
BUSH 35
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
id
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.
Examples
REQUEST/1
, F2=BUSH(1001,0,2,0)/
, F3=BUSH(1001,0,3,0)/
, F4=BUSH(1001,0,4,0)
This REQUEST statement stores the x-, y-, and z-component of the forces in BUSH/1001 in columns 2,
3, and 4, respectively. The forces are calculated at the I marker. The results are computed in the global
coordinate system.
See other Element-specific applied force measures available.
36 Adams/Solver
C++ Functions
CHEBY
The CHEBY function evaluates a Chebyshev polynomial at a user specified value x.
Format
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
Extended Definition
The CHEBY function evaluates a Chebyshev polynomial at a user specified value x. x0, a0, a1,..., a30
are parameters used to define the constants for the Chebyshev polynomial. The Chebyshev polynomial
is defined as:
C(x) =
aj Tj (x-x0)
where the functions Tj are recursively defined as:
Tj (x-x0) = 2 * (x-x0) * Tj-1 (x-x0) - Tj-2 (x-x0)
with T0 (x-x0) = 1, and T1 (x-x0) =x-x0.
The index j has a range from zero to n, where n is the number of terms in the series.
Note the following:
T2 (x-x0) = 2 * (x-x0)2 - 1
T3 (x-x0) = 4 * (x-x0)3 - 3 * (x-x0)
Examples
MOTION/1, JOINT=21, TRANSLATION,
,FUNCTION = IF (TIME-2:CHEBY(TIME, 1, 1, 0, -1), 0, 0)
This MOTION statement defines a motion using a quadratic Chebyshev polynomial and the system
variable TIME. The arithmetic IF ensures that the function remains zero after 2 time units. When time is
less than 2 time units, Adams/Solver (C++) evaluates a Chebyshev polynomial to determine the motion.
The polynomial defined in the above example is:
Cheby = 1 + 0 * (time-1) - 1 * [2 (time-1)2 - 1]= -2*time2 +4*time
CONTACT 37
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
id
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
rm
The coordinate system in which the results are expressed. To return the results in the global
coordinate system, set rm = 0.
Examples
REQUEST/1
, F2= CONTACT(11,0,2,0)/
, F3= CONTACT(11,0,3,0)/
, F4= CONTACT(11,0,4,0)/
, F6= CONTACT(11,0,6,0)/
, F7= CONTACT(11,0,7,0)/
, F8= CONTACT(11,0,8,0)
This REQUEST statement outputs the x-, y- and z-components of the force and torque at the I marker of
CONTACT/11. Because rm is specified as zero, all vectors are expressed in the global coordinate system.
38 Adams/Solver
C++ Functions
COS
The COS function returns the cosine of an expression a.
Format
COS(a)
Arguments
Examples
MOTION/2060, JOINT=2060, ROTATION,
, FUNCTION=20D+COS(2*PI*TIME)
This MOTION statement defines a rotational motion acting on JOINT/2060. The rotational degree of
freedom is specified to be 20D+COS(2*PI*TIME).
See other FORTRAN 77 intrinsic functions available.
COSH 39
C++ Functions
COSH
The COSH function computes the hyperbolic cosine of an expression a.COSH(a) = (ea + e-a) / 2.0
Format
COSH(a)
Arguments
Examples
REQUEST/36,
, F2=COSH(DZ(21,11,11))
This REQUEST statement returns the hyperbolic cosine of the z-component of the displacement of
Marker 21 with respect to Marker 11 in its second column. The result is computed in the coordinate
system of Marker 11.
See other FORTRAN 77 intrinsic functions available.
40 Adams/Solver
C++ Functions
CPU
Number of seconds of CPU time used during an Adams run.
Format
CPU
Example
SENSOR/1
, VALUE=100
, GE
, HALT
, FUN=CPU
In the example above, the sensor stops a simulation if it is taking longer than 100 seconds.
See other Simulation parameters and constants available.
CUBSPL 41
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
A real variable that specifies the independent variable value along the x-axis of the CUBSPL.
A real variable that specifies the second independent variable value along the z-axis of the
surface being interpolated. If the SPLINE statement defines only one curve, Adams/Solver
(C++) ignores this variable.
id
iord
An optional integer that specifies the order of the derivative at the interpolate value to be
returned by CUBSPL.
Range: 0 < iord < 2
Extended Definition
The CUBSPL function uses the standard cubic method of interpolation to create a spline function across
a set of data points. The data points are defined in the SPLINE statement in Adams/Solver (C++) data
deck. The SPLINE that you define in the Adams/Solver dataset may represent a curve (x-y points) or a
surface (x-y-z points). Interpolation in the y direction is cubic and interpolation in the z direction is linear.
To interpolate the values specified in a curve, set z = 0.
iord specifies the order of the derivative and may be used only when interpolating a curve (that is, when
z = 0.
CUBSPL, though not as fast as AKISPL, always produces good results for the value of the function being
approximated, its first and second derivatives. There is no requirement on the data points being evenly
spaced. This may be an important consideration when you use splines to define functions in
Adams/Solver (C++). The solution process often requires estimates of derivatives of the functions being
defined. The smoother a derivative is, the easier it is for the solution process to converge.
If the spline data contains sudden changes in value, the CUBSPL function gives more oscillatory results
for the curve or surface than are given by the AKISPL function.
For more information on the cubic method of interpolation, see the references listed in Additional
Publications.
42 Adams/Solver
C++ Functions
Examples
SPLINE/1,
, X= -3, -2, -1, 0, 1, 2, 3
, Y= -67.4, -48.6, -33.7, 4.8, 24.12, 37.6, 48.4
SFORCE/1, I=409, J=109, TRANSLATION,
, FUNCTION=CUBSPL(TIME, 0, 1)
This SFORCE statement defines the translational force acting between Markers 409 and 109. The
SPLINE statement provides the discrete data used to generate the interpolation function using the cubic
spline. Since the SPLINE statement defines only one curve, the value of z is defined to be 0.
See other Interpolation functions available.
CURVE 43
C++ Functions
CURVE
The CURVE function evaluates a B-spline or user-written curve that is created with the CURVE
statement.
Format
alpha
A real variable that identifies the value of the independent parameter, , at which the
CURVE function evaluates the curve. If the curve is a B-spline computed by the CURVE
statement, alpha must be in the domain -1 < < 1. If the curve is computed by a CURSUB,
alpha must be in the domain MINPAR < < MAXPAR (these are specified in the CURVE
statement).
iord
An integer variable that specifies the order of the derivative the CURVE function returns.
The legal values are:
0 - returns the curve coordinate
1 - returns the first derivative
2 - return the second derivative
comp
An integer variable that specifies the component that the CURVE function returns. The legal
values are:
1 - returns the x coordinate or derivative
2 - returns the y coordinate or derivative
3 - returns the z coordinate or derivative
Parameters iord and icomp together allow you to request any one of the following nine
return values:
iord
0
1
2
id
2y( )
d---------------d 2
d 2 z ( )---------------d 2
Examples
VFORCE/1, I=101, JFLOAT=201, RM=99,
, FX=CURVE(.4*TIME - 1, 0, 1, 8)/
44 Adams/Solver
C++ Functions
, 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*TIME-1 computes
the instantaneous value of alpha from the simulation time.
See other Interpolation functions available.
CVCV 45
C++ Functions
CVCV
The CVCV function returns component comp of a force or torque due to CVCV/id as calculated in the
coordinate system of marker rm. If jflag is set to zero, the value returned is the force/torque acting on the
IFLOAT marker of the CVCV. If jflag is set to one, the value returned is that acting on the JFLOAT
marker. rm may be specified as zero if the results are desired in the global coordinate system
Format
CVCV (id,jflag,comp,rm)
Arguments
id
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
Examples
REQUEST/18,
, F2=CVCV(210,0,2,0)/
, F3=CVCV(210,0,3,0)/
, F4=CVCV(210,0,4,0)/
, F6=CVCV(210,0,6,0)/
, F7=CVCV(210,0,7,0)/
, F8=CVCV(210,0,8,0)
This REQUEST statement returns all three components of the forces and moments acting at the IFLOAT
marker of CVCV Joint 210.
See other Element-specific reaction force measures available.
46 Adams/Solver
C++ Functions
DELAY
The DELAY function returns the value of an expression at a delayed time.
The DELAY function is useful to define Delay Differential Equations (DDE) or Delay DifferentialAlgebraic Equations (DDAE) of the retarded type (when delays are positive). Neither DDE nor DDAE
of the advance type (negative delays) are supported.
The DELAY function can be used in MOTION and GCON definitions (possibly involving neutral type
of DDE or DDAE).
During linearization the DELAY function is approximated by a first order polynomial equivalent to an
order 1 Pad approximant.
The user does not require to specify a buffer size. Adams/Solver (C++) will manage a variable-size buffer
automatically.
Format
e_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 delayed expression can have jumps and derivative discontinuities. If the signal has jumps, a jump
threshold J (see Figure below) can be specified. The default jump threshold is 0.5. If the signal has
corners, an angle corner threshold A (see Figure below) can be specified. The default angle corner
threshold is /8.
The default interpolation order is 6. In cases in which the delayed expression changes abruptly, a lower
integration order may be required. If the interpolation order is equal to 1, the corner and jump detection
are disabled.
By default the refinement parameter R is 200. The value of R controls the separation T (see Figure below)
between points used by the interpolator. Only points such that
t tl > / R
DELAY 47
C++ Functions
are stored in the history of the expression. In the above expression, t is the current time, tl is the last point
in the stored history, and is the current value of the delay. The bigger the value of R, the more
integration points are stored in the history of the delayed expression. The value /R can be seen as a
lower bound for the separation between points in the delayed expression history. For delays smaller than
the current integration step, R is ignored and all integration points are recorded.
Examples
1. A simple DDE system.
The equations below define a typical DDE system with a state-dependent delay expression:
x1 ( t ) = 5 x2 ( t )
x2 ( t ) = 3 x1 ( t )x2 ( t )
= x1 3 x2 > 0
x2 ( t ) = 0.95
(t < 0 )
The expression to delay (e_delayed) is x2, the delay expression (e_delay) is , and the history
(e_history) is the constant expression 0.95.
This system could be modeled in Adams as follows:
DIF/1,
DIF/2,
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)
mx + kx ( t ) + cx = 0
48 Adams/Solver
C++ Functions
DELAY 49
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 !
,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)
50 Adams/Solver
C++ Functions
!
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
DELAY 51
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
Caution:
The DELAY function uses an internal buffer, that holds the history of the expression 'edelayed'. 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.
52 Adams/Solver
C++ Functions
DIF
The DIF function returns the value of the state associated with DIFF/id.
Format
DIF(id)
Arguments
id
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.
DIF1 53
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
id
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.
54 Adams/Solver
C++ Functions
DIM
The DIM function calculates the positive difference of the instantaneous values of two expressions a1
and a2.
DIM(a1,a2) = 0 if a1 < a2
DIM(a1,a2) =a1-a2 if a1 > a2
Caution:
Format
DIM(a1,a2)
Arguments
a1
a2
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)
DM 55
C++ Functions
DM
The DM function returns the magnitude of the translational displacement vector from marker j to marker
i. Marker j defaults to the global coordinate system if it is not specified. DM is the distance between
markers i and j and, by definition, is always non-negative.
Format
DM(i[,j])
Arguments
The marker whose origin is the reference point for the displacement calculation.
Extended Definition
DM =
[ Ri Rj ] [ Ri Rj ]
R j is the displacement of
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.
56 Adams/Solver
C++ Functions
DTOR
The DTOR variable returns degrees to radians conversion factor (PI/180).
Format
DTOR
Examples
VARIABLE/1, FUNCTION=30*DTOR*TIME
This VARIABLE statement specifies a user-defined, algebraically-determined state variable whose value
is 30 degrees*time. The state variable is stored in radians.
See other Simulation parameters and constants available.
DX 57
C++ Functions
DX
The DX function returns the x-component of the translational displacement vector from marker j to
marker i as expressed in the marker k coordinate system. Marker j defaults to the global coordinate
system if it is not specified. Similarly, marker k defaults to ground if it is not specified.
Format
DX(i[,j][,k])
Arguments
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.
The marker that is referenced to calculate the x-component of the displacement vector. Set k =
0 if you want the results to be calculated along the x-axis of the global coordinate system.
Extended Definition
DX = [ R i R j ] x k
where:
Examples
VARIABLE/1, FUNCTION=DX(21,11,32)**2
This VARIABLE statement specifies a user-defined, algebraically-determined state variable. Its value is
the square of the x-displacement of Marker 21 with respect to Marker 11 as computed in the coordinate
system of Marker 32.
See other Displacement measures available.
58 Adams/Solver
C++ Functions
DXYZ
The DXYZ measure returns the translational displacement vector from marker j to marker i as expressed
in the coordinate system of marker k.
Format
DXYZ(i[,j][,k])
Arguments
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.
The marker in whose coordinate system the displacement vector is being expressed. If not
specified, k defaults to the global coordinate system.
Extended Definition
[ Ri Rj ] xk
DX
DXYZ = [ R i R j ] y k = DY
[ R i R j ] z k
DZ
where:
DX is theDX measure.
DY is the DY measure.
DZ is the DZ measure.
DXYZ 59
C++ Functions
Examples
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.
60 Adams/Solver
C++ Functions
DY
The DY function returns the y-component of the translational displacement vector from marker j to
marker i as expressed in the marker k coordinate system. Marker j defaults to the global coordinate
system if it is not specified. Similarly, marker k defaults to the global coordinate system if it is not
specified.
Format
DY(i[,j][,k])
Arguments
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.
The coordinates of the marker that are referenced to calculate coordinates the y-component of
the displacement vector is being calculated. Set k = 0 if you want the results to be calculated
along the y-axis of the global coordinate system.
Extended Definition
DY = [ R i R j ] y k
where:
Examples
VARIABLE/1, FUNCTION=DY(21,11,32)**2
This VARIABLE statement specifies a user-defined, algebraically-determined state variable. Its value is
the square of the y-displacement of Marker 21 with respect to Marker 11 as computed in the coordinate
system of Marker 32.
See other Displacement measures available.
DZ 61
C++ Functions
DZ
The DZ function returns the z-component of the translational displacement vector from marker j to
marker i as expressed in the marker k coordinate system. Marker j defaults to the global coordinate
system if it is not specified. Similarly marker k defaults to the global coordinate system if it is not
specified.
Format
DZ(i[,j][,k])
Arguments
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.
The marker in whose coordinates the z-component of the displacement vector is being
calculated. Set k = 0 if you want the results to be calculated along the z-axis of the global
coordinate system.
Extended Definition
DZ = [ R i R j ] z k
where:
Examples
VARIABLE/1, FUNCTION=DZ(21,11,32)**2
This VARIABLE statement specifies a user-defined, algebraically-determined state variable. Its value is
the square of the z-displacement of Marker 21 with respect to Marker 11 as computed in the coordinate
system of Marker 32.
See other Displacement measures available.
62 Adams/Solver
C++ Functions
EXP
The EXP function computes the value ea, where a is any expression.
Format
EXP(a)
Arguments
Examples
REQUEST/10, F2=EXP(WDTX(21,11,11,31))
where WDTX (21,11,11,31) is the x-component of the accelerations of Marker 21 with respect to Marker
11 as expressed in the coordinate system of Marker 11. The time derivative is taken in the reference frame
of Marker 31.
See other FORTRAN 77 intrinsic functions available.
FIELD 63
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
id
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.
Examples
REQUEST/1
, F2=FIELD(1001,0,2,0)/
, F3=FIELD(1001,0,3,0)/
, F4=FIELD(1001,0,4,0)
This REQUEST statement stores the x-, y-, and z-component of the forces in FIELD/1001 in columns 2,
3, and 4, respectively. Adams/Solver (C++) calculates the forces at the I marker, and computes results in
the global coordinate system.
See other Element-specific applied force measures available.
64 Adams/Solver
C++ Functions
FM
The FM measure returns the magnitude of the net translational force acting on marker i. All force and
constraint elements acting between markers i and j are included in the calculation of the force. If j is not
specified, FM measures the sum of all force and constraint elements acting on marker i.
Format
FM(i[,j])
Arguments
An integer that specifies the identifier of the marker at which the magnitude of the net force is
to be calculated.
A second integer that specifies a marker identifier. All forces acting between the [i,j] pair are to
be included in the calculation. Set j = 0 or do not specify if you are interested in all forces acting
on marker i.
Examples
VARIABLE/1, FUNCTION=FM(23)
A user-defined state variable is specified by this VARIABLE statement. Its value is the magnitude of the
sum of all action-only forces acting at Marker 23.
VARIABLE/1, FUNCTION=FM(23,11)
A user-defined 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.
FORCOS 65
C++ Functions
FORCOS
The FORCOS function evaluates a Fourier Cosine series at a user-specified value x. The x0, a0, a1,...,a30
are parameters used to define the constants for the Fourier Cosine series.
Format
A real variable that specifies the independent variable. For example, if the independent
variable in the function is time, x is the system variable TIME.
x0
A real variable that specifies the fundamental frequency of the series. Adams/Solver
(C++) assumes w is in radians per unit of the independent variable unless you use a D after
the value.
a0
A real variable that defines the constant bias term for the function.
a1,...,a30
The real variables that define as many as thirty-one coefficients for the Fourier Cosine
series.
Extended Definition
F ( x ) = ao +
aj + Tj ( x xo )
j=1
T j ( x x o ) = cos { j ( x x o ) }
The index j has a range from 1 to n, where n is the number of terms in the series.
Examples
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:
66 Adams/Solver
C++ Functions
FORCOS = 1+2*COS(1*360D*TIME)
+3*COS(2*360D*TIME)
+4*COS(3*360D*TIME)
FORSIN 67
C++ Functions
FORSIN
The FORSIN function evaluates a Fourier Sine series at a user specified value x. x0,a0,a1,...,a30 are
parameters used to define the constants for the Fourier Sine series.
Format
A real variable that specifies the independent variable. For example, if the independent
variable in the function is time, x is the system variable TIME.
x0
A real variable that specifies 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.
a0
A real variable that defines the constant bias term for the function.
a1,...,a30
The real variables that define as many as thirty-one coefficients for the Fourier Sine
series.
Extended Definition
F ( x ) = ao +
aj + Tj ( x xo )
j=1
T j ( x x o ) = sin { j ( x x o ) }
The index j has a range from 1 to n, where n is the number of terms in the series.
Examples
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:
68 Adams/Solver
C++ Functions
FRICTION 69
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
id
INDEX
An integer variable specifying the output component index to be returned. See the table
below for a list of component indices.
Friction Index
Index:
Name:
Description:
FFX
FFY
FFZ
FTX
FTY
FTZ
13
x
y
z
rx
ry
rz
1
14
Vx
Joint velocity at sliding surfaces along the x-axis of the JOINTs J marker
15
Vy
Joint velocity at sliding surfaces along the y-axis of the JOINTs J marker
16
Vz
17
Wx
18
Wy
19
Wz
8
9
10
11
12
70 Adams/Solver
C++ Functions
20
CREEP_X
21
CREEP_Y
22
CREEP_Z
23
CREEP_RX Static friction creep about the x-axis of the JOINTs J marker
24
CREEP_RY Static friction creep about the y-axis of the JOINTs J marker
25
CREEP_RZ Static friction creep about the z-axis of the JOINTs J marker
26
BETA
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
friction-force vector resolved in the associated J marker coordinate system of the JOINT.
Caution:
The FRICTION function is accessible only through the REQUEST and SENSOR function
expressions.
The FRICTION function evaluates to zero if the index corresponds to a force or velocity
which is not used by the corresponding friction model. For example, if FRICTION/2 from
above is applied on a translational joint, then FRICTION (2,1) would be zero because the
friction force is applied along the z axes of the joint.
FX 71
C++ Functions
FX
The FX measure returns the x-component of the net translational force acting on marker i, represented in
the coordinate system of marker k. All force and constraint elements acting between markers i and j are
included in the calculation of the force. If j is not specified, FX measures the sum of all force and
constraint elements acting on marker i. If k not specified or if k=0, the force is represented in the
GROUND coordinate system. To specify k without specifying j, use j=0.
Format
FX(i[,j][,k])
Arguments
An integer that specifies the identifier of the marker at which the magnitude of the net force is
to be calculated.
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.
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.
Examples
VARIABLE/1, FUNCTION=FX(23,0,432)
A user-defined state variable is specified by this VARIABLE statement. Its value is FX(23,0,432). This
is the x-component of the sum of all the action-only forces acting at Marker 23 as computed in the
coordinate system of Marker 32.
See other Generic force measures available.
72 Adams/Solver
C++ Functions
FXFREQ
The FXFREQ function returns the modal frequency in cycles per user-defined time for the current mode
of the current FLEX_BODY when used in function expressions defining the CRATIO argument of a
FLEX_BODY. 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(FXFREQ-100:0.01,0.1,IF(FXFREQ-1000:0.1,1.0,1.0))
For a model using units of seconds for time, this example recreates the default modal damping scheme
using nested IF function expressions.
See other Flexible body constants available.
FXMODE 73
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.
74 Adams/Solver
C++ Functions
FXYZ
The FXYZ measure returns the net translational force vector acting on marker i, represented in the
coordinate system of marker k. All force and constraint elements acting between markers i and j are
included in the calculation of the force. If j is not specified, FXYZ measures the sum of all force and
constraint elements acting on marker i. If k is not specified or if k=0, the force is represented in the
GROUND coordinate system. To specify k without specifying j, use j=0.
Format
FXYZ(i[,j][,k])
Arguments
An integer that specifies the identifier of the marker at which the magnitude of the net force is to
be calculated.
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.
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.
Extended Definition
FX
FXYZ ( i ,j ,k ) = FY
FZ
where:
FX is the FX measure.
FY is the FY measure.
FZ is the FZ measure.
Examples
FY 75
C++ Functions
FY
The FY measure returns the y-component of the net translational force acting on marker i, represented in
the coordinate system of marker k. All force and constraint elements acting between markers i and j are
included in the calculation of the force. If j is not specified, 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
An integer that specifies the identifier of the marker at which the magnitude of the net force is
to be calculated.
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.
An integer that specifies the identifier of a marker (coordinate system) in which the ycomponent of the force is to be returned. k defaults to the global coordinate system when it is
not specified.
Examples
SFORCE/1, I=132, J=234, TRANSLATION, ACTIONONLY
, FUNCTION=-0.3*FY(677,866)
This SFORCE statement defines a translation, action-only force acting at Marker 132. The force is
directed along the z-axis of Marker 234. The value of the force is -0.3 times the y-component of the net
force along the global y-axis, acting at Marker 677. All forces acting between Markers 677 and 866 are
included in this calculation.
See other Generic force measures available.
76 Adams/Solver
C++ Functions
FZ
The FZ measure returns the z-component of the net translational force acting on marker i, represented in
the coordinate system of marker k. All force and constraint elements acting between markers i and j are
included in the calculation of the force. If j is not specified, 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
An integer that specifies the identifier of the marker at which the magnitude of the net force is to
be calculated.
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.
An integer that specifies the identifier of a marker (coordinate system) in which the z-component
of the force is to be returned. k defaults to the global coordinate system when it is not specified.
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, action-only, nonlinear force. The force is directed along
the z-axis of Marker 11. The value of the force is a 5th order step function (see STEP5). The independent
variable for the STEP5 function is FZ(34), the net force acting along the global z-axis at Marker 34. Since
no j marker is specified, only action-only forces acting at Marker 34 are included in the calculation of
FZ().
See other Generic force measures available.
GFORCE 77
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
id
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
rm
The coordinate system in which the results are expressed. To return the results in the global
coordinate system, set rm = 0.
Examples
GFORCE/1, I=516, J=34, RM=23
, FX=-0.3*GFORCE(1,0,4,23)/
, FY=0/
, FZ=IMPACT(DZ(516,0,23),VZ(516,0,23,23),4.6,1e5,1.5,10,0.01)
This GFORCE statement defines a force acting at Marker 516. The components of the force are defined
along the x-, y-, z-axes of Marker 23.
The x-component of the force is -0.3 times the z-component of the force.
The z-component of the force is defined as an impact force (see IMPACT ) that is a function of the
displacement and velocity of Marker 516, as seen by Marker 23.
78 Adams/Solver
C++ Functions
HAVSIN 79
C++ Functions
HAVSIN
The HAVSIN function defines a haversine function. It is used most often to represent a smooth transition
between two functions.
Format
x0
A real variable that specifies the x value at which the haversine function begins.
x1
A real variable that specifies the x value at which the haversine function ends.
h0
h1
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
80 Adams/Solver
C++ Functions
h0
BISTOP = a + b sin ( c 2 )
h1
Tip:
: ( x x0 )
: xo < x < x1
:x x 1
The HAVSIN function behavior is similar to the STEP function. It has a discontinuous
second derivative and, therefore, is not recommended for use in displacement level
motions.
Examples
MOTION/1, JOINT=21, VELOCITY
, FUNCTION=HAVSIN(TIME, 1, 0, 2, 1)
This MOTION statement defines a smooth transition in velocity from time 1 to time 2. Note that the
motion is specified in velocity rather than displacement.
See other Miscellaneous Adams intrinsic functions available.
HSIZE 81
C++ Functions
HSIZE
The instantaneous simulation step size being used for any simulation that advances time (for example,
dynamic, kinematic and quasistatic analyses).
Example
SENSOR/1
, VALUE=1e-4
, ERR=1e-5
, LE
, HALT
, FUN=HSIZE+1*STEP(TIME,0.799,1,0.8,0)
In above example, the sensor halts the simulation if the step size is smaller than 1e-4. Note that a STEP
function is used to delay the sensor to avoid the start-up condition of a step size-0.0, and to accommodate
HMIN and allow the integrator to start.
See other Simulation parameters and constants available.
82 Adams/Solver
C++ Functions
IF
The arithmetic IF function allows you to conditionally define a function expression.
IF (expression 1: expression 2, expression 3, expression 4)
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.
Examples
SFORCE/1, I=20, J=31,
, FUNCTION=-6*IF(VR(10,31): 0, 0, VR(10,31)**3)
IF 83
C++ Functions
of SFORCE/1 is zero.
If the radial velocity between Markers 10 and 31 is greater than zero, the value of SFORCE/1 is
-6*VR(10,31)**3.
84 Adams/Solver
C++ Functions
IMPACT
The IMPACT function models collisions.
Format
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 x is VX(0201,0301,0,0301).
x1
Positive real variable that specifies the free length of x. If x is less than x1, then
Adams/Solver (C++) calculates a positive value for the force. Otherwise, the force value is
zero. You can define x1as a real number, function, or variable.
Non-negative real variable that specifies the stiffness of the boundary surface interaction.
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.
cmax
Positive real variable that specifies the boundary penetration at which Adams/Solver (C++)
applies full damping.
Extended Definition
The IMPACT function activates when the distance between the I and J markers falls below a nominal
free length (x1), that is, when two parts collide. As long as the distance between the I and J markers is
greater than x1; the force is zero. An example of a system you can model with the IMPACT function is a
ball falling towards the ground. Figure 3 below shows the free length value x1at which the IMPACT force
turns on.
The force has two components, a spring or stiffness component, and a damping or viscous component.
The stiffness component is proportional to k, and is a function of the penetration of the I marker within
the free-length distance from the J marker. The stiffness component opposes the penetration. The
damping component of the force is a function of the speed of penetration. The damping opposes the
direction of relative motion. To prevent a discontinuity in the damping force at contact, the damping
coefficient is, by definition, a cubic step function of the penetration. Thus, at zero penetration, the
damping coefficient is always zero. The damping coefficient achieves a maximum, cmax, at a userdefined penetration, d.
IMPACT 85
C++ Functions
Figure 3
: x < x1
: x x 1
x1 - x)
Also note that when p < d, the instantaneous damping coefficient is a cubic step function of the
penetration, p.
When p > d, the instantaneous damping coefficient is cmax.
Adams/Solver (C++) never returns a negative force for IMPACT. If the above expression is negative,
Adams/Solver (C++) returns a value of zero.
Figure 4 below is a plot of damping coefficient versus penetration.
86 Adams/Solver
C++ Functions
Figure 4
Tip:
Caution:
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.
For maximum performance, define e >1. When e is <1, the defined force contains
F n = k* (g**e)
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.
IMPACT 87
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 single-component force at Marker 11 and along the z-axis of Marker 21. DZ(11,21,21) defines the
instantaneous displacement of Marker 11 with respect to Marker 21 along the z-axis of Marker 21.
VZ(11,21,21,21) defines the instantaneous velocity.
The free length is 1; that is, the radius of the ball is 1 unit. The stiffness is 100, the exponent of
deformation is 1.5, and the maximum damping coefficient is 25. The penetration at which Adams/Solver
(C++) applies full damping is 0.1.
VFORCE/1, I=27, JFLOAT=25, RM=26
, FX=0/
, FY=IMPACT(DY(4,1,1), VY(4,1,1), 1-AKISPL(DX(4,1,1),
, DZ(4,1,1),3),le7, 1.01, le4,.25)/
, FZ=0
This statement defines an impact force when a ball penetrates a surface defined by a spline. The force is
a translational force at Marker 27. The DY(4,1,1) defines the y-component of the instantaneous
displacement of Marker 4 with respect to Marker 1. The VY(4,1,1) defines the y-component of the
instantaneous velocity. The free length is defined using spline 3, which represents the surface.
The independent variables in the spline are defined using the x- and z-components of the instantaneous
displacement of Marker 4 with respect to Marker 1, DX(4,1,1) and DZ(4,1,1), respectively. The stiffness
is le7, the exponent of deformation is 1.01, the maximum damping coefficient is le4, and the penetration
at which Adams/Solver (C++) applies full damping is 0.25.
See other Miscellaneous Adams intrinsic functions available.
88 Adams/Solver
C++ Functions
INCANG
The INCANG function computes the included angle between the line defined by markers i and j, and the
line defined by markers j and k. The three markers can be on separate parts.
Note:
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.
INTERP 89
C++ Functions
INTERP
The INTERP function returns the iord derivative of the interpolated value of SPLINE/id at time=x. The
INTERP function supports time-series splines, which are splines that include a FILE argument that
specifies a time history file of type DAC or RPC III.
Format
A real variable that specifies the value of time, the independent variable along the x-axis of
the time series spline that is being interpolated.
degree
An integer variable that specifies the degree of interpolation. For example, a value of 1
performs linear interpolation, while 3 performs cubic interpolation of the spline data.
Range: degree > 1
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
Extended Definition
The INTERP function uses a B-Spline formulation to create a function across a set of data points. The
data points are defined in a SPLINE statement in the Adams/Solver data deck. The SPLINE statement
with the FILE argument that you define in the Adams/Solver dataset must reference a time series file of
type DAC or RPC III. For more information on these file types, see Adams/Durability.
In general, the INTERP function with linear interpolation will not be a smooth function because, in
almost all cases, the function will be discontinuous in the first derivative. Therefore, the estimate of the
first derivative may be erroneous even though, by definition, the data points of a DAC or RPC time
history file are evenly spaced. In all cases, the second derivative of the function being approximated is
unreliable with linear interpolation.
90 Adams/Solver
C++ Functions
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.
Note:
You may increase the order of interpolation beyond that of a cubic fit by setting the
degree argument to an integer value greater than 3. However, you may see a performance
penalty in doing so as higher order fitting is more computationally expensive than lower
order fitting. Typical Adams simulations run satisfactorily with cubic or lower order of
interpolation.
Examples
SPLINE/101
,FILE=test_data.rsp
,CHANNEL=9
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.
INVPSD 91
C++ Functions
INVPSD
The INVPSD (Inverse Power Spectral Density) function regenerates a time signal from a power spectral
density description.
Format
id
The id number of the spline containing the PSD versus frequency data.
f0
f1
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.
Extended Definition
INVPSD =
( Ai sin ( 2fi x + i ) )
i=1
The regenerated signal consists of a series of sinusoidal functions where the amplitudes, Ai, are
determined in such a way that the effective value for the PSD and the time signal are the same. The phase
angle,
Using the same seed value will always result in the same set of phase angles.
92 Adams/Solver
C++ Functions
Examples
For the power spectral density data shown in Figure 5, INVPSD(TIME, spline_1, 1, 10, 20, 0, 0)
regenerates the time signal shown in Figure 6.
Figure 5
Figure 6
JOINT 93
C++ Functions
JOINT
The JOINT function returns component comp of a force or torque due to JOINT/id as calculated in the
coordinate system of marker rm. If jflag is set to zero, the value returned is the force/torque acting on the
I marker of the JOINT. If jflag is set to one, the value returned is that acting on the J marker. rm may be
specified as zero if the results are desired in the global coordinate system.
Format
id
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.
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 z-axis of Marker 23 opposes this motion.
JOINT(1,0,1,23) determines the magnitude of the reaction force at Marker 23. JOINT(1,0,4,23)
determines the component of the constraint force along the axis of the rotational of the joint.
JOINT(1,0,12)-ABS(JOINT(1,0,4,23)) defines the radial load in the revolute joint (i.e., the normal
force).
94 Adams/Solver
C++ Functions
JPRIM 95
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
id
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.
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.
96 Adams/Solver
C++ Functions
LOG 97
C++ Functions
LOG
The LOG function returns the natural logarithm an expression a. If ex=a then LOG(a)=x. The LOG
function is defined only for positive values of a (that is, a > 0). It is undefined for all other values.
Format
LOG(a)
Arguments
Any valid function expression that returns a positive value during a simulation.
Number of Arguments: 1
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.
98 Adams/Solver
C++ Functions
LOG10
The LOG10 function returns log to base 10 of an expression a. If 10^x=a, then LOG10(a)= x. The LOG10
function is defined only for positive values of a (a>0). It is undefined for all other values.
Format
LOG10(a)
Arguments
Any valid function expression that returns a positive value during a simulation.
Number of Arguments: 1
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.
MAG 99
C++ Functions
MAG
The MAG function returns the magnitude of an arbitrary vector function expression.
Format
MAG(exp)
Arguments
exp
Extended Definition
MAG ( exp ) =
where
exp exp
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.
100 Adams/Solver
C++ Functions
MAX
The MAX function returns the maximum of two expressions a1 and a2.
MAX(a1,a2) = a1 if a1 > a2
MAX(a1,a2) = a2 if a2 > a1
Format
MAX(a1,a2)
Arguments
a1
a2
Caution:
The MAX function is generally discontinuous. Use this function expression with care when
you are specifying force or motion input.
Examples
SFORCE/1, ROTATIONAL, ACTIONONLY, I=21, J=11
, FUNCTION=MAX(0,-3*(AZ(21,11)-25D))
This SFORCE statement defines an action-only torque that acts at Marker 21 and acts along the z-axis of
Marker 11. The torque is defined to always be non-negative through the use of the MAX function. Thus,
the torque can only act to decrease the AZ rotation of Marker 21 with respect to Marker 11 (see AZ).
See other FORTRAN 77 intrinsic functions available.
MIN 101
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
a1
a2
Caution:
The MIN function is generally discontinuous. Use this function expression with care when
you are specifying force or motion input.
Examples
SFORCE/1, ROTATIONAL, ACTIONONLY, I=21, J=11
, FUNCTION=MIN(0,-3*(AZ(21,11)-25D))
This SFORCE statement defines an action-only torque that acts at Marker 21 and acts along the z-axis of
Marker 11. The torque is defined to always be 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.
102 Adams/Solver
C++ Functions
MOD
The MOD function returns the remainder when a1 is divided by a2.
MOD(a1,a2) = a1 - int(a1/a2) * a2
Format
MOD(a1,a2)
Arguments
a1
a2
Caution:
The MOD function is generally discontinuous. Use this function expression with care when
you are specifying force or motion input.
Examples
MOD(45,16)=13
MODE 103
C++ Functions
MODE
The MODE function returns the current analysis mode. These are defined as:
1 = Kinematics
2 = Reserved
3 = Initial conditions
4 = Dynamics
5 = Statics
6 = Quasi-statics
7 = Linear analysis
Format
MODE
Caution:
Use the MODE function with care if you use the STATICS argument on the SIMULATE
command to request a static or quasi-static simulation of a kinematic system,
Adams/Solver (C++) performs a kinematic analysis and, consequently, returns a MODE
analysis constant of 1 (not 5 or 6).
Examples
SFORCE/1, TRANSLATION, I=21, J=11
, FUNCTION=IF(MODE-4:0,0,-4*(DM(21,11)-10.6)
This example defines a translational force that is active only during statics, quasi-static, and linear
analysis modes. For these analysis modes, the SFORCE acts as a simple spring. For all other analyses,
the net force applied by the SFORCE is zero.
See other Simulation parameters and constants available.
104 Adams/Solver
C++ Functions
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
id
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.
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 Element-specific reaction force measures available.
NJAC 105
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
106 Adams/Solver
C++ Functions
NRHS
The number of times that the equations of motion have been evaluated. You can use it as a counter for
the number of iterations needed during the Adams solution.
Example
!
! adams_view_name='FUNCTION_MEA_NRHS'
VARIABLE/3
, FUNCTION = NRHS
ORDER 107
C++ Functions
ORDER
The current order of a variable-order integrator.
Example
!
! adams_view_name='FUNCTION_MEA_ORDER'
VARIABLE/2
, FUNCTION = ORDER
108 Adams/Solver
C++ Functions
PHI
The PHI function calculates the third angle (in radians) of a body-fixed-3-1-3 Euler rotation sequence
between markers i and j. Marker j defaults to the global coordinate system if it is not specified. See
Figure 7 for a schematic description of the body-fixed-3-1-3 Euler rotation sequence.
Format
PHI(i[,j])
Arguments
The marker with respect to which the rotations are being measured.
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
PHI 109
C++ Functions
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'.)
110 Adams/Solver
C++ Functions
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.
PINVAL 111
C++ Functions
PINVAL
The PINVAL function returns component comp of PINPUT/id.
Format
id
comp
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.
112 Adams/Solver
C++ Functions
PITCH
Calculates the second angle of a body-fixed 3 -2 1 yaw-pitch-roll 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
The marker with respect to which the rotations are being measured.
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.
POLY 113
C++ Functions
POLY
The POLY function evaluates a standard polynomial at a user-specified value x.
Format
A real variable that specifies the independent variable. For example, if the
independent variable in the function is time, x is the system variable TIME.
x0
The real variables that define as many as thirty-one coefficients for the polynomial
series.
Extended Definition
The POLY function evaluates a standard polynomial at a user-specified value x. x0, a0, a1,..., a30 are
parameters used to define the constants for the polynomial. The standard polynomial is defined as:
n
P(x) =
aj ( x xo )j
j=0
= ao + a1 ( x xo ) + a2 ( x xo ) 2 + an ( x xo ) n
The index j has a range from zero to n, where n is the number of terms in the series.
Examples
MOTION/1, JOINT=21, TRANSLATION
, FUNCTION=POLY(TIME, 0, 0, 0, 1)
This MOTION statement uses a quadratic polynomial function with respect to the system variable TIME
to define a motion. That expanded function is:
Poly = time2
MOTION/1, JOINT=21, TRANSLATION
, FUNCTION = IF(TIME-5: 0, 0, POLY(TIME, 5, 0, 10))
This MOTION statement uses an arithmetic IF in its function expression to switch between functions.
The expanded function is:
if (time > 5) then Poly=0
else Poly=10*time-5
114 Adams/Solver
C++ Functions
This SFORCE statement defines a force with a nonlinear force deformation characteristic. This
relationship is:
Poly=-25*[DM(10,20)-10]- 0.75*[DM(10,20)-10]3
where, DM(10,20) represents the magnitude of the displacement of Marker 10 with respect to Marker 20.
The free length of the spring is 10 units.
See other Miscellaneous Adams intrinsic functions available.
POUVAL 115
C++ Functions
POUVAL
The POUVAL function returns component comp of POUTPUT/id.
Format
id
comp
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.
116 Adams/Solver
C++ Functions
PSI
The PSI function expression calculates the first angle (in radians) of a body-fixed-3-1-3 Euler rotation
sequence between markers i and j. Marker j defaults to the global coordinate system if it is not specified.
For a schematic of the body-fixed-3-1-3 Euler angles, click here.
Format
PSI(i[,j])
Arguments
The marker with respect to which the rotations are being measured.
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.
PTCV 117
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
id
jflag
An integer flag specifying the point-to-curve 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
rm
The coordinate system in which the results are expressed. To return the results in the global
coordinate system, set rm = 0.
Examples
REQUEST/1
,
,
,
,
,
,
,
F2=PTCV(31,0,2,0)/
F3=PTCV(31,0,3,0)/
F4=PTCV(31,0,4,0)/
F5=PTCV(31,0,5,0)/
F6=PTCV(31,0,6,0)/
F7=PTCV(31,0,7,0)/
F8=PTCV(31,0,8,0)/
This REQUEST statement outputs the x-, y-, and z-components of the force and torque at the I marker
of PTCV/31. Since rm is specified as zero, all vectors are expressed in the global coordinate system.
See other Element-specific reaction force measures available.
118 Adams/Solver
C++ Functions
Q
The Q function returns the current value of the modal coordinate for mode number mode_number for
FLEX_BODY/id.
Format
Q(id, mode_number)
Arguments
id
mode_number
Example
MFORCE/20,FLEX_BODY=6,CASE_INDEX=1,SCALE=Q(5,10)
In this example, a modal force, whose loadcase is scaled by the current value of the modal coordinate
corresponding to mode number 10 on FLEX_BODY/5, is defined.
QDDOT 119
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
id
mode_number
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.
120 Adams/Solver
C++ Functions
QDOT
The QDOT function returns the first time derivative of the modal coordinate for mode number
mode_number of FLEX_BODY/id.
Format
QDOT(id, mode_number)
Arguments
id
mode_number
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.
ROLL 121
C++ Functions
ROLL
The ROLL function calculates the third angle of a body-fixed 3 -2 1 yaw-pitch-roll rotation sequence
between markers i and j. Marker j defaults to the global coordinate system if it is not specified. Note that
roll is an Euler angle.
Format
ROLL (i[,j])
Arguments
The marker with respect to which the rotations are being measured.
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.
122 Adams/Solver
C++ Functions
RTOD
RTOD returns the radians to degrees conversion factor.
Format
RTOD
Examples
REQUEST/1, F2=ROLL(23,14)*RTOD
This REQUEST statement outputs the roll angle between Markers 23 and 14 in degrees.
See other Simulation parameters and constants available.
SENVAL 123
C++ Functions
SENVAL
The SENVAL function returns the last scored value from the function expression or user-written
subroutine associated with the EVALUATE argument on SENSOR/id. See the SENSOR statement for
more information.
Format
SENVAL(id)
Arguments
id
Caution:
If the SENSOR/id does not have the EVALUATE argument, SENVAL(id) returns zero.
Examples
VARIABLE/1, FUNCTION=SENVAL(100)
SENSOR/100, EQ, VALUE=0
, FUNCTION=AZ(22,11)-PI/2/
, EVALUATE=SENVAL(100) +1
This SENSOR statement counts the number of times function AZ(22,11) passes through
VARIABLE statement defines a variable equal to the count.
/2. The
124 Adams/Solver
C++ Functions
SFORCE
The SFORCE function returns component comp of a force due to SFORCE/id as calculated in the
coordinate system of marker rm. If jflag is set to zero, the value returned is the force or torque acting on
the I marker of the SFORCE/id. If jflag is set to 1, the value returned is that which acts on the J marker.
You can specify rm as zero if you want the results to be returned in the global coordinate system.
Format
id
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
rm
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 z-components 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 Element-specific applied force measures available.
SHF 125
C++ Functions
SHF
The SHF function evaluates a simple harmonic function. The following equation defines SHF:
SHF = a*sin( *(x-x0)-phi)+b
Format
The independent variable in the function. It may be any valid expression. For example, if the
independent variable in the function is twice the current simulation time, x is the system
variable 2*TIME.
x0
The 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.
Examples
MOTION/1, JOINT=21, TRANSLATION
, FUNCTION=SHF(TIME, 25D, PI, 360D, 0, 5)
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.
126 Adams/Solver
C++ Functions
SIGN
The SIGN function transfers the sign of a2 to the magnitude of a1.
SIGN(a1,a2) = ABS(a1) if a2 > 0
SIGN(a1,a2) = -ABS(a1) if a2 < 0
Format
SIGN (a1,a2)
Arguments
a1
a2
Caution:
The SIGN function is discontinuous. Use this function with care to avoid creating
expressions that are discontinuous.
Examples
VARIABLE/23, FUNCTION=10*SIGN(DM(24,33),VZ(24,33))
When VZ(24,33) >0, the value of VARIABLE/23 is +10*DM(24,33). When VZ(24,33) < 0, the value of
VARIABLE/23 is -10*DM(24,33).
See other FORTRAN 77 intrinsic functions available.
SIN 127
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.
128 Adams/Solver
C++ Functions
SINH
The SINH function return the hyperbolic sine of an expression a.
SINH(a) = (ea - e-a) /2.0
Format
SINH(a)
Arguments
Examples
VARIABLE/1, FUNCTION=SINH(DX(21,32))
The value of VARIABLE/1 is the hyperbolic sine of the x-component of the displacement between
Markers 21 and 32, as calculated in the global coordinate system.
See other FORTRAN 77 intrinsic functions available.
SPDP 129
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
id
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
Examples
REQUEST/1
, F2=SPDP(31,0,2,0)/
, F3=SPDP(31,0,3,0)/
, F4=SPDP(31,0,4,0)/
, F6=SPDP(31,0,6,0)/
, F7=SPDP(31,0,7,0)/
, F8=SPDP(31,0,8,0)
This REQUEST statement output the x-, y- and z-components of the force and torque at the I marker of
SPDP/31. Since rm is specified as zero, all vectors are expressed in the global coordinate system.
See other Element-specific applied force measures available.
130 Adams/Solver
C++ Functions
SQRT
The SQRT function returns the square root of an expression a. The square root function is defined only
for non-negative values of the argument a.
Format
SQRT(a)
Arguments
Examples
VARIABLE/23,
, FUNCTION=SQRT (FX(23,11)**2+FY(23,11)**2)
A new state variable with a value equal to the square root of the sum of the squares of the global x- and
y- components of the net force acting between Markers 21 and 11.
See other FORTRAN 77 intrinsic functions available.
STEP 131
C++ Functions
STEP
The STEP function approximates the Heaviside step function with a cubic polynomial. It has continuous
first derivatives. Its second derivatives are discontinuous at x=x0 and x=x1.
Format
x0
A real variable that specifies the x value at which the STEP function begins.
x1
A real variable that specifies the x value at which the STEP function ends.
h0
h1
Extended Definition
The STEP function approximates the Heaviside step function with a cubic polynomial. The figure below
illustrates the STEP function.
Step Function
a = h1 h0
= ( x x0 ) ( x1 x0 )
132 Adams/Solver
C++ Functions
h0
STEP = h 0 + a 2 ( 3 2 )
h1
Tip:
: x x0
: x0 < x < x1
: x x1
HAVSIN, STEP5, and TANH offer other approximations for the Heaviside step function.
These (except for HAVERSINE) have a higher degree of continuity and differentiability,
but may have larger derivatives.
The figure shown next compares the STEP, STEP5, HAVSIN, and TANH functions.
Comparisons of STEP, STEP5, HAVSIN, and TANH
The next figure shows the first derivatives of these four functions.
STEP 133
C++ Functions
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 secondorder 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.
134 Adams/Solver
C++ Functions
STEP5
The STEP5 function provides approximation to the Heaviside step function with a quintic polynomial. It
has continuous first and second derivatives. Its third derivative is discontinuous at x=x0 and x=x1.
Format
x0
A real variable that specifies the x value at which the STEP5 function begins.
x1
A real variable that specifies the x value at which the STEP5 function ends.
h0
h1
Extended Definition
= h1 h0
= ( x x0 ) ( x1 x0 )
STEP5 135
C++ Functions
h0
STEP5 = h 0 + a 3 [ 10 15 + 6 2 ]
h1
: x x0
: x0 < x < x1
: x x1
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.
136 Adams/Solver
C++ Functions
SWEEP
The SWEEP function returns a constant amplitude sinusoidal function with linearly increasing
frequency.
Format
x0
The value of the independent variable at which the SWEEP function begins.
f0
x1
The value of the independent variable value at which the SWEEP function ends
f1
dx
Extended Definition
f0
f1 f2
freq ( x ) = f 0 + ---------------- x
x 0 + x 1
f1
: x < x0
: x0 < x < x1
: x1 < x
SWEEP 137
C++ Functions
: x < x0
f0 x
( f1 f0 )
: x 0 < x < x 1
f 0 ( x x 0 ) + ------------------------ ( x x 0 ) 2 + f 0 x 0
2 ( x1 x0 )
f req ( x )dx =
( f1 f0 )
2
- ( x1 x0 ) : x < x0
f 1 ( x x 1 ) + f 0 x 0 + f 0 ( x 1 x 0 ) + ----------------------
2
(
x
x
)
1
0
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.
138 Adams/Solver
C++ Functions
MOTION/1,JOINT=1
, FUNCTION=SWEEP(TIME, 1.0, 0.0, 2.0, 5.0, 6.0, 0.01)
TAN 139
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.
140 Adams/Solver
C++ Functions
TANH
The TANH function returns the hyperbolic tangent of an expression a.
TANH(a) = (ea - e-a) / (ea + e-a)
Format
TANH(a)
Arguments
Extended Definition
Example
MOTION/1, JOINT=21, TRANSLATION
, FUNCTION=0.5(1+TANH(5*(TIME-1.5)))
This MOTION statement defines a smooth step function that transitions from a value of 0 to 1. The value
of the step function at time=1.5 is 0.5.
See other FORTRAN 77 intrinsic functions available.
THETA 141
C++ Functions
THETA
The THETA function calculates the second angle (in radians) of a body-fixed-3-1-3 Euler rotation
sequence between markers i and j. Marker j defaults to the global coordinate system if it is not specified.
View a schematic of the body-fixed-3-1-3 Euler angles.
Format
THETA(i[,j])
Arguments
The marker with respect to which the rotations are being measured.
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.
142 Adams/Solver
C++ Functions
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.
TM 143
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
An integer that specifies the identifier of the marker at which the magnitude of the net torque
is to be calculated.
A second integer that specifies a marker identifier. All forces acting between the [i,j] pair are
to be included in the calculation. Set j = 0 or do not specify if you are interested in all forces
acting on marker i.
Examples
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.
144 Adams/Solver
C++ Functions
TRANS
The TRANS function transforms an arbitrary vector function expression represented in the coordinate
system of marker j to the coordinate system of marker i.
Format
TRANS(exp,i[,j])
Arguments
exp
The marker in whose coordinate system the expression, exp, is specified. If not specified, the
expression, exp, is assumed to be specified in the global coordinate system.
Examples
VFORCE/1, I=1, JFLOAT=2, RM=3, FXYZ=VXYZ(i,j,k)
VFORCE/2, I=1, JFLOAT=2, RM=3, FXYZ=TRANS(VXYZ(i,j),k)
VFORCE/3, I=1, JFLOAT=2, RM=3, FXYZ=TRANS(VXYZ(i,j,l),k,l)
Variables 1, 2 and 3 are synonymous. They all specify a vector force law that is equal to the velocity
vector of marker i with respect to marker j, represented in the coordinate system of marker k.
See other Vector functions available.
TX 145
C++ Functions
TX
The TX measure returns the x-component of the net translational torque acting on marker i, represented
in the coordinate system of marker k. All force and constraint elements acting between markers i and j
are included in the calculation of the torque. If j is not specified, TX measures the sum of all force and
constraint elements acting on marker i. If k not specified or if k=0 the torque is represented in the
GROUND coordinate system. To specify k without specifying j use j=0.
Format
TX(i[,j][,k])
Arguments
An integer that specifies the identifier of the marker at which the magnitude of the net torque is
to be calculated.
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.
An integer that specifies the identifier of a marker (coordinate system) in which the xcomponent of the torque is to be returned. k defaults to the global coordinate system when it is
not specified.
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 x-component of the sum of all torques acting between
markers 32 and 44 as computed in the global coordinate system. Since JOINT 1 and motion 1 are defined
between markers 32 and 44, their reaction torque will be included in the computation of TX().
See other Generic force measures available.
146 Adams/Solver
C++ Functions
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
An integer that specifies the identifier of the marker at which the magnitude of the net torque is
to be calculated.
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.
An integer that specifies the identifier of a marker (coordinate system) in which the xcomponent of the torque is to be returned. k defaults to the global coordinate system when it is
not specified.
Extended Definition
TX
TXYZ ( i ,j ,k ) = TY
TZ
where:
TX is the TX measure.
TY is the TY measure.
TZ is the TZ measure.
Examples
TXYZ 147
C++ Functions
148 Adams/Solver
C++ Functions
TY
The TY measure returns the y-component of the net translational torque acting on marker i, represented
in the coordinate system of marker k. All force and constraint elements acting between markers i and j
are included in the calculation of the torque. If j is not specified, 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
An integer that specifies the identifier of the marker at which the magnitude of the net torque
is to be calculated.
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.
An integer that specifies the identifier of a marker (coordinate system) in which the ycomponent of the torque is to be returned. k defaults to the global coordinate system when it is
not specified.
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 y-component of the sum of all torques acting between
markers 32 and 44 as computed in the global coordinate system. Since joint 1 and motion 1 are defined
between markers 32 and 44, their reaction torque will be included in the computation of TY().
See other Generic force measures available.
TZ 149
C++ Functions
TZ
The TZ measure returns the z-component of the net translational torque acting on marker i, represented
in the coordinate system of marker k. All force and constraint elements acting between markers i and j
are included in the calculation of the torque. If j is not specified, 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
An integer that specifies the identifier of the marker at which the magnitude of the net torque is
to be calculated.
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.
An integer that specifies the identifier of a marker (coordinate system) in which the zcomponent of the torque is to be returned. k defaults to the global coordinate system when it is
not specified.
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 z-component of the sum of all torques
acting between markers 32 and 44 as computed in the global coordinate system. Since joint 1 and motion
1 are defined between markers 32 and 44, their reaction torque will be included in the computation of
TZ( ).
See other Generic force measures available.
150 Adams/Solver
C++ Functions
UV
The UV function returns the unit vector in the direction of an arbitrary vector function expression.
Format
UV(exp)
Arguments
exp
Extended Definition
exp
UV ( exp ) = -------------------------exp exp
where
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.
UVX 151
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
The marker in whose coordinate system the unit vector is being expressed. If k is not
specified, k defaults to the global coordinate system.
Extended Definition
xi xk
UVX ( i, k ) = x i y k
x z
i
where:
Examples
VARIABLE/1, FUN=DXYZ(i,j)*UVX(k)
VARIABLE/2, FUN=DX(i,j,k)
Variables 1 and 2 are synonymous. They both produce the translational displacement between markers i
and j along the direction of the x-axis of marker k.
See other Vector measures available.
152 Adams/Solver
C++ Functions
UVY
The UVY measure returns the unit vector in the direction of the y axis of marker i, resolved in the
coordinate system of marker k.
Format
UVY(i[,k])
Arguments
The marker in whose coordinate system the unit vector is being expressed. If k is not
specified, k defaults to the global coordinate system.
Extended Definition
yi xk
UVY ( i, k ) = y i y k
y z
i
where:
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 y-axis of marker k.
See other Vector measures available.
UVZ 153
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
The marker in whose coordinate system the unit vector is being expressed. If
k is not specified, k defaults to the global coordinate system.
Extended Definition
zi xk
UVZ ( i, k ) = z i y k
z z
i
where:
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 z-axis of marker k.
See other Vector measures available.
154 Adams/Solver
C++ Functions
VARVAL
The VARVAL function returns current value of VARIABLE/id.
Format
VARVAL (id)
Arguments
id
Examples
VARIABLE/10, FUNCTION=DX(21,32,43)
SFORCE/20, TRANSLATION, I=346, J=567
, FUNCTION=(VARVAL(10)-5)**2
VFORCE 155
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
id
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
Examples
MARKER/236, QP=4,6,7, EU=90D,90D,0, PART=23
MARKER/169, PART=16, FLOATING
MARKER/168, QP=1,2,3, EU=30D,45D,60D, PART=16
VFORCE/19, I=236, JFLOAT=169
,FX=-10*VX(236,168,168,168)/
,FY=-10*VY(236,168,168,168)/
,FZ=-10*VZ(236,168,168,168)
REQUEST/1
,F2=VFORCE(23,0,2,0)/
This REQUEST statement contains the x-component of the force exerted by VFORCE/19 calculated in
the coordinate system of Marker 168.
156 Adams/Solver
C++ Functions
VM 157
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
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.
The reference frame in which the time derivative of the displacement vector is taken. Set l = 0 or
omit the argument if you want the time derivatives to be taken in the ground coordinate system
(GCS).
Extended Definition
VM ( i, j, l ) =
where
(l) d
dt
Ri
(l) d
dt
Rj
(l) d
dt
Ri
(l) d
dt
Rj
Examples
DIFF/51, IC=-6.2, FUNCTION=VM(23,0,32)
A dynamically determined user state is defined by DIFF/51. The time derivative of the user-state is the
magnitude of the velocity of the origin of Marker 23 with respect to ground. The time derivative for the
velocity computation is taken in the reference frame of Marker 32.
VARIABLE/1, FUNCTION=VM(21,32,43)
This VARIABLE statement defines an algebraic, user-defined state whose instantaneous value is the
magnitude of the velocity vector between Markers 21 and 32, as seen by an observer at Marker 43.
See other Velocity measures available.
158 Adams/Solver
C++ Functions
VR
The VR function calculates the radial (separation) velocity of marker i with respect to marker j. The
vector time derivative is taken in the reference frame of marker l. Markers j and l default to the global
coordinate system if they are not specified.
Format
VR(i[,j][,l])
Arguments
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.
The reference frame in which the time derivative of the displacement vector is taken. Set l = 0
or omit the argument if you want the time derivatives to be taken in the ground coordinate
system (GCS).
Extended Definition
Mathematically, VR is calculated by projecting the velocity vector on a unit vector along the line of sight
between i and j, as follows:
(l) d
(l) d
Ri
Rj [ Ri Rj ]
dt
dt
------------------------------------------------------------------- = VXYZ UV ( DXYZ )
VR ( i, j, l ) =
[ Ri Rj ] [ Ri Rj ]
where:
As markers i and j separate from each other, VR is positive. VR is negative when markers i and j approach
each other.
Examples
VR 159
C++ Functions
160 Adams/Solver
C++ Functions
VTORQ
The VTORQ function returns the component comp of force in VTORQUE/id in the coordinate system
of marker rm. If jflag is set to zero, Adams/Solver (C++) returns the value of the torque that acts on the
I marker of VTORQUE/id. If jflag is set to 1, Adams/Solver (C++) returns the value that acts on the J
marker. To obtain results in the global coordinate system, you can specify rm as zero.
Format
id
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
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 x-component of the torque exerted by VTORQUE/19 calculated
in the coordinate system of Marker 168.
VTORQ 161
C++ Functions
162 Adams/Solver
C++ Functions
VX
The VX function returns the x-component of the difference between the velocity vector of marker i and
the velocity vector of marker j as computed in the coordinate system of marker k. All vector time
derivatives are taken in the reference frame of marker l. Marker j defaults to the global coordinate system
if it is not specified. Similarly, markers i and j default to the global coordinate system if they are not
specified.
Format
VX(i[,j][,k][,l])
Arguments
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.
The marker in whose coordinate system the velocity vector is being expressed. Set k = 0, while
still specifying l, if you want the results to be calculated along the x-axis of the global
coordinate system.
The reference frame in which the first time derivative of the displacement vector is taken. Set
l = 0 or omit the argument if you want the time derivatives to be taken in the ground coordinate
system (GCS).
Extended Definition
Vx ( i, j ,k, l ) =
(l) d
dt
Ri
(l) d
dt
Rj xk
where:
(l) d
dt
VX 163
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.
164 Adams/Solver
C++ Functions
VXYZ
The VXYZ measure returns the difference between the velocity vector of marker i and the velocity vector
of marker j resolved in the coordinate system of marker k. All vector time derivatives are taken in the
reference frame of marker l.
Format
VXYZ(i[,j][,k][,l])
Arguments
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.
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.
The reference frame in which the first-time derivative of the displacement vector is taken. Set
l = 0 or omit the argument if you want the time derivatives to be taken in the global reference
frame.
Extended Definition
VXYZ ( i ,j ,k ,l ) =
(l) d
(l) d
Rj xk
dt
dt
VX
(l) d
(l) d
Ri
R j y k = VY
dt
dt
VZ
(l) d
(l) d
Ri
Rj zk
dt
dt
Ri
where:
VX is the VX measure.
VY is the VY measure.
VZ is the VZ measure.
VXYZ 165
C++ Functions
(l) d
dt
Examples
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)
166 Adams/Solver
C++ Functions
VY
The VY function returns the y-component of the difference between the velocity vector of marker i and
the velocity vector of marker j as computed in the coordinate system of marker k. All vector time
derivatives are taken in the reference frame of marker l. Marker j defaults to the global coordinate system
if it is not specified. Similarly, markers i and j default to the global coordinate system if they are not
specified.
Format
VY(i[,j][,k][,l])
Arguments
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.
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 y-axis of the global coordinate
system.
The reference frame in which the first time derivative of the displacement vector is taken. Set l
= 0 or omit the argument if you want the time derivatives to be taken in the ground coordinate
system (GCS).
Extended Defintion
VY ( i ,j ,k ,l ) =
(l) d
dt
Ri
(l) d
dt
Rj yk
where:
(l) d
dt
VY 167
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.
168 Adams/Solver
C++ Functions
VZ
The VZ function returns the z-component of the difference between the velocity vector of marker i and
the velocity vector of marker j as computed in the coordinate system of marker k. All vector time
derivatives are taken in the reference frame of marker l. Marker j defaults to the global coordinate system
if it is not specified. Similarly, markers i and j default to the global coordinate system if they are not
specified.
Format
VZ(i[,j][,k][,l])
Arguments
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.
The marker in whose coordinate system the velocity vector is expressed. Set k = 0, while still
specifying l, if you want the results to be calculated along the z-axis of the global coordinate
system.
The reference frame in which the first time derivative of the displacement vector is taken. Set
l = 0 or omit the argument if you want the time derivatives to be taken in the ground coordinate
system (GCS).
Extended Definition
VZ ( i ,j ,k ,l ) =
(l) d
dt
Ri
(l) d
dt
Rj zk
where:
(l) d
dt
VZ 169
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.
170 Adams/Solver
C++ Functions
WDTM
The WDTM function returns the magnitude of the difference between the angular acceleration vector of
marker i in the reference frame of marker l and the angular acceleration of marker j in the reference frame
of marker l.
Format
WDTM(i[,j][,l])
Arguments
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.
The reference frame in which the first time derivative of the angular velocity vector is taken. Set
l = 0 if you want the time derivatives to be taken in the ground reference frame.
Extended Definition
WDTM ( i ,j, l ) =
(l) d
dt
(l) d
dt
(l) d
dt
(l) d
dt
where:
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.
WDTX 171
C++ Functions
WDTX
The WDTX function returns the x-component of the difference between the angular acceleration vector
of marker i in the reference frame of marker l and the angular acceleration vector of marker j in the
reference frame of marker l, as computed in the coordinate system of marker k. Marker j defaults to
global coordinate system if it is not specified. Similarly, marker k and l default to global coordinate
system if they are not specified.
Format
WDTX(i[,j][,k][,l])
Arguments
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.
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 x-axis of the global
coordinate system.
The reference frame in which the first time derivative of the angular acceleration vector is taken.
Set l = 0 if you want the time derivatives to be taken in the ground coordinate system (GCS).
Extended Definition
WDTX ( i ,j ,k ,l ) =
(l) d
dt
(l) d
dt
j xk
where:
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)/
172 Adams/Solver
C++ Functions
,F3=WDTY(1236,2169,2169,2169)/
,F4=WDTZ(1236,2169,2169,2169)
In its second column REQUEST/16 contains the x-component of the angular acceleration vector of
Marker 1236 with respect to Marker 2169, as seen in the global coordinate system of Marker 2169 and
measured in the reference frame containing Marker 2169.
See other Acceleration measures available.
WDTXYZ 173
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
The marker with respect to which the angular acceleration is being measured. If j is not
specified, it defaults to the global origin. Specify j = 0 if you want to use this default, and then
specify k or l.
The marker in whose coordinate system the angular acceleration vector is being expressed. If
not specified, k defaults to the global coordinate system. Specify k = 0 if you want to use this
default, and then specify l.
The reference frame in which the first time derivative of the angular velocity vector is taken.
Set l = 0 or omit the argument if you want the time derivative to be taken in the global reference
frame.
Extended Definition
WDTXYZ ( i ,j ,k ,l ) =
(l) d
(l) d
j xk
WDTX
(l) d
(l) d
i
j y k = WDTY
dt
dt
WDTZ
(l) d
(l) d
i
j z k
dt
dt
dt
dt
where:
(l) d
dt
174 Adams/Solver
C++ Functions
Examples
A vector expression for angular acceleration might be used directly in the definition of a vector torque
element:
VTORQUE/3, I=310, JFLOAT=9911, RM=310,
, TXYZ = -6.*WDTXYZ(310,9900,310)
WDTY 175
C++ Functions
WDTY
The WDTY function returns the y-component of the difference between the angular acceleration vector
of marker i in the reference frame of marker l and the angular acceleration vector of marker j in the
reference frame of marker l, as computed in the coordinate system of marker k. Marker j defaults to the
global coordinate system if it is not specified. Similarly, marker k and l default to the global coordinate
system if they are not specified.
Format
WDTY(i[,j][,k][,l])
Arguments
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.
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 y-axis of the global
coordinate system.
The reference frame in which the first time derivative of the angular acceleration vector is taken.
Set l = 0 if you want the time derivatives to be taken in the ground coordinate system (GCS).
Extended Definition
WDTY ( i ,j ,k ,l ) =
(l) d
dt
(l) d
dt
j y k
where:
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)/
176 Adams/Solver
C++ Functions
,F3=WDTY(1236,2169,2169,2169)/
,F4=WDTZ(1236,2169,2169,2169)
In its third column REQUEST/16 contains the y-component of the angular acceleration vector of Marker
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.
WDTZ 177
C++ Functions
WDTZ
The WDTZ function returns the z-component of the difference between the angular acceleration vector
of marker i in the reference frame of marker l and the angular acceleration vector of marker j in the
reference frame of marker l, as computed in the coordinate system of marker k. Marker j defaults to the
global coordinate system if it is not specified. Similarly, marker k and l default to the global coordinate
if they are not specified.
Format
WDTZ(i[,j][,k][,l])
Arguments
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.
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 z-axis of the global
coordinate system.
The reference frame in which the first time derivative of the angular acceleration vector is
taken. Set l = 0 if you want the time derivatives to be taken in the ground coordinate system
(GCS).
Extended Definition
WDTZ ( i ,j ,k ,l ) =
(l) d
dt
(l) d
dt
j z k
where:
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)/
178 Adams/Solver
C++ Functions
,F3=WDTY(1236,2169,2169,2169)/
,F4=WDTZ(1236,2169,2169,2169)
In its fourth column REQUEST/16 contains the z-component of the angular acceleration vector of
Marker 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.
WM 179
C++ Functions
WM
The WM function returns the magnitude of the angular velocity vector of marker i with respect to marker
j. Marker j defaults to the global coordinate system if it is not specified.
Format
WM(i[,j])
Arguments
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.
Extended Definition
WM ( i ,j ) =
[ i j ] [ i j ]
where:
Examples
MARKER/1236, QP=4,6,7 EU=90D,90D,90D, PART=23
MARKER/2169, PART=16
REQUEST/16
,F1=WM(1236,2169)/
,F2=WX(1236,2169,2169)/
,F3=WY(1236,2169,2169)/
,F4=WZ(1236,2169,2169)
In its first column, REQUEST/16 contains the magnitude of the angular velocity vector of Marker 1236
and Marker 2169.
See other Velocity measures available.
180 Adams/Solver
C++ Functions
WX
The WX function returns the x-component of the difference between the angular velocity vector of
marker i in ground and the angular velocity vector of marker j in ground, and expressed in the coordinate
system of marker k. Marker j defaults to the global coordinate system if it is not specified. Similarly,
marker k defaults to the global coordinate system if it is not specified.
Format
WX(i[,j][,k])
Arguments
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.
The marker in whose coordinate system the velocity vector is being expressed. Set k = 0 if you
want the results to be calculated along the x-axis of the global coordinate system.
Extended Definition
WX ( i ,j ,k ) = [ i j ] x k
where:
Examples
MARKER/1236, QP=4,6,7 EU=90D,90D,90D, PART=23
MARKER/2169, PART=16
REQUEST/16
,F1=WM(1236,2169)/
,F2=WX(1236,2169,2169)/
,F3=WY(1236,2169,2169)/
,F4=WZ(1236,2169,2169)
In its second column, REQUEST/16 contains the x-component of the angular velocity Markers 1236 and
2169 as measured in the coordinate system of Marker 2169.
See other Velocity measures available.
WXYZ 181
C++ Functions
WXYZ
The WXYZ measure returns the difference between the angular velocity vector of marker i and the
angular velocity vector of marker j resolved in the coordinate system of marker k.
Format
WXYZ(i[,j][,k])
Arguments
The marker with respect to which the angular velocity is being measured. If j is not specified, it
defaults to the global origin. Specify j = 0 if you want to use this default, and then specify k.
The marker in whose coordinate system the angular velocity vector is being expressed. If not
specified, k defaults to the global coordinate system.
Extended Definition
[ i j ] xk
WX
WXYZ ( i ,j ,k ) = [ i j ] y k = WY
[ i j ] z
WZ
k
where:
WX is the WX measure.
WY is the WY measure.
WZ is the WZ measure.
182 Adams/Solver
C++ Functions
Examples
A vector expression for angular velocity might be used directly in the definition of a vector torque
element:
VTORQUE/3, I=310, JFLOAT=9911, RM=310,
, TXYZ = -6.*WXYZ(310,9900,310)
WY 183
C++ Functions
WY
The WY function returns the y-component of the difference between the angular velocity vector of
marker i in ground and the angular velocity vector of marker j in ground, and expressed in the coordinate
system of marker k. Marker j defaults to the global coordinate system if it is not specified. Similarly,
marker k defaults to the global coordinate system if it is not specified.
Format
WY(i[,j][,k])
Arguments
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.
The marker in whose coordinate system the velocity vector is being expressed. Set k = 0 if you
want the results to be calculated along the y-axis of the global coordinate system.
Extended Definition
WY ( i ,j ,k ) = [ i j ] y k
where:
Examples
MARKER/1236, QP=4,6,7 EU=90D,90D,90D, PART=23
MARKER/2169, PART=16
REQUEST/16
,F1=WM(1236,2169)/
,F2=WX(1236,2169,2169)/
,F3=WY(1236,2169,2169)/
,F4=WZ(1236,2169,2169)
In its third column, REQUEST/16 contains the y-component of the angular velocity Markers 1236 and
2169 as measured in the coordinate system of Marker 2169.
See other Velocity measures available.
184 Adams/Solver
C++ Functions
WZ
The WZ function returns the z-component of the difference between the angular velocity vector of
marker i in ground and the angular velocity vector of marker j in ground, and expressed in the coordinate
system of marker k. Marker j defaults to the global coordinate system if it is not specified. Similarly,
marker k defaults to the global coordinate system if it is not specified.
Format
WZ(i[,j][,k])
Arguments
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.
The marker in whose coordinate system the velocity vector is being expressed. Set k = 0 if you
want the results to be calculated along the z-axis of the global coordinate system.
Extended Definition
WZ ( i ,j ,k ) = [ i j ] z k
where:
Examples
MARKER/1236, QP=4,6,7 EU=90D,90D,90D, PART=23
MARKER/2169, PART=16
REQUEST/16
,F1=WM(1236,2169)/
,F2=WX(1236,2169,2169)/
,F3=WY(1236,2169,2169)/
,F4=WZ(1236,2169,2169)
In its fourth column, REQUEST/16 contains the z-component of the angular velocity Markers 1236 and
2169 as measured in the coordinate system of Marker 2169.
See other Velocity measures available.
YAW 185
C++ Functions
YAW
The YAW function calculates the first angle of a body-fixed 3 -2 1 yaw-pitch-roll rotation sequence
between markers i and j. Marker j defaults to the global coordinate system if it is not specified. Note that
yaw is an Euler angle.
Format
YAW(i[,j])
Arguments
The marker with respect to which the rotations are being measured.
Examples
REQUEST/1
,F2=YAW(21,11)/
,F3=PITCH(21,11)/
,F4=ROLL(21,11)
This REQUEST statement calculates the yaw, pitch, and roll angles between Markers 21 and 11 for
output purposes.
See other Displacement measures available.
186 Adams/Solver
C++ Functions
1
C++ Commands
C++ Commands
You use commands to control the simulation. Commands allow you to modify statements, invoke and
control the simulations, and display simulation output and status information.
Below are the Adams/Solver (C++) commands grouped according to their function. Detailed information
on each command can be found by following the links.
a
Type of command:
Command name:
MARKER
FLEX_BODY
Constraints
JOINT
MOTION
GCON
Forces
ACCGRAV
BEAM
BUSHING
FIELD
FRICTION
GFORCE
SFORCE
SPRINGDAMPER
VFORCE
VTORQUE
Reference data
ARRAY
SPLINE
STRING
VARIABLE
Analysis parameters
DEBUG
EQUILIBRIUM
IC
INTEGRATOR
KINEMATICS
LSOLVER
SENSOR
Output
OUTPUT
REQUEST
2 Adams/Solver
C++ Commands
Type of command:
Command name:
Simulation
ACTIVATE
CONTROL
DEACTIVATE
ENVIRONMENT
FILE
LINEAR
PREFERENCES
RELOAD
SAVE
SIMULATE
STOP
Information
HELP
INFO
MENU
SHOW
TIME
ACCGRAV 3
C++ Commands
ACCGRAV
The ACCGRAV command redefines and/or lists the data for a ACCGRAV statement.
Format
Arguments
IGRAV=r
JGRAV=r
KGRAV=r
LIST
Examples
ACCGRAV/LIST
This ACCGRAV command lists all the data for the ACCGRAV statement in the dataset.
See other Forces available.
4 Adams/Solver
C++ Commands
ACTIVATE
The ACTIVATE command activates a statement that was previously turned off by the DEACTIVATE
command.
Format
Arguments
BEAM
CONTACT
COUPLER
BUSHING
FIELD
GCON
GFORCE
ID=id1[,...,id30]
JOINT
JPRIM
ACTIVATE 5
C++ Commands
LIST
Indicates that Adams/Solver (C++) is to display a list of all the existing elements
of the specified type, along with their current activity status.
MOTION
RANGE=id1,id2
SENSOR
SFORCE
VTORQUE
Extended Defintion
The ACTIVATE command, used in conjunction with the DEACTIVATE command, switches
Adams/Solver (C++) elements on and off. All Adams/Solver (C++) elements are active by default in the
input dataset, but can be deactivated using the DEACTIVATE command. For simulation purposes, when
Adams/Solver (C++) activates a statement, the statement appears as though it was always in the dataset.
When Adams/Solver (C++) deactivates a statement, the statement effectively disappears from the model.
Both the ACTIVATE and DEACTIVATE commands take effect when you issue the next SIMULATE
command.
After the activation of any element, Adams/Solver (C++) reprocesses the model at the next SIMULATE
command, as if it had just been read in from the dataset. During the reprocessing, Adams/Solver (C++)
checks the entire model for consistency, reinitializes user subroutines, and recomputes initial conditions.
While checking the entire model, Adams/Solver (C++) verifies that the model is still valid when the
newly activated elements are included. For example, if an activated JOINT overconstrains a model
resulting in an immobile system, Adams/Solver (C++) issues an error message. Adams/Solver (C++) also
reinitializes all user subroutines to re-establish functional dependencies. For each element that refers to
a user-written subroutine, Adams/Solver (C++) calls the user-written subroutine with IFLAG set to true.
Prior to the actual simulation, Adams/Solver (C++) computes initial conditions for the model. If this is
the first simulation, Adams/Solver (C++) begins with the positions and velocities specified in the dataset,
and maintains any user-supplied joint initial-conditions and part positions specified as EXACT. If you
ran a previous simulation, Adams/Solver (C++) begins with the final displacements and velocities.
6 Adams/Solver
C++ Commands
Adams/Solver (C++) then adjusts the initial conditions to ensure that they are consistent with the model
constraints.
Tip:
Use the ACTIVATE and DEACTIVATE commands after a FILE or RELOAD command to
set up the model for a particular loadcase or configuration.
Examples
ACTIVATE/SFORCE,ID=201,202
This ACTIVATE command activates JPRIMs 400 and 499, and all JPRIMs with identifiers between 400
and 499.
See other Simulation available.
ARRAY 7
C++ Commands
ARRAY
The ARRAY command redefines and/or lists the array of up to 1,200 real numbers for an IC-type ARRAY
statement.
Format
LIST
[,NUMBERS=r1 [,r2,...]]
Caution:
You can use the ARRAY command on only an IC-type ARRAY statement (the default
type). Adams/Solver (C++) issues an error message if you specify an X-, U-, or Y-type
ARRAY statement.
Example
ARRAY/12, NUMBERS=0.5,0.12, LIST
8 Adams/Solver
C++ Commands
BEAM
The BEAM command redefines and/or lists the data for a BEAM statement. Although you cannot redefine
the I and the J markers, you can redefine any of the other BEAM arguments.
Format
Arguments
AREA=r
Respecifies the uniform area of the beam cross-section. The centroidal axis
must be orthogonal to this cross-section.
ASY=r
Respecifies the correction factor for shear deflection in the y direction for
Timoshenko beams.
ASZ=r
Respecifies the correction factor for shear deflection in the z direction for
Timoshenko beams.
CMATRIX=r1,...,r21
Respecifies the six-by-six damping matrix for the beam. Because this matrix
is symmetric, you need to specify only one-half of it, that is, twenty-one
entries. The units for the translational and rotational components of
CMATRIX should be force-time per displacement unit and torque-time per
radian, respectively.
CRATIO=r
Respecifies the ratio for calculating the structural damping matrix for the
beam. Adams/Solver (C++) multiplies the stiffness matrix by the value of
CRATIO to obtain the damping matrix.
EMODULUS=r
GMODULUS=r
BEAM 9
C++ Commands
IXX=r
IYY=r,IZZ=r
Denotes the area moments of inertia about the neutral axes of the beam cross
sectional area (y-y and z-z). These are sometimes referred to as the second
moment of area about a given axis. They are expressed as unit length to the
fourth power. For a solid circular section, Iyy=Izz=
where r is the radius
of the cross-section. For a thin-walled sections, open sections, and noncircular
sections, the user should consult a handbook.
LENGTH
Respecifies the undeformed length of the beam along the x-axis of the J
marker.
LIST
10 Adams/Solver
C++ Commands
BUSHING
The BUSHING command redefines and/or lists the data for a BUSHING statement. Although you cannot
define the I and J markers defining the bushing, you can redefine other characteristics of the bushing.
Format
Arguments
C=r1,r2,r3
Respecifies three viscous damping coefficients for the force transferred by the
bushing.
CT=r1,r2,r3
Respecifies three viscous damping coefficients for the torque transferred by the
bushing.
FORCE=r1,r2,r3
K=r1,r2,r3
Respecifies three stiffness coefficients for the force transferred by the bushing.
KT=r1,r2,r3
Respecifies three stiffness coefficients for the torque transferred by the bushing.
LIST
TORQUE=r1,r2,r3
Caution:
For the rotational constitutive equations to be accurate, at least two of the rotations (a, b,
and c) must be small. That is, two of the three values must remain smaller than 10 degrees.
In addition, if a becomes greater than 90 degrees, b becomes erratic. If b becomes greater
than 90 degrees, a becomes erratic. Only c can become greater than 90 degrees without
causing problems. For these reasons, it is best to define your BUSHING such that angles a
and b (not a and c and not b and c) remain small.
CONTROL 11
C++ Commands
CONTROL
The CONTROL command branches program control to the driver subroutine CONSUB (see the
CONSUB subroutine). Adams/Solver (C++) passes parameter arguments to the command as an array.
Upon completion of CONSUB, Adams/Solver (C++) prompts you for another command.
Format
CONTROL/[FUNCTION=USER(r1[,...,r30])[\]][ROUTINE=libname::subname]
[[ ]] Optionally select an item combination
Caution:
Adams/Solver (C++) issues an error message and ignores the entire command if a
CONTROL command is issued when no CONSUB driver subroutine is linked with
Adams/Solver (C++).
Tip:
12 Adams/Solver
C++ Commands
DEACTIVATE
The DEACTIVATE command turns off a statement that was previously turned on by the ACTIVATE
command, or that was active by default.
Format
Arguments
BEAM
BUSHING
CONTACT
COUPLER
FIELD
GCON
GFORCE
ID=id1[,...,id30]
JOINT
JPRIM
DEACTIVATE 13
C++ Commands
LIST
Indicates that Adams/Solver (C++) is to display a list of all the existing elements
of the specified type, along with their current activity status.
MOTION
RANGE=id1, id2
SENSOR
SFORCE
SPRINGDAMPER
VFORCE
VTORQUE
Extended Definition
The DEACTIVATE command, used in conjunction with the ACTIVATE command, switches
Adams/Solver (C++) elements off and on. All Adams/Solver (C++) elements are active by default in the
input dataset, but some may be deactivated using the DEACTIVATE command. For simulation purposes,
when Adams/Solver (C++) deactivates a statement, the statement effectively disappears from the model.
When a statement is activated, the statement appears as though it were always in the dataset. Both the
DEACTIVATE and ACTIVATE commands take effect when you issue the next SIMULATE command.
Once deactivated, a statement remains inactive until it is activated using an ACTIVATE command.
After the deactivation of any element, Adams/Solver (C++) reprocesses the model at the next
SIMULATE command as if it had just been read in from the dataset. During the reprocessing,
Adams/Solver (C++) checks the entire model for consistency, reinitializes user subroutines, and
recomputes initial conditions.
Adams/Solver (C++) reports zero forces for the inactive element if a force request or force graphic refers
to an inactive element. Additionally, references to deactivated elements in function expressions evaluate
to zero.
Adams/Solver (C++) also reinitializes all user subroutines to re-establish functional dependencies. For
each element that refers to a user-written subroutine, Adams/Solver (C++) calls the user-written
subroutine with IFLAG set to true.
Prior to the actual simulation, Adams/Solver (C++) computes initial conditions for the model. If this is
the first simulation, Adams/Solver (C++) begins with the positions and velocities specified in the dataset.
If you ran a previous simulation, Adams/Solver (C++) begins with the final displacements and velocities.
Adams/Solver (C++) then adjusts the initial conditions to ensure that they are consistent with the model
14 Adams/Solver
C++ Commands
constraints. If this is the first simulation, Adams/Solver (C++) also maintains any user-supplied joint
initial-conditions and part positions specified as EXACT.
Adams/Solver (C++) reports zero values in all output files for any forces associated with inactive
elements, including both applied forces and joint reaction forces. This includes force requests, force
graphics, and forces in the Results File.
Tip:
Typically, you use DEACTIVATE and ACTIVATE to set up the model for a particular
loadcase or configuration after a FILE or RELOAD command.
Caution:
Examples
DEACTIVATE/JOINT,ID=71,72,73
This DEACTIVATE command deactivates all SENSORs with identifiers between 5 and 10, including 5
and 10.
You can turn off contact forces in your model during a simulation by using the DEACTIVATE command
in the .acf file.
SIMULATE/TRANSIENT, END=1.0, STEPS=100
DEACTIVATE/CONTACT,ID=1,3, LIST
SIMULATE/TRANSIENT, DURATION=1.0, STEPS=100
This simulates four active contact elements for one second, disabling two out of four contacts, then
continuing the simulation for another second. The LIST argument is useful for obtaining feedback in the
.msg file on the status of active elements. When deactivation has taken place, you will see a similar
message:
CONTACT/1, INACTIVE CONTACT/2, ACTIVE CONTACT/3, INACTIVE CONTACT/4,
ACTIVE
DEBUG 15
C++ Commands
DEBUG
The DEBUG command redefines and/or lists the data for a DEBUG statement. See the DEBUG statement
for more information.
Format
16 Adams/Solver
C++ Commands
Arguments
DUMP
Writes the current representation of a dataset to the Message File. This facility essentially saves
the system at the current time and also provides numeric values for functions and orientations.
Default: Off
EPRINT
Prints a block of information for each kinematic, static, or dynamic step. This information helps
you monitor the simulation process and to locate the source of the error if there is a problem. Each
step consists of two phases: 1) a forward step in time (the predictor for dynamics) and 2) the
solution of the equations of motion (the corrector for dynamics). For the first phase, Adams/Solver
prints out the following information:
The step number. This is a running count of the number of steps taken and can be used as a
Adams/Solver 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 prints out the cumulative number of iterations and a table of
information about the iterations. The cumulative number of iterations is a running count of the
iterations needed to solve the equations of motion and can be used as a measure of how many
computations Adams/Solver is performing. The table contains information about the maximum
equation error and maximum variable change for each iteration. For each iteration, Adams/Solver
prints out the following information:
The iteration number. This is one at the beginning of each step and increments by one until
close to zero. This number is an indicator of how far Adams/Solver is from a solution. This
number should decrease after every iteration.
The 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 far Adams/Solver 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 has updated the Jacobian, YES appears under the new Jacobian header.
Default: NOEPRINT
DEBUG 17
C++ Commands
JMDUMP
LIST
NOEPRINT
Suppresses the printing of three numbers at each integration step and five numbers at each
corrector iteration during an integration.
Default: NOEPRINT
NOJMDUMP
NOREQDUMP Disables the dumping of REQUEST and MREQUEST statement output at each iteration.
Default: NOREQDUMP
NORHSDUMP Disables the dumping of the YY array (state vector), the RHS array (error terms), and the DELTA
array (increment to state vector) at each iteration.
Default: NORHSDUMP
NOVERBOSE
Deactivates the output of explanations and possible remedies and the output of the names of
subroutines from which Adams/Solver sends diagnostics.
Default: NOVERBOSE
REQDUMP
Enables the dumping of the REQUEST and the MREQUEST statement output at each iteration.
Default: NOREQDUMP
RHSDUMP
Enables the dumping of the YY array (state vector), RHS array (error terms), and DELTA array
(increment to state vector) at each iteration.
Default: NORHSDUMP
VERBOSE
Outputs to the screen such additional information as the name of the subroutine from which
Adams/Solver sends each diagnostic, explanations, and possible remedies (when available). If you
do not include the VERBOSE argument, Adams/Solver outputs to the screen only basic error
messages. Whether or not you include the VERBOSE argument, Adams/Solver outputs
VERBOSE information to the Message File.
Default: NOVERBOSE
Extended Definition
Of all the arguments in the DEBUG command, EPRINT is perhaps the most useful. This section explains
the EPRINT argument in detail.
18 Adams/Solver
C++ Commands
The kinematic, dynamic, and quasi-static analyses in Adams/Solver involve the solution of the governing
equations of motion. Static analysis is the solution of the equilibrium and the initial conditions analysis
solves the assembly equations at a particular point in time.
The equations to be solved, for all these analyses, are non-linear algebraic or differential-algebraic
equations. The solution of these equations is an iterative process. The EPRINT argument enables
Adams/Solver to write out the information pertaining to the solution process in a succinct and
understandable format. All analyses that march through time consist of two distinct phases: predictor
phase and corrector phase.
Predictor Phase
In order to proceed efficiently from one time to the next, Adams/Solver uses a predictor. The predictor is
simply a means of estimating the values of the system state by looking at the past values of the state and
extrapolating the data based on a simple curve fitting algorithm.
Consider a series of values yi defined at discrete times ti
where i=1...n. A simple first order predictor that may be used to predict the value yn+1 at tn+1 is:
Figure 1
You can easily surmise from Figure 1, a first order predictor simply consists of connecting the points yn1 and yn with a straight line and extending it to time tn+1.
DEBUG 19
C++ Commands
A second order predictor, similarly, can be thought of as constructing a parabola between the points (tn2, yn-2), (tn-1, yn-1) and (tn, yn) and extending the parabola to time tn+1. The predicted value of y at tn+1
is the intersection of the vertical line t=tn+1 with this parabola. Predictors are typically polynomials
(linear, quadratic, cubic, etc.) and the order of the polynomial is frequently called the order of the solution
method.
For kinematic analyses, Adams/Solver employs a first or second order predictor. For quasi-statics, a first
order predictor is used. For dynamic analyses much higher order predictors are used. The BDF methods
(GSTIFF and WSTIFF) use up to six order predictors. ABAM on the other hand can use up to a 12th
order predictor. Sophisticated numerical analysis is employed to determine the most appropriate order of
prediction to use at any given step.
Furthermore, sophisticated curve fitting methods like Newton-Divided Difference tables are usually
employed to efficiently predict the system state. Figure 2 shows the format of the output produced by the
EPRINT argument and explains the data pertinent to the predictor phase of a dynamic analysis step.
The predictor polynomials used for the dynamic analyses interpolate previous values and the slope of the
variable at the current time to estimate the solution at the next time. Therefore, in Figure 5, a second order
polynomial that fits the solution at times t4 and t5 and the slope of the solution at time t5 is used to predict
the value of the solution at time t6.
Figure 2
Corrector Phase
20 Adams/Solver
C++ Commands
Since all predictors simply look at past values to estimate the solution at the next time, the predicted
values almost never satisfy the governing equations. They simply constitute a good initial guess for the
solution. The refining of the predicted solution to one that satisfies the governing equations is called the
correction. Since the governing equations are usually non-linear, an iterative scheme like NewtonRaphson iterations are used.
This methodology is explained for the simplest case of one non-linear algebraic equation in one variable.
Let f(x) be a smooth function of a single variable x. Given an initial guess x=x0, a solution x=xc that
satisfies f(x)=0 is desired for this simple example. The Newton-Raphson iterations may be expressed as:
for i=0 ... max_no_iterations.
1. Evaluate ri = f(xi)
2. If | ri | <
3. Evaluate
4. Calculate
5. Set
6. Set i = i+1 and go to Step 1.
The quantity ri is frequently called the residual and is a measure of the accuracy of the solution. The
quantity Ji is the partial derivative of f with respect to x, evaluated at x=xi and is commonly known as
DEBUG 21
C++ Commands
the Jacobian. The graph on the left side of Figure 3 illustrates the Newton-Raphson iterations for the onedimensional example discussed above.
Figure 3
J0 is the slope of the curve f(x) at x=x0. Through simple trigonometry it can be seen that x0-x1 = r0/J0
(i.e., x1 = x0 - r0/J0).
22 Adams/Solver
C++ Commands
Similarly,
The corrector in Adams/Solver involves the solution of many variables simultaneously. The algorithm
for one dimension is easily extended to n dimensions as follows:
Let x = {x1, x2,... xn} be a set of n variables and f = {f1(x), f2(x),... fn(x)} be a set of n non-linear equations
in the variables x.
Define:
J=
where i=1,...,n and j=1,...,n. Then the Newton-Raphson iterations for the n-dimensional case becomes:
given an initial guess x = x0 = {x01, x02,... x0n} for i=0,...,max_no_interations.
number that specifies the convergence criterion.
is a small user-defined
1. Evaluate ri = f(xi)
2. If || ri || <
3. Calculate
4. Evaluate
5. Set
DEBUG 23
C++ Commands
Newton-Raphson iterations in a dynamic analysis. The numbers on the left are the values of the
maximum residuals at each iteration. The maximum corrections are on the right. In practice, the
convergence rate of the iterations is used to determine whether a Jacobian evaluation is to be performed
or not.
Figure 4
Figure 5
The DEBUG/EPRINT option generates a table of data on the action of Adams/Solver for each of the
iterative algorithms in the various analyses. The iterative algorithm, or corrector, is used to evaluate the
variables governed by the system of non-linear equations. Table 1 contains the DEBUG/EPRINT
information for the variables associated with the mass-bearing elements (parts, point masses, and flexible
bodies) and for the corresponding equations. A combination of several equations is needed to define each
24 Adams/Solver
C++ Commands
joint and joint primitive. Table 2 includes the variables for the various joint constraints and the
corresponding equations.
Adams/Solver uses a combination of equations to represent the different types of forces. While certain
equations are specific to a particular force, others are generic to all types. The combination of variables
and corresponding equations for the forces are included in Table 3. The DEBUG/EPRINT information
for the variables and corresponding equations that define the Adams system elements is contained in
Table 4. Finally, Table 5 includes the information on the variables and equations for the remaining
miscellaneous elements in an Adams system.
Table 1
Element
type:
Parts
Code:
mx
m y
Explanation:
Translational force,
x-direction, GCS
Translational force,
y-direction, GCS
VARIABLES
Code:
Explanation:
x
Translational coordinate,
x-direction, GCS
y
Translational coordinate,
y-direction, GCS
mz
Translational force,
z-direction, GCS
vx
Velocity equation,
x-coordinate, GCS
Translational coordinate,
x-direction, GCS
vy
Velocity equation,
y-coordinate, GCS
Translational coordinate,
y-direction, GCS
vz
Velocity equation,
z-coordinate, GCS
Translational coordinate,
z-direction, GCS
Translational coordinate,
z-direction, GCS
Rotational rate, first component, 31-3 Euler angles, GCS
Rotational rate, second component,
3-1-3 Euler angles, GCS
DEBUG 25
C++ Commands
EQUATIONS
Element
type:
Code:
Code:
Explanation:
mx
Translational force,
x-direction, GCS
Translational coordinate,
x-direction, GCS
m y
Translational force,
y-direction, GCS
Translational coordinate,
y-direction, GCS
mz
Translational force,
z-direction, GCS
Translational coordinate,
z-direction, GCS
Flexible
Bodies
Explanation:
VARIABLES
M qj
q j
Time-derivative of the
coordinate
Time-derivative of the
coordinate
Time-derivative of the
coordinate
Time-derivatives of modal
coordinates for 1 j number of
flexible modes
vx
Velocity equation,
x-coordinate, GCS
Translational coordinate,
x-direction, GCS
vy
Velocity equation,
y-coordinate, GCS
Translational coordinate,
y-direction, GCS
vz
Velocity equation,
z-coordinate, GCS
Translational coordinate,
z-direction, GCS
26 Adams/Solver
C++ Commands
EQUATIONS
Element
type:
Point
Masses
Code:
Explanation:
VARIABLES
Code:
q j
qj
mx
Translational force,
x-direction, GCS
Translational velocity,
x-direction, GCS
m y
Translational force,
y-direction, GCS
Translational velocity,
y-direction, GCS
mz
Translational force,
z-direction, GCS
Translational velocity,
z-direction, GCS
Table 2
Element
type:
Code:
Explanation:
VARIABLES
Code:
Explanation:
Notes:
y Force
At Point Constraint
(z)
zi z j = 0
z Force
xi yj
xy Torque
zi xj
zx Torque
zi yj
zy Torque
zi xj
zx Torque
zi yj
zy Torque
Joint Initial
Condition,
At Point Constraint
(x)
xi xj = 0
Translational
At Point Constraint
(y)
yi yj = 0
z
Joint Initial
Condition,
Rotational
Cylindrical
Joint
Explanation:
DEBUG 27
C++ Commands
EQUATIONS
Element
type:
Convel Joint
Fixed Joint
Hooke Joint
Planar Joint
Code:
VARIABLES
Explanation:
Code:
Explanation:
Notes:
s xj
sx Force
s yj
Sliding Constraint(s,
yj)
s yj = 0
sy Force
At Point Constraint
(x)
xi xj = 0
x Force
At Point Constraint
(y)
yi yj = 0
y Force
At Point Constraint
(z)
zi zj = 0
z Force
xi yj
xy Torque
At Point Constraint
(x)
xi xj = 0
x Force
At Point
Constraint(y)
=0
y Force
yi yj
At Point Constraint
(z)
zi zj = 0
z Force
xi yj
xy Torque
zi x j
zx Torque
zi y j
zy Torque
At Point
Constraint(x)
=0
x Force
xi xj
At Point Constraint
(y)
yi yj = 0
y Force
At Point Constraint
(z)
zi zj = 0
z Force
xi yj
xy Torque
zi xj
zx Torque
28 Adams/Solver
C++ Commands
EQUATIONS
Element
type:
Code:
Explanation:
VARIABLES
Code:
Explanation:
Notes:
zi yj
zy Torque
s zj
sz Force
Rack-&Pinion Joint
Rotation/Translation
Dependency
ap Force
Reaction Force ( )
Revolute
Joint
At Point Constraint
(x)
xi xj = 0
x Force
At Point Constraint
(y)
yi yj = 0
y Force
At Point Constraint
(z)
zi z j = 0
z Force
zi xj
zx Torque
zi yj
zy Torque
Screw Joint
Rotation/Translation
Dependency
ap Force
Reaction Force ( )
Spherical
Joint
At Point Constraint
(x)
xi xj = 0
x Force
At Point Constraint
(y)
yi yj = 0
y Force
At Point Constraint
(z)
zi z j = 0
z Force
zi xj
zx Torque
zi yj
zy Torque
xi yj
xy Torque
s xj
sx Force
s yj
sy Force
At Point Constraint
(x)
xi xj = 0
x Force
Translational
Joint
Universal
Joint
DEBUG 29
C++ Commands
EQUATIONS
Element
type:
Code:
Explanation:
VARIABLES
Code:
Explanation:
Notes:
At Point Constraint
(y)
yi yj = 0
y Force
At Point Constraint
(z)
zi zj = 0
z Force
zi zj
zz Torque
At Point Constraint
(x)
xi xj = 0
x Force
At Point Constraint
(y)
yi yj = 0
y Force
At Point Constraint
(z)
zi zj = 0
z Force
xij
Equivalent to Sliding
Constraint (s, xj) s xj =
0
x Force
yij
Equivalent to Sliding
y Force
Constraint (s, yj) s yj = 0
Inplane Joint
Primitive
zij
Equivalent to Sliding
Constraint (s, zj)
z Force
Orientation
Joint
Primitive
zi x j
zx Torque
zi y j
zy Torque
xi yj
xy Torque
zi x j
zx Torque
zi y j
zy Torque
Perpendicular zi zj
Joint
Primitive
zz Torque
Atpoint Joint
Primitive
Inline Joint
Primitive
Parallel Joint
Primitive
Notes
30 Adams/Solver
C++ Commands
1. An At Point Constraint ensures that the origins of the two markers connected by this constraint
remain spatially collocated during the simulation. This constraint is made up of 3 equations for
the displacement between the two markers in the global X, Y and Z directions, respectively. For
each of the equations, a corresponding variable is introduced to represent the constraint reaction
in the X, Y and Z directions, respectively. In Table 3 a at point constraint equation in the n1
direction is denoted by At_point_constraint(n1) and the corresponding reaction force by
Reaction_force(n1).
The three At Point Constraint equations are: xi - xj = 0, yi - yj = 0, and zi - zj = 0.
2. An Angular Constraint ensures that two vectors fixed in separate mass bearing elements (PARTs,
POINT_MASSes, or FLEX_BODY) (MBE) remain mutually perpendicular during the
simulation. This constraint is represented by 1 equation. This equation requires the dot product of
the two vectors to be zero. Corresponding to this equation, a variable is introduced to represent
the constraint reaction torque. In Table 3, this constraint is denoted as Angular Constraint(v1,v2)
and its reaction torque as Reaction Torque(v1,v2).
An Angular Constraint is given as
3. A Sliding constraint is a constraint between a spanning vector and a direction fixed in a MBE. A
spanning vector is defined as the spatial vector from the origin of marker i to the origin of marker
j. A sliding constraint ensures that a spanning vector remains perpendicular to the vector fixed in
a MBE. This constraint is enforced by 1 equation that sets the dot product between the spanning
vector and the fixed vector to zero. Introduction of this equation in a model causes a variable in
the form of a constraint reaction force to be included in the model. In Table 3, the equation for
this constraint is denoted as Sliding_constraint(s,v1) and the reaction force by
Reaction_force(s,v1).
A Sliding constraint is given as
Element
type:
Code:
Explanation:
VARIABLES
Code:
Explanation:
Notes:
FIELD,
BEAM,
Dx
x-displacement equation Dx
Element x-displacement
BUSHIN
G
Dy
y-displacement equation Dy
Element y-displacement
Dz
z-displacement equation Dz
Element z-displacement
DEBUG 31
C++ Commands
EQUATIONS
Element
type:
GFORCE
NFORCE
Code:
Explanation:
VARIABLES
Code:
Explanation:
Notes:
Theta x
Theta x
Rotational displacement
about x-axis
Theta y
Theta y
Rotational displacement
about y-axis
Theta z
Theta z
Rotational displacement
about z-axis
Fx
x-direction force
equation
Fx
Fy
y-direction force
equation
Fy
Fz
z-direction force
equation
Fz
Tx
Tx
Ty
Ty
Tz
Tz
Fx
x-force equation
Fx
Fy
y-force equation
Fy
Fz
z-force equation
Fz
Tx
x-torque equation
Tx
Ty
y-torque equation
Ty
Tz
z-torque equation
Tz
Fx
x-force equation
Fx
Force in x direction
Fy
y-force equation
Fy
Force in y direction
Fz
z-force equation
Fz
Force in z direction
Tx
x-torque equation
Tx
Ty
y-torque equation
Ty
Tz
z-torque equation
Tz
32 Adams/Solver
C++ Commands
EQUATIONS
Element
type:
Code:
Translatio Length
nal
SFORCE
Explanation:
VARIABLES
Code:
Explanation:
Notes:
Length
Force
Force
Force in element
Fx
x-force equation
Fx
Force in x direction
Fy
y-force equation
Fy
Force in y direction
Fz
z-force equation
Fz
Force in z direction
Rotational Torque
SFORCE
Torque in element
Translatio Length
nal
Springda
mper
Length
L Vel
L Vel
Element velocity
Fx
x-force equation
Fx
Force in x direction
Fy
y-force equation
Fy
Force in y direction
Fz
z-force equation
Fz
Force in z direction
5
6
Rotational Torque
Springda
mper
Torque in element
VFORCE
Fx
x-force equation
Fx
Fy
y-force equation
Fy
Fz
z-force equation
Fz
VTORQU Tx
E
x-torque equation
Tx
Ty
y-torque equation
Ty
Tz
z-torque equation
Tz
Notes
5. Force equations and variables: forces are defined via explicit force equations. These equations
take the general form of:
Force_variable - Force_expression = 0
DEBUG 33
C++ Commands
where:
Force_variable denotes the force in the x, y or z direction, respectively.
Force_expression is an expression defining the force in terms of state variables and user
defined coefficients.
6. Torque equations are defined in a manner similar to force equations. These equations take the
form of:
Torque_variable - Torque_expression = 0
where:
Torque_variable denotes the torque in the element in the x, y, or z direction, respectively.
Torque_expression defines the torque in term of state variables and user defined coefficients.
7. In addition to force and torque equations, element-specific equations and variables can be used to
define force elements. Typically these equations are to define intermediate kinematic quantities
used in force and torque computation.
Table 4
Element
type:
DIFF
GSE
LSE
TFSISO
VARIABLES
Code:
Explanation:
Differential
Equation
States x
User
Variable
State xj
Outputs yj
Outputs yj
States x j
State xj
Outputs yj
State x j
Code:
Explanation:
34 Adams/Solver
C++ Commands
EQUATIONS
Element
type:
Code:
VARIABLE
Table 5
VARIABLES
Explanation:
Code:
Explanation:
Output y
Algebraic
Equation
Algebraic
Variable
VARIABLES
Elemen
t type:
Code:
COUPL
ER
f(1,2,3
)=0
Reaction force
CVCV
x Force
y Force
z Force
Ti Nj
TN
Torque
Constraint torque
variable
F-
Constraint force on
curve 1
F-
Constraint force on
curve 2
Parameter for
curve 1
Parameter for
curve 2
Explanation:
Code:
Explanation:
First derivative of
the first parameter
Second derivative
of the first
parameter
First derivative of
the second
parameter
Notes:
DEBUG 35
C++ Commands
EQUATIONS
Elemen
t type:
Code:
VARIABLES
Explanation:
Code:
Explanation:
Notes:
Second derivative
of the second
parameter
GEAR
Reaction force
MOTIO
N
-f(t)=0
Reaction force
PTCV
x Force
y Force
z Force
Perpendicular constraint
F-
Constraint force
Curve parameter
UCON
f(Q)=0
Derivative of the
curve parameter
Second derivative
Associated
reaction force
36 Adams/Solver
C++ Commands
ENVIRONMENT
Using the ENVIRONMENT command is an alternative way of setting an Adams/Solver (C++) runtime
environment variable. For example, rather than using the setenv command when working with the
Linux operating system, one may use the ENVIRONMENT command instead.
One feature of the ENVIRONMENT command is the following, the execution of this command does not
modify the operating system environment; it only affects the Adams/Solver (C++) runtime environment
for the model being run. When the simulations are finished, the original operating system environment
is left intact.
A second feature is related to the collection of environment variables one may set. Only environment
variables related to the Adams/Solver (C++) may be set. For example, you may not use this command to
set an environment variable used by other products.
Format
ENVIRONMENT NAME = c [ ,LIST ]
ENVIRONMENT NAME = c, VALUE = c [ ,LIST ]
ENVIRONMENT NAME = c, UNSET [ ,LIST ]
Arguments
NAME=c
Specifies a character string for the name of the Adams/Solver (C++) runtime environment
variable being set.
VALUE=c Specifies a character string for the value of the Adams/Solver (C++) runtime environment
variable being set. Some variables do not need a value to be specified.
The character string may be enclosed between double quotes.
UNSET
Specifies the removal of the variable from the Adams/Solver (C++) runtime environment.
LIST
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
ENVIRONMENT 37
C++ Commands
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 you define the following environment variable from a Linux shell:
% setenv MSC_ADAMS_SOLVER_BEAM_MODEL=LINEAR
Let's assume the ADM dataset file has no ENVIRONMENT statements and that the ACF
command file has the following commands:
ENV/NAME=MSC_ADAMS_SOLVER_BEAM_MODEL, VALUE=NONLINEAR
FILE/MODEL=beam_model
ENV/NAME=MSC_ADAMS_STATICS_NO_RESTORE_VELOCITIES
SIM/STA
Running the model, Adams/Solver (C++) will print the following messages:
OS-environment variable
MSC_ADAMS_SOLVER_BEAM_MODEL=LINEAR
Enforces Adams/Solver C++ to use a different beam model.
Options are LINEAR, STRING, NONLINEAR.
command: FILE/COMMAND=beam_model
command:
command: ENVIRONMENT/NAME=MSC_ADAMS_SOLVER_BEAM_MODEL,
VALUE=STRING
User-environment variable
MSC_ADAMS_SOLVER_BEAM_MODEL=STRING
Enforces Adams/Solver C++ to use a different beam model.
Options are LINEAR, STRING, NONLINEAR.
* Overwrites a previous definition.
command:
command: file/model=beam_model
38 Adams/Solver
C++ Commands
--------------------------------------------------------------|
Model Title
|
|==============================================================|
|
|
|
Beam model
|
|
|
---------------------------------------------------------------command:
command: env/name = MSC_ADAMS_STATICS_NO_RESTORE_VELOCITIES
User-environment variable
MSC_ADAMS_STATICS_NO_RESTORE_VELOCITIES
Enforces Adams/Solver C++ not to restore initial velocities after
a STATIC analysis at time t=0.
Running the above ACF command file, the following message is printed:
command: environment/name=MSC_ADAMS_SOLVER_BEAM_MODEL,
value=STRING
---- START: ERROR ---Environment variable MSC_ADAMS_SOLVER_BEAM_MODEL must be set
before the model is constructed.
Command will be ignored.
To avoid this problems do one of these:
(1) Set the env variable in the operating system.
(2) Set the env variable in the *.adm file.
(3) Issue the ENV/ command before the FILE/MODEL command.
---- END: ERROR ----
ENVIRONMENT 39
C++ Commands
Adams/Solver (C++) prints an error message and ignores the setting of the the
MSC_ADAMS_SOLVER_BEAM_MODEL because the model has already been constructed.
Caution:
40 Adams/Solver
C++ Commands
EQUILIBRIUM
An EQUILIBRIUM command redefines and/or lists the data for an EQUILIBRIUM statement. If an
EQUILIBRIUM statement is not included in the Adams/Solver model and an EQUILIBRIUM command
is not issued before a static or quasi-static simulation, Adams/Solver (C++) uses the default values for
ALIMIT, ERROR, IMBALANCE, MAXIT, PATTERN, STABILITY, and TLIMIT for the analysis.
Format
EQUILIBRIUM/
,ERROR = r
,IMBALANCE = r
,MAXIT = i
,STABILITY = r
,TLIMIT = r
[ ,LIST ]
,METHOD =i
,ATOL = r
,RTOL = r
,MAXITL = i
,ETAMAX = r
,ETA = r
ALIMIT = r
DEFAULT
{}
[[ ]]
EQUILIBRIUM 41
C++ Commands
Arguments
ALIMIT=r
DEFAULT
ERROR=r
IMBALANCE=r
LIST
MAXIT=i
PATTERN=c1[:...:c10] Specifies as many as ten character strings that together establish the pattern
for evaluating the Jacobian matrix during the modified Newton-Raphson
iteration. For each iteration, T or TRUE indicates that Adams/Solver (C++)
evaluates the Jacobian and F or FALSE indicates that Adams/Solver (C++)
does not evaluate the Jacobian. Thus, cj determines whether or not
Adams/Solver (C++) evaluates the Jacobian at the jth iteration. If necessary,
Adams/Solver (C++) repeats the pattern of evaluations until it reaches the
maximum number of iterations (MAXIT). The number of Ts or TRUEs and
Fs or FALSEs together must be at least one and no more than ten.
42 Adams/Solver
C++ Commands
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.>
Range: STABILITY >0
TLIMIT=r
EQUILIBRIUM 43
C++ Commands
METHOD=i
Specifies the option which determines the static solver method to be used for
equilibrium solution.
1. ORIGINAL, for running only the ORIGINAL Solver
2. ADVANCED, runs, in order, the following methods until one shows
progress:
a. ORIGINAL
b. ORIGINAL+Krylov
c. ORIGINAL+UMF
d. Newton+Krylov
e. Tensor-Krylov block-3
f. Tensor-Krylov block-2+
3. AGGRESSIVE, runs, in order, the following methods until one
shows progress:
a. ORIGINAL
b. ORIGINAL+Krylov
c. ORIGINAL+UMF
d. Newton+Krylov
e. Tensor-Krylov block-3
f. Tensor-Krylov block-2+
g. Broyden-Armijo
h. Trust-Region
4. ALL, runs, in order, all the available methods, until one shows
progress:
a. ORIGINAL
b. ORIGINAL+Krylov
c. ORIGINAL+UMF
d. Newton+Krylov
e. Tensor-Krylov block-3
f. Tensor-Krylov block-2+
g. Broyden-Armijo
h. Trust-Region
i. Hooke-Jeeves
Default: ORIGINAL
44 Adams/Solver
C++ Commands
ATOL
RTOL
MAXITL
Specifies the maximum number of allowed inner loops in all the solvers.
ORIGINAL, ORIGINAL+Krylov and ORIGINAL+UMF solver methods
ignore this parameter. For Hooke-Jeeves method, allowed budget of function
evaluations is set to MAXITL*N, where N is the size of the problem (number
of unknowns).
Default: 40
Range: > 0
ETAMAX
Specifies the maximum threshold for the error tolerance of the linear Krylov
solver (for Newton+Krylov and Tensor-Krylov methods) that solves the
linear systems required by Krylov algorithm. Maximum error tolerance for
residual in inner iteration. The inner iteration terminates when the relative
linear residual is smaller than eta*| F(x_c) |. eta is determined by the modified
Eisenstat-Walker formula if etamax > 0. If etamax < 0, then eta = |etamax|
for the entire iteration.
Default: 0.9
Range: 0.0 < ETAMAX < 1.0
ETA
Specifies the initial residual tolerance for the linear Krylov Solver for TensorKrylov method. The Tensor-Krylov ETA parameter is maintained adaptively
by the Krylov algorithm but ETA is the indicated starting value, while
ETAMAX is the maximum threshold for ETA.
Default: 1.0e-4
Range: 0.0 < ETA < 1.0
Specifies the dimensionless radius of the trust-region for Trust-region
method. The smaller the value, the more the refinement of Trust-region
solution (hence more work).
Range: 0.0 < ETA < 0.25
Extended Definition
For an extended definition on the EQUILIBRIUM command and corresponding tips, cautions, and
examples, refer to the EQUILIBRIUM statement.
See other Analysis parameters available.
FIELD 45
C++ Commands
FIELD
The FIELD command redefines and/or lists the data for a FIELD statement. You cannot redefine the I and
the J markers, but you can redefine any other argument values.
Format
46 Adams/Solver
C++ Commands
Arguments
CMATRIX=r1,...,r36
CRATIO=r
FORCE=r1,...,r6
FUNCTION=USER(r1[,...,r30]) Respecifies the USER parenthetical list for a nonlinear field. Follow
FUNCTION with an equal sign, the character string USER, and the
values (r1[,...,r30]) that you want Adams/Solver (C++) to pass to the
FIESUB user-written subroutine. The FUNCTION argument is
used, it must either be the last argument in the FIELD command or
be followed by a backslash (\).
KMATIX=r1,...r36
LENGTH=r1,...r6
LIST
ROUTINE=libname::subname
FIELD 47
C++ Commands
Tip:
Caution:
Finite element analysis programs can give the values for CMATRIX and KMATRIX.
The three rotational displacements (a, b, and c) that define the field are not Euler
angles. They are the projected angles of the I marker with respect to the J marker.
Adams/Solver (C++) measures them about the x-, y-, and z-axis of the J marker.
For the constitutive equations to be accurate, at least two of the rotations (a, b, c)
must be small. That is, two of the three values must remain smaller than 10
degrees. In addition, if a becomes greater than 90 degrees, b becomes erratic. If b
becomes greater than 90 degrees, a becomes erratic. Only c can become greater
than 90 degrees without causing convergence problems. For these reasons, it is
best to define your field such that angles a and b (not a and c and not b and c)
remain small.
Adams/Solver (C++) applies the component translational and rotational forces for
forces. However, when massless beams are being defined, you may want to use the
BEAM command. It requires only six input values to compute the thirty-six values
for the KMATRIX argument (see the BEAM statement).
The K and C matrices must be positive semidefinite. In other words:
48 Adams/Solver
C++ Commands
FILE
The FILE command loads a new model from a dataset file, or executes commands from a Command file.
Format
Arguments
COMMAND=c
Specifies the file name of a file that contains Adams/Solver (C++) commands.
The file name may include the directory on operating systems that support path
names, such as UNIX. Adams/Solver (C++) assumes an .acf file extension if
you do not specify one. Because the COMMAND argument and value can be
at most eighty characters long, the file name and path name are limited from
seventy-two characters (if you do not abbreviate COMMAND=) to seventy-six
characters (if you abbreviate COMMAND= to COM=).
Range: All printable characters except !, ;, , and &
MODEL=c
OUTPUT_PREFIX=c Optionally, specifies a new file base name for output files that Adams/Solver
(C++) generates by subsequent simulations. The file extensions conform to
standard Adams/Solver (C++) naming conventions. If you do not specify an
OUTPUT_PREFIX argument, Adams/Solver (C++) defaults to the basename
of the MODEL argument. Because the OUTPUT_PREFIX argument and value
can be at most eighty characters long, the basename and path are limited from
sixty-six characters (if you do not abbreviate OUTPUT_PREFIX) to seventysix characters (if you abbreviate OUTPUT_PREFIX to OUT=).
Range: All printable characters except !, ;, , and &
FILE 49
C++ Commands
Extended Definition
The FILE command either restarts Adams/Solver (C++) with a new model, or a executes a set of
commands from a file.
The MODEL argument specifies a new dataset (.adm) file. Adams/Solver (C++) closes any output files
from a previous simulation, and then completely restarts by setting the simulation time to zero and
reading the new model. Next, Adams/Solver (C++) prompts you for a new command, just as if
Adams/Solver (C++) had read the model when first started. By default, the output files use the same base
name as the model file. The optional OUTPUT_PREFIX argument specifies a different base name, if
needed. An OUTPUT_PREFIX argument only changes the names of the output files (files with .res, .req,
and .gra extensions). A message file with a new name is not created. Every message from a single
Adams/Solver (C++) session is logged in the same message file.
The COMMAND argument specifies a file containing Adams/Solver (C++) commands. Adams/Solver
(C++) reads and executes the commands in the file. If the FILE command was interactive, Adams/Solver
(C++) returns to interactive input when the command file is exhausted. If the FILE command was in a
command file itself, Adams/Solver (C++) returns to reading commands from that file. Command files
can contain other FILE commands.
Tip:
within one Adams/Solver (C++) run. This may be quicker and more convenient
than invoking Adams/Solver (C++) separately for each simulation.
Although the FILE command may be used to repeatedly reload the same model,
the SAVE and RELOAD combination is much quicker than rereading the original
dataset.
Caution:
The COMMAND argument does not automatically load a new model, it executes
commands just as they appear in the specified file. Unlike a Command file used to
start Adams/Solver (C++), a Command file read here must start with an
Adams/Solver (C++) command, not input and output file names.
Since Adams/Solver (C++) does not support TIRE 5.2.1, the TIRE_LIST_FILE is
not supported.
Examples
FILE/MODEL=TURN45
This FILE command loads dataset TURN45.ADM. The output files default to TURN45.REQ,
TURN45.GRA, etc.
FILE/MODEL=TURN45,OUTPUT_PREFIX=TEST2
This FILE command also loads dataset TURN45.ADM, but the output files are TEST2.REQ,
TEST2.GRA, etc.
50 Adams/Solver
C++ Commands
FLEX_BODY 51
C++ Commands
FLEX_BODY
The FLEX_BODY command redefines and/or lists the data for the FLEX_BODY statement that defines
linear elastic body.
Format
Arguments
52 Adams/Solver
C++ Commands
FRICTION
The FRICTION command defines parameters that enable joint friction forces on translational, revolute,
cylindrical, hooke, universal, and spherical joints.
Note:
Format
Frictional forces and torques are computed by Adams/Solver (C++) using a friction model
that supports dynamic frictions and stiction.
FRICTION 53
C++ Commands
Arguments
BALL_RADIUS=Rb
Defines the radius of the ball in a spherical joint for use in friction-force and
torque calculations.
Range: BALL_RADIUS > 0
STICTION_TRANSITION_VEL
OCITY=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.
Range: STICTION_TRANSITION_VELOCITY > 0
EFFECT={ALL[[STICTION,
SLIDING]]}
Defines the frictional effects included in the friction model. Stiction is staticfriction effect, while sliding is dynamic-friction effect. Excluding stiction in
simulations that dont require it can greatly improve simulation speed.
FRICTION_FORCE_PRELOAD= Defines the joints preload frictional force, which is usually caused by
r
mechanical interference in the assembly of the joint.
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.
Range: FRICTION_ARM > 0
INACTIVE=STATIC
INITIAL_OVERLAP=Xs0
Defines the input forces to the friction model. By default, all user-defined
preloads and joint-reaction force and moments are included. You can
customize the friction-force model by limiting the input forces you list in the
statement.
Joint type: (Available inputs:)
Translational (PRELOAD, REACTION_FORCE, BENDING_MOMENT,
TORSIONAL_MOMENT)
Cylindrical, Revolute, Universal, Hooke (PRELOAD,
REACTION_FORCE, BENDING_MOMENT)
Spherical (PRELOAD, REACTION_FORCE)
54 Adams/Solver
C++ Commands
JOINT=id
MAX_STICTION_DEFORMATI
ON=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.
Range: MAX_STICTION_DEFORMATION > 0
MU_DYNAMIC=r
Defines the coefficient of dynamic friction during the sliding regime. The
magnitude of the frictional force is the product of MU_DYN and the
magnitude of the normal force in the joint, for example:
Friction force magnitude, F = N
where = MU_DYNAMIC and N = normal force
The dynamic frictional force acts in the opposite direction of the velocity of the
joint.
Range: MU_DYNAMIC > 0
LIST
MU_STATIC=r
Defines the coefficient of static friction in the joint. The magnitude of the
frictional force is the product of a function of MU_STATIC, MU_DYNAMIC,
and the creep, times the magnitude of the normal force in the joint, for
example:
Friction Force Magnitude, F = N
where = (MU_STATIC, MU_DYNAMIC, creep) and N = normal force
The static frictional force acts to oppose the net force or torque along the
degrees of freedom of the joint.
Range: MU_STATIC > 0
FRICTION 55
C++ Commands
OVERLAP_DELTA={INCREAS
E, DECREASE, CONSTANT}
the positive direction along the J Marker; the slider moves to be within the
joint.
DECREASE indicates that the overlap decreases with positive translation
Defines the radius of the pin for a revolute, cylindrical, Hooke, or universal
joint.
Range: PIN_RADIUS > 0
REACTION_ARM=Rn
Defines the effective moment arm of the joint-reaction torque about the
translational joints axial axis (the z-direction of the joints J marker). This
value is used to compute the contribution of the torsional moment to the net
frictional force.
Range: REACTION_ARM > 0
FRICTION_TORQUE_PRELOA
D=r
Defines the preload friction torque in the joint, which is usually caused by
mechanical interference in the assembly of the joint.
Range: FRICTION_TORQUE_PRELOAD > 0
I_YOKE
J_YOKE
For an extended definition on the statement associated with this command, see the FRICTION statement.
Caution:
Examples
FRICTION/102, INPUTS=NONE
56 Adams/Solver
C++ Commands
GCON 57
C++ Commands
GCON
The GCON (general constraint) command lists all the data for a GCON statement.
Format
GCON/id [,LIST]
[ ] Optionally select the item
Arguments
LIST
Examples
GCON/10, LIST
This GCON command lists all the data for GCON 10.
See other Constraints available.
58 Adams/Solver
C++ Commands
GFORCE
The GFORCE command redefines and/or list the data for a GFORCE statement that defines a force
element that consists of three orthogonal translational force components and three orthogonal torque
components.
Format
Arguments
FY=e
FZ=e
GFORCE 59
C++ Commands
I=id
JFLOAT=id
LIST
RM=id
ROUTINE=libname::subname
TX=e
TY=e
TZ=e
Extended Definition
The GFORCE command lists or redefines a force element that consists of three mutually orthogonal
translational force components and three orthogonal torque components. You can alter one or both points
of force and torque application, change the force reference marker, and change the force and torque
function expressions or the parameters passed to the GFOSUB user-written subroutine.
60 Adams/Solver
C++ Commands
After a change to a GFORCE, Adams/Solver (C++) reprocesses the model at the next SIMULATE
command, as if it had just been read in from the dataset. During the reprocessing, Adams/Solver (C++)
checks the entire model for consistency, reinitializes user subroutines, and recomputes initial conditions.
While checking, Adams/Solver (C++) verifies that the model is still valid with the new GFORCE. If, for
example, the GFORCE function expression refers to an inactive element, Adams/Solver (C++) issues an
error.
Adams/Solver (C++) also reinitializes all user subroutines to re-establish functional dependencies. For
each element that refers to a user-written subroutine, Adams/Solver (C++) calls the user-written
subroutine with IFLAG set to true.
Prior to the actual simulation, Adams/Solver (C++) computes initial conditions for the model. If this is
the first simulation, Adams/Solver begins with the positions and velocities specified in the dataset. If you
ran a previous simulation, Adams/Solver begins with the final displacements and velocities.
Adams/Solver (C++) then adjusts the initial conditions to ensure that they are consistent with the model
constraints. If this is the first simulation, Adams/Solver (C++) also maintains any user supplied joint
initial-conditions and positions specified as EXACT.
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 user-defined functions FX, FY, FZ, TX, TY, and TZ should be smooth, continuous, and
single-valued. These conditions make the solution process very effective.
Examples
GFORCE/1, I=8, JFLOAT=6, RM=7, LIST, &
FY = 0/ &
FZ = 0/ &
TY = 0/ &
TZ = 0
This GFORCE command redefines and lists the general, six-component force acting between fixed
Marker 310 and floating Marker 9910. The force and torque components FY, FZ, TY, and TZ are set to
zero along the y and z axes of the reference marker, which is Marker 310. Adams/Solver (C++)
superimposes floating Marker 9910 on Marker 310 and applies the FX and TX reaction force and torque
at that point.
See other Forces available.
HELP 61
C++ Commands
HELP
The HELP command opens the online help for Adams/Solver.
To navigate through the help:
Select a topic from the left.
62 Adams/Solver
C++ Commands
IC
The IC command redefines and/or lists the data for an IC statement. If you issue neither the IC command
nor statement in an Adams/Solver (C++) session, Adams/Solver (C++) uses the default values for
AERROR, ALIMIT, AMAXIT, APATTERN, ERROR, MAXIT, PATTERN, TLIMIT, and VERROR
when finding initial conditions.
Format
IC 63
C++ Commands
Arguments
AERROR=r
ALIMIT=r
AMAXIT=i
APATTERN=c1[:...:c10] Respecifies 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 is to evaluate the Jacobian at
the jth iteration. If necessary, Adams/Solver (C++) repeats the pattern of
evaluation until it reaches the maximum number of iterations (AMAXIT).
The number of T's or TRUEs and Fs or FALSEs together must be at least
one and no more than 10.
DEFAULT
ERROR
64 Adams/Solver
C++ Commands
LIST
MAXIT=i
PATTERN=c1[:...:c10]
TLIMIT=r
VERROR=r
Tip:
Use the ALIMIT and TLIMIT arguments to limit the increments of the displacement
variables if Adams/Solver (C++) fails to converge to a solution or converges to an
undesirable configuration. This lessens the position change on successive iterations, and
tends to keep the solution closer to the initial configuration.
INFO 65
C++ Commands
INFO
The INFO command lists the vector components for the displacement, velocity, or acceleration of one
marker with respect to another or displays force values at the current simulation time. This command
resolves components in the ground coordinate system (GCS) or in another specified reference frame.
Format
Arguments
ACCELERATION Lists the accelerations of the I marker minus the accelerations of the J marker.
Adams/Solver (C++) reports translational accelerations in units of displacement
per time squared and rotational accelerations in units of radians per time squared.
DISPLACEMENT Lists the x, y, z, psi, theta, and phi displacements of the I marker with respect to
the J marker. Adams/Solver (C++) reports translational displacements in units of
displacement and rotational displacements in units of radians.
FORCE
Lists the components for the force at the I marker. A BEAM, BUSHING, CVCV,
FIELD, GFORCE, JOINT, JPRIM, MOTION, NFORCE, PTCV, SFORCE,
SPRINGDAMPER, VFORCE, or VTORQUE statement can define the force.
You should include both the I and the J arguments to measure the action-reaction
force(s) between two markers (I, J). You should include the I argument and either
give zero as the J argument or omit the J argument altogether to measure the
action-only force(s) at a marker (I).
I=id
Specifies the identifier of the fixed or floating marker for which Adams/Solver
(C++) is to measure displacements, velocities, accelerations, or action forces.
J=id
Specifies the identifier of the fixed or floating marker with respect to which
Adams/Solver (C++) is to measure the displacements, velocities, or accelerations
of the I marker, or the identifier of the marker for which Adams/Solver (C++) is
to measure reaction forces.
66 Adams/Solver
C++ Commands
RM=id
VELOCITY
Lists the velocities of the I marker minus the velocities of the J marker.
Translational velocities are given in units of displacement per time. Rotational
displacements are given in units of radians per time.
Examples
INTEGRATOR 67
C++ Commands
INTEGRATOR
The INTEGRATOR command lets you redefine data in the INTEGRATOR statement.
Format
68 Adams/Solver
C++ Commands
Arguments
ALPHA = r
BETA = r
2
-------------------4
original
CORRECTOR =
modified
Specifies the corrector algorithm used with the stiff integrators GSTIFF
or WSTIFF. 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 how they assess when the
corrector iterations have converged.
CORRECTOR=original - Specifies the corrector available in
INTEGRATOR 69
C++ Commands
DEFAULT
ERROR=r
Specifies the relative and absolute local integration error tolerances that
the integrator must satisfy at each step. For BDF integrators,
Adams/Solver (C++) monitors the integration errors in the
displacement and state variables that the other differential equations
(DIFFs, LSEs, GSEs, and TFSISOs) define. The larger the ERROR, the
greater the error/step in your solution.
Note that the value for ERROR is units-sensitive. For example, if a
system is modeled in mm-kg-s units, the units of length must be in mm.
Assuming that all the translational states are larger than 1mm, setting
ERROR=1E-3 implies that the integrator monitors all changes of the
order of 1 micron.
The error tolerances (e) are enforced as:
||Yc - Y|| < MAX (e,e * ||Y||)
where Yc is the column matrix of computed values for the unknowns,
Y. The symbol || || indicates the root-mean-square of the array of
numbers.
Range: ERROR > 0
GAMMA
2
-------------------4
70 Adams/Solver
C++ Commands
GSTIFF
HHT
HINIT=r
HMAX=r
Defines the maximum time step that the integrator is allowed to take.
Default: When setting the argument INTERPOLATE = ON, the
integration step size is limited to the value specified for HMAX, but if
HMAX is not defined, no limit is placed on the integration step size. If
INTERPOLATE = OFF, the maximum step size is limited to the output
step.
Range: 0 < HMIN < HINIT < HMAX
HMIN=r
Defines the minimum time step that the integrator is allowed to take.
Default:
1.0E-6*HMAX for GSTIFF, WSTIFF, and I3
Machine precision for GSTIFF, WSTIFF, SI2, and for HHT and
Newmark
Range: 0 < HMIN < HINIT < HMAX
ON
INTERPOLATE =
OFF
I3
INTEGRATOR 71
C++ Commands
KMAX=i
Indicates the maximum order that the integrator can use. The order of
integration refers to the order of the polynomials used in the solution.
The integrator controls the order of the integration and step size, and
therefore, controls the local integration error at each step so that it is less
than the error tolerance specified.
Note:
MAXIT=i
Specifies the maximum number of iterations allowed for the NewtonRaphson iterations to converge to the solution of the nonlinear
equations. The corrector uses Newton-Raphson iterations.
MAXIT should not be set larger than 10. This is because round-off
errors increase when a large number of iterations are taken. This can
cause an error in the solution.
Range: MAXIT > 0
NEWMARK
PATTERN=c1[:...:c10]
Indicates the pattern of trues and falses for re-evaluating the Jacobian
matrix for Newton-Raphson. A value of true (T) indicates that
Adams/Solver (C++) is evaluating a new Jacobian matrix for that
iteration. A value of false (F) indicates that Adams/Solver (C++) is
using the previously calculated Jacobian matrix as an approximation of
the current one.
Note:
72 Adams/Solver
C++ Commands
SI2
WSTIFF
HASTIFF
SI1
INTEGRATOR 73
C++ Commands
Extended Definition
For a detailed definition, cautions, tips, and more, see the Extended Defintion in the INTEGRATOR
statement.
Caution:
Examples
INTEGRATOR/SI2,GSTIFF, ERROR=1.0E-4, HINIT=1.0E-6, LIST
This command specifies a dynamic simulation using the SI2 equation formulation combined
with the GSTIFF integrator.
The integrator has an error limit of 1.0E-4 and overrides the default value of 1.0E-3.
HINIT =1.0E-6 specifies an initial timestep of 1.0E-6, which overrides the default of 1/20th
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.0E-6.
The maximum step size the integrator is to take is 1.0E-3.
74 Adams/Solver
C++ Commands
JOINT
The JOINT command lists all the data for a JOINT statement.
Format
JOINT/id [,LIST]
[ ] Optionally select the item
Arguments
LIST
Examples
JOINT/10, LIST
This JOINT command lists all the data for Joint 10.
See other Constraints available.
KINEMATICS 75
C++ Commands
KINEMATICS
The KINEMATICS command redefines and/or lists the data for a KINEMATICS statement. If you issue
neither the KINEMATICS command nor statement in an Adams/Solver (C++) session, Adams/Solver
(C++) uses the default values for AERROR, ALIMIT, AMAXIT, APATTERN, ERROR, MAXIT,
PATTERN, and TLIMIT when performing a kinematic analysis.
Format
76 Adams/Solver
C++ Commands
Arguments
AERROR=r
ALIMIT=r
AMAXIT=i
APATTERN=c1[:...:c10] Respecifies 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 (C++) is to evaluate the
Jacobian at the jth iteration. If necessary, Adams/Solver (C++) repeats the
pattern of evaluations until it reaches the maximum number of iterations
(AMAXIT). The number of Ts or TRUEs and Fs or FALSEs together
must be at least one and no more than 10.
DEFAULT
ERROR=r
KINEMATICS 77
C++ Commands
HMAX=r
Defines the maximum time step that the KINEMATICS solution is allowed
to take.
When performing kinematic simulations on systems with parts that are
rotating at very high speeds (at or more than one revolution per time step),
it is possible for the kinematic to fail or provide inaccurate results because
of lack of information on the system between output step solutions. The
HMAX value can be used to limit the time between solution steps without
having to specify a large number of output steps.
LIST
MAXIT=i
PATTERN=c1[:...:c10]
TLIMIT=r
Tip:
Using the PATTERN argument to request less frequent evaluations of the Jacobian
matrix may decrease the computation time, thereby decreasing the cost and
improving the response time. However, it could also have the opposite effect since
more iterations may be required to reach the solution with a stale Jacobian matrix.
Use the ALIMIT and TLIMIT arguments to limit the increments of the
78 Adams/Solver
C++ Commands
LINEAR
Note:
LINEAR 79
C++ Commands
Examples
Applications
Eigen analysis application
State matrices output
Appendix
1. General
You can use the LINEAR command to linearize Adams models. Linearized Adams models can be
represented by complex valued eigendata (eigenvalues, mode shapes) or by a state-space representation
in the form of real-valued state matrices. Two state-space representations are possible, the ABCD
standard representation and the MKB Nastran representation. Moreover, the LINEAR command can be
used to export the linearized Adams model into an equivalent Nastran bulk data deck.
Adams/Solver (C++) uses a state-of-the-art condensation scheme to reduce an Adams model to a
minimal linear form for efficient solution. (For more information, see On an approach for the
linearization of the Differential Algebraic Equations of Multi-body Dynamic, D. Negrut and J. L. Ortiz.
Fifth ASME International Conference on Multibody Systems, Nonlinear Dynamics and Control, ASME
2005.)
The LINEAR command has four main options designed to provide important insight into the dynamic
behavior of the model. For instance, the LINEAR/EIGENSOL option can be used to assess the stability
of the model. Stability properties of the model have a direct relationship to the real part of the complex
eigenvalues. Eigenvalues with positive real parts represent unstable modes of the system, while those
with negative real parts represent stable modes. If bounded inputs to the system cause excitation of an
unstable mode, the system produces an unbounded response. On the other hand, bounded excitation of a
stable mode results in a bounded response. Eigenvalues computed by Adams/Solver (C++) can be plotted
on a real-imaginary plot and the mode shapes can be animated using Adams/View. In addition to
verifying stability, eigendata is used for validating implementation of models with eigendata from other
modeling approaches or experimental data. This is especially true if an elastic or control sub-system
model has been implemented in Adams/Solver (C++). If you issue the LINEAR/EIGENSOL option,
Adams/Solver (C++) computes the model eigendata and reports the model eigenvalues to the workstation
screen. If the results outputs are enabled, eigendata is also written into the results (.res) file, and may be
taken to Adams for further processing.
Both the LINEAR/STATEMAT and the LINEAR/MKB options output a state-space representation in a
form suitable for importation into matrix manipulation and control design packages such as MATRIXx
and MATLAB (for more information see the Xmath Basics Guide, 1996, Integrated Systems Inc., Santa
Clara, CA and Matlab User's Guide, The MathWorks Inc., Natick, Massachusetts). A state-space model
representation is suitable for obtaining frequency response of the Adams model, verifying model control
properties (controllability and observability), and designing feedback controllers for Adams models. If
you issue the LINEAR/STATEMAT or LINEAR/MKB command, Adams/Solver (C++) computes the
state matrices for the model and writes them to a user-specified file or files. If enabled, state matrices are
also written out to the Results file.
80 Adams/Solver
C++ Commands
Option LINEAR/EXPORT is used to export the linearized model into an equivalent Nastran model.
Using this option, Adams/Solver (C++) creates an ASCII file containing a Nastran bulk data deck. Two
sub options are available: a "blackbox" sub option equivalent to a state space representation, and a
"whitebox" sub option in which an element-to-element export is performed. Using the "whitebox" sub
option, rigid Adams PARTS are exported as CONM2 cards, Adams JOINTS are exported as RJOINT
cards or as sets of MPC cards, etc. Both the "blackbox" and "whitebox" sub options honor a configuration
file which is used to fine tune the exporting process. The configuration file can be used to custom the
exported model. See below for current limitations of the LINEAR/EXPORT option.
2. Definition
The LINEAR command linearizes the nonlinear system equations of motion and provides four basic
capabilities: an eigensolution, a standard state-space matrix calculation, a Nastran-specific state space
calculation, and an export to a Nastran bulk data deck.
The eigensolution option determines natural frequencies and mode shapes while the state space
calculations compute the linear state space matrices that describe the linearized mechanical system.
You may issue this command following initial conditions, a static or a transient analysis. Depending on
the options you specify, the results of the command are reported on the screen and written to the Message
file, the Results file, and, if required, the user-specified files.
The LINEAR/EXPORT option has been modified to support all types of operating points (static or
dynamic). However, matching eigenvalues with Nastran can be obtained using static operating points
only. Kinematic models (zero degrees of freedom) can only be exported using the WHITEBOX option.
For theoretical details on the linearization algorithm, see the white paper in Knowledge Base Article
12721.
LINEAR 81
C++ Commands
3. Format
82 Adams/Solver
C++ Commands
4. Arguments
CONFIG=c
COORDS=i1[,i2]
DISSIPAT=i1[,i2]
EIGENSOL
EXPORT
LINEAR 83
C++ Commands
FILE=c
(C++) is to output the state matrices. Presently, two software formats are
FORMAT =
supported: MATRIXX (FSAVE format) and MATLAB (ASCII flat file
MATLAB
format). This argument is a qualifier for the MKB or STATEMAT option.
Type: Optional with MKB or STATEMAT
KINETIC=i1[,i2]
MKB
NODAMPIN
84 Adams/Solver
C++ Commands
NOVECTOR
PINPUT=id
POUTPUT=id
PSTATE=id
RM=id
STATEMAT
LINEAR 85
C++ Commands
STRAIN=i1[,i2]
Specifies that a table of strain energy distribution for mode numbers in the
range i1 to i2 be computed and output. If i2 is not specified, Adams/Solver
(C++) produces the table of strain energy distribution for mode number i1
only.
Range: i1 > 1, i2 > i1
Type: Optional with EIGENSOL; mutually exclusive with NOVECTOR
WHITEBOX
TYPE =
BLACKBOX
Specifies the type of Nastran bulk data deck export. Using the
BLACKBOX option Adams/Solver (C++) exports the state space
matrices MKB using DMIG cards. Using the WHITEBOX option
Adams/Solver (C++) exports the model using an element-to-element
translation.
Type: Required with EXPORT.
5. Extended Definition
If you specify the EIGENSOL option, Adams/Solver (C++) computes the A state matrix of the Adams
model and it performs an eigenanalysis. Eigendata results from the solution of a generalized eigenvalue
problem of the form:
Az=z
where:
z is the eigenvector.
is the eigenvalue.
A is the state matrix computed by Adams/Solver (C++) from the Adams model.
86 Adams/Solver
C++ Commands
The standard approach to compute the state matrix (A) consists of a direct linearization of the equations
of motion, hence the state variables (x) are a subset of the default coordinates used to build the equations
of motion. However, the default state variables may not be the correct choice. In rotational systems
(turbines, helicopter blades, etc.), you may prefer using relative coordinates or user-defined coordinates
instead of the default coordinates. The RM and PSTATE options (see Using the RM Option) allow you to
specify user-defined coordinates, which results in better eigensolution computations.
Once the eigensolution is completed, the eigenvector is mapped to the mode shape prior to output to the
results (.res) file.
If you specify the NODAMPIN argument, Adams/Solver (C++) does not include the velocity-dependent
terms in forces nor does it include velocity-dependent terms in the VARIABLE statements in the A
matrix. Using this option may be beneficial in determining the underlying modes for a system with
critical or greater than critical damping.
If you specify the NOVECTOR argument, Adams/Solver (C++) computes only the eigenvalues and not
the mode shapes. Adams/Solver (C++) reports on the screen eigenvalues that result from the
eigensolution. If you use the RESULTS statement to enable output to the results file (.res) in the
Adams/Solver (C++) dataset, the eigenvalues and mode shapes (if computed) will be written to this file.
The results file may be taken to a postprocessor, such as Adams/View, for further processing.
All eigenvalues are normalized to be in cycles/second. The imaginary component of the eigenvalue
represents the oscillatory behavior of the mode and the real component the damping characteristic.
The model eigenvalues are reported to the workstation screen. In general, the eigenvalues are complex
values, made up of real and imaginary components. The imaginary component represents the damped
natural frequency
component in the eigenvalue - in other words, the damped natural frequency is zero whenever the
damping ratio is 1 or greater.
The undamped natural frequency and damping ratio obeys the following equations:
n =
( r2 + i2 )
r
= -----n
where:
LINEAR 87
C++ Commands
d = n ( 1 2 )
The damped natural frequency is the actual frequency at which the system is oscillating for that mode.
5.1.2 Using the RM option
By default (if no RM option and no PSTATE option are used), Adams/Solver (C++) uses the global
displacements and global rotations about the ground origin of all PARTS to build the linearized equations
of motion. The complete set of defaults coordinates is shown in the next table.
Default linearization coordinates (no RM, no PSTATE options used)
Global displacements of the BCS of all PARTS, FLEX_BODY and POINT_MASS relative
Note:
BCS stands for an internal MARKER located at the Body Coordinate System which is the
location specified by the QG and REULER arguments of the PART, FLEX_BODY and
POINT_MASS statements.
The default linearization coordinates are not a minimal set. Therefore, Adams/Solver (C++) selects an
optimal subset x (the state variables) and linearizes the system in terms of those variables. As mentioned
above, the default coordinate selection may not be the best choice in cases of rotating or accelerating
systems. The first tool to customize the state variables is the RM option. The RM option sets the ADAMS
id of a MARKER, for example:
LINEAR/EIGENSOL, RM=b
88 Adams/Solver
C++ Commands
MARKER/b may be located on a rotating hub or accelerating subsystem of the model. When the option
RM is used, the default coordinates are the following:
Default linearization coordinates using RM=b
Relative displacements of the BCS of all PARTS, FLEX_BODY and POINT_MASS relative
namely AX(BCS,b), DY(BCS,b) and DZ(BCS,b). There is one exception: for the PART that
owns MARKER/b, the default coordinates are AX(GROUND,b), AY(GROUND,b) and
AZ(GROUND,b).
All active modal coordinates in FLEX_BODY.
All states in LSE, TFSISO, LSE and GSE objects.
All states in DIFF objects.
The RM option is useful in linearizing helicopter blades, turbines, etc. If no RM option is used, the
computed frequencies reflect a dependency on the rotation frequency, hiding the frequencies of interest.
When the RM option is used, Adams/Solver (C++) selects a subset x of the coordinates shown in the table
above to perform the linearization.
For example, Figure 6 below shows a rotating system modeled using coordinates and u.
Figure 6
The exact equations of motion in terms of the shown coordinates are the following:
2Buu
----------------- =
A + Bu 2
LINEAR 89
C++ Commands
K ( u uo ) U
u = u 2 ----------------------- + ------2B
2B
where:
1
A = --- ( m 1 h 12 + I 1 + I 2 )
2
1
B = --- m 2
2
Setting m1=m2=3, I1=I2=10, e=1, K=5, uo=10 and selecting an operating point defined by t=0, =10,
u=0,
=0, u =0, we obtain that one eigenvalue is zero and the other is 2.63056 Hz.
PART/2 corresponds to the first link and PART/3 is the mass on the tip. Computing an eigensolution using
the default command LINEAR/EIG, we obtain the following results shown in the message file:
This model has
4 kinematic states (displacement and velocities)
0 differential states (DIFFs, LSEs, etc.)
The selected kinematic states are:
1 Global rotation AZ(BCS)
PART/2
2 Global displacement DX(BCS)
PART/3
The other kinematic states are the respective derivatives.
E I G E N V A L U E S at time = 0.00000E
Number
Real(cycles/unit time)
Imag.(cycles/unit time)
1
0.00000E
2
0.00000E
3
0.00000E
3.07455E
90 Adams/Solver
C++ Commands
Notice that the selected states are the global rotation of PART/2 about the z-axis (AZ(BCS) PART/2) and
the global x-displacement of PART/3 (DX(BCS) PART/3). While the first one coincides with the
coordinate alpha used to generate the equations of motion, the second one does not correspond to
coordinate u.
The correct results are obtained using the following command:
LINEAR/EIGEN, RM=5
Where MARKER/5 is located on the first link. The corresponding results are:
This model has
4 kinematic states (displacement and velocities)
0 differential states ( DIFFs, LSEs, etc.)
The selected kinematic states are:
1 Relative rotation AZ(GROUND,5)
PART/2
2 Relative displacement DX(BCS,5,5)
PART/3
The other kinematic states are the respective derivatives.
E I G E N V A L U E S at time = 0.00000E
Number
Real(cycles/unit time)
Imag.(cycles/unit time)
1
0.00000E
2
0.00000E
3
0.00000E
2.63056E
Notice that the selected states now coincide with and u and that the results match the theoretical ones.
For an example of using RM, see Knowledge Base Article 12690.
5.1.3 Using the PSTATE option
The PSTATE option is used to indicate the ADAMS ID of a PSTATE object. A PSTATE object is a set
of VARIABLES defining user-defined coordinates (see the PSTATE statement). You may want to
linearize the system using specific coordinates that the RM option does not provide. The methodology is:
1. Create as many variables as user-defined coordinates you want Adams/Solver (C++) to use when
linearizing the model.
2. Create a PSTATE object and enter the Adams id of all variables created in the previous step.
3. Issue a LINEAR/EIGEN command using the PSTATE=id option.
LINEAR 91
C++ Commands
Figure 7
Figure 7 shows a simplified model of a rigid helicopter blade where the first link has a prescribed angular
velocity w. Observe that the system has one degree of freedom but there are several coordinates to choose
from to build the equations of motion. The classical approach is to use angle
requirement to use coordinate y instead.
If the angle
( I + ml 2 ) + mel 2 sin ( t ) = 0
Linearizing this equation in terms of
mel 2-----------------0
[A] =
I + ml 2
1
0
and the corresponding frequency is
mel
1, 2 = i ----------------I + ml 2
where i is the imaginary constant. Setting m=3, e=2, l=10, I=10, and w=10, we obtain
= 0.70019 Hz.
92 Adams/Solver
C++ Commands
MARKER/5, PART = 2
MARKER/8, PART = 2, QP = 2, 0, 0
PART/3, MASS = 3, CM = 10, IP = 0, 0, 10, WZ = 10
MARKER/7, PART = 3, QP = 2, 0, 0
MARKER/10, PART = 3, QP = 12, 0, 0
MARKER/12, PART = 3, QP = 22, 0, 0
JOINT/1, REVOLUTE, I = 5, J = 6
JOINT/2, REVOLUTE, I = 7, J = 8
MOTION/1, ROTATIONAL, JOINT = 1, FUNCTION = 10*TIME
ACCGRAV/I=0, J=0, K=0
RESULTS/XRF
END
where PART/2 is the first link and PART/3 is the rigid blade. Running the model with a LINEAR/EIG
command, we obtain the following output:
This model has
2 kinematic states (displacement and velocities)
0 differential states ( DIFFs, LSEs, etc.)
The selected kinematic states are:
1 Global rotation AZ(BCS)
PART/3
The other kinematic states are the respective derivatives.
E I G E N V A L U E S at time = 0.00000E
Number
Real(cycles/unit time)
Imag.(cycles/unit time)
1
0.00000E
7.00188E-01
Notice the exact match with the theoretical results. However, let's assume you want to linearize the model
using coordinate y instead. If that is the case, the state matrix is now:
melw 2
----------------0
w2
[ A ] =
I + ml 2
1
0
and the frequencies are:
mel
1, 2 = iw -----------------2- + 1
I + ml
Using the same physical parameters, the frequency turns out to be = 1.73867 Hz. To obtain this second
result, add the following lines to the dataset file:
VARIABLE/1, FUN=DY(10)
PSTATE/1, VAR=1
Notice that MARKER/10 is located on the CM of the blade, therefore DY(10) is the coordinate y shown
in the figure above. Re-running the model using the following command:
LIN/EIGEN, PSTATE=1
LINEAR 93
C++ Commands
measure.
The displacement or angular measure can be global or relative.
The number of user-defined coordinates can be less than the number of degrees of freedom of the
model. Adams/Solver (C++) will complete the state array using coordinates taken from the set of
default coordinates.
The number of user-defined coordinates can be greater than the number of degrees of freedom of
the model. Adams/Solver (C++) selects the required number, ignoring the rest.
Redundant definitions will be rejected.
Adams/Solver (C++) may ignore a user-defined coordinate if there is already an equivalent
default definition.
For an example of using PSTATE, see Knowledge Base Article 12663.
5.1.4 Using both the RM and PSTATE options
You may safely use both the RM and the PSTATE options. Adams/Solver (C++) assigns a higher priority
to the user-defined states specified by the VARIABLES referenced in the PSTATE object. Default
coordinates generated by the RM option have a lower priority.
For example, the following command linearizes the model using both options.
LINEAR/EIGEN, RM=77, PSTATE=3
5.1.5 Coordinates, Kinetic, Dissipative and Strain options
If you specify the COORDS, KINETIC, DISSIPAT, or STRAIN arguments, Adams/Solver (C++)
computes tabular output and writes it to an ASCII (.txt) file. For each mode in the specified range, this
output could consist of up to five sections. The header section contains the mode number, undamped
natural frequency, damping ratio, generalized stiffness, generalized mass and model energy for the mode.
Generalized stiffness and generalized mass are in user-specified units.
94 Adams/Solver
C++ Commands
The second section is a table of coordinates if the COORDS argument is specified. This section is not
output if the COORDS argument is not specified or if the particular mode number is not within the range
specified on the COORDS argument. Each part in the Adams/Solver (C++) model has one row in this
table. The part translational coordinates in columns labeled (X,Y, and Z), represent the small translational
displacements of the part center-of-mass (cm) marker in the global reference frame. The part rotational
coordinates, in columns labeled (RX, RY, and RZ), represent the small rotational displacements of the
part about the global x, y and z axes, respectively. Each coordinate in this table is represented by a
magnitude and a phase. The mode is normalized so that the largest component in the mode has a value
of 1.0 and a phase angle of 0 degrees. Magnitude and phase of all other components in the mode are
reported relative to this largest component. Phase angles are represented in the range 0 to 355 degrees.
Phase angles in the range 175 to 185 degrees are reported as 180 degrees. Phase angles in the range 355
to 360 degrees as well as phase angles in the range zero to five degrees are reported as zero degrees. States
of elements resulting in user supplied differential equations are also represented in the coordinate table.
All components with zero magnitude are also reported as having zero phase angles.
The third section is a table of modal kinetic energy distribution if the KINETIC arguments are specified.
This section is not present in the output for a particular mode if the mode number is not within the range
of the modes specified on the KINETIC arguments. Each part is represented by a single row in this table.
Each entry in this table represents the percentage of the total modal kinetic energy for that part in a
particular direction. Translational directions in which the modal kinetic energy distribution is computed
are x, y and z displacement of the part center-of-mass (cm) in the global reference frame. Rotational
directions are denoted by RXX, RYY, and RZZ; these represent the small displacement rotations of the
part about the global x, y and z axes, respectively. The cross rotations are represented as RXY, RYZ, and
RXZ. The sum of all values in a modal energy distribution table should be 100.0. Elements resulting in
user-supplied differential equations are not considered in the computation for this table.
The fourth section is a table of modal strain energy distribution if the STRAIN argument is specified.
This section is not present in the output for a particular mode if the mode number is not within the range
of the modes specified on the STRAIN argument. Each force element is represented by one or more rows
in this table. The table below shows the contribution of various element types to this table. Computation
of strain energy accounts for the direct and indirect dependence of the force on PART displacements. The
indirect dependence on PART displacements may be through dependence of the force on other FORCEs,
VARIABLEs, or algebraic DIFFs that may be directly or indirectly dependent on PART displacements.
Elements Contributing to Table for Dissipative and Strain Energy Computations
Total
RX
RY
RZ
BEAM
BUSHING
CONTACT
FIELD
GFORCE
...
LINEAR 95
C++ Commands
Total
for marker n
SFORCE (translational)
SFORCE (rotational)
SPRINGDAMPER
(translational)
SPRINGDAMPER
(rotational)
VFORCE
VTORQUE
RX
RY
RZ
In the table, X, Y, and Z refer to translation components along the global x, y and z directions and RX,
RY, and RZ refer to rotational components about the global x, y and z directions. x indicates locations for
contributions for individual elements. The column labeled Total contains a summation of the
strain/dissipative energy contribution due to the element in various directions.
The fifth section is a table of modal dissipative energy distribution if the DISSIPAT argument is specified.
This section is not present in the output for a particular mode if the mode number is not within the range
of the modes specified on the DISSIPAT argument. Each force element is represented by one or more
rows in this table. The table shows the contribution of elements to this table. Computation of dissipative
energy accounts for the direct and indirect dependence of the force on PART velocities. The indirect
dependence on PART velocities may be through dependence of the force on other FORCEs,
VARIABLEs, or algebraic DIFFs that may be directly or indirectly dependent on PART velocities.
5.2 State matrices and MKB computation
5.2.1 Scope
If you specify the STATEMAT option, Adams/Solver (C++) computes the state matrices representation
for an Adams model. The linearized Adams model is represented as:
x = Ax + Bu
y = Cx + Du
where:
Vector x represents the state variables of the plant model. The state variables can be user-defined
coordinates (see the RM and PSTATE options). By default, the state variables are the
displacements, modal coordinates (from flexible elements) and their corresponding time
derivatives. The state variables also include all of the differential states from DIFs, LSEs, GSEs
and TFSISOs.
Vector u represents the inputs of the plant model.
96 Adams/Solver
C++ Commands
If you specify the MKB option, Adams/Solver (C++) computes another form of the state matrices
representation for an Adams model. In this case, the linearized Adams model is represented as:
Mx + Kx + Bx = Pu
y = Cx + Du
where:
Vector x represents the state variables of the plant model. The state variables can be user-defined
coordinates (see the RM and PSTATE options.) In this case the state variables are the
displacements, modal coordinates (from flexible elements) and all differential states from DIFS,
LSEs, GSEs and TFSISOs.
Vector u represents the inputs of the plant model.
Vector y represents the outputs from the plant model.
M, K, B, C, and D are state matrices representing the plant.
Matrices M, K, B, computed using the MKB option are equivalent to matrices A and B obtained using
the STATEMAT option. The MKB option is useful if you need to export the Adams model to be a
subsystem of an MSC.NASTRAN model.
5.2.2 Using the RM and PSTATE options
You can specify the definition of plant inputs with the PINPUT argument value. Similarly, plant outputs
are specified by the POUTPUT argument. States variables (x) are automatically selected by
Adams/Solver (C++) out of the total set of coordinates used to model the mechanical system. However,
using the RM and/or the PSTATE options, you may have Adams/Solver (C++) use user-defined
coordinates for linearization. This is particularly important for rotating systems. While several PINPUT
statements and POUTPUT statements may be present in an Adams model, you can specify only one of
each on the LINEAR command.
Corresponding to each VARIABLE id specified on the PINPUT statement, a column exists in the B and
D matrices (STATEMAT option). Similarly, for each VARIABLE id specified on the POUTPUT
statement, a row exists in the C and D matrices. In effect, each VARIABLE id specified on the PINPUT
or POUTPUT statement specifies an input or output channel, respectively.
Input channels are important in the computation of state matrices. It is important to notice that
Adams/Solver (C++) assumes the function expressions of all input channels are zero. If the function
expression of an input VARIABLE is not zero, then you have two choices to properly model the system
(assume the original input variable is VARIABLE/f):
LINEAR 97
C++ Commands
1. Remove VARIABLE/f from the INPUT statement. This is usually the simples and correct choice.
2. Create a new VARIABLE/d and add it to the INPUT statement. Remove VARIABLE/f from the
INPUT statement and modify its function expression to original_expression + VARVAL(d).
Choose this approach if you need to keep the size of the B to an specified value.
Following the above recommendation you may properly model both open-loop and close-loop control
systems.
Tip:
its eigenvalues. Eigenvalues with positive real parts correspond to unstable modes
of the system.
If you specify the PINPUT and the POUTPUT arguments for state matrices output,
Adams/Solver (C++) produces all four matrices (A, B, C, and D). If you do not
specify the PINPUT argument, Adams/Solver (C++) does not produce the B or D
matrices. Similarly, if you do not specify the POUTPUT argument, Adams/Solver
(C++) will not produce the C or D matrices. If you do not specify either the
PINPUT or POUTPUT arguments, Adams/Solver (C++) produces only the A
matrix.
You may define several PINPUT and POUTPUT statements in an Adams/Solver
(C++) dataset, however, a LINEAR command allows only one PINPUT and one
POUTPUT statement to be specified at a time. If you issue a series of LINEAR
commands, Adams/Solver (C++) computes alternate state matrix descriptions at
the same operating point with different combinations of PINPUT and POUTPUT
identifiers. Changes in the PINPUT and POUTPUT descriptions are reflected in
the A, B, C, and D matrices.
5.2.4 MATRIXX format
State matrices output by Adams/Solver (C++) in the MATRIXX format conforms to the MATRIXx
FSAVE ASCII file specification. These specifications are given in the Xmath Basics Guide, 1996,
Integrated Systems Inc., Santa Clara, CA.
More than one matrix may be present in a single file. The Adams/Solver (C++) state matrices file can
have up to seven matrices. The first four matrices are the A, B, C, and D state matrices. The next three
matrices are STATES, PINPUT, and POUTPUT. The contents and format of these matrices are explained
in the next sections.
5.2.5 MATLAB format
State matrices output by Adams/Solver (C++) in the MATLAB format conform to the ASCII flat file
format. This format requires that all entries in a row of the matrix be written in a single record. Successive
values in a row are separated by a single space. A file is allowed to contain only one matrix. Therefore,
98 Adams/Solver
C++ Commands
Adams/Solver (C++) may create up to seven output files, one each for the A, B, C, and D matrices, one
for STATES, one for PINPUT, and one for POUTPUT. The contents and format of the last three matrices
are as shown in the next sections. The file name you specify is used as a base name and is appended with
the matrix name to write the matrix of the appropriate type. The file names used for the seven matrices
are as given in the table below.
File Names Used for MATLAB State Matrices Output
Matrix Name
file Name
"base_name" "a"
"base_name" "b"
"base_name" "c"
"base_name" "d"
STATES
"base_name" "st"
PINPUT
"base_name" "pi"
POUTPUT
"base_name" "po"
The STATES matrix contains information regarding states that Adams/Solver (C++) has chosen for the
state matrices representation. For each state, one record exists in this matrix. The following information
is contained in each record:
Type_of_element Element_identifier Element_coordinate
Type_of_element
Type_of_element can take on the following values:
1. PART coordinates (using Euler angles)
2. States in a LSE element
3. States in a TFSISO element
4. States in a GSE element
5. Diff variable
6. Coordinate for a PTCV element
7. Coordinates for a CVCV element
8. FLEX_BODY element
9. POINT_MASS element
10. PSTATE variable (a VARIABLE used in a PSTATE object)
LINEAR 99
C++ Commands
Element_identifier
Element_identifier is the eight-digit Adams/Solver (C++) identifier of the element.
Element_coordinate
If Type_of_element=1, the Element_coordinate can take on the values:
1 Global x-displacement of PBCS (See the Note: below)
2 Global y-displacement of PBCS
3 Global z-displacement of PBCS
PBCS stands for Principal Body Coordinate System. PBCS is a frame coincident with the
PARTs CM MARKER but it is oriented along the principal inertia axis. PBCS is an internal
MARKER used by Adams/Solver (C++) to build the equations of motion.
BCS stands for Body Coordinate System. For details on BCS, see the PART command.
100 Adams/Solver
C++ Commands
LINEAR 101
C++ Commands
1.20000000000000000e+01
6.00000000000000000e+00
The first column shows a 21, which stands for a PART. No option RM was used in the linearization
command. The second column shows a 3 which stands for the ADAMS id of the PART. The third column
shows a 12 and a 6, therefore the states used by the linearization are:
1. Global rotation of the BCS of PART/3 about the global z-axis
2. The derivative of the global rotation of the BCS of PART/3 about the global z-axis.
5.2.7 Contents of the PINPUT and POUTPUT matrices
The first record in the PINPUT (or POUTPUT) exported matrix data contains the Adams/Solver (C++)
identifier of the PINPUT (or POUTPUT) statement that was used on the LINEAR command to generate
these state matrices. Subsequent records contain the Adams/Solver (C++) identifiers of the VARIABLE
statement identifiers used on these statements. In the MATRIXX as well as the MATLAB format, this
data is organized as a matrix with 1 column and number of rows equal to one plus the number of variables
on the PINPUT (or POUTPUT) statement.
All data for the STATES, PINPUT, and POUTPUT matrices is written as floating point data.
5.3 Nastran bulk data deck export
5.3.1 Scope
Using the EXPORT option Adams/Solver (C++) exports the linearized Adams model as a set of Nastran
bulk data deck files.
The syntax to invoke the EXPORT job calls for the type of export (WHITEBOX or BLACKBOX), the
name of the main bulk data deck file to be created (FILE argument), and an optional name for a
configuration file (CONFIG argument). The configuration file is useful to customize the export process.
It supports two types of EXPORT jobs, namely, a WHITEBOX option or a BLACKBOX option which
must be specified using the TYPE argument. These two types are conceptually different. Using the
BLACKBOX option, Adams/Solver (C++) computes the MKB matrices and exports the model as a set
102 Adams/Solver
C++ Commands
of three DMIGs. Individual contributions to the MKB matrices from all of the inertial elements, applied
forces and constraints cannot be identified, hence the exported model is practically non modifiable. On
the other hand, using the WHITEBOX option, the linearized model is exported as a set of Nastran cards
where an element-to-element translation takes place; this option exports a model that can be further
edited and modified.
Using the EXPORT option, a configuration file can be specified to fine tune the export job. The syntax
of the configuration file allows the user to select the solution number, specify exported MARKERS,
single out applied forces, change the default numbering of GRID and other Nastran cards, select include
directories, choose a type of graphical output, select a style of file generation, etc.
5.3.2 Limitations
There are no limitations on the type of previous analysis prior to the invocation of the LINEAR/EXPORT
command if using the BLACKBOX export type. Also, eigenvalues computed by Nastran on the exported
model will match eigenvalues computed by Adams on the Adams model. In a few words, both, static and
dynamic operating points are supported by the BLACKBOX export.
When using the WHITEBOX export type, we guarantee matching eigenvalues computed by both,
Nastran and Adams, only if the operating point is a static one (if the previous simulation in Adams was
either STATIC or QUASISATIC). Notice that a STATIC simulation at time t=0 may not be a truly static
operating point because Adams/Solver restores the initial velocities found in the model. This restoration
of velocities after a STATIC simulation at time t=0 can be avoided by setting the environment variable
MSC_ADAMS_STATICS_NO_RESTORE_VELOCITIES.
If the previous simulation done by Adams is a dynamic or kinematic analysis, the exported model
includes TIC cards defining the velocities of the model. However, eigenvalues computed by both,
Nastran and Adams will not necessarily match. This is not a limitation on the Adams side but a limitation
inherent to most linear/nonlinear Finite Element codes available in the market.
If the operating point is KINEMATIC (no degrees of freedom), the only type allowed is WHITEBOX.
No BLACKBOX export is possible for that type of operating point.
5.3.3 BLACKBOX and WHITEBOX exported cards
LINEAR 103
C++ Commands
3. A set of SPOINT cards representing differential states from DIF, LSE, TFSISO and GSE objects
in the Adams model.
4. A set of CONM2 cards representing PART and POINT_MASS objects in the Adams model.
5. As set of RJOINT and/or MPC cards representing each of the JOINTS, GCON, JPRIM and
MOTION objects in the model.
6. A set of DMIG cards representing the dynamic contributions from DIF, LSE, TFSISO and GSE
objects in the Adams model.
7. A set of DMIG representing the contribution of applied forces, gravity and flexible bodies. By
default, all applied force, gravity and flexible bodies are exported into a single DMIG. The
configuration file can be used to single out applied forces and flexible bodies. There are
configuration directives to export forces using CBUSH cards.
Both, BLACKBOX and WHITEBOX options export the following cards
1. If the configuration file defines outputs channels and solution 108 is specified, the bulk data will
include a set of CORD2R and GRID cards representing the output channels. Along with each
GRID card, a set of MPC cards are exported.
2. If the configuration file defines input channels and solution 108 is specified, the bulk data will
include a set of CORD2R and GRID cards representing each of the input channels. Along with
each GRID card, a set of MPC cards are exported.
3. If the configuration file defines subcases, the bulk data will include a FREQ1 (or FREQ2) card.
A set of TABLED1 cards to define the force magnitude of the actuators, and a set of DLOAD
cards and corresponding RLOAD1, FORCE, MOMENT and DPHASE cards defining the input
channels, are also included.
4. By default, solution 107 and corresponding cards are exported. The configuration file can be used
to select solution 108.
5. A set of CORD2R and GRID cards representing Adams MARKERS in the model. Each exported
Adams MARKER creates GRIDs (with corresponding RBE2 cards) or a set of required MPC
cards. MARKERS are not exported by default if BLACKBOX type is selected. See the syntax of
the configuration files to export Adams MARKERS.
5.3.4 Configuration file syntax
The configuration file is an ASCII file used to fine tune the export job. The file can be seen as a set of
configuration directives and data definitions. Configuration directives have the syntax:
KEY = VALUE1 [, VALUE2]
104 Adams/Solver
C++ Commands
If a KEY is repeated, the latest definition is used. Comments start with the character $. The contents are
case sensitive.
Supported directives
Syntax
Example
Explanation
actuator_swept_sine {
name = [string]
magnitude = [real]
phase_angle = [angle]
}
actuator_swept_sine {
name = actuator_1
magnitude = 2.2
phase_angle = 45D
}
LINEAR 105
C++ Commands
add_space_before_names= {yes | no }
add_space_before_names = yes
Specifies to export all flexible bodies one by one creating sets of DMIGs
per body.
Ignored if job is BLACKBOX.
Default is yes.
all_forces_editable = [yes|no]
all_forces_editable = no
Specifies to export all forces creating a CBUSH and residual DMIGs per
forcing object.
Ignored if job is BLACKBOX.
Default is yes.
106 Adams/Solver
C++ Commands
begin_frequency = [real]
begin_frequency = 1.0
Sets the initial value of the frequency for a frequency response analysis.
Ignored if solution 107 is specified.
Required if solution 108 is specified.
cmethod_number = [integer]
cmethod_number = 445
cbush_offset = [integer]
cbush_offset = 7000000
LINEAR 107
C++ Commands
cord2r_offset = [integer]
cord2r_offset = 600
108 Adams/Solver
C++ Commands
debug = { yes | no }
debug = yes
differentials_dmig_name = [string]
differentials_dmig_name = ZQ
If job is WHITEBOX, defines the name of the DMIG used to export the
stiffness and damping contribution of all differential elements (DIFF, LSE,
TFSISO and GSE). Adams/Solver (C++) will append the given name to
predefined roots to form the names of the matrices to be exported.
Ignored if job is BLACKBOX.
Optional in all types of solution sequences.
Default is ZZZ.
disp_plot_punch = {string}
disk_plot_punch = plot
Prints PLOT, PUNCH or both in the DISP cards. Options for the string:
plot, punch, and both.
Optional in all types of solution sequences.
Default is "both".
LINEAR 109
C++ Commands
displacement_output_channel {
name = [string]
marker_id = [integer]
marker_name = [string]
mode = { local | global }
}
displacement_output_channel {
name = oc_1
marker_by_name = model.MARKER_77
mode = local
}
dload_card_number = [integer]
dload_card_number = 558
110 Adams/Solver
C++ Commands
dload_card_number_increment = [integer]
dload_card_number_increment = 2
dphase_card_number = [integer]
dphase_card_number = 658
dphase_card_number_increment = [integer]
dphase_card_number_increment = 2
LINEAR 111
C++ Commands
end_frequency = [real]
end_frequency = 1.0E+09
Sets the final value of the frequency for a frequency response analysis.
Ignored if solution 107 is specified.
Required if solution 108 is specified.
export_all_markers = { yes | no }
export_all_markers = yes
112 Adams/Solver
C++ Commands
export_cbush= {yes | no }
export_cbush = yes
export_external = { yes | no }
export_external = no
export_graphics = { yes | no }
export_graphics = no
LINEAR 113
C++ Commands
export_ground_markers = { yes | no }
export_ground_markers = yes
45-52, 88
114 Adams/Solver
C++ Commands
If this directive is set to yes, Adams/Solver exports a punch file (*.pch) with
mode shape information of a subset of GRIDs and SPOINTs of the model.
Only GRIDs corresponding to the CM of parts and SPOINTs
corresponding to flexible bodies and differential states are exported.
Optional in all types of solution sequences.
Ignored if job is BLACKBOX
Default is no
If this directive is set to yes, Adams/Solver exports a file with RBE2 cards
restoring the connectivity lost when using the option file_name_style=C.
Optional in all types of solution sequences.
Ignored if job is BLACKBOX
Default is "no"
LINEAR 115
C++ Commands
export_residuals= {yes | no }
export_residuals = yes
export_spc_connectivity = {yes | no }
export_spc_connectivity = yes
116 Adams/Solver
C++ Commands
file_include_extension= [string]
file_include_extension = .bdf2
LINEAR 117
C++ Commands
file_name_style= {A | B | C }
file_name_style = C
If this directive is set to A and the export command option FILE is FILE =
path, the exported files are:
path.dat (main file)
path_MODEL.nas (model file, all parts, flexible bodies and joints)
path_DMIGNAMES.bdf (several files, one file per DMIG)
Notice the ".dat", ".nas" and ".bdf" extensions are appended to the given
path. You may change the extensions using directives
main_file_include_extension, model_include_extension, and
file_include_extension.
If this directive is set to B and the export command option FILE is FILE =
path.ext, the exported files are:
path.ext
path_MODEL.ext
path_DMIGNAMES.ext
Notice that the extension is obtained from the LINEAR/EXPORT
command. The content of the exported files is identical to that of style A.
If this directive is set to C and the export command option FILE is FILE =
path, the exported files are:
path.dat
path_PROPERTY.nas
path_BODY.nas (several file, one per Adams PART)
path_CONNECTIVITY.nas
Notice the extension is appended to the given path.
Optional in all types of solution sequences.
Ignored if job is BLACKBOX
Default is A.
118 Adams/Solver
C++ Commands
force_card_number = [integer]
force_card_number = 558
LINEAR 119
C++ Commands
force_card_number_increment = [integer]
force_card_number_increment = 2
Causes to export an applied force. The first string argument determines the
type of applied force. The available types are: sforce, springdamper,
bushing, beam, field, vforce, vtorque, friction, or gforce. The second
argument corresponds to the ID of the element. The third argument is a
suffix used to create the DMIG cards.
Ignored if job is BLACKBOX.
Optional in all types of solution sequences.
Causes to export an applied force. The first string argument determines the
type of applied force. The available types are: sforce, springdamper,
bushing, beam, field, vforce, vtorque, friction, or gforce. The second
argument corresponds to the name of the element. The third argument is a
suffix used to create the DMIG cards.
Ignored if job is BLACKBOX.
Optional in all types of solution sequences.
120 Adams/Solver
C++ Commands
force_input_channel {
name = [string]
marker_id = [integer]
marker_name = [string]
dof = { x | y | z | rx | ry | rz }
actuator_name = [string]
mode = { local | global }
}
force_input_channel {
name = ic_1
marker_by_name = model.MARKER_88
dof = rx
actuator_name = actuator_1
mode = local
}
LINEAR 121
C++ Commands
forces_dmig_name = [string]
forces_dmig_name = FQ
If job is BLACKBOX, defines the name of the DMIG cards used to export
the stiffness matrix. If job is WHITEBOX, defines the name of the DMIG
used to export the stiffness contribution of all forces and flexible bodies
which have not been singled out by other directives. See for example
force_editable_by_name.
Optional in all types of solution sequences.
Default is VVV.
frequency_card_number = [integer]
frequency_card_number = 770
frequency_response_subcase {
number = [integer]
input_channel_names = [list of string]
output_channel_names = [list of string]
}
122 Adams/Solver
C++ Commands
frequency_response_subcase {
number = 107
input_channel_names = ic_1, ic_2, ic_3
output_channel_names = oc_7, oc_8
}
graphics_grid_offset= [integer]
graphics_grid_offset = 5000
Specifies the grid point identification number of the first GRID card used
to export graphical information.
Optional in all types of solution sequences.
Ignored if job is BLACKBOX
Default is 4000000.
grid_offset = [integer]
grid_offset = 1000
Specifies the grid point or spoint identification number of the first GRID or
SPOINT card exported. All other GRID and SPOINT identifications will
be sequentially numbered. This option is ignored if the directive
use_adams_ids is set to true.
Optional in all types of solution sequences.
Default is 1.
LINEAR 123
C++ Commands
ignore_errors = { yes | no }
ignore_errors = yes
include_directory= [string]
include_directory = myinclude
initial_dmig_set = [integer]
initial_dmig_set = 50
Specifies the number of the first SET to create a list of DMIG names.
Optional in all types of solution sequences.
Default 1
load = [integer]
load = 4
124 Adams/Solver
C++ Commands
main_file_include_extension = [string]
main_file_include_extension=.data
marker_offset = [integer]
marker_offset = 30000
material_card_number= [integer]
material_card_number = 500
Specifies the material identification number of the first MAT1 card used to
export graphical information.
Optional in all types of solution sequences.
Ignored if directive use_wireframe is set to true.
Ignored if job is BLACKBOX
Default is 1000.
LINEAR 125
C++ Commands
matrix_entry_zero_tolerance = [real]
matrix_entry_zero_tolerance = 1.e-06
model_include_extension = [string]
model_include_extension = .bdf
mpc_set = [integer]
mpc_set = 700
126 Adams/Solver
C++ Commands
number_of_eigenvalues = [integer]
number_of_eigenvalues = 40
param_post = [integer]
param_post = 1
pointmass_offset = [integer]
pointmass_offset = 30000
LINEAR 127
C++ Commands
remove_unused_items=[string] [,string]
remove_unused_items = cbush, grid
Removes empty CBUSH cards and/or GRID cards not being used.
Ignored if solution 107 is specified.
Optional if solution 108 is specified.
By default, no cards are removed.
rload1_card_number = [integer]
rload1_card_number = 558
rload1_card_number_increment = [integer]
rload1_card_number_increment = 2
128 Adams/Solver
C++ Commands
set_card_number = 558
LINEAR 129
C++ Commands
set_card_number_increment = [integer]
set_card_number_increment = 2
Sets the flag to either create a single included file or multiple included files.
If the option "yes" is used, all DMIG and graphical information is exported
in a single included file.
Ignored if job is BLACKBOX.
Optional if job is WHITEBOX.
Default is "no".
small_mass= [real]
small_mass = 1
Specifies the value of the small mass to be set to zero-mass parts during the
export process. After the export process is finished, zero-mass parts are
restored to their original configuration.
If this value is zero, Adams/Solver will use the smallest mass in the model
divided by 1000.
Optional in all types of solution sequences.
Ignored if job is BLACKBOX.
Default is 0.
130 Adams/Solver
C++ Commands
solution_number = [integer]
solution_number = 108
spc_set = [integer]
spc_set = 10
LINEAR 131
C++ Commands
spc_set_connectivity= [integer]
spc_set_connectivity = 1
Specifies the set identification number of the first SPC card used to export
the broken connectivity of the model when these two conditions met:
1. The directive export_spc_connectivity is set to true.
2. The directive file_name_style is set to C.
Optional in all types of solution sequences.
Ignored if job is BLACKBOX.
Default is 30000.
split_dmigs = [yes|no]
split_dmigs = no
spoint_offset = [integer]
spoint_offset = 30000
132 Adams/Solver
C++ Commands
steps_frequency = [integer]
steps_frequency = 50
subtitle = [string]
subtitle = Ann Arbor run - J. P. & L. L.
tabled1_card_number = [integer]
tabled1_card_number = 555
tabled1_card_number_increment = [integer]
tabled1_card_number_increment = 3
LINEAR 133
C++ Commands
tic_set= [integer]
tic_set = 500
Specifies the set identification number of the TIC cards used to export the
current velocities of the model.
Caution: Adams/Solver does not export the IC Case Control command.
title = [string]
title = Export 1.2.22 - Type 722.7-b
134 Adams/Solver
C++ Commands
use_damping = {yes | no }
use_damping = no
use_includes = { yes|no}
use_includes = no
use_plotel = {yes | no }
use_plotel = yes
LINEAR 135
C++ Commands
use_rjoints={yes|no}
use_rjoints = no
use_wireframe={yes | no }
136 Adams/Solver
C++ Commands
use_wireframe = yes
verbatim {
}
verbatim {
$ Added the following control cards
ECHO=BOTH
}
verbose_names=[ yes | no ]
verbose_names = no
LINEAR 137
C++ Commands
use_damping = yes
grid_offset = 1000
$
$ All MARKERS in specified range
export_markers_by_id = 1-99
$
$ We need this MARKER located on ground
export_marker_by_name = model.PART_999.MARKER_919
$
$ Export SFORCE/7, to be replaced by custom force
force_editable_by_id = sforce, 7, SF7
$ End
$ 45 degrees
force_input_channel {
name = inp1
marker_id = 88
dof = X
actuator_name = act1
}
force_input_channel {
name = inp2
marker_id = 88
dof = RZ
actuator_name = act1
}
displacement_output_channel {
name = out1
marker_id = 77
}
frequency_response_subcase {
number = 100
input_channel_names = inp1, inp2
output_channel_names = out1
}
frequency_response_subcase {
number = 200
input_channel_names = inp1
138 Adams/Solver
C++ Commands
output_channel_names = out1
solution_number = 108
begin_frequency = 1.0
end_frequency = 1000.0
steps_frequency = 20
spacing_frequency = log
use_damping = yes
grid_offset = 1000
$
$ End
5.3.6 Theoretical background
The BLACKBOX option exports the state space matrix representation of the Adams model following an
exact approach mentioned in section 1.0 above. The BLACKBOX export is straight forward to
implement.
On the other hand, the WHITEBOX option poses a delicate problem. Next sections present the exact
linearization of the equations of motion, an approximate linearization method, and some issues related to
exporting the model to Nastran.
Exact linearization
Lagrange's equations of motion (as assembled by Adams/Solver (C++)) have the following partitioned
form:
M 1 M 2 u&&
M 3 M 4 v&& +
(u, v) = 0
T
fu
u
T = fv
v
Where the u's are the dependent coordinates and the v's are the independent coordinates. The independent
coordinates are not arbitrarily selected but chosen after performing a LU factorization of the constraint
equations using full pivoting. The LU factorization will select the best choice of coordinates for the
independent states.
The first step to exactly linearize the system is to define matrix P as:
T
1
P =
u
v
Multiplying the top row of the equations of motion by P and summing it to the second one, the Lagrange
multipliers are eliminated:
LINEAR 139
C++ Commands
( M + PM 1 )u + ( M 4 + PM 2 ) = f + Pf u (Eq. 1)
3
u + + ( q q ) q q + 2 q q + = 0
u
t
tt
u&& =
1
1
v&& q& q& + 2 q& +
u v
u q q
qt
tt
u&& = P v&& +
Putting this result into Eq. 1, the ODE (minimal representation) of the equations of motion is found to be:
( M 3 P T + PM 1 P T + M 4 + PM 2 ) + ( M 3 + P M 1 ) = f v + Pf u
Notice that this equation has a functional dependency on both u and its first derivatives. However, both
quantities can always be obtained from the constraint equations.
The final step is to perturb the ODE to obtain the linearized form:
{ ( M 3 P T + PM 1 P T + M 4 + PM 2 ) + ( M 3 + P M 1 ) } = ( f v + Pf u ) (Eq. 2)
Adams/Solver (C++) computes the equation above by using a different yet equivalent approach. Equation
above is important because it shows that the contribution of each element can be singled out and
exported. However, for the general dynamical case, the contribution of each element (inertial element,
force or constraint) is heavily distributed all over the state matrices making very difficult the replacement
of say an exported force by a new set of Nastran cards.
Approximate linearization
An approach followed by several computer codes consists of first linearizing the constraint equations, the
equations motion and then assembling the ODE. The linearized constraints are:
u u + = 0 (Eq. 3)
140 Adams/Solver
C++ Commands
Redefining matrix P as
T
1
P =
u
v
we obtain that
u = P T
Notice that in this case matrix P is numerically equal to matrix P defined in the previous section.
However, in this case matrix P is a constant; therefore taking two time derivatives of the last expression
we arrive to:
u = P T (Eq. 4)
T
M 1 M 2 u&& u
fu
M 2 M 4 v&& + T = fv
(Eq. 5)
Multiplying the first row by P and summing it to the second row we find:
( M + PM 1 )u + ( M 4 + PM 2 ) = f + Pfu
3
( M 3 P T + PM 1 P T + M 4 + PM 2 ) = f + P fu (Eq. 6)
This is the set of assembled equations of motion obtained from the linearized constraint equations
(Eq. 3) and the linearized equations of motion (Eq. 5).
Feasibility of the export approach
Comparing Eq. 6 and Eq. 2 we notice that, in the general case, eigenvalues computed by those two
equations do not match. The complete variation of Eq. 2 involves terms that are missing in Eq. 2. (Notice
that matrix P in Eq. 6 is a constant.)
However, both Eq. 6 and Eq. 2 will produce the same eigenvalues only for the static case. If both
velocities and accelerations are zero, several terms drop from Eq. 2 and matching expressions are
obtained except for the right-hand side (applied forces). The variation of the right-hand side on Eq. 2 is:
( f v + Pf u ) = f v + P f u + Pf u
LINEAR 141
C++ Commands
which compared with the right-hand side of Eq. 6 shows that there is a missing term a linear code can not
compute. The solution is to export applied forces as DMIG cards.
Some of the issues addressed during the export job (WHITEBOX option) are the following:
1. The linearization is internally performed using the same coordinates Nastran uses to assemble the
equations of motion. This is accomplished by using Adams/Solver (C++) capability to linearize
the system in terms of user-defined coordinates.
2. The linearized constraint equations (Eq. 3) are evaluated by a two-stages process and exported a
set of MPC cards.
3. The inertia elements (PARTS and POINT_MASS) are exported as CONM2 cards. This
information is taken directly from a mass matrix obtained by temporarily deactivating all
constraints. The mass matrices of flexible bodies are obtained in a similar way.
4. The stiffness and damping contribution of applied forces are computed and exported as DMIG
cards. By default all forces and flexible bodies contributions are dumped into the same set of
DMIGs. The configuration file can be used to single out the contribution of each applied force or
flexible body, however, each singled out element involves one extra linearization.
5. All differential states contributions to the equations of motion are dumped into a set of DMIGs
and SPOINT cards. Currently there are no tools to single out the contribution of differential states.
6. Examples
The command
LINEAR/EIGENSOL
computes an eigenanalysis for the Adams model. Adams/Solver (C++) writes the eigenvalues and mode
shapes to the Results file where they can be read and displayed by a postprocessor such as Adams/View.
The command
LINEAR/STATEMAT, PINPUT=10, POUTPUT=20
, FORMAT=MATRIXX FILE=STATES.MAT
computes state matrices for the Adams model, using PINPUT/10 as inputs and POUTPUT/20 as outputs.
The state matrices are written to file STATES.MAT in MATRIXX format.
7. Applications
There are several areas in which the LINEAR command is required. Some examples include:
1. Eigensolutions provide you with information that may be used in assessing stability of the Adams
model. If you import control systems descriptions or distributed elasticity data from external
sources, you can verify the stability of their Adams models.
2. Eigendata computed by Adams/Solver (C++) can be used to validate Adams models against
eigendata from external sources.
142 Adams/Solver
C++ Commands
3. State matrices descriptions can be used in designing control systems for Adams models. This
description is suitable for computing frequency response data in matrix manipulation software
packages (see the PINPUT, POUTPUT, and VARIABLE statements).
4. State matrices output by Adams/Solver (C++) in the MATRIXX format are suitable for being read
into a second Adams model with a MATRIX statement. These matrices can form the definition
of a dynamical system defined by an LSE statement in the second Adams model.
5. Exported linearized model as Nastran bulk data decks using the "whitebox" option can be used in
eigensolutions, frequency response analysis using Nastran. The exported model can be further
edited to perform other types of solution sequences in Nastran.
7.1 Eigen analysis application
Consider a model of an inverted pendulum on a sliding cart as shown in the figure shown next. The listing
of the Adams/Solver (C++) dataset for this model is shown in Listing 1 (see Appendix).
Figure 8
The sliding cart in this model is represented by PART/1 and the inverted pendulum is represented by
PART/2. PART/1 slides along the global x axis in translational joint, JOINT/1, while PART/2 can rotate
about the axis of revolute joint, JOINT/2. PART/1 is connected to ground by a SPRINGDAMPER/1.
TFSISO/1 represents an actuator connected between PART/1 and PART/2. Force generated by this
actuator is applied on the two parts by SFORCE/1. No input is applied to the actuator for the present. To
assess stability of this model, execution of Adams/Solver (C++) is initiated. Once Adams/Solver (C++)
verifies that the model data is syntactically correct, issue the SIMULATE/STATIC command. On
achieving static equilibrium, issue the LINEAR/EIGEN command. Eigenvalues reported by
Adams/Solver (C++) are shown in the table below.
Model Eigenvalues
EIGENVALUES
Number
5.00909210E-02
0.00000000E+00
-5.00924580E-02
0.00000000E+00
LINEAR 143
C++ Commands
-3.18309800E+01
0.00000000E+00
-3.17994185E-01
+/- 6.36188992E-01
The table shows that the system has three stable and one unstable mode. To determine the cause of this
instability, use the data produced by Adams/Solver (C++) (.res, .adm, and so on) in Adams to display the
deformed mode shapes of the model.
Figure 9 (a) and (b) show mode shapes for mode 1, which is unstable, and mode 4, which is stable.
Figure 9
Figure 9 (a) shows that PART/1 is essentially stationary while PART/2 is moving. You can conclude that
PART/2 is the cause of the instability in this model. This is an expected result for this model, since the
inverted pendulum is at an unstable operating point. It is obvious that disturbing the pendulum will cause
it to swing about the revolute joint axis.
As illustrated by this example, viewing mode shapes in a graphical display can provide very significant
insight into the dynamic behavior of the model. In complicated Adams models, this insight is vital in
understanding the model dynamics. In Example 2: State Matrices Output below, based on the state
matrices computed for this model, a feedback control law will be designed to stabilize this model.
7.2 State matrices output
This section presents the design and implementation of a control system for the Adams model described
in Section 7.1. The purpose of the control design exercise is to design a feedback controller to attempt to
stabilize the inverted pendulum. For control design purposes, the state matrix representation of the
Adams model is required and is generated by the LINEAR/STATEMAT command.
144 Adams/Solver
C++ Commands
Stabilization of this model requires that PART/2 maintain its inverted vertical position despite external
disturbances applied on it. External disturbances considered here are gravity acting vertically downwards
and an external force applied to the pendulum in the x-direction. On sensing a deviation of the pendulum
from the desired position, the control law determines an appropriate signal to apply to actuator TFSISO/1
to restore PART/2 to its desired position. The control law operates on the basis of measuring output
signals from the plant and then computes a signal to apply to the actuator.
As shown in Figure 10 for the present model, 3 signals are output by the plant. VARIABLE/10 is a
measurement of the relative x displacement between PART/1 and PART/2. VARIABLE/20 is a
measurement of the relative x velocities between the two parts. VARIABLE/30 is the integral of the
relative x displacements between the two parts. These 3 signals are designated as outputs from the plant
by POUTPUT/1.
Input to the plant, that is, input signal to the actuator, is defined as VARIABLE/2. This is designated as
input to the plant by PINPUT/1. Adams/Solver (C++) implementation of the input/output structure and
the external disturbances is shown in Listing 2: Plant Input/output Specification (see Appendix). This
implementation, when combined with the plant model as shown in dataset 1 in. This implementation,
when combined with the plant model as shown in dataset 1 in FILE=c results in the open-loop model.
When the open-loop model is complete, an Adams/Solver (C++) execution session is initiated.
Figure 10
Open-Loop Model
The model is read into Adams/Solver (C++). After Adams/Solver (C++) verifies the model data syntax,
issue the SIMULATE/STATIC command to determine the equilibrium position. On achieving the
equilibrium position, issue the LINEAR/EIGEN, NOVECTOR command to verify the eigenvalues of the
model. The next table shows the eigenvalues for the open-loop model.
Open-Loop Eigenvalues
EIGENVALUES
Number
-2.66440631E-17
0.00000000E+00
5.00909210E-02
0.00000000E+00
-5.00924580E-02
0.00000000E+00
-3.18309800E+01
0.00000000E+00
-3.17994185E-01
+/- 6.36188992E-01
LINEAR 145
C++ Commands
The table shows that the open-loop model has one eigenvalue more than the model in Eigenanalysis
Application. This is due to the introduction of the relative displacement integrator TFSISO/2 in the openloop model. To linearize the model and compute the state matrices, issue the LINEAR/STATEMAT,
PINPUT=1, POUTPUT=1, file=adams.mat command. Adams/Solver (C++) linearizes the model and
writes the state matrices in the default format to adams.mat file. Contents of the ADAMS.MAT file are
in Listing 3: State Matrices (FSAVE Format) for the Open-Loop Model (see Appendix). The Adams/Solver
(C++) session then terminates. You may design a controller by reading the ADAMS.MAT file into the
control design package exercising various control design methodologies. The description of the control
design step is beyond the scope of the present document. A text on this subject or documentation for
control design software packages should be consulted for further details.
Now that the feedback control has been designed, it needs to be implemented in Adams/Solver (C++) for
a closed-loop simulation (see Listing 4 in the Appendix). The controller designed for this example is a
dynamic compensator. As shown in Figure 11 below, this is implemented in Adams/Solver (C++) as
LSE/1. The A, B and C matrices associated with this LSE are defined by MATRIX/100, 200, and 300,
respectively. Adams/Solver (C++) reads the data for these matrices from a file named incomp.dat (see
Listing 5 in the Appendix). To connect this feedback compensator to the plant model, inputs to LSE/1,
ARRAY/303 are connected to outputs from the plant model. Also, ARRAY/1, which is input to the
actuator, TFSISO/1, is now defined as the output from the compensator, VARIABLE/2. This completes
the closed-loop Adams model. The complete Adams/Solver (C++) dataset for this model Listing 4 (see
Appendix).
Figure 11
Closed-Loop Model
To verify and simulate the closed-loop model, an Adams/Solver (C++) simulation is initiated. The
closed-loop model is first equilibrated in its static position. The eigenvalues for this model are computed
and represented in Table 4 shown next.
146 Adams/Solver
C++ Commands
Closed-Loop Eigenvalues
EIGENVALUES
Number
-5.35233760E-01
0.00000000E+00
-3.18270747E+01
0.00000000E+00
-2.37397000E-01
+/- 7.54488218E-02
-7.37798519E-03
+/- 1.51611302E-01
-5.47796070E-01
+/- 5.12745191E-01
-2.43466412E-01
+/- 5.71313964E-01
-2.46528313E+01
+/- 1.00614794E+01
Table 4 above shows that the closed-loop model is stable. The closed-loop model has more eigenvalues
than the open-loop model. This is due to the dynamical state variables introduced by LSE/1. Eigenvalues
for the closed-loop Adams model can be compared with the closed-loop eigenvalues computed in the
control design package. Now that the stability properties of the closed-loop Adams model have been
verified, it can be simulated to obtain its dynamic response. The time profile of the external disturbance
is as shown in Figure 12. The closed-loop model response to external disturbance is as shown in
Figure 13. As illustrated in this figure, the closed-loop model provides complete disturbance rejection for
displacement of PART/2.
Figure 12
LINEAR 147
C++ Commands
Figure 13
The input signal applied to the actuator and the force generated by the actuator are shown in Figure 14
and Figure 15, respectively.
148 Adams/Solver
C++ Commands
Figure 14
Figure 15
The process of control design and simulation is an iterative one. If the closed-loop system does not
perform as expected, the control design specifications may have to be changed and a new controller
designed to achieve better performance.
LINEAR 149
C++ Commands
8. Appendix
Listing 1: Inverted Pendulum Model
ADAMS Inverted pendulum model.
!
pa/99, ground
ma/99,qp=0,0,0, zp =1,0,0
!
! ===> Sliding cart <===
pa/1,ma=10,ip=10,10,10,cm=10
ma/10,qp=5,0,0
! CM marker.
ma/11,qp=5,0,2, zp=5,1,2
! revolute joint marker.
ma/12,qp=3,-2,-2
! graphics marker.
ma/13,qp=5,0,0, zp=6,0,0
! translational joint marker.
ma/14,qp=5,0,12
ma/15,qp=12,0,2
! actutator attachment point
!
! ===> Inverted pendulum <===
pa/2,ma=1,cm=20, ip=1,1,1
ma/20,qp=5,0,12
! CM marker.
ma/21,qp=5,0,2, zp=5,1,2
! revolute joint marker.
ma/22,qp=5,0,12, zp=5,1,12
! graphics marker.
ma/23,qp=5,0,7
! actutator attachment point
ma/24,qp=5,0,2, zp=5,0,3
! graphics marker.
!
joint/1,tran,i=13,j=99
joint/2,rev,i=11,j=21
!
! ===> Spring damper between cart and ground <===
springdamper/1,tran,i=99,j=13,k=200,c=40,l=5
!
gra/2, circle,cm=20, r=1.5,seg=20
gra/3, circle,cm=22, r=1.5,seg=20
gra/4, cylind,cm=24, l=8.5, r=0.25,seg=10,side=10
gra/5, box, corn=12, x=9, y=4, z=4
!
! ===> External disturbance <===
sforce/1001, i=20, j=99, action, tran,
,fun=step(time,0,0,.5,10)-step(time,1,0,1.5,10)
!
! ===>Actuator Dynamics<===
tfsiso/1,num=10, den=1,0.005
,u=1,x=2,y=3
array/1,u,var=2
! input signal to actuator
array/2,x
! actuator state
array/3,y
! force generated by actuator.
!
! ===>Actuator force<===
sforce/1,i=15,j=23, trans,
,function=aryval(3,1)
!
! ===>Input to Actuator<===
vari/2,fun=0
!
150 Adams/Solver
C++ Commands
accgrav/kg=-1
result/format
!
end
Listing 2: Plant Input/output Specification
! ===> PLANT INPUT/OUTPUT definition <===
!
------------------!
var/1,fun=dx(20,14)
Displacement integrator
tfsiso/2, num=1, den=0,1
,u=20,x=21,y=22
array/20, U, VAR=1
array/21, X
array/22, Y
!
! ===> Outputs <===
vari/10, function= varval(1)
!
displacement
vari/20, function= vx(20,14)
!
velocity
vari/30, function= aryval(22,1)
!
displ. integrated
!
!
! ===> Plant input designation <===
pinput/1,var=2
!
! ===> Plant output designation <===
poutput/1,var=10,20,30
!
Listing 3:State Matrices (FSAVE Format) for the Open-Loop Model
MATRIXx VERSION 700
A
6
6B
7 2005-04-21 19:31:36
6
1C
6D
STATES
3
6PINPUT
2
1POUTPUT
4
1
A
6
6
0(3(1PE25.17))
-3.99604352126607365e+00 1.00000000000000000e+00 3.95647873392680538e-01
0.00000000000000000e+00 0.00000000000000000e+00 0.00000000000000000e+00
-1.99802176063303669e+01 0.00000000000000000e+00 1.97823936696340263e+00
0.00000000000000000e+00 0.00000000000000000e+00 0.00000000000000000e+00
0.00000000000000000e+00 0.00000000000000000e+00 0.00000000000000000e+00
1.00000000000000000e+00 0.00000000000000000e+00 0.00000000000000000e+00
-9.89119683481701345e-02 0.00000000000000000e+00 1.08803165182987160e-01
0.00000000000000000e+00 0.00000000000000000e+00 1.00000000000000000e+01
4.02439896739235914e-02 0.00000000000000000e+00 -4.42683886413159505e-02
0.00000000000000000e+00 -2.00000000000000000e+02 0.00000000000000000e+00
0.00000000000000000e+00 0.00000000000000000e+00 0.00000000000000000e+00
0.00000000000000000e+00 0.00000000000000000e+00 0.00000000000000000e+00
B
6
1
0(3(1PE25.17))
0.00000000000000000e+00 0.00000000000000000e+00 0.00000000000000000e+00
0.00000000000000000e+00 2.00000000000000000e+03 0.00000000000000000e+00
C
3
6
0(3(1PE25.17))
0.00000000000000000e+00 0.00000000000000000e+00 0.00000000000000000e+00
LINEAR 151
C++ Commands
0.00000000000000000e+00 0.00000000000000000e+00
0.00000000000000000e+00 1.00000000000000000e+01
1.00000000000000000e+01 0.00000000000000000e+00
0.00000000000000000e+00 0.00000000000000000e+00
0.00000000000000000e+00 0.00000000000000000e+00
D
3
1
0(3(1PE25.17))
0.00000000000000000e+00 0.00000000000000000e+00
STATES
3
6
0(3(1PE25.17))
2.10000000000000000e+01 1.00000000000000000e+00
2.10000000000000000e+01 1.00000000000000000e+00
2.10000000000000000e+01 2.00000000000000000e+00
2.10000000000000000e+01 2.00000000000000000e+00
3.00000000000000000e+00 1.00000000000000000e+00
3.00000000000000000e+00 2.00000000000000000e+00
PINPUT
2
1
0(3(1PE25.17))
1.00000000000000000e+00 2.00000000000000000e+00
POUTPUT
4
1
0(3(1PE25.17))
1.00000000000000000e+00 1.00000000000000000e+01
3.00000000000000000e+01
0.00000000000000000e+00
0.00000000000000000e+00
0.00000000000000000e+00
0.00000000000000000e+00
1.00000000000000000e+00
0.00000000000000000e+00
7.00000000000000000e+00
1.00000000000000000e+00
1.10000000000000000e+01
5.00000000000000000e+00
1.00000000000000000e+00
1.00000000000000000e+00
2.00000000000000000e+01
152 Adams/Solver
C++ Commands
LINEAR 153
C++ Commands
9.98460749273361898E+01
-1.78574044858736743E+04
1.01587769607181722E+00
-1.69576019090885748E+04
-9.98470640470196713E+01
1.79036593612407414E+04
-1.02576889290663420E+00
1.74318979368853470E+04
-1.23564688768258060E-01
2.82840625758381648E+04
-4.02439896739235858E-01
-2.09248210623341492E+02
1.12468086129738198E+00
-9.30005800767228163E-01
9.98470640470196713E+01
-1.36246052474731605E+04
1.23564688768258060E-01
2.08671855656208993E-01
-2.13952705688378986E+00
4.62410531167074812E-03
154 Adams/Solver
C++ Commands
LSOLVER
The LSOLVER command allows the user to change the linear solver used by the Adams/Solver (C++).
The linear solver is invoked multiple times throughout the simulation to compute corrections in the
system state.
Format
Arguments
AUTO
CALAHAN Specifies that Adams/Solver (C++) is to use the CALAHAN solver exclusively. The
Calahan solver is usually fastest for most models.
UMF
Specifies that the Adams/Solver (C++) is to use the Unstructured Multi-Frontal sparse
matrix solver. This solver is faster for very large models.
Prior to MSC 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 Multi-Frontal) uses a very different solution technique than the Calahan
solver. The advantages of the UMF solver are 1) reduced memory use for large models, 2) better
performance for large models and 3) ability to use SMP parallelism for the linear system solution. 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 simplyconnected 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
LSOLVER 155
C++ Commands
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.
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.
156 Adams/Solver
C++ Commands
MARKER
The MARKER command moves and/or reorients an existing fixed Adams/Solver (C++) marker. (See the
MARKER statement for more information). You may also list information about the position of the
marker.
Format
Arguments
LIST
Lists the current values of the MARKER data. The data is with respect to the body
coordinate system (BCS) coordinates.
QP=x,y,z
Redefines the the x-, y-, and z-coordinates of the origin of the MARKER with
respect to the PART on which it lies. The coordinates are specified in the body
coordinate system (BCS) of the PART to which it belongs. For markers associated
with CURVES and SURFACES, the coordinates are specified in the RM coordinate
system and are susceptible to change as Adams/Solver (C++) iteratively solves for
initial conditions that satisfy all constraints while maintaining the marker on the
curve.
MARKER 157
C++ Commands
REULER=a,b,c
Redefines the three-dimensional spatial orientation of the marker axes relative to the
axes of the BCS. For markers associated with CURVES and SURFACES, the
orientation is relative to the natural coordinate system of the CURVE or SURFACE.
The a, b, and c values represent a set of body-fixed 3-1-3 Euler angles expressed in
radians. These angles can be interpreted as follows:
To orient a marker, first align the marker axes identically to the BCS axes.
Perform a right-handed rotation of the marker x- and y-axes by a radians about
axis.
Perform a right-handed rotation of the x- and y-axes of the marker by c radians
USEXP
When using the x-point-z-point method of orientation, USEXP causes the marker to
be oriented with the x-axis lying on XP and ZP lying in the positive x-z plane. This
is useful to orient markers for use in BEAM statements.Examples of using the ZP,
XP and USEXP.
158 Adams/Solver
C++ Commands
XP=x,y,z
By default, redefines the BCS coordinates of any point in the positive x-z plane of
the marker, but not on the z-axis of the marker. A point on the positive x-axis may
be the most convenient. When used with USEXP, XP defines the BCS coordinates
of any point on the positive x-axis of the marker.
If the marker is associated with a FLEX_BODY or PART, the x-, y-, and zcoordinates are specified in the BCS. For markers associated with CURVES and
SURFACES, the x-, y-, and z-coordinates are specified in the natural coordinate
system of the CURVE or SURFACE.
For every point on a CURVE or SURFACE, Adams/Solver (C++) computes a
natural coordinate system defined by tangent, normal, and binormal orthonormal
vectors. In general, as the solution progresses and the marker moves along the
CURVE or SURFACE, the orientation of the natural coordinate system changes, but
the orientation of the marker relative to the natural coordinate system remains fixed.
The fixed orientation of the marker relative to the natural coordinate system is
specified with XP and ZP arguments. Examples of using the ZP, XP and USEXP.
ZP=x,y,z
By default, redefines the BCS coordinates of any point in the positive z-axis of the
marker. When used with USEXP, ZP defines the BCS coordinates of any point in the
positive x-z plane of the marker, but not on the x-axis of the marker.
If the marker is associated with a FLEX_BODY or PART, the x-, y-, and zcoordinates are specified in the BCS. For markers associated with CURVES and
SURFACES, the x-,y- and z-coordinates are specified in the natural coordinate
system of the CURVE or SURFACE.
For every point on a CURVE or SURFACE, Adams/Solver (C++) computes a
natural coordinate system defined by tangent, normal, and binormal orthonormal
vectors. In general, as the solution progresses and the marker moves along the
CURVE or SURFACE, the orientation of the natural coordinate system changes, but
the orientation of the marker relative to the natural coordinate system remains fixed.
The fixed orientation of the marker relative to the natural coordinate system is
specified with XP and ZP arguments. Examples of using the ZP, XP and USEXP.
Extended Definition
The MARKER command allows you to reposition and/or reorient a fixed marker with respect to the body
coordinate system (BCS) of the element to which the marker is attached, or to another nonfloating marker
on the same element. You may use any of the standard Adams/Solver (C++) methods to specify the
location and orientation of the marker. Floating markers may not be moved, but their current information
may be listed. For more information on BCS, see Coordinate Systems and Local Versus Global
Geometric Data.
After a change to a MARKER, Adams/Solver (C++) reprocesses the model at the next SIMULATE
command, as if it had just been read in from the dataset. During the reprocessing, Adams/Solver (C++)
checks the entire model for consistency, reinitializes user subroutines, and recomputes initial conditions.
MARKER 159
C++ Commands
While checking, Adams/Solver (C++) verifies that the model is still valid with the new MARKER
positions. If a JOINT is now misaligned, for instance, Adams/Solver (C++) issues a warning or error.
Adams/Solver (C++) also reinitializes user subroutines to re-establish functional dependencies. For each
element that refers to a user-written subroutine, Adams/Solver (C++) calls the user-written subroutine
with IFLAG set to true.
Prior to the actual simulation, Adams/Solver (C++) computes initial conditions for the model. If this is
the first simulation, Adams/Solver (C++) begins with the positions and velocities specified in the dataset.
If you have run a previous simulation, Adams/Solver (C++) begins with the final displacements and
velocities. Adams/Solver (C++) then adjusts the initial conditions to ensure that they are consistent with
the model constraints. If this is the first simulation, Adams/Solver (C++) also maintains any user supplied
joint initial-conditions and positions specified as EXACT.
If you change a MARKER in the middle of a simulation, by default Adams/Solver (C++) splits the
tabular, request, graphics, and results output into two separate sets of output concatenated together. This
ensures that the output correctly reflects the new system geometry.
The OUTPUT/NOSEPARATOR argument prevents Adams/Solver (C++) from splitting the file. This
allows you to plot or animate the output continuously from beginning to end, but may result in misleading
graphics during postprocessing. See the OUTPUT statement for more information on the
NOSEPARATOR argument.
Tip:
You can use the QP argument to translate the marker while maintaining the existing
orientation. If you use only the REULER argument, Adams/Solver (C++) reorients the
marker while maintaining the existing position.
Caution:
When reorienting a marker, you should completely specify the necessary information
for the selected orientation method. Adams/Solver (C++) uses the new orientation
information; it does not try to combine it with old information from the dataset
statement or a previous command. For example, if you supply ZP but not XP,
Adams/Solver (C++) uses a default position for the x-axis. Adams/Solver (C++) does
not use a value of XP from the statement or an earlier command.
When you change a marker, Adams/Solver (C++) updates all elements that depend on
that marker. Moving a marker may have subtle effects since many Adams/Solver (C++)
elements rely on them. Be careful when moving markers as unintended side effects (for
example, moving both a joint and force that share a common marker) may occur.
Examples
MARKER/10,REULER=15D,0,0
160 Adams/Solver
C++ Commands
This MARKER command repositions/reorients Marker 18 so that it has the same location and orientation
as Marker 8.
See other bordered commands available.
MENU 161
C++ Commands
MENU
The MENU command lists all of the Adams/Solver (C++) interactive commands.
Format
MENU
See other Information available.
162 Adams/Solver
C++ Commands
MOTION
The MOTION command redefines and/or lists the characteristics of a MOTION statement which
specifies a system degree of freedom as an explicitly function of time. For more information, see the
MOTION statement.
Format
Arguments
ACCELERATION
B1
B2
MOTION 163
C++ Commands
B3
DISPLACEMENT
ICDISP
ICVEL
I=id, J=id
JOINT
LIST
ROTATION
ROUTINE=libname::subname
TRANSLATION
VELOCITY
164 Adams/Solver
C++ Commands
Extended Definition
The MOTION command allows you to list or modify the characteristics of an existing MOTION
statement. You can change the motion definition, change the joint to which the motion is being applied,
and/or change the type of motion on a cylindrical joint.
After a change to a MOTION, Adams/Solver (C++) reprocesses the model at the next SIMULATE
command, as if it had just been read in from the dataset. During the reprocessing, Adams/Solver (C++)
checks the entire model for consistency, reinitializes user subroutines, and recomputes initial conditions.
While checking, Adams/Solver (C++) verifies that the model is still valid with the new MOTION. If, for
example, the new MOTION conflicts with another MOTION at the same joint, Adams/Solver (C++)
issues an error.
Adams/Solver (C++) also reinitializes user subroutines to re-establish functional dependencies. For each
element that refers to a user-written subroutine, Adams/Solver (C++) calls the user-written subroutine
with IFLAG set to true.
Prior to the actual simulation, Adams/Solver (C++) computes initial conditions for the model. If this is
the first simulation, Adams/Solver (C++) begins with the positions and velocities specified in the dataset.
If you ran a previous simulation, Adams/Solver (C++) begins with the final displacements and velocities.
Adams/Solver (C++) then adjusts the initial conditions to ensure that they are consistent with the model
constraints. If this is the first simulation, Adams/Solver (C++) also maintains any user-supplied joint
initial-conditions and part positions specified as EXACT.
Examples
MOTION/3,JOINT=21
This MOTION command specifies, as a function of time, the translation or rotation for Motion 11.
See other Constraints available.
OUTPUT 165
C++ Commands
OUTPUT
The OUTPUT command redefines and/or lists the data for an OUTPUT statement.
Format
Arguments
GRSAVE
Resaves graphics output in the Graphics file so that you can use a postprocessor to
display graphics.
LIST
NOGRSAVE
NOREQSAVE
REQSAVE
Resaves the request output in the Request file so you can use a postprocessor to
display x-y plots.
Extended Definition
Like the OUTPUT statement, the OUTPUT command controls the generation of the request file and
graphics file.
See other Output available.
166 Adams/Solver
C++ Commands
PART
The PART command redefines and/or lists the data for a PART statement. Although you cannot redefine
the center-of-mass markers, the inertia markers, you are free to move and reorient those markers using
the MARKER command. You can also redefine the mass of the part and the 6 values of the inertia tensor.
Format
PART 167
C++ Commands
Arguments
IP=xx,yy,zz Specifies the mass-inertia tensor as computed about the origin of the IM marker,
expressed in the coordinate system of the IM marker.
You can compute the individual terms of the IP argument as:
Ixx =
( y 2 + z 2 ) dm
Iyy =
( x 2 + z 2 ) dm
Izz =
( x 2 + y 2 ) dm
Ixy =
xy dm
Ixz =
xz dm
Iyz =
yz dm
In the above formulae, x, y, and z are the components of the displacement of the center
of an infinitesimal volume of mass dm, measured from the origin of the inertia marker
in the coordinate system of the inertia marker. The integral is performed over the entire
volume of the body. If the inertia marker was not specified by the PART statment for the
part, the IM marker defaults to the CM marker. In that case, these quantities are
computed about the origin of the CM marker in the coordinate system of the CM marker.
Note:
Adams/Solver (C++) defines Ixy, Ixz, and Iyz as positive integrals, as shown.
Some references define these terms as the negative of these integrals. Be sure
to compute these values as shown above.
LIST
MASS=r
Caution:
Examples
PART/2, MASS=10
168 Adams/Solver
C++ Commands
This PART command respecifies the moments of inertia of Part 5 as principal moments of inertia and lists
all the data for the Part. If the original definition of Part 5 included an IM marker the moments of inertia
are w.r.t. this marker, otherwise the CM marker. If the original definition of Part 5 specified all 6 inertia
tensor values, the off-diagonal values are set to zero as a consequence of not being respecified.
PREFERENCES 169
C++ Commands
PREFERENCES
The PREFERENCES command controls general options that apply to the model defined in the
Adams/Solver (C++) dataset or the commands defined in the Adams/Solver (C++) command file.
Format
170 Adams/Solver
C++ Commands
Arguments
CONTACT_FACETING_TOLERANCE=value
PREFERENCES 171
C++ Commands
172 Adams/Solver
C++ Commands
PREFERENCES 173
C++ Commands
LIST
STATUS_MESSAGE
Examples
Caution:
174 Adams/Solver
C++ Commands
RELOAD
The RELOAD command restarts a simulation from a previously saved model or simulation state.
Format
FILE=c
Specifies the complete name of a file you created with the SAVE command.
The file name may include the directory on operating systems that support path
names, such as UNIX. There is no default extension for this file. Because the
FILE argument and value can be at most eighty characters long, the file name
and path name are limited from seventy-five characters (if you do not
abbreviate FILE=) to seventy-six characters (if you abbreviate FILE= to
FIL=).
Range: All printable characters except !, ;, , and &
OUTPUT_PREFIX=c Optionally specifies a new base (root) name for output files (.req, .res, .gra, and
so on) from simulations which follow this RELOAD command. If you do not
specify the OUTPUT_PREFIX argument, Adams/Solver (C++) appends the
output to the currently-open output files after writing a special delimiter line
into the file. Because the OUTPUT_PREFIX argument and value can be at
most eighty characters long, the basename and path are limited from sixty-six
characters (if you do not abbreviate OUTPUT_PREFIX) to seventy-six
characters (if you abbreviate OUTPUT_PREFIX to OUT=).
Range: All printable characters except !, ;, , and &
RELOAD 175
C++ Commands
SYSTEM
Specifies that Adams/Solver (C++) reloads the entire saved system, including
the model definition (parts, markers, joints, and so on), simulation time and
state values (displacements, velocities, force values, user-defined variable
values, and so on), and solver data (integrator parameters, state derivatives,
and so on). This completely replaces the existing model and simulation
conditions with the saved model and simulation conditions.
TITLE=c
Optionally specifies a new title for the model in output from simulations which
follow this RELOAD command. The title string may not contain any special
Adams/Solver (C++) characters and must fit on a single line (no
continuations). If not the last argument, the title is terminated by the last nonblank prior to the following comma. Because the TITLE argument and value
can be at most eighty characters long, the file name and path name are limited
from seventy-four characters (if you do not abbreviate TITLE=) to seventy-six
characters (if you abbreviate TITLE= to TIT=).
Range: All printable characters except !, ;, , and &
Extended Definition
Using the RELOAD command with the SYSTEM argument allows you to reload the entire saved system,
including the model definition (parts, markers, joints, and so on), simulation time and state values
(displacements, velocities, force values, user-defined variable values, and so on), and solver data
(integrator parameters, state derivatives, and so on). Adams/Solver (C++) completely resets all model,
simulation, and solver data to that stored in the file. Except for interactive plotting, Adams/Solver (C++)
responds to subsequent commands just as it would have at the time the file was saved. (Because past
simulation results are not stored in the Save file, they cannot be plotted when the file is restored.)
Tip:
Caution:
Except for the leading delimiter line, the appended sections of the output files are complete
(that is, they may be extracted with any editor, renamed, and handled like any other
Adams/Solver (C++) output).
Files are saved in a machine- and code-dependent binary format. They are not
176 Adams/Solver
C++ Commands
Examples
RELOAD/SYSTEM,FILE=TCT1.SAV,TITLE=TEST#2
This RELOAD command reloads the model and simulation states saved in file TCT1.SAV. Adams/Solver
(C++) appends subsequent output to the currently open output files with the new title TEST#2.
The SAVE and RELOAD commands can help simulate several versions of the same model when used
with other interactive Adams/Solver (C++) commands. SAVE/SYSTEM creates a baseline configuration
that you can then reload and simulate repeatedly without leaving Adams/Solver (C++). After each
RELOAD/SYSTEM, you may modify the model, and use the ACTIVATE and DEACTIVATE
commands to switch sets of loads on and off, for example.
The following command file uses the SAVE/SYSTEM and RELOAD/SYSTEM commands to run three
simulations from the same input file, creating three sets of output files: case1, case2, and case3. The
command file loads example.adm, the original model, that contains three sets of forces. After
deactivating all the forces and performing a static solution, the SAVE command saves the whole system.
ACTIVATE commands then turn on one set of forces at a time.
Between simulations, the RELOAD command restores the saved version of the model. Reloading the
save file returns the model to the conditions at the time of the save. In this case, the saved version of the
model is at static equilibrium with all the forces inactive.
example
case1
dea/sfo,id=101,102,201,202,301,302 !Deactivate all forces
sim/static
save/system, file=ex.sav
act/sfo, id=101,102
!Simulate
! Simulate
! Simulate
stop
REQUEST 177
C++ Commands
REQUEST
The REQUEST command redefines and/or lists the data for a REQUEST statement, and/or redefines the
function expressions for a REQUEST statement.
Format
Arguments
F2=e
F3=e
F4=e
F6=e
178 Adams/Solver
C++ Commands
F7=e
F8=e
ROUTINE=libname::subname
Examples
REQUEST/21, F4=DX(2110, 409)/F8=DX(2115, 409)
This REQUEST command changes the channels F4 and F8 expressions for REQUEST/21. The other
function expressions remain as they were.
See other Output available.
SAVE 179
C++ Commands
SAVE
The SAVE command stores the current Adams/Solver (C++) model and simulation conditions or only
the current simulation states. This allows you to return to the model or states at a later time using the
RELOAD command.
Format
SAVE/SYSTEM, FILE=c
Arguments
FILE=C
Specifies the complete file name where Adams/Solver (C++) writes the SAVE
command information. The file name may include the directory on operating systems
that support such path names, such as UNIX. There is no default extension for this file.
Range: All printable characters except !, ;, , and &
SYSTEM
Specifies that Adams/Solver (C++) saves the entire current system, including the
model definition (parts, markers, joints, and so on), simulation time and state values
(displacements, velocities, force values, user-defined variable values, and so on), and
solver data (integrator parameters, state derivatives, and so on). SYSTEM creates a
complete record of the current model and simulation conditions. The
RELOAD/SYSTEM command can later reload this record to return to these model and
simulation conditions.
Extended Definition
You can use the SAVE command with the SYSTEM argument to save the entire current system, including
the model definition (parts, markers, joints, and so on), simulation time, state values (displacements,
velocities, force values, user-defined variable values, and so on), and solver data (integrator parameters,
state derivatives, and so on). SAVE/SYSTEM creates a complete record of the current model and
simulation conditions. You can later return to this point by reloading the conditions using the
RELOAD/SYSTEM command.
When you reload a system file, Adams/Solver (C++) completely resets all model, simulation, and solver
data to that stored in the file. Except for interactive plotting, Adams/Solver (C++) responds to subsequent
commands just as it would have at the time the file was saved. (Because past simulation results are not
stored in the save file, they cannot be plotted when the file is restored.)
180 Adams/Solver
C++ Commands
Caution:
Files are saved in a machine- and code-dependent binary format. They are not portable
Examples
SAVE/SYSTEM,FILE=BASE1.SAV
This SAVE command saves the current model and simulation information in file BASE1SAV. When this
file is reloaded with the RELOAD command, Adams/Solver (C++) returns to this exact configuration.
Used with other interactive Adams/Solver (C++) commands, SAVE and RELOAD can help simulate
several versions of the same model. SAVE/SYSTEM creates a baseline configuration which you can then
reload and simulate repeatedly without leaving Adams/Solver (FORTRAN). After each
RELOAD/SYSTEM, you may modify the model. This can be done by using the ACTIVATE and
DEACTIVATE commands to switch sets of loads on and off, for example.
The following command file uses the SAVE/SYSTEM and RELOAD/SYSTEM commands to run three
simulations from the same input file, creating three sets of output files: case1, case2, and case3. The
command file loads example.adm, the original model, which contains three sets of forces. After
deactivating all the forces and performing a static solution, the SAVE command saves the whole system.
ACTIVATE commands then turn on one set of forces at a time.
Between simulations, the RELOAD command restores the saved version of the model. Reloading the
save file returns the model to the conditions at the time of the save. In this case, the saved version of the
model is at static equilibrium with all the forces inactive.
example
case1
dea/sfo,id=101,102,201,202,301,302 ! Deactivate all forces
sim/static
save/system, file=ex.sav
act/sfo, id=101,102
! Simulate
! Simulate
SAVE 181
C++ Commands
! Simulate
stop
182 Adams/Solver
C++ Commands
SENSOR
The SENSOR command lists the data for a SENSOR statement, and/or redefines the function expression.
Format
Arguments
ROUTINE=libname::subname
SENSOR 183
C++ Commands
Examples
SENSOR/231, FUNCTION=DX(0202,0307)
184 Adams/Solver
C++ Commands
SFORCE
The SFORCE command lists or changes the characteristics of an SFORCE statement.
Format
Arguments
ACTIONONLY
SFORCE 185
C++ Commands
I=id,J=id
LIST
REACTION
ROUTINE=libname::subname
Extended Defintion
The SFORCE command lists or changes the characteristics of an existing SFORCE element. You can
alter one or both points of force application, change the force from ACTIONONLY to ACTIONREACTION, or the reverse, or change the force from TRANSLATION to ROTATION, or the reverse. In
addition, you can change the force definition function expression or SFOSUB parameter list, or switch
the definition between function expression and subroutine.
After a change to an SFORCE, Adams/Solver (C++) reprocesses the model at the next SIMULATE
command, as if it had just been read in from the dataset. During the reprocessing, Adams/Solver (C++)
checks the entire model for consistency, reinitializes user subroutines, and recomputes initial conditions.
While checking, Adams/Solver (C++) verifies that the model is still valid with the new SFORCE. If, for
example, the SFORCE function expression refers to an inactive element, Adams/Solver (C++) issues an
error.
Adams/Solver (C++) also reinitializes all user subroutines to re-establish functional dependencies. For
each element that refers to a user-written subroutine, Adams/Solver (C++) calls the user-written
subroutine with IFLAG set to true.
Prior to the actual simulation, Adams/Solver (C++) computes initial conditions for the model. If this is
the first simulation, Adams/Solver (C++) begins with the positions and velocities specified in the dataset.
If you ran a previous simulation, Adams/Solver (C++) begins with the final displacements and velocities.
Adams/Solver (C++) then adjusts the initial conditions to ensure that they are consistent with the model
186 Adams/Solver
C++ Commands
constraints. If this is the first simulation, Adams/Solver (C++) also maintains any user supplied joint
initial-conditions and positions specified as EXACT.
Examples
SFORCE/201,FUNCTION=-10.*VR(101,201)
This SFORCE command changes the force definition for SFORCE 201.
SFORCE/6,I=28
This SFORCE command applies SFORCE 6 to Marker 28, leaving the J marker unchanged.
See other Forces available.
SHOW 187
C++ Commands
SHOW
The SHOW command lists statistics for any of these topics: CPU time, graphics options, status, and time.
Format
ALL
SHOW [CPUTIME] [GROPTIONS]
STATUS=
,GRAPHICS
[TIME]
,REQUESTS
,SIMULATION
CPUTIME
Lists the current total use of CPU time for the execution.
GROPTIONS
TIME
See other Information available.
188 Adams/Solver
C++ Commands
SIMULATE
The SIMULATE command specifies the type of simulation you want Adams/Solver (C++) to run. It also
defines the run time and the number or size of the output steps.
Format
Arguments
ACCELERATION
DISPLACEMENT
DTOUT=r
Specifies the size of the output step for the analysis in model time units.
Range: DTOUT > 0
DURATION
SIMULATE 189
C++ Commands
DYNAMICS
END
STATICS
use the STATICS argument and you do not specify an end time or
steps.
Performs a quasi-static equilibrium simulation if you use the
190 Adams/Solver
C++ Commands
TRANSIENT
VELOCITY
Extended Definition
Adams/Solver (C++) allows you to do one or more analyses on the same dataset until the STOP
command is issued. These analyses can be different types as long as they meet the degree-of-freedom
requirements for that type of analysis. For example, it is often useful or necessary to do a static
equilibrium analysis on a model to establish equilibrium conditions before doing a dynamic analysis.
Tip:
Note the distinction between END and DURATION. At time zero, a SIMULATE
command with END=1 or DURATION=1 indicates an end time of one second. At time one
second, a SIMULATE command with END=1.5 indicates an end time of 1.5 seconds; a
SIMULATE command with DURATION=1.5 indicates an end time of 2.5 seconds.
SIMULATE 191
C++ Commands
Caution:
computes the velocity and acceleration initial conditions even if they were
computed prior to the static simulation. This ensures that the velocity and
acceleration initial conditions are consistent with the displacements from the static
simulation.
When you use END and STEPS parameters with the SIM/STAT command, time
increments past time = 0. As such, initial velocities are no longer valid and are not
considered in subsequent dynamic analyses.
If a static simulation directly follows a dynamic simulation, Adams/Solver (C++)
sets the velocities and accelerations (except gravity) to zero and repeats the
displacement initial conditions.
Adams/Solver (C++) automatically performs a dynamic analysis for kinematic
systems that include DIFFs and sets the MODE analysis constant to 4 (not 1).
The STEPS and DTOUT arguments can indirectly affect the accuracy of the
This SIMULATE command instructs Adams/Solver (C++) to perform a kinematic analysis from the
begin time to 5 time units with 200 output steps. If this is the first analysis on this dataset in this session,
the begin time is 0 time units. Adams/Solver (C++) can execute this command only if the system has zero
degrees of freedom.
SIMULATE / KINEMATICS, DURATION=2, DTOUT=.025
This SIMULATE command instructs Adams/Solver (C++) to perform a kinematic analysis for 2 time
units with one output step every .025 time units.
See other Simulation available.
192 Adams/Solver
C++ Commands
SPLINE
The SPLINE command modifies or lists an existing SPLINE statement. You can change the values of the
SPLINE data, and in the process increase or decrease the number of X data or the number of curve
families. You cannot change the extrapolation method, nor can you read data from a file.
For information on the corresponding statement, see the SPLINE statement
For information on the corresponding subroutine, see the SPLINE_READ subroutine.
Format
SPLINE/id
, X=x1, x2, x3, x4 [, . . . , xn]
, Y=y1, y2, y3, y4 [, . . . , yn]
, LIST
or
SPLINE/id
, X=x1, x2, x3, x4 [, . . . , xn]
, Y=z1, y11, y12, y13, y14 [, . . . ,y1n], Y=z2, y21, y22, y23, y24 [, . . . ,y2n], Y=z3, y31, y32, y33, y34 [, .
. . ,y4n], Y=z4, y41, y42, y43, y44 [, . . . ,y4n][, . . . , Y=zm, ym1, ym2, ym3, ym4,[, . . . ,ymn]]
, LIST
X=x1,x2,x3,x4[ , . . . , xn]
allow expressions.
Values must be in increasing order: x1< x2 < x3, and so
on.
Y=y1,y2,y3,y4 [ , . . . , yn]
allow expressions.
SPLINE 193
C++ Commands
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]]
allow expressions.
Values for z must be in increasing order: z1 < z2 < z3, and
so on.
LIST
See other Reference data available.
194 Adams/Solver
C++ Commands
SPRINGDAMPER
The SPRINGDAMPER command redefines and/or lists the data for a SPRINGDAMPER statement. You
cannot redefine the I and J marker defining the springdamper or the translational/rotational characteristic,
but you can redefine other characteristics.
Format
Arguments
ANGLE=r
Respecifies the reference angle for the torsional spring. If the reference torque of the
spring is zero, ANGLE equals the free angle. Adams/Solver (C++) assumes ANGLE is
in radians unless a D is added after the value.
C=r
Respecifies the viscous damping coefficient for the force. The force due to damping is
zero when the system is at rest. C must be greater than or equal to zero.
CT=r
Respecifies the viscous damping coefficient for the torque. The torque due to damping
is zero when the system is at rest. CT must be in units of torque per radian per unit of
time.
Range: CT > 0
FORCE=r
K=r
KT=r
Respecifies the spring stiffness coefficient for the torque. KT must be in units of torque
per radian.
Range: KT > 0
SPRINGDAMPER 195
C++ Commands
LENGTH=r Respecifies the reference LENGTH for the spring. If the reference force of the spring is
zero, LENGTH equals the free length.
Range: LENGTH > 0
LIST
196 Adams/Solver
C++ Commands
STOP
The STOP command terminates execution of Adams/Solver (C++) in the interactive mode and returns
control to the operating system.
Format
STOP
See other Simulation available.
STRING 197
C++ Commands
STRING
The STRING command redefines and/or lists the data for a STRING statement.
Format
STRING=c
Respecifies the string to be stored. The STRING argument and value must appear
together on one 80-character line. If STRING is abbreviated to S and starts a line, the
supplied string can be as long as 1024 characters.
LIST
Caution:
The following characters are not permitted in a STRING argument because they are
delimiters in the Adams/Solver (C++) command language: comma (,), semicolon (;),
ampersand (&), and exclamation point (!). This is because the comma indicates that
additional Adams/Solver (C++) arguments follow, the semicolon indicates that additional
Adams/Solver (C++) statements follow on the same line, the ampersand indicates that the
next line is a continuation of the statement on this line, and the exclamation point indicates
that Adams/Solver (C++) is to stop reading the line.
198 Adams/Solver
C++ Commands
TIME
The TIME command shows the simulation time, integration step size, number of function evaluations
completed, and number of integration steps completed.
Format
TIME
Examples
TIME
Current Simulation Time
= 5.0E-02
= 1.0E-03
= 133
= 59
VARIABLE 199
C++ Commands
VARIABLE
A VARIABLE command redefines or lists data for a VARIABLE statement that defines a variable in terms
of a scalar algebraic equation. The variable can be either independently used, or as part of the PINPUT,
POUTPUT, or ARRAY statement.
Format
Arguments
LIST
ROUTINE=libname::subname
The VARIABLE command redefines or lists a user-defined algebraic equation and its initial value. After
a change to a variable, Adams/Solver (C++) reprocesses the model at the next SIMULATE command, as
if it had just been read in from the dataset. During the reprocessing, Adams/Solver (C++) checks the
entire model for consistency, reinitializes user subroutines, and recomputes initial conditions.
200 Adams/Solver
C++ Commands
Adams/Solver (C++) also reinitializes user subroutines to re-establish functional dependencies. For each
element that refers to a user-written subroutine, Adams/Solver (C++) calls the user-written subroutine
with the IFLAG argument set to true.
Tip:
Caution:
and then try to alter IC, Adams/Solver (C++) rejects the entire VARIABLE
command.
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.
See other Reference data available.
VFORCE 201
C++ Commands
VFORCE
The VFORCE command redefines and/or lists the data for a VFORCE statement that defines a
translational vector force element as specified using three orthogonal components.
Format
Arguments
FX=e
FY=e
FZ=e
202 Adams/Solver
C++ Commands
JFLOAT=id
LIST
RM=id
ROUTINE=libname::subname
Extended Definition
The VFORCE statement lists or redefines a force element that consists of three mutually orthogonal
translational force components. You can alter one or both points of force application, change the force
reference marker, and change the force function expressions or the parameters passed to the VFOSUB
user-written subroutine.
After a change to a VFORCE, Adams/Solver (C++) reprocesses the model at the next SIMULATE
command, as if it had just been read in from the dataset. During the reprocessing, Adams/Solver (C++)
checks the entire model for consistency, reinitializes user subroutines, and recomputes initial conditions.
While checking, Adams/Solver (C++) verifies that the model is still valid with the new VFORCE. If, for
example, the VFORCE function expression refers to an inactive element, Adams/Solver (C++) issues an
error.
Adams/Solver (C++) also reinitializes all user subroutines to re-establish functional dependencies. For
each element that refers to a user-written subroutine, Adams/Solver (C++) calls the user-written
subroutine with IFLAG set to true.
Prior to the actual simulation, Adams/Solver (C++) computes initial conditions for the model. If this is
the first simulation, Adams/Solver (C++) begins with the positions and velocities specified in the dataset.
If you ran a previous simulation, Adams/Solver (C++) begins with the final displacements and velocities.
Adams/Solver (C++) then adjusts the initial conditions to ensure that they are consistent with the model
constraints. If this is the first simulation, Adams/Solver (C++) also maintains any user supplied joint
initial-conditions and positions specified as EXACT.
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.
VFORCE 203
C++ Commands
Caution:
The user-defined functions FX, FY, and FZ should be smooth, continuous, and singlevalued. These conditions make the solution process very effective.
Example
VFORCE/10,LIST &
,FX= -90.5*Dx(109,102,102) - 9.05*Vx(109,102,102,102)\ &
,FY= -90.5*Dy(109,102,102) - 9.05*Vy(109,102,102,102)\ &
,FZ=-750.8*Dz(109,102,102) - 75.08*Vz(109,102,102,102)
204 Adams/Solver
C++ Commands
VTORQUE
The VTORQUE command redefines and/or lists the data for a VTORQUE statement that defines a vector
torque that consists of three orthogonal components.
Format
Arguments
I=id
LIST
ROUTINE=libname::subname
RM=id
VTORQUE 205
C++ Commands
TX=e
TY=e
TZ=e
Extended Definition
The VTORQUE command lists or redefines a force element that consists of three mutually orthogonal
translational torque components. You can alter one or both points of torque application, change the torque
reference marker, and change the torque function expressions or the parameters passed to the VTOSUB
user-written subroutine.
After a change to a VTORQUE, Adams/Solver (C++) reprocesses the model at the next SIMULATE
command, as if it had just been read in from the dataset. During the reprocessing, Adams/Solver (C++)
checks the entire model for consistency, reinitializes user subroutines, and recomputes initial conditions.
While checking, Adams/Solver (C++) verifies that the model is still valid with the new VTORQUE. If,
for example, the VTORQUE function expression refers to an inactive element, Adams/Solver (C++)
issues an error.
Adams/Solver (C++) also reinitializes all user subroutines to re-establish functional dependencies. For
each element that refers to a user-written subroutine, Adams/Solver (C++) calls the user-written
subroutine with IFLAG set to true.
Prior to the actual simulation, Adams/Solver (C++) computes initial conditions for the model. If this is
the first simulation, Adams/Solver (C++) begins with the positions and velocities specified in the dataset.
If you ran a previous simulation, Adams/Solver (C++) begins with the final displacements and velocities.
Adams/Solver (C++) then adjusts the initial conditions to ensure that they are consistent with the model
constraints. If this is the first simulation, Adams/Solver (C++) also maintains any user supplied joint
initial-conditions and positions specified as EXACT.
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.
206 Adams/Solver
C++ Commands
Caution:
The user-defined functions TX, TY, and TZ should be smooth, continuous, and singlevalued. These conditions make the solution process very effective.
2 Adams/Solver
Statement Name
Dataset delimiter
END
TITLE
PART
FLEX_BODY
POINT_MASS
bordered
GRAPHICS
MARKER
Constraints
COUPLER
CVCV
GEAR
JOINT
JPRIM
MOTION
PTCV
UCON
Forces
ACCGRAV
BEAM
BUSHING
CONTACT
FIELD
FRICTION
GFORCE
MFORCE
NFORCE
SFORCE
SPRINGDAMPER
VFORCE
VTORQUE
Type of Statement
Statement Name
Reference data
ARRAY
CURVE
MATRIX
PINPUT
POUTPUT
SPLINE
STRING
Analysis parameters
DEBUG
EQUILIBRIUM
IC
INTEGRATOR
KINEMATICS
PREFERENCES
SENSOR
UNITS
Output
FEMDATA
LIST/NOLIST
MREQUEST
OUTPUT
REQUEST
RESULTS
4 Adams/Solver
ACCGRAV
The ACCGRAV statement specifies the magnitude and direction of the acceleration of gravity. In
conjunction with the part masses, the gravitational field defines a body force at the center of gravity in
each part.
Format
Arguments
IGRAV
JGRAV
KGRAV
Examples
ACCGRAV/JGRAV=-386.088
This ACCGRAV statement defines the gravitational constant of 386.088, acting along the y-axis of the
ground coordinate system (GCS) in the negative direction.
See other Forces available.
ARRAY 5
Adams/Solver (FORTRAN) Statements
ARRAY
The ARRAY statement defines a list of input variables (U), state variables (X), output variables (Y), or
initial conditions (IC) associated with system modeling elements such as GSE, LSE, and TFSISO (see
GSE, LSE and TFSISO). IC ARRAY's or ARRAY's without a type can also be used to define a list of
constants. These values may be accessed in function expressions or user-written subroutines.
Format
IC
NUMBERS=r1[,r2,...]
SIZE=i
Allows you to define the size of the array. In cases where Adams/Solver
(FORTRAN) calculates the SIZE differently from the SIZE that you
supply, Adams/Solver (FORTRAN) returns an error or warning message.
6 Adams/Solver
Extended Definition
The ARRAY statement defines a list of input variables (U), state variables (X), output variables (Y), and
initial conditions (IC) associated with system modeling elements such as GSE, LSE, and TFSISO.
ARRAY may also be used to define a list of constants. These values may be accessed in function
expressions or user-written subroutines.
There are three basic variations of the ARRAY statement:
The X and Y arrays designate the state and output variable arrays for a systems element.
For the X and Y arrays, the corresponding systems modeling element automatically determines the size
of the array and checks it against the ARRAY statements SIZE value (if given).
The IC and SIZE parameters are optional. Adams/Solver (FORTRAN) determines the actual size of the
array during input-file parsing as it counts the NUMBERS argument. However, if you provide a value
for SIZE, Adams/Solver (FORTRAN) checks the count for consistency.
For X and Y arrays, you should reference the array as the state variable array or output variable array of
one of the system elements in the dataset, either LSE, GSE, or TFSISO. U and IC arrays may exist
independently. Grouping VARIABLES in a U array does not offer any computational advantage,
although it might have a convenience value.
ARRAY 7
Adams/Solver (FORTRAN) Statements
The SIZE argument, if used, should match the number of entries in the VARIABLES or NUMBERS
arguments or the size needed for the associated element. Adams/Solver (FORTRAN) provides the SIZE
argument mainly for your convenience in dataset creation. For LSE arrays, the X size is the row
dimension of the A and B matrix, and the Y size is the row dimension of the C and D matrix. For TFSISO
arrays, the transformation from the transfer function form to canonical state space form determines the
X size; the size of Y and U is always one. For GSE arrays, X is size NS as defined in the matching GSE
statement and Y is size NO, as defined in the same GSE statement.
Both function expressions and user-written subroutines can access the array values. Function expressions
use the function ARYVAL (id, nseq) to access the values. The id specifies the identifier of the ARRAY,
and nseq specifies the position of the desired value in the ARRAY statement. To access all the elements
of an array from a user written subroutine, you should call the subroutine SYSARY (see the SYSARY
subroutine). To access one element of an ARRAY in a subroutine, you should call the subroutine
SYSFNC.
Examples
8 Adams/Solver
BEAM
The BEAM statement defines a massless elastic beam with a uniform cross section. The beam transmits
forces and torques between two markers in accordance with Timoshenko beam theory.
Format
Arguments
AREA=r
Specifies the uniform area of the beam cross section. The centroidal axis must
be orthogonal to this cross section.
ASY=r
Specifies the correction factor (that is, the shear area ratio) for shear deflection
in the y direction for Timoshenko beams.
A Qy
ASY = ------2 ------ dA
Iy A lz
2
BEAM 9
Adams/Solver (FORTRAN) Statements
ASZ=r
Specifies the correction factor (that is, the shear area ratio) for shear deflection
in the z direction for Timoshenko beams.
A Qz 2
ASZ = -----2- ------ dA
Iz A ly
r01
r02
r03
r04
r05
r06
r07
r08
r09
r10
r11
r12
r13 r16
r14 r17 r19
r15 r18 r20 r21
Enter the elements by columns from top to bottom, then by rows from left to
right. If you do not use either CMATRIX or CRATIO, CMATRIX defaults to a
matrix with thirty-six zero entries; that is, r1 through r21 each default to zero.
10 Adams/Solver
CRATIO=R
Establishes a ratio for calculating the damping matrix for the beam.
Adams/Solver multiplies the stiffness matrix by the value of CRATIO to obtain
the damping matrix.
Defaults: 0
EMODULUS=r
GMODULUS=r
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
r
J = -------2
Denote the area moments of inertia about the neutral axes of the beam cross
sectional areas (y-y and z-z). These are sometimes referred to as the second
moment of area about a given axis. They are expressed as unit length to the
fourth power. For a solid circular section,
4
Iyy=Izz=
r
-------4
Defines the underformed length of the beam along the x-axis of the J marker.
Extended Definition
To model the effects of a beam, Adams/Solver (FORTRAN) uses a linear translational and linear
rotational action-reaction force between two markers. The forces the beam produces are linearly
dependent on the displacements, rotations, and corresponding velocities between the markers at its
endpoints.
The figure below shows the two markers (I and J) that define the extremities of the beam and indicates
the twelve forces (s1 to s12) it produces.
BEAM 11
Adams/Solver (FORTRAN) Statements
Massless Beam
The x-axis of the J marker defines the centroidal axis of the beam. The y-axis and z-axis of the J marker
are the principal axes of the cross section. They are perpendicular to the x-axis and to each other. When
the beam is in an undeflected position, the I marker has the same angular orientation as the J marker, and
the I marker lies on the x-axis of the J marker a distance LENGTH away.
The beam statement applies the following forces to the I marker in response to the relative motion of the
I marker with respect to the J marker:
Axial forces (s1 and s7)
Bending moments about the y-axis and z-axis (s5, s6, s11, and s12)
Twisting moments about the x-axis (s4 and s10)
Shear forces (s2, s3, s8, and s9)
The following constitutive equations define how Adams/Solver uses the data for a linear field to apply a
force and a torque to the I marker depending on the displacement rotation and velocity of the I marker
relative to the J marker.
12 Adams/Solver
Fx
K 11 0
Fy
Fz
0 K 22 0
0 K 26
0 K 33 0 K 35 0
Ty
0 K 53 0 K 55 0
Tz
0 K 62 0
Tx
0 K 44 0
0
0 K 66
xL
y
z
a
b
c
c 11 c 21 c 31 c 41 c 51 c 61 V x
c 21 c 22 c 32 c 42 c 52 c 62 V y
c 31 c 32 c 33 c 43 c 53 c 63 V z
c 41 c 42 c 43 c 44 c 54 c 64 x
c 51 c 52 c 53 c 54 c 55 c 65 y
c 61 c 62 c 63 c 64 c 65 c 66 z
where:
Fx, Fy, and Fz are the measure numbers of the translational force components in the coordinate
x , y , and z are the components of the angular velocity of the I marker with respect to the
J marker, as seen by the J marker and measured in the J marker coordinate system.
Cij are the entries of the damping matrix either specified by the CMATRIX option or computed
BEAM 13
Adams/Solver (FORTRAN) Statements
Adams/Solver (FORTRAN) applies an equilibrating force and torque at the J marker, as defined by the
following equations:
Fj = - Fi
Tj = - Ti - L x 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 beams physical properties, which Adams/Solver
(FORTRAN) uses to calculate the matrix entries.
Tip:
with characteristics unlike those the BEAM statement assumes. For example, a
FIELD statement should be used to define a beam with a nonuniform cross section
or a beam with nonlinear material characteristics.
The beam element in Adams/Solver is similar to those in most finite element
programs. That is, the stiffness matrix that Adams/Solver (FORTRAN) computes
is the standard beam element stiffness matrix.
The USEXP option on the MARKER statement may make it easier to direct the x-
14 Adams/Solver
Caution:
The K1 and K2 terms used by MSC.NASTRAN for defining the beam properties
using PBEAM are inverse of the ASY and ASZ used by Adams/Solver
(FORTRAN).
When the x-axes of the markers defining a beam are not collinear, the beam
unlike most other Adams/Solver force statements, for which the z-axis is the
significant axis.) Therefore, the I marker must have a positive x displacement with
respect to the J marker when viewed from the J marker. In its undeformed
configuration, the orientation of the I and the J markers must be the same.
The damping matrix that CMATRIX specifies should be positive semidefinite.
This ensures that damping does not feed energy into the system. Adams/Solver
(FORTRAN) does not warn you if CMATRIX is not positive semidefinite.
When the beam element angular deflections are small, the stiffness matrix
deflecting the I marker produces different results than holding the I marker fixed
and deflecting the J marker by the same amount. This asymmetry occurs because
the coordinate system frame that the deflection of the BEAM is measured in
moves with the J marker.
Examples
A cantilevered stainless steel beam is to be modeled with a circular cross section that has the loading
shown in the figure below.
BEAM 15
Adams/Solver (FORTRAN) Statements
A weight of 17.4533 lbf at the free end of the beam with a 100-inch axial offset in the negative y direction
causes torsion to the beam as shown in the figure above. The following statement defines this beam:
BEAM/0201, I=0010, J=0020, LENGTH=100
, IXX=100, IYY=50, IZZ=50, AREA=25.0663
, ASY=1.11, ASZ=1.11, EMOD=28E6, GMOD=10.6E6,
, CRATIO=0.0001
The beam lies between Marker 0010 and Marker 0020. The length of the beam is 100 inches; its torsional
constant is 100 inch4; its principal area moments of inertia about the y-axis is 50 inch4, and about the zaxis is 50 inch4; its cross-sectional area is 25.0663 inch2; its shear area ratio in the y direction is 1.11; its
shear area ratio in the z direction is 1.11; its modulus of elasticity is 28E6 psi; its shear modulus is 10.6
psi; and its damping ratio relative to the stiffness matrix Adams/Solver (FORTRAN) calculates is 0.0001.
Note that the beam ends belong to different parts.
References
1. Roark's Formulas for Stress and Strain, Young, Warren C., Sixth Edition, page 201. New York:
McGraw Hill, 1989.
16 Adams/Solver
BUSHING
The BUSHING statement defines a massless bushing with linear stiffness and damping properties.
Format
Arguments
C=r1,r2,r3
Specifies three viscous damping coefficients for the force transferred by the
bushing. The three coefficients multiply the relative translational velocity
components of the I marker with respect to the J marker as seen by the J marker
and along the x-, y-, and z-axis of the J marker. The force due to damping is zero
when there is no relative translational velocity between the two markers. C must
be in units of force per unit length per unit of time.
Default: 0,0,0
Range: C > 0
CT=r1,r2,r3
Specifies three viscous damping coefficients for the torque transferred by the
bushing. The three coefficients multiply the components of the relative angular
velocity of the part containing the I marker with respect to the part containing the
J marker as expressed in the x-, y-, and z-axis of the J marker. The torque due to
damping is zero when there is no relative angular velocity between the two
markers. CT must be in units of torque per radian per unit of time.
Default: 0,0,0
Range: CT > 0
FORCE=r1,r2,r3
Specifies three constant force (preload) values. Constant values indicate the force
components along the x-, y-, and z-axis of the J marker when both the relative
displacement and the relative velocity of the I and J markers are zero.
Default: 0,0,0
I=id, J=id
Specifies the identifiers of the two markers between which the bushing is placed.
BUSHING 17
Adams/Solver (FORTRAN) Statements
K=r1,r2,r3
Specifies three stiffness coefficients for the force transferred by the bushing. The
three coefficients multiply the three translational displacement components of the
I marker with respect to the J marker as expressed in the x-, y-, and z-axis of the J
marker. K must be specified in terms of force per unit of deformation.
Default: 0,0,0
Range: K > 0
KT=r1,r2,r3
Specifies three stiffness coefficients for the torque transferred by the bushing. The
three coefficients multiply the three rotational displacement components of the I
marker axes relative to the J marker axes as expressed in the x-, y-, and z-axis of
the J marker. KT must be in units of torque per radian.
Default: 0,0,0
Range: KT > 0
TORQUE=r1,r2,r3 Specifies three constant torque (preload) values. Constant values indicate the
torque components about the x-, y-, and z-axis of the J marker when both the
relative displacement and the relative velocity of the I and the J markers are zero.
Default: 0,0,0
Extended Definition
The BUSHING statement defines a massless bushing with linear stiffness and damping properties. The
BUSHING statement applies a force and torque to two parts. You specify a marker on each part for force
or torque application.
Each force consists of three components in the coordinate system of the J marker, one in the x-axis
direction, one in the y-axis direction, and one in the z-axis direction.
Likewise each torque consists of three components in the coordinate system of the J marker: one about
the x-axis, one about the y-axis, and one about the z-axis. The force is linearly dependent upon the
relative displacement and the relative velocity of the two markers. The torque is dependent upon the
relative angle of rotation and the relative rotational velocity of the parts containing the specified markers.
A BUSHING statement has the same constitutive relation form as a FIELD statement. The primary
difference between the two statements is that certain coefficients (Kij and Cij, where i j) are zero for the
BUSHING statement. Only the diagonal coefficients (Kii and Cii) are defined for a BUSHING.
18 Adams/Solver
Fx
K 11 0
0 K 22 0
0 K 33 0
0 K 44 0
Ty
0 K 55 0
Tz
Fy
Fz
Tx
Vx
F1
0 c 22 0
Vy
F2
0 c 33 0
Vz
0 c 44 0
0 c 55 0
T2
0 c 66 z
T3
c 11 0
0 K 66
x
y
z
a
b
c
F3
T1
Fx, Fy, and Fz are the measure numbers of the translational force components in the coordinate system of
the J marker. The terms x, y, and z are the translational displacements of the I marker with respect to the
J marker measured in the coordinate system of the J marker. The terms Vx, Vy, and Vz are the time
derivatives of x, y, and z, respectively. The terms F1, F2, and F3 represent the measure numbers of any
constant preload force components in the coordinate system of the J marker.
Tx, Ty, and Tz are the rotational force components in the coordinate system of the J marker. The terms a,
b, and c are the relative rotational displacements of the I marker with respect to the J marker as expressed
in the x-, y-, and z-axis, respectively, of the J marker. The terms
velocity components of the I marker with respect to the J marker, measured in the coordinate system of
the J marker. The terms T1, T2, and T3 are the measure numbers of any constant torque in the coordinate
system of the J marker.
Adams/Solver (FORTRAN) applies an equilibrating force and torque to the J marker, as defined by the
following equations:
Fj=-Fi
Tj = - Ti -
x Fi
is the instantaneous deformation vector from the J marker to the I marker. While the force at the J
marker is equal and opposite to the force at the I marker, the torque at the J marker is usually not equal
to the torque at the I marker because of the deformation.
BUSHING 19
Adams/Solver (FORTRAN) Statements
The BUSHING only models linear bushings. The GFORCE or FIELD (with a FIESUB) may be used
to model nonlinear bushings.
Caution:
For the rotational constitutive equations to be accurate, at least two of the rotations (a, b,
c) must be small. That is, two of the three values must remain smaller than 10 degrees. In
addition, if a becomes greater than 90 degrees, b becomes erratic. If b becomes greater than
90 degrees, a becomes erratic. Only c can become greater than 90 degrees without causing
convergence problems. For these reasons, it is best to define your bushing such that angles
a and b (not a and c and not b and c) remain small.
Examples
BUSHING/1022, I=10, J=22, K=5000,5000,2000, C=5,5,2
, KT=50000,50000,0, CT=50,50,0
This BUSHING statement describes a bushing with translational spring rates of 5000 units in both the xaxis and the y-axis directions of Marker 22 and of 2000 units in the z-axis direction of Marker 22. The
corresponding damping rates for the force are 5 units in both the x- and y-axis directions of Marker 22
and 2 units in the z-axis direction of Marker 22. The rotational spring rates are 50000 units about the xand y-axis of Marker 22. The corresponding damping rates for the torque are 50 units in both the x- and
y-axis directions of Marker 22 and zero units in the z-axis direction of Marker 22. Since the z components
of KT and CT are zero, the I marker can rotate about the z-axis of the J marker without generating any
torque. There are no FORCE or TORQUE values because there is no initial load (preload) associated with
the input positions of the markers.
See other Forces available.
20 Adams/Solver
CONTACT
The CONTACT statement lets you define a two- or three-dimensional contact between a pair of
geometric objects. Adams/Solver (FORTRAN) models the contact as a unilateral constraint, that is, as a
force that has zero value when no penetration exists between the specified geometries, and a force that
has a positive value when penetration exists between two geometries.
The CONTACT statement supports:
Multiple contacts
Dynamic friction
Contact between three-dimensional solid geometries
Contact between two-dimensional geometries
It does not support non-solid three-dimensional geometries, such as shells that do not encompass a
volume and sheets. It also does not support contact between a two-dimensional and a three-dimensional
geometry.
Adams/Solver (FORTRAN) has two geometry engines that it uses for three-dimensional contacts. It uses
Parasolid, a geometry toolkit from EDS/Unigraphics and RAPID. Currently, RAPID is the default and
Adams/Solver (FORTRAN) supports version 2.01.
For two-dimensional contacts, Adams/Solver (FORTRAN) uses an internally developed geometry
engine. Currently, Adams/Solver (FORTRAN) supports Parasolid 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.
Note:
You can only define two-dimensional contacts between bodies that are constrained to be in
the same plane. This is usually done with planar or revolute joints or an equivalent set of
constraints that enforce the planarity.
Failure to enforce planarity will result in a run-time error, when the bodies go out of plane
during a simulation.
View a table that shows Supported Geometry Combinations for the CONTACT statement. If you use
unsupported geometry combinations, you will receive an error.
Note:
You can set the default geometry library. See the PREFERENCES statement.
CONTACT 21
Adams/Solver (FORTRAN) Statements
Format
22 Adams/Solver
Arguments
AUGMENTED_LAGRANGIA Refines the normal force between two sets of rigid geometries that
N_FORMULATION
are in contact. It uses iterative refinement to ensure that penetration
between the geometries is minimal. It also ensures that the normal
force magnitude is relatively insensitive to the penalty or stiffness
used to model the local material compliance effects.
You can use this formulation only with the POISSON model for
normal force.
COULOMB_FRICTION =
off/on
Used when you specify the IMPACT model for calculating normal
forces. DAMPING defines the damping properties of the contacting
material. You should set the damping coefficient is about one percent
of the stiffness coefficient.
Range: DAMPING > 0
DMAX = r
Used when you specify the IMPACT model for calculating normal
forces. DMAX defines the penetration at which Adams/Solver turns
on full damping. Adams/Solver uses a cubic STEP function to
increase the damping coefficient from zero, at zero penetration, to
full damping when the penetration is DMAX. A reasonable value for
this parameter is 0.01 mm. For more information, refer to the
IMPACT function.
Range: DMAX > 0
EXPONENT=r
Used when you specify the IMPACT model for calculating normal
forces. Adams/Solver (FORTRAN) models normal force as a
nonlinear spring-damper. If PEN is the instantaneous penetration
between the contacting geometry, Adams/Solver calculates the
contribution of the material stiffness to the instantaneous normal
forces as STIFFNESS * (PENALTY)**EXPONENT. For more
information, see the IMPACT function.
Exponent should normally be set to 1.5 or higher.
Range: 0 < EXPONENT
CONTACT 23
Adams/Solver (FORTRAN) Statements
FRICTION_TRANSITION_V
ELOCITY = r
FRICTION_ROUTINE =
library::function
IGEOM = id
JGEOM = id
IFLIP_GEOMETRY =
id1,id2,...,idN
IMPACT
24 Adams/Solver
JFLIP_GEOMETRY =
id1,id2,...,idN
MU_DYNAMIC = r
MU_STATIC=r
NORMAL_FUNCTION =
USER(r1,[,...,r30])
NORMAL_ROUTINE =
library::function
PENALTY=r
POISSON
CONTACT 25
Adams/Solver (FORTRAN) Statements
RESTITUTION_COEFFICIEN The coefficient of restitution models the energy loss during contact.
T=r
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_V
ELOCITY = r
Specifies a material stiffness that you can use to calculate the normal
force for the impact model.
In general, the higher the STIFFNESS, the more rigid or hard the
bodies in contact are. Also note that the higher the STIFFNESS is,
the harder it is for an integrator to solve through the contact event.
Extended Definition
For more information on the key issues about the CONTACT statement, select one of the following:
Contact Kinematics
Outward Normal Definition
Contact Kinetics
Contact Normal Force Calculation
26 Adams/Solver
Contact Kinematics
The CONTACT statement lets you define contact between two geometry objects that you specify in
GRAPHICS entities in an Adams dataset (see the GRAPHICS statement). Adams/Solver (FORTRAN)
supports:
Both two- and three-dimensional geometry.
Two-dimensional or planar contact between POINT, PLANE, CIRCLE, ARC, and CURVE
geometries.
Three-dimensional contact between CYLINDER, ELLIPSOID, BOX, FRUSTUM, and
EXTERNAL geometries.
Currently, Adams/Solver (FORTRAN) does not support contact between two- and three-dimensional
geometries.
The CURVE and the EXTERNAL graphics types are the generic geometry modeling entities. These
provide you with a way to specify arbitrarily complex two- and three-dimensional geometric shapes,
respectively. For both of these entities, the data is in files, which are usually generated by a geometry
modeling system. The CURVE object is specified as a series of x, y, and z points that are a function of
an independent curve parameter. The three-dimensional EXTERNAL object is more complex, and is
specified in the format of the geometry modeling system. Parasolid from Unigraphics is the default
geometry modeling system in Adams/Solver (FORTRAN). This is a well recognized, state-of-the-art
geometry modeling system that is used in many CAD systems. Parasolid geometry files typically have
the extension xmt_txt.
During a simulation, the first step is to find out if the contact is occurring between the geometry pairs
identified in the CONTACT statements. If there is no contact, there is no force.
If contact exists, the geometry modeling system calculates the location of the individual contact points
and the outward normals to the two geometries at the contact point. Adams/Solver (FORTRAN)
calculates the normal and slip velocities of the contact point from this information. Adams/Solver
(FORTRAN) then uses the velocities to calculate the contact force at each individual contact.
Outward Normal Definition
The calculation of the outward normal for geometry is important because it defines where the material
lies and, therefore, determines the direction of the contact normal force.
For three-dimensional solids, which are closed by definition, the outward normal is implicit in the
geometry description, and there is no ambiguity in its definition.
CONTACT 27
Adams/Solver (FORTRAN) Statements
For two-dimensional geometries, especially open curves, there is an ambiguity in calculating the outward
normal. Adams/Solver (FORTRAN) uses the specified geometry to calculate a default outward normal,
but allows the user to reverse this direction using the IFLIP_NORMAL and JFLIP_NORMAL
arguments.
The figure below shows an open curve with eight points defined in the coordinate system of the reference
marker (RM). The z-axis of the RM marker is directed out of the plane of the paper. This defines the binormal for the curve, denoted as
b.
The tangent at point 3 points towards point 4, and is denoted by t . The outward normals are defined as
follows:
n = tb
IFLIP_NORMAL and JFLIP_NORMAL simply reverse the direction of
n.
IFLIP_NORMAL and JFLIP_NORMAL only apply when a single ID is specified in IGEOM and
JGEOM. When lists of geometries are specified by IGEOM and JGEOM, use IFLIP_GEOMETRY and
JFLIP_GEOMETRY to flip normals.
Contact Kinetics
impulsive contact. Two geometries approach each other, undergo a collision, and separate as a
result of the contact. The collision results in the generation of an impulse, that affects the
momentum of the colliding bodies. Adams/Solver (FORTRAN) develops an estimate of the
contact force by modeling the local deformation behavior of the contacting geometries.
Energy loss during the collision is usually modeled as a damping force that is specified with a
damping coefficient or a coefficient of restitution.
Intermittent contact is characterized by two distinct phases. The first is compression, where the
28 Adams/Solver
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.
Persistent contact - Is characterized by contact for relatively long periods of time. External
forces acting between the two bodies serve to maintain continuous contact. Persistent contact is
modeled as a nonlinear spring-damper, the stiffness modeling the elasticity of the surfaces of
contact, and the damping modeling the dissipation of energy. Two bodies are said to be in
persistent contact when the separation velocity, after a collision event, is close to zero. The
bodies, therefore, cannot separate after the contact.
Contact forces are calculated at each individual contact point. Individual contributions are summed up to
compute the net response of the system to the contact event.
Contact Normal Force Calculation
Two models for normal force calculations are available in Adams/Solver (FORTRAN):
IMPACT function model
Coefficient of restitution or the POISSON model
Both force models result from a penalty regularization of the normal contact constraints. Penalty
regularization is a modeling technique in mechanics, in which a constraint is enforced mathematically by
applying forces along the gradient of the constraint. The force magnitude is a function of the constraint
violation.
Contact between rigid bodies theoretically requires that the two bodies not penetrate each other. This can
be expressed as a unilateral (inequality) constraint. The contact force is the force associated with
enforcing this constraint. Handling these auxiliary constraint conditions is usually accomplished in one
of two ways, either through introduction of Lagrange multipliers or by penalty regularization.
For contact problems, the latter technique has the advantage of simplicity; no additional equations or
variables are introduced. This is particularly useful when treating intermittent contact and algorithmically
managing active and inactive conditions associated with unilateral constraints. Additionally, a penalty
formulation is easily interpreted from a physical standpoint. For example, the magnitude of the contact
reaction force is equal to the product of material stiffness and penetration between contacting bodies,
similar to a spring force. For these reasons, Adams/Solver (FORTRAN) uses a penalty regularization to
enforce all contact constraints. The disadvantage of the penalty regularization, however, is that you are
responsible for setting an appropriate penalty parameter, that is, the material stiffness. Furthermore, a
large value for the material stiffness or penalty parameter can cause integration difficulties.
Before presenting the contact normal force models in Adams/Solver (FORTRAN), it is helpful to clearly
define the contact constraints and associated kinematic and kinetic quantities. First, impenetrability of
two approaching bodies is measured with a gap function g, where a positive value of g indicates
penetration. Next, we denote the normal contact force magnitude as Fn, where a positive value indicates
CONTACT 29
Adams/Solver (FORTRAN) Statements
a separation force between the contacting bodies. With this notation in hand, the auxiliary contact
constraints are defined as:
g0
Fn > 0
F n g = 0
dg
F n ------ = 0
dt
The first three equations reflect:
The impenetrability constraint
Separating, normal force constraint
Requirement that the normal force be nonzero only when contact occurs.
The fourth condition is called the persistency condition and it specifies that the normal force is nonzero
only when the rate of separation between the two bodies is zero. The last constraint is particularly
important when you are interested in energy conservation or energy dissipation.
We obtain the IMPACT force model by replacing the first three auxiliary contact conditions with the
following expression:
F n = k*(g**e)
where k (stiffness) is a scalar penalty parameter. The penalization becomes exact as k approaches infinity,
but otherwise allows small violation of the impenetrability constraint. It is important to note that ill
conditioning of the governing equations, and ultimately an integrator failure, will result as the stiffness
becomes excessively large. Therefore, you must appropriately select k while preserving the stability of
the solution.
You can also approximate the compliance of a body by correlating k to the bodies material and geometric
parameters; however, in doing so, you should recall the earlier remark concerning ill conditioning. In an
effort to incorporate general material constitutive relationships for the contacting bodies, as well as
facilitate time integration, Adams/Solver (FORTRAN) augments the previous expression with nonlinear
displacement-dependent, viscous damping terms. The general form of the IMPACT force function is then
given by:
dg
dt
where:
g represents the penetration of one geometry into another.
30 Adams/Solver
dg
------ is the penetration velocity at the contact point.
dt
dg
dt
derived from the persistency condition, Fn * ------ = 0. A penalty regularization of the fourth contact
constraint yields:
dg
dt
Fn = 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:
dg
F n = p ( 1 ) ------
dt
Here is coefficient of restitution and the subscripts ()- and ()+ denote values immediately before and
after contact.
See Learning More about the Contact Detection Algorithm.
The Augmented Lagrangian Technique
When using penalty methods to enforce contact constraints, large penalty (or stiffness) parameters cannot
be used without the risk of making the equations of motion ill conditioned. Ill conditioning manifests
itself in a loss of numerical accuracy during the solution process, causing either slowed convergence or
even divergence. However, softening the penalty parameter compromises the accuracy of the unilateral
contact constraint by permitting excessive penetration between interacting bodies.
To circumvent penalty sensitivity, Adams/Solver (FORTRAN) offers an augmented Lagrangian solution
technique. The method involves an iterative process to calculate the unknown contact force. For example,
in the context of the POISSON force model, with k being the iteration counter, the augmented Lagrangian
iterations are:
CONTACT 31
Adams/Solver (FORTRAN) Statements
The above augmented Lagrangian regularization is more general than the POISSON force model
presented earlier, but encompasses a particular case, when the iteration process is executed only once.
For subsequent iterations, the penalty parameter does not need to be very large, because the accumulated
force during the iterative procedure eliminates the resulting error in the contact constraints.
Contact Friction Force Calculation
Adams/Solver (FORTRAN) uses a relatively simple velocity-based friction model for contacts.
Specifying the frictional behavior is optional. The figure below shows how the coefficient of friction
varies with slip velocity.
32 Adams/Solver
( vs ) = s
( vs ) = s
(0) = 0
( vd ) = d
( vd ) = d
where:
V: Slip velocity at contact point
vs: STICTION_TRANSITION_VELOCITY
vd: FRICTION_TRANSITION_VELOCITY
s : MU_STATIC
d : MU_DYNAMIC
Contact Friction Torque Calculation
If Adams/Solver detects an angular velocity about the contact normal axis, it will apply a torque
proportional to the friction force. The reason for this is that the contact friction force, by itself, cannot
retard relative rotation between bodies; it can only retard relative translation.
The magnitude of the contact friction torque is given by the formula:
2
T = --- RF
3
2
Where R is the radius of the contact area (which is assumed to be circular). The coefficient --- comes from
3
If you need some other formulation of the friction torque, the only alternative is to write
your own friction force subroutine (CFFSUB). An example is given at the end of this
section.
CONTACT 33
Adams/Solver (FORTRAN) Statements
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
This section explains how the various analysis modes deal with contact, and provide modeling tips on
how to successfully negotiate difficult contact events.
Contacts and Static Equilibrium
Both the static and quasi-static equilibrium analysis modes use Newton-Raphson (NR) iterations to solve
the nonlinear algebraic equations of force balance. The Jacobian matrix of first partial derivatives and the
residue of the equations of motion are used to set up an iterative scheme that normally converges to the
solution.
The Jacobian matrix is a measure of the stiffness matrix of the system. The inverse of the Jacobian is,
therefore, the compliance in the system. The NR algorithm ensures that the system solution moves in the
direction of most compliance (least stiffness). When a contact is active, the stiffness in the direction of
the normal force is high, so the NR algorithm modifies the system states to decrease this force. If a contact
is inactive, there is no stiffness in the direction of increasing contact. The NR algorithm will likely
compute a large movement in this direction, leading to excessive penetration. During the very next
iteration, since the contact force may turn on, a large stiffness is detected in this direction, and the
algorithm will change the system to dramatically reduce the amount of penetration. It is not uncommon
34 Adams/Solver
for the algorithm to over-react to this stiffness and move the system sufficiently to deactivate the contact.
The algorithm may never be able to resolve this discontinuity in the system.
Adams/Solver (FORTRAN) anticipates this situation and uses a contact-force-sensing mechanism to
avoid excessive contact. You can further enhance this method, however, by choosing the correct
equilibrium parameters.
Here are some modeling tips for aiding equilibrium (static) analysis (for more information on equilibrium
analysis, see the EQUILIBRIUM statement):
Use EQUILIBRIUM/DYNAMICS to specify that a quasi-dynamic algorithm is to be used to
find static equilibrium. For more information, see the EQUILIBRIUM statement.
If possible, make sure that all contacts are active, and each contact penetration is small. This will
ensure that the contact forces are small, and the system is aware of the contacts.
Set TLIMIT and ALIMIT small enough so gross contact violations are avoided.
Increase the maximum number of iterations, MAXIT, so that you can get to convergence in spite
situations, increase STABILITY (try STABILITY = 0.1). Also increase MAXIT, the maximum
number of iterations you will allow to obtain convergence.
Contacts and Kinematics
In kinematically determinate systems, the system configuration is completely defined by the system
constraints (JOINTs, JPRIMs, COUPLERs, and so on) and MOTIONs. The contact penetration and force
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
CONTACT 35
Adams/Solver (FORTRAN) Statements
STICTION_TRANSITION_VELOCITY.
Too large of a value for MU_STATIC and MU_DYNAMIC.
The following modeling tips will help dynamic analyses. For more information on integrator settings, see
the INTEGRATOR statement.
Reduce STIFFNESS or PENALTY by a factor of 10 and see if the solver can solve through the
contact.
Increase the integration error tolerance using INTEGRATOR/ERROR=value. A larger integrator
or penalty if you are using the Poisson method for normal force calculations. Remember to
decrease PENALTY by a factor of 10 to 100 when you use the
AUGMENTED_LAGRANGIAN.
Use the SI2 formulation. The corrector for this formulation is more stable than standard GSTIFF,
and may solve the problem where the standard GSTIFF failed.
Always run a model without contact friction first, and refine the functioning model by adding
friction later.
If the addition of frictional forces causes numerical difficulties or simulation slowdowns,
Adams/Solver (FORTRAN) has two different geometry engines that can be used for three-dimensional
contact detection. The first geometry engine is based on Parasolid and it is fundamentally the same
engine that was available in ADAMS 11.0 and ADAMS 12.0. Currently, Adams/Solver (FORTRAN)
supports Parasolid version 19.0.17. The second geometry engine is based on RAPID a polygon based
interference detection package developed at the University of North Carolina. Currently, Adams/Solver
(FORTRAN) supports RAPID version 2.01.
The RAPID geometry engine was added to Adams/Solver (FORTRAN) because, for many models, it can
substantially reduce the simulation time. However, because it is polygon based, it is not always as
accurate as the Parasolid geometry engine. Parasolid is an exact boundary-representation geometric
modeler, which makes it highly accurate, but not as fast as a polygon-based engine. For these reasons, it
was decided to include both geometry engines in Adams/Solver (FORTRAN) and give you the capability
of switching from one to the other.
36 Adams/Solver
The RAPID geometry engine is the default geometry in this release of Adams/Solver (FORTRAN). To
switch to the Parasolid geometry engine, you must set the environment variable
MDI_ADAMS_GEOM_LIB to TRUE before starting Adams. Setting environment variables is usually
done using a shell script, a batch file, or the command line.
The RAPID geometry engine has another environment variable, MDI_FACETING_TOLERANCE,
which controls the faceting of 3D geometry. Faceting is the process of approximating the surface of an
object by a mesh of triangles. All polygon-based geometry engines used faceted representations of
surfaces. The default value of MDI_FACETING_TOLERANCE is 300. Increasing this value will result
in a finer mesh of triangles, which gives a more accurate representation of surfaces which are curved.
However, increasing the tolerance also increases the memory requirements of the geometry engine and
adds to the computational overhead, which makes it run slower. Setting the faceting tolerance to values
greater than 1000 is not recommended. Values smaller than 300 will give negligible performance
improvements. The faceting tolerance has no effect on inherently polygonal surfaces such as boxes.
Tip:
If you notice that energy is dissipated during contact events, note the following:
Impact method - A three-dimensional contact with zero damping can exhibit
some dissipation of energy during the impact. The dissipation is due to the
numerics of the integration algorithm. To reduce the dissipation, reduce the time
step or tighten (decrease) the error tolerance.
Restitution method - A three-dimensional contact with coefficient of restitution
set to one should conserve energy. If you notice some dissipation, try activating the
Augmented Lagrangian or increasing the PENALTY argument. Recall that the
larger the PENALTY argument, the more exact the contact constraint will be
enforced. In the case of intermittent contact and a restitution coefficient set to one,
a larger penalty parameter more exactly enforces the conservation of momentum
during the contact event.
The PENALTY argument is analogous to the stiffness in the IMPACT function.
The larger the stiffness, the smaller the penetration.
CONTACT 37
Adams/Solver (FORTRAN) Statements
Caution:
An artificially low value of stiffness or penalty will not generate the necessary
contact forces. You may see a loss of energy when none is expected.
If you find that your model response changes as the number of output steps is
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.
Examples
The example below demonstrates contact between two generic three-dimensional geometries.
star_geneva.xmt_txt is a geometry file that was generated by Parasolid. Adams/View or any CAD
package using Parasolid as its geometry package can generate this file. It contains two geometries,
SOLID4 and SOLID3. Contact is to be defined between these two geometries.
The .adm file portion for this example is as follows:
MARKER/30027, PART = 1005
GRAPHICS/11,
, EXTERNAL,
, FILE = star_geneva.xmt_txt,
, ELEMENT = SOLID4,
, RM = 30027
!
38 Adams/Solver
Below is an example of lists of geometry. Geometries 11 and 12 must belong to one part. Geometries 13,
14, and 15 must all be on one part. Geometries 12, 13, and 15 are flipped.
CONTACT/1,
, IGEOM = 11, 12
, JGEOM = 13, 14, 15
, IFLIP_GEOMETRY = 12
, JFLIP_GEOMETRY = 13, 15
, IMPACT,
, STIFFNESS = 1E6,
, DAMPING = 10,
, DMAX = 0.1,
, EXPONENT = 2.2
Below is an example of user-written subroutines in contacts. The normal force subroutine (CNFSUB)
and the friction force subroutine (CFFSUB) are in the same library (cnforc1).
CONTACT/1
, IGEOM = 7
, JGEOM = 6
, NORMAL_ROUTINE = cnforc1::CNFSUB
, FRICTION_ROUTINE = cnforc1::CFFSUB
, NORMAL_FUNC = USER(1.0E+004, 1.0, 1000, 0.1)/
, FRICTION_FUNC = USER(0.37, 0.30, 10.0, 10)
CONTACT 39
Adams/Solver (FORTRAN) Statements
The example below demonstrates how to specify contact between two two-dimensional geometries:
MARKER/30027, PART = 1005
GRAPHICS/11, CURVE, RM = 30027, CID = 147
!
MARKER/30028, PART = 1004
GRAPHICS/12, CIRCLE, CM = 30028, RADIUS = 1.36
A POISSON-type contact with Augmented Lagrangian iterations, and no energy dissipation would be
defined as:
CONTACT/1,
, IGEOM=11,
, JGEOM=12,
, POISSON,
, PENALTY = 1E5,
, RESTITUTION_COEFFICIENT = 1.0,
, AUGMENTED_LAGRANGIAN_FORMULATION
40 Adams/Solver
CURVE
The CURVE statement defines a three-dimensional parametric curve that you can reference using PTCV,
CVCV, GRAPHICS statements, and function expressions.
Format
Arguments
CLOSED
CURVE_POINTS
FUNCTION=USER
(r1[,...,r30])/
MATRIX=id
CURVE 41
Adams/Solver (FORTRAN) Statements
MAXPAR=r
Specifies the maximum value of the curve parameter for a userwritten curve. Adams/Solver (FORTRAN) uses this value when
drawing a curve graphic. The maximum parameter value is always
1.0 for curves you define using CURVE_POINTS.
Default: 1.0
MINPAR=r
Specifies the minimum value of the curve parameter for a userwritten curve. Adams/Solver (FORTRAN) uses this value when
drawing a curve graphic. The minimum parameter value is always 1.0 for curves you define using CURVE_POINTS.
Default: -1.0
OPEN
Specifies that the curve does not meet at the ends. Adams/Solver
(FORTRAN) does not allow a PTCV or CVCV contact point to move
beyond the end of the curve.
ORDER
ROUTINE=libname::subname
Extended Definition
The x, y, and z coordinates of a point on a parametric curve are functions of an independent parameter,
u. As u varies from its minimum to maximum value, the functions x(u), y(u), and z(u) sweep out points
on the curve. A simple example of a parametric curve is a helix defined by the following equations and
illustrated in the figure below:
x = cos(u)
y = sin(u)
z = u
42 Adams/Solver
CURVE 43
Adams/Solver (FORTRAN) Statements
Adams/Solver (FORTRAN) computes the control points internally from the curve points.
To use a different type of curve, or to model an analytically-defined curve such as a helix, you can write
a CURSUB user-written subroutine. When providing a CURSUB, you can also specify MINPAR and
MAXPAR to define the limits of the curve. These default to -1 and +1, respectively.
A curve is OPEN or CLOSED. A CLOSED curve meets at the ends, connecting the curve at minimum
and maximum parameter values. Adams/Solver (FORTRAN) automatically moves a PTCV or CVCV
contact point across the closure of a CLOSED curve, if needed. For instance, you can model a cam profile
as a CLOSED curve, and Adams/Solver (FORTRAN) allows the follower to move across the closure as
the cam rotates.
Caution:
Examples
CURVE/5, OPEN, CURVE_POINTS, MATRIX=2
This statement creates an open curve using the curve point coordinates in MATRIX/2. Adams/Solver
(FORTRAN) computes a B-spline curve to fit the points.
CURVE/7, CLOSED, CURVE_POINTS, MATRIX=1, ORDER=2
This statement creates a closed curve of order 2 (polyline) using the curve point coordinates in
MATRIX/1. Adams/Solver (FORTRAN) computes a B-spline curve to fit the points.
Applications
The PTCV, CVCV, and GRAPHICS statements reference the CURVE statement:
44 Adams/Solver
In each case, you must specify a reference marker that identifies the part to which the curve attaches and
the coordinate system to which Adams/Solver (FORTRAN) applies the curve coordinates. You can also
reference a curve in a function expression, much like the cubic or Akima splines (see the CURVE
function).
See other Reference data available.
COUPLER 45
Adams/Solver (FORTRAN) Statements
COUPLER
A COUPLER statement relates the translational and/or the rotational motion of two or three joints.
Format
Arguments
FUNCTION=USER(r1[,...,r30])
Specifies up to thirty user-defined constants passed to the externallydefined 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]
ROUTINE=lib1::cou1,
lib2::cou2, lib3::cou3
46 Adams/Solver
SCALES=[r1,]r2[,r3]
T T T
TYPE =
R R R
COUPLER 47
Adams/Solver (FORTRAN) Statements
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:
displacement of the I marker origin with respect to the J marker origin along the J
marker z-axis. Positive translations are along the positive z-axis of J, and negative
translations are along its negative z-axis.
To measure rotational motion, Adams/Solver (FORTRAN) finds the displacement
of the x-axis of the I marker with respect to the x-axis of the J marker about the
common z-axis of the I and the J markers. To determine the positive sense of
rotation, apply the right-hand rule to the z-axis.
The COUPLER can relate any combination of translational and rotational motions.
models only the reaction forces that are along or about the degrees of freedom that
are being coupled.
You can model a pair of mating spur gears as a COUPLER between two
REVOLUTE joints. If (I1, J1) are the I and J markers of the first joint and (I2, J2)
are the I and J markers of the second joint, the COUPLER constraint is:
AZ(I1,J1) * scale_1 + AZ(I2,J2) * scale_2 = 0
where scale_1 and scale_2 are the radii of the two gears.
The reaction forces generated by the COUPLER are the torques at the two joints
required to maintain the constraint shown above. The reaction on the first joint is
the torque about the z-axis of marker J1. The reaction on the second joint is the
torque about the z-axis of marker J2. You can compute the tooth force from these
torques, but Adams/Solver (FORTRAN) does not explicitly solve for them.
You can also model a rack and pinion gear as a COUPLER relating the rotation in
a REVOLUTE joint, with the translation in a TRANSLATIONAL joint. If (I1, J1)
are the I and J markers of the REVOLUTE joint and (I2, J2) are the I and J markers
of the TRANSLATIONAL joint, the COUPLER constraint is:
AZ(I1,J1) * scale_1 + DZ(I2,J2,J2) * scale_2 = 0
where scale_1 is the pinion radius, and scale_2=1.
The COUPLER reaction on the REVOLUTE joint is a torque about the z-axis of
Marker J1, and the reaction on the TRANSLATIONAL joint is a force along the zaxis of Marker J2.
48 Adams/Solver
Caution:
assumes radians rather than degrees. Use a D after the value to indicate that the
units are degrees.
When measuring translational motions in couplers, Adams/Solver (FORTRAN)
(FORTRAN) requires you to input one or more entries for the TYPE argument,
depending on the order of the cylindrical joint(s) in the JOINTS argument list.
Adams/Solver (FORTRAN) must have a type entry for every cylindrical joint and
a place holder entry for every joint entered before a cylindrical joint on the
JOINTS argument.
Examples
COUPLER/01, JOINTS=4,6, TYPE=T:R, SCALES=90D, -1
This COUPLER statement relates the translational motion at Joint 4 to the rotational motion at Joint 6.
Joint 4 is either a translational or cylindrical joint, and Joint 6 is either a revolute or cylindrical joint. The
SCALES argument indicates the relationship:
(90D)q1 - q2 = 0
or
(90D)q1 = q2.
In other words, when q1 is a positive translation of one system unit, q2 is a positive rotation of 90 degrees.
Internal to Adams/Solver (FORTRAN), all values entered in degrees are converted to radians for
calculation purposes. The figure below shows a coupler.
Coupler
CVCV 49
Adams/Solver (FORTRAN) Statements
CVCV
The CVCV statement defines a curve-to-curve constraint that restricts a planar curve on one part that is
to be in contact with, and tangent to, a planar curve on a second part. The curves must lie in the same
plane, but the parts to which they are attached may undergo three-dimensional motion.
Format
Arguments
ICURVE=id Specifies the identifier of a CURVE statement from which Adams/Solver constructs the
first curve. The IRM marker specifies the coordinate system in which the x, y, z
coordinates of ICURVE are specified. The curve is attached rigidly to the part containing
the IRM marker. The z component of the curve must be zero. As a result, the curve lies
in the x-y plane of the IRM marker.
IDISP=x,y,z Specifies the initial point of contact on the first curve. Adams/Solver (FORTRAN) uses
a point on the curve nearest to that specified if the point specified is not exactly on the
curve. By default, the contact point is specified in the IRM marker coordinate system.
You may supply the IICM argument and enter IDISP in IICM marker coordinates if
another coordinate system is more convenient.
Adams/Solver (FORTRAN) assembles the system with the contact at the specified point
on the curve if you supply IDISP. Adams/Solver (FORTRAN) assumes the initial contact
is at the point on the first curve closest to the second curve at the input configuration if
you do not supply IDISP. In this case, Adams/Solver (FORTRAN) may adjust that
contact point to maintain other part or constraint initial conditions.
50 Adams/Solver
IFLOAT=id
IICM=id
Specifies the identifier of a fixed marker defining the coordinate system in which the
values for IDISP are defined. The IICM marker must be on the same part as the IRM
marker.
Default: IRM marker
IRM=id
Specifies the identifier of a fixed marker on the part containing ICURVE. The IRM
marker identifies not only the part that the ICURVE is attached to, but also identifies the
coordinate system in which the coordinates of ICURVE are specified. Adams/Solver
(FORTRAN) constructs the ICURVE in the x-y plane of the IRM marker coordinate
system. The IFLOAT and IRM markers must lie on the same part.
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 (FORTRAN) gives the contact point the specified initial speed along the
first curve if you supply IVEL. Adams/Solver (FORTRAN) assumes the initial velocity
is zero if you do not supply IVEL, but may adjust the velocity to maintain other part or
constraint initial conditions.
Default: 0
JCURVE=id Specifies the identifier of a CURVE statement from which Adams/Solver (FORTRAN)
constructs the second curve. The JRM marker specifies the coordinate system in which
the x, y, z coordinates of JCURVE are specified. The curve is attached rigidly to the part
containing the JRM marker. The z component of the CURVE must be zero. As a result,
the curve lies in the x-y plane of the JRM marker.
CVCV 51
Adams/Solver (FORTRAN) Statements
JDISP=x,y,z Specifies the initial point of contact on the second curve. Adams/Solver (FORTRAN)
uses a point on the curve nearest to that specified if the point specified is not exactly on
the curve. By default, the contact point is specified in the JRM marker coordinate system.
You may supply the JICM argument and enter JDISP in JICM marker coordinates if
another coordinate system is more convenient.
Adams/Solver (FORTRAN) assembles the system with the contact at the specified point
on the curve if you supply JDISP. Adams/Solver (FORTRAN) assumes the initial contact
is at a point on the second curve closest to ICURVE in the input configuration if you do
not supply JDISP. In this case, Adams/Solver (FORTRAN) may adjust that contact point
to maintain other part or constraint initial conditions.
Default: Closest point to ICURVE in the input configuration
JFLOAT=id
JICM=id
Specifies the identifier of a fixed marker defining the coordinate system in which the
values for JDISP are defined. The JICM marker must be on the same part as the JRM
marker.
Default: JRM marker
JRM=id
Specifies the identifier of a fixed marker on the part containing JCURVE. The JRM
marker identifies not only the part the JCURVE is attached to, but also the coordinate
system in which the coordinates of JCURVE are specified. Adams/Solver (FORTRAN)
constructs JCURVE in the x-y plane of the JRM marker coordinate system. The JFLOAT
and JRM markers must lie on the same part.
JVEL=r
Specifies the magnitude of the initial velocity of the contact point relative to the part
containing JCURVE. This is the speed at which the contact point is initially moving
tangent to the curve. JVEL is negative if the contact point is moving towards the start of
the curve, positive if the contact point is moving toward the end of the curve, and zero if
the contact point is stationary on the curve.
Adams/Solver (FORTRAN) gives the contact point the specified initial speed along the
second curve if you supply JVEL. Adams/Solver (FORTRAN) assumes the initial
velocity is zero if you do not supply JVEL, but may adjust that velocity to maintain other
part or constraint initial conditions.
Default: 0
52 Adams/Solver
Extended Definition
The CVCV statement defines a curve-to-curve constraint that restricts a planar curve on one part to be in
contact with, and tangent to, a planar curve on a second part. The curves must lie in parallel planes.
Adams/Solver (FORTRAN) constructs the first curve from the ICURVE curve and IRM marker, and the
second curve from the JCURVE curve and JRM marker. In both cases, the CURVE statement (ICURVE
or JCURVE) defines x and y coordinates along the curve as a function of an independent parameter (u).
The z coordinates of the curves must be zero. The reference marker (IRM or JRM) defines the part on
which the constraining curve is attached and the coordinate system in which Adams/Solver (FORTRAN)
applies the coordinates from the CURVE statement.
Both ICURVE and JCURVE may be open or closed curves, defined analytically or as a set of discrete
data points. Figure 1 below shows a curve-to-curve constraint.
A CVCV statement removes two degrees-of-freedom from the system. Adams/Solver restricts the
motion of the parts such that the curves are always in contact and the curves are tangent at the contact
point. The first curve may slide or roll on the second, but may not move perpendicular to the curve
tangents at the contact.
Figure 1
Tip:
Curve-To-Curve Constraint
More than one CVCV statement can reference the same CURVE statement. You can enter
one CURVE statement if the mechanism contains several similar contacts and use it with
several CVCV constraints, each with a different IRM and JRM marker.
CVCV 53
Adams/Solver (FORTRAN) Statements
Caution:
Adams/Solver (FORTRAN) requires that the curves lie in the same plane,
however, this is not enforced by the CVCV statement. The CVCV statement
simply enforces that the two curves remain in contact. You must build the model
so that the curves are held in the same plane.
IVEL and JVEL are specified relative to the body coordinate system (BCS) of the
part containing the IRM or JRM marker, respectively. In other words, IVEL is the
speed of the contact point relative to the part containing the first curve. This means
if the contact point is not moving relative to part, but the first curve is moving
relative to the ground, then IVEL is still nonzero.
Adams/Solver (FORTRAN) applies a force to prevent the contact point from
moving of the end of an open curve. For this reason, you may want to specify an
open curve that extends beyond the range of actual curve travel on both ends of the
curve.
The initial conditions arguments, IDISP, JDISP, IVEL, and JVEL, impose
constraints that are active only during an initial conditions analysis. Adams/Solver
(FORTRAN) does not impose these initial conditions during subsequent analyses.
For a kinematic analysis, the initial conditions are redundant. Do not use the
IDISP, JDISP, IVEL, or JVEL arguments on the CVCV statements for systems
with zero degrees of freedom. Adams/Solver (FORTRAN) requires that there be a
unique contact point in the vicinity of the IFLOAT and JFLOAT markers during
simulation. If there is more than one contact point, Adams/Solver may be unable to
find the correct contact point or may even jump from one contact point to the next.
One way to ensure that contact points are unique is to specify curve shapes that are
convex. Figure 2 below depicts two curves, the first is convex and the second
nonconvex. Note that for a convex curve, any line segment connecting two
arbitrary points on the curve lies in the domain of the curve (that is, it does not
intersect the curve). The same is not true for the nonconvex curve.
It is easy to accidently over-constrain a system using the CVCV constraint. For
54 Adams/Solver
Figure 2
Examples
CVCV/20, IFLOAT=402, ICURVE=11, IRM=401, JFLOAT=502,
, JCURVE=12, JRM=501
This statement creates a curve-curve constraint between a curve on the part containing Markers 401 and
402 and a curve on the part containing Markers 501 and 502. CURVE/11 defines the first curve in the
coordinate system of Marker 401. CURVE/12 defines the second curve in the coordinate system of
Marker 501.
Applications
The CVCV statement models one curve rolling or slipping along another, such as in a cam-follower
mechanism. Figure 3 illustrates a cam follower.
Adams/Solver (FORTRAN) automatically moves the contact across the closure as needed when a closed
curve is specified in the CURVE statement. This means that the cam may rotate as many times as needed
during the simulation.
A point-to-curve constraint, PTCV statement, can be used if the follower is small and sharp enough to be
considered a point.
The curves always maintain contact, even when the dynamics of the system would actually lift one curve
off the other, because CVCV is a geometric spatial constraint. You can examine the constraint forces to
determine if lift-off should have occurred. If an accurate simulation of intermittent contact is required,
you should model the contact forces directly using a VFORCE.
The CVCV statement models only one contact. Therefore, if the curves have contact at more than one
point you must enter a CVCV statement for each contact, each with a displacement initial condition
(IDISP and JDISP) near the appropriate point.
CVCV 55
Adams/Solver (FORTRAN) Statements
Figure 3
Cam-Follower Mechanism
56 Adams/Solver
DEBUG
The DEBUG statement outputs data that helps you debug a simulation.
Format
Arguments
DOF
Prints a degree-of-freedom table in the tabular output file. This table tells whether or not each of the
six components of motion (that is, translation along the x-axis, y-axis, and z-axis and rotation about
the x-axis, y-axis, and z-axis) is constrained for each part center of mass relative to the origin of the
ground coordinate system (GCS). These are the degrees of freedom as input.
Default: Off
DUMP
Writes the internal representation of a dataset in the Tabular Output file after Adams/Solver
(FORTRAN) reads and checks the input. This facility essentially maps the equations and variables in
the system and provides their numeric codes.
Default: Off
DEBUG 57
Adams/Solver (FORTRAN) Statements
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 (FORTRAN)
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
Adams/Solver (FORTRAN) 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 (FORTRAN) prints out the cumulative number of iterations and
a table of information about the iterations. The cumulative number of iterations is a running count of
the iterations needed to solve the equations of motion and can be used as a measure of how many
computations Adams/Solver (FORTRAN) is performing. The table contains information about the
largest equation imbalance (error) and maximum variable change for each iteration. For each iteration,
Adams/Solver (FORTRAN) prints out seven or eight pieces of the following information:
The iteration number. This is one at the beginning of each step and increments by one until
value close to zero. This number is an indicator of how far Adams/Solver (FORTRAN) is
from a solution. This number should decrease after every iteration.
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
(FORTRAN) 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 (FORTRAN) has updated the Jacobian, YES appears under the new Jacobian
header.
Default: Off
JMDUMP
58 Adams/Solver
REQDUMP Dumps the REQUEST and MREQUEST statement output at each iteration.
Default: Off
RHSDUMP Dumps the YY array (state vector), RHS array (error terms), and DELTA array (increment to state
vector) at each iteration.
Default: Off
VERBOSE
Outputs to the screen such additional information as the name of the subroutine from which
Adams/Solver (FORTRAN) sends each diagnostic, explanations, and possible remedies (when
available). When you do not include the VERBOSE argument, Adams/Solver (FORTRAN) outputs
only the basic error messages to the screen. In either case, Adams/Solver (FORTRAN) outputs the
information to the Message file.
Default: Off
Caution:
Extended Definition
The DEBUG command section contains additional descriptions on the information returned by
DEBUG/EPRINT command.
Examples
DEBUG/EPRINT
This DEBUG statement generates the information in Figure 4 that appears in the message file.
In this example, Adams/Solver (FORTRAN) is printing the information for the third step of a dynamic
analysis. For this step, Adams/Solver (FORTRAN) uses a second-order polynomial to guess the solution.
Using a time step of 7.25694E-04, the integration step goes from 6.458333333E-04 to 1.371527778E-03.
After the first iteration, the z velocity equation of PART/245330 has the largest error: its absolute value
is 2E+00. The z coordinate of PART/245330 changes the most during the first iteration. The absolute
value of the change is 8.E-04. Adams/Solver (FORTRAN) updates the Jacobian before the first iteration,
but not before the second or third.
DEBUG 59
Adams/Solver (FORTRAN) Statements
Figure 4
60 Adams/Solver
DIFF
The DIFF statement creates a user-defined state variable and defines a first-order differential equation
that describes it.
Format
Arguments
DIFF 61
Adams/Solver (FORTRAN) Statements
IMPLICIT
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
quasi-static analysis.
Extended Definition
The DIFF statement creates a user-defined state variable and defines a first-order differential equation
that describes it. The equation may be dependent on any Adams/Solver (FORTRAN) state variable
available in a function expression except PTCV and CVCV forces. You can create systems of differential
equations by using more than one DIFF statement or LSE and GSE statements.
Both function expressions and user-written subroutines can access the DIFF state variable and its
derivative. Function expressions access the value by using the function DIF(id1) and the derivative by
using DIF1(id1) (see DIF and DIF1 functions). In each case, i1 specifies the identifier of the DIFF
statement that defines the variable. User-written subroutines access the value and derivative by calling
the subroutine SYSFNC (see the SYSFNC subroutine).
The function can be defined by a function expression, or by providing a user-written subroutine. Because
the Solver typically handles a function expression more efficiently than a user-written subroutine, it is
recommended that you use a function expression whenever possible.
The DIFF may be defined in either explicit or implicit form. The following equation defines the explicit
form of a differential equation:
y = f (y, u, t)
where y is the time derivative of the user-defined state variable, y is the user-defined state variable itself,
and u is a vector of Adams/Solver-defined state variables.
You need to use the implicit form if the first derivative of the state variable cannot be isolated. The
following equation defines the implicit form of a differential equation:
0 = F( y,
y , u, t)
62 Adams/Solver
Caution:
Although you can currently use a DIFF statement to define an implicit, algebraic
y as shown
y + 2y - 4 - sin (t) = 0
Applications
The DIFF statement defines a first order, linear or nonlinear, explicit or implicit, ordinary differential
equation for Adams/Solver (FORTRAN) to integrate along with the dynamic simulation of a multibody
DIFF 63
Adams/Solver (FORTRAN) Statements
system. The equation may be independent of the rest of the problem or it may depend upon any variable
in the state vector. The solution to the differential equation can be used in the function expressions which
define a number of other elements in Adams/Solver (FORTRAN) such as the SFORCE statement. Thus,
you can use Adams/Solver (FORTRAN) to solve an independent initial value problem, or the differential
equations defined by DIFF statements may be fully coupled with the system of equations that governs
the dynamics of the problem.
DIFF statements are best for creating single equations or small sets of equations. Although you may
create sets of DIFF statements to represent higher order equations or large systems of equations, other
Adams/Solver (FORTRAN) elements such as TFSISO, LSE, or GSE may be more convenient in these
cases.
See other Generic systems modeling available.
64 Adams/Solver
END
An END delimiter indicates the end of a dataset. Although the file may contain additional data,
Adams/Solver (FORTRAN) does not read any statements or comments that follow the END statement.
Format
END
See other Dataset delimiter available.
EQUILIBRIUM 65
Adams/Solver (FORTRAN) Statements
EQUILIBRIUM
The EQUILIBRIUM statement specifies error tolerances and other parameters for static equilibrium and
quasi-static equilibrium analyses.
Format
Arguments
66 Adams/Solver
DYNAMIC
ERROR=r
GLOBAL_DAMPING=r
IMBALANCE=r
KINETIC_ENERGY_ERRO
R=r
MAXIT=i
EQUILIBRIUM 67
Adams/Solver (FORTRAN) Statements
PATTERN=c1[:...:c10]
SETTLING_TIME=r
STABILITY=r
STATIC
TLIMIT=r
68 Adams/Solver
Extended Definition
The EQUILIBRIUM statement specifies the use of static or dynamic analyses to find static and quasistatic equilibria. The statement also specifies error tolerances and other parameters for static and quasistatic equilibrium analyses, and dynamic analyses that are used to find static equilibria. You use this
statement when you want to change one or more of the tolerances or other parameters from the default
values.
Use the SIMULATE command to request one of the following:
Single static equilibrium analysis.
Dynamic analysis for finding static equilibrium.
Series of static equilibrium analyses over time, for example, a quasi-static equilibrium analysis.
A static or quasi-static equilibrium analysis is appropriate only when the system has one or more degrees
of freedom (degrees of freedom after Adams/Solver (FORTRAN) has removed any redundant
constraints). Static and quasi-static equilibrium analyses solve for displacement and static forces, but not
for velocity, acceleration, or inertia forces which are all assumed to be zero. To perform a static
equilibrium analysis, Adams/Solver (FORTRAN) finds the configuration and static forces for which all
the static forces in the system balance after being evaluated at the current simulation time. This process
requires the solution of a set of nonlinear algebraic equations. Adams/Solver (FORTRAN) uses the
modified Newton-Raphson iteration to solve these equations.
When you specify the DYNAMIC argument for an EQUILIBRIUM statement or command, and you
issue a SIMULATE/STATIC command, Adams/Solver (FORTRAN) performs a dynamic analysis that is
similar to one it would perform if you issued the SIMULATE/DYNAMIC command, except for the
following:
The function-expression variable, TIME, whether accessed using function expressions or the
TIME variable passed to most user subroutines, is set to the starting time for the duration of the
analysis. This setting has the effect of freezing all time-dependent excitations.
Body forces are applied to all rigid bodies (damping forces) that oppose motion relative to
ground. The magnitude of the forces depends on the velocity of the rigid bodies relative to
ground and on the GLOBAL_DAMPING argument used with the EQUILIBRIUM statement or
command.
The simulation time is reset to the starting time once the analysis is complete.
The analysis terminates when one of the following occurs:
A norm of the system acceleration falls below ACCELERATION_ERROR and the system
Because a dynamic analysis occurs here, the INTEGRATOR statement/command specifies the error
tolerances and other parameters normally associated with dynamic analyses.
If neither an EQUILIBRIUM command nor an EQUILIBRIUM statement is issued in an Adams/Solver
session, to set the default values for ALIMIT, ERROR, IMBALANCE, MAXIT, PATTERN,
EQUILIBRIUM 69
Adams/Solver (FORTRAN) Statements
STABILITY, and TLIMIT,the Adams/Solver (FORTRAN) uses their default values when performing a
static equilibrium or quasi-static equilibrium analysis.
Note:
Tip:
If the dynamic analysis will be followed by a static analysis, the goal of the dynamic
analysis is not to find equilibrium, but to allow the system to settle enough to permit the
subsequent analysis to be successful.
Using the PATTERN argument to request less frequent evaluations of the Jacobian
matrix may decrease the computation time. However, infrequent evaluations could
also be more expensive since the modified Newton-Raphson algorithm might
require more iterations due to the slower convergence rates.
Use the ALIMIT and TLIMIT arguments to limit incrementing displacement
70 Adams/Solver
Caution:
the system is neutrally stable, STABILITY must be greater than zero in order for
Adams/Solver (FORTRAN) to compute static equilibrium.
Static equilibrium, or quasi-static equilibrium analyses often have multiple
static equilibrium (flexible bodies and point masses are ignored both when
applying global damping forces and when calculating system acceleration and
kinetic energy). It is possible to use the EQUILIBIUM/DYNAMIC option with
flexible bodies and/or point masses in the model. The results may or may not be
useful.
Examples
EQUILIBRIUM/ STABILITY=0.01, TLIMIT=10
, IMBALANCE=1.0E-05
This EQUILIBRIUM statement instructs Adams/Solver (FORTRAN) to use these values instead of the
defaults when performing a static or quasi-static equilibrium analysis. It adds 0.01 times the sum of the
mass and damping matrices to the stiffness matrix during an equilibrium iteration. It limits the translation
in any one iteration to 10 length units. The force imbalance in the system must be less than 1.0E-05 force
units for Adams/Solver (FORTRAN) to consider the system to be in equilibrium.
EQUILIBRIUM/ DYNAMIC, SETTLING_TIME = 0.5, LIST
FEMDATA 71
Adams/Solver (FORTRAN) Statements
FEMDATA
The FEMDATA statement produces data files of component loads, deformations, stresses, or strains for
input to subsequent finite element or fatigue life analysis. 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
72 Adams/Solver
Arguments
CRITERION = c
DATUM = node_id
END = t2
Specifies the time, t2, at which to end the output of the data or the search of
a peak load.
Default: Output or search to the end of the simulation.
Range: t2 > t1
HOTSPOTS = n
Specifies the number of hot spots to locate on the flexible body and output.
A search for the top n nodes that recorded the highest stress or strain during
the simulation will ensue. With the START, END or SKIP arguments,
FEMDATA only checks the time steps within those specifications for hot
spots. A text file containing a table of hot-spot data (node ID, maximum
value, time of maximum value, and location) will be output. The complete
time history of nodal stress or strain will be output as well for each hot spot,
if the STRAIN or STRESS option is specified in the OUTPUT statement.
FLEX_BODY = id
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
NODAL_DEFORMATI
ON
FEMDATA 73
Adams/Solver (FORTRAN) Statements
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
SKIP = n
Specifies the number of output steps to skip when outputting the data.
Default: n=0 (every step is output).
74 Adams/Solver
START = t1
STRAIN
Outputs strain information if strain modes are available in the modal neutral
file (MNF) of the specified flexible body. FEMDATA outputs all six
components of strain (normal-X, normal-Y, normal-Z, shear-XY, shear-YZ,
shear-ZX). It outputs strains in the basic FEA coordinate system of the
flexible body, unless the RM=id option is specified.
STRESS
Outputs stress information if modal stresses are available in the MNF of the
flexible body. FEMDATA outputs all six components of stress (normal-X,
normal-Y, normal-Z, shear-XY, shear-YZ, shear-ZX). It outputs stresses
output in the simulation set of units in the basic FEA coordinate system of
the flexible body, unless the RM=id option is specified.
Extended Definition
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
FEMDATA 75
Adams/Solver (FORTRAN) Statements
Type of data:
Format:*
File name:
<run_name>_<body_name>
<run_name>_<body_name>
<run_name>_<body_name>
.ndf
.spc
.inp
Strain
<run_name>_<node_id>e_<channel_id>
<run_name>_<body_name>
.dac
.nsf
<run_name>_body_name>_hots
.tab
<run_name>_<node_id>se_<channel_id>
<run_name>_<body_name>
.dac
.nsf
<run_name>_<body_name>_hote
.tab
DAC
Generic
Hotspots
Stress
DAC
Generic
Hotspots
Extension:
An older version of the FEMDATA statement where one or more RM markers are specified with no data
type is still being supported. The format of this version of FEMDATA is:
FEMDATA/id, RM=id1[,...,id100]
In this case, a text file with extension .fem is generated. This file contains generic load specifications for
the parent body of each RM marker specified.
Format of .fem File
The .fem file contains information sufficient to define all forces (inertial and applied) acting on one or
more parts. The data in this file is intended to be converted to boundary conditions input to a finite
element program. This file is composed of the following lines:
Line1: <Header>
Line 2: <Title>
Lines repeated for every part:
Lines repeated for every output step:
<Record 1> (RM Displacement)
<Record 2> (CM Displacement)
<Record 3> (CM Velocity)
<Record 4> (CM Acceleration)
<Record 5> (Force Displacement)
<Record 6> (Force Values)
<Header> Definition
Output: File Version #, Date&Time, User ID, Job ID, Program ID
Format: 1X, A4, 4X, A18, 6X, 2I10, 2X, A2
<Title> Definition
Output: Title of ADAMS run
Format: A80
<Record 1> Definition - RM Location
Output: Part ID, Time, 1, X, Y, Z, <Euler Angles (radians)>, RM
ID
Format: I10, 1PE13.5, I2, 6(1PE13.5), I10
76 Adams/Solver
Except for FMAG, GMAG, and TMAG, each PEAK_SLICE load specification (FX, FY, FZ, TX, TY, TZ)
generates two output time steps for each marker force of the component, one for the maximum (peak)
and one for the minimum (valley). For FMAG and TMAG, only one time step is output for each marker
force since these quantities are load magnitudes and generate only positive values. With GMAG, only one
time step is output per body. If:
Fm(t) represents the force acting on the body at Marker m.
r , r , r represents the unit vector of the reference coordinate system of the rigid body (FEA
x y z
coordinate system of the flexible body).
r(t) represents the position of the reference marker (RM) in that coordinate system.
m.
FY = Output loads at time t when
m.
FZ = Output loads at time t when
m.
FMAG = Output loads at time t when
FEMDATA 77
Adams/Solver (FORTRAN) Statements
MAX
Fm ( t ) rx ( t ) , Fm ( t ) ry ( t ) , Fm ( t ) rz ( t )
m
Note:
Similar expressions exist for TX, TY, TZ, and TMAG. The PEAK_SLICE argument is
not available when you specify a time history OUTPUT load format (DAC or RPC).
Modal Superposition
Nodal displacements, strains, and stresses are computed using the principal of modal superposition:
Here i are the respective mode shapes from FEA and {q(t)}are the modal displacements of the flexible
body that Adams/Solver computes.
Coordinate Reference Transformation of Stress or Strain
Because stress and strain are second-order tensors, the following equation is used to transform these
quantities to a reference coordinate system:
[ S ]' = [ A g ] [ S ] [ A g ] T
Where
[ A g ] is the skew-rotation matrix from the flexible bodys LPRF (FE origin) to the markers
S xx S xy S xz
[ S ] = S yx S yy S yz
where
S ij = S ji
S zx S zy S zz
Definition of Hot Spots
The figure below illustrates how the radius argument can affect the definition of a hot spot region. In this
figure, the top 7 hottest nodes (those with the largest stress) are listed. If the number 5 and no radius is
specified on HOTSPOTS, then only nodes 4, 5, 3, 6, and 2 would be output. If a radius of 0.5 mm is
specified, then only node 4 would be listed from this region and the other 4 hot spots would come from
nodes with the highest stress from other regions.
78 Adams/Solver
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.
FEMDATA 79
Adams/Solver (FORTRAN) Statements
Caution:
Note that all FEMDATA are output in the Adams modeling units. This causes a problem
when the Adams units are inconsistent with those used in the finite element model, and the
data that is output will be included in a subsequent finite element analysis.
For example, when outputting FEMDATA of type LOADS to ANSYS or MSC.Nastran for
inclusion in the FE analysis, the Adams and FE modeling units must be consistent. This is
also true when outputting FEMDATA of type NODAL_DEFORMATION when the
OUTPUT format is ANSYS or MSC.Nastran and the data will be used as input to the FE
analysis.
In the case of outputting FEMDATA of type MODAL_DEFORMATION, the only concern
for units is when MSC.Nastran (or PUNCH) has been specified as the OUTPUT format.
This is because rigid body motion is included in the output file along with the modal
coordinates. By definition, modal coordinates are unitless, so the modal stresses (or strains)
will be recovered correctly in MSC.Nastran irregardless of unit settings. However, in order
for the overall displacement of the component to be correctly recovered, the unit of length
must be consistent between models.
Examples
FEMDATA/100, STRESS, FLEX_BODY=101
, HOTSPOTS = 7, CRITERION = MAX_PRIN
, RADIUS = 0.5, FILE = hotspots_101
OUTPUT/STRESS = DAC
These statements create a text file, named hotspots_101.tab containing hot spot information for flexible
body 101. Seven hot spots with a radius of 0.5 based on maximum principal stress are requested. Also, a
time history of the stress for each node found to be a hot spot is output in DAC format. The names of the
DAC files are given the prefix hotspots_101 as specified in the FILE argument.
FEMDATA/1, LOADS, RM=201
, PEAK_SLICE = GMAG
, FILE = peak201.nas
OUTPUT/LOADS = NASTRAN
These statements create a NASTRAN input file containing loads of the parent part of marker 201 in that
markers coordinate reference system. They output the loads for only one time step when the magnitude
of the global sum of all marker forces on the part is greatest in the simulation.
FEMDATA/2, LOADS, FLEX_BODY=101
, PEAK_SLICE = FX:FY:FZ:FMAG
OUTPUT/LOADS = ANSYS
These statements create an ANSYS input file with .dat default extension containing loads acting on
flexible body 101 in the FEA coordinate system. If the flexible body has, say 4 attachments, you should
expect (3*2 + 1)*4 load cases (loads from 28 time steps) to be output, because FX, FY and FZ output
loads for 2 time steps per attachment, and FMAG will output 1 per attachment.
80 Adams/Solver
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 FEFatigue or MSC.Fatigue to perform a fatigue analysis based on linear superposition theory.
See other Output available.
FIELD 81
Adams/Solver (FORTRAN) Statements
FIELD
The FIELD statement applies a translational and rotational action-reaction force between two markers.
Format
82 Adams/Solver
Arguments
CMATRIX=r1,...,r36
r 1 r 7 r 13 r 19 r 25 r 31
r 2 r 8 r 14 r 20 r 26 r 32
r 3 r 9 r 15 r 21 r 27 r 33
r 4 r 10 r 16 r 22 r 28 r 34
r 5 r 11 r 17 r 23 r 29 r 35
r 6 r 12 r 18 r 24 r 30 r 36
Enter the elements by columns from top to bottom, then from left to right.
CMATRIX defaults to a matrix with thirty-six zero entries if you do not
use either CMATRIX or both CRATIO and KMATRIX. The units for the
translational and rotational components of CMATRIX should be forcetime per unit displacement and torque-time per radian, respectively.
CRATIO = r
FORCE=r1,...r6
FIELD 83
Adams/Solver (FORTRAN) Statements
Specifies the identifiers of two markers between which the force and
torque is to exert.
KMATRIX=r1,...,r36
r 1 r 7 r 13 r 19 r 25 r 31
r 2 r 8 r 14 r 20 r 26 r 32
r 3 r 9 r 15 r 21 r 27 r 33
r 4 r 10 r 16 r 22 r 28 r 34
r 5 r 11 r 17 r 23 r 29 r 35
r 6 r 12 r 18 r 24 r 30 r 36
Enter the elements by columns from top to bottom, then from left to right.
KMATRIX defaults to a matrix with thirty-six zero entries. The units for
the translational and rotational components of KMATRIX should be
force per unit displacement and torque per radian, respectively.
Adams/Solver (FORTRAN) cannot calculate the damping coefficients if
you do not use both CRATIO and KMATRIX. In that case, CMATRIX
must be explicitly defined if you want to include damping coefficients in
the calculation of the field forces.
84 Adams/Solver
LENGTH=r1,...,r6
Defines six reference length angles. This is the nominal position of the I
marker with respect to the J marker, resolved in the J marker coordinate
system. The terms r1,...,r6 are the x, y, and z translational components
(specified in linear displacement units) of the displacement between the
I and J markers; and a, b, and c are rotational displacement of the axes of
the I marker with respect to the J marker, resolved in the J marker axes
(specified in radians). If the reference force is zero, LENGTH is the same
as the free length. LENGTH is optional and defaults to a six zero entry.
ROUTINE=libname::sub Specifies an alternative library and name for the user subroutine FIESUB.
name
Learn more about the ROUTINE Argument.
Extended Definition
The FIELD statement applies a translational and rotational action-reaction force between two markers.
To specify a linear field, use the arguments in the FIELD statement to specify constants for the six-bysix stiffness matrix, a six reference lengths, and a six-by-six damping matrix. The stiffness and damping
matrices must be positive semidefinite, but need not be symmetric. To specify a nonlinear field, use the
user-written subroutine FIESUB to define the three force components and three torque components and
use the argument FUNCTION=USER(r1[,...,r30]) to pass constants to FIESUB.
The following constitutive equations define how Adams/Solver (FORTRAN) uses the data for a linear
field to apply a force and a torque to the I marker depending on the displacement and velocity of the I
marker relative to the J marker.
Fx
K 11 K 12 K 13 K 14 K 15 K 16 x x 0
C 11 C 12 C 13 C 14 C 15 C 16 V x
F1
Fy
K 21 K 22 K 23 K 24 K 25 K 26 y y 0
C 21 C 22 C 23 C 24 C 25 C 26 V y
F2
Fz
Tx
K 31 K 32 K 33 K 34 K 35 K 36 z z 0
K 41 K 42 K 43 K 44 K 45 K 46 a a 0
C 31 C 32 C 33 C 34 C 35 C 36 V z
C 41 C 42 C 43 C 44 C 45 C 46 x
F3
T1
Ty
K 51 K 52 K 53 K 54 K 55 K 56 b b 0
C 51 C 52 C 53 C 54 C 55 C 56 y
T2
Tz
K 61 K 62 K 63 K 64 K 65 K 66 c c 0
C 61 C 62 C 63 C 64 C 65 C 66 z
T3
For a nonlinear field, the following constitutive equations are defined in the FIESUB subroutine:
Fx = f1(x,y,z,a,b,c,Vx,Vy,Vz, x , y , z )
Fy = f2(x,y,z,a,b,c,Vx,Vy,Vz, x , y , z )
Fz = f3(x,y,z,a,b,c,Vx,Vy,Vz, x , y , z )
FIELD 85
Adams/Solver (FORTRAN) Statements
Tx = f4(x,y,z,a,b,c,Vx,Vy,Vz, x , y , z )
Ty = f5(x,y,z,a,b,c,Vx,Vy,Vz, x , y , z )
Tz = f6(x,y,z,a,b,c,Vx,Vy,Vz, x , y , z )
Adams/Solver (FORTRAN) applies the defined forces and torques at the I marker. In the linear and
nonlinear equations:
Fx, Fy, and Fz are the three translational force measure numbers.
Tx, Ty, and Tz are the three rotational force measure numbers associated with unit vectors
damping matrix.
F1, F2, F3, T1, T2, and T3 are the translational and the rotational pre-tensions.
All variables and time derivatives are computed in the J marker coordinate system.
Adams/Solver (FORTRAN) applies an equilibrating force and torque at the J marker, as defined by the
following equations.
Fj = -Fi
Tj = - Ti - L x 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 the
displacement vector L.
Tip:
However, when defining massless beams, you may want to use a BEAM
statement. It requires only six input values to compute the thirty-six values for the
Kmatrix (see BEAM).
Finite element analysis programs can give the values for CMATRIX and
KMATRIX.
86 Adams/Solver
Caution:
For the constitutive equations to be accurate, at least two of the rotations (a, b, c)
must be small. That is, two of the three values must remain smaller than 10
degrees. In addition, if a becomes greater than 90 degrees, b becomes erratic. If b
becomes greater than 90 degrees, a becomes erratic. Only c can become greater
than 90 degrees without causing problems. For these reasons, it is best to define
your field such that angles a and b (not a and c and not b and c) remain small.
The three rotational displacements (a, b, and c) that define the field are not Euler
angles. They are the projected angles of the I marker with respect to the J marker.
Adams/Solver (FORTRAN) measures them about the x-, y-, and z-axis of the J
marker.
Adams/Solver (FORTRAN) applies the component translational and rotational
forces for a field to the I marker and imposes reaction forces on the J marker.
The K and C matrices must be positive semidefinite. In other words:
FIELD 87
Adams/Solver (FORTRAN) Statements
In order to model the elastic freedoms at location I shown on the figure, the system stiffness matrix must
first be determined for the retained freedoms. A finite element super element analysis is one method for
determining the matrix. Assume that all other freedoms are either constrained or superfluous for this
analysis. The system stiffness matrix is:
X
0.198E+04
0.126E-01
-0.147E+04
0.126E-01
0.208E+03
-0.933E-02
-0.147E+04
-0.933E-02
0.763E+07
0.198E+04
0.126E-01
-0.147E+04
0.126E-01
0.208E+03
-0.933E-02
x
y
z
-0.147E+04
-0.933E-02
0.763E+07
88 Adams/Solver
The FIELD statement describing these elastic forces applied to Marker 100 due to displacement of
Marker 100 relative to Marker 57 is:
FIELD/1, I=100, J=57, KMATRIX=0.198E+04
, 0, 0.126E-01, 0, -0.147E+04, 0,
, 0, 0, 0, 0, 0, 0,
, 0.126E-01, 0, 0.208E+03, 0, -0.933E-02, 0,
, 0, 0, 0, 0, 0, 0,
,-0.147E+04, 0, -0.933E-02, 0, 0.763E+07, 0,
, 0, 0, 0, 0, 0, 0
, LENGTH=0, 150, 0, 0, 0, 0
These entries must be made column by column. The distance between the I and J markers is zero except
in the y direction (where it is 150).
FLEX_BODY 89
Adams/Solver (FORTRAN) Statements
FLEX_BODY
The FLEX_BODY statement defines a linear elastic body floating in space. The FLEX_BODY is
capable of undergoing large motion, characterized by six non-linear generalized coordinates for a
floating body coordinate system (BCS) relative to GROUND. The small, linear elastic deformations of
the FLEX_BODY relative to this BCS are described by a linear combination of mode shapes. The modal
amplitudes from this linear combination are additional generalized coordinates for the FLEX_BODY.
The body can be connected to the rest of the mechanical system through applied forces and kinematic
constraints.
Format
90 Adams/Solver
Arguments
CRATIO =
user ( r 1 [ , ,r 30 ] )
EXACT=c1:...:c6
FLEX_BODY 91
Adams/Solver (FORTRAN) Statements
INVARIANTS=c1:...:c9
Specifies a true and false pattern indicating which of the nine inertia
invariants Adams/Solver (FORTRAN) should use to model inertia
coupling of the flexible and rigid body motion. The order of the patterns
corresponds to the nine successive inertia invariants. For more details on
the inertia invariants, see the Theory of Flexible Bodies in Adams/Flex.
The following combinations have special significance:
T:T:F:F:T:T:T:T:T - Full inertia coupling of deformation and rigid body
motion.
T:T:F:F:F:T:T:T:F - Ignore second-order deformation corrections to the
inertia tensor, and the first-order corrections to the rotational and flexible
inertia coupling. This is also called partial coupling.
T:T:F:F:F:T:T:F:F - Neglect all deformation corrections to the mass matrix.
*:*:*:*:*:F:*:*:* - Disable all deformations.
The pattern T:T:F:F:F:T:T:T:F is the default, because although it
potentially sacrifices small levels of accuracy compared to the first pattern
of full inertia coupling, it does so with significant computational savings.
If an MNF has six rigidbody modes in it, theoretically, invariants 3 and 4
should be zero even though there may be some non-zero entries in the
MNF file due to numerical errors. This is the reason that they are disabled
by default. The pattern T:T:F:F:F:T:T:F:F should be used with great care,
because it only returns an accurate answer when the flexible component is
quite rigid. The pattern *:*:*:*:*:F:*:*:*, where the * can be either T or F,
offers a way to turn off all flexibility in the structure, usually for debugging
purposes. Note that even with this last pattern, the FLEX_BODY statement
does not function like a PART statement, due to formulation differences.
It is hard to envision circumstances where it is appropriate to disable
invariants 1 (the total mass), 2 (the undeformed CM location), and 7 (the
undeformed inertia tensor). Disabling these normally causes a numerical
singularity.
Default: T:T:F:F:F:T:T:T:F
92 Adams/Solver
MATRICES=id 1,...,idn
FLEX_BODY 93
Adams/Solver (FORTRAN) Statements
MNF_FILE=file_name
Specifies the path to the Modal Neutral File that defines the detailed
properties of the flexible body. Note that this argument is not required by
Adams/Solver (FORTRAN) (see MATRICES argument above), only by
Adams/View.
QG=x,y,z
Defines the Cartesian initial coordinates of the BCS with respect to the
ground coordinate system.
Default: 0.0, 0.0, 0.0
Range: Real values
REULER=a,b,c
VM=id
VMODE-a1,a2,...,an
Specifies the initial values of the time rate of change of the modal
generalized coordinates.
Default: 0
Range: Real Values
VX=x,VY=y,VZ=z
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. Furthermore, the origin of the
WM marker lies on the axis of rotation. This is most useful for rotating
systems.
WX=a,WY=b,WZ=c
94 Adams/Solver
Tip:
All of the locations corresponding to a constraint attachment should have the finite
element nodes associated with them. The nodal identifiers for these points are
listed in the NODE argument. This allows for accessing the nodal information in
the .adm file.
The Modal Body Preprocessor provides the input matrices in the Adams/Solver
matrix format. See the online help for Adams/Flex.
When the nodal list is empty, the modal body cannot be attached to any other
stationary axis, significant solver performance can be realized by aligning the zaxis of the body coordinate system (BCS) with the spin axis. Because the BCS of
the FLEX_BODY is defined by the basic coordinate system in the finite element
model, re-orientating the BCS with respect to the body requires you to re-orient the
finite element model with respect to its basic coordinate system. In MSC.Nastran,
this can be done easily with CORDxx Bulk Data entries.
FLEX_BODY 95
Adams/Solver (FORTRAN) Statements
Caution:
When one of the following Joints or JPRIMS constrains a flexible body directly
JPRIMS:
INLINE
INPLANE
When one of the following forces is applied directly to a flexible body
Examples
FLEX_BODY/1
, MATRICES=1,2,3,4,5,6,7,8,9,10,11,12,13,14
, CRATIO=0.0\
, DMODE=.0,.0,.0,.0
, VMODE=.0,.1,.0,.0
This statement defines a flexible body with a damping ratio of 0.0 on all modes. Zero initial modal
displacements are specified by the DMODE argument. The VMODE argument specifies an initial modal
velocity for mode 2 of 0.1.
96 Adams/Solver
FLEX_BODY/1
, CRATIO = STEP(TIME, 0.1, 1.0, 1.2, STEP(FXFREQ, 3000, 0.02, 10000,
0.2))\
This example specifies modal damping that varies both with time and modal frequency, such that all
modes have 100% critical damping until t=0.1, after which:
Modal damping decreases smoothly to between 2% and 20% of modal damping at time=1.2.
Modes with modal frequencies less than 3,000 reach 2% modal damping.
Modes with modal frequencies above 10,000 reach 20% modal damping.
Modes with modal frequencies between 3,000 and 10,000 reach modal damping values smoothly
This example recreates the default modal damping scheme using nested IF function expressions.
See other Inertia and material data available.
FRICTION 97
Adams/Solver (FORTRAN) Statements
FRICTION
The FRICTION statement defines parameters for frictional forces on translational, revolute, cylindrical,
hooke, universal, and spherical joints.
Note:
Frictional forces and torques are computed by Adams/Solver (FORTRAN) using a friction
model that supports dynamic friction and stiction.
Format
98 Adams/Solver
Arguments
BALL_RADIUS=Rb
BENDING_REACTION_ARM=Rb
FRICTION_ARM=Rn
FRICTION 99
Adams/Solver (FORTRAN) Statements
INACTIVE=STATIC
INITIAL_OVERLAP=Xs0
JOINT=id
MAX_STICTION_DEFORMATION=r
100 Adams/Solver
MU_DYNAMIC=r
MU_STATIC=r
FRICTION 101
Adams/Solver (FORTRAN) Statements
OVERLAP_DELTA={INCREASE,
DECREASE, CONSTANT}
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
REACTION_ARM=Rn
102 Adams/Solver
FRICTION_TORQUE_PRELOAD=r
I_YOKE J_YOKE
Extended Definition
FRICTION 103
Adams/Solver (FORTRAN) Statements
_________
Description:
Scalar quantity
Vector quantity
Summing junction:
c=a+b
Multiplication junction:
c=axb
MAG
ABS
FRD
Table 2. Relationship Between the INPUTS Argument and Switches Used in the Block Diagrams
Switch:
INPUTS=:
SW1
PRELOAD
SW2
REACTION FORCE
SW3
SW4
Symbol:
Fprfrc or Tprfc
Acceptable Values:
ON/OFF
ON/OFF
BENDING MOMENT
F or F
Tr
TORSIONAL MOMENT
Tn
ON/OFF
ON/OFF
104 Adams/Solver
Static friction
FRICTION 105
Adams/Solver (FORTRAN) Statements
The joint velocity determines the instantaneous friction regime for a joint. The figure below shows the
block diagram of the friction regimes available in Adams/Solver (FORTRAN).
Caution:
Examples
FRICTION/102, JOINT=102, I_YOKE
, MU_Static=0.03, Mu_Dynamic=0.024
, Stiction_Transition _velocity=0.1
, Max_Stiction_Deformation=0.1
, Pin_Radius=12.25
, Friction_arm=8.2
, Effect=All
, Inputs=Reaction_force
This statement creates frictional forces about the rotational degree of freedom associated with the I
markers part of either a hooke or universal joint. The following items apply:
We assume that the joint has a 12.25 length-unit-radius pin and an effective-friction-moment arm
106 Adams/Solver
When computing the frictional force, Adams/Solver (FORTRAN) identifies only the joint-
joint falls below 0.1 rads/unit time. A maximum deflection of 0.1 length units is permitted when
the joint is stiction.
See other Forces available.
GEAR 107
Adams/Solver (FORTRAN) Statements
GEAR
The GEAR statement defines a gear pair constraint. Examples include a spur, helical, planetary, bevel,
and rack-and-pinion gear pairs
Format
CV=id
Identifier of the marker that designates the point of contact and implicitly
determines the ratio of the two gears. The z-axis of the CV marker must point in
the direction of common velocity at the point of contact. The direction of common
velocity is tangent to both pitch circles and would be normal to the tooth surfaces
of the gears if the pressure angle was zero (Adams/Solver (FORTRAN) always
assumes a zero pressure angle). The CV marker must belong to the carrier part that
also hosts the J markers of the joints.
JOINTS=id1,id2
Specifies the two joints whose relative motion is to be related with a gear. Each of
these two joints must be translational, revolute, or cylindrical. Note that both J
markers of these joints belong to a carrier part that must also host the CV marker.
Extended Definition
The GEAR statement uses the location of a common velocity marker to determine the point of contact of
the two gear pitch circles. The direction of the z-axis of the common velocity marker indicates the
direction of the common velocity of points on the gear teeth in contact. This is also the direction in which
gear tooth forces act. Note that the CV marker has constant position and orientation in the carrier body
coordinate system (BCS). The CV marker through its z-axis only provides a direction, and there is no
need to be more specific than this. In this context, there is no need to indicate things such as how the
power flow occurs through the gear.
The reaction force reported back to you for a GEAR element is the reaction force measured on the J
marker of the joint that is specified first in the GEAR definition. It is important to keep in mind that the
J markers for both joints associated with the GEAR element must belong to the carrier part (the part that
hosts the CV marker).
108 Adams/Solver
Caution:
Gear reaction forces and torques are difficult to obtain from the Request file
The figure below illustrates the use of a GEAR statement to define a bevel gear pair.
Bevel Gear Pair
This GEAR statement indicates that the gear pair relates the motions of Joints 13 and 23 and indicates
the common velocity marker. Below are the statements that work with this GEAR statement to
communicate the characteristics of the gear pair to Adams/Solver (FORTRAN).
MARKER/303, PART=3, QP=-2, -2, 0
JOINT/13, I=101, J=301, REVOLUTE
MARKER/101, PART=1, QP=-10, 0, 0
, REULER=0, -90D, 0
MARKER/301, PART=3, QP=-10, 0, 0
GEAR 109
Adams/Solver (FORTRAN) Statements
, 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 (FORTRAN) can determine that the first gear is Part
1 and that it forms a revolute joint with the carrier, which is Part 3. Adams/Solver (FORTRAN) can also
determine that the second gear is Part 2 and that it also forms a revolute joint with the carrier. MARKER
statement 303 defines the location of the common velocity marker.
Schematic of a Rack-and-Pinion Gear Pair
For this gear pair, the same GEAR statement is used as the one in the previous example, but a different
set of JOINT and MARKER statements communicate characteristics of the gear to Adams/Solver. Those
statements are as follows:
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
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).
110 Adams/Solver
GFORCE 111
Adams/Solver (FORTRAN) Statements
GFORCE
The GFORCE statement defines a force element that consists of three orthogonal translational force
components and three orthogonal torque components. You may define the GFORCE statement through
user-specified function expressions in the Adams/Solver (FORTRAN) dataset or through user-written
subroutines.
Format
Arguments
FY=e
FZ=e
I=id
112 Adams/Solver
JFLOAT=id
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
TX=e
TY=e
TZ=e
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 user-specified function expressions in the Adams/Solver (FORTRAN) 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 (FORTRAN) moves the JFLOAT marker on
its part to always keep the JFLOAT and I markers superimposed. Therefore, Adams/Solver (FORTRAN)
applies the reaction force to the part containing the JFLOAT marker at the instantaneous position of the
I marker.
GFORCE 113
Adams/Solver (FORTRAN) Statements
The magnitude of the force depends on the expressions or subroutines you supply. You can specify these
functions with Adams/Solver (FORTRAN) function expressions or user-written FORTRAN-77
subroutines.
The vector formed by the three user-defined component forces along the RM marker axes defines the
direction of the translational force action. The reaction is equal and opposite to the action.
The vector formed by the three component torques determines the direction of the rotational torque
action. You define these torques about the RM marker axes. The reaction is equal and opposite to the
action.
Formulation
Action
Values
Reaction
114 Adams/Solver
where Fr and Tr are the translational and rotational reactions applied at the JFLOAT marker, respectively.
Tip:
Depending on the nature of the desired force relationship, the RM marker may belong to
the same part as the I marker or JFLOAT marker, or to a third, unrelated part.
Caution:
The user-defined forces FX, FY, FZ, TX, TY, and TZ should be smooth, continuous, and
single-valued. These conditions make the solution process very effective.
Examples
GFORCE/1, I=310, JFLOAT=9910, RM=310,
, FX = -20.*VX(310,9900,310)\
, FY = -20.*VY(310,9900,310)\
, FZ = -20.*VZ(310,9900,310)\
, TX = -6.*WX(310,9900,310)\
, TY = -6.*WY(310,9900,310)\
, TZ = -6.*WZ(310,9900,310)
This GFORCE statement defines a general, six-component force acting between fixed Marker 310 and
floating Marker 9910, which must belong to different parts. Expressions FX, FY, FZ, TX, TY, and TZ
define the force and torque components the x, y, and z axes of the reference marker, which is Marker 310.
Adams/Solver (FORTRAN) superimposes floating Marker 9910 on Marker 310, and apply the reaction
force and torque at that point.
Applications
The GFORCE statement is most useful when you need to define a vector force and vector torque whose
point of application and/or direction is most easily formulated in a coordinate system which moves or is
on a different part than the parts containing the force application points. For example, a GFORCE
statement could be used to model the normal and friction force effects for a ball rolling down an inclined
surface. See the figure below.
GFORCE 115
Adams/Solver (FORTRAN) Statements
For this application, the RM reference marker would be fixed to the surface and would supply the
orientation for the normal and friction forces and the torque about the ball center due to the friction.
When compared with the SFORCE (see SFORCE statement), the GFORCE statement can vary both its
point of application (with respect to the part containing the JFLOAT marker) and its resultant direction
(with respect to the RM-marker). In these cases, a single GFORCE statement can represent the complete
force/torque condition at a point along with its reaction forces, whereas it would require six translational
SFORCEs and six rotational SFORCEs, with appropriately-oriented markers, to accomplish the same
thing.
See other Forces available.
116 Adams/Solver
GRAPHICS
The GRAPHICS statement creates:
Two- or three-dimensional geometry for CONTACT. You always define the geometry with
Note:
Because there are two uses for geometry, one for contact and the second for the graphical display of
objects, we have divided the documentation into two separate sections:
GRAPHICS for CONTACT
GRAPHICS for Graphic Display of Objects
New types of graphics are available for representing a wide variety of geometries in contact.
Adams/Solver does not write these new geometric entities (point, plane, ellipsoid, and external) to the
graphics file, and therefore, they cannot be displayed in standalone Adams/Solver (FORTRAN). You can,
however, view them from Adams/View.
Graphics for Contact
Format
,ARC, CM = id, RADIUS = r,RANGLE = r
,BOX, CORNER = id, X = x, Y = y, Z = z
,CIRCLE, CM = id, RADIUS = r
,CURVE, CID = id, CRM = id
,CYLINDER, CM = id, RADIUS = r, LENGTH = r, RANGLE = r
,FRUSTUM, CM = id, RADIUS = r, LENGTH = r, TOP = r, BOTTOM = r, [RANGLE = r]
GRAPHICS/id ,PO INT, RM=id
,PLANE, RM = id, XMIN = r, XMAX = r, YMIN = r, YMAX = r
,EL LIPSOID, CM = id, XSCALE = r, YSCALE = r, ZSCALE = r
,EXTERNAL, RM = id, {FILE = file_name, [ELEMENT = geometry_name]}
,EXTRUSION, CRM = id, GID = id, PID = id
,REVOLUTION, CRM = id, GID = id
,TORUS, CM = id, MINOR_RADIUS = r, MAJOR_RADIUS = r
{ } Select one item
[ ] Optionally select the item
GRAPHICS 117
Adams/Solver (FORTRAN) Statements
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
BOTTOM=r
BOX
Creates a rectangular box. You use the following arguments to define the box:
CORNER to specify the ID of a reference marker at one corner of the
box.
X, Y, and Z to define the extent of the box along the x-, y-, and z-axes of
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 xand y-axes of the marker. The z-axis of the marker defines the centerline
axis of the cylinder or frustum.
For a torus, the origin of the marker specifies the center of the torus. The
Defines the reference marker with respect to which the curve data points are
specified.
CORNER=id
Defines a reference marker, which is at a corner of the box that is being created.
CURVE
Creates a curve graphic based on a CURVE statement. You define the curve data
with respect to a reference marker (CRM). The CONTACTand CVCV modeling
entities require that the curve be planar. It must be in the plane defined by the xand y-axes of the RM marker, and must contain the origin of the marker.
118 Adams/Solver
CYLINDER
Creates a cylinder whose top and bottom are perpendicular to the cylinder central
axis. You use the following arguments to define the cylinder:
CM to specify the center marker (CM) of the cylinder. The z-axis of the
ELEMENT =
geometry_name
ELLIPSOID
Creates an ellipsoid. You use the following arguments to define the ellipsoid:
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.
y-, and z-axes of the CM marker. If the argument values are all equal
(XSCALE = YSCALE = ZSCALE), then Adams/Solver (FORTRAN)
creates a sphere.
EXTERNAL
identifies.
Adams/Solver (FORTRAN) uses the geometry package Parasolid 14.0 to
understand geometry. Parasolid input files have the extension .xmt_txt and
.xmt_bin. Both are supported, however, .xmt_bin files are not portable across
platforms.
Parasolid can read in the geometry data and tell Adams/Solver (FORTRAN):
Whether or not two geometries are in contact.
Where the contact points are located on each geometry.
The outward normals at the calculated contact points.
GRAPHICS 119
Adams/Solver (FORTRAN) Statements
EXTRUSION
FILE=file_name
FRUSTUM
Creates a frustum of a cone whose top and bottom are perpendicular to the cone
central axis. You use the following arguments to define the frustum:
CM to specify the center marker (CM) of the frustum. The z-axis of the
GID=id
LENGTH=r
Defines the height for either a cylinder or frustum. The two circles at the ends of
a cylinder or frustum are both perpendicular to the z-axis of the CM marker.
Therefore, the circles are parallel. Adams/Solver (FORTRAN) uses the value of
LENGTH to specify the z distance between the two circles. There is no limit on
the value of r. A positive value specifies a cylinder or frustum along the positive
z-axis of the CM marker, and a negative value specifies a cylinder or frustum
along the negative z-axis of the CM marker.
120 Adams/Solver
PLANE
Creates a finite plane. You use the following arguments to create a plane:
RM to specify a reference coordinate system for the plane. The plane lies
in the x-y plane of the RM marker (that is, the z-axis of the RM marker is
normal to the plane).
XMIN, XMAX, YMIN, and YMAX to specify the extent of the plane.
The plane is a two-dimensional element, and, therefore, you can only use it when
defining contact with another two-dimensional element (point, arc, circle, curve).
POINT
RADIUS=r
RANGLE=r
Defines an angle measured positive (according to the right-hand rule) about the
z-axis of the CM marker. Adams/Solver (FORTRAN) assumes RANGLE is in
radians. The angle starts at the positive x-axis of the CM marker and subtends the
arc, the arc of the cylinder, or the arc of the cone frustum.
Range: -2 < RANGLE < 2
REVOLUTION
RM=id
Identifies the marker that defines the reference coordinate system for a point,
plane, or external geometric entity. Adams/Solver (FORTRAN) defines the
geometries in this coordinate system.
TOP=r
Defines the radius at the top of a frustum. The top is perpendicular to the CM
marker z-axis, and the center of the top is at the position on the CM marker z-axis
that LENGTH specifies. There is no limit on the value of r.
TORUS
Creates a torus graphic. You use the following arguments to create a torus:
CM to specify the id of the marker that defines the center of the torus. The z-
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.
GRAPHICS 121
Adams/Solver (FORTRAN) Statements
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.
XCALE = r,
YSCALE = r,
ZSCALE = r
Specifies the diameters along the x-, y-, and z-axes of an ellipsoid.
This GRAPHICS statement creates a cylinder with its base at Marker 0201. Marker 0201 is located at the
center of the circular cross-section, which has a radius of two. The cylinder has a length of two along the
negative z-axis of Marker 0201.
GRAPHICS/1297, EXTERNAL, RM=7921,
, FILE = GenevaWheel.xmt_txt
, ELEMENT = Geneva
This GRAPHICS statement creates a three-dimensional solid element. The data for this solid element is
contained in a Parasolid file, GenevaWheel.xmt_txt. Within this file, which contains several geometric
entities, the solid with a tag, Geneva, is to be extracted. The solid definition is specified with respect to
Marker 7921.
The geometry associated with GenevaWheel.xmt_txt is shown next.
122 Adams/Solver
GRAPHICS 123
Adams/Solver (FORTRAN) Statements
FRUSTUM,
CM
=
id
[
,RANGLE
=
r],
LENGTH
=
r
[
,SIDES
=
i]
,TOP
=
r,
BOTTOM
=
r
[
,SEG
=
i
]
,
DA
=
r,
COILS
=
i
SPDP,
I
=
id,
J
=
id
,
DB
=
r,
LA
=
r,
LC
=
r
,
DC
=
r,
LB
=
r,
LD=
r
BEAM
BUSHING
FIELD
GRAPHICS/id,
SFORCE
SPDP
VFORCE
FORCE,
GFORCE
NFORCE
JOINT
JPRIM
PTCV
CVCV
CURVE,
CID=
id,
CRM
=
id1
[
,
...
,
idn]
[
,
SEG
=
i
]
124 Adams/Solver
Arguments
ARC
Creates an arc.
BOTTOM=r
BOX
CID=id
CIRCLE
Creates a circle.
CM=id
Defines the identifier of the marker at the center of an arc, circle, cylinder,
frustum, or torus. If you are creating a circle or arc, orient the CM marker so that
its z-axis is normal to the plane of the circle or plane of the arc. Similarly, if you
are defining a cylinder or frustum, orient the CM marker so that its z-axis is
normal to the bottom plane of the cylinder or the frustum. For the torus the z-axis
should be the axis of the revolution.
COILS
CORNER=id
CRM=id 1[,...,idn]
CURVE
CYLINDER
Creates a cylinder whose top and bottom are perpendicular to the cylinder central
axis.
DA=r
DB=r
Defines the diameter of the damper in a spring-damper at the I marker (see the
spring-damper figure below). There is no limit on the value of r.
Default: 0
DC=r
Defines the diameter of the damper in a spring-damper at the J marker (see the
spring-damper figure below). There is no limit on the value of r.
Default: 0
GRAPHICS 125
Adams/Solver (FORTRAN) Statements
Spring-Damper
EID=id
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
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.
126 Adams/Solver
GID
I=id, J=id
Defines the I and J markers for creating a spring-damper graphic. The I and J
markers define the attachment points of the spring-damper.
LA=r
Defines the distance between the I marker and the end of the damper to which it
is closest (see the spring-damper figure ). There is no limit on the value of r.
Default: 0
LB=r
Defines the distance between the J marker and the end of the damper to which it
is closest (see the spring-damper figure). There is no limit on the value of r.
Default: 0
LC=r
Defines the height of the damper at I. Adams/Solver measures the height from the
bottom of the damper to its top along the line segment between the I and J marker.
There is no limit on the value of r.
Default: 0
LD=r
Defines the height of the damper at J. Adams/Solver measures the height from
the 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 z-axis of the CM
marker, they are parallel. Adams/Solver (FORTRAN) uses the value of LENGTH
to specify the z distance between the two circles. There is no limit on the value
of r. A positive value specifies a cylinder or frustum along the positive z-axis of
the CM marker, and a negative value specifies a cylinder or frustum along the
negative z-axis of the CM marker.
MAJOR_RADIUS
MINOR_RADIUS
OUTLINE=id1[,...,i
d2500]
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 (FORTRAN) draws from
one marker to the next. A comma (,) between two marker identifiers causes
Adams/Solver (FORTRAN) to draw a line segment between two markers. A
comma and minus sign (,-) between two marker identifiers causes Adams/Solver
(FORTRAN) to draw an invisible line from the first marker to the second.
PID
RADIUS=r
Defines the radius of a circle, arc, or cylinder. There is no limit on the value of r.
GRAPHICS 127
Adams/Solver (FORTRAN) Statements
RANGLE=r
Defines an angle measured positive (according to the right-hand rule) about the
z-axis of the CM. Adams/Solver (FORTRAN) assumes RANGLE is in radians.
The angle starts at the positive x-axis of the CM marker and subtends the arc, the
arc of the cylinder, or the arc of the cone frustum. Adams/Solver (FORTRAN)
clips to -2 values of r less than -2 and clips to 2 values of r greater than
2 .
Range: 2 > r > -2
REVOLUTION
RM=id
SEG=i
Defines the number of straight line segments Adams/Solver uses to draw a curve,
circle, an arc, or the two circles at the ends of a cylinder or a frustum.
Default: 20
Range: 99,999 > SEG > 0
SIDES=i
Defines the number of straight line segments Adams/Solver draws between the
two parallel circles of a cylinder or a frustum.
Default: 20
Range: 99,999 > SIDES > 0
SPDP
TOP=r
Defines the radius at the top of a frustum. The top is perpendicular to the CM
marker z-axis, and the center of the top is at the position on the CM marker z-axis
that LENGTH specifies. There is no limit on the value of r.
128 Adams/Solver
TORUS
Creates a torus graphic. You use the following arguments to create a torus:
CM to specify the id of the marker that defines the center of the torus. The z-
X=x,Y=y,Z=z
Locates the vertex of the box that is diagonally opposite from the corner defined
by CORNER. The values of X, Y, and Z must be specified with respect to the
marker coordinate system.
Extended Definition
The GRAPHICS statement creates three-dimensional graphic data for display on a graphics device. You
can use it to create line segments, boxes, curves, circles, arcs, cylinders, frustums of cones, and springdampers. 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 cross-section, which has a radius of two. The cylinder has a length of two along the
negative z-axis of Marker 0201. Twenty sides define the body of the cylinder, and the circles at the top
and at the bottom of the cylinder are actually twenty-sided polygons.
GRAPHICS/0001, OUTLINE=1001,1002,-1003,1004
This GRAPHICS statement creates a line from Marker 1001 to Marker 1002 and creates a line from
Marker 1003 to Marker 1004. Because a minus sign (-) precedes Marker 1003, the statement creates an
invisible line segment from Marker 1002 to Marker 1003.
See other bordered available.
GSE 129
Adams/Solver (FORTRAN) Statements
GSE
The GSE (General State Equation) statement lets you represent a subsystem that has well defined inputs
(u), internal states (x), and a set of well defined outputs (y).
The GSE is represented mathematically as:
x c = f c ( x c, u, t )
x dn + 1 = f d ( x dn, u, t )
xc ( t0 ) = xc
(1)
x d ( t o ) = x do
(2)
y = g ( x c, x d, u, t )
(3)
It consists of continuous states xc, and discrete states xd. The continuous states xc are defined in
Equations (1) as explicit, first-order, ordinary differential equations. fc() is specified in a user-written
subroutine, and is assumed to be continuous everywhere. Integrators in Adams/Solver (FORTRAN)
evaluate fc() as needed.
The discrete states xd are defined in Equations (2) by the function fd(). fd() is specified in a second userwritten subroutine. Equations (2) are difference equations. A sampling period is associated with
Equations (2), and integrators only evaluate Equations (2) at the sample times. The discrete states, xd, are
assumed to be constant between sampling periods. In Equations 2, x d is the short form for xd(tn).
n
The output, y, is sampled continuously, and is defined by g(). g() is specified in a third user-written
subroutine. It may be discontinuous in nature. If the output is to be fed back into the mechanical system
through a force element, then it is customary to eliminate the discontinuities in y, by passing it through a
low-pass filter before feeding the signal into the force element. You can use the TFSISO element to define
a low-pass filter. Failure to eliminate discontinuities in y will cause significant integration difficulties.
If Equations (1) are not present, the GSE is classified as a purely discrete GSE. If Equations (2) are not
present, the GSE is classified as being purely continuous. If both Equations (1) and (2) are present, the
GSE is classified as a sampled system. When neither Equations (1) nor (2) are present, the GSE does not
contain any internal states.
130 Adams/Solver
Format
GSE 131
Adams/Solver (FORTRAN) Statements
Arguments
IC=id
ICD=id
INTERFACE=lib1::gse1,
lib2::gse2, lib3::gse3, lib4::gse4
ND=i
Specifies the number of discrete states in the GSE. Discrete states are
updated by calling the function GSE_UPDATE at the sample times.
ND defaults to zero when not specified.
NO=i
132 Adams/Solver
NS=i
ROUTINE=lib1::gse1,
Specifies alternative library and subroutine names for the deprecated
lib2::gse2, lib3::gse3, lib4::gse4, user subroutines GSESUB, GSEXX, GSEXU, GSEYX, GSEYU
lib5::gse5
respectively.
Learn more about the ROUTINE Argument.
SAMPLE_OFFSET=r
SAMPLE_PERIOD=expression Specifies the sampling period associated with the discrete states of a
GSE. This tells Adams/Solver (FORTRAN) to control its step size so
that the discrete states of the GSE are updated at:
last_sample_time + sample_period
In cases where an expression for SAMPLE_PERIOD is difficult to
write, you can specify it in a user-written subroutine
GSE_SAMP(). Adams/Solver (FORTRAN) will call this function
at each sample time to find out the next sample period.
STATIC_HOLD
Indicates that the continuous GSE states are not permitted to change
during static and quasi-static simulations.
U=id
X=id
GSE 133
Adams/Solver (FORTRAN) Statements
Y=id
XD=id
Extended Definition
The GSE (General State Equation) statement defines the equations for modeling a nonlinear, time
varying, dynamic system. The statement is especially useful for importing nonlinear control laws
developed manually or with an independent software package. It can also be used to define an arbitrary
system of coupled differential and algebraic equations that can be expressed as:
x c = f c ( x c, u, t )
xc ( t0 ) = xc
x dn + 1 = f d ( x dn, u, t )
x d ( t o ) = x do
y = g ( x c, x d, u, t )
(4)
(5)
(6)
The GSE allows you to implement four different kinds of systems. These are:
Continuous Systems
Discrete Systems
Sampled Systems
Feed-Forward Only System
Continuous Systems
x c = f c (x c,u ,t) , x c ( t 0 ) = x c 0
(7)
y = g (x c,u ,t)
(8)
xc is called the state of the system, and contains n elements for an nth-order system. In matrix notation,
xc is a column matrix of dimension nx1. u defines the inputs to the system. Its size is equal to the number
of inputs to the system being modeled. In this description, the system is assumed to have m inputs,
134 Adams/Solver
consequently u is a column matrix of size mx1. y defines the outputs from the system. If a system has p
outputs, y is represented with a column matrix of dimension px1.
Using this system description, a nonlinear, second-order differential equation, with input u, such as:
2
y + 2 n yy + n y = Ku
(9)
x2
x 1
=
x2
2 n x 1 x 2 2n x + Ku
y = x1
(10)
(11)
The state Equations (7) or (10) are integrated by Adams/Solver using its integrators. Therefore, it is
necessary that the functional relationship expressed in Equations (7) or (10) be continuous. That is a
minimum requirement for successfully integrating these equations. Similarly, if the output is to be fed
back into a plant model, such as a mechanical system, Equations (8)5 or (11) are also required to be
continuous. A higher degree of differentiability will help the integrators solve these equations more
efficiently.
Discrete Systems
Discrete systems can be described by their difference equations. They are, therefore, represented in the
state-space form as:
x dn + 1 = f d ( x d n, u, t )
y = g (x d,u ,t)
x d ( t o ) = x do
(12)
(13)
xd is called the state of the system, and contains n elements for an nth-order system. In matrix notation,
xd is a column matrix of dimension nx1. u and y have the same meaning as for continuous systems.
The fundamental difference between continuous and discrete systems is that the discrete or digital system
operates on samples of the sensed plant data, rather than on the continuous signal. The dynamics of the
controller are represented by recursive algebraic equations, known as difference equations, that have the
form shown in Equations (12).
The sampling of any signal occurs repetitively at instants in time that are T seconds apart. T is called the
sampling period of the controller. In complex systems, the sampling period is not a constant, but is,
instead, a function of time and the instantaneous state of the controller. The signal being sampled is
usually maintained at the sampled value in between sampling instances. This is called zero-order-hold
(ZOH). Determining an appropriate sampling period is a crucial design decision for discrete and sampled
systems.
GSE 135
Adams/Solver (FORTRAN) Statements
One major problem to avoid with sampling is aliasing. This is a phenomenon where a signal at a
frequency
occurring too infrequently. The general rule of thumb for such situations is as follows:
If you want to avoid aliasing in a signal with a maximum frequency of
frequency is calculated from
, the sampling
s / < 40.
The sampling rate for sampling the states of a discrete system must follow the above criterion to avoid
aliasing.
Note that when an Adams/Solver output time and a GSE sample time coincide, the output of the GSE at
that time will be calculated using the values of the discrete states before the update takes place. This is
true for discrete states in discrete systems and sampled systems.
Sampled Systems
There are many systems that are neither continuous nor discrete. Some signals are sampled at discrete
intervals, while others are sampled continuously. These systems are called sampled systems and are
represented in the state-space for as:
x c = f c ( x c, u, t )
x c ( t 0 ) = x co
x dn + 1 = f d ( x dn, u, t )
y = g ( x c, x d, u, t )
x d ( t o ) = x do
(14)
(15)
(16)
Equations (14) represent the dynamics associated with the continuous piece of the sampled system. States
xc are continuous and fc() is assumed to be continuous.
Equations (15) represent the dynamics associated with the discrete piece of the sampled system. The
equations are evaluated only at discrete points in time, the sample times for the sampled system. In
between sample times, the discrete states are assumed to be constant.
Equation (16) defines the outputs of the system. It is important to note that the ADAMS integrators
evaluate Equation (16) as often as necessary. In many problems, it is important to examine the output
between sampling instants. Often, for example, the maximum overshoot may occur not at a sampling
point, but between samples. This implementation allows for such observations to be made on the output.
Feed-Forward Only System
These are systems that have no independent states. The output of the system is an algebraic function of
the inputs. They can be represented as:
y = g (u,t)
(17)
136 Adams/Solver
Caution:
The GSE statement provides a very general capability for modeling nonlinear
systems. However, the routines for solving the linear equations in Adams/Solver
(FORTRAN) have been developed and refined to work particularly well with the
sparse systems of equations that come from the assembly of mechanical models.
With the GSE statement, you can create very dense sets of equations. If these
equations form a large portion of the completed model, Adams/Solver
(FORTRAN) may perform more slowly than expected.
During a static analysis, Adams/Solver (FORTRAN) finds equilibrium values for
Outputs
It has one output, y.
The output is an actuator signal.
States
GSE 137
Adams/Solver (FORTRAN) Statements
Transfer Functions
The transfer functions of the controller are:
Y ( s ) 2e7
------------= -------------------------------------2
U1 ( s )
s + 2e3s + 1e7
Y(s)
1e3s 1e7 -------------- = -------------------------------------2
U2 ( s )
s + 2e3s + 1e7
A GSE represents the controller. Standard ADAMS modeling elements PART, JOINT, and SFORCE
represent the block, translational joint, and the actuator, respectively.
Model Input File
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,
marker/2, part = 2, qp =
marker/4, part = 2, qp =
marker/6, part = 2, qp =
marker/7, part = 2, qp =
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.
138 Adams/Solver
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.
GSE 139
Adams/Solver (FORTRAN) Statements
140 Adams/Solver
C
C
C
C
C
C
LEFLAG)
LEFLAG)
B(1,1)*U(1)+B(1,2)*U(2)
B(2,1)*U(1)+B(2,2)*U(2)
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
GSE 141
Adams/Solver (FORTRAN) Statements
C
C
RETURN
END
The example below demonstrates how you can use a GSE to define a discrete controller in ADAMS. The
plant consists of a block on a translational joint. A discrete control force is applied to the block to move
it exactly 150 mm from its initial position. The controller has a sample time of 0.001 seconds. The control
system is defined as follows:
Inputs
It has two inputs (u1 and u2).
The first input (u1) is the location of the block.
The second input (u2) is the velocity of the block.
Outputs
It has one output, y.
The output is an actuator signal.
States
The controller is a linear PID controller.
It has two discrete states (x1 and x2).
Y(z)
5.285z 2.707 -------------- = ------------------------------------------------------2
U1 ( z )
z 0.73576z + 0.1353
Y ( z ) 0.63212
------------= ---------------------------z 0.36788
U1 ( z )
A GSE represents the controller. Standard ADAMS modeling elements PART, JOINT, and SFORCE
represent the block, translational joint, and the actuator, respectively.
GSE Test: Continuous states=0, Discrete states=2, 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
142 Adams/Solver
MARKER/2,
MARKER/4,
MARKER/6,
MARKER/7,
PART
PART
PART
PART
=
=
=
=
2,
2,
2,
2,
QP
QP
QP
QP
=
=
=
=
0, 0,
-150,
0, 0,
-150,
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
ARRAY/2, Y, SIZE = 1
ARRAY/3, X, SIZE = 2
GSE/99, ND=2, NO = 1, XD = 3, U = 1, Y = 2
, Sample_Period = 0.001/
, FUNCTION = USER(3,1)/
ACCGRAV/JGRAV = -9806.65
RESULTS/FORMATTED
END
Simulation Results
The figure below below shows the time history of the location and velocity of the block. Notice the
displacement (red curve) starts at 0 mm, and stops moving when it reaches a value of 150 mm.
GSE 143
Adams/Solver (FORTRAN) Statements
The next figure shows the time history of the actuator signal computed by the controller. This is the force
applied on the block. Zooming into the curve shows that the output of the controller is discrete. Because
the sampling period of the controller is 0.001 seconds, output was requested every 0.0005 seconds in
order to see the discrete nature of the output. The states also show similar behavior.
144 Adams/Solver
GSE 145
Adams/Solver (FORTRAN) Statements
C Y = C*Xd
C
AXD(1) = NINT(PAR(1))
CALL SYSARY ('ARRAY', AXD, 1, XD, ND, LEFLAG)
Y(1) = C(1)*XD(1) + C(2)*XD(2)
C
C
RETURN
END
C
C+===================================================================
=*
C
SUBROUTINE GSE_UPDATE (ID, TIME, PAR, NPAR, DFLAG, IFLAG, ND,
*
XDplus1)
C
C Inputs:
C
INTEGER
ID, NPAR, ND
DOUBLE PRECISION PAR(*), TIME
LOGICAL
IFLAG, DFLAG
C
C Outputs:
C
DOUBLE PRECISION XDplus1(ND)
C
C Local Variables:
C
LOGICAL
LEFLAG
INTEGER
AXD(1), AU(1), NDD, NU
DOUBLE PRECISION A(2,2), B(2,2), XD(2), U(2)
SAVE
A, B
DATA
A/.36788, 0.0, -7.3576, .36788/
DATA
B/-.0052848, 0.00063212, -.00063212, 0.0/
C
C+--------------------------------------------------------------------*
C
C Xd+1 = A*Xd + B*U
C
AXD(1) = NINT(PAR(1))
AU (1) = NINT(PAR(2))
CALL SYSARY ('ARRAY', AXD, 1, XD, NDD, LEFLAG)
CALL SYSARY ('ARRAY', AU , 1, U , NU, LEFLAG)
XDplus1(1) = A(1,1)*XD(1)+ A(1,2)*XD(2) + B(1,1)*U(1) +
B(1,2)*U(2)
XDplus1(2) = A(2,1)*XD(1)+ A(2,2)*XD(2) + B(2,1)*U(1) +
B(2,2)*U(2)
C
C
RETURN
END
C
146 Adams/Solver
C+===================================================================
=*
C
Sampled GSE
The example below demonstrates how you can use a GSE to define a sampled controller in Adams. The
plant consists of a block on a translational joint. A sampled system controls the block to move it exactly
150 mm from its initial position.
The controller is modeled in Simulink. Real Time Workshop (RTW) is then employed to generate the
governing equations for the GSE. An interface is then written between the code generated by RTW and
the GSE subroutines: GSE_DERIV, GSE_UPDATE, GSE_OUTPUT, and GSE_SAMP.
The block diagram for the sampled control system is shown below:
Block Diagram of the Sampled System Used to Control the Block
States
The controller has two continuous states.
It has three discrete states.
GSE 147
Adams/Solver (FORTRAN) Statements
Outputs
It has one output, out1.
The output is an actuator signal, which is a function of the continuous and the discrete states of
the controller and the two inputs. A low pass filter, Fcn2, is employed to obtain a smooth output
that may be fed into the mechanical system.
The controller is represented in a GSE. The block, translational joint, and the actuator are represented
using the standard ADAMS modeling elements PART, JOINT, and SFORCE, respectively.
To see a representation of the model and a Simulink representation of the control system, see the Release
Notes.
Simulation Results
The figure below shows the time history of the control force on the block. Notice that the control force
changes sign when the block overshoots its desired position.
Time History of the Actuator Force on the Block
148 Adams/Solver
IC
The IC statement specifies error tolerances and other parameters for the analysis of the initial conditions
and for reconciling integrator output.
Format
Arguments
AERROR=r
ALIMIT=r
AMAXIT=i
IC 149
Adams/Solver (FORTRAN) Statements
APATTERN=c1 Specifies as many as ten character strings that together establish the pattern for
[:...:c10]
evaluating the Jacobian matrix during the modified Newton-Raphson solution for the
accelerations. For each iteration, T or TRUE indicates that Adams/Solver
(FORTRAN) is to evaluate the Jacobian, and F or FALSE indicates that
Adams/Solver (FORTRAN) is not to evaluate the Jacobian. Thus, cj determines
whether or not Adams is to evaluate the Jacobian at the jth iteration. If necessary,
Adams/Solver (FORTRAN) repeats the pattern of evaluation until it reaches the
maximum number of iterations (AMAXIT). The number of T's or TRUEs and Fs or
FALSEs 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=
MAXIT=i
PATTERN=ci[:. Specifies as many as ten character strings that together establish the pattern for
..:c10]
evaluating the Jacobian matrix during the modified Newton-Raphson solution for the
displacements. For each iteration, T or TRUE indicates that Adams/Solver
(FORTRAN) is to evaluate the Jacobian, and F or FALSE indicates that
Adams/Solver (FORTRAN) is not to evaluate the Jacobian. Thus, cj determines
whether or not ADAMS is to evaluate the Jacobian at the jth iteration. If necessary,
Adams/Solver (FORTRAN) repeats the pattern of evaluation until it reaches the
maximum number of iterations (MAXIT). The number of Ts or TRUEs and Fs or
FALSEs 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.
150 Adams/Solver
TLIMIT=r
VERROR=r
Extended Definition
The IC statement specifies error tolerances and other parameters for the analysis of initial conditions and
for reconciling integrator output. By default, ABAM and WSTIFF reconcile integrator results to be
consistent with constraints; GSTIFF does not, unless you set INTERPOLATE=ON.
This statement is used only when requesting a dynamic, static equilibrium, or quasi-static equilibrium
analysis, and when one or more of the tolerances and other parameters for the initial conditions analysis
from the default values is to be changed.
Use the SIMULATE command to request a dynamic, static equilibrium, or quasi-static equilibrium
analysis. Before performing one of these analyses, Adams/Solver (FORTRAN) automatically does an
initial conditions analysis. An initial conditions analysis is not necessary when the system has zero
degrees of freedom because the kinematics of the system fully determine its configuration.
The initial conditions analysis ensures that the system satisfies all constraints within the system. If
necessary, Adams/Solver (FORTRAN) moves parts until both parts of each joint are in contact. This
analysis involves three separate phases. First, Adams/Solver (FORTRAN) makes the displacements
between all parts and joints in the system physically consistent. This requires the use of Newton-Raphson
iteration to solve a set of nonlinear algebraic equations. Once the displacements are consistent,
Adams/Solver (FORTRAN) makes the velocities physically consistent. Since this requires solving a set
of linear equations, iteration is not necessary. Finally, Adams/Solver (FORTRAN) also calculates
consistent accelerations and forces. This solution also requires solving a set of nonlinear equations using
Newton-Raphson iteration.
When reconciling, the integrator uses the initial conditions solution process at each output step to ensure
that velocities, accelerations, and forces are consistent with the system constraints. If you set
INTERPOLATE=ON, the integrator also uses the initial conditions solution at each output step to ensure
displacements are consistent with the constraints. The IC parameters control those solutions as well as
the initial conditions solution.
If you issue neither the IC command nor statement in an Adams/Solver (FORTRAN) session,
Adams/Solver (FORTRAN) uses the default values for AERROR, ALIMIT, AMAXIT, APATTERN,
IC 151
Adams/Solver (FORTRAN) Statements
ERROR, MAXIT, PATTERN, TLIMIT, and VERROR when finding initial conditions and reconciling
integrator output.
Tip:
Use the ALIMIT and TLIMIT arguments to limit incrementing displacement variables and
thus the size of the position change on successive iterations. This tends to prevent
Adams/Solver (FORTRAN) from assembling the mechanism in an undesirable
configuration.
Examples
IC/ALIMIT=10D, ERROR=1.0E-6, MAXIT=45
This statement instructs Adams/Solver (FORTRAN) to use these values instead of the defaults when
performing an initial conditions analysis. It limits the angular increment per iteration to 10 degrees,
reduces the displacement error to less than 1.0E-6, and limits the number of iterations to 45.
See other Analysis parameters available.
152 Adams/Solver
INTEGRATOR
The INTEGRATOR statement lets you control the numerical integration of the equations of motion for
a dynamic analysis. You should use the INTEGRATOR statement when the default values for the
numerical solution parameters are not optimal for a particular simulation.
Format
INTEGRATOR 153
Adams/Solver (FORTRAN) Statements
Arguments
ABAM
ADAPTIVITY=r
CONSTANT_BDF
154 Adams/Solver
Specifies the corrector algorithm that is to be used with the stiff integrators
ORIGNAL GSTIFF, WSTIFF, or CONSTANT_BDF. The corrector in a stiff integrator
CORRECTOR =
ensures that all candidate solutions satisfy the equations of the system. The two
MODIFIED
algorithms, original and modified, differ primarily in the algorithm that they use to
define when the corrector iterations have converged.
CORRECTOR=original - Specifies that the corrector available in the
INTEGRATOR 155
Adams/Solver (FORTRAN) Statements
ERROR=r
Specifies the relative and absolute local integration error tolerances that the
integrator must satisfy at each step. For BDF integrators, Adams/Solver
(FORTRAN) monitors the integration errors in the displacement and state
variables that the other differential equations (DIFFs, LSEs, GSEs, and TFSISOs)
define. ABAM, SI1, and SI2 formulations also monitor errors in velocity variables.
The larger the ERROR, the greater the error/step in your solution.
Note that the value for ERROR is units-sensitive. For example, if a system is
modeled in mm-kg-s units, the units of length must be in mm.
Assuming that all the translational states are larger than 1mm, setting ERROR=1E3 implies that the integrator monitors all changes of the order of 1 micron.
The error tolerances (e) are enforced as:
||Yc - Y|| < MAX (e, e * ||Y||)
where Yc is the column matrix of computed values for the unknowns, Y. The
symbol || . || indicates the root-mean-square of the array of numbers.
Default: 1E-3
Range: ERROR > 0
GSTIFF
Specifies that the GSTIFF (Gear) integrator is to be used for integrating the
differential equations of motion.
HINIT=r
HMAX=r
Defines the maximum time step that the integrator is allowed to take.
Default: When setting the argument INTERPOLATE = ON, the integration step
size is limited to the value specified for HMAX, but if HMAX is not defined, no
limit is placed on the integration step size. If INTERPOLATE = OFF, the
maximum step size is limited to the output step.
Range: 0 < HMIN < HINIT < HMAX
Note:
156 Adams/Solver
HMIN=r
Defines the minimum time step that the integrator is allowed to take.
Default: 1.0E-6*HMAX for GSTIFF and WSTIFF. Machine precision for ABAM,
SI1, and the SI2 formulation
Range: 0 < HMIN < HINIT < HMAX
ON
INTERPOLATE =
OFF
Specifies that the integrator is not required to control its step size to hit an output
point. Therefore, when the integrator crosses an output point, it computes a
preliminary solution by interpolating to the output point. It then refines or
reconciles the solution to satisfy the equations of motion and constraint.
INTERPOLATE=OFF turns off interpolation for the chosen integrator.
Default: OFF for GSTIFF and WSTIFF;
ON for ABAM
Note:
I3
Specifies the Index-3 (I3) formulation be used. For more information, see
Extended Definition.
Default: I3
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:
INTEGRATOR 157
Adams/Solver (FORTRAN) Statements
MAXIT=i
PATTERN=c1[:...:c10]
Indicates the pattern of trues and falses for re-evaluating the Jacobian matrix for
Newton-Raphson. A value of true (T) indicates that Adams/Solver (FORTRAN) is
evaluating a new Jacobian matrix for that iteration. A value of false (F) indicates
that Adams/Solver (FORTRAN) is using the previously calculated Jacobian matrix
as an approximation of the current one.
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
Note:
RKF45
158 Adams/Solver
SCALE=r1[,r2][,r3]
SCALE applies to only WSTIFF and ABAM. It is not applicable to GSTIFF and
CONSTANT_BDF.
SCALE scales the sum of the relative and absolute error tolerances. If T is the sum
of the relative and absolute error tolerances applied to the state vector, then the
following tolerance is applied:
r1 * T to the translational displacements
r2 * T to the angular displacements
r3 * T to the modal coordinates
Note:
Default:
WSTIFF, ABAM, and RKF45: SCALE = 1, 1, 1e-3
GSTIFF and CONSTANT_BDF: You cannot control SCALE
Specifies that the Stabilized Index-1 (SI1) formulation, in conjunction with the
GSTIFF, WSTIFF, or CONSTANT_BDF 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. In addition, it monitors the integration error on the impulse of
the Lagrange Multipliers in the system. These additional safeguards enable the
integrators to monitor the integrator error in velocity variables and the impulse of
the Lagrange Multipliers. Simulations results are therefore very accurate. A
positive side effect of the SI1 formulation is that the Jacobian matrix remains stable
at small step sizes, which in turn increases the stability and robustness of the
corrector at small step sizes.
For additional information, see the Extended Definition.
Default: I3
INTEGRATOR 159
Adams/Solver (FORTRAN) Statements
SI2
Specifies that the Stabilized Index-2 (SI2) formulation, in conjunction with the
GSTIFF or CONSTANT_BDF integrator, be used for formulating and integrating
differential equations of motion.
The SI2 formulation takes into account constraint derivatives when solving for
equations of motion. This process enables the GSTIFF integrator to monitor the
integration error of velocity variables, and, therefore, renders highly accurate
simulations. A positive side effect of the SI2 formulation is that the Jacobian
matrix remains stable at small step sizes, which in turn increases the stability and
robustness of the corrector at small step sizes.
The SI2 formulation is available only with GSTIFF, WSTIFF, and
CONSTANT_BDF.
For additional information, see the Extended Definition.
Default: I3
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
Extended Definition
You use the INTEGRATOR statement to select an integrator when you choose to perform a dynamic
analysis. The dynamic analysis of a mechanical system consists essentially of numerically integrating the
nonlinear differential equations of motion.
Ordinary differential equations (ODEs) can be characterized as being stiff or non-stiff. A set of ODEs is
said to be stiff when it has widely separated eigenvalues (low and high frequencies) with the high
frequency eigenvalues being overdamped. Therefore, while the system has the ability to vibrate at high
frequencies, it usually does not because of the associated high damping, which dissipates this mode of
motion.
The stiffness ratio of a set of ODEs is defined as the highest inactive frequency divided by the highest
active frequency. Stiff ODEs typically have a stiffness ratio of 200 or higher. In contrast, non-stiff
systems have a stiffness ratio less than 20. This basically means that for a non-stiff system of ODEs, the
higher frequencies of the system are active. The system can and does vibrate at these frequencies.
An example of a stiff system is a flexible body in which the higher frequencies have been damped out
completely, leaving only the lower frequency vibration modes active.
The system above becomes non-stiff if the higher frequencies are excited by an external force. Nonlinear
ODEs can be stiff at some points in time and non-stiff at other points.
Stiff and Non-Stiff Integrators
160 Adams/Solver
Integrators are classified as stiff or non-stiff. A stiff integrator is one that can handle numerically stiff
systems efficiently. For stiff integrators, the integration step is limited by the inverse of the highest active
frequency in the system. For non-stiff integrators, the integration step is limited by the inverse of the
highest frequency (active or inactive) in the system. Thus, non-stiff integrators are notoriously inefficient
for solving stiff problems.
Because many mechanical systems are numerically stiff, the default integrator in Adams/Solver (C++) is
GSTIFF, a stiff integrator that is based on the DIFSUB integrator developed by C.W. Gear. The DIFSUB
integrator by C.W. Gear is unrelated to the Adams/Solver subroutine that is known by the same acronym.
Adams/Solver (FORTRAN) also provides two additional stiff integrators: CONSTANT_BDF and
WSTIFF. All of these integrators are based on Backward-Difference Formulae (BDF) and are multi-step
integrators. The solution for these integrators occurs in two phases: a Prediction followed by a Correction.
Note:
If you are not sure whether your model is numerically stiff, you should avoid using ABAM
or RKF45. Instead, select GSTIFF or WSTIFF. If you incorrectly select ABAM for a stiff
system, the numerical method fails or becomes extremely slow.
Prediction
When taking a new step, the integrator fits a polynomial of a given order through the past values of each
system state, and then extrapolates them to the current time to perform a prediction. Standard techniques
like Taylor's series (GSTIFF) or Newton Divided Differences (WSTIFF) are used to perform the
prediction.
Prediction is an explicit process in which only past values are considered, and is based on the premise
that past values are a good indicator of the current values being computed. The predicted value does not
guarantee that it will satisfy the equations of motion or constraint. It is simply an initial guess for starting
the correction, which ensures that the governing equations are satisfied.
The degree of polynomial used for prediction is called the order of the predictor. For example, a predictor
of order 3 will fit a cubic polynomial that includes the past 4 values for each state. Clearly, if the
governing equations are smooth, the prediction will be quite accurate. On the other hand, if the governing
equations are not smooth, the prediction can be quite inaccurate.
Correction
The corrector formulae are an implicit set of difference relationships (BDFs) that relate the derivative of
the states at the current time to the values of the states themselves. This relationship transforms the
nonlinear differential algebraic equations to a set of nonlinear, algebraic difference equations in the
system states. The Backward Euler integrator is an example of a first-order BDF. Given a set of ODEs of
the form dy/dt = f (y,t), the Backward Euler uses the difference relationship:
y n + 1 = y n + hy n + 1
where:
yn is the solution calculated at t = tn.
(18)
INTEGRATOR 161
Adams/Solver (FORTRAN) Statements
Notice that the subscript n+1 is on both sides of Equation (18). This is an implicit method.
Adams/Solver (FORTRAN) uses an iterative, quasi-Newton-Raphson algorithm to solve the difference
equations and obtain the values of the state variables. This algorithm ensures that the system states satisfy
the equations of motion and constraint. The Newton-Raphson iterations require a matrix of the partial
derivatives of the equations being solved with respect to the solution variables. This matrix, known as
the Jacobian matrix, is used at each iteration to calculate the corrections to the states.
Assume that the equations of motion have the form:
F (y,y ,t) = 0
(19)
F
k k
= F (y ,y ,t) + -----y
y ,y
k
y and ( y y ) with y , you get:
replacing y - yk with
F
k k
F (y ,y ,t) + -----y
y ,y
F
y + -----y
k
y ,y
y = 0
(20)
k
y ,y
k
From Equation (18), which is a first-order BDF, you can get the relationship:
1
y = --- y
h
(21)
----Fy
1 F
+ --- -----h y
k
y ,y
k k
y = F (y ,y ,t)
y ,y
k
(22)
----Fy
1 F
+ --------- -----h
0 y
k
y ,y
where:
k k
y = F (y ,y ,t)
k
y ,y
(23)
162 Adams/Solver
scalar that is characteristic to an integration order. For each integration order this scalar is
constant.
The matrix on the left side of Equation (23) is the Jacobian matrix of F.
The corrector is said to have converged when the residue F and the corrections
After the corrector has converged to a solution, the integrator estimates the local integration error in the
solution. This is usually a function of the difference between the predicted value and the corrected value,
the step size, and the order of the integrator. If the estimated error is greater than the specified integration
ERROR, the integrator rejects the solution and takes a smaller time step. If the estimated error is less than
the specified local integration ERROR, the integrator accepts the solution and takes a new time step. The
integrator repeats the prediction-correction-error estimation process until it reaches the time specified in
the SIMULATE command.
Note:
The premise for using predictions as an initial guess for the corrector is severely violated
when discontinuities occur or when large forces turn on or off in the model. Contact,
friction, and state transitions (as in hydraulics where a valve is suddenly closed or opened)
are examples of such phenomena. These kinds of models are difficult for multi-step
integrators.
GSTIFF
GSTIFF is based on the DIFSUB integrator. GSTIFF is the most widely-used and tested integrator in
Adams/Solver (FORTRAN). It is a variable-order, variable-step and multi-step integrator with a
maximum integration order of six. The BDF coefficients it uses are calculated by assuming that the step
size of the model is mostly constant. Thus, when the step size changes in this integrator, a small error is
introduced in the solution. This formulation offers the following benefits and limitations:
Characteristics of GSTIFF Integrator
Benefits:
High speed.
High accuracy of the system
displacements.
Robust in handling a variety
of analysis problems.
Limitations:
Velocities and especially accelerations can have errors.
INTEGRATOR 163
Adams/Solver (FORTRAN) Statements
References
Jersey: Prentice-Hall.
CONSTANT_BDF
CONSTANT_BDF is a modification of the DIFSUB integrator, to make it behave like a stable, fixed-step
integrator. It is a variable-order, predominantly fixed-step, multi-step integrator, with a maximum order
of six. Because it is a BDF method, it is stiffly stable, that is, it can solve stiff problems efficiently without
becoming unstable.
The maximum integrator step size, HMAX, controls the integration error in CONSTANT_BDF.
CONSTANT_BDF does not attempt to calculate the local integration error. If the corrector has
converged, CONSTANT_BDF assumes that the solution is correct. The step size is fixed at HMAX. The
integrator order is gradually increased up to KMAX. In this regard, it is very much like a fixed-step
integrator.
If the corrector fails to converge, CONSTANT_BDF reduces the step size until the corrector converges.
CONSTANT_BDF restores the step size to HMAX every 25 steps. CONSTANT_BDF works with both
the Index-3 (I3) and the Stabilized Index-2 (SI2) formulations. We recommend that you use the SI2
formulation wherever possible because it is much more stable. Like GSTIFF, CONSTANT_BDF also
works with the modified corrector, which can handle discontinuities much more effectively. To use the
modified corrector, choose corrector=modified in the INTEGRATOR statement.
Unlike GSTIFF or WSTIFF, CONSTANT_BDF tends to run at the maximum allowable KMAX. A high
integration order implies greater accuracy. Coupled with explicit step size control, the use of a high
integrator order normally results in quite accurate solutions. If your answers do not seem to be accurate,
decrease HMAX. This will give you better answers. We recommend that you scale down HMAX
gradually in factors of two, because simulation times can increase when you reduce HMAX.
All integration control parameters available for GSTIFF are also available for CONSTANT_BDF.
The table below summarizes the benefits and limitations of the CONSTANT_BDF integrator.
Characteristics of CONSTANT_BDF Integrator
Benefits:
Limitations:
164 Adams/Solver
Benefits:
Limitations:
Is not as susceptible to spikes in accelerations and Too small of a value for HMAX results in slow
forces as GSTIFF.
simulations.
High accuracy in system displacements and
velocities.
000
SI2
SI2 (Stabilized-Index Two) is an equation formulation technique that can be used for equations
describing mechanical systems. Currently, this formulation is available only with GSTIFF, WSTIFF, and
CONSTANT_BDF.
To understand what the SI2 formulation does, you need to know what Differential Algebraic Equations
(DAE) are and understand the notions of Index of a DAE and stabilization of DAE. A brief summary is
given below. For more information, refer to:
Brenan, K.E., Campbell, S.I., and Perzold, L.R. (1996). Numerical Solution of Initial Value
E = y f ( y ,t ) = 0, y ( 0 ) = y 0
(24)
E
= I , and is never singular.
y
E = F ( y ,y ,t ) = 0, y ( 0 ) = y 0
(25)
E
y
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:
T
T
Mq + q A F (q,q) = 0
(26)
(q,t) = 0
(27)
where:
INTEGRATOR 165
Adams/Solver (FORTRAN) Statements
F is the set of applied forces and gyroscopic terms of the inertia forces.
AT is the matrix that projects the applied forces in the direction q.
q is the gradient of the constraints at any given state and can be thought of as the normal to the
constraint surface in configuration space.
Notice that Equation (26) is a second-order differential equation but Equation (27) is an algebraic
equation. Also notice the time derivatives of q are seen in Equations (26), but
Equation (26) or (27).
The index of a DAE is defined as the number of time derivatives required to convert a set of DAEs to
Odes
Equations (26) can be converted to a set of ODE by first taking two time derivatives of the kinematic
position constraint equations in Eq.(27), to obtain the set of kinematic acceleration constraint equations.
These equations together with the equations of motion in Eq.(26) can be formally solved for the
accelerations and the Lagrange multipliers . By taking a third and last time derivative of the Lagrange
multipliers, one is left with a set of ODE in accelerations and the Lagrange multipliers.
Therefore, the Euler-Lagrange equations for mechanical systems are said to have an Index=3.
Solution of DAEs
Equations (26) are converted to first-order form, so that commercially available DAE integrators can
solve them. This is usually done by introducing a new variable, the velocity variable u, which is defined
as:
u q = 0
(28)
(29)
u q = 0
(30)
= 0
(31)
These are the DAE (in first order form) for a mechanical system. Applying the BDF formula (like
Equation (21)), one obtains the Jacobian of Equation (29):
166 Adams/Solver
M
--------- A T F U
h 0
M q u + qq ( A F )
I
--------h 0
This matrix becomes ill conditioned as the integration step size h decreases, and becomes singular as h
moves closer to 0.
This is the reason why Index 3 formulations become unstable at small step sizes -- a very counterintuitive result.
Another important result for Index 3 formulations is that the integration error cannot be monitored on
either velocities, u, or reaction forces, .
Index reduction methods (IRM) are typically employed to make DAE more easily solvable by numerical
methods. The key benefit to using IRM is that the integration error can be monitored on velocities.
Index Reduction Methods
There are many ways to reduce the index of a DAE. In general, the lower the index of a DAE, the more
theoretically tractable it is to being numerically solved. So in general, it is a good idea to try to reduce
the index of a DAE.
One common approach is to replace Equation (31) with the time derivatives of the constraint. Every level
of differentiation reduces the index by one.
For example, you might be tempted to reduce the Index of Equation (29) to two by differentiating (31):
T
T
Mu + q A F = 0
T
u q + q = 0
( q ,u ,t ) = 0
(q,t) = 0
(32)
Solving Equations (32) numerically adds a new complication, however. The solution satisfies Equation
(32), but is not guaranteed to solve Equation (29), the original constraint.
If you were to formulate a simple pendulum using Equations (32) and solve them, you would notice that
after some time the pin-joint constraint is violated and the pendulum drifts off into space, grossly
violating the pin-joint, and the system Equation (32) is not aware.
Clearly, a means for considering Equation (31) along with Equations (32) to prevent drift-off is required.
The SI2 formulation does precisely this.
INTEGRATOR 167
Adams/Solver (FORTRAN) Statements
Gear, Gupta, and Leimkuhler have shown that drift-off can be prevented by appending Equation (29) to
(32) and adding a new set of variable as follows:
T
T
Mu + q A F = 0
T
u q + q = 0
( q ,u ,t ) = 0
(q,t) = 0
(33)
Equations (33) are stabilized. Because the constraints have been differentiated once, Equation (33) has
an Index = 2.
Equations (33) are called the Stabilized Index Two representation of Equations (30). It has been proven
rigorously that Equation (33) and Equation (30) have the same solution when
rigorously enforced by the SI2 formulation in Adams/Solver (FORTRAN).
= 0. This condition is
It can also be shown that the Jacobian of Equation (33) does not become ill-conditioned as h moves closer
to 0. Furthermore, since Equation (33) has an Index of 2, the integrators can monitor integration error on
both u and q.
You can then, in principle, append the second time derivative of the constraints,
( q, u, u, t ) = 0 to
Equation (33) and introduce yet another set of variables to reduce the index of Equations (33) to one
(SI1). We have found this to be computationally very expensive and not much more accurate than the SI2
formulation.
There is, however, an alternative method for implementing the SI1 formulation that is promising.
Benefits and Limitations
The benefits and limitations of the S12 formulation are described in the following table:
168 Adams/Solver
accurately.
SI1 Formulation
The version of SI1 implemented in Adams/Solver does not use the second-time derivative of the
constraints, ( q,
Instead, it uses a change of variables to reduce the index. The Lagrange Multipliers
Equations (33) are replaced by new variables
and in
( q ,u ,t ) = 0
(q,t) = 0
(34)
INTEGRATOR 169
Adams/Solver (FORTRAN) Statements
This change of variables has effectively reduced the index of Equations (34) to 1. This is because we only
need to differentiate the velocity constraint equation once to explicitly calculate expressions for
and
.
Using the SI1 formulation, you can now monitor the integration error in
as the impulse associated with and
dt
dt
Therefore, in the SI1 formulation, the integration error can be monitored on all states (q, u,
(35)
, and ).
In this respect, the SI1 formulation is even more accurate than the SI2 formulation.
In practice, we have observed that, for most models, SI1 and SI2 give the same quality of answers.
However, system accelerations (that is ) tend to be more accurate with the SI1 formulation. The
performance of the SI1 formulation is also quite comparable to the SI2 formulation for many classes of
models. The SI1 formulation is more sensitive and finicky for models containing significant contact or
friction.
References
with Constaints. Journal of Computation and Applied Mathematics, 12 & 13, pp. 79-90, NorthHolland: 1985.
Orlandea, N.V. A study of the effects of the lower index methods on ADAMS sparse tableau
formulation for the computational dynamics of multi-body mechanical systems, IMechE Proc
Instn Mech Engrs V01 213 Part K: 1999 1-9
WSTIFF
170 Adams/Solver
Van Bokhoven, W.M.G. (1975, February). Linear Implicit Differentiation Formulas of Variable
ABAM
ABAM (Adams Bashforth-Adams Moulton) is a non-stiff integrator based on a code originally written
by Laurence F. Shampine and Marilyn K. Gordon.
ABAM is a multi-step, variable-order, variable-step integrator that has a maximum order of 12. ABAM
uses a PECE (Predict-Evaluate-Correct-Evaluate) scheme to integrate a set of ordinary differential
equations. ABAM may be better for simulating systems that undergo sudden changes (non-stiff systems)
or for those with active, high frequencies. The easiest way to know that your system is not numerically
stiff is to check that its high frequencies are underdamped. If they are, you can select ABAM. The
command LINEAR/EIGEN calculates the eigenvalues for any system at a given configuration.
ABAM uses coordinate partitioning, which is a method of eliminating constraint equations, such as the
ones induced by joints, from the equations of motion. This method reduces the entire system of
differential algebraic equations (DAEs) to a condensed set of ordinary differential equations (ODEs). It
does so by selecting the coordinates (degrees of freedom) that will change the most during the simulation
as the independent coordinates. Only these coordinates are integrated. All other dependent coordinates
in the system can be expressed as algebraic functions of the independent coordinates through the
constraints. After each successful integration step, the coordinate-partitioning algorithm computes the
dependent displacements, their time derivatives, and the accelerations and Lagrange multipliers
(constraint reactions). During this process, Adams/Solver (FORTRAN) holds the independent
coordinates constant and employs a Newton-Raphson iteration scheme to find the dependent coordinates.
After computing the dependent velocities from the independent values, Adams/Solver (FORTRAN) uses
the Newton-Raphson algorithm again to find the full set of accelerations and Lagrange multipliers
(constraint forces).
The displacement solution for the full set of dependent and independent coordinates provides the
appropriate matrix for Adams/Solver (FORTRAN) to explicitly solve for the velocities of the dependent
coordinates. When the integrator has a complete set of displacements, velocities, accelerations, and
Lagrange multipliers, it is ready to begin the next integration step.
GSTIFF, WSTIFF, and CONSTANT_BDF control only errors in displacements and user-defined
variables that are specified in differential equations. This solution method is guaranteed to satisfy the
equations of constraint and the equations of motion. It is not guaranteed to satisfy the first and second
time derivatives of the constraint equations. This solution method usually leads to acceptable accuracy
in the velocity, acceleration, and force results. However, you may find cases when the velocity,
acceleration, or force results are not acceptable, even when ERROR is set appropriately and the
displacement results are accurate. In these cases, you may improve accuracy by using the HMAX
argument, which lets you directly limit the size of the integration steps.
The SI2 formulation and ABAM control errors in all displacements, velocities, and user-defined
variables that are specified in differential equations. This solution method is guaranteed to satisfy the
equations of motion, and the equations of constraint and their first time derivative. ABAM also satisfies
INTEGRATOR 171
Adams/Solver (FORTRAN) Statements
the second time derivative of the equations of motion. This leads to increased accuracy in the velocity,
acceleration, and force results, but can slow down the simulation.
Caution:
The ABAM integrator does not support the VELOCITY and ACCELERATION arguments
on the MOTION statement.
References
For more information on the methods used in the ABAM integrator, see:
Shampine, L.F., Gordon, M.K. (1974). Computer Solutions of Ordinary Differential Equations.
y' = f ( x, y ), y ( x o ) = y o
consieder the steps to be taken to proceed the integration from
y n be the solution at x = x n
Now define:
V 1 = f ( x n, y n )
(36)
x = x n to x = x n + 1 . Let:
(37)
172 Adams/Solver
j1
V j = f x n + j h, y n + ji V i
i=1
yn + 1 = yn + h i Vi
(order 4)
i=1
6
y n + 1 = y n + y n + 1 i V i
(order 5)
i=1
trunc = y n + 1 y n + 1 = h C j V j
j=1
The coefficients j, j, j, j and C j are property of the method and are known as prion.
RKF45 is primarily designed to solve non-stiff and mildly stiff differential equations, where the
derivative evaluations are not expensive (time consuming). In the formulation used in Adams/Solver, the
derivative evaluation is expensive. Consequently, RKF45 is usually not very fast. In our testing, RKF45
is about five times slower than ABAM for most models. RKF45 is a good addition to the suite of
integrators in Adams, because, unlike all the others, it is a single-step integrator, and therefore,
fundamentally different.
RKF45 can only handle ordinary differential equations (ODE), and not DAE. Therefore, the DAE
corresponding to the model needs to be transformed to ODE.
Like ABAM, RKF45 uses coordinate partitioning to convert the DAE into ODE. For more information
about coordinate partitioning, see the third paragraph in the description of ABAM above.
References
The following sections include descriptions and work-arounds for common error conditions you might
encounter during a simulation. The sections include:
Integration Failures
INTEGRATOR 173
Adams/Solver (FORTRAN) Statements
Corrector Failures
Integration Restarts
Singular Matrices and Symbolic Refactorization
Integration Failures
An integration failure is the condition when the integrator calculates a solution, but then rejects it because
it does not meet the accuracy requirements you specified. Because all integrators attempt to take the
largest time step possible, failure is a fairly routine occurrence and is not cause for concern. Integrators
can automatically decrease the step size and/or integrator order and repeat the step. Integration failures
in multi-step methods are caused when the predictor and corrector give different answers. Such a
situation can occur often when a force is suddenly turned on or off, thus, causing a discontinuity in the
solution. For this reason, past values are not a good indicator of current values. The following tips can
help you avoid integration failure:
When modeling, be sure that all motion inputs, user-defined forces, and user-written differential
equations are both continuous and differentiable. The smoother a function is, the easier it is to
integrate. Always use a STEP or STEP5 function to switch a signal on or off, instead of using IF
logic.
Remember that cubic SPLINEs can only guarantee first-order differentiability. Inputting a
can take. HMAX enables the integrator to reach higher orders and maintain them consistently.
Be careful when using non-differentiable intrinsic functions, such as IF, MIN, MAX, SIGN,
MOD, and DIM. These functions can give discontinuous answers and can cause integrator
problems. The integration failure diagnostic identifies the variable and its parent modeling
element with the most error in it. Examine the entities that connect to the parent modeling
element to see if you can identify the cause of the failure.
Corrector Failures
A corrector failure occurs when the Newton-Raphson iterations in the correction phase do not converge
to a solution. Corrector failure occurs if the predictor cannot provide a reasonable initial guess and the
equations themselves are not smooth, as the Newton-Raphson algorithm assumes. A corrector failure is
a fairly severe event that you should avoid by changing your model. Some tips to help avoid corrector
failure are:
As with preventing integrator failures, be sure that all motion inputs, user-defined forces, user-
written differential equations, and user-defined algebraic variables are both continuous and
differentiable. The smoother a function is, the easier it is to solve for it. Use a STEP or STEP5
function to switch a signal on or off instead of using IF logic.
Use the ERROR keyword to loosen the integration error. Loosening the value for ERROR also
174 Adams/Solver
Use the new corrector. Set the environment variable MDI_ADAMS_NEWCOR to TRUE and re-
tolerance.
Here are some diagnostic techniques for identifying the cause of some failures:
Examine the EPRINT output from DEBUG to identify the modeling entities that are having the
for a PART, POINT_MASS, or FLEX_BODY, try to identify the entities that may be
applying anomalous forces on the body.
Look at the accelerations of the body. A large acceleration in a certain direction is always
caused by a large force in that direction. Try to identify the modeling element that is causing
the large acceleration, examine how it is defined, and try to understand why it is applying a
large force.
If the modeling element is a CONTACT, review the stiffness, damping, and frictional
properties of the contact. Reducing stiffness and damping helps. Similarly, increasing stiction
and dynamic friction transition velocities can help the integrator.
If the modeling element is a FRICTION entity, increasing the stiction and dynamic friction
transition velocities usually helps. Evaluate the effect of reducing the friction coefficients and
the pre-load.
If the modeling element is a DIFF or GSE, make sure that the derivatives you are defining
have reasonable values. Large derivatives cause problems. Make sure that the constitutive
equations are smooth (differentiable) and that they do not have any kinks.
If the modeling element is a redundant constraint, this implies that Adams/Solver is having
difficulty satisfying the constraint. The most likely cause for such a failure is an inconsistently
defined or ill-behaved model. Eliminate the inconsistency.
If the modeling element is a constraint reaction, try to identify the applied force or torque that
An integration restart is when the integrator fails to take a new step successfully. Adams/Solver
(FORTRAN) calculates a new and consistent set of initial conditions at the point of failure and the
solution progresses with this new set of initial conditions. A restart occurs if the integrator encounters
several consecutive integration failures and/or corrector failures while attempting a new step. Integration
INTEGRATOR 175
Adams/Solver (FORTRAN) Statements
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
integrator or corrector error. Identify that element and see why it may be causing problems.
Smoothen its definition if there is a function expression or user subroutine associated with it. For
more information on how to diagnose modeling problems, see Corrector Failures.
Use the CONSTANT_BDF integrator, and see if the problem goes away. Step size change can
destabilize correctors that assume predominantly fixed step sizes, by introducing a small error in
the solution when the step size changes.
Singular Matrices and Symbolic Refactorization
A singular matrix condition occurs when the Jacobian matrix is not invertible. Recall that the corrector
needs to invert the Jacobian matrix during its iterations to solve a set of linearized algebraic equations.
(See Correction). A scalar analogy to a singular matrix is a divide-by-zero situation. Adams/Solver
(FORTRAN) does not actually invert the matrix, but calculates the matrixes Lower and Upper triangular
factors (LU factors). This method of computation is very efficient and is equivalent to an inversion.
Given a Jacobian matrix, Adams/Solver (FORTRAN) calculates and stores the LU factors in a symbolic
form. In other words, Adams/Solver (FORTRAN) explicitly calculates the LU factors as a function of the
values in the Jacobian matrix. Adams/Solver (FORTRAN) also assumes that the pivots are never zero.
(Pivots are chosen during the Gaussian elimination and are used to factorize the matrix.) Because the
equations being solved are nonlinear, it is likely that a set of pivots chosen earlier may not be optimal.
Some of the pivots may become small or even zero. This event is known as the singular matrix condition.
When Adams/Solver (FORTRAN) encounters this condition, it recalculates the symbolic LU factors for
the Jacobian matrix using the current values of the state variables. This process is known as symbolic
refactorization.
Occasional occurrences with singular matrixes and symbolic refactorization are normal and are no cause
for alarm. However, if these events occur frequently, you should examine your model. The typical causes
for singular matrices are:
A mass or inertia component is not specified.
The system has reached a locked configuration, that is, it can no longer move without violating
176 Adams/Solver
Large force suddenly turns on. The large force is usually associated with a high stiffness. A large
notice this.
The Index-3 Jacobian matrix (see Equation 6) contains some terms that are inversely proportional to the
step size being taken. As the step size shrinks, these terms grow large. In fact, they grow so large that
they eclipse all other entries in the matrix. Computers typically have difficulty dealing with matrices that
have entries spanning a large range. The smaller numbers consequently get lost in round-off error, and,
thus, cause singular or ill-conditioned matrices to occur. The root cause for these problems is that the step
size is very small. The solution is to understand why the step size is so small, and modify the model
accordingly. Discontinuities are prime causes for problems related to small steps sizes. Eliminating the
discontinuities causes the integrator to take larger steps, and, therefore, avoid fatal singular matrix
condition. Using the SI2 formulation can also help solve this problem.
Choosing and Integration Error
The integration ERROR is a key parameter that you need to specify for a simulation. The following are
three options for calculating a reasonable value for ERROR:
For I3 formulation with GSTIFF and WSTIFF:
ERROR = VEPS *(6*Nb + 3*Np + Nu + 2*Nm)
For ABAM:
ERROR= K * VEPS *(2*Ndof+Nu)
where:
VEPS is the desired error per variable per integration step.
Nb is the number of rigid bodies in the model (excluding GROUND).
Np is the number of point masses in the system.
Nu is the number of user-defined differential equations in the system (DIFFs+LSEs+GSEs).
Nm is the total number of modal coordinates in the system:
K =10 (for smooth problems).
K =100 (for impact and friction problems).
Ndof = total number of mechanical degrees of freedom.
All integrators require that you input a value, referred to as ERROR in this guide, that specifies the degree
of accuracy you want to achieve in a simulation. ERROR is the maximum error allowed per integration
step for the entire system. This can be confusing in Adams/Solver (FORTRAN) because some of the
INTEGRATOR 177
Adams/Solver (FORTRAN) Statements
ERROR states are displacements, some are velocities, and others may be user-defined states (for
example, pressure, and temperature).
In Adams/Solver (FORTRAN), integration ERROR is the difference between the exact solution f(t) and
the approximate solution p(t) being calculated. The difference, f(t)-p(t), is the truncation error. The higher
the integrator order, the smaller the truncation error.
For displacement variables, the truncation error has units of length. For velocities, the truncation error
has units of velocities. For example, if you are working in millimeters, your maximum error tolerance
would be smaller than 1 micron. Then, for each variable, you would have an error of 0.001 mm.
You find the error per step by estimating the total number of integration steps, and then dividing the error
per variable by the estimated number. Thus, if you estimate that you need 100 integration steps, the error
per step, VEPS, is 0.00001 mm. This is always a conservative calculation (sometimes too conservative)
because errors tend to be random and typically cancel each other out. The calculation shown earlier
assumes the worst case scenario, where the errors are always additive. You should use the information
shown here as a guide, not as a rule, for setting ERROR.
Velocities must be treated in the same way as displacements. However, keep in mind that the errors in the
derivatives are higher, and, if you impose an error on the velocities that are identical to the errors on the
displacements, you force a larger number of iterations per step to occur, which increases the simulation
time. In general, if an error-control exists on velocities, such as in SI2 and ABAM, then the errors
computed for the displacements can be increased by a factor of 10 and can also be applied for velocities.
Modal coordinates have small values, and, therefore, to be able to accurately capture their effects, you
may need to tighten the ERROR parameter. Typically, when the rigid body displacements and velocities
are accurate, then the modal coordinates and velocities are also fairly accurate.
Tip:
Jacobian matrix can improve convergence rates. However, this can also increase
the computation time.
For kinematic (zero-DOF) systems, a kinematic analysis is usually faster and less
178 Adams/Solver
Caution:
Examples
INTEGRATOR/SI2, GSTIFF, ERROR=1.0E-4, HINIT=1.0E-6
This integrator statement specifies that dynamic simulations be run using the SI2 equation formulation
combined with the GSTIFF integrator. This solution has an error limit of 1.0E-4. The integrator is to take
an initial step of 1.0E-6.
See other Analysis parameters available.
JOINT 179
Adams/Solver (FORTRAN) Statements
JOINT
The JOINT statement describes a physically recognizable combination of constraints that are used to
connect bodies (rigid and flexible) together. Examples of joints include constant-velocity, cylindrical,
fixed, Hooke, planar, rack-and-pinion, revolute, screw, spherical, translational, and universal joints.
Format
180 Adams/Solver
Arguments
CONVEL
CYLINDRICAL
JOINT 181
Adams/Solver (FORTRAN) Statements
Cylindrical Joint
FIXED
HOOKE
182 Adams/Solver
Hooke Joint
I=id, J=id
Specifies the identifier of one fixed marker in each part the joint connects.
Adams/Solver (FORTRAN) connects one part at the I marker to the other
at the J marker.
IC=r1,r2
JOINT 183
Adams/Solver (FORTRAN) Statements
ICROT=r1,r2
ICTRAN=r1,r2
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 z-axis of the I marker, a positive pitch
diameter moves the rack in the positive direction along the z-axis of the J
marker and a negative pitch diameter moves the rack in the negative
direction along the z-axis of the J marker.
184 Adams/Solver
PITCH=r
PLANAR
JOINT 185
Adams/Solver (FORTRAN) Statements
RACKPIN
REVOLUTE
186 Adams/Solver
Revolute Joint
SCREW
JOINT 187
Adams/Solver (FORTRAN) Statements
SPHERICAL
TRANSLATIONAL
188 Adams/Solver
Translational Joint
UNIVERSAL
Indicates a two-degree-of-freedom joint that rotates about two axes: the zaxis of the I marker and the z-axis of the J marker (see the figure below).
For the UNIVERSAL joint, Adams/Solver (FORTRAN) superimposes the
origins of the I and J markers and keeps their z-axes perpendicular, so they
outline the crosspiece of the joint. The origins of the I and J markers are at
the center of the cross. The UNIVERSAL joint functions the same as the
HOOKE joint, but uses different marker orientations.
Universal Joint
Extended Definition
The JOINT statement describes a physically recognizable combination of constraints such as constantvelocity, cylindrical, fixed, Hooke, planar, rack-and-pinion, revolute, screw joints, spherical,
JOINT 189
Adams/Solver (FORTRAN) Statements
translational, and universal (see the figure on the Summary of Joints and the table on joint constraints that
follows).
Summary of Joints
Joint Constraints
Removes
Translational DOF:
Removes
Rotational DOF:
Removes Total
Number DOF:
Constant Velocity
Cylindrical
190 Adams/Solver
Removes
Translational DOF:
Removes
Rotational DOF:
Removes Total
Number DOF:
Fixed
Hooke
Planar
Rack-and-pinion
0.5*
0.5*
Revolute
Screw
0.5*
0.5*
Spherical
Translational
Universal
* The rack-and-pinion and screw joints are shown as half translational and half rotational because they
relate a translational motion to a rotational motion. They each create one constraint, but the constraint is
neither purely translational nor purely rotational.
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
pinion joint. In addition, the GEAR statement is more accurate. The current RACKPIN joint
applies a parasitic rotational force to the rack part. For some models the parasitic rotational force
could cause inaccurate results. Learn more information about the GEAR statement.
The UNIVERSAL and HOOKE joints function identically. One may be more convenient to
define than the other, however, depending on the data you have available. If the joint is initially
straight, for instance, the HOOKE joint may be defined by two identical markers.
Functionally, the constant-velocity joint is similar to the UNIVERSAL and HOOKE joints.
Connecting two shafts with a constant-velocity joint ensures that the shafts always spin at the
same rate, however, unlike the UNIVERSAL and HOOKE joints which cause some fluctuation
as the joint bends.
JOINT 191
Adams/Solver (FORTRAN) Statements
Caution:
The two markers that define a joint must be in two different parts.
Be careful when defining UNIVERSAL and HOOKE joints. In an actual universal
joint, if the spin axis of either part comes into alignment with either rotational axis
of the joint, the joint can no longer transmit rotational motion. The figure below
shows a universal joint in this singular position.
In Adams/Solver (FORTRAN) the singular position allows the universal joint to
spin freely and usually causes simulation failure.
Universal Joint in the Singular Position
Be careful when defining CONVEL joints. Whenever the z-axes of the I and J markers in a
CONVEL joint become colinear and codirected, the joint is in a singular position. The behavior
of the CONVEL joint in the singular position is unpredictable and may be incorrect.
The screw joint relates the rotational motion of the I marker to the translational motion of the I
marker and measures both motions with respect to the J marker. However, the screw joint does
not model the backlash or slop that may occur in actual screw joints.
For both the rack-and-pinion and screw joints, Adams/Solver (FORTRAN) positions the I and
the J markers at the nearest pitch-multiple position that satisfies the constraint. Examples of pitch
multiples of a joint with a pitch value of 2.5 include -5.0, -2.5, 0.0, 2.5, 5.0, etc. Therefore, you
should be careful to ensure that the part, marker, and joint information that contributes to the
initial positioning of the I marker with respect to the J marker correctly describes the initial
position of the I marker.
If the initial conditions are inconsistent with other conditions in the system, Adams/Solver
(FORTRAN) varies the part initial positions through an iterative process to correct the
inconsistencies and then begins the simulation.
192 Adams/Solver
Use caution when using the initial conditions arguments (IC, ICTRAN, ICROT) in conjunction
with a MOTION statement on the same joint. If the MOTION statement and the initial
conditions argument(s) specify motion for the same degree of freedom, Adams/Solver
(FORTRAN) uses the MOTION statement, ignores the initial conditions argument, and issues a
warning message.
If the initial rotational displacement of a revolute or cylindrical joint (as specified by the IC or
the ICROT argument on the JOINT statement or by a MOTION statement) varies by anywhere
from 5 to 60 degrees from the initial configuration of the joint as indicated by the input positions
of the two parts constituting the joint, Adams/Solver (FORTRAN) issues a warning message and
continues execution. If the variation is greater than 60 degrees, Adams/Solver (FORTRAN)
issues an error message and stops execution.
The initial conditions arguments impose constraints that are active only during initial conditions
analysis. Adams/Solver (FORTRAN) does not impose these initial conditions during subsequent
analyses.
For a kinematic analysis, the initial conditions are redundant. Do not use initial condition
arguments on the JOINT statements for systems with zero degrees of freedom.
Adams/Solver (FORTRAN) checks whether axes that are constrained to be parallel or
perpendicular are actually close to parallel or perpendicular as input in the dataset. If you input
joint markers such that constrained axes are misaligned by more than 5 degrees, Adams/Solver
(FORTRAN) issues a warning but continues the simulation. If you misalign constrained axes by
more than 60 degrees, Adams/Solver (FORTRAN) issues an error and stops the simulation. You
can input unconstrained axes in any position. In a REVOLUTE joint, for example,
Adams/Solver (FORTRAN) issues a warning if the angle between the z-axes of the I and J
markers is greater than 5 degrees, and an error if the angle is greater than 60 degrees. The x-axes,
however, may be at any angle.
Examples
JOINT/0403, UNIVERSAL, I=0406, J=0306
This JOINT statement indicates that Adams/Solver (FORTRAN) is to connect one part at Marker 0406
to another part at Marker 0306. Because the statement includes the argument UNIVERSAL,
Adams/Solver (FORTRAN) uses a universal joint to make the connection.
See other Constraints available.
JPRIM 193
Adams/Solver (FORTRAN) Statements
JPRIM
The JPRIM statement describes a joint primitive, which constrains one, two, or three degrees of either
translational or rotational freedom. JPRIMs do not usually have a physical analogue and are
predominantly useful in enforcing standard geometric constraints.
Format
Arguments
ATPOINT
I=id,J=id
Specifies the identifier of one fixed marker in each part the primitive connects.
Adams/Solver (FORTRAN) connects one part at the I marker to another at the J
marker.
194 Adams/Solver
INLINE
INPLANE
JPRIM 195
Adams/Solver (FORTRAN) Statements
ORIENTATION
196 Adams/Solver
JPRIM 197
Adams/Solver (FORTRAN) 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.
Summary of Joint Primitive
198 Adams/Solver
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
Inline
Inplane
Orientation
Parallel Axes
Perpendicular
The reaction force on the part containing the I marker always acts at the I marker. The reaction force on
the part containing the J marker acts at the instantaneous location of the I marker; that is, the point of
application can vary with time if the I and J markers translate with respect to one another. The reaction
force on the part containing the J marker is always equal and opposite to the reaction force on the part
containing the I marker.
Joint primitives can be combined to define a complex constraint. In fact, they can be used to create any
of the recognizable joints (except for RACKPIN and SCREW). However, motions cannot be applied on
joint primitives as they can be on recognizable joints. For more information on recognizable joints, see
JOINT.
Tip:
Caution:
The two markers that define a joint primitive must be in two different parts.
Examples
JPRIM/0101, INLINE, I=0140, J=0240
This JPRIM statement indicates that Adams/Solver (FORTRAN) is to use an inline joint primitive to
connect one part to another. This connects the first part at Marker 0140 to the second at Marker 0240.
See other Constraints available.
KINEMATICS 199
Adams/Solver (FORTRAN) Statements
KINEMATICS
The KINEMATICS statement specifies error tolerances and other parameters for kinematic analyses.
Format
Arguments
AERROR
ALIMIT=r
AMAXIT=i
200 Adams/Solver
APATTERN=c1[
:...:c10]
Specifies as many as ten character strings that together establish the pattern for
evaluating the Jacobian matrix during the modified Newton-Raphson solution for
the accelerations. For each iteration, T or TRUE indicates that Adams/Solver
(FORTRAN) is to evaluate the Jacobian, and F or FALSE indicates that
Adams/Solver (FORTRAN) is not to evaluate the Jacobian. Thus, cj determines
whether or not Adams/Solver is to evaluate the Jacobian at the jth iteration. If
necessary, Adams/Solver (FORTRAN) repeats the pattern of evaluations until it
reaches the maximum number of iterations (AMAXIT). The number of Ts or
TRUEs and Fs or FALSEs together must be at least one and no more than 10.
Default: T:T:T:T:T:T:T:T:T:T, that is, to evaluating the Jacobian at every iteration
(that is, the unmodified Newton-Raphson algorithm)
ERROR=r
HMAX=r
Defines the maximum time step that the kinematics solver is allowed to take.
Default: The output step size.
MAXIT=i
PATTERN=c1[:.. Specifies as many as ten character strings that together establish the pattern for
.:c10]
evaluating the Jacobian matrix during the modified Newton-Raphson solution for
the displacements. For each iteration, T or TRUE indicates that Adams/Solver
(FORTRAN) is to evaluate the Jacobian and F or FALSE indicates that
Adams/Solver (FORTRAN) is not to evaluate the Jacobian. Thus cj determines
whether or not Adams/Solver is to evaluate the Jacobian at the jth iteration. If
necessary, Adams/Solver (FORTRAN) repeats the pattern of evaluations until it
reaches the maximum number of iterations (MAXIT). The number of 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, that is, to evaluating the Jacobian at every iteration
(that is., the unmodified Newton-Raphson algorithm)
TLIMIT=r
KINEMATICS 201
Adams/Solver (FORTRAN) Statements
Extended Definition
The KINEMATICS statement specifies error tolerances and other parameters for kinematic analyses.
This statement would only be used when you are requesting a kinematic analysis and you want to change
one or more of the tolerances and parameters from the default values.
Use the SIMULATE command to request a series of kinematic analyses over time. A kinematic analysis
is only appropriate when a system has zero degrees of freedom. A kinematic analysis solves for the
displacements, velocities, accelerations, and forces (if any) at a series of points in time. To find the
displacements, Adams/Solver (FORTRAN) uses Newton-Raphson iteration to solve a nonlinear set of
algebraic equations.
After finding the displacements, Adams/Solver (FORTRAN) solves a system of linear equations to find
the velocities, then solves another set of nonlinear equations to find accelerations and forces.
Adams/Solver (FORTRAN) repeats this procedure at successively later times until it obtains results over
the period of time specified in a SIMULATE command.
If you issue neither a KINEMATICS command nor statement in an Adams/Solver (FORTRAN) session,
Adams/Solver (FORTRAN) uses the default values for AERROR, ALIMIT, AMAXIT, APATTERN,
ERROR, MAXIT, PATTERN, and TLIMIT when performing a kinematic analysis.
Tip:
matrix may decrease the computation time, decreasing the cost and improving the
response time. However, infrequent evaluations could also be more expensive
since the modified Newton-Raphson algorithm might require more iterations due
to the slower convergence rates.
Use the ALIMIT and TLIMIT arguments to limit the increments in the
displacement variables and thus the size of the position change on successive
iterations. This tends to prevent Adams/Solver (FORTRAN) from moving the
mechanism to an undesirable configuration.
Examples
KINEMATICS/TLIMIT=10, MAXIT=30
This KINEMATICS statement assigns new values to TLIMIT and MAXIT for a kinematic analysis.
Thus, the maximum translational increment allowed in each iteration of a kinematic analysis is 10 length
units and the number of iterations of the algorithm for the solution of the nonlinear equations is limited
to 30.
See other Analysis parameters available.
202 Adams/Solver
LIST/NOLIST
The LIST and NOLIST statements allow and suppress writing of the input data to the tabular output file.
Combinations of LIST and NOLIST can be used to output any part of the input dataset. The portion of
the dataset following the LIST statement up to the NOLIST statement or through the end of the file is
copied to the tabular output file. If you include neither a LIST statement nor a NOLIST statement in the
dataset, Adams/Solver (FORTRAN) assumes that you do not want to record any portion of the input
dataset in the tabular output file.
Format
LIST
or
NOLIST
See other Output available.
LSE 203
Adams/Solver (FORTRAN) Statements
LSE
The LSE (Linear State Equation) statement defines the following linear system:
x = A x + Bu
y = C x + Du
of first-order, explicit differential equations and algebraic equations in classical state-space form. The
state variables, x, the inputs, u, and the outputs, y, are specified by ARRAY statements. Use MATRIX
statements to define the coefficient matrices A, B, C, and D.
Format
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.
204 Adams/Solver
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 quasi-static
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.
Extended Definition
The LSE (Linear State Equation) statement is used, along with associated ARRAY and MATRIX
statements, to define a system of constant coefficient, explicit, differential and algebraic equations in
state-space form. The system of equations describes a model for a linear, time-invariant dynamic system.
The LSE, ARRAY, and MATRIX statements provide the means for importing controllers developed
LSE 205
Adams/Solver (FORTRAN) Statements
manually or with other software packages. It can also be used, however, to define an arbitrary set of
coupled, constant-coefficient differential and algebraic linear equations in the form
x A B
y C D
x
u
The LSE statement provides a very general capability for defining a linear
element. The Adams solvers, however, have been developed and refined for sparse
systems of equations that arise from the modeling of mechanical systems. With the
LSE statement, you can create very dense sets of equations. If these equations
form a large portion of your completed model, Adams/Solver (FORTRAN) may
perform more slowly than expected.
Note that, if the algebraic equations defined by the LSE statement have no solution
or multiple solutions (this is possible because of the general nature of the input
ARRAY), Adams/Solver (FORTRAN) most likely fails to converge or possibly
converge to an unexpected answer. To avoid this possibility, you should not
reference the X (state) or Y (output) ARRAY statements in the VARIABLE
statements listed in the U (input) array.
During a static analysis, Adams/Solver (FORTRAN) finds equilibrium values for
206 Adams/Solver
retained as the static equilibrium values. Thus, the final equilibrium values are the
same as the user-specified initial conditions. Note that this does not guarantee that
the time derivatives of the user-defined variable are zero after static analysis.
Examples
LSE/10, X=10, A=10, U=11, B=11, IC=12
ARRAY/10, X
ARRAY/11, U, VARIABLE=11
ARRAY/12, IC, NUMBER=0.0,0.0
MATRIX/10, FULL=RORDER, ROW=2, COL=2,
, VALUE=0.0,1.0,-986.96,-6.2832
MATRIX/11, FULL=RORDER, ROW=2, COL=1, VALUE=0.0,1.0
VARIABLE/11, FUNCTION=5.0*SIN(PI*TIME**2)
x =
0
1
x + 0 5 sin ( t 2 )
986.96 6.2832
1
x(0) = 0
0
The LSE statement may be most useful for adding feedback control systems to an Adams/Solver
(FORTRAN) model. The A, B, C and D matrices can be derived manually or imported directly from a
control system design program such as MATRIXx or MATLAB. Normally, the mechanical portion of the
model includes some kind of actuator that depends on one or more of the LSE statement outputs or states.
LSE statements can also be conveniently used in many cases to replace systems of coupled DIFF and
VARIABLE statements (for nonlinear equations, the GSE statement should be used). Examples of
possible dynamical system uses include unsteady aerodynamics and electrodynamics.
You can use the current values of LSE states and outputs in both function expressions and user-written
subroutines using the associated ARRAY facilities (see the ARYVAL function and the subroutines
SYSARY and SYSFNC). That is, instead of Adams/Solver (FORTRAN) functions and FORTRAN
callable subroutines dedicated expressly to the LSE statement, the system states and outputs are accessed
by offset referencing through the appropriate ARRAY routines. This allows for consistent access to
system states and outputs for all three system modeling elements, the LSE, GSE, and TFSISO statements.
LSE 207
Adams/Solver (FORTRAN) Statements
208 Adams/Solver
MARKER
The MARKER statement defines a geometric point in space and a set of three mutually perpendicular
coordinate axes emanating from that point.
Format
MARKER 209
Adams/Solver (FORTRAN) Statements
Arguments
FLOATING
Defines the marker as one that moves relative to the part with which it is
associated. Without this argument, a marker is considered spatially fixed
relative to the part with which it is associated. A floating marker must be used
with VTORQUE, VFORCE, GFORCE, CVCV, and PTCV, and cannot exist
without being referenced by one of these statements.
FLEX_BODY=id
Specifies the identifier of the flexible body to which the marker belongs. A
FLEX_BODY argument is not required in the MARKER statement if the
MARKER statement follows the associated FLEX_BODY statement with no
intervening FLEX_BODY, PART, or POINT_MASS statement.
Default: ID of preceding FLEX_BODY, PART, or POINT_MASS
Range: Flexible body IDs
Specifies the identifier of the part to which the marker belongs. A PART
argument is not required in the MARKER statement if the MARKER statement
follows the associated PART statement with no intervening FLEX_BODY,
PART, or POINT_MASS statements.
Default: ID of preceeding FLEX_BODY, PART, or POINT_MASS
Range: Part IDs
POINT_MASS=id
Specifies the identifier of the point mass to which the marker belongs. A
POINT_MASS argument is not required in the MARKER statement if the
MARKER statement follows the associated POINT_MASS statement with no
intervening FLEX_BODY, PART, or POINT_MASS statement.
Default: ID of preceding FLEX_BODY, PART or POINT_MASS
Range: Point mass IDs
210 Adams/Solver
QP=x,y,z
Defines the x-, y-, and z-coordinates of the origin of the MARKER with respect
to the element on which it lies. The coordinates are specified in the body
coordinate system (BCS).
Range: Real numbers for x, y, and z
REULER=a,b,c
Specifies the Euler angle 3-1-3 sequence rotation defining the spatial orientation
of the marker axes relative to the element on which it lies. The orientation is
relative to the body coordinate system (BCS).
The a, b, and c, values represent the set of body-fixed 3-1-3 Euler angles
expressed in radians. These angles can be interpreted by following the steps
below.
To orient a marker:
1. Align the marker axes identical to the axes of the parent coordinate
system to which the orientation will be relative.
2. Perform a right-handed rotation of the marker x- and y-axes by a radians
about the positive z-axis of the marker.
3. Rotate the marker y- and z-axes by b radians about the current marker
positive x-axis.
4. Perform a right-handed rotation of the x- and y-axes of the marker by c
radians about the current z-axis of the marker.
To enter the Euler angles in degrees instead of radians, add a D after each value.
Range: Real numbers for a, b, and c
USEXP
Causes the marker to be oriented with the x-axis lying on XP, and ZP lying in
the positive x-z plane, when using the x-point-z-point method of orientation.
This is useful for orienting markers used in BEAM statements. Examples of
using the ZP, XP and USEXP.
XP=x,y,z
By default, defines the coordinates of any point in the positive x-z plane of the
marker, but not on the z-axis of the marker. A point on the positive x-axis may
be the most convenient. When used with USEXP, XP defines the BCS
coordinates of any point on the positive x-axis of the marker. Examples of using
the ZP, XP and USEXP.
ZP=x,y,z
By default, defines the coordinates of any point on the positive z-axis of the
marker. When used with USEXP, ZP defines the BCS coordinates of any point
in the positive x-z plane of the marker, but not on the x-axis of the marker.
Examples of using the ZP, XP and USEXP.
MARKER 211
Adams/Solver (FORTRAN) Statements
Extended Definition
The marker defines a geometric point in space and a set of three mutually perpendicular coordinate axes
emanating from the point. Markers are always associated with specific parts of a mechanism and can
either be fixed on the part or may float relative to the part. A MARKER statement identifies the location
and orientation of a marker with respect to a BCS. Markers are the basic building blocks used to specify
points of: application for forces, connectivity for constraints, attachment for graphic elements, or interest
in the model. For more information on BCS, see Coordinate Systems and Local Versus Global Geometric
Data.
In the online help, a reference to a marker without a type usually refers to a fixed marker. A floating
marker normally has the term floating associated with it in some way.
Requests for information pertaining to fixed and floating markers are easy to write (see REQUEST).
However, only information on fixed markers can be used in FUNCTION arguments that affect how the
model behaves. You may reference the position of a floating marker in a REQUEST statement or a
REQSUB evaluation subroutine, for instance, but not in an SFORCE statement or a SFOSUB evaluation
subroutine
Tip:
position and orientation. For every floating marker, you specify only the part to
which it belongs.
Select one of the following three methods to define the position and orientation of
the marker:
To select the Euler angles method, add QP and/or REULER.
To select the x-point-z-point method using the ZP point to define a point on the
z-axis, add QP, ZP, and/or XP. It is often unnecessary to define XP.
To select the x-point-z-point method using the XP point to define a point on the
x-axis, add QP, XP, and/or ZP, as well as USEXP. It is often unnecessary to
define ZP.
Caution:
212 Adams/Solver
Note:
In general, locate and orient a marker with respect to its parent BCS. If the marker is on the
ground part or is on a part whose BCS is coincident with the ground coordinate system
(GCS) at time zero, the marker can be positioned and oriented with respect to the GCS.
Examples
MARKER/0406, ZP=0,1,0, XP=0,0,1, PART=4
This MARKER statement assigns Marker 0406 to Part 4 and defines the position and orientation of 0406
with respect to the BCS of Part 4 using the x-point-z-point method. QP defaults to QP=0,0,0, so
Adams/Solver (FORTRAN) positions Marker 0406 at the origin of the BCS. The ZP values indicate that
the marker z-axis is parallel to the BCS y-axis and that the XP point lies on the BCS z-axis.
MARKER/0408, QP=2,0,0, REULER=90D,90D,0, PART=4
This MARKER statement, like the previous one, describes a marker on Part 4. Adams/Solver
(FORTRAN) places the origin of Marker 0408 at coordinates 2,0,0 with respect to the BCS. To orient the
marker, Adams/Solver (FORTRAN) aligns it with its BCS and then rotates the marker 90 degrees about
its z-axis, 90 degrees about its new x-axis, and 0 degrees about its new z-axis.
MARKER/1002, FLOATING, PART=2
This MARKER statement defines a floating marker named Marker 1002 on Part 2. A floating marker
requires the use of one of the following: VTORQUE, VFORCE, GFORCE, PTCV, or CVCV. The
statement referencing the floating marker determines the instantaneous location and orientation of this
marker.
MARKER/8007, XP=0,0,1, ZP=0.1,0,0.1, USEXP, PART=8
This MARKER statement defines Marker 8007 on Part 8. QP defaults to QP=0,0,0, so Adams/Solver
(FORTRAN) positions Marker 8007 at the origin of the BCS. With USEXP active, the XP values indicate
that the marker x-axis passes through point 0,0,1, and the ZP values indicate the z-x plane passes through
BCS coordinates 0.1,0.0,0.1.
Applications
requires two markers, one in each part that the joint or the joint primitive connects (see the
JOINT and JPRIM statements).
Denote force direction and action and reaction points (see the statements: BEAM, BUSHING,
FIELD, SFORCE, and SPRINGDAMPER).
Specify points for request and graphics output (see the REQUEST and GRAPHICS statements).
MARKER 213
Adams/Solver (FORTRAN) Statements
Provide coordinate system(s) other than the ground coordinate system(s) for resolving the
components of vector quantities such as velocities, accelerations, and forces (see the REQUEST
statement).
Use floating markers to:
Denote reaction points that can change position on a part (see the statements: VFORCE,
VTORQUE, and GFORCE).
Denote contact points in CVCV and PTCV constraints (see the CVCV and PTCV statements).
214 Adams/Solver
MATRIX
The MATRIX statement provides the means for inputting a two-dimensional array of numerical values.
It is used primarily to support other statements such as CURVE, LSE, and NFORCE. The entries in the
matrix can be assigned values with the arguments on the MATRIX statement itself or the MATRIX
statement can specify the name of another data file from which the code reads the values. The data file
can be in one of two formats: the Adams/Solver (FORTRAN) format or the standard FSAVE format
supported by the MATRIXx software package.
Format
MATRIX 215
Adams/Solver (FORTRAN) Statements
Arguments
COLUMNS=i
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 (FORTRAN). There is no limit on the size of an array read from
a file.
The first record in the file contains an 80-character header of which the first
seven or eight characters are meaningful.
If the first record begins with the characters ADAMSMAT or
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
216 Adams/Solver
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
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
SPARSE
Specifies that a SPARSE input format is used where the row position, column
position, and value are given, usually only for nonzero entry values.
VALUES=r1,...,rn
If you select the FULL option, the VALUES argument specifies all of the m
times n entries in the matrix. The sequence depends on the value of the FULL
argument. If RORDER is specified, the values are listed row-by-row. If
CORDER is specified, the values are listed column-by-column.
If you select the SPARSE option, the VALUES argument specifies only the
entries that may be nonzero. That is, Adams/Solver (FORTRAN) assumes all
entries in the M x N array not assigned values by the I, J, and VALUES
arguments are equal to zero. The kth entry in VALUES is assigned to the row
identified by the kth entry in I and to the column identified by the kth entry in J
for k=1,...,n.
Each pair of I and J entries must specify a unique entry in the array; there can
be no duplicate entries for the same position in the matrix.
Extended Definition
The MATRIX statement defines a general M x N array that can be a rectangular or square twodimensional matrix or even a row or column matrix. You can enter the data in a FULL or SPARSE format.
When the matrix has approximately one-third or more of its entries nonzero, the FULL format is more
efficient. When the matrix is mostly empty and the labor associated with entering each nonzero entrys
row position, column position, and value is less than entering all of the values, you should use the
SPARSE format. In cases where the matrix to be input is very large, you should use the FILE and NAME
arguments to specify an external file containing the matrix.
You can enter data for an M x N matrix into Adams/Solver (FORTRAN) from a file specified by the FILE
argument on the MATRIX statement. The contents of the file can be in one of four formats:
ADAMSMAT, ADAMSMAT2, or either the standard FSAVE format or the optional MATSAVE format.
MATRIX 217
Adams/Solver (FORTRAN) Statements
The first 7,8, or 9 characters in the header of the file must be MATRIXx, MATSAVE, ADAMSMAT, or
ADAMSMAT2 to identify the format of the data. Although the remaining content of an ADAMSMAT
or ADAMSMAT2 file (as well as all of an Adams/Solver (FORTRAN) dataset) is case insensitive, the
identifying labels at the beginning of the first record in a matrix file must appear exactly as shown.
A file in the in the ADAMSMAT or ADAMSMAT2 format consists of variable-length records that must
be laid out as described in the following paragraphs. The example at the end, Table 1, and Table 2
illustrate the details. The FSAVE and MATSAVE formats are described in MATRIXx literature.
To select the option, the header or first record must begin with the characters ADAMSMAT or
ADAMSMAT2. The remainder of the first record can be used as a title to identify the kind of data in the
file.
The second record contains only an integer n right-justified within the first five spaces (the I5 FORTRAN
format). It tells how many matrices are contained in the file. The next several records (one or more)
contain the alphanumeric names (eight characters or less) of all of the matrices in the file. The names are
listed sequentially, four to a line, in eight-character fields separated by ten blanks. That is, the FORTRAN
format for the records containing the matrix names is A8, 10X, A8, 10X, A8, 10X, A8.
Sets of contiguous records define each matrix. Without any intervening blank lines, the blocks of records
begin immediately after the last line of matrix names. The first record in each block contains the name
of the matrix in the first eight characters of the line. The code searches through the file until it finds the
block of records corresponding to the NAME argument on the MATRIX statement.
The first record of the block contains the type of matrix (either FULL or SPARSE) within the second
eight spaces on the record. If the type is FULL, the next eight spaces (from 17 through 24) contain the
string CORDER or RORDER to indicate that the values are listed by column or by row, respectively.
Otherwise, if the type is SPARSE, the space is left blank.
The numerical values specified on the first record of the block include the:
Number of rows M in the matrix
Number of columns N
Total number of entries to be assigned values from the file
If the matrix type is SPARSE, then the total number of entries must be less than or equal to
(generally much less than) M x N. If the matrix is FULL, the total number must be equal to M x
N.
For a matrix in the ADAMSMAT format, the values for M, N, and the total number of entries
must be right justified in the fields 25 to 29, 30 to 34, and 35 to 39, respectively.
For a matrix in the ADAMSMAT2 format, the values for M, N, and the total number of entries
218 Adams/Solver
The final entry on the first line of the block of records defining each matrix is the format
specification for the records containing the values of the matrix. Beginning in column 40, 41
spaces are allowed for the character string containing the FORTRAN format specification which
must include delimiting parentheses. The lines of data begin on the next record and continue
with successive records until the code has read into storage either M x N values in case the
matrix is FULL or the total number specified in case the matrix is SPARSE.
Table 1. Specifications for the ADAMSMAT Matrix File
Number of
records:
Item:
Argument or
symbol:
Contents:
FORTRAN
format:
ADAMSMAT
I5
(n+3)/4
NAME
4 (8A,10X)
NAME
A8,
A8,
A8,
A(I,J)
or
I,J, A(I,J)
Note:
variable
M,N,
number
format
3I5
A41
FORMAT
FORMAT
Items 4 and 5 have to be repeated n times, once for each matrix named in Item 3.
Item:
Contents:
Argument or
symbol:
FORTRAN
format:
ADAMSMAT2
I5
(n+3)/4
NAME
4 (8A,10X)
MATRIX 219
Adams/Solver (FORTRAN) Statements
Number of
records:
Item:
Contents:
Argument or
symbol:
NAME
M,N,
number
format
5
Note:
variable
A(I,J)
or
I,J, A(I,J)
FORTRAN
format:
A8,
A8,
A8,
Values
separated by
spaces
A41
FORMAT
FORMAT
Items 4 and 5 have to be repeated n times, once for each matrix named in Item 3.
For a FULL matrix, the code simply reads matrix entries sequentially from the file. If the matrix is
SPARSE, the data have to be organized in triplets: Adams/Solver (FORTRAN) reads the row and column
indices followed by the corresponding entry in the matrix. One triplet follows another until the specified
total number of values have been read into the storage arrays.
If another matrix is contained in the file, the block of records defining its structure and containing its
values must follow immediately after the last line of data for the previous matrix.
Tip:
The largest square matrix that may be entered directly in the dataset is 48 48. In order to
enter a larger matrix, you must supply the matrix entries in a file using the FILE and NAME
arguments.
Caution:
The file name must be on one line following the argument FILE =, which if abbreviated,
limits the identifier to about 75 characters.
Examples
Small Matrix Input
220 Adams/Solver
TRF =
1.364
0.000
3.546
0.000
0.000
0.000
4.008
0.799
Because it is small in size, you will have little difficulty in entering the matrix directly into the
Adams/Solver (FORTRAN) dataset.
Version 1, FULL Format (row order):
Assume that in addition to the matrix above, there are two additional matrices you want to enter into
Adams/Solver (FORTRAN).
VALK =
1.698045 10
2.307452 10
STL =
0.00 10
0.016390 10
0.044571 10
0
0.00 10
MATRIX 221
Adams/Solver (FORTRAN) Statements
Assume that you want to use an external file to input the matrices and that all of the matrices are resident
in a file called prob.dat which is in the system subdirectory, /home/staff/demo. The Adams/Solver
(FORTRAN) dataset entries would appear as the following:
MATRIX/1, File=/home/staff/demo/prob8.dat, Name= trf
MATRIX/2, File=/home/staff/demo/prob8.dat, Name= valk
MATRIX/3, File=/home/staff/demo/prob8.dat, Name= stl
The leading record of a matrix file is read as character data. The first seven or eight columns must contain
one of the three character strings: MATRIXx, MATSAVE, or ADAMSMAT.
In the current example, the prob.dat is in the directory, /home/staff/demo, and contains the following data:
1
2
3
4
5
6
7
8
123456789012345678901234567890123456789012345678901234567890123456789
01234567890
ADAMSMAT Floating platform example
3
TRF
VALK
STL
TRF
FULL
RORDER
4
2
8
( 8F8.5 )
1.36400 0.00000 0.00000 0.00000 -3.54600 4.00800 0.00000
0.79900
VALK
FULL
CORDER
3
3
9
( 3F6.3 )
1.970 0.000-3.440
0.000 4.510 6.020
-3.440 6.020 2.110
STL
SPARSE
6
1
4
( 2( 2I5,
E14.6 ) )
1
1
0.169805E+02
2
1 -0.230745E+02
4
1
0.016390E+00
5
1 0.011271E+00
The second and third records are read with format I5 and 4(A8,10X), respectively. Then, the first record
of each of the blocks corresponding to the three matrices TRF, VALK, and STL is read with the format
3A8, 3I5, A41. Finally, as can be seen in the copy of the file shown above between the two strings of 80
characters that mark the columns (which, of course, are not part of the file), the single record of data for
the matrix TRF is read with the format 8F8.5; the three records for VALK are read with 3F6.3; and the
two records for STL with 2(2I5,E14.6).
Applications
The CURVE, LSE, and NFORCE statements refer to the MATRIX statement. The CURVE statement
specifies a MATRIX statement containing the coordinates of the points defining a general curve in space.
For the LSE statement (Linear State Equation), the MATRIX statement is used to store the system state
matrices (A, B, C, and D). For the NFORCE statement, the MATRIX statement is used to input the
system stiffness and damping matrices (K and C), as well as the free length (Lo) and the preload (Fo).
See other Reference data available.
222 Adams/Solver
MFORCE
The MFORCE statement applies a force directly to the modal coordinates and rigid-body degrees of
freedom of a FLEX_BODY.
Format
Arguments
FLEX_BODY=id
JFLOAT=id
Specifies the floating marker on which the reaction force is applied. If you
do not specify a floating marker, Adams/Solver (FORTRAN) ignores the
reaction force.
CASE_INDEX=i
Specifies the loadcase number that defines the MFORCE. The loadcases
are force distributions that have been predefined and stored in a modal
neutral file (MNF) for an associated FLEX_BODY. Specifically,
CASE_INDEX refers to a column in the MODLOAD matrix that is
referenced in the FLEX_BODY statement. The column contains the
modal loads for the modes selected for an Adams simulation. For more
information about how to generate modal loadcases, see Adams/Flex
online help.
Note:
ROUTINE=libname::subn Specifies an alternative library and name for the user subroutine
MFOSUB.
ame
Learn more about the ROUTINE Argument.
MFORCE 223
Adams/Solver (FORTRAN) Statements
SCALE=e
The MFORCE statement allows you to apply any distributed load vector F to a FLEX_BODY. Such a
load vector is typically generated with a finite-element program. Examples of distributed loadcases
include thermal expansion or pressure loads. To help you understand how Adams handles distributed
loads, the following section discusses the equations of motion of a flexible body, starting with the
physical coordinate form that the finite-element program uses.
Equations
[ M ]x + [ K ]x = F
where [ M ] and [ K ] are the finite element mass and stiffness matrices for the flexible component; x is
the nodal coordinate vector; and F is the distributed load vector. This equation can be transformed into
the modal coordinates, q:
T
T
T
[ P ] [ M ] [ P ]q + [ P ] [ K ] [ P ]q = [ P ] F
where
[ M ]q + [ K ]q = f
where [ M ] and [ K ] are the generalized mass and stiffness matrices, and f is a modal load case vector
that Adams uses to define the MFORCE element.
The projection of the nodal force vector on the modal coordinates:
T
f = [P] F
This is a computationally expensive operation that poses a problem when F is a general function of time.
Adams circumvents this problem by assuming that the spatial dependency and time dependency can be
224 Adams/Solver
separated such that the load is a time varying linear combination of an arbitrary number of static
loadcases:
F ( t ) = s 1 ( t )F 1 + + s n ( t )F n
Therefore, the expensive projection of the load to modal coordinates is performed only once during the
creation of the MNF, rather than repeatedly during the Adams simulation. Adams needs only to account
for the modal form of the load:
f ( t ) = s 1 ( t )f 1 + + s n ( t )f n
where the vectors f1 to fn are n different loadcase vectors. Each of the loadcase vectors contains one entry
for each selected mode.
A more general definition of f allows it to have an explicit dependency on system response, which is
denoted as f(q,t), where q represents all the states of the system. The equation for the modal load is then:
f ( q, t ) = s 1 ( q, t )f 1 + + s n ( q, t )f n
which allows the load on a flexible body to be a function of its proximity to another body, such as a heat
source, its velocity, or other.
General Definition of Modal Force
Adams/Solver (FORTRAN) lets you define a modal load with the general definition in the last equation.
However, because of the definitions comprehensiveness, you may find it cumbersome to use. Depending
on your needs, you may be able to use one of the more elementary versions, which are described next,
beginning with the simplest definition.
Definition 1:
If the FLEX_BODY receiving the load has the modal loadcases f1, f2,...,fn defined in its MNF, you can
define the MFORCE by referring to exactly one of the loadcases using the CASE_INDEX argument. The
loadcase is scaled using the SCALE argument, making the load a function of time and/or system
response. This corresponds to the load definition:
f ( q, t ) = s ( q, t )f i
where CASE_INDEX=i and SCALE=s(q,t) is expressed as an Adams/Solver (FORTRAN) function
expression.
Definition 2:
Alternatively, you can achieve the same effect using the MFOSUB user-written subroutine. The
MFOSUB references one of the loadcases and computes the scale factor:
f ( q, t ) = s ( q, t )f i
MFORCE 225
Adams/Solver (FORTRAN) Statements
where the dependency on q occurs through the use of SYSFNC or SYSARY in the user subroutine. This
method of MFORCE definition is strictly equivalent to the first one.
Definition 3:
Alternatively, you can use MFOSUB to combine the loadcases, f1,...,fn as follows:
f ( q, t ) = s ( q, t ) [ g 1 ( t )f 1 + + g n ( t )f n ]
In this case, rather than referencing a single loadcase, the MFOSUB computes a new loadcase by
combining the existing loadcases in a time varying fashion. Adams/Solver (FORTRAN) then scales the
new loadcase by a scale factor that is also computed by the MFOSUB. It is important to note that although
the scale factor can be a function of time and of system state, the new loadcase may be only a function
of time. In other words, using values obtained by calls to SYSFNC or SYSARY to define the functions
gi(t) is not allowed.
Definition 4:
If the FLEX_BODY has no loadcases in the MNF, then MFOSUB can compute the loadcase. Again, the
loadcase vector may be a function of time only, while the scale factor that is applied to it may be a
function of both time and system state:
f ( q, t ) = s ( q, t )f u ( t )
where s(q,t) is a user-defined scale factor and fu(t) is a user-defined load vector. This method of
MFORCE specification is primarily provided for completeness, and will be used primarily by very
experienced users.
Definition 5:
f ( q, t ) = s 1 ( q, t )f 1 + + s n ( q, t )f n
where each loadcase fi has its own response-dependent scale factor si(q,t) that can be achieved only
through the use of multiple MFORCE elements acting on the same flexible body.
For distributed loads that have an external resultant, portions of the load will project on the rigid body
modes of the flexible body. However, the rigid-body modes must be disabled because Adams/Solver
(FORTRAN) will replace them with the nonlinear, large motion, generalized coordinates: X, Y, Z,
, and . In this case, the load on the rigid-body modes are transferred to the large motion generalized
coordinates.
Part of this transfer occurs during the MNF2MTX translation of the flexible body's MNF, and,
consequently, the MODLOAD matrix has a dimension that equals 6 plus the number of modes. The first
6 entries in each column correspond to the external force and torque acting on the flexible body for this
loadcase, expressed relative to the body coordinate system (BCS). When the loadcase is an internal force
(as would be expected in the case of a thermal load), this force and torque will be zero.
226 Adams/Solver
You should also be aware of the way modal truncation affects the application of modal load. When you
define a distributed load, it will be projected on the available modes. It is important to understand that
the available modes form an efficient but incomplete basis for the flexible component. Therefore, it is
inevitable that some portion of the load will be orthogonal to modal basis. This portion of the load will
be irretrievably lost. Furthermore, during mode selection within Adams, you should realize that a mode
whose removal is being considered may also have a significant modal load associated with it. In this case,
the mode should not be disabled.
Examples
MFORCE/1, FLEX_BODY = 1, CASE_INDEX = 1
, SCALE = SIN(TIME)*DX(1,4)
Using the first loadcase defined for FLEX_BODY/1, this example defines a modal load on
FLEX_BODY/1 by scaling the values of the loadcase by the function expression SIN(TIME)*DX(1,4).
The reaction force that corresponds to this load is ignored.
MFORCE/2, FLEX_BODY = 2, JFLOAT = 4
, FUNCTION = USER(10,1e5,23.)
This example defines a modal load whose reaction resultant force acts on the parent part of floating
marker 2. The magnitude and shape of the load is provided by the MFOSUB user-written subroutine,
based on the user parameters 10,1e5,23.
See other Forces available.
MOTION 227
Adams/Solver (FORTRAN) Statements
MOTION
The MOTION statement specifies a system degree of freedom as an explicit function of time. The
freedom is specified by either:
Specifying the joint and type of motion (translational or rotational).
Identifying a specific translation or rotational displacement component between two markers
The time dependency can be described in either a function expression or user-written subroutine. The
motion inputs may be a displacement, velocity, or acceleration. Velocity and accelerations are
numerically integrated to provide the displacements, with the initial conditions providing the constants
of integration.
Format
228 Adams/Solver
Arguments
ACCELERATION
B1
Specifies the first angle of the Body 1-2-3 Euler angle sequence
as a function of time. The 123 rotation sequence of the I marker
coordinate system is defined with respect to the J marker
coordinate system.
Range: None
Default: None
B2
B3
DISPLACEMENT
FUNCTION =
Specifies an expression or defines and constants to be passed to
USER ( r 1 [ , , r 30 ] ) the MOTSUB user-written subroutine to determine the motion.
The motion must be a function of time only and not a function
of the state variables. To determine the motion with an
expression, follow FUNCTION with an equal sign and the
expression. To determine the motion with a user-written
subroutine, follow FUNCTION with an equal sign, the
character string USER, and the values (r1[,...,r30]) that you
want Adams/Solver (FORTRAN) to pass to MOTSUB. If the
FUNCTION argument is used, it must either be the last
argument in the MOTION statement or be followed by a
backslash (\).
MOTION 229
Adams/Solver (FORTRAN) Statements
ICDISP
ICVEL
I=id, J=id
JOINT=id
ROTATION
ROUTINE=libname::subname
TRANSLATION
VELOCITY
230 Adams/Solver
Motions can be specified to act on joints. A translational motion is specified at either a translational or
cylindrical joint. A rotational motion is specified at either a revolute or cylindrical joint. The type of the
joint together with the markers of the joint specify the degree-of-freedom being controlled.
For a translational motion, Adams/Solver (FORTRAN) moves the I marker along the z-axis of the J
marker. The J marker origin represents zero displacement while the z-axis of the J marker defines the
positive direction.
For a rotational motion, Adams/Solver (FORTRAN) rotates the I marker about the z-axis of the J marker.
The right-hand rule is used to determine the sign of the motion. The z-axis of the I marker must be
colinear with the z-axis of the J marker at all times. The angle is zero when the x-axis of the I marker is
also collinear with the x-axis of the J marker.
Motions on Markers
MOTION 231
Adams/Solver (FORTRAN) Statements
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
If you want to determine the translational or rotational force a motion applies, use
Caution:
The motion must be a function of only time, not displacements, forces, or any other
Non-smooth functions that do not have continuous first and second time derivatives can
cause severe numerical problems.
Be careful when specifying multi-axial rotational motions between a pair of markers.
B1, B2, and B3 specify a Body 1-2-3 rotation sequence and are Euler angles. This
implies that the first rotation occurs about the x-axis of the J marker, the second rotation
about an intermediate y-axis and the last about the z-axis of the I marker. For example,
if you are measuring rotations between two markers in the sequence z, y, x, this
corresponds to a Body 3 -2 1 rotation sequence, you will have to convert this to a Body
1-2-3 rotation sequence before specifying it in a MOTION.
232 Adams/Solver
When using any of the following motion types: B1, B2, or B3, avoid situations where
the B2 angle is at +/- 90degrees or +/- 270 degrees. At these angles the Body 1-2-3
angles are undefined. If this situation occurs, Adams/Solver (FORTRAN) issues a
warning and stops the execution. There is no solution for this condition.
Do not use an initial conditions argument, such as, IC, ICTRAN, or ICROT, on a
JOINT statement with a motion that acts in the same direction on the joint. If both are
used, Adams/Solver (FORTRAN) uses the MOTION statement and ignores the initial
conditions argument(s) specifying motion in the same direction(s) specified by the
JOINT statement.
If the initial rotational displacement of a revolute or cylindrical joint (as specified by an
(FORTRAN) integrator may not produce reliable accelerations and velocities for the
first two or three internal integration steps. Adams/Solver (FORTRAN) automatically
corrects for this, so that values returned at the first output step are accurate. However, a
sensor that depends on the accelerations or reaction forces due to this motion may trip
unexpectedly prior to the first output step, even though the solution appears correct
when the sensor is removed. If this occurs, you should modify the displacement
function in the MOTION statement so that the initial accelerations are zero.
The ABAM integrator does not support the VELOCITY and ACCELERATION
functions.
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:
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)
MOTION 233
Adams/Solver (FORTRAN) Statements
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-
These MOTION statements control the three rotational degrees-of-freedom in a spherical joint by
specifying the Body 1-2-3 angles between the I and J markers of the joint as functions of time.
JOINT/401, PLANAR, I=4011, J=4012
MOTION/4011, I=4011, J=4012, X
, FU=STEP5(TIME, 0.5, 0.0, 4.0, 1.0)*50
MOTION/4012, I=4011, J=4012, Y
, FU=-SHF(TIME, 0.0, 10/2, 2*PI, 90D, 10/2)
MOTION/4016, I=4011, J=4012, B3, FU=0D
These MOTION statements control the three degrees-of-freedom in a planar joint:
The displacement of the origin of Marker 4011 with respect to the origin of Marker 4012, along
specified to be zero.
See other Constraints available.
234 Adams/Solver
MREQUEST
The MREQUEST statement specifies multiple sets of data that you want Adams/Solver (FORTRAN) to
write in the tabular output file and request file. You can request sets of displacements, velocities,
accelerations, or forces for system elements such as parts, joints, joint primitives, or applied forces in the
system.
Format
MREQUEST 235
Adams/Solver (FORTRAN) Statements
Arguments
ACCELERATION Generates acceleration requests that output the accelerations for the markers that
define part centers of mass, joints, joint primitives, or applied forces. This
argument generates nine headings and nine columns of output for each part, joint,
joint primitive, or applied force. The columns in the Tabular Output file include the
time (TIME), the translational magnitude (ACCM), the x component (ACCX), the
y component (ACCY) the z component (ACCZ), the rotational magnitude
(WDTM), the rotational x component (WDTX), the rotational y component
(WDTY), and the rotational z component (WDTZ). The same data without the
magnitude are written in the Request file.
id1 [ ,, id30 ]
APPFORS =
ALL
Specifies a title for the top of each set of information the MREQUEST statement
outputs. The entire comment must be on one line. Because the COMMENT
argument can be only eighty characters long at most, the title can be from seventytwo characters long (if you do not abbreviate COMMENT=) to seventy-eight
characters long (if you abbreviates COMMENT= to C=). Blank spaces and all
alphanumeric characters can be used. However, the comma (,), the semicolon (;),
the ampersand (&), and the exclamation point (!) cannot be used.
236 Adams/Solver
DISPLACEMENT Generates displacement requests that output the displacements for the markers that
define part centers of mass, joints, joint primitives, or applied forces. This
argument generates eight headings and eight columns of output for each part, joint,
joint primitive, or applied force. The columns in the tabular output file include the
time (TIME), the translational magnitude (MAG), the x component (X), the y
component (Y), the z component (Z), the psi angle (PSI), the theta angle (THETA),
and the phi angle (PHI). The same data without the magnitude are written in the
Request file. For joints, joint primitives, and applied forces, the psi, theta, and phi
angles are the Euler angle displacements of the I marker with respect to the J
marker. For parts, the psi, theta, and phi angles are the Euler rotations of the part
center-of-mass marker with respect to the ground coordinate system (GCS) or with
respect to a J marker you specify.
FORCE
Generates force requests that output the forces for the markers that define joints,
joint primitives, or applied forces. This argument generates nine headings and nine
columns of output for each joint, joint primitive, or applied force. The columns in
the Tabular Output file include the time (TIME), the translational force magnitude
(FM), the translational x component (FX), the translational y component (FY), the
translational z component (FZ), the rotational force magnitude (TM), the rotational
x component (TX), the rotational y component (TY), and the rotational z
component (TZ). The same data without the magnitudes are written to the Request
file. The FORCE argument cannot be used with the PARTS argument.
MREQUEST 237
Adams/Solver (FORTRAN) Statements
J=id
id1 [ ,, id30 ]
JOINTS =
ALL
id1 [ ,, id30 ]
JPRIMS =
ALL
id1 [ ,, id30 ]
PARTS =
ALL
238 Adams/Solver
VELOCITY
Generates velocity requests that output the velocities for the markers that define
part centers of mass, joints, joint primitives, or applied forces. This argument
generates nine headings and nine columns of data for each part, joint, joint
primitive, or applied force. The columns in the tabular output file include the time
(TIME), the translational magnitude (VM), the x component (VX), the y
component (VY), the z component (VZ), the rotational magnitude (WM), the
rotational x component (WX), the rotational y component (WY), and the rotational
z component (WZ). The same data without the magnitudes are written in the
request file.
RM=id
Identifies the reference marker with respect to which you want to resolve
information. RM defaults to zero, which causes Adams/Solver (FORTRAN) to
resolve components in the ground coordinate system (GCS).
Extended Definition
The MREQUEST statement indicates multiple sets of data you want Adams/Solver (FORTRAN) to write
in the tabular output file and request file. You can request sets of displacements, velocities, accelerations,
or forces for system elements such as parts, joints, joint primitives, or applied forces in the system.
Adams/Solver (FORTRAN) calculates all time derivatives in the ground coordinate system (GCS),
although you can specify that the data be resolved in another reference frame. This is of no importance
in the case of force data, but it can be very important in the case of velocities and accelerations. For
example, joint velocities are actually translational and rotational velocity difference vectors of the joint
I marker and the joint J marker in ground. Joint accelerations are actually translational and rotational
acceleration difference vectors of the joint I marker in ground and the joint J marker in ground.
Because two markers (I and J) define each joint, joint primitive, and applied force, Adams/Solver
(FORTRAN) measures the request information for one of these at the I marker with respect to the J
marker. Because a center-of-mass marker is the only marker that is necessary to define a part,
Adams/Solver (FORTRAN) measures the request information for a part at its center-of-mass marker with
respect to ground or with respect to an alternative marker you specify. Regardless of the system
information you want, a reference marker (RM) can be used to resolve the component information into
any coordinate system you wish.
Caution:
Note that the units for rotational displacement data in the request output of the tabular
output file default to degrees. The units for all other angular output data default to radians.
For any argument =ALL, Adams/Solver (FORTRAN) ignores any invalid selections.
MREQUEST 239
Adams/Solver (FORTRAN) Statements
Applied forces and torques are those generated by beams, bushings, fields, general forces
forces, and vector torques, the forces and torques acting at the J marker are equal
and opposite to the forces and torques acting at the I marker.
For action-only single-component forces, no force or torque acts at the applied force
J marker.
For beams, fields, bushings, and multi-point forces, the forces acting at the applied
force J marker are equal and opposite to the forces acting at the applied force I
marker.
As long as the applied force I marker and the applied force J marker are coincident, the
torques acting at the applied force J marker are equal and opposite to the torques acting at
the applied force I marker. If there is a finite separation distance between the I and J
markers, the torques acting at the applied force J marker are not necessarily opposite or
equal, to the torques acting at the applied force I marker.
Reaction forces and torques are those generated by constraint-inducing elements. For
revolute, spherical, and universal joints and for atpoint, orientation, parallel axes, and
perpendicular joint primitives, Adams/Solver (FORTRAN) outputs the reaction forces and
torques acting at the request I marker (which may be either the constraint I marker or the
constraint J marker). Depending on the type of constraint, some or all of the torques acting
at the I marker are zero. The force and torque acting at the request J marker are equal and
opposite to the force and torque acting at the request I marker.
Determining reaction forces-and torques for cylindrical, planar, rack-and-pinion, screw,
and translational joints and for inline and inplane joint primitives is more complex. If the
request I marker corresponds to the constraint I marker, then Adams/Solver (FORTRAN)
outputs the force and torque acting at the constraint I marker. If the request I marker
corresponds to the constraint J marker, then Adams/Solver (FORTRAN) outputs the force
and torque acting at the instantaneous location of the constraint I marker, but on the part
containing the constraint J marker. The force translated to the constraint J marker is the
same as computed above. If the I and J markers are coincident, the torque translated to the
constraint J marker is the same as computed above. But if there is a finite separation
between the I and J markers, the torque translated to the constraint J marker is different
from the one computed above (because of the moments contributed by the reaction forces).
The MREQUEST statement is not scheduled to be supported in Adams/Solver (C++). You
are encouraged to migrate away from this statement and use the REQUEST statement
instead.
240 Adams/Solver
Examples
MREQUEST/01, DISPLACEMENT, PARTS=1014,1013,1012
This MREQUEST statement requests displacement data for Parts 1014, 1013, and 1012. For each of the
three parts, Adams/Solver (FORTRAN) outputs eight headings and eight columns of data to the tabular
output file. The same information also goes to the request file. Because this statement does not supply
arguments J and RM, Adams/Solver (FORTRAN) measures the displacements with respect to the ground
coordinate system (GCS), and resolves the displacements in the global coordinate system.
MREQUEST/04, FORCE, JOINTS=ALL
This MREQUEST statement requests the force data for all the joints in the dataset. For each joint,
Adams/Solver (FORTRAN) outputs nine headings and nine columns of data to the tabular output file
with the same information going to the request file.
See other Output available.
NFORCE 241
Adams/Solver (FORTRAN) Statements
NFORCE
The NFORCE statement creates a multi-point force element which establishes linear force-displacement
(stiffness) and/or force-velocity (damping) relationships between many markers (up to 351) in the model.
Format
Arguments
CMATRIX=id
Specifies the identifier of the MATRIX that the NFORCE uses as its damping
matrix. The CMATRIX is a 6n 6n matrix (n is the number of I markers) that
defines the linear relationships between the I marker velocities relative to the J
marker and the viscous forces generated by the NFORCE. The CMATRIX is
derived in the J markers coordinate system. If neither CMATRIX nor CRATIO is
given, the NFORCE is undamped. Marker translational and rotational velocities
appear sequentially in Vx, Vy, Vz, x , y , z order, while the markers appear
in the same sequence as in the IMARKER argument.
CRATIO=r
Specifies the proportional damping ratio for the NFORCE. The elements of the
damping matrix are determined by multiplying the corresponding stiffness element
value by this number. If direct input of the damping properties is desired, the
CMATRIX may be used. If neither CMATRIX nor CRATIO is given, the
NFORCE is undamped.
FORCE
Specifies the identifier of the MATRIX that contains the forces and torques that the
NFORCE would produce if all the I markers were at the positions given in
LENGTH. FORCE is a 6n 1 matrix (n is the number of I markers) of forces and
torques, appearing sequentially for each marker in Fx, Fy, Fz, Tx, Ty, Tz order, while
the markers appear in the same sequence as in the IMARKER argument. The force
and torque components are expressed in the J markers coordinate system. When
LENGTH is used to specify the systems free lengths, FORCE gives the preloads.
If FORCE is not given, the NFORCE acts as though a matrix of zeros are input.
242 Adams/Solver
IMARKERS=id1, Lists the markers (except for the J marker) between which the NFORCE forces and
...,idn
torques act.
Number of values: 1 to 350
J=id
Specifies the identifier of the marker that determines the reference frame in which
the relative velocities and all of the forces associated with the NFORCE are
calculated and the coordinate system in which all the components and LENGTHs
are evaluated. The NFORCE automatically applies the proper reaction forces at the
J marker.
KMATRIX=id
Specifies the identifier of the MATRIX that the NFORCE uses as its stiffness
matrix. The KMATRIX is a 6n 6n matrix (n is the number of I markers) that
defines the linear relationships between the I marker displacements relative to the
J marker and elastic forces generated by the NFORCE. The KMATRIX is specified
in the J markers 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 markers 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 systems free (no internal force) lengths when they differ from the input
positions. If LENGTH is not given, the NFORCE assumes that the input positions
of the I markers are at the reference locations.
Extended Definition
The NFORCE creates a set of forces and torques which act between the I and J markers which appear in
the NFORCE statement. These forces and torques are linear functions of the relative displacements and
velocities of the markers, in a manner equivalent to the finite element method. For each NFORCE, one
marker (J) is used as the reference marker. The velocities are resolved into the J markers reference frame
and expressed in the J markers coordinate system. The force and torque components computed by the
NFORCE are also given in the J markers coordinate system.
The force-displacement and force-velocity relationships are specified using stiffness and damping
matrices, or by using a stiffness matrix and a proportional damping ratio. These matrices are defined
using MATRIX statements in the dataset. The stiffness and damping matrices that Adams/Solver
(FORTRAN) requires are defined for the I markers only; that is, they should be derived normally using
the 6(n+1) J marker and I marker degrees-of-freedom, but are input using only the rows and columns
corresponding to the I marker degrees-of-freedom. This is equivalent, in finite element terminology, to
applying fixed boundary conditions at the J marker by simply removing the corresponding rows and
columns from the matrices. Adams/Solver (FORTRAN) automatically computes and applies the correct
reaction forces at the J marker.
NFORCE 243
Adams/Solver (FORTRAN) Statements
Formulation
FI = - KMATRIX (X - L) - CMATRIX
X + FORCE
where:
FI is the 6n x 1 matrix of forces exerted on the I markers.
KMATRIX is the 6n x 6n truncated stiffness matrix, created by striking out the rows and
expressed in the J markers 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
X is the 6n x 1 matrix of the translational and linearized angular velocities of the I markers with
respect to the J marker, and expressed in the J markers coordinate system.
FORCE is the 6n x 1 matrix of the reference forces on the I markers; that is, the forces on the I
markers when their displacements relative to the J marker are specified by L. When LENGTH
contains the free lengths, FORCE is the preload.
Reaction Forces (Forces on the J marker)
F j trans = F itrans
i
where:
trans denotes translational degrees-of-freedom
=rot denotes rotational degrees-of-freedom
Xji is the instantaneous vector from the J marker to each I marker.
244 Adams/Solver
Tip:
When importing stiffness and damping matrices that are developed using finite
element methods, the LENGTH and FORCE arguments are most easily thought of
as the system free lengths (zero internal stress) and preloads. You can, however,
specify any consistent set of reference lengths and resulting forces, just as for the
SPRINGDAMPER element.
Physically meaningful NFORCES have positive semi-definite KMATRIX and
CMATRIX matrices. That is, the diaginal enteries of the matrices have positive
value. Adams/Solver (FORTRAN) only accepts NFORCES having positive semidefinite matrices.
Caution:
Like the BEAM, the NFORCE is a linear element, so that the forces computed are
generally valid only for small displacements. When the applied loading is such that
the small displacement limits are exceeded (a good estimate is ten percent of
lengths and less than 0.2 radian rotations), the NFORCE results may be less
accurate. In cases where the structure undergoes large overall deflections but
remains linearly elastic (small local deflections), you can use more NFORCE
elements, so that each NFORCE element remains locally within small
displacement limits. Note that because of the way that Adams/Solver (FORTRAN)
computes angular displacements, the absolute magnitude of this inaccuracy due to
overly large displacement may depend on the instantaneous spatial orientation of
the system.
A two-point NFORCE is not identical to a field, although it is very similar. The
default that the input positions of the I markers are at the reference locations.
The FIELD allows you to specify reference angles for the rotational
displacements, while the NFORCE assumes the reference angles are always
zero.
Examples
The figure below illustrates a simple, planar, triangular truss attached to some large base body.
NFORCE 245
Adams/Solver (FORTRAN) Statements
The following NFORCE statement defines a 24 force components acting between Markers 10, 20, 30,
and 40.
NFORCE/1234, J=10, I=20,30,40, KMATRIX=1234, CRATIO=0.02
Marker 10 is the J marker. This means Matrix 1234 is an 18-by-18 stiffness matrix relating forces to
displacements at Markers 20, 30 and 40. The forces and displacements are measured in the coordinate
system of Marker 10. Because the LENGTH argument is not included, Adams/Solver (FORTRAN)
measures the displacements from the input position. Because the FORCE argument is not specified, there
are no loads at the reference position (in this case the input position). In other words, the truss has been
input in the unloaded, undeformed configuration. The damping matrix is .02 times the stiffness matrix.
Depending on the assumptions you make, the stiffness matrix for this structure could be quite elaborate.
A simple case, however, is to assume the ends of the truss members are pinned, and that the truss
members only transmit translational, in-plane forces.
Due to the simple geometry, this matrix can be determined by inspection, and is shown in the table shown
next.
246 Adams/Solver
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
NFORCE 247
Adams/Solver (FORTRAN) Statements
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
super-element condensation before importing it into Adams/Solver (FORTRAN) as an NFORCE.
Because of formulational differences between FEA and Adams multibody systems analysis, it is
generally not possible to have a one-to-one correspondence between Adams/Solver (FORTRAN) PARTs
and FEA nodes, unless the FEA model is very small.
Flexible Satellite Panels
248 Adams/Solver
OUTPUT
The OUTPUT statement controls the generation of request and graphics files. It also controls the form,
format, coordinates, filtering, and scaling of request data in the tabular output file (.out).
The OUTPUT statement has been extended to control generation and format of output files from
FEMDATA or REQUEST statements. For example, it lets you generate RPC III and DAC files of
Adams/Solver (FORTRAN) request data.
OUTPUT 249
Adams/Solver (FORTRAN) Statements
Format
250 Adams/Solver
Arguments
ABAQUS
ANSYS
ASCALE=r1[,r2]
AZERO=r
Specifies that output accelerations less than r in magnitude are to be set equal
to zero. The value of r must be greater than zero. The value of r defaults to
1.0E-7 for output in scientific notation and to 0.001 for output in fixed-point
notation.
CHART
Produces x-y charts of the request data for the tabular output file. If you do
not specify CHART, Adams/Solver (FORTRAN) does not produce charts of
the request data for the tabular output file.
DAC
Specifies the output of FEM data to DAC files. DAC is a file format supported
by nCode/nSoft. A DAC file is generated for each component of load, stress
or strain, or modal coordinate.
DACSAVE
Saves all request output in DAC format. If you do not specify DACSAVE,
Adams/Solver (FORTRAN) does not save request data in DAC format.
DSCALE=r1[,r2]
DZERO
Specifies that output displacements less than r in magnitude are to be set equal
to zero. The value of r must be greater than zero. The value of r defaults to
1.0E-7 for output in scientific notation and to 0.001 for output in fixed-point
notation.
FIXED
Formats numerical output in fixed-point notation. Any values that are too
small or too large for fixed-point notation are output in scientific notation. If
you do not specify FIXED, Adams/Solver (FORTRAN) formats numerical
output in scientific notation.
FSCALE=r1[,r2]
FZERO
Specifies that output forces less than r in magnitude are to be set equal to zero.
The value of r must be greater than zero. The value of r defaults to 1.0E-7 for
output in scientific notation and to 0.001 for output in fixed-point notation.
OUTPUT 251
Adams/Solver (FORTRAN) Statements
GENERIC
Specifies the output of FEM data to a human readable (ASCII) text file.
GRSAVE
GR521SAVE
Saves graphics output in the graphics file in Adams 5.2.1 format. Graphics
files written by Adams 6.0 and later (when GRSAVE is specified) contain
more information than those written by Adams 5.2.1. Consequently,
applications written to use the older files may no longer work with 6.0 and
later files. If the application does not accept 6.0 and later files, you can specify
GR521SAV to create a 5.2.1 format file. A 5.2.1 graphics file does not contain
curve graphics, road surface graphics, or floating markers. If neither
GRSAVE nor GR521SAV is specified, Adams/Solver (FORTRAN) does not
save graphics output in the graphics file.
LOADS
Controls output of FEM data to the specified format. If you do not specify
LOADS, Adams/Solver (FORTRAN) does not process any
FEMDATA/LOADS statements.
MODAL_DEFORMA
TION
NASTRAN
Specifies the output of FEM data to a NASTRAN readable format. Load data
or nodal deformations are written out as NASTRAN input commands. Modal
deformations are written out to NASTRAN OUTPUT2 (binary) format.
NODAL_DEFORMA
TION
NOPRINT
252 Adams/Solver
NOSEPARATOR
OSFORMAT
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
REQSAVE
Saves request output in the request file so that you can use a postprocessor to
display x-y plots. If you do not specify REQSAVE, Adams/Solver
(FORTRAN) does not save the request output in the request file.
RPC
Specifies the output of FEM data to an RPC III file. RPC III is a file format
supported by MTS. Each channel in the RPC file represents a load component
acting on the part.
OUTPUT 253
Adams/Solver (FORTRAN) Statements
RPCSAVE
Saves all request output in RPC III format. If you do not specify RPCSAVE,
Adams/Solver (FORTRAN) does not save request data in RPC III format.
STRAIN
Controls output of strain data to the specified format. If you do not specify
STRAIN, Adams/Solver (FORTRAN) does not process any
FEMDATA/STRAIN statements.
Note:
STRESS
Controls output of stress data to the specified format. If you do not specify
STRESS, Adams/Solver (FORTRAN) does not process any
FEMDATA/STRESS statements.
Note:
TELETYPE
VSCALE=r[,r2]
254 Adams/Solver
VZERO
Specifies that output velocities less than VZERO in magnitude are to be set
equal to zero. The value of r must be greater than zero. VZERO defaults to
1.0E-7 in scientific notation and to 0.001 in fixed-point notation.
YPR
The OUTPUT statement controls the generation of request and graphics files. In addition, it controls the
form, format, coordinates, filtering, and scaling of request data in the tabular output file. Also, the
OUTPUT statement controls the generation and format of REQUEST or FEM data. Specifically, the
OUTPUT statement controls the following:
Forms of Request Data in the Tabular Output File
Formats of Request Data in the Tabular Output File
Numerical Notation of Request Data in the Tabular Output File
Coordinates of Rotational Request Data in the Tabular Output File
Scales for Request Data in the Tabular Output File
Filters for Request Data in the Tabular Output File
Output of FEMDATA
OUTPUT 255
Adams/Solver (FORTRAN) Statements
X-Y charts of the request data for the tabular output file the output is in the same order as the requests
are in the dataset. The information about each request (including those created by an MREQUEST
command/statement) is in two parts. The left side of the first part contains a table of simulation time and
the translational information output by the request, and the right side contains a plot of the translational
information against time. The left side of the second part contains a table of simulation time and the
rotational information output by the request, and the right side contains a plot of the rotational
information against time (see Figure 2). (The column titles may vary according to the type of request
information and other arguments on the OUTPUT command/statement.)
These plots differ in two important ways from the plots created with Adams/Solver (FORTRAN) or most
postprocessors. First, time is along the vertical axis in the chart plots and request data is along the
horizontal axis. Second, the chart plots are normalized; that is, each curve is scaled independently of the
others from the highest value to the lowest value for that curve. Therefore, use care when comparing
curves to one another. You can compare the shapes but not the magnitudes of the curves.
Time-response-request tables A time-response-request table lists all values for a single
request throughout the simulation. One line appears in the table for each output time step; the
lines are in ascending order of time.
Output-step-request (OS) table An OS table lists the values of all requests at each output time
step. One line appears for each output time step, followed by one line per request.
Formats of Request Data in the Tabular Output File
exponent.
Scientific - Scientific notation expresses a number as a value between 1 and 10 (the mantissa)
256 Adams/Solver
Output of FEMDATA
With LOADS, the ABAQUS, ANSYS, or NASTRAN format option creates a text file of the input
commands of the respective FEA package (case control and bulk data in the case of NASTRAN) of all
the part forces.
With NODAL_DEFORMATION, the ANSYS or NASTRAN option creates a text file of input
commands for defining enforced displacements in the respective FEA package (for example, SPC* cards
in the case of NASTRAN).
With MODAL_DEFORMATION, the NASTRAN option produces an OUTPUT2 (NASTRAN binary)
file. This file can be imported by NASTRAN for stress recovery on the flexible body using the
Adams/Durability Modal Stress Recovery. Note that this file format is machine dependent. NASTRAN
will not be able to read the file if it was created on a platform different than the one running NASTRAN.
Alternatively, the PUNCH format option for MODAL_DEFORMATIONS produces a text file that can
be imported by NASTRAN for stress recovery. This file format is not as compact as the OUTPUT2
format (see NASTRAN option), but it is machine independent. If NASTRAN is run on a different
platform than Adams, the modal deformations can be transferred via this file format for subsequent
NASTRAN runs.
Also, with MODAL_DEFORMATIONS, the ANSYS option produces a file of modal deformations. This
file can be processed by ANSYS using a custom macro provided by Adams/Durability (Reading Modal
Deformations File (MDF)). Modal deformations can be combined with the modal stress shapes stored in
the ANSYS database to recover dynamic stresses in ANSYS using modal superposition.
Output of Request Data in RPCIII and DAC Formats
You can save request data in RPC III and DAC format.
RPC III format- Adams/Solver (FORTRAN) creates one RPC file of all data components
where:
Prefix is the prefix specified when you set up Adams results.
OUTPUT 257
Adams/Solver (FORTRAN) Statements
DAC format - Adams/Solver (FORTRAN) can only store one channel of data in a DAC file.
Therefore, Adams/Solver (FORTRAN) creates six DAC files, one per request component. The
files are named according to the DAC file naming convention:
prefix_request name_component label.dac
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
prints records 132 characters wide and because CHART prints information next to
a plot.
The ICSAVE argument and .icf file have been discontinued. The SAVE and
RELOAD commands replace the OUTPUT/ICSAVE and EXECUTION/ICSTART
arguments.
Examples
OUTPUT/GRSAVE, REQSAVE
This OUTPUT statement causes Adams/Solver (FORTRAN) to save both graphics and request output.
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 (FORTRAN) to save request output defined in the above
REQUEST statement to DAC files only. Adams/Solver (FORTRAN) creates a total of six DAC files in
the current working directory with the following names:
adams_req01_x.dac
adams_req01_y.dac
adams_req01_z.dac
258 Adams/Solver
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 (FORTRAN) to save request output defined in the three
REQUEST statements to an RPC III file. Adams/Solver (FORTRAN) creates one RPC III file named
Adams.rsp, containing 18 channels of data (six per REQUEST statement).
See other Output available.
PART 259
Adams/Solver (FORTRAN) 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 may be massless under certain circumstances. Adams/Solver (FORTRAN) assumes that all parts are
rigid bodies. The PART statement is also used to specify which part is used as the fixed inertial (or
ground) global coordinate system. Each movable part (that is, other than ground) can add up to 6 degrees
of freedom (DOF) to a system.
Format
260 Adams/Solver
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
GROUND
Indicates the part being defined as the Newtonian reference frame. It is, by
definition, at absolute rest. Because there can be only one ground part in the
system, a dataset must never have more than one PART statement with the
GROUND argument.
IM=id
Specifies the identifier of the marker about which you specify the moments of
inertia for the part. This marker can be any marker in the part. The IM marker
defaults to the CM marker.
PART 261
Adams/Solver (FORTRAN) Statements
IP=xx,yy,zz[,xy,xz,yz]
Ixx =
(y
+ z ) dm
Iyy =
(x
+ z ) dm
Izz =
(x
+ y ) dm
Ixy =
xy dm
Ixz =
xz dm
Iyz =
yz dm
MASS=r
MATERIAL=mat_name Specifies the type of material the part is made of. You define the different
material types in the MATERIAL statement.
Range: Material type as defined in the MATERIAL statement
Default: Steel
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).
262 Adams/Solver
REULER=a,b,c
Defines the 3-1-3 Euler angles that Adams/Solver uses to establish the initial
orientation of the BCS with respect to the coordinate system. The a, b, and c
rotations are in radians and are, respectively, about the z-axis of ground, the
new x-axis, and the new z-axis of the BCS. To input Euler angles in degrees,
you should add a D after each value.
VM=id
WM=id
Specifies the identifier of the marker that specifies the axes about which
angular velocity initial conditions (WX, WY, and WZ) are defined. WM
defaults to the CM location and orientation. Furthermore, the origin of the
WM marker lies on the axis of rotation. This is most useful for rotating
systems. A typical application is a spinning flexible satellite model in space.
In this case, you add a marker to your system at the combined CG location of
the system and orient the marker such that one of its axes is along the spin axis
of the satellite.
Specifies the initial rotational velocities, in radians per second, of the part
about the x-axis (WX), the y-axis (WY), and the z-axis (WZ) of the CM
marker coordinate system.
XG=x,y,z
Defines the coordinates, measured in the GCS, of any point in the positive xz plane of the part BCS, but not on the z-axis of the part BCS.
ZG=x,y,z
Defines the coordinates measured in the GCS of any point on the positive zaxis of the BCS.
PART 263
Adams/Solver (FORTRAN) Statements
Tip:
If the part has no CM marker, as may be the case for some massless parts,
Adams/Solver (C++) uses the part BCS to represent the position and orientation of the
part internally.For more information on BCS, see Coordinate Systems and Local
Versus Global Geometric Data.
Using a CM on a massless part can improve model robustness by removing large
offsets between the BCS and markers on the massless part, without repositioning all the
markers on the massless part. Do not be confused by the contradiction of specifying a
center-of-mass of a massless part. In this case the CM marker is simply suggesting an
advantageous choice of internal coordinate systems.
If the part has mass, Adams/Solver (FORTRAN) uses the position of the CM marker to
represent the translational position of the part internally and uses the principal axes of
the inertia tensor about the CM marker to represent the orientation of the part
internally. This internal coordinate system is commonly referred to as the part principal
coordinate system.
Due to a basic property of Euler angles, a singularity occurs when the principal z-axis
of the CM becomes parallel to the ground z-axis. Whenever the principal z-axis of the
part nearly parallels the ground z-axis, Adams/Solver (FORTRAN) rotates the part
principal axes 90 degrees about the z-axis and then 90 degrees about the new x-axis to
avoid the singularity. Adams/Solver (FORTRAN), however, does not change the
marker locations and orientations with respect to the BCS nor does it alter the BCS
location or orientation with respect to ground. (The principal axes of the inertia tensor
of the CM are referred to as the part principal axes.)
The BCS for each part can have any position and orientation. In fact, the location of the
BCS does not have to be within the physical confines of the part. It may be at some
convenient point outside the actual part boundaries.
To superimpose the BCS of a part on the GCS, define QG=0,0,0 and REULER=0,0,0
or let QG and REULER default. The position and orientation data for the markers on
the part is now with respect to the GCS.
Caution:
Each part defined with the PART statement, with the exception of ground, must have at
least one marker associated with it (see MARKER).
For the argument IP, if one of the moments of inertia (xx, yy, or zz) is specified, the
other two must be specified. Similarly, if one of the products of inertia (xy, xz, or yz) is
specified, the other two must be specified.
Make sure the units for mass moments of inertia and for mass products of inertia are
of forces) must have nonzero masses and/or inertias. You may assign or default zero
mass to a part whose six degrees of motion are fully constrained with respect to parts
that do have mass.
264 Adams/Solver
EXACT, VX, VY, VZ, WX, WY, and WZ arguments ensure that the corresponding
specify more initial displacements to be exact than the system has degrees of freedom.
After you are sure the system has zero or more degrees of freedom, look at the model
and see if the remaining set of part motions will permit Adams/Solver (FORTRAN) to
adjust the system to satisfy all the initial conditions. Remember that IC, ICTRAN, and
ICROT arguments on the JOINT statement remove degrees of freedom from a system
during initial conditions analysis. Similarly, do not specify more initial velocities than
the system has degrees of freedom.
A part without mass cannot have moments of inertia, or initial conditions on
Examples
PART/01, GROUND
This PART statement specifies the mass (2 units), the center-of-mass marker identifier (0201), and the
principal moments of inertia for Part 2 (Ixx = 5 units, Iyy = 6 units, Izz = 10 units). The principal moments
of inertia are about the x-axis (5), the y-axis (6), and the z-axis (10) of the center-of-mass marker. Because
this statement includes no arguments that define the orientation or position of Part 2, Adams/Solver
(FORTRAN) superimposes Part 2 on the ground coordinate system (GCS). This statement identifies no
IM marker, so Adams/Solver (FORTRAN) assumes that the inertias are defined with respect to the part
CM marker.
PART/04, MASS=.5, CM=0407, QG=10,0,0
This statement specifies the mass (.5 units), the center-of-mass marker identifier (0407), and the initial
position of the BCS (10,0,0) with respect to the ground coordinate system (GCS). This statement does
not define the principal moments of inertia, so the inertia of the part is zero about each of the CM marker
axes. In addition, this statement has no arguments to indicate the orientation of Part 4, so Adams/Solver
(FORTRAN) aligns the axes of the BCS of Part 4 with the axes of the ground coordinate system (GCS).
See other Inertia and material data available.
PINPUT 265
Adams/Solver (FORTRAN) Statements
PINPUT
The PINPUT statement defines a list of VARIABLE statements that Adams/Solver (FORTRAN)
recognizes as system input during a LINEAR/STATEMAT analysis (see the LINEAR command).
Format
PINPUT/id, VARIABLES=id1[,id2,...]
[ ] Optionally select the item
Arguments
VARIABLES=id1[,id2,...]
Extended Definition
The PINPUT statement, along with a POUTPUT statement, is used with the LINEAR/STATEMAT
command. PINPUT defines a set of inputs to the mechanical system, and POUTPUT defines the set of
measured outputs from the system. The LINEAR/STATEMAT command linearizes the system equations
to the following form
X = Ax + Bu
y = Cx + Du
where x is the linearized system state array, u is the array of system inputs defined by the PINPUT
statement, and y is the array of system outputs defined by the POUTPUT statement. This form is
commonly referred to as the state space form of the system equations in control theory. Adams/Solver
(FORTRAN) outputs the A, B, C, and D matrices for use in a control-system design or any other linear
system analysis software. If only the A matrix is required, PINPUT and POUTPUT are not necessary.
When you run an analysis type other than LINEAR/STATEMAT, the PINPUT statement acts only as a
pointer to the list of the specified VARIABLE statements.
Both function expressions and user-written subroutines can access the PINPUT statement. Function
expressions access the values by using the internal Adams/Solver (FORTRAN) function PINVAL(i1,i2)
(see the PINVAL function), where i1 specifies the PINPUT id, and i2 specifies the i2th VARIABLE in the
PINPUT statement list. Note that i2 is not the id of the VARIABLE statement.
User-written subroutines call the subroutine SYSFNC to access single elements of the PINPUT list and
call the subroutine SYSARY to access all values for a PINPUT (see the SYSARY and SYSFNC
subroutines).
266 Adams/Solver
Tip:
VARIABLE statements may appear in more than one PINPUT statement. This allows you
to output two or more sets of state matrices at the same time.
Examples
PINPUT/3, VARIABLES=12,13,25
This PINPUT statement identifies VARIABLES 12, 13, and 25 as inputs to the mechanical system. These
variables might appear in expressions for computing actuating forces, for instance. You may refer to this
PINPUT in a LINEAR/STATEMAT command.
Applications
The PINPUT statement along with the POUTPUT, VARIABLE, ARRAY, TFSISO, LSE, and GSE
statements make up the interface between Adams/Solver (FORTRAN) and control design and analysis
packages such as MATRIXx and MATLAB.
As shown in the figure below, PINPUT and POUTPUT act as sockets for input and output to your
controller, organizing the VARIABLE wires.
PINPUT and POUTPUT as Sockets
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 (FORTRAN) model using VARIABLE, ARRAY, TFSISO, LSE, or GSE statements. See
the LINEAR command.
See other Reference data available.
POINT_MASS 267
Adams/Solver (FORTRAN) 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
268 Adams/Solver
Arguments
CM=id
Specifies the identifier of the marker that defines the location of the point mass
relative to the local body coordinate system (BCS).
Default: None
Range: Valid fixed MARKER ids
EXACT=c1:c2:c3
Specifies as many as three point mass coordinates that Adams/Solver should not
change as it iteratively solves for initial conditions which satisfy all constraints.
The three coordinates are below.
x - x coordinate
y - y coordinate
z - z coordinate
These coordinates can be entered in any order following EXACT. These are not
changed by Adams/Solver (FORTRAN) unless the values specified are
inconsistent with initial conditions for a joint or motion.
Default: None
Range: X, Y, or Z
MASS=r
QG=x,y,z
Defines the Cartesian initial coordinates of the BCS with respect to the global
coordinate system.
Default: 0.0, 0.0, 0.0
Range: Any real values
REULER=a,b,c
Defines the 3-1-3 Euler angles that Adams/Solver uses to establish the initial
orientation of the BCS with respect to the coordinate system. The a, b, and c
rotations are in radians and are, respectively, about the z-axis of ground, the new
x-axis, and the new z-axis of the BCS. To input Euler angles in degrees, add a D
after each value.
Defaults: 0.0, 0.0, 0.0 when REULER, XG, and ZG are omitted
Range: Any real values
POINT_MASS 269
Adams/Solver (FORTRAN) Statements
VX=x, VY=y, VZ=z Specifies the initial translational velocities of the CM marker with respect to the
ground coordinate system (GCS) along the x-axis (VX), y-axis (VY), and z-axis
(VZ) of the global coordinate system.
Default: Inexact 0, 0, 0
Range: Any real values
XG=x,y,z
Defines the coordinates, measured in the global coordinate system, of any point
in the positive x-z plane of the part BCS, but not on the z-axis of the part BCS.
Default: If ZG is omitted, XG is oriented like the global x-axis
Range: Any real values
ZG=x,y,z
Defines the coordinates measured in the global coordinate system of any point on
the positive z-axis of the BCS.
Default: If XG is omitted, ZG is oriented like the global z-axis
Range: Any real values
Extended Definition
Although the point mass concept would normally suggest a particle, this is not how a point mass is
implemented in Adams. If a particle is subjected to a torque, a singularity ensues. This was not considered
a practical behavior for an element in Adams.
Rather than thinking of the point mass as a particle think of it as a rigid body with built-in angular
constraints removing any rotational degrees of freedom. It is legal to apply torques to a point mass, and
such torques are simply discarded. If one takes care not to apply a torque, the Adams point mass behaves
exactly like a particle.
270 Adams/Solver
The point mass offers all the computational benefits of a particle without the complications which would
arise from forbidding the application of a torque.
Tip:
All markers on a point mass that are involved in constraints or are at force
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.
See other Inertia and material data available.
POUTPUT 271
Adams/Solver (FORTRAN) Statements
POUTPUT
The POUTPUT statement defines a list of VARIABLE statements that Adams/Solver (FORTRAN)
recognizes as system output during a LINEAR/STATEMAT analysis (see the LINEAR command).
Format
POUTPUT/id, VARIABLES=id1[,id2,...]
[ ] Optionally select the item
Arguments
VARIABLES=id1[,id2,...]
Extended Definition
The POUTPUT statement, along with a PINPUT statement, is used with the LINEAR/STATEMAT
command. POUTPUT defines the set of measured outputs from the system and PINPUT defines a set of
inputs to the mechanical system. The LINEAR command linearizes the system equations to the following
form:
X = Ax + Bu
y = Cx + Du
where:
x is the linearized system state array
u is the array of system inputs defined by the PINPUT statement.
y is the array of system outputs defined by the POUTPUT statement.
This form is commonly referred to as the state space form of the system equations in control theory.
Adams/Solver (FORTRAN) outputs the A, B, C, and D matrices for use in a control-system design or
any other linear system analysis software. If only the A matrix is required, PINPUT and POUTPUT are
not necessary. When you run an analysis type other than LINEAR, the POUTPUT statement acts only as
a pointer to the list of VARIABLE statements specified.
Both function expressions and user-written subroutines can access the POUTPUT statement. Function
expressions access the values by using the internal Adams/Solver (FORTRAN) function POUVAL(i1,i2)
(see the PINVAL function), where i1 specifies the POUTPUT id , and i2 specifies the i2th VARIABLE in
the POUTPUT statement list. Note that i2 is not the id of the VARIABLE.
User-written subroutines access single elements of the POUTPUT list and call the subroutine SYSFNC
to access all values for a POUTPUT by calling the subroutine SYSARY (see the SYSARY and SYSFNC
subroutines).
272 Adams/Solver
Tip:
VARIABLE statements may appear in more than one POUTPUT statement. This allows
you to output two or more sets of state matrices at the same time.
Examples
POUTPUT/4, VARIABLES=4,8,9,10
This POUTPUT statement identifies VARIABLES 4, 8, 9, and 10 as outputs from the mechanical system.
These variables might represent part displacements and velocities, for instance. You may refer to this
POUTPUT in a LINEAR/STATEMAT command.
Applications
The POUTPUT statement with the PINPUT, VARIABLE, ARRAY, TFSISO, LSE, and GSE statements
define the interface between Adams/Solver (FORTRAN) and control design and analysis packages such
as MATRIXx and MATLAB.
As shown in the figure below, PINPUT and POUTPUT act as socket for input and output to your
controller, organizing the VARIABLE wires.
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 (FORTRAN) model using VARIABLE, ARRAY, TFSISO, LSE, or GSE statements. See
the LINEAR command.
POUTPUT 273
Adams/Solver (FORTRAN) Statements
274 Adams/Solver
PREFERENCES
The PREFERENCES statement controls general options that apply to the model defined in the
Adams/Solver (FORTRAN) dataset or the commands defined in the Adams/Solver (FORTRAN)
command file.
Format
PREFERENCES 275
Adams/Solver (FORTRAN) Statements
Arguments
276 Adams/Solver
PTCV 277
Adams/Solver (FORTRAN) Statements
PTCV
The PTCV statement defines a point-to-curve constraint, which restricts a fixed point defined on one part
to lie on a curve defined on a second part. This is an instance of a higher pair constraint.
Format
Arguments
CURVE=id
Specifies the identifier of a CURVE statement that defines the contour or shape on which
the fixed marker can move. The x, y, z values associated with the curve are the
coordinates of points lying on the curve and are calculated in the coordinate system of the
RM marker.
DISP=x,y,z
Specifies the initial point of contact on the curve. If the point specified is not exactly on
the curve, Adams/Solver (FORTRAN) uses a point on the curve nearest to that specified.
By default, DISP is specified in the RM marker coordinate system. If another coordinate
system is more convenient, you may supply the ICM argument and enter DISP in ICM
marker coordinates.
If you supply DISP, Adams/Solver (FORTRAN) assembles the system with the I marker
at the specified point on the curve. If you do not supply DISP, Adams/Solver
(FORTRAN) assumes the initial contact is at the point on the curve closest to the initial I
marker position. However, it may adjust that contact point to maintain other part or
constraint initial conditions.
I=id
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.
278 Adams/Solver
JFLOAT=id Specifies the identifier of a floating marker. Adams/Solver (FORTRAN) positions the
origin of the JFLOAT marker at the instantaneous point of contact on the curve.
Adams/Solver (FORTRAN) orients the JFLOAT marker such that the x-axis is tangent to
the curve at the contact point, the y-axis points outward from the curve's center of
curvature at the contact point, and the z-axis is along the binormal at the contact point.
RM=id
Specifies the identifier of a fixed 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 (FORTRAN) gives the I marker the specified initial
tangential speed along the curve. If you do not supply VEL, Adams/Solver (FORTRAN)
assumes the initial tangential velocity is zero, but may adjust that velocity to maintain
other part or constraint initial conditions.
Default: 0
Extended Definition
The PTCV statement defines a point-to-curve constraint. The part containing the I marker is free to roll
and slide on the curve that is fixed to the second part. Lift-off is not allowed, that is, the I marker must
always lie on the curve.
is located at the contact point on the curve; its orientation is defined by the tangent, normal and binormal
at the contact point (see Figure 5).
Figure 6 shows a schematic of the point-to-curve constraint.
A PTCV statement removes two translational degrees-of-freedom from the system. Adams/Solver
(FORTRAN) restricts the origin of the I marker to always lie on the curve. The I marker may translate
only in one direction relative to the curve, along the instantaneous tangent. The I marker is free to rotate
in all three directions.
PTCV 279
Adams/Solver (FORTRAN) Statements
Figure 5
280 Adams/Solver
Figure 6
Note:
Point-To-Curve Constraint
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.
PTCV 281
Adams/Solver (FORTRAN) Statements
Caution:
VEL is specified relative to the part containing the RM marker. In other words,
VEL is the tangential speed of the I marker relative to the part containing the
curve. This means that if the I marker is stationary relative to ground, but the curve
is moving relative to ground, then VEL is still nonzero.
Adams/Solver (FORTRAN) applies a restoring force tangent to the curve at the
contact point if the contact point moves off the end of an open curve. The
magnitude of the force applied is defined as:
Force = COSH(MIN(200,500*DELTA)) - 1, if DELTA > 0
where DELTA is a normalized penetration of the end of the curve, defined as:
DISP or VEL arguments on the PTCV statements for systems with zero degrees
of freedom.
It is easy to accidentally over-constrain a system using the PTCV constraint. For
This statement creates a point-curve constraint between Marker 201 and a curve on the part containing
floating Marker 301 and fixed Marker 302. CURVE/10 defines the x, y, z coordinates curve in the
coordinate system of Marker 302. Because the statement does not specify initial conditions,
Adams/Solver (FORTRAN) assumes that the initial position of the contact point on the curve is set to be
282 Adams/Solver
the minimum distance between the specified I marker and the curve. Adams/Solver (FORTRAN) also
assumes the velocity of Marker 201 with respect to the curve is zero, meaning it is initially stationary on
the curve. Adams/Solver (FORTRAN) may adjust these assumed initial conditions in order to enforce
other part or constraint initial conditions.
PTCV/55, I=201, JFLOAT=301, CURVE=10, RM=302,
, DISP=2.,3.,0., VEL=-5.
This statement is the same as the last example, except it contains initial conditions. Adams/Solver
assembles the system with Marker 201 at the point on the curve nearest to coordinates (2.,3.,0.) in the
Marker 302 coordinate system. Adams/Solver imposes an initial speed of -5.0 on Marker 201 with
respect to the curve, meaning Marker 201 is moving towards the start of the curve.
Applications
The simplest point-curve constraint application is a pin-slot connection as illustrated in Figure 7 below.
Figure 7
The point-curve constraint keeps the center of the pin in the center of the slot, while allowing it to move
freely along the slot and rotate in the slot. Note that the point-curve constraint does not stop the pin at the
end of the slot. If the travel of the pin must be restricted, a force element, such as an SFORCE with an
IMPACT function, must be used.
A point-curve constraint may also represent a point follower on a cam, where the follower has a very
small radius compared to the curvature of the cam. Figure 8 below illustrates a point follower on a cam.
If the CURVE statement specifies a closed curve, Adams/Solver (FORTRAN) automatically moves the
point across the closure as needed. This means the cam may rotate as many times as needed during the
simulation.
In some cases, the PTCV statement may be used to model a circular follower on a curve. This requires
you to construct a curve offset from the actual profile by a distance equal to the radius of the follower.
Figure 9 illustrates the follower, original profile, and offset curve.
PTCV 283
Adams/Solver (FORTRAN) Statements
Figure 8
Point-Follower Mechanism
Figure 9
To model more complex cam-follower applications, see the CVCV statement. In the CVCV statement,
both the follower and cam can be represented as curves.
Because PTCV is a constraint, the point always maintains contact with the curve, even when the
dynamics of the system would actually lift the point off the profile. You may examine the constraint
forces to determine if lift-off should have occurred. If an accurate simulation of intermittent contact is
required, you should model the contact forces directly using a VFORCE.
Unlike the CVCV statement, the PTCV statement is not restricted to planar curves. PTCV can model
three-dimensional slots and cams, as well as mechanisms riding on nonplanar tracks, or a robot endeffector following a three-dimensional path in space.
See other Constraints available.
284 Adams/Solver
REQUEST
The REQUEST statement indicates a set of data you want Adams/Solver (FORTRAN) to write in the
tabular output file, the request file, and the XML formatted results file. Using a REQUEST statement,
you can output a set of displacements, velocities, accelerations, or forces with respect to markers in the
system. FUNCTION keywords allow you to explicitly define the output variables or employ a userwritten subroutine REQSUB to define nonstandard output.
Format
REQUEST 285
Adams/Solver (FORTRAN) Statements
Arguments
ACCELERATION
Outputs the acceleration of the I marker with respect to the J marker. This
argument generates nine headings and nine columns of output in the tabular output
file. The columns include the time (TIME), the magnitude of translational
acceleration (ACCM), the translational x component (ACCX), the translational y
component (ACCY), the translational z component (ACCZ), the magnitude of
rotational acceleration (WDTM), the rotational x component (WDTX), the
rotational y component (WDTY), and the rotational z component (WDTZ). The
same data without the magnitudes are written to the Request file. Adams/Solver
calculates this acceleration data (the second derivative of the displacement of the
I marker with respect to the J marker) in the global coordinate system. If you
specify RM, Adams/Solver (FORTRAN) resolves the translational x component,
the translational y component, the translational z component, the rotational x
component, the rotational y component, and the rotational z component in the
coordinate system of the RM marker.
CNAMES
(Component Names) Sets one or more strings that identify the names of the result
set components produced by this REQUEST in XML results files.
For example, by default a result set for a request looks like:
<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 want to reduce the memory overhead of the simulation
data.
286 Adams/Solver
COMMENT=c
Specifies a title for the top of each set of information the REQUEST statement
outputs. The entire comment must be on one line. Because input lines can be only
eighty characters long at most, the comment can be from seventy-two characters
long (if you do not abbreviate COMMENT=) to seventy-eight characters long (if
you abbreviate COMMENT= to C=). Blank spaces and all alphanumeric
characters can be used. However, the comma (,), the semicolon (;), the ampersand
(&), and the exclamation point (!) cannot be used. The COMMENT data is printed
in the request file only.
CUNITS
(Component Units) Sets one or more strings that identify the unit dimension of the
result set components in XML result files. If the CUNITS argument is omitted,
then the units of the components are predefined based upon standard request type
(for example, displacement, velocity, and acceleration) or they are considered user
units and no unit conversion will be performed. This argument is mutually
exclusive with the CLABEL argument.
The legal choices for the CUNITS parameter are:
MASS
AREA
TIME
VOLUME
FORCE
TORQUE
LENGTH
PRESSURE
VELOCITY
DENSITY
ACCELERATION
ENERGY
ANGLE
TORSIONAL_STIFFNESS
ANGULAR_VELOCITY
TORSIONAL_DAMPING
ANGULAR_ACCELERATION
FREQUENCY
INERTIA
AREA_INERTIA
STIFFNESS
FORCE_TIME
DAMPING
TORQUE_TIME
REQUEST 287
Adams/Solver (FORTRAN) Statements
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.
DISPLACEMENT
Outputs the displacement of the I marker with respect to the J marker. This
argument generates eight headings and eight columns of output in the tabular
output file. The columns include:
time (TIME)
translational magnitude (MAG)
x component (X)
y component (Y)
z component (Z)
psi angle (PSI)
theta angle (THETA)
the phi angle (PHI)
The same data without the magnitude are written to the request file. The psi, theta,
and phi angles are the Euler angle displacements of the I marker with respect to
the J marker. Adams/Solver (FORTRAN) calculates this displacement data in the
global coordinate system. If you specify RM, Adams/Solver (FORTRAN)
resolves the translational x-component, the translational y component, and the
translational z-component in the coordinate system of the RM marker. RM does
not affect psi, theta, and phi. If the YPR argument is placed in the OUTPUT
statement, the psi, theta, and phi rotations are converted to yaw, pitch, and roll
rotations.
F1=e
Defines the first component of the request that is being specified. If the F1
argument is used, it must either be the last argument in the REQUEST statement
or be followed by a backslash (\) (not a comma). The value of the expression is
written in the corresponding column of the tabular output file.
F2=e
Defines the second component of the request that is being specified. If the F2
argument is used, it must either be the last argument in the REQUEST statement
or be followed by a backslash (\) (not a comma). The value of the expression is
written in the corresponding column of the tabular output file. It is also sent to the
request file.
F3=e
Defines the third component of the request that is being specified. If the F3
argument is used, it must either be the last argument in the REQUEST statement
or be followed by a backslash (\) (not a comma). The value of the expression is
written in the corresponding column of the tabular output file. It is also sent to the
request file.
288 Adams/Solver
F4=e
Defines the fourth 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). The value of the expression is
written in the corresponding column of the tabular output file. It is also sent to the
request file.
F5=e
Defines the fifth component of the request that is being specified. If the F5
argument is used, it must either be the last argument in the REQUEST statement
or be followed by a backslash (\) (not a comma). The value of the expression is
written in the corresponding column of the tabular output file.
F6=e
Defines the sixth 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). The value of the expression is
written in the corresponding column of the tabular output file. It is also sent to the
request file.
F7=e
Defines the seventh component of the request that is being specified. If the F7
argument is used, it must either be the last argument in the REQUEST statement
or be followed by a backslash (\) (not a comma). The value of the expression is
written in the corresponding column of the tabular output file. It is also sent to the
request file.
F8=e
Defines the eighth 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). The value of the expression is
written in the corresponding column of the tabular output file. It is also sent to the
request file.
FORCE
Outputs the force associated with the I and the J markers or, if the I marker and not
the J marker is given, outputs the action-only forces on the I marker. When both
the I and the J markers are given, Adams/Solver (FORTRAN) sums the forces on
the I marker due to the forces associated with the I and the J markers. These forces
can include both applied forces (such as spring dampers and bushings) and
reaction forces from constraint elements (such as joints and motions).
When the I marker and not the J marker is given, Adams/Solver (FORTRAN)
sums all of the action-only forces applied to the I marker. If RM is specified,
Adams/Solver (FORTRAN) reports the components of the resulting vectors in the
reference frame of the RM marker. If RM is not specified, Adams/Solver
(FORTRAN) reports the components in the ground coordinate system (GCS). The
FORCE argument generates nine columns of output in the tabular output file. The
columns include the time, the translational force magnitude, the three components
of the translational force, the rotational force (torque) magnitude, and the three
components of the torque. The same data without the magnitudes are written in the
request file.
REQUEST 289
Adams/Solver (FORTRAN) Statements
FUNCTION=USER{r1[,...,r30]} Defines and passes constants to the user-written subroutine REQSUB to define the
request. Follow FUNCTION with an equal sign, the character string USER, and
the values (r1[,...,r30]) that you want Adams/Solver (FORTRAN) to pass to
REQSUB. If the FUNCTION argument is used, it must either be the last argument
in the REQUEST statement or be followed by a backslash (\). All eight columns
of the data that can be defined in a REQSUB are written in the tabular output file.
Only columns 2, 3, and 4 and columns 6, 7, and 8 are written in the request file.
I=id, J=id
RM=id
Identifies the marker with respect to which you want to resolve information.
Adams/Solver (FORTRAN) computes the data identified by the I marker and the
J marker, then reports the data as x, y, and z components in the reference frame of
the RM marker. Angular displacements, which are not vectors, are not affected by
RM. RM defaults to zero, which causes Adams/Solver (FORTRAN) to resolve
components in the ground coordinate system (GCS).
RESULTS_NAME
Specifies the name of the result set in which all result set components produced by
this request are placed when the result file is written in XML. If there is an existing
result set with this name, then the result set components are placed in that result
set. If there isn't an existing result set, then a new one is created and all the result
set components are placed there.
This is helpful if you wish to group the output from multiple requests into a single
result set. For example, you might have several different requests measuring driver
input for a vehicle, and you might wish to place them all within a result set named
Driver_Inputs for easier viewing in Adams/PostProcessor.
ROUTINE=libname::subname
Specifies an alternative library and name for the user subroutine REQSUB.
Learn more about the ROUTINE Argument.
290 Adams/Solver
TITLE=c1:...:c8
VARIABLES
VELOCITY
Outputs the velocity of the I marker with respect to the J marker. This argument
generates nine headings and nine columns of data for velocity. The nine columns
in the tabular output file include:
time (TIME)
translational magnitude (VM)
translational x component (VX)
translational y component (VY)
translational z component (VZ)
rotational magnitude (WM)
rotational x component (WX)
rotational y component (WY)
rotational z component (WZ)
The same data without the magnitudes are written in the request file.
Adams/Solver (FORTRAN) calculates this velocity data (the first derivative of the
displacement of the I marker with respect to the J marker) in the global coordinate
system. If you specify RM, Adams/Solver (FORTRAN) resolves the translational
and rotational velocities vector in the coordinate system of the RM marker.
Extended Definition
The REQUEST statement indicates a set of data you want Adams/Solver (FORTRAN) to write in the
request file. REQUEST is also printed in the result file if the XRF option was selected in the RESULTS
statement. Using a REQUEST statement, you can output a set of displacements, velocities, accelerations,
or forces with respect to markers in the system. FUNCTION keywords allow you to explicitly define the
output variables or employ a user-written subroutine REQSUB to define nonstandard output.
REQUEST 291
Adams/Solver (FORTRAN) Statements
Adams/Solver (FORTRAN) calculates all time derivatives in the ground coordinate system (GCS),
although you can specify that the data be resolved in another reference frame. This is of no importance
in the case of force data, but it can be very important in the case of velocities and accelerations. For
example, joint velocities are actually translational and rotational velocity difference vectors of the joint
I marker and the joint J marker in ground. Joint accelerations are actually translational and rotational
acceleration difference vectors of the joint I marker in ground and the joint J marker in ground. When
requesting force information, you must specify the identifiers of markers on which there are forces. The
forces on these markers can be either applied or reaction forces.
Adams/Solver (FORTRAN) writes REQUEST data to the tabular output file. The OUTPUT statement
contains several options controlling the format of the output. If you include an OUTPUT statement with
the REQSAVE argument, Adams/Solver (FORTRAN) also writes REQUEST data to the Request file.
You may load the request file into Adams/PostProcessor and plot the request data.
Tip:
Note that the units for rotational displacement data in the request output of the tabular
output file default to degrees. The units for all other angular output data default to
radians.
Adams/Solver (FORTRAN) outputs UCON reaction forces only to the results file. If
you wish UCON forces information, you must include a RESULTS statement in the
dataset.
You only need to enter as many of the eight function expressions F1,...,F8 as required.
Caution:
Applied forces and torques are those generated by beams, bushings, fields, general
292 Adams/Solver
Reaction forces and torques are those generated by constraint-inducing elements. For
revolute, spherical, and universal joints and for atpoint, orientation, parallel axes, and
perpendicular joint primitives, Adams/Solver (FORTRAN) outputs the reaction forces
and torques acting at the request I marker (which may be either the constraint I marker
or the constraint J marker). The force and torque acting at the request J marker are
equal and opposite to the force and torque acting at the request I marker. Depending on
the type of constraint, some or all of the torques acting at the I marker are zero.
Determining reaction forces and torques for cylindrical, planar, rack-and-pinion, screw,
and translational joints and for inline and inplane joint primitives is more complex.
If the request I marker corresponds to the constraint I marker, then Adams/Solver
(FORTRAN) outputs the force and torque acting at the constraint I marker. If the
request I marker corresponds to the constraint J marker, then Adams/Solver
(FORTRAN) outputs the force and torque acting at the instantaneous location of the
constraint I marker, but on the part containing the constraint J marker. The force
translated to the constraint J marker is the same as computed above. If the I and the J
markers are coincident, the torque translated to the constraint J marker is the same as
computed above. But if there is a finite separation between the I and the J markers, the
torque translated to the constraint J marker is different from the one computed above
(because of the moments contributed by the reaction forces).
Rotational displacement information differs from all other standard output. Whether
this information is in psi, theta, and phi coordinates or in yaw, pitch, and roll
coordinates, the rotation sequence is not a vector. As a result, no magnitude column is
in the output. In addition, the sequence of coordinates is independent of any frame
external to the I and the J markers. Therefore, the RM argument has no effect on the
angular coordinates.
You must be careful when requesting a force with the I and the J markers reversed from
REQUEST 293
Adams/Solver (FORTRAN) Statements
When computing velocity and acceleration for a marker pair that includes a floating
request file. To plot requests from the Request file, you should not use F1 or F5.
Adams/Solver (FORTRAN) writes output for F1 and F5 to the tabular output file and
the results file.
Examples
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, eight headings,
and eight columns of data to the tabular output file. The information is duplicated in the request file.
REQUEST/08, FORCE, I=0304, J=0204
, COMMENT=ROD/CRANK REACTION
This REQUEST statement requests data for an action-reaction force on Marker 0304 from Marker 0204.
Adams/Solver outputs the comment ROD/CRANK REACTION, nine headings, and nine columns of
data to the tabular output file. The information is duplicated in the request file.
REQUEST/21, F2=VARVAL(1)/ F3=DIF1(1)*5/ F4=DX(2109,409)/
, TITLE=NULL:VAR 1:DERIV5:DISP:NULL:NULL:NULL:NULL
This REQUEST statement requests the value of VARIABLE/1 to be placed in the second column, the
first time derivative of DIFF/1 multiplied by five to be placed in the third column, and the x component
of the displacement of Marker 2109 relative to Marker 409 to be placed in the fourth column. The titles
for the eight columns from left to right are: NULL, VAR_1, DERIV5, DISP, NULL, NULL, NULL,
NULL.
REQUEST/1, DISPLACEMENT, I=100, J=102
,CNAMES="", X_100, Y_100
,RESULTS_NAME=PQT
REQUST/2, DISPLACEMENT, I=200, J=202
,CNAMES="", X=200, Y=200
,RESULTS_NAME=PQT
If using XML, these two REQUEST statements generate a combined result set named "PQT" containing
only 4 channesl names X_100,Y_100, X_200 and Y_200. The result set would look as follows:
<entity name="PQT" objectId="25">
<component name="X_100" id="67"/>
<component name="Y_100" id="68"/>
<component name="X_200" id="69"/>
<component name="Y_200" id="70"/>
</entity>
294 Adams/Solver
Instead of generating 2 result sets with 8 channels each (default XML behaviour), only one result set with
4 channels is created.
Applications
Requests are used whenever a particular output is desired from Adams/Solver (FORTRAN). The output
generated from the request can be in two forms: a tabular output file for tables and a request file that
contains data needed for plotting in a postprocessor. The writing of these files is controlled by the
OUTPUT statement.
When you are interested in a series of requests that are quite similar, MREQUEST may be easier to use.
This statement is very similar to the REQUEST statement, but allows a shorthand method of statement
entry.
A third alternative is the RESULTS statement, which causes all the results for the analysis to be saved to
a results file (see RESULTS). This file can then be used in a postprocessor. The major drawbacks to using
the RESULTS statement is the size of the file, and having the data in a form that needs to be translated
by a postprocessor.
When using a REQUEST statement, you must also have an OUTPUT/REQSAV statement in order to
create a request file (.req). The request tables in the tabular output file (.out) are written regardless of the
existence of the OUTPUT statement.
Data from certain Adams/Solver (FORTRAN) statements is accessible only through the request
functions (F1,...,F8). The statements include PINPUT, POUTPUT, VARIABLE, ARRAY, LSE, GSE,
TFSISO, and DIFF. To request information on PINPUT, POUTPUT, ARRAY, or VARIABLE, you
should write the function expression referencing PINVAL, POUVAL, ARYVAL, and VARVAL,
respectively. To request information on LSE, GSE, TFSISO, you should write the function expression
referencing ARYVAL. To request information on DIFF, you should write the function expression
referencing DIF for the value of the independent variable associated with a user-defined differential
equation, and DIF1 for the value of the time derivative of the independent variable of the user-defined
differential equation.
See other Output available.
RESULTS 295
Adams/Solver (FORTRAN) Statements
RESULTS
The RESULTS statement creates a results file that includes all the simulation output from Adams/Solver
(FORTRAN). The results file can be either unformatted (binary) or formatted (ASCII).
Format
296 Adams/Solver
Arguments
COMMENT=c
DECIMALPLACES=i
FORMATTED
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.
RESULTS 297
Adams/Solver (FORTRAN) Statements
NOREACTIONFORCES
NOREQUESTS
Specifies that the results file not include request output. The default is
a results file that includes user-defined request, in the case of a classic
results file, or all request data (in the case of an XML-formatted
results file (XRF)).
NOSYSTEMELEMENTS
Specifies that the results file is not to include results for system
modeling elements such as user-defined differential equations, linear
state equations, general state equations, and transfer functions. The
default is a results file that contains results for system modeling
elements.
NOTIRES
Specifies that the results file is not to include results for tires. The
default is a results file that contains results for tires.
NOVELOCITIES
Specifies that the results file is not to include part velocities. The
default is a results file that includes part velocities.
ROUNDOFF
298 Adams/Solver
TRAILINGZEROS
XRF
ZEROTHRESHOLD=r
Extended Definition
The RESULTS statement creates a results file that includes selections of output from an Adams/Solver
(FORTRAN) simulation. This all-purpose file can contain all the simulation output from Adams/Solver
(FORTRAN). The results file can contain any combination of the following information:
Displacements - Displacements of the BCS with respect to ground and resolved in the ground
GCS.
Applied forces - Forces on the I marker applied by Adams/Solver (FORTRAN) force elements,
modeling elements such as user-written differential equations, linear state equations, general
state equations, and transfer functions.
Tires - Displacements, velocities, accelerations, forces, and other information about tires.
Floating markers - Displacements of floating markers.
RESULTS 299
Adams/Solver (FORTRAN) Statements
Linear - Eigenvectors, eigenvalues, and state matrices computed by a linear analysis invoked by
The title specified in the COMMENT argument helps identify the results file. If
(FORTRAN) during a simulation, they may become quite large. The NO...
arguments should be used to remove unwanted output and conserve disk space.
Caution:
Examples
RESULTS/FORMATTED, NODATASTRUCTURES, NOSYSTEMELEMENTS
RESULTS/NODISPLACEMENTS, NOVELOCITIES
,NOACCELERATIONS, NODATASTRUCTURES
,NOSYSTEMELEMENTS, NOLINEAR
,NOFLOATINGMARKERS, NOTIRES
300 Adams/Solver
SENSOR
The SENSOR statement is used to modify the simulation when a user-defined event occurs during runtime. The event is defined by a logical expression which compares an expression to a target value. If the
logical expression becomes true during the simulation, the sensor modifies the simulation by the means
described below.
Format
SENSOR 301
Adams/Solver (FORTRAN) Statements
Arguments
CODGEN
DT=r
EQ
ERROR=r
302 Adams/Solver
EVALUATE =
USER ( r 1 [ ,, r 30 ] )
Specifies an expression or defines and passes constants to a userwritten subroutine that is evaluated when the event Adams/Solver
(FORTRAN) is monitoring becomes true. The scalar value of the
expression or the return value of the user-written subroutine can
then be obtained using the SENVAL function expression.
If you want to define the evaluated function with an expression,
EVALUATE must be followed with an equal sign and the
expression. If you want to define the evaluated function with a usersubroutine, FUNCTION must be followed with an equal sign, the
character string USER, and the selected values (r1[,...,r30]) that
Adams/Solver (FORTRAN) passes to the user-written subroutine
SEVSUB.
If the EVALUATE argument is used, it must either be the last
argument in the SENSOR statement or be followed by a backslash
(\).
EVALUATE_ROUTINE=libname::subname
FUNCTION =
USER ( r 1 [ ,, r 30 ] )
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 user-written subroutine, follow
FUNCTION with an equal sign, the character string USER, and the
values (r1[,...,r30]) that you want Adams/Solver (FORTRAN) to
pass to the user-written subroutine SENSUB. If the FUNCTION
argument is used, it must either be the last argument in the SENSOR
statement, or be followed by a backslash (\).
Default: None
Range: An expression or user-parameter list of 1 to 30 real values
GE
HALT
SENSOR 303
Adams/Solver (FORTRAN) Statements
LE
Writes data to the request, graphics, and output files when the event
Adams/Solver (FORTRAN) is monitoring becomes true.
Default: Off
RESTART
RETURN
Stops the simulation and returns to the command level when the
event Adams/Solver (FORTRAN) is monitoring becomes true.
Default: Off
ROUTINE=libname::subname
304 Adams/Solver
VALUE=r
YYDUMP
The SENSOR statement defines a user-defined event that affects a set of simulation controls when the
event occurs. The event is defined by a logical expression that compares a function expression (or
evaluation of a user-written subroutine) to a target value using a relational operator. If the logical
expression becomes true during the simulation, the sensor modifies a set of simulation controls, which
include output and integration step sizes, simulation end time, and the Jacobian pivot sequence. A sensor
can also output diagnostic information and store the value of a function expression for later recall.
The Adams/Solver (FORTRAN) evaluates the logical expression after every successful integration step
when doing dynamic analysis and after every successful output step when doing other types of analyses.
To define the function, use a function expression or a user-written subroutine. More information on valid
function expressions. User-written subroutines and utility subroutines discuss the subroutines they can
access.
Caution:
adjust the step size to find the exact time when the sensor becomes active. This process is
inaccurate and time consuming when the function is discontinuous. For that reason,
functions of time or displacements work best for sensors; functions of velocities,
accelerations, and forces are less desirable.
Adams/Solver (FORTRAN) tests the sensor after every successful time step during dynamic
analyses and after every output step during other analyses. If the sensor becomes active,
Adams/Solver (FORTRAN) modifies the simulation control accordingly and does not test
the sensor again until it has completed three time steps. Then, Adams/Solver (FORTRAN)
again tests the sensor after every time step.
SENSOR 305
Adams/Solver (FORTRAN) Statements
If you want Adams/Solver (FORTRAN) to take an action, make sure to include one of the
(FORTRAN) integrator may not produce reliable accelerations and velocities for the first
two or three internal integration steps. Adams/Solver (FORTRAN) automatically corrects
for this, so that the values returned at the first output step are accurate. A SENSOR,
however, that depends on the accelerations or reaction forces due to this motion may trip
unexpectedly prior to the first output step, even though the solution appears correct when the
SENSOR is removed. If this occurs, you should modify the displacement function in the
MOTION statement so that the initial accelerations are zero.
In some cases, Adams/Solver (FORTRAN) may not be able to use the specified STEPSIZE.
If this step size gives poor convergence or generates too much error,
specified step size steps past the next output step, Adams/Solver (FORTRAN) reduces
the step size to reach the output step exactly.
If the specified step size is larger than HMAX, Adams/Solver (FORTRAN) uses
HMAX.
If the specified step size is smaller than HMIN, and you specify RESTART, the value of
SENSOR, especially if the specified error is very small. In these cases, Adams/Solver
(FORTRAN) may appear to pass through the sensed value without invoking the sensor
action. If this occurs, you should try increasing the error tolerance, if possible. An
alternative is to change to an inequality (GE or LE) sensor, then DEACTIVATE the sensor
after it has triggered.
Examples
SENSOR/231, FUNCTION=DX(0201,0307)/
,VALUE=3.24, RETURN
This SENSOR statement senses the x-component for the displacement of Marker 0201 with respect to
Marker 0307 and resolves the displacement in the ground coordinate system (GCS). When the relative x
displacement equals 3.24 (+/_ 0.001), the statement stops the simulation and returns to the command
level.
See other Analysis parameters available.
306 Adams/Solver
SFORCE
The SFORCE statement applies a single-component force or a torque to one or both of the parts it
connects.
Format
Arguments
ACTIONONLY
FUNCTION =
USER ( r 1 [ ,, r 30 ] )
SFORCE 307
Adams/Solver (FORTRAN) Statements
I=id, J=id
You can use the same marker for both the I and J markers
when you are specifying an action-only SFORCE. For
example, you would do this when specifying rocket
thrust forces.
ROTATION
Designates a rotational force, that is, a torque. For an actionreaction torque, the z-axes of the I and the J markers must be
parallel and must point in the same direction. Adams/Solver
(FORTRAN) applies a torque about each z-axis. By definition, the
right-hand rule defines a positive torque.
ROUTINE=libname::subname
TRANSLATION
Extended Definition
The SFORCE statement applies a force or torque to two parts. You specify a marker on each part for force
or torque application. The magnitude of the force may be defined as a function of any combination of
displacements, velocities, other applied forces, user-defined variables, and time. An SFORCE statement
can apply action-reaction forces or can apply action-only forces.
For translational action-reaction forces, Adams/Solver (FORTRAN) applies an action and reaction force
along the line connecting the I and the J markers. The force exerted on I is directed from J toward I, while
the force exerted on J is directed from I toward J. The magnitude of each is specified in the FUNCTION
argument.
For translational action-only forces, Adams/Solver (FORTRAN) applies the force on the I marker only.
There is no reaction on the J marker. The force on the I marker is directed along a vector parallel to and
co-directed with the z-axis of the J marker.
308 Adams/Solver
For rotational action-reaction forces, Adams/Solver (FORTRAN) applies an action torque on the I
marker about the z-axes of the I marker and a reaction torque on the J marker about the z-axis of the J
marker. Furthermore, Adams/Solver (FORTRAN) assumes that the z-axes of the I and the J markers are
parallel.
For rotational action-only forces, Adams/Solver (FORTRAN) applies the torque on the I marker only.
There is no reaction on the J marker. The torque on the I marker is applied about a vector parallel to and
co-directed with the z-axis of the J marker.
You write a function expression or a user-written subroutine (SFOSUB) to define the constitutive
equation for the force applied at the I marker. Adams/Solver (FORTRAN) evaluates the reaction forces
at the J marker.
Tip:
value of the FUNCTION argument) between two markers causes them to repel
each other and a negative force causes them to attract each other.
Caution:
For rotational action-reaction SFORCEs, the z-axes of the I and the J markers must be
parallel and pointed in the same direction. If they are not, the results are unpredictable and
may differ between Adams/Solver (C++) and Adams/Solver (FORTRAN).
Examples
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 action-reaction, compression-only 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= k0 + k1(x-1) + k2(x-1)2 + cx'
where k0 is a static preload, x is the instantaneous length of the translational spring, x' is the time
derivative of x, l is the natural, unstretched spring length, k1 and k2 are stiffness coefficients, and c is a
SFORCE 309
Adams/Solver (FORTRAN) Statements
damping coefficient. This equation representing the force magnitude can be rewritten in the following
polynomial format:
2
F =
kj ( x l )
+ cx'
j=0
If k0 = -10.1, k1 = 15.2, k2 = 4.1, c = 1.5, and l = 3.142, then the Adams/Solver (FORTRAN) statement
that represents this translational spring acting between two parts containing Markers 12 and 34,
respectively, appears as
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 (FORTRAN) interprets the value of the FUNCTION
argument as the magnitude of the repelling force between two markers; hence, a negative sign was
prepended to the attracting force expression defined earlier.
See other Forces available.
310 Adams/Solver
SPLINE
The SPLINE statement defines discrete data that Adams/Solver (FORTRAN) interpolates using the
AKISPL and CUBSPL function expressions and the AKISPL and CUBSPL data-access subroutines. A
SPLINE statement provides one or two independent variables and one dependent variable for each data
point you supply.
If you are licensed to use the Adams/Durability plugin, the SPLINE statement includes arguments to
perform durability analyses. These arguments are explained in the following pages along with the
standard arguments.
Format
SPLINE/id
,X = x1, x2, x3, x4 [, ..., xn]
,Y = y1, y2, y3, y4 [, ..., yn]
[, XUNITS = string ]
[, YUNITS = string ]
[, UNITS = string ]
[, LINEAR_EXTRAPOLATE]
or
SPLINE/id
,X = x1, x2, x3, x4 [, ..., xn]
,Y = z1, y11, y12, y13, y14 [, ..., y1n]
,Y = z2, y21, y22, y23, y24 [, ..., y2n]
,Y = z3, y31, y32, y33, y34 [, ..., y3n]
,Y = z4, y41, y42, y43, y44 [, ..., y4n]
[, ..., Y = zm, ym1, ym2, ym3, ym4 [, ..., ymn]]
[, XUNITS = string ]
[, YUNITS = string ]
[, ZUNITS = string ]
[, UNITS = string ]
[, LINEAR_EXTRAPOLATE]
or
SPLINE 311
Adams/Solver (FORTRAN) Statements
SPLINE/id
, FILE = filename
[, BLOCK = blockname]
[ , CHANNEL = id ]
[, XUNITS = string ]
[, YUNITS = string ]
[, UNITS = string ]
[, LINEAR_EXTRAPOLATE]
Arguments
BLOCK
Specifies the use of a particular, named block within a file. The BLOCK
argument is optional, and requires the FILE argument.
CHANNEL
FILE
Specifies the use of a file, rather than the X and Y arguments, to supply data
for the SPLINE. FILE causes Adams/Solver (FORTRAN) to call the 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 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.
312 Adams/Solver
X=x1,x2,x3,x4[ , . . . ,
xn]
Y=y1,y2,y3,y4 [ , . . . ,
yn]
Y=z1,y11,y12,y13,y14
[ , . . . , y1n]
,Y=z2,y21,y22,y23,y2
4 [ , . . . , y2n]
,Y=z3,y31,y32,y33,y3
4 [ ,ym1,ym2,ym3,ym4
[ , . . . , ymn]]
UNITS
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)
SPLINE 313
Adams/Solver (FORTRAN) Statements
Extended Definition
Adams/Solver (FORTRAN) applies curve-fitting techniques that interpolate between data points to
create a continuous function. If the SPLINE data has one independent variable, Adams/Solver
(FORTRAN) uses a cubic polynomial to interpolate between points. If the SPLINE data has two
independent variables, Adams/Solver (FORTRAN) uses a cubic method to interpolate between points of
the first independent variable, and then uses a linear method to interpolate between curves of the second
independent variable.
The next sections explain more about using the SPLINE statement:
Using the Spline Function
Spline Function Interpolation Methods
Using SPLINE with Adams/Durability
To use discrete data input with a SPLINE statement, you must write either a function expression that
includes one of the two Adams/Solver (FORTRAN) spline functions (AKISPL and CUBSPL) or a userwritten subroutine that calls one of the two spline data-access subroutines (AKISPL and CUBSPL).
Spline Function Interpolation Methods
The SPLINE functions and data-access subroutines use two different interpolation methods: the Akima
method and a traditional cubic interpolation method.
The AKISPL function and the AKISPL subroutine use the Akima method of interpolation. This
314 Adams/Solver
To use DAC or RPC III data that is specified in a SPLINE statement as input to Adams/Solver
(FORTRAN), you must write a function expression that includes the INTERP function. For more on how
to use the Adams/Durability INTERP function, see the INTERP function.
Tip:
Caution:
The x and z data must cover the anticipated range of values. However, the following
situations sometimes cause Adams/Solver (FORTRAN) to evaluate a spline outside of its
defined range:
Adams/Solver (FORTRAN) occasionally approximates partial derivatives using a
The set of values in the table below relates the force in a spring to its deformation.
Data Relating Spring and Spring-Deflection Force
Deflection
Force
-0.33
-38.5
-0.17
-27.1
-0.09
-15.0
0.0
0.0
0.10
10.0
025
30.0
0.40
43.5
0.70
67.4
SPLINE 315
Adams/Solver (FORTRAN) 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 (FORTRAN) creates a continuous function
that relates deflection and force. This continuous approximation can evaluate the value of the spring force
at a deflection of -0.25. If you input two sets of values (X and Y) with the SPLINE statement, then
Adams/Solver can effectively define the function as a curve. The following example illustrates how the
SPLINE statement is used to store the discrete data in the table above.
SPLINE/01,
, X=-0.33,
, Y=-38.5,
, XUNITS =
, YUNITS =
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 (FORTRAN) to interpolate
a value of Y for any value of X. It also specifies that the X values are of type length and Y values are
of type force.
The set of values in the table below details a set of nonlinear, force-deflection relationships of a spring at
various temperatures.
Data Relating Spring Force to Spring Deflections at Various Temperatures
20
30
40
50
-0.33
-38.5
-36.0
-30.0
-25.1
-0.17
-27.1
-25.4
-21.7
-18.6
-0.09
-15.0
-13.1
-9.6
-4.4
0.0
0.0
0.0
0.0
0.0
0.1
10.0
9.1
7.5
4.6
0.25
30.0
26.4
21.3
17.8
0.40
43.5
37.9
34.1
27.1
0.70
67.4
60.3
53.2
46.3
From table above, you can determine force when deflection equals -0.33 and when temperature equals
20. You can also determine force when deflection equals -0.17 and when temperature equals 30.
However, what is the force when deflection equals -0.25 and when temperature equals 25?
To determine the force at any deflection and temperature, you need to define a set of continuous functions
that generally relate force to deflection and temperature. If deflection is the independent x value and
temperature is the independent z value, you can define a set of functions in a family of curves using the
SPLINE statement. The SPLINE statement for this example is shown next:
316 Adams/Solver
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
(FORTRAN).
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 z-axis of
Marker 401 using a function expression.
The function expression for the MOTION statement references data from the SPLINE statement using
the INTERP function. The test data from the DAC file is known to be acquired in degrees, and since
Adams/Solver (FORTRAN) expects rotational motion to be specified in radians, a conversion from
degrees to radians (factor DTOR) is also included in the function expression.
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.
SPRINGDAMPER 317
Adams/Solver (FORTRAN) Statements
SPRINGDAMPER
The SPRINGDAMPER statement applies a rotational or a translational springdamper between two
markers.
Format
Arguments
ANGLE=r
Defines the reference angle for the torsional spring. If the reference torque of the
spring is zero, ANGLE equals the free angle. Adams/Solver (FORTRAN)
assumes ANGLE is in radians unless a D is added after the value.
Default: 0
C=r
Specifies the viscous damping coefficient for the force. The force due to damping
is zero when the system is at rest.
Range: C > 0
CT=r
Specifies the viscous damping coefficient for the torque. The torque due to
damping is zero when the system is at rest. CT must be in units of torque per
radian per unit of time.
Range: CT > 0
FORCE=r
318 Adams/Solver
I=id, J=id
Specifies the identifiers of the two markers between which the force or the torque
is to be exerted.
K=r
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
TORQUE=r
The force value is the force on the I marker applied by the J marker; the force on the J marker is equal
and opposite. The term b is the distance between the I and the J markers. Adams/Solver (FORTRAN)
assumes that b is always greater than zero. Adams/Solver (FORTRAN) automatically computes the terms
db/dt and b. The following linear constitutive equation describes the torque applied at the I marker:
Ta = -CT (da/dt) - KT(a-ANGLE) + TORQUE
The torque value is applied to the I marker about the positive z-axis of the I marker; the torque on the J
marker is equal and opposite to the torque on the I marker. The right-hand rule defines a positive torque.
The term a is the angle of the I-marker x-axis relative to the J-marker x-axis, measured about the J-marker
SPRINGDAMPER 319
Adams/Solver (FORTRAN) Statements
z-axis. Adams/Solver (FORTRAN) takes into account the total number of complete rotations.
Adams/Solver (FORTRAN) automatically computes the terms da/dt and a.
Caution:
If the z-axis of the I marker is not parallel to, and/or not pointed in the same
direction as, the z-axis of the J marker for a rotational springdamper, the results are
unpredictable.
Since the line-of-sight method determines the direction of a translational
This SPRINGDAMPER statement describes a force that Marker 30 applies to Marker 25. Marker 25 also
applies a force of equal magnitude and opposite direction to Marker 30. The argument TRANSLATION
indicates that this is a translational springdamper, rather than a rotational one. Therefore, the magnitude
of the force is proportional to the spring free length, to the distance between the two markers, and to the
time rate of change of the distance between the two markers. The L argument indicates that the spring
free length is 0.01 length units (L is the free length because the FORCE argument defaults to zero). The
spring constant K is 5 force units per unit length, and the damping constant C is 0.1 force units-seconds
per unit length.
See other Forces available.
320 Adams/Solver
STRING
The STRING statement defines a character string that may be referred to later in the execution of
Adams/Solver. An interactive STRING command can be used to alter or review this character string. A
GTSTRG subroutine can be used to retrieve this character string in a user-written subroutine.
Format
STRING/id, STRING=c
Arguments
STRING=c
Caution:
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.
The following characters are not permitted in a STRING argument because they are
delimiters in the Adams/Solver command language: comma (,), semicolon (;), ampersand
(&), and exclamation point (!). This is because the comma indicates that additional
Adams/Solver arguments follow; the semicolon indicates that additional Adams/Solver
statements follow on the same line; the ampersand indicates that the next line is a
continuation of the statement on this line; and the exclamation point indicates that
Adams/Solver is to stop reading the line.
Examples
STRING/101, STRING=MARKER=
This STRING statement enters the character string MARKER= for later reference. The GTSTRG
subroutine can retrieve this string.
See other Reference data available.
TFSISO 321
Adams/Solver (FORTRAN) Statements
TFSISO
The TFSISO (Transfer Function, Single-Input, Single-Output) statement defines a single-input, singleoutput transfer function as a ratio of two polynomials in the Laplace domain when used with the
associated ARRAY statements.
Format
Arguments
DENOMINATOR
=a0[,...,a29]
NUMERATOR=b0 Specifies the coefficients of the polynomial in the numerator of the transfer
[,...,b29]
function. Coefficients are listed in order of ascending powers of s, starting with s
to the zero power, including any intermediate zero coefficients. The number of
coefficients for the numerator must be less than or equal to the number of
coefficients for the denominator.
STATIC_HOLD
Indicates that the TFSISO states are not permitted to change during static and
quasi-static analysis.
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.
322 Adams/Solver
X=id
Designates the ARRAY statement in the dataset that is used to define the state
variable array for the transfer function. You must have an ARRAY statement with
this identifier in the dataset; it must be of the X type; and it may not be used in any
other LSE, GSE, or TFSISO statement. If you specify the SIZE of the X ARRAY,
it must be one less than the number of coefficients in the denominator.
Y=id
Designates the ARRAY statement in the dataset that is used to define the output for
the transfer function. You must have an ARRAY statement with this identifier in
the dataset; it must be of the Y type; and it may not be used in any other LSE, GSE,
or TFSISO statement. If you specify the SIZE of the Y ARRAY, it must be 1.
Extended Definition
The TFSISO (Transfer Function, Single-Input, Single-Output) statement is designed to model a linear,
time-invariant dynamic system defined in the Laplace domain, especially to facilitate the import of
elements from control-system block diagrams. It can also be used, however, to define an arbitrary set of
constant-coefficient, differential and algebraic equations which can be expressed in the Laplace domain
as
b0 + b1 s 1 + + bm s m
y--------( s )= ----------------------------------------------------G(s) =
u(s)
a0 + a1 s 1 + + ak s k
where m < k
The TFSISO follows standard control systems terminology, where x is the state variable array, y is the
output variable, and u is the input variable. Initial conditions are assumed to be identically zero. In the
Adams/Solver (FORTRAN) dataset, each of these arrays is defined using an ARRAY statement. The
characteristic equation for a single TFSISO statement, defined by the DENOMINATOR argument, can
be a polynomial of degree less than 30.
Internally to Adams/Solver (FORTRAN), there is an algorithm to automatically convert the list of fixed
numerator and denominator coefficients to a canonical state-space form; that is, a set of coupled, linear,
constant-coefficient differential equations and a single algebraic equation.
When you reference only the output of the TFSISO, the details of the internal equations are unimportant.
In some cases, however, it may be useful to understand how Adams/Solver (FORTRAN) constructs the
equations. When interpreting Adams/Linear output or examining the values in the X ARRAY, for
instance, it may be necessary to determine what the internal states represent.
The conversion from transfer function to canonical state-space form is done in two steps. First, the
numerator and denominator are normalized by the coefficient of the largest power of s in the
denominator.
q = [b0/ak,b1/ak,...,bm/ak,0,...,0,0]
p = [a0/ak,a1/ak,...,ak-1/ak,1]
TFSISO 323
Adams/Solver (FORTRAN) 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:
q0 + q1 s1 + + qk sk
y(s)
G ( s ) = ---------- = --------------------------------------------------u(s)
p0 + p1 s1 + + pk sk
The equivalent state space realization of this transfer function is:
x
A B x
=
C D y
y
where:
A =
pk 1 1 0 . . . 0 0
qk 1 pk 1 qk
pk 2 0 1 . . . 0 0
qk 2 pk 2 qk
.
.
.
.
.
.
p1 0
.
.
.
0
1
.
.
.
.
.
.
.
.
.
.
.
.
.
1
0
.
.
.
1
B =
po 0 0 . . . 0 0
C =
Note:
Tip:
100...00
.
.
.
q1 p1 qk
qo po qk
D =
qk
Except in the specific case where the numerator and denominator are of equal orders, qk= 0.
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
324 Adams/Solver
Caution:
or multiple solutions (this is possible because of the general nature of the input
ARRAY), Adams/Solver (FORTRAN) most likely fails to converge or possibly
converge to an unexpected answer. You can avoid this possibility by not
referencing the X (state) or Y (output) ARRAYs in the definition of the
VARIABLE in the U (input) ARRAY.
You must be sure to list the coefficients in order of increasing powers of s. Some
texts and programs use the opposite convention, listing coefficients in order of
decreasing powers of s.
Adams/Solver (FORTRAN) does not check for pole-zero cancellation in the
TFSISO numerator and denominator. In this case, the canonical transform used in
Adams/Solver leads to an unobservable but controllable state space realization.
Adams/Solver (FORTRAN) models containing such elements when tested for
observability in control design software are indicated having some unobservable
portions. You should perform any pole-zero cancellation prior to defining the
TFSISO data.
During a static analysis, Adams/Solver (FORTRAN) finds equilibrium values for
retained as the static equilibrium values. Thus, the final equilibrium values are the
same as the user-specified initial conditions. Note that this does not guarantee that
the time derivatives of the user-defined variable are zero after static analysis.
Examples
ARRAY/100, X
ARRAY/101, U, VARIABLE=101
ARRAY/102, Y
VARIABLE/101, FUNCTION=ACCZ(5,99,5)
TFSISO/100, X=100, U=101, Y=102,
, NUMERATOR=1.0, DENOMINATOR=100.0,10.0,1.0
TFSISO 325
Adams/Solver (FORTRAN) Statements
1
G ( s ) = ---------------------------------2
s + 10s + 100
ARRAY/100 is the state array. ARRAY/101 is the input array. ARRAY/102 is the output array.
VARIABLE/101 defines the input.
Applications
The TFSISO statement may be most useful for adding feedback controls to an Adams/Solver
(FORTRAN) model. A series of TFSISO statements can be assembled to resemble any linear block
diagram arrangement. The transfer function can be derived manually or may be imported directly from
a control system design program such as MATRIXx or MATLAB. Normally, the mechanical portion of
the model includes some kind of actuator which depends on the TFSISO output.
TFSISO statements can also be conveniently used in many cases to replace systems of coupled DIFF and
VARIABLE statements (for nonlinear equations, the GSE statements should be used). Examples of
possible dynamics system uses include unsteady aerodynamics, hydraulics, power transmission, and
electrodynamics.
You can use the current values of TFSISO state variables and outputs in both function expressions and
user-written subroutines via the associated ARRAY facilities (see the function expression ARYVAL, and
the subroutines: GTARAY, SYSARY, and SYSFNC). That is, instead of Adams/Solver (FORTRAN)
functions and FORTRAN callable subroutines dedicated explicitly to the TFSISO statement, the system
states and outputs are accessed by offset referencing through the appropriate ARRAY routines. This
method of referencing the variables makes access to the system states and outputs consistent for all three
system modeling elements, the TFSISO statement, the GSE statement, and the LSE statement.
See other Generic systems modeling available.
326 Adams/Solver
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 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
UCON 327
Adams/Solver (FORTRAN) Statements
UCON
The UCON statement defines a user-written constraint. With a UCON, it is possible to constrain the
configuration of the system as well as the motion of the system. Configuration constraints (that is,
holonomic constraints) can be:
Explicit functions of time, in which case, they are referred to as rheonomic.
Restricted to functions of system displacements, in which case, they are referred to as
scleronomic.
Motion constraints (that is, nonholonomic constraints) may be defined in terms of a linear combination
of system velocities.
Format
UCON/id, FUNCTION=USER(r1[,...,r30])
[[ ]] Optionally select an item combination
Arguments
The UCON statement defines a system constraint as a function of time and as many as thirty variables.
Each of these variables must be the displacement or the velocity of a part. For any part at any point in
time, six displacements define its position, and six velocities define its motion.
The six displacements are the x, y, and z translations and the three Euler angle rotations. The six velocities
are the x, y, and z translational speed and the time derivatives of the three Euler angles. Adams/Solver
(FORTRAN) measures all of these displacements and velocities at the origin of the principal axes with
328 Adams/Solver
respect to the global coordinate system. The UCON statement should be used to define only a constraint
that is not available in any of the other constraint statements.
Tip:
The principal axes are located at the part center of mass. The principal axes of a part are
the axes about which products of inertia are zero, that is, for which the inertia matrix is
diagonal.
Adams/Solver (FORTRAN) imposes UCONs on the principal coordinate systems of
the parts to which they belong. If a part has mass, its principal coordinate system is at
its center of mass and is in alignment with the axes of its principal moments of inertia.
If products of inertia (xy, xz, or yz) are declared for the IP argument of a PART
statement, the principal axes may differ from the center-of-mass marker axes specified
with the CM argument. This is because Adams/Solver (FORTRAN) changes the Euler
angles of the principal axes until the products of inertia disappear. In that case, the
origin of the principal axes are located at the origin of the center-of-mass marker axes,
but the orientation of the principal axes differ from the orientation of the center-ofmass marker axes. If a part has zero mass, its principal coordinate system is the same as
that of its body coordinate system (BCS).
Caution:
The UCON statement should be used only if you are very familiar with
F ( q', q, t ) =
ai ( q, t )q'i + f ( t ) =
i=1
In this equation, the a coefficients must not be velocity dependent. The symbols qi
and ai refer to the ith velocity variable and to its accompanying coefficient. The
coefficient can be functionally dependent on displacements and time, but it cannot
be dependent on velocities. Note that the equation includes no products involving
one velocity variable with another.
Caution:
part and not to the center-of-mass marker, REQUEST statements or the SYSARY
or SYSFNC subroutines cannot be used to obtain UCON reaction forces.
UCON 329
Adams/Solver (FORTRAN) Statements
Caution:
If you use the UCON statement for a velocity-dependent constraint and then use
330 Adams/Solver
UNITS
The UNITS statement sets the appropriate units for an Adams/Solver (FORTRAN) analysis. This ensures
that force computations, both on input and on output, correctly conforms to your choice of length, mass,
and time units.
Format
UNITS 331
Adams/Solver (FORTRAN) Statements
Arguments
SYSTEM={CGS,FPS,IPS,MKS,NONE}
TIME={HOUR,MILLISECONDS,MINU
TE,SECOND}
UCF=r
Extended Definition
The UNITS statement sets the appropriate units for an Adams/Solver (FORTRAN) analysis and allows
Adams/View to account for your choice. This ensures that Adams/Solver (FORTRAN) both interprets
and reports force values in the chosen force units.
332 Adams/Solver
In most cases, you select a system of units using the SYSTEM argument or the FORCE, MASS,
LENGTH, and TIME arguments. For cases not covered by the predefined choices, specifying the
appropriate UCF still allows Adams/Solver (FORTRAN) to interpret forces correctly.
To determine the correct UCF, you must solve the following dimensional analysis equation.
For example, if you want to work in kiloNewtons (kN), kilograms (kg), meters (m) and seconds (s), you
would write the following equation:
1kN = 1000N
and
kg m1N = -------------s2
1kg 1m
- UCF
1kN = --------------------1s 2
1000N = 1N UCF
UCF = 1000
If you want to work in tons_force (tf), tons_mass (tm), yard (yd), and minute (min) units you would write
the following equation.
1tm yd
1tf = ------------------- UCF
1min 2
given:
1tf = 2000lbf
1tm = 2000lbm
let:
1g = 32.2ft s 2
then:
1lbf = 1slug ft s 2
1lbm = 1slug 1g
1yd = 3ft
1min = 60s
UNITS 333
Adams/Solver (FORTRAN) Statements
lbf
1lbm = ----------------------232.2ft s
You cna substitute these equations into the equation to get:
2000lbms 3ft
UCF
2000lbf = -----------------------------------( 60s ) 2
2000 ( lbfs 2 32.2ft ) 3ft UCF
2000lbf = ----------------------------------------------------------( 60s ) 2
Then cancel common terms and solve for UCF:
3 32.2
1 = ----------------- UCF
60 60
UCF = 38640.0
Tip:
Using the UNITS statement with the individual unit arguments or the SYSTEM argument
allows Adams/View to understand the model's units and give consistent output. Avoid
using UCF, if possible.
Examples
UNITS/FORCE=KILOGRAM_FORCE,
,MASS=KILOGRAM, LENGTH=MILLIMETER, TIME=SECOND
This UNITS statement selects force units of kilogram_force, mass units of kilograms, length units of
millimeters, and time units of seconds.
See other Analysis parameters available.
334 Adams/Solver
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
FUNCTION =
USER ( r 1 [ ,, r 30 ] )
IC=r
ROUTINE=libname::subname
Extended Definition
The VARIABLE statement creates a user-defined algebraic equation. The value of the VARIABLE
statement may depend on almost any Adams/Solver (FORTRAN) system variable. Note that you cannot
access reaction forces from a UCON, and PTCV and CVCV reaction forces may only be accessed from
REQUEST and SENSOR expressions.
VARIABLE 335
Adams/Solver (FORTRAN) Statements
You can define the value of the VARIABLE statement by either writing a function expression in the
dataset or by calling a VARSUB user-written subroutine. For more on user-written and utility
subroutines, see User-Written Subroutines on and Utility Subroutines.
Function expressions and user-written subroutines can access the value of the VARIABLE statement with
the Adams/Solver (FORTRAN) function VARVAL(id) (see VARVAL) to represent the value, where id
specifies the user-selected identifier of the VARIABLE statement. User-written subroutines access single
VARIABLE statement values by calling the subroutine SYSFNC.
Caution:
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.
336 Adams/Solver
VFORCE
The VFORCE statement creates a translational vector force element that is specified using three
orthogonal components. You may define the VFORCE statement through user-specified function
expressions in the Adams/Solver (FORTRAN) dataset or through user-written subroutines.
Format
Arguments
FX=e
FY=e
FZ=e
VFORCE 337
Adams/Solver (FORTRAN) Statements
JFLOAT=id
RM=id
ROUTINE=libname::subname
Extended Definition
The VFORCE statement creates an Adams/Solver (FORTRAN) translational vector force element that
applies a three-component force between two parts of the system. The element applies an action force to
the part to which the I marker belongs and a corresponding reaction force to the part to which the JFLOAT
marker belongs. The VFORCE statement establishes the position of the JFLOAT marker. As the system
moves, Adams/Solver (FORTRAN) moves the JFLOAT marker on its part to keep the JFLOAT and I
markers superimposed. Therefore, Adams/Solver (FORTRAN) applies the reaction force to the JFLOAT
markers part at the instantaneous position of the I marker.
The total vector force depends on the vector sum of the individual force components that you specify.
The magnitude of the force is the square root of the sum of the squares of the magnitude of the three
mutually-orthogonal force components. You can specify the functions with function expressions (see
Function Expressions) or user-written FORTRAN subroutines (see User-Written Subroutines).
RM marker axes determine the direction of the force action. The reaction is equal and opposite to the
action.
Formulation
Action
338 Adams/Solver
FX is the user-defined function defining the magnitude and sign of the x-component
FY is the user-defined function defining the magnitude and sign of the y-component
FZ is the user-defined function defining the magnitude and sign of the z-component
Reaction
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 user-defined functions FX, FY, and FZ should be smooth, continuous, and singlevalued. These conditions make the solution process very effective.
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 (FORTRAN)
superimposes floating Marker 9910 on Marker 310, and apply the reaction force at that point.
Applications
The VFORCE statement is most useful to define a vector force whose point of application and/or
direction is most easily formulated in a coordinate system that moves or is on a different part. You can
use a VFORCE statement to model a point mass sliding down an inclined cantilever for normal and
frictional force effects (see the figure below). The RM reference marker is fixed to the cantilever and
supplies the orientation for the normal and frictional forces.
VFORCE 339
Adams/Solver (FORTRAN) Statements
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 six-component force set.
See other Forces available.
340 Adams/Solver
VTORQUE
The VTORQUE statement defines a vector torque that consists of three orthogonal components. You can
define the VTORQUE statement through user-specified function expressions in the Adams/Solver
(FORTRAN) dataset or through user-written subroutines.
Format
Arguments
JFLOAT=id
RM=id
ROUTINE=libname::subname
VTORQUE 341
Adams/Solver (FORTRAN) Statements
TX=e
TY=e
TZ=e
Extended Definition
The VTORQUE statement creates an Adams/Solver (FORTRAN) rotational force element that applies a
vector torque between two parts of the system. The element applies an action to the part to which the I
marker belongs and a corresponding reaction to the part to which the JFLOAT marker belongs. The
VTORQUE statement establishes the position of the JFLOAT marker. As the system moves,
Adams/Solver (FORTRAN) moves the JFLOAT marker on its part to keep the JFLOAT and I markers
superimposed. Thus, Adams/Solver (FORTRAN) applies the reaction torque to the JFLOAT markers
part.
The components of the torque depend on expressions or subroutines that you supply. The magnitude of
the torque is the square root of the sum of the squares of the magnitudes of the three mutually orthogonal
torque components. You can specify these functions using function expressions (see Function
Expressions) or user-written FORTRAN subroutines (see User-Written Subroutines).
The direction of the torque action is determined by the resultant vector formed by the three component
torque you defined along the RM marker axes. The reaction is equal and opposite to the action.
Formulation
Action
342 Adams/Solver
TX is the user-defined function defining the magnitude and sign of the x-component according
Reaction
Depending on the nature of the desired torque relationship, the RM marker may belong to
the same part as the I marker or the JFLOAT marker, or to a third, unrelated part.
Caution:
The user-defined functions TX, TY, and TZ should be smooth, continuous, and singlevalued. These conditions make the solution process very effective.
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 (FORTRAN)
superimposes floating Marker 9911 on Marker 310, and apply the reaction force at that point.
Applications
The VTORQUE statement is particularly useful when you need to define a vector torque whose point of
application and/or direction is most easily formulated in a coordinate system which moves or is on a
different part.
VTORQUE 343
Adams/Solver (FORTRAN) Statements
For example, the VTORQUE statement could be used to represent the yaw, pitch, and rolling moments
on a flight vehicle (see the figure below). In this instance, the RM marker would be fixed to the vehicle
at its aero-dynamic center. You can use a VFORCE statement (see VFORCE) to supply the remaining
translational forces, or the GFORCE statement (see GFORCE) to provide all six forces using a single
entity. In any event, you can use the reference marker to resolve the aircraft inertial velocity onto aircraft
axes for subsequent calculation of aerodynamic forces.
Yaw, Pitch, and Rolling Moments on a Flight Vehicle
Another application where a VTORQUE would significantly simplify modeling and analysis is in
consideration of gravitational torques exerted on Earth-orbiting satellites. In this case the RM marker
would not be fixed in the satellite or the Earth, but would move with the rotating line segment extending
between the satellite and the Earth.
When compared with the SFORCE statement (see SFORCE ), the VTORQUE statement offers the
advantage that the resultant torque direction (with respect to the RM marker) can vary.
See other Forces available.
344 Adams/Solver
1
Adams/Solver (FORTRAN) Functions
FORTRAN 77
Function Name:
ABS
ACOS
AINT
ANINT
ASIN
ATAN
ATAN2
COS
COSH
EXP
LOG
MAX
MIN
MOD
SIGN
SIN
SINH
SQRT
TAN
TANH
Displacement
AX
AY
AZ
DM
DX
DY
DZ
INCANG
PHI
PITCH
PSI
ROLL
THETA
YAW
Velocity
VM
VR
VX
VY
VZ
WM
WX
WY
WZ
Acceleration
ACCM
ACCX
ACCY
ACCZ
WDTM
WDTX
WDTY
WDTZ
Generic force
FM
FX
FY
FZ
TM
TX
TY
TZ
2 Adams/Solver
Type of Function:
Function Name:
BEAM
BUSH
FIELD
FRICTION
GFORCE
CVCV
JOINT
JPRIM
MOTION
PTCV
System element
ARYVAL
DIF
DIF1
PINVAL
POUVAL
SENVAL
VARVAL
Arithmetic IF
IF
Interpolation
AKISPL
CUBSPL
CURVE
INTERP
General
BISTOP
CHEBY
FORCOS
FORSIN
HAVSIN
IMPACT
FXFREQ
FXMODE
NFORCE
SFORCE
SPDP
VFORCE
VTORQ
INVPSD
POLY
SHF
STEP
STEP5
SWEEP
ABS 3
Adams/Solver (FORTRAN) 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 available.
4 Adams/Solver
ACCM
The ACCM function calculates the magnitude of the second time derivative of the displacement vector
of marker i from marker j. The time derivatives are taken in the reference frame of marker l. Markers j
and l default to the global coordinate system and the global reference frame if they are not specified.
Format
ACCM(i[,j][,l])
Arguments
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.
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).
Extended Definition
ACCM ( i ,j ,l ) =
where
(l)
d
Ri
dt2
dt
d
Rj
d t2
(l)
d
Ri
dt2
(l)
d
Rj
d t2
(l)
(B) d
dt
p:
Examples
REQUEST/10, F2=ACCM(21,11)
This statement defines the second component of a user-defined request as the magnitude of translational
acceleration of Marker 21 with respect to Marker 11. Since the l marker is not specified, the derivatives
are taken in the inertial reference frame.
REQUEST/10, F2=ACCM(21,11)
This statement defines the second component of a user-defined request as the magnitude of the
translational acceleration of Marker 21 with respect to Marker 11. Vector time derivatives taken in
reference to Marker 32. See other Acceleration available.
ACCX 5
Adams/Solver (FORTRAN) Functions
ACCX
The ACCX function returns the x-component of the difference between the acceleration vector of marker
i and the acceleration vector of marker j as computed in the coordinate system of marker k. All vector
time derivatives are taken in the reference frame of marker l. Marker j defaults to the global coordinate
system if it is not specified. Similarly, markers k and l default to the global coordinate system and the
global reference frame if they are not specified.
Format
ACCX(i[,j][,k][,l])
Arguments
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.
The marker in whose coordinate system the acceleration vector is being expressed. Set k = 0,
while still specifying l, if you want the results to be calculated along the x-axis of the global
coordinate system.
The reference frame in which the second time derivative of the displacement vector is taken.
Set l = 0 or omit the argument if you want the time derivatives to be taken in the ground
coordinate system (GCS).
Extended Definition
ACCX ( i ,j ,k ,l ) =
where
(l)
d
Ri
dt2
(l)
Rj xk
2
dt
This statement defines a user-specified differential equation. The time derivative of the state is specified
to be the x-component of the acceleration of Marker 21 with respect to Marker 11. The coordinate system
for calculating the component, and for referencing the frame that takes time derivatives, defaults to
ground.
DIFF/2, IC=1, FUNCTION=ACCX(21,0,31)
6 Adams/Solver
This statement defines a user-specified differential equation. The time derivative of the state is specified
to be the x-component 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 available.
ACCY 7
Adams/Solver (FORTRAN) Functions
ACCY
The ACCY function returns the y-component of the difference between the acceleration vector of marker
i and the acceleration vector of marker j as computed in the coordinate system of marker k. All vector
time derivatives are taken in the reference frame of marker l. Marker j defaults to the global coordinate
system if it is not specified. Similarly, markers k and l default to the global coordinate system and the
global reference frame if they are not specified.
Format
ACCY(i[,j][,k][,l])
Arguments
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.
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 y-axis of the global
coordinate system.
The reference frame in which the second time derivative of the displacement vector is taken.
Set l = 0 or omit the argument if you want the time derivatives to be taken in the ground
coordinate system (GCS).
Extended Definition
ACCY ( i ,j ,k ,l ) =
where
(l)
d
Ri
dt2
(l)
Rj yk
2
dt
This statement defines a user-specified differential equation. The time derivative of the state is specified
to be the x-component of the acceleration of Marker 21 with respect to Marker 11. The coordinate system
for calculating the component, and for referencing the frame that takes time derivatives, defaults to
ground.
DIFF/2, IC=1, FUNCTION=ACCX(21,0,31)
8 Adams/Solver
This statement defines a user-specified differential equation. The time derivative of the state is specified
to be the x-component 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 available.
ACCZ 9
Adams/Solver (FORTRAN) Functions
ACCZ
The ACCZ function returns the z-component of the difference between the acceleration vector of marker
i and the acceleration vector of marker j as computed in the coordinate system of marker k. All vector
time derivatives are taken in the reference frame of marker l. Marker j defaults to the global coordinate
system if it is not specified. Similarly, markers k and l default to the global coordinate system and the
global reference frame if they are not specified.
Format
ACCZ(i[,j][,k][,l])
Arguments
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.
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 z-axis of the global
coordinate system.
The reference frame in which the second-time derivative of the displacement vector is taken.
Set l = 0 or omit the argument if you want the time derivatives to be taken in the ground
coordinate system (GCS).
Extended Definition
ACCZ ( i ,j ,k ,l ) =
where
(l)
d
Ri
dt2
(l)
Rj zk
2
dt
This statement defines a user-specified differential equation. The time derivative of the state is specified
to be the x-component of the acceleration of Marker 21 with respect to Marker 11. The coordinate system
for calculating the component, and for referencing the frame that takes time derivatives, defaults to
ground.
DIFF/2, IC=1, FUNCTION=ACCX(21,0,31)
10 Adams/Solver
This statement defines a user-specified differential equation. The time derivative of the state is specified
to be the x-component 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 available.
ACOS 11
Adams/Solver (FORTRAN) Functions
ACOS
The ACOS function calculates the arc cosine of an expression a. Expression a must evaluate to a value
whose absolute value is less than or equal to 1. The value returned by ACOS lies in the range [0, ] (i.e.,
0 < ACOS(a) <
).
Format
ACOS(a)
Arguments
Examples
VARIABLE/1, FU=ACOS((DX(21,11)*DX(31,41)+DY(21,11)*DY(31,41)
+ DZ(21,11)*DZ(31,41))/(DM(21,11)*DM(31,41))
This statement specifies a new user-defined state variable. Its value is the included angle of the lines
joining Markers 11 and 21 and Markers 41 and 31. The result is in radians.
See other FORTRAN 77 available.
12 Adams/Solver
AINT
The AINT function returns the nearest integer whose magnitude is not larger than the integer value of the
expression a.
AINT(a) = 0 if ABS(a) < 1
AINT(a) = int(a) if ABS(a) > 1
The value of the mathematical function int of a variable x is equal to x if x is an integer. If x is not an
integer, then int(x) is equal to the nearest integer to x whose magnitude is not greater than the magnitude
of x. Thus int(-7.0) = -7, int(-4.8) = -4, and int(4.8) = 4.
Format
AINT(a)
Arguments
Caution:
Note that AINT is not a differentiable function. Be careful when using this function in an
expression that defines a force or motion input to the system.
Examples
AINT(-6.5) = -6
AINT(4.6 ) = 4
AKISPL 13
Adams/Solver (FORTRAN) Functions
AKISPL
The AKISPL function returns the iord derivative of the interpolated value of SPLINE/id at X=x and Z=z.
Format
A real variable that specifies the independent variable value along the x-axis of the
AKISPL.
A real variable that specifies the second independent variable value along the z-axis of the
surface being interpolated. Specify z = 0 if the SPLINE statement defines only one curve.
id
An integer variable that specifies the identifier of a SPLINE statement that you define in the
Adams/Solver dataset.
iord
An integer variable that specifies the order of the derivative to be taken at the interpolated
point. iord may not be specified when interpolating on a surface (for example, when z 0 ).
Default: 0
Range: 0 < iord < 2
Extended Definition
The AKISPL function uses the Akima method of interpolation to create a spline function across a set of
data points. The data points to be interpolated are defined by a SPLINE statement in the Adams/Solver
dataset. The SPLINE that you define in the dataset may represent a curve (x-y points) or a surface (x-yz 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.
14 Adams/Solver
For more information on the Akima method of interpolation, see the references listed in Additional
Publications.
Tip:
If you want to force a particular region of a spline function to be linear, you should know
that four consecutive points on a straight line will yield a linear section in the region
between the central two points, and, similarly, four consecutive points on a straight line at
the end of a spline will yield a linear fit from the second point onward.
Examples
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 available.
ANINT 15
Adams/Solver (FORTRAN) Functions
ANINT
The ANINT function calculates the nearest integer to a.
ANINT(a) = int(a + .5) if a > 0
ANINT(a) = int(a - .5) if a < 0
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
16 Adams/Solver
ARYVAL
The ARYVAL function returns component comp of ARRAY/id. Depending on the definition of
ARRAY/id, this may be a constant that you defined in the Adams/Solver (FORTRAN) dataset, an input
to an LSE, GSE, or TFSISO, a state variable defined by an LSE, GSE, or TFSISO, or an output from an
LSE, GSE, or TFSISO.
Format
id
comp
Examples
ARRAY/17, NUM=11.465,2.321
SFORCE/19, ROT, I=23, J=11
, FUNCTION=-ARYVAL(17,1)*(AZ(23,11)-ARYVAL(17,2))
This example illustrates how a value defined in an ARRAY statement can be accessed using the
ARYVAL function.
LSE/1, X=1, U=2, Y=3, A=11, B=12, C=13, D=14
This statement defines a set of linear state equations. The A, B, C, and D matrices for this LSE are defined
by matrices 11-14.
SFORCE/6, ROT, I=23, J=11, FUNCTION=ARYVAL(3,2)
The second output of the LSE is used to define a torque acting on the system.
See other System element available.
ASIN 17
Adams/Solver (FORTRAN) Functions
ASIN
The ASIN function computes the arc sine of an expression a. ASIN is defined only when the absolute
value of a is less than or equal to 1. The range of ASIN is [- /2, /2] (that is, - /2 < ASIN(a) <
/2).
Format
ASIN(a)
Arguments
Examples
DIFF/1, IC=1.05, FUNCTION=ASIN(DX(21,11)/DM(21,11))
This statement defines a user-specified differential equation. The initial value of the state variable is 1.05.
The time derivative of the state variable is the expression:
ASIN(DX(21,11)/DM(21,11))
18 Adams/Solver
ATAN
The ATAN function returns the arc tangent of an expression a. The range of ATAN is [- /2,
is, - /2 < ATAN(a)<
/2] (that
/2).
Format
ATAN(a)
Arguments
Examples
SFORCE/1, ROTATIONAL, I=21, J=11
, FUNCTION=-10*ATAN(DY(42,33)/DX(42,33))
This SFORCE statement defines a torque acting between Markers 21 and 11. The value of the torque is
the spring constant (10) multiplied by the angle between the line joining Markers 33 and 42 and the global
x-axis as shown in the figure below.
Example Illustrating the Use of the ATAN Function
ATAN2 19
Adams/Solver (FORTRAN) Functions
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
a1
a2
Examples
VARIABLE/1,
, FUNCTION=ATAN2(DY(21,31,41), DX(21,31,41))
20 Adams/Solver
AX
The AX function returns the rotational displacement of marker i about the x-axis of marker j, and
accounts for angle wrapping.
Marker j defaults to the global coordinate system if it is not specified. This value is computed as follows:
assume that rotations about the other two axes (y- and z-axes) of marker j are zero. Then, AX is the angle
between the two y-axes (or the two z-axes). AX is measured in a counter-clockwise sense from the y-axis
of marker J to the y-axis of marker I (see the figure below).
Measurement of AX
Format
AX(i[,j])
Arguments
The marker whose coordinate system is used as a reference to calculate the rotations of marker i.
When j is not specified, Adams/Solver (FORTRAN) defaults to the global coordinate system.
Extended Definition
AX = ATAN2 ( z i y j, z i z j )
where:
AX 21
Adams/Solver (FORTRAN) Functions
Tip:
If you want to change the AX function so it does not account for angle wrapping, use the
MOD function. For example, use the function:
(MOD(AX(2,1) + PI, 2 * PI) - PI
The MOD function achieves the cyclic effect and the +PI and -PI shift the curve
accordingly.
Caution:
For large rotations (greater than 10 degrees) about the y-axis or z-axis on Marker j, the AX
function becomes increasingly non-physical. Moreover, AX is undefined when both
arguments to ATAN2 are zero. This occurs when the z-axis of marker i is orthogonal to the
plane defined by the y and z-axis of the j marker.
Examples
GFORCE/1, I=21, JFLOAT=31, RM=41
, FX=-20*AX(43,32)
This GFORCE statement applies a force at the origin of Marker 21 along the x-axis of Marker 41. The
reaction force is on floating Marker 31. The floating Marker 31 can belong to another part but its location
is always the same as Marker 21.
The value of the force is -20 times the angle between the y axes of Markers 43 and 32. The angle is
measured in a counterclockwise sense from the y-axis of Marker 32 to the y-axis of Marker 43.
See other Displacement available.
22 Adams/Solver
AY
The AY function returns the rotational displacement of marker i about the y-axis of marker j, and
accounts for angle wrapping.
Marker j defaults to the global coordinate system if it is not specified. The values are computed as
follows: assume rotations about the other two axes (x-, z-axes) of marker j are zero. Then AY is the angle
between the two x-axes (or the two z-axes). AY is measured counter-clockwise from the z-axis of the J
marker to the z-axis of the I marker (see the figure below).
Measurement of AY
Format
AY(i[,j])
Arguments
The marker with respect to which the rotations are being measured.
Extended Defintion
AY = ATAN2 ( z i x j, z i z j )
where:
AY 23
Adams/Solver (FORTRAN) Functions
Tip:
If you want to change the AY function so it does not account for angle wrapping, use the
MOD function. For example, use the function:
(MOD(AY(2,1)+PI,2*PI)-PI)
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 x-axis or z-axis of marker j, the AY
function becomes increasingly non-physical. Moreover, AY is undefined when both
arguments to ATAN2 are zero. This occurs when the z-axis of marker i is orthogonal to the
plane defined by the x and z-axis of the j marker.
Examples
SFORCE/10, ROTATION, I=23, J=34
, FUNCTION=-4*(AY(46,57)**2)
This SFORCE statement applies a moment about the common z-axes of Markers 23 and 34. The torque
acts on Marker 23; the reaction torque acts on Marker 34.
The value of the torque being applied is -4 times the square of the angle between the z axes of Markers
46 and 57. The angle is measured in a counterclockwise sense from the z-axis of Marker 57 to the z-axis
of Marker 46.
See other Displacement available.
24 Adams/Solver
AZ
The AZ function returns the rotational displacement of marker i about the z-axis of marker j, and accounts
for angle wrapping.
Marker j defaults to the global coordinate system if it is not specified. This value is computed as follows:
assume that rotations about the other two axes (x-, y-axes) of marker j are zero. Then AZ is the angle
between the two x-axes (or the two y-axes). AZ is measured in a counter- clockwise sense from the xaxis of the J marker to the x-axis of the I marker (see the figure below).
Measurement of AZ
Format
AZ(i [,j ])
Arguments
The marker with respect to which the rotations are being measured.
Extended Definition
AZ = ATAN2 ( x i y j, x i x j )
where:
AZ 25
Adams/Solver (FORTRAN) Functions
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(.model_1.PART_1.MAR_2, .model_1.ground.MAR_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 x-axis or y-axis of marker j, the AZ
function becomes increasingly non-physical. Moreover, AZ is undefined when both
arguments to ATAN2 are zero. This occurs when the x-axis of marker i is orthogonal to the
plane defined by the x and y-axis of the j marker.
Examples
VTORQUE/1, I=21, JFLOAT=31, RM=41
, TX=-10*(AX(21,32)-10D)/
, TY=-15*(AY(21,32)-15D)/
, TZ=-30*(AZ(21,32)-25D)
This VTORQUE statement applies a moment at Marker 21. The reaction moment is at the floating
Marker 31. The torques are expressed in the coordinate system of Marker 41.
See other Displacement available.
26 Adams/Solver
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
id
jflag
An integer flag specifying the beam connectivity marker at which the forces and torques are
computed.
0 = forces and moments at the I marker
1 = forces and moment at the J marker
comp
An integer value that specifies the component of the beam force to be returned.
1 = Magnitude of the force
2 = x component of the force
3 = y component of the force
4 = z component of the force
5 = Magnitude of the torque
6 = x component of the torque
7 = y component of the torque
8 = z component of the torque
rm
The coordinate system in which the results are expressed. To return the results in the global
coordinate system, set rm = 0.
Examples
REQUEST/1
, F2=BEAM(1001,0,2,0)/
, F3=BEAM(1001,0,3,0)/
, F4=BEAM(1001,0,4,0)
This REQUEST statement stores the x-, y-, and z-component of the forces in BEAM/1001 in columns 2,
3, and 4, respectively. The forces are calculated at the I marker. The results are computed in the global
coordinate system.
See other Element-specific applied force available.
BISTOP 27
Adams/Solver (FORTRAN) Functions
BISTOP
The BISTOP function models a gap element (see Figure 1).
Format
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).
x1
x2
A non-negative value that specifies the stiffness of the boundary surface interaction.
A positive value that specifies the exponent of the force deformation characteristic. For a
stiffening spring characteristic, e > 1.0. For a softening spring characteristic, 0 < e < 1.0.
cmax
A positive real variable that specifies the penetration at which the full damping coefficient
is applied.
Extended Definition
The BISTOP function models a gap element. Figure 1 below illustrates the BISTOP force. The gap
element consists of a slot which defines the domain of motion of a Part I located in the slot. As long as
Part I is inside the slot and has no interference with the ends of the slot, it is free to move without forces
acting on it. When Part I tries to move beyond the physical definition of the slot, impact forces
representing contact are created by the BISTOP function. The created force tends to move Part I back
into the slot.
The BISTOP force has two components: A stiffness component dependent on the penetration of Part I
into the restricting Part J and a damping or viscous component that may be used to model energy loss.
28 Adams/Solver
Figure 1
To prevent a discontinuity in the damping force at zero penetration, the damping coefficient is defined as
a cubic step function of the penetration. Thus at zero penetration, the damping coefficient is always zero.
The damping coefficient achieves a maximum, cmax, at a user-defined penetration, d. Even though the
points of contact between the floating part and the restricting part may change as the system moves,
Adams/Solver (FORTRAN) always exerts the force between the I and the J markers.
Figure 2
Caution:
When e is < 1, the defined force contains a slope discontinuity that may casue difficulty for
the integrator.
Examples
You may model a slider in a slot with a BISTOP function as depicted in Figure 1. Assume a translational
joint constrains the slider to move in a slot. The line of translation is along the colinear z-axes of the I
and the J markers, I belonging to the slider and J to the part containing the slot. You can use an SFORCE
statement together with the BISTOP function to restrict the movement of the slider in the slot and model
the gap.
BISTOP 29
Adams/Solver (FORTRAN) Functions
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
x = VZ(I,J,J,J)
- x).
x > x2 penetration occurs at the end farther away from the J marker, and the force is < 0
(penetration p = x - x2).
Also note that when p < d the instantaneous damping coefficient is a cubic step function of the
penetration, p; when p > d the instantaneous damping coefficient is cmax.
The BISTOP function for this example is:
BISTOP(DZ(I,J,J,J), VZ(I,J,J,J), x1, x2, k, e, cmax, d)
The values of k, e, cmax, and d depend on the materials used in the two parts and on the shapes of the parts
and are used to define the contact force. The BISTOP force can be mathematically expressed as follows:
e
Max ( k x 1 x STEP x, x 1 d, c max, x 1, 0 x', 0 )
x1 x x2
BISTOP = 0
x < x1
x > x2
30 Adams/Solver
BUSH 31
Adams/Solver (FORTRAN) 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
id
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.
Examples
REQUEST/1
, F2=BUSH(1001,0,2,0)/
, F3=BUSH(1001,0,3,0)/
, F4=BUSH(1001,0,4,0)
This REQUEST statement stores the x-, y-, and z-component of the forces in BUSH/1001 in columns 2,
3, and 4, respectively. The forces are calculated at the I marker. The results are computed in the global
coordinate system.
See other Element-specific applied force available.
32 Adams/Solver
CHEBY
The CHEBY function evaluates a Chebyshev polynomial at a user specified value x.
Format
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
Extended Definition
The CHEBY function evaluates a Chebyshev polynomial at a user specified value x. x0, a0, a1,..., a30 are
parameters used to define the constants for the Chebyshev polynomial. The Chebyshev polynomial is
defined as:
C(x) =
aj Tj (x-x0)
The index j has a range from zero to n, where n is the number of terms in the series.
Note the following:
T2 (x-x0) = 2 * (x-x0)2 - 1
T3 (x-x0) = 4 * (x-x0)3 - 3 * (x-x0)
Examples
MOTION/1, JOINT=21, TRANSLATION,
,FUNCTION = IF (TIME-2:CHEBY(TIME, 1, 1, 0, -1), 0, 0)
This MOTION statement defines a motion using a quadratic Chebyshev polynomial and the system
variable TIME. The arithmetic IF ensures that the function remains zero after 2 time units. When time is
less than 2 time units, Adams/Solver (FORTRAN) evaluates a Chebyshev polynomial to determine the
motion. The polynomial defined in the above example is:
Cheby = 1 + 0 * (time-1) - 1 * [2 (time-1)2 - 1]
= 2*time2 - 4*time
CONTACT 33
Adams/Solver (FORTRAN) 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 (FORTRAN) returns the value of the
force/torque that acts on the I marker of CONTACT. If jflag is set to 1, Adams/Solver (FORTRAN)
returns the value that acts on the J marker. To obtain results in the global coordinate system, you can
specify rm as zero.
Format
id
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
rm
The coordinate system in which the results are expressed. To return the results in the global
coordinate system, set rm = 0.
Examples
REQUEST/1
, F2= CONTACT(11,0,2,0)/
, F3= CONTACT(11,0,3,0)/
, F4= CONTACT(11,0,4,0)/
, F6= CONTACT(11,0,6,0)/
, F7= CONTACT(11,0,7,0)/
, F8= CONTACT(11,0,8,0)
This REQUEST statement outputs the x-, y- and z-components of the force and torque at the I marker of
CONTACT/11. Because rm is specified as zero, all vectors are expressed in the global coordinate system.
34 Adams/Solver
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 available.
COSH 35
Adams/Solver (FORTRAN) Functions
COSH
The COSH function computes the hyperbolic cosine of an expression a. COSH(a) = (ea + e-a) / 2.0
Format
COSH(a)
Arguments
Examples
REQUEST/36,
, F2=COSH(DZ(21,11,11))
This REQUEST statement returns the hyperbolic cosine of the z-component of the displacement of
Marker 21 with respect to Marker 11 in its second column. The result is computed in the coordinate
system of Marker 11.
See other FORTRAN 77 available.
36 Adams/Solver
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
A real variable that specifies the independent variable value along the x-axis of the CUBSPL.
A real variable that specifies the second independent variable value along the z-axis of the
surface being interpolated. If the SPLINE statement defines only one curve, Adams/Solver
(FORTRAN) ignores this variable.
id
iord
An optional integer that specifies the order of the derivative at the interpolate value to be
returned by CUBSPL.
Range: 0 < iord < 2
Extended Definition
The CUBSPL function uses the standard cubic method of interpolation to create a spline function across
a set of data points. The data points are defined in the SPLINE statement in Adams/Solver (FORTRAN)
data deck. The SPLINE that you define in the Adams/Solver dataset may represent a curve (x-y points)
or a surface (x-y-z points). Interpolation in the y direction is cubic and interpolation in the z direction is
linear. To interpolate the values specified in a curve, set z = 0.
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 (FORTRAN). The solution process often requires estimates of derivatives of the functions
being defined. The smoother a derivative is, the easier it is for the solution process to converge.
If the spline data contains sudden changes in value, the CUBSPL function gives more oscillatory results
for the curve or surface than are given by the AKISPL function.
For more information on the cubic method of interpolation, see the references listed in Additional
Publications.
CUBSPL 37
Adams/Solver (FORTRAN) Functions
Examples
SPLINE/1,
, X= -3, -2, -1, 0, 1, 2, 3
, Y= -67.4, -48.6, -33.7, 4.8, 24.12, 37.6, 48.4
SFORCE/1, I=409, J=109, TRANSLATION,
, FUNCTION=CUBSPL(TIME, 0, 1)
This SFORCE statement defines the translational force acting between Markers 409 and 109. The
SPLINE statement provides the discrete data used to generate the interpolation function using the cubic
spline. Since the SPLINE statement defines only one curve, the value of z is defined to be 0.
See other Interpolation available.
38 Adams/Solver
CURVE
The CURVE function evaluates a B-spline or user-written curve that is created with the CURVE
statement.
Format
alpha
A real variable that identifies the value of the independent parameter, , at which the CURVE
function evaluates the curve. If the curve is a B-spline computed by the CURVE statement,
alpha must be in the domain -1 < < 1. If the curve is computed by a CURSUB, alpha must
be in the domain MINPAR < < MAXPAR (these are specified in the CURVE statement).
iord
An integer variable that specifies the order of the derivative the CURVE function returns. The
legal values are:
0 - returns the curve coordinate
1 - returns the first derivative
2 - return the second derivative
comp
An integer variable that specifies the component that the CURVE function returns. The legal
values are:
1 - returns the x coordinate or derivative
2 - returns the y coordinate or derivative
3 - returns the z coordinate or derivative
Parameters iord and icomp together allow you to request any one of the following nine return
values:
iord
0
1
2
id
2y()
d---------------d 2
d 2 z ( )---------------d 2
Examples
VFORCE/1, I=101, JFLOAT=201, RM=99,
, FX=CURVE(.4*TIME - 1, 0, 1, 8)/
, FY=CURVE(.4*TIME - 1, 0, 2, 8)/
, FZ=CURVE(.4*TIME - 1, 0, 3, 8)
CURVE 39
Adams/Solver (FORTRAN) Functions
This example applies to a VFORCE acting between Markers 101 and 201. The CURVE statement defines
the force components as a function of alpha, which varies from -1.0 to 1.0. The term 4*TIME-1 computes
the instantaneous value of alpha from the simulation time.
See other Interpolation available.
40 Adams/Solver
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
id
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
Examples
REQUEST/18,
, F2=CVCV(210,0,2,0)/
, F3=CVCV(210,0,3,0)/
, F4=CVCV(210,0,4,0)/
, F6=CVCV(210,0,6,0)/
, F7=CVCV(210,0,7,0)/
, F8=CVCV(210,0,8,0)
This REQUEST statement returns all three components of the forces and moments acting at the IFLOAT
marker of CVCV Joint 210.
See other Element-specific reaction force available.
DIF 41
Adams/Solver (FORTRAN) Functions
DIF
The DIF function returns the value of the state associated with DIFF/id.
Format
DIF(id)
Arguments
id
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 available.
42 Adams/Solver
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
id
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 available.
DIM 43
Adams/Solver (FORTRAN) Functions
DIM
The DIM function calculates the positive difference of the instantaneous values of two expressions a1
and a2.
DIM(a1,a2) = 0 if a1 < a2
DIM(a1,a2) =a1-a2 if a1 > a2
Format
DIM(a1,a2)
Arguments
a1
a2
Caution:
44 Adams/Solver
DM
The DM function returns the magnitude of the translational displacement vector from marker j to marker
i. Marker j defaults to the global coordinate system if it is not specified. DM is the distance between
markers i and j and, by definition, is always non-negative.
Format
DM(i[,j])
Arguments
The marker whose origin is the reference point for the displacement calculation.
Extended Definition
DM =
[ Ri Rj ] [ Ri Rj ]
R j is the displacement of
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 available.
DTOR 45
Adams/Solver (FORTRAN) Functions
DTOR
The DTOR variable returns degrees to radians conversion factor (PI/180).
Format
DTOR
Examples
VARIABLE/1, FUNCTION=30*DTOR*TIME
This VARIABLE statement specifies a user-defined, algebraically-determined state variable whose value
is 30 degrees*time. The state variable is stored in radians.
See other Simulation constants and variables available.
46 Adams/Solver
DX
The DX function returns the x-component of the translational displacement vector from marker j to
marker i as expressed in the marker k coordinate system. Marker j defaults to the global coordinate
system if it is not specified. Similarly, marker k defaults to ground if it is not specified.
Format
DX(i[,j][,k])
Arguments
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.
The marker that is referenced to calculate the x-component of the displacement vector. Set k =
0 if you want the results to be calculated along the x-axis of the global coordinate system.
Extended Definition
DX = [ R i R j ] x k
where:
Examples
VARIABLE/1, FUNCTION=DX(21,11,32)**2
This VARIABLE statement specifies a user-defined, algebraically-determined state variable. Its value is
the square of the x-displacement of Marker 21 with respect to Marker 11 as computed in the coordinate
system of Marker 32.
See other Displacement available.
DY 47
Adams/Solver (FORTRAN) Functions
DY
The DY function returns the y-component of the translational displacement vector from marker j to
marker i as expressed in the marker k coordinate system. Marker j defaults to the global coordinate
system if it is not specified. Similarly, marker k defaults to the global coordinate system if it is not
specified.
Format
DY(i[,j][,k])
Arguments
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.
The coordinates of the marker that are referenced to calculate coordinates the y-component of
the displacement vector is being calculated. Set k = 0 if you want the results to be calculated
along the y-axis of the global coordinate system.
Extended Definition
DY = [ R i R j ] y k
where:
Examples
VARIABLE/1, FUNCTION=DY(21,11,32)**2
This VARIABLE statement specifies a user-defined, algebraically-determined state variable. Its value is
the square of the y-displacement of Marker 21 with respect to Marker 11 as computed in the coordinate
system of Marker 32.
See other Displacement available.
48 Adams/Solver
DZ
The DZ function returns the z-component of the translational displacement vector from marker j to
marker i as expressed in the marker k coordinate system. Marker j defaults to the global coordinate
system if it is not specified. Similarly marker k defaults to the global coordinate system if it is not
specified.
Format
DZ(i[,j][,k])
Arguments
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.
The marker in whose coordinates the z-component of the displacement vector is being
calculated. Set k = 0 if you want the results to be calculated along the z-axis of the global
coordinate system.
Extended Definition
DZ = [ R i R j ] z k
where:
Examples
VARIABLE/1, FUNCTION=DZ(21,11,32)**2
This VARIABLE statement specifies a user-defined, algebraically-determined state variable. Its value is
the square of the z-displacement of Marker 21 with respect to Marker 11 as computed in the coordinate
system of Marker 32.
See other Displacement available.
EXP 49
Adams/Solver (FORTRAN) Functions
EXP
The EXP function computes the value ea, where a is any expression.
Format
EXP(a)
Arguments
Examples
REQUEST/10, F2=EXP(WDTX(21,11,11,31))
where WDTX (21,11,11,31) is the x-component of the accelerations of Marker 21 with respect to Marker
11 as expressed in the coordinate system of Marker 11. The time derivative is taken in the reference frame
of Marker 31.
See other FORTRAN 77 available.
50 Adams/Solver
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
id
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.
Examples
REQUEST/1
, F2=FIELD(1001,0,2,0)/
, F3=FIELD(1001,0,3,0)/
, F4=FIELD(1001,0,4,0)
This REQUEST statement stores the x-, y-, and z-component of the forces in FIELD/1001 in columns 2,
3, and 4, respectively. Adams/Solver (FORTRAN) calculates the forces at the I marker, and computes
results in the global coordinate system.
See other Element-specific applied force available.
FM 51
Adams/Solver (FORTRAN) Functions
FM
The FM function returns the magnitude of the net translational force acting at marker i. All force and
constraint elements between markers i and j are included in the calculation of the force, unless a force is
an action-only type. To return the magnitude of the action-only forces acting at marker i, you should omit
the specification of marker j or specify it to be zero.
Format
FM(i[,j])
Arguments
An integer that specifies the identifier of the marker at which the magnitude of the net force is
to be calculated.
A second integer that specifies a marker identifier. All forces acting between the [i,j] pair are
included in the calculation. Set j = 0 or do not specify it if you are interested in action-only
forces.
Examples
VARIABLE/1, FUNCTION=FM(23)
A user-defined state variable is specified by this VARIABLE statement. Its value is the magnitude of the
sum of all action-only forces acting at Marker 23.
VARIABLE/1, FUNCTION=FM(23,11)
A user-defined 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 available.
52 Adams/Solver
FORCOS
The FORCOS function evaluates a Fourier Cosine series at a user-specified value x. The x0, a0, a1,...,a30
are parameters used to define the constants for the Fourier Cosine series.
Format
A real variable that specifies the independent variable. For example, if the independent
variable in the function is time, x is the system variable TIME.
x0
A real variable that specifies the fundamental frequency of the series. Adams/Solver
(FORTRAN) assumes w is in radians per unit of the independent variable unless you use
a D after the value.
a0
A real variable that defines the constant bias term for the function.
a1,...,a30
The real variables that define as many as thirty-one coefficients for the Fourier Cosine
series.
Extended Definition
aj + Tj ( x xo )
F ( x ) = ao +
j=1
T j ( x x o ) = cos { j ( x x o ) }
The index j has a range from 1 to n, where n is the number of terms in the series.
Examples
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:
FORCOS 53
Adams/Solver (FORTRAN) Functions
FORCOS = 1+2*COS(1*360D*TIME)
+3*COS(2*360D*TIME)
+4*COS(3*360D*TIME)
54 Adams/Solver
FORSIN
The FORSIN function evaluates a Fourier Sine series at a user specified value x. x0,a0,a1,...,a30 are
parameters used to define the constants for the Fourier Sine series.
Format
A real variable that specifies the independent variable. For example, if the independent
variable in the function is time, x is the system variable TIME.
x0
A real variable that specifies the fundamental frequency of the series. Adams/Solver
(FORTRAN) assumes is in radians per unit of the independent variable unless you use
a D after the value.
a0
A real variable that defines the constant bias term for the function.
a1,...,a30
The real variables that define as many as thirty-one coefficients for the Fourier Sine series.
Extended Definition
F ( x ) = a0 +
a j T j ( x x 0 )
j=1
This MOTION statement defines a harmonic motion as a function of time. The motion has a -0.25 second
shift, a fundamental frequency of 0.5 cycle ( radians or 180 degrees) per time unit, and no constant
value. The function defined is:
FORSIN = 0+SIN( *(TIME+0.25))
+2*SIN(2 *(TIME+0.25))
+3*SIN(3 *(TIME+0.25))
FORSIN 55
Adams/Solver (FORTRAN) Functions
56 Adams/Solver
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
id
INDEX
An integer variable specifying the output component index to be returned. See the table
below for a list of component indices.
Friction Index
Index:
Name:
Description:
FFX
FFY
FFZ
FTX
FTY
FTZ
10
rx
11
ry
12
rz
13
14
Vx
Joint velocity at sliding surfaces along the x-axis of the JOINTs J marker
15
Vy
Joint velocity at sliding surfaces along the y-axis of the JOINTs J marker
16
Vz
17
Wx
18
Wy
19
Wz
FRICTION 57
Adams/Solver (FORTRAN) Functions
Index:
Name:
Description:
20
CREEP_X
21
CREEP_Y
22
CREEP_Z
23
CREEP_RX Static friction creep about the x-axis of the JOINTs J marker
24
CREEP_RY Static friction creep about the y-axis of the JOINTs J marker
25
CREEP_RZ Static friction creep about the z-axis of the JOINTs J marker
26
BETA
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
friction-force vector resolved in the associated J marker coordinate system of the JOINT.
Caution:
The FRICTION function is accessible only through the REQUEST and SENSOR function
expressions.
The FRICTION function evaluates to zero if the index corresponds to a force or velocity
which is not used by the corresponding friction model. For example, if FRICTION/2 from
above is applied on a translational joint, then FRICTION (2,1) would be zero because the
friction force is applied along the z axes of the joint.
58 Adams/Solver
FX
The FX function returns the x-component of the net translational force acting at marker i, as computed
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, unless a force is an action-only type force. To return the xcomponent of the action-only forces acting at marker i, you should omit specification of marker j or
specify it to be zero. Note that you can not specify marker k and omit marker j. In this case, you should
specify marker j to be zero.
Format
FX(i[,j][,k])
Arguments
An integer that specifies the identifier of the marker at which the magnitude of the net force is
to be calculated.
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 it if you are interested in action-only
forces.
An integer that specifies the identifier of a marker (coordinate system) in which the x-component
of the force is to be returned. k defaults to the global coordinate system when it is not specified.
Examples
VARIABLE/1, FUNCTION=FX(23,0,432)
A user-defined state variable is specified by this VARIABLE statement. Its value is FX(23,0,432). This
is the x-component of the sum of all the action-only forces acting at Marker 23 as computed in the
coordinate system of Marker 32.
See other Generic force available.
FXFREQ 59
Adams/Solver (FORTRAN) Functions
FXFREQ
The FXFREQ function returns the modal frequency in cycles per user-defined time for the current mode
of the current FLEX_BODY when used in function expressions defining the CRATIO argument of a
FLEX_BODY. (Learn more about FLEX_BODY). FXMODE returns zero when used in other
expressions.
Format
FXFREQ
Extended Definition
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.
60 Adams/Solver
FXMODE
The FXMODE function returns the mode number of the current mode of the current FLEX_BODY when
used in function expressions defining the CRATIO argument of a FLEX_BODY. FXMODE returns zero
when used in other expressions. (Learn more on FLEX_BODY.)
Format
FXMODE
Extended Definition
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.
FY 61
Adams/Solver (FORTRAN) Functions
FY
The FY function returns the y-component of the net translational force acting at marker i, as computed
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, unless a force is an action-only type force. To return the ycomponent of the action-only forces acting at marker i, you should omit specification of marker j or
specify it to be zero. Note that you can not specify marker k and omit marker j. In this case, you should
specify marker j to be zero.
Format
FY(i[,j][,k])
Arguments
An integer that specifies the identifier of the marker at which the magnitude of the net force is to
be calculated.
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 it if you are interested in action-only
forces.
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.
Examples
SFORCE/1, I=132, J=234, TRANSLATION, ACTIONONLY
, FUNCTION=-0.3*FY(677,866)
This SFORCE statement defines a translation, action-only force acting at Marker 132. The force is
directed along the z-axis of Marker 234. The value of the force is -0.3 times the y-component of the net
force along the global y-axis, acting at Marker 677. All forces acting between Markers 677 and 866 are
included in this calculation.
See other Generic force available.
62 Adams/Solver
FZ
The FZ function returns the z-component of the net translational force acting at marker i, as computed 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, unless a force is an action-only type force. To return the zcomponent of the action-only forces acting at marker i, you should omit specification of marker j or
specify it to be zero. Note that you can not specify marker k and omit marker j. In this case, you should
specify marker j to be zero.
Format
FZ(i[,j][,k])
Arguments
An integer that specifies the identifier of the marker at which the magnitude of the net force is to
be calculated.
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 it if you are interested in action-only
forces.
An integer that specifies the identifier of a marker (coordinate system) in which the z-component
of the force is to be returned. k defaults to the global coordinate system when it is not specified.
Examples
SFORCE/1, I=23, J=11, TRANSLATION, ACTIONONLY
, FUNCTION=STEP5(FX(34), -1.5, -200, 1.5, 200)
This SFORCE statement defines a translational, action-only, nonlinear force. The force is directed along
the z-axis of Marker 11. The value of the force is a 5th order step function (see STEP5). The independent
variable for the STEP5 function is FZ(34), the net force acting along the global z-axis at Marker 34. Since
no j marker is specified, only action-only forces acting at Marker 34 are included in the calculation of
FZ().
See other Generic force available.
GFORCE 63
Adams/Solver (FORTRAN) 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 (FORTRAN) returns the value of the force/torque that
acts on the I marker of GFORCE/id. If jflag is set to 1, Adams/Solver (FORTRAN) returns the value that
acts on the J marker. To obtain results in the global coordinate system, you can specify rm as zero.
Format
id
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
rm
The coordinate system in which the results are expressed. To return the results in the
global coordinate system, set rm = 0.
Examples
GFORCE/1, I=516, J=34, RM=23
, FX=-0.3*GFORCE(1,0,4,23)/
, FY=0/
, FZ=IMPACT(DZ(516,0,23),VZ(516,0,23,23),4.6,1e5,1.5,10,0.01)
This GFORCE statement defines a force acting at Marker 516. The components of the force are defined
along the x-, y-, z-axes of Marker 23.
The x-component of the force is -0.3 times the z-component of the force.
The z-component of the force is defined as an impact force (see IMPACT ) that is a function of the
displacement and velocity of Marker 516, as seen by Marker 23.
See other Element-specific applied force available.
64 Adams/Solver
HAVSIN
The HAVSIN function defines a haversine function. It is used most often to represent a smooth transition
between two functions.
Format
x0
A real variable that specifies the x value at which the haversine function begins.
x1
A real variable that specifies the x value at which the haversine function ends.
h0
h1
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
HAVSIN 65
Adams/Solver (FORTRAN) Functions
ho
h1
Tip:
x x0
x0 < x < x1
x x1
The HAVSIN function behavior is similar to the STEP function. It has a discontinuous
second derivative and therefore is not recommended for use in displacement level motions.
Examples
MOTION/1, JOINT=21, VELOCITY
, FUNCTION=HAVSIN(TIME, 1, 0, 2, 1)
This MOTION statement defines a smooth transition in velocity from time 1 to time 2. Note that the
motion is specified in velocity rather than displacement.
See other General available.
66 Adams/Solver
IF
The arithmetic IF function allows you to conditionally define a function expression.
IF (expression 1: expression 2, expression 3, expression 4)
Adams/Solver (FORTRAN) evaluates expression 1.
If the value of expression 1 is less than zero, the arithmetic IF is evaluated using expression 2.
If the value of expression 1 is zero, the arithmetic IF is evaluated using expression 3.
If the value of expression 1 is greater than zero, the arithmetic IF is evaluated using expression 4.
test
Any valid function expression. Adams/Solver (FORTRAN) evaluated the test expression to
determine which branch of the arithmetic IF, lt, eq, or gt will be selected.
lt
Any valid function expression. If the value of the test expression is less than zero,
Adams/Solver (FORTRAN) evaluates the lt expression and the IF function takes the value
of lt. Otherwise, the lt expression is not evaluated.
eq
Any valid function expression. If the value of the test expression is equal to zero,
Adams/Solver (FORTRAN) evaluates the eq expression and the IF function takes the value
of eq. Otherwise, the eq expression is not evaluated.
gt
Any valid function expression. If the value of the test expression is equal to zero,
Adams/Solver (FORTRAN) evaluates the gt expression and the IF function takes the value
of gt. Otherwise, the gt expression is not evaluated.
Caution:
When using an arithmetic IF function, ensure that the resulting function is continuous. If
the function is discontinuous, Adams/Solver (FORTRAN) may fail to find a solution when
it encounters the discontinuity. Even the greater reliability can be achieved if continuity of
the first derivative can be ensured.
Much greater care is required when using an arithmetic IF function to define a MOTION
element. In this case, a continuous second derivative is also required. The use of arithmetic
IF functions to define MOTION is best avoided.
IF 67
Adams/Solver (FORTRAN) Functions
Examples
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.
68 Adams/Solver
IMPACT
IThe IMPACT function models collisions.
Format
An expression that specifies a distance variable used to compute the IMPACT function. For
example, if you use the x displacement of Marker 0201 with respect to Marker 0301, then x
is DX(0201,0301,0301). See DX.
An expression that specifies the time derivative of x to IMPACT. For example, if x is
DX(0201,0301), then x is VX(0201,0301,0,0301).
x1
A positive real variable that specifies the free length of x. If x is less than x1, then
Adams/Solver (FORTRAN) calculates a positive value for the force. Otherwise, the force
value is zero. You can define x1 as a real number, function, or variable.
A non-negative real variable that specifies the stiffness of the boundary surface interaction.
A 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.
cmax
A positive real variable that specifies the boundary penetration at which Adams/Solver
(FORTRAN) applies full damping.
Extended Definition
The IMPACT function activates when the distance between the I and the J markers falls below a nominal
free length (x1), that is, when two parts collide. As long as the distance between the I and J markers is
greater than x1, the force is zero. An example of a system you can model with the IMPACT function is a
ball falling towards the ground. Figure 3 below shows the free length value x1 at which the IMPACT
force turns on.
The force has two components, a spring or stiffness component and a damping or viscous component.
The stiffness component is proportional to k, and is a function of the penetration of the I marker within
the free length distance from the J marker. The stiffness component opposes the penetration. The
damping component of the force is a function of the speed of penetration. The damping opposes the
direction of relative motion. To prevent a discontinuity in the damping force at contact, the damping
coefficient is, by definition, a cubic step function of the penetration. Thus, at zero penetration, the
damping coefficient is always zero. The damping coefficient achieves a maximum, cmax, at a userdefined penetration, d.
IMPACT 69
Adams/Solver (FORTRAN) Functions
Figure 3
x < x1
x x1
x1 - x).
Also note that when p < d, the instantaneous damping coefficient is a cubic step function of the
penetration p.
When p > d, the instantaneous damping coefficient is cmax.
Adams/Solver (FORTRAN) never returns a negative force for IMPACT. If the above expression is
negative, Adams/Solver (FORTRAN) returns a value of zero.
Figure 4 below is a plot of damping coefficient versus penetration.
70 Adams/Solver
Figure 4
Tip:
Caution:
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.
For maximum performance, define e > 1. When e is < 1, the defined force contains
The reason for this is that the contact force due to penetration is defined as:
dg
dt
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.
IMPACT 71
Adams/Solver (FORTRAN) 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 single-component force at Marker 11 and along the z-axis of Marker 21. DZ(11,21,21) defines the
instantaneous displacement of Marker 11 with respect to Marker 21 along the z-axis of Marker 21.
VZ(11,21,21,21) defines the instantaneous velocity.
The free length is 1; that is, the radius of the ball is 1 unit. The stiffness is 100, and the exponent of
deformation is 1.5, the maximum damping coefficient is 25. The penetration at which Adams/Solver
(FORTRAN) applies full damping is 0.1.
VFORCE/1, I=27, JFLOAT=25, RM=26
, FX=0/
, FY=IMPACT(DY(4,1,1), VY(4,1,1), 1-AKISPL(DX(4,1,1),
, DZ(4,1,1),3),le7, 1.01, le4,.25)/
, FZ=0
This statement defines an impact force when a ball penetrates a surface defined by a spline. The force is
a translational force at Marker 27. The DY(4,1,1) defines the y-component of the instantaneous
displacement of Marker 4 with respect to Marker 1. The VY(4,1,1) defines the y-component of the
instantaneous velocity. The free length is defined using spline 3, which represents the surface.
The independent variables in the spline are defined using the x-component and z-component of the
instantaneous displacement of Marker 4 with respect to Marker 1, DX(4,1,1) and DZ(4,1,1), respectively.
The stiffness is le7, the exponent of deformation is 1.01, the maximum damping coefficient is le4, and
the penetration at which Adams/Solver (FORTRAN) applies full damping is 0.25.
See other General available.
72 Adams/Solver
INCANG
The INCANG function computes the included angle between the line defined by markers i and j, and the
line defined by markers j and k. The three markers can be on separate parts.
Note:
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 available.
INTERP 73
Adams/Solver (FORTRAN) Functions
INTERP
IThe INTERP function returns the iord derivative of the interpolated value of SPLINE/id at time=x. The
INTERP function supports time-series splines, which are splines that include a FILE argument that
specifies a time history file of type DAC or RPC III.
Format
A real variable that specifies the value of time, the independent variable along the x-axis of
the time series spline that is being interpolated.
method
An integer variable that specifies the method of interpolation, either linear or cubic
interpolation.
Range: method = 1 (linear interpolation)
method = 3 (cubic interpolation)
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
Extended Definition
The INTERP function uses linear or cubic interpolation to create a function across a set of data points.
The data points are defined in a SPLINE statement in the Adams/Solver data deck. The SPLINE
statement with the FILE argument that you define in the Adams/Solver dataset must reference a time
series file of type DAC or RPC III. For more information on these file types, see Adams/Durability.
In general, the INTERP function with linear interpolation will not be a smooth function because, in
almost all cases, the function will be discontinuous in the first derivative. Therefore, the estimate of the
first derivative may be erroneous even though, by definition, the data points of a DAC or RPC time
history file are evenly spaced. In all cases, the second derivative of the function being approximated is
unreliable with linear interpolation.
On the other hand, with cubic interpolation, the INTERP function will be continuous to the second
derivative. Therefore, we recommend that you use cubic interpolation, especially if first or second
derivatives of the function will be evaluated.
74 Adams/Solver
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 method of interpolation.
See other Interpolation available.
INVPSD 75
Adams/Solver (FORTRAN) Functions
INVPSD
IThe INVPSD (Inverse Power Spectral Density) function regenerates a time signal from a power spectral
density description.
Format
id
The id number of the spline containing the PSD versus frequency data.
f0
f1
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.
Extended Definition
nf
INVPSD =
( Ai sin ( 2fi x + i ) )
i=1
The regenerated signal consists of a series of sinusoidal functions where the amplitudes, Ai, are
determined in such a way that the effective value for the PSD and the time signal are the same. The phase
angle,
Using the same seed value will always result in the same set of phase angles.
76 Adams/Solver
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
Figure 6
JOINT 77
Adams/Solver (FORTRAN) 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
id
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.
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 z-axis of Marker 23 opposes this motion.
JOINT(1,0,1,23) determines the magnitude of the reaction force at Marker 23. JOINT(1,0,4,23)
determines the component of the constraint force along the axis of the rotational of the joint.
JOINT(1,0,12)-ABS(JOINT(1,0,4,23)) defines the radial load in the revolute joint (i.e., the normal
force). See other Element-specific reaction force available.
78 Adams/Solver
JPRIM
JThe 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
id
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.
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.
See other Element-specific reaction force available.
LOG 79
Adams/Solver (FORTRAN) Functions
LOG
The LOG function returns the natural logarithm an expression a. If ex=a then LOG(a)=x. The LOG
function is defined only for positive values of a (that is, a > 0). It is undefined for all other values.
Format
LOG(a)
Arguments
Any valid function expression that returns a positive value during a simulation.
Number of Arguments: 1
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 available.
80 Adams/Solver
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
a1
a2
Caution:
The MAX function is generally discontinuous. Use this function expression with care when
you are specifying force or motion input.
Examples
SFORCE/1, ROTATIONAL, ACTIONONLY, I=21, J=11
, FUNCTION=MAX(0,-3*(AZ(21,11)-25D))
This SFORCE statement defines an action-only torque that acts at Marker 21 and acts along the z-axis of
Marker 11. The torque is defined to always be non-negative through the use of the MAX function. Thus,
the torque can only act to decrease the AZ rotation of Marker 21 with respect to Marker 11 (see AZ).
See other FORTRAN 77 available.
MIN 81
Adams/Solver (FORTRAN) 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
a1
a2
Caution:
The MIN function is generally discontinuous. Use this function expression with care when
you are specifying force or motion input.
Examples
SFORCE/1, ROTATIONAL, ACTIONONLY, I=21, J=11
, FUNCTION=MIN(0,-3*(AZ(21,11)-25D))
This SFORCE statement defines an action-only torque that acts at Marker 21 and acts along the z-axis of
Marker 11. The torque is defined to always be 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 available.
82 Adams/Solver
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
a1
a2
Caution:
The MOD function is generally discontinuous. Use this function expression with care when
you are specifying force or motion input.
Examples
MOD(45,16)=13
See other FORTRAN 77 available.
MODE 83
Adams/Solver (FORTRAN) Functions
MODE
The MODE function returns the current analysis mode. These are defined as:
1 = Kinematics
2 = Reserved
3 = Initial conditions
4 = Dynamics
5 = Statics
6 = Quasi-statics
7 = Linear analysis
Format
MODE
Caution:
Use the MODE function with care if you use the STATICS argument on the SIMULATE
command to request a static or quasi-static simulation of a kinematic system,
Adams/Solver (FORTRAN) performs a kinematic analysis and, consequently, returns a
MODE analysis constant of 1 (not 5 or 6).
Examples
SFORCE/1, TRANSLATION, I=21, J=11
, FUNCTION=IF(MODE-4:0,0,-4*(DM(21,11)-10.6))
This example defines a translational force that is active only during statics, quasi-static, and linear
analysis modes. For these analysis modes, the SFORCE acts as a simple spring. For all other analyses,
the net force applied by the SFORCE is zero.
See other Simulation constants and variables available.
84 Adams/Solver
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
id
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.
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 Element-specific reaction force available.
NFORCE 85
Adams/Solver (FORTRAN) Functions
NFORCE
The NFORCE function returns component comp of a force due to NFORCE/id acting at the marker,
at_marker, as calculated in the coordinate system of marker rm. The rm marker may be specified as zero
if the results are desired in the global coordinate system. The marker must be one of the I or J markers to
which NFORCE/id connects.
Format
id
at_marker
An integer marker identifier specifying the NFORCE connectivity marker at which the
forces and torques are computed.
comp
rm
The coordinate system in which the results are expressed. To return the results in the
global coordinate system, set rm = 0.
86 Adams/Solver
Cautions
Adams/Solver
(FORTRAN)
The NFORCE function is
Adams/Solver (C++)
Unlike Adams/Solver (FORTRAN), the NFORCE measure can
measure from the SYSFNC utility subroutine. Instead, use the FX,
FY, and FZ. measures. These can either be used to measure the sum
of forces on a single marker, or the sum of forces transmitted by all
connectors connecting a pair of markers. Unfortunately, these
measures can not directly compute the force transmitted between
two I markers on an NFORCE and something similar to FX(I1,J)FX(I2,J) may be required.
PHI 87
Adams/Solver (FORTRAN) Functions
PHI
The PHI function calculates the third angle (in radians) of a body-fixed-3-1-3 Euler rotation sequence
between markers i and j. Marker j defaults to the global coordinate system if it is not specified. See
Figure 7 for a schematic description of the body-fixed-3-1-3 Euler rotation sequence.
Format
PHI(i[,j])
Arguments
The marker with respect to which the rotations are being measured.
Examples
REQUEST/1, F2=PHI(222,434)
This REQUEST statement output the phi angle between Markers 222 and 434 in its second column.
See other Displacement available.
88 Adams/Solver
Figure 7
PHI 89
Adams/Solver (FORTRAN) Functions
90 Adams/Solver
PI
PI returns the ratio of the circumference of a circle to its diameter (3.14159...).
Format
PI
See other Simulation constants and variables available.
PINVAL 91
Adams/Solver (FORTRAN) Functions
PINVAL
The PINVAL function returns component comp of PINPUT/id.
Format
id
comp
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 available.
92 Adams/Solver
PITCH
Calculates the second angle of a body-fixed 3 -2 1 yaw-pitch-roll 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
The marker with respect to which the rotations are being measured.
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 available.
POLY 93
Adams/Solver (FORTRAN) Functions
POLY
The POLY function evaluates a standard polynomial at a user-specified value x.
Format
A real variable that specifies the independent variable. For example, if the
independent variable in the function is time, x is the system variable TIME.
x0
The real variables that define as many as thirty-one coefficients for the polynomial
series.
Extended Definition
The POLY function evaluates a standard polynomial at a user-specified value x. x0, a0, a1,..., a30 are
parameters used to define the constants for the polynomial. The standard polynomial is defined as:
n
P( x) =
aj ( x x0 )j
j=0
= a 0 + a 1 ( x x 0 ) + a 2 ( x x 0 ) 2 + + a n ( x x 0 ) n
The index j has a range from zero to n, where n is the number of terms in the series.
Examples
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(TIME-5: 0, 0, POLY(TIME, 5, 0, 10))
This MOTION statement uses an arithmetic IF in its function expression to switch between functions.
The expanded function is:
if (time > 5) then Poly=0
94 Adams/Solver
else Poly=10*time-5
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 General available.
POUVAL 95
Adams/Solver (FORTRAN) Functions
POUVAL
The POUVAL function returns component comp of POUTPUT/id.
Format
id
comp
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 available.
96 Adams/Solver
PSI
The PSI function expression calculates the first angle (in radians) of a body-fixed 3-1-3 Euler rotation
sequence between markers i and j. Marker j defaults to the global coordinate system if it is not specified.
For a schematic of the body-fixed-3-1-3 Euler angles, click here.
Format
PSI(i[,j])
Arguments
The marker with respect to which the rotations are being measured.
Examples
REQUEST/1, F2=PSI(222,434)
This REQUEST statement output the psi angle between Markers 222 and 434 in its second column.
See other Displacement available.
PTCV 97
Adams/Solver (FORTRAN) 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
id
jflag
An integer flag specifying the point-to-curve 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 point-to-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.
Examples
REQUEST/1
,
,
,
,
,
,
,
F2=PTCV(31,0,2,0)/
F3=PTCV(31,0,3,0)/
F4=PTCV(31,0,4,0)/
F5=PTCV(31,0,5,0)/
F6=PTCV(31,0,6,0)/
F7=PTCV(31,0,7,0)/
F8=PTCV(31,0,8,0)/
This REQUEST statement outputs the x-, y-, and z-components of the force and torque at the I marker
of PTCV/31. Since rm is specified as zero, all vectors are expressed in the global coordinate system.
See other Element-specific reaction force available.
98 Adams/Solver
ROLL
The ROLL function calculates the third angle of a body-fixed 3 -2 1 yaw-pitch-roll rotation sequence
between markers i and j. Marker j defaults to the global coordinate system if it is not specified. Note that
roll is an Euler angle.
Format
ROLL (i[,j])
Arguments
The marker with respect to which the rotations are being measured.
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 available.
RTOD 99
Adams/Solver (FORTRAN) Functions
RTOD
RTOD returns the radians to degrees conversion factor.
Format
RTOD
Examples
REQUEST/1, F2=ROLL(23,14)*RTOD
This REQUEST statement outputs the roll angle between Markers 23 and 14 in degrees.
See other Simulation constants and variables available.
100 Adams/Solver
SENVAL
The SENVAL function returns the last scored value from the function expression or user-written
subroutine associated with the EVALUATE argument on SENSOR/id. See the SENSOR statement for
more information.
Format
SENVAL(id)
Arguments
id
Caution:
If the SENSOR/id does not have the EVALUATE argument, SENVAL(id) returns zero.
Examples
VARIABLE/1, FUNCTION=SENVAL(100)
SENSOR/100, EQ, VALUE=0
, FUNCTION=AZ(22,11)-PI/2/
, EVALUATE=SENVAL(100) +1
This SENSOR statement counts the number of times function AZ(22,11) passes through
VARIABLE statement defines a variable equal to the count.
/2. The
SFORCE 101
Adams/Solver (FORTRAN) Functions
SFORCE
The SFORCE function returns component comp of a force due to SFORCE/id as calculated in the
coordinate system of marker rm. If jflag is set to zero, the value returned is the force or torque acting on
the I marker of the SFORCE/id. If jflag is set to 1, the value returned is that which acts on the J marker.
You can specify rm as zero if you want the results to be returned in the global coordinate system.
Format
id
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
rm
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 z-components 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 Element-specific applied force available.
102 Adams/Solver
SHF
The SHF function evaluates a simple harmonic function. The following equation defines SHF:
SHF = a*sin( *(x-x0)-phi)+b
Format
The independent variable in the function. It may be any valid expression. For example, if the
independent variable in the function is twice the current simulation time, x is the system
variable 2*TIME.
x0
The 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.
Examples
MOTION/1, JOINT=21, TRANSLATION
, FUNCTION=SHF(TIME, 25D, PI, 360D, 0, 5)
SIGN 103
Adams/Solver (FORTRAN) Functions
SIGN
The SIGN function transfers the sign of a2 to the magnitude of a1.
SIGN(a1,a2) = ABS(a1) if a2 > 0
SIGN(a1,a2) = -ABS(a1) if a2 < 0
Format
SIGN (a1,a2)
Arguments
a1
a2
Caution:
The SIGN function is discontinuous. Use this function with care to avoid creating
expressions that are discontinuous.
Examples
VARIABLE/23, FUNCTION=10*SIGN(DM(24,33),VZ(24,33))
When VZ(24,33) >0, the value of VARIABLE/23 is +10*DM(24,33). When VZ(24,33) < 0, the value of
VARIABLE/23 is -10*DM(24,33).
See other FORTRAN 77 available.
104 Adams/Solver
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 available.
SINH 105
Adams/Solver (FORTRAN) Functions
SINH
The SINH function return the hyperbolic sine of an expression a.
SINH(a) = (ea - e-a) /2.0
Format
SINH(a)
Arguments
Examples
VARIABLE/1, FUNCTION=SINH(DX(21,32))
The value of VARIABLE/1 is the hyperbolic sine of the x-component of the displacement between
Markers 21 and 32, as calculated in the global coordinate system.
See other FORTRAN 77 available.
106 Adams/Solver
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
id
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
Examples
REQUEST/1
, F2=SPDP(31,0,2,0)/
, F3=SPDP(31,0,3,0)/
, F4=SPDP(31,0,4,0)/
, F5=SPDP(31,0,5,0)/
, F6=SPDP(31,0,6,0)/
, F7=SPDP(31,0,7,0)/
, F8=SPDP(31,0,8,0)
This REQUEST statement output the x-, y- and z-components of the force and torque at the I marker of
SPDP/31. Since rm is specified as zero, all vectors are expressed in the global coordinate system.
See other Element-specific applied force available.
SQRT 107
Adams/Solver (FORTRAN) Functions
SQRT
The SQRT function returns the square root of an expression a. The square root function is defined only
for non-negative values of the argument a.
Format
SQRT(a)
Arguments
Examples
VARIABLE/23,
, FUNCTION=SQRT (FX(23,11)**2+FY(23,11)**2)
A new state variable with a value equal to the square root of the sum of the squares of the global x- and
y- components of the net force acting between Markers 21 and 11.
See other FORTRAN 77 available.
108 Adams/Solver
STEP
The STEP function approximates the Heaviside step function with a cubic polynomial. It has continuous
first derivatives. Its second derivatives are discontinuous at x=x0 and x=x1.
Format
x0
A real variable that specifies the x value at which the STEP function begins.
x1
A real variable that specifies the x value at which the STEP function ends.
h0
h1
Extended Definition
The STEP function approximates the Heaviside step function with a cubic polynomial. The figure below
illustrates the STEP function.
Step Function
STEP 109
Adams/Solver (FORTRAN) Functions
a = h1 h0
= ( x x0 ) ( x1 x0 )
h0
STEP = h 0 + a 2 ( 3 2 )
h1
Tip:
x x0
x0 < x < x1
x x1
HAVERSINE, STEP5, and TANH offer other approximations for the Heaviside step
function. These (except for HAVERSINE) have a higher degree of continuity and
differentiability, but may have larger derivatives.
The figure shown next compares the STEP, STEP5, HAVSIN, and TANH functions.
Comparisons of STEP, STEP5, HAVSIN, and TANH
The next figure shows the first derivatives of these four functions.
110 Adams/Solver
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 secondorder 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 General available.
STEP5 111
Adams/Solver (FORTRAN) Functions
STEP5
The STEP5 function provides approximation to the Heaviside step function with a quintic polynomial. It
has continuous first and second derivatives. Its third derivative is discontinuous at x=x0 and x=x1.
Format
x0
A real variable that specifies the x value at which the STEP5 function begins.
x1
A real variable that specifies the x value at which the STEP5 function ends.
h0
h1
Extended Definition
= h1 - h0
= (x - x0)/(x1 - x0)
112 Adams/Solver
h0
STEP5 = h 0 + a 3 [ 10 15 + 6 2 ]
h1
x x0
x0 < x < x1
x x1
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 General available.
SWEEP 113
Adams/Solver (FORTRAN) Functions
SWEEP
The SWEEP function returns a constant amplitude sinusoidal function with linearly increasing
frequency.
Format
x0
The value of the independent variable at which the SWEEP function begins.
f0
x1
The value of the independent variable value at which the SWEEP function ends
f1
dx
Extended Definition
where:
f0
f1 f0
freq ( x ) = f 0 + ---------------- x
x0 + x1
f1
: x < x0
: x0 < x < x1
: x1 < x
114 Adams/Solver
: x < x0
f0 x
( f1 f0 )
: x 0 < x < x 1
f 0 ( x x 0 ) + ------------------------ ( x x 0 ) 2 + f 0 x 0
2 ( x1 x0 )
f req ( x )dx =
( f1 f0 )
2
- ( x1 x0 ) : x < x0
f 1 ( x x 1 ) + f 0 x 0 + f 0 ( x 1 x 0 ) + ----------------------
2
(
x
x
)
1
0
Examples
The following example defines motion with a sinusoidal function with a rising frequency from 2 to 6Hz
during the time interval 0 to 5.
MOTION/1,JOINT=1
, FUNCTION=SWEEP(TIME, 1.0, 0.0, 2.0, 5.0, 6.0, 0.01)
SWEEP 115
Adams/Solver (FORTRAN) Functions
116 Adams/Solver
TAN
The TAN function returns the tangent of an expression a.
Format
TAN(a)
Arguments
TANH 117
Adams/Solver (FORTRAN) Functions
TANH
The TANH function returns the hyperbolic tangent of an expression a.TANH(a) = (ea - e-a) / (ea + e-a)
Format
TANH(a)
Arguments
Extended Definition
Examples
MOTION/1, JOINT=21, TRANSLATION
, FUNCTION=0.5(1+TANH(5*(TIME-1.5)))
This MOTION statement defines a smooth step function that transitions from a value of 0 to 1. The value
of the step function at time=1.5 is 0.5.
See other FORTRAN 77 available.
118 Adams/Solver
THETA
The THETA function calculates the second angle (in radians) of a body-two fixed 3-1-3 Euler rotation
sequence between markers i and j. Marker j defaults to the global coordinate system if it is not specified.
View a schematic of the body-fixed-3-1-3 Euler angles.
Format
THETA(i[,j])
Arguments
The marker with respect to which the rotations are being measured.
Examples
REQUEST/1, F2=THETA(222,434)
This REQUEST statement output the THETA angle between Markers 222 and 434 in its second column.
See other Displacement available.
TIME 119
Adams/Solver (FORTRAN) Functions
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 constants and variables available.
120 Adams/Solver
TM
The TM function returns the magnitude of the net torque acting at marker i. All force and constraint
elements between markers i and j are included in the calculation of torque, unless it is an action-only type.
To return the torque magnitude of the action-only forces acting as marker i, you should omit specification
of marker j, or specify it to be zero.
Format
TM(i[j])
Arguments
An integer that specifies the identifier of the marker at which the magnitude of the net torque is
to be calculated.
A second integer that specifies a marker identifier. All torques acting between the [i,j] pair are
to be included in the calculation. Set j = 0 or do not specify it if you are interested in action-only
torques.
Examples
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
algebraically determined state variable VARIABLE/31 is defined to have the magnitude of the net torque
between these two markers as its value.
The TM function returns the magnitude of the net torque acting at marker i. All force and constraint
elements between markers i and j are included in the calculation of torque, unless it is an action-only type.
To return the torque magnitude of the action-only forces acting as marker i, you should omit specification
of marker j, or specify it to be zero.
See other Generic force available.
TX 121
Adams/Solver (FORTRAN) Functions
TX
The TX function returns the x-component of the net torque acting at marker i, as computed 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, unless a force element is an action-only type force. To return
the x-component of the action-only torques acting at marker i, you should omit specification of marker j
or specify it as zero. Note that you can not specify marker k and omit marker j. In this case, you should
specify marker j to be zero.
Format
TX(i[,j][,k])
Arguments
An integer that specifies the identifier of the marker at which the magnitude of the net torque
is to be calculated.
A second integer that specifies a marker identifier. All torques acting between the [i,j] pair are
to be included in the calculation. Set j = 0 or do not specify it if you are interested in actiononly torques.
An integer that specifies the identifier of a marker (coordinate system) in which the xcomponent of the torque is to be returned. k defaults to the global coordinate system when it is
not specified.
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 x-component of the sum of all torques acting between
markers 32 and 44 as computed in the global coordinate system. Since joint 1 and motion 1 are defined
between markers 32 and 44, their reaction torque will be included in the computation of TX().
See other Generic force available.
122 Adams/Solver
TY
The TY function returns the y-component of the net torque acting at marker i as computed 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, unless a force element is an action-only type force. To return
the y-component of the action-only torques acting at marker i, you should omit specification of marker j
or specify it as zero. Note that you can not specify marker k and omit marker j. In this case, you should
specify marker j to be zero.
Format
TY(i[,j][,k])
Arguments
An integer that specifies the identifier of the marker at which the magnitude of the net torque is
to be calculated.
A second integer that specifies a marker identifier. All torques acting between the [i,j] pair are
to be included in the calculation. Set j = 0 or do not specify it if you are interested in action-only
torques.
An integer that specifies the identifier of a marker (coordinate system) in which the ycomponent of the torque is to be returned. k defaults to the global coordinate system when it is
not specified.
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 y-component of the sum of all torques acting between
markers 32 and 44 as computed in the global coordinate system. Since joint 1 and motion 1 are defined
between markers 32 and 44, their reaction torque will be included in the computation of TY( ).
See other Generic force available.
TZ 123
Adams/Solver (FORTRAN) Functions
TZ
The TZ function returns the z-component of the net torque acting at marker i as computed 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, unless a force element is an action-only type force. To return
the z-component of the action-only torques acting at marker i, you should omit specification of marker j
or specify it as zero. Note that you can not specify marker k and omit marker j. In this case, you should
specify marker j to be zero.
Format
TZ(i[,j][,k])
Arguments
An integer that specifies the identifier of the marker at which the magnitude of the net torque is
to be calculated.
A second integer that specifies a marker identifier. All torques acting between the [i,j] pair are to
be included in the calculation. Set j = 0 or do not specify it if you are interested in action-only
torques.
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.
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 z-component of the sum of all torques
acting between markers 32 and 44 as computed in the global coordinate system. Since joint 1 and motion
1 are defined between markers 32 and 44, their reaction torque will be included in the computation of
TZ().
See other Generic force available.
124 Adams/Solver
VARVAL
The VARVAL function returns current value of VARIABLE/id.
Format
VARVAL (id)
Arguments
id
Examples
VARIABLE/10, FUNCTION=DX(21,32,43)
SFORCE/20, TRANSLATION, I=346, J=567
, FUNCTION=(VARVAL(10)-5)**2
VFORCE 125
Adams/Solver (FORTRAN) 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 (FORTRAN) returns the value of force/torque that acts
on the I marker of VFORCE/id. If jflag is set to 1, Adams/Solver (FORTRAN) returns the value that acts
on the J marker. To obtain results in the global coordinate system, you can specify rm as zero.
Format
id
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
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)/s
This REQUEST statement contains the x-component of the force exerted by VFORCE/19 calculated in
the coordinate system of Marker 168.
See other Element-specific applied force available.
126 Adams/Solver
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
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.
The reference frame in which the time derivative of the displacement vector is taken. Set l = 0
or omit the argument if you want the time derivatives to be taken in the ground coordinate
system (GCS).
Extended Definition
(l)
VM ( i, j, l ) =
where
Ri
d
Ri
dt2
(l)
d
Rj
dt2
(l)
Rj
d
Ri
dt2
(l)
d
Rj
dt2
Examples
DIFF/51, IC=-6.2, FUNCTION=VM(23,0,32)
A dynamically determined user state is defined by DIFF/51. The time derivative of the user-state is the
magnitude of the velocity of the origin of Marker 23 with respect to ground. The time derivative for the
velocity computation is taken in the reference frame of Marker 32.
VARIABLE/1, FUNCTION=VM(21,32,43)
This VARIABLE statement defines an algebraic, user-defined state whose instantaneous value is the
magnitude of the velocity vector between Markers 21 and 32, as seen by an observer at Marker 43.
See other Velocity available.
VR 127
Adams/Solver (FORTRAN) Functions
VR
The VR function calculates the radial (separation) velocity of marker i with respect to marker j. The
vector time derivative is taken in the reference frame of marker l. Markers j and l default to the global
coordinate system if they are not specified.
Format
VR(i[,j][,l])
Arguments
The marker with respect to which the velociy is being measured. Set j = 0, while still specifying l,
if you want j default to the global coordinate system.
The reference frame in which the time derivative of the displacement vector is taken. Set l = 0 or
omit the argument if you want the time derivatives to be taken in the ground coordinate system
(GCS).
Extended Definition
Mathematically, VR is calculated by projecting the velocity vector on a unit vector along the line of sight
between i and j, as follows:
(l) d
(l) d
Ri
Rj [ Ri Rj ]
dt
dt
VR ( i, j, l ) = ----------------------------------------------------------------------- = VXYZ UV ( DXYZ )
[ Ri Rj ] [ Ri Rj ]
where:
Ri
Rj
As markers i and j separate from each other, VR is positive. VR is negative when markers i and j approach
each other.
128 Adams/Solver
Examples
SFORCE/1, TRANSLATION, I=467, J=764
, FUNCTION=-10*VR(467,764)
! defines a translational damper with a damping constant of 10.
VTORQ 129
Adams/Solver (FORTRAN) Functions
VTORQ
The VTORQ function returns the component comp of force in VTORQUE/id in the coordinate system
of marker rm. If jflag is set to zero, Adams/Solver (FORTRAN) returns the value of the torque that acts
on the I marker of VTORQUE/id. If jflag is set to 1, Adams/Solver (FORTRAN) returns the value that
acts on the J marker. To obtain results in the global coordinate system, you can specify rm as zero.
Format
id
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
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 x-component of the torque exerted by VTORQUE/19 calculated
in the coordinate system of Marker 168.
See other Element-specific applied force available.
130 Adams/Solver
VX
The VX function returns the x-component of the difference between the velocity vector of marker i and
the velocity vector of marker j as computed in the coordinate system of marker k. All vector time
derivatives are taken in the reference frame of marker l. Marker j defaults to the global coordinate system
if it is not specified. Similarly, markers i and j default to the global coordinate system if they are not
specified.
Format
VX(i[,j][,k][,l])
Arguments
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.
The marker in whose coordinate system the velocity vector is being expressed. Set k = 0, while
still specifying l, if you want the results to be calculated along the x-axis of the global coordinate
system.
The reference frame in which the first time derivative of the displacement vector is taken. Set l
= 0 or omit the argument if you want the time derivatives to be taken in the ground coordinate
system (GCS).
Extended Definition
VX ( i, j, k, l ) =
(l) d
dt
Ri
(l)
d
R j x k
dt
where:
Ri
Rj
(l) d
dt
VX 131
Adams/Solver (FORTRAN) 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 available.
132 Adams/Solver
VY
The VY function returns the y-component of the difference between the velocity vector of marker i and
the velocity vector of marker j as computed in the coordinate system of marker k. All vector time
derivatives are taken in the reference frame of marker l. Marker j defaults to the global coordinate system
if it is not specified. Similarly, markers i and j default to the global coordinate system if they are not
specified.
Format
VY(i[,j][,k][,l])
Arguments
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.
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 y-axis of the global coordinate
system.
The reference frame in which the first time derivative of the displacement vector is taken. Set l
= 0 or omit the argument if you want the time derivatives to be taken in the ground coordinate
system (GCS).
Extended Defintion
VY ( i, j, k, l ) =
(l) d
dt
Ri
(l)
d
R j y k
dt
where:
Ri
Rj
(l) d
dt
VY 133
Adams/Solver (FORTRAN) 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 available.
134 Adams/Solver
VZ
The VZ function returns the z-component of the difference between the velocity vector of marker i and
the velocity vector of marker j as computed in the coordinate system of marker k. All vector time
derivatives are taken in the reference frame of marker l. Marker j defaults to the global coordinate system
if it is not specified. Similarly, markers i and j default to the global coordinate system if they are not
specified.
Format
VZ(i[,j][,k][,l])
Arguments
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.
The marker in whose coordinate system the velocity vector is expressed. Set k = 0, while still
specifying l, if you want the results to be calculated along the z-axis of the global coordinate
system.
The reference frame in which the first time derivative of the displacement vector is taken. Set l
= 0 or omit the argument if you want the time derivatives to be taken in the ground coordinate
system (GCS).
Extended Definition
VZ ( i, j, k, l ) =
(l) d
dt
Ri
(l)
d
R j z k
dt
where:
Ri
Rj
(l) d
dt
VZ 135
Adams/Solver (FORTRAN) 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 available.
136 Adams/Solver
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
The marker with respect to which the acceleration is being measured. Set j = 0, while still
specifying l, if you want j default to the global coordinate system.
The reference frame in which the first time derivative of the angular velocity vector is taken. Set
l = 0 if you want the time derivatives to be taken in the ground coordinate system (GCS).
Extended Definition
WDTM ( i, j, l ) =
(l) d
dt
(l) d
dt
(l) d
dt
where:
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)
(l) d
dt
WDTM 137
Adams/Solver (FORTRAN) Functions
In its first column REQUEST/16 contains the magnitude of the angular acceleration vector of Marker
1236 with respect to Marker 2169, as seen in the global coordinate system and measured in the ground
coordinate system (GCS).
See other Acceleration available.
138 Adams/Solver
WDTX
The WDTX function returns the x-component of the difference between the angular acceleration vector
of marker i in the reference frame of marker l and the angular acceleration vector of marker j in the
reference frame of marker l, as computed in the coordinate system of marker k. Marker j defaults to
global coordinate system if it is not specified. Similarly, marker k and l default to global coordinate
system if they are not specified.
Format
WDTX(i[,j][,k][,l])
Arguments
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.
The marker in whose coordinate system the acceleration vector is being expressed. Set k = 0,
while still specifying l, if you want the results to be calculated along the x-axis of the global
coordinate system.
The reference frame in which the first time derivative of the angular acceleration vector is
taken. Set l = 0 if you want the time derivatives to be taken in the ground coordinate system
(GCS).
Extended Definition
WDTX ( i, j, k, l ) =
(l) d
dt
(l)
d
j x k
dt
where:
Examples
MARKER/1236, QP=4,6,7 EU=90D,90D,90D, PART=23
MARKER/2169, PART=16
REQUEST/16
WDTX 139
Adams/Solver (FORTRAN) Functions
,F1=WDTM(1236,2169)/
,F2=WDTX(1236,2169,2169,2169)/
,F3=WDTY(1236,2169,2169,2169)/
,F4=WDTZ(1236,2169,2169,2169)
In its second column REQUEST/16 contains the x-component of the angular acceleration vector of
Marker 1236 with respect to Marker 2169, as seen in the global coordinate system of Marker 2169 and
measured in the reference frame containing Marker 2169.
See other Acceleration available.
140 Adams/Solver
WDTY
The WDTY function returns the y-component of the difference between the angular acceleration vector
of marker i in the reference frame of marker l and the angular acceleration vector of marker j in the
reference frame of marker l, as computed in the coordinate system of marker k. Marker j defaults to the
global coordinate system if it is not specified. Similarly, marker k and l default to the global coordinate
system if they are not specified.
Format
WDTY(i[,j][,k][,l])
Arguments
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.
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 y-axis of the global
coordinate system.
The reference frame in which the first time derivative of the angular acceleration vector is taken.
Set l = 0 if you want the time derivatives to be taken in the ground coordinate system (GCS).
Extended Definition
WDTY ( i, j, k, l ) =
(l) d
dt
(l)
d
j y k
dt
where:
Examples
MARKER/1236, QP=4,6,7 EU=90D,90D,90D, PART=23
MARKER/2169, PART=16
REQUEST/16
,F1=WDTM(1236,2169)/
WDTY 141
Adams/Solver (FORTRAN) Functions
,F2=WDTX(1236,2169,2169,2169)/
,F3=WDTY(1236,2169,2169,2169)/
,F4=WDTZ(1236,2169,2169,2169)
In its third column REQUEST/16 contains the y-component of the angular acceleration vector of Marker
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 available.
142 Adams/Solver
WDTZ
The WDTZ function returns the z-component of the difference between the angular acceleration vector
of marker i in the reference frame of marker l and the angular acceleration vector of marker j in the
reference frame of marker l, as computed in the coordinate system of marker k. Marker j defaults to the
global coordinate system if it is not specified. Similarly, marker k and l default to the global coordinate
if they are not specified.
Format
WDTZ(i[,j][,k][,l])
Arguments
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.
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 z-axis of the global
coordinate system.
The reference frame in which the first time derivative of the angular acceleration vector is taken.
Set l = 0 if you want the time derivatives to be taken in the ground coordinate system (GCS).
Extended Definition
WDTZ ( i, j, k, l ) =
(l) d
dt
(l)
d
j z k
dt
where:
Examples
MARKER/1236, QP=4,6,7 EU=90D,90D,90D, PART=23
MARKER/2169, PART=16
REQUEST/16
,F1=WDTM(1236,2169)/
WDTZ 143
Adams/Solver (FORTRAN) Functions
,F2=WDTX(1236,2169,2169,2169)/
,F3=WDTY(1236,2169,2169,2169)/
,F4=WDTZ(1236,2169,2169,2169)
In its fourth column REQUEST/16 contains the z-component of the angular acceleration vector of
Marker 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 available.
144 Adams/Solver
WM
The WM function returns the magnitude of the angular velocity vector of marker i with respect to marker
j. Marker j defaults to the global coordinate system if it is not specified.
Format
WM(i[,j])
Arguments
The marker with respect to which the velocity is being measured. Set j = 0, while
still specifying l, if you want j to default to the global coordinate system.
Extended Definition
WM ( i, j ) =
[ i j ] [ i j ]
where:
Examples
MARKER/1236, QP=4,6,7 EU=90D,90D,90D, PART=23
MARKER/2169, PART=16
REQUEST/16
,F1=WM(1236,2169)/
,F2=WX(1236,2169,2169)/
,F3=WY(1236,2169,2169)/
,F4=WZ(1236,2169,2169)
In its first column, REQUEST/16 contains the magnitude of the angular velocity vector of Marker 1236
and Marker 2169.
See other Velocity available.
WX 145
Adams/Solver (FORTRAN) Functions
WX
The WX function returns the x-component of the difference between the angular velocity vector of
marker i in ground and the angular velocity vector of marker j in ground, and expressed in the coordinate
system of marker k. Marker j defaults to the global coordinate system if it is not specified. Similarly,
marker k defaults to the global coordinate system if it is not specified.
Format
WX(i[,j][,k])
Arguments
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.
The marker in whose coordinate system the velocity vector is being expressed. Set k = 0 if you
want the results to be calculated along the x-axis of the global coordinate system.
Extended Definition
WX ( i, j, k ) = [ i j ] x k
where:
Examples
MARKER/1236, QP=4,6,7 EU=90D,90D,90D, PART=23
MARKER/2169, PART=16
REQUEST/16
,F1=WM(1236,2169)/
,F2=WX(1236,2169,2169)/
,F3=WY(1236,2169,2169)/
,F4=WZ(1236,2169,2169)
In its second column, REQUEST/16 contains the x-component of the angular velocity Markers 1236 and
2169 as measured in the coordinate system of Marker 2169. See other Velocity available.
146 Adams/Solver
WY
The WY function returns the y-component of the difference between the angular velocity vector of
marker i in ground and the angular velocity vector of marker j in ground, and expressed in the coordinate
system of marker k. Marker j defaults to the global coordinate system if it is not specified. Similarly,
marker k defaults to the global coordinate system if it is not specified.
Format
WY(i[,j][,k])
Arguments
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.
The marker in whose coordinate system the velocity vector is being expressed. Set k = 0 if you
want the results to be calculated along the y-axis of the global coordinate system.
Extended Definition
WY ( i, j, k ) = [ i j ] y k
where:
Examples
MARKER/1236, QP=4,6,7 EU=90D,90D,90D, PART=23
MARKER/2169, PART=16
REQUEST/16
,F1=WM(1236,2169)/
,F2=WX(1236,2169,2169)/
,F3=WY(1236,2169,2169)/
,F4=WZ(1236,2169,2169)
In its third column, REQUEST/16 contains the y-component of the angular velocity Markers 1236 and
2169 as measured in the coordinate system of Marker 2169. See other Velocity available.
WZ 147
Adams/Solver (FORTRAN) Functions
WZ
The WZ function returns the z-component of the difference between the angular velocity vector of
marker i in ground and the angular velocity vector of marker j in ground, and expressed in the coordinate
system of marker k. Marker j defaults to the global coordinate system if it is not specified. Similarly,
marker k defaults to the global coordinate system if it is not specified.
Format
WZ(i[,j][,k])
Arguments
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.
The marker in whose coordinate system the velocity vector is being expressed. Set k = 0 if you
want the results to be calculated along the z-axis of the global coordinate system.
Extended Definition
WZ ( i, j, k ) = [ i j ] z k
where:
Examples
MARKER/1236, QP=4,6,7 EU=90D,90D,90D, PART=23
MARKER/2169, PART=16
REQUEST/16
,F1=WM(1236,2169)/
,F2=WX(1236,2169,2169)/
,F3=WY(1236,2169,2169)/
,F4=WZ(1236,2169,2169)
In its fourth column, REQUEST/16 contains the z-component of the angular velocity Markers 1236 and
2169 as measured in the coordinate system of Marker 2169. See other Velocity available.
148 Adams/Solver
YAW
The YAW function calculates the first angle of a body-fixed 3 -2 1 yaw-pitch-roll rotation sequence
between markers i and j. Marker j defaults to the global coordinate system if it is not specified. Note that
yaw is an Euler angle.
Format
YAW(i[,j])
Arguments
The marker with respect to which the rotations are being measured.
Examples
REQUEST/1
,F2=YAW(21,11)/
,F3=PITCH(21,11)/
,F4=ROLL(21,11)
This REQUEST statement calculates the yaw, pitch, and roll angles between Markers 21 and 11 for
output purposes.
See other Displacement available.
1
Adams/Solver (FORTRAN) Commands
Command name:
MARKER
FLEX_BODY
Constraints
JOINT
MOTION
UCON
Forces
ACCGRAV
BEAM
BUSHING
FIELD
FRICTION
GFORCE
SFORCE
SPRINGDAMPER
VFORCE
VTORQUE
Reference data
ARRAY
SPLINE
STRING
VARIABLE
Analysis parameters
DEBUG
EQUILIBRIUM
IC
INTEGRATOR
KINEMATICS
LSOLVER
SENSOR
Output
OUTPUT
REQUEST
2 Adams/Solver
Type of command:
Command name:
Simulation
ACTIVATE
CONTROL
DEACTIVATE
EXECUTION
FILE
LINEAR
PREFERENCES
RELOAD
SAVE
SIMULATE
STOP
Information
HELP
INFO
MENU
SHOW
TIME
Display
ACENTER
AINIT
AUTOSCALE
BACKUP
CENTER
CLEAR
DISPLAY
DRAW
DT
ERASE/RESTORE
PLOT
RETURN
SET
ACCGRAV 3
Adams/Solver (FORTRAN) Commands
ACCGRAV
The ACCGRAV command redefines and/or lists the data for a ACCGRAV statement.
Format
Arguments
IGRAV=r
JGRAV=r
KGRAV=r
LIST
Examples
ACCGRAV/LIST
This ACCGRAV command lists all the data for the ACCGRAV statement in the dataset.
See other Forces available.
4 Adams/Solver
ACENTER
The ACENTER (automatic center) command lists the global x, y, and z values of the current display
center.
Format
ACENTER
See other Display available.
ACTIVATE 5
Adams/Solver (FORTRAN) Commands
ACTIVATE
The ACTIVATE command activates a statement that was previously turned off by the DEACTIVATE
command.
Format
Arguments
BEAM
BUSHING
FIELD
ID=id1[,...,id30]
JOINT
JPRIM
LIST
MOTION
6 Adams/Solver
RANGE=id1,id2
SENSOR
SFORCE
The ACTIVATE command, used in conjunction with the DEACTIVATE command, switches
Adams/Solver (FORTRAN) elements on and off. All Adams/Solver (FORTRAN) elements are active by
default in the input dataset, but can be deactivated using the DEACTIVATE command. For simulation
purposes, when Adams/Solver (FORTRAN) activates a statement, the statement appears as though it was
always in the dataset. When Adams/Solver (FORTRAN) deactivates a statement, the statement
effectively disappears from the model. Both the ACTIVATE and DEACTIVATE commands take effect
when you issue the next SIMULATE command.
After the activation of any element, Adams/Solver (FORTRAN) reprocesses the model at the next
SIMULATE command, as if it had just been read in from the dataset. During the reprocessing,
Adams/Solver (FORTRAN) checks the entire model for consistency, reinitializes user subroutines, and
recomputes initial conditions.
While checking the entire model, Adams/Solver (FORTRAN) verifies that the model is still valid when
the newly activated elements are included. For example, if an activated JOINT overconstrains a model
resulting in an immobile system, Adams/Solver (FORTRAN) issues an error message.
Adams/Solver (FORTRAN) also reinitializes all user subroutines to re-establish functional
dependencies. For each element that refers to a user-written subroutine, Adams/Solver (FORTRAN) calls
the user-written subroutine with IFLAG set to true.
Prior to the actual simulation, Adams/Solver (FORTRAN) computes initial conditions for the model. If
this is the first simulation, Adams/Solver (FORTRAN) begins with the positions and velocities specified
in the dataset, and maintains any user-supplied joint initial-conditions and part positions specified as
EXACT. If you ran a previous simulation, Adams/Solver (FORTRAN) begins with the final
displacements and velocities. Adams/Solver (FORTRAN) then adjusts the initial conditions to ensure
that they are consistent with the model constraints.
If a constraint or force is activated in the middle of a simulation, by default Adams/Solver (FORTRAN)
splits the tabular, request, graphics, and results output into two separate sets of output concatenated
together. This ensures that the output correctly reflects the new system topology.
ACTIVATE 7
Adams/Solver (FORTRAN) Commands
The OUTPUT/NOSEPARATOR argument prevents Adams/Solver (FORTRAN) from splitting the file.
This allows you to plot or animate the output continuously from beginning to end, but may result in
misleading graphics during postprocessing. See OUTPUT for more information on the NOSEPARATOR
argument.
Tip:
Use the ACTIVATE and DEACTIVATE commands after a FILE or RELOAD command to
set up the model for a particular loadcase or configuration.
Examples
ACTIVATE/SFORCE,ID=201,202
This ACTIVATE command activates JPRIMs 400 and 499, and all JPRIMs with identifiers between 400
and 499.
See other Simulation available.
8 Adams/Solver
AINIT
The AINIT (angle initialization) command resets the display to its original orientation about the global
x, y, and z axes. When a subsequent DISPLAY command is used to redisplay the data, it has its original
orientation.
Format
AINIT
See other Display available.
ARRAY 9
Adams/Solver (FORTRAN) Commands
ARRAY
The ARRAY command redefines and/or lists the array of up to 1,200 real numbers for an IC-type ARRAY
statement.
Format
LIST
NUMBERS=r1[,r2,...]
Caution:
You can use the ARRAY command on only an IC-type ARRAY statement (the default
type). Adams/Solver (FORTRAN) issues an error message if you specify an X-, U-, or Ytype ARRAY statement.
Example
ARRAY/12, NUMBERS=0.5,0.12, LIST
10 Adams/Solver
AUTOSCALE
The AUTOSCALE command rescales and recenters the data for the current graphics display.
Adams/Solver (FORTRAN) uses the extreme dimensions of the marker coordinates in the dataset to
calculate the display scale and center. When the DISPLAY command is used to redisplay the data, it fills
the screen, and the center of the data is at the center of the screen.
Format
AUTOSCALE
See other Display available.
BACKUP 11
Adams/Solver (FORTRAN) Commands
BACKUP
The BACKUP and ZOOM commands change the scale of the current display. BACKUP shrinks the
display to an area that fits into the defined rectangular parallelepiped, while retaining the same aspect
ratio as the screen. ZOOM enlarges the display to an area that fits into the defined rectangular
parallelepiped, while retaining the same aspect ratio as the screen. This command may work slightly
differently on different types of terminals.
Format
BACKUP
or
ZOOM
Instructions
Method A: Backing Up from or Zooming in on a Multiple-View Display.
To back up or zoom:
1. Enter either BACKUP or ZOOM.
Adams/Solver (FORTRAN) displays one plane of the display.
2. Use the perpendicular cross hairs to locate one vertex.
Locate the vertex of a rectanglar area that you want to fit the current display window.
3. Click the mouse button or select any alphanumeric key.
Adams/Solver (FORTRAN) displays a cross at the vertex where the cross hairs intersect.
12 Adams/Solver
To back up or zoom:
1. Enter either BACKUP or ZOOM.
Adams/Solver (FORTRAN) displays the view specified by the SET command.
2. Use the perpendicular cross hairs to locate one vertex.
Locate the vertex on the rectangle in which you want to fit the current display or (in this plane) to
be enlarged to backup or zoom, respectively.
3. Select any alphanumeric key or click the mouse button.
Adams/Solver (FORTRAN) displays a cross at the vertex where the cross hairs intersect.
4. Use the cross hairs to locate a second vertex.
Adams/Solver (FORTRAN) uses the two vertices to define the length and width of a rectangle,
so the second vertex must be diagonal to the first. The two plus signs here represent two diagonal
vertices, and the lines show the rectangle they define.
BACKUP 13
Adams/Solver (FORTRAN) Commands
Tektronix terminals do not require you to press the RETURN key in addition to an
alphanumeric key to display a cross at a point located with the cross hairs. Do not
press the RETURN key to display a cross on a Tektronix terminal, this causes
program failure. However, some graphics terminals (either Tektronix emulators or
terminals other than Tektronix) may require you to press both an alphanumeric key
and the RETURN key to display a cross and/or another plane.
The BACKUP or ZOOM command should be preceded with a DISPLAY
command.
These two commands require that you fix cross hairs and therefore BACKUP or
ZOOM cannot be included in a Command file. If they are, the results are
unpredictable and may result in a program abort.
When you use BACKUP or ZOOM and then use the SET command to change the
view, the new view has the same backup or zoom characteristic as the previous
view.
See other Display available.
14 Adams/Solver
BEAM
The BEAM command redefines and/or lists the data for a BEAM statement. Although you cannot redefine
the I and the J markers, you can redefine any of the other BEAM arguments.
Format
Arguments
AREA=r
Respecifies the uniform area of the beam cross-section. The centroidal axis
must be orthogonal to this cross-section.
ASY=r
Respecifies the correction factor for shear deflection in the y direction for
Timoshenko beams.
ASZ=r
Respecifies the correction factor for shear deflection in the z direction for
Timoshenko beams.
CMATRIX=r1,...,r21 Respecifies the six-by-six damping matrix for the beam. Because this matrix is
symmetric, you need to specify only one-half of it, that is, twenty-one entries.
The units for the translational and rotational components of CMATRIX should
be force-time per displacement unit and torque-time per radian, respectively.
CRATIO=r
Respecifies the ratio for calculating the structural damping matrix for the beam.
Adams/Solver (FORTRAN) multiplies the stiffness matrix by the value of
CRATIO to obtain the damping matrix.
EMODULUS=r
GMODULUS=r
BEAM 15
Adams/Solver (FORTRAN) Commands
IXX=r
IYY=r,IZZ=r
Denotes the area moments of inertia about the neutral axes of the beam cross
sectional area (y-y and z-z). These are sometimes referred to as the second
moment of area about a given axis. They are expressed as unit length to the
fourth power. For a solid circular section, Iyy=Izz=
. For a thin-walled
sections, open sections, and noncircular sections, the user should consult a
handbook.
LENGTH
Respecifies the undeformed length of the beam along the x-axis of the J marker.
LIST
16 Adams/Solver
BUSHING
The BUSHING command redefines and/or lists the data for a BUSHING statement. Although you cannot
define the I and J markers defining the bushing, you can redefine other characteristics of the bushing.
Format
Arguments
C=r1,r2,r3
Respecifies three viscous damping coefficients for the force transferred by the
bushing.
CT=r1,r2,r3
Respecifies three viscous damping coefficients for the torque transferred by the
bushing.
FORCE=r1,r2,r3
K=r1,r2,r3
Respecifies three stiffness coefficients for the force transferred by the bushing.
KT=r1,r2,r3
Respecifies three stiffness coefficients for the torque transferred by the bushing.
LIST
Caution:
For the rotational constitutive equations to be accurate, at least two of the rotations (a, b,
and c) must be small. That is, two of the three values must remain smaller than 10 degrees.
In addition, if a becomes greater than 90 degrees, b becomes erratic. If b becomes greater
than 90 degrees, a becomes erratic. Only c can become greater than 90 degrees without
causing problems. For these reasons, it is best to define your BUSHING such that angles a
and b (not a and c and not b and c) remain small.
CENTER 17
Adams/Solver (FORTRAN) Commands
CENTER
The CENTER command brings up cross hairs that allow you to define a new center for the display. This
command may work slightly differently on different makes of terminals
Format
CENTER
Instructions
Method A: Defining the Center of a Multiple-View Display
18 Adams/Solver
an alphanumeric key to display a cross at a point located with the cross hairs. Do
not press the RETURN key to display the cross on a Tektronix terminal; doing so
causes program failure. However, some graphics terminals (either Tektronix
emulators or terminals other than Tektronix) may require both an alphanumeric
key and the RETURN key to be pressed to display a cross and/or another plane.
Do not unnecessarily press the RETURN key.
The CENTER command should be preceded with a DISPLAY command.
You cannot include CENTER in a command file because this command requires
that you fix cross hairs. If you do, the results are unpredictable and may include a
program abort.
See other Display available.
CLEAR 19
Adams/Solver (FORTRAN) Commands
CLEAR
The CLEAR command clears the graphics screen. Use this command only if analysis is being done on a
graphics terminal.
Format
CLEAR
See other Display available.
20 Adams/Solver
CONTROL
The CONTROL command branches program control to the driver subroutine CONSUB. Adams/Solver
(FORTRAN) passes parameter arguments to the command as an array. Upon completion of CONSUB,
Adams/Solver (FORTRAN) prompts you for another command.
Format
CONTROL/[FUNCTION=USER(r1[,...,r30])[\]][ROUTINE=libname::subname]
[[ ]] Optionally select an item combination
FUNCTION=USER(r1[,...,r30])
ROUTINE=libname::subname
Tip:
Caution:
Adams/Solver (FORTRAN) issues an error message and ignores the entire command if a
CONTROL command is issued when no CONSUB driver subroutine is linked with
Adams/Solver (FORTRAN).
DEACTIVATE 21
Adams/Solver (FORTRAN) Commands
DEACTIVATE
The DEACTIVATE command turns off a statement that was previously turned on by the ACTIVATE
command, or that was active by default.
Format
Arguments
BEAM
BUSHING
FIELD
ID=id1[,...,id30]
JOINT
JPRIM
LIST
MOTION
RANGE=id1, id2
22 Adams/Solver
SENSOR
SFORCE
The DEACTIVATE command, used in conjunction with the ACTIVATE command, switches
Adams/Solver (FORTRAN) elements off and on. All Adams/Solver (FORTRAN) elements are active by
default in the input dataset, but some may be deactivated using the DEACTIVATE command. For
simulation purposes, when Adams/Solver (FORTRAN) deactivates a statement, the statement effectively
disappears from the model. When a statement is activated, the statement appears as though it were always
in the dataset. Both the DEACTIVATE and ACTIVATE commands take effect when you issue the next
SIMULATE command. Once deactivated, a statement remains inactive until it is activated using an
ACTIVATE command.
After the deactivation of any element, Adams/Solver (FORTRAN) reprocesses the model at the next
SIMULATE command as if it had just been read in from the dataset. During the reprocessing,
Adams/Solver (FORTRAN) checks the entire model for consistency, reinitializes user subroutines, and
recomputes initial conditions.
While checking, Adams/Solver (FORTRAN) examines all active-element function expressions and
arguments for references to inactive elements. Adams/Solver (FORTRAN) issues an error message if an
active force, constraint, or sensor refers to an inactive element just as if the inactive element did not exist.
Adams/Solver (FORTRAN) reports zero forces for the inactive element if a force request or force graphic
refers to an inactive element.
Adams/Solver (FORTRAN) also reinitializes all user subroutines to re-establish functional
dependencies. For each element that refers to a user-written subroutine, Adams/Solver (FORTRAN) calls
the user-written subroutine with IFLAG set to true.
Prior to the actual simulation, Adams/Solver (FORTRAN) computes initial conditions for the model. If
this is the first simulation, Adams/Solver (FORTRAN) begins with the positions and velocities specified
in the dataset. If you ran a previous simulation, Adams/Solver (FORTRAN) begins with the final
displacements and velocities. Adams/Solver (FORTRAN) then adjusts the initial conditions to ensure
that they are consistent with the model constraints. If this is the first simulation, Adams/Solver
(FORTRAN) also maintains any user-supplied joint initial-conditions and part positions specified as
EXACT.
Adams/Solver (FORTRAN) reports zero values in all output files for any forces associated with inactive
elements, including both applied forces and joint reaction forces. This includes force requests, force
graphics, and forces in the Results File.
Adams/Solver (FORTRAN) continues to report displacements, velocities, and accelerations for all
JOINT and JPRIM MREQUESTs, even for JOINTs and JPRIMs that have been deactivated.
MREQUEST creates displacement, velocity, and acceleration requests for the markers associated with
DEACTIVATE 23
Adams/Solver (FORTRAN) Commands
the specified JOINTs and JPRIMs. Adams/Solver (FORTRAN) continues to output the relative marker
displacements, velocities, and accelerations, even if you deactivated the original JOINT or JPRIM.
If you deactivate a constraint or force in the middle of a simulation, by default Adams/Solver
(FORTRAN) will split the tabular, request, graphics, and results output into two separate sets of output
concatenated together. This ensures that the output correctly reflects the new system topology.
The OUTPUT/NOSEPARATOR argument prevents Adams/Solver (FORTRAN) from splitting the file.
This allows you to plot or animate the output continuously from beginning to end, but may result in
misleading graphics during postprocessing. See OUTPUT for more information on the NOSEPARATOR
argument.
Tip:
Typically, you use DEACTIVATE and ACTIVATE to set up the model for a particular
loadcase or configuration after a FILE or RELOAD command.
Caution:
Examples
DEACTIVATE/JOINT,ID=71,72,73
This DEACTIVATE command deactivates all SENSORs with identifiers between 5 and 10, including 5
and 10.
See other Simulation available.
24 Adams/Solver
DEBUG
The DEBUG command redefines and/or lists the data for a DEBUG statement. See the DEBUG
statement for more information.
Format
DEBUG 25
Adams/Solver (FORTRAN) Commands
Arguments
DUMP
Writes the internal representation of a dataset in the Tabular Output File after Adams/Solver reads
and checks the input. This facility essentially maps the equations and variables in the system and
provides their numeric codes.
Default: Off
EPRINT
Prints a block of information for each kinematic, static, or dynamic step. This information helps
you monitor the simulation process and to locate the source of the error if there is a problem. Each
step consists of two phases: 1) a forward step in time (the predictor for dynamics) and 2) the
solution of the equations of motion (the corrector for dynamics). For the first phase, Adams/Solver
prints out the following information:
The step number. This is a running count of the number of steps taken and can be used as a
Adams/Solver 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 prints out the cumulative number of iterations and a table of
information about the iterations. The cumulative number of iterations is a running count of the
iterations needed to solve the equations of motion and can be used as a measure of how many
computations Adams/Solver is performing. The table contains information about the maximum
equation error and maximum variable change for each iteration. For each iteration, Adams/Solver
prints out the following information:
The iteration number. This is one at the beginning of each step and increments by one until
close to zero. This number is an indicator of how far Adams/Solver is from a solution. This
number should decrease after every iteration.
The 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 far Adams/Solver 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 has updated the Jacobian, YES appears under the new Jacobian header.
Default: NOEPRINT
26 Adams/Solver
JMDUMP
LIST
NOEPRINT
Suppresses the printing of three numbers at each integration step and five numbers at each corrector
iteration during an integration.
Default: NOEPRINT
NOJMDUMP
NOREQDUMP Disables the dumping of REQUEST and MREQUEST statement output at each iteration.
Default: NOREQDUMP
NORHSDUMP Disables the dumping of the YY array (state vector), the RHS array (error terms), and the DELTA
array (increment to state vector) at each iteration.
Default: NORHSDUMP
NOVERBOSE
Deactivates the output of explanations and possible remedies and the output of the names of
subroutines from which Adams/Solver sends diagnostics.
Default: NOVERBOSE
REQDUMP
Enables the dumping of the REQUEST and the MREQUEST statement output at each iteration.
Default: NOREQDUMP
RHSDUMP
Enables the dumping of the YY array (state vector), RHS array (error terms), and DELTA array
(increment to state vector) at each iteration.
Default: NORHSDUMP
VERBOSE
Outputs to the screen such additional information as the name of the subroutine from which
Adams/Solver sends each diagnostic, explanations, and possible remedies (when available). If you
do not include the VERBOSE argument, Adams/Solver outputs to the screen only basic error
messages. Whether or not you include the VERBOSE argument, Adams/Solver outputs
VERBOSE information to the Message File.
Default: NOVERBOSE
Extended Definition
Of all the arguments in the DEBUG command, EPRINT is perhaps the most useful. This section explains
the EPRINT argument in detail.
DEBUG 27
Adams/Solver (FORTRAN) Commands
The kinematic, dynamic, and quasi-static analyses in Adams/Solver involve the solution of the governing
equations of motion. Static analysis is the solution of the equilibrium and the initial conditions analysis
solves the assembly equations at a particular point in time.
The equations to be solved, for all these analyses, are non-linear algebraic or differential-algebraic
equations. The solution of these equations is an iterative process. The EPRINT argument enables
Adams/Solver to write out the information pertaining to the solution process in a succinct and
understandable format. All analyses that march through time consist of two distinct phases: predictor
phase and corrector phase.
Predictor Phase
In order to proceed efficiently from one time to the next, Adams/Solver uses a predictor. The predictor is
simply a means of estimating the values of the system state by looking at the past values of the state and
extrapolating the data based on a simple curve fitting algorithm.
Consider a series of values yi defined at discrete times ti
where i=1...n. A simple first order predictor that may be used to predict the value yn+1 at tn+1 is:
Figure 1
You can easily surmise from Figure 1, a first order predictor simply consists of connecting the points yn1 and yn with a straight line and extending it to time tn+1.
28 Adams/Solver
A second order predictor, similarly, can be thought of as constructing a parabola between the points (tn2, yn-2), (tn-1, yn-1) and (tn, yn) and extending the parabola to time tn+1. The predicted value of y at tn+1
is the intersection of the vertical line t=tn+1 with this parabola. Predictors are typically polynomials
(linear, quadratic, cubic, etc.) and the order of the polynomial is frequently called the order of the solution
method.
For kinematic analyses, Adams/Solver employs a first or second order predictor. For quasi-statics, a first
order predictor is used. For dynamic analyses much higher order predictors are used. The BDF methods
(GSTIFF and WSTIFF) use up to six order predictors. ABAM on the other hand can use up to a 12th
order predictor. Sophisticated numerical analysis is employed to determine the most appropriate order of
prediction to use at any given step.
Furthermore, sophisticated curve fitting methods like Newton-Divided Difference tables are usually
employed to efficiently predict the system state. Figure 2 shows the format of the output produced by the
EPRINT argument and explains the data pertinent to the predictor phase of a dynamic analysis step.
The predictor polynomials used for the dynamic analyses interpolate previous values and the slope of the
variable at the current time to estimate the solution at the next time. Therefore, in Figure 5, a second order
polynomial that fits the solution at times t4 and t5 and the slope of the solution at time t5 is used to predict
the value of the solution at time t6.
Figure 2
DEBUG 29
Adams/Solver (FORTRAN) Commands
Corrector Phase
Since all predictors simply look at past values to estimate the solution at the next time, the predicted
values almost never satisfy the governing equations. They simply constitute a good initial guess for the
solution. The refining of the predicted solution to one that satisfies the governing equations is called the
correction. Since the governing equations are usually non-linear, an iterative scheme like NewtonRaphson iterations are used.
This methodology is explained for the simplest case of one non-linear algebraic equation in one variable.
Let f(x) be a smooth function of a single variable x. Given an initial guess x=x0, a solution x=xc that
satisfies f(x)=0 is desired for this simple example. The Newton-Raphson iterations may be expressed as:
for i=0 ... max_no_iterations.
1. Evaluate ri = f(xi)
2. If | ri | <
3. Evaluate
4. Calculate
5. Set
6. Set i = i+1 and go to Step 1.
The quantity ri is frequently called the residual and is a measure of the accuracy of the solution. The
quantity Ji is the partial derivative of f with respect to x, evaluated at x=xi and is commonly known as
30 Adams/Solver
the Jacobian. The graph on the left side of Figure 3 illustrates the Newton-Raphson iterations for the onedimensional example discussed above.
Figure 3
J0 is the slope of the curve f(x) at x=x0. Through simple trigonometry it can be seen that x0-x1 = r0/J0
(i.e., x1 = x0 - r0/J0).
DEBUG 31
Adams/Solver (FORTRAN) Commands
Similarly,
The corrector in Adams/Solver involves the solution of many variables simultaneously. The algorithm
for one dimension is easily extended to n dimensions as follows:
Let x = {x1, x2,... xn} be a set of n variables and f = {f1(x), f2(x),... fn(x)} be a set of n non-linear equations
in the variables x.
Define:
J=
where i=1,...,n and j=1,...,n. Then the Newton-Raphson iterations for the n-dimensional case becomes:
given an initial guess x = x0 = {x01, x02,... x0n} for i=0,...,max_no_interations.
number that specifies the convergence criterion.
is a small user-defined
1. Evaluate ri = f(xi)
2. If || ri || <
3. Calculate
4. Evaluate
5. Set
32 Adams/Solver
Newton-Raphson iterations in a dynamic analysis. The numbers on the left are the values of the
maximum residuals at each iteration. The maximum corrections are on the right. In practice, the
convergence rate of the iterations is used to determine whether a Jacobian evaluation is to be performed
or not.
Figure 4
Figure 5
The DEBUG/EPRINT option generates a table of data on the action of Adams/Solver for each of the
iterative algorithms in the various analyses. The iterative algorithm, or corrector, is used to evaluate the
variables governed by the system of non-linear equations. Table 1 contains the DEBUG/EPRINT
information for the variables associated with the mass-bearing elements (parts, point masses, and flexible
bodies) and for the corresponding equations. A combination of several equations is needed to define each
DEBUG 33
Adams/Solver (FORTRAN) Commands
joint and joint primitive. Table 2 includes the variables for the various joint constraints and the
corresponding equations.
Adams/Solver uses a combination of equations to represent the different types of forces. While certain
equations are specific to a particular force, others are generic to all types. The combination of variables
and corresponding equations for the forces are included in Table 3. The DEBUG/EPRINT information
for the variables and corresponding equations that define the Adams system elements is contained in
Table 4. Finally, Table 5 includes the information on the variables and equations for the remaining
miscellaneous elements in an Adams system.
Table 1
Element
type:
Parts
Code:
mx
m y
Explanation:
Translational force,
x-direction, GCS
Translational force,
y-direction, GCS
VARIABLES
Code:
Explanation:
x
Translational coordinate,
x-direction, GCS
y
Translational coordinate,
y-direction, GCS
mz
Translational force,
z-direction, GCS
vx
Velocity equation,
x-coordinate, GCS
Translational coordinate,
x-direction, GCS
vy
Velocity equation,
y-coordinate, GCS
Translational coordinate,
y-direction, GCS
vz
Velocity equation,
z-coordinate, GCS
Translational coordinate,
z-direction, GCS
Translational coordinate,
z-direction, GCS
Rotational rate, first component, 31-3 Euler angles, GCS
Rotational rate, second component,
3-1-3 Euler angles, GCS
34 Adams/Solver
EQUATIONS
Element
type:
Code:
Code:
Explanation:
mx
Translational force,
x-direction, GCS
Translational coordinate,
x-direction, GCS
m y
Translational force,
y-direction, GCS
Translational coordinate,
y-direction, GCS
mz
Translational force,
z-direction, GCS
Translational coordinate,
z-direction, GCS
Flexible
Bodies
Explanation:
VARIABLES
M qj
q j
Time-derivative of the
coordinate
Time-derivative of the
coordinate
Time-derivative of the
coordinate
Time-derivatives of modal
coordinates for 1 j number of
flexible modes
vx
Velocity equation,
x-coordinate, GCS
Translational coordinate,
x-direction, GCS
vy
Velocity equation,
y-coordinate, GCS
Translational coordinate,
y-direction, GCS
vz
Velocity equation,
z-coordinate, GCS
Translational coordinate,
z-direction, GCS
DEBUG 35
Adams/Solver (FORTRAN) Commands
EQUATIONS
Element
type:
Point
Masses
Code:
Explanation:
VARIABLES
Code:
q j
qj
mx
Translational force,
x-direction, GCS
Translational velocity,
x-direction, GCS
m y
Translational force,
y-direction, GCS
Translational velocity,
y-direction, GCS
mz
Translational force,
z-direction, GCS
Translational velocity,
z-direction, GCS
Table 2
Element
type:
Code:
Explanation:
VARIABLES
Code:
Explanation:
Notes:
y Force
At Point Constraint
(z)
zi zj = 0
z Force
xi yj
xy Torque
zi xj
zx Torque
zi y j
zy Torque
zi x j
zx Torque
zi y j
zy Torque
Joint Initial
Condition,
At Point Constraint
(x)
xi xj = 0
Translational
At Point Constraint
(y)
yi yj = 0
z
Joint Initial
Condition,
Rotational
Cylindrical
Joint
Explanation:
36 Adams/Solver
EQUATIONS
Element
type:
Convel Joint
Fixed Joint
Hooke Joint
Planar Joint
Code:
VARIABLES
Explanation:
Code:
Explanation:
Notes:
s xj
sx Force
s yj
Sliding Constraint(s,
yj)
s yj = 0
sy Force
At Point Constraint
(x)
xi xj = 0
x Force
At Point Constraint
(y)
yi yj = 0
y Force
At Point Constraint
(z)
zi z j = 0
z Force
xi yj
xy Torque
At Point Constraint
(x)
xi xj = 0
x Force
At Point
Constraint(y)
=0
y Force
yi yj
At Point Constraint
(z)
zi z j = 0
z Force
xi yj
xy Torque
zi xj
zx Torque
zi yj
zy Torque
At Point
Constraint(x)
=0
x Force
xi xj
At Point Constraint
(y)
yi yj = 0
y Force
At Point Constraint
(z)
zi z j = 0
z Force
xi yj
xy Torque
zi xj
zx Torque
DEBUG 37
Adams/Solver (FORTRAN) Commands
EQUATIONS
Element
type:
Code:
Explanation:
VARIABLES
Code:
Explanation:
Notes:
zi y j
zy Torque
s zj
sz Force
Rack-&Pinion Joint
Rotation/Translation
Dependency
ap Force
Reaction Force ( )
Revolute
Joint
At Point Constraint
(x)
xi xj = 0
x Force
At Point Constraint
(y)
yi yj = 0
y Force
At Point Constraint
(z)
zi zj = 0
z Force
zi x j
zx Torque
zi y j
zy Torque
Screw Joint
Rotation/Translation
Dependency
ap Force
Reaction Force ( )
Spherical
Joint
At Point Constraint
(x)
xi xj = 0
x Force
At Point Constraint
(y)
yi yj = 0
y Force
At Point Constraint
(z)
zi zj = 0
z Force
zi x j
zx Torque
zi y j
zy Torque
xi yj
xy Torque
s xj
sx Force
s yj
sy Force
At Point Constraint
(x)
xi xj = 0
x Force
Translational
Joint
Universal
Joint
38 Adams/Solver
EQUATIONS
Element
type:
Code:
Explanation:
VARIABLES
Code:
Explanation:
Notes:
At Point Constraint
(y)
yi yj = 0
y Force
At Point Constraint
(z)
zi z j = 0
z Force
zi zj
zz Torque
At Point Constraint
(x)
xi xj = 0
x Force
At Point Constraint
(y)
yi yj = 0
y Force
At Point Constraint
(z)
zi z j = 0
z Force
xij
Equivalent to Sliding
Constraint (s, xj) s xj =
0
x Force
yij
Equivalent to Sliding
y Force
Constraint (s, yj) s yj = 0
Inplane Joint
Primitive
zij
Equivalent to Sliding
Constraint (s, zj)
z Force
Orientation
Joint
Primitive
zi xj
zx Torque
zi yj
zy Torque
xi yj
xy Torque
zi xj
zx Torque
zi yj
zy Torque
Perpendicular zi zj
Joint
Primitive
zz Torque
Atpoint Joint
Primitive
Inline Joint
Primitive
Parallel Joint
Primitive
Notes
DEBUG 39
Adams/Solver (FORTRAN) Commands
1. An At Point Constraint ensures that the origins of the two markers connected by this constraint
remain spatially collocated during the simulation. This constraint is made up of 3 equations for
the displacement between the two markers in the global X, Y and Z directions, respectively. For
each of the equations, a corresponding variable is introduced to represent the constraint reaction
in the X, Y and Z directions, respectively. In Table 3 a at point constraint equation in the n1
direction is denoted by At_point_constraint(n1) and the corresponding reaction force by
Reaction_force(n1).
The three At Point Constraint equations are: xi - xj = 0, yi - yj = 0, and zi - zj = 0.
2. An Angular Constraint ensures that two vectors fixed in separate mass bearing elements (PARTs,
POINT_MASSes, or FLEX_BODY) (MBE) remain mutually perpendicular during the
simulation. This constraint is represented by 1 equation. This equation requires the dot product of
the two vectors to be zero. Corresponding to this equation, a variable is introduced to represent
the constraint reaction torque. In Table 3, this constraint is denoted as Angular Constraint(v1,v2)
and its reaction torque as Reaction Torque(v1,v2).
An Angular Constraint is given as
3. A Sliding constraint is a constraint between a spanning vector and a direction fixed in a MBE. A
spanning vector is defined as the spatial vector from the origin of marker i to the origin of marker
j. A sliding constraint ensures that a spanning vector remains perpendicular to the vector fixed in
a MBE. This constraint is enforced by 1 equation that sets the dot product between the spanning
vector and the fixed vector to zero. Introduction of this equation in a model causes a variable in
the form of a constraint reaction force to be included in the model. In Table 3, the equation for
this constraint is denoted as Sliding_constraint(s,v1) and the reaction force by
Reaction_force(s,v1).
A Sliding constraint is given as
Element
type:
Code:
Explanation:
VARIABLES
Code:
Explanation:
Notes:
FIELD,
BEAM,
Dx
x-displacement equation Dx
Element x-displacement
BUSHIN
G
Dy
y-displacement equation Dy
Element y-displacement
Dz
z-displacement equation Dz
Element z-displacement
40 Adams/Solver
EQUATIONS
Element
type:
GFORCE
NFORCE
Code:
Explanation:
VARIABLES
Code:
Explanation:
Notes:
Theta x
Theta x
Rotational displacement
about x-axis
Theta y
Theta y
Rotational displacement
about y-axis
Theta z
Theta z
Rotational displacement
about z-axis
Fx
x-direction force
equation
Fx
Fy
y-direction force
equation
Fy
Fz
z-direction force
equation
Fz
Tx
Tx
Ty
Ty
Tz
Tz
Fx
x-force equation
Fx
Fy
y-force equation
Fy
Fz
z-force equation
Fz
Tx
x-torque equation
Tx
Ty
y-torque equation
Ty
Tz
z-torque equation
Tz
Fx
x-force equation
Fx
Force in x direction
Fy
y-force equation
Fy
Force in y direction
Fz
z-force equation
Fz
Force in z direction
Tx
x-torque equation
Tx
Ty
y-torque equation
Ty
Tz
z-torque equation
Tz
DEBUG 41
Adams/Solver (FORTRAN) Commands
EQUATIONS
Element
type:
Code:
Translatio Length
nal
SFORCE
Explanation:
VARIABLES
Code:
Explanation:
Notes:
Length
Force
Force
Force in element
Fx
x-force equation
Fx
Force in x direction
Fy
y-force equation
Fy
Force in y direction
Fz
z-force equation
Fz
Force in z direction
Rotational Torque
SFORCE
Torque in element
Translatio Length
nal
Springda
mper
Length
L Vel
L Vel
Element velocity
Fx
x-force equation
Fx
Force in x direction
Fy
y-force equation
Fy
Force in y direction
Fz
z-force equation
Fz
Force in z direction
5
6
Rotational Torque
Springda
mper
Torque in element
VFORCE
Fx
x-force equation
Fx
Fy
y-force equation
Fy
Fz
z-force equation
Fz
VTORQU Tx
E
x-torque equation
Tx
Ty
y-torque equation
Ty
Tz
z-torque equation
Tz
Notes
5. Force equations and variables: forces are defined via explicit force equations. These equations
take the general form of:
Force_variable - Force_expression = 0
42 Adams/Solver
where:
Force_variable denotes the force in the x, y or z direction, respectively.
Force_expression is an expression defining the force in terms of state variables and user
defined coefficients.
6. Torque equations are defined in a manner similar to force equations. These equations take the
form of:
Torque_variable - Torque_expression = 0
where:
Torque_variable denotes the torque in the element in the x, y, or z direction, respectively.
Torque_expression defines the torque in term of state variables and user defined coefficients.
7. In addition to force and torque equations, element-specific equations and variables can be used to
define force elements. Typically these equations are to define intermediate kinematic quantities
used in force and torque computation.
Table 4
Element
type:
DIFF
GSE
LSE
TFSISO
VARIABLES
Code:
Explanation:
Differential
Equation
States x
User
Variable
State xj
Outputs yj
Outputs yj
States x j
State xj
Outputs yj
State x j
Code:
Explanation:
DEBUG 43
Adams/Solver (FORTRAN) Commands
EQUATIONS
Element
type:
Code:
VARIABLE
Table 5
VARIABLES
Explanation:
Code:
Explanation:
Output y
Algebraic
Equation
Algebraic
Variable
VARIABLES
Elemen
t type:
Code:
COUPL
ER
f(1,2,3
)=0
Reaction force
CVCV
x Force
y Force
z Force
Ti Nj
TN
Torque
Constraint torque
variable
F-
Constraint force on
curve 1
F-
Constraint force on
curve 2
Parameter for
curve 1
Parameter for
curve 2
Explanation:
Code:
Explanation:
First derivative of
the first parameter
Second derivative
of the first
parameter
First derivative of
the second
parameter
Notes:
44 Adams/Solver
EQUATIONS
Elemen
t type:
Code:
VARIABLES
Explanation:
Code:
Explanation:
Notes:
Second derivative
of the second
parameter
GEAR
Reaction force
MOTIO
N
-f(t)=0
Reaction force
PTCV
x Force
y Force
z Force
Perpendicular constraint
F-
Constraint force
Curve parameter
UCON
f(Q)=0
Derivative of the
curve parameter
Second derivative
Associated
reaction force
DISPLAY 45
Adams/Solver (FORTRAN) Commands
DISPLAY
The DISPLAY command generates a graphics display for the current simulation time.
Format
DISPLAY
See other Display available.
46 Adams/Solver
DRAW
The DRAW command displays joints and their identifiers or parts and (optionally) markers and their
identifiers.
Format
Arguments
JOINT=ALL
JOINT=id1[,...,id50]
JSTART=id,JEND=id
Display all the joints from the identifier JSTART to the identifier JEND.
When these arguments are used, Adams/Solver (FORTRAN) expects the
dataset to include all consecutive joint identifiers between JSTART and
JEND.
MARKER=ALL
DRAW 47
Adams/Solver (FORTRAN) Commands
PART=id1[,...,id50]
PSTART=id,PEND=id
Display all the parts from the identifier PSTART to the identifier PEND.
When these arguments are used, Adams/Solver (FORTRAN) expects the
dataset to include all consecutive part identifiers between PSTART and
PEND.
Instructions
1. Type DRAW.
To see many parts at once, issue the SET SUPER command before the DRAW command.
If the dataset does not include all joint, marker, or part identifiers specified in the
This command displays Part 1 and Markers 11, 12, and 14, that are on Part 1.
48 Adams/Solver
This command displays Part 5 and Markers 23 through 28 that are on Part 5.
DRAW JOINT=ALL
DT 49
Adams/Solver (FORTRAN) Commands
DT
The DT (delta time) command displays and modifies the simulation time between successive display
frames. This command is issued only while in the graphics mode with pause set (see the EXECUTION
and SET commands). The program prompts you for a time value.
Format
DT
Instructions
1. Type DT.
Examples
DT
START TIME=0.0, OUTPUT TIME INTERVAL=0.1, END TIME=1.0
ENTER NEW OUTPUT TIME INTERVAL:
0.5
If you type and enter DT as in this example, Adams/Solver (FORTRAN) displays the simulation begin
time (START TIME), the delta time (OUTPUT TIME INTERVAL), the simulation end time (END
TIME), and the message ENTER NEW OUTPUT TIME INCREMENT. In this case, you enter 0.5 to
request that Adams/Solver (FORTRAN) display one frame for every 0.5 units of simulation time.
See other Display available.
50 Adams/Solver
EQUILIBRIUM
An EQUILIBRIUM command redefines and/or lists the data for an EQUILIBRIUM statement. If an
EQUILIBRIUM statement is not included in the Adams/Solver model and an EQUILIBRIUM command
is not issued prior to a static or quasi-static simulation, Adams/Solver (FORTRAN) uses the default
values for ALIMIT, ERROR, IMBALANCE, MAXIT, PATTERN, STABILITY, and TLIMIT for the
analysis.
Format
EQUILIBRIUM 51
Adams/Solver (FORTRAN) Commands
Arguments
ACCELERATION_ERROR=r
ALIMIT=r
DEFAULT
STATIC
ALIMIT = 10D
ERROR = 1.0
IMBALANCE = 1.0E-4
MAXIT = 25
PATTERN = T:T:T:T:T:T:T:T:T:T
STABILITY = 1.0E-5
TLIMIT = 20
DYNAMIC
ERROR=r
GLOBAL_DAMPING=r
IMBALANCE=r
52 Adams/Solver
LIST
MAXIT=r
PATTERN=c1[:...:c10]
SETTLING_TIME=r
STABILITY=r
EQUILIBRIUM 53
Adams/Solver (FORTRAN) Commands
STATIC
TLIMIT=r
Extended Definition
For an extended definition on the EQUILIBRIUM command and corresponding tips, cautions, and
examples, refer to the EQUILIBRIUM statement.
See other Analysis parameters available.
54 Adams/Solver
ERASE/RESTORE
The ERASE and RESTORE commands disable or enable the graphics output from GRAPHICS
statements.
Format
ERASE GRAPHICS=id1[,...,idn]
or
RESTORE GRAPHICS=id1[,...,idn]
Arguments
GRAPHICS=id1[,...,idn]
Tip:
EXECUTION 55
Adams/Solver (FORTRAN) Commands
EXECUTION
The EXECUTION command lets you toggle between the graphics and alphanumeric modes, and lets you
list the current status of the command.
Format
Arguments
GRAPHICS
LIST
NOGRAPHICS Indicates that Adams/Solver (FORTRAN) is to stop displaying the graphics for the
mechanism each time it writes output. NOGRAPHICS is the opposite of GRAPHICS.
Tip:
If you want Adams/Solver (FORTRAN) to display a graphic frame for each iteration of a
static simulation, enter DEBUG/EPRINT before entering EXE/GRAPHIC. Adams/Solver
(FORTRAN) prompts you to press return each time Adams/Solver (FORTRAN) iterates,
and the current configuration are displayed. If the static simulation converges, the last
iteration is the static configuration.
Caution:
The ICSTART argument and the .icf file have been discontinued. The SAVE and RELOAD
commands replace the OUTPUT/ICSAVE and EXECUTION/ICSTART arguments. See
the RELOAD and SAVE commands.
Examples
EXECUTION/GRAPHICS
This EXECUTION command indicates that Adams/Solver (FORTRAN) is to display graphics each time
it writes output.
56 Adams/Solver
FIELD 57
Adams/Solver (FORTRAN) Commands
FIELD
The FIELD command redefines and/or lists the data for a FIELD statement. You cannot redefine the I and
the J markers, but you can redefine any other argument values.
Format
58 Adams/Solver
Arguments
CMATRIX=r1,...,r36
CRATIO=r
FORCE=r1,...,r6
LENGTH=r1,...r6
LIST
ROUTINE=libname::subname
FIELD 59
Adams/Solver (FORTRAN) Commands
Tip:
Caution:
Finite element analysis programs can give the values for CMATRIX and KMATRIX.
The three rotational displacements (a, b, and c) that define the field are not Euler
angles. They are the projected angles of the I marker with respect to the J marker.
Adams/Solver (FORTRAN) measures them about the x-, y-, and z-axis of the J
marker.
For the constitutive equations to be accurate, at least two of the rotations (a, b, c)
must be small. That is, two of the three values must remain smaller than 10
degrees. In addition, if a becomes greater than 90 degrees, b becomes erratic. If b
becomes greater than 90 degrees, a becomes erratic. Only c can become greater
than 90 degrees without causing convergence problems. For these reasons, it is
best to define your field such that angles a and b (not a and c and not b and c)
remain small.
Adams/Solver (FORTRAN) applies the component translational and rotational
forces for a field to the I marker and imposes reaction forces on the J marker.
The FIELD command allows you to define all six-component, action-reaction
forces. However, when massless beams are being defined, you may want to use the
BEAM command. It requires only six input values to compute the thirty-six values
for the KMATRIX argument (see the BEAM statement).
The K and C matrices must be postitive semidefinite. In other words, xtK x > 0 for
60 Adams/Solver
FILE
The FILE command loads a new model from a dataset file, or executes commands from a Command file.
Format
Arguments
COMMAND=c
FILE 61
Adams/Solver (FORTRAN) Commands
MODEL=c
OUTPUT_PREFIX=c Optionally, specifies a new file base name for output files that Adams/Solver
(FORTRAN) generates by subsequent simulations. The file extensions conform
to standard Adams/Solver (FORTRAN) naming conventions. If you do not
specify an OUTPUT_PREFIX argument, Adams/Solver (FORTRAN) defaults
to the basename of the MODEL argument. Because the OUTPUT_PREFIX
argument and value can be at most eighty characters long, the basename and
path are limited from sixty-six characters (if you do not abbreviate
OUTPUT_PREFIX) to seventy-six characters (if you abbreviate
OUTPUT_PREFIX to OUT=).
Range: All printable characters except !, ;, , and &
Extended Definition
The FILE command either restarts Adams/Solver (FORTRAN) with a new model, or a executes a set of
commands from a file.
The MODEL argument specifies a new dataset (.adm) file. Adams/Solver (FORTRAN) closes any output
files from a previous simulation, and then completely restarts by setting the simulation time to zero and
reading the new model. Next, Adams/Solver (FORTRAN) prompts you for a new command, just as if
Adams/Solver (FORTRAN) had read the model when first started. By default, the output files use the
same base name as the model file. The optional OUTPUT_PREFIX argument specifies a different base
name, if needed.
The COMMAND argument specifies a file containing Adams/Solver (FORTRAN) commands.
Adams/Solver (FORTRAN) reads and executes the commands in the file. If the FILE command was
interactive, Adams/Solver (FORTRAN) returns to interactive input when the command file is exhausted.
62 Adams/Solver
If the FILE command was in a command file itself, Adams/Solver (FORTRAN) returns to reading
commands from that file. Command files can contain other FILE commands, nested up to 10 files deep.
Tip:
within one Adams/Solver (FORTRAN) run. This may be quicker and more
convenient than invoking Adams/Solver (FORTRAN) separately for each
simulation.
Although the FILE command may be used to repeatedly reload the same model,
the SAVE and RELOAD combination is much quicker than rereading the original
dataset.
Caution:
The COMMAND argument does not automatically load a new model, it executes
commands just as they appear in the specified file. Unlike a Command file used to start
Adams/Solver (FORTRAN), a Command file read here must start with an Adams/Solver
(FORTRAN) command, not input and output file names.
Examples
FILE/MODEL=TURN45
This FILE command loads dataset TURN45.ADM. The output files default to TURN45.REQ,
TURN45.GRA, etc.
FILE/MODEL=TURN45,OUTPUT_PREFIX=TEST2
This FILE command also loads dataset TURN45.ADM, but the output files are TEST2.REQ,
TEST2.GRA, etc.
See other Simulation available.
FLEX_BODY 63
Adams/Solver (FORTRAN) Commands
FLEX_BODY
The FLEX_BODY command redefines and/or lists the data for the FLEX_BODY statement that defines
linear elastic body.
Format
Arguments
CRATIO =
USER ( r 1 [ ,, r 30 ] )
64 Adams/Solver
FRICTION
The FRICTION command defines parameters that enable joint friction forces on translational, revolute,
cylindrical, hooke, universal, and spherical joints.
Note:
Format
Frictional forces and torques are computed by Adams/Solver (FORTRAN) using a friction
model that supports dynamic frictions and stiction.
FRICTION 65
Adams/Solver (FORTRAN) Commands
Arguments
BALL_RADIUS=Rb
FRICTION_FORCE_PRELOAD=r
FRICTION_ARM=Rn,
INACTIVE=STATIC
INITIAL_OVERLAP=Xs0
66 Adams/Solver
JOINT=id
MAX_STICTION_DEFORMATION=r
MU_DYNAMIC=r
LIST
FRICTION 67
Adams/Solver (FORTRAN) Commands
MU_STATIC=r
OVERLAP_DELTA={INCREASE,
DECREASE, CONSTANT}
REACTION_ARM=Rn
68 Adams/Solver
FRICTION_TORQUE_PRELOAD=r
I_YOKE
J_YOKE
Extended Defintion
For an extended definition on the statement associated with this command, see the FRICTION statement.
Caution:
Examples
FRICTION/102, INPUTS=NONE
This command turns off the friction calculations of FRICTION/102.
See other Forces available.
GFORCE 69
Adams/Solver (FORTRAN) Commands
GFORCE
The GFORCE command redefines and/or list the data for a GFORCE statement that defines a force
element that consists of three orthogonal translational force components and three orthogonal torque
components.
Format
Arguments
FY=e
FZ=e
70 Adams/Solver
I=id
JFLOAT=id
LIST
RM=id
ROUTINE=libname::subname
TX=e
TY=e
TZ=e
Extended Definition
The GFORCE command lists or redefines a force element that consists of three mutually orthogonal
translational force components and three orthogonal torque components. You can alter one or both points
GFORCE 71
Adams/Solver (FORTRAN) Commands
of force and torque application, change the force reference marker, and change the force and torque
function expressions or the parameters passed to the GFOSUB user-written subroutine.
After a change to a GFORCE, Adams/Solver (FORTRAN) reprocesses the model at the next SIMULATE
command, as if it had just been read in from the dataset. During the reprocessing, Adams/Solver
(FORTRAN) checks the entire model for consistency, reinitializes user subroutines, and recomputes
initial conditions.
While checking, Adams/Solver (FORTRAN) verifies that the model is still valid with the new GFORCE.
If, for example, the GFORCE function expression refers to an inactive element, Adams/Solver
(FORTRAN) issues an error.
Adams/Solver also reinitializes all user subroutines to re-establish functional dependencies. For each
element that refers to a user-written subroutine, Adams/Solver calls the user-written subroutine with
IFLAG set to true.
Prior to the actual simulation, Adams/Solver computes initial conditions for the model. If this is the first
simulation, Adams/Solver begins with the positions and velocities specified in the dataset. If you ran a
previous simulation, Adams/Solver begins with the final displacements and velocities. Adams/Solver
then adjusts the initial conditions to ensure that they are consistent with the model constraints. If this is
the first simulation, Adams/Solver also maintains any user supplied joint initial-conditions and positions
specified as EXACT.
If you change a GFORCE I marker, J marker, or type in the middle of a simulation, by default
Adams/Solver (FORTRAN) splits the tabular, request, graphics, and results output into two separate sets
of output concatenated together. This ensures that the output correctly reflects the new system topology.
Adams/Solver (FORTRAN) does not split the files if you change only the GFORCE function expression.
The OUTPUT/NOSEPARATOR argument prevents Adams/Solver (FORTRAN) from splitting the file.
This allows you to plot or animate the output continuously from beginning to end, but may result in
misleading graphics during postprocessing. See OUTPUT for more information on the NOSEPARATOR
argument.
Tip:
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 user-defined functions FX, FY, FZ, TX, TY, and TZ should be smooth, continuous, and
single-valued. These conditions make the solution process very effective.
Examples
GFORCE/1, I=8, JFLOAT=6, RM=7, LIST, &
FY = 0/ &
FZ = 0/ &
TY = 0/ &
TZ = 0
72 Adams/Solver
This GFORCE command redefines and lists the general, six-component force acting between fixed
Marker 310 and floating Marker 9910. The force and torque components FY, FZ, TY, and TZ are set to
zero along the y and z axes of the reference marker, which is Marker 310. Adams/Solver (FORTRAN)
superimposes floating Marker 9910 on Marker 310 and applies the FX and TX reaction force and torque
at that point.
See other Forces available.
HELP 73
Adams/Solver (FORTRAN) Commands
HELP
The HELP command opens the online help for Adams/Solver.
To navigate through the help:
Select a topic from the left.
74 Adams/Solver
IC
The IC command redefines and/or lists the data for an IC statement. If you issue neither the IC command
nor statement in an Adams/Solver (FORTRAN) session, Adams/Solver (FORTRAN) uses the default
values for AERROR, ALIMIT, AMAXIT, APATTERN, ERROR, MAXIT, PATTERN, TLIMIT, and
VERROR when finding initial conditions.
Format
IC 75
Adams/Solver (FORTRAN) Commands
Arguments
AERROR=r
ALIMIT=r
AMAXIT=i
APATTERN=c1[:...:c10] Respecifies 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 (FORTRAN) is to evaluate the Jacobian, and F
or FALSE indicates that Adams/Solver (FORTRAN) is not to evaluate the
Jacobian. Thus, cj determines whether or not ADAMS is to evaluate the
Jacobian at the jth iteration. If necessary, Adams/Solver (FORTRAN)
repeats the pattern of evaluation until it reaches the maximum number of
iterations (AMAXIT). The number of T's or TRUEs and Fs or FALSEs
together must be at least one and no more than 10.
DEFAULT
Resets all options to the default values specified in the IC statement, namely:
AERROR = 1.0E-4
ALIMIT = 30D
AMAXIT = 25
APATTERN = T:T:T:T:T:T:T:T:T:T
ERROR = 1.0E-10
MAXIT = 25
PATTERN = T:T:T:T:T:T:T:T:T:T
TLIMIT = 1.0E10
VERROR = 1.0E-4
ERROR
76 Adams/Solver
LIST
MAXIT=i
PATTERN=c1[:...:c10]
TLIMIT=r
VERROR=r
Tip:
Use the ALIMIT and TLIMIT arguments to limit the increments of the displacement
variables if Adams/Solver (FORTRAN) fails to converge to a solution or converges to an
undesirable configuration. This lessens the position change on successive iterations, and
tends to keep the solution closer to the initial configuration.
INFO 77
Adams/Solver (FORTRAN) Commands
INFO
The INFO command lists the vector components for the displacement, velocity, or acceleration of one
marker with respect to another or displays force values at the current simulation time. This command
resolves components in the ground coordinate system (GCS) or in another specified reference frame.
Format
Arguments
ACCELERATION Lists the accelerations of the I marker minus the accelerations of the J marker.
Adams/Solver (FORTRAN) reports translational accelerations in units of
displacement per time squared and rotational accelerations in units of radians per
time squared.
DISPLACEMENT Lists the x, y, z, psi, theta, and phi displacements of the I marker with respect to
the J marker. Adams/Solver (FORTRAN) reports translational displacements in
units of displacement and rotational displacements in units of radians.
FORCE
Lists the components for the force at the I marker. A BEAM, BUSHING, CVCV,
FIELD, GFORCE, JOINT, JPRIM, MOTION, NFORCE, PTCV, SFORCE,
SPRINGDAMPER, VFORCE, or VTORQUE statement can define the force.
You should include both the I and the J arguments to measure the action-reaction
force(s) between two markers (I, J). You should include the I argument and either
give zero as the J argument or omit the J argument altogether to measure the
action-only force(s) at a marker (I).
I=id
Specifies the identifier of the fixed or floating marker for which Adams/Solver
(FORTRAN) is to measure displacements, velocities, accelerations, or action
forces.
J=id
Specifies the identifier of the fixed or floating marker with respect to which
Adams/Solver (FORTRAN) is to measure the displacements, velocities, or
accelerations of the I marker, or the identifier of the marker for which
Adams/Solver (FORTRAN) is to measure reaction forces.
78 Adams/Solver
RM=id
VELOCITY
Lists the velocities of the I marker minus the velocities of the J marker.
Translational velocities are given in units of displacement per time. Rotational
displacements are given in units of radians per time.
Examples
INFO/ DISP, I=10, J=15, RM=43
This INFO command lists the x, y, z, psi, theta, and phi displacements of Marker 10 with respect to
Marker 15. Adams/Solver (FORTRAN) measures x, y, and z in the Cartesian coordinates of Marker 43.
INFO/ ACC, I=12, J=100
This INFO command lists the x, y, and z translational and rotational accelerations of Marker 12 with
respect to Marker 100. Adams/Solver (FORTRAN) measures x, y, and z in the Cartesian coordinates of
the ground coordinate system (GCS).
See other Information available.
INTEGRATOR 79
Adams/Solver (FORTRAN) Commands
INTEGRATOR
The INTEGRATOR command lets you redefine data in the INTEGRATOR statement.
Format
80 Adams/Solver
Arguments
ABAM
ADAPTIVITY=r
CONSTANT_BD
F
INTEGRATOR 81
Adams/Solver (FORTRAN) Commands
Specifies the corrector algorithm that is to be used with the stiff integrators
GSTIFF, WSTIFF,
or CONSTANT_BDF. The corrector in a stiff integrator
ORIGNAL
Resets the integrator parameters. See the default values in the INTEGRATOR
statement.
82 Adams/Solver
ERROR=r
Specifies the relative and absolute local integration error tolerances that the
integrator must satisfy at each step. For BDF integrators, Adams/Solver
(FORTRAN) monitors the integration errors in the displacement and state
variables that the other differential equations (DIFFs, LSEs, GSEs, and TFSISOs)
define. ABAM, SI1, and SI2 formulations also monitor errors in velocity
variables. The larger the ERROR, the greater the error/step in your solution.
Note that the value for ERROR is units-sensitive. For example, if a system is
modeled in mm-kg-s units, the units of length must be in mm.
Assuming that all the translational states are larger than 1mm, setting
ERROR=1E-3 implies that the integrator monitors all changes of the order of 1
micron.
The error tolerances (e) are enforced as:
||Yc - Y|| < MAX (e,e * ||Y||)
where Yc is the column matrix of computed values for the unknowns, Y. The
symbol || . || indicates the root-mean-square of the array of numbers.
Range: ERROR > 0
GSTIFF
Specifies that the GSTIFF (Gear) integrator is to be used for integrating the
differential equations of motion.
HINIT=r
HMAX=r
Defines the maximum time step that the integrator is allowed to take.
Default: When setting the argument INTERPOLATE = ON, the integration step
size is limited to the value specified for HMAX, but if HMAX is not defined, no
limit is placed on the integration step size. If INTERPOLATE = OFF, the
maximum step size is limited to the output step.
Range: 0 < HMIN < HINIT < HMAX
HMIN=r
Defines the minimum time step that the integrator is allowed to take.
Range: 0 < HMIN < HINIT < HMAX
INTEGRATOR 83
Adams/Solver (FORTRAN) Commands
INTERPOLATE=ON specifies that the integrator is not required to control its step
size to hit an output point. Therefore, when the integrator crosses an output point,
ON
INTERPOLATE = it computes
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 therefore, controls the local
integration error at each step so that it is less than the error tolerance specified.
Note:
LIST
MAXIT=i
84 Adams/Solver
PATTERN=c1[:...: Indicates the pattern of trues and falses for re-evaluating the Jacobian matrix for
c10]
Newton-Raphson. A value of true (T) indicates that Adams/Solver (FORTRAN)
is evaluating a new Jacobian matrix for that iteration. A value of false (F) indicates
that Adams/Solver (FORTRAN) is using the previously calculated Jacobian
matrix as an approximation of the current one.
PATTERN accepts a sequence of at least 1 character string and not more than 10
character strings. Each string must be either TRUE or FALSE, which you can
abbreviate with T or F. You must separate the strings with colons.
Note:
RKF45
SCALE=r1[,r2][,r
3]
The SCALE parameter applies to only WSTIFF and ABAM. It is not applicable
to GSTIFF and CONSTANT_BDF.
SCALE scales the sum of the relative and absolute error tolerances. If T is the sum
of the relative and absolute error tolerances applied to the state vector, then the
following tolerance is applied:
r1 * T to the translational displacements
r2 * T to the angular displacements
r3 * T to the modal coordinates
Note:
INTEGRATOR 85
Adams/Solver (FORTRAN) Commands
SI1
Specifies that the Stabilized Index-1 (SI1) formulation, in conjunction with the
GSTIFF, WSTIFF, or CONSTANT_BDF 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. In addition, it monitors the integration error on the impulse
of the Lagrange Multipliers in the system. These additional safeguards enable the
integrators to monitor the integrator error in velocity variables and the impulse of
the Lagrange Multipliers. Simulation results are, therefore, very accurate. A
positive side effect of the SI1 formulation is that the Jacobian matrix remains
stable at small step sizes, which increases the stability and robustness of the
corrector at small step sizes.
For additional information, see the Extended Definition in the INTEGRATOR
statement.
SI2
Specifies that the Stabilized Index-2 (SI2) formulation, in conjunction with the
GSTIFF or CONSTANT_BDF integrator, be used for formulating and integrating
differential equations of motion.
The SI2 formulation takes into account constraint derivatives when solving for
equations of motion. This process enables the GSTIFF integrator to monitor the
integration error of velocity variables, and therefore renders highly accurate
simulations. A positive side effect of the SI2 formulation is that the Jacobian
matrix remains stable at small step sizes, which increases the stability and
robustness of the corrector at small step sizes.
The SI2 formulation is available only with GSTIFF and CONSTANT_BDF.
For additional information, see the Extended Definition in the INTEGRATOR
statement.
WSTIFF
Specifies that the WSTIFF (Wielenga stiff) integrator be used for integrating the
differential equations of motion. WSTIFF uses the BDF method that takes step
sizes into account when calculating the coefficients for any particular integration
order.
Extended Definition
For an extended definition, cautions, and tips, see the INTEGRATOR statement.
Examples
86 Adams/Solver
The integrator has an error limit of 1.0E-4 and overrides the default value of 1.0E-3.
HINIT= 1.0E-6 specifies an initial timestep of 1.0E-6, which overrides the default of 1/20th of
JOINT 87
Adams/Solver (FORTRAN) Commands
JOINT
The JOINT command lists all the data for a JOINT statement.
Format
JOINT/id [,LIST]
[ ] Optionally select the item
Arguments
LIST
Examples
JOINT/10, LIST
This JOINT command lists all the data for Joint 10.
See other Constraints available.
88 Adams/Solver
KINEMATICS
The KINEMATICS command redefines and/or lists the data for a KINEMATICS statement. If you issue
neither the KINEMATICS command nor statement in an Adams/Solver (FORTRAN) session,
Adams/Solver (FORTRAN) uses the default values for AERROR, ALIMIT, AMAXIT, APATTERN,
ERROR, MAXIT, PATTERN, and TLIMIT when performing a kinematic analysis.
Format
KINEMATICS 89
Adams/Solver (FORTRAN) Commands
Arguments
AERROR=r
ALIMIT=r
AMAXIT=i
APATTERN=c1[:...:c10] Respecifies as many as ten character strings that together establish the pattern
for evaluating the Jacobian matrix during the modified Newton-Raphson
solution for the accelerations. For each iteration, T or TRUE indicates that
Adams/Solver (FORTRAN) is to evaluate the Jacobian, and F or FALSE
indicates that Adams/Solver (FORTRAN) is not to evaluate the Jacobian.
Thus, cj determines whether or not Adams/Solver (FORTRAN) is to evaluate
the Jacobian at the jth iteration. If necessary, Adams/Solver (FORTRAN)
repeats the pattern of evaluations until it reaches the maximum number of
iterations (AMAXIT). The number of Ts or TRUEs and Fs or FALSEs
together must be at least one and no more than 10.
DEFAULT
ERROR=r
90 Adams/Solver
HMAX=r
Defines the maximum time step that the KINEMATICS solution is allowed
to take.
When performing kinematic simulations on systems with parts that are
rotating at very high speeds (at or more than one revolution per time step), it
is possible for the kinematic to fail or provide inaccurate results because of
lack of information on the system between output step solutions. The HMAX
value can be used to limit the time between solution steps without having to
specify a large number of output steps.
LIST
MAXIT=i
PATTERN=c1[:...:c10]
Respecifies as many as ten character strings that together establish the pattern
for evaluating the Jacobian matrix during the modified Newton-Raphson
solution for the displacements. For each iteration, T or TRUE indicates that
Adams/Solver (FORTRAN) is to evaluate the Jacobian and F or FALSE
indicates that Adams/Solver (FORTRAN) is not to evaluate the Jacobian.
Thus cj determines whether or not Adams/Solver (FORTRAN) is to evaluate
the Jacobian at the jth iteration. If necessary, Adams/Solver (FORTRAN)
repeats the pattern of evaluations until it reaches the maximum number of
iterations (MAXIT). The number of Ts or TRUEs and Fs or FALSEs
together must be at least one and no more than ten.
TLIMIT=r
Tip:
Using the PATTERN argument to request less frequent evaluations of the Jacobian
matrix may decrease the computation time, thereby decreasing the cost and
improving the response time. However, it could also have the opposite effect since
more iterations may be required to reach the solution with a stale Jacobian matrix.
Use the ALIMIT and TLIMIT arguments to limit the increments of the
LINEAR 91
Adams/Solver (FORTRAN) Commands
LINEAR
Note:
1. General
You can use the LINEAR command to linearize Adams models. Linearized Adams models can be
represented by complex valued eigendata (eigenvalues, mode shapes) or by a state space representation
in the form of real-valued state matrices (A, B, C, and D). Adams uses a condensation scheme to reduce
an Adams model to a minimal realization linear form for efficient solution. (For more information, see
Automatic Linearization of Constrained Dynamical Systems, Sohoni, V.N. and J. Whitesell. ASME J. of
Mechanisms, Transmissions and Automation in Design, Sept. 1986, Vol. 108, No.3, pp.300-304.)
There are several applications where a linearized representation of the model can provide important
insight into the dynamical behavior of the model. Stability properties of the system have a direct
relationship to the real part of the complex eigenvalue. Eigenvalues with positive real parts represent
unstable modes of the system, while those with negative real parts represent stable modes. If bounded
inputs to the system cause excitation of an unstable mode, the system produces an unbounded response.
On the other hand, bounded excitation of a stable mode results in a bounded response. Eigenvalues
computed by Adams/Solver (FORTRAN) can be plotted on a real-imaginary plot and the mode shapes
then animated in Adams. In addition to verifying stability, eigendata is used for validating
implementation of models with eigendata from other modeling approaches or experimental data. This is
especially true if an elastic or control sub-system model has been implemented in Adams/Solver
(FORTRAN).
Adams/Linear outputs a state space representation in a form suitable for importation into matrix
manipulation and control design packages such as MATRIXx and MATLAB (for more information see
the Xmath Basics Guide, 1996, Integrated Systems Inc., Santa Clara, CA and Matlab User's Guide, The
MathWorks Inc., Natick, Massachusetts). A state space model representation is suitable for obtaining
frequency response of the Adams model, verifying model control properties (controllability and
observability), and designing feedback controllers for Adams models.
92 Adams/Solver
The LINEAR command invokes the Adams/Linear option in Adams/Solver (FORTRAN). The LINEAR
command linearizes the nonlinear system equations of motion and provides two basic capabilities, an
eigensolution or a state space matrix calculation. The eigensolution option determines natural
frequencies and mode shapes while the matrix calculation option computes the linear state space matrix
that describes the mechanical system. You may issue this command following initial conditions, a static
or a transient analysis. Depending on the options you specify, the results of the command are reported on
the screen and written to the Tabular Output file, the Results file, and, if required, the user-specified files.
3. Format
LINEAR 93
Adams/Solver (FORTRAN) Commands
4. Arguments
COORDS=i1[,i2]
EIGENSOL
ENERGY=i1[,i2]
Specifies that a table of modal energy distribution for mode numbers in the
range i1 to i2 be computed and output.
If i2 is not specified, Adams/Solver (FORTRAN) produces the table of modal
energy distribution for mode number i1 only.
Range: i1 > 1, i2 > i1
Type: Optional with EIGENSOL; mutally exclusive with NOVECTOR
DISSIPAT=i1[,i2]
FILE=c
94 Adams/Solver
Specifies that a table of kinetic energy distribution for mode numbers in the
range i1 to i2 be computed and output.
If i2 is not specified, Adams/Solver (FORTRAN) produces the table of kinetic
energy distribution for mode number i1 only.
Range: i1 > 1, i2 > i1
Type: Optional with EIGENSOL; mutually exclusive with NOVECTOR
NODAMPIN
NOVECTOR
PINPUT=id
POUTPUT=id
LINEAR 95
Adams/Solver (FORTRAN) Commands
STATEMAT
STRAIN=i1[,i2]
Specifies that a table of strain energy distribution for mode numbers in the
range i1 to i2 be computed and output. If i2 is not specified, Adams/Solver
(FORTRAN) produces the table of strain energy distribution for mode number
i1 only.
Type: Optional with EIGENSOL; mutually exclusive with NOVECTOR
5. Extended Definition
Mz
where:
z is the eigenvector
is the eigenvalue
K and M are the constant coefficient matrices derived by Adams/Solver (FORTRAN) from the
Adams model
The eigenvector is mapped to the mode shape prior to output to the results (.res) file.
If you specify the NODAMPIN argument, Adams/Solver (FORTRAN) does not include the velocitydependent terms in forces nor does it include velocity-dependent terms in the VARIABLE statements in
the K and M matrices. Using this option may be beneficial in determining the underlying modes for a
system with critical or greater than critical damping.
If you specify the NOVECTOR argument, Adams/Solver (FORTRAN) computes only the eigenvalues
and not the mode shapes. Adams/Solver (FORTRAN) reports on the screen eigenvalues that result from
the eigensolution and writes this data to the tabular output file (.out). If you use the RESULTS statement
to enable output to the results file (.res) in the Adams/Solver (FORTRAN) dataset, the eigenvalues and
mode shapes (if computed) will be written to this file. The results file may be taken to a postprocessor
such as Adams/View for further processing.
96 Adams/Solver
All eigenvalues are normalized to be in cycles/second. The imaginary component of the eigenvalue
represents the oscillatory behavior of the mode and the real component, the damping characteristic.
The model eigenvalues are reported to the workstation screen or in a tabular form to the tabular output
(.out) file. In general, the eigenvalues are complex values, made up of real and imaginary components.
The imaginary component represents the 'damped' natural frequency, d. The damping ratio must be
less than 1 in order to produce an imaginary component in the eigenvalue -- in other words, the damped
natural frequency is zero whenever the damping ratio is 1 or greater.
The undamped natural frequency and damping ratio obeys following equations:
n =
( r2 + i2 )
r
= -----n
where:
d = n ( 1 2 )
The damped natural frequency is the actual frequency at which the system is oscillating for that mode.
If you specify the COORDS, ENERGY, KINETIC, DISSIPAT, or STRAIN arguments, Adams/Solver
(FORTRAN) computes tabular output and writes it to the output (.out) file. For each mode in the specified
range, this output could consist of up to five sections. The header section contains the mode number,
undamped natural frequency, damping ratio, generalized stiffness, generalized mass and model energy
for the mode. Generalized stiffness and generalized mass are in user-specified units.
The second section is a table of coordinates if the COORDS argument is specified. This section is not
output if the COORDS argument is not specified or if the particular mode number is not within the range
specified on the COORDS argument. Each part in the Adams/Solver (FORTRAN) model has one row in
this table. The part translational coordinates in columns labeled (x,y,z), represent the small translational
displacements of the part center-of-mass (cm) marker in the global reference frame. The part rotational
coordinates, in columns labeled (RX, RY, RZ), represent the small rotational displacements of the part
about the global x, y and z axes, respectively. Each coordinates in this table is represented by a magnitude
LINEAR 97
Adams/Solver (FORTRAN) Commands
and a phase. The mode is normalized so that the largest component in the mode has a value of 1.0 and a
phase angle of 0 degrees. Magnitude and phase of all other components in the mode are reported relative
to this largest component. Phase angles are represented in the range 0 to 355 degrees. Phase angles in the
range 175 to 185 degrees are reported as 180 degrees. Phase angles in the range 355 to 360 degrees as
well as phase angles in the range zero to five degrees are reported as zero degrees. States of elements
resulting in user supplied differential equations are also represented in the coordinate table. All
components with zero magnitude are also reported as having zero phase angles.
The third section is a table of modal kinetic energy distribution if the ENERGY or KINETIC arguments
are specified. This section is not present in the output for a particular mode if the mode number is not
within the range of the modes specified on the ENERGY or KINETIC arguments. Each part is
represented by a single row in this table. Each entry in this table represents the percentage of the total
modal kinetic energy for that part in a particular direction. Translational directions in which the modal
kinetic energy distribution is computed are x, y and z displacement of the part center-of-mass (cm) in the
global reference frame. Rotational directions are denoted by RXX, RYY, and RZZ; these represent the
small displacement rotations of the part about the global x, y and z axes, respectively. The cross rotations
are represented as RXY, RYZ, and RXZ. The sum of all values in a modal energy distribution table should
be 100.0. Elements resulting in user-supplied differential equations are not considered in the computation
for this table.
The fourth section is a table of modal strain energy distribution if the STRAIN argument is specified.
This section is not present in the output for a particular mode if the mode number is not within the range
of the modes specified on the STRAIN argument. Each force element is represented by one or more rows
in this table. The table below shows the contribution of various element types to this table. Computation
of strain energy accounts for the direct and indirect dependence of the force on PART displacements. The
indirect dependence on PART displacements may be through dependence of the force on other FORCEs,
VARIABLEs, or algebraic DIFFs that may be directly or indirectly dependent on PART displacements.
Table 1. Elements Contributing to Table for Dissipative and Strain Energy Computations
Total
RX
RY
RZ
BEAM
BUSHING
FIELD
GFORCE
...
for marker n
SFORCE (translational)
SFORCE (rotational)
SPRINGDAMPER
(translational)
98 Adams/Solver
Total
SPRINGDAMPER
(rotational)
VFORCE
VTORQUE
RX
RY
RZ
X
X
In the table, X, Y, and Z refer to translation components along the global x, y and z directions and RX,
RY, and RZ refer to rotational components about the global x, y and z directions. x indicates locations for
contributions for individual elements. The column labeled Total contains a summation of the
strain/dissipative energy contribution due to the element in various directions.
The fifth section is a table of modal dissipative energy distribution if the DISSIPAT argument is specified.
This section is not present in the output for a particular mode if the mode number is not within the range
of the modes specified on the DISSIPAT argument. Each force element is represented by one or more
rows in this table. The table shows the contribution of elements to this table. Computation of dissipative
energy accounts for the direct and indirect dependence of the force on PART velocities. The indirect
dependence on PART velocities may be through dependence of the force on other FORCEs,
VARIABLEs, or algebraic DIFFs that may be directly or indirectly dependent on PART velocities.
If you specify the STATEMAT argument, Adams/Solver (FORTRAN) computes the state matrices
representation for an Adams model. The linearized Adams model is represented as:
x =A x + B u
y=Cx+Du
where:
You can specify the definition of plant inputs with the PINPUT argument value. Similarly, plant outputs
are specified by the POUTPUT argument. Plant states are automatically determined by Adams/Solver
(FORTRAN) and result in the best numerical conditioning of the state matrices. While several PINPUT
statements and POUTPUT statements may be present in an Adams model, you can specify only one of
each on the LINEAR command.
Corresponding to each VARIABLE id specified on the PINPUT statement, a column exists in the B and
D matrices. Similarly, for each VARIABLE id specified on the POUTPUT statement, a row exists in the
C and D matrices. In effect, each VARIABLE id specified on the PINPUT or POUTPUT statement
specifies an input or output channel, respectively.
LINEAR 99
Adams/Solver (FORTRAN) Commands
Open-loop/closed-loop input channels are important in the computation of state matrices. If a VARIABLE
statement whose id is specified on a PINPUT statement is defined as:
VARIABLE/id, FUNCTION = constant
or
VARIABLE/id, FUNCTION = function_of_time
then it is designated as an open-loop input channel. However, if the VARIABLE is of the form:
VARIABLE/id, FUNCTION=function_of_ADAMS-model-states
it is designated as a closed-loop input channel with feedback. This distinction is reflected in the A, B, and
D matrices. Columns in the B and D matrices corresponding to a closed-loop input channel will have all
zero values. Effects of the feedback loop due to these inputs is reflected in the A matrix. This implies that
external inputs on these channels are not permitted.
Consider a system of the following form:
x =A x + B u
y=Cx
Partitioning the plant input into two groups called u1 and u2, the plant model becomes:
x =A x + B1u1 + B2u2
y=Cx
where B1 and B2 are sub-matrices of B, corresponding to u1 and u2, respectively; and u1 and u2 are the
closed-loop and open-loop input channels, respectively.
If the input u1 represents the closed-loop input channels defined by the feedback loop:
u1 = -G y
where G is the feedback gain matrix, the plant model can then be represented as:
x = [ A - B1 G C ] x + [0] u1 + B2 u2
y=Cx
Adams/Solver (FORTRAN) computes the state matrices for a model with this combination of inputs and
outputs as:
100 Adams/Solver
= [ A B KC ]
A
1
= [0 B ]
B
2
= C
C
matrix. Columns of the B
matrix
The effects of the closed-loop channels are reflected in the A
corresponding to the closed-loop channel are zero. In other words, the PINPUT or POUTPUT id
specification that you choose on the LINEAR command affects the structure of the A, B, C, and D
matrices.
Tip:
its eigenvalues. Eigenvalues with positive real parts correspond to unstable modes
of the system.
If you specify the PINPUT and the POUTPUT arguments for state matrices output,
Adams/Solver (FORTRAN) produces all four matrices (A, B, C, and D). If you do
not specify the PINPUT argument, Adams/Solver (FORTRAN) does not produce
the B or D matrices. Similarly, if you do not specify the POUTPUT argument,
Adams/Solver (FORTRAN) will not produce the C or D matrices. If you do not
specify either the PINPUT or POUTPUT arguments, Adams/Solver (FORTRAN)
produces only the A matrix.
You may define several PINPUT and POUTPUT statements in an Adams/Solver
LINEAR 101
Adams/Solver (FORTRAN) Commands
Caution:
TRANSIENT analysis.
Dependence of function expressions on joint reaction forces is ignored for
linearization.
Adams models containing nonholonomic UCONs cannot be linearized.
Since the eigensolution and state matrices characterize behavior of the nonlinear
angular velocities. If the angular velocity vector passes through the center of
mass of the respective parts, it is acceptable to linearize such models. An
example of such a system would be a vehicle moving in a straight line with its
wheels rotating about their axes.
If, however, the angular velocity vector does not pass through the center of mass
of the respective part, the system should not be linearized. This is especially true
if the angular velocity magnitudes are large. An example of this would be a
spinning, articulated structure containing a center hub with articulated outboard
parts. The spin axes of the outboard parts do not pass through the center of mass
of the parts. Linearization of such models may produce spurious results.
Applying MOTION to a JOINT restricts the respective degree-of-freedom. As
a result, during state matrices output, any PINPUT applied to a part constrained
by such a MOTION results in a zero column for the B matrix.
6. Examples
LINEAR/EIGENSOL
This command computes an eigenanalysis for the Adams model. Adams/Solver (FORTRAN) writes the
eigenvalues and mode shapes to the Results file where they can be read and displayed by a postprocessor
such as Adams/View.
LINEAR/STATEMAT, PINPUT=10, POUTPUT=20
, FORMAT=MATRIXX FILE=STATES.MAT
This command computes state matrices for the Adams model, using PINPUT/10 as inputs and
POUTPUT/20 as outputs. The state matrices are written to file STATES.MAT in MATRIXX format.
102 Adams/Solver
7. Applications
Eigensolutions provide you with information that may be used in assessing stability of the Adams model.
If you import control systems descriptions or distributed elasticity data from external sources, you can
verify the stability of their Adams models.
1. Eigendata computed by Adams/Solver (FORTRAN) can be used to validate Adams models
against eigendata from external sources.
2. State matrices descriptions can be used in designing control systems for Adams models. This
description is suitable for computing frequency response data in matrix manipulation software
packages (see the PINPUT, POUTPUT, and VARIABLE statements).
3. State matrices output by Adams/Solver (FORTRAN) in the MATRIXX format are suitable for
being read into a second Adams model with a MATRIX statement. These matrices can form the
definition of a dynamical system defined by an LSE statement in the second Adams model.
7.1 Example 1: Eigenanalysis Application
Consider a model of an inverted pendulum on a sliding cart as shown in Figure 6 below. The listing of
the Adams/Solver (FORTRAN) dataset for this model is shown in Listing 1.
Figure 6
The sliding cart in this model is represented by PART/1 and the inverted pendulum is represented by
PART/2. PART/1 slides along the global x axis in translational joint, JOINT/1, while PART/2 can rotate
about the axis of revolute joint, JOINT/2. PART/1 is connected to ground by a SPRINGDAMPER/1.
TFSISO/1 represents an actuator connected between PART/1 and PART/2. Force generated by this
actuator is applied on the two parts by SFORCE/1. No input is applied to the actuator for the present. To
assess stability of this model, execution of Adams/Solver (FORTRAN) is initiated. Once Adams/Solver
(FORTRAN) verifies that the model data is syntactically correct, issue the SIMULATE/STATIC
command. On achieving static equilibrium, issue the LINEAR/EIGEN command. Eigenvalues reported
by Adams/Solver (FORTRAN) are shown in Table 2 below.
LINEAR 103
Adams/Solver (FORTRAN) Commands
EIGENVALUES
Number
5.00909210E-02
0.00000000E+00
-5.00924580E-02
0.00000000E+00
-3.18309800E+01
0.00000000E+00
-3.17994185E-01
+/- 6.36188992E-01
The table shows that the system has three stable and one unstable mode. To determine the cause of this
instability, use the data produced by Adams/Solver (FORTRAN) (.res, .adm, and so on) in Adams to
display the deformed mode shapes of the model.
Figure 7 (a) and (b) show mode shapes for mode 1, which is unstable, and mode 4, which is stable.
Figure 7
Figure 7 (a) shows that PART/1 is essentially stationary while PART/2 is moving. You can conclude that
PART/2 is the cause of the instability in this model. This is an expected result for this model, since the
inverted pendulum is at an unstable operating point. It is obvious that disturbing the pendulum will cause
it to swing about the revolute joint axis.
As illustrated by this example, viewing mode shapes in a graphical display can provide very significant
insight into the dynamic behavior of the model. In complicated Adams models, this insight is vital in
understanding the model dynamics. In Example 2: State Matrices Output below, based on the state
matrices computed for this model, a feedback control law will be designed to stabilize this model.
104 Adams/Solver
Design and implementation of a control system for an Adams model is described in this example. The
plant model used in this example is identical to the Adams model described in Example 1. The purpose
of the control design exercise is to design a feedback controller to attempt to stabilize the inverted
pendulum Adams model described in Example 1. For control design purposes, the state matrix
representation of the Adams model is required and is generated by the LINEAR/STATEMAT command.
Stabilization of this model requires that PART/2 maintain its inverted vertical position despite external
disturbances applied on it. External disturbances considered here are gravity acting vertically downwards
and an external force applied to the pendulum in the x-direction. On sensing a deviation of the pendulum
from the desired position, the control law determines an appropriate signal to apply to actuator TFSISO/1
to restore PART/2 to its desired position. The control law operates on the basis of measuring output
signals from the plant and then computes a signal to apply to the actuator.
As shown in Figure 8 for the present model, 3 signals are output by the plant. VARIABLE/10 is a
measurement of the relative x displacement between PART/1 and PART/2. VARIABLE/20 is a
measurement of the relative x velocities between the two parts. VARIABLE/30 is the integral of the
relative x displacements between the two parts. These 3 signals are designated as outputs from the plant
by POUTPUT/1.
Input to the plant, that is, input signal to the actuator, is defined as VARIABLE/2. This is designated as
input to the plant by PINPUT/1. Adams/Solver (FORTRAN) implementation of the input/output
structure and the external disturbances is shown in Listing 2: Plant Input/output Specification . This
implementation, when combined with the plant model as shown in dataset 1 in FILE=c results in the openloop model. When the open-loop model is complete, an Adams/Solver (FORTRAN) execution session is
initiated.
Figure 8
Open-Loop Model
The model is read into Adams/Solver (FORTRAN). After Adams/Solver (FORTRAN) verifies the model
data syntax, issue the SIMULATE/STATIC command to determine the equilibrium position. On
achieving the equilibrium position, issue the LINEAR/EIGEN, NOVECTOR command to verify the
eigenvalues of the model. The next table shows the eigenvalues for the open-loop model.
Table 3. Open-Loop Eigenvalues
EIGENVALUES
Number
LINEAR 105
Adams/Solver (FORTRAN) Commands
-2.66440631E-17
0.00000000E+00
5.00909210E-02
0.00000000E+00
-5.00924580E-02
0.00000000E+00
-3.18309800E+01
0.00000000E+00
-3.17994185E-01
+/- 6.36188992E-01
The table shows that the open-loop model has one eigenvalue more than the model in Example 1:
Eigenanalysis Application This is due to the introduction of the relative displacement integrator
TFSISO/2 in the open-loop model. To linearize the model and compute the state matrices, issue the
LINEAR/STATEMAT, PINPUT=1, POUTPUT=1, file=adams.mat command. Adams/Solver
(FORTRAN) linearizes the model and writes the state matrices in the default format to adams.mat file.
Contents of the ADAMS.MAT file are in Listing 3: State Matrices (FSAVE Format) for the Open-Loop
Model. The Adams/Solver (FORTRAN) session then terminates. You may design a controller by reading
the ADAMS.MAT file into the control design package exercising various control design methodologies.
The description of the control design step is beyond the scope of the present document. A text on this
subject or documentation for control design software packages should be consulted for further details.
Now that the feedback control has been designed, it needs to be implemented in Adams/Solver
(FORTRAN) for a closed-loop simulation. The controller designed for this example is a dynamic
compensator. As shown in Figure 4 below, this is implemented in Adams/Solver (FORTRAN) as LSE/1.
The A, B and C matrices associated with this LSE are defined by MATRIX/100, 200, and 300,
respectively. Adams/Solver (FORTRAN) reads the data for these matrices from a file named incomp.dat.
To connect this feedback compensator to the plant model, inputs to LSE/1, ARRAY/303 are connected
to outputs from the plant model. Also, ARRAY/1, which is input to the actuator, TFSISO/1, is now
defined as the output from the compensator, VARIABLE/2. This completes the closed-loop Adams
model. The complete Adams/Solver (FORTRAN) dataset for this model is shown in dataset 3 and dataset
4.
Figure 9
Closed-Loop Model
106 Adams/Solver
To verify and simulate the closed-loop model, an Adams/Solver (FORTRAN) simulation is initiated. The
closed-loop model is first equilibrated in its static position. The eigenvalues for this model are computed
and represented in Table 4 shown next.
Table 4. Closed-Loop Eigenvalues
EIGENVALUES
Number
-5.35233760E-01
0.00000000E+00
-3.18270747E+01
0.00000000E+00
-2.37397000E-01
+/- 7.54488218E-02
-7.37798519E-03
+/- 1.51611302E-01
-5.47796070E-01
+/- 5.12745191E-01
-2.43466412E-01
+/- 5.71313964E-01
-2.46528313E+01
+/- 1.00614794E+01
Table 4 above shows that the closed-loop model is stable. The closed-loop model has more eigenvalues
than the open-loop model. This is due to the dynamical state variables introduced by LSE/1. Eigenvalues
for the closed-loop Adams model can be compared with the closed-loop eigenvalues computed in the
control design package. Now that the stability properties of the closed-loop Adams model have been
verified, it can be simulated to obtain its dynamic response. The time profile of the external disturbance
is as shown in Figure 10. The closed-loop model response to external disturbance is as shown in
LINEAR 107
Adams/Solver (FORTRAN) Commands
Figure 11. As illustrated in this figure, the closed-loop model provides complete disturbance rejection for
displacement of PART/2.
Figure 10
Figure 11
108 Adams/Solver
The input signal applied to the actuator and the force generated by the actuator are shown in Figure 12
and Figure 13, respectively.
Figure 12
Figure 13
The process of control design and simulation is an iterative one. If the closed-loop system does not
perform as expected, the control design specifications may have to be changed and a new controller
designed to achieve better performance.
LINEAR 109
Adams/Solver (FORTRAN) Commands
MATRIXX Format
State matrices output by Adams/Solver (FORTRAN) in the MATRIXX format conforms to the
MATRIXx FSAVE ASCII file specification. These specifications are given in the Xmath Basics Guide,
1996, Integrated Systems Inc., Santa Clara, CA.
More than one matrix may be present in a single file. The Adams/Solver (FORTRAN) state matrices file
can have up to seven matrices. The first four matrices are the A, B, C, and D state matrices. The next
three matrices are STATES, PINPUT, and POUTPUT. The contents and format of these matrices are
explained in Contents of the STATES, PINPUT, and POUTPUT Matrices.
MATLAB Format
State matrices output by Adams/Solver (FORTRAN) in the MATLAB format conform to the ASCII flat
file format. This format requires that all entries in a row of the matrix be written in a single record.
Successive values in a row are separated by a single space. A file is allowed to contain only one matrix.
Therefore, Adams/Solver (FORTRAN) may create up to seven output files, one each for the A, B, C, and
D matrices, one for STATES, one for PINPUT, and one for POUTPUT. The contents and format of the
last three matrices are as shown in Contents of the STATES, PINPUT, and POUTPUT Matrices. The file
name you specify is used as a base name and is appended with the matrix name to write the matrix of the
appropriate type. The file names used for the seven matrices are as given in Table 5 below.
Table 5. File Names Used for MATLAB State Matrices Output
Matrix name
File Name
"base_name" "a"
"base_name" "b"
"base_name" "c"
"base_name" "d"
STATES
"base_name" "st"
PINPUT
"base_name" "pi"
POUTPUT
"base_name" "po"
STATES Matrix
The STATES matrix contains information regarding states that Adams/Solver (FORTRAN) has chosen
for the state matrices representation. For each state, one record exists in this matrix. The following
information is contained in each record:
Type_of_element Element_identifier Element_coordinate
110 Adams/Solver
Type_of_element
Type_of_element can take on the following values:
1. Part coordinates
2. States in a LSE element
3. States in a TFSISO element
4. States in a GSE element
5. Diff variable
6. Coordinate for a PTCV element
7. Coordinates for a CVCV element
8. FLEX_BODY element
9. POINT_MASS element
Element_identifier
Element_identifier is the eight-digit Adams/Solver (FORTRAN) identifier of the element.
Element_coordinate
If Type_of_element=1, the Element_coordinate can take on the values:
1. x-displacement
2. y-displacement
3. z-displacement
7.
8.
9.
10.
x
y
z
12.
11.
For Type_of_element=2 to 5, Element_coordinate is the sequence number in the set of states defining
that element.
For Type_of_element=6, the only permissible value for Element_coordinate is 1, that is, the alpha
parameter value that defines the contact point on the curve.
For Type_of_element=7, Element_coordinate may take on the value of 1 or 2, representing the parameter
values for the first (I) or second (J) curve in a CVCV statement that defines the contact point on the curve.
LINEAR 111
Adams/Solver (FORTRAN) Commands
The first record in the PINPUT/POUTPUT data contains the Adams/Solver (FORTRAN) identifier of the
PINPUT/POUTPUT statement, respectively, that was used on the LINEAR command to generate these
state matrices. Subsequent records contain the Adams/Solver (FORTRAN) identifiers of the VARIABLE
statement identifiers used on these statements. In the MATRIXX as well as the MATLAB format, this
data is organized as a matrix with 1 column and number of rows equal to one plus the number of variables
on the PINPUT or POUTPUT statement.
All data for the STATES, PINPUT, and POUTPUT matrices is written as floating point data.
8. File Listings
Listing 1: Inverted Pendulum Model
ADAMS Inverted pendulum model.
!
pa/99, ground
ma/99,qp=0,0,0, zp =1,0,0
!
! ===> Sliding cart <===
pa/1,ma=10,ip=10,10,10,cm=10
ma/10,qp=5,0,0
ma/11,qp=5,0,2, zp=5,1,2
ma/12,qp=3,-2,-2
ma/13,qp=5,0,0, zp=6,0,0
ma/14,qp=5,0,12
ma/15,qp=12,0,2
!
! ===> Inverted pendulum <===
pa/2,ma=1,cm=20, ip=1,1,1
ma/20,qp=5,0,12
ma/21,qp=5,0,2, zp=5,1,2
ma/22,qp=5,0,12, zp=5,1,12
!
!
!
!
CM marker.
revolute joint marker.
graphics marker.
translational joint marker.
! CM marker.
! revolute joint marker.
! graphics marker.
112 Adams/Solver
ma/23,qp=5,0,7
! actutator attachment point
ma/24,qp=5,0,2, zp=5,0,3
! graphics marker.
!
joint/1,tran,i=13,j=99
joint/2,rev,i=11,j=21
!
! ===> Spring damper between cart and ground <===
springdamper/1,tran,i=99,j=13,k=200,c=40,l=5
!
gra/2, circle,cm=20, r=1.5,seg=20
gra/3, circle,cm=22, r=1.5,seg=20
gra/4, cylind,cm=24, l=8.5, r=0.25,seg=10,side=10
gra/5, box, corn=12, x=9, y=4, z=4
!
! ===> External disturbance <===
sforce/1001, i=20, j=99, action, tran,
,fun=step(time,0,0,.5,10)-step(time,1,0,1.5,10)
!
! ===>Actuator Dynamics<===
tfsiso/1,num=10, den=1,0.005
,u=1,x=2,y=3
array/1,u,var=2
! input signal to actuator
array/2,x
! actuator state
array/3,y
! force generated by actuator.
!
! ===>Actuator force<===
sforce/1,i=15,j=23, trans,
,function=aryval(3,1)
!
! ===>Input to Actuator<===
vari/2,fun=0
!
accgrav/kg=-1
result/format
!
end
Listing 2: Plant Input/output Specification
! ===> PLANT INPUT/OUTPUT definition <===
!
------------------!
var/1,fun=dx(20,14)
Displacement integrator
tfsiso/2, num=1, den=0,1
,u=20,x=21,y=22
array/20, U, VAR=1
array/21, X
array/22, Y
!
! ===> Outputs <===
vari/10, function= varval(1)
!
displacement
vari/20, function= vx(20,14)
!
velocity
vari/30, function= aryval(22,1)
!
displ. integrated
LINEAR 113
Adams/Solver (FORTRAN) Commands
!
!
! ===> Plant input designation <===
pinput/1,var=2
!
! ===> Plant output designation <===
poutput/1,var=10,20,30
!
A
6
6B
6
1C
3
6D
3 1
STATES
3
6PINPUT
2
1POUTPUT
4
1
A
6
6
0(3(1PE25.17))
-3.99604352126607320E+00 1.00000000000000000E+00 -3.95647873392680550E-02
0.00000000000000000E+00 0.00000000000000000E+00 0.00000000000000000E+00
-1.99703264094955490E+01 0.00000000000000000E+00 -2.96735905044510420E-01
0.00000000000000000E+00 0.00000000000000000E+00 -9.99999999962142390E-01
0.00000000000000000E+00 0.00000000000000000E+00 0.00000000000000000E+00
1.00000000000000000E+00 0.00000000000000000E+00 0.00000000000000000E+00
-9.89119683481701380E-03 0.00000000000000000E+00 9.89119683481701210E-02
0.00000000000000000E+00 0.00000000000000000E+00 9.99999999962142390E-01
4.02439896739235910E-02 0.00000000000000000E+00 -4.02439896739235860E-01
0.00000000000000000E+00 -2.00000000000000000E+02 0.00000000000000000E+00
0.00000000000000000E+00 0.00000000000000000E+00 0.00000000000000000E+00
0.00000000000000000E+00 0.00000000000000000E+00 0.00000000000000000E+00
B
6
1
0(3(1PE25.17)
0.00000000000000000E+00 0.00000000000000000E+00 0.00000000000000000E+00
0.00000000000000000E+00 2.00000000000000000E+03 0.00000000000000000E+00
C
3
6
0(3(1PE25.17))
0.00000000000000000E+00 -1.00000000000000000E+00 0.00000000000000000E+00
-9.99999999962142390E-01 0.00000000000000000E+00 0.00000000000000000E+00
0.00000000000000000E+00 1.00000000000000000E+00 0.00000000000000000E+00
9.99999999962142390E-01 0.00000000000000000E+00 0.00000000000000000E+00
0.00000000000000000E+00 0.00000000000000000E+00 0.00000000000000000E+00
0.00000000000000000E+00 0.00000000000000000E+00 1.00000000000000000E+00
D
3
1
0(3(1PE25.17))
0.00000000000000000E+00 0.00000000000000000E+00 0.00000000000000000E+00
STATES
3
6
0(3(1PE25.17))
1.00000000000000000E+00 1.00000000000000000E+00 7.00000000000000000E+00
1.00000000000000000E+00 1.00000000000000000E+00 1.00000000000000000E+00
1.00000000000000000E+00 2.00000000000000000E+00 7.00000000000000000E+00
1.00000000000000000E+00 2.00000000000000000E+00 1.00000000000000000E+00
3.00000000000000000E+00 1.00000000000000000E+00 1.00000000000000000E+00
3.00000000000000000E+00 2.00000000000000000E+00 1.00000000000000000E+00
PINPUT
2
1
0(3(1PE25.17))
1.00000000000000000E+00 2.00000000000000000E+00
POUTPUT
4
1
0(3(1PE25.17))
1.00000000000000000E+00 1.00000000000000000E+01 2.00000000000000000E+01
3.00000000000000000E+01
114 Adams/Solver
pa/99, ground
ma/99,qp=0,0,0, zp =1,0,0
!
! ===> Sliding cart <===
pa/1,ma=10,ip=10,10,10,cm=10
ma/10,qp=5,0,0
! CM marker.
ma/11,qp=5,0,2, zp=5,1,2
! revolute joint marker.
ma/12,qp=3,-2,-2
! graphics marker.
ma/13,qp=5,0,0, zp=6,0,0
! translational joint marker.
ma/14,qp=5,0,12
ma/15,qp=12,0,2
! actutator attachment point
!
! ===> Inverted pendulum <===
pa/2,ma=1,cm=20, ip=1,1,1
ma/20,qp=5,0,12
! CM marker.
ma/21,qp=5,0,2, zp=5,1,2
! revolute joint marker.
ma/22,qp=5,0,12, zp=5,1,12
! graphics marker.
ma/23,qp=5,0,7
! actutator attachment point
ma/24,qp=5,0,2, zp=5,0,3
! graphics marker.
!
joint/1,tran,i=13,j=99
joint/2,rev,i=11,j=21
!
! ===> Spring damper between cart and ground <===
springdamper/1,tran,i=99,j=13,k=200,c=40,l=5
!
gra/2, circle,cm=20, r=2,seg=10
gra/3, circle,cm=22, r=2,seg=10
gra/4, cylind,cm=24, l=8, r=0.5,seg=10,side=10
gra/5, box, corn=12, x=9, y=4, z=4
!
! ===> External disturbance <===
sforce/1001, i=20, j=99, action, tran,
,fun=step(time,0,0,.5,10)-step(time,1,0,1.5,10)
!
! ===>Actuator Dynamics<===
tfsiso/1,num=10, den=1,0.005
,u=1,x=2,y=3
array/1,u,var=2
! input signal to actuator
array/2,x
! actuator state
array/3,y
! force generated by actuator.
!
! ===>Actuator force<===
sforce/1,i=15,j=23, trans,
,function=aryval(3,1)
!
!
! ===> PLANT INPUT/OUTPUT definition <===
!
------------------!
var/1,fun=dx(20,14)
Displacement integrator
tfsiso/2, num=1, den=0,1
,u=20,x=21,y=22
array/20, u, var=1
array/21, x
array/22, y
!
! ===> Outputs <===
vari/10, function= varval(1)
!
displacement
LINEAR 115
Adams/Solver (FORTRAN) Commands
9.98460749273361898E+01
-1.78574044858736743E+04
1.01587769607181722E+00
-1.69576019090885748E+04
-9.98470640470196713E+01
1.79036593612407414E+04
-1.02576889290663420E+00
1.74318979368853470E+04
-1.23564688768258060E-01
2.82840625758381648E+04
-4.02439896739235858E-01
-2.09248210623341492E+02
1.12468086129738198E+00
-9.30005800767228163E-01
9.98470640470196713E+01
-1.36246052474731605E+04
1.23564688768258060E-01
2.08671855656208993E-01
116 Adams/Solver
LSOLVER 117
Adams/Solver (FORTRAN) Commands
LSOLVER
The LSOLVER command allows the user to change the linear solver used by the Adams/Solver
(FORTRAN). The linear solver is invoked multiple times throughout the simulation to compute
corrections in the system state.
Format
Arguments
CALAHAN
HARWELL
Tip:
The CALAHAN and HARWELL solvers use somewhat different strategies for picking
pivots during the linear solution. If one solver is experiencing difficulties solving an illconditioned model, you may try the other solver. One may work better on a particular
model than the other.
Caution:
Even though you deactivate all your redundant constraints, Adams/Solver (FORTRAN)
does not allow you to use the Calahan solver. If (under these circumstances) you issue the
LSOLVER/CALAHAN command, Adams/Solver (FORTRAN) returns the message:
Changing to the CALAHAN solver is not allowed for this model due to the presence of
redundant constraints.
To avoid this problem, deactivate all your redundant constraints, run a short simulation,
and then issue the LSOLVER/CALAHAN command.
118 Adams/Solver
MARKER
The MARKER command moves and/or reorients an existing fixed Adams/Solver (FORTRAN) marker.
(See the MARKER statement for more information). You may also list information about the position of
the marker.
Format
Arguments
LIST
Lists the current values of the MARKER data. The data is with respect to the body
coordinate system (BCS) coordinates.
QP=x,y,z
Redefines the the x-, y-, and z-coordinates of the origin of the MARKER with respect
to the PART on which it lies. The coordinates are specified in the body coordinate
system (BCS) of the element to which it belongs.
REULER=a,b,c Redefines the three-dimensional spatial orientation of the marker axes relative to the
axes of the BCS. The a, b, and c values represent a set of body-fixed 3-1-3 Euler angles
expressed in radians. These angles can be interpreted as follows:
To orient a marker, first align the marker axes identically to the BCS axes.
Perform a right-handed rotation of the marker x- and y-axes by a radians
x-axis.
Perform a right-handed rotation of the x- and y-axes of the marker by c
MARKER 119
Adams/Solver (FORTRAN) Commands
RM=id
Redefines a reference marker on the same part with respect to which Adams/Solver
(FORTRAN) interprets QP, XP, ZP, and REULER.
USEXP
When using the x-point-z-point method of orientation, USEXP causes the marker to
be oriented with the x-axis lying on XP and ZP lying in the positive x-z plane. This is
useful to orient markers for use in BEAM statements. See Examples of using the ZP,
XP and USEXP.
XP=x,y,z
By default, redefines the BCS coordinates of any point in the positive x-z plane of the
marker, but not on the z-axis of the marker. A point on the positive x-axis may be the
most convenient. When used with USEXP, XP defines the BCS coordinates of any
point on the positive x-axis of the marker. See Examples of using the ZP, XP and
USEXP.
ZP=x,y,z
By default, redefines the BCS coordinates of any point in the positive z-axis of the
marker. When used with USEXP, ZP defines the BCS coordinates of any point in the
positive x-z plane of the marker, but not on the x-axis of the marker.See Examples of
using the ZP, XP and USEXP.
Extended Definition
The MARKER command allows you to reposition and/or reorient a fixed marker with respect to the body
coordinate system (BCS) of the element to which the marker is attached, or to another nonfloating marker
on the same element. You may use any of the standard Adams/Solver (FORTRAN) methods to specify
the location and orientation of the marker. Floating markers may not be moved, but their current
information may be listed. For more information on BCS, see Coordinate Systems and Local Versus
Global Geometric Data.
After a change to a MARKER, Adams/Solver (FORTRAN) reprocesses the model at the next
SIMULATE command, as if it had just been read in from the dataset. During the reprocessing,
Adams/Solver (FORTRAN) checks the entire model for consistency, reinitializes user subroutines, and
recomputes initial conditions.
While checking, Adams/Solver (FORTRAN) verifies that the model is still valid with the new MARKER
positions. If a JOINT is now misaligned, for instance, Adams/Solver (FORTRAN) issues a warning or
error.
Adams/Solver (FORTRAN) also reinitializes user subroutines to re-establish functional dependencies.
For each element that refers to a user-written subroutine, Adams/Solver (FORTRAN) calls the userwritten subroutine with IFLAG set to true.
Prior to the actual simulation, Adams/Solver (FORTRAN) computes initial conditions for the model. If
this is the first simulation, Adams/Solver (FORTRAN) begins with the positions and velocities specified
in the dataset. If you have run a previous simulation, Adams/Solver (FORTRAN) begins with the final
displacements and velocities. Adams/Solver (FORTRAN) then adjusts the initial conditions to ensure
that they are consistent with the model constraints. If this is the first simulation, Adams/Solver
(FORTRAN) also maintains any user supplied joint initial-conditions and positions specified as EXACT.
120 Adams/Solver
If you change a MARKER in the middle of a simulation, by default Adams/Solver (FORTRAN) splits
the tabular, request, graphics, and results output into two separate sets of output concatenated together.
This ensures that the output correctly reflects the new system geometry.
The OUTPUT/NOSEPARATOR argument prevents Adams/Solver (FORTRAN) from splitting the file.
This allows you to plot or animate the output continuously from beginning to end, but may result in
misleading graphics during postprocessing. See the OUTPUT statement for more information on the
NOSEPARATOR argument.
Tip:
Caution:
You can use the QP argument to translate the marker while maintaining the existing
orientation. If you use only the REULER argument, Adams/Solver (FORTRAN) reorients
the marker while maintaining the existing position.
When reorienting a marker, you should completely specify the necessary
another. You should ensure that the RM marker is on the same part as the marker
being moved.
When you change a marker, Adams/Solver (FORTRAN) updates all elements that
depend upon that marker. Moving a marker may have subtle effects since many
Adams/Solver (FORTRAN) elements rely on them. Be careful when moving
markers not to cause unintended side effects (for example, moving both a joint and
force that share a common marker).
Examples
MARKER/10,REULER=15D,0,0
This MARKER command repositions/reorients Marker 18 so that it has the same location and orientation
as Marker 8.
MARKER 121
Adams/Solver (FORTRAN) Commands
122 Adams/Solver
MENU
The MENU command lists all of the Adams/Solver (FORTRAN) interactive commands. As you progress
through the menu, Adams/Solver (FORTRAN) repeatedly issues the prompt, More?. To respond, you
should enter an upper- or lower-case y or yes or press RETURN to view more about the commands. To
get another Enter Command prompt, you should enter an upper- or lower-case n or no. Adams/Solver
(FORTRAN) does not prompt, More?, if the MENU command comes from a command file.
Format
MENU
See other Information available.
MOTION 123
Adams/Solver (FORTRAN) Commands
MOTION
The MOTION command redefines and/or lists the characteristics of a MOTION statement which
specifies a system degree of freedom as an explicitly function of time. For more information, see the
MOTION statement.
Format
Arguments
ACCELERATION
B1
Respecifies the first angle of the Body 1-2-3 Euler angle sequence
as a function of time.
Range: None
B2
124 Adams/Solver
B3
DISPLACEMENT
FUNCTION =
USER ( r 1 [ ,, r 30 ] )
ICDISP
ICVEL
I=id, J=id
JOINT
LIST
ROTATION
ROUTINE=libname::subname
TRANSLATION
VELOCITY
MOTION 125
Adams/Solver (FORTRAN) Commands
The MOTION command allows you to list or modify the characteristics of an existing MOTION
statement. You can change the motion definition, change the joint to which the motion is being applied,
and/or change the type of motion on a cylindrical joint.
After a change to a MOTION, Adams/Solver (FORTRAN) reprocesses the model at the next SIMULATE
command, as if it had just been read in from the dataset. During the reprocessing, Adams/Solver
(FORTRAN) checks the entire model for consistency, reinitializes user subroutines, and recomputes
initial conditions.
While checking, Adams/Solver (FORTRAN) verifies that the model is still valid with the new MOTION.
If, for example, the new MOTION conflicts with another MOTION at the same joint, Adams/Solver
(FORTRAN) issues an error.
Adams/Solver (FORTRAN) also reinitializes user subroutines to re-establish functional dependencies.
For each element that refers to a user-written subroutine, Adams/Solver (FORTRAN) calls the userwritten subroutine with IFLAG set to true.
Prior to the actual simulation, Adams/Solver (FORTRAN) computes initial conditions for the model. If
this is the first simulation, Adams/Solver (FORTRAN) begins with the positions and velocities specified
in the dataset. If you ran a previous simulation, Adams/Solver (FORTRAN) begins with the final
displacements and velocities. Adams/Solver (FORTRAN) then adjusts the initial conditions to ensure
that they are consistent with the model constraints. If this is the first simulation, Adams/Solver
(FORTRAN) also maintains any user-supplied joint initial-conditions and part positions specified as
EXACT.
If you change a MOTION joint or type in the middle of a simulation, by default Adams/Solver
(FORTRAN) splits the tabular, request, graphics, and results output into two separate sets of output
concatenated together with different headers. This ensures that the output correctly reflects the new
system topology. Adams/Solver (FORTRAN) does not split the files if you change only the MOTION
function expression.
The OUTPUT/NOSEPARATOR argument prevents Adams/Solver (FORTRAN) from splitting the file.
This allows you to plot or animate the output continuously from beginning to end, but may result in
126 Adams/Solver
misleading graphics during postprocessing. See the OUTPUT statement for more information on the
NOSEPARATOR argument.
Caution:
Examples
MOTION/3,JOINT=21
This MOTION command specifies, as a function of time, the translation or rotation for Motion 11.
See other Constraints available.
OUTPUT 127
Adams/Solver (FORTRAN) Commands
OUTPUT
The OUTPUT command redefines and/or lists the data for an OUTPUT statement.
Format
Arguments
Respecifies that output accelerations less than r in magnitude are to be set equal to
zero. The value of r must be greater than zero. The value of r defaults to 1.0E-7 for
output in scientific notation and to 0.001 for output in fixed-point notation.
CHART
Reproduces x-y charts of the request data for the Tabular Output file.
128 Adams/Solver
Respecifies that output displacements less than r in magnitude are to be set equal to
zero. The value of r must be greater than zero. The value of r defaults to 1.0E-7 for
output in scientific notation and to 0.001 for output in fixed-point notation.
FIXED
Reformats numerical output in fixed-point notation. Any values that are too small or
too large for fixed-point notation are output in scientific notation.
FSCALE=r1[,r2]
FZERO
Respecifies that output forces less than r in magnitude are to be set equal to zero. The
value of r must be greater than zero. The value of r defaults to 1.0E-7 for output in
scientific notation and to 0.001 for output in fixed-point notation.
GRSAVE
Resaves graphics output in the Graphics file so that you can use a postprocessor to
display graphics.
LIST
NOCHART
Stops producing x-y charts of the request data for the Tabular
Output file.
NOFIXED
NOGRSAVE
NOOSFORMAT
Stops writing output-step-request tables to the Tabular Output file during a dynamic,
kinematic, or quasi-static equilibrium analysis. If you specify OSFORMAT,
Adams/Solver (FORTRAN) outputs an output-step-request table at each output time
step. Whether you specify NOOSFORMAT or OSFORMAT, Adams/Solver
(FORTRAN) always outputs an output step request table when a static equilibrium
analysis is requested.
NOPRINT
NOREQSAVE
OUTPUT 129
Adams/Solver (FORTRAN) Commands
NOSEPARATOR Respecifies that Adams/Solver (FORTRAN) is not to write separators to the request,
graphics, results, and tabular output files when you modify the model topology in the
middle of a simulation. You can change the model topology by using interactive
commands to activate an element, deactivate an element, change a marker position,
or change the type or point of application of a force or constraint during a simulation.
When this happens, by default Adams/Solver (FORTRAN) writes a separator and
new header to the request, graphics, results, and tabular output files. Adams/Solver
(FORTRAN) then writes subsequent simulation output after the new headers. This
ensures that the changes are correctly reflected in the output files, but it creates two
sets of output that cannot be plotted or animated continuously. The NOSEPARATOR
argument prevents Adams/Solver (FORTRAN) from breaking up the files by
creating a continuous set of output that can be plotted and animated from beginning
to end.
Note:
This output may be misleading because the Graphics file does not include
the effects of any changes in marker, force, or constraint positions during
the simulation. While the part motions are correct, the force, joint, and
marker graphics remain in their original positions, even if you move them
during the simulation.
NOTELETYPE
NOYPR
Restarts outputting rotational values in psi, theta, and phi coordinates, rather than in
yaw, pitch, and roll coordinates. If during the course of a simulation this argument is
used on an OUTPUT command after using the YPR argument on the OUTPUT
command/statement, the output is part in yaw, pitch, and roll coordinates and part in
psi, theta, and phi coordinates. Output in mixed coordinates is confusing and is not
recommended.
OSFORMAT
Rewrites output-step-request (OS) tables to the tabular output file immediately after
completion of each output step for dynamic, kinematic, or quasi-static equilibrium
simulation. If OSFORMAT is specified, Adams/Solver (FORTRAN) outputs an OS
table at each output time step during simulation. When a static equilibrium analysis
is requested, Adams/Solver (FORTRAN) always outputs an OS table whether
NOOSFORMAT or OSFORMAT is specified. Use OSFORMAT to view the values
of all requests at a particular output time or to provide printed output in cases where
the simulation might not run to completion. A simulation may not run to completion
because the model or user-written subroutines are not fully debugged. OSFORMAT
might provide information useful in debugging the model or the user-written
subroutines.
Reprints time-response-request tables (one table for each request) in the tabular
output file after the simulation is complete. Time-response-request tables list all of
the values for a single request. There is one line in the table for each output time step;
the lines are in ascending order of time.
130 Adams/Solver
REQSAVE
Resaves the request output in the Request file so you can use a postprocessor to
display x-y plots.
SEPARATOR
TELETYPE
VSCALE=r1[,r2] Rescales the translational and the rotational velocities Adams/Solver (FORTRAN)
outputs. Define r1 to scale the translational velocities, and define r2 to scale the
rotational velocities. Both r1 and r2 default to 1.0.
VZERO
Respecifies that output velocities less than VZERO in magnitude are to be set equal
to zero. The value of r must be greater than zero. The value of r defaults to 1.0E-7
for output in scientific notation and to 0.001 for output in fixed-point notation.
YPR
Outputs rotational values in yaw, pitch, and roll coordinates, rather than in psi, theta,
and phi coordinates (Euler angles). NOYPR is the default. If during the course of a
simulation this argument is used on an OUTPUT command after using an OUTPUT
command/statement without the YPR argument or after using an OUTPUT
command with the NOYPR argument, the output is part in psi, theta, and phi
coordinates and part in yaw, pitch, and roll coordinates.
Extended Definition
Like the OUTPUT statement, the OUTPUT command controls the generation of the request file and
graphics file, in addition to the form, format, coordinates, filtering, and scaling of request data in the
tabular output file.
Forms of Request Data in the Tabular Output File
X-y charts of the request data for the tabular output file - The output is in the same order as the
requests are in the dataset. The information about each request (including those created by an
MREQUEST command/statement) is in two parts.The left side of the first part contains a table of
simulation time and the translational information output by the request, and the right side
contains a plot of the translational information against time. The left side of the second part
contains a table of simulation time and the rotational information output by the request, and the
right side contains a plot of the rotational information against time. (The column titles can vary
according to the type of request information and other arguments on the OUTPUT
command/statement.)
These plots differ in two important ways from plots created with Adams/Solver (FORTRAN) or
most postprocessors. First, time is along the vertical axis in the chart plots and request data is
OUTPUT 131
Adams/Solver (FORTRAN) Commands
along the horizontal axis. Second, the chart plots are normalized; that is, each curve is scaled
independently of the others from the highest value to the lowest value for that curve. Therefore,
use care when comparing curves to one another. You can compare the shapes but not the
magnitudes of the curves.
Time-response-request tables - A time-response-request table lists all values for a single request
throughout the simulation. There is one line in the table for each output time step; the lines are in
ascending order of time.
Output-step-request (OS) table An OS table lists the values of all requests at each output time
step. There is a line for each output time step, followed by one line for each request.
Forms of Request Data in the Tabular Output File
Columns per line
72 columns
132 columns
Numerical notation of request data in the Tabular Output file
Fixed-point - Fixed-point notation expresses a decimal or an integer number without an
exponent.
Scientific - Scientific notation expresses a number as a value between 1 and 10 (the mantissa)
132 Adams/Solver
Caution:
argument because the OSFORMAT argument prints records 132 characters wide
and because CHART prints information next to a plot.
The ICSAVE and NOICSAVE arguments and the .icf file have been discontinued.
PART 133
Adams/Solver (FORTRAN) Commands
PART
The PART command redefines and/or lists the data for a PART statement. Although you cannot redefine
the center-of-mass marker, the inertia marker, the part orientation, or the part initial conditions, you can
redefine the part mass and the part principal moments of inertia about the x-, y-, and z-axis of the
principal axis coordinate system.
Format
IP=xx,yy,zz
Respecifies the principal moments of inertia about the x-axis, the y-axis, and the z-axis
of the principal axis coordinate system.
LIST
MASS=r
Caution:
products of inertia (that is, xy, xz, and yz) and/or if the PART statement defines an
inertia marker (IM) different from the center-of-mass marker (CM). This is
because the IP argument values (xx, yy, and zz) are with respect to the part principal
axis coordinate system. The principal axes of a part are the coordinate axes about
which mass moments are zero, that is, for which the inertia matrix is diagonal.
Part velocities do not change if you use the PART command to alter the mass or the
This PART command respecifies the principal moments of inertia of Part 5 about the x-, y-, and z-axis of
the principal axis coordinate system and lists all the data for Part 5.
134 Adams/Solver
PLOT
The PLOT command plots the REQUEST and MREQUEST statement output from the current dataset
execution.
Format
PLOT 135
Adams/Solver (FORTRAN) Commands
Arguments
DEGREES
POINTS=i
Specifies the increment to be used to plot the data. For example, POINTS=2
plots every second point.
RADIANS
TMIN=r,TMAX=r
136 Adams/Solver
XMIN=r,XMAX=r
YMIN=r,YMAX=r
Tip:
To see a list of all REQUEST statement identifiers (including those written by the
may be the result of an Euler singularity. To avoid the Euler singularity (and thus
the spikes), add the Adams/Solver (FORTRAN) OUTPUT statement with the YPR
(yaw-pitch-roll) argument to the Adams/Solver (FORTRAN) dataset and rerun the
simulation. Alternatively, issue the OUTPUT command with the YPR argument
before the SIMULATE command is issued. When the new results are plotted, they
should not have the spurious spikes. Note that yaw-pitch-roll angles may also
display singularities. If display singularities appear, however, they are in different
positions than the Euler singularities.
Caution:
When the character string TIME is used to specify that you want to plot the output time
steps, do not indicate a REQUEST statement identifier. The output time steps are the same
for all the REQUEST statements in an Adams/Solver (FORTRAN) dataset.
Examples
PLOT XAXIS=TIME:X 10, YAXIS=MAG 1:AMAG 2, POINTS=3 D
This command plots the magnitude of Request 1 against the output time steps and plots the angular
magnitude of Request 2 against the x component of Request 10. It plots every third output point and plots
angular values in degrees.
See other Display available.
PREFERENCES 137
Adams/Solver (FORTRAN) Commands
PREFERENCES
The PREFERENCES command controls general options that apply to the model defined in the
Adams/Solver (FORTRAN) dataset or the commands defined in the Adams/Solver (FORTRAN)
command file.
Format
138 Adams/Solver
Arguments
STOPCF
SIMFAIL =
NOSTOPCF
PREFERENCES 139
Adams/Solver (FORTRAN) Commands
CXX
SOLVERBIAS = F77
NONE
LIST
Examples
140 Adams/Solver
RELOAD
The RELOAD command restarts a simulation from a previously saved model or simulation state.
Format
Arguments
FILE=c
Specifies the complete name of a file you created with the SAVE command.
The file name may include the directory on operating systems that support path
names, such as UNIX. There is no default extension for this file. Because the
FILE argument and value can be at most eighty characters long, the file name
and path name are limited from seventy-five characters (if you do not
abbreviate FILE=) to seventy-six characters (if you abbreviate FILE= to FIL=).
Range: All printable characters except !, ;, , and &
OUTPUT_PREFIX=c Optionally specifies a new base (root) name for output files (.req, .res, .gra,
.out, and so on) from simulations which follow this RELOAD command. If you
do not specify the OUTPUT_PREFIX argument, Adams/Solver (FORTRAN)
appends the output to the currently-open output files after writing a special
delimiter line into the file. Because the OUTPUT_PREFIX argument and value
can be at most eighty characters long, the basename and path are limited from
sixty-six characters (if you do not abbreviate OUTPUT_PREFIX) to seventysix characters (if you abbreviate OUTPUT_PREFIX to OUT=).
Range: All printable characters except !, ;, , and &
STATES
RELOAD 141
Adams/Solver (FORTRAN) Commands
SYSTEM
TITLE=c
Optionally specifies a new title for the model in output from simulations which
follow this RELOAD command. The title string may not contain any special
Adams/Solver (FORTRAN) characters and must fit on a single line (no
continuations). If not the last argument, the title is terminated by the last nonblank prior to the following comma. Because the TITLE argument and value
can be at most eighty characters long, the file name and path name are limited
from seventy-four characters (if you do not abbreviate TITLE=) to seventy-six
characters (if you abbreviate TITLE= to TIT=).
Range: All printable characters except !, ;, , and &
Extended Definition
Using the RELOAD command with the STATES argument allows you to reload the saved simulation
time and state values, including displacements, velocities, force values, and user-defined variable values.
Adams/Solver (FORTRAN) resets the simulation time to the saved values, and uses the saved states as
initial conditions for the next simulation.
Using the RELOAD command with the SYSTEM argument allows you to reload the entire saved system,
including the model definition (parts, markers, joints, and so on), simulation time and state values
(displacements, velocities, force values, user-defined variable values, and so on) and solver data
(integrator parameters, state derivatives, etc.). Adams/Solver (FORTRAN) completely resets all model,
simulation, and solver data to that stored in the file. Except for interactive plotting, Adams/Solver
(FORTRAN) responds to subsequent commands just as it would have at the time the file was saved.
(Since past simulation results are not stored in the Save file, they cannot be plotted when the file is
restored.)
Tip:
Except for the leading delimiter line, the appended sections of the output files are complete
(that is, they may be extracted with any editor, renamed, and handled like any other
Adams/Solver (FORTRAN) output).
142 Adams/Solver
Caution:
Files are saved in a machine- and code-dependent binary format. They are not
This RELOAD command reloads the model and simulation states saved in file TCT1.SAV. Adams/Solver
(FORTRAN) appends subsequent output to the currently open output files with the new title TEST#2.
RELOAD/STATES,FILE=BASE.SAV,OUTPUT_PREFIX=RUN2
This RELOAD command reloads the simulation states saved in file BASE.SAV. Adams/Solver
(FORTRAN) creates a new set of output files RUN2.REQ, RUN2.GRA, and so on.
The SAVE and RELOAD commands can help simulate several versions of the same model when used
with other interactive Adams/Solver (FORTRAN) commands. SAVE/SYSTEM creates a baseline
configuration that you can then reload and simulate repeatedly without leaving Adams/Solver
(FORTRAN). After each RELOAD/SYSTEM, you may modify the model, and use the ACTIVATE and
DEACTIVATE commands to switch sets of loads on and off, for example.
The following command file uses the SAVE/SYSTEM and RELOAD/SYSTEM commands to run three
simulations from the same input file, creating three sets of output files: case1, case2, and case3. The
command file loads example.adm, the original model, that contains three sets of forces. After
deactivating all the forces and performing a static solution, the SAVE command saves the whole system.
ACTIVATE commands then turn on one set of forces at a time.
Between simulations, the RELOAD command restores the saved version of the model. Reloading the
save file returns the model to the conditions at the time of the save. In this case, the saved version of the
model is at static equilibrium with all the forces inactive.
example
case1
dea/sfo,id=101,102,201,202,301
,302
sim/static
save/system, file=ex.sav
act/sfo, id=101,102
!Simulate
RELOAD 143
Adams/Solver (FORTRAN) Commands
rel/system, file=ex.sav,
out=case2
act/sfo, id=201,202
! Simulate
rel/system, file=ex.sav,
out=case3
act/sfo, id=301,302
! Simulate
stop
144 Adams/Solver
REQUEST
The REQUEST command redefines and/or lists the data for a REQUEST statement, and/or redefines the
function expressions for a REQUEST statement.
Format
Arguments
F1=e
Redefines the first component of the request that is being specified. If the
F1 argument is used, it must either be the last argument in the REQUEST
statement or be followed by a backslash (\) (not a comma). Adams/Solver
(FORTRAN) writes the expression value to the corresponding column of
the tabular output file, but not to the request file.
F2=e
F3=e
Redefines the third 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). Adams/Solver
(FORTRAN) writes the expression value to the corresponding column of
the tabular output file and to the request file.
REQUEST 145
Adams/Solver (FORTRAN) Commands
F4=e
Redefines the fourth 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). Adams/Solver
(FORTRAN) writes the expression value to the corresponding column of
the tabular output file and to the request file.
F5=e
Redefines the fifth component of the request that is being specified. If the
F5 argument is used, it must either be the last argument in the REQUEST
statement or be followed by a backslash (\) (not a comma). Adams/Solver
(FORTRAN) writes the expression value to the corresponding column of
the tabular output file, but not to the request file.
F6=e
Redefines the sixth component of the request that is being specified. If the
F6 argument is used, it must either be the last argument in the REQUEST
statement or be followed by a backslash (\) (not a comma). Adams/Solver
(FORTRAN) writes the expression value to the corresponding column of
the tabular output file and to the request file.
F7=e
F8=e
Redefines the eighth 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
(FORTRAN) writes the expression value to the corresponding column of
the tabular output file and to the request file.
ROUTINE=libname::sub Specifies an alternative library and name for the user subroutine REQSUB.
name
Learn more about the ROUTINE Argument.
Examples
REQUEST/21, F4=DX(2110, 409)/F8=DX(2115, 409)
This REQUEST command changes the fourth and eighth expressions for REQUEST/21. The other
function expressions remain as they were.
146 Adams/Solver
RETURN 147
Adams/Solver (FORTRAN) Commands
RETURN
The RETURN command indicates that you do not want to enter more graphics commands at this time
and that you want execution to continue. Entering this command has the same effect as pressing the
RETURN key in response to a prompt. This command is only necessary when Adams/Solver
(FORTRAN) is in graphics mode (see the EXECUTION command) and is set to pause after each graphic
display (see the SET command).
Format
RETURN
Tip:
In most cases, it is more efficient to press the RETURN key than it is to type RETURN;
however, some computers do not accept the RETURN key alone in response to a prompt.
148 Adams/Solver
SAVE
The SAVE command stores the current Adams/Solver (FORTRAN) model and simulation conditions or
only the current simulation states. This allows you to return to the model or states at a later time using
the RELOAD command.
Format
Arguments
AUTOSAVE=i
FILE=C
Specifies the complete file name where Adams/Solver (FORTRAN) writes the
SAVE command information. The file name may include the directory on
operating systems that support such path names, such as UNIX. There is no
default extension for this file.
Range: All printable characters except !, ;, , and &
STATES
SYSTEM
Extended Definition
You can use the SAVE command with the STATES argument to save the current simulation time and state
values, including displacements, velocities, force values, and user-defined variable values. You can later
SAVE 149
Adams/Solver (FORTRAN) Commands
restart a simulation from this point by reloading the states with the RELOAD/STATES command. When
you reload this file, Adams/Solver (FORTRAN) resets the simulation time to the saved value and uses
the saved states as initial conditions for the next simulation.
You may use the SAVE command with the SYSTEM argument to save the entire current system,
including the model definition (parts, markers, joints, and so on), simulation time and state values
(displacements, velocities, force values, user-defined variable values, and so on), and solver data
(integrator parameters, state derivatives, and so on). SAVE/SYSTEM creates a complete record of the
current model and simulation conditions. You can later return to this point by reloading the conditions
using the RELOAD/SYSTEM command.
When you reload a system file, Adams/Solver (FORTRAN) completely resets all model, simulation, and
solver data to that stored in the file. Except for interactive plotting, Adams/Solver (FORTRAN) responds
to subsequent commands just as it would have at the time the file was saved. (Since past simulation
results are not stored in the save file, they cannot be plotted when the file is restored.)
Tip:
Caution:
You can use the AUTOSAVE=i argument feature to checkpoint a difficult simulation at
the specified interval. If the simulation fails, you can debug it by restarting the simulation
from the last saved step. This is very similar to the OUTPUT/ICSAVE-EXEC/ICSTART
capability which the SAVE/RELOAD command now supersedes.
The AUTOSAVE=i argument function continually overwrites the information in
the specified file. Therefore, this file contains only one set of states. For multiple
files, you need to specify multiple times with different file names with the SAVE
command.
Files are saved in a machine- and code-dependent binary format. They are not
This SAVE command saves the current model and simulation information in file BASE1SAV. When this
file is reloaded with the RELOAD command, Adams/Solver (FORTRAN) returns to this exact
configuration.
SAVE/STATES,AUTOSAVE=10,FILE=AS.SAV
150 Adams/Solver
This SAVE command saves the simulation states in file AS.SAV at every tenth output step. When this
file is reloaded, Adams/Solver (FORTRAN) resets the current model with the saved states.
Used with other interactive Adams/Solver (FORTRAN) commands, SAVE and RELOAD can help
simulate several versions of the same model. SAVE/SYSTEM creates a baseline configuration which you
can then reload and simulate repeatedly without leaving Adams/Solver (FORTRAN). After each
RELOAD/SYSTEM, you may modify the model. This can be done by using the ACTIVATE and
DEACTIVATE commands to switch sets of loads on and off, for example.
The following command file uses the SAVE/SYSTEM and RELOAD/SYSTEM commands to run three
simulations from the same input file, creating three sets of output files: case1, case2, and case3. The
command file loads example.adm, the original model, which contains three sets of forces. After
deactivating all the forces and performing a static solution, the SAVE command saves the whole system.
ACTIVATE commands then turn on one set of forces at a time.
Between simulations, the RELOAD command restores the saved version of the model. Reloading the
save file returns the model to the conditions at the time of the save. In this case, the saved version of the
model is at static equilibrium with all the forces inactive.
example
case1
dea/sfo,id=101,102,201,202,301,302
sim/static
save/system, file=ex.sav
act/sfo, id=101,102
! Simulate
act/sfo, id=201,202
! Simulate
act/sfo, id=301,302
! Simulate
stop
See other Simulation available.
SENSOR 151
Adams/Solver (FORTRAN) Commands
SENSOR
The SENSOR command lists the data for a SENSOR statement, and/or redefines the function expression.
Format
Arguments
EVALUATE_ROUTINE=libname::subname
FUNCTION =
USER ( r 1 [ ,, r 30 ] )
LIST
ROUTINE=libname::subname
152 Adams/Solver
Examples
SENSOR/231, FUNCTION=DX(0202,0307)
SET 153
Adams/Solver (FORTRAN) Commands
SET
The SET command sets the options for graphics display.
Format
154 Adams/Solver
Arguments
ANGLE=a,b,c
Rotates the current display a, b, and c degrees about the screen x-axis, the screen
y-axis, and the screen z-axis, respectively. Positive values rotate the display in
the positive direction (as defined by the right-hand rule). Negative values rotate
the display in the negative direction (as defined by the right-hand rule).
Subsequent ANGLE arguments are additive.
BASEMARKER=id Specifies a marker that you want to keep in the same screen position throughout
the simulation.
BAUD=i
Specifies the baud rate or transmission rate to the terminal. The baud rate
defaults to 1200, but can be set and reset to 150, 300, 1200, 2400, 4800, or 9600.
Changing the baud rate affects delay times after the screen is cleared (see the
CLEAR command).
CONTINUOUS
EYE=x,y,z
Specifies the view of the data that you want to display. A point (x,y,z) is defined
with respect to a coordinate system whose axes are parallel to the ground
coordinate system and whose origin is at the center of the picture. Adams/Solver
(FORTRAN) displays the view of the data seen along the line defined by the
origin of the coordinate system and the point (x,y,z). x, y or z defaults to zero if
it is not specified.
FSCALE=r
PAUSE
SCALE=r
SET 155
Adams/Solver (FORTRAN) Commands
SHIFT=x,y,z
Shifts the display x units along the x-axis, y units along the y-axis, and z units
along the z-axis. Define x, y, and z with respect to the ground coordinate system
(GCS). x, y or z defaults to zero if it is not specified. A positive x, y or z value
shifts displays along the respective axis in the positive direction, and a negative
x, y or z, value shifts displays along the respective axis in the negative direction
SINGLE
Erases each graphics frame before displaying the next. SINGLE is the opposite
of SUPER; SINGLE is the default.
SUPER
Does not erase each graphics frame before displaying the next. SUPER is the
opposite of SINGLE; SINGLE is the default.
TARGET=x,y,z
Specifies a new center for the display. You must give the values of x, y, and z
with respect to the ground coordinate system (GCS).
TSCALE=r
VIEW=c
Displays an orthogonal view of the schematic. Set view equal to one of these
character strings.
XY or YX Displays the x-y plane
YZ or ZY Displays the y-z plane
XZ or ZX Displays the x-z plane
ALL Displays all three planes
Caution:
Once you se the SET command to rotate the image through one or more angles, the axes
shown on the screen no longer indicate the global x-axis, the global y-axis, and/or the
global z-axis. The axes on the screen then serve only to indicate the view chosen.
Examples
SET VIEW=XY, SCALE=1.5, CONTINUOUS
This SET command selects the Adams/Solver (FORTRAN) view that initially shows the x-y plane.
Subsequent use of the ANGLE argument realigns all views. In addition, this command scales the display
to one and one-half times the present size and specifies that, when set to graphics, Adams/Solver
(FORTRAN) is to show displays at each output step without pausing to allow time for you to use graphics
commands.
See other Display available.
156 Adams/Solver
SFORCE
The SFORCE command lists or changes the characteristics of an SFORCE statement.
Format
Arguments
ACTIONONLY
FUNCTION =
USER ( r 1 [ ,, r 30 ] )
SFORCE 157
Adams/Solver (FORTRAN) Commands
I=id,J=id
LIST
REACTION
TRANSLATION
ROTATION
ROUTINE=libname::subname
The SFORCE command lists or changes the characteristics of an existing SFORCE element. You can
alter one or both points of force application, change the force from ACTIONONLY to ACTIONREACTION, or the reverse, or change the force from TRANSLATION to ROTATION, or the reverse. In
addition, you can change the force definition function expression or SFOSUB parameter list, or switch
the definition between function expression and subroutine.
After a change to an SFORCE, Adams/Solver (FORTRAN) reprocesses the model at the next
SIMULATE command, as if it had just been read in from the dataset. During the reprocessing,
Adams/Solver (FORTRAN) checks the entire model for consistency, reinitializes user subroutines, and
recomputes initial conditions.
While checking, Adams/Solver (FORTRAN) verifies that the model is still valid with the new SFORCE.
If, for example, the SFORCE function expression refers to an inactive element, Adams/Solver
(FORTRAN) issues an error.
Adams/Solver (FORTRAN) also reinitializes all user subroutines to re-establish functional
dependencies. For each element that refers to a user-written subroutine, Adams/Solver calls the userwritten subroutine with IFLAG set to true.
Prior to the actual simulation, Adams/Solver (FORTRAN) computes initial conditions for the model. If
this is the first simulation, Adams/Solver (FORTRAN) begins with the positions and velocities specified
158 Adams/Solver
in the dataset. If you ran a previous simulation, Adams/Solver (FORTRAN) begins with the final
displacements and velocities. Adams/Solver (FORTRAN) then adjusts the initial conditions to ensure
that they are consistent with the model constraints. If this is the first simulation, Adams/Solver
(FORTRAN) also maintains any user supplied joint initial-conditions and positions specified as EXACT.
If you change an SFORCE I marker, J marker, or type in the middle of a simulation, by default
Adams/Solver (FORTRAN) splits the tabular, request, graphics, and results output into two separate sets
of output concatenated together. This ensures that the output correctly reflects the new system topology.
Adams/Solver (FORTRAN) does not split the files if you change only the SFORCE function expression.
The OUTPUT/NOSEPARATOR argument prevents Adams/Solver (FORTRAN) from splitting the file.
This allows you to plot or animate the output continuously from beginning to end, but may result in
misleading graphics during postprocessing. For more information on the NOSEPARATOR argument, see
OUTPUT.
Examples
SFORCE/201,FUNCTION=-10.*VR(101,201)
This SFORCE command changes the force definition for SFORCE 201.
SFORCE/6,I=28
This SFORCE command applies SFORCE 6 to Marker 28, leaving the J marker unchanged.
See other Forces available.
SHOW 159
Adams/Solver (FORTRAN) Commands
SHOW
The SHOW command lists statistics for any of these topics: CPU time, graphics options, status, and time.
Format
Arguments
CPUTIME
Lists the current total use of CPU time for the execution.
GROPTIONS
TIME
See other Information available.
160 Adams/Solver
SIMULATE
The SIMULATE command specifies the type of simulation you want Adams/Solver (FORTRAN) to run.
It also defines the run time and the number or size of the output steps.
Format
Arguments
ACCELERATION
DISPLACEMENT
DTOUT=r
Specifies the size of the output step for the analysis in model time units.
Range: DTOUT > 0
DURATION
SIMULATE 161
Adams/Solver (FORTRAN) Commands
DYNAMICS
END
STATICS
use the STATICS argument and you do not specify an end time or
steps.
Performs a quasi-static equilibrium simulation if you use the
162 Adams/Solver
STEPS=i
TRANSIENT
VELOCITY
Extended Definition
Adams/Solver (FORTRAN) allows you to do one or more analyses on the same dataset until the STOP
command is issued. These analyses can be different types as long as they meet the degree-of-freedom
requirements for that type of analysis. For example, it is often useful or necessary to do a static
equilibrium analysis on a model to establish equilibrium conditions before doing a dynamic analysis.
Tip:
Note the distinction between END and DURATION. At time zero, a SIMULATE
command with END=1 or DURATION=1 indicates an end time of one second. At time one
second, a SIMULATE command with END=1.5 indicates an end time of 1.5 seconds; a
SIMULATE command with DURATION=1.5 indicates an end time of 2.5 seconds.
SIMULATE 163
Adams/Solver (FORTRAN) Commands
Caution:
(FORTRAN) computes the velocity and acceleration initial conditions even if they were
computed prior to the static simulation. This ensures that the velocity and acceleration
initial conditions are consistent with the displacements from the static simulation.
When you use END and STEPS parameters with the SIM/STAT command, time
increments past time = 0. As such, initial velocities are no longer valid and are not
considered in subsequent dynamic analyses.
If a static simulation directly follows a dynamic simulation, Adams/Solver (FORTRAN)
sets the velocities and accelerations (except gravity) to zero and repeats the displacement
initial conditions.
For a zero-degree-of-freedom model, Adams/Solver (FORTRAN) solves the kinematic
equations during a static simulation. This means that, even though it is a static
simulation, Adams/Solver (FORTRAN) uses the parameters from the KINEMATICS
statement or command (not the EQUILIBRIUM statement or command) and sets the
MODE analysis constant to 1 (not 5 or 6).
Adams/Solver (FORTRAN) automatically performs a dynamic analysis for kinematic
systems that include DIFFs and sets the MODE analysis constant to 4 (not 1).
The STEPS and DTOUT arguments can indirectly affect the accuracy of the results
164 Adams/Solver
SPLINE 165
Adams/Solver (FORTRAN) Commands
SPLINE
The SPLINE command modifies or lists an existing SPLINE statement. You can change the values of the
SPLINE data, and in the process increase or decrease the number of X data or the number of curve
families. You cannot change the extrapolation method, nor can you read data from a file.
For information on the corresponding statement, see the SPLINE statement.
For information on the corresponding subroutine, see the SPLINE_READ subroutine.
Format
SPLINE/id
, X=x1, x2, x3, x4 [, . . . , xn]
, Y=y1, y2, y3, y4 [, . . . , yn]
, LIST
or
SPLINE/id
, X=x1, x2, x3, x4 [, . . . , xn]
, Y=z1, y11, y12, y13, y14 [, . . . ,y1n]
, Y=z2, y21, y22, y23, y24 [, . . . ,y2n]
, Y=z3, y31, y32, y33, y34 [, . . . ,y4n]
, Y=z4, y41, y42, y43, y44 [, . . . ,y4n]
[, . . . , Y=zm, ym1, ym2, ym3, ym4,[, . . . ,ymn]]
, LIST
[ ] Optionally select the item
Arguments
X=x1,x2,x3,x4[ , . . . , xn]
on.
Y=y1,y2,y3,y4 [ , . . . , yn]
166 Adams/Solver
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]]
and so on.
LIST
See other Reference data available.
SPRINGDAMPER 167
Adams/Solver (FORTRAN) Commands
SPRINGDAMPER
The SPRINGDAMPER command redefines and/or lists the data for a SPRINGDAMPER statement. You
cannot redefine the I and J marker defining the springdamper or the translational/rotational characteristic,
but you can redefine other characteristics.
Format
Arguments
ANGLE=r
Respecifies the reference angle for the torsional spring. If the reference torque of the
spring is zero, ANGLE equals the free angle. Adams/Solver (FORTRAN) assumes
ANGLE is in radians unless a D is added after the value.
C=r
Respecifies the viscous damping coefficient for the force. The force due to damping is
zero when the system is at rest. C must be greater than or equal to zero.
CT=r
Respecifies the viscous damping coefficient for the torque. The torque due to damping is
zero when the system is at rest. CT must be in units of torque per radian per unit of time.
Range: CT > 0
FORCE=r
K=r
KT=r
Respecifies the spring stiffness coefficient for the torque. KT must be in units of torque
per radian.
Range: KT > 0
168 Adams/Solver
LENGTH=r Respecifies the reference LENGTH for the spring. If the reference force of the spring is
zero, LENGTH equals the free length.
Range: LENGTH > 0
LIST
STOP 169
Adams/Solver (FORTRAN) Commands
STOP
The STOP command terminates execution of Adams/Solver (FORTRAN) in the interactive mode and
returns control to the operating system.
Format
STOP
See other Simulation available.
170 Adams/Solver
STRING
The STRING command redefines and/or lists the data for a STRING statement.
Format
STRING=c
Respecifies the string to be stored. The STRING argument and value must appear
together on one 80-character line. If STRING is abbreviated to S and starts a line, the
supplied string can be as long as 1024 characters.
LIST
Caution:
The following characters are not permitted in a STRING argument because they are
delimiters in the Adams/Solver (FORTRAN) command language: comma (,), semicolon
(;), ampersand (&), and exclamation point (!). This is because the comma indicates that
additional Adams/Solver (FORTRAN) arguments follow, the semicolon indicates that
additional Adams/Solver (FORTRAN) statements follow on the same line, the ampersand
indicates that the next line is a continuation of the statement on this line, and the
exclamation point indicates that Adams/Solver (FORTRAN) is to stop reading the line.
TIME 171
Adams/Solver (FORTRAN) Commands
TIME
The TIME command shows the simulation time, integration step size, number of function evaluations
completed, and number of integration steps completed.
Format
TIME
Examples
TIME
Current Simulation Time
= 5.0E-02
= 1.0E-03
= 133
= 59
172 Adams/Solver
UCON
The UCON command redefines and/or lists the parameters for a UCON statement.
Format
FUNCTION=USER(r1[,...,r30]) Respecifies and passes up to thirty constants to the UCOSUB userwritten subroutine. These can be part identifiers, variable codes,
and other data that the UCOSUB user-written subroutine needs to
define the constraint. If the FUNCTION argument is used, it must
be either the last argument in the UCON command or be followed
by a backslash (\).
LIST
Caution:
If you use the UCON command for a velocity-dependent constraint and then use the
Adams-Bashforth and Adams-Moulton (ABAM) integrator to integrate the equations of
motion, Adams/Solver (FORTRAN) prevents execution. Under these circumstances, use a
Backward-Differentiation-Formula (BDF) integrator to integrate the equations of motion.
VARIABLE 173
Adams/Solver (FORTRAN) Commands
VARIABLE
A VARIABLE command redefines or lists data for a VARIABLE statement that defines a variable in terms
of a scalar algebraic equation. The variable can be either independently used, or as part of the PINPUT,
POUTPUT, or ARRAY statement.
Format
Arguments
FUNCTION =
USER ( r 1 [ ,, r 30 ] )
IC=r
LIST
ROUTINE=libname::subname
Extended Definition
The VARIABLE command redefines or lists a user-defined algebraic equation and its initial value.
After a change to a variable, Adams/Solver (FORTRAN) reprocesses the model at the next SIMULATE
command, as if it had just been read in from the dataset. During the reprocessing, Adams/Solver
174 Adams/Solver
(FORTRAN) checks the entire model for consistency, reinitializes user subroutines, and recomputes
initial conditions.
Adams/Solver (FORTRAN) also reinitializes user subroutines to re-establish functional dependencies.
For each element that refers to a user-written subroutine, Adams/Solver (FORTRAN) calls the userwritten subroutine with the IFLAG argument set to true.
Tip:
Caution:
and then try to alter IC, Adams/Solver (FORTRAN) rejects the entire VARIABLE
command.
The IC argument should be used whenever a zero value might cause a floating
VFORCE 175
Adams/Solver (FORTRAN) Commands
VFORCE
The VFORCE command redefines and/or lists the data for a VFORCE statement that defines a
translational vector force element as specified using three orthogonal components.
Format
Arguments
FX=e
FY=e
FZ=e
176 Adams/Solver
JFLOAT=id
LIST
RM=id
ROUTINE=libname::subname
Extended Definition
The VFORCE statement lists or redefines a force element that consists of three mutually orthogonal
translational force components. You can alter one or both points of force application, change the force
reference marker, and change the force function expressions or the parameters passed to the VFOSUB
user-written subroutine.
After a change to a VFORCE, Adams/Solver (FORTRAN) reprocesses the model at the next SIMULATE
command, as if it had just been read in from the dataset. During the reprocessing, Adams/Solver
(FORTRAN) checks the entire model for consistency, reinitializes user subroutines, and recomputes
initial conditions.
While checking, Adams/Solver (FORTRAN) verifies that the model is still valid with the new VFORCE.
If, for example, the VFORCE function expression refers to an inactive element, Adams/Solver
(FORTRAN) issues an error.
Adams/Solver (FORTRAN) also reinitializes all user subroutines to re-establish functional
dependencies. For each element that refers to a user-written subroutine, Adams/Solver (FORTRAN) calls
the user-written subroutine with IFLAG set to true.
Prior to the actual simulation, Adams/Solver (FORTRAN) computes initial conditions for the model. If
this is the first simulation, Adams/Solver (FORTRAN) begins with the positions and velocities specified
in the dataset. If you ran a previous simulation, Adams/Solver (FORTRAN) begins with the final
displacements and velocities. Adams/Solver (FORTRAN) then adjusts the initial conditions to ensure
that they are consistent with the model constraints. If this is the first simulation, Adams/Solver
(FORTRAN) also maintains any user supplied joint initial-conditions and positions specified as EXACT.
If you change a VFORCE I marker, J marker, or type in the middle of a simulation, by default
Adams/Solver (FORTRAN) splits the tabular, request, graphics, and results output into two separate sets
VFORCE 177
Adams/Solver (FORTRAN) Commands
of output that are concatenated. This ensures that the output correctly reflects the new system topology.
Adams/Solver (FORTRAN) does not split the files if you change only the VFORCE function expression
or use the LIST arguments.
The OUTPUT/NOSEPARATOR argument prevents Adams/Solver (FORTRAN) from splitting the file.
This allows you to plot or animate the output continuously from beginning to end, but may result in
misleading graphics during postprocessing. See OUTPUT for more information on the NOSEPARATOR
argument.
Tip:
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 user-defined functions FX, FY, and FZ should be smooth, continuous, and singlevalued. These conditions make the solution process very effective.
178 Adams/Solver
VTORQUE
The VTORQUE command redefines and/or lists the data for a VTORQUE statement that defines a vector
torque that consists of three orthogonal components.
Format
Arguments
I=id
LIST
RM=id
ROUTINE=libname::subname
VTORQUE 179
Adams/Solver (FORTRAN) Commands
TX=e
TY=e
TZ=e
Extended Definition
The VTORQUE command lists or redefines a force element that consists of three mutually orthogonal
translational torque components. You can alter one or both points of torque application, change the torque
reference marker, and change the torque function expressions or the parameters passed to the VTOSUB
user-written subroutine.
After a change to a VTORQUE, Adams/Solver (FORTRAN) reprocesses the model at the next
SIMULATE command, as if it had just been read in from the dataset. During the reprocessing,
Adams/Solver (FORTRAN) checks the entire model for consistency, reinitializes user subroutines, and
recomputes initial conditions.
While checking, Adams/Solver (FORTRAN) verifies that the model is still valid with the new
VTORQUE. If, for example, the VTORQUE function expression refers to an inactive element,
Adams/Solver (FORTRAN) issues an error.
Adams/Solver (FORTRAN) also reinitializes all user subroutines to re-establish functional
dependencies. For each element that refers to a user-written subroutine, Adams/Solver (FORTRAN) calls
the user-written subroutine with IFLAG set to true.
Prior to the actual simulation, Adams/Solver (FORTRAN) computes initial conditions for the model. If
this is the first simulation, Adams/Solver (FORTRAN) begins with the positions and velocities specified
in the dataset. If you ran a previous simulation, Adams/Solver (FORTRAN) begins with the final
displacements and velocities. Adams/Solver (FORTRAN) then adjusts the initial conditions to ensure
that they are consistent with the model constraints. If this is the first simulation, Adams/Solver
(FORTRAN) also maintains any user supplied joint initial-conditions and positions specified as EXACT.
If you change a VTORQUE I marker, J marker, or type in the middle of a simulation, by default
Adams/Solver (FORTRAN) splits the tabular, request, graphics, and results output into two separate sets
of output that are concatenated. This ensures that the output correctly reflects the new system topology.
180 Adams/Solver
Adams/Solver (FORTRAN) does not split the files if you change only the VTORQUE function
expression.
The OUTPUT/NOSEPARATOR argument prevents Adams/Solver (FORTRAN) from splitting the file.
This allows you to plot or animate the output continuously from beginning to end, but may result in
misleading graphics during postprocessing.
Tip:
Depending on the nature of the desired torque relationship, the RM marker may belong to
the same part as the I marker or the JFLOAT marker, or to a third, unrelated part.
Caution:
The user-defined functions TX, TY, and TZ should be smooth, continuous, and singlevalued. These conditions make the solution process very effective.
2 Adams/Solver
Indicates:
CONSUB
The type of value or types of parameters that are to follow the statement,
command, or argument. A summary of these terms include:
i
Integer
Real
Function expression
id
Identifier
x,y,z
a,b,c
PART
{}
[]
[[ ]]
A two-dimensional matrix.
A one-dimensional matrix.
R
x
A vector.
Unit vectors.
System Requirements
To use subroutines, you need the system requirements outlined in the following sections.
To work with user-written subroutines you must have the appropriate compilers and linkers. For more
information, refer to the hardware and software specifications included with your installation
instructions, and on the Adams Web site.
Languages
You can write user-written subroutines in any language, provided there is a way to call FORTRAN
subroutines in that language. FORTRAN is the preferred language for writing user-written subroutines,
although C and C++ are acceptable.
Debuggers
To facilitate the debugging of user-written subroutines, you should have a source-level debugger.
Debuggers are not required when using your own subroutines with Adams/Solver, but are useful for
finding mistakes, such as improper syntax or logic, in your subroutines.
Types of Subroutines
The following sections introduce the three types of subroutines that Adams/Solver provides:
About User-Written Subroutines
About Utility Subroutines
About Callable Subroutines (no longer supported)
User-written subroutines are used primarily for modeling specialized phenomena or calculating
nonstandard results. Many simulations require the modeling of special phenomena that are not a part of
the standard Adams software. These phenomena may be expressed mathematically as differential
equations, algebraic equations, applied forces, constraints, motion inputs to system, or a combination of
these general modeling entities.
Adams/Solver can accept user-specified descriptions of phenomena. You define the governing
relationships for the phenomena in the user-written subroutines. Adams then evaluates these
relationships as part of the solution process.
For more information about user-written subroutines and details about each of the user-written
subroutines, see User-Written Subroutines.
About Utility Subroutines
Utility subroutines are used for accessing current system state information. You typically use this
information as input for defining phenomena or modeling elements that are not available as a part of
standard Adams.
For more information about utility subroutines and details about each of the utility subroutines, see Utility
Subroutines.
4 Adams/Solver
MSC no longer supports callable subroutines. If you have questions on callable subroutines, please refer
to:
Knowledge Base (http://support.adams.com/kb/)
ASK List (http://support.adams.com/services/support/tech_ask.shtm).
Utility Subroutines
About Utility Subroutines
The utility subroutines provide all the functionality found in the dataset function expressions, and more.
You use utility subroutines to perform operations such as the following:
Access data defined in a model.
Access current state information.
Interpolate through raw data using standard curve-fitting techniques.
Evaluate standard functions.
CONSUB is the only subroutine that can call execution control subroutines. In conjunction with
ANALYS, DATOUT, and MODIFY, you can use CONSUB to control an Adams simulation.
ANALYS and MODIFY contain the FORTRAN equivalents of interactive commands to initiate analysis
and to modify the Adams/Solver dataset, respectively. DATOUT produces output from the simulation(s).
These subroutines are of most value if you want to run many simulations on a single dataset or on
variations of that dataset.
Subroutine:
ANALYS
DATOUT
Outputs all data for the current time step into the specified output files.
MODIFY
The data access subroutines report the current values for system variables, or return static data stored in
a model. User subroutines can use this data to define their output quantities.
6 Adams/Solver
Utility Subroutines
The following table lists the names and definitions for the data access subroutines:
Subroutine:
AKISPL
Uses the Akima cubic-curve fitting method to interpolate data specified in a SPLINE
statement.
BISTOP
CHEBY
CUBSPL
ERRMES
FORCOS
FORSIN
GETCPU
GETINM
GETINT
GETMOD
GETSLV
GETSTM
GETVER
GTARAY
GTCMAT
GTCURV
GTSTRG
GTUNTS
HAVSIN
IMPACT
ISTRNG
MODINF
Accesses the original mode numbers and the modal frequencies, in Hertz, of all active
modes associated with a FLEX_BODY statement.
NMODES
POLY
Subroutine:
PUT_SPLINE
RCNVRT
RSTRNG
SHF
STEP
STEP5
SYSARY
SYSFNC
SYSPAR
Allows you to supply the analytical partial derivatives of a subroutine with respect to
values measured through SYSFNC and SYSARY.
TCNVRT
TIMGET
Returns the simulation time corresponding to the last successful simulation step.
UCOVAR
Used with UCOSUB, tells Adams/Solver which of the principal axes coordinates are
used in the user-defined constraint.
USRMES
Allows you to output messages for information or for documenting errors that occur in
user-written subroutines.
Serialization Subroutines
The serialization subroutines are used as an alternative to the SAVSUB and RELSUB user subroutines
to save and restore static data, stored in user subroutines, when issuing SAVE/RELOAD commands.
During executing Save and Reload command Adams/Solver calls all user subroutines with IFAG=7, and
IFLAG=9 respectively. Through branching on the IFLAG values your user subroutines can save and
restore data.
Subroutine:
SERIALIZE_CHARACTERS
SERIALIZE_DOUBLES
SERIALIZE_INTEGERS
UNSERIALIZE_INTEGERS
8 Adams/Solver
Utility Subroutines
Unsupported Subroutines
Although Adams/Solver continues to recognize unsupported subroutines, new subroutines have made
them obsolete. The new subroutines are more flexible and straightforward to use. We recommend that
you use the new subroutines, as the unsupported ones might be removed from future Adams/Solver
releases.
The following table lists the unsupported subroutines, along with references to alternate subroutines:
Unsupported Subroutines and Their Alternates
Instead of:
Use:
DEQINF
SYSFNC
FNCDEP
SYSARY; SYSFNC
INFO
SYSARY; SYSFNC
SPLINE
AKISPL; CUBSPL
ANLMOD
GETMOD
ADAMS_DECLARE_THREADSAFE 9
Utility Subroutines
ADAMS_DECLARE_THREADSAFE
A call to the ADAMS_DECLARE_THREADSAFE subroutine informs Adams/Solver (C++) that the
user-written subroutine is threadsafe and that multiple threads can execute this user-written subroutine
simultaneously.
Use
Called By
None
Calling Sequence
CALL ADAMS_DECLARE_THREADSAFE ()
Input Arguments
None
Output Arguments
None
Extended Definition
Adams/Solver (C++) includes the option of threaded (parallel) execution. That is, multiple threads are
permitted to execute portions of the code simultaneously. On machines with multiple processors, this can
result in a significant reduction in the wall time required for a simulation to complete.
This parallel capability places restrictions on the way the code is written to ensure that different threads
do not adversely interact with each other. Code that is written in such a way is threadsafe. Care has been
take to ensure that relevant portions of Adams/Solver (C++) are threadsafe, but no such assumption can
be made about user-written subroutines. Consequently, by default, all user-written subroutines are
executed serially. By default, no user-supplied subroutine will take advantage of the parallel capabilities
of Adams/Solver (C++).
Because complex models often use user-written subroutines extensively, it can greatly improve
performance to execute these in parallel, as well. If this is to be done, you must ensure that the userwritten subroutine and its dependants are threadsafe. If so, the user-written subroutine can indicate this
with a call to ADAMS_DECLARE_THREADSAFE. This call should occur during subroutine
initialization (iflag = true). Adams/Solver (C++) then permits threads to make simultaneous calls to that
user-written subroutine. For more information, see the PREFERENCES statement.
10 Adams/Solver
Utility Subroutines
While a complete guide to writing parallel code is left to other texts, a few general points are covered
here.
Code can be made thread-safe by eliminating any possibility for data (program variables) to be shared
between different threads. For example, if all variables in a user-written subroutine were either passed in
as arguments or are dynamically allocated local variables, then that user-written subroutine would be
threadsafe.
Coding in such a manner, however, is often not practical. There may be a need for a user-written
subroutine to access constant tabular data or other parameters, which is most efficiently implemented as
global data and shared by multiple threads. To allow for this, during subroutine initialization, all userwritten subroutines are run serially. In addition, calls to REQSUBs are always performed serially.
General Guidelines
1. The only data that can be modified at any time is:
Dynamically allocated local variables.
Static or global variable that are uniquely indexed so there is no possibility that two threads
will modify them simultaneously. For example, a user-written subroutine with a static array
of data could safely modify the array element that is uniquely mapped to the ID of the current
modeling element being evaluated. Because each thread is evaluating a different modeling
element, the threads will not access the same array element at the same time.
2. All data that will be shared by multiple threads must be allocated and set during subroutine
initialization. At other times, this data may be read, but must not be written to.
3. No special coding practices need to be followed inside a REQSUB.
FORTRAN-Specific Guidelines
1. Some FORTRAN compilers (such as Digital/Compaq Visual FORTRAN) statically allocate local
variables by default. This is avoided by using a compiler option (/automatic) that causes all local
variables to be allocated on the stack (unless the SAVE statement is used).
2. Avoid or minimize the use of data in COMMON blocks. Such data is statically allocated and
shared between threads. As stated in the General Guidelines above, such data must either be
written during the initialization phase only or uniquely indexed.
3. Avoid or minimize the use of SAVE statements. Again, this data is statically allocated and must
either be written during the initialization phase only or uniquely indexed.
Note:
There is no way to specify, ensure, or verify that any modeling element be evaluated by any
particular thread.
The use of synchronization constructs within the user-written subroutines themselves is not
recommended. Because user-written subroutines are called so frequently, it is likely that
the overhead of the synchronization will exceed the benefit of parallelization.
ADAMS_NEEDS_PARTIALS 11
Utility Subroutines
ADAMS_NEEDS_PARTIALS
ADAMS_NEEDS_PARTIALS returns a logical value that when true indicates Adams/Solver is
calculating partial derivatives for the calling user subroutine. It is used in conjunction with SYSPAR to
identify when to call SYSPAR.
Use
Called by
None
Calling Sequence
Value a logical variable that when returned true indicates SYSPAR should be called.
12 Adams/Solver
Utility Subroutines
ADAMS_SMP_GROUP
A call to the ADAMS_SMP_GROUP subroutine informs Adams/Solver (C++) that, if the user-written
subroutine is executed in parallel, it must be executed in the same thread as other subroutines with the
same ADAMS_SMP_GROUP id. Note that this applies to each use of the user-written subroutine.
Use
Called By
Any user-written subroutine. However, this utility subroutine only has an effect when both a) the model
is being run in parallel (with preferences/nthreads=n, where n>1) and b) the user-written subroutine has
also made a call to ADAMS_DECLARE_THREADSAFE such that it can be executed in parallel.
Prerequisite
None
Calling Sequence
groupId
An integer variable giving the smp group id. All user-written subroutines with the same
group id will be executed in the same thread.
Valid group ids are any nonzero positive integer.
A group id of zero explicitly states that this user-written subroutine is not part of an smp
group and, if executed in parallel, can be executed by any available thread. This is the
default case.
Output Arguments
None
Extended Definition
ADAMS_SMP_GROUP 13
Utility Subroutines
For example, a complex user-defined bushing might make use of several user-written subroutines which
are not threadsafe. However, it is possible that if there are multiple bushings in the model and all userwritten subroutines that affect a particular bushing are run in the same thread, that the non-threadsafe
issues can be avoided. The ADAMS_SMP_GROUP utility subroutine would permit parallelism in this
case if each use of the user-written subroutines gave the bushing id as its group id.
Within each SMP group, the user-written subroutines are evaluated in the order that they would have
been evaluated if the model were run serially.
It is not recommended that this be used as a substitute to writing completely threadsafe user subroutines.
User-written subroutines which are completely threadsafe will be able to take more effective advantage
of parallelism in Adams.
14 Adams/Solver
Utility Subroutines
ADD_MASS_PROPERTY
The ADD_MASS_PROPERTY utility subroutine accepts the mass properties for two parts or sets of
parts and returns the mass properties for the aggregate set.
It is primarily intended for use with the BODY_MASS_PROPERTY utility subroutine to compute the
aggregate mass properties for a group of parts.
Use
Called By
None
Calling Sequence
CALL ADD_MASS_PROPERTY (cm1, mass1, ip1, cm2, mass2, ip2)
Input Arguments
cm1
A double-precision array of length 3 containing the center of mass of the first part or set of
parts expressed in the GCS.
mass1
A double-precision variable containing the mass of the first part or set of parts.
ip1
A double-precision array of length 6 giving the 6 independent terms in the inertia tensor for
the first part or set of parts. (Ixx, Iyy, Izz, Ixy, Ixz, Iyz) These inertia terms much be
computed about the center of mass of the part and oriented in GCS.
cm2
A double-precision array of length 3 containing the center of mass of the second part or set
of parts expressed in the GCS.
mass2
ip2
A double-precision array of length 6 giving the 6 independent terms in the inertia tensor for
the second part or set of parts. (Ixx, Iyy, Izz, Ixy, Ixz, Iyz) These inertia terms much be
computed about the center of mass of the part and oriented in GCS.
Output Arguments
cm2
A double-precision array of length 3 containing the center of mass of the combined system
of parts expressed in GCS.
ADD_MASS_PROPERTY 15
Utility Subroutines
mass2
Ip2
Extended Definition
The user is responsible for employing consistent units when adding mass properties.
Example
C=======================================+===========================
SUBROUTINE REQSUB (ID, TIME, PAR, NPAR, IFLAG, RESULT)
C+-----------------------------------------------------------------*
C
C This REQSUB gets the mass properties of part 2, and constructs the
C aggregate mass properties of the set of parts 3-9 (constructed to be
C equivalent, in aggregate, to part 2) and returns the first four
terms
C of the inertia tensor for each, 2 and 3-9, for comparison.
C
IMPLICIT NONE
C
C Inputs:
C
INTEGER
ID, NPAR, IBODY
DOUBLE PRECISION PAR(*), TIME
LOGICAL
IFLAG
C
C Outputs:
C
DOUBLE PRECISION RESULT(8)
C
C Local Variables:
C
DOUBLE PRECISION CM(3), MASS, IP(6)
DOUBLE PRECISION SUMCM(3), SUMMASS, SUMIP(6)
C
C+-----------------------------------------------------------------*
C
C
C
Output 8 variables.
C
- The first four elements of the IP of the reference body
C
- The first four elements of the IP of the equivalent set of
bodies.
16 Adams/Solver
Utility Subroutines
C
C
C
C
C
C
C
=
=
=
=
IP(1)
IP(2)
IP(3)
IP(4)
AKISPL 17
Utility Subroutines
AKISPL
The AKISPL data access subroutine uses the Akima cubic-curve fitting method to interpolate data from
the SPLINE statement (C++ or FORTRAN).
Use
Called By
xval
zval
id
An integer variable that specifies the identifier of the corresponding SPLINE statement.
iord
An integer variable that specifies the order of the derivative that AKISPL is to return. The
order is usually zero, but it can be one or two.
18 Adams/Solver
Utility Subroutines
Output Arguments
array
A double-precision array of length three. If iord equals zero, array(1) returns the value of
y that AKISPL calculates. If iord equals one, array returns:
y
----- and ----y- , respectively. If iord equals two, array returns:
x
z
2
y- --------- yy
------,
, and -------- , respectively.
2
2
x x z
z
2
Note that:
errflg
yy
---------= ----------z x
x z
A logical (true or false) variable that AKISPL returns to the calling subroutine. If
AKISPL detects an error in its calculations, it sets errflg to true before it returns errflg to
the calling subroutine.
Extended Definition
AKISPL accesses data in a SPLINE statement (C++ or FORTRAN), using the Akima cubic-curve fitting
method to fit a spline to the data (that is, to add interpolated points), and returns one of the following:
A value for the dependent variable (y) for each value it receives for the independent variable or
variables.
The first partial derivatives of the dependent variable.
The second partial derivatives of the dependent variable.
If the spline data input with the SPLINE statement has one independent variable, Adams/Solver uses a
cubic polynomial to interpolate between points. If the spline data has two independent variables,
Adams/Solver first uses a cubic interpolation method to interpolate between points of the first (x)
independent variable, and then uses a linear method to interpolate between curves of the second (z)
independent variable.
In addition to the AKISPL data access subroutine, Adams/Solver includes the CUBSPL data access
subroutine, which uses the traditional cubic curve fitting method. Use CUBSPL if the primary usage is
in MOTIONs. Use AKISPL if the primary concern is with the forces or torques acting on a model.
If the spline data incorporates sudden changes in value, the CUBSPL data access subroutine gives more
oscillatory results for the curve or surface than AKISPL gives. However, the first and second derivatives
of CUBSPL are smoother than those AKISPL calculates.
ANALYS 19
Utility Subroutines
ANALYS
The ANALYS subroutine performs the analysis requested of it.
Use
Called By
CONSUB
Prerequisite
None
Calling Sequence
antype
cid
A character string or variable associated with this analysis. If the CONSUB driver
subroutine calls DATOUT, Adams/Solver prints the current value of cid (truncated to
twenty characters) in the IDANAL field of the analysis output block in the results file.
timbeg
A double-precision value that specifies the time at which you want the analysis to
begin. This must equal the current simulation time. If it does not equal the current
simulation time, Adams/Solver issues an error message, stops the simulation, and
returns to the calling subroutine.
timend
A double-precision value that specifies the time at which you want the analysis to end.
The value must be greater than or equal to timbeg. If timend is less than timbeg,
Adams/Solver issues an error message, stops the simulation, and returns to the calling
subroutine.
Note that Adams/Solver modifies this argument to reflect the simulation time to which
the simulation has progressed. Therefore, you must be careful to pass a doubleprecision variable, not a constant, in the argument list for this variable. Passing in a
constant can result in a fatal error or program crash.
init
A logical variable that tells Adams whether or not it should reformulate the equations
of motion and perform system assembly at the start of the simulation.
20 Adams/Solver
Utility Subroutines
Output Argument
istat
An integer variable that indicates either the success or the reason for the failure of the call
to ANALYS.
If:
Then:
istat = 0
istat = -1
istat = -9
istat =-10
Extended Definition
ANALYS passes control to the Adams/Solver simulation routines. Adams/Solver performs the analysis
requested. This gives you complete control over the time for which to get a simulation.
Call ANALYS from CONSUB as often as necessary to create the simulation required. After completion
of each analysis, Adams/Solver returns program control to CONSUB. For an example of a CONSUB
driver subroutine that calls ANALYS, see CONSUB.
Caution:
an analysis has been performed before ANALYS is called, the equations have
already been set up for that type of analysis. Set init equal to true on the first call to
ANALYS, otherwise.
When program control passes to CONSUB, automatic generation of output stops.
To generate output, call DATOUT.
BISTOP 21
Utility Subroutines
BISTOP
BISTOP evaluates a BISTOP function (C++ or FORTRAN).
Use
Called By
None
Calling Sequence
CALL BISTOP (x, x', x1, x2, k, e, cmax, d, iord, vector, errflg)
Input Arguments
A double-precision variable that specifies the deformation to be used to compute the force.
x'
x1
A double-precision variable that specifies the lower bound of x. If x is less than x1,
Adams/Solver calculates a positive value for the force. The value of x1 must be less than
the value of x2.
x2
A double-precision variable that specifies the upper bound of x. If x is greater than x2,
Adams/Solver calculates a negative value for the force. The value of x2 must be greater than
the value of x1.
A positive, double-precision variable that specifies the stiffness for the force-deformation
law.
cmax
iord
An integer variable that specifies the order of the derivative that BISTOP is to return. IORD
can be zero, one, or two.
22 Adams/Solver
Utility Subroutines
Output Arguments
vector
A double-precision vector that returns the values calculated by the subroutine. For
BISTOP, vector is a vector of length three. The following table indicates what information
vector returns for each of the possible values of iord.
Vector returns:
0
(1)
(2)
errflg
F ( x, x' )
F ( x, x' )
x
F ( x, x' )
2
x
F ( x, x' )
x'
F ( x, x' )
x' x
A logical (true or false) variable that BISTOP returns to the calling subroutine. If BISTOP
detects an error in a subroutine call statement, it sets errflg to true before it returns errflg
to the calling subroutine.
Extended Definition
The BISTOP function models a force restricting the displacement of a body relative to a gap in another
body.
The force BISTOP evaluates is zero, as long as the floating part lies within the gap in the restricting body.
It is nonzero when the floating part tries to move beyond the gap boundaries in either direction.
The force has two components: a spring or stiffness component and a damping or viscous component.
The stiffness component is a function of the penetration of the floating part into the restricting part. The
stiffness opposes the penetration.
The damping component of the force is a function of the speed of penetration multiplied by a damping
coefficient. The damping opposes the direction of relative motion. To prevent a discontinuity in the
BISTOP 23
Utility Subroutines
damping force at contact, the damping coefficient is, by definition, a cubic step function of the
penetration. Therefore, at zero penetration, the damping coefficient is always zero. The damping
coefficient achieves a maximum, cmax, at a user-defined penetration, d. Even though the points of
contact between the floating part and the restricting part may change as the system moves, Adams/Solver
always exerts the force between the I and the J markers. Examples of systems you can model with the
BISTOP function include a ball rebounding between two walls and a slider moving in a slot. The slider
is the floating body, and the part containing the slot is the restricting body. As long as the slider remains
within the confines of the slot, there is no force acting on the slider. But if the slider tries to move beyond
the slot, a force turns on, effectively preventing the slider's escape.
The following summarizes the BISTOP function:
When x1 < x < x2, force = 0.
When x < x1, p = x1 - x and the force is positive.
When x > x2, p = x - x2 and the force is negative.
When p < d, the damping coefficient is a cubic step function of the penetration.
When p > d, the damping coefficient is cmax.
The values of k, e, cmax, and d depend on the materials used in the two parts and on the shapes of
the parts.
The following equation defines
BISTOP:
e
x < x1
Min ( k ( x 1 x ) STEP ( x, x 1 d, c max, x 1 0 ) x, 0 )
x1 x x2
BISTOP =
0
e
Max ( k ( x x 2 ) STEP ( x, x 2, 0, x 2 + d, c max ) x, 0 ) x > x 2
24 Adams/Solver
Utility Subroutines
BODY_MASS_PROPERTY
The BODY_MASS_PROPERTY utility subroutine accepts specifiers for either a single part or the entire
Adams model and returns to the caller the mass properties (mass, center of mass and inertia tensor) for
that part or model.
Use
Called By
None
Calling Sequence
type
A character variable that specifies the type of modeling element for which the mass
properties are requested. The valid options are one of "Part", "Point_Mass", "Flex_Body" or
"Model". The input is case-insensitive but abbreviations are not permitted.
id
An integer variable that specifies the ID of the element of the type specified for which the
mass properties are requested. If the type is "Model" then this input is ignored. For all other
types this is required.
Output Arguments
cm
A double-precision array of length 3 containing the center of mass of the requested modeling
element expressed in GCS.
mass
ip
BODY_MASS_PROPERTY 25
Utility Subroutines
Caution:
26 Adams/Solver
Utility Subroutines
CHEBY
The CHEBY subroutine evaluates a Chebyshev polynomial.
Use
Called By
None
Calling Sequence
x0
par
npar
iord
An integer variable that specifies the order of the derivative that CHEBY is to return. IORD
can be zero, one, or two.
Output Arguments
value
A double-precision value the subroutine returns. The table below summarizes the value it
returns:
IORD:
0
1
2
errflg
Value:
F(x)
F
(2x )
----------------------------F(x)
x 2 x
A logical (true or false) variable that CHEBY returns to the calling subroutine. If CHEBY
detects an error in the subroutine call statement, it sets errflg to true before it returns errflg
to the calling subroutine.
CHEBY 27
Utility Subroutines
Extended Definition
aj Tj ( x x0 )
j=0
where:
Tj ( x x0 ) = 2 ( x x0 ) Tj 1 ( x x0 ) Tj 2 ( x x0 )
T0 ( x x0 ) = 1
and:
T1 ( x x0 ) = x x0 ,
28 Adams/Solver
Utility Subroutines
CUBSPL
CUBSPL uses the traditional cubic-curve fitting method to interpolate data in the SPLINE statement
(C++ or FORTRAN).
Use
Called By
xval
zval
id
An integer variable that specifies the identifier of the corresponding SPLINE statement.
iord
An integer variable that specifies the order of the derivative that CUBSPL is to return. The
order is usually zero, but can be one or two.
CUBSPL 29
Utility Subroutines
Output Arguments
array
A double-precision array of length three. The values contained in array depend on IORD.
The table below summarizes what array is to contain:
IORD:
Array:
Array(0) = y
Array(1) = 0
Array(2) = 0
Array(1) =
y
Array(2) = x
Array(3) = 0 z2
Array(1) =
Array(2) =
Array(3) =
Note that:
2
2y
2y2
xy
x z
2
z
y
y
=
z x
x z
errflg
A logical (true or false) variable that CUBSPL returns to the calling subroutine. If
CUBSPL detects an error in its calculations, it sets errflg to true before it returns errflg to
the calling subroutine.
Extended Definition
CUBSPL accesses data in a SPLINE statement, using the traditional cubic curve-fitting method to fit a
spline to the data, and returns one of the following:
A value for the dependent variable (y) for each value it receives for the independent variable or
variables.
The first partial derivatives of y with respect to the dependent variable(s).
The second partial derivatives of y with respect to the dependent variable(s).
If the spline data input with the SPLINE statement has one independent variable, Adams/Solver uses a
cubic polynomial to interpolate between points. If the spline data has two independent variables,
Adams/Solver first uses a cubic interpolation method to interpolate between points of the first (x)
independent variable, and then uses a linear method to interpolate between curves of the second (z)
independent variable.
In addition to CUBSPL, Adams/Solver includes the AKISPL data access subroutine, which uses the
Akima cubic curve-fitting method. Use CUBSPL when defining motion inputs. Use AKISPL if the
primary concern is with the forces or torques acting on the model.
30 Adams/Solver
Utility Subroutines
If the spline data incorporates sudden changes in value, CUBSPL gives more oscillatory results for the
curve or surface than are given by the AKISPL data access subroutine. However, the first and second
derivatives are smoother than those of the curve or surface given by AKISPL. This may be an important
consideration. For example, if one of these spline subroutines is used to define a motion, Adams/Solver
uses the second derivative to compute the force or torque attributable to the motion. It also uses the first
and second derivatives to calculate results. If one of these spline subroutines is used to define a force, the
dependent values give the force, and Adams/Solver uses the first derivative to calculate results.
DATOUT 31
Utility Subroutines
DATOUT
DATOUT outputs all data from a simulation initiated by the ANALYS execution control subroutine.
Depending on the statements in the dataset, Adams/Solver may output data to the request, graphics,
results, and FEM files.
Use
Called By
CONSUB
Prerequisite
Call to ANALYS
Calling Sequence
istat
An integer variable that indicates whether the call to DATOUT was successful. If istat = 0,
the call to DATOUT was successful. Currently, Adams/Solver always returns a value of
zero. You do not need to check istat before continuing.
Extended Definition
DATOUT outputs data from a simulation initiated by ANALYS. When you advance the simulation by a
call to ANALYS, Adams/Solver does not automatically output data. If you want to process output (for
example, requests, graphics), call DATOUT from the CONSUB driver subroutine. In this way, you can
choose the type and amount of output. For an example of a CONSUB driver subroutine that calls
DATOUT, see CONSUB.
32 Adams/Solver
Utility Subroutines
ERRMES
ERRMES provides the facility for outputting error messages from user-written subroutines.
Use
Called By
None
Calling Sequence
errflg
A logical (true or false) variable. When errflg is true, ERRMES writes the message
passed in to its output files.
mesage
A character string or variable of as many as 1024 characters that you want ERRMES to
document when the subroutine has an error. This character string should be a descriptive
message and should include the name of the subroutine with the error.
id
An integer variable that specifies the identifier of the statement that is currently invoking
the user-written subroutine.
endflg
A character variable that stops execution when it equals STOP. If endflg has any other
value, Adams/Solver continues execution.
Extended Definition
The ERRMES data access subroutine allows you to output messages to document errors that occur in
user-written subroutines. The messages always go to the message file, and during interactive execution,
Adams/Solver displays them on the screen.
Although ERRMES can be called in response to any execution problem, it should always be called in
response to a data access or a general subroutine call that returns an error flag. For an example of a
DIFSUB evaluation subroutine that calls ERRMES, see DIFSUB.
FORCOS 33
Utility Subroutines
FORCOS
FORCOS evaluates a Fourier cosine series.
Use
Called By
None
Calling Sequence
x0
A double-precision variable that specifies the fundamental frequency of the series. The
variable w must be in radians per unit of the independent variable.
par
npar
An integer variable that indicates the number of coefficients specified in the Fournier cosine
series.
iord
An integer variable that defines the order of the derivative that FORCOS is to return. IORD
can be zero, one, or two.
34 Adams/Solver
Utility Subroutines
Output Arguments
errflg
A logical (true or false) variable that FORCOS returns to the calling subroutine. If
FORCOS detects an error in the subroutine call statement, it sets errflg to true before it
returns errflg to the calling subroutine.
value
IORD:
Value:
F
-----x
F
--------2
x
F(x)
Extended Definition
FORCOS evaluates a Fourier cosine series. The following equation defines FORCOS:
n
aj Tj ( x x0 )
j=0
where:
T j ( x x 0 ) = cos ( j w ( x x 0 ) )
For an example of a MOTSUB evaluation subroutine that calls FORCOS, see MOTSUB.
FORSIN 35
Utility Subroutines
FORSIN
FORSIN evaluates a Fourier sine series.
Use
Called By
None
Calling Sequence
x0
A double-precision variable that specifies the fundamental frequency of the series. The
variable w must be in radians per unit of the independent variable.
par
npar
An integer variable that indicates the number of coefficients specified in the Fournier sine
series.
iord
An integer variable that defines the order of the derivative that FORSIN is to return. IORD
can be zero, one, or two.
36 Adams/Solver
Utility Subroutines
Output Arguments
errflg
A logical (true or false) variable that FORSIN returns to the calling subroutine. If FORSIN
detects an error in the subroutine call statement, it sets errflg to true before it returns errflg
to the calling subroutine.
value
Value:
F
-----x
F
--------2
x
F(x)
Extended Definition
FORSIN evaluates a Fourier sine series. The following equation defines FORSIN:
n
aj Tj ( x x0 )
j=0
where:
T j ( x x 0 ) = sin ( j w ( x x 0 ) )
GET_FULL_MATRIX_DATA 37
Utility Subroutines
GET_FULL_MATRIX_DATA
Returns the values entered in a dataset MATRIX statement (C++ or FORTRAN) of type full, given the
statement identifier.
Use
Called By
id
size
Output Arguments
vals
A double-precision array of size size contains the values from the MATRIX statement.
ierr
Successful
ierr=1
ierr=2
Failed, the value of size does not match the size of the MATRIX
ierr=3
Extended Definition
GET_FULL_MATRIX_DATA returns the values stored in a dataset MATRIX statement of type full. You
can determine the matrix ordering of the matrix data (row or column ordered), by the type that
GET_MATRIX_INFO returns. The order may not be as entered in the MATRIX statement.
Tip:
38 Adams/Solver
Utility Subroutines
GET_MATRIX_INFO
Returns information about a dataset MATRIX statement given the statement identifier (C++ or
FORTRAN).
Use
Called By
id
Output Arguments
type
Sparse
type=2
Full, row-order
type=3
Full, column-order
nrows
ncols
size
An integer value that contains the total number of entries in a sparse MATRIX. For a full
matrix, size is ncols*nrows.
ierr
Successful
ierr=1
Extended Definition
GET_MATRIX_INFO 39
Utility Subroutines
GET_SPARSE_MATRIX_DATA
Number of rows and columns needed to interpret the full matrix data.
40 Adams/Solver
Utility Subroutines
GET_GRAVITY
Returns the current Adams/Solver gravity vector. Specifically this is the gravity vector that would have
been specified by the ACCGRAV statement or command. See the ACCGRAV documentation for more
details.
Use
Use this utility subroutine to obtain the Adams gravity vector from a user-written subroutine.
Called by
None
Calling Sequence
CALL GET_GRAVITY (GX, GY, GX)
Input Arguments
None
Output Arguments
GX
GY
GZ
GET_SPARSE_MATRIX_DATA 41
Utility Subroutines
GET_SPARSE_MATRIX_DATA
Returns the values entered in a dataset MATRIX statement (C++ or FORTRAN) in sparse matrix form
given the statement identifier.
Use
Called By
id
size
Output Arguments
rows
An integer array of size size that contains the row indices corresponding to the MATRIX
values stored in vals.
cols
An integer array of size size that contains the column indices corresponding to the MATRIX
values stored in vals.
vals
A double-precision array of size size that contains the values from the MATRIX statement
in sparse form.
ierr
Successful
ierr=1
ierr=2
Failed, the value of size does not match the size of the
MATRIX
42 Adams/Solver
Utility Subroutines
Extended Definition
GETCPU 43
Utility Subroutines
GETCPU
GETCPU retrieves CPU time used so far.
Use
Called by
None
Calling Sequence
value
44 Adams/Solver
Utility Subroutines
GETINM
The GETINM reports whether the current Adams/Solver command input mode is interactive or
command file-driven.
Use
Called by
None
Calling Sequence
value
A logical variable that returns true if the Adams/Solver command input mode is
interactive, and false if it is command file-driven.
GETINT 45
Utility Subroutines
GETINT
The GETINT data access subroutine retrieves the type of integrator used for the current simulation. The
strings GETINT returns to indicate the integrator type are: ABAM, GSTIFF, GSTIFF_SI2, GSTIFF_SI1,
WSTIFF, WSTIFF_SI2 and WSTIFF_SI1.
Use
Called by
None
Calling Sequence
value
Extended Definition
GETINT returns the type of integrator used for the current simulation. It can have one of the following
values:
ABAM - Adams-Bashforth-Adams-Moulton integrator
GSTIFF - The fixed coefficient BDF integrator using an index three equation formulation
GSTIFF_SI2- The fixed coefficient BDF integrator using a stabilized index two equation
formulation
GSTIFF_SI1- The fixed coefficient BDF integrator using a stabilized index one equation
formulation
WSTIFF - The variable coefficient BDF integrator
WSTIFF_SI2 - The fixed coefficient BDF integrator using a stabilized index two equation
formulation
WSTIFF_SI1- The fixed coefficient BDF integrator using a stabilized index one equation
formulation
UNDEF - The integrator is undefined
Caution:
Value is meaningful only during a simulation, that is, after you have issued a SIMULATE
command.
46 Adams/Solver
Utility Subroutines
GETMOD
GETMOD returns the current analysis mode.
Use
Called By
mode
Variable:
Caution:
Analysis mode:
mode=1
Kinematics
mode=2
Reserved
mode=3
Initial conditions
mode=4
Dynamics
mode=5
Statics
mode=6
Quasi-statics
mode=7
Linearization
GETMOD should be called from a user-written subroutine only when iflag is false. (That
is, GETMOD should not be called during the subroutine initialization.) Calls to GETMOD
when iflag is true can result in erroneous mode information.
GETSLV 47
Utility Subroutines
GETSLV
GETSLV returns the name of the active solver, either HARWELL or CALAHAN.
Use
Called by
None
Calling Sequence
value
Caution:
A character*7 variable containing the name of the solver; HARWELL for the
Harwell solver or CALAHAN for the Calahan solver.
Value is meaningful only during a simulation, that is, after you have issued a SIMULATE
command.
48 Adams/Solver
Utility Subroutines
GETSTM
GETSTM returns the current simulation time.
Use
Called by
None
Calling Sequence
value
Caution:
Value is meaningful only during a simulation, that is, after you have issued a SIMULATE
command.
GETVER 49
Utility Subroutines
GETVER
GETVER returns the current Adams/Solver version number as it appears in the Adams/Solver banner.
Use
Called by
None
Calling Sequence
value
50 Adams/Solver
Utility Subroutines
GSE
The following defines a set of utility subroutines which are to be used in the GSE_DERIV and
GSE_OUTPUT user subroutines that are associated with the GSE element.
These utilities supplement and enhance the SYSARY and SYSPAR utility subroutines that are used in
Adams/Solver (FORTRAN) to access the input and state arrays of the GSE, and provide the derivatives
of the GSE.
If you are using Adams/Solver (C++), you should use the utility subroutines described here rather than
SYSARY and SYSPAR because they are more efficient and they permit access to enhanced GSE
capabilities (sparse GSE and implicit GSE).
The utility subroutines can be grouped into the following categories:
Dimension query utilities (GSE_NS, GSE_ND, GSE_NI, GSO_NO)
Array query utilities (GSE_X, GSE_XDOT, GSE_U, GSE_XD)
Partial-derivative entry utilities (GSEPAR_X, GSEPAR_U, GSEPAR_XDOT)
Partial-derivative mapping utilities (GSEMAP_X, GSEMAP_U, GSEMAP_XDOT)
Note that none of the utility subroutines require that the ID of the GSE be provided. Adams/Solver knows
which GSE is being referred to.
Dimension Query Utilities: GSE_NS, GSE_ND, GSE_NI, GSE_NO
The dimension query utility subroutines are called to obtain information about the dimension of the
various arrays associated with the GSE. Access to this information allows proper dimensioning of arrays.
The dimensions obtained from these utilities must be passed to other utility subroutines as verification
that the subroutine developer is aware of the required array dimension.
Each of the dimension query utility subroutines takes a single integer argument. After the call to the
subroutine, the integer contains the associated dimension.
Called By
GSE_DERIV, GSE_OUTPUT
Prerequisite
None
Calling Sequence
CALL GSE_NS(NS)
CALL GSE_ND(ND)
CALL GSE_NI(NI)
CALL GSE_NO(NO)
GSE 51
Utility Subroutines
Arguments
NS
ND
NI
NO
The array query utility subroutines are called to obtain information about the values of:
Continuous states, X
Time derivative of the continuous states, XDOT
Discrete states, XD
GSE inputs, U
Called By
Require input values, which must be obtained by a previous call to the dimension query utility
subroutines.
Calling Sequence
CALL GSE_X(X,NS)
CALL GSE_XDOT(XDOT,ND)
CALL GSE_XD(XD,ND)
CALL GSE_U(U,NI)
Input Arguments
NS
ND
NI
52 Adams/Solver
Utility Subroutines
Output Arguments
XDOT
XD
Caution:
If the incorrect validation integer value is provided, Adams/Solver (C++) will stop
The partial derivative entry utility subroutines are used to provide Adams/Solver with:
The partial derivative of the GSE_DERIV and GSE_OUTPUT with respect to the continuous
states, X
The time derivative of the continuous states, XDOT (implicit GSE only)
The inputs, U
A call to GSEPAR_X from GSE_DERIV is understood to provide the partial derivative of GSE_DERIV
with respect to X, and so on.
The GSEPAR utility subroutines are assumed to provide full partials unless one or more calls were made
to the corresponding GSEMAP when the GSE_DERIV or the GSE_OUTPUT user subroutine was called
with IFLAG set. When full partials are provided with the GSEPAR utility subroutines, the order of the
entries should be such that all the partial derivatives with respect to the first state or input should be
provided in order before the partial derivatives with respect to the second state or input. If sparse partial
derivatives are used, the entries to GSEPAR should be in the same order as was defined by GSEMAP.
Called By
Calls may be dependent on calls made to GSEMAP utility subroutines when IFLAG was set.
Calling Sequence
CALL GSEPAR_X(D,N)
CALL GSEPAR_XDOT(D,N)
CALL GSEPAR_U(D,N)
GSE 53
Utility Subroutines
Input Arguments
Caution:
If N does not validate, Adams/Solver (C++) stops with an error message. For full
The partial derivative mapping utility subroutines may optionally be used to configure the GSE to have
sparse entries. For a GSE with a large number of states, inputs and/or outputs, the computational savings
can be significant.
GSEMAP_X, GSEMAP_XDOT, and GSEMAP_U register dependencies with respect to state, the time
derivative of state (implicit GSE only) and input, respectively.
If Adams/Solver (C++) detects calls to the GSEMAP utility subroutines during calls to GSE_DERIV or
GSE_OUTPUT, when IFLAG is set, then the corresponding partial derivative is taken to be sparse.
GSEMAP utility subroutine calls may be made for one or more of the families of partial derivaties. For
example, if GSEMAP_X is called from GSE_DERIV, this particular partial derivative is taken to be
sparse while the other families of partial derivatives, for example the partial derivative of GSE_DERIV
with respect to U, is taken to be full.
Multiple calls are made to GSEPAR utility subroutines, one per dependency. For example, a call
GSEMAP_X(1,1) from GSE_OUTPUT indicates to Adams/Solver (C++) that the first output depends
on the first state. The order of the calls to GSEMAP utility subroutines is significant because entries in
the array subsequently passed to the corresponding GSEPAR utility subroutines is assumed to be in this
order.
Called By
None
Calling Sequence
CALL GSEMAP_X(I,J)
54 Adams/Solver
Utility Subroutines
CALL GSEMAP_XDOT(I,J)
CALL GSEMAP_U(I,J)
Input Arguments
Integer - the row index (the index of the state derivative or the output which has a functional
dependency)
Integer - the column index (the index of the state or the input with respect to which the
functional dependency is being registered)
GTARAY 55
Utility Subroutines
GTARAY
GTARAY returns the double-precision numbers stored by an IC-type ARRAY statement (C++ or
FORTRAN).
Use
Called By
id
Output Arguments
array
istat
An integer that indicates the success or the reason for the failure of the call to GTARAY.
If:
number
Caution:
Then:
istat = 0
istat = -1
istat = -2
Make sure that array is large enough to hold all of the returned values.
You can only use GTARAY to access values for an IC-type ARRAY (the default
type). If you want to access values for an X-type, a Y-type, or a U-type ARRAY,
use SYSARY and the ARRAY function, or SYSFNC and the C++ ARYVAL
function or the FORTRAN ARYVAL function.
56 Adams/Solver
Utility Subroutines
GTCMAT
GTCMAT computes the compliance matrix for a set of markers in an Adams/Solver model.
Use
Called By
CONSUB
Prerequisite
nmid
An integer variable that specifies the number of marker, mid. nmid must be greater than
zero and less than or equal to 100.
mid
ndim
An integer variable specifying the number of rows in c. ndim must be at least 6*nmid, since
each marker results in six rows. You must dimension c in CONSUB with exactly ndim
rows (and at least 6*nmid columns).
GTCMAT 57
Utility Subroutines
Output Arguments
istat
Then:
istat= 0
Normal return
istat= -1
nmid < 0
istat= -2
istat= -3
istat= -6
istat= -7
istat= -8
istat= -9
istat= -10
Miscellaneous problems
istat= -11
istat= -12
istat= -13
Extended Definition
The compliance matrix for a system, C, is defined as the partial derivatives of displacements with respect
to applied forces:
C =
x
f
Note that the compliance matrix is the inverse of the stiffness matrix for a system (which is defined as
the partial derivatives of the applied forces with respect to the displacements). If a system is assumed to
58 Adams/Solver
Utility Subroutines
be linear, the compliance matrix can be used to predict the system movement due to force inputs:
x = C f
From this perspective, matrix element cij is the displacement of system degree of freedom i due to a unit
force at degree-of-freedom j.
In order for the system to have meaningful compliances, it must have one or more degrees of freedom.
A kinematic (zero-degree-of-freedom) model does not move in response to applied forces, so by
definition the compliances are zero. GTCMAT returns an error if run on a kinematic model.
GTCMAT returns a matrix containing six columns and six rows for each marker requested. The rows and
columns are in groups of six, appearing in the same order as the markers are listed in mid. The rows
correspond to global x, y, and z translations and global AX, AY, AZ rotations. The columns correspond
to global x, y, and z forces and torques about the global x, y, and z axes.
If, for example, you specify two marker identifiers in mid, GTCMAT returns a 12 x 12 matrix. Element
c(2,4) is the change in the global y displacement of the first marker due to a unit torque about the global
x-axis applied at the first marker (assuming a linear system). Element c(2,8) is the change in the global
y displacement of the first marker due to a global Y force applied at the second marker.
Using Adams/Solver (FORTRAN)
When using Adams/Solver (FORTRAN), GTCMAT computes the compliance matrix by inverting the
Jacobian from an Adams/Solver static solution. Because of this, you must first call ANALYS to perform
a static solution, before calling GTCMAT. GTCMAT returns an error if you have not first run a static
analysis.
Using Adams/Solver (C++)
When using Adams/Solver (C++), GTCMAT computes the compliance matrix as follows:
1. A linearization of the system is performed (the linearization does not change the current state of
the system) and a standard input-output representation is obtained:
X = AX + BU
y = CX
where the output y consists of the displacements of the MARKERs and the input U consists of
applied forces at the MARKERs locations. For more information on the state vector X and the
state matrices A,B, C, see the LINEAR command.
2. Solving for X we find that
1
1
X = A X A BU
GTCMAT 59
Utility Subroutines
1
1
y = [ CA B ]U + [ CA X ]
C = [ CA B ]
Notice that the term [ CA X ] is due to perturbations of the velocities and accelerations of the
system at the operating point, therefore it can be neglected.
The GTCMAT subroutine can be called during a dynamic or a quasi-static simulation.
Caution:
If you don't dimension matrix c properly or don't assign the proper value to ndim,
GTCMAT can overwrite other memory.
60 Adams/Solver
Utility Subroutines
GTCURV
GTCURV evaluates a B-spline or user-written curve created by a CURVE statement (C++ or
FORTRAN).
Use
Called By
id
alpha
A double-precision variable that identifies the value of the independent parameter, a, at which
GTCURV is to evaluate the curve. If the curve is a B-spline computed by the CURVE statement,
alpha must be in the domain -1 < alpha < 1. If the curve is computed by CURSUB, alpha must
be in the domain MINPAR < alpha < MAXPAR (these are specified in the CURVE statement).
iord
An integer variable that specifies the order of the derivative the GTCURV is to return. The legal
values are:
0 - Returns the curve coordinate.
1 - Returns the first derivative with respect to .
2 - Returns the second derivative with respect to .
GTCURV 61
Utility Subroutines
Output Arguments
array
array(1)
array(2)
array(3)
x()
y()
z( )
dx
( -)
-------------d
dy
( )-------------d
dz
( )------------d
2
2
d---------------x ( )2
d
istat
d---------------y ( )2
d
d z()
----------------2
d
An integer variable that indicates either the success or teason for the failure of the call to
GTCURV.
If:
Then:
istat= -1
istat= 0
istat= 1
istat= 2
Extended Definition
GTCURV evaluates a B-spline or a user-written curve defined by a CURVE statements and returns one
of the following:
A value for the dependent variables (x, y, z) for each value it receives for alpha.
The first partial derivatives of the dependent variable.
The second partial derivatives of the dependent variable.
62 Adams/Solver
Utility Subroutines
GTSTRG
GTSTRG returns the character string stored in a STRING statement.
Use
Called By
id
Output Arguments
istat
Then:
istat= 0
istat= -2
nchars
The number of characters in the returned string. Trailing blank spaces are ignored.
string
Caution:
Make sure that string is long enough to hold all of the string.
The string is left-justified (that is, Adams/Solver deletes all blank spaces to the left
of the string).
GTUNTS 63
Utility Subroutines
GTUNTS
GTUNTS returns model unit information from Adams/Solver.
Use
Called By
None
Calling Sequence
exist
A logical variable that, if true, indicates units were set for the model.
scales
units
A character*2 array containing two-letter abbreviations for the model units for time,
length, force, and mass.
Example
For example, if you have an Aero_Force defined in Newtons, and you want to convert to model units,
you must divide your force by scales(3).
DOUBLE PRECISION SCALES(4)
LOGICAL EXIST
CHARACTER*2 UNITS(4)
INTEGER TIME, LENGTH, FORCE, MASS PARAMETER
(TIME=1,LENGTH=2,FORCE=3, MASS=4)
CALL GTUNTS(EXIST, SCALES, UNITS)
Model_Force = Aero_Force/SCALES(FORCE)
To compute a spring in MKS units, give disp, flen, and K in model units:
64 Adams/Solver
Utility Subroutines
GTUNTS uses the UNITS statement in your dataset to determine the units being used in
your model. When a UNITS statement is missing, or if you use a unit consistency factor
(UCF), GTUNTS is not able to determine time, length, mass, or force units. In that case,
GTUNTS returns:
exist = FALSE
scales = 1.0, 1.0, 1.0, 1.0
units = US
HAVSIN 65
Utility Subroutines
HAVSIN
The HAVSIN general subroutine evaluates a haversine function.
Use
Called By
None
Calling Sequence
CALL HAVSIN (x, x0, h0, x1, h1, iord, value, errflg)
Input Arguments
h0
A double-precision variable that specifies the value of the function before the step (x x0).
h1
A double-precision variable that specifies the value of the function after the step (x x1).
iord
An integer variable that defines the order of the derivative that HAVSIN is to return. The
order is usually zero, but it can be one or two.
x0
A double-precision variable that specifies the x value at which the haversine function begins.
x1
A double-precision variable that specifies the value at which the haversine function ends.
66 Adams/Solver
Utility Subroutines
Output Arguments
errflg
A logical (true or false) variable that HAVSIN returns to the calling subroutine. If
HAVSIN detects an error in the subroutine call statement, it sets errflg to true before it
returns errflg to the calling subroutine.
value
A double-precision value the subroutine returns. If iord equals zero, value is the
function evaluated at x. If iord equals one, value is the first derivative of F(x) with
respect to the independent variable x. If iord equals two, value is the second derivative
of F(x) with respect to the independent variable x. Value is:
IORD:
Value:
F(x)
F
(x)
-------------x
F ( x )---------------2
x
Extended Definition
The HAVSIN general subroutine evaluates a haversine function. Figure 1 below illustrates the haversine
function.
The value x is the independent variable, h0 and h1 are the initial and final values of the haversine
function. The following equation defines HAVSIN:
HAVSIN 67
Utility Subroutines
( h0 + h1 )
a = ---------------------2
( h1 h0 )
b = --------------------2
( x x0 )
c = --------------------( x1 x0 )
h0
h2
Caution:
;x x 0
;x 0 < x < x 2
;x x 1
The value x1 must not equal x0. Equal values of x1 and x0 imply a sharp step,
68 Adams/Solver
Utility Subroutines
IMPACT
IMPACT is a simple model for contacts. It evaluates a force that turns on when a distance falls below a
nominal free length (that is, when two parts collide).
Use
Called By
None
Calling Sequence
A double-precision variable that specifies the distance variable you want to use to compute
the force.
x'
x1
A double-precision variable that specifies the free length of x. If x is less than x1,
Adams/Solver calculates a positive value for the force. Otherwise, the force value is zero.
The value of x1 must be greater than zero.
cmax
iord
An integer variable that defines the order of the derivative IMPACT is to return. The order
is usually zero, but it can be one or two.
IMPACT 69
Utility Subroutines
Output Arguments
errflg
A logical (true or false) variable that IMPACT returns to the calling subroutine. If
IMPACT detects an error during its calculations, it sets errflg to true.
vector
(1)
F ( x, x )
(2)
(3)
2
2
F
( x, x )--------------------x
F ( x, x )
-----------------------2
x
F
( x, x )--------------------x
-----------------------F ( x, x )
xx
Extended Definition
IMPACT models collisions and contact. It evaluates a force that turns on when a distance falls below a
nominal free length (that is, when two parts collide).
The force has two components: a spring or stiffness component and a damping or viscous component.
The stiffness component opposes the penetration. The damping component of the force is a function of
the speed of penetration. The damping opposes the direction of relative motion. To prevent a
discontinuity in the damping force at contact, the damping coefficient is, by definition, a cubic step
function of the penetration. Thus at zero penetration, the damping coefficient is always zero. The
damping coefficient achieves a maximum, cmax, at a user-defined penetration, d.
An object colliding with ground is an example of a system that can be modeled with the IMPACT
function.
Let x be the instantaneous distance, x1 be the free length (when x is less than x1, the force turns on), x1
- x be the penetration, and d be the penetration at which Adams/Solver applies full damping (cmax).
When x > x1, force = 0.
When x < x1, force is positive.
When (x1-d) < x < x1, force is positive; there is damping, but it is less than cmax.
When x < (x1-d), force is positive and damping = cmax.
70 Adams/Solver
Utility Subroutines
: x < x1
direction.
When e is less than or equal to one, the rate of change of the force is discontinuous
ISTRNG 71
Utility Subroutines
ISTRNG
ISTRNG converts a number from integer format to character format. The character string representing
the integer is always left justified.
Use
Called By
None
Calling Sequence
number
Output Arguments
istat
An integer variable indicating the success or the reason for the failure of the
call to ISTRNG.
If:
Then:
istat= 0
istat= -3
istat= -4
length
string
Extended Definition
One purpose of ISTRNG is to provide the CONSUB driver subroutine with a character representation of
an integer. This is necessary because the MODIFY execution control subroutine requires commands in
72 Adams/Solver
Utility Subroutines
the form of a character string that may include integers (for example, statement identifiers). The integer
and the character string representing the integer appear identical when printed.
Tip:
If the dimension of the string is CHARACTER*12 or longer, the string can hold any
integer defined on a 32-bit machine.
MODIFY 73
Utility Subroutines
MODIFY
The MODIFY allows execution of any Adams/Solver command except CONTROL, STOP, from a
CONSUB.
Use
Called By
CONSUB
Prerequisite
None
Calling Sequence
comand
Output Argument
istat
An integer variable that indicates whether or not the call to MODIFY was successful.
If istat = 0, the call to MODIFY was successful.
Extended Definition
You must build a character string for the input and pass the string to MODIFY as if it were an actual
interactive command. The general subroutines RSTRNG and ISTRNG are available to help build these
strings. CONSUB can call MODIFY. Program control returns to CONSUB after execution of the
command(s) issued from MODIFY. For an example of a CONSUB driver subroutine that calls MODIFY,
see CONSUB.
Caution:
Adams/Solver ignores any part of an argument following five blank spaces. Therefore,
when using string concatenation to build a command, it is important to remove trailing
blanks. Do this by referring only to the nonblank portion of the string.
74 Adams/Solver
Utility Subroutines
MODINF
MODINF returns the original mode numbers and the modal frequencies, in cycles per user-defined time,
of all active modes associated with a FLEX_BODY statement (C++ or FORTRAN).
Use
Called By
id
Output Argument
mode
An integer array that contains the original mode numbers of all the active modes
associated with the specified FLEX_BODY.
freq
A double-precision array that contains the modal frequencies, in cycles per user-defined
time, of all active modes associated with the specified FLEX_BODY.
errflg
A logical variable that returns true if an error has occurred during the call to MODINF.
Caution:
You must be sure mode and freq are dimensioned large enough to contain all the values
returned by MODINF. You can check the number of active modes using NMODES.
When errflg is true, the values of mode and freq may be wrong.
Example
MODINF 75
Utility Subroutines
For UNIX, in the directory /install_dir/solver/samples, where install_dir is the directory in which you
installed your Adams software.
sysary_sample.acf
sysary_sample.adm
sysary_sample.f
sysary_sample.mtx
76 Adams/Solver
Utility Subroutines
NMODES
NMODES returns the number of modal generalized coordinates associated with a FLEX_BODY
statement (C++ or FORTRAN).
Use
Called By
id
An integer variable containing the identifier of the FLEX_BODY statement for which the
number of modal generalized coordinates should be retrieved.
Output Argument
nq
An integer that indicates the number of modal generalized coordinates associated with the
specified FLEX_BODY.
errflg
A logical variable that returns true if an error has occurred during the call to NMODES.
Caution:
The value of nq will be zero and errflg will return true if there is no active
Example
NMODES 77
Utility Subroutines
sysary_sample.adm
sysary_sample.f
sysary_sample.mtx
78 Adams/Solver
Utility Subroutines
POLY
The POLY general subroutine evaluates a polynomial.
Use
Called By
None
Calling Sequence
iord
An integer variable that defines the order of the derivative that POLY is to return. The order
is usually zero, but it can be one or two.
npar
An integer variable that indicates the number of coefficients specified. The primary purpose
of npar is to provide POLY with the number of values stored in the par array.
par
x0
POLY 79
Utility Subroutines
Output Arguments
errflg
A logical (true or false) variable that POLY returns to the calling subroutine. If POLY
detects an error in the subroutine call statement, it sets errflg to true before it returns errflg
to the calling subroutine.
value
A double-precision value the subroutine returns. If iord equals zero, value is the function
evaluated at x. If iord equals one, value is the first derivative of F(x) with respect to the
independent variable x. If iord equals two, value is the second derivative of F(x) with
respect to the independent variable x. Value is:
IORD:
Value:
F(x)
F
(x)
-------------x
F
( x )---------------2
x
Extended Definition
A POLY general subroutine evaluates a polynomial. The following equation defines POLY:
a
aj ( x x0 )
j=0
80 Adams/Solver
Utility Subroutines
PUT_SPLINE
PUT_SPLINE is used in conjunction with SPLINE_READ. SPLINE_READ reads in the data points for
a spline from a file. PUT_SPLINE is used to store this data within Adams/Solver.
Use
Called By
SPLINE_READ
Calling Sequence
id
nx
An integer variable that specifies the number of x values contained in the x array. The
number of x values must be at least 4.
nz
An integer variable that specifies the number of z values contained in the z array. The number
of z values must be at least 1.
A double-precision array containing the x values for the spline element. The number of x
values must be at least nx.
A double-precision array containing the y values for the spline element. The number of
y values must be at least nx nz.
A double-precision array containing the z values for the spline element. The number of
z values must be at least nz.
Output Argument
errflg
A logical variable that indicates if Adams successfully accepts the x, y, [and z] data.
SPLINE_READ checks the value of errflg after calling PUT_SPLINE.
Extended Definition
PUT_SPLINE transfers spline data to Adams/Solver from local variables that you define in the
SPLINE_READ user-written subroutine. For an example of a SPLINE_READ subroutine that calls
PUT_SPLINE, see SPLINE_READ.
Cautions
If there are more than nx values in x, more than nx nz values in y, or more than nz values in z,
then Adams/Solver ignores the extra values.
PUT_SPLINE 81
Utility Subroutines
The z array is not used when nz = 1. The value of z is irrelevant in this case; however, z must
exist.
The order of values that are stored in the y array must correspond to the order of points in the x
correspond to the values in the x array, and the sets correspond to the values in the z array). It
is possible to use either a single- or double-dimensioned array for y.
If a double-dimensioned array is used, the first dimension must be equal to nx, not greater, and
82 Adams/Solver
Utility Subroutines
RCNVRT
RCNVRT converts rotational coordinates from one representation to another.
Use
Called By
None
Calling Sequence
RCNVRT 83
Utility Subroutines
Input Arguments
84 Adams/Solver
Utility Subroutines
RCNVRT 85
Utility Subroutines
sys1
A character string specifying the system in which the values passed in coord1 were
determined. The following table shows the possible character strings and their meanings:
Character
string:
Means:
'EULER'
'EULPAR'
'AXAYAZ'
'YPR'
Yaw-pitch-roll
'COSINES'
Directional cosines
'BRYANT'
Bryant angles
'B123'
`B231'
Body-three: 2-3-1
`B312'
Body-three: 3-1-2
`B132'
Body-three: 1-3-2
`B213'
Body-three: 2-1-3
`B321'
Body-three: 3-2-1
`B121'
Body-two: 1-2-1
`B131'
Body-two: 1-3-1
`B212'
Body-two: 2-1-2
`B232'
Body-two: 2-3-2
`B313'
`B323'
Body-two: 3-2-3
`S123'
Space-three: 1-2-3
`S231'
Space-three: 2-3-1
`S312'
Space-three: 3-1-2
`S132'
Space-three: 1-3-2
`S213'
Space-three: 2-1-3
`S321'
Space-three: 3-2-1
`S121'
Space-two: 1-2-1
`S131'
Space-two: 1-3-1
`S212'
Space-two: 2-1-2
86 Adams/Solver
Utility Subroutines
`S232'
Space-two: 2-3-2
`S313'
Space-two: 3-1-3
`S323'
Space-two: 3-2-3
`RODPAR'
Rodrigues parameters
sys2
A character string specifying the system in which the values returned as output in coord2 are
to be determined. Possible character strings are the same as those for sys1.
coord1
RCNVRT 87
Utility Subroutines
Output Arguments
coord2
istat
An integer variable indicating the unqualified success, the qualified success, or the
reason for the failure of the call to RCNVRT. The values for istat are as follows:
If:
Then:
istat= 0
istat> 0
istat= +1
istat= +2
istat< 0
istat= -1
istat= -2
istat= -3
istat= -4
istat= -5
istat= -6
istat= -7
Extended Definition
In Adams/Solver, rotational coordinates are often used to specify the orientation of a coordinate system.
For example, a DIFSUB, a REQSUB, or an SFOSUB can call RCNVRT to change Euler angles to Euler
parameters.
88 Adams/Solver
Utility Subroutines
Euler parameters are P0, P1, P2, and P3. P0 is the cosine of one-half the angle of rotation of the rotated
frame with respect to the reference frame. P1, P2, and P3 are the x, y, and z components, respectively, of
the unit vector around which the rotation occurs, multiplied by the sine of one-half the angle.
Rodrigues parameters (R1, R2, and R3) define the relative rotation between two frames of reference. The
relationship between Rodrigues parameters and Euler parameters is R1 = P1/P0, R2 = P2/P0, and R3 =
P3/P0. Rodrigues parameters become undefined when P0 = 0, that is, when the angle of rotation about
the vector is 180 degrees.
Tip
The coord1 and coord2 array length is three, except when the coordinates are in the EULPAR system
(when the array length is four) or in the COSINES system (when the array length is nine). The nine values
of the COSINES system, which forms a three-by-three matrix, are stored in column order in coord2.
RSTRNG 89
Utility Subroutines
RSTRNG
RSTRNG converts a double-precision variable to a character string.
Use
Called By
None
Calling Sequence
reel
Output Arguments
istat
An integer variable indicating the success or the reason for the failure of the call to
RSTRNG.
If:
Then:
istat= 0
istat= -3
istat= -4
length
An integer variable that returns the number of nonblank characters in the converted string.
string
A character string that represents the number. Adams/Solver left justifies the converted
string (that is, removes all leading blank spaces) and retains all other blank spaces.
Extended Definition
RSTRNG converts a double-precision number to the characters representing that number. One purpose
of RSTRNG is to provide the CONSUB driver subroutine with a character representation of a real
number. This is necessary because the MODIFY execution control subroutine requires commands in the
form of a character string that can include real numbers (for example, data). The double-precision
variable and the character string representing the number appear identical when printed.
90 Adams/Solver
Utility Subroutines
Tip:
If the dimension of the string is CHARACTER*12 or longer, the string can hold any real
number.
SERIALIZE_CHARACTERS 91
Utility Subroutines
SERIALIZE_CHARACTERS
SERIALIZE_CHARACTERS allows you to save character static data from your user subroutines when
Solver is executing a SAVE/ command to be used later when reloading an analysis.
Use
Called By
c_array
Example
F77:
IF(IFLAG .EQ. 3)THEN
... Make calls to sysfnc and sysary to set up dependencies ...
ELSEIF (IFLAG .EQ. 7)THEN
CALL SERIALIZE_CHARACTERS(C_DATA, LEN(C_DATA))
ELSEIF (IFLAG .EQ. 9)THEN
CALL UNSERIALIZE_CHARACTERS(C_DATA, LEN(C_DATA))
ENDIF
CXX:
switch(IFLAG){
case 3:
... Make calls to c_sysfnc and c_sysary to set up dependencies ...
break;
case 7:
c_dataSize = strlen(c_data)+1;
c_adams_serialize_integers(&c_dataSize, 1);
c_adams_serialize_characters(c_data, c_dataSize);
break;
case 9:
if(c_data)free(c_data);
c_adams_unserialize_integers(&c_dataSize, 1);
c_data = (char*) malloc(sizeof(char)*c_dataSize);
c_adams_unserialize_characters(c_data, c_dataSize);
92 Adams/Solver
Utility Subroutines
break;
SERIALIZE_DOUBLES 93
Utility Subroutines
SERIALIZE_DOUBLES
SERIALIZE_DOUBLES allows you to save static double precision data from your user subroutines
when Solver is executing a SAVE/ command to be used later when reloading an analysis.
Use
Called By
d_array
Example
F77:
IF(IFLAG .EQ. 3)THEN
... Make calls to sysfnc and sysary to set up dependencies ...
ELSEIF (IFLAG .EQ. 7)THEN
CALL SERIALIZE_DOUBLES(DP_DATA, N_DP_DATA)
ELSEIF (IFLAG .EQ. 9)THEN
CALL UNSERIALIZE_DOUBLES(DP_DATA, N_DP_DATA)
ENDIF
CXX:
switch(IFLAG){
case 3:
... Make calls to c_sysfnc and c_sysary to set up dependencies ...
case 7:
c_adams_serialize_integers(&d_dataSize, 1);
c_adams_serialize_doubles(d_data, d_dataSize);
break;
case 9:
c_adams_unserialize_integers(&d_dataSize, 1);
if( d_data )free(d_data);
d_data= (double*) malloc(sizeof(double)*d_dataSize);
c_adams_unserialize_doubles(d_data, d_dataSize);
break;
}
94 Adams/Solver
Utility Subroutines
SERIALIZE_INTEGERS
SERIALIZE_INTEGERS allows you to save static integer data from your user subroutines when Solver
is executing a SAVE/ command to be used later when reloading an analysis.
Use
Called By
Example
F77:
IF(IFLAG .EQ. 3)THEN
... Make calls to sysfnc and sysary to set up dependencies ...
ELSEIF (IFLAG .EQ. 7)THEN
CALL SERIALIZE_INTEGERS(I_DATA, N_I_DATA)
ELSEIF (IFLAG .EQ. 9)THEN
CALL UNSERIALIZE_INTEGERS(I_DATA, N_I_DATA)
ENDIF
CXX:
switch(IFLAG){
case 3:
... Make calls to c_sysfnc and c_sysary to set up dependencies ...
case 7:
c_adams_serialize_integers(&i_dataSize, 1);
c_adams_serialize_integers(i_data, i_dataSize);
break;
case 9:
c_adams_unserialize_integers(&i_dataSize, 1);
if( i_data )free(i_data);
d_data= (int*) malloc(sizeof(int)*i_dataSize);
c_adams_unserialize_integers(i_data, i_dataSize);
break;
}
SHF 95
Utility Subroutines
SHF
SHF evaluates a simple harmonic function.
Use
Called By
None
Calling Sequence
x0
A double-precision variable that specifies the frequency of the sine function. The variable
must be in radians per unit of the independent variable.
phi
A double-precision variable that specifies a phase shift in the sine function. The variable phi
must be in radians.
iord
An integer variable that defines the order of the derivative that SHF is to return. The order is
usually zero, but it can be one or two.
96 Adams/Solver
Utility Subroutines
Output Arguments
errflg
A logical (true or false) variable that SHF returns to the calling subroutine. If SHF detects
an error in the subroutine call statement, it sets errflg to true before it returns errflg to the
calling subroutine.
value
A double-precision value the subroutine returns. The value returned depends on IORD as
follows
IORD:
Value:
Extended Definition
a sin ( w ( x x0 ) phi ) + b
F(x)
F
-----x
2
-------F2
x
STEP 97
Utility Subroutines
STEP
STEP approximates a step function with a cubic polynomial.
Use
Called By
None
Calling Sequence
CALL STEP (x, x0, h0, x1, h1, iord, value, errflg)
Input Arguments
x0
A double-precision variable that specifies the x value at which the step function begins.
h0
A double-precision variable that specifies the value of the function before the step.
x1
A double-precision variable that specifies the x value at which the step function ends.
h1
A double-precision variable that specifies the value of the function after the step.
iord
An integer variable that defines the order of the derivative that STEP is to return. The order
is usually zero, but it can be one or two.
98 Adams/Solver
Utility Subroutines
Output Arguments
errflg
A logical (true or false) variable that STEP returns to the calling subroutine. If STEP
detects an error in the subroutine call statement, it sets errflg to true before it returns errflg
to the calling subroutine.
value
A double-precision value the subroutine returns. The value returned depends on IORD as
follows:
IORD:
Value:
F(x)
F
-----x
2
-------F2
x
Extended Definition
Figure 1 below demonstrates the step function. For a comparison of STEP and STEP5, and the first
derivatives of STEP and STEP5, see:
STEP (C++ or FORTRAN) function
STEP5 (C++ or FORTRAN) function
STEP 99
Utility Subroutines
The value x is the independent variable, x0 and x1 define the variable values at which the step begins and
ends, h0 and h1 are the initial value and the final value of the step. The equation that defines STEP
follows.
h0
( x x0 ) 2
( x x0 )
STEP = h 0 + ( h 1 h 0 ) -------------------- 3 2 -------------------
( x1 x0 )
( x1 x0 )
h1
;x 0 < x < x 1
;x x 1
;x x 0
For an example of a SENSUB evaluation subroutine that calls STEP, see SENSUB.
Caution:
The value x1 must not equal x0. Equal values of x1 and x0 imply a discontinuous step,
which STEP cannot fit.
100 Adams/Solver
Utility Subroutines
STEP5
STEP5 approximates a step function with a quintic polynomial.
Use
Called By
None
Calling Sequence
CALL STEP5 (x, x0, h0, x1, h1, iord, value, errflg)
Input Arguments
x0
A double-precision variable that specifies the x value at which the step function begins.
h0
A double-precision variable that specifies the value of the function before the step.
x1
A double-precision variable that specifies the x value at which the step function ends.
h1
A double-precision variable that specifies the value of the function after the step.
iord
An integer variable that defines the order of the derivative that STEP5 is to return. The order
is usually zero, but it can be one or two.
STEP5 101
Utility Subroutines
Output Arguments
errflg
A logical (true or false) variable that STEP5 returns to the calling subroutine. If STEP5
detects an error in the subroutine call statement, it sets errflg to true before it returns errflg
to the calling subroutine.
value
A double-precision value the subroutine returns. The value returned depends on IORD as
follows:
IORD:
Value:
F(x)
F
-----x
2
-------F2
x
Extended Definition
Figure 1 below demonstrates the STEP5 function. For a comparison of STEP and STEP5, and the first
derivatives of STEP and STEP5, see:
STEP (C++ or FORTRAN) function
STEP5 (C++ or FORTRAN) function
102 Adams/Solver
Utility Subroutines
The value x is the independent variable, x0 and x1 define the variable values at which the step begins and
ends, h0 and h1 are the initial and values of the step. The equation defining the STEP5 function is:
a = h1 h0
( x x0 )
= --------------------( x1 x0 )
h0
STEP5 = h + a ( 3 [ 10 15 + 6 2 ] )
0
h1
;x 0 < x < x 1
;x x 1
;x x 0
The STEP5 subroutine calling sequence is identical to the STEP subroutine. For an example of a
SENSUB evaluation subroutine that calls STEP5, see SENSUB.
Caution:
The value x1 must not equal x0. Equal values of x1 and x0 imply a discontinuous step,
which STEP5 cannot fit.
SUBTRACT_MASS_PROPERTY 103
Utility Subroutines
SUBTRACT_MASS_PROPERTY
The SUBTRACT_MASS_PROPERTY utility subroutine accepts the mass properties for two parts or
sets of parts and returns the mass properties of the second set minus the mass properties of the first.
Use
Called By
None
Calling Sequence
CALL SUBTRACT_MASS_PROPERTY (cm1, mass1, ip1, cm2, mass2, ip2)
Input Arguments
cm1
A double-precision array of length 3 containing the center of mass of the first part or set
of parts expressed in the GCS (Ground/Global Coordinate System).
mass1
A double-precision variable containing the mass of the first part or set of parts.
ip1
A double-precision array of length 6 giving the 6 independent terms in the inertia tensor
for the first part or set of parts. (Ixx, Iyy, Izz, Ixy, Ixz, Iyz) These inertia terms much be
computed about the center of mass of the part and oriented in GCS.
cm2
A double-precision array of length 3 containing the center of mass of the second part or
set of parts expressed in the GCS.
mass2
ip2
A double-precision array of length 6 giving the 6 independent terms in the inertia tensor
for the second part or set of parts. (Ixx, Iyy, Izz, Ixy, Ixz, Iyz) These inertia terms much
be computed about the center of mass of the part and oriented in GCS.
Output Arguments
cm2
A double-precision array of length 3 containing the center of mass of the second system
minus the first expressed in GCS.
mass2
A double-precision variable containing the mass of the second system minus the first.
Ip2
104 Adams/Solver
Utility Subroutines
Extended Definition
SYSARY 105
Utility Subroutines
SYSARY
The SYSARY data access subroutine provides system state values, such as displacement and velocity, to
your subroutines, and defines and stores the Adams/Solver state variables on which the system states are
dependent.
Use
Called By
CONSUB, DIFSUB, GFOSUB, REQSUB, SENSUB, SFOSUB, VARSUB, VFOSUB, and VTOSUB
Calling Sequence
106 Adams/Solver
Utility Subroutines
Input Arguments
fncnam
A character variable that specifies the name of the function whose data is being requested
from SYSARY. The legal values for fncnam are derived from the list of functions
available to you in the FUNCTION= expression construct. Any one of the following
character strings is legal.
Displacement Functions:
DISP
TDISP
RDISP
UVX
UVY
UVZ
DC
SYSARY 107
Utility Subroutines
Velocity Functions:
VEL
TVEL
RVEL
QDOT
ACC
TACC
RACC
QDDOT
FORCE
TFORCE
RFORCE
PINPUT
POUTPUT
ARRAY
108 Adams/Solver
Utility Subroutines
ipar
An integer array of size nsize that contains the parameter list for function fncnam. The table
above defines the appropriate parameter list types and dimensions for the different
functions available.
nsize
An integer variable that gives the number of parameters that the function fncnam requires.
Its value is dependent on the function name. See the table above for the number of
parameters that function fncnam requires.
Output Arguments
errflg
A logical variable that returns as true if an error occurred during your call to SYSARY.
nstates
An integer variable that returns the number of values Adams/Solver has put in states. Note
that an integer variable must be used here for Adams/Solver to return the number of states.
The value returned in this variable is as defined in the table above.
states
A double-precision array whose size depends on the fncnam (see the table above) that
contains the values that SYSARY returns. When the iflag argument in the user subroutine
is true or when input errors are found, states contains zeros.
Extended Definition
SYSARY returns a set of system states or stores the dependencies of the user value on the set of system
states. You can use the system state values to compute the instantaneous values of a user-defined
function; Adams/Solver uses the dependency on state variables to create the matrix of partial derivatives
(Jacobian) of the system states with respect to the Adams/Solver state variables. Adams/Solver uses the
Jacobian matrix in several analysis computations.
When called from a force evaluation subroutine or from VARSUB, SYSARY returns the current
predicted values of the state. SENSUB is called only after a completed integration state, so SYSARY
returns the converged values when called from SENSUB. REQSUB is called at output steps and, like
SENSUB, SYSARY returns the converged values when called from REQSUB. Therefore, the values
returned from SYSARY are the current values of the state; whether they are the predicted values, or the
corrected values, depends on where you are when calling SYSARY.
You should use SYSFNC (see SYSFNC) to access a single system state corresponding to one modeling
element.
Where SYSFNC evaluates one Adams/Solver function, SYSARY evaluates several with one call. For
example, to evaluate DX(12,10,99), DY(12,10,99) and DZ(12,10,99), you call SYSARY with:
fncnam='TDISP'
ipar(1)=12
ipar(2)=10
ipar(3)=99
nsize=3
SYSARY 109
Utility Subroutines
SYSARY would return the requested x, y, and z displacements in states(1), states(2), and states(3), and
return nstates=3. The following table lists the correspondence of other SYSARY fncnam values to
Adams/Solver function names.
fncnam:
nsize:
nstates:
states:
DISP
1-3
states(1) = DX(i1[,i2,i3])
states(2) = DY(i1[,i2,i3])
states(3) = DZ(i1[,i2,i3])
states(4) = PSI(i1[,i2])
states(5) = THETA(i1[,i2])
states(6) = PHI(i1[,i2])
TDISP
1-3
states(1) = DX(i1[,i2,i3])
states(2) = DY(i1[,i2,i3])
states(3) = DZ(i1[,i2,i3])
RDISP
1-2
states(1) = PSI(i1[,i2])
states(2) = THETA(i1[,i2])
states(3) = PHI(i1[,i2])
NMODES*
--
UVX**
--
UVY**
--
UVZ**
--
DC**
--
VEL
1-4
states(1) = VX(i1[,i2,i3,i4])
states(2) = VY(i1[,i2,i3,i4])
states(3) = VZ(i1[,i2,i3,i4])
states(4) = WX(i1[,i2,i3])
states(5) = WY(i1[,i2,i3])
states(6) = WZ(i1[,i2,i3])
TVEL
1-4
states(1) = VX(i1[,i2,i3,i4])
states(2) = VY(i1[,i2,i3,i4])
states(3) = VZ(i1[,i2,i3,i4])
RVEL
1-3
states(1) = WX(i1[,i2,i3])
states(2) = WY(i1[,i2,i3])
states(3) = WZ(i1[,i2,i3])
QDOT
NMODES*
--
110 Adams/Solver
Utility Subroutines
ACC
1-4
states(1) = ACCX(i1[,i2,i3,i4])
states(2) = ACCY(i1[,i2,i3,i4])
states(3) = ACCZ(i1[,i2,i3,i4])
states(4) = WDTX(i1[,i2,i3,i4])
states(5) = WDTY(i1[,i2,i3,i4])
states(6) = WDTZ(i1[,i2,i3,i4])
TACC
1-4
states(1) = ACCX(i1[,i2,i3,i4])
states(2) = ACCY(i1[,i2,i3,i4])
states(3) = ACCZ(i1[,i2,i3,i4])
RACC
1-4
states(1) = WDTX(i1[,i2,i3,i4])
states(2) = WDTY(i1[,i2,i3,i4])
states(3) = WDTZ(i1[,i2,i3,i4])
QDDOT
NMODES*
FORCE
1-3
states(1) = FX(i1[,i2,i3])
states(2) = FY(i1[,i2,i3])
states(3) = FZ(i1[,i2,i3])
states(4) = TX(i1[,i2,i3])
states(5) = TY(i1[,i2,i3])
states(6) = TZ(i1[,i2,i3])
TFORCE
1-3
states(1) = FX(i1[,i2,i3])
states(2) = FY(i1[,i2,i3])
states(3) = FZ(i1[,i2,i3])
RFORCE
1-3
states(1) = TX(i1[,i2,i3])
states(2) = TY(i1[,i2,i3])
states(3) = TZ(i1[,i2,i3])
PINPUT
n***
states(1) = PINVAL(i1,1)
states(2) = PINVAL(i1,2)
states(3) = PINVAL(i1,3)
.
.
.
states(n) = PINVAL(i1,n)
POUTPUT
n***
states(1) = POUVAL(i1,1)
states(2) = POUVAL(i1,2)
states(3) = POUVAL(i1,3)
states(n) = POUVAL(i1,n)
SYSARY 111
Utility Subroutines
ARRAY
n***
states(1) = ARYVAL(i1,1)
states(2) = ARYVAL(i1,2)
states(3) = ARYVAL(i1,3)
.
.
.
states(n) = ARYVAL(i1,n)
*NMODES (see NMODES) is the number of active modes defined for that flex body. You can use the
utility subroutine NMODES to determine the number of active modes. The ipar(1) array must contain
the id of the flex body of interest.
**Assume that the ipar array contains two markers, I and J. You can specify either I or J to be zero. In
that case, the marker specified as zero defaults to the ground coordinate system.
***Size as specified in the PINPUT, POUTPUT, or ARRAY statement.
When the iflag argument in the user subroutine is true, SYSARY sets up the dependencies of the system
states on the Adams/Solver state variables and sets the states array equal to zero. When the iflag argument
is false, SYSARY returns the instantaneous values of the system states. You can make several calls to
SYSARY, specifying each time the function used, and the parameters of the function.
Tip:
1. Use SYSFNC to access individual states. Quite often, user-defined values depend
on a single-system state such as the x component of the displacement between two
markers, or the z component of the velocity between two markers. While you can
use SYSARY to access the individual components, a single call to SYSFNC is
convenient and more efficient. The use of SYSFNC is therefore recommended
under these circumstances.
2. Use RCNVRT to convert rotational displacements Euler angles to any other angle
representation, for example Adams AX, AY, AZ projected angles.
CALL SYSFNC (`RDISP', IPAR, 2, ANGLES, NSTATE, ERRFLG)
CALL RCNVRT (`EULER', ANGLES, `AXAYAZ', ANGLES, ISTAT)
Use SYSFNC to access individual states.Quite often, user-defined values depend
on a single-system state such as the x component of the displacement between two
markers. While you may use SYSARY to access the individual components, a
single call to SYSFNC is convenient and more efficient. The use of SYSFNC is
therefore recommended under these circumstances.
112 Adams/Solver
Utility Subroutines
Caution:
When the iflag argument is true, you must be sure to make the same SYSARY calls as when
actually computing the results. Adams/Solver passes a parameter iflag to each user-written
subroutine (xxxSUB). It indicates to you whether Adams/Solver is calling the subroutine
for an initialization pass (iflag = true) or for a function evaluation (iflag =false). You must
construct user-written subroutines such that all calls to SYSARY that are made during the
simulation are also invoked when the iflag argument is true. Adams/Solver uses this
information to construct the correct Jacobian matrix.
When unit vectors ('UVX', 'UVY', 'UVZ') are requested, it is possible, due to numerical
roundoff, that the vectors are not of exactly unit length. It is up to the author of the userwritten subroutine to ensure that these roundoff differences do not cause errors. For
example, the term sqrt(1.0-UVX(1)^2-UVX(2)^2) can fail due to a negative argument for
the sqrt() function.
Similarly, the direction cosine matrix ('DC') may not be perfectly orthogonal.
Examples
This example shows properly written calls to SYSARY for UVX, UVY, UVE, and DC.
SUBROUTINE VARSUB (ID, TIME, PAR, NPAR, DFLAG, IFLAG, VALUE)
C
C Inputs:
C
INTEGER ID, NPAR
DOUBLE PRECISION TIME, PAR(*)
LOGICAL DFLAG, IFLAG
C
C Outputs:
C
LOGICAL VALUE
C
C Local Variables:
C
INTEGER IPAR(2), N_UVX, N_UVY, N_UVZ, N_DC, NSIZE
DOUBLE PRECISION UVX(3), UVY(3), UVZ(3), DC(3,3)
LOGICAL ERRFLG
C
C+-----------------------------------------------------*
C
IPAR(1) = NINT (PAR(1))
IPAR(2) = NINT (PAR(2))
NSIZE = 2
C
C Get the directions of the x axis
C
CALL SYSARY ('UVX', IPAR, NSIZE, UVX, N_UVX, ERRFLG)
C
C Get the directions of the y axis
C
SYSARY 113
Utility Subroutines
This example shows properly written calls to SYSARY for Q, QDOT, and QDDOT, as well as an
associated use of the utility subroutines NMODES and MODINF.
SUBROUTINE VARSUB ( ID, TIME, PAR, NPAR, DFLAG,
& IFLAG, VALUE)
C
C === Type and dimension statements ===================
C
C Note: For machines with 60 or more bits per word,
C substitute "REAL" for "DOUBLE PRECISION".
C
C --- External variable definitions ------------------C
INTEGER ID
DOUBLE PRECISION TIME
DOUBLE PRECISION PAR( * )
INTEGER NPAR
LOGICAL DFLAG
LOGICAL IFLAG
DOUBLE PRECISION VALUE
C
C ID Identifier of calling VARIABLE statement
C TIME Current time
C PAR Array of passed statement parameters
C NPAR Number of passed parameters
C DFLAG Differencing flag
C IFLAG Initialization pass flag
C VALUE The VARIABLE value returned to ADAMS
C
C --- Local variables --------------------------------C
INTEGER NARG
PARAMETER (NARG = 1)
INTEGER MAXQ
PARAMETER (MAXQ = 100)
C
CHARACTER*60 STRING
CHARACTER*8 FNCNAM
114 Adams/Solver
Utility Subroutines
SYSARY 115
Utility Subroutines
DO 40 I=1,NQ
IF (FREQ(I) .LT. MAXFRQ) VALUE = VALUE + C3*Q(I)
40 CONTINUE
C
RETURN
END
For other examples that use the SYSARY data access subroutine, see the evaluation subroutines
VFOSUB and VTOSUB.
116 Adams/Solver
Utility Subroutines
SYSFNC
The SYSFNC subroutine provides a single-system state value, such as displacement or velocity, to your
subroutines, and defines and stores the Adams/Solver state variables on which the system state is
dependent.
Use
Called By
CONSUB, DIFSUB, GFOSUB, REQSUB, SENSUB, SFOSUB, VARSUB, VFOSUB, and VTOSUB
Calling Sequence
SYSFNC 117
Utility Subroutines
Input Arguments
fncnam
A character variable specifying the name of the function whose data is being requested
from SYSFNC. The legal values for fncnam are derived from the list of functions
available to you in the FUNCTION= expression construct. Note that this function
requires single quotes. For example,
CALL SYSFNC (`DX', IPAR, 2, DX, ERRFLG)
Here, the DX characters needs to be in single quotes.
Any of the following character strings are legal:
Functions/
variables:
Displacement
Velocity
Character strings: 1
DM, DX, DY, DZ, AX, AY, AZ, PSI, PHI, THETA, YAW, PITCH,
ROLL
VM, VR, VX, VY, VZ, WM, WX, WY, WZ
Acceleration
Generic force
Elementspecific force
Note:
ipar
An integer array containing the parameter list for fncnam. It consists of any valid list of
parameters used in the associated Adams/Solver function, just as they would appear in a
dataset FUNCTION = expression.
nsize
118 Adams/Solver
Utility Subroutines
Output Arguments
errflg
A logical variable that returns true if an error has occurred during your call to SYSFNC.
state
A double-precision variable returned by SYSFNC. State is zero when the iflag argument
is set to true in the user-written subroutine, or when input errors are found.
Extended Definition
The SYSFNC subroutine provides system-state values (such as displacement and velocity) to user
subroutines, and defines and stores the Adams/Solver state variables on which the system state is
dependent.
SYSFNC returns one system state or stores the dependency of the user value on the system state. You use
the system state values to compute the instantaneous value of a user-defined function: Adams/Solver uses
the dependency on state variables to create the matrix of partial derivatives (Jacobian) of the system state
with respect to the Adams/Solver state variables. Adams/Solver uses the Jacobian matrix in several
analysis computations.
If you need to access several system states corresponding to one modeling element, you should use
SYSARY (see SYSARY).
SYSFNC requires that you specify system-state information as requested from Adams/Solver as a series
of function call specifications. This is almost as if you were using the function expression capabilities to
obtain the system state. For example, to request DX(12,10,99), you can call SYSFNC with fncnam='DX',
ipar(1)=12, ipar(2)=10, ipar(3)=99, and nsize=3.
When the iflag argument in the user subroutine is true, SYSFNC sets up the dependencies of the system
states on the Adams/Solver state variables and sets state equal to zero. When the iflag argument is false,
SYSFNC returns the instantaneous values of the system states.
Tip:
Use SYSARY to simultaneously access several states. Quite often, user-defined values
depend on a set of related system states such as all displacement components between two
markers, or all velocity components between two markers. While SYSFNC can be called
several times to access the individual components, a single call to SYSARY is not only
more convenient, but more efficient. Therefore, we recommend that you use SYSARY
under these circumstances.
SYSFNC 119
Utility Subroutines
Caution:
When the iflag argument is true, you must be sure to make the same SYSFNC calls as when
actually computing the results. Adams/Solver passes a parameter iflag to each user-written
subroutine (xxxSUB). It indicates to you whether Adams/Solver is calling the subroutine
for an initialization pass (iflag = true) or for a function evaluation (iflag = false). You must
construct user-written subroutines such that all calls to SYSFNC that are made during the
simulation are also invoked when the iflag argument is true. Adams/Solver uses this
information to construct the correct Jacobian matrix.
Examples
For examples using the SYSFNC data access subroutine, see the evaluation subroutines SFOSUB and
VARSUB.
120 Adams/Solver
Utility Subroutines
SYSPAR
The SYSPAR subroutine lets you supply the analytical partial derivatives of a subroutine with respect to
values measured through SYSFNC and SYSARY.
When you supply analytical partial derivatives, Adams/Solver does not need to resort to finite
differencing to approximate these partial derivatives. Therefore, you potentially improve both accuracy
and speed.
SYSPAR can be used for any number (all, some, or none) of the SYSFNC or SYSARY calls made from
your subroutine.
You can also use SYSPAR intermittently. For example, you can use it only during the first half of the
simulation. Adams/Solver will use the values you provide, when you provide them, and compute them
automatically when you do not.
Note:
SYSPAR works primarily in the Adams/Solver (C++) or with the GSE statement
in Adams/Solver FORTRAN.
Use
Called By
fncname
A character variable specifying the name of the function corresponding to the partial
derivatives that are being provided. The legal values for fncname are derived from the
list of functions available to you in the FUNCTION = expression construct.
Depending on the subroutine you are calling, see either SYSARY or SYSFNC for a list
of legal characters.
iparam
An integer array containing the parameter list for fncnam. It consists of any valid list
of parameters used in the associated Adams/Solver function, just as they would appear
in a dataset FUNCTION = expression.
nparam
partl
npartl
Number of partial derivatives in partl. Adams/Solver compares this number with the
number that it expects, and issues an error message if you provide an incorrect number
of partial derivatives.
SYSPAR 121
Utility Subroutines
Output Arguments
errflg
A logical variable that returns true if an error has occurred during your call to SYSPAR.
Extended Definition
Adams/Solver offers a number of user subroutines that you can use to define the value of Adams
variables, differential equations, forces, and so on. The subroutines return values of dimension 1, 3, or 6.
Usually, the subroutines have a dependency on system states through measurements of the system state
provided by a functional interface, SYSFNC and SYSARY. We define the following nomenclature:
F - The value computed by the user subroutine
Mi - The ith measured value
q - The system generalized coordinates
and observe that, in general:
F(M1(q), M2 (q), ..., MN (q))
Because the user subroutine is effectively a black box, all that Adams/Solver knows about this function
is that it depends on the measures, Mi, that you call through SYSFNC/SYSARY.
During its analyses, Adams/Solver must construct a Jacobian matrix of the system of equations. For this
purpose, Adams/Solver requires the partial derivatives,
F
------ , of the function relative to the systemq
generalized coordinates, q.
The FORTRAN 77 version of Adams/Solver approaches the problem of computing these partial
derivatives in a direct manner, by altering the system states:
F ( qi + ) F ( qi )
F
------ = ----------------------------------------q
We refer to this scheme as finite differencing or, more specifically, forward differencing. This approach
has two main problems:
Some Adams elements, particularly the FLEX_BODY element, can have an extremely large
number of generalized coordinates. Computing the partial derivatives in this way can be quite
time consuming. Note that during finite differencing the user subroutine must be evaluated once
for each state, qi, on which it depends.
You cannot assist Adams/Solver in the evaluation of the partial derivatives because you do not
122 Adams/Solver
Utility Subroutines
F
------=
q i
j=1
F- M
----------------j =
M j q i
j=1
F ( M j + ) F ( M j ) M j
--------------------------------------------- --------
q i
Note that in keeping with the observation that F is a black box, Adams/Solver continues to rely
on finite differencing to compute
F
--------, where Mj is well known and its partial derivatives can
M j
F
--------may be straightforward. Adams/Solver (C++) provides
M j
SYSPAR: an interface you can use to register these partial derivatives, in the cases where they
are known and can be efficiently computed.
Note that the potential of user-provided partial derivatives does not only affect the computational
cost of evaluating the system Jacobian, but can also improve the accuracy of simulations and the
rate of convergence. This is because your analytical derivatives are likely to be more accurate
than those obtained using finite differencing. When Adams/Solver uses the Jacobian directly, as
in Adams/Linear, the quality of the solution may also be improved.
When F and M have dimension greater than 1, the partial matrix,
F
--------should be stored in partl
M j
in FORTRAN 77 style column order. In other words, all the partial derivatives of F with respect
to the first component of M come before the partial derivatives of F with respect to the second
component of M, and so on.
Each call to SYSFNC/SYSARY creates what the previous section refers to as a measure. For
each of these measures, the creator of the user subroutine is allowed to register the partials of the
function with respect to this measure.
You do not need partial derivatives during every call to the user's subroutine, because they are
only needed when the Jacobian is being evaluated. You must request the flag that indicates
whether the partial derivatives are required, by calling the following function:
SYSPAR 123
Utility Subroutines
CALL ADAMS_NEEDS_PARTIALS(PARFLG)
Note that, ideally, the PARFLG would have been added to the user subroutine call, alongside
IFLAG and DFLAG, but the user subroutines have a standard interface that cannot be changed.
You can make calls to SYSPAR only for those SYSFNC/SYSARY for which partials are
conveniently available. As mentioned earlier, you can make SYSPAR calls intermittently. In
other words, you can call SYSPAR only during some period of the simulation when partials can
be easily computed, but skipped during other parts of the simulation. For example, when an
impact force is zero, its partials are trivially zero.
Caution:
SYSPAR is optional. You should expect the number of function evaluations and CPU time
to decrease. If they do not, you may have made a mistake.
When you do not provide partial information, Adams/Solver fills in the blanks using finite
differencing.
It is, of course, an error to call SYSPAR without a matching call to SYSFNC or SYSARY.
Examples
F--------= VZ ( 1, 2 )
M 1
and
F--------= DX ( 1, 2 )
M 2
The SFOSUB implementation follows:
SUBROUTINE SFOSUB (ID, TIME, PAR, NPAR, DFLAG, IFLAG, VALUE)
INTEGER ID
DOUBLE PRECISION TIME
DOUBLE PRECISION PAR( * )
INTEGER NPAR
124 Adams/Solver
Utility Subroutines
LOGICAL DFLAG
LOGICAL IFLAG
DOUBLE PRECISION VALUE
This SFOSUB example shows how you can use SYSPAR in conjunction with utility subroutines. In this
SFOSUB you have:
VALUE = -IMPACT(400-DM(12,9),-VR(12,9))
where M1 = DM(12,9) and M2 = VR(12,9). Here, you must rely on the ability of the IMPACT utility
function to provide partial derivatives of its arguments.
FIMPACT
--------= -------------------------- ( 400 M 1 M 2 ) ( 1 )
M 1
M 1
F
IMPACT
---------= -------------------------- ( 400 M 1 M 2 ) ( 1 )
M 2
M 2
The implementation follows. Pay close attention to the use of the IORD argument (argument 8) to the
IMPACT function. It controls whether 0th, 1st, or 2nd derivative of the impact is being requested. Learn
more about the IMPACT function (C++ or FORTRAN).
SUBROUTINE SFOSUB (ID, TIME, PAR, NPAR, DFLAG, IFLAG, VALUE)
INTEGER ID
SYSPAR 125
Utility Subroutines
where DISP and VELO are the displacement and velocity of the I and J markers of the field element that
are input to FIESUB. FIESUB computes the 6D value of the force, FIELD. Also, when DFLAG is TRUE,
you must provide the partial derivatives with respect to displacement, DFDDIS, and the partial
derivatives with respect to velocity, DFDVEL. Learn more about FIELD (C++ or FORTRAN).
The removal of the advantage of FIESUB over GFOSUB is demonstrated by implementing the FIESUB
in a GFOSUB:
SUBROUTINE GFOSUB (ID, TIME, PAR, NPAR, DFLAG, IFLAG, RESULT)
INTEGER ID
DOUBLE PRECISION TIME
DOUBLE PRECISION PAR( * )
INTEGER NPAR
LOGICAL DFLAG
LOGICAL IFLAG
DOUBLE PRECISION RESULT(6)
DOUBLE PRECISION DISP(6), VELO(6)
DOUBLE PRECISION DFDDIS(6,6), DFDVEL(6,6)
126 Adams/Solver
Utility Subroutines
INTEGER IPAR(4)
LOGICAL ERRFLG, PARFLG
C
C This GFOSUB should never be finite differenced
C
CALL ERRMES(DFLAG,'DFLAG=.TRUE. UNEXPECTED',ID,'STOP')
C
C Check if partials are needed
C
CALL ADAMS_NEEDS_PARTIALS(PARFLG)
C
C Measure displacements, projection angles and velocity
C between markers I and J (PAR(1) and PAR(2)). Note that
C velocity measure takes four marker arguments because
C FIESUB uses velocity of I wrt J in coordinate system
C of J with observer in J.
C
IPAR(1)=NINT(PAR(1))
IPAR(2)=NINT(PAR(2))
IPAR(3)=NINT(PAR(2))
IPAR(4)=NINT(PAR(2))
C
CALL SYSARY('TDISP', IPAR, 3, DISP, 3, ERRFLG )
CALL SYSFNC('AX', IPAR, 2, DISP(4), ERRFLG )
CALL SYSFNC('AY', IPAR, 2, DISP(5), ERRFLG )
CALL SYSFNC('AZ', IPAR, 2, DISP(6), ERRFLG )
CALL SYSARY('VEL', IPAR, 4, VELO, 6, ERRFLG )
IF(PARFLG) THEN
DO 100 I = 1 , 6
DO 100 J = 1 , 6
DFDDIS(I,J)=0.D0
DFDVEL(I,J)=0.D0
100 CONTINUE
ENDIF
C
C Subtract the free length, PAR(3),...,PAR(8)
C
DO 200 I = 1 , 6
DISP(I)=DISP(I)-PAR(I+2)
200 CONTINUE
CALL FIESUB(ID, TIME, PARS, NPAR, DISP, VELO, PARFLG, IFLAG,
+ VALUE, DFDDIS, DFDVEL)
IF (PARFLG) THEN
CALL SYSPAR('TDISP', IPAR, 3, DFDDIS, 18, ERRFLG)
CALL SYSPAR('AX', IPAR, 2, DFDDIS(1,4), 6, ERRFLG)
CALL SYSPAR('AY', IPAR, 2, DFDDIS(1,5), 6, ERRFLG)
CALL SYSPAR('AZ', IPAR, 2, DFDDIS(1,6), 6, ERRFLG)
CALL SYSPAR('VEL', IPAR, 4, DFDVEL, 36, ERRFLG)
ENDIF
RETURN
END
SYSPAR 127
Utility Subroutines
Debugging
When modifying a user subroutine by adding SYSPAR calls, you may be concerned about the correctness
of the partial derivatives. In this case, you can define the environment variable MDI_DEBUG_SYSPAR.
When this environment variable is set, Adams/Solver uses finite differencing to verify the user-provided
partial derivative and write debug information to the standard output (the terminal). For example:
SFOSUB(1): DZ(1,11) A: 5.00000E+00 U: 2.06158E+11
which informs you that during the verification of the SFOSUB for SFORCE/1, you provided the value
2.06158E+11 for the partial derivative with respect to the DZ(1,11) measure, but Adams/Solver found,
using finite differencing, that this value should be 5.0. A closer inspection of the source code reveals that
it contained single precision:
CALL SYSPAR('DZ', IPAR, 2, 5., 1, ERRFLG)
rather than double precision:
CALL SYSPAR('DZ', IPAR, 2, 5.D0, 1, ERRFLG)
Computing Partial Derivatives
1. Apply the ADIFOR Preprocessor to your FORTRAN 77 program to produce augmented code for
the computation of derivatives. The preprocessor invokes the ADIntrinsics template expander
directly.
2. Construct a derivative driver code that invokes the generated derivative code and uses the
computed derivatives.
3. Compile the generated derivative code and your derivative driver code, and link these with the
derivative support packages. That is, the ADIntrinsics exception handling package and
(optionally) the SparsLinC sparse derivative package.
128 Adams/Solver
Utility Subroutines
To retrieve the ADIFOR 2.0 automatic differentiation software for educational and non-profit research
use, and for commercial evaluation, visit either of the ADIFOR group Web sites, at:
http://www.mcs.anl.gov/adifor or http://www.cs.rice.edu/~adifor. These pages describe how to request
access to ADIFOR 2.0 and download the software. The pages also contain links to publications related
to ADIFOR, as well as legal notices.
TCNVRT 129
Utility Subroutines
TCNVRT
TCNVRT converts translational coordinates from one representation to another.
Use
Called By
None
Calling Sequence
sys1
A character string specifying the system in which the values passed in coord1 were
determined. The possible character strings and their meanings are:
CARTESIAN - Cartesian coordinates (x, y, and z).
CYLINDRICAL - Cylindrical coordinates (radius, theta, and z).
SPHERICAL - Spherical coordinates (radius, phi, and theta).
Note:
Do not confuse this phi and theta with the Euler angles named phi and theta.
coord1
sys2
A character string specifying the system in which the values returned as output in coord2
are to be determined. Possible character strings are the same as those for sys1.
130 Adams/Solver
Utility Subroutines
Output Arguments
coord2
istat
An integer variable indicating either the success or the reason for the failure of the call
to TCNVRT.
If:
Then:
istat= 0
istat= -1
istat= -2
Extended Definition
MOTSUB, REQSUB, or SFOSUB can call TCNVRT to change the Cartesian coordinates used to specify
a displacement vector to cylindrical coordinates.
TIMGET 131
Utility Subroutines
TIMGET
TIMGET returns the simulation time corresponding to the last successful simulation step.
Use
Called By
time
A double-precision scalar that contains the simulation time at the end of the last successful
step.
Extended Definition
TIMGET is primarily useful in situations where past values of system states are to be used in defining
the current values of system. In some applications, you need to determine when a specific time has been
successfully passed in the simulation. The value of the time argument passed to user-written subroutines
is the current simulation time, and is therefore not a reliable indicator of the last successful simulation
time. Moreover, if convergence at the current time is not achieved, Adams/Solver backs up to the last
successful simulation step and tries a new step.
The value of simulation time returned by TIMGET represents a successful simulation time.
Adams/Solver never backs up over this time again.
Digital control systems are instances where the values provided by TIMGET are useful. Digital control
systems are characterized by the fact that observations of system states are taken at pre-specified regular
intervals named sampling periods. Based on the system states sampled and the governing control laws,
forces acting on the system are defined. These forces are held constant until the next sample period,
regardless of how the system state changed.
Make sure that you only sample converged values of system states when determining the current system
state. TIMGET is useful in this context, because it provides to user subroutines a record of when a set of
system states have converged.
Tip:
SENSUB has commonly been used to identify a successful simulation step. You don't need
to rely on TIMGET anymore.
132 Adams/Solver
Utility Subroutines
UNSERIALIZE_CHARACTERS
UNSERIALIZE_CHARACTERS allows you to reload character data into your user subroutines when
Solver is executing a RELOAD/ command.
Use
Called By
Output Argument
c_array
Example
F77
IF(IFLAG .EQ. 3)THEN
... Make calls to sysfnc and sysary to set up dependencies ...
ELSEIF (IFLAG .EQ. 7)THEN
CALL SERIALIZE_CHARACTERS(C_DATA, LEN(C_DATA))
ELSEIF (IFLAG .EQ. 9)THEN
CALL UNSERIALIZE_CHARACTERS(C_DATA, LEN(C_DATA))
ENDIF
CXX:
switch(IFLAG){
case 3:
... Make calls to c_sysfnc and c_sysary to set up dependencies ...
break;
case 7:
c_dataSize = strlen(c_data)+1;
c_adams_serialize_integers(&c_dataSize, 1);
c_adams_serialize_characters(c_data, c_dataSize);
break;
UNSERIALIZE_CHARACTERS 133
Utility Subroutines
case 9:
if(c_data)free(c_data);
c_adams_unserialize_integers(&c_dataSize, 1);
c_data = (char*) malloc(sizeof(char)*c_dataSize);
c_adams_unserialize_characters(c_data, c_dataSize);
break;
134 Adams/Solver
Utility Subroutines
UNSERIALIZE_DOUBLES
UNSERIALIZE_DOUBLES allows you to reload double precision data into your user subroutines when
Solver is executing a RELOAD/ command.
Use
Called By
Output Argument
d_array
Example
F77:
IF(IFLAG .EQ. 3)THEN
... Make calls to sysfnc and sysary to set up dependencies ...
ELSEIF (IFLAG .EQ. 7)THEN
CALL SERIALIZE_DOUBLES(DP_DATA, N_DP_DATA)
ELSEIF (IFLAG .EQ. 9)THEN
CALL UNSERIALIZE_DOUBLES(DP_DATA, N_DP_DATA)
ENDIF
CXX:
switch(IFLAG){
case 3:
... Make calls to c_sysfnc and c_sysary to set up dependencies ...
case 7:
c_adams_serialize_integers(&d_dataSize, 1);
c_adams_serialize_doubles(d_data, d_dataSize);
break;
case 9:
c_adams_unserialize_integers(&d_dataSize, 1);
if( d_data )free(d_data);
UNSERIALIZE_DOUBLES 135
Utility Subroutines
136 Adams/Solver
Utility Subroutines
UNSERIALIZE_INTEGERS
UNSERIALIZE_INTEGERS allows you to reload integer data into your user subroutines when Solver
is executing a RELOAD/ command.
Use
Called By
Output Argument
i_array
Example
F77:
IF(IFLAG .EQ. 3)THEN
... Make calls to sysfnc and sysary to set up dependencies ...
ELSEIF (IFLAG .EQ. 7)THEN
CALL SERIALIZE_INTEGERS(I_DATA, N_I_DATA)
ELSEIF (IFLAG .EQ. 9)THEN
CALL UNSERIALIZE_INTEGERS(I_DATA, N_I_DATA)
ENDIF
CXX:
switch(IFLAG){
case 3:
... Make calls to c_sysfnc and c_sysary to set up dependencies
...
case 7:
c_adams_serialize_integers(&i_dataSize, 1);
c_adams_serialize_integers(i_data, i_dataSize);
break;
case 9:
UNSERIALIZE_INTEGERS 137
Utility Subroutines
c_adams_unserialize_integers(&i_dataSize, 1);
if( i_data )free(i_data);
d_data= (int*) malloc(sizeof(int)*i_dataSize);
c_adams_unserialize_integers(i_data, i_dataSize);
break;
138 Adams/Solver
Utility Subroutines
UCOVAR
UCOVAR is used with UCOSUB, to tell Adams/Solver the part states that are used in the user-defined
constraint.
Use
Called By
UCOSUB
Prerequisite
id
An integer variable that specifies the ID of the UCON statement for which you are defining
the variables. Use the identifier in the UCOSUB argument list.
nparts
An integer variable that specifies the total number of elements in the array lparts. The value
of nparts must equal the value of nvars.
lparts
An integer array that lists the part identifiers corresponding to the variable types in lvars.
The number of part identifiers in lparts must equal the number of integer codes in lvars.
Thus the lparts and lvars arrays must be equal in length.
UCOVAR 139
Utility Subroutines
nvars
An integer value that indicates the total number of integer codes in lvars. The value of
nvars must equal the value of nparts.
The function:
Means that:
11
12
13
14
15
16
21
22
23
24
25
26
Note that the tens digit is one for displacement codes and two for velocity codes. Also, note
that the ones digit indicates a translational or a rotational component with an integer from
one to six. All translational variable values refer to the motion of the part center-of-mass,
and all rotational variable values refer to the rotation of the principal axes, with respect to
the ground reference frame. The number of integer codes in lvars must equal the number
of part identifiers in lparts. Therefore, the lvars and lparts arrays must be equal in length.
lvars
An integer array that contains the integer codes that identify the variables involved in the
constraint. The table below defines the codes that lvars can contain.
Extended Definition
UCOVAR tells Adams/Solver which of the principal axes coordinates are used in the user-defined
constraint. Adams/Solver subsequently passes these to the evaluation subroutine UCOSUB in the array
140 Adams/Solver
Utility Subroutines
q. UCOSUB should call UCOVAR in response to a true initialization flag (iflag). For an example of a
UCOSUB evaluation subroutine that calls UCOVAR, see UCOSUB.
Caution:
The arrays lparts and lvars can contain as many as thirty values. Don't attempt to
load and pass these two arrays with more than thirty values in each.
When selecting the displacements or the velocities of the part principal axes for the
constraint, remember that the part principal axes are not always identical to those
of the part center-of-mass marker (cm). The following list summarizes the
circumstances in which the part principal axes may differ from those of the part
center-of-mass marker.
When the PART statement does not include the CM argument, the principal
USRMES 141
Utility Subroutines
USRMES
USRMES allows you to output messages for information or for documenting errors that occur in userwritten subroutines.
Use
Called By
None
Calling Sequence
id
An integer variable that specifies the ID of the statement that is currently invoking the
user-written subroutine.
mesage
A character string or variable of as many as 1024 characters that you want USRMES
to document. This character string should be a descriptive message and should include
the name of the subroutine issuing the message.
msgflg
msgtyp
A character variable that indicates what type of message is given. msgtyp can have one
of four values:
INFO - For information messages
WARN - For warnings
ERROR - For error messages
FAULT - For fatal error messages
INFO_NOPAD - Prints out the information message but without the
USRMES:USER1 tag before the message
LOGINF - Writes out the message in the message file but doesnt print it out on the
screen
If msgtyp has any other value, Adams/Solver issues an information message.
142 Adams/Solver
Utility Subroutines
Extended Definition
USRMES allows you to output messages from user-written subroutines. The messages always go to the
Message File, and during interactive execution, Adams/Solver displays them on the screen.
USRMES 143
User-Written Subroutines
User-Written Subroutines
User-written subroutines, while a little more difficult to use, provide a degree of generality, efficiency
and flexibility that function expressions do not. Subroutines allow you to use FORTRAN-77 features to
define functions not otherwise available with Adams/Solver, and to tailor Adams/Solver to your needs.
By linking in user-written subroutines, you don't lose any efficiency or decrease the simulation speed.
Subroutines and function expressions serve essentially the same purpose: they both allow you to define
non-standard input to Adams.
Function expressions are easier to work with, because you don't have to compile or link programs. Also,
they work on every machine on which Adams/Solver is available. User-written subroutines, however, are
much more general. The power of the programming language is available to define modeling elements
or special output.
On the other hand, function expressions support a limited set of programming constructs. Therefore,
complicated phenomena, especially those involving a lot of logic, cannot be easily described using
function expressions.
You use user-written subroutines when:
Dataset functions become awkward.
You need to define functions used by a group of users.
Statements, such as GSE and UCON, require them.
You want to control the running of complex simulations that require decision-making logic.
Write user-written subroutines with care because incorrectly coded subroutines are very difficult to
debug. Follow a crawl-walk-run approach for developing user subroutines. Start with simple versions of
a user-written subroutine, make sure it works as desired, then gradually increase the complexity of the
subroutine. Make sure that there are no compiler or linker warnings when your subroutine is linked into
Adams.
The "C" style interface to user subroutines has been enhanced to replace some of the arguments with a
pointer to a structure. This will require changes to your user subroutine source code. If you are using the
fortran style interface to user subroutines you will not be effected and no changes will be required.
The new argument list to the "C" style interface replaces some of the arguments with a pointer to a
structure. This structure contains the replaced arguments plus additional information. Old arguments
such as ID, PAR, and NPAR have been incorperated into the structure. New arguments such as marker
id's have been added to the structure.
144 Adams/Solver
User-Written Subroutines
Basics
Driver Subroutine
The driver subroutine, CONSUB, drives Adams/Solver. It lets you further automate the analysis and
modification of Adams/Solver models by defining your own sequence of events or data flow within a
simulation. It is a very powerful tool, so you will probably not need to use it unless you are an advanced
Adams/Solver user.
With CONSUB you can issue commands to request, regulate, and vary one or more Adams/Solver
simulations. Using a CONSUB, you can issue interactive commands to modify a dataset and/or run many
different analyses. The most common modes for running Adams/Solver simulations are interactive or
batch processing, involving a single analysis at a time. Using CONSUB, you can, for example, perform
a dynamic analysis of a dataset, vary a statement, and repeat the dynamic analysis.
Evaluation Subroutines
The evaluation subroutines allow you to tailor Adams modeling elements to individual applications.
Evaluation subroutines are user-defined elements. Many Adams/Solver statements allow you to write
subroutines to evaluate nonstandard or complex values for statements (see the table below).
The following table lists the names and definitions for the evaluation subroutines:
Adams/Solver
Statement/Command:
Subroutines:
Do the following:
CONTROL
CONSUB
COUPLER
COUSUB,
COUXX,
COUXX2,
CURVE
CURSUB
DIFF
DIFSUB
FLEX_BODY
DMPSUB
Basics 145
User-Written Subroutines
Adams/Solver
Statement/Command:
Subroutines:
Do the following:
FIELD
FIESUB
GFORCE
GFOSUB
GSE
GSE_DERIV,
GSE_UPDATE,
GSE_OUTPUT,
GSE_SAMP
MFORCE
MFOSUB
MOTION
MOTSUB
RELOAD
RELSUB
REQUEST
REQSUB
SAVE
SAVSUB
SENSOR
SENSUB
SFORCE
SFOSUB
UCON
UCOSUB
VARIABLE
VARSUB
VFORCE
VFOSUB
VTORQUE
VTOSUB
Restart Subroutines
The two restart subroutines, SAVSUB and RELSUB, allow you to save and reload any data that might
be necessary to restart or reinitialize other user-written subroutines following a RESTART command.
You only need to use them if other user-written subroutines store data internally from call to call. Unless
you use RELSUB and SAVSUB, the internal data is lost when you save a simulation and then later reload
it into an Adams/Solver run.
The SAVE command allows you to save model and simulation data to a save file. You can then restart a
simulation from the saved point, by reloading the save file using the RELOAD command. The SAVE and
146 Adams/Solver
User-Written Subroutines
RELOAD commands do not, however, take any special action to restart user-written subroutines. After
a RELOAD, Adams/Solver continues calling user-written subroutines just as it would have at the time
you saved the file.
For example, if an SFOSUB computes force coefficients when first called and then stores them for later
use, they can be lost during a SAVE and RELOAD. You could write a SAVSUB to save the coefficients
in the save file and a RELSUB to re-read them, or you could write only a RELSUB to recompute the
coefficients. Either way, when you issue a RELOAD command, the SFOSUB regains the proper
coefficients.
If, however, an SFOSUB uses only the information that Adams/Solver passes through the PAR array and
information from utility subroutines, then a SAVSUB and RELSUB are not required because the
SFOSUB is not relying on any past data.
Guidelines
The following sections provide general guidelines for writing user-written subroutines:
Subroutine Arguments
Declaring Variables
Using Parameters to Make Subroutines More General
Avoiding Discontinuities
FORTRAN Input/Output Units
Subroutine Arguments
corresponding command or statement, or from calculations indicating the current system state.
Do not change the values of these input arguments.
Output arguments provide Adams/Solver with information you have derived. Unless explicitly
stated otherwise, you should always supply values for output arguments.
Input and output arguments are in lowercase letters to indicate that you can choose any legal FORTRAN
variable for the argument name. Input arguments are listed first, followed by output arguments. Because
FORTRAN uses argument order to distinguish between arguments, you must not change the order of
arguments when passing them to, or when receiving them from, subroutines. Also, for each argument,
use a variable of the proper type and dimension. For information on variables, see the next section.
Declaring Variables
To ensure that values are properly transferred between your subroutines and Adams/Solver subroutines,
you need to declare your subroutine arguments with the same type that Adams/Solver uses.
Floating Point Variables
Basics 147
User-Written Subroutines
On 32-bit machines (most UNIX and Windows machines), Adams/Solver uses DOUBLE PRECISION
floating-point variables. Because an untyped floating-point variable usually defaults to single-precision
(that is, REAL), you must explicitly declare all your floating-point variables to be DOUBLE
PRECISION.
Integers
Adams/Solver always supplies to user-written subroutines the parameter values from the
FUNCTION=USER() argument on the corresponding statement or command. If you use
FUNCTION=USER (4.0, 5.0, 6.0), for example, Adams/Solver passes a PAR array containing the values
4.0, 5.0, and 6.0, and passes NPAR containing the value of 3.
You can use this feature to make your subroutines more flexible. If your calculations depend on the
distance between markers 101 and 201, for example, you could write these identifiers directly in your
subroutine. If, however, you wanted to change the marker identifiers or use the subroutine with a different
model, you would have to edit the FORTRAN file, recompile, and then relink with Adams/Solver.
You can avoid these time-consuming changes by putting the marker identifiers in the
FUNCTION=USER() argument and then using them as variables in your subroutine. If you want to
change them, you only need to change the FUNCTION=USER() argument in your statement or
command, then re-run Adams/Solver with the same library.
Avoiding Discontinuities
As with run-time expressions, when using a subroutine to define motions, sensors, forces, or state
equations in a model, you must ensure that these functions are continuous. Furthermore, when defining
displacement-based motions, these functions are expected to be twice differentiable.
Discontinuous functions are difficult to handle because most numerical integration schemes require, and
therefore assume, that system equations are inherently continuous. If you violate this rule, Adams/Solver
could produce unexpected results such as integration failure at the discontinuity. Discontinuous functions
are created most often when using IF statements to piece together separate functions. To ensure that the
complete function is indeed continuous, be very careful when using this type of logic.
Other discontinuous functions available in the FORTRAN language:
MIN
MAX
DIM
SIGN
MOD
148 Adams/Solver
User-Written Subroutines
If you need to read or write files from your user-written subroutines, use FORTRAN units 90 and above.
Adams/Solver reserves these units for your use.
Writing Subroutines
To help you create your own user-written subroutines, we have provided subroutine templates in the
directory /install_dir/adams/solver/usersubs (install_dir is the directory where the Adams products are
installed). If you can't find this directory, please see your system administrator.
Templates in C format are not currently available. If you need a C-formatted subroutine, you must create
it by modifying the FORTRAN file, or creating your own using the FORTRAN template as your guide.
For more information on using C-formatted subroutines, see Knowledge Base Article 8384.
To write a user-written subroutine:
1. Determine which user-written subroutine you need to use. For example, if you have a GFORCE
statement, you need to create a GFOSUB user-written subroutine.
2. Determine what you need to calculate, and what the input parameters are. This information
determines the information you pass from the FUNCTION=USER() argument in the statement to
the subroutine.
3. Copy the appropriate user-written subroutine template from the installation directory to your local
directory. The template directory contains all the subroutine templates you might need to use.
4. View the user-written subroutine template using a text editor.
5. Modify the user-written subroutine as desired. You can call a utility subroutine or other
FORTRAN or C subroutines from within the user-written subroutine.
6. Save your user-written subroutine. Give the file a descriptive name because you may want to use
the same subroutine for different models.
Basics 149
User-Written Subroutines
User-written
Adams
Subroutine #1
User-written
Adams
Subroutine #2
Pre-defined
Adams Library
User-written
Adams
Subroutine #N
User-written
Generic
Subroutine #N
Standard
Adams/Solver
Executable
Custom
Library (.dll)
where:
150 Adams/Solver
User-Written Subroutines
id - Adams/Solver identification number of the statement calling the subroutine (for example,
numeric differencing (logical variable set to true); typically used for debugging or more
advanced management of numeric differencing
iflag - Initialization flag indicating that Adams/Solver is calling the subroutine for the first time
Note:
The actual names of the arguments do not matter. For example, value could be called result.
It is the order of the arguments that is important.
2. Compile each subroutine individually with the flags specified by Adams, as specified in
Compiling Subroutines.
Note: If source code is supplied, the script will automatically compile the files for you.
3. Link all object files into one user library. For example:
On Windows: adams03 cr-user myvarsub.obj yourreqsub.obj n my_lib.dll
On UNIX: adams03 c cr-user myvarsub.f yourreqsub.f n my_lib.so
Here, both object files are linked into one library, my_lib.[dll,so,sl].
Basics 151
User-Written Subroutines
2. Consolidate your Adams subroutines based on type (for example, put both algorithms for the three
VARSUBs into one VARSUB).
3. Use a PAR (parameter list) entry to branch between the different calculations for your subroutine.
4. Compile and link the subroutine.
5. Add an additional parameter to your Adams elements referencing the subroutines to choose the
appropriate algorithm.
Note:
Example
152 Adams/Solver
User-Written Subroutines
&
&
&
&
INTEGER
LOGICAL
C
C === Executable code =================================
C
DISP_TRIG
= PAR(1)
STIFF_COEFF = PAR(2)
STIFF_EXP
= PAR(3)
DAMP_COEFF = PAR(4)
PEN_DEPTH
= PAR(5)
I_MAR
= PAR(6)
J_MAR
= PAR(7)
MU
= PAR(8)
BRANCH_ID
= PAR(9)
IORD
= 0
EPSILON
= 0.1
NEG_EPSILON = -1.0*EPSILON
H0
= 1
H1
= -1
C
IPAR(1) = I_MAR
IPAR(2) = J_MAR
IPAR(3) = J_MAR
NSIZE
= 3
CALL SYSFNC('DY', IPAR, NSIZE, DISP_Y, ERRFLG)
CALL SYSFNC('VY', IPAR, NSIZE, VEL_Y, ERRFLG)
CALL SYSFNC('VX', IPAR, NSIZE, VEL_X, ERRFLG)
CALL SYSFNC('WZ', IPAR, NSIZE, OMEGA_Z, ERRFLG)
C
CALL IMPACT(DISP_Y, VEL_Y, DISP_TRIG, STIFF_COEFF, STIFF_EXP,
&
DAMP_COEFF, PEN_DEPTH, IORD, IMPARY, ERRFLG )
C
IF (BRANCH_ID .EQ. 1) THEN
C
VALUE = IMPARY(1)
C
ELSEIF (BRANCH_ID .EQ. 2) THEN
C
SLIP = VEL_X+OMEGA_Z*DISP_TRIG
CALL STEP(SLIP, NEG_EPSILON, H0, EPSILON, H1, IORD,
&
STPVAL, ERRFLG)
VALUE = MU*IMPARY(1)*STPVAL
C
ELSEIF (BRANCH_ID .EQ. 3) THEN
C
SLIP = VEL_X+OMEGA_Z*DISP_TRIG
CALL STEP(SLIP, NEG_EPSILON, H0, EPSILON, H1, IORD,
&
STPVAL, ERRFLG)
VALUE = MU*IMPARY(1)*STPVAL*DISP_TRIG
C
Basics 153
User-Written Subroutines
ENDIF
RETURN
END
Invoking Subroutines
Some modeling elements allow you to use subroutines to define their behavior. You can invoke userwritten subroutines from statements or commands. You have to use pre-assigned names for your custom
subroutines so that Adams/Solver knows which ones to call, and when.
The table below lists the statements or commands that can reference user-written subroutines and the
name of the user-written subroutine(s) they can reference.
To invoke the subroutine:
CFFSUB, CNFSUB
FRICTION
CONSUB
CONTROL
COUPLER
CURSUB
CURVE
DIFSUB
DIFF
FIESUB
FIELD
GFOSUB
GFORCE
GSE
MOTSUB
MOTION
RELSUB
RELOAD
REQSUB
REQUEST
SAVSUB , SEVSUB
SAVE
SENSUB
SENSOR
SFOSUB
SFORCE
UCOSUB
UCON
VARSUB
VARIABLE
VFOSUB
VFORCE
VTOSUB
VTORQUE
You can call utility subroutines from your user-written subroutine. Utility Subroutines can provide
information about the current state of the system to the user-written subroutine.
154 Adams/Solver
User-Written Subroutines
You can replace the above statement with the following statement that requires a user-written subroutine
GFOSUB to evaluate the force expressions. Notice how marker IDs are being passed through the
parameter list to make the subroutine generic.
GFORCE/5, I=310, JFLOAT=9910, RM=310,
, FUNCTION=USER(20, 500, 310, 9900)
You can then create a GFOSUB user-written subroutine that looks like the following:
SUBROUTINE GFOSUB(ID, TIME, PAR, NPAR, DFLAG,
&
IFLAG, RESULT)
C
C === Type and dimension statements ===================
Basics 155
User-Written Subroutines
C
C
Note: For a machine with 60 or more bits per word,
C
substitute "REAL" for "DOUBLE PRECISION".
C
C - External variable definitions -----------C
INTEGER
ID
DOUBLE PRECISION
TIME
DOUBLE PRECISION
PAR( * )
INTEGER
NPAR
LOGICAL
DFLAG
LOGICAL
IFLAG
DOUBLE PRECISION
RESULT(6)
C
C
ID
Identifier of calling GFORCE statement
C
TIME
Current time
C
PAR
Array containing passed parameters
C
NPAR
Number of passed parameters
C
DFLAG
Differencing flag
C
IFLAG
Initial pass flag
C
RESULT
Array (dimension 6) of computed GFORCE
C
components returned to ADAMS
C
C - Local variable and parameter definitions -----C
DOUBLE PRECISION CT, CR, VEL(6)
INTEGER
IPAR(3), IM, JM, NSTATES
LOGICAL
ERRFLG
C
C ===Executable code ==================================
C
C
Assign readable variable names to passed parameters
C
CT
CR
IM
JM
=
=
=
=
PAR(1)
PAR(2)
PAR(3)
PAR(4)
C
C
Call SYSARY to collect information for the
C
calculations below. Note: if IFLAG is true, this
C
call is actually setting functional dependencies.
C
C - Use VEL to get marker translational and rotational
C
velocities
C
IPAR(1) = IM
IPAR(2) = JM
IPAR(3) = IM
CALL SYSARY('VEL', IPAR, 3, VEL, NSTATES, ERRFLG)
C
C - Check SYSARY call through ERRMES utility routine
C
CALL ERRMES(ERRFLG, 'Error calling SYSARY for VEL',
156 Adams/Solver
User-Written Subroutines
&
ID, 'STOP')
C
C - Evaluate GFORCE components ------------C
RESULT(1) = -CT * VEL(1)
RESULT(2) = -CT * VEL(2)
RESULT(3) = -CT * VEL(3)
RESULT(4) = -CR * VEL(4)
RESULT(5) = -CR * VEL(5)
RESULT(6) = -CR * VEL(6)
C
RETURN
END
Unsupported Subroutines
Although Adams/Solver continues to recognize many unsupported subroutines, new subroutines have
made some of them obsolete. The use of unsupported subroutines is discouraged as they may be removed
from future Adams/Solver releases without notice.
This release of Adams/Solver no longer supports the following subroutines available in previous
releases:
GSESUB
GSEXX, GSEXU, GSEYX, GSEYU
CFFSUB 157
User-Written Subroutines
CFFSUB
The CFFSUB evaluation subroutine computes a set of friction force values for a CONTACT statement
(C++ or FORTRAN). You can use a CFFSUB when the default friction force routine is not applicable to
your model.
Use
Calling Sequence
SUBROUTINE CFFSUB (id, time, par, npar, loci, locj, x, xdot, nforce, area, dflag, iflag, result)
Input Arguments
area
dflag
A logical variable that Adams/Solver sets to true when it calls CFFSUB to evaluate the
partial derivatives of the specified functions. Otherwise, Adams/Solver sets the dflag
argument to false.
id
An integer variable that provides the identifier of the CONTACT statement requesting
information from CFFSUB. From the identifier, Adams/Solver automatically recognizes
other information (such as the par argument) that is available in the corresponding
statement.
158 Adams/Solver
User-Written Subroutines
iflag
An integer variable that Adams/Solver sets to indicate why the routine is being called:
Value
Description
Mapping dependencies
Expression serialization
Expression un-serialization
Adams/Solver sets iflag to 3 when it needs the functional dependency of the user-defined
variable. The functional dependencies are set with the same calls to the SYSARY and
SYSFNC utility subroutines that are made to compute the value of the user-defined
variable. If iflag is 0, Adams/Solver computes the value of the user-written variable.
When your user-defined subroutine has static data that needs to be saved and restored to
support the Adams/Solver commands Save and Reload, then call the serialization
functions for your data when iflag is set to 7, and the un-serialization functions when iflag
is set to 9.
Note:
In simple subroutines where serializing data is not needed, you can declare iflag
as a logical variable. In this case you declare your dependencies when
Adams/Solver sets iflag to true, and compute the subroutine's value when
Adams/Solver sets iflag to false.
loci
A double-precision array that specifies the vector from the reference marker of the
CONTACT I Geometry (IGEOM) to the contact point on IGEOM. Expressed in the
coordinate system of the reference marker of IGEOM.
locj
A double-precision array that specifies the vector from the reference marker of the
CONTACT J Geometry (JGEOM) to the contact point on JGEOM. Expressed in the
coordinate system of the reference marker of JGEOM.
nforce
A double-precision variable that specifies the value of the contact normal force.
npar
An integer variable that indicates the number of constants you specify in the USER
parenthetical list. This variable provides the CFFSUB evaluation subroutine with the
number of values stored in the par array.
par
time
CFFSUB 159
User-Written Subroutines
xdot
A double-precision array that specifies the slip velocities at the contact point.
(1) - Translational slip velocity along the x-axis of the contact
I incident marker.
(2) - Translational slip velocity along the y-axis of the contact
I incident marker.
(3) - Relative angular velocity of contacting surfaces about the
z-axis of the contact I incident marker.
Output Argument
result
A double-precision array that returns the three components of the friction force.
(1) - Translational force along the x-axis of the contact I incident marker.
(2) - Translational force along the y-axis of the contact I incident marker.
(3) - Rotational torque about the z-axis of the contact I incident marker.
Extended Definition
The default friction model in the CONTACT statement can only model simple dynamic friction. This
means that to produce a friction force, contacting bodies must be sliding at the point of contact. Effects
such as static friction and frictional torque are not modeled.
If you require another force model, you can use a CFFSUB. If the algorithms use or consist of alreadyexisting FORTRAN-77 subroutines, CFFSUB can be made to call them. You can call utility subroutines,
such as AKISPL, CUBSPL, SYSARY, and SYSFNC from CFFSUB, to obtain information about system
variables, user-defined variables, and splines.
The SYSARY and SYSFNC utility subroutines set functional dependencies when the CFFSUB argument
iflag is true. To compute solutions efficiently, Adams/Solver must know the other variables on which
each user-defined variable depends. Adams/Solver determines these functional dependencies at the
beginning of the simulation by calling CFFSUB with the argument iflag set to true. Adams/Solver does
160 Adams/Solver
User-Written Subroutines
The use of the DFLAG variable is optional. Its purpose is to simply let you know that CFFSUB is being
called to evaluate a partial derivative. One of the states on which the CFFSUB depends has been
perturbed very slightly. In many situations, it is likely that major calculations in the CFFSUB are
insensitive to small changes in state, and therefore, need not be recalculated. In such situations, you can
structure the CFFSUB not to redo these calculations.
Tip:
If the SYSARY or SYSFNC subroutines are called to access angular displacements, the
values returned by CFFSUB may contain discontinuities. Discontinuities occur if there is
an Euler singularity. To avoid the Euler singularity (and thus the discontinuities), use the
RCNVRT utility subroutine to convert the rotational angles from Euler angles to some
other coordinate system that does not encounter a singularity.
If the calculations always use the same SYSARY and SYSFNC calls through the
whole simulation, and you have no initialization to do, you do not need to check
the flag argument at all. You can just call SYSARY and/or SYSFNC, compute the
user-defined variable value, and return to Adams/Solver (FORTRAN)
Caution:
compute the component values of the CONTACT statement. This ensures that
Adams/Solver has the proper functional dependencies. In general, failure to
account for dependencies in the CONTACT statement components can make it
difficult for Adams/Solver to converge to a solution and/or can force
Adams/Solver to take small integration steps, potentially causing large increases in
execution time.
SYSARY and SYSFNC return zero values for system and user-defined variables.
When you use Adams/Solver, computations that divide by these values result in
fatal errors. You should check for nonzero values, or ensure the iflag argument is
set to false, before dividing by these values.
Fortran - Prototype
A sample structure for CFFSUB is shown next. The comments explain how the subroutine works.
CFFSUB 161
User-Written Subroutines
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
PRECISION
PRECISION
PRECISION
PRECISION
US
UD
VS
VD
162 Adams/Solver
User-Written Subroutines
X0 = -VS
-1
VS
1
C Style - Prototype
typedef void adams_c_CFFSUB(const struct sAdamsContactFriction* fric,
double TIME, const double* LOCI, const double* LOCJ, const double* X,
const double* XDOT, double NFORCE, double AREA, int DFLAG, int IFLAG,
double* VALUES );
typedef void STDCALL adams_f77_CFFSUB(const int* ID, const double*
TIME, const double* PAR, const int* NPAR, const double* LOCI, const
double* LOCJ, const double* X, const double* XDOT, const double*
NFORCE, const double* AREA, const int* DFLAG, const int* IFLAG,
double* VALUES );
struct sAdamsContact
{
int ID;
int nIGEOM;
int nJGEOM;
int* IGEOM;
int* JGEOM;
int* IFLIP_GEOM;
CFFSUB 163
User-Written Subroutines
int* JFLIP_GEOM;
};
struct sAdamsContactFriction
{
struct sAdamsContact contact;
int NPAR;
const double* PAR;
};
164 Adams/Solver
User-Written Subroutines
CNFSUB
The CNFSUB evaluation subroutine computes a set of normal force values for a CONTACT statement
(C++ or FORTRAN). You can use a CNFSUB when the default normal force routine is not applicable to
your model.
Use
Calling Sequence
SUBROUTINE CNFSUB (id, time, par, npar, loci, ni, locj, nj, gap, gapdot, gapdotdot, area, dflag, iflag,
result)
Input Arguments
area
dflag
A logical variable that Adams/Solver sets to true when it calls CNFSUB to evaluate
the partial derivatives of the specified functions. Otherwise, Adams/Solver sets the
dflag argument to false.
gap
gap no penetration
gap < 0 penetration
gapdot
id
An integer variable that provides the identifier of the CONTACT statement requesting
information from CNFSUB. From the identifier, Adams/Solver automatically
recognizes other information (such as the par argument) that is available in the
corresponding statement.
CNFSUB 165
User-Written Subroutines
iflag
An integer variable that Adams/Solver sets to indicate why the routine is being called:
Value
Description
Mapping dependencies
Expression serialization
Expression un-serialization
Adams/Solver sets iflag to 3 when it needs the functional dependency of the userdefined variable. The functional dependencies are set with the same calls to the
SYSARY and SYSFNC utility subroutines that are made to compute the value of the
user-defined variable. If iflag is 0, Adams/Solver computes the value of the userwritten variable.
When your user-defined subroutine has static data that needs to be saved and restored
to support the Adams/Solver commands Save and Reload, then call the serialization
functions for your data when iflag is set to 7, and the un-serialization functions when
iflag is set to 9.
Note:
In simple subroutines where serializing data is not needed, you can declare
iflag as a logical variable. In this case you declare your dependencies when
Adams/Solver sets iflag to true, and compute the subroutine's value when
Adams/Solver sets iflag to false.
loci
A double-precision array that specifies the vector from the reference marker of the
CONTACT I Geometry (IGEOM) to the contact point on IGEOM. Expressed in the
coordinate system of the reference marker of IGEOM.
locj
A double-precision array that specifies the vector from the reference marker of the
CONTACT J Geometry (JGEOM) to the contact point on JGEOM. Expressed in the
coordinate system of the reference marker of JGEOM.
ni
A double-precision array that specifies the surface normal vector of the CONTACT I
Geometry (IGEOM) at the contact location. Expressed in the coordinate system of the
reference marker of IGEOM.
nj
A double-precision array that specifies the surface normal vector of the CONTACT J
Geometry (JGEOM) at the contact location. Expressed in the coordinate system of the
reference marker of JGEOM.
npar
An integer variable that indicates the number of constants you specify in the USER
parenthetical list. This variable provides the CNFSUB evaluation subroutine with the
number of values stored in the par array.
166 Adams/Solver
User-Written Subroutines
par
time
Output Argument
result
Extended Definition
The IMPACT and POISSON force types in the CONTACT statement are usually sufficient to define the
contact normal force. However, if you require another force model, you can use a CNFSUB. If the
algorithms use or consist of already-existing FORTRAN-77 subroutines, CNFSUB can be made to call
them.
You can call utility subroutines, such as AKISPL, CUBSPL, SYSARY, and SYSFNC, from CNFSUB,
to obtain information about system variables, user-defined variables, and splines.
The SYSARY and SYSFNC utility subroutines set functional dependencies when the CNFSUB
argument iflag is true. To compute solutions efficiently, Adams/Solver must know the other variables on
which each user-defined variable depends. Adams/Solver determines these functional dependencies at
the beginning of the simulation by calling CNFSUB with the argument iflag set to true. Adams/Solver
does this once for each CONTACT statement with a
NORMAL_FUNCTION=USER() argument.
During each call to CNFSUB, Adams/Solver records which calls you make to SYSARY and SYSFNC.
Adams/Solver assumes that the CONTACT components depend on those Adams/Solver variables that
are accessed through SYSARY and SYSFNC.
Using the dflag variable
The use of the dflag variable is optional. Its purpose is to simply let you know that CNFSUB is being
called to evaluate a partial derivative. One of the states on which the CNFSUB depends has been
perturbed very slightly. In many situations, it is likely that major calculations in the CNFSUB are
CNFSUB 167
User-Written Subroutines
insensitive to small changes in state, and therefore, need not be recalculated. In such situations, you can
structure the CNFSUB not to redo these calculations.
Tip:
If the SYSARY or SYSFNC subroutines are called to access angular displacements, the
values returned by CNFSUB may contain discontinuities. Discontinuities occur if there is
a Euler singularity. To avoid the Euler singularity (and thus the discontinuities), use the
RCNVRT utility subroutine to convert the rotational angles from Euler angles to some
other coordinate system that does not encounter a singularity. If the calculations always use
the same SYSARY and SYSFNC calls through the whole simulation, and you have no
initialization to do, you do not need to check the iflag argument at all. You can just call
SYSARY and/or SYSFNC, compute the user-defined variable value, and return to
Adams/Solver.
Caution:
compute the component values of the CONTACT statement. This ensures that
Adams/Solver has the proper functional dependencies. In general, failure to
account for dependencies in the CONTACT statement components can make it
difficult for Adams/Solver to converge to a solution and/or can force
Adams/Solver (FORTRAN) to take small integration steps, potentially causing
large increases in execution time.
SYSARY and SYSFNC return zero values for system and user-defined variables.
When you use Adams/Solver, computations that divide by these values result in
fatal errors. You should check for nonzero values, or ensure that the iflag argument
is set to false, before dividing by these values.
FORTRAN - Prototype
A sample structure for CNFSUB is shown next. The comments explain how the subroutine works.
SUBROUTINE CNFSUB(ID, TIME,PAR, NPAR, LOCI, NI, LOCJ, NJ,
& GAP, GAPDOT,& GAPDOTDOT, AREA, DFLAG, IFLAG, RESULT)
C
C === Type and dimension statements ===================
C
IMPLICIT NONE
INTEGER ID
DOUBLE PRECISION TIME
DOUBLE PRECISION PAR( * )
INTEGER NPAR
DOUBLE PRECISION LOCI(3)
DOUBLE PRECISION NI(3)
DOUBLE PRECISION LOCJ(3)
DOUBLE PRECISION NJ(3)
168 Adams/Solver
User-Written Subroutines
CNFSUB 169
User-Written Subroutines
ENDIF
C
C - Evaluate Normal Force components ------------C
C Your algorithms
C
...
C
C Assign values to the RESULT array
C
RESULT(1) = ...
RESULT(2) = ...
RESULT(3) = ...
C
RETURN
END
C Style - Prototype
typedef void adams_c_CNFSUB(const struct sAdamsContactFriction* fric,
double TIME, const double* LOCI, const double* NI, const double* LOCJ,
const double* NJ, double GAP, double GAPDOT, double GAPDOTDOT, double
AREA, int DFLAG, int IFLAG, double* VALUES );
typedef void STDCALL adams_f77_CNFSUB(const int* ID, const double*
TIME, const double* PAR, const int* NPAR, const double* LOCI, const
double* NI, const double* LOCJ, const double* NJ, const double* GAP,
const double* GAPDOT, const double* GAPDOTDOT, const double* AREA,
const int* DFLAG, const int* IFLAG, double* VALUES );
struct sAdamsContact
{
int ID;
int nIGEOM;
int nJGEOM;
int* IGEOM;
int* JGEOM;
int* IFLIP_GEOM;
int* JFLIP_GEOM;
};
struct sAdamsContactFriction
{
struct sAdamsContact contact;
int NPAR;
const double* PAR;
};
170 Adams/Solver
User-Written Subroutines
CONSUB
The CONSUB driver subroutine can be used to control an Adams simulation from within a user
subroutine. Interactively issuing the CONTROL command (C++ or FORTRAN) invokes CONSUB.
Other user-written subroutines cannot call CONSUB.
Use
Corresponding Command
CONTROL/ [FUNCTION=USER(r1[,...,r30])[/]]
[[ ]] Optionally select an item combination
Calling Sequence
npar
An integer variable that indicates the number of constants specified in the parenthetical list
of the USER keyword. The primary purpose of npar is to provide CONSUB with the
number of values stored in the par array.
par
A double-precision array of constants taken in order from the parenthetical list in the USER
keyword CONTROL command.
Extended Definition
simulation(s).
When execution of CONSUB stops, Adams/Solver prompts you for another command.
Caution:
When program control passes to CONSUB, automatic generation of output stops. If you
want to create output, call the DATOUT utility subroutine.
CONSUB 171
User-Written Subroutines
FORTRAN - Prototype
A sample structure for CONSUB is shown next. The comments explain how the subroutine works.
SUBROUTINE CONSUB ( PAR, NPAR )
C
C === Type and dimension statements ==================
C
C
C - External variable definitions --------C
INTEGER
NPAR
DOUBLE PRECISION
PAR( * )
C
C PAR
Array containing passed parameters
C NPAR
Number of passed parameters
C
C - Local variable definitions ----------C
...
C
C === Executable code ================================
C
C - Your commands ----------------C
...
C
RETURN
END
C Style - Prototype
typedef void adams_c_CONSUB(const struct sAdamsControl* con);
/*
*
CONTROL
*/
struct sAdamsControl
{
int NPAR;
const double* PAR;
};
Examples
172 Adams/Solver
User-Written Subroutines
coupled.
COUXX returns to Adams/Solver the first partial derivatives of the coupler constraint, with
Calling Sequence
SUBROUTINE COUSUB (id, time, par, npar, disp, ndisp, iflag, phi)
SUBROUTINE COUXX (id, time, par, npar, disp, ndisp, iflag, dfda)
SUBROUTINE COUXX2 (id, time, par, npar, disp, ndisp, iflag, dfda2)
Input Arguments
id
An integer variable that specifies the identifier of the COUPLER statement whose
constraint function is being specified.
time
par
A double-precision array that contains the constants taken, in order, from the list of values
provided with the USER argument in the COUPLER statement.
npar
disp
ndisp
An integer variable that defines the size of the DISP array. This is equal to the number of
joints being coupled in the COUPLER statement.
iflag
An integer variable that Adams/Solver sets to indicate why the routine is being called:
Value
Description
Mapping dependencies
Expression serialization
Expression un-serialization
When iflag is 0 Adams/Solver calling to compute the value of the user-written variable.
When iflag is set to 1 or 3 do any initializations that your subroutine requires.
When your user-defined subroutine has static data that needs to be saved and restored to
support the Adams/Solver commands Save and Reload, then call the serialization
functions for your data when iflag is set to 7, and the un-serialization functions when iflag
is set to 9.
Note:
In simple subroutines where serializing data is not needed, you can declare iflag
as a logical variable. In this case you can do any initializations when
Adams/Solver sets iflag to true, and compute the subroutine's value when
Adams/Solver sets iflag to false.
Output Arguments
phi
A double-precision scalar that contains the value of the coupler constraint equation.
The constraint equation must be specified in implicit form. For example, the equation
must be in the form: f (disp) = 0.
dfda
A double-precision array of length ndisp that contains the partial derivatives of phi with
respect to disp. Therefore, fda ( i ) = phi disp ( i )
dfda2
A double-precision array of dimensions ndisp that contains the second partials derivatives
of phi with respect to disp.
Therefore,
174 Adams/Solver
User-Written Subroutines
Extended Definition
The COUPLER statement is used to relate the motion of two or more joints. If the relationship between
the motion in a set consisting of two or three joints is linear, the scale factors relating the motion can be
directly specified in the dataset.
However, when the relationship between the joints is nonlinear in nature, the equation specifying this
relationship must be specified in the user-written subroutines COUSUB, COUXX, and COUXX2.
Therefore, if d1, d2, and d3 are displacement/rotations in three translational or revolute joints, the
relationship between them may be written analytically as: 1 (d1) + 2(d2) + 3(d3) = 0
COUSUB, COUXX, and COUXX2 must only be functions of the input variables specified above. You
cannot call SYSFNC or SYSARY to access other system states.
FORTRAN - Prototype
A sample structure for COUSUB, COUXX, and COUXX2 is shown next. The comments explain the
logical structure of each of the subroutines.
COUSUB
SUBROUTINE COUSUB (ID, TIME, PAR, NPAR, DISP,
&
NDISP, IFLAG, PHI)
C
C+----------------------------------------------------*
C
C Inputs:
C
INTEGER
ID
DOUBLE PRECISION TIME
DOUBLE
PRECISION PAR(*)
INTEGER
NPAR
DOUBLE PRECISION
DISP(*)
INTEGER
NDISP
LOGICAL
IFLAGCC
Outputs:
C
DOUBLE PRECISION PHICC Local Variables:
C
...
...
C
C+----------------------------------------------------*
C
Executable Code
C+----------------------------------------------------*
C
C
IF (IFLAG) THEN
C
C+----------------------------------------------------*
C
Initialization pass: Initialize necessaryC
local
variables
C+----------------------------------------------------*C
...
...
C
ELSEC
C+----------------------------------------------------*
C
Evaluation pass: Define Phi the
C
coupler constraint
C+----------------------------------------------------*
C
...
...
PHI = ...
C
ENDIF
C
C
RETURN
END
COUXX
&
C
C+----------------------------------------------------*
C
C Inputs:
C
INTEGER
ID
DOUBLE PRECISION TIME
DOUBLE PRECISION PAR(*)
INTEGER
NPAR
DOUBLE PRECISION DISP(*)
INTEGER
NDISP
LOGICAL
IFLAG
C
C Outputs:
C
DOUBLE PRECISION DFDA(*)
C
C Local Variables:
C
...
...
C
C+----------------------------------------------------*
C
Executable Code
C+----------------------------------------------------*
C
C
IF (IFLAG) THEN
C
C+----------------------------------------------------*
C
Initialization pass: Initialize
C
necessary local variables
C+----------------------------------------------------*
C
...
...C
ELSE
C
C+----------------------------------------------------*
C
Evaluation pass: Define the partial
176 Adams/Solver
User-Written Subroutines
C+----------------------------------------------------*
C
...
...
C
ELSE
C
C+----------------------------------------------------*
C
Evaluation pass: Define the second partial
C
derivatives of the coupler constraint
C+----------------------------------------------------*
C
...
...
DFDA2(1) = ...
DFDA2(2) = ...
...
...
C
ENDIF
C
C
RETURN
END
C Style - Prototype
typedef void adams_c_COUSUB(const struct sAdamsCoupler* coupler,
double TIME, double*, int IFLAG, double* PHI);
typedef void adams_c_COUXX(const struct sAdamsCoupler* coupler,
double TIME, double*, int IFLAG, double* dFda);
typedef void adams_c_COUXX2(const struct sAdamsCoupler* coupler,
double TIME, double*, int IFLAG, double* d2Fda2);
/*
*
COUPLER
---------------------------------------------------------------*/
struct sAdamsCoupler
{
int ID;
int NPAR;
const double* PAR;
int NJOINT;
int JOINTS[3];
char TYPE[3];
};
178 Adams/Solver
User-Written Subroutines
Examples
The mechanical system shown in Figure 1 consists of three rigid bodies and two joints; the first is a
revolute joint and the second translational. The translational joint represents an actuator whose output
displacement controls the angular motion in the revolute joint.
Let the displacement in the translational joint be defined as and the rotation in revolute joint as a.
Now assume that the variables s and a are related by the following equation:
s = 10 * Cos (a)
Figure 1. Simple Mechanical System Consisting of a Coupler
180 Adams/Solver
User-Written Subroutines
RETURN
END
COUXX
&
C
C+----------------------------------------------------*
C
C Inputs:
C
INTEGER
ID
DOUBLE PRECISION TIME
DOUBLE PRECISION PAR(*)
INTEGER
NPAR
DOUBLE PRECISION DISP(*)
INTEGER
NDISP
LOGICAL
IFLAG
C
C Outputs:
C
DOUBLE PRECISION DFDA(*)
C
C Local Variables:
C
DOUBLE PRECISION LENGTH, S, ALPHA
C
C+----------------------------------------------------*
C
Executable Code
C+----------------------------------------------------*C
IF (IFLAG) THEN
C
C
there are no variables to initialize in this example
C
ELSE
C
C+----------------------------------------------------*
C
Evaluation pass: Define the partial derivatives
C
of the coupler constraint
C+----------------------------------------------------*
C
LENGTH = PAR(1)
ALPHA = DISP(1)
S
= DISP(2)
C
DFDA(1) = + LENGTH * SIN(ALPHA)
DFDA(2) = 1.0
C
ENDIF
C
RETURN
END
COUXX2
SUBROUTINE COUXX2 (ID, TIME, PAR, NPAR, DISP,
&
NDISP, IFLAG, DFDA2)
C
C+----------------------------------------------------*
C Inputs:
C
INTEGER
ID
DOUBLE PRECISION TIME
DOUBLE PRECISION PAR(*)
INTEGER
NPAR
DOUBLE PRECISION DISP(*)
INTEGER
NDISP
LOGICAL
IFLAG
C
C Outputs:
C
DOUBLE PRECISION DFDA2(NDISP)
C
C Local Variables:
C
DOUBLE PRECISION LENGTH, ALPHA, S
C
C+----------------------------------------------------*
C
Executable Code
C+----------------------------------------------------*
C
IF (IFLAG) THEN
C
C
no variables to initialize in this example.
C
ELSE
C
C+----------------------------------------------------*
C
Evaluation pass: Define the second partial
C
derivatives of the coupler constraint
C+----------------------------------------------------*
C
LENGTH = PAR(1)
ALPHA = DISP(1)
S
= DISP(2)
DFDA2(1) = LENGTH * COS(ALPHA)
DFDA2(2) = 0.0
C
ENDIF
C
RETURN
END
182 Adams/Solver
User-Written Subroutines
CURSUB 183
User-Written Subroutines
CURSUB
CURSUB is an evaluation subroutine that computes curve coordinates and their derivatives for a CURVE
statement (C++ or FORTRAN). CURSUB is optional. You can use it to define a curve instead of using
control points or data points.
Use
Corresponding Statement
Calling Sequence
alpha
A double-precision variable that specifies the value of the independent parameter a which
CURSUB uses to evaluate a curve. Adams/Solver restricts a to be:
Greater than or equal to the MINPAR value on the CURVE statement (-1.0 by default).
Less than or equal to the MAXPAR value on the CURVE statement (1.0 by default).
id
An integer variable that provides the identifier of the CURVE statement, which requests
information from the CURSUB. Adams/Solver automatically derives additional
information (such as the par argument) from the identifier of the corresponding statement.
184 Adams/Solver
User-Written Subroutines
iflag
An integer variable that Adams/Solver sets to indicate why the routine is being called:
Value
Description
Mapping dependencies
Expression serialization
Expression un-serialization
When iflag is 0 Adams/Solver calling to compute the value of the user-written variable.
When iflag is set to 1 or 3 do any initializations that your subroutine requires.
When your user-defined subroutine has static data that needs to be saved and restored to
support the Adams/Solver commands Save and Reload, then call the serialization
functions for your data when iflag is set to 7, and the un-serialization functions when iflag
is set to 9.
Note:
iord
In simple subroutines where serializing data is not needed, you can declare iflag
as a logical variable. In this case you can do any initializations when
Adams/Solver sets iflag to true, and compute the subroutine's value when
Adams/Solver sets iflag to false.
An integer variable that specifies the order of the derivative that CURSUB returns. The
possible values are:
zero (return curve coordinates)
one (return first derivatives with respect to alpha)
two (return second derivatives with respect to alpha).
npar
An integer variable that indicates the number of constants specified in the USER
parenthetical list. The primary purpose of npar is to provide the CURSUB evaluation
subroutine with the number of values stored in the par array.
par
A double-precision array of constants that is taken in order from the USER parenthetical
list of the CURVE statement.
CURSUB 185
User-Written Subroutines
Output Arguments
values
A double-precision array of size three that returns the x, y, and z coordinates of the curve
or their first or second derivatives with respect to a. The values the CURSUB should
compute and return depend on the input value of argument iord, as summarized next:
iord:
values (1):
x( )
values (2):
y( )
values (3):
z()
d x( )
d
d y( )
d
d z()
d
d x()
2
d
d y()
2
d
d z()
2
d
Extended Definition
The CURVE statement lets you define a uniform B-Spline curve using control points or a tensioned BSpline curve that is fitted to data points. If you cannot represent the curve you want using a uniform or
tensioned B-Spline, you can use the FUNCTION=USER ( ) argument in the CURVE statement and write
a CURSUB evaluation subroutine to calculate the curve coordinates and derivatives.
Caution:
Define the curve only as a function of . Don't make calls to the SYSARY and SYSFNC
utility subroutines to access other system variables.
FORTRAN - Prototype
A sample structure for CURSUB is shown next. The comments explain how the subroutine works.
SUBROUTINE CURSUB ( ID, PAR, NPAR, ALPHA, IORD,
&
IFLAG, VALUES )
C
C === Type and dimension statements ===================
186 Adams/Solver
User-Written Subroutines
C
C Note: For machines with 60 or more bits per word,
C
substitute "REAL" for "DOUBLE PRECISION".
C
C - External variable definitions --------C
INTEGER
ID
DOUBLE PRECISION
PAR( * )
INTEGER
NPAR
DOUBLE PRECISION
ALPHA
INTEGER
IORD
LOGICAL
IFLAG
DOUBLE PRECISION
VALUES( 3 )
C
C ID
Identifier of calling CURVE statement
C PAR
Array containing passed parameters
C NPAR
Number of passed parameters
C ALPHA
Curve parameter value
C IORD
Derivative order of value to be returned
C IFLAG
Initialization pass flag
C VALUES
Derivative values of CURVE returned to ADAMS
C
C - Local variable and parameter definitions ---C
...
C
C === Executable code =================================
C
C Assign parameters to readable variable names
C...CIF ( IFLAG ) THEN
C
C - Subroutine initialization ----------C
...
C
ENDIF
C
C - Compute and assign the curve coordinates ---C
IF ( IORD .EQ. 0 ) THEN
C
C Your algorithm
C
...
C
C Assign values for the X, Y, and Z coordinates
C
VALUES(1) = ...
VALUES(2) = ...
VALUES(3) = ...
C
C - Compute and assign the curve first derivatives C
ELSE IF ( IORD .EQ. 1 ) THEN
CURSUB 187
User-Written Subroutines
C
C Your algorithm
C
...
C
C Assign values for the X, Y, and Z first derivatives
C
VALUES(1) = ...
VALUES(2) = ...
VALUES(3) = ...
C
C - Compute and assign the curve second derivatives C
ELSE
C
C Your algorithm
C
...
C
C Assign values for the X, Y, and Z second derivatives
C
VALUES(1) = ...
VALUES(2) = ...
VALUES(3) = ...
C
ENDIF
C
RETURN
END
C Style - Prototype
typedef void adams_c_CURSUB(const struct sAdamsCurve* crv, double
ALPHA, int IORD, int IFLAG, double* VALUES );
/*
*
CURVE
*/
struct sAdamsCurve
{
int ID;
int NPAR;
const double* PAR;
int CLOSED;
int ORDER;
double MINPAR;
double MAXPAR;
};
Examples
188 Adams/Solver
User-Written Subroutines
DIFSUB
The DIFSUB evaluation subroutine computes a differential-equation value for a DIFF statement (C++ or
FORTRAN). DIFSUB is optional. You only need it if you don't want to use a function expression in the
DIFF statement.
Use
Corresponding Statement
Calling Sequence
dflag
A logical variable that Adams/Solver sets to true when it calls DIFSUB to evaluate partial
derivatives of the function. Otherwise, Adams/Solver sets dflag to false.
id
An integer variable that provides the identifier of the DIFF statement requesting
information from the DIFSUB. From the identifier, Adams/Solver automatically knows
other information (such as the par argument) available in the corresponding statement.
DIFSUB 189
User-Written Subroutines
iflag
An integer variable that Adams/Solver sets to indicate why the routine is being called:
Value
Description
Mapping dependencies
Expression serialization
Expression un-serialization
Adams/Solver sets iflag to 3 when it needs the functional dependency of the user-defined
variable. The functional dependencies are set with the same calls to the SYSARY and
SYSFNC utility subroutines that are made to compute the value of the user-defined
variable. If iflag is 0, Adams/Solver computes the value of the user-written variable.
When your user-defined subroutine has static data that needs to be saved and restored to
support the Adams/Solver commands Save and Reload, then call the serialization
functions for your data when iflag is set to 7, and the un-serialization functions when iflag
is set to 9.
Note:
In simple subroutines where serializing data is not needed, you can declare iflag
as a logical variable. In this case you declare your dependencies when
Adams/Solver sets iflag to true, and compute the subroutine's value when
Adams/Solver sets iflag to false.
npar
An integer variable that indicates the number of constants specified in the USER
parenthetical list. The primary purpose of npar is to provide the DIFSUB evaluation
subroutine with the number of values stored in the par array.
par
A double-precision array of constants taken in order from the USER parenthetical list of
the DIFF statement.
time
Output Argument
value
A double-precision variable that returns the value of the differential equation. If the
equation is in the explicit form, value contains the derivative. If the equation is in the
implicit form, value contains the residual (that is, the error relative to zero) of the implicit
equation. In this case, value can be a function of the dependent variable and its time
derivative.
190 Adams/Solver
User-Written Subroutines
Extended Definition
A DIFF statement with a function expression is sufficient for defining most user-defined differential
equations. However, if the expression becomes lengthy and awkward or if the definition of the equation
requires additional features of FORTRAN-77, you should use the FUNCTION=USER() argument in the
DIFF statement, and write a DIFSUB evaluation subroutine to define the differential equation.
DIFSUB allows you to define a differential equation for a variable either explicitly or implicitly:
In an explicit definition, the derivative of the variable is evaluated on the right side of a
For further information on implicit and explicit definitions, see the DIFF statement (C++ or FORTRAN).
You can call utility subroutines, such as AKISPL, CUBSPL, SYSARY, and SYSFNC, from DIFSUB to
obtain information about system variables, other user-defined variables, and splines.
The SYSARY and SYSFNC utility subroutines automatically set functional dependencies when the
DIFSUB argument iflag is true. In order for Adams/Solver to compute solutions efficiently, it must know
on which other variables each user-defined variable directly depends. Adams/Solver determines these
functional dependencies at the beginning of the simulation by calling a DIFSUB evaluation subroutine
with argument iflag set to true. Adams/Solver does this once for each DIFF statement with a
FUNCTION=USER() argument. During each call to the DIFSUB evaluation subroutine, Adams/Solver
records which calls you make to SYSARY and SYSFNC. Adams/Solver assumes that the user-defined
variable depends on those system and user-defined variables, and no others.
Tip:
DIFSUB 191
User-Written Subroutines
Caution:
When the iflag argument is true, be sure to make all the same calls to the SYSARY
and SYSFNC utility subroutines that are done when actually computing the value
of the user-defined variable. This ensures that Adams/Solver has the proper
functional dependencies. In general, failure to account for dependencies of the
user-defined variables might make it difficult for Adams/Solver to converge to a
solution, and/or might force Adams/Solver to take small integration steps,
potentially causing large increases in execution time.
When the iflag argument is true, SYSARY and SYSFNC return zero values for
system and user-defined variables. Computations that divide by these values result
in system errors when Adams/Solver is executed. Be sure to check for nonzero
values, or the iflag argument set to false, before dividing by these values.
FORTRAN - Prototype
A sample structure for DIFSUB is shown next. The comments explain how the subroutine works.
&
C
C === Type and dimension statements ==================
C
C Note: For machines with 60 or more bits per word,
C
substitute "REAL" for "DOUBLE PRECISION".
C
C - External variable definitions --------C
INTEGER
ID
DOUBLE PRECISION
TIME
DOUBLE PRECISION
PAR( * )
INTEGER
NPAR
LOGICAL
DFLAG
LOGICAL
IFLAG
DOUBLE PRECISION
VALUE
C
C ID
Identifier of calling DIFF statement
C TIME
Current time
C PAR
Array containing passed parameters
C NPAR
Number of passed parameters
C DFLAG
Differencing flag
C IFLAG
Initialization pass flag
C VALUE
Computed value of DIFF returned to ADAMS
C
C - Local variables and parameters definitions --C
...
C
C === Executable code ================================
C
C Assign readable variable names to passed parameters
C
192 Adams/Solver
User-Written Subroutines
C
C
C
C
C
C
C
C
C
...
Call SYSFNC and/or SYSARY to collect information for
the following calculations. Note: if IFLAG is
true, these calls are actually setting
functional dependencies.
CALL SYSFNC ( ... )
Check SYSFNC call through ERRMES utility routine
DIFSUB 193
User-Written Subroutines
Examples
194 Adams/Solver
User-Written Subroutines
DMPSUB
The DMPSUB evaluation subroutine computes the modal damping ratios for a FLEX_BODY statement
(C++ or FORTRAN). DMPSUB is optional. You need it only if you want custom damping that is not the
same for all modes, or if the modal damping changes with time.
Use
Corresponding Statement
Calling Sequence
DMPSUB 195
User-Written Subroutines
Input Arguments
id
time
par
A double-precision array of constants taken, in order, from the USER parenthetical list
of the FLEX_BODY statement.
npar
An integer variable that indicates the number of constants specified in the USER
parenthetical list. The primary purpose of npar is to provide the DMPSUB evaluation
subroutine with the number of values stored in the par array.
freq
An array of natural frequencies for the modes in cycles per user-defined time.
nmode
The current integrator step size. This is useful if you are using damping to prevent
integration problems.
Output Argument
cratios
An array of damping ratios as a fraction of critical damping. There must be one value
computed for each of the modes.
Examples
To control the modal damping of individual modes using a user-written subroutine, use CRATIO=USER
according to Adams standard practice. The damping ratios for the selected modes are obtained through
a call to the DMPSUB subroutine. For a model using units of seconds for time, this example illustrates:
1% critical damping for modes less than 100 Hz.
10% critical damping for modes greater or equal to 100 Hz but less than 1 kHz.
100% critical damping for modes greater than or equal to 1 kHz.
The following statement defines the constants Adams/Solver is to pass to the DMPSUB evaluation
subroutine:
FLEX_BODY/1, I=101, J=201
, CRATIO=USER(.01,100,.1,1000,1)
For the current example of this subroutine, see dmpsub.f
C Style - Prototype
typedef void adams_c_DMPSUB(const struct sAdamsCratio* flex, double
TIME, const double* FREQS, int NMODE, double STEPSIZE, double*
CRATIOS);
196 Adams/Solver
User-Written Subroutines
/*
*
FLEX_BODY ---------------------------------------------------*/
struct sAdamsFlexBody
{
int ID;
/* int NMAT;
const int* MATRICES;
int VM;
int WM; */
};
struct sAdamsCratio
{
struct sAdamsFlexBody FlexBody;
int NPAR;
const double* PAR;
};
FIESUB 197
User-Written Subroutines
FIESUB
The FIESUB evaluation subroutine computes the force and torque components and their derivatives for
a FIELD statement (C++ or FORTRAN). FIESUB is optional. You only need it if you don't want to use
the constant stiffness and damping matrices in the FIELD statement.
Use
Corresponding Statement
Calling Sequence
SUBROUTINE FIESUB (id, time, par, npar, disp, velo,& dflag, iflag, field, dfddis, dfdvel)
Input Arguments
id
An integer variable that provides the identifier of the FIELD statement requesting
information from FIESUB. From the identifier, Adams/Solver automatically knows other
information (such as the par argument) available in the corresponding statement.
time
par
A double-precision array of constants taken, in order, from the USER parenthetical list of
the FIELD statement.
198 Adams/Solver
User-Written Subroutines
npar
An integer variable that indicates the number of constants specified in the USER
parenthetical list. The primary purpose of npar is to provide FIESUB with the number of
values stored in the par array.
disp
velo
dflag
A logical variable that Adams/Solver sets to true when it needs derivatives from FIESUB.
FIESUB needs to evaluate dfddis and dfdvel only when the dflag argument is true.
Otherwise, Adams/Solver sets the dflag argument to false.
iflag
An integer variable that Adams/Solver sets to indicate why the routine is being called:
Value
Description
Mapping dependencies
Expression serialization
Expression un-serialization
When iflag is 0 Adams/Solver calling to compute the value of the user-written variable.
When iflag is set to 1 or 3 do any initializations that your subroutine requires.
When your user-defined subroutine has static data that needs to be saved and restored to
support the Adams/Solver commands Save and Reload, then call the serialization functions
for your data when iflag is set to 7, and the un-serialization functions when iflag is set to 9.
Note:
In simple subroutines where serializing data is not needed, you can declare iflag
as a logical variable. In this case you can do any initializations when
Adams/Solver sets iflag to true, and compute the subroutine's value when
Adams/Solver sets iflag to false.
FIESUB 199
User-Written Subroutines
Output Arguments
field
A six-element, double-precision array that returns the x, y, and z translational forces and
the x, y, and z rotational forces that Adams/Solver applies at the I marker with respect to
the J marker, resolved in the coordinate system of the J marker.
dfddis
A six-by-six, double-precision array that returns the derivatives of the six field
components with respect to the six displacement values in the disp array. For example, the
derivative of the fourth FIELD component (TX) with respect to the second displacement
variable (y) is dfddis (4,2). You only need to define dfddis when dflag is set to true.
dfdvel
A six-by-six, double-precision array of the derivatives of the six field components with
respect to the six velocity values in the velo array. For example, the derivative of the first
FIELD component (FX) with respect to the sixth velocity variable (WZ) is dfdvel(1,6).
You need to define dfdvel only when dflag is set to true.
Extended Definition
The FIELD statement with KMATRIX and CMATRIX/CRATIO arguments specified may be used for
defining six-component forces whose stiffness and damping matrices have constant entries. If, however,
the force components are nonlinear functions of the relative displacements and the relative velocities of
the FIELD I and J markers, then use a FIELD statement with FUNCTION=USER() and write a FIESUB
to calculate the six FIELD components. These components and their derivatives can be functions of time
and of the FIELD I marker component displacements and component velocities, with respect to the J
marker. Adams/Solver resolves the components in the J marker coordinate system.
200 Adams/Solver
User-Written Subroutines
FIESUB output must be strictly a function of the values in arrays disp and velo. Consequently, FIESUB
may not call the SYSARY or SYSFNC utility subroutine. FIESUB may call other utility subroutines,
such as AKISPL, and CUBSPL, that do not introduce a dependency on Solver states.
Caution:
The dfddis and dfdvel arrays must always be positive semidefinite. Adams/Solver
does not warn you if the dfddis array, the dfdvel array, or both, are not positive
semidefinite. An array A is positive semidefinite if xT A x > 0 for all x not equal to
0.
Don't attempt to make any of the six field components dependent on system
variables other than those FIESUB passes through the arguments disp, velo, and
time. This rule prohibits calls to the utility subroutines SYSARY and SYSFNC.
Failure to comply with this rule does not produce error messages, but greatly
reduces the integration step sizes, increases the CPU time, and decreases the
probability of convergence to a solution.
If FIESUB returns the six field components without their correct derivatives,
don't forget to involve the derivatives returned by these subroutines when the
FIESUB derivatives are evaluated.
Field components with continuous derivatives are desirable. Discontinuous
derivatives cause a reduction of integration step size at the discontinuity, and may
cause Adams/Solver to fail to converge to a solution.
When the iflag argument is true, Adams/Solver sets the disp and velo arguments to
zeros. When you execute Adams/Solver, computations that divide by these values
result in fatal errors. You should check for nonzero values, or ensure the iflag
argument is false, before dividing by disp or velo values.
FORTRAN - Prototype
A sample structure for FIESUB is shown next. The comments explain how the subroutine works.
&
&
C
C === Type and dimension statements ===================
C
C - External variable definitions --------C
INTEGER
ID
DOUBLE PRECISION
TIME
DOUBLE PRECISION
PAR( * )
INTEGER
NPAR
DOUBLE PRECISION
DISP( 6 )
FIESUB 201
User-Written Subroutines
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
DOUBLE PRECISION
LOGICAL
LOGICAL
DOUBLE PRECISION
DOUBLE PRECISION
DOUBLE PRECISION
ID
TIME
PAR
NPAR
DISP
VELO
DFLAG
IFLAG
FIELD
DFDDIS
DFDVEL
VELO( 6 )
DFLAG
IFLAG
FIELD( 6 )
DFDDIS( 6, 6 )
DFDVEL( 6, 6 )
...
C
C === Executable code =================================
C
C Assign readable variable names to passed parameters
C
...
C
IF ( IFLAG ) THEN
C
C - Subroutine initialization ----------C
...
C
ENDIF
C
C - Calculate field component forces -------C
C X translation field force
C
...
FIELD(1) = ...
C
C Y translation field force
C
...
FIELD(2) = ...
C
C Z translation field force
C
...
FIELD(3) = ...
C
202 Adams/Solver
User-Written Subroutines
FIESUB 203
User-Written Subroutines
DFDDIS(6,1) = ...
...
DFDDIS(6,6) = ...
C
C Assign velocity partials
C
DFDVEL(1,1) = ...
...
DFDVEL(1,6) = ...
C
C Assign velocity partials
C
DFDVEL(2,1) = ...
...
DFDVEL(2,6) = ...
C
C Assign velocity partials
C
DFDVEL(3,1) = ...
...
DFDVEL(3,6) = ...
C
C Assign velocity partials
C
DFDVEL(4,1) = ...
...
DFDVEL(4,6) = ...
C
C Assign velocity partials
C
DFDVEL(5,1) = ...
...
DFDVEL(5,6) = ...
C
C Assign velocity partials
C
DFDVEL(6,1) = ...
...
DFDVEL(6,6) = ...
C
ENDIF
C
RETURN
END
for X force
for Y force
for Z force
for X torque
for Y torque
for Z torque
C Style - Prototype
typedef void adams_c_FIESUB(const struct sAdamsField* fie, double
TIME, double* DISP, double* VELO, int DFLAG, int IFLAG, double*
FIELD, double* DFDDIS, double* DFDVEL);
/*
*
FIELD
---------------------------------------------------------------*/
struct sAdamsField
204 Adams/Solver
User-Written Subroutines
};
int ID;
int NPAR;
const double* PAR;
int I;
int J;
Examples
GSE_SET_IMPLICIT 205
User-Written Subroutines
GSE_SET_IMPLICIT
This subroutine is used to specify the implicit/explicit character of the equations governing the GSE.
See the definition of the IMPLICIT attribute in the documentation for the GSE statement.
When the GSE is initialized Adams/Solver (C++) will look for a GSE_SET_IMPLICIT entry point in the
GSE (if it was not explicitly specified using the INTERFACE= attribute). If GSE_SET_IMPLICIT is
present, then during initialization of the GSE this subroutine will be called.
Note:
The value returned by GSE_SET_IMPLICIT will override any IMPLICIT attribute setting
that is specified in the GSE statement
This user-defined subroutine is new for Adams/Solver (C++) v2006r1 and gives the GSE the ability to
define the implicit/explicit character of its governing equations. That is, the formulation of a GSE can
be changed without changing the corresponding adams model (.amd).
Calling Sequence and Structure
ID
An integer variable that gives the identifier of the GSE statement requesting information
from the GSE subroutine. From the identifier, Adams/Solver automatically recognizes other
information (such as the Par argument) that is associated with that GSE statement.
Output Arguments
IMPLICIT
Example
C
C+===============================================================*
C
SUBROUTINE GSE_SET_IMPLICIT (ID, IMPLICIT)
C
C Inputs:
C
INTEGER
ID
C
C Outputs:
C
206 Adams/Solver
User-Written Subroutines
INTEGER
IMPLICIT
C
C This GSE is formulated implicitly.
IMPLICIT = 1
RETURN
END
C
C+===============================================================*
C
GSE_SET_ND 207
User-Written Subroutines
GSE_SET_ND
This subroutine is used to specify the number of discrete internal states the in the GSE.
When the GSE is initialized Adams/Solver (C++) will look for a GSE_SET_ND entry point in the GSE
(if it was not explicitly specified using the INTERFACE= attribute). If GSE_SET_ND is found, then
during initialization of the GSE this subroutine will be called.
Note:
The value, ND, returned by GSE_SET_ND will override any value of ND that is specified
in the GSE statement
This user-defined subroutine is new for Adams/Solver (C++) v2006r1 and gives the GSE the ability to
define its own number of discrete states. That is, the number of discrete states in a GSE can be changed
without changing the corresponding adams model (.amd).
Calling Sequence and Structure
ID
An integer variable that gives the identifier of the GSE statement requesting
information from the GSE subroutine. From the identifier, Adams/Solver
automatically recognizes other information (such as the Par argument) that is
associated with that GSE statement.
Output Arguments
ND
An integer number giving the number of discrete states that this GSE maintains.
Example
C
C+=================================================================*
C
SUBROUTINE GSE_SET_ND (ID, ND)
C
C Inputs:
C
INTEGER
ID
C
C Outputs:
208 Adams/Solver
User-Written Subroutines
INTEGER
ND
C
C This GSE has two discrete internal states.
ND = 2
RETURN
END
C
C+=================================================================*
C
GSE_SET_NS 209
User-Written Subroutines
GSE_SET_NS
This subroutine is used to specify the number of internal states the in the GSE.
When the GSE is initialized Adams/Solver (C++) will look for a GSE_SET_NS entry point in the GSE
(if it was not explicitly specified using the INTERFACE= attribute). If GSE_SET_NS is found, then
during initialization of the GSE this subroutine will be called.
Note:
The value, NS, returned by GSE_SET_NS will override any value of NS that is specified
in the GSE statement.
This user-defined subroutine is new for Adams/Solver (C++) v2006r1 and gives the GSE the ability to
define its own number of states. That is, the number of states in a GSE can be changed without changing
the corresponding adams model (.amd).
Calling Sequence and Structure
ID
An integer variable that gives the identifier of the GSE statement requesting information
from the GSE subroutine. From the identifier, Adams/Solver automatically recognizes
other information (such as the Par argument) that is associated with that GSE statement.
Output Arguments
NS
An integer number giving the number of states that this GSE maintains.
Example
C
C+=================================================================*
C
SUBROUTINE GSE_SET_NS (ID, NS)
C
C Inputs:
C
INTEGER
ID
C
C Outputs:
C
INTEGER
NS
C
C This GSE has two internal states.
210 Adams/Solver
User-Written Subroutines
NS = 2
RETURN
END
C
C+=================================================================*
C
GSE_SET_SAMPLE_OFFSET 211
User-Written Subroutines
GSE_SET_SAMPLE_OFFSET
This subroutine is used to specify the simulation time at which the sampling of the discrete states is to
start.
See the definition of the SAMPLE_OFFSET attribute in the documentation for the GSE statement.
When the GSE is initialized Adams/Solver (C++) will look for a GSE_SET_SAMPLE_OFFSET entry
point in the GSE (if it was not explicitly specified using the INTERFACE= attribute). If
GSE_SET_SAMPLE_OFFSET is present, then during initialization of the GSE this subroutine will be
called.
Note:
This user-defined subroutine is new for Adams/Solver (C++) v2006r1 and gives the GSE the ability to
set the SAMPLE_OFFSET attribute itself. That is, the formulation of a GSE can be changed without
changing the corresponding Adams model (.amd).
Calling Sequence and Structure
ID
An integer variable that gives the identifier of the GSE statement requesting information
from the GSE subroutine.
Output Arguments
SAMPLE_OFFSET
Example
C
C+=================================================================*
C
SUBROUTINE GSE_SET_SAMPLE_OFFSET (ID, SAMPLE_OFFSET)
C
C Inputs:
C
INTEGER
ID
C
212 Adams/Solver
User-Written Subroutines
C
C
Outputs:
DOUBLE_PRECISION STATIC_HOLD
C
C Discrete states are to be sampled at time at time = 1.23.
C
SAMPLE_OFFSET = 1.23
RETURN
END
C
C+=================================================================*
C
GSE_SET_STATIC_HOLD 213
User-Written Subroutines
GSE_SET_STATIC_HOLD
This subroutine is used to enforce the condition that continuous states are or are not allowed to change
during a static or quasi-static simulation.
See the definition of the STATIC_HOLD attribute in the documentation for the GSE statement.
When the GSE is initialized Adams/Solver (C++) will look for a GSE_SET_STATIC_HOLD entry point
in the GSE (if it was not explicitly specified using the INTERFACE= attribute). If
GSE_SET_STATIC_HOLD is present, then during initialization of the GSE this subroutine will be
called.
Note:
This user-defined subroutine is new for Adams/Solver (C++) v2006r1 and gives the GSE the ability to
set the STATIC_HOLD attribute itself. That is, the formulation of a GSE can be changed without
changing the corresponding Adams model (.amd).
Calling Sequence and Structure
ID
An integer variable that gives the identifier of the GSE statement requesting information
from the GSE subroutine.
Output Arguments
STATIC_HOLD An integer specifying whether the GSE formulation has the STATIC_HOLD
attribute set. A nonzero (true) value for STATIC_HOLD specifies that that GSE has
its STATIC_HOLD attribute set.
Example
C
C+=================================================================*
C
SUBROUTINE GSE_SET_STATIC_HOLD (ID, STATIC_HOLD)
C
C Inputs:
C
INTEGER
ID
214 Adams/Solver
User-Written Subroutines
C
C
C
Outputs:
INTEGER
STATIC_HOLD
C
C Continuous variables are held constant during static or
C
quasi-static simulations.
C
STATIC_HOLD = 1
RETURN
END
C
C+=================================================================*
C
GFOSUB 215
User-Written Subroutines
GFOSUB
The GFOSUB evaluation subroutine computes a set of six force values applied by a GFORCE statement
(C++ or FORTRAN). You can use a GFOSUB when the functions are too cumbersome or complex to
enter as expressions in a GFORCE statement.
Use
Corresponding Statement
Calling Sequence
id
An integer variable that provides the identifier of the GFORCE statement requesting
information from GFOSUB. From the identifier, Adams/Solver automatically recognizes
other information (such as the par argument) that is available in the corresponding
statement.
time
par
A double-precision array of constants taken in order from the USER parenthetical list of
the GFORCE statement.
npar
An integer variable that indicates the number of constants you specify in the USER
parenthetical list. This variable provides the GFOSUB evaluation subroutine with the
number of values stored in the par array.
216 Adams/Solver
User-Written Subroutines
dflag
A logical variable that Adams/Solver sets to true when it calls GFOSUB to evaluate the
partial derivatives of the specified functions. Otherwise, Adams/Solver sets the dflag
argument to false.
iflag
An integer variable that Adams/Solver sets to indicate why the routine is being called:
Value
Description
Mapping dependencies
Expression serialization
Expression un-serialization
Adams/Solver sets iflag to 3 when it needs the functional dependency of the user-defined
variable. The functional dependencies are set with the same calls to the SYSARY and
SYSFNC utility subroutines that are made to compute the value of the user-defined
variable. If iflag is 0, Adams/Solver computes the value of the user-written variable.
When your user-defined subroutine has static data that needs to be saved and restored to
support the Adams/Solver commands Save and Reload, then call the serialization
functions for your data when iflag is set to 7, and the un-serialization functions when
iflag is set to 9.
Note:
In simple subroutines where serializing data is not needed, you can declare
iflag as a logical variable. In this case you declare your dependencies when
Adams/Solver sets iflag to true, and compute the subroutine's value when
Adams/Solver sets iflag to false.
Output Argument
result
A double-precision array that returns the six values of the GFORCE components.
Extended Definition
The GFORCE statement with a function expression is usually adequate for defining functions that
represent the three translational and three rotational vector components of a force at a point. However, if
the force and torque expressions become lengthy and awkward, you can use a GFOSUB.
You can call utility subroutines, such as AKISPL, CUBSPL, SYSARY, and SYSFNC, from GFOSUB,
to obtain information about system variables, user-defined variables, and splines.
The SYSARY and SYSFNC utility subroutines set up functional dependencies when the GFOSUB
argument iflag is true. In order for Adams/Solver to compute solutions efficiently, it must know the
GFOSUB 217
User-Written Subroutines
Solver states on which the GFORCES depend. Adams/Solver determines these functional dependencies
at the beginning of the simulation by calling GFOSUB with the argument iflag set to true. Adams/Solver
does this once for each GFORCE statement with a FUNCTION=USER() argument. During each call to
GFOSUB, Adams/Solver records the calls you make to SYSARY and SYSFNC. Adams/Solver assumes
that the GFORCE components depend on those Adams/Solver states that are accessed through SYSARY
and SYSFNC.
Using the DFLAG Variable
The use of the DFLAG variable with a GFOSUB is optional. It merely identifies that GFOSUB is being
called to evaluate a partial derivative. One of the states on which the GFOSUB depends has been
perturbed very slightly. In many situations, it is likely that major calculations in the GFOSUB are
insensitive to small changes in state, and therefore, need not be recalculated.
In such situations, you can structure the GFOSUB not to redo these calculations. For example, assume
you are using a GFOSUB to model tire and terrain interactions. The terrain is modeled as a set of
triangular patches, and the tire forces as a GFOSUB. A labor-intensive calculation in the problem is to
identify the patch that is in contact with the tire. Because pertubations of system states are always small
when DFLAG is true, it is not necessary to recalculate the patch that is in contact with the tire.
Caution:
system and user-defined variables. Computations that divide by these values will
result in fatal errors. You should check for nonzero values, or ensure the iflag
argument is set to false, before dividing by these values.
FORTRAN - Prototype
A sample structure for GFOSUB is shown next. The comments explain how the subroutine works.
&
C
C === Type and dimension statements ===================
C
C
Note: For a machine with 60 or more bits per word,
218 Adams/Solver
User-Written Subroutines
C
substitute "REAL" for "DOUBLE PRECISION".
C
C - External variable definitions ----------C
INTEGER
ID
DOUBLE PRECISION
TIME
DOUBLE PRECISION
PAR( * )
INTEGER
NPAR
LOGICAL
DFLAG
LOGICAL
IFLAG
DOUBLE PRECISION
RESULT( 6 )
C
C ID
Identifier of calling GFORCE statement
C TIME
Current time
C PAR
Array containing passed parameters
C NPAR
Number of passed parameters
C DFLAG
Differencing flag
C IFLAG
Initial pass flag
C RESULT
Array (dimension 6) of computed GFORCE
C
components returned to ADAMS
C
C - Local variable and parameter definitions ----C
...
C
C === Executable code =================================
C
C Assign readable variable names to passed parameters
C
...
C
C Call SYSFNC and/or SYSARY to collect information for
C the following calculations. Note: if IFLAG is
C true, these calls are actually setting functional
C dependencies.
C
CALL SYSFNC (...)
C
C Check SYSFNC call through ERRMES utility routine
C
CALL ERRMES (...)
C
C Repeat for all required SYSFNC or SYSARY calls
C
...
C
IF (IFLAG) THEN
C
C - Subroutine initialization ------------C
...
C
ENDIF
C
GFOSUB 219
User-Written Subroutines
Examples
220 Adams/Solver
User-Written Subroutines
x c = f c ( x c, u, t )
xc ( t0 ) = xc
x dn + 1 = f d ( x dn, u, t )
x d ( t o ) = x do
y = g ( x c, x d, u, t )
(1)
(2)
(3)
and in implicit form equations (1) and (3) are replaced by equations (4) and (5), respectively, below:
0 = f c ( x c, x c, u , t )
x c ( t 0 ) = x c0
y = g ( x c, x c, x d, u, t )
(4)
(5)
GSE_DERIV defines the function fc(), shown in Equation (1) or (3) above. In the explicit case
f ( ) , (f ( ))
u c
xc c
and in implicit case following three partial derivatives should be provided:
f ( ), f ( ) , (f ( ))
c
u c
xc c
xc
GSE_UPDATE defines the function fd(), shown in Equation (2) above. It defines the derivative
of the states that the GSE introduces. GSE_UPDATE does not return any partial derivatives.
GSE_OUTPUT defines the function g(), shown in Equation (3) or (5) above. In the explicit case
g ( ), g ( )
xc
u
and in the implicit case following three partial derivatives should be provided:
g ( ), x g ( ), u g ( )
xc
c
GSE_SAMP defines the sampling period associated with Equation (2). The sampling period is
the time between two consecutive updates. It does not need to be a constant.
Use
Corresponding Statement
GSE_DERIV
Calling Sequence and Structure
SUBROUTINE GSE_DERIV (ID, TIME, PAR, NPAR, DFLAG, IFLAG, NS, XDOT)
Input Arguments
id
An integer variable containing the ID of the GSE statement requesting information from
the GSE subroutine. From the identifier, Adams/Solver automatically recognizes other
information (such as the PAR argument) that is associated with that GSE statement.
time
par
A double-precision array containing the constant parameters taken in order from the
USER parenthetical list in the GSE statement.
222 Adams/Solver
User-Written Subroutines
npar
dflag
iflag
An integer variable that Adams/Solver sets to indicate why the routine is being called:
Value
Description
Mapping dependencies
Expression serialization
Expression un-serialization
When iflag is 0 Adams/Solver calling to compute the value of the user-written variable.
When iflag is set to 1 or 3 do any initializations that your subroutine requires.
When your user-defined subroutine has static data that needs to be saved and restored to
support the Adams/Solver commands Save and Reload, then call the serialization
functions for your data when iflag is set to 7, and the un-serialization functions when iflag
is set to 9.
Note:
ns
In simple subroutines where serializing data is not needed, you can declare
iflag as a logical variable. In this case you can do any initializations when
Adams/Solver sets iflag to true, and compute the subroutine's value when
Adams/Solver sets iflag to false.
An integer variable containing the number of continuous states in the GSE; taken from
the NS argument to the GSE statement.
Output Arguments
xdot
A double-precision array of dimension NS, containing the derivatives of the state xc.
Examples
GSE_UPDATE
Calling Sequence
SUBROUTINE GSE_UPDATE (ID, TIME, PAR, NPAR, DFLAG, IFLAG, ND, XDplus1)
Input Arguments
id
An integer variable containing the ID of the GSE statement requesting information from
the GSE subroutine. From the identifier, Adams/Solver automatically recognizes other
information (such as the PAR argument) that is associated with that GSE statement.
time
par
A double-precision array containing the constant parameters taken in order from the
USER parenthetical list in the GSE statement.
npar
dflag
224 Adams/Solver
User-Written Subroutines
iflag
An integer variable that Adams/Solver sets to indicate why the routine is being called:
Value
Description
Mapping dependencies
Expression serialization
Expression un-serialization
Adams/Solver sets iflag to 3 when it needs the functional dependency of the user-defined
variable. The functional dependencies are set with the same calls to the SYSARY and
SYSFNC utility subroutines that are made to compute the value of the user-defined
variable. If iflag is 0, Adams/Solver computes the value of the user-written variable.
When your user-defined subroutine has static data that needs to be saved and restored to
support the Adams/Solver commands Save and Reload, then call the serialization
functions for your data when iflag is set to 7, and the un-serialization functions when iflag
is set to 9.
Note:
nd
In simple subroutines where serializing data is not needed, you can declare iflag
as a logical variable. In this case you declare your dependencies when
Adams/Solver sets iflag to true, and compute the subroutine's value when
Adams/Solver sets iflag to false.
An integer variable containing the number of discrete states in the GSE; taken from the
ND argument to the GSE statement.
Output Arguments
XdPlus1
A double-precision array of dimension ND, containing the value of the GSE discrete states
at time T=Tn+1.
Examples
Input Arguments
id
An integer variable containing the ID of the GSE statement requesting information from
the GSE subroutine. From the identifier, Adams/Solver automatically recognizes other
information (such as the par argument) that is associated with that GSE statement.
time
par
A double-precision array containing the constant parameters taken in order from the
USER parenthetical list in the GSE statement.
npar
dflag
iflag
An integer variable that Adams/Solver sets to indicate why the routine is being called:
Value
Description
Mapping dependencies
Expression serialization
Expression un-serialization
Adams/Solver sets iflag to 3 when it needs the functional dependency of the user-defined
variable. The functional dependencies are set with the same calls to the SYSARY and
SYSFNC utility subroutines that are made to compute the value of the user-defined
variable. If iflag is 0, Adams/Solver computes the value of the user-written variable.
When your user-defined subroutine has static data that needs to be saved and restored to
support the Adams/Solver commands Save and Reload, then call the serialization
functions for your data when iflag is set to 7, and the un-serialization functions when iflag
is set to 9.
Note:
no
In simple subroutines where serializing data is not needed, you can declare iflag
as a logical variable. In this case you declare your dependencies when
Adams/Solver sets iflag to true, and compute the subroutine's value when
Adams/Solver sets iflag to false.
An integer variable containing the number of outputs in the GSE; taken from the NO
argument to the GSE statement.
226 Adams/Solver
User-Written Subroutines
Output Arguments
A double-precision array of dimension NO, containing the value of the GSE at the current
simulation time.
Example
id
An integer variable that gives the identifier of the GSE statement requesting information
from the GSE subroutine. From the identifier, Adams/Solver automatically recognizes
other information (such as the Par argument) that is associated with that GSE statement.
time
par
A double-precision array containing the constant parameters taken in order from the USER
parenthetical list in the GSE statement.
npar
iflag
An integer variable that Adams/Solver sets to indicate why the routine is being called:
Value
Description
Mapping dependencies
Expression serialization
Expression un-serialization
Adams/Solver sets iflag to 3 when it needs the functional dependency of the user-defined
variable. The functional dependencies are set with the same calls to the SYSARY and
SYSFNC utility subroutines that are made to compute the value of the user-defined
variable. If iflag is 0, Adams/Solver computes the value of the user-written variable.
When your user-defined subroutine has static data that needs to be saved and restored to
support the Adams/Solver commands Save and Reload, then call the serialization functions
for your data when iflag is set to 7, and the un-serialization functions when iflag is set to 9.
Note:
In simple subroutines where serializing data is not needed, you can declare iflag
as a logical variable. In this case you declare your dependencies when
Adams/Solver sets iflag to true, and compute the subroutine's value when
Adams/Solver sets iflag to false.
Output Arguments
sample_step
A double-precision scalar, containing the sample step (that is, the difference
between the next sample time, and the current simulation).
Example
228 Adams/Solver
User-Written Subroutines
void
void
void
void
void
/*
*
GSE
*/
struct sAdamsGSE
{
int ID;
int NPAR;
const double* PAR;
int NI;
int NO;
int U;
int Y;
int NS;
int X;
int IC;
int STATIC_HOLD;
int IMPLICIT;
int ND;
int XD;
int ICD;
double SAMPLE_OFFSET;
};
230 Adams/Solver
User-Written Subroutines
MFOSUB
MFOSUB is an evaluation subroutine that computes the modal force corresponding to an MFORCE
statement (C++ or FORTRAN). MFOSUB is optional. You need it only if you don't want to use a function
expression in the MFORCE statement, or if you need the added capabilities of the USER form of the
MFORCE statement.
Use
Corresponding Statement
You invoke the MFOSUB by using either the FUNCTION or FORCE option in the MFORCE statement.
The MFOSUB output arguments are interpreted differently depending on the form used. Adams/Solver
(C++) can invoke the MFOSUB using either form. Adams/Solver (FORTRAN) can only invoke the
MFOSUB using FUNCTION.
Calling Sequence
id
An integer variable that provides the identifier of the MFORCE statement that is
requesting information from the MFOSUB.
time
par
A double-precision array of constants taken in order from the USER parenthetical list of
the MFORCE statement.
npar
An integer variable that indicates the number of constants specified in the USER
parenthetical list. The primary purpose of npar is to enable MFOSUB to correctly
dimension the par array.
MFOSUB 231
User-Written Subroutines
dflag
A logical variable that Adams/Solver sets to true when calling MFOSUB to evaluate the
partial derivatives of the specified functions. Otherwise, Adams/Solver sets dflag to false.
iflag
An integer variable that Adams/Solver sets to indicate why the routine is being called:
Value
Description
Mapping dependencies
Expression serialization
Expression un-serialization
Adams/Solver sets iflag to 3 when it needs the functional dependency of the user-defined
variable. The functional dependencies are set with the same calls to the SYSARY and
SYSFNC utility subroutines that are made to compute the value of the user-defined
variable. If iflag is 0, Adams/Solver computes the value of the user-written variable.
When your user-defined subroutine has static data that needs to be saved and restored to
support the Adams/Solver commands Save and Reload, then call the serialization
functions for your data when iflag is set to 7, and the un-serialization functions when iflag
is set to 9.
Note:
In simple subroutines where serializing data is not needed, you can declare iflag
as a logical variable. In this case you declare your dependencies when
Adams/Solver sets iflag to true, and compute the subroutine's value when
Adams/Solver sets iflag to false.
modloads
A double-precision array containing the values of the modal load cases that are defined for
the FLEX_BODY and that the MFORCE is acting on. The modload array has the
dimensions modload (6+nmodes, ncases).
nmodes
An integer variable that indicates the number of modes in the associated FLEX_BODY.
The value of nmodes provides MFOSUB with a way to correctly dimension the modloads
and loadvec arrays.
ncases
An integer variable that indicates the number of load cases available in the associated
FLEX_BODY. The value of ncases provides MFOSUB with a means to correctly
dimension the modloads array. If ncases=0, then the contents of modloads are undefined
because no user-defined load cases are available for the FLEX_BODY.
232 Adams/Solver
User-Written Subroutines
Output Arguments
scale
A double-precision variable.
If MFOSUB is called with the FUNCTION form:
This output argument contains the scale factor that is to be applied to the modal load
vector. The value of scale can depend on the values Adams/Solver calls from SYSFNC
and SYSARY (see SYSARY and SYSFNC).
If MFOSUB is called with the FORCE form:
Adams/Solver ignores this output argument.
case
loadvec
Examples
A sample for MFOSUB is shown next. In this example, MFOSUB is invoked using the FUNCTION form
and uses load case 3 and scales it with 10.
MFOSUB 233
User-Written Subroutines
C
C
$
$
ERRFLG = NCASES.LT.CASE
CALL ERRMES(ERRFLG, 'Trying to use an invalid load case.',
&
ID, 'STOP' )
RETURN
END
234 Adams/Solver
User-Written Subroutines
MFOSUB 235
User-Written Subroutines
END DO
C
RETURN
END
236 Adams/Solver
User-Written Subroutines
MOTSUB
The MOTSUB evaluation subroutine computes the joint displacement, velocity, or acceleration for a
MOTION statement (C++ or FORTRAN). MOTSUB is optional. You only need it if you don't want to
use a function expression in the MOTION statement.
Use
Corresponding Statement
Calling Sequence
MOTSUB 237
User-Written Subroutines
Input Arguments
id
An integer variable that provides the identifier of the MOTION statement requesting
information from MOTSUB. From the identifier, Adams/Solver automatically knows
other information (such as the par argument) available in the corresponding statement.
iflag
An integer variable that Adams/Solver sets to indicate why the routine is being called:
Value
Description
Mapping dependencies
Expression serialization
Expression un-serialization
When iflag is 0 Adams/Solver calling to compute the value of the user-written variable.
When iflag is set to 1 or 3 do any initializations that your subroutine requires.
When your user-defined subroutine has static data that needs to be saved and restored to
support the Adams/Solver commands Save and Reload, then call the serialization
functions for your data when iflag is set to 7, and the un-serialization functions when iflag
is set to 9.
Note:
iord
In simple subroutines where serializing data is not needed, you can declare
iflag as a logical variable. In this case you can do any initializations when
Adams/Solver sets iflag to true, and compute the subroutine's value when
Adams/Solver sets iflag to false.
An input integer variable indicating the order of the time derivative that Adams/Solver
requires at different points in the analysis.
When the motion is a displacement, Adams/Solver, at various times, calls MOTSUB with
IORD set to 0, 1, or 2, requesting the displacement value and its first and second time
derivatives, respectively.
When the motion is a velocity, Adams/Solver only calls MOTSUB with IORD set to 0 or
1, and returns the velocity value and its time derivative, respectively. The second time
derivative, a velocity motion, is never required.
When the motion is an acceleration, Adams/Solver only uses IORD set to 0. No time
derivatives of the function used in the MOTSUB for an acceleration motion are needed.
npar
An integer variable that indicates the number of constants specified in the USER
parenthetical list. The primary purpose of npar is to provide MOTSUB with the number
of values stored in the par array.
238 Adams/Solver
User-Written Subroutines
par
A double-precision array of constants taken in order from the USER parenthetical list of
the MOTION statement.
time
Output Arguments
value
A double-precision variable that returns the zeroth, first, or second derivative of the motion
of the I marker with respect to the J marker. These derivatives represent the displacement,
velocity, and acceleration of the motion, respectively. The value of IORD indicates which
derivative of motion value must return.
Extended Definition
In most cases, the MOTION statement with a function expression is adequate for defining the motion
input. However, if the expression becomes lengthy and awkward, you should use the
FUNCTION=USER() argument in the MOTION statement, and write a MOTSUB to calculate the
displacement.
MOTSUB measures translational displacements from the origin of the J marker to the origin of the I
marker. The positive z-axis of the J marker defines the positive direction. MOTSUB measures rotational
displacements from the x-axis of the J marker to the x-axis of the I marker. The right-hand rule defines a
positive angle with respect to the positive z-axis of the J marker.
MOTSUB output must be strictly a function of time. Consequently, MOTSUB must not call the
SYSARY and SYSFNC utility subroutines. To describe discrete time-dependent functions, MOTSUB
may call the CUBSPL utility subroutine.
Caution:
Define the motion only as a function of time. Don't make calls to the SYSARY and
SYSFNC utility subroutines to access other system variables or to access userdefined variables.
Make sure the first and second derivatives MOTSUB returns for displacement are
correct.
If the CUBSPL utility subroutine or any of the Adams/Solver utility subroutines
are used, do not forget to involve the derivatives returned by these subroutines
when the MOTSUB derivatives are evaluated.
Avoid conditional branching that results in discontinuous accelerations, velocities,
or displacements.
Make sure MOTSUB uses length units to define translational displacements and
MOTSUB 239
User-Written Subroutines
FORTRAN - Prototype
A sample structure for MOTSUB is shown next. The comments explain how the subroutine works.
SUBROUTINE MOTSUB ( ID, TIME, PAR, NPAR, IORD,
&
IFLAG, VALUE )
C
C === Type and dimension statements ===================
C
C Note: For machines with 60 or more bits per word,
C
substitute "REAL" for "DOUBLE PRECISION".
C
C - External variable definitions --------C
INTEGER
ID
DOUBLE PRECISION
TIME
DOUBLE PRECISION
PAR( * )
INTEGER
NPAR
INTEGER
IORD
LOGICAL
IFLAG
DOUBLE PRECISION
VALUE
C
C ID
Identifier of calling MOTION statement
C TIME
Current time
C PAR
Array containing passed parameters
C NPAR
Number of passed parameters
C IORD
Derivative order of value to be returned
C IFLAG
Initialization pass flag
C VALUE
Derivative value of MOTION returned to ADAMS
C
C - Local variable and parameter definitions ---C
...
C
C === Executable code =================================
C
C Assign parameters to readable variable names
C
...
C
IF ( IFLAG ) THEN
C
C - Subroutine initialization ----------C
...
C
ENDIF
C
C - Compute and assign the motion displacement --C
IF ( IORD .EQ. 0 ) THEN
C
C Your algorithm
C
...
240 Adams/Solver
User-Written Subroutines
C
C Assign a value to VALUE for the motion displacement
C
VALUE = ...
C
C - Compute and assign the motion velocity ----C
ELSE IF ( IORD .EQ. 1 ) THEN
C
C Your algorithm
C
...
C
C Assign a value to VALUE for the motion velocity
C
VALUE = ...
C
C - Compute and assign the motion acceleration --C
ELSE
C
C Your algorithm
C
...
C
C Assign a value to VALUE for the motion acceleration
C
VALUE = ...
C
ENDIF
C
RETURN
END
C Style - Protoype
typedef void adams_c_MOTSUB(const struct sAdamsMotion* motion, double
TIME, int DFLAG, int IFLAG, double* RESULT);
/*
*
MOTION
*/
struct sAdamsMotion
{
int ID;
int NPAR;
const double* PAR;
int JOINT;
const char* Type;
int I;
int J;
char Which[2];
const char* DVA;
};
MOTSUB 241
User-Written Subroutines
Examples
242 Adams/Solver
User-Written Subroutines
RELSUB
The RELSUB restart subroutine allows you to reload any information needed to restart user-written
subroutines. Adams/Solver calls SAVSUB during a SAVE command to write user data. RELSUB can
then read the data during a RELOAD command.
SAVSUB and RELSUB are optional. You only need them if you want the SAVE and RELOAD
commands to save and reload user data, in addition to internal Adams/Solver data.
Use
Corresponding Command
Calling Sequence
iunit
An integer variable that contains the FORTRAN IO unit of the Adams/Solver save file.
Adams/Solver opens the save file as sequential and unformatted. If SAVSUB has written
data to the save file, the RELSUB may read it from this unit with an unformatted
FORTRAN READ statement.
Output Argument
errflg
Tip:
A logical variable that indicates to Adams/Solver that an error has occurred while reading
user data. If you set errflg to true, Adams/Solver writes an error message to the screen and
to the message file.
The most straightforward way to reinitialize user-written subroutines may be to collect the
necessary variables in a COMMON block, use SAVSUB to write them to the save file, and
RELSUB to read them back from the save file.
RELSUB 243
User-Written Subroutines
Caution:
RELSUB must read data from the save file in the same order in which SAVSUB wrote the
data.
Structure
A sample structure for RELSUB is shown next. The comments describe how the subroutine works.
SUBROUTINE RELSUB(IUNIT, ERRFLG)
C
C === Type and dimension statements ===================
C
C --- External variable definitions ------------------C
INTEGER IUNIT
LOGICAL ERRFLG
C
C IUNIT
FORTRAN IO unit attached to Save File
C ERRLFG
used to signal problems back to ADAMS
C
C --- COMMON Blocks ----------------------------------C
COMMON ...
C
C === Executable code =================================
C
C Read in the information which appears in the COMMON
C blocks, through which this routine shares information
C with other user-written subroutines.
C
READ (IUNIT) ...
C
RETURN
END
Example
244 Adams/Solver
User-Written Subroutines
REQSUB
The REQSUB evaluation subroutine computes the output values for a REQUEST statement (C++ or
FORTRAN). REQSUB is optional. You only need it if you do not want to use the standard requests or
F1,F2,...,F8 expressions in the REQUEST statement.
Use
Corresponding Statement
Calling Sequence
REQSUB 245
User-Written Subroutines
Input Arguments
id
An integer variable that provides the identifier of the REQUEST statement requesting
information from REQSUB. From the identifier, Adams/Solver automatically knows
other information (such as the par argument) available in the corresponding statement.
iflag
An integer variable that Adams/Solver sets to indicate why the routine is being called:
Value
Description
Mapping dependencies
Expression serialization
Expression un-serialization
Adams/Solver sets iflag to 3 when it needs the functional dependency of the user-defined
variable. The functional dependencies are set with the same calls to the SYSARY and
SYSFNC utility subroutines that are made to compute the value of the user-defined
variable. If iflag is 0, Adams/Solver computes the value of the user-written variable.
When your user-defined subroutine has static data that needs to be saved and restored to
support the Adams/Solver commands Save and Reload, then call the serialization
functions for your data when iflag is set to 7, and the un-serialization functions when iflag
is set to 9.
Note:
In simple subroutines where serializing data is not needed, you can declare iflag
as a logical variable. In this case you declare your dependencies when
Adams/Solver sets iflag to true, and compute the subroutine's value when
Adams/Solver sets iflag to false.
npar
An integer variable that indicates the number of constants specified in the USER
parenthetical list. The primary purpose of npar is to provide REQSUB with the number of
values stored in the par array.
par
A double-precision array of constants taken in order from the USER parenthetical list of
the REQUEST statement.
time
246 Adams/Solver
User-Written Subroutines
Output Argument
result
A double-precision array of eight values that contains the values you calculate in the
REQSUB. Adams/Solver sends all the values and the current time to the tabular output
file.
If the dataset contains an OUTPUT statement with the REQSAVE argument,
Adams/Solver stores values two through four, and six through eight in the request file
for subsequent plotting in the postprocessor (see the C++ OUTPUT command or the
FORTRAN OUTPUT command).
Adams/Solver does not store columns one and five in the request file. These columns
usually contain translational and rotational magnitude values for the request. If the
dataset contains a RESULTS statement without the NODATASTRUCTURES
argument, Adams/Solver stores all eight values in the results file for subsequent
postprocessing. If fewer than eight values are used in the result array, Adams/Solver
sets the remaining values to zero.
Extended Definition
The REQUEST and MREQUEST statements are usually adequate for outputting displacement, velocity,
acceleration, or force data between two markers in the system. But if you want to output other quantities,
include the FUNCTION=USER() argument in the REQUEST statement and define the request output in
a REQSUB.
REQSUB passes back an array of eight values. You can call any utility subroutine from REQSUB to
make any element in the result array functionally dependent on system displacements, velocities,
accelerations, forces, user-defined differential variables, or on-spline data.
Tip:
FORTRAN - Prototype
A sample structure for REQSUB is shown next. The comments explain how the subroutine works.
SUBROUTINE REQSUB ( ID, TIME, PAR, NPAR, IFLAG,
&
RESULT )
C
C === Type and dimension statements ===================
C
C - External variable definitions --------C
INTEGER
ID
DOUBLE PRECISION
TIME
REQSUB 247
User-Written Subroutines
C
C
C
C
C
C
C
C
C
C
DOUBLE PRECISION
INTEGER
LOGICAL
DOUBLE PRECISION
ID
TIME
PAR
NPAR
IFLAG
RESULT
PAR( * )
NPAR
IFLAG
RESULT( 8 )
...
C
C === Executable code =================================
C
C Assign parameter values to readable variable names
C
...
C
IF( IFLAG ) THEN
C
C - Subroutine initialization ----------C
...
C
ENDIF
C
C - Create request information ----------C
C Your algorithms
C
...
C
C Assign values to the result array
C
RESULT(1) = ...
...
RESULT(8) = ...
C
RETURN
END
C Style - Prototype
typedef void adams_c_REQSUB(const struct sAdamsRequest* req, double
TIME, int IFLAG, double* OUTPUT);
/*
*
REQUEST
---------------------------------------------------------------*/
struct sAdamsRequest
248 Adams/Solver
User-Written Subroutines
};
int ID;
int NPAR;
const double* PAR;
const char* COMMENT;
const char* TITLE[8];
Examples
SAVSUB 249
User-Written Subroutines
SAVSUB
The SAVSUB restart subroutine allows you to store any information needed to later restart user-written
subroutines. Adams/Solver calls SAVSUB during a SAVE command to write user data. The RELSUB
restart subroutine can then read the data during a RELOAD command.
SAVSUB and RELSUB are optional. You only need them if you want to use the SAVE and RELOAD
commands to save and reload user data, in addition to internal Adams/Solver data.
Use
Corresponding Command
Calling Sequence
iunit
An integer variable that contains the FORTRAN IO unit of the Adams/Solver save file.
Adams/Solver opens the save file as sequential and unformatted. You may store data in the
save file by writing it to this unit with an unformatted FORTRAN WRITE statement.
Output Argument
errflg
Tip:
A logical variable that indicates to Adams/Solver that an error has occurred while saving
user data. If you set errflg to true, Adams/Solver writes an error message to the screen and
to the message file.
250 Adams/Solver
User-Written Subroutines
Caution:
RELSUB must read data from the save file in the same order in which SAVSUB wrote the
data.
Structure
A sample structure for SAVSUB is shown next. The comments describe how the subroutine works.
SUBROUTINE SAVSUB(IUNIT, ERRFLG)
C
C === Type and dimension statements ===================
C
C --- External variable definitions ------------------C
INTEGER IUNIT
LOGICAL ERRFLG
C
C IUNIT
FORTRAN IO unit attached to Save File
C ERRLFG
used to signal problems back to ADAMS
C
C --- COMMON Blocks ----------------------------------C
COMMON...
C
C === Executable code =================================
C
C Write out the information which appears in the COMMON
C blocks, through which this routine shares information
C with other user-written subroutines.
C
WRITE (IUNIT) ...
C
RETURN
END
Example
SENSUB 251
User-Written Subroutines
SENSUB
The SENSUB evaluation subroutine computes the values sensed by a SENSOR statement (C++ or
FORTRAN). SENSUB is optional. You only need it if you do not want to use a function expression in
the SENSOR statement.
Use
Corresponding Statement
Calling Sequence
id
An integer variable that contains the ID of the SENSOR statement that requests information
from SENSUB. From the identifier, Adams/Solver automatically knows other information
(such as the par argument) available in the corresponding statement.
time
252 Adams/Solver
User-Written Subroutines
par
A double-precision array of constants taken, in order, from the USER parenthetical list of
the SENSOR statement.
npar
An integer variable that indicates the number of constants specified in the USER
parenthetical list. The primary purpose of npar is to provide SENSUB with the number of
values stored in the par array.
iflag
An integer variable that Adams/Solver sets to indicate why the routine is being called:
Value
Description
Mapping dependencies
Expression serialization
Expression un-serialization
Adams/Solver sets iflag to 3 when it needs the functional dependency of the user-defined
variable. The functional dependencies are set with the same calls to the SYSARY and
SYSFNC utility subroutines that are made to compute the value of the user-defined
variable. If iflag is 0, Adams/Solver computes the value of the user-written variable.
When your user-defined subroutine has static data that needs to be saved and restored to
support the Adams/Solver commands Save and Reload, then call the serialization functions
for your data when iflag is set to 7, and the un-serialization functions when iflag is set to 9.
Note:
In simple subroutines where serializing data is not needed, you can declare iflag
as a logical variable. In this case you declare your dependencies when
Adams/Solver sets iflag to true, and compute the subroutine's value when
Adams/Solver sets iflag to false.
Output Argument
value
A double-precision variable that contains the value of the function that SENSUB
evaluates.
Extended Definition
The SENSOR statement with a function expression is usually adequate for most sensing requirements.
However, if the expression becomes lengthy and awkward, you should use the FUNCTION=USER()
argument in the SENSOR statement, and write a SENSUB to define the function you want to sense.
SENSUB 253
User-Written Subroutines
To access information on which the function depends, you can use the utility subroutines such as
AKISPL, CUBSPL, SYSARY, and SYSFNC in SENSUB.
Tip:
If the SYSARY or SYSFNC utility subroutines are called to access angular displacements,
the values returned by them may contain discontinuities. To avoid the discontinuities, use
the RCNVRT utility subroutine to convert the rotational angles from Euler angles to some
other rotational representation that does not encounter a singularity.
FORTRAN - Prototype
A sample structure for SENSUB is shown next. The comments explain how the subroutine works.
SUBROUTINE SENSUB ( ID, TIME, PAR, NPAR, IFLAG,
&
VALUE )
C
C === Type and dimension statements ===================
C
C - External variable definitions --------C
INTEGER
ID
DOUBLE PRECISION
TIME
DOUBLE PRECISION
PAR( * )
INTEGER
NPAR
LOGICAL
IFLAG
DOUBLE PRECISION
VALUE
C
C ID
Identifier of calling SENSOR statement
C TIME
Current time
C PAR
Array of passed statement parameters
C NPAR
Number of passed parameters
C IFLAG
Initialization pass flag
C VALUE
The returned value of the sensor
C
C - Local variable definitions ----------C
...
C
C === Executable code =================================
C
C Assign parameter values to readable variables
C
...
C
IF( IFLAG ) THEN
C
C - Subroutine initialization ----------C
...
C
ENDIFCC - Evaluate sensor ---------------C
254 Adams/Solver
User-Written Subroutines
C Your algorithm
C
...
C
C Assign the returned value
C
VALUE = ...
C
RETURN
END
C Style - prototype
typedef void adams_c_SENSUB(const struct sAdamsSensor* sensor, double
TIME, int IFLAG, double* OUTPUT);
/*
*
SENSOR
---------------------------------------------------------------struct sAdamsSensorEval
{
int NPAR;
const double* PAR;
};
*/
struct sAdamsSensor
{
int ID;
int NPAR;
const double* PAR;
double VALUE;
double Error;
char Logic[2];
/* struct sAdamsSensorEval Eval; */
};
Examples
SEVSUB 255
User-Written Subroutines
SEVSUB
The SEVSUB evaluation subroutine computes a scalar value that a SENSOR statement (C++ or
FORTRAN) stores and is available through the SENVAL function expression. SEVSUB is evaluated
only when the event defined by the SENSOR occurs. SEVSUB is optional. You only need it if you do
not want to use a function expression in the EVALUATE argument of the SENSOR statement.
Use
Corresponding Statement
Calling Sequence
id
An integer variable that contains the ID of the SENSOR statement that requests information
from SEVSUB. From the identifier, Adams/Solver automatically knows other information
(such as the par argument) available in the corresponding statement.
time
256 Adams/Solver
User-Written Subroutines
par
A double-precision array of constants taken, in order, from the USER parenthetical list of
the SENSOR statement.
npar
An integer variable that indicates the number of constants specified in the USER
parenthetical list. The primary purpose of npar is to provide SEVSUB with the number of
values stored in the par array.
iflag
An integer variable that Adams/Solver sets to indicate why the routine is being called:
Value
Description
Mapping dependencies
Expression serialization
Expression un-serialization
Adams/Solver sets iflag to 3 when it needs the functional dependency of the user-defined
variable. The functional dependencies are set with the same calls to the SYSARY and
SYSFNC utility subroutines that are made to compute the value of the user-defined variable.
If iflag is 0, Adams/Solver computes the value of the user-written variable.
When your user-defined subroutine has static data that needs to be saved and restored to
support the Adams/Solver commands Save and Reload, then call the serialization functions
for your data when iflag is set to 7, and the un-serialization functions when iflag is set to 9.
Note:
In simple subroutines where serializing data is not needed, you can declare iflag
as a logical variable. In this case you declare your dependencies when
Adams/Solver sets iflag to true, and compute the subroutine's value when
Adams/Solver sets iflag to false.
Output Argument
result
A double-precision variable that returns the value of the EVALUATE function for the
SENSOR.
Extended Definition
Defining the EVALUATE argument of SENSOR with a function expression is usually sufficient for must
users. If the expression becomes lengthy and awkward, however, you can use SEVSUB. If the algorithms
for computing the EVALUATE function use or consist of existing subroutines, SEVSUB can be made to
call them.
SEVSUB 257
User-Written Subroutines
SEVSUB is only called by Adams/Solver when the event defined by the SENSOR occurs. Adams/Solver
evaluates whether a SENSOR event has occurred only when it has determined the state of the system for
the current time step.
Once the EVALUATE function has been evaluated, Adams/Solver stores the result until the SENSOR
event reoccurs. The most recent value of the EVALUATE function is available through the SENVAL
function expression.
FORTRAN - Prototype
A sample structure for SEVSUB is shown next. The comments explain how the subroutine works.
SUBROUTINE SEVSUB ( ID, TIME, PAR, NPAR, IFLAG,
&
RESULT )
C
C === Type and dimension statements ===================
C
C
C --- External variable definitions ------------------C
INTEGER
ID
DOUBLE PRECISION
TIME
DOUBLE PRECISION
PAR( * )
INTEGER
NPAR
LOGICAL
IFLAG
DOUBLE PRECISION
RESULT
C
C ID
Identifier of calling SENSOR statement
C TIME
Current time
C PAR
Array of passed statement parameters
C NPAR
Number of passed parameters
C IFLAG
Initialization pass flag
C RESULT
Scalar value returned to ADAMS
C
C --- Local variable definitions ---------------------C
...
C
C === Executable code =================================
C
C --- Assign parameter values to readable variable names
C
...
C
IF( IFLAG ) THEN
C
C --- Subroutine initialization ----------C
...
C
ENDIF
C
C --- Compute the result
C
258 Adams/Solver
User-Written Subroutines
C Your algorithm
C
...
C
C --- Assign the return value
C
RESULT = ...
C
RETURN
END
C Style - Prototype
typedef void adams_c_SEVSUB(const struct sAdamsSensor* sensor, double
TIME, int IFLAG, double* OUTPUT);
/*
*
SENSOR
struct sAdamsSensorEval
{
int NPAR;
const double* PAR;
};
*/
struct sAdamsSensor
{
int ID;
int NPAR;
const double* PAR;
double VALUE;
double Error;
char Logic[2];
/* struct sAdamsSensorEval Eval; */
};
Examples
SFOSUB 259
User-Written Subroutines
SFOSUB
The SFOSUB evaluation subroutine computes the force magnitude for an SFORCE statement. SFOSUB
is optional. You only need it if you don't want to use a function expression in the SFORCE statement
(C++ or FORTRAN).
Use
Corresponding Statement
Calling Sequence
id
An integer variable that contains the ID of the SFORCE statement that requests
information from SFOSUB. From the identifier, Adams/Solver automatically knows other
information (such as the par argument) available in the corresponding statement.
time
par
A double-precision array of constants taken in order from the USER parenthetical list of
the SFORCE statement.
dflag
A logical variable that Adams/Solver sets to true when it calls SFOSUB to evaluate partial
derivatives of the function. Otherwise, Adams/Solver sets dflag to false. See Using the
DFLAG Variable.
260 Adams/Solver
User-Written Subroutines
npar
An integer variable that indicates the number of constants specified in the USER
parenthetical list. The primary purpose of npar is to provide SFOSUB with the number of
values stored in the par array.
iflag
An integer variable that Adams/Solver sets to indicate why the routine is being called:
Value
Description
Mapping dependencies
Expression serialization
Expression un-serialization
Adams/Solver sets iflag to 3 when it needs the functional dependency of the user-defined
variable. The functional dependencies are set with the same calls to the SYSARY and
SYSFNC utility subroutines that are made to compute the value of the user-defined
variable. If iflag is 0, Adams/Solver computes the value of the user-written variable.
When your user-defined subroutine has static data that needs to be saved and restored to
support the Adams/Solver commands Save and Reload, then call the serialization
functions for your data when iflag is set to 7, and the un-serialization functions when iflag
is set to 9.
Note:
In simple subroutines where serializing data is not needed, you can declare iflag
as a logical variable. In this case you declare your dependencies when
Adams/Solver sets iflag to true, and compute the subroutine's value when
Adams/Solver sets iflag to false.
Output Argument
value
A double-precision variable that contains the force value that SFOSUB computes.
Extended Definition
The SFORCE statement (C++ or FORTRAN) with a function expression is usually adequate for defining
most single-component forces. If the expression becomes lengthy and awkward, however, you should use
the FUNCTION=USER() argument in the SFORCE statement, and write an SFOSUB to calculate the
single-component force.
You can call utility subroutines, such as SYSARY, SYSFNC, AKISPL, and CUBSPL, from SFOSUB to
obtain information about system variables, user-defined variables, and splines.
SFOSUB 261
User-Written Subroutines
The SYSARY and SYSFNC utility subroutines automatically set functional dependencies when the
SFOSUB argument iflag is true. For Adams/Solver to compute solutions efficiently, it must know
on which other variables each user-defined SFORCE directly depends. Adams/Solver determines these
functional dependencies at the beginning of the simulation by calling SFOSUB evaluation subroutine
with argument iflag set to true. Adams/Solver does this once for each SFORCE statement with a
FUNCTION=USER() argument. During each call to SFOSUB, Adams/Solver records which calls you
make to SYSARY and SYSFNC. Adams/Solver assumes the SFORCE depends on those system
variables, and no others.
Tip:
If the SYSARY or SYSFNC utility subroutines are called to access angular displacements,
the values they return may contain discontinuities. To avoid the discontinuities, use the
RCNVRT utility subroutine to convert the rotational angles from Euler angles to some
other rotational representation that does not encounter a singularity.
Caution:
and SYSFNC that are made when actually computing the value of the user-defined
SFORCE. This ensures that Adams/Solver has the proper functional dependencies.
In general, failure to account for dependencies of the user-defined SFORCE might
make it difficult for Adams/Solver to converge to a solution and/or might force
Adams/Solver to take small integration steps. Both of these usually cause large
increases in execution time.
When the iflag argument is true, SYSARY and SYSFNC return zero values for
system and user-defined variables. Computations that divide by these values result
in system errors when Adams/Solver is executed. Be sure to check for nonzero
values, or the iflag argument set to false, before dividing by these values.
FORTRAN - Prototype
A sample structure for SFOSUB is shown next. The comments explain how the subroutine works.
SUBROUTINE SFOSUB ( ID, TIME, PAR, NPAR, DFLAG,
&
IFLAG, VALUE )
C
C === Type and dimension statements ===================
C
C Note: For machines with 60 or more bits per word,
262 Adams/Solver
User-Written Subroutines
C
substitute "REAL" for "DOUBLE PRECISION".
C
C - External variable definitions --------C
INTEGER
ID
DOUBLE PRECISION
TIME
DOUBLE PRECISION
PAR( * )
INTEGER
NPAR
LOGICAL
DFLAG
LOGICAL
IFLAG
DOUBLE PRECISION
VALUE
C
C ID
Identifier of calling SFORCE statement
C TIME
Current time
C PAR
Array of passed statement parameters
C NPAR
Number of passed parameters
C DFLAG
Differencing flag
C IFLAG
Initialization pass flag
C VALUE
The SFORCE value returned to ADAMS
C
C - Local variable definitions ----------C
...
C
C === Executable code =================================
C
C Assign parameters to readable variable names
C
...
C
C Call SYSFNC and/or SYSARY to collect information for
C calculations below. Note: if IFLAG is true, these
C calls are actually setting functional dependencies.
C
CALL SYSFNC ( ... )
C
CALL ERRMES ( ... )
C
C Repeat for all required SYSFN
C or SYSARY calls
C
...
C
IF( IFLAG ) THEN
C
C - Subroutine initialization ----------C
...
C
ENDIF
C
C - Evaluate force ----------------C
C Your algorithm
SFOSUB 263
User-Written Subroutines
...
C
C Assign the returned value
C
VALUE = ...
C
RETURN
END
C Style - Prototype
typedef void adams_c_SFOSUB(const struct sAdamsSforce* sforce, double
TIME, int DFLAG, int IFLAG, double* RESULT);
/*
*
SFORCE
*/
struct sAdamsSforce
{
int ID;
int NPAR;
const double* PAR;
int I;
int J;
int ACTION_ONLY;
const char* Type;
};
Examples
264 Adams/Solver
User-Written Subroutines
SPLINE_READ
SPLINE_READ reads x, y, [and z] data from a file to a SPLINE statement. The SPLINE_READ
subroutine is optional. You use it only if you do not want to use the X and Y arguments in the SPLINE
statement (C++ or FORTRAN).
Use
Corresponding Statement
SPLINE/id
, X=x1, x2, x3, x4 [, . . . , xn]
, Y=y1, y2, y3, y4 [, . . . , yn]
[,LINEAR_EXTRAPOLATE]
or
SPLINE/id
, X=x1, x2, x3, x4 [, . . . , xn]
, Y=z1, y11, y12, y13, y14 [, . . . ,y1n]
, Y=z2, y21, y22, y23, y24 [, . . . ,y2n]
, Y=z3, y31, y32, y33, , LINEAR_EXTRAPOLATE y34 [, . . . ,y3n]
, Y=z4, y41, y42, y43, y44 [, . . . ,y4n]
[, . . . , Y=zm, ym1, ym2, ym3, ym4,[, . . . ,ymn]]
[, LINEAR_EXTRAPOLATE]
or
SPLINE/id
, FILE=filename
[, BLOCK=blockname]
[, LINEAR_EXTRAPOLATE]
id
SPLINE_READ 265
User-Written Subroutines
file_name
A character array of dimension 132 that contains the FILE name that you specify using
the FILE argument in the corresponding SPLINE statement.
block_name
A character array of dimension 132 that contains the BLOCK name (if any) that you
specify using the BLOCK argument of the corresponding SPLINE statement.
Output Argument
status
A logical variable that indicates if SPLINE_READ successfully reads and passes the x,
y, [and z] data from the file to Adams/Solver. If the SPLINE data does not pass correctly,
you can set the status to .TRUE. using PUT_SPLINE, which stops the appropriate
operations in Adams/Solver. Otherwise, set the status to .FALSE.
Extended Definition
If you are a novice Adams/SOLVER user, you can use the X and Y arguments in the SPLINE statement
to define the spline elements. If you are an expert user and a sizeable amount of data is required to define
the spline elements, you might prefer to use the FILE argument in the SPLINE statement in conjunction
with the SPLINE_READ user-written subroutine.
Adams/Solver calls SPLINE_READ during the model-input phase. At this point, the model is not fully
defined, and consequently, SPLINE_READ may not call most utility subroutines. SPLINE_READ must
call the PUT_SPLINE utility subroutine in order to pass Adams/Solver the x, y, [and z] data that it reads
from the file (see PUT_SPLINE).
FORTRAN - Prototype
A sample structure for the SPLINE_READ subroutine follows next. The comments explain the activities
that the subroutine performs.
SUBROUTINE SPLINE_READ (ID, FILE_NAME, BLOCK_NAME, STATUS)
C
C === Type and dimension statements ===================
C
C Note: For machines with 60 or more bits per word,
C
substitute "REAL" for "DOUBLE PRECISION".
C
C - External variable definitions --------C
INTEGERID
CHARACTER*132FILE_NAME
CHARACTER*132BLOCK_NAME
LOGICALSTATUS
C
C IDIdentifier of calling SPLINE statement
C FILE_NAMEName of file containing data to define spline
C BLOCK_NAMEName of named block within the file to be
C
used for this spline
C STATUS Error status flag
C
266 Adams/Solver
User-Written Subroutines
SURSUB 267
User-Written Subroutines
SURSUB
SURSUB is an evaluation subroutine that computes surface coordinates and their derivatives for a
SURFACE element (C++). The use of SURSUB is optional; it is not required when a Parasolid file is
provided as input for the surface definition.
Use
Corresponding Statement
Calling Sequence
268 Adams/Solver
User-Written Subroutines
Input Arguments
id
An integer variable that provides the identifier of the SURFACE statement that is being
defined by SURSUB.
iflag
An integer variable that Adams/Solver sets to indicate why the routine is being called:
Value
Description
Mapping dependencies
Expression serialization
Expression un-serialization
When iflag is 0 Adams/Solver calling to compute the value of the user-written variable.
When iflag is set to 1 or 3 do any initializations that your subroutine requires.
When your user-defined subroutine has static data that needs to be saved and restored to
support the Adams/Solver commands Save and Reload, then call the serialization functions
for your data when iflag is set to 7, and the un-serialization functions when iflag is set to 9.
Note:
iord
In simple subroutines where serializing data is not needed, you can declare iflag
as a logical variable. In this case you can do any initializations when
Adams/Solver sets iflag to true, and compute the subroutine's value when
Adams/Solver sets iflag to false.
An integer variable that specifies the order of the derivative that SURSUB returns. The
possible values are:
zero - Return surface coordinates.
one - Return first derivatives with respect to u, v.
two - Return second derivatices with respect to u, v.
npar
An integer variable that indicates the number of constants specified in the USER
parenthetical list. The purpose of npar is to provide SURSUB with the number of values
stored in the par array.
par
A double-precision array of constants that is taken in order from the USER parenthetical list
of the SURFACE statement.
SURSUB 269
User-Written Subroutines
A double-precision variable that specifies the value of the independent parameter u, which
SURSUB uses to evaluate coordinates of a point on the surface. Adams/Solver restricts u to
be:
Greater than or equal to the MINPAR[1] value on the SURFACE statement (-1.0 by
default).
Less than or equal to the MAXPAR[1] value on the SURFACE statement (1.0 by default).
A double-precision variable that specifies the value of the independent parameter v which
SURSUB uses to evaluate coordinates of a point on the surface. Adams/Solver restricts v to
be:
Greater than or equal to the MINPAR[2] value on the SURFACE statement (-1.0 by
default).
Less than or equal to the MAXPAR[2] value on the SURFACE statement (1.0 by default).
270 Adams/Solver
User-Written Subroutines
Output Arguments
values
A double-precision array that contains the output data. The data are dependent on IORD and
IERR. This is elaborated below.
Note:
IORD=0,
IERR=0
x ( u, v )
y ( u, v )
z ( u, v )
3x1 array
IERR
IORD=0,
IERR=1
x ( u, v )
y ( u, v )
z ( u, v )
u*
v*
5x1 array
IORD=1,
IERR=0 or
IERR=1
x
u
x
v
y
u
y
v
z
u
z
v
3x2 array
IORD=2
IERR=0 or
IERR=1
2
x
u u
2
y
u u
2
z
u u
x
u v
2
y
u v
2
z
u v
x
v v
2
y
v v
2
z
v v
3x3 array
An integer variable that specifies whether or not the [u,v] provided as input is on the surface.
IERR=0 implies the point is on the SURFACE
IERR=1 implies the point is not on the SURFACE
IERR should be set only when IORD=0.
IF IERR=0, then SURSUB should just return the x ,y ,z coordinates of the point on the
SURFACE. The first three components of the output array VALUES should contain this data.
The last two components of VALUES can remain undefined.
IF IERR=1, then SURSUB is required to extrapolate the SURFACE definition and return the
x, y, z coordinates of the point on the extrapolated SURFACE. The first three components of
the output array VALUES should contain this data. In addition, SURSUB is also expected to
return the u,v values of the point on the surface closest to the x, y, z coordinates that were
calculated. These values, u* and v*, are returned in components 4,5 of the output array
VALUES.
Extended Definition
SURSUB is a user-written subroutine that allows you to define a SURFACE. The x, y, and z coordinates
of a point on a parametric surface are functions of independent parameters, (u,v). As (u,v) vary from their
minimum to maximum values, the functions x(u,v), y(u,v), and z(u,v) sweep out points on the surface.
SURSUB 271
User-Written Subroutines
A surface can be open or closed in both u and v. A surface closed in u (UCLOSED) meets along the edges
defined by the maximum and minimum values of u. A surface closed in v (VCLOSED) meets along the
edges defined by the maximum and minimum values of v.
Surfaces can be used in Adams constraints. A surface marker allowed to only move on the surface is
provided for this purpose. Any valid constraint (joint, jprim, and so on) can be constructed using the
surface marker.
A surface has parameterization limits as prescribed by MINPAR and MAXPAR. It is likely, however, that
there are regions within the parameter space where the surface is not defined. The finiteness of the surface
(including holes) are modeled using a penalty approach. The penalty approach applies a force to prevent
the surface marker from moving off the edge of an open surface, or from moving into a hole in the
surface. This approach necessarily requires that the surface marker move off the surface for a short
duration. In such a situation, the surface descriptor is provided with [u,v] values outside the domain of
the surface. The descriptor is expected to extrapolate the surface definition to provide an estimated
location of the surface marker at these [u,v] points. Linear extrapolation is adequate for most purposes.
Adams/Solver automatically extrapolates the surface as needed when the surface description is provided
as a Parasolid geometry file. You are required to perform such extrapolation when you provide the
surface definition through a SURSUB user-written subroutine.
If [u,v] are the parameters corresponding to the current point on the surface, and [u*, v*] are the
parameters for the closest material point on the surface to [u,v], the penalty force that is applied in the
[u,v] domain is:
F = -K * [(u-u*)2 + (v-v*)2]
K = 108
At this time, you have no control over the stiffness parameter, K.
Caution:
Define the SURFACE only as a function of u, v. Do not make calls to the SYSARY and
SYSFNC utility subroutines to access other system variables.
FORTRAN - Prototype
A sample structure for SURSUB is shown next. The comments explain how the subroutine works.
SUBROUTINE SURSUB ( ID, PAR, NPAR, U, V, IORD, IFLAG,
&
VALUES, IERR )
C
C Inputs:
C
INTEGER
ID
DOUBLE PRECISION
PAR( * )
INTEGER
NPAR
DOUBLE PRECISION
U,V
INTEGER
IORD
LOGICAL
IFLAG
C
272 Adams/Solver
User-Written Subroutines
C Outputs:
C
DOUBLE PRECISION
VALUES( * )
INTEGER
IERR
C
C+---------------------------------------------------------------*
C
C ID
Identifier of calling CURVE statement
C PAR
Array containing passed parameters
C NPAR
Number of passed parameters
C U,V
Curve parameter value
C IORD
Derivative order of value to be returned
C IFLAG
Initialization pass flag
C VALUES
Derivative values of CURVE returned to ADAMS
C IERR
Return flag; 0 =(U,V) on surface
1 =(U,V) outside surface
C
C+---------------------------------------------------------------*
C
C Local Variables:
C
...
C
C External Functions:(Note : This function must be written by you)
C
EXTERNAL UV_IS_OUTSIDE_SURFACE
LOGICAL UV_IS_OUTSIDE_SURFACE
C
C+---------------------------------------------------------------*
C
IF ( IFLAG ) THEN
C
C
Initialization call:
C
...
<perform initialization operations>
<opening files, calculating constants etc.>
...
RETURN
ENDIF
C
C
Computation call:
C
IERR = 0
IF ( IORD .EQ. 0 ) THEN
C
C
Check whether [u,v] lie on the surface:
C
IF ( UV_IS_OUTSIDE_SURFACE(...) ) THEN
...
SURSUB 273
User-Written Subroutines
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
C
<extrapolate surface>
<calculate x-y-z-coordinates corresponding to [u,v]
<calculate [u*,v*] on surface, closest to [u,v]>
...
Set IERR, and VALUES:
IERR = 1
VALUES(1) = x....
VALUES(2) = y....
VALUES(3) = z....
VALUES(4) = u*...
VALUES(5) = v*...
ELSE
...
<calculate x-y-z-coordinates corresponding to [u,v]
<calculate [u*,v*] on surface, closes to [u,v>]
...
Set IERR, and VALUES:
VALUES(1) = x...
VALUES(2) = y...
VALUES(3) = z...
ENDIF
ELSEIF ( IORD .EQ. 1 ) THEN
Need matrix of 1st partial derivatives wrt. Parameters u,v:
...
<calculate partials of x-y-z-coordinates wrt to [u,v]>
...
Return the 3x2 matrix of partials, sorted by column
VALUES(1) = dx_du...
VALUES(3) = dz_du...
VALUES(5) = dy_dv...
ELSEIF ( IORD .EQ. 2 ) THEN
VALUES(2) = dy_du...
VALUES(4) = dx_dv...
VALUES(6) = dz_dv...
274 Adams/Solver
User-Written Subroutines
C
C
VALUES(1) = d2x_dudu...
VALUES(2) = d2y_dudu...
VALUES(3) = d2z_dudu...
VALUES(4) = d2x_dudv...
VALUES(5) = d2y_dudv...
VALUES(6) = d2z_dudv...
VALUES(7) = d2x_dvdv...
VALUES(8) = d2y_dvdv...
VALUES(9) = d2z_dvdv...
ELSECC
Error - Should not be here:
CALL ERMESS (...)
ENDIF
RETURN
END
C Style Prototype
typedef void adams_c_SURSUB(const struct sAdamsSurface* srf, double
ALPHA, double BETA, int IORD, int IFLAG, double* VALUES, int* IERR );
/*
*
SURFACE
*/
struct sAdamsSurface
{
int ID;
int NPAR;
const double* PAR;
/* const char* FILENAME; */
int ORDER[2];
int CLOSED[2];
double MINPAR[2];
double MAXPAR[2];
};
Examples
The figure below illustrates a circular surface S with a hole H at its very center. The surface S belongs to
a body A. A point P, belonging to a different body B, is required to move on the surface S. The bounds
of the parameterization are the outer perimeter of the circular suface A circular surface with a hole in its
center.
SURSUB 275
User-Written Subroutines
276 Adams/Solver
User-Written Subroutines
UCOSUB
The UCOSUB evaluation subroutine computes a constraint value and its derivatives for a UCON
statement (f77). You must write a UCOSUB whenever one or more UCON statements are used in a
dataset.
Use
Corresponding Statement
UCON/id, FUNCTION=USER(r1[,...,r30])
[ ] Optionally select the item.
Calling Sequence
id
An integer variable that contains the ID of the UCON statement requesting information
from UCOSUB. From the identifier, Adams/Solver automatically knows other
information (such as the par argument) available in the corresponding statement.
time
A double-precision array (of as many as thirty elements) that contains the current values
of the part principal axes variables. These values are in the order specified by the call to
UCOVAR.
par
A double-precision array of constants taken in order from the USER parenthetical list of
the UCON statement; r1[,...,r30].
npar
An integer variable that indicates the number of constants specified in the USER
parenthetical list. The primary purpose of npar is to provide UCOSUB with the number
of values stored in the par array.
UCOSUB 277
User-Written Subroutines
idrsel
A three-element integer array containing control values for returning the proper
information through scalar, array, and xmatrx.
iflag
An integer variable that Adams/Solver sets to indicate why the routine is being called:
Value
Description
Mapping dependencies
Expression serialization
Expression un-serialization
When iflag is 0 Adams/Solver calling to compute the value of the user-written variable.
When iflag is set to 3 call UCOVAR for initial definition of the principal axes variables
and do any initializations that your subroutine requires.
When your user-defined subroutine has static data that needs to be saved and restored to
support the Adams/Solver commands Save and Reload, then call the serialization
functions for your data when iflag is set to 7, and the un-serialization functions when
iflag is set to 9.
Note:
In simple subroutines where serializing data is not needed, you can declare
iflag as a logical variable. In this case you can do any initializations when
Adams/Solver sets iflag to true, and compute the subroutine's value when
Adams/Solver sets iflag to false.
278 Adams/Solver
User-Written Subroutines
Output Arguments
array
qm
2
If idresel (2) is: 2 array is : array(m) = F ( q, t )
t q m
If any of the elements of array are symbolically zero, they don't need to be defined.
UCOSUB 279
User-Written Subroutines
scalar
A double-precision variable for returning the residue (the error relative to zero) of the
implicit constraint expression, the nonprincipal axes variable-dependent portion of the
constraint expression (the value of the constraint expression if all principal axes variables
are zero), or the various time derivatives of the constraint expression.
The value UCOSUB returns to Adams/Solver depends on the value of idrsel(1). In the
following table, q represents the variables, t stands for time, F refers to the constraint
equation, and f refers to the equation when all variables (q) are set equal to zero.
If idresel (1) is: (scalar is: )
0 (No evaluation )
1 (scalar = F(q,t))
2 (scalar = F ( q, t ) )
3 (scalar =
t
2
F ( q, t )
4 (scalar = f(t))
xmatrx
F9 ( q, t )
)
q n q m
The letter q represents the variables, t stands for time, and F refers to the constraint
equation. If any of the elements of xmatrx are symbolically zero, they need not be defined.
Extended Definition
The standard constraint statements are usually adequate for defining commonly occurring displacement
constraints between marker pairs. For displacement constraint combinations not available through these
statements or for constraints involving velocity variables, you should use the FUNCTION=USER()
argument in the UCON statement, and write a UCOSUB to define the constraint. The constraints defined
in the subroutine can incorporate velocity variables. You can select as many as thirty displacements
and/or velocities of part principal axes to be the variables in the constraint relationship for a UCON
statement. Each UCON statement removes one degree of freedom from the system.
At every evaluation step, Adams/Solver evaluates UCOSUB to determine the value of the constraints.
During the initialization of UCOSUB, the utility subroutine UCOVAR should be called to declare the
variables used in the relationship. PART statement identifiers and type codes identify the variables. To
280 Adams/Solver
User-Written Subroutines
preserve the generality of UCOSUB, the identifiers and the type codes can be passed through the
parameter list of the UCON statement.
For the formulation of constraints, you cannot access information with SYSARY or SYSFNC. You can,
however, access information with AKISPL or CUBSPL (see AKISPL, CUBSPL, and UCOVAR). You
must set up UCOSUB system dependencies using UCOVAR, and use system information from the q
parameter only.
For each system constraint, Adams/Solver formulates a governing constraint equation. For standard
Adams/Solver constraint statements, symbolic partial derivatives of the constraint equation with respect
to the system variables have been pre-computed and stored in the program for use in the system Jacobian
when the particular constraint is involved.
When you write a UCOSUB, equations of motion are added to the set of equations Adams/Solver
generates for the standard constraint statements. You must provide the first and second derivatives of the
constraint relationship with respect to the set of variables. You must code the constraint relationship in
the implicit form. For information on implicit forms, see DIFF statement (C++ or FORTRAN).
Caution:
When selecting the displacements or the velocities of the part principal axes for the
constraint, remember that the part principal axes are not always identical to those
of the part center-of-mass marker (CM). The following list summarizes the
circumstances in which the part principal axes may differ from those of the part
center-of-mass marker.
When the PART statement does not include the CM argument, the principal
A sample structure for UCOSUB is shown next. The comments explain how the subroutine works.
&
UCOSUB 281
User-Written Subroutines
&
XMATRX)
C
C === Type and dimension statements ===================
C
C - External variable definitions --------C
INTEGER
ID
DOUBLE PRECISION
TIME
DOUBLE PRECISION
Q( 30 )
DOUBLE PRECISION
PAR( * )
INTEGER
NPAR
INTEGER
IDRSEL( 3 )
LOGICAL
IFLAG
DOUBLE PRECISION
SCALAR
DOUBLE PRECISION
ARRAY( 30 )
DOUBLE PRECISION
XMATRX( 30, 30 )
C
C ID
Identifier of calling UCON statement
C TIME
Current time
C Q
Array of part state variables
C PAR
Array of passed statement parameters
C NPAR
Number of passed parameters
C IDRSEL
UCON values selection control flag
C IFLAG
Initialization pass flag
C SCALAR
Scalar value returned to ADAMS
C ARRAY
Partial derivatives
C XMATRX
Second partial derivatives
C
C - Local variable definitions ----------C
...
C
C === Executable code =================================
C
C - Assign parameters to readable variable names -C
...
C
C - Subroutine initialization ----------C
IF( IFLAG ) THEN
C
C Declare principal axis variables
C
CALL UCOVAR ( ... )
C
ENDIF
C
C - Find implicit constraint relation ------C
IF ( IDRSEL(1) .EQ. 1 ) THEN
C
C Your algorithm
C
282 Adams/Solver
User-Written Subroutines
...
C
C Assign scalar
C
SCALAR = ...
C
C - First time derivative of constraint relation -C
ELSE IF ( IDRSEL(1) .EQ. 2 ) THEN
C
C Your algorithm
C
...
C
C Assign first time derivative to scalar
C
SCALAR = ...
C
C - Second time derivative of constraint -----C
relation
C
ELSE IF ( IDRSEL(1) .EQ. 3 ) THEN
C
C Your algorithm
C
...
C
C Assign second time derivative to scalar
C
SCALAR = ...
C
C - Nonprincipal-axes-dependent portion of ---C
constraint relation
C
ELSE IF ( IDRSEL(1) .EQ. 4 ) THEN
C
C Your algorithm
C
...
C
C Assign nonprincipal-axes-dependent portion to scalar
C
SCALAR = ...
C
ENDIF
C
C - Evaluate array ----------------C
C - First derivative of constraint relationship with
C
respect to the variables
C
IF ( IDRSEL(2) .EQ. 1 ) THEN
UCOSUB 283
User-Written Subroutines
C
C Your algorithm
C
...
C
C Assign array values
C
ARRAY(1) = ...
...
ARRAY(30) = ...
C
C - Derivatives of prior first
C
respect to time
C
ELSE IF ( IDRSEL(2) .EQ.
C
C Your algorithm
C
...
C
C Assign array values
C
ARRAY(1) = ...
...
ARRAY(30) = ...
C
ENDIF
C
C - Derivatives of prior first
C
respect to the variables
C
IF ( IDRSEL(3) .EQ. 1 )
C
C Your algorithm
C
...
C
C Assign matrix values
C
XMATRX(1, 1)
= ...
...
XMATRX(30, 30) = ...
C
ENDIF
C
RETURN
END
Examples
284 Adams/Solver
User-Written Subroutines
VARSUB
The VARSUB evaluation subroutine computes an algebraic value for a VARIABLE statement (C++ or
FORTRAN). VARSUB is optional. You only need it if you don't want to use a function expression in the
VARIABLE statement.
Use
Corresponding Statement
Calling Sequence
VARSUB 285
User-Written Subroutines
Input Arguments
id
time
par
A double-precision array of constants taken in order from the USER parenthetical list of
the VARIABLE statement.
npar
An integer variable that indicates the number of constants you specify in the USER
parenthetical list. The primary purpose of the npar argument is to provide VARSUB with
the number of values stored in the par array.
dflag
A logical variable that Adams/Solver sets to true when it calls VARSUB to evaluate the
partial derivatives of the specified functions. Otherwise, Adams/Solver sets the dflag
argument to false.
iflag
An integer variable that Adams/Solver sets to indicate why the routine is being called:
Value
Description
Mapping dependencies
Expression serialization
Expression un-serialization
Adams/Solver sets iflag to 3 when it needs the functional dependency of the user-defined
variable. The functional dependencies are set with the same calls to the SYSARY and
SYSFNC utility subroutines that are made to compute the value of the user-defined
variable. If iflag is 0, Adams/Solver computes the value of the user-written variable.
When your user-defined subroutine has static data that needs to be saved and restored to
support the Adams/Solver commands Save and Reload, then call the serialization
functions for your data when iflag is set to 7, and the un-serialization functions when iflag
is set to 9.
Note:
Output Arguments
In simple subroutines where serializing data is not needed, you can declare iflag
as a logical variable. In this case you declare your dependencies when
Adams/Solver sets iflag to true, and compute the subroutine's value when
Adams/Solver sets iflag to false.
286 Adams/Solver
User-Written Subroutines
value
Extended Definition
You can use the VARIABLE statement with the function expression to define most user-defined
VARIABLE statements. However, if the expression becomes lengthy and awkward, you should use the
FUNCTION=USER() argument in the VARIABLE statement, and write a VARSUB to define the
VARIABLE statement.
You can call utility subroutines, such as AKISPL, CUBSPL, SYSARY, and SYSFNC, from VARSUB,
to obtain information about system variables, user-defined variables, and splines (see AKISPL,
CUBSPL, SYSARY, and SYSFNC).
The SYSARY and SYSFNC utility subroutines automatically set functional dependencies when the
VARSUB argument iflag is true. To compute solutions efficiently, Adams/Solver must know the other
variables on which each user-defined variable depends. Adams/Solver determines these functional
dependencies at the beginning of the simulation by calling VARSUB with the argument iflag set to true.
Adams/Solver does this once for each VARIABLE statement with a FUNCTION=USER() argument.
During each call to VARSUB, Adams/Solver records which calls you make to SYSARY and SYSFNC.
Adams/Solver assumes the user-defined variable depends on those system and user-defined variables,
and no others.
Tip:
If the SYSARY or SYSFNC utility subroutines are called to access angular displacements,
the values returned by them may contain discontinuities. To avoid the discontinuities, use
the RCNVRT utility subroutine to convert the rotational angles from Euler angles to some
other rotational representation that does not encounter a singularity.
VARSUB 287
User-Written Subroutines
Caution:
When the iflag argument is true, you should make the same calls to SYSARY and
system and user-defined variables. Computations that divide these values result in
system errors when you execute Adams/Solver. You should check for nonzero
values or ensure that the iflag argument is set to false before dividing by these
values.
You must be careful when defining a VARIABLE statement dependent on another
A sample structure for VARSUB is shown next. The comments explain how the subroutine works.
&
C
C === Type and dimension statements ===================
C
C
C - External variable definitions --------C
INTEGER
ID
DOUBLE PRECISION
TIME
DOUBLE PRECISION
PAR( * )
INTEGER
NPAR
LOGICAL
DFLAG
LOGICAL
IFLAG
DOUBLE PRECISION
VALUE
C
288 Adams/Solver
User-Written Subroutines
C
C
C
C
C
C
C
C
C
C
ID
TIME
PAR
NPAR
DFLAG
IFLAG
VALUE
...
C
C === Executable code =================================
C
C Assign parameters to readable variable names
C
...
C
C Call SYSFNC and/or SYSARY to collect information for
C calculations below. Note: if IFLAG is true, these
C calls are actually setting functional dependencies.
C
CALL SYSFNC ( ... )
C
CALL ERRMES ( ... )
C
C Repeat for all required SYSFN
C or SYSARY calls
C
...
C
IF( IFLAG ) THEN
C
C - Subroutine initialization ----------C
...
C
ENDIF
C
C - Evaluate variable---------------C
C Your algorithm
C
...
C
C Assign the returned value
C
VALUE = ...
C
RETURN
END
VARSUB 289
User-Written Subroutines
C Style - Prototype
typedef void adams_c_VARSUB(const struct sAdamsVariable* variable,
double TIME, int DFLAG, int IFLAG, double* RESULT);
/*
*
VARIABLE
*/
struct sAdamsVariable
{
int ID;
int NPAR;
const double* PAR;
double IC;
};
Examples
290 Adams/Solver
User-Written Subroutines
VFOSUB
The VFOSUB evaluation subroutine computes force components for a VFORCE (C++ or FORTRAN).
VFOSUB is optional. You only need it if you don't want to use function expressions in the VFORCE
statement.
Use
Corresponding Statement
Calling Sequence
id
time
par
A double-precision array of constants taken in order from the USER parenthetical list
of the VFORCE statement.
npar
An integer variable that indicates the number of constants you specify in the USER
parenthetical list. The primary purpose of the npar argument is to provide to VFOSUB
the number of values stored in the par array.
VFOSUB 291
User-Written Subroutines
dflag
A logical variable that Adams/Solver sets to true when it calls VFOSUB to evaluate the
partial derivatives of the specified functions. Otherwise, Adams/Solver sets the dflag
argument to false. See Using the DFLAG Variable.
iflag
An integer variable that Adams/Solver sets to indicate why the routine is being called:
Value
Description
Mapping dependencies
Expression serialization
Expression un-serialization
Adams/Solver sets iflag to 3 when it needs the functional dependency of the userdefined variable. The functional dependencies are set with the same calls to the
SYSARY and SYSFNC utility subroutines that are made to compute the value of the
user-defined variable. If iflag is 0, Adams/Solver computes the value of the user-written
variable.
When your user-defined subroutine has static data that needs to be saved and restored
to support the Adams/Solver commands Save and Reload, then call the serialization
functions for your data when iflag is set to 7, and the un-serialization functions when
iflag is set to 9.
Note:
In simple subroutines where serializing data is not needed, you can declare
iflag as a logical variable. In this case you declare your dependencies when
Adams/Solver sets iflag to true, and compute the subroutine's value when
Adams/Solver sets iflag to false.
Output Arguments
result
A double-precision array that returns the three values of the VFORCE components, in xy-z order.
Extended Definition
You can usually use the VFORCE statement with function expressions to define the three components of
a translational vector force at a point. However, if the force expressions become lengthy and awkward or
require external computations, it may be necessary to use a VFOSUB. If the algorithms use or consist of
already-existing FORTRAN-77 subroutines, VFOSUB can be made to call them.
292 Adams/Solver
User-Written Subroutines
You can call utility subroutines, such as AKISPL, CUBSPL, SYSARY, and SYSFNC, from VFOSUB to
obtain information about system variables, user-defined variables, and splines. (See AKISPL, CUBSPL,
SYSARY, and SYSFNC).
The SYSARY and SYSFNC utility subroutines automatically set functional dependencies when the
VFOSUB argument iflag is true. For Adams/Solver to compute solutions efficiently, it must know
on which other variables each user-defined variable depends directly. Adams/Solver determines these
functional dependencies at the beginning of the simulation by calling VFOSUB with the argument iflag
set to true. During each call to VFOSUB, Adams/Solver records which calls you make to SYSARY and
SYSFNC and assumes that the resulting values are dependent only on those Adams/Solver variables
accessed through the SYSARY and SYSFNC calls.
Tip:
If the SYSARY or SYSFNC utility subroutines are called to access angular displacements,
the values returned by them may contain discontinuities. To avoid the discontinuities, use
the RCNVRT utility subroutine to convert the rotational angles from Euler angles to some
other rotational representation that does not encounter a singularity.
Caution:
When the iflag argument is true, you must make all the calls to SYSARY and
SYSFNC as are made to compute the component values of the VFORCE. This
ensures that Adams/Solver has the proper functional dependencies. In general,
failure to account for dependencies in the VFORCE components can make it
difficult for Adams/Solver to converge to a solution and/or can force
Adams/Solver to take small integration steps. Both of these effects usually cause
large increases in execution time.
When the iflag argument is true, SYSARY and SYSFNC return zero values.
Computations that divide by these values result in fatal errors when you execute
Adams/Solver. You should check for nonzero values or ensure that the iflag
argument is set to false before dividing by these values.
FORTRAN - Prototype
A sample structure for VFOSUB is shown next. The comments explain how the subroutine works.
&
C
C === Type and dimension statements ===================
C
C - External variable definitions ----------C
INTEGER
ID
DOUBLE PRECISION
TIME
DOUBLE PRECISION
PAR(*)
INTEGER
NPAR
LOGICAL
DFLAG
VFOSUB 293
User-Written Subroutines
LOGICAL
DOUBLE PRECISION
IFLAG
RESULT(3)
C
C ID
Identifier of calling VFORCE statement
C TIME
Current time
C PAR
Array containing passed parameters
C NPAR
Number of passed parameters
C DFLAG
Differencing flag
C IFLAG
Initial pass flag
C RESULT
Array (dimension 3) of computed VFORCE
C
components returned to ADAMS
C
C - Local variable and parameter definitions -----C
...
C
C === Executable code =================================
C
C Assign readable variable names to passed parameters
C
...
C
C Call SYSFNC and/or SYSARY to collect information for
C the calculations below. Note: if IFLAG is true, these
C calls are actually setting functional dependencies.
C
CALL SYSFNC (...)
C
C Check SYSFNC call through ERRMES utility routine
C
CALL ERRMES (...)
C
C Repeat for all required SYSFNC or SYSARY calls
C
...
C
IF (IFLAG) THEN
C
C - Subroutine initialization ------------C
...
C
ENDIF
C
C - Evaluate VFORCE components -----------C
C Your algorithms
C
...
C
C Assign values to the RESULT array
C
RESULT(1) = ...
RESULT(2) = ...
RESULT(3) = ...
294 Adams/Solver
User-Written Subroutines
RETURN
END
C Style - Prototype
typedef void adams_c_VFOSUB(const struct sAdamsVforce* vfo, double
TIME, int DFLAG, int IFLAG, double* RESULT);
/*
*
VFORCE
---------------------------------------------------------------*/
struct sAdamsVforce
{
int ID;
int NPAR;
const double* PAR;
int I;
int JFLOAT;
int RM;
};
Examples
VTOSUB 295
User-Written Subroutines
VTOSUB
The VTOSUB evaluation subroutine computes torque components for a VTORQUE statement (C++ or
FORTRAN). VTOSUB is optional. You only need it if you don't want to use function expressions in the
VTORQUE statement.
Use
Corresponding Statement
Calling Sequence
id
time
par
A double-precision array of constants taken in order from the USER parenthetical list of
the VTORQUE statement.
npar
An integer variable that indicates the number of constants you specify in the USER
parenthetical list. The primary purpose of the npar argument is to provide VTOSUB with
the number of values stored in the par array.
296 Adams/Solver
User-Written Subroutines
dflag
A logical variable that Adams/Solver sets to true when it calls VTOSUB to evaluate the
partial derivatives of the specified functions. Otherwise, Adams/Solver sets the dflag
argument to false.
iflag
An integer variable that Adams/Solver sets to indicate why the routine is being called:
Value
Description
Mapping dependencies
Expression serialization
Expression un-serialization
Adams/Solver sets iflag to 3 when it needs the functional dependency of the user-defined
variable. The functional dependencies are set with the same calls to the SYSARY and
SYSFNC utility subroutines that are made to compute the value of the user-defined
variable. If iflag is 0, Adams/Solver computes the value of the user-written variable.
When your user-defined subroutine has static data that needs to be saved and restored to
support the Adams/Solver commands Save and Reload, then call the serialization
functions for your data when iflag is set to 7, and the un-serialization functions when iflag
is set to 9.
Note:
In simple subroutines where serializing data is not needed, you can declare iflag
as a logical variable. In this case you declare your dependencies when
Adams/Solver sets iflag to true, and compute the subroutine's value when
Adams/Solver sets iflag to false.
Output Arguments
result
A double-precision array of length 3 that returns the x-, y-, and z-components of the
VTORQUE.
Extended Definition
You can often use the VTORQUE statement with function expressions sufficient to define the three
rotational vector components of a torque at a point. However, if the torque expressions become lengthy
and awkward, you can use a VTOSUB evaluation subroutine. If the algorithms use or consist of already
existing FORTRAN-77 subroutines, VTOSUB can be made to call them.
You can call utility subroutines, such as AKISPL, CUBSPL, SYSARY and SYSFNC, from VTOSUB to
obtain information about system variables, user-defined variables, and splines. See AKISPL, CUBSPL,
SYSARY, and SYSFNC.
VTOSUB 297
User-Written Subroutines
The SYSARY and SYSFNC utility subroutines automatically set functional dependencies when the
VTOSUB argument iflag is true. In order for Adams/Solver to compute solutions efficiently, it must
know on which other variables each user-defined variable depends directly. Adams/Solver determines
these functional dependencies at the beginning of the simulation by calling VTOSUB with the argument
iflag set to true. Adams/Solver does this once for each VTORQUE statement with a
FUNCTION=USER() argument.
During each call to the VTOSUB evaluation subroutine, Adams/Solver records which calls you make to
SYSARY and SYSFNC and assumes that the resulting values are dependent on only those Adams/Solver
variables accessed through the SYSARY and SYSFNC calls.
Tip:
If the SYSARY or SYSFNC utility subroutines are called to access angular displacements,
the values returned by these may contain discontinuities. To avoid the discontinuities, use
the RCNVRT utility subroutine to convert the rotational angles from Euler angles to some
other coordinate system that does not encounter a singularity.
Caution:
When the iflag argument is true, you must make all the same calls to SYSARY and
A sample structure for VTOSUB is shown next. The comments explain how the subroutine works.
&
C
C === Type and dimension statements ===================
C
C - External variable definitions ----------C
INTEGER
ID
DOUBLE PRECISION
TIME
DOUBLE PRECISION
PAR(*)
INTEGER
NPAR
LOGICAL
DFLAG
298 Adams/Solver
User-Written Subroutines
LOGICAL
DOUBLE PRECISION
IFLAG
RESULT(3)
C
C ID
Identifier of calling VTORQUE statement
C TIME
Current time
C PAR
Array containing passed parameters
C NPAR
Number of passed parameters
C DFLAG
Differencing flag
C IFLAG
Initial pass flag
C RESULT
Array (dimension 3) of computed VTORQUE
C
components returned to ADAMS
C
C - Local variable and parameter definitions -----C
...
C
C === Executable code =================================
C
C Assign readable variable names to passed parameters
C
...
C
C Call SYSFNC and/or SYSARY to collect information for
C the following calculations. Note: if IFLAG is true, these
C calls are actually setting functional dependencies.
C
CALL SYSFNC (...)
C
C Check SYSFNC call through ERRMES utility routine
C
CALL ERRMES (...)
C
C Repeat for all required SYSFNC or SYSARY calls
C
...
C
IF (IFLAG) THEN
C
C - Subroutine initialization ------------C
...
C
ENDIF
C
C - Evaluate VTORQUE components -----------C
C Your algorithms
C
...
C
C Assign values to the RESULT array
C
RESULT(1) = ...
RESULT(2) = ...
VTOSUB 299
User-Written Subroutines
RESULT(3) = ...
RETURN
END
C Style - Prototype
typedef void adams_c_VTOSUB(const struct sAdamsVtorque* vto, double
TIME, int DFLAG, int IFLAG, double* RESULT);
/*
*
VTORQUE
---------------------------------------------------------------*/
struct sAdamsVtorque
{
int ID;
int NPAR;
const double* PAR;
int I;
int JFLOAT;
int RM;
};
Examples
300 Adams/Solver
User-Written Subroutines
Adams/Solver Examples 1
Adams/Solver Examples
The following examples are available:
For examples of Adams/Solver features, see Knowledge Base Article 10544.
To see the Adams Verification Guide, refer to Knowledge Base Article 9587.
2 Adams/Solver
A
ABS 3
ACCGRAV
command 3
statement 8, 4
ACCM 4
ACCX 5
ACCY 9, 7
ACCZ 11, 9
ACENTER 4
ACOS 13, 11
ACTIVATE 4, 5
Adams/Solver
datasets 22
modeling
simulating 16
understanding modeling concepts 37
using statements
define your model 28
AINIT 8
AINT 12
AKISPL 13
ANINT 15
ARRAY
command 7, 9
statement 9, 5
ARYVAL 20, 16
ASIN 21, 17
ATAN 22, 18
ATAN2 23, 19
AUTOSCALE 10
AX 24, 20
AY 26, 22
AZ 28, 24
B
BACKUP 11
BEAM
command 8, 14
2 Adams/Solver
function 30, 26
statement 12, 8
BISTOP 31, 27
BUSH 34, 30
BUSHING
command 10, 16
statement 20, 17
C
CENTER 17
CHEBY 35, 31
CLEAR 19
CONTACT
function 36, 32
statement 24, 21
Contacts, working with 44
CONTROL 11, 20
COS 37, 33
COSH 38, 34
COUPLER 49, 46
CUBSPL 40, 35
CURVE
function 42, 37
statement 53, 41
CVCV
function 44, 39
statement 58, 50
D
DEACTIVATE 12, 21
DEBUG
command 15, 24
statement 65, 57
DIF 49, 40
DIF1 50, 41
DIFF 69, 61
DIM 51, 42
DISPLAY 45
DM 52, 43
DRAW 46
DT 49
DTOR 53, 44
DX 54, 45
DXYZ 55
DY 57, 46
DZ 58, 47
E
END 74, 65
EQUILIBRIUM
command 36, 50
statement 75, 66
ERASE/RESTORE 54
EXECUTION 55
EXP 59, 48
F
FEMDATA 78, 72
FIELD
command 38, 56
function 60, 49
statement 88, 82
FILE 41, 59
FLEX_BODY
command 43, 62
statement 95, 90
FM 61, 50
FORCE 152
FORCOS 62, 51
FORSIN 64, 53
FRICTION
command 44
function 66, 55
statement 106
FX 68, 57
FXFREQ 69, 58
FXMODE 70, 59
FY 72, 60
FZ 73, 61
G
GCON
4 Adams/Solver
command 48
statement 114
GEAR 119, 108
GFORCE
command 49, 68
function 74, 62
statement 123, 111
GRAPHICS
Graphics for Contact 128
Graphics for Graphic Display of Objects 135, 123
GSE 141, 129
H
HAVSIN 75, 63
HELP 72
HSIZE 77
I
IC
command 52, 73
statement 158, 148
IF 78, 65
IMPACT 80, 67
INCANG 84, 71
INFO 55, 76
INTEGRATOR
command 78
statement 162, 152
INTEGRATORP
command 57
INTERP 85, 72
INVPSD 87, 74
J
JOINT
command 64, 86
function 89, 76
statement 191, 179
JPRIM
function 77
statement 193
K
KINEMATICS
command 65, 87
statement 215, 199
L
LINEAR 90
LIST/NOLIST 202
LOG 91, 78
LOG10 92
LSE 218, 203
LSOLVER 116
M
MARKER
command 140, 117
statement 223, 207
MATRIX 234, 212
MAX 94, 79
MENU 145, 120
MFORCE 242, 220
MIN 95, 80
MOD 96, 81
MODE 97, 82
MOTION 225
command 146, 121
function 98, 83
statement 247
MREQUEST 232
N
NFORCE
function 84
statement 239
NJAC 99
NRHS 100
O
ORDER 101
OUTPUT
command 149, 125
statement 261, 246
6 Adams/Solver
P
PART
command 150, 131
statement 267, 257
PHI 102, 85
phics 116
PI 104, 88
PINPUT 263
PINVAL 89
PITCH 90
PLOT 132
POINT_MASS 265
POLY 91
POUTPUT 269
POUVAL 93
PREFERENCES
command 153, 135
statement 283, 272
PSI 110, 94
PTCV
function 111, 95
statement 292, 274
Q
Q 112
QDDOT 113
QDOT 114
R
RELOAD 138
REQUEST
command 161, 142
statement 299, 281
RESULTS 309, 292
RETURN 144
ROLL 115, 96
ROUTINE argument 56
RTOD 116, 97
S
SAVE 145
SENSOR 314
command 148
statement 297
SENVAL 117, 98
SET 149
SFORCE
command 167, 152
function 99
statement 320, 303
SHF 119, 100
SHOW 170
command 155
SIGN 120, 101
SIMULATE 171, 156
SIN 121, 102
SINH 122, 103
SPDP 123, 104
SPLINE
command 175, 160
statement 324, 307
SPRINGDAMPER
command 177, 162
statement 330, 313
SQRT 124, 105
STEP 125, 106
STEP5 128, 109
STOP 179, 164
STRING
command 180, 165
statement 333, 316
SURFACE 334
SWEEP 130, 111
T
TAN 133, 114
TANH 134, 115
TFSISO 338, 317
THETA 135, 116
TIME
command 181, 166
8 Adams/Solver
WY 173, 144
WZ 174, 145
Y
YAW 175, 146