85 views

Original Title: Solver c Plus Statements

Uploaded by Namelezz Shadoww

- R Programming Course Notes
- Backtest Your Trading Strategies White Paper
- REXX
- TSMP4002 - SmartPlant 3D Programming II Labs v7 SP4
- PLAXIS Tutorial Manual
- Shimpo Able VRS Brochure
- Ferris Wheel Report
- DIN ISO Programming USer Manual 2010
- harvard how to use scratch
- eTrust SeOS
- C++ Lab Manual
- Qbasic
- Short Manual Turbo-prog v1.02_en
- EnterpriseTrack_V8.0_Integration_API_Reference_Guide.pdf
- Delta Dynamic Object-Oriented Programming Language
- Fm Read_text
- C++
- Share Parameter
- Clone Rman COA v1.0 (2)
- Ch7 Printer File Functions

You are on page 1of 383

Adams/Solver

The C++ version of Adams/Solver, part of the Adams suite of software, is the next generation of Solver

technology. It is available as an alternative to the commercially available FORTRAN 77 Solver. You can

use Adams/Solver (C++) to test your models for compatibility and to take advantage of the new features.

The online help provides detailed information on the individual statements, function expressions, and

commands you use when working with Adams/Solver (C++).

To Switch to the Adams/Solver (FORTRAN) click Welcome to the FORTRAN Version of Adams/Solver.

2 Adams/Solver

Adams/Solver (C++) FAQs

Below is a list of the most common Adams/Solver (C++) questions. For updated information or to ask

another Adams/Solver (C++) question, use the Adams Knowledge Base.

Q: Why are the Adams/Solver built-in graphics capabilities not available in Adams/Solver (C++)?

A: The graphics capability in Adams/Solver (FORTRAN) is surpassed by the graphical user interface,

Adams/View. Since this capability has a limited user base, the following commands are not implemented

in Adams/Solver (C++):

ACENTER

CLEAR

EXECUTION

AINIT

DISPLAY

PLOT

AUTOSCALE

DRAW

RETURN

BACKUP

DT

SET

CENTER

ERASE

Q: Why is the UCON user-defined constraint element not supported in Adams/Solver (C++)?

A: The UCON element was always an extremely difficult element for users to use and only expert users

derived a benefit from this element. The C++ version of Solver, with its analytical derivative capability,

has replaced UCON with an extremely user-friendly user-defined constraint element (see the GCON

statement and command), which does not require the user to write user subroutines containing the partial

derivatives of the constraint equations. Instead, the user provides a function expression which is to

constrained to the value zero.

Adams/Solver (C++) computes all the required derivatives.

As a result, the UCON command and the UCON statement are not supported in Adams/Solver (C++).

Q: Why are the LIST/NOLIST statements not supported in C++?

A: These statements are not supported because Adams/Solver (C++) does not generate a tabular output

file.

Q: Why is the tabular output file (.out) not supported in C++?

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

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

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

GSE

LSE

TFSISO

VARIABLE

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

MREQUEST(Not yet supported)

OUTPUT

REQUEST

RESULTS

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

subroutines. You can use IC to designate an initial conditions array for an LSE or GSE.

In that case, you should ensure that t he SIZE is the same as the X (state variable) array

of the associated LSE or GSE.

NUMBERS= Allows you to enter a one-dimensional array of real numbers when using the IC array.

r1[,r2,...,]

SIZE=i

Allows you to define the size of the array. In cases where Adams/Solver (C++)

calculates the SIZE differently from the SIZE that you supply, Adams/Solver (C++)

returns an error or warning message.

=id1[,id2,...] VARIABLES argument is used with only an input array (U).

Range: Any valid VARIABLE id

X

Designates an ARRAY statement to be the state variable array for a systems modeling

element, LSE, GSE, or TFSISO. To use these arrays, you must reference the ARRAY

statement as the state variable array in a system element statement. You can use a single

X array with only a single systems element. When you choose X, the only other

argument available is SIZE. When you 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.

The U array defines an array of inputs for a systems element. Adams/Solver (C++) computes

The IC array defines an array of constants used as initial conditions.

For the X and Y arrays, the corresponding systems modeling element automatically determines the size

of the array and checks it against the ARRAY 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 linear Timoshenko beam theory is used. To use the geometrically non-linear model EulerBernoulli, set the environment variable MSC_ADAMS_SOLVER_BEAM_MODEL to NONLINEAR. A

third beam model can be used by setting the said environment variable to STRING. In that case, a

simplified geometrically non-linear model is used which can speed up the simulation time (see the string

model in reference [2]).

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

where Qy is the first moment of cross-sectional area to be sheared by a force in the z

direction, and Iz is the cross section dimension in the z direction.

If you want to neglect the deflection due to y-direction shear, ASY does not need to be

included in a BEAM statement.

Defaults: 0

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

where Qz is the first moment of cross-sectional area to be sheared by a force in the y

direction, and Iy is the cross section dimension in the y direction.

If you want to neglect the deflection due to z-direction shear, ASZ does not need to be

included in a BEAM statement.

Defaults: 0

Commonly encountered values for the shear area ratio are:

Cross-section:

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

Tx

Ty

0 K 53 0 K 55 0

Tz

0 K 62 0

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 translational displacements of the I marker with respect to the J marker

BEAM 15

C++ Statements

Tx, Ty, and Tz are the rotational force components in the coordinate system of the J marker.

a, b, and c are the relative rotational displacements of the I marker with respect to the J marker as

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

Note that both matrices, Cij and Kij, are symmetric, that is, Cij=Cji and Kij=Kji. You define the twentyone unique damping coefficients when the BEAM statement is written. Adams/Solver (C++) defines

each Kij as follows:

Adams/Solver (C++) applies an equilibrating force and torque at the J marker, as defined by the following

equations:

Fj = - Fi

Tj = - Ti - L x Fi

L is the instantaneous vector from the J marker to the I marker. While the force at the J marker is equal

and opposite to the force at the I marker, the torque is usually not equal and opposite, because of vector L.

The BEAM statement implements a force in the same way the FIELD statement does, but the BEAM

statement requires you to input only the values of the 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 linear Euler-Bernoulli formulation is the default model for the BEAM statement. The nonlinear

formulation can be used when one or more BEAM elements in the model are subject to axial forces. This

can be done by setting the environment variable MSC_ADAMS_SOLVER_BEAM_MODEL to

NONLINEAR, which will use the nonlinear formulation for all BEAM elements in the model.

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-

Generally, it is desirable to define the x-axis of the Adams/Solver (C++) beam on

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

nonzero. To minimize the effect of such misalignments, perform a static

equilibrium at the start of the simulation.

By definition, the beam lies along the positive x-axis of the J marker. (This is

unlike most other Adams/Solver force statements, for which the z-axis is the

significant axis.) Therefore, the I marker must have a positive x displacement with

respect to the J marker when viewed from the J marker. In its undeformed

configuration, the orientation of the I and the J markers must be the same.

The damping matrix that CMATRIX specifies should be positive semidefinite.

This ensures that damping does not feed energy into the system. Adams/Solver

(C++) does not warn you if CMATRIX is not positive semidefinite.

When the beam element angular deflections are small, the stiffness matrix

deflections are large, they are not commutative; so the stiffness matrix that

produces the translational and rotational force components may not correctly

describe the beam behavior. If BEAM translational displacements exceed ten

percent of the undeformed LENGTH, then Adams/Solver issues a warning

message.

By its definition a BEAM is asymmetric. Holding the J marker fixed and

deflecting the I marker produces different results than holding the I marker fixed

and deflecting the J marker by the same amount. This asymmetry occurs because

the coordinate system frame that the deflection of the BEAM is measured in

moves with the J marker.

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

Tx

0 K 44 0

Ty

0 K 55 0

Tz

Fy

Fz

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.

CLEARANCE 23

C++ Statements

CLEARANCE

The CLEARANCE statement defines a measure of the distance between two or more geometries or

FLEX_BODIES.

Format

CLEARANCE/id, IGEOM=id1[,...,idn]

JGEOM=id2[,...,idn]

IFLEX=id1[,....,idn] [,IREGION=id1[,...,idn],[IEXCLUDE=c1[:...:cn]]

JFLEX=id2[...,idn] [,JREGION=id2[,...,idn],[JEXCLUDE=c2[:...:cn]]

[]Select one item

[[]] Optionally select the item

Arguments

IGEOM = id

JGEOM = id

IFLEX = id

JFLEX = id

IREGION/JREGION = id

List matrix id's, the matrix is the list of node id's to include or exclude.

Note: Not specifying the IREGION or JREGION will automatically

include all nodes by default.

IEXCLUDE/JEXCLUDE = id List of booleans to indicate if the nodes indicated by the matrix are to

be included or excluded. The default is false so the nodes are included

be default.

THRESHOLD = distance

than the given THRESHOLD then the clearance between the

bounding boxes is given. The default value is zero which will always

calculate the clearance between the geometries.

Extended Definition

The clearance statement defines a measure of the distance between two or more geometries or

FLEX_BODIES.

The results are written to the XRF results file as XYZ location on the I geometry, XYZ location on the J

geometry, the scalar distance between the two points, the id of the I geometry, and the id of J geometry.

For FLEX_BODIES it is possible to include or exclude a subset of nodes using the REGION and

EXCLUDE lists.

24 Adams/Solver

C++ Statements

The clearance or one of its components may be referenced in an expression using the following 1D and

3D functions.

DCLEAR

IVCLEARZ

JACCCLEARX

VCLEAR

IACCCLEARX

JACCCLEARY

ACCCLEAR

IACCCLEARY

JACCCLEARZ

ICLEAR

IACCCLEARZ

IDCLEAR

JCLEAR

JDCLEARX

IVCLEAR

IDCLEARX

JDCLEARY

IACCCLEAR

IDCLEARY

JDCLEARZ

JDCLEAR

IDCLEARZ

JVCLEARX

JVCLEAR

IVCLEARX

JVCLEARY

JACCCLEAR

IVCLEARY

JVCLEARZ

ACCCLEAR(cid [,l])

DCLEAR(cid)

Clearance distance

ICLEAR(cid)

IDCLEAR(cid [,l])

IDCLEARX(cid [,l] )

IDCLEARY(cid [,l])

IDCLEARZ(cid [,l])

CLEARANCE 25

C++ Statements

JCLEAR(cid)

JDCLEAR(cid [,l])

JDCLEARX(cid [,l] )

JDCLEARY(cid [,l])

JDCLEARZ(cid [,l])

VCLEAR(cid [,l])

Where:

cid

The marker in whose coordinate is being calculated. Set k=0 if you the

results to be calculated in the global coordinate system.

The reference frame in which the derivative of the vector is taken. Set

l=0 if you want the time derivative to be taken in the ground reference

frame.

Examples

CLEARANCE/7, IFLEX=3,9, JGEOM=4

, IREGION=0,2, IEXCLUDE=F:T

26 Adams/Solver

C++ Statements

CONTACT

The CONTACT statement lets you define a two- or three-dimensional contact between a pair of

geometric objects. Adams/Solver (C++) models the contact as a unilateral constraint, that is, as a force

that has zero value when no penetration exists between the specified geometries, and a force that has a

positive value when penetration exists between two geometries.

The CONTACT statement supports:

Multiple contacts

Dynamic friction

Contact between three-dimensional solid geometries

Contact between two-dimensional geometries

It does not support non-solid three-dimensional geometries, such as shells that do not encompass a

volume and sheets. It also does not support contact between a two-dimensional and a three-dimensional

geometry.

Adams/Solver (C++) has two geometry engines that it uses for three-dimensional contacts. It uses

Parasolid, a geometry toolkit from EDS/Unigraphics, and RAPID. Currently, RAPID is the default and

Adams/Solver (C++) supports version 2.01.

Adams/Solver understands some geometries as analytical. Whenever possible use analytical geometries

to speed up solution time and realize smoother contact forces. Analytical geometries are created via the

GRAPHICS/ statement; following is the list of supported types:

Ellipsoid (this includes sphere as a special case)

Cylinder

Torus

Frustum

Box

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.

CONTACT 27

C++ Statements

Once the contact kinematics are known, contact forces, which are a function of the contact kinematics,

are applied to the intersecting bodies.

Note:

You can only define two-dimensional contacts between bodies that are constrained to be in

the same plane. This is usually done with planar or revolute joints or an equivalent set of

constraints that enforce the planarity.

Failure to enforce planarity will result in a run-time error, when the bodies go out of plane

during a simulation.

The following table shows the legal combinations of geometry for the CONTACT statement. If you use

unsupported geometry combinations, you will receive an error.

Supported Geometry Combinations

Arc Circle Curve Point Plane Box Cylinder Frustum Ellipsoid External FlexBody

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.

28 Adams/Solver

C++ Statements

Format

,JGEOM=id2[ ,..., idn]

IMPACT

,STIFFNESS=r

,

EXPONENT=r

,

DAMPING=r

, ,DMAX=r

POISSON

,PENALTY=r

,RESTITUTION_COEFFICIENT=r

COULOMB_FRICTION={On/Off}

,MU_STATIC=r

, ,MU_DYNAMIC=r

,STICTION_TRANSITION_VELOCITY=r

,FRICTION_TRANSITION_VELOCITY=r

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

CONTACT 29

C++ Statements

[ ] Optionally select one item

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

DAMPING = r

Used when you specify the IMPACT model for calculating normal forces.

DAMPING defines the damping properties of the contacting material. You

should set the damping coefficient is about one percent of the stiffness

coefficient.

Range: DAMPING >0

DMAX = r

Used when you specify the IMPACT model for calculating normal forces.

DMAX defines the penetration at which Adams/Solver turns on full damping.

Adams/Solver uses a cubic STEP function to increase the damping coefficient

from zero, at zero penetration, to full damping when the penetration is

DMAX. A reasonable value for this parameter is 0.01 mm. For more

information, refer to the IMPACT function.

Range: DMAX > 0

EXPONENT=r

Used when you specify the IMPACT model for calculating normal forces.

Adams/Solver (C++) models normal force as a nonlinear spring-damper. If

PEN is the instantaneous penetration between the contacting geometry,

Adams/Solver calculates the contribution of the material stiffness to the

instantaneous normal forces as STIFFNESS * (PENALTY)**EXPONENT.

For more information, see the IMPACT function.

Exponent should normally be set to 1.5 or higher.

Range: 0 < EXPONENT

30 Adams/Solver

C++ Statements

CITY = r

at the contact locations. Adams/Solver (C++) gradually transitions the

coefficient of friction from MU_STATIC to MU_DYNAMIC as the slip

velocity at the contact point increases. When the slip velocity is equal to the

value specified for FRICTION_TRANSITION_VELOCITY, the effective

coefficient of friction is set to MU_DYNAMIC. For more details, see

Extended Definition.

Note:

the integrator difficulties. You should specify this value as:

where ERROR is the integration error used for the solution. Its default value

is 1E-3.

Range:

FRICTION_TRANSITION_VELOCITY >

STICTION_TRANSITION_VELOCITY > 0

FRICTION_FUNCTION=USER(r

1[,...,r30])

components in a user-defined subroutine, CNFSUB.

FRICTION_ROUTINE =

library::function

the contact friction force.

IEDGE = id

ID of an edge on the IFLEX Body. Specifies a single edge. List of IDs is not

supported. IEDGE cannot be used without IFLEX. IFLIP may be used with

IEDGE.

IGEOM = id

ID of the GRAPHICS statement that defines the first of two geometric bodies

between which a CONTACT is to be modeled. Specifies a list of GRAPHICS

IDs. The limit is 32,767. All geometries must belong to the same part.

JGEOM = id

bodies between which a CONTACT is to be modeled. Specifies a list of

GRAPHICS IDs. The limit is 32,767. All geometries must belong to the same

part.

IFLEX = id

ID of the FLEX_BODY statement that defines the first of two flexible bodies

between which a CONTACT is to be modeled. Specifies a single FLEX ID.

List of IDs is not supported.

JEDGE = id

ID of an edge on the JFLEX Body. Specifies a single edge. List of IDs is not

supported. JEDGE cannot be used without JFLEX. JFLIP may be used with

JEDGE.

JFLEX = id

ID of the _BODY statement that defines the second of two flexible bodies

between which a CONTACT is to be modeled. Specifies a single FLEX ID.

List of IDs is not supported.

CONTACT 31

C++ Statements

IFLIP_GEOMETRY =

id1,id2,...,idN

reversed in direction (flipped). Use IFLIP_GEOMETRY only with twodimensional geometries (for example, curves, arcs, and circles). You can also

use IFLIP_GEOMETRY when defining contact between two spheres

(ellipsoids with equal axes). For an explanation of how CONTACT calculates

tangents and normals, see Extended Definition.

IMPACT

Specifies that the IMPACT method is to be used to model the normal force.

For more information, see Extended Definition.

JFLIP_GEOMETRY =

id1,id2,...,idN

reversed in direction (flipped). Use JFLIP_GEOMETRY only with twodimensional geometries (for example, curves, arcs, and circles). You can also

use JFLIP_GEOMETRY when defining contact between two spheres

(ellipsoids with equal axes). For an explanation of how CONTACT calculates

tangents and normals, see Extended Definition.

MU_DYNAMIC = r

Specifies the coefficient of friction at a contact point when the slip velocity is

larger than the FRICTION_TRANSITION_VELOCITY. For information on

material types versus commonly used values of the coefficient of the dynamic

coefficient of friction, see the Material Contact Properties table. Excessively

large values of MU_DYNAMIC can cause integration difficulties.

Range:0 < MU_DYNAMIC < MU_STATIC

MU_STATIC=r

Specifies the coefficient of friction at a contact point when the slip velocity is

smaller than the STICTION_TRANSITION_VELOCITY. For information

on material types versus commonly used values of the coefficient of static

friction, see the Material Contact Properties table. Excessively large values of

MU_STATIC can cause integration difficulties.

Range: MU_STATIC > 0

NORMAL_FUNCTION =

USER(r1,[,...,r30])

components in a user-defined subroutine, CNFSUB.

NORMAL_ROUTINE =

library::function

the contact normal force.

PENALTY=r

Used when you specify a restitution model for calculating normal forces.

PENALTY defines the local stiffness properties between the contacting

material. A large value of PENALTY ensures that the penetration, of one

geometry into another, will be small. Large values, however, will cause

numerical integration difficulties. A value of 1E6 is appropriate for systems

modeled in Kg-mm-sec. For more information on how to specify this value,

see Extended Definition.

Range: PENALTY > 0

POISSON

normal force. For more information, see the Extended Definition.

32 Adams/Solver

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

at the contact locations. Adams/Solver (C++) gradually transitions the

coefficient of friction from MU_DYNAMIC to MU_STATIC as the slip

velocity at the contact point decreases. When the slip velocity is equal to the

value specified for STICTION_TRANSITION_VELOCITY, the effective

coefficient of friction is set to MU_STATIC. For more details, see the

Extended Definition.

Note:

numerical integrator difficulties. A general rule of thumb for

specifying this value is:

STICTION_TRANSITION_VELOCITY> 5 ERROR

where ERROR is the accuracy requested of the integrator. Its default value is

1E-3.

Range: 0 < STICTION_TRANSITION_VELOCITY <

FRICTION_TRANSITION_VELOCITY

STIFFNESS=r

Specifies a material stiffness that you can use to calculate the normal force for

the impact model.

In general, the higher the STIFFNESS, the more rigid or hard the bodies in

contact are. Also note that the higher the STIFFNESS is, the harder it is for an

integrator to solve through the contact event.

Extended Definition

For more information on the key issues about the CONTACT statement, click a link below.

Contact Kinematics

Outward Normal Definition

Contact Kinetics

Contact Normal Force Calculation

Contact Friction Force Calculation

Contact Friction Torque Calculation

Contact Prediction

CONTACT 33

C++ Statements

Flexible Bodies

Contact Kinematics

The CONTACT statement lets you define contact between two geometry objects that you specify in

GRAPHICS entities in an Adams dataset (see the GRAPHICS statement). Adams/Solver (C++) supports:

Both two- and 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.

34 Adams/Solver

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

Intermittent contact - Is characterized by contact for short periods of time. It is also known as

impulsive contact. Two geometries approach each other, undergo a collision, and separate as a

result of the contact. The collision results in the generation of an impulse, that affects the

momentum of the colliding bodies. Adams/Solver (C++) develops an estimate of the contact

force by modeling the local deformation behavior of the contacting geometries.

Energy loss during the collision is usually modeled as a damping force that is specified with a

damping coefficient or a coefficient of restitution.

Intermittent contact is characterized by two distinct phases. The first is compression, where the

bodies continue to approach each other even after contact occurs. The kinetic energy of the

bodies is converted to potential and dissipation energy of the compressing contact material.

When the entire kinetic energy is transformed, the potential energy stored in the material

reverses the motion of the contacting bodies. Potential energy is transformed again to dissipation

energy and kinetic energy. This is known as the decompression phase. It is important to note that

energy losses due to dissipation occur in both phases.

CONTACT 35

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

36 Adams/Solver

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.

CONTACT 37

C++ Statements

dg

------ is the penetration velocity at the contact point.

dt

dmax is a positive real value specifying the boundary penetration to apply the maximum damping

coefficient cmax.

Clearly, for cmax = 0 and e = 1, the original penalization is recovered. The POISSON force model is

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.

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.

38 Adams/Solver

C++ Statements

(-vs) = s

(vs) = - s

(0) = 0

(-vd) = d

(vd) = - d

where:

V: Slip velocity at contact point

vs: STICTION_TRANSITION_VELOCITY

CONTACT 39

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

Caution:

If you need some other formulation of the friction torque, the only alternative is to write

your own friction force subroutine (CFFSUB). An example is given at the end of this

section.

Contact Prediction

Contact is fundamentally a discontinuous event. When two geometries come into contact:

A large normal force or an impulse is generated.

The velocities of the bodies change sign.

The accelerations are almost discontinuous, and have a large spike. This spike represents the

The bodies usually separate because of the contact forces or impulses. Numerical integrators assume that

the equations of motion are continuous. A contact event is, therefore, quite hard for an integrator to solve

through. Adams/Solver (C++) contains a contact predictor that predicts the onset of contact and controls

the integrator step size accordingly. The following paragraphs briefly summarize the contact prediction

algorithm.

When Adams/Solver (C++) detects a new contact, it calculates the penetration and penetration velocity

between the two geometries. From these two values, Adams/Solver (C++) estimates a more refined

contact time. Adams/Solver (C++) rejects the current time step and uses the refined step size to accurately

sense the onset of contact.

Furthermore, the integrator order is set to one, so that Adams/Solver (C++) does not use the time history

of the system to predict the future behavior of the system.

40 Adams/Solver

C++ Statements

The penetration for a new contact is small.

The integrator is at first order when the contact event occurs.

The integrator is taking small time steps.

Contacts and Analysis Mode Issues

This section explains how the various analysis modes deal with contact, and provides modeling tips on

how to successfully negotiate difficult contact events.

Contacts and Static Equilibrium

Both the static and quasi-static equilibrium analysis modes use Newton-Raphson (NR) iterations to solve

the nonlinear algebraic equations of force balance. The Jacobian matrix of first partial derivatives and the

residue of the equations of motion are used to set up an iterative scheme that normally converges to the

solution.

The Jacobian matrix is a measure of the stiffness matrix of the system. The inverse of the Jacobian is,

therefore, the compliance in the system. The NR algorithm ensures that the system solution moves in the

direction of most compliance (least stiffness). When a contact is active, the stiffness in the direction of

the normal force is high, so the NR algorithm modifies the system states to decrease this force. If a contact

is inactive, there is no stiffness in the direction of increasing contact. The NR algorithm will likely

compute a large movement in this direction, leading to excessive penetration. During the very next

iteration, since the contact force may turn on, a large stiffness is detected in this direction, and the

algorithm will change the system to dramatically reduce the amount of penetration. It is not uncommon

for the algorithm to overreact to this stiffness and move the system sufficiently to deactivate the contact.

The algorithm may never be able to resolve this discontinuity in the system.

Adams/Solver (C++) anticipates this situation and uses a contact-force-sensing mechanism to avoid

excessive contact. You can further enhance this method, however, by choosing the correct equilibrium

parameters.

Here are some modeling tips for aiding equilibrium (static) analysis (for more information on equilibrium

analysis, see the EQUILIBRIUM statement):

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

Avoid neutral equilibrium situations. If you know that your model has neutral equilibrium

situations, increase STABILITY (try STABILITY = 0.1). Also increase MAXIT, the maximum

number of iterations you will allow to obtain convergence.

See Best Practices for Working with Contacts for more information.

CONTACT 41

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

Increase the integration error tolerance using INTEGRATOR/ERROR=value. A larger integrator

Reduce damping. This decreases the duration of the contact and can help simulations.

Set the maximum integration order to 2, using INTEGRATOR/KMAX=2. Lower-order

Set HMAX to a small value to prevent the integrator from taking large steps.

Use the SI2 formulation. The corrector for this formulation is more stable than standard GSTIFF,

and may solve the problem where the standard GSTIFF failed.

Always run a model without contact friction first, and refine the functioning model by adding

friction later.

42 Adams/Solver

C++ Statements

FRICTION_TRANSITION_VELOCITY. Also reduce the coefficients of friction, which usually

helps the integrator.

Flexible Bodies

Flexible Bodies used in Contacts do not need a corresponding GRAPHICS statement. The geometry for

the Flexible Body is extracted from the Modal Neutral File (MNF), which is required.

CONTACT 43

C++ Statements

Caution:

An artificially low value of stiffness or penalty will not generate the necessary contact

If you find that your model response changes as the number of output steps is modified,

the solution.

The HHT integrator is incompatible with restitution (POISSON) contact.

If your model uses different length units than the stiffness properties you would like to

use, you need to scale the stiffness by:

length conversion factor**exponent

The reason for this is that the contact force due to penetration is defined as:

Adams/View will do this conversion for you if you change the units under Settings.

However, you will need to do it if you enter the parameters in different units.

Example:

k = 3800 N/mm

e = 2.0

current model units: force = N, length = m

stiffness to enter for contact = 3800*(1000**2) = 3.8e9

Also note that only length is raised to the exponent, so if you have a different force unit,

you would only scale it by the force conversion factor.

Contact cannot be defined between a Flexible Body and a list of 3D geometries

FLIP cannot be used with flexible bodies

The edges used in flexible body contact are modeled as 2D polylines. Higher order

interpolation is not allowed. Because they are 2D geometry, they may contact any other

2D geometry (rigid or flexible). They cannot be used in contact with 3D geometry.

The thickness of shell elements is ignored in flexible body contact.

44 Adams/Solver

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.

CONTACT 45

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

46 Adams/Solver

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.

Step size - Simulations allowed to run at large relative step sizes may cause contacts to have

integration steps can cause significant discontinuities. Running with a smaller hmax can help

some models by limiting the predictor-induced displacements.

Equilibrium - Static equilibrium is a very difficult problem to solve with contacts. Use good

modeling techniques, such as making sure that the objects expected to be in contact at

equilibrium are initially in contact in the input configuration. If this is not feasible, make sure

that the objects expected to be in contact are very close so that the contacts can be detected

during equilibrium iterations. It will also help to consider the appropriate TLIM and ALIM to

help limit the perturbations for finding equilibrium. Use dynamic equilibrium for models that

have difficulty finding static equilibrium.

Thin shells - During one solution step, Adams may take several integrator steps in order to

satisfy predictor-corrector requirements. If input geometry is very thin, there is a possibility that

one geometry may completely pass through another, resulting in invalid volume of intersection

calculations. This can result in missed contacts, passthroughs, or generation of unusually high

contact force. Reducing hmax can help prevent this problem.

Friction - Friction calculations are highly discontinuous and can cause numerical convergence

problems, especially at low relative velocities. The friction difficulties compound the already

difficult contact evaluations. Whenever possible, run a model without contact friction first, and

refine the functioning model by adding friction later. If the addition of frictional forces causes

numerical difficulties or simulation slowdowns, gradually increase the values for

STICTION_TRANSITION_VELOCITY and FRICTION_TRANSITION_VELOCITY. Also

reduce the coefficients of friction, which usually helps the integrator.

CONTACT 47

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.

Analytical Contact - Analytical contact should be used whenever possible.

Contact Parameters (Stiffness, Damping, Force Exponent) - Take into account the mass and

inertia of each part in the mechanism and the resulting velocities at which the contact bodies are

traveling with respect to each other. Based on this, ensure that the contact parameters are defined

with appropriate values.

Examples

The example below demonstrates contact between two generic three-dimensional geometries.

star_geneva.xmt_txt is a geometry file that was generated by Parasolid. Adams/View or any CAD

48 Adams/Solver

C++ Statements

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

!

MARKER/30028, PART = 1004

GRAPHICS/12,

, EXTERNAL,

, FILE = star_geneva.xmt_txt,

, ELEMENT = SOLID3,

, RM = 30028

CONTACT/1,

, IGEOM=11,

, JGEOM=12,

, IMPACT,

, STIFFNESS = 1E6,

, DAMPING = 10,

, DMAX = 0.1,

, EXPONENT = 2.2

CONTACT/1,

, IGEOM=11,

, JGEOM=12,

, POISSON,

, PENALTY = 1E5,

, RESTITUTION_COEFFICIENT = 0.6

Below is an example of lists of geometry. Geometries 11 and 12 must belong to one part. Geometries 13,

14, and 15 must all be on one part. Geometries 12, 13, and 15 are flipped.

CONTACT/1,

, IGEOM = 11, 12

, JGEOM = 13, 14, 15

, IFLIP_GEOMETRY = 12

, JFLIP_GEOMETRY = 13, 15

, IMPACT,

, STIFFNESS = 1E6,

, DAMPING = 10,

, DMAX = 0.1,

, EXPONENT = 2.2

Below is an example of user-written subroutines in contacts. The normal force subroutine (CNFSUB)

and the friction force subroutine (CFFSUB) are in the same library (cnforc1).

CONTACT 49

C++ Statements

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)

star_geneva Mechanism

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.

50 Adams/Solver

C++ Statements

CONTACT/1

, IFLEX = 1

, IEDGE = 2

, JGEOM = 1

, IMPACT

, STIFFNESS = 1.0E+005

, DAMPING = 10

, DMAX = 0.1

, EXPONENT = 2.2

COUPLER 51

C++ Statements

COUPLER

A COUPLER statement relates the translational and/or the rotational motion of two or three joints.

Format

Arguments

0])

defined subroutine COUSUB, COUXX, COUXX2. These subroutines

define the coupler displacement constraint function, and provide its first

and second order partials, respectively (see the COUSUB, COUXX,

COUXX2 subroutines).

JOINTS=id1,id2[,id3]

and/or rotational displacements are to be coupled. You can only specify

identifiers of translational, revolute, and cylindrical joints.

ROUTINE=lib1::cou1,

lib2::cou2, lib3::cou3

subroutines COUSUB, COUXX, and COUXX2 respectively.

Learn more about the ROUTINE Argument.

52 Adams/Solver

C++ Statements

SCALES=[r1,]r2[,r3]

Adams/Solver (C++) uses the values in the SCALES argument to form

the equation:

(r1 * q1) + (r2 * q2) + (r3 * q3) = 0,

where r1, r2, and r3 are the scale factors for the three joints, and for each

joint, q1, q2, and q3 are the translational or rotational displacements of

the joint I marker with respect to the joint J marker. Suppose two joints

are being coupled, and SCALES=1,-2. The equation that relates the two

joints is:

(1 * q1) + (-2 * q2) = 0

or

q1 = 2 * q2.

The displacement (q1) of the I marker with respect to the J marker in the

first joint is twice that of the displacement (q2) of the I marker with

respect to the J marker in the second joint; the two displacements have

the same sign. If two joints are specified in the JOINTS argument, r2

must be specified. Adams/Solver (C++) assumes r2 if only one value is

specified and uses the default value of 1 for r1.

If three joints are specified in the JOINT argument, you should either

specify three scale values r1, r2, and r3, or provide only two scale

values. In the latter case, the two values are assigned by Adams/Solver

(C++) to r2 and r3 (in this order) while r1 is given the default value 1.0.

Defaults: r1 (1); r2, r3 (none)

Range: non-zero real numbers

Indicates whether joints transfer translational or rotational motion. If the

coupler includes no cylindrical joints, do not use TYPE. However, if the

coupler includes one or more cylindrical joints, TYPE must be used. In

that case, input T (translational) or R (rotational) for each joint specified

with JOINTS, even the translational or revolute joints. Because

Adams/Solver (C++) assumes that translational joints transfer

translational motion and that revolute joints transfer rotational motion,

Adams/Solver (C++) ignores Ts and Rs for translational and revolute

joints; they are placeholders only. But because a cylindrical joint

permits either translational or rotational motion, Adams/Solver needs a

T or R for each cylindrical joint to determine the type of motion on

which the coupler acts.

COUPLER 53

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.

translational motion, rotational to rotational, or translational to rotational.

The COUPLER is a constraint between joint degrees of freedom. Therefore, it

models only the reaction forces that are along or about the degrees of freedom that

are being coupled.

You can model a pair of mating spur gears as a COUPLER between two

REVOLUTE joints. If (I1, J1) are the I and J markers of the first joint and (I2, J2)

are the I and J markers of the second joint, the COUPLER constraint is:

AZ(I1,J1) * scale_1 + AZ(I2,J2) * scale_2 = 0

where scale_1 and scale_2 are the radii of the two gears.

The reaction forces generated by the COUPLER are the torques at the two joints

required to maintain the constraint shown above. The reaction on the first joint is

the torque about the z-axis of marker J1. The reaction on the second joint is the

torque about the z-axis of marker J2. You can compute the tooth force from these

torques, but Adams/Solver (C++) does not explicitly solve for them.

You can also model a rack and pinion gear as a COUPLER relating the rotation in

a REVOLUTE joint, with the translation in a TRANSLATIONAL joint. If (I1, J1)

are the I and J markers of the REVOLUTE joint and (I2, J2) are the I and J markers

of the TRANSLATIONAL joint, the COUPLER constraint is:

AZ(I1,J1) * scale_1 + DZ(I2,J2,J2) * scale_2 = 0

where scale_1 is the pinion radius, and scale_2=1.

The COUPLER reaction on the REVOLUTE joint is a torque about the z-axis of

Marker J1, and the reaction on the TRANSLATIONAL joint is a force along the zaxis of Marker J2.

54 Adams/Solver

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

If one or more cylindrical joints for the coupler is specified, Adams/Solver (C++)

requires you to input one or more entries for the TYPE argument, depending on the

order of the cylindrical joint(s) in the JOINTS argument list. Adams/Solver (C++)

must have a type entry for every cylindrical joint and a place holder entry for every

joint entered before a cylindrical joint on the JOINTS argument.

Examples

COUPLER/01, JOINTS=4,6, TYPE=T:R, SCALES=90D, -1

This COUPLER statement relates the translational motion at Joint 4 to the rotational motion at Joint 6.

Joint 4 is either a translational or cylindrical joint, and Joint 6 is either a revolute or cylindrical joint. The

SCALES argument indicates the relationship:

(90D)q1 - q2 = 0

or

(90D)q1 = q2.

In other words, when q1 is a positive translation of one system unit, q2 is a positive rotation of 90 degrees.

Internal to Adams/Solver (C++), all values entered in degrees are converted to radians for calculation

purposes. The figure below shows a coupler.

Coupler

CURVE 55

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])/

computes the curve coordinates and derivatives (see the CURSUB subroutine).

The FUNCTION argument must be either the last argument in the CURVE

statement or it must be followed by a backslash (\).

MATRIX=id

Specifies a MATRIX statement that contains data for a curve. The matrix

contains the x, y, and z coordinates of the curve points. The matrix should have

a row for each point and three columns containing the x-, y-, and z-coordinates

of the points. You must supply at least four curve points. The first and last points

must be the same for a closed curve.

56 Adams/Solver

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

B-spline of order K means that it is made up of piecewise polynomial segments

of degree K-1. A cubic B-spline is order 4. A B-spline of order 2 is called a

polyline because it is made up of straight line segments between each of the

CURVE_POINTS. It is important to note that a B-spline of order K will have

K-2 continuous derivatives. The discontinuities appear where the polynomial

segments join together. Increasing the order of the B-spline arbitrarily may

introduce unwanted oscillation into the curve.

Default: 4

Range: ORDER > 2

ROUTINE=libname

::subname

Specifies an alternative library and name for the user subroutine CURSUB.

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

CURVE 57

C++ Statements

Enter curve points to which Adams/Solver (C++) matches a curve.

Write a CURSUB evaluation subroutine with which Adams/Solver (C++) computes curve

A uniform B-spline is a piecewise polynomial spline used in many CAD (computer-aided design)

applications. A B-spline is defined by control points that form a polygon in space and a knot vector.

Adams/Solver (FORTRAN) uses a non-uniform knot vector with quadruple multiplicity at both ends.

The curve starts at the first control point and ends at the last. In between, it is attracted to, but does not

necessarily hit, the intermediate control points. Adams/Solver (FORTRAN) parameterizes a B-Spline

starting at -1 and ending at +1. The figure below shows a set of control points and the B-spline curve it

defines.

58 Adams/Solver

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.

CURVE 59

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.

60 Adams/Solver

C++ Statements

CVCV

The CVCV statement defines a curve-to-curve constraint that restricts a planar curve on one part that is

to be in contact with, and tangent to, a planar curve on a second part. The curves must lie in the same

plane, but the parts to which they are attached may undergo three-dimensional motion.

Format

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.

CVCV 61

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.

62 Adams/Solver

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

CVCV 63

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.

64 Adams/Solver

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

cylindrical joint, not a revolute joint. If the follower is held by a translational joint

and the cam by a cylindrical joint, the CVCV constraint between the follower and

cam prevents the cam from translating along the axis of rotation (that is, the axis of

the cylindrical joint). A revolute joint would add a redundant constraint in that

direction.

CVCV 65

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.

66 Adams/Solver

C++ Statements

Figure 3

Cam-Follower Mechanism

DEBUG 67

C++ Statements

DEBUG

The DEBUG statement outputs data that helps you debug a simulation.

Format

DEBUG/ EPRINT

,JMDUMP

, MATLAB

,RHSDUMP

[]

[[ ]]

Optionally select an item combination

68 Adams/Solver

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

The order of the predictor for dynamics. This corresponds to the order of the polynomial

Adams/Solver (C++) uses to predict the solution at the end of the integration step.

The value of time at the beginning of the step.

The size of the step.

For the second phase, Adams/Solver (C++) prints out the cumulative number of iterations and a table

of information about the iterations. The cumulative number of iterations is a running count of the

iterations needed to solve the equations of motion and can be used as a measure of how many

computations Adams/Solver (C++) is performing. The table contains information about the largest

equation imbalance (error) and maximum variable change for each iteration. For each iteration,

Adams/Solver (C++) prints out seven or eight pieces of the following information:

The iteration number. This is one at the beginning of each step and increments by one until

iterations.

The absolute value of the largest equation residual error. Each equation should have an error

value close to zero. This number is an indicator of how far Adams/Solver (C++) is from a

solution. This number should decrease after every iteration.

The dataset element associated with the largest equation residual error.

The equation that has the largest equation residual error for the above dataset element.

The absolute value of the largest change in a variable. The final iteration should not need to

change variables very much. This number is an indicator of how aggressive Adams/Solver

(C++) needs to change variables to approach a solution. This number should decrease after

every iteration.

The dataset element associated with the absolute value of the largest change in a variable.

The variable with the largest change for the above dataset element.

If Adams/Solver (C++) has updated the Jacobian, YES appears under the new Jacobian

header.

Default: Off

DEBUG 69

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:

extremely large tabular output file. If a dataset needs to be debugged, include these

arguments in the DEBUG statement and execute only a brief simulation.

Extended Definition

The DEBUG command section contains additional descriptions on the information returned by

DEBUG/EPRINT command.

Examples

DEBUG/EPRINT

This DEBUG statement generates the information in Figure 4 that appears in the message file.

In this example, Adams/Solver (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.

70 Adams/Solver

C++ Statements

Figure 4

DIFF 71

C++ Statements

DIFF

The DIFF statement creates a user-defined state variable and defines a first-order differential equation

that describes it.

Format

72 Adams/Solver

C++ Statements

Argument

argument list for the user-written subroutine that defines the

differential equation. To define the equation with an expression,

follow FUNCTION with an equal sign and the expression. To

define the equation with a user-written subroutine, follow

FUNCTION with an equal sign, the character string USER, and

the argument list (r1[,...,r30]) of values and system variables to

be passed to the user-written subroutine DIFSUB (see the

DIFSUB subroutine). In a function expression, the system

variable DIF(i) is the value of the dependent variable defined by

the DIFF/i statement. DIF1(j) is the first derivative of the

dependent variable defined by the DIFF/j statement. Note that

the FUNCTION argument must either be the last argument in the

DIFF statement or be followed by a backslash (\).

IC=r1[,r2]

optionally, an approximate value of the initial time derivative.

The value r1 is the value of the user-defined variable at the start

of the simulation. If you enter an implicit equation, r2 may also

need to be specified, which is an approximate value of the time

derivative of the user-defined variable at the start of the

simulation. Adams/Solver (C++) might adjust the value of the

time derivative when it performs an initial conditions analysis.

Entering an initial value for the time derivative helps

Adams/Solver (C++) converge to a desired initial conditions

solution. You do not need to supply r2 when you enter a explicit

equation since Adams/Solver (C++) can compute the initial time

derivative directly from the equation. Adams/Solver (C++)

requires you to enter r1.

Default: 0

IMPLICIT

defines the implicit form of a differential equation.

Adams/Solver (C++) assumes that either the expression or userwritten subroutine defines the explicit form of the equation if

IMPLICIT is not specified. In this case, the time derivative of the

state variable is set to the value of FUNCTION.

ROUTINE=libname::subname

DIFSUB.

Learn more about the ROUTINE Argument.

STATIC_HOLD

static and quasi-static analysis.

DIFF 73

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:

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)

74 Adams/Solver

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)

DIFF/11 defines the equation in explicit form, where the function expression computes

below.

y as shown

DIFF/12 defines the equation in implicit form, where Adams/Solver equates the function expression to

zero, as shown below.

y + 2y - 4 - sin (t) = 0

Applications

The DIFF statement defines a first order, linear or nonlinear, explicit or implicit, ordinary differential

equation for Adams/Solver (C++) to integrate along with the dynamic simulation of a multibody system.

The equation may be independent of the rest of the problem or it may depend upon any variable in the

DIFF 75

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.

76 Adams/Solver

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.

ENVIRONMENT 77

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

runtime environment variable being set.

VALUE=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

runtime environment.

Extended Definition

The operating system environment stands for a set of environment variables. Each of these environment

variables has a name, and it may have an associated value. Both name and value are character strings set

by the user using tools provided by the operating system.

The use of environment variables provides a simple mechanism to let users communicate preferences to

a running computer program. The use of environment variables is a practical way to trigger the execution

of undocumented features, workarounds, experimental methods, etc. without the need to modify the

AMD/ACF language layers of the Adams/Solver (C++).

When the execution of Adams/Solver (C++) starts, all the environment variables are scanned and the

Adams/Solver (C++) runtime environment is created. The Adams/Solver (C++) runtime environment is

initialized with all the environment variables that the Adams/Solver (C++) recognizes. Environment

78 Adams/Solver

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:

ENVIRONMENT 79

C++ Statements

---------------------------------------------------------------MSC_ADAMS_SOLVER_BEAM_MODEL=NONLINEAR

Enforces Adams/Solver C++ to use a different beam model.

Options are LINEAR, STRING, NONLINEAR.

* Overwrites a previous definition.

Observe Adams/Solver prints the note "Overwrites a previous definition" indicating that the

ENVIRONMENT statement overwrote the value of the environment variable set in the operating

system.

3. In this example we use the ENVIRONMENT statement to unset any previous definition of an

environment variable.

ENV/

, NAME=MSC_ADAMS_SOLVER_BEAM_MODEL, UNSET

If the environment variable was not defined, the statement is ignored with a warning message.

Caution:

undocumented features. They may be removed in a future release without notice. Please

bear this in mind when using the ENVIRONMENT statement and command.

80 Adams/Solver

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

Optionally select an item combination

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

carried out during the equilibrium analysis can not converge prior to all

relevant relative corrections being smaller than this value.

Default: 1.0E-04

Range: ERROR > 0

EQUILIBRIUM 81

C++ Statements

IMBALANCE=r

carried out during the equilibrium analysis can not converge prior to each

equation imbalance being smaller than this value.

Default: 1.0E-04

Range: IMBALANCE > 0

MAXIT=i

equilibrium.

Default: 25

Range: MAXIT > 0

PATTERN=c1[:...:c10] Allows you to specify as many as ten character strings that together establish

the pattern for evaluating the Jacobian matrix during the modified 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

Default: 20

Range: TLIMIT > 0

82 Adams/Solver

C++ Statements

METHOD=i

Specifies the option which determines the static solver method to be used for

equilibrium solution.

1. ORIGINAL, for running only the ORIGINAL Solver

2. ADVANCED, runs, in order, the following methods until one shows

progress:

a. ORIGINAL

b. ORIGINAL+Krylov

c. ORIGINAL+UMF

d. Newton+Krylov

e. Tensor-Krylov block-3

f. Tensor-Krylov block-2+

3. AGGRESSIVE, runs, in order, the following methods until one shows

progress:

a. ORIGINAL

b. ORIGINAL+Krylov

c. ORIGINAL+UMF

d. Newton+Krylov

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

EQUILIBRIUM 83

C++ Statements

ATOL

Default: 1.0e-6

Range: 0.0 < ATOL < 1.0

RTOL

For all solvers, except ORIGINAL and ORIGINAL+Krylov, the tolerance is

defined as : TOL=ATOL+||xIC||*RTOL.

For ORIGINAL and ORIGINAL+Krylov solvers the tolerance is equal to

ERROR.

Default: 0.0

Range: 0.0 < RTOL < 1.0

MAXITL

Specifies the maximum number of allowed inner loops in all the solvers.

ORIGINAL, ORIGINAL+Krylov and ORIGINAL+UMF solver methods

ignore this parameter. For Hooke-Jeeves method, allowed budget of function

evaluations is set to MAXITL*N, where N is the size of the problem (number

of unknowns).

Default: 40

Range: > 0

ETAMAX

Specifies the maximum threshold for the error tolerance of the linear Krylov

solver (for Newton+Krylov and Tensor-Krylov methods) that solves the linear

systems required by Krylov algorithm. Maximum error tolerance for residual

in inner iteration. The inner iteration terminates when the relative linear

residual is smaller than eta*| F(x_c) |. eta is determined by the modified

Eisenstat-Walker formula if etamax > 0. If etamax < 0, then eta = |etamax| for

the entire iteration.

Default: 0.9

Range: 0.0 < ETAMAX < 1.0

ETA

Specifies the initial residual tolerance for the linear Krylov Solver for

Tensor_Krylov method. The Tensor-Krylov ETA parameter is maintained

adaptively by the Krylov algorithm but ETA is the indicated starting value,

while ETAMAX is the maximum threshold for ETA.

Default: 1.0e-4

Range: 0.0 < ETA < 1.0

Specifies the dimensionless radius of the trust-region for Trust-region method.

The smaller the value, the more the refinement of Trust-region solution (hence

more work).

Range: 0.0 < ETA < 0.25

84 Adams/Solver

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.].

EQUILIBRIUM 85

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

prevent Adams/Solver (C++) from finding a static equilibrium position.

Use the IMBALANCE argument if the physical units of the problem are such that

Changing from an inappropriate to an appropriate value for IMBALANCE saves

CPU time.

You can use the MSC_USE_ALTERNATE_SOLVERS environment variable to

specify a particular method to be used for equilibrium solution. The variable works

as an integer bit-mask with 9 bits, corresponding to the eight solvers above in the

order: ORIGINAL (bit0), ORIGINAL+Krylov (bit1), ORIGINAL+UMF

(bit2), Newton+Krylov (bit3), Tensor-Krylov block-3 (bit4), Tensor-Krylov

block-2+ (bit5), Broyden-Armijo (bit6), Trust-Region (bit7), Hooke-Jeeves

(bit8). The lowest order bit, if set to 1, means ORIGINAL solver will be used. The

highest order bit, if set to 1, means Continuation method will be used.

For example if the user wants to enforce the exclusive use of only

ORIGINAL+Krylov, ORIGINAL+UMF, Broyden-Armijo, and Trust-Region

solvers, then the bits that must be set are bit1, bit2, bit5, and bit7. Hence, the

binary value of MSC_USE_ALTERNATE_SOLVERS is 10100110, 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

stable position. For example, Adams/Solver (C++) may converge to an inverted

pendulum position rather than the more common hanging pendulum. Items such as

the initial position of parts and the settings for ALIMIT, TLIMIT, and STABILITY

can all influence the solution to which Adams/Solver (C++) converges.

If MSC_USE_ALTERNATE_SOLVERS is set to a non-zero value, then its value

86 Adams/Solver

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.

FEMDATA 87

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

88 Adams/Solver

C++ Statements

Arguments

CRITERION = c

Supported criteria are one of: VON_MISES, MAX_PRIN, MIN_PRIN,

MAX_SHEAR, NORMAL_X, NORMAL_Y, NORMAL_Z, SHEAR_XY,

SHEAR_YZ, and SHEAR_XZ. Default criterion is VON_MISES.

DATUM = node_id

displacements. Adams/Solver computes all nodal displacements relative to

this node ID. If you do not specify a datum node, Adams/Solver generates an

arbitrary relative set of nodal displacements. It displays a warning message if

the specified node does not belong to the flexible body.

END = t2

Specifies the time, t2, at which to end the output of the data or the search of

a peak load.

Default: Output or search to the end of the simulation.

Range: t2 > t1

HOTSPOTS = n

Specifies the number of hot spots to locate on the flexible body and output.

A search for the top n nodes that recorded the highest stress or strain during

the simulation will ensue. With the START, END or SKIP arguments,

FEMDATA only checks the time steps within those specifications for hot

spots. A text file containing a table of hot-spot data (node ID, maximum

value, time of maximum value, and location) will be output. The complete

time history of nodal stress or strain will be output as well for each hot spot,

if the STRAIN or STRESS option is specified in the OUTPUT statement.

FLEX_BODY = id

FEMDATA outputs the data in the FEM basic coordinate system that is

inherent to the flexible body, except in the case of STRAIN or STRESS with

the RM=id option.

FILE = name

Specifies the output file name for the FEM data. You can specify an existing

directory, root name, and/or extension. By default, the file name will be

composed of the ADAMS run and body IDs according to the type of data and

file format that you specified in the OUTPUT statement.

LOADS

Outputs all external forces (reaction and applied forces except gravity) acting

on the specified body and inertial forces of the specified body (angular

velocities and accelerations including effects of gravity) as a function of time.

Load data will be output in the simulation set of units.

ON

body. FEMDATA will only export coordinates of the active modes in the

simulation.

NODAL_DEFORMATI

ON

FEMDATA writes the formations in the simulation set of units.

FEMDATA 89

C++ Statements

you do not specify a node list, FEMDATA exports nodal data at each

attachment point of the flexible body. Adams/Solver issues a warning if a

node ID is specified that does not belong to the flexible body.

NOINERTIA

Turns off the output of inertia loads. Inertia loads include linear acceleration,

angular acceleration, and angular velocity of the part or flexible body. Only

loads due to reaction and applied forces are output with this option. This

results in a load imbalance specification for the body, so you must employ a

technique, such as inertia relief, to recover the inertia loads from the external

loads in the finite element program.

PEAK_SLICE =

Specifies that FEM load data are to be output only at those time steps where

FX:FY:FZ:FMAG: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

output loads. Because Adams/Solver resolves all loads acting on the rigid

body in the coordinate system of the specified marker, the marker should

represent the FEA basic coordinate system of the part's finite element model

(FEM).

If only RM is specified with no accompanying type (that is, LOADS or

STRESS or STRAIN), an old style .fem file is generated with loading

information for each rigid body that has a marker listed on this field.

For STRESS or STRAIN, optionally specifies the reference coordinate

system in which to output. If RM is not specified, stress/strain will be

computed in the flexible bodys LPRF. If specified, the stress/strain tensor

will be transformed relative to instantaneous coordinate system of marker ID.

The RM does not have to belong to the flexible body, but can be any marker

in the model. All six components of stress or strain (Sxx, Syy, Szz, Sxy, Syz,

Szx) can be affected by this coordinate transformation. This option can be

useful when correlating test results such as strain gauge data on a flexible

component.

SKIP = n

Specifies the number of output steps to skip when outputting the data.

Default: n=0 (every step is output).

90 Adams/Solver

C++ Statements

START = t1

Default: Output at the start of the simulation.

Range: t1 > t2 (See END argument)

STRAIN

Outputs strain information if strain modes are available in the modal neutral

file (MNF) of the specified flexible body. FEMDATA outputs all six

components of strain (normal-X, normal-Y, normal-Z, shear-XY, shear-YZ,

shear-ZX). It outputs strains in the basic FEA coordinate system of the

flexible body, unless the RM=id option is specified.

STRESS

Outputs stress information if modal stresses are available in the MNF of the

flexible body. FEMDATA outputs all six components of stress (normal-X,

normal-Y, normal-Z, shear-XY, shear-YZ, shear-ZX). It outputs stresses

output in the simulation set of units in the basic FEA coordinate system of the

flexible body, unless the RM=id option is specified.

Extended Definition

Default File Naming Conventions

You can use the FILE argument to specify the directory, name, and/or extension

(directory/name.extension) for the output file. If you do not specify a directory, FEMDATA creates all its

output files except DAC files in the current working directory. Because several DAC files are typically

generated for a FEMDATA statement, FEMDATA creates them in a separate directory named after the

body. It creates this directory in the current working directory if it does not exist.

If a file name is not specified in the FILE argument, default file names are assigned according to the type

of FEM data and file format (which is specified in the OUTPUT statement) as shown in the table below.

FEMDATA Default File Names and Extensions

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

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 91

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

Old Style FEMDATA

An older version of the FEMDATA statement where one or more RM markers are specified with no data

type is still being supported. The format of this version of FEMDATA is:

FEMDATA/id, RM=id1[,...,id100]

In this case, a text file with extension .fem is generated. This file contains generic load specifications for

the parent body of each RM marker specified.

Format of .fem File

The .fem file contains information sufficient to define all forces (inertial and applied) acting on one or

more parts. The data in this file is intended to be converted to boundary conditions input to a finite

element program. This file is composed of the following lines:

Line1: <Header>

Line 2: <Title>

Lines repeated for every part:

Lines repeated for every output step:

<Record 1> (RM Displacement)

<Record 2> (CM Displacement)

<Record 3> (CM Velocity)

<Record 4> (CM Acceleration)

<Record 5> (Force Displacement)

<Record 6> (Force Values)

<Header> Definition

Output: File Version #, Date&Time, User ID, Job ID, Program ID

Format: 1X, A4, 4X, A18, 6X, 2I10, 2X, A2

92 Adams/Solver

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.

FX = Output loads at time t when

m.

FEMDATA 93

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

94 Adams/Solver

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.

FEMDATA 95

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

96 Adams/Solver

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.

FIELD 97

C++ Statements

FIELD

The FIELD statement applies a translational and rotational action-reaction force between two markers.

Format

98 Adams/Solver

C++ Statements

Arguments

CMATRIX=r1,...,r36

shows the values to input.

Enter the elements by columns from top to bottom, then from left to right.

CMATRIX defaults to a matrix with thirty-six zero entries if you do not use

either CMATRIX or both CRATIO and KMATRIX. The units for the

translational and rotational components of CMATRIX should be force-time

per unit displacement and torque-time per radian, respectively.

CRATIO = r

Adams/Solver (C++) multiplies KMATRIX by CRATIO to obtain

CMATRIX. Do not use CRATIO without also using KMATRIX.

Default: 0

FORCE=r1,...r6

Defines three preload force components and three preload torque components

in the field element when the I and J markers are separated/misaligned by the

values specified in the LENGTH argument. The terms r1,...,r6 are the force

components along the x-, y-, and z-axis of the J marker and the torque

components about the x-, y-, and z-axis of the J marker, respectively. FORCE

is optional and defaults to six zero entries.

FUNCTION=USER(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.

FIELD 99

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.

100 Adams/Solver

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

K 31 K 32 K 33 K 34 K 35 K 36 z z 0

C 31 C 32 C 33 C 34 C 35 C 36 V z

F3

Tx

K 41 K 42 K 43 K 44 K 45 K 46 a a 0

C 41 C 42 C 43 C 44 C 45 C 46 x

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

T1

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

K is the stiffness matrix.

x0, y0, z0, a0, b0, and c0 are the free lengths.

x, y, z, a, b, and c are the translational and the rotational displacements of the I marker with

Vx,Vy,Vz, x , y , and

damping matrix.

F1, F2, F3, T1, T2, and T3 are the translational and the rotational pre-tensions.

FIELD 101

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.

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.

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

The K and C matrices must be positive semidefinite. In other words:

ytC y > 0 for all non-zero velocities y.

If this is not true, the stiffness matrix of the field may be removing energy from the system.

Similarly, the damping matrix may be adding energy to the system. Both of these situations

are uncommon. Adams/Solver (C++) does not warn you if the C matrix, K matrix, or both

are not positive semidefinite. While Adams/Solver (C++) does not require that these

matrices be symmetric, it is most realistic.

102 Adams/Solver

C++ Statements

Examples

Cantilever, Semimonocoque Wing Structure

In order to model the elastic freedoms at location I shown in the figure, the system stiffness matrix must

first be determined for the retained degrees of freedom. A finite element super element analysis is one

method for determining the matrix. Assume that all other degrees of freedom are either constrained or

superfluous for this analysis. The system stiffness matrix is:

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

FIELD 103

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.

104 Adams/Solver

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]

FLEX_BODY 105

C++ Statements

[ ] Optionally select the item

[[ ]] Optionally select an item combination

106 Adams/Solver

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

DB_FILE=file_name

properties of the flexible body. If there are more than one flexible

bodies stored in the database, an INDEX argument should be

specified to identify the body.

This is one of the two ways to specify the detailed properties of a

flexible body (See MNF_FILE for the alternative). Note that this

argument (or MNF_FILE) is not required by Adams/Solver (C++)

unless flexible body contact is defined, but is required by

Adams/View.

FLEX_BODY 107

C++ Statements

DMODE=a1,a2,...,an

Default: 0

Range: Real values

DYNAMIC_LIMIT=d

Modes whose frequencies are higher than d will be treated as quasistatic modes, i.e., the dynamic effects ( q and q terms) are ignored in

dynamic simulation. So for quasi-static mode, the equation of motion

is just Kq = F , where K is the generalized stiffness, q is the modal

coordinate and F is the modal force acting on this mode, which may

include the coupling effects with other DOFs of flexible body. When

only static deformations are of interest for a particular simulation,

using the dynamic limit may improve the simulation performance for

models that have a lot of high-frequency modes.

The damping specified by CRATIO or GDAMP will be ignored for

quasi-static modes. Please refer to STABILITY_FACTOR on how to

specify damping on quasi-static modes.

Default: +

EXACT=c1:...:c6

Adams/Solver (C++) should not change as it iteratively solves for

initial conditions which satisfy all constraints. The six coordinates

are:

X - x coordinate

Y - y coordinate

Z - z coordinate

PSI - Psi angle

THETA - Theta angle

PHI - Phi angle

These coordinates can be entered in any order following EXACT.

Adams/Solver (C++) does not change coordinates unless the values

specified are inconsistent with initial conditions for a joint or defined

motion.

Default: None

Range: X, Y, Z, Psi, Theta, or Phi

108 Adams/Solver

C++ Statements

MATRICES argument should be applied to the FLEX_BODY. If

GDAMP is OFF, the generalized damping matrix is ignored. If FULL

is specified, the generalized damping matrix is applied to both the

rigid and modal coordinates of the FLEX_BODY. If you specify

INTERNAL_ONLY, only the portion of the generalized damping

matrix corresponding to the modal coordinates is applied.

Default: OFF

Note:

INDEX=index

defined a GENDAMP matrix for the associated

FLEX_BODY.

of storing more than one flexible body.

Default: 1

FLEX_BODY 109

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

110 Adams/Solver

C++ Statements

MATRICES=id1,...,idn

FLEX_BODY, such as inertia, node locations, mode shape

information, applied modal loads, and preloads. Each matrix is

defined via a MATRIX statement. Normally, these matrices are

generated by a modal flexibility preprocessor (MNF2MTX), which

writes these matrices to a file. The MATRIX statement then references

this file, along with the appropriate name from the list below. To learn

more about this process, see Creating Matrix Files.

The FLEX_BODY recognizes the following matrix names. Their

identifiers can be specified in any order.

SELMOD: A list of selected modes and their natural frequency.

SELNOD: A list of selected nodes and their location.

GENSTIFF: The generalized stiffness matrix.

INVAR1: Invariant 1 - the total mass of the flexible body.

INVAR2: Invariant 2 - the mass scaled center of mass location.

INVAR3: Invariant 3.

INVAR4: Invariant 4.

INVAR5: Invariant 5.

INVAR6: Invariant 6 - the generalized mass.

INVAR7: Invariant 7 - the moment of inertia.

INVAR8: Invariant 8.

INVAR9: Invariant 9.

T_MODE: Translational mode shape of selected modes at selected

nodes.

R_MODE: Rotational mode shape of selected modes at selected

nodes.

PRELOAD: The preload on the selected modes.

MODLOAD: The modal loadcases on the selected modes.

GENDAMP The generalized damping matrix.

EDGE_xx: A list of selected nodes which define an edge of the

flexible body (xx denotes an arbitrary edge id).

Default: None

Range: Adams identifiers

FLEX_BODY 111

C++ Statements

(C++) should not change as it iteratively solves for initial conditions

that satisfy all constraints. The variable n is the number of modal

coordinates.

These coordinates can be entered in any order following MEXACT.

They are not changed by Adams/Solver (C++) unless the values

specified are inconsistent with initial conditions for a joint or defined

motion.

Default: None

Range: Active mode numbers

MNF_FILE=file_name

Specifies the path to the modal neutral file that defines the detailed

properties of the flexible body.

This is one of the two ways to specify the detailed properties of a

flexible body (See DB_FILE for the alternative). Note that this

argument( or DB_FILE) is not required by Adams/Solver (C++)

unless flexible body contact is defined, but is required by

Adams/View.

QG=x,y,z

the ground coordinate system.

Default: 0.0, 0.0, 0.0

Range: Real values

REULER=a,b,c

establish the initial orientation of the BCS with respect to the ground

coordinate system. The a, b, and c rotations are in radians and are,

respectively, about the z-axis of ground, new x-axis, and new z-axis

of the BCS. To input Euler angles in degrees, you should add a D after

each value.

Default: 0.0, 0.0, 0.0

Range: Real values

112 Adams/Solver

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

2smq + Kq = F , where is the frequency of the mode.

Default: 10.0

VM=id

translational velocity initial conditions (VX, VY, and VZ). VM

defaults to global orientation.

VMODE=b1,b2,...,bn

Specifies the initial values of the time rate of change of the modal

generalized coordinates.

Default: 0

Range: Real Values

VX=x,VY=y,VZ=z

System (BCS) along the x-axis (VX), y-axis (VY), and z-axis (VZ) of

the VM coordinate system.

Default: 0

Range: Real values

WM=id

Specifies the identifier of the marker that specifies the axes about

which angular velocity initial conditions (WX, WY, and WZ) are

defined. WM defaults to the BCS location and orientation. The origin

of the WM marker lies on the axis of rotation. This is most useful for

rotating systems.

WX=a,WY=b,WZ=c

Specifies the initial rotational velocities of the BCS along the x-axis

(WX), y-axis (WY), and z-axis (WZ) of the WM coordinate system.

Default: 0

Range: Real values

FLEX_BODY 113

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

modal frequency (see FXMODE and FXFREQ functions).

If your FLEX_BODY undergoes high-speed, rigid body rotations about a

stationary axis, significant solver performance can be realized by aligning the 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,

Flexible body CONTACT is only supported when using Adams/Solver (C++).

The FLEX_BODY does not support floating markers. Consequently, the reaction

Only use modes with nonzero eigenvalues. A mode with a zero eigenvalue (or

the BCS.

Due to the numeric methods involved, rigid body modes may have nonzero

these modes will cause simulation problems.

If there are less than six rigid body modes in the MNF it is strongly recommended

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

114 Adams/Solver

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

FLEX_BODY/1,

, CRATIO = IF(FXFREQ-100:0.01,0.1,if(FXFREQ-1000:0.1,1.0,1.0)\

,MATRICES = 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14

This example recreates the default modal damping scheme using nested IF function expressions.

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).

FLEX_BODY 115

C++ Statements

116 Adams/Solver

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.

FRICTION 117

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

mechanical interference in the assembly of the joint.

Default: 0.0

Range: FRICTION_FORCE_PRELOAD > 0

FRICTION_ARM=Rn

Defines the effective moment arm used to compute the axial component of

the friction torque in revolute, hooke, and universal joints.

Default: 1.0

Range: FRICTION_ARM > 0

INACTIVE=STATIC

solution.

Default: none

Range: Static

118 Adams/Solver

C++ Statements

INITIAL_OVERLAP=

Xs0

cylindrical joint. The joint's bending moment is divided by overlap to

compute the bending moment's contribution to frictional forces.

Default: 1000.0

Range: INITIAL_OVERLAP > 0

INPUTS=( {ALL,

NONE [[PRELOAD:

REACTION_FORCE:

BENDING_MOMENT:

TORSIONAL_MOMEN

T]]} )

Defines the input forces to the friction model. By default, all 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

FRICTION 119

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}

joint), Adams/Solver (C++) computes the overlap of the joint. As the joint

slides, the overlap can increase, decrease, or remain constant.

OVERLAP_DELTA is used to define any change in overlap.

INCREASE indicates that overlap increases as the

J marker; the slider moves to be within the joint.

DECREASE indicates that the overlap decreases with positive

CONSTANT indicates that the amount of overlap does not change

as the joint slides; all of the slider remains within the joint.

Default: CONSTANT

PIN_RADIUS=Rp

Defines the radius of the pin for a revolute, cylindrical, hooke, or universal

joint.

Default: 1.0

Range: PIN_RADIUS > 0

120 Adams/Solver

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

FRICTION statement acts. I_YOKE identifies the yoke to the I markers

rotational constraint. Likewise, J_YOKE identifies the yoke to the J

markers rotational constraint. These keywords are used with only hooke and

universal joints.

Extended Definition

Application of Friction in Joints

This section provides graphical descriptions and block diagrams of the joints and friction regimes

available in the FRICTION statement.

To learn about block diagrams and friction regimes, see:

Conventions in Block Diagrams

Friction Regime Determination (FRD)

Translational Joint

Revolute Joint

Cylindrical Joint

Universal/Hooke Joint

Spherical Joint

Conventions in Block Diagrams

Table 1 identifies symbols in the diagrams.

Table 2 describes the relationship between the INPUTS argument in the FRICTION statement

FRICTION 121

C++ Statements

Table 1

Symbol:

Description:

_________

Scalar quantity

Vector quantity

Summing junction:

c=a+b

Multiplication junction:

c=axb

MAG

ABS

FRD

Table 2

Block Diagrams

Switch:

INPUTS=:

Symbol:

Acceptable Values:

SW1

PRELOAD

Fprfrc or Tprfc

ON/OFF

SW2

REACTION

FORCE

F or F

ON/OFF

SW3

BENDING

MOMENT

Tr

ON/OFF

SW4

TORSIONAL

MOMENT

Tn

ON/OFF

applicable switches

ON/OFF,

respectively

122 Adams/Solver

C++ Statements

Dynamic friction

1.5 times the stiction transition velocity. The dynamic coefficient of

friction (md) is used in the computation of frictional forces.

and static friction

If the joint velocity magnitude is between 1 and 1.5 times the stiction

transition velocity, the joint is considered to be transitioning between

static and dynamic friction. A STEP function transitions the

coefficient of friction between the dynamic (md) and static (ms)

coefficients of friction.

Static friction

below the stiction transition velocity. The effective coefficient of

friction is computed using the joint creep, joint velocity, and static

coefficient of friction (ms).

The joint velocity determines the instantaneous friction regime for a joint. The figure below shows the

block diagram of the friction regimes available in Adams/Solver (C++).

FRICTION 123

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

The friction model includes dynamic- and stiction-friction effect. The static-friction coefficient

When computing the frictional force, Adams/Solver (C++) identifies only the joint-reaction

The transition from dynamic friction to stiction occurs when the relative angular velocity in the

joint falls below 0.1 units of length/unit time. A maximum deflection of 0.15 length units is

permitted when the joint is stiction.

See other Forces available.

124 Adams/Solver

C++ Statements

GCON

The GCON statement introduces a constraint equation that must be satisfied by Adams/Solver (C++)

during the simulation. This allows you to specify both holonomic and non-holonomic constraints.

Format

Arguments

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

GCON/111, I=2, FUNC=DX(2,3)

GCON/112, I=2, FUNC=DY(2,3)

GCON/113, I=2, FUNC=DZ(2,3)

The GCON statement allows you to define both holonomic and non-holonomic constraints. Holonomic

constraints only depend on position measures, like GCON/111 through GCON/113 above. A constraint

is non-holonomic if (a) its expression exp1 contains velocity measures, and (b) there is no expression exp2

that is the time integral of exp1. An example of a non-holonomic constraint is a roll without slip condition

GCON/34, FUNC=VX(2) - WZ(2)*DY(2)

The GCON statement introduces a constraint to Adams/Solver (C++) that is guaranteed to be handled

correctly as long as the FUNCTION is in Pfaffian form. In this context, note that any holonomic

expression is automatically in Pfaffian form. In the case of non-holonomic constraints, a Pfaffian

constraint requires that the FUNCTION is limited to expressions that are linear in velocity quantities. In

other words, if there are velocity quantities in the definition of the FUNCTION (as is the case in the

previous GCON), a partial derivative of the FUNCTION with respect to any velocity quantity present in

its definition should lead to an expression that does not depend on velocity quantities. The previous

GCON 125

C++ Statements

FUNC

FUNC

-------------------- = 1 , and -------------------- = DX 2 , which makes

WZ 2

VX 2

Another example of a Pfaffian non-holonomic constraint is the perpendicularity condition

GCON/25, FU=VX(2,3)*DX(2,1)+ VY(2,3)*DY(2,1)+ VZ(2,3)*DZ(2,1)

that indicates that the velocity V(2,3) is orthogonal to the distance vector between markers I=2 and J=1.

An example of a non-Pfaffian GCON is

GCON/25,FU=VX(2,3)*VX(2,3)*DX(2,1)+VY(2,3)*DY(2,1)+ VZ(2,3)*DZ(2,1)

-------------------------VX (2,3)

The FUNCTION expression exp can reference variables defined in the .adm file through the VARVAL

construct. It should be stressed again that correct handling of the GCON requires that the expression

defining the VARIABLE only depends on time, and position and velocity measures; in other words, the

Pfaffian character of the GCON is not undermined by the presence of the VARVAL.

Tip:

There is no dedicated function that returns the reaction force induced by a user constraint

on a marker. You can invoke an existing function such as FX(I[; J][;K]) for this purpose.

Note that FX(I[; J][;K]) reports the force that acts on the I marker as a result of both

constraint and external forces applied to this marker. To only obtain the contribution of the

the GCON, the markers that appear in FX(I[; J][;K]) should be exclusively used to define

the GCON, and no other elements such as applied forces, joints, or motions should refer

them.

126 Adams/Solver

C++ Statements

Caution:

Kinematic models are incompatible with velocity constraints. If a model is

constraints will be either redundant or conflicting. In either case, version 2003 of

Adams/Solver (C++) is incapable of analyzing the model as explained in the

Known Limitations. Consequently, a model that contains velocity constraints can

only be simulated using the dynamic solver.

For a position-level GCON, the FUNCTION must be at least three times

FUNCTION should be at least twice differentiable. This requirement ensures that

internally Adams/Solver (C++) can take the necessary derivatives to perform

certain types of analyses such as Acceleration/Force reconciliation, dynamic

analysis, and so on. Note that if the expression provided for GCON is not

continuously differentiable for the required number of times, the integrator will

either fail, or have a difficult time finding the numerical solution.

The ability of the Adams/Solver (C++) to handle function expressions to provide

the necessary derivatives required by the GCON does not extend to user

subroutines. Consequently, a VARIABLE can only be referenced in a GCON

provided it is defined using function expressions, rather than a VARSUB

subroutine.

Use the RESULTS/XRF statement in order to get the reaction force on marker I

reported in the results file. This is the only output format currently able to handle

GCON output.

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

GCON 127

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

GCON/1, I=6

,FUN=UVZ(10)*(WXYZ(6,7)%DXYZ(10,6)-WXYZ(8,9)%DXYZ(10,8))

The example also previews a 3D expression language extension wherein the UVZ(10) measure refers to

a Unit Vector (UV) in the direction of the z-axis of marker 10, and the % corresponds to the cross

product. Likewise, DXYZ(10,6) represents the three-dimensional distance vector between markers 10

and 6, while WXYZ(8,9) is the angular velocity of marker 8 with respect to marker 9. The 3D extensions

cannot yet be used with statements other than GCON and is not documented elsewhere.

Note that if the GEAR statement was changed to a GCON statement in a kinematically determinate

model, that is, a zero degree of freedom model, the model would gain one degree-of-freedom and become

a dynamic model. This is because one displacement constraint has been eliminated and replaced with a

velocity constraint.

Applications

The user-defined constraint is intended to be used to prescribe simple algebraic equations in position and

velocity measures that must be satisfied by Adams/Solver (C++). The statement is a new feature added

in Adams/Solver (C++). Due to its complexity and extremely general nature, it is highly probable that

not all possible applications have been anticipated and tested. Although models which exceed the

capabilities of the system will, in most cases, be detected, this can not be completely guaranteed. It is

advisable to use the GCON statement with a degree of caution. Some of the known limitations are listed

below.

128 Adams/Solver

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.

GEAR 129

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

Arguments

CV=id

Identifier of the marker that designates the point of contact and implicitly

determines the ratio of the two gears. The z-axis of the CV marker must point in

the direction of common velocity at the point of contact. The direction of common

velocity is tangent to both pitch circles and would be normal to the tooth surfaces

of the gears if the pressure angle was zero (Adams/Solver (C++) always assumes

a zero pressure angle). The CV marker must belong to the carrier part that also

hosts the J markers of the joints.

JOINTS=id1,id2 Specifies the two joints whose relative motion is to be related with a gear. Each of

these two joints must be translational, revolute, or cylindrical. Note that both J

markers of these joints belong to a carrier part that must also host the CV marker.

Extended Definition

The GEAR statement uses the location of a common velocity CV marker to determine the point of

contact of the two gear pitch circles. The direction of the z-axis of the common velocity marker indicates

the direction of the common velocity of points on the gear teeth in contact. This is also the direction in

which gear tooth forces act. Note that the CV marker has constant position and orientation in the carrier

body coordinate system (BCS). The CV marker through its z-axis only provides a direction, and there is

no need to be more specific than this. In this context, there is no need to indicate things such as how the

power flow occurs through the gear.

The reaction force reported back to you for a GEAR element is the reaction force measured on the J

marker of the joint that is specified first in the GEAR definition. It is important to keep in mind that the

130 Adams/Solver

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

Both joints associated with the gear resist the tooth force generated by the gear.

Therefore, the gear tooth reaction force appears in both joints. The reaction torques

due to the gear does not appear in the joints, but they can be calculated from the

gear tooth reaction force and the moment arms to the joints. The Results file

explicitly gives the gear tooth reaction force.

A GEAR statement does not simulate the backlash and the other intermittent

Examples

The figure below illustrates the use of a GEAR statement to define a bevel gear pair.

Bevel Gear Pair

GEAR/1, JOINTS=13,23, CV=303

This GEAR statement indicates that the gear pair relates the motions of Joints 13 and 23 and indicates

the common velocity marker. Below are the statements that work with this GEAR statement to

communicate the characteristics of the gear pair to Adams/Solver (C++).

MARKER/303, PART=3, QP=-2, -2, 0

JOINT/13, I=101, J=301, REVOLUTE

MARKER/101, PART=1, QP=-10, 0, 0

GEAR 131

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

132 Adams/Solver

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.

GFORCE 133

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

components in a user-defined subroutine GFOSUB.

FX=e

translational force. Adams/Solver (C++) applies this force parallel to

the x-axis of the RM marker.

FY=e

translational force. Adams/Solver (C++) applies this force parallel to

the y-axis of the RM marker.

FZ=e

translational force. Adams/Solver (C++) applies this force parallel to

the z-axis of the RM marker.

I=id

and torques. You must ensure that the I marker is a fixed marker and

on a different part than the JFLOAT marker. Because I is a fixed

marker, Adams/Solver (C++) always applies the force at a fixed point

on the part containing the I marker.

134 Adams/Solver

C++ Statements

JFLOAT=id

reaction forces and torques. You must ensure that the JFLOAT marker

is a floating marker and on a different part than the I marker.

Adams/Solver (C++) moves the JFLOAT marker to keep it

superimposed on the I marker, meaning that the point of application

of the reaction force may move with respect to its part. Adams/Solver

(C++) does not calculate reaction forces when the JFLOAT marker is

on the ground part.

RM=id

Specifies the marker and therefore the coordinate system in which the

force and torque components are specified. You must ensure that RM

is a fixed marker. RM can be the same as I and can be fixed on any

part in your system.

ROUTINE=libname::subname

GFOSUB.

Learn more about the ROUTINE Argument.

TX=e

rotational torque. Adams/Solver (C++) applies this torque parallel to

the x-axis of the RM marker in the sense of the right-hand rule (that

is, a positive torque causes a counterclockwise rotation).

TY=e

rotational torque. Adams/Solver (C++) applies this torque parallel to

the y-axis of the RM marker in the sense of the right-hand rule (that

is, a positive torque causes a counterclockwise rotation).

TZ=e

rotational torque. Adams/Solver (C++) applies this torque parallel to

the z-axis of the RM marker in the sense of the right-hand rule (that

is, a positive torque causes a counterclockwise rotation).

Extended Definition

A GFORCE statement defines a force element that consists of three mutually orthogonal translational

force 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.

GFORCE 135

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

T a = TXx rm + TYy rm + TZz rm

where:

Fa is the translational action applied to the I marker.

FX is the user-defined function for the x-component force magnitude.

FY is the user-defined function for the y-component force magnitude.

FZ is the user-defined function for the z-component force magnitude.

Ta is the rotational action applied to the I marker.

TX is the user-defined function for the x-component according to the right-hand rule.

TY is the user-defined function for the y-component according to the right-hand rule.

TZ is the user-defined function for the z-component according to the right-hand rule.

Reaction

Values:

Fr = -Fa

Tr = - Ta

136 Adams/Solver

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.

GFORCE 137

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.

138 Adams/Solver

C++ Statements

GRAPHICS

The GRAPHICS statement creates:

Two- or three-dimensional geometry for CONTACT. You always define the geometry with

Three-dimensional graphic data that represents the parts, constraints, or forces in a system.

Because there are two uses for geometry, one for contact and the second for the graphical display of

objects, we have divided the documentation into two separate sections:

Graphics for Contact

Graphics for Graphic Display of Objects

New types of graphics are available for representing a wide variety of geometries in contact.

Adams/Solver does not write these new geometric entities (point, plane, ellipsoid, and external) to the

graphics file, and therefore, they cannot be displayed in standalone Adams/Solver (C++). You can,

however, view them from Adams/View.

See the Supported Geometry Combinations for CONTACT

Graphics for Contact

Format

,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 139

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

SEG to specify the number of line segments to use to display the arc.

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-

CRM=id

Defines the reference marker with respect to which the curve data points are

specified.

CORNER=id

Defines a reference marker, which is at a corner of the box that is being created.

CURVE

Creates a curve graphic based on a CURVE statement. You define the curve data with

respect to a reference marker (CRM). The CONTACT and CVCV modeling entities

require that the curve be planar. It must be in the plane defined by the x- and y-axes

of the RM marker, and must contain the origin of the marker.

140 Adams/Solver

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

RADIUS to define the radius of the cylinder.

RANGLE to define the angular extent of the cylinder, with the arc always

LENGTH to define the height of the cylinder.

ELEMENT =

geometry_name

Specifies the name of a geometric entity in a file that FILE identifies. The file can

contain multiple geometries. You use ELEMENT to select a particular geometry

from the file even when it contains just one geometry. You will need additional

GRAPHICS statements if you want to read multiple geometries from the same file.

ELLIPSOID

Creates an ellipsoid. You use the following arguments to define the ellipsoid:

CM to specify the center marker (CM) of the ellipsoid.

XSCALE, YSCALE, and ZSCALE to specify the diameters along the x-, y-,

and z-axes of the CM marker. If the argument values are all equal (XSCALE

= YSCALE = ZSCALE), then Adams/Solver (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

ELEMENT to specify the name of a geometric entity in a file that FILE

identifies.

Adams/Solver (C++) uses the geometry package Parasolid 14.0 to understand

geometry. Parasolid input files have the extension .xmt_txt and .xmt_bin. Both are

supported, however, .xmt_bin files are not portable across platforms.

Parasolid can read in the geometry data and tell Adams/Solver (C++):

Whether or not two geometries are in contact.

Where the contact points are located on each geometry.

The outward normals at the calculated contact points.

GRAPHICS 141

C++ Statements

EXTRUSION

CRM to specify the id of the reference marker for the extrusion.

GID to specify the id of the closed curve or circle graphic to be extruded.

PID to specify the id of the curve, arc, or circle graphic to extrude along.

FILE=file_name Specifies the name of a file containing one or more geometric entities. Adams/Solver

(C++) can only read Parasolid files. Parasolids is an exact boundary representation

(b-rep) geometric modeler. This means that it represents solids (and other types of

geometry) by their boundaries. Other file formats (such as shell files) must be

converted to a boundary representation externally before the Adams/Solver (C++)

Parasolid geometry engine can use them.

FRUSTUM

Creates a frustum of a cone whose top and bottom are perpendicular to the cone

central axis. You use the following arguments to define the frustum:

CM to specify the center marker (CM) of the frustum. The z-axis of the CM

TOP and BOTTOM to define its top and bottom radii, respectively.

RANGLE to define the angular extent of the frustum, with the arc always

RADIUS to define the radius of the frustum cone.

LENGTH to specify the height of the frustum.

GID=id

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

142 Adams/Solver

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

Range: Radius > 0

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

CRM to specify the id of the marker that defines the center of revolution. The z-

GID to specify the id of the closed curve or circle graphic to be revolved.

RM=id

Identifies the marker that defines the reference coordinate system for a point, plane,

or external geometric entity. Adams/Solver (C++) defines the geometries in this

coordinate system.

TOP=r

Defines the radius at the top of a frustum. The top is perpendicular to the CM marker

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

MINOR_RADIUS to specify the smaller radius of the torus.

MAJOR_RADIUS to specify the larger radius of the torus.

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 143

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.

YMIN < YMAX

YSCALE > 0

ZSCALE > 0

GRAPHICS/0202, CYLINDER, CM=0201, RADIUS=2

, LENGTH=-2

This GRAPHICS statement creates a cylinder with its base at Marker 0201. Marker 0201 is located at the

center of the circular cross-section, which has a radius of two. The cylinder has a length of two along the

negative z-axis of Marker 0201.

GRAPHICS/1297, EXTERNAL, RM=7921,

, FILE = GenevaWheel.xmt_txt

, ELEMENT = Geneva

This GRAPHICS statement creates a three-dimensional solid element. The data for this solid element is

contained in a Parasolid file, GenevaWheel.xmt_txt. Within this file, which contains several geometric

entities, the solid with a tag, Geneva, is to be extracted. The solid definition is specified with respect to

Marker 7921.

The geometry associated with GenevaWheel.xmt_txt is shown next.

144 Adams/Solver

C++ Statements

GRAPHICS 145

C++ Statements

Format

OUTLINE = id1[,..., id2500]

,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

[ ] Optionally select the item

[[ ]] Optionally select an item combination

146 Adams/Solver

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

generates a curve graphic in each marker reference frame you specify with CRM.

CIRCLE

Creates a circle.

CM=id

Defines the identifier of the marker at the center of an arc, circle, cylinder, frustum,

or torus. If you are creating a circle or arc, orient the CM marker so that its z-axis is

normal to the plane of the circle or plane of the arc. Similarly, if you are defining a

cylinder or frustum, orient the CM marker so that its z-axis is normal to the bottom

plane of the cylinder or the frustum. For the torus the z-axis should be the axis of

the revolution.

COILS

Default: 0

Range: 99,999 > COILS > 0

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

GRAPHICS 147

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

CRM to specify the id of the reference marker for the extrusion.

GID to specify the id of the closed curve or circle graphic to be extruded.

PID to specify the id of the curve, arc, or circle graphic to extrude along.

FORCE

Creates an arrow whose direction is identical to the direction of a force and whose

length is proportional to the magnitude of a force.

FRUSTUM

Creates a frustum of a cone whose top and bottom are perpendicular to the cone

central axis.

148 Adams/Solver

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

S

OUTLINE=id1[,

...,id2500]

Creates visible and invisible line segments to connect at least two and not more than

2,500 markers. The values id 1[,...,id 2500] are marker identifiers. They define an

outline of line segments that Adams/Solver (C++) draws from one marker to the

next. A comma (,) between two marker identifiers causes Adams/Solver (C++) to

draw a line segment between two markers. A comma and minus sign (,-) between

two marker identifiers causes Adams/Solver (C++) to draw an invisible line from

the first marker to the second.

PID

RADIUS=r

Defines the radius of a circle, arc, or cylinder. There is no limit on the value of r.

GRAPHICS 149

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

CRM to specify the id of the marker that defines the center of revolution. The z-

GID to specify the id of the closed curve or circle graphic to be revolved.

RM=id

Defines the radius of a circle, arc, or cylinder. Adams/Solver (C++) measures the

distance from the CM marker to the RM marker to determine the radius.

SEG=i

Defines the number of straight line segments Adams/Solver uses to draw a curve,

circle, an arc, or the two circles at the ends of a cylinder or a frustum, or the arc of

the Torus.

Default: 20

Range: 99,999 > SEG >0

SIDES=i

Defines the number of straight line segments Adams/Solver draws between the two

parallel circles of a cylinder or a frustum, or the arc of the Torus.

Default: 20

Range: 99,999 > SIDES > 0

SPDP

SPDP, use I and J. To draw just the spring, use DA and COILS. To draw just the

damper at the I marker, use DB, LA, and LC. To draw just the damper at the J

marker, use DC, LB, and LD. To draw the entire spring-damper, use all of the

arguments for SPDP. DA, DB, DC, LA, LB, LC, LD, and COILS are all optional,

but Adams/Solver cannot draw anything unless you include (at a minimum) the

arguments for the spring or one of the dampers.

TOP=r

Defines the radius at the top of a frustum. The top is perpendicular to the CM marker

z-axis, and the center of the top is at the position on the CM marker z-axis that

LENGTH specifies. There is no limit on the value of r.

150 Adams/Solver

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

MINOR_RADIUS to specify the smaller radius of the torus.

MAJOR_RADIUS to specify the larger radius of the torus.

X=x,Y=y,Z=z

Locates the vertex of the box that is diagonally opposite from the corner defined by

CORNER. The values of X, Y, and Z must be specified with respect to the marker

coordinate system.

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.

GSE 151

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()

152 Adams/Solver

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

GSE 153

C++ Statements

Arguments

FUNCTION=USER(r1[,...,r30])

subroutines that define the constitutive equations of a GSE.

Two user subroutines are associated with a GSE.

GSE_DERIV is called to evaluate f() in Equation 1 (or F()

in Equation 3 if IMPLICIT).

GSE_OUTPUT is called to evaluate g() in Equation 2.

IC=id

initial conditions for the states in the system.

This is an optional argument. When you use the IC argument, an

ARRAY statement with this identifier must be in the dataset, it must

be of the IC type, and it must have the number of elements specified

in the argument NS.

When you do not specify an IC array for a GSE statement, all the

states are initialized to zero.

IMPLICIT

implicitly defined and takes the form given in Equation 3.

Note that the use of this attribute mandates that the GSE_XDOT

and GSEPAR_XDOT utility subroutines get called by the user to

obtain and supply required information.

In the default case, when the IMPLICIT attribute is not present, the

equation governing the states must be explicit in state-space form as

given by Equation 1 (and the user is permitted to use any of the

available utility subroutines).

INTERFACE=

lib1::gse_deriv,

lib2::gse_update,

lib3::gse_output,

lib4::gse_samp,

lib5::gse_set_ns,

lib6::gse_set_nd,

lib7::gse_set_implicit,

lib8::gse_set_static_hold,

lib9::gse_set_sample_offset

subroutines GSE_DERIV, GSE_UPDATE, GSE_OUTPUT,

GSE_SAMP, GSE_SET_NS, GSE_SET_ND,

GSE_SET_IMPLICIT, GSE_SET_STATIC_HOLD,

GSE_SET_SAMPLE_OFFSET respectively. The rules for the

INTERFACE argument are the same as for the ROUTINE argument.

ND=i

are updated by calling the function GSE_UPDATE at the sample

times. ND defaults to zero when not specified.

154 Adams/Solver

C++ Statements

NO=i

equations (algebraic variables) that are used in the definition of

Equation 2. If NO is greater than 0, you must also specify a Y array.

GSE outputs are evaluated by calling the user written subroutine

GSE_OUTPUT.

NS=i

of Equation 1 (or Equation 3 if IMPLICIT). The time derivatives of

the states of a GSE are evaluated by calling the user-written

subroutine GSE_DERIV. NS defaults to zero when not specified.

ROUTINE=lib1::gse1,

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

states is to start. All discrete states before SAMPLE_OFFSET are

defined to be at the initial condition specified. SAMPLE_OFFSET

defaults to zero when not specified.

SAMPLE_PERIOD=expression

a GSE. This tells Adams/Solver (C++) to control its step size so that

the discrete states of the GSE are updated at:

last_sample_time + sample_period

In cases where an expression for SAMPLE_PERIOD is difficult to

write, you can specify it in a user-written subroutine

GSE_SAMP(). Adams/Solver (C++) will call this function at

each sample time to find out the next sample period.

STATIC_HOLD

Indicates that the continuous GSE states are not permitted to change

during static and quasi-static simulations.

U=id

define the input variables for the GSE. The U argument is optional.

When it is not present in the GSE statement, there are no system

inputs. When you use the U argument an ARRAY with this

identifier must be in the dataset. The number of inputs to the GSE

statement is inferred from the number of VARIABLE statements in

the U array.

X=id

define the states for the GSE. When you specify it, an ARRAY

statement with this identifier must be in the dataset, it must be of the

X type, and it may not be used in any other LSE, GSE, or TFSISO

statement. If you specify SIZE on the ARRAY statement, it must

have the same value as the argument NS.

GSE 155

C++ Statements

Y=id

define the output variables for the GSE. The Y argument is optional,

but it must be provided if the argument NO is greater than zero.

When it is not present in the GSE statement (and NO=0), there are

no system outputs. When you use the Y argument, an ARRAY with

this identifier must be in the dataset. If you specify SIZE on the

ARRAY statement, it must have the same value as the argument

NO.

XD=id

access the discrete states for the GSE. An ARRAY statement with

this identifier must be in the dataset, it must be of the X type, and it

may not be used in any other LSE, GSE, or TFSISO statement. If

you specify SIZE on the ARRAY statement, it must have the same

value as the argument ND.

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.

156 Adams/Solver

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)

GSE 157

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)

158 Adams/Solver

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)

GSE 159

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

160 Adams/Solver

C++ Statements

States

The controller is a linear PID controller.

It has two continuous states (x1 and x2).

Transfer Functions

2e7

Y s - = --------------------------------------,

------------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.

GSE 161

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.

162 Adams/Solver

C++ Statements

SUBROUTINE GSE_DERIV(ID, TIME, PAR, NPAR, DFLAG, IFLAG, NS, XDOT)

C

C Inputs:

C

INTEGER ID, NPAR, NS

DOUBLE PRECISION PAR(*), TIME

LOGICAL IFLAG, DFLAG

C

C Outputs:

C DOUBLE PRECISION XDOT(*)

C

C Local Variables:

C

LOGICAL LEFLAG, PARFLG

INTEGER AX(1), AU(1), NSS, NU

DOUBLE PRECISION A(2,2), B(2,2), X(2), U(2)

SAVE A, B

DATA A /-1.0e3, 0.0, -2.0e4, -1.0e3/

DATA B /0.0, 1.0, -1.0, 0.0/

C

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

C

C Define the function fc():

C

GSE 163

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

164 Adams/Solver

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.

GSE 165

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:

use of a GSE_MAP_* utility subroutine implies a sparse representation for that

array.

2. Sparse and non-sparse representations can be mixed. As in this example, the E

matrix can be represented sparsely while the others are represented as full.

The only change to the previous example is in the GSE_DERIV user-supplied subroutine. In this case it

looks like:

SUBROUTINE GSE_DERIV(ID, TIME, PAR, NPAR, DFLAG, IFLAG, NS, F)

C

C Inputs:

C

INTEGER ID, NPAR, NS

DOUBLE PRECISION PAR(*), TIME

LOGICAL IFLAG, DFLAG

C

166 Adams/Solver

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

GSE 167

C++ Statements

CALL GSEPAR_XDOT (E, NStates )

CALL GSEPAR_U (B, NStates*NInputs)

ENDIF

RETURN

END

Again, the results are identical to the previous two examples to within roundoff error.

See other Generic systems modeling available.

168 Adams/Solver

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

during an initial conditions solution or for reconciling integrator acceleration

output.

Default: 1.0E-4

Range: AERROR > 0

ALIMIT=r

testing trial solutions for a set of consistent initial conditions that satisfy all

system constraints. The default units for ALIMIT are radians. To specify

ALIMIT in degrees, add a D after the value.

Default: 30D

Range: ALIMIT > 0

AMAXIT=i

finding accelerations during an initial conditions solution or for reconciling

integrator acceleration output.

Default: 25

Range: AMAXIT > 0

IC 169

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

the assembly process.

Default: 1.0E-10

Range: ERROR > 0

MAXIT=i

finding displacements during initial conditions, or when reconciling the position

of configuration during integration (interpolate on, or with the WSTIFF

integrator), and static analysis.

Default: 25

Range: MAXIT > 0

PATTERN=ci[:...: 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.

170 Adams/Solver

C++ Statements

TLIMIT=r

while testing trial solutions during a solution step.

Default: 1.0E10 (no limit)

Range: TLIMIT > 0

VERROR=r

during an initial conditions solution. Adams/Solver (C++) issues a warning if the

value of VERROR is exceeded. Adams/Solver (C++) issues an error if

PREFERENCES/SIMFAIL=STOPCF is chosen.

Default: 1.0E-4

Range: VERROR > 0

Extended Definition

The IC statement specifies error tolerances and other parameters for the analysis of initial conditions and

for reconciling integrator output. By default, WSTIFF reconciles integrator results to be consistent with

constraints; GSTIFF does not, unless you set INTERPOLATE=ON.

This statement is used only when requesting a dynamic, static equilibrium, or quasi-static equilibrium

analysis, and when one or more of the tolerances and other parameters for the initial conditions analysis

from the default values is to be changed.

Use the SIMULATE command to request a dynamic, static equilibrium, or quasi-static equilibrium

analysis. Before performing one of these analyses, Adams/Solver (C++) automatically does an initial

conditions analysis. An initial conditions analysis is not necessary when the system has zero degrees of

freedom because the kinematics of the system fully determine its configuration.

The initial conditions analysis ensures that the system satisfies all constraints within the system. If

necessary, Adams/Solver (C++) moves parts until both parts of each joint are in contact. This analysis

involves three separate phases. First, Adams/Solver (C++) makes the displacements between all parts and

joints in the system physically consistent. This requires the use of Newton-Raphson iteration to solve a

set of nonlinear algebraic equations. Once the displacements are consistent, Adams/Solver (C++) makes

the velocities physically consistent. Since this requires solving a set of linear equations, iteration is not

necessary. Finally, Adams/Solver (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.

IC 171

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.

172 Adams/Solver

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

INTEGRATOR 173

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

method.

Default Value: 0.36

Range: Defined in conjunction with GAMMA. Together

they must satisfy the stability condition.

2

+ 1---

2

-------------------4

MODIFIED

CORRECTOR=original - Specifies that the corrector

be used. This is the default. This implementation of the

corrector requires that at convergence, the error in all

solution variables be less than the corrector error tolerance.

CORRECTOR=modified - Specifies that a modified

requires that at convergence, the error in only those

variables for which integration error is being monitored be

less than the corrector error tolerance. This is a slightly

looser definition of convergence, and you should use proper

care when selecting this setting.

For additional information, see the Extended Definition. Note that

for HHT and Newmark, you cannot invoke this attribute, because

the original corrector is available for these two integrators.

Default: corrector=original

174 Adams/Solver

C++ Statements

ERROR=r

that the integrator must satisfy at each step. For BDF, HHT, and

Newmark integrators, Adams/Solver (C++) monitors the

integration errors in the displacement and state variables that the

other differential equations (DIFFs, LSEs, GSEs, and TFSISOs)

define. The SI2 formulation also monitors errors in velocity

variables. The larger the ERROR, the greater the error/step in your

solution.

Note that the value for ERROR is units-sensitive. For example, if a

system is modeled in mm-kg-s units, the units of length must be in

mm.

Assuming that all the translational states are larger than 1 mm,

setting ERROR=1E-3 implies that the integrator monitors all

changes of the order of 1 micron.

The error tolerance is compared against a local error measure that

depends on the difference between the current predicted and

corrected states, the past history of the states, and the current

integration order.

A slightly different integration ERROR definition is used for HHT

and Newmark integrators. For these two integrators, the default is

1E-5. For more information, see Remarks.

Defaults:

HHT and Newmark: 1E-5

All other integrators: 1E-3

GAMMA=r

associated with the Newmark method.

Default value: 0.7

Range: Defined in conjunction with BETA. Together they must

satisfy the stability condition

2

+ 1---

2

-------------------4

GSTIFF

integrating the differential equations of motion.

INTEGRATOR 175

C++ Statements

HHT

for integrating the equations of motion.

HINIT=r

Default: 1/20 of the output step

Range: 0 < HMIN < HINIT < HMAX

HMAX=r

take.

Default:

If INTERPOLATE = ON, the integration step size is limited

no limit is placed on the integration step size.

If INTERPOLATE = OFF, the maximum step size is

Range: 0 < HMIN < HINIT < HMAX

HMIN=r

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

176 Adams/Solver

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

CONTACT, you may see intermediate data at intervals

that do not coincide with your specified output interval.

This intermediate data (the data in-between the

interpolated outputs) actually corresponds to contact

incidences. You can turn off these extra contact data

points with an environment variable,

MDI_ADAMS_CONTACT_OUT.

information, see Extended Definition.

Default for GSTIFF/WSTIFF/HHT

KMAX=i

Indicates the maximum order that the integrator can use. The order

of integration refers to the order of the polynomials used in the

solution. The integrator controls the order of the integration and the

step size, and thus, controls the local integration error at each step

so that it is less than the error tolerance specified.

Note:

For problems involving discontinuities, such as contacts,

We do not recommend that you set the KMAX parameter

unless you are a very experienced user. Any modification

can adversely affect the integrators accuracy and

robustness.

KMAX is irrelevant (ignored) if the integrator selected is

order (order 2 and 1, respectively) and therefore, the order

does not change during simulation as is the case for the rest

of the integrators available in the solver.

Default: KMAX = 6

Range: 1 < KMAX < 6

INTEGRATOR 177

C++ Statements

MAXIT=i

Newton-Raphson iterations to converge to the solution of the

corrector nonlinear equations.

Typically, MAXIT should not be set larger than 10. This is because

round-off errors start becoming large when a large number of

iterations are taken. This can cause an error in the solution.

Default: 10

Range: MAXIT > 0

NEWMARK

equations of motion.

PATTERN=c1[:...:c10]

Jacobian matrix for Newton-Raphson. A value of true (T) indicates

that Adams/Solver (C++) is evaluating a new Jacobian matrix for

that iteration. A value of false (such as PATTERN=F) turns on the

adaptive Jacobian evaluation algorithm. The evaluation of the

integration Jacobian is then only done when needed.

The algorithm determines a corrector convergence speed and based

on this value, it extrapolates the configuration of the system after

MAXIT iterations. The Jacobian is updated if the algorithm

indicates that the convergence rate is too slow for the corrector to

meet the convergence criteria. Overall, this approach is expected to

result in fewer Jacobian evaluations, which in turn can lead to

shorter simulation times.

PATTERN accepts a sequence of at least one character string and

not more than 10 character strings. Each string must be either

TRUE or FALSE, which you can abbreviate with T or F. You must

separate the strings with colons.

Default: T:F:F:F:T:F:F:F:T:F (For GSTIFF and WSTIFF)

Default: F (HHT/Newmark)

Note:

A pattern setting of all false implies that Adams/Solver

corrector failure. For problems that are almost linear or are

linear, this setting can improve simulation speed

substantially.

178 Adams/Solver

C++ Statements

SI2

conjunction with the GSTIFF, WSTIFF, or HASTIFF integrators,

be used for integrating the equations of motion.

The SI2 formulation takes into account constraint derivatives when

solving for equations of motion. This process enables the GSTIFF

and WSTIFF integrators to monitor the integration error of velocity

variables, and, therefore, renders highly accurate simulations. A

positive side effect of the SI2 formulation is that the Jacobian

matrix remains stable at small step sizes, which in turn increases the

stability and robustness of the corrector at small step sizes.

The SI2 formulation is available only with GSTIFF, WSTIFF, and

HASTIFF.

For additional information, see the Extended Definition.

WSTIFF

integrating the equations of motion. WSTIFF uses the BDF method

that takes step sizes into account when calculating the coefficients

for any particular integration order.

Default: GSTIFF

HASTIFF

used for integrating the differential equations of motion.HASTIFF

uses the BDF method that takes step sizes into account when

calculating the coefficients for any particular integration order.

SI1

conjunction with the HASTIFF integrator, be used for formulating

and integrating differential equations of motion.

The SI1 formulation takes into account constraint derivatives when

solving for equations of motion. This process enables the HASTIFF

integrator to monitor the integration error of velocity variables, and

therefore renders highly accurate simulations. A positive side effect

of the SI1 formulation is that the Jacobian matrix remains stable at

small step sizes, which increases the stability and robustness of the

corrector at small step sizes.

The SI1 formulation is available only with HASTIFF, for which it

is the default.

INTEGRATOR 179

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

180 Adams/Solver

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)

INTEGRATOR 181

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

From Equation (20), which is a first-order BDF, you can get the relationship:

1

y = --- y

h

(23)

y ,y

1 F

+ --- -----h y

k

y = F (y

k

y ,y

(24)

y ,y

1 F

+ --------- -----h 0 y

k

y = F (y

(25)

k

y ,y

where:

0 is a scalar that is characteristic to an integration order. This scalar is constant for each

integration order.

The matrix on the left side of Equation (25) is the Jacobian matrix of F.

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

182 Adams/Solver

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:

HASTIFF SI1/SI2

CONSTANT_BDF SI1, SI2,

and I3

Original Corrector

Modified corrector

velocities of body equations,

flex modes, flex mode

velocities, applied forces, and

state variables from differential

equations (DIFFs); i.e., all

states except Lagrange

multipliers, Lagrange multiplier

velocities, and contact forces.

of body equations, flex modes,

and state variables from

differential equations (DIFFs).

Error control on displacements

and velocities of body equations,

flex modes, flex mode

velocities, and state variables

from differential equations

(DIFFs).

HHT Newmark

and state variables from differential equations (DIFFs).

INTEGRATOR 183

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

control HMAX so that the integrator runs at a

constant step size and runs consistently at a high

order (three or more).

You can encounter corrector failures at small step

function of the inverse of the step size and becomes

ill-conditioned at small steps.

References

Gear, C.W. (1971a). The Simultaneous Solution of Differential Algebraic Systems. IEEE

CT-18, No.1, 89-95.

Gear, C.W. (1971b). Numerical Initial Value Problems in Ordinary Differential Equations. New

Jersey: Prentice-Hall.

SI2

SI2 (Stabilized-Index Two) is an equation formulation technique that can be used for equations

describing mechanical systems. This formulation is available with both GSTIFF and WSTIFF

integrators.

To understand what the SI2 formulation does, you need to know what Differential Algebraic Equations

(DAE) are and understand the notions of Index of a DAE and stabilization of DAE. A brief summary is

given below. For more information, refer to:

Brenan, K.E., Campbell, S.I., and Petzold, L.R. (1996). Numerical Solution of Initial Value

ISBN: 0-89871-353-6 (pbk.)

184 Adams/Solver

C++ Statements

E y f y ,t = 0 y 0 = y 0

is defined to be a set of ODEs, because

(26)

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

Index of a DAE

The index of a DAE is defined as the number of time derivatives required to convert a set of DAEs to

ODEs.

INTEGRATOR 185

C++ Statements

Equations (28) and (29) can be converted to a set of ODE by first taking two time derivatives of the

kinematic position constraint equations in Eq. (29), to obtain the set of kinematic acceleration constraint

equations. These equations together with the equations of motion in Eq. (28) can be formally solved for

the accelerations and the Lagrange multipliers . By taking a third and last time derivative of the

Lagrange multipliers, you are left with a set of ODE in accelerations and the Lagrange multipliers.

Therefore, the Euler-Lagrange equations for mechanical systems are said to have an Index=3.

Solution of DAEs

Equations (28) and (29)are converted to first-order form, so that commercially available DAE integrators

can solve them. This is usually done by introducing a new variable, the velocity variable u, which is

defined as:

u q = 0

(30)

T

T

Mu + q A F = 0

(31)

u q = 0

(32)

= 0

(33)

These are the DAE (in first order form) for a mechanical system. Applying the BDF formula (like

Equation (23), one obtains the Jacobian of Equation (31):

M- A T F

-------U

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

186 Adams/Solver

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.

Benefits and Limitations

INTEGRATOR 187

C++ Statements

The benefits and limitations of the SI2 formulation are described in the following table:

Characteristics of the SI2 Formulation

Gives very accurate results, especially for

Usually allows an ERROR that is

regular GSTIFF to produce the same quality of

results.

Is very robust and stable at small step sizes.

Corrector failures that small step sizes cause

GSTIFF formulation.

Singular matrices due to small step sizes occur

Is typically 25% to 100% slower for

when run with the same error.

Requires that all velocity inputs be

define your MOTIONS so that they

are smooth and twice differentiable.

Non-smooth motions, which

theoretically cause infinite

accelerations, cause failures in the

SI2 formulation. The I3 formulations

can sometimes handle such models.

formulation.

Corrector failures are typically indicative of a

deficiency in the Adams/Solver software.

Tracks high frequency oscillations very

accurately.

WSTIFF

maximum order of six. The BDF coefficients it uses are a function of the integrator step size. Thus, when

the step size changes in this integrator, the BDF coefficients change. WSTIFF can change step size

without any loss of accuracy, which helps problems run more smoothly. The benefits and limitations of

WSTIFF are the same as those of GSTIFF and are listed in the Characteristics of GSTIFF Integrator table.

References

Van Bokhoven, W.M.G. (1975, February). Linear Implicit Differentiation Formulas of Variable

The HHT and Newmark Integrators

The HHT integrator is based on the -method proposed by H.M. Hilber, T.J.R. Hughes, and R.L. Taylor

[1]. The

-method is widely used in the structural dynamics community for the numerical integration

188 Adams/Solver

C++ Statements

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

h

q n + 1 = 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

(41)

2

+ 1---

2

-------------------4

(42)

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

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).

INTEGRATOR 189

C++ Statements

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

obtain the equivalent form:

(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

Using the notation:

(49)

190 Adams/Solver

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

expressed in terms of

(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

F 2

1

F

1

T

------- = ------------- M ------ h + ------------- Mq q q q ------ h

q

q

1+

q 1 +

e 1

T

-------- = q

e 2

2

------- = q h

q

e 2

-------- = 0

1

F

1

T

F- h 2

M = ------------- M ------ h + ------------- Mq q + q q ----1+

q

1+

q

one correction in the quasi-Newton algorithm is computed as the solution of the linear system:

(51)

INTEGRATOR 191

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

------- q 0

2

h

(53)

k + 1

k

k

q

= q + q

k + 1

(54)

k

k + 1

(41) and (42), respectively.

(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

Simcompanion Knowledge Base Article KB8016154

Remarks:

The following explains how the HHT and Newmark integrators are more efficient than the

1. The most time-consuming part of simulation is the computation of the Jacobian associated with

the nonlinear discretization system. The HHT integrator contains heuristics to reduce the number

of Jacobian evaluations as much as possible. Unlike the BDF integrator, where terms of the

integration Jacobian can become disproportionately large as a result of a scaling by the inverse of

the step-size, the HHT integrator employs a different approach, where certain values are

multiplied (never divided) by the step-size before populating the Jacobian. As long as the stepsize does not change dramatically, this approach better supports the recycling of the Jacobian over

several consecutive time-steps.

192 Adams/Solver

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:

2 = 1--------------2

1 = ------------------4

for and that satisfy equations (41) and (42). Typical values are = 0.7 and = 0.36.

The priority of the HHT and Newmark integrator is speed rather than accuracy. If accuracy is of

concern, the current integrators available in Adams historically are very accurate and serve the

purpose well.

The HHT and Newmark error control for DIFF, TFSISO, LSE, and GSE elements is

significantly more lax than the one carried out for these elements by the other integrators

available in Adams/Solver (C++) (such as GSTIFF, WSTIFF, and so on). This is related to the

nature of the HHT and Newmark integration formulas, which deal exclusively with second-order

differential equations. To have these formulas accommodate DIFF's for example, these are first

converted from first- into second-order differential equations. The consequence of this

transformation is that error control is now performed on the integrals of the DIFF states, rather

than on the actual states. As far as smoothness is concerned, it is well known that an integral of a

quantity is better behaved than the quantity itself. Consequently, the HHT and Newmark

integrators are typically more optimistic in selecting integration step-sizes. While these 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.

INTEGRATOR 193

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

spurious oscillations, while accurately

preserving low frequency oscillations.

Can control the cutoff frequency by

closer to -0.3, the lower the cutoff

threshold).

Stable at small value of the integration

step size.

Integrators

Because of the reduced order, the

with this I3 formulation are going to be

more spiky.

The numerical damping associated with

BDF integrators used by the GSTIFF

family.

If a BDF-based integrator manages to run

take step sizes significantly larger than

HHT. This is because HHT is a low-order

integrator and it needs to limit the step

size based on accuracy characteristics.

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 KB8016154.

N. M. Newmark. A method of computation for structural dynamics. Journal of the Engineering

194 Adams/Solver

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

2. Solving for y ', instead of y (y is discretized as a function of y')

3. The constrained are scale by 1/h1. (h=steps-size, is the BDF coefficient that multiplies y).

4. The formulation is Stabilized Index-1: an index-1 formulation is preferable because its more

stable numerically, hence it potentially allows for bigger and fewer steps to reach the end-time.

5. Stabilized Index-1 (SI1) and Stabilized Index-2 (SI2) are available for HASTIFF. SI1 is the

default for HASTIFF.

INTEGRATOR 195

C++ Statements

1. Ensures that the solution satisfies all both position and velocity constraints.

2. Does ensure that the velocities and accelerations calculated satisfy all first- and second-time

derivatives.

3. Monitors integration error only in system displacements and velocities.

4. Is as fast as GSTIFF SI-2.

5. The Jacobian matrix *cannot* become ill-conditioned even at small step sizes

See the theory of HASTIFF

Error in Handling Simulations

The following sections include descriptions and 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

input the SPLINE in a velocity-based MOTION.

For greater simulation control, use HMAX to control the maximum step size that the integrator

can take. HMAX enables the integrator to reach higher orders and maintain them consistently.

196 Adams/Solver

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

Use the SI2 formulation and see if the failures go away.

Use the new corrector by setting CORRECTOR = MODIFIED.

Here are some diagnostic techniques for identifying the cause of some failures:

Examine the EPRINT output from DEBUG to identify the modeling entities that are having the

If the modeling element is a force:

Make sure that the force law it obeys is smooth.

Examine the stiffness of the force entity. Reduce it if necessary to overcome the failures.

Examine the damping of the force entity. Damping is usually less than 5% of the stiffness.

If the modeling element causing the corrector failures is an equation of force/torque balance for a

PART, POINT_MASS, or FLEX_BODY, try to identify the entities that may be applying

anomalous forces on the body. Look at the accelerations of the body. A large acceleration in a

certain direction is always caused by a large force in that direction. Try to identify the modeling

element that is causing the large acceleration, examine how it is defined, and try to understand

why it is applying a large force.

If the modeling element is a CONTACT, review the stiffness, damping, and frictional properties

of the contact. Reducing stiffness and damping helps. Similarly, increasing stiction and dynamic

friction transition velocities can help the integrator.

If the modeling element is a FRICTION entity, increasing the stiction and dynamic friction

transition velocities usually helps. Evaluate the effect of reducing the friction coefficients and the

pre-load.

INTEGRATOR 197

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

Integration Restarts

An integration restart is when the integrator fails to take a new step successfully. Adams/Solver (C++)

calculates a new and consistent set of initial conditions at the point of failure and the solution progresses

with this new set of initial conditions. A restart occurs if the integrator encounters several consecutive

integration failures and/or corrector failures while attempting a new step. Integration restart is usually

indicative of discontinuous equations describing the system. To help avoid integration restart, you can:

Increase ERROR value. Integration restarts sometimes occur simply because the value specified

Identify modeling problems in your system. Typically, a single modeling element dominates an

integrator or corrector error. Identify that element and see why it may be causing problems.

Smoothen its definition if there is a function expression or user subroutine associated with it. For

more information on how to diagnose modeling problems, see Corrector Failures.

Singular Matrices and Symbolic Refactorization

A singular matrix condition occurs when the Jacobian matrix is not invertible. Recall that the corrector

needs to invert the Jacobian matrix during its iterations to solve a set of linearized algebraic equations.

(See Correction). A scalar analogy to a singular matrix is a 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.

198 Adams/Solver

C++ Statements

The system has reached a locked configuration, that is, it can no longer move without violating

A large force or moment has been suddenly turned on or off.

The integrator is forced to take an extremely small step because of a hidden discontinuity in an

intrinsic functions, such as SIGN, MOD, MIN, MAX, and so on, can create non-differentiable or

even discontinuous descriptions of modeling elements. Be very careful when using these aspects

of a programming language.

The Index-3 Jacobian matrix (see Equation 6) contains some terms that are inversely proportional to the

step size being taken. As the step size shrinks, these terms grow larger. In fact, they grow so large that

they eclipse all other entries in the matrix. Computers typically have difficulty dealing with matrices that

have entries spanning a large range (matrices with large condition numbers). The smaller numbers

consequently get lost in round-off error, and, therefore, cause singular or ill-conditioned matrices to

occur. The root cause for these problems is that the step size is very small. The solution is to understand

why the step size is so small, and modify the model accordingly. Discontinuities are prime causes for

problems related to small steps sizes. Eliminating the discontinuities causes the integrator to take larger

steps, and, therefore, avoid fatal singular matrix condition. Using the SI2 formulation can also help solve

this problem.

Choosing and Integration Error

The integration ERROR is a key parameter that you need to specify for a simulation. For calculating a

reasonable value for ERROR, we recommend that:

For I3 formulation with GSTIFF and WSTIFF:

For SI2 formulation with GSTIFF and WSTIFF:

where:

VEPS is the desired error per variable per integration step.

Nb is the number of rigid bodies in the model (excluding GROUND).

Np is the number of point masses in the system.

Nu is the number of user-defined differential equations in the system (DIFFs+LSEs+GSEs).

Nm is the total number of modal coordinates in the system:

K =10 (for smooth problems).

K =100 (for impact and friction problems).

For HHT and Newmark integrators, use the error that you would use for GSTIFF but typically

INTEGRATOR 199

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:

differential variables, and, therefore, yield acceptable accuracy in velocity, acceleration,

and force results. In some cases, however, the acceleration and force results may not be

acceptable, even when ERROR is set appropriately and the displacement results are

accurate. In these cases, use the HMAX argument to directly limit the size of the

integration steps.

Using the PATTERN argument to request more frequent evaluations of the Jacobian matrix

can improve convergence rates. This can also increase the computation time.

For kinematic (zero-DOF) systems, a kinematic analysis is usually faster and less

expensive than a dynamic analysis. To force the integration of a kinematic system, use

GSTIFF, WSTIFF, HHT, or Newmark.

200 Adams/Solver

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.

JOINT 201

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

202 Adams/Solver

C++ Statements

Arguments

CONVEL

Indicates the joint is a two-degree-of-freedom joint that allows rotation about two

axes: the zi and zj axes (see the figure below).

For the CONVEL joint, Adams/Solver (C++) superimposes the origins of the I and

J markers and constrains the rotation about the z-axis of the I marker to be equal

and opposite to the rotation about the z-axis of the J marker. When connecting two

shafts, the z-axes of the I and J markers should point down the shafts, away from

the center of the joint. Additionally, the angle between the x-axis of the I marker

and the y-axis of the J marker must be the same as the angle between the y-axis of

the I marker and the x-axis of the J marker. The easiest way to ensure the x and y

axes are properly aligned is to make the I and J x-axes parallel, or the I and J y-axes

parallel.

Convel Joint

CYLINDRICAL

Indicates that the joint is a two-degree-of-freedom joint that allows both relative

translational and relative rotational displacement of one part with respect to another

(see the figure below). I marker translation along the zj axis and rotation about the

zj axis are permitted.

For the CYLINDRICAL joint, Adams/Solver (C++) keeps the z-axis of the I

marker parallel to, and co-directed with, the z-axis of the J marker and confines the

origin of the I marker to the z-axis of the J marker so that the I and J markers have

a common z-axis. To determine translational motion, Adams/Solver (C++)

measures the movement of the origin of the I marker along the z-axis and with

respect to the J marker. To determine rotational motion, Adams/Solver (C++)

measures the rotation of the x-axis of the I marker about the common z-axis and

with respect to the x-axis of the J marker.

JOINT 203

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.

204 Adams/Solver

C++ Statements

Hooke Joint

I=id, J=id

Specifies the identifier of one fixed marker in each part the joint connects.

Adams/Solver (C++) connects one part at the I marker to the other at the J marker.

IC=r1,r2

revolute joint. The value r1 is the velocity of the I marker with respect to the J

marker as seen by the J marker. The value r2 is the displacement of the I marker

with respect to the J marker. Adams/Solver (C++) measures both the rotational

velocity and the rotation of the x-axis of the I marker about the common z-axis of

the I and J markers with respect to the x-axis of the J marker.

The IC argument imposes a constraint that is active only during initial conditions

analysis (not at the time of the initial configuration). Adams/Solver (C++) does not

impose initial conditions during subsequent analyses. If the IC argument imposes

initial conditions on the joint that are inconsistent with those on one of the bodies

the joint connects, the initial conditions on the joint have precedence over those on

the body.

For the initial conditions for a translational joint, velocity is in units of translational

displacement per unit of time and displacement is in units of length. For the initial

conditions for a revolute joint, velocity is in radians per unit of time and

displacement is in radians.

JOINT 205

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

joint. The value r1 is the translational velocity of the I marker with respect to the J

marker (in units of length per unit of time). The value r2 is the translation of the I

marker with respect to the J marker (in units of length). Adams/Solver (C++)

measures both translational velocity and translation at the origin of the I marker

along the common z-axis of I and J and with respect to the J marker.

The ICTRAN argument imposes a constraint that is active only during initial

conditions analysis (not at the time of the initial configuration). Adams/Solver

(C++) does not impose initial conditions during subsequent analyses.

If the ICTRAN argument imposes initial conditions on the joint that are

inconsistent with those specified on one of the bodies the joint connects, the initial

conditions on the joint have precedence over those on the body.

PD=r

Pitch diameter (PD) defines the pitch diameter of the pinion gear of a rack-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

revolution of its rotational displacement. A positive pitch creates a right-hand

thread, and a negative pitch creates a left-hand thread.

206 Adams/Solver

C++ Statements

PLANAR

Indicates that the joint is a three-degree-of-freedom joint that allows a plane of one

part to slide on a plane on a second part (see the figure below). The x and y axis of

the I and J markers of the joint define the planes on the two parts.

For the PLANAR joint, Adams/Solver (C++) constrains the z-axis of the I marker

so that it remains parallel to, and co-directed with, the z-axis of the J marker and

does not allow the linear displacement with respect to the J marker to have a z

component.

Planar Joint

JOINT 207

C++ Statements

RACKPIN

rotational displacement of the I marker to the translational displacement of the J

marker and measures both displacements with respect to the J marker. The I marker

is at the center of the pinion, and the J marker is in the rack. The figure below

illustrates a rack-and-pinion joint.

For the RACKPIN joint, the z-axis of the pinion must be parallel to and co-directed

with the x-axis of the rack. The separation between the two axes should be one-half

the pitch diameter of the pinion. The rack-and-pinion joint itself does not enforce

the position and orientation it requires, but the chain of both parts and joints that

connects markers I and J should enforce the position and orientation. A common

approach for enforcing the position and orientation is to support the rack with a

translational joint and to support the pinion with a revolute joint.

During simulation, the I marker displacement parallel to the J marker z-axis is a

function of the angle between the I marker x-axis and the J marker z-axis.

Adams/Solver (C++) measures a positive rotation according to the right-hand rule.

For every full rotation, the distance the I marker moves parallel to the z-axis of the

J marker is equal to the value of PD times p. The direction the I marker moves

depends on the sign of PD. For a positive PD and positive rotation, the I marker

moves in the negative direction along the z-axis of the J marker (and the J marker

moves in the positive direction).

Rack and Pinion Joint (PD > 0)

REVOLUTE

one part with respect to another about a common axis denoted as zi,j in the figure

below.

For the REVOLUTE joint, Adams/Solver (C++) superimposes the origins of the I

and J markers and keeps their z-axes parallel. Relative motion occurs about the

common z-axes.

208 Adams/Solver

C++ Statements

Revolute Joint

SCREW

translation of the I marker to its rotation (see the figure below).

For the SCREW joint, the z-axis of the I marker and the z-axis of the J marker must

always be parallel and co-directed. Although the SCREW joint does not enforce

this parallelism, the chain of parts and joints that connects the two markers should.

During simulation, the I marker displacement along the J marker z-axis is a

function of the relative angle of the x-axis of the I marker with respect to the x-axis

of the J marker. Adams/Solver (C++) measures a positive rotation according to the

right-hand rule. For every full rotation, the displacement of the I marker along the

z-axis of the J marker is equal to the value of PITCH. If is zero, the translational

displacement may be zero or any multiple of PITCH.

Screw Joint

JOINT 209

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

displacement of one part relative to another along the common z axes, zi and zj, as

shown in the figure below.

For the TRANSLATIONAL joint, Adams/Solver (C++) keeps the axes of the I and

the J markers parallel and co-directed, and keeps the origin of the I marker on the

z-axis of the J marker so that the two markers have a common z-axis. To determine

the translational displacement of the I marker with respect to the J marker,

Adams/Solver (C++) measures the origin of the I marker with respect to the origin

of the J marker along their common z-axis.

210 Adams/Solver

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

JOINT 211

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

212 Adams/Solver

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

In general, the GEAR statement is easier to use than the JOINT statement to define a rack-and-

pinion joint. In addition, the GEAR statement is more accurate. The current RACKPIN joint

applies a parasitic rotational force to the rack part. For some models the parasitic rotational force

could cause inaccurate results. Learn more about the GEAR statement.

The UNIVERSAL and HOOKE joints function identically. One may be more convenient to

define than the other, however, depending on the data you have available. If the joint is initially

straight, for instance, the HOOKE joint may be defined by two identical markers.

JOINT 213

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

singular position. The behavior of the CONVEL joint in the singular position is

unpredictable and may be incorrect.

The screw joint relates the rotational motion of the I marker to the translational

motion of the I marker and measures both motions with respect to the J marker.

However, the screw joint does not model the backlash or slope that may occur in

actual screw joints.

For both the rack-and-pinion and screw joints, Adams/Solver (C++) positions the I

and J markers at the nearest pitch-multiple position that satisfies the constraint.

Examples of pitch multiples of a joint with a pitch value of 2.5 include -5.0, -2.5,

0.0, 2.5, 5.0, and so on. Therefore, you should ensure that the part, marker, and

joint information that contributes to the initial positioning of the I marker with

respect to the J marker correctly describes the initial position of the I marker.

214 Adams/Solver

C++ Statements

If the initial conditions are inconsistent with other conditions in the system,

Adams/Solver (C++) varies the part initial positions through an iterative process to

correct the inconsistencies and then begins the simulation.

Use caution when using the initial conditions arguments (IC, ICTRAN, ICROT)

with a MOTION statement on the same joint. If the MOTION statement and the

initial conditions argument(s) specify motion for the same degree of freedom,

Adams/Solver (C++) uses the MOTION statement, ignores the initial conditions

argument, and issues a warning message.

If the initial rotational displacement of a revolute or cylindrical joint (as specified

statement) varies by 5 to 60 degrees from the initial configuration of the joint as

indicated by the input positions of the two parts constituting the joint,

Adams/Solver (C++) issues a warning message and continues execution. If the

variation is greater than 60 degrees, Adams/Solver (C++) issues an error message

and stops execution.

The initial conditions arguments impose constraints that are active only during

initial conditions analysis. Adams/Solver (C++) does not impose these initial

conditions during subsequent analyses.

For a kinematic analysis, the initial conditions are redundant. Do not use initial

condition arguments on the JOINT statements for systems with zero degrees of

freedom.

Adams/Solver (C++) checks whether axes that are constrained to be parallel or

If you input joint markers such that constrained axes are misaligned by more than

5 degrees, Adams/Solver (C++) issues a warning but continues the simulation. If

you misalign constrained axes by more than 60 degrees, Adams/Solver (C++)

issues an error and stops the simulation. You may input unconstrained axes in any

position. In a REVOLUTE joint, for example, Adams/Solver (C++) issues a

warning if the angle between the z-axes of the I and J markers is greater than 5

degrees, and an error if the angle is greater than 60 degrees. The x-axes, however,

may be at any angle.

JOINT 215

C++ Statements

however, which do not keep the I and J markers coincident require special

consideration when the J marker is on a flexible body. In general, joint reaction

forces only act on flexible bodies at the marker attachment. If the joint permits the

markers to move relative to each other, the offset between the markers is treated as

a rigid lever. That is, a reaction force-moment pair (Fi, Mi) at marker I will cause a

reaction force-moment pair (Fj, Mj) at marker J according to:

Fj = -Fi

Mj = - Mi - r x F i

Where r is the instantaneous position vector from marker J to marker I.

For example, an I marker on a part which is constrained by an cylindrical joint to

move on thez axis of a J marker on a flexible body should not be considered to be

sliding over the surface of the flexible body because the true effect of the joint is

that of a part sliding on a rigid rod which is welded to the flexible body at the

location of J.

Some JOINT elements purport to align marker axes so that they are parallel and

point in the same direction. In actuality, the JOINT only guarantees that the axes

are either parallel or 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

216 Adams/Solver

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.

JPRIM 217

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

of one part with respect to another (see the figure below).

For an atpoint primitive, Adams/Solver (C++) constrains all three translational

displacements so that the I and J markers are always superimposed.

Atpoint Primitive

I=id,J=id

Specifies the identifier of one fixed marker in each part the primitive connects.

Adams/Solver (C++) connects one part at the I marker to another at the J marker.

218 Adams/Solver

C++ Statements

INLINE

three rotational motions of one part with respect to another (see the figure

below).

For an inline primitive, Adams/Solver (C++) imposes two translational

constraints, which confine the translational motion of the I marker to the line

defined by the z-axis of the J marker.

Inline Primitive

INPLANE

rotational motion of one part with respect to another (see the figure below).

For an inplane primitive, Adams/Solver (C++) imposes one translational

constraint, which confines the translational motion of the I marker to the x-y

plane of the J marker.

Inplane Primitive

JPRIM 219

C++ Statements

ORIENTATION

motion of one part with respect to another (see the figure below).

For an orientation primitive, Adams/Solver (C++) imposes three rotational

constraints to keep the orientation of the I marker identical to the orientation of

the J marker.

Orientation Primitive

rotational motion of one part with respect to another (see the figure below).

For a parallel axes primitive, Adams/Solver (C++) imposes two rotational

constraints so that the z-axis of the I marker stays parallel to the z-axis of the J

marker. This primitive permits relative rotation about the common z-axis of I

and J and permits all relative displacements.

Parallel Axes Primitive

220 Adams/Solver

C++ Statements

rotational motion of one part with respect to another (see the figure below).

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

constraint on the I and the J markers so that their z-axes remain perpendicular.

This allows relative rotations about either z-axis, but does not allow any relative

rotation in the direction perpendicular to both z-axes.

Perpendicular Primitive

Extended Definition

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.

JPRIM 221

C++ Statements

The table below lists the number of translational or rotational constraints each joint primitive imposes.

Primitive Constraints

Primitive:

Removes No.

Translational DOF

Removes No. of

Rotational DOF

Removes Total

Number DOF

Atpoint

Inline

Inplane

222 Adams/Solver

C++ Statements

Primitive:

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:

Just as the JPRIM elements are the primitive forms of the JOINT elements, the

the system. The GCON element can easily represent some of the constraints that

users have looked for in the JPRIM element. For example, users have occasionally

requested a distance JPRIM, a constraint that keeps two markers offset by a

specified distance. To do this, use:

GCON/id, I=i, FUN=DM(i,j)-<offset>

which will keep two markers, i and j, apart by the distance <offset> and report, as a

result, the reaction force applied to i to accomplish this. Note that <offset> must be

non-negative. Furthermore, an <offset> of zero should not be considered

equivalent to an ATPOINT JPRIM that removes three DOFs, when the GCON

only removes one. The <offset> value does not need to be constant, nor is it

limited to functions of time.

JPRIM 223

C++ Statements

Caution:

The two markers that define a joint primitive must be in two different parts.

flexible body, thereby lifting restrictions in the Adams/Solver (FORTRAN). Joint

primitives, however, which do not keep the I and J markers coincident require

special consideration when the J marker is on a flexible body. In general, joint

reaction forces only act on flexible bodies at the marker attachment. If the joint

permits the markers to move relative to each other, the offset between the markers

is treated as a rigid lever. That is, a reaction force-moment pair (Fi, Mi) at marker I

will cause a reaction force-moment pair (Fj, Mj) at marker J according to:

Fj = -Fi

Mj = - Mi - r x F i

For example, an I marker on a part that is constrained by an inline joint primitive

to move on the z-axis of a J marker on a flexible body should not be considered to

be sliding over the surface of the flexible body because the true effect of the

primitive is that of a part sliding on a rigid rod that is welded to the flexible body at

the location of J.

Some JPRIM elements purport to align marker axes so that they are parallel and

point in the same direction. In actuality, the JPRIM only guarantees that the axes

are either parallel or anti-parallel (pointing in the opposite direction). Because the

parallel orientation is verified during model input, and because markers are very

unlikely to instantaneously to flip by 180 degrees, the likelihood of anti-parallel

axes has been very low. However, with the advent of curve-markers, which will

experience an orientation flip when passing through an inflection point, the

situation has become a possibility.

Although it would have been possible to forbid anti-parallel assembly of JPRIM

axes and enforce this at run-time, the overhead of such checking would not be

justifiable, given the low probability of the occurrence. Furthermore, because the

only recourse would be to stop the simulation, it is not clear that this check would

be very useful.

If the user requires that two axes (for example, the Z axes) remain parallel, as

opposed to anti-parallel, we recommend that the following GCON be added to the

model:

GCON/id, FUN=UVZ(i)*UVZ(j)-1

(replace UVZ with UVX or UVY for X and Y axes, respectively). The GCON will

be flagged as a redundant constraint, but since Adams/Solver (C++) stops as soon

as a redundant constraint becomes a conflicting constraint, a solution involving

anti-parallel axes will be prevented.

224 Adams/Solver

C++ Statements

Examples

This JPRIM statement indicates that Adams/Solver (C++) is to use an inline joint primitive to connect

one part to another. This connects the first part at Marker 0140 to the second at Marker 0240.

See other Constraints available.

KINEMATICS 225

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

iteration. The default units for ALIMIT are radians. To specify ALIMIT in degrees, add

a D after the value.

Default: 30D

Range: ALIMIT > 0

AMAXIT=i

finding accelerations at a point in time.

Default: 25

Range: AMAXIT > 0

226 Adams/Solver

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

finding the displacements at a point in time.

Default: 25

Range: MAXIT > 0

PATTERN=c1

[:...:c10]

Specifies as many as ten character strings that together establish the pattern for

evaluating the Jacobian matrix during the modified 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

iteration.

Default: 1.0E10 (no limit)

Range: TLIMIT > 0

KINEMATICS 227

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.

228 Adams/Solver

C++ Statements

LSE 229

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.

230 Adams/Solver

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

LSE 231

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.

232 Adams/Solver

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

LSE 233

C++ Statements

ARRAY/11 is the input array (u).

ARRAY/12 is the initial condition array. The input is defined by VARIABLE/11.

MATRIX/10 is the state matrix (A).

MATRIX/11 is the control matrix (B). This LSE has no output, so there is no output array (y),

Applications

The LSE statement may be most useful for adding feedback control systems to an Adams/Solver (C++)

model. The A, B, C and D matrices can be derived manually or imported directly from a control system

design program such as MATRIXx or MATLAB. Normally, the mechanical portion of the model includes

some kind of actuator that depends on one or more of the LSE statement outputs or states.

LSE statements can also be conveniently used in many cases to replace systems of coupled DIFF and

VARIABLE statements (for nonlinear equations, the GSE statement should be used). Examples of

possible dynamical system uses include unsteady aerodynamics and electrodynamics.

You can use the current values of LSE states and outputs in both function expressions and user-written

subroutines using the associated ARRAY facilities (see the ARYVAL function and SYSARY and SYSFNC

subroutines). That is, instead of Adams/Solver (C++) functions and FORTRAN callable subroutines

dedicated expressly to the LSE statement, the system states and outputs are accessed by offset referencing

through the appropriate ARRAY routines. This allows for consistent access to system states and outputs

for all three system modeling elements, the LSE, GSE, and TFSISO statements.

See other Generic systems modeling available.

234 Adams/Solver

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

solver based on the model being solved. This is the default setting.

CALAHAN Specifies that Adams/Solver (C++) is to use the CALAHAN solver exclusively. The

Calahan solver is usually fastest for most models.

UMF

Specifies that the Adams/Solver (C++) is to use the Unstructured Multi-Frontal sparse

matrix solver. This solver is faster for very large models.

Prior to Adams 2012, 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 235

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.

236 Adams/Solver

C++ Statements

MARKER

The MARKER statement defines three mutually perpendicular coordinate axes emanating from a

common origin. A marker can exist on a PART, POINT_MASS, FLEX_BODY, CURVE, SURFACE, or

GROUND.

Format

MARKER 237

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]

on a structure defined by the finite element nodes n1, n2,...,nn. If the NODE

argument is not specified for a marker on a FLEX_BODY, the marker behaves

as if it were attached to a rigid body; its position, velocity, and acceleration are

invariant to deformation, and all forces/torques defined on that marker only

project onto the rigid body degrees of freedom. The NODE argument can only

be applied to a marker on a FLEX_BODY.

Default: None

Range: IDs of nodes on the FLEX_BODY

238 Adams/Solver

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.

MARKER 239

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 to be oriented with the x-axis lying on XP, and ZP lying in the positive

x-z plane. This is useful for orienting markers that are used in BEAM statements.

Examples of using the ZP, XP and USEXP

240 Adams/Solver

C++ Statements

XP=x,y,z

By default, defines the coordinates of any point in the positive x-z plane of the

marker, but not on the z-axis of the marker. A point on the positive x-axis may

be the most convenient. When used with USEXP, XP defines the coordinates of

any point on the positive x-axis of the marker.

If the marker is associated with a FLEX_BODY or PART, the x-, y-, and 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.

MARKER 241

C++ Statements

translational velocity of the maker along the x-axis (VX), y-axis (VY), and zaxis (VZ) of the RM coordinate system. Adams/Solver (C++) will project the

initial velocity onto the CURVE or SURFACE. Therefore, any contribution of

the specified initial velocity vector which is not along the CURVE or SURFACE

will be discarded.

V1=r1, V2=r2

For a marker associated with a SURFACE, V1=r1, and V2=r2 define the initial

velocity of the marker on the surface along the two-dimensional surface

parameterization.

Extended Definition

The MARKER statement defines a geometric point in space and a set of three mutually perpendicular

coordinate axes emanating from that point. MARKERs are the basic building blocks for specifying

applied forces, constraints, or simply points of interest in the model.

MARKERs are always associated with a specific element in the model (for example, PART,

FLEX_BODY, CURVE, or SURFACE) and could be fixed on the element or move relative to it.

Markers on Parts

A marker on a PART can either be fixed or it may float relative to the PART. A MARKER statement

identifies the location and orientation of a marker with respect to the body coordinate system (BCS).(For

more information on BCS, see Coordinate Systems and Local Versus Global Geometric Data.) Requests

for information pertaining to fixed and floating markers are easy to write (see REQUEST). However, only

information on fixed markers can be used in function arguments that affect how the model behaves. You

may reference the position of a floating marker in a REQUEST statement or a REQSUB evaluation

subroutine, for example, but not in an SFORCE statement or a SFOSUB evaluation subroutine.

Markers on Flexible Bodies

Adams/Solver (C++) distinguishes between positioning a marker on a flexible body and attaching a

marker to a flexible body. Positioning the marker using arguments QP, REULER, ZP, and XP defines the

initial position and orientation relative to the BCS of the flexible body. Attaching defines the interaction

between the marker and the flexible body; namely, how forces acting on the 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)

242 Adams/Solver

C++ Statements

Ao = Transformation matrix from BCS to GCS

s = Initial position of marker relative to BCS, resolved in the BCS

ui = Displacement vector of node i relative to BCS, resolved in the BCS

rc = Initial position of marker relative to the centroid of the attachment nodes, resolved in the BCS

Ai = Small rotation transformation from frame fixed to node i during deformation back to the BCS

ri = Initial position of node i relative to BCS, resolved in the BCS

I = 3 x 3 identity matrix

wi = Weighting parameter

1

------------------ri rc

w i = ---------------------------n

1

-----------------rj rc

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.

MARKER 243

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

Important: Warning messages for a node has zero mode shapes

The warning messages is printed from C++ solver when a node has zero mode shapes is

attached to some connectors in MD/MSC Adams 2011 and later. This message is inviting

user's attention to find out a potential problem in the model because the flexibility of the

node is infinite, the other words the node behave the same as the marker on rigid part, and

it may not be user's intention. The example of the message for zero rotational mode shapes

is shown below.

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.

244 Adams/Solver

C++ Statements

The z-axis of the surface marker will point along the surface v (beta) tangent vector at the marker

location.

The y-axis of the surface marker will point along the surface normal vector at the marker

location.

Tip:

Select one of the following three methods to define the position and orientation of the

marker.

Note:

In general, locate and orient a marker with respect to its parent BCS. If the

marker is on the ground part or is on a part whose BCS is superimposed on the

ground coordinate system (GCS) at time zero, the marker can be positioned and

oriented with respect to the ground coordinate system (GCS).

To select the x-point-z-point method using the ZP point to define a point on the z-

axis, add QP, ZP, and/or XP. It is often unnecessary to define XP.

To select the x-point-z-point method using the XP point to define a point on the z-

axis, add QP, ZP, and/or ZP as well as USEXP. It is often unnecessary to define ZP

MARKER 245

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,

246 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/QP=1.1, 1.2, 1.3, ZP=2.1, 2.2, 2.3, XP=3.1, 3.2, 3.3

When both ZP and XP are given (no USEXP option used) the solver will compute the orientation as

shown below.

MARKER 247

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

MARKER/QP=1.1, 1.2, 1.3, ZP=2.1, 2.2, 2.3, XP=3.1, 3.2, 3.3, USEXP

In this case, the solver computes the orientation as shown below.

248 Adams/Solver

C++ Statements

z

x

y

z

=

=

=

=

ZP QP

XP QP

zx

xy

Case 3. ZP given

MARKER/QP=1.1, 1.2, 1.3, ZP=2.1, 2.2, 2.3

In this case, the solver will compute a point XP as shown in figure below.

MARKER 249

C++ Statements

z = ZP QP = a x a y a z

XP = a y a x 0

Case 4. XP and USEXP given.

MARKER/QP=1.1, 1.2, 1.3, XP=3.1, 3.2, 3.3, USEXP

In this case, the solver will compute a point ZP as shown in figure below.

250 Adams/Solver

C++ Statements

x = XP QP = a x a y a z

ZP = 0 a z a y

Applications

Designate the center of mass of a part (see the PART statement).

Indicate the position and orientation of the coordinate system with respect to which you specify

Define the position and orientation of a joint or joint-primitive connection point/direction. This

requires two markers, one in each part that the joint or joint primitive connects (see the JOINT

and JPRIM statements).

Denote force direction and action and reaction points. For more information, see the following

statements:

BUSHING

FIELD

SFORCE

SPRINGDAMPER

Specify points for requests and graphics output (see the REQUEST and GRAPHICS statements)

MARKER 251

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.

Define the position and orientation of a joint or joint primitive connection point/direction. This

requires two markers, one in each part that the joint or joint primitive connects (see the JOINT

and JPRIM statements).

Denote force direction and action and reaction points. For more information, see the following

statements:

BUSHING

FIELD

SFORCE

SPRINGDAMPER

Provide coordinate system(s) other than ground coordinate system(s) for resolving the

components of vector quantities such as velocities, accelerations, and forces (see the REQUEST

statement).

Use markers on curves to:

Define the position and orientation of a joint or joint primitive connection point/direction. This

requires two markers, one in each part that the joint or joint primitive connects.

Use markers on surfaces to:

Define the position and orientation of a joint or joint primitive connection point/direction. This

requires two markers, one in each part that the joint or joint primitive connects.

See other Geometry statement available.

252 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 253

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

Adams/Solver (C++) code.

If the first record begins with the characters MATRIXx, then the file is

If the first record begins with the characters MATSAVE, then the file is

package.

Note that the three specifications for the format of the data file are case sensitive.

Capital letters and a lower case x must be used to make the MATRIXx selection.

No other kinds of files are currently supported. However, the ADAMSMAT and

ADAMSMAT2 options are fairly general since the format for reading in the data is

specified within the file. See the example, Multiple Matrix Input Using the FILE

Option, for details on the structure of an ADAMSMAT file.

Because the FILE argument and value can be at most eighty characters long, the file

path and name are limited from seventy-five characters (if you do not abbreviate

FILE=) to seventy-seven characters (if you abbreviate FILE= to FI=).

Range: All printable characters except '!', ';', ',', and '&'

FULL={RORDE

R,CORDER}

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

254 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 255

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

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.

256 Adams/Solver

C++ Statements

Table 3

Item:

Number of

records:

Argument or

symbol:

Contents:

FORTRAN

format:

ADAMSMAT

I5

(n+3)/4

NAME

4 (8A,10X)

{FULL or SPARSE}

{CORDER or RORDER if FULL

or blank if SPARSE}

Number of rows, columns, and

total number of entries

FORTRAN format specification

NAME

A8,

A8,

A8,

or

The indices and nonzero entries in

the matrix if SPARSE

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

Number of

records:

Argument or

symbol:

Contents:

FORTRAN

format:

ADAMSMAT2

I5

(n+3)/4

NAME

4 (8A,10X)

{FULL or SPARSE}

{CORDER or RORDER if FULL

or blank if SPARSE}

Number of rows, columns, and

total number of entries

FORTRAN format specification

NAME

A8,

A8,

A8,

M,N,

number

format

5

Note:

variable

or

The indices and nonzero entries in

the matrix if SPARSE

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 257

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):

, VALUES=1.364,0.000,0.000,0.000,-3.546,4.008,0.000,0.799

Version 2, FULL Format (column order):

, VALUES= 1.364,0.000,-3.546,0.000,0.000,0.000,4.008,0.799

Version 3, SPARSE Format:

, I=1,3,3,4,J=1,1,2,2,

, VALUES=1.364,-3.546,4.008,0.799

258 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 =

0.00 4.52 6.02

3.44 6.02 2.11

01

1.698045 10

2.307452 10

01

STL =

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 259

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.

260 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

define an MFORCE only if you have defined a MODLOAD matrix for

the associated FLEX_BODY.

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:

define an MFORCE only if you have defined a MODLOAD matrix for

the associated FLEX_BODY.

MFORCE 261

C++ Statements

ROUTINE=libna

me::subname

Specifies an alternative library and name for the user subroutine MFOSUB.

Learn more about the ROUTINE Argument.

FORCE=USER(r

1{r2,...,r30})

MFOSUB to directly compute the modal force on the FLEX_BODY. Each

component of the modal force can depend on time or the state of the system.

FUNCTION=US

ER(r1{r2,...,r30})

MFOSUB to directly compute the modal load case and scale function whose

product is the modal force applied to the FLEX_BODY. The scale function can

depend on time or the state of the system. The load case can only be a function of

time.

Extended Definition

The MFORCE statement allows you to apply any distributed load vector F to a FLEX_BODY. Such a

load vector is typically generated with a finite element program. Examples of distributed load cases

include thermal expansion or pressure loads. To help you understand how Adams handles distributed

loads, the following section discusses the equations of motion of a flexible body, starting with the

physical coordinate form that the finite element program uses.

Equations

M x + K x = F

where M and K are the finite element mass and stiffness matrices for the flexible component; x is

the nodal coordinate vector; and F is the distributed load vector. This equation can be transformed into

the modal coordinates, q:

T

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.

262 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

fT(q,t) = e(q,t) fi

is then applied to the FLEX_BODY, where CASE_INDEX = i references load case fi in the MNF, and

SCALE = e defines the state-dependent scalar function e(q,t).

Definition 2: Defining MFOSUB Subroutine

If the scalar function expression is too complicated to define using the Adams/Solver (C++) function

expression language, you can use the MFOSUB user-written subroutine interface and specify the

MFORCE as follows:

MFORCE/id, FLEX_BODY = id [,JFLOAT=id], FUNCTION = USER(r1,[r2,r30])

fT(q,t) = e(q,t) fi

However, here the load case index is returned from the MFOSUB as well as the state dependent scalar

function e(q,t). The dependency on q arises from calls to the SYSFNC and SYSARY utilities in the 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 263

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

fT(q,t) = f(q,t)

where each component of f(q,t) depends independently on time and system state can only be achieved

through the MFOSUB interface and the following MFORCE specification

MFORCE/id, FLEX_BODY = id [,JFLOAT=id], FORCE = USER(r1,[r2,r30])

Note that the keyword FORCE is used instead of FUNCTION. This instructs Adams/Solver (C++) to

ignore the scale function returned from the user-written subroutine and apply the load case defined in the

subroutine directly to the FLEX_BODY. Furthermore, calls to SYSFNC and SYSARY establish state

dependencies in the individual modal force components, not just the scalar function. An MFORCE

defined in this way is more general, but less efficient than the previous forms. Therefore, it should only

be used if your application does not allow for the previous definitions.

Definition 6: Combining Modal Load Cases using multiple scale factors

This is expanded definition of Definition 3 to allow you to indicate multiple scale factors. The force

description is same as Definition 3 as follows:

fT(q,t) = e(q,t) [g1(t) f1 + g2(t) f2 + + gn(t) fn]

The values of e(q,t) and g1(t), g2(t), gn(t) are specified in MFOSUB instead of e(q,t) and the term of

[] in Definition 3. The MFORCE specification is also same as Definition 3, namely:

MFORCE/id, FLEX_BODY = id [,JFLOAT=id], FUNCTION = USER(r1,[r2,r30])

Note that the modeling is quite same as Definition 3 but this is useful for correct MFORCE visualization

in Adams/PostProcessor.

264 Adams/Solver

C++ Statements

Resultant Forces

For distributed loads that have an external resultant, portions of the load will project on the rigid body

modes of the flexible body. However, the rigid body modes must be disabled because Adams/Solver

(C++) will replace them with the non-linear, large motion, generalized coordinates: X, Y, Z,

, , and

. In this case, the load on the rigid body modes are transferred to the large motion generalized

coordinates.

Part of this transfer occurs during the MNF2MTX translation of the flexible body's MNF, and,

consequently, the MODLOAD matrix has a dimension that equals 6 plus the number of modes. The first

6 entries in each column correspond to the external force and torque acting on the flexible body for this

modal load case, expressed relative to the body coordinate system (BCS). When the modal load case is

an internal force (as would be expected in the case of a thermal load), this force and torque will be zero.

You should also be aware of the way modal truncation affects the application of modal loads. When you

define a distributed load, it will be projected on the available modes. It is important to understand that

the available modes form an efficient but incomplete basis for the flexible component. Therefore, it is

inevitable that some portion of the load will be orthogonal to the modal basis. This portion of the load

will be irretrievably lost. Furthermore, during mode selection within Adams, you should realize that a

mode whose removal is being considered may also have a significant modal load associated with it. In

this case, the mode should not be disabled.

Examples

MFORCE/1, FLEX_BODY = 1, CASE_INDEX = 1

, SCALE = SIN(TIME)*DX(1,4)

Using the first load case defined for FLEX_BODY/1, this example defines a modal load on

FLEX_BODY/1 by scaling the values of the load case by the function expression SIN(TIME)*DX(1,4).

The reaction force that corresponds to this load is ignored.

MFORCE/2, FLEX_BODY = 2, JFLOAT = 4

, FUNCTION = USER(10,1e5,23.)

This example defines a modal load whose reaction resultant force acts on the parent part of floating

marker 2. The magnitude and shape of the load is provided by the MFOSUB user-written subroutine,

based on the user parameters 10,1e5,23. Furthermore, Adams/Solver (C++) builds the applied modal

force by multiplying the scale and load case returned from the user-written subroutine, and only the scale

function is assumed to depend on state.

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 265

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

266 Adams/Solver

C++ Statements

Arguments

ACCELERATION

acceleration as a function of time. The acceleration expression is

integrated twice to calculate the corresponding displacement.

Default: DISPLACEMENT

B1

Specifies the first angle of the Body 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

sequence as a function of time. The 123 rotation sequence of the

I marker coordinate system is defined with respect to the J

marker coordinate system.

Range: None

Default: None

B3

Specifies the third angle of the Body 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

displacement. This is the default.

e

FUNCTION =

The motion must be a function of time only and not a function of

USER r1 ,... ,r30

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 (C++) to

pass to MOTSUB (see the MOTSUB subroutine). If the

FUNCTION argument is used, it must either be the last argument

in the MOTION statement or be followed by a backslash (\).

MOTION 267

C++ Statements

ICDISP

is defined in terms of velocity or acceleration.

Default: 0

ICVEL

defined in terms of acceleration.

Default: 0

I=id, J=id

is being controlled.

Range: Any valid non-floating marker not belonging to a flexible

body

Default: None

JOINT=id

assigned. The joint must be either translational, revolute, or

cylindrical. If you specify a translational joint, Adams/Solver

(C++) assumes you are assigning translational motion and does

not allow you to assign rotational motion. Similarly, if you

specify a revolute joint, Adams/Solver (C++) assumes you are

assigning rotational motion and does not allow you to assign

translational motion. However, if a cylindrical joint is specified,

either translational or rotational motion can be specified with

TRANSLATION or ROTATION, respectively.

ROTATION

when rotational motion is being applied to a cylindrical joint.

ROUTINE=libname::subname

MOTSUB.

TRANSLATION

only when translational motion is being applied to a cylindrical

joint.

VELOCITY

velocity.

Default: DISPLACEMENT

of the displacement of the I marker with respect to the J marker

evaluated in the J marker coordinate system.

Range: None

Default: None

268 Adams/Solver

C++ Statements

of the displacement of the I marker with respect to the J marker

evaluated in the J marker coordinate system.

Range: None

Default: None

of the displacement of the I marker with respect to the J marker

evaluated in the J marker coordinate system.

Range: None

Default: None

Extended Definition

You can apply MOTIONs to either joints or between a pair of markers. When a motion is applied on a

joint, a joint degree of freedom is controlled as a function of time. When a motion is applied between a

pair of markers, movement along a user-specified direction is controlled as a function of time. You can

define the value of the degree-of-freedom being controlled, either as a function expression or user-written

subroutine.

Motions on Joints

Motions can be specified to act on joints. A translational motion is specified at either a translational or

cylindrical joint. A rotational motion is specified at either a revolute or cylindrical joint. The type of the

joint together with the markers of the joint specify the degree-of-freedom being controlled.

For a translational motion, Adams/Solver (C++) moves the I marker along the z-axis of the J marker. The

J marker origin represents zero displacement while the z-axis of the J marker defines the positive

direction.

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

DY(I,J,J) is the displacement of the origin of the I marker with respect to the origin of the J

MOTION 269

C++ Statements

DZ(I,J,J) is the displacement of the origin of the I marker with respect to the origin of the J

B1(I,J) is the first angle of a Body 1-2-3 Euler rotation sequence that measures the orientation of

B2(I,J) is the second angle of a Body 1-2-3 Euler rotation sequence that measures the orientation

B3(I,J) is the third angle of a Body 1-2-3 Euler rotation sequence that measures the orientation of

For the velocity and acceleration motions, Adams/Solver (C++) numerically integrates the velocity or

acceleration signal to obtains corresponding displacement signal of the motion.

Tip:

If you want to determine the translational or rotational force a motion applies, use

A MOTION statement can define zero motion with respect to time.

Although the extended capabilities of Adams/Solver (C++) in the area of

constraint equations would not require that the FUNCTION expression be limited

to an explicit function of time, it was rejected on the grounds of backward

compatibility with Adams/Solver (FORTRAN). Users interested driving a motion

generator with a function of displacements, velocities, or variables are encouraged

to study the general constraint element (GCON).

Important: The FORTRAN Solver does not consider any change to MOTION function expression to

be a topology change. This is because the FORTRAN Solver assumes that MOTION

function expression will always be an explicit function of time.

function of time by analyzing it. If the C++ Solver determines that a MOTION function

expression that IS an explicit function of time has changed to a new expression that is also

an explicit function of time, then there is no change in model topology (which is equivalent

to the FORTRAN Solver).

However, if a MOTION function expression changes to something that IS NOT an explicit

function of time, then the C++ Solver concludes that a topology change has occurred and

an analysis separator will be added to the output files. This is different behavior from the

FORTRAN Solver because the FORTRAN Solver will never add separators to the output

files when a MOTION expression changes.

270 Adams/Solver

C++ Statements

Caution:

The motion must be a function of only time, not displacements, forces, or any

difficulty finding a solution.

Motion function expressions are required to have first and second time

second time derivatives can cause severe numerical problems.

Be careful when specifying multi-axial rotational motions between a pair of

markers. B1, B2, and B3 specify a Body 1-2-3 rotation sequence and are Euler

angles. This implies that the first rotation occurs about the x-axis of the J

marker, the second rotation about an intermediate y-axis and the last about the

z-axis of the I marker. For example, if you are measuring rotations between

two markers in the sequence z, y, x, this corresponds to a Body 3 -2 1 rotation

sequence, you will have to convert this to a Body 1-2-3 rotation sequence

before specifying it in a MOTION.

When using any of the following motion types: B1, B2, or B3, avoid situations

where the B2 angle is at +/- 90degrees or +/- 270 degrees. At these angles the

Body 1-2-3 angles are undefined. If this situation occurs, Adams/Solver (C++)

issues a warning and stops the execution. There is no solution for this

condition.

Do not use an initial conditions argument, such as, IC, ICTRAN, or ICROT,

on a JOINT statement with a motion that acts in the same direction on the

joint. If both are used, Adams/Solver (C++) uses the MOTION statement and

ignores the initial conditions argument(s) specifying motion in the same

direction(s) specified by the JOINT statement.

If the initial rotational displacement of a revolute or cylindrical joint (as

MOTION statement) varies by anywhere from 5 to 60 degrees from the initial

configuration of the joint as indicated by the input positions of the two

markers constituting the joint, Adams/Solver (C++) issues a warning message

and continues execution. If the variation is greater than 60 degrees,

Adams/Solver (C++) issues an error message and stops execution.

MOTION 271

C++ Statements

velocities for the first two or three internal integration steps. Adams/Solver

(C++) automatically corrects for this, so that values returned at the first output

step are accurate. However, a sensor that depends on the accelerations or

reaction forces due to this motion may trip unexpectedly prior to the first

output step, even though the solution appears correct when the sensor is

removed. If this occurs, you should modify the displacement function in the

MOTION statement so that the initial accelerations are zero.

Adams/Solver (FORTRAN) is incapable of performing a kinematic analysis

ACCELERATION arguments. Not so for Adams/Solver (C++), which uses a

more advanced quadrature scheme to integrate the MOTION function. This is

a potential source of differences in the results produced by the two solvers.

A function expression for a MOTION statement can not use BISTOP and/or

IMPACT functions.

Examples

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)

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-

272 Adams/Solver

C++ Statements

The rotation about the z-axis of Marker 11 (third angle of the Body 1-2-3 rotation sequence

JOINT/301, SPHERICAL, I=3011, J=3012

MOTION/3014, I=3011, J=3012, B1

, FU=30D*SIN(360D*TIME+30D)

MOTION/3015, I=3011, J=3012, B2

, FU=-25D*SIN(360D*TIME-25D)

MOTION/3016, I=3011, J=3012, B3

, FU=45D*SIN(360D*TIME-57D)

These MOTION statements control the three rotational degrees-of-freedom in a spherical joint by

specifying the Body 1-2-3 angles between the I and J markers of the joint as functions of time.

JOINT/401, PLANAR, I=4011, J=4012

MOTION/4011, I=4011, J=4012, X

, FU=STEP5(TIME, 0.5, 0.0, 4.0, 1.0)*50

MOTION/4012, I=4011, J=4012, Y

, FU=-SHF(TIME, 0.0, 10/2, 2*PI, 90D, 10/2)

MOTION/4016, I=4011, J=4012, B3, FU=0D

These MOTION statements control the three degrees-of-freedom in a planar joint:

The displacement of the origin of Marker 4011 with respect to the origin of Marker 4012, along

The displacement of the origin of Marker 4011 with respect to the origin of Marker 4012, along

The rotation of Marker 4011 with respect to Marker 4012 about the z-axis of Marker 4011 is

specified to be zero.

See other Constraints available.

NFORCE 273

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.

274 Adams/Solver

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.

NFORCE 275

C++ Statements

Formulation

Action Forces (Forces on the I markers)

FI = - KMATRIX (X - L) - CMATRIX

X + FORCE

where:

FI is the 6n x 1 matrix of forces exerted on the I markers.

KMATRIX is the 6n x 6n truncated stiffness matrix, created by striking out the rows and

X is the 6n x 1 matrix of the translational and angular displacements of the I markers with

L is a 6n x 1 matrix of the reference displacements of the I markers with respect to the J marker,

expressed in the J 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 i trans

i

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.

276 Adams/Solver

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

FIELDs.

The FIELD defaults reference lengths to zero, while the NFORCE assumes by

default that the input positions of the I markers are at the reference locations.

The FIELD allows you to specify reference angles for the rotational

displacements, while the NFORCE assumes the reference angles are always

zero.

Examples

The figure below illustrates a simple, planar, triangular truss attached to some large base body.

NFORCE 277

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.

278 Adams/Solver

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

NFORCE 279

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

280 Adams/Solver

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

ANSYS

DAC

GENERIC

,MODAL_DEFORMATION =

NASTRAN

PUNCH

,

RPC

ANSYS

,NODAL_DEFORMATION = GENERIC

NASTRAN

DAC

,STRAIN =

GENERIC

DAC

,STRESS =

GENERIC

[ ] Optionally select the item

[[ ]] Optionally select an item combination

OUTPUT 281

C++ Statements

Arguments

ABAQUS

data are written out as ABAQUS input commands.

ANSYS

data or nodal deformations are written out as ANSYS input commands.

Modal deformations are written out to a file format supported by the

Adams MSR ANSYS-customized macro, available in Adams/Durability

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

DACSAVE, Adams/Solver (C++) does not save request data in DAC

format.

GENERIC

GRSAVE

to display graphics. If neither GRSAVE nor GR521SAV is specified,

Adams/Solver (C++) does not save graphics output in the graphics file.

LOADS

Controls output of FEM data to the specified format. If you do not specify

LOADS, Adams/Solver (C++) does not process any FEMDATA/LOADS

statements.

MODAL_DEFORMATION Controls output of modal deformation data to the specified format. If you

do not specify MODAL_DEFORMATION, Adams/Solver (C++) does

not process any FEMDATA/MODAL_DEFORMATION statements.

NASTRAN

data or nodal deformations are written out as NASTRAN input

commands. Modal deformations are written out to NASTRAN

OUTPUT2 (binary) format.

NODAL_DEFORMATION

do not specify NODAL_DEFORMATION, Adams/Solver (C++) does

not process any FEMDATA/NODAL_DEFORMATION statements.

282 Adams/Solver

C++ Statements

NOSEPARATOR

request, graphics, results, and tabular output files when you modify the

model topology in the middle of a simulation. You can change the model

topology by using interactive commands to activate an element,

deactivate an element, change a marker position, or change the type or

point of application of a force or constraint during a simulation.

When you change the model topology, by default, Adams/Solver (C++)

writes a separator and new header to the request, graphics, results, and

tabular output files. Adams/Solver (C++) then writes subsequent

simulation output after the new headers. This ensures that the changes are

correctly reflected in the output files, but it creates two sets of output that

cannot be plotted or animated continuously. The NOSEPARATOR

argument prevents Adams/Solver (C++) from breaking up the files;

instead it creates a continuous set of output that can be plotted and

animated from beginning to end.

Note:

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

file) format.

REQSAVE

Saves request output in the request file so that you can use a

postprocessor to display x-y plots. If you do not specify REQSAVE,

Adams/Solver (C++) does not save the request output in the request file.

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

specify STRAIN, Adams/Solver (C++) does not process any

FEMDATA/STRAIN statements.

Note:

OUTPUT 283

C++ Statements

STRESS

specify STRESS, Adams/Solver (C++) does not process any

FEMDATA/STRESS statements.

Note:

YPR

coordinates, rather than in psi, theta, and phi coordinates. Using dashed

lines to represent original orientations and using solid lines to represent

new orientations, Figure below shows how these coordinates define a

rotational orientation.

Figure. Successive Yaw, Pitch, and Roll Rotations

negative rotation about the new y-axis (y'), and then about the second

new x-axis (x"). If you do not specify YPR, Adams/Solver (C++) outputs

rotational displacement values in psi, theta, and phi coordinates.

YPR only affects rotational displacement output. Adams/Solver (C++)

always outputs angular velocities and accelerations as vectors, with

orthogonal x, y, and z components.

Extended Definition

The OUTPUT statement controls the generation and format of REQUEST or FEM data. Specifically, the

OUTPUT statement controls the following:

Output of FEMDATA

Output of Request Data in RPCIII and DAC Formats

Output 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.

284 Adams/Solver

C++ Statements

With NODAL_DEFORMATION, the ANSYS or NASTRAN option creates a text file of input

commands for defining enforced displacements in the respective FEA package (for example, SPC* cards

in the case of NASTRAN).

With MODAL_DEFORMATION, the NASTRAN option produces an OUTPUT2 (NASTRAN binary)

file. This file can be imported by NASTRAN for stress recovery on the flexible body with the

Adams/Durability Modal Stress Recovery DMAP. Note that this file format is machine dependent.

NASTRAN will not be able to read the file if it was created on a platform different than the one running

NASTRAN.

Alternatively, the PUNCH format option for MODAL_DEFORMATIONS produces a text file that can

be imported by NASTRAN for stress recovery. This file format is not as compact as the OUTPUT2

format (see NASTRAN option), but it is machine independent. If NASTRAN is run on a different

platform than Adams, the modal deformations can be transferred using this file format for subsequent

NASTRAN runs.

Also, with MODAL_DEFORMATIONS, the ANSYS option produces a file of modal deformations. This

file can be processed by ANSYS using a custom macro provided by the Adams/Durability. Modal

deformations can be combined with the modal stress shapes stored in the ANSYS database to recover

dynamic stresses in ANSYS using modal superposition.

Output of Request Data in RPCIII and DAC Formats

You can save request data in RPC III and DAC format.

RPC III format- Adams/Solver (C++) creates one RPC file of all data components specified in

The RPC III file is named according to the naming convention:

Prefix.rsp

where:

Prefix is the prefix specified when you set up Adams results.

DAC format - Adams/Solver (C++) can only store one channel of data in a DAC file. Therefore,

Adams/Solver (C++) creates six DAC files, one per request component. The files are named

according to the DAC file naming convention:

prefix_request name_component label.dac

where:

prefix is the prefix you specified when you set up the Adams results.

request name is the request name you specified when you created a new request.

component label is the reserved label assigned to the six components of request data by Adams

Examples

OUTPUT/GRSAVE, REQSAVE

This OUTPUT statement causes Adams/Solver (C++) to save both graphics and request output.

OUTPUT 285

C++ Statements

, FILE=adams

, NODE=100, 200, 300

OUTPUT/STRESS=DAC

DAC files are created with the job name adams in the FLEX_BODY_201 subdirectory. Each DAC file

contains the time history of one of the six stress components (Sx, Sy, Sz, Txy, Tzx, Tyz) at a node. Since

three nodes are specified, a total of eighteen DAC files are created.

OUTPUT/MODAL=NASTRAN, NODAL=GENERIC

A NASTRAN binary file will be created of each FEMDATA statement with modal deformations. No

output files will be generated for loads, strain or stress since no OUTPUT specification was given for

these types of FEMDATA.

REQUEST/1, DISPLACEMENT, I=201, J= 103, TITLE=REQ01

OUTPUT/DACSAVE

This OUTPUT statement causes Adams/Solver (C++) to save request output defined in the above

REQUEST statement to DAC files only. Adams/Solver (C++) creates a total of six DAC files in the

current working directory with the following names:

adams_req01_x.dac

adams_req01_y.dac

adams_req01_z.dac

adams_req01_r1.dac

adams_req01_r2.dac

adams_req01_r3.dac

REQUEST/1, FORCE, I=201, J=103, TITLE=REQ01

REQUEST/2, FORCE, I=202, J=104, TITLE=REQ02

REQUEST/3 FORCE, I=203, J=105, TITLE=REQ03

OUTPUT, RPCSAVE

This OUTPUT statement causes Adams/Solver (C++) to save request output defined in the three

REQUEST statements to an RPC III file. Adams/Solver (C++) creates one RPC III file named

Adams.rsp, containing 18 channels of data (six per REQUEST statement).

See other Output available.

286 Adams/Solver

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

PART 287

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

(C++) does not change these unless the values specified are inconsistent with initial

conditions for a joint or defined motion.

GROUND

Indicates the part being defined as the Newtonian reference frame. It is, by

definition, at absolute rest. Because there can be only one ground part in the system,

a dataset must never have more than one PART statement with the GROUND

argument.

IM=id

Specifies the identifier of the marker about which you specify the moments of

inertia for the part. This marker can be any marker in the part. The IM marker

defaults to the CM marker.

288 Adams/Solver

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:

shown. Some references define these terms as the negative of these

integrals. Be sure to compute these values as shown above.

MASS=r

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).

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.

PART 289

C++ Statements

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.

290 Adams/Solver

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.

PART 291

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

beyond six digits is not guaranteed.

Use the EXACT, VX, VY, VZ, WX, WY, and WZ arguments with caution. Do not

specify more initial displacements to be exact than the system has degrees of

freedom. After you are sure the system has zero or more degrees of freedom, look

at the model and see if the remaining set of part motions will permit Adams/Solver

(C++) to adjust the system to satisfy all the initial conditions. Remember that IC,

ICTRAN, and ICROT arguments on the JOINT statement remove degrees of

freedom from a system during initial conditions analysis. Similarly, do not specify

more initial velocities than the system has degrees of freedom.

A part without mass cannot have moments of inertia, initial conditions on

If you specify the mass for a part, you must also specify the CM marker for the

part.

A planar part is implicitly constrained to move in a plane at a fixed global value of

Z. Any force applied to the planar part in the global Z direction will be discarded.

The same applies to torques about the global X and Y axes. It is not possible to

measure the reaction forces required to constrain the planar part to stay in plane. If

such forces are desired, the equivalent part and planar joint combination must be

substituted.

Examples

PART/01, GROUND

The PART statement above indicates that Part 1 is the ground part.

PART/02, MASS=2, CM=0201, IP=5,6,10

The PART statement above specifies the mass (2 units), the center-of-mass marker identifier (0201), and

the principal moments of inertia for Part 2:

292 Adams/Solver

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

Mass (.5 units)

Center-of-mass marker identifier (0407)

Initial position of the BCS (10,0,0) with respect to the ground coordinate system (GCS).

This statement does not define the principal moments of inertia, so the inertia of the part is zero about

each of the CM marker axes. In addition, this statement has no arguments to indicate the orientation of

Part 4, so Adams/Solver (C++) aligns the axes of the BCS of Part 4 with the axes of the GCS.

See other Inertia and material data statement available.

PINPUT 293

C++ Statements

PINPUT

The PINPUT statement defines a list of VARIABLE statements that Adams/Solver (C++) recognizes as

system input during a LINEAR/STATEMAT analysis (see the LINEAR command).

Format

PINPUT/id, VARIABLES=id1[,id2,...]

Arguments

VARIABLES=id1[,id2,...]

Adams/Solver (C++) model.

Extended Definition

The PINPUT statement, along with a POUTPUT statement, is used with the LINEAR/STATEMAT

command. PINPUT defines a set of inputs to the mechanical system, and POUTPUT defines the set of

measured outputs from the system. The LINEAR/STATEMAT command linearizes the system equations

to the following form

x = Ax + Bu

y = Cx + Du

where x is the linearized system state array, u is the array of system inputs defined by the PINPUT

statement, and y is the array of system outputs defined by the POUTPUT statement. This form is

commonly referred to as the state space form of the system equations in control theory. Adams/Solver

(C++) outputs the A, B, C, and D matrices for use in a control-system design or any other linear system

analysis software. If only the A matrix is required, PINPUT and POUTPUT are not necessary.

When you run an analysis type other than LINEAR/STATEMAT, the PINPUT statement acts only as a

pointer to the list of the specified VARIABLE statements.

Both function expressions and user-written subroutines can access the PINPUT statement. Function

expressions access the values by using the internal Adams/Solver (C++) function PINVAL(i1,i2) (see the

PINVAL function), where i1 specifies the PINPUT id, and i2 specifies the i2th VARIABLE in the

PINPUT statement list. Note that i2 is not the id of the VARIABLE statement.

294 Adams/Solver

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.

PINPUT 295

C++ Statements

296 Adams/Solver

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

POINT_MASS 297

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

not change as it iteratively solves for initial conditions which satisfy all

constraints. The three coordinates are below.

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

Default: 0

Range: r > 0

QG=x,y,z

Defines the Cartesian initial coordinates of the BCS with respect to the global

coordinate system.

Default: 0.0, 0.0, 0.0

Range: Any real values

REULER=a,b,c

Defines the 3-1-3 Euler angles that Adams/Solver uses to establish the initial

orientation of the BCS with respect to the coordinate system. The a, b, and c

rotations are in radians and are, respectively, about the z-axis of ground, the

new x-axis, and the new z-axis of the BCS. To input Euler angles in degrees,

add a D after each value.

Defaults: 0.0, 0.0, 0.0 when REULER, XG, and ZG are omitted

Range: Any real values

298 Adams/Solver

C++ Statements

VX=x, VY=y,

VZ=z

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.

POINT_MASS 299

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

issues a warning. Adams/Solver does not generate moments due to offsets from

CM.

The CM can be offset from the BCS, but still the markers involved in constraints

Markers on a point mass to which no constraints or forces are applied (such as

Function expressions may reference markers associated with point masses.

However, Adams/Solver rejects expressions that should not refer to point mass

markers, such as TM, TX, TY, TZ, and NFORCE. You may use point mass

markers in rotational function expressions (such as AX, PSI, WY, and WDTZ), but

remember that the orientation of point mass markers is constant and their

rotational velocities and accelerations are always zero with respect to the ground

coordinate system (GCS).

Adams/Solver permits you to request displacements, velocities, accelerations, and

forces between two point mass markers. However, the rotational displacements are

always constants, the rotational velocities are always zero, the rotational

accelerations are always zero, and the torques are zero.

See other Inertia and material data statement available.

300 Adams/Solver

C++ Statements

POUTPUT

The POUTPUT statement defines a list of VARIABLE statements that Adams/Solver (C++) recognizes

as system output during a LINEAR/STATEMAT analysis (see the LINEAR command).

Format

POUTPUT/id, VARIABLES=id1[,id2,...]

Arguments

VARIABLES=id1id1[,id2,...]

Adams/Solver (C++) model.

Extended Definition

The POUTPUT statement, along with a PINPUT statement, is used with the LINEAR/STATEMAT

command. POUTPUT defines the set of measured outputs from the system and PINPUT defines a set of

inputs to the mechanical system. The LINEAR command linearizes the system equations to the following

form:

x = Ax + Bu

y = Cx + Du

where:

x is the linearized system state array

u is the array of system inputs defined by the PINPUT statement.

y is the array of system outputs defined by the POUTPUT statement.

This form is commonly referred to as the state space form of the system equations in control theory.

Adams/Solver (C++) outputs the A, B, C, and D matrices for use in a control-system design or any other

linear system analysis software. If only the A matrix is required, PINPUT and POUTPUT are not

necessary.

When you run an analysis type other than LINEAR, the POUTPUT statement acts only as a pointer to

the list of VARIABLE statements specified.

Both function expressions and user-written subroutines can access the POUTPUT statement. Function

expressions access the values by using the internal Adams/Solver (C++) function POUVAL(i1,i2) (see

the PINVAL function), where i1 specifies the POUTPUT id , and i2 specifies the i2th VARIABLE in the

POUTPUT statement list. Note that i2 is not the id of the VARIABLE.

POUTPUT 301

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.

302 Adams/Solver

C++ Statements

PREFERENCES 303

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

304 Adams/Solver

C++ Statements

Arguments

operations:

Parasolid - Specifies the Parasolid geometry

determination. Adams/Solver (C++) supports

Parasolid version 19.0.17.

Default_library - Specifies that the default

default library is based on RAPID, a polygonbased interface detection package developed

at the University of North Carolina. Currently,

Adams/Solver (C++) supports RAPID 2.01.

For many models, the Default Library can

substantially reduce simulation time. Because it is

polygon-based, however, it is not always as accurate

as the Parasolid geometry engine. Parasolid is an

exact boundary-representation geometric modeler,

which makes it highly accurate, but not as fast as a

polygon-based engine. For these reasons, you can

switch from one to the other depending on your needs.

CONTACT_FACETING_TOLERANCE=valu

e

created from the solid geometries in the model.

Contact kinematics are calculated by intersecting the

meshes corresponding to two solid geometries. A

finer mesh results in more accurate contact

calculations. Calculations may be slower, however,

and computer memory requirements increase as the

mesh resolution increases.

The faceting tolerance is defined as the maximum

error between the true surface and the surface of the

faceted representation of the geometry. The maximum

error is guaranteed not to exceed (1/value) * the

minimum dimension of each geometry's bounding

box.

The default value of this parameter is 300.

The faceting tolerance has no effect on inherently

polygonal surfaces such as boxes.

PREFERENCES 305

C++ Statements

LIBPATH=dir1:dir2:...

are to be searched for user subroutine plug-in libraries

before searching in the default locations. See the

ROUTINE Argument for more information.

NTHREADS=n

Adams/Solver (C++) will use when performing the

simulation.

The number of threads, n, must be an integer in the

range of 1 to 8. The default value is 1.

By executing multiple threads in parallel across

multiple processors, Adams/Solver (C++) can reduce

the walltime required for a simulation.

Typically, the optimal number of threads is between N

and 2N, where N is the number of processors

(including virtual processors, such as Pentium

processors supporting HyperThreading).

Note that this option has no effect on IRIX

architectures.

Learn about Threaded (Parallel) Operation of

Adams/Solver(C++).

STATUS_MESSAGE

.msg file produced by Adams/Solver (C++). These

status messages mimic status messages produced by

Adams/Solver (FORTRAN). This preference has no

effect on Adams/Solver (FORTRAN).

Default: OFF

The first status message is sent after every simulation

and has the form Simulate status =i.

The second message is sent when Adams/Solver

(C++) terminates and has the form Termination

status = i.

In both cases, i is an integer number reporting the

status.

306 Adams/Solver

C++ Statements

FLEX_LIMIT_CHECK={skin, SELNOD}

flexible bodies.

skin - Adams/Solver (C++) will check the

whether they exceed the linear limit. To use

this option, MNF_FILE or DB_FILE need to

be specified in FLEX_BODY statement.

SELNOD - Adams/Solver (C++) will only

in MTX file.

The linear limit is defined as 10% of the characteristic

length of the flexible body. User can use CHAR_LEN

in FLEX_BODY statement to specify the

characteristic length. If CHAR_LEN is not specified,

Adams/Solver (C++) will try to calculate the

characteristic length use MNF or MD DB if

MNF_FILE or DB_FILE is specified. Otherwise,

Adams/Solver (C++) will issue a warning.

FLEX_LIMIT_CHECK_ACTION={HALT,

RETURN, MESSAGE_ONLY}

take if a flexible body exceeds its linear limit.

HALT - Terminates execution of

Adams/Solver (C++).

RETURN - Stops the simulation and returns

MESSAGE_ONLY - Issue a warning

Threaded (Parallel) Operation of Adams/Solver(C++)

Adams/Solver (C++) allows for threaded operations (multiple threads of execution operating in parallel).

Selecting multiple threads can allow Adams/Solver (C++) to take advantage of systems with multiple

processors and, therefore, reduce the walltime for a simulation to complete (that is, the amount of time

the operator spends waiting).

The reduction in execution time that threaded operation can provide depends greatly on the particular

model being simulated. You can expect walltime speed ups of 1.2 times (serial execution time/threaded

execution time). Depending on the model, however, anywhere from no speed improvement to more than

2 times are possible.

Models that reference 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.

PREFERENCES 307

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

PREFERENCES/CONTACT_GEOMETRY_LIBRARY=Parasolid

VARSUB/1, ROUTINE=foo::bar, FUN=USER(2,3)

PREFERENCES/LIBPATH=/home/joe/plugins:/usr/projects/lifters

Adams/Solver (C++) searches for a user subroutine named BAR in a dynamically loaded library named

libfoo.so (see documentation for ROUTINE Argument for more information about library name rules) in

the directories /home/joe/plugins and /usr/projects/lifters, before searching in the default plugin

directories.

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.

308 Adams/Solver

C++ Statements

PSTATE

The PSTATE statement defines a set of user-defined coordinates to be used during a LINEAR analysis

(see the LINEAR command).

You can specify as many states as there are degrees-of-freedom. If a smaller set of states are provided,

then the system will "fill in" by choosing a set of internally available states for the ones that were not

explicitly specified. If too many states are specified, Adams/Solver (C++) identifies and discards the

redundant states.

For theoretical details, see the white paper in Simcompanion Knowledge Base Article KB8016460.

For an example of using PSTATE, see Simcompanion Knowledge Base Article KB8016414.

Format

PSTATE/id, VARIABLES=id1[,id2,...]

Arguments

VARIABLES=id1[,id2,...]

define a displacement or angular expression; the expressions must be

nonconstant.

The VARIABLE expressions constitute a set of user-defined

coordinates to be used during a linearization or eigensolution

computation.

Extended Definition

LINEAR/MKB command. PSTATE defines a set of user-defined coordinates. The LINEAR/STATEMAT

command linearizes the system equations to the following form:

x = Ax + Bu

y = Cx + Du

where:

x is the linearized system state array.

u is the array of system inputs defined by the PINPUT statement.

y is the array of system outputs defined by the POUTPUT statement.

PSTATE 309

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)

310 Adams/Solver

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:

Do not confuse a PSTATE statement with the PSTATE option in the LINEAR

command.

Examples

The model shown in the figure below is a simple rigid helicopter blade.

Assuming that MARKER/10 is located on the CM of the blade, by default, Adams/Solver (C++) will

linearize the model using the rotation AZ(10). If you want to linearize the model using the displacement

'y' shown in the figure, then add the following objects to the data set:

VARIABLE/1, FU=DY(10)

PSTATE/1, VAR=1

LINEAR/STATE, PSTATE=1

In this case, Adams/Solver (C++) linearizes the system using the 'y' coordinate shown in the figure (see

Using the PSTATE option section in the LINEAR command).

Applications

The PSTATE statement is of fundamental importance in cases in which you need to linearize the system

using relative coordinates. The most important case is the eigenvalue calculations of rotating systems.

PSTATE 311

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.

312 Adams/Solver

C++ Statements

PTCV

The PTCV statement defines a point-to-curve constraint, which restricts a fixed point defined on one part

to lie on a curve defined on a second part. This is an instance of a higher pair constraint.

Format

Arguments

CURVE=id

Specifies the identifier of a CURVE statement that defines the contour or shape on which

the fixed marker can move. The x, y, z values associated with the curve are the

coordinates of points lying on the curve and are calculated in the coordinate system of

the RM marker.

DISP=x,y,z

Specifies the initial point of contact on the curve. If the point specified is not exactly on

the curve, Adams/Solver (C++) uses a point on the curve nearest to that specified. By

default, DISP is specified in the RM marker coordinate system. If another coordinate

system is more convenient, you may supply the ICM argument and enter DISP in ICM

marker coordinates.

If you supply DISP, Adams/Solver (C++) assembles the system with the I marker at the

specified point on the curve. If you do not supply DISP, Adams/Solver (C++) assumes

the initial contact is at the point on the curve closest to the initial I marker position.

However, it may adjust that contact point to maintain other part or constraint initial

conditions.

I=id

Specifies the identifier of a fixed MARKER that Adams/Solver (C++) constrains to lie

on the curve defined by CURVE and RM. The I and RM markers must belong to

different parts.

ICM=id

Specifies the identifier of a fixed MARKER defining the coordinate system in which the

values for DISP are specified. The ICM marker must be on the same part as the RM

marker.

PTCV 313

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.

314 Adams/Solver

C++ Statements

Figure 5

PTCV 315

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.

316 Adams/Solver

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:

MAXPAR

or

DELTA = -(ALPHA-MINPAR)/ABS(MAXPAR-MINPAR), if ALPHA <

MINPAR

This force is intended to prevent solution problems when unexpected situations

occur, and should not be relied upon intentionally. You should make sure the

CURVE statement defines the curve over the expected range of motion.

The initial conditions arguments, DISP and VEL, impose constraints that are

active only during an initial conditions analysis. Adams/Solver (C++) does not

impose these initial conditions during subsequent analyses.

For a kinematic analysis, the initial conditions are redundant. Do not use the DISP

or VEL arguments on the PTCV statements for systems with zero degrees of

freedom.

It is easy to accidentally over-constrain a system using the PTCV constraint. For

cylindrical joint, not a revolute joint. If the follower is held by a translational joint

and the cam by a cylindrical joint, the PTCV constraint between the follower and

cam prevents the cam from moving along the axis of rotation (that is, the axis of

the cylindrical joint). A revolute joint would add a redundant constraint in that

direction.

Examples

PTCV/55, I=201, JFLOAT=301, CURVE=10, RM=302>

This statement creates a point-curve constraint between Marker 201 and a curve on the part containing

floating Marker 301 and fixed Marker 302. CURVE/10 defines the x, y, z coordinates curve in the

coordinate system of Marker 302. Because the statement does not specify initial conditions,

PTCV 317

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.

318 Adams/Solver

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.

REQUEST 319

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

320 Adams/Solver

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.

REQUEST 321

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.

322 Adams/Solver

C++ Statements

DISPLACEMENT

Outputs the displacement of the I marker with respect to the J marker. The

output data includes:

x component (X)

y component (Y)

z component (Z)

psi angle (PSI)

theta angle (THETA)

the phi angle (PHI)

The psi, theta, and phi angles are the Euler angle displacements of the I marker

with respect to the J marker. Adams/Solver (C++) calculates this displacement

data in the global coordinate system. If you specify RM, Adams/Solver (C++)

resolves the translational x-component, the translational y component, and the

translational z-component in the coordinate system of the RM marker. RM does

not affect psi, theta, and phi. If the YPR argument is placed in the OUTPUT

statement, the psi, theta, and phi rotations are converted to yaw, pitch, and roll

rotations.

F1=e

Defines the first component of the request that is being specified. If the F1

argument is used, it must either be the last argument in the REQUEST statement

or be followed by a backslash (\) (not a comma).

F2=e

used, it must either be the last argument in the REQUEST statement or be

followed by a backslash (\) (not a comma).

F3=e

used, it must either be the last argument in the REQUEST statement or be

followed by a backslash (\) (not a comma).

F4=e

used, it must either be the last argument in the REQUEST statement or be

followed by a backslash (\) (not a comma).

F5=e

Defines the fifth component of the request that is being specified. If the F5

argument is used, it must either be the last argument in the REQUEST statement

or be followed by a backslash (\) (not a comma).

F6=e

used, it must either be the last argument in the REQUEST statement or be

followed by a backslash (\) (not a comma).

F7=e

used, it must either be the last argument in the REQUEST statement or be

followed by a backslash (\) (not a comma).

REQUEST 323

C++ Statements

F8=e

used, it must either be the last argument in the REQUEST statement or be

followed by a backslash (\) (not a comma).

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).

324 Adams/Solver

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

with this REQUEST. The VARIABLES argument requires one or more

VARIABLE id references. This option is only used in XML result files.

VELOCITY

Outputs the velocity of the I marker with respect to the J marker. The output data

includes:

translational x component (VX)

translational y component (VY)

translational z component (VZ)

rotational x component (WX)

rotational y component (WY)

rotational z component (WZ)

Adams/Solver (C++) calculates this velocity data (the first derivative of the

displacement of the I marker with respect to the J marker) in the global

coordinate system. If you specify RM, Adams/Solver (C++) resolves the

translational and rotational velocities vector in the coordinate system of the RM

marker.

Extended Definition

The REQUEST statement indicates a set of data you want Adams/Solver (C++) to write in the request

file. Using a REQUEST statement, you can output a set of displacements, velocities, accelerations, or

forces with respect to markers in the system. FUNCTION keywords allow you to explicitly define the

output variables or employ a user-written subroutine REQSUB to define nonstandard output.

Adams/Solver (C++) calculates all time derivatives in the ground coordinate system (GCS), although you

can specify that the data be resolved in another reference frame. This is of no importance in the case of

force data, but it can be very important in the case of velocities and accelerations. For example, joint

velocities are actually translational and rotational velocity difference vectors of the joint I marker and the

REQUEST 325

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.

326 Adams/Solver

C++ Statements

Caution:

Applied forces and torques are those generated by beams, bushings, fields, general

(SPRINGDAMPERs), vector forces (VFORCEs), and vector torques

(VTORQUEs). Adams/Solver outputs the applied forces and torques acting at the

request I marker (which may be either the applied force I marker or the applied

force J marker). The magnitude and point of force application on the part

containing the applied force J marker varies according to the type and source of the

force.

For spring dampers, action-reaction single-component forces, general forces,

vector forces, and vector torques, the forces and torques acting at the J marker are

equal and opposite to the forces and torques acting at the I marker. For action-only

single-component forces, there is no force or torque acting at the applied force J

marker. For beams, fields, bushings, and multi-point forces, the forces acting at the

applied force J marker are equal and opposite to the forces acting at the applied

force I marker. As long as the applied force I marker and the applied force J marker

are coincident, the torques acting at the applied force J marker are equal and

opposite to the torques acting at the applied force I marker. If there is a finite

separation between the I and the J markers, the torques acting at the applied force J

marker are calculated by solving the moment balance equation at the J marker.

Reaction forces and torques are those generated by constraint-inducing elements.

For revolute, spherical, and universal joints and for atpoint, orientation, parallel

axes, and perpendicular joint primitives, Adams/Solver (C++) outputs the reaction

forces and torques acting at the request I marker (which may be either the

constraint I marker or the constraint J marker). The force and torque acting at the

request J marker are equal and opposite to the force and torque acting at the

request I marker. Depending on the type of constraint, some or all of the torques

acting at the I marker are zero. Determining reaction forces and torques for

cylindrical, planar, rack-and-pinion, screw, and translational joints and for inline

and inplane joint primitives is more complex.

If the request I marker corresponds to the constraint I marker, then Adams/Solver

(C++) outputs the force and torque acting at the constraint I marker. If the request I

marker corresponds to the constraint J marker, then Adams/Solver (C++) outputs

the force and torque acting at the instantaneous location of the constraint I marker,

but on the part containing the constraint J marker. The force translated to the

constraint J marker is the same as computed above. If the I and the J markers are

coincident, the torque translated to the constraint J marker is the same as computed

above. But if there is a finite separation between the I and the J markers, the torque

translated to the constraint J marker is different from the one computed above

(because of the moments contributed by the reaction forces).

REQUEST 327

C++ Statements

Caution:

You must be careful when requesting a force with the I and the J markers reversed

the force as if it were applied to the J marker of the force-producing element. The

translational force on the J marker of the force element is equal and opposite to the

translational force on the I marker of the force element if it is not action-only. The

force is zero if it is action only. The torque on the J marker of the force element has

components that may have significance. The torque is the sum of two

contributions. The first contribution is the opposite of the torque on the I marker.

The second contribution is due to the force acting across the separation between

the I and the J markers. If the force acts along the line of sight of the two markers,

this extra torque is zero. To minimize misunderstandings, attach the REQUEST

markers in the same order as the markers on the force-producing element.

When computing velocity and acceleration for a marker pair that includes a

though the floating marker were permanently attached to the part at its current

position.

Examples

REQUEST/01, DISPLACEMENT, I=0201, J=0103

, COMMENT=CRANK CENTER OF MASS DISPLACEMENT

This REQUEST statement requests displacement data for Marker 0201 with respect to Marker 0103.

Adams/Solver outputs the comment CRANK CENTER OF MASS DISPLACEMENT to the request file.

REQUEST/08, FORCE, I=0304, J=0204

, COMMENT=ROD/CRANK REACTION

This REQUEST statement requests data for an 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"/>

328 Adams/Solver

C++ Statements

</entity>

Instead of generating 2 result sets with 8 channels each (default XML behaviour), only one result set with

4 channels is created.

Applications

Requests are used whenever a particular output is desired from Adams/Solver (C++). The output

generated from the request contains data needed for plotting in a postprocessor. The writing of this files

is controlled by the OUTPUT statement.

An alternative to the use of REQUESTS is the RESULTS statement, which causes all the results for the

analysis to be saved to a results file. This file can then be used in a postprocessor. The major drawbacks

to using the RESULTS statement is the size of the file, and having the data in a form that needs to be

translated by a postprocessor.

When using a REQUEST statement, you must also have an OUTPUT/REQSAV statement in order to

create a request file (.req).

Data from certain Adams/Solver (C++) statements is accessible only through the request functions

(F2,...,F8). The statements include PINPUT, POUTPUT, VARIABLE, ARRAY, LSE, GSE, TFSISO, and

DIFF. To request information on PINPUT, POUTPUT, ARRAY, or VARIABLE, you should write the

function expression referencing PINVAL, POUVAL, ARYVAL, and VARVAL, respectively. To request

information on LSE, GSE, TFSISO, you should write the function expression referencing ARYVAL. To

request information on DIFF, you should write the function expression referencing DIF for the value of

the independent variable associated with a 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 329

C++ Statements

RESULTS

The RESULTS statement creates a results file that includes all the simulation output from Adams/Solver

(C++). The results file can be either unformatted (binary) or formatted (ASCII).

Format

,NOACCELERATIONS

,NOAPPLIEDFORCES

,NODATASTRUCTURES

,NODISPLACEMENTS

,NOFLOATINGMARKERS

,NOLINEAR

RESULTS/[FORMATTED][XRF]

,NOREACTIONFORCES

,NOREQUESTS

,NOSYSTEMELEMENTS

,NOVELOCITIES

,NOCONTACTS

,NODE_INCIDENTS

,DECIMALPLACES = i

,ROUNDOFF

,SCIENTIFICATION = i1, i2

RESULTS/[XRF]

,SIGINIFICANTFIGURES = i

,TRAILINGZEROES

,ZEROTHRESHOLD = r

[[ ]] Optionally select an item combination

330 Adams/Solver

C++ Statements

Arguments

DECIMALPLACES=i

Specifies how many digits are written after the decimal point for real

numbers. The default value is 17 decimal places (full precision for

recovery of double-precision numbers).

FORMATTED

Specifies that the results file is to be a formatted (text) file. The default is

an unformatted (binary) file. The formatted results file contains

Adams/Solver (C++) output in plain text that you can read. You cannot

examine an unformatted results file directly. Although the unformatted

results file is not user-readable, it is generally preferred for several reasons.

The unformatted file is smaller, contains more precise data, and is much

quicker for Adams/Solver (C++) to write and for a postprocessor to read.

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.

RESULTS 331

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

Enables the roundoff feature for real numbers (the default is disabled). The

SIGNIFICANTFIGURES argument controls the actual numbers of digits

retained during rounding off.

1,i2

Specifies the boundaries at which the format for real numbers switches

from a fixed point format to scientific notation. The values are exponents

for the base ten. The default values are -4 and 5, meaning that any number

less than or equal to 1.0E-04 or greater than or equal to 1.0E+05 will be

written in scientific notation.

SIGNIFICANTFIGURES=i This argument is only available with XRF.

Specifies how many significant figures of a real number are retained

during round off (when round off is enabled). The default is to use ten

significant figures.

This number is distinct from the number of places actually printed for a

real number, which the DECIMALPLACES argument controls.

Note:

TRAILINGZEROS

the decimal point.

Specifies that trailing zeros are printed for real numbers. The default is not

to print trailing zeros. When enabled, all the digits after the decimal point

will be printed, whether they are zero or not. When disabled, any zeros at

the end of the fractional part of the number will be dropped, leaving the

last digit as a non-zero digit.

332 Adams/Solver

C++ Statements

XRF

Markup Language) is an industry-standard format facilitating structured

data representation and web communication.

XRF will produce an XML-formatted results file even if the

FORMATTED parameter has not been specified.

ZEROTHRESHOLD=r

Specifies the zero threshold value for numbers being written to an output

file. If a number has an absolute value smaller than the zero threshold

value, then it will be written out as zero. This value is independent of units.

Extended Definition

The RESULTS statement creates a results file that includes selections of output from an Adams/Solver

(C++) simulation. This all-purpose file can contain all the simulation output from Adams/Solver (C++).

The results file can contain any combination of the following information:

Displacements - Displacements of the BCS with respect to ground and resolved in the ground

Velocities - Velocities of the the BCS with respect to ground and resolved in the GCS.

Accelerations - Accelerations of the BCS with respect to ground and resolved in the GCS.

Reaction forces - Forces on the I marker required to enforce each constraint, resolved in the

GCS.

Applied forces - Forces on the I marker applied by Adams/Solver (C++) force elements, resolved

in the GCS.

Data structures - Values computed for data structures such as variables, plant inputs, plant

System elements - Inputs, outputs, state variables, and state derivatives defined by system

modeling elements such as user-written differential equations, linear state equations, general

state equations, and transfer functions.

Tires - Displacements, velocities, accelerations, forces, and other information about tires.

Floating markers - Displacements of floating markers.

Linear - Eigenvectors, eigenvalues, and state matrices computed by a linear analysis invoked by

Contact Incidents - Values computed for individual contact points on Rigid and Flex Bodies in

contact.

RESULTS 333

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:

argument and the NOSYSTEMELEMENTS argument has superseded the old NODIFF

argument.

Including Node Incidents for Flex Body Contact may generate a very large results file.

Examples

RESULTS/FORMATTED, NODATASTRUCTURES, NOSYSTEMELEMENTS

RESULTS/NODISPLACEMENTS, NOVELOCITIES

,NOACCELERATIONS, NODATASTRUCTURES

,NOSYSTEMELEMENTS, NOFLOATINGMARKERS

334 Adams/Solver

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

SENSOR 335

C++ Statements

Arguments

BISECTION

to isolate the activation time of the sensor.

When not present the default, secant-type root-finding

algorithm is used.

CODGEN

when the event Adams/Solver (C++) is monitoring

becomes true. This may help the integrator to produce

more accurate data or to proceed more smoothly at

troublesome points in time. A pivot sequence for matrix

factorization is generated before the start of a

simulation. A new pivot sequence is not generated

unless the CODGEN argument is used or

Adams/Solver (C++) determines it is necessary to reach

convergence.

Default: Off

DT=r

when the event Adams/Solver (C++) is monitoring

becomes true.

Default: Time between output steps determined by

SIMULATE command

EQ

is true (active) if the function expression (or userwritten subroutine) minus VALUE is equal or less than

ERROR.

Default: EQ

ERROR=r

specifies the absolute value of allowable error to be

realized in VALUE.

Default: 0.001

336 Adams/Solver

C++ Statements

to a user-written subroutine that is evaluated when the

event Adams/Solver (C++) is monitoring becomes true.

The scalar value of the expression or the return value of

the user-written subroutine can then be obtained using

the SENVAL function expression.

If you want to define the evaluated function with an

expression, EVALUATE must be followed with an

equal sign and the expression. If you want to define the

evaluated function with a user-subroutine, FUNCTION

must be followed with an equal sign, the character

string USER, and the selected values (r1[,...,r30]) that

Adams/Solver (C++) passes to the user-written

subroutine SEVSUB.

If the EVALUATE argument is used, it must either be

the last argument in the SENSOR statement or be

followed by a backslash (\).

EVALUATE_ROUTINE=libname::subname Specifies an alternative library and name for the user

subroutine SEVSUB.

Learn more about the ROUTINE Argument.

Specifies an expression or defines and passes constants

to a user-written subroutine to define the event logical

expression. To define an expression, follow

FUNCTION with an equal sign and the expression (e).

To define a user-written subroutine, follow

FUNCTION with an equal sign, the character string

USER, and the values (r1[,...,r30]) that you want

Adams/Solver (C++) to pass to the user-written

subroutine SENSUB. If the FUNCTION argument is

used, it must either be the last argument in the SENSOR

statement, or be followed by a backslash (\).

Default: None

Range: An expression or user-parameter list of 1 to 30

real values

GE

is true (active) if the function or user-written subroutine

is equal to or greater than (VALUE-ERROR).

Default: EQ

SENSOR 337

C++ Statements

HALT

(C++) is monitoring becomes true (active).

Default: Off

LE

is true (active) if the function or user-written subroutine

is equal to or less than (VALUE + ERROR).

Default: EQ

when the event Adams/Solver (C++) is monitoring

becomes true.

Default: Off

RESTART

(C++) is monitoring becomes true. Adams/Solver

(C++) reduces the integration order to one. If the

SENSOR includes STEPSIZE, the integration step size

is reinitialized to the specified value. If you do not

specify STEPSIZE, Adams/Solver (C++) reinitializes

the integration step size to HINIT.

Default: Off

RETURN

when the event Adams/Solver (C++) is monitoring

becomes true.

Default: Off

ROUTINE=libname::subname

subroutine SENSUB.

Learn more about the ROUTINE Argument.

STEPSIZE=r

Adams/Solver (C++) is monitoring because true. This

change is temporary and lasts only for the next step.

Default: An integrator determined value except when

the SENSOR statement includes the RESTART

argument. In this case, STEPSIZE defaults to HINIT.

Range: STEPSIZE > 0

338 Adams/Solver

C++ Statements

TERROR

time of the sensor is isolated.

Default: 1e-6

VALUE=r

expression (or evaluation of the user-written

subroutine). When using GE with VALUE, the event

logical expression is true only if the function expression

is equal to or greater than (VALUE - ERROR). When

using EQ with VALUE, the event logical expression is

true only if the absolute value of the function

expression minus VALUE is equal to or less than

ERROR. When using LE with VALUE, the event

logical expression is true only if the function expression

is less than (VALUE + ERROR).

Default: None

Range: Any real number

YYDUMP

Adams/Solver (C++) is monitoring becomes true.

Default: Off

Extended Definition

The SENSOR statement defines a user-defined event that affects a set of simulation controls when the

event occurs. The event is defined by a logical expression that compares a function expression (or

evaluation of a user-written subroutine) to a target value using a relational operator. If the logical

expression becomes true during the simulation, the sensor modifies a set of simulation controls, which

include output and integration step sizes, simulation end time, and the Jacobian pivot sequence. A sensor

can also output diagnostic information and store the value of a function expression for later recall.

Adams/Solver (C++) evaluates the logical expression after every successful integration step when doing

dynamic analysis and after every successful output step when doing other types of analyses. To define

the function, use a function expression or a user-written subroutine. User-written subroutines and utility

subroutines discuss the subroutines they can access.

Adams/Solver(C++) uses a different algorithm for sensor detection from the one used by

Adams/Solver(FORTRAN). Adams/Solver(FORTRAN) uses a prediction to try to pick an integration

step that will detect the sensor. Adams/Solver(C++) uses three methods of search algorithms for sensor

detection:

1. Bisection method (primarily meant for discrete signals)

2. Time-based method

SENSOR 339

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,

Adams/Solver (C++) tests the sensor after every successful time step during dynamic

analyses and after every output step during other analyses. If the sensor becomes

active, Adams/Solver (C++) modifies the simulation control accordingly and does not

test the sensor again until it has completed three time steps. Then, Adams/Solver (C++)

again tests the sensor after every time step.

If you want Adams/Solver (C++) to take an action, make sure to include one of the

EVALUATE, and YYDUMP) in the SENSOR statement. The sensor can become

active even if one of the action arguments is not included. However, Adams/Solver

(C++) does not, of course, take action unless one is specified.

340 Adams/Solver

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,

For those INTEGRATOR statements where you set INTERPOLATE=OFF, if the

specified step size steps past the next output step, Adams/Solver (C++) reduces the

step size to reach the output step exactly.

If the specified step size is larger than HMAX, Adams/Solver (C++) uses HMAX.

If the specified step size is smaller than HMIN, and you specify RESTART, the

Adams/Solver (C++) may occasionally have difficulty enforcing an equality (EQ)

SENSOR, especially if the specified error is very small. In these cases, Adams/Solver

(C++) may appear to pass through the sensed value without invoking the sensor action.

If this occurs, you should try increasing the error tolerance, if possible. An alternative

is to change to an inequality (GE or LE) sensor, then DEACTIVATE the sensor after it

has triggered.

Examples

SENSOR/231, FUNCTION=DX(0201,0307)/

,VALUE=3.24, RETURN

This SENSOR statement senses the x-component for the displacement of Marker 0201 with respect to

Marker 0307 and resolves the displacement in the ground coordinate system (GCS). When the relative x

displacement equals 3.24 (+/- 0.001), the statement stops the simulation and returns to the command

level.

See other Analysis parameters available.

SFORCE 341

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

an action-reaction force. Adams/Solver (C++) applies no

reaction at the J marker.

Specifies an expression or defines and passes constants to a

user-written subroutine to define the single-component force.

To define the force with an expression, follow FUNCTION with

an equal sign and the expression. To define the force with a userwritten subroutine, follow FUNCTION with an equal sign, the

character string USER, and the values (r1[,...,r30]) that

Adams/Solver (C++) is to pass to the user-written evaluation

subroutine SFOSUB. If the FUNCTION argument is used, it

must either be the last argument in the SFORCE statement or be

followed by a backslash (\).

342 Adams/Solver

C++ Statements

I=id, J=id

force. If SFORCE defines a translational action-reaction force,

I and J specify the identifiers of the two markers between which

you want to exert the force. Adams/Solver (C++) applies the

translational action-reaction force along the line of action

defined by the line segment connecting I and J. If SFORCE

defines an action-only force, I specifies the point of application,

and the z-axis of J specifies the direction of the force. If

SFORCE defines a torque, the z-axis of the J marker specifies

the axis of rotation. In the case of action-reaction torques, the zaxis of the J marker must be parallel to, and pointed in the same

direction as, the z-axis of the I marker.

Note:

You can use the same marker for both the I and J

markers when you are specifying an action-only

SFORCE. For example, you would do this when

specifying rocket thrust forces.

ROTATION

Designates a rotational force, that is, a torque. For an 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.

ROUTINE=libname::subname

SFOSUB.

Learn more about the ROUTINE Argument.

TRANSLATION

the translational force between the I and the J markers.

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.

SFORCE 343

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.

where k0 is a static preload, x is the instantaneous length of the translational spring, x' is the time

derivative of x, l is the natural, unstretched spring length, k1 and k2 are stiffness coefficients, and c is a

damping coefficient. This equation representing the force magnitude can be rewritten in the following

polynomial format:

344 Adams/Solver

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.

SPLINE 345

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

346 Adams/Solver

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

Specifies the integer ID of a particular channel of data in the file referenced by

the SPLINE. This argument is used for files of type RPC III, which can contain

more than one channel of data. An error results if the specified file is of type

RPC and no CHANNEL argument is given or if the supplied channel ID does

not exist in the file. Adams/Solver ignores this argument for files of type DAC,

which by definition contain only one channel of data.

Default: (none)

Range: 1 < n < 128

FILE

Specifies the use of a file, rather than the X and Y arguments, to supply data for

the SPLINE. FILE causes Adams/Solver (C++) to call the user-written

subroutine SPLINE_READ, which you must provide. The FILE argument and

the X and Y arguments are mutually exclusive.

If you are using FILE with Adams/Durability, it specifies the name of the time

history file that supplies data for the SPLINE. The file can be of type DAC

(nSoft format) or RPC III (MTS format).

For more on how to define a SPLINE using the FILE argument, see the example

in SPLINE_READ subroutine.

LINEAR_EXTRAP

OLATE

range by applying linear function(s) tangent to the spline at the end(s) of the

defined range. By default, Adams/Solver (C++) extrapolates a SPLINE that

exceeds a defined range by applying a cubic function over the first or last three

data points.

SPLINE 347

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]

y1,y2,y3,y4[, . . . ,yn] for each x value.

Values must be constants; Adams/Solver (C++) does not allow expressions.

Y=z1,y11,y12,y13,y

14 [ , . . . , y1n]

,Y=z2,y21,y22,y23,

y24 [ , . . . , y2n]

,Y=z3,y31,y32,y33,

y34 [

,ym1,ym2,ym3,ym4

[ , . . . , ymn]]

y1,y2,y3,y4[, . . . ,yn] for the x values at unique z values

(z1[, . . . ,zm]).

UNITS

Values for z must be in increasing order: z1 < z2 < z3, and so on.

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,

348 Adams/Solver

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 CUBSPL function and the CUBSPL subroutine use the traditional cubic method of

Both the Akima method and the traditional cubic method use cubic polynomials to interpolate values that

fall between two adjacent points on a curve. Both provide closer approximations than other curve fitting

techniques (for example, Lagrange polynomials, difference tables, and Fourier series). For data with two

independent variables, Adams/Solver (C++) uses linear interpolation to determine values that fall

between curves. For more information about these curve-fitting techniques, see AKISPL and CUBSPL

functions.

Using Spline with Adams/Durability

The Adams/Durability SPLINE statement is an extension of the Adams/Solver (C++) SPLINE statement

that supports the input of experimental test data from industry standard formats DAC and RPC III. The

DAC format comes from nCode/nSoft. The RPC III file format comes from MTS.

DAC or RPC III files do not have standard file extensions. To determine which of these file types is in

use, Adams/Solver (C++) opens the file and reads a minimal amount of information contained in the file

head. If the specified file is not of type DAC or RPC III, Adams/Solver (C++) assumes that the file is a

user-defined file format, and processes the SPLINE statement using a SPLINE_READ user-supplied

subroutine. For more on how to define a SPLINE using the FILE argument for user-defined file formats,

see the example in SPLINE_READ subroutine.

SPLINE 349

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:

Crowd points in regions with high rates of change.

Spread out points in regions with slow rates of change.

Caution:

The x and z data must cover the anticipated range of values. However, the following

situations sometimes cause Adams/Solver (C++) to evaluate a spline outside of its defined

range:

Adams/Solver (C++) occasionally approximates partial derivatives using a finite

differencing algorithm.

Adams/Solver (C++) occasionally attempts an iteration that moves the

(C++) issues a warning message and extrapolates the four closest spline points. If

the extrapolation is poor, Adams/Solver (C++) may have difficulty reaching

convergence, which may affect the results.

To avoid these problems, try to use real points, and extend spline values 10 percent beyond

the total dynamic range.

Examples

The set of values in the table below relates the force in a spring to its deformation.

Data Relating Spring and Spring-Deflection Force

Deflection Force

-0.33

-38.5

-0.17

-27.1

-0.09

-15.0

0.0

0.0

0.10

10.0

025

30.0

0.40

43.5

0.70

67.4

350 Adams/Solver

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 =

-27.1, -15.0, 0.0, 10.0, 30.0, 43.5, 67.4

length

force

This SPLINE statement passes the data in the table above to a subroutine or function that uses cubic

spline functions to fit a curve to the values. The curve allows Adams/Solver (C++) to interpolate a value

of Y for any value of X. It also specifies that the X values are of type length and Y values are of type

force.

The set of values in the table below details a set of nonlinear, force-deflection relationships of a spring at

various temperatures.

Data Relating Spring Force to Spring Deflections at Various Temperatures

Force at degrees Fahrenheit:

Deflection:

20

30

40

50

-0.33

-38.5

-36.0

-30.0

-25.1

-0.17

-27.1

-25.4

-21.7

-18.6

-0.09

-15.0

-13.1

-9.6

-4.4

0.0

0.0

0.0

0.0

0.0

0.1

10.0

9.1

7.5

4.6

0.25

30.0

26.4

21.3

17.8

0.40

43.5

37.9

34.1

27.1

0.70

67.4

60.3

53.2

46.3

From table above, you can determine force when deflection equals -0.33 and when temperature equals

20. You can also determine force when deflection equals -0.17 and when temperature equals 30.

However, what is the force when deflection equals -0.25 and when temperature equals 25?

To determine the force at any deflection and temperature, you need to define a set of continuous functions

that generally relate force to deflection and temperature. If deflection is the independent x value and

temperature is the independent z value, you can define a set of functions in a family of curves using the

SPLINE statement. The SPLINE statement for this example is shown next:

SPLINE 351

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.

352 Adams/Solver

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

Default: 0

SPRINGDAMPER 353

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

Range: K > 0

KT=r

Specifies the spring stiffness coefficient for the torque. KT must be in units of

torque per radian.

Range: KT > 0

LENGTH=r

Defines the reference length for the spring. If the reference force of the spring

is zero, LENGTH equals the free length.

Range: LENGTH > 0

Default: 0

ROTATIONAL

TORQUE=r

Default: 0

TRANSLATIONAL

Extended Definition

markers. For a rotational springdamper, the z-axis of the I marker and the z-axis of the J marker must be

parallel and must point in the same direction.

Because the springdamper force is always an action-reaction force, the direction of the translational force

is along the line segment connecting the I and the J markers. Thus, if the force is positive, the markers

experience a repelling force along this line, and if the force is negative, the markers experience an

attracting force. The magnitude of the translational force applied to the parts containing the two markers

is linearly dependent upon the relative displacement and velocity of the two markers. The following

linear constitutive equation describes the force applied at the I marker:

Fa = -C (db/dt) - K(b-LENGTH) + FORCE

The force value is the force on the I marker applied by the J marker; the force on the J marker is equal

and opposite. The term b is the distance between the I and the J markers. Adams/Solver (C++) assumes

that b is always greater than zero. Adams/Solver (C++) automatically computes the terms db/dt and b.

The following linear constitutive equation describes the torque applied at the I marker:

Ta = -CT (da/dt) - KT(a-ANGLE) + TORQUE

The torque value is applied to the I marker about the positive z-axis of the I marker; the torque on the J

marker is equal and opposite to the torque on the I marker. The right-hand rule defines a positive torque.

354 Adams/Solver

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

Examples

SPRINGDAMPER/012, I=25, J=30, K=5, C=.1, L=.01

, TRANSLATION

This SPRINGDAMPER statement describes a force that Marker 30 applies to Marker 25. Marker 25 also

applies a force of equal magnitude and opposite direction to Marker 30. The argument TRANSLATION

indicates that this is a translational springdamper, rather than a rotational one. Therefore, the magnitude

of the force is proportional to the spring free length, to the distance between the two markers, and to the

time rate of change of the distance between the two markers. The L argument indicates that the spring

free length is 0.01 length units (L is the free length because the FORCE argument defaults to zero). The

spring constant K is 5 force units per unit length, and the damping constant C is 0.1 force units-seconds

per unit length.

See other Forces available.

STRING 355

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:

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.

356 Adams/Solver

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

contain a single face of a sheet body.

FUNCTION=USER

(r1[,...,r30])/

subroutine that computes the surface coordinates and derivatives.

The FUNCTION argument must be either the last argument in

the SURFACE statement or followed by a backslash (\).

MAXPAR=r1, r2

a user-written surface. If a file is specified, the file is queried for

the MAXPAR values.

Default: (1.0, 1.0)

MINPAR=r1, r2

a user-written surface. If a file is specified, the file is queried for

the MINPAR values.

Default: (-1.0, -1.0)

SURFACE 357

C++ Statements

ROUTINE=libname::subname

SURSUB.

UCLOSED

parameter. If specified, you must ensure that the defined surface

meets along the u edges and has continuous first and second

derivatives across the closure. If a file is specified, the file is

queried for UCLOSED.

Default: surface is open in u

VCLOSED

parameter. If specified, you must ensure that the defined surface

meets along the v edges and has continuous first and second

derivatives across the closure. If a file is specified, the file is

queried for VCLOSED.

Default: surface is open in v

Extended Definition

The x, y, and z coordinates of a point on a parametric surface are functions of independent parameters,

(u,v). As (u,v) vary from their minimum to maximum values, the functions x(u,v), y(u,v), and z(u,v)

sweep out points on the surface. A simple example of a parametric surface is defined by the following

equations and illustrated in the figure below:

x=u

y=v

z = cos( u2 + v2)

358 Adams/Solver

C++ Statements

Enter the name of a Parasolid geometry file containing one face of a sheet body.

Write a SURSUB evaluation subroutine with which Adams/Solver (C++) computes surface

To model an analytically defined surface such as a cylinder, you can write a SURSUB user-written

subroutine. When providing a SURSUB, you can also specify MINPAR and MAXPAR to define the

limits of the surface. These default to (-1,-1) and (1, 1), respectively.

A surface can be open or closed in both u and v. A surface closed in u (UCLOSED) meets along the edges

defined by the maximum and minimum values of u. A surface closed in v (VCLOSED) meets along the

edges defined by the maximum and minimum values of v.

Surfaces can be used in Adams constraints. A surface marker, allowed to only move on the surface, is

provided for this purpose. Any valid constraint (joint, jprim, and so on) can be constructed using the

surface marker.

A surface has parameterization limits as prescribed by MINPAR and MAXPAR. It is likely, however, that

there are regions within the parameter space where the surface is not defined. The finiteness of the surface

(including holes) are modeled using a penalty approach. The penalty approach applies a force to prevent

the surface marker from moving off the edge of an open surface or from moving into a hole in the surface.

This approach necessarily requires that the surface marker move off the surface for a short duration. In

SURFACE 359

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.

360 Adams/Solver

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

transfer function. Coefficients are listed in order of ascending powers

of s, starting with s to the zero power, including any intermediate zero

coefficients. The number of coefficients for the denominator must be

greater than or equal to the number of coefficients for the numerator.

NUMERATOR=b0[,...,b29]

transfer function. Coefficients are listed in order of ascending powers

of s, starting with s to the zero power, including any intermediate zero

coefficients. The number of coefficients for the numerator must be

less than or equal to the number of coefficients for the denominator.

STATIC_HOLD

Indicates that the TFSISO states are not permitted to change during

static and quasi-static analysis.

U=id

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.

TFSISO 361

C++ Statements

X=id

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

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

bo + b1 s1 + + bm sm

y

G s = ---------- = -----------------------------------------------------us

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]

362 Adams/Solver

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:

1

k

y s - = q-------------------------------------------------o + q1 s + + qk s

G s = --------us

p o + ps 1 + + p k s k

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.

TFSISO 363

C++ Statements

Caution:

form is typically not robust for higher-order systems. Such systems should be used

only when you are confident that the problem is well-posed. An alternate approach

more suited to Adams/Solver (C++) would be to break up (factor) the large

transfer function into a series of smaller ones in separate TFSISO statements.

Note that, if the output equation defined by the TFSISO statement has no solution

or 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

Adams/Solver leads to an unobservable but controllable state space realization.

Adams/Solver (C++) models containing such elements when tested for

observability in control design software are indicated having some unobservable

portions. You should perform any pole-zero cancellation prior to defining the

TFSISO data.

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

ARRAY/100, X

ARRAY/101, U, VARIABLE=101

ARRAY/102, Y

VARIABLE/101, FUNCTION=ACCZ(5,99,5)

364 Adams/Solver

C++ Statements

, NUMERATOR=1.0, DENOMINATOR=100.0,10.0,1.0

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.

TITLE 365

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.

366 Adams/Solver

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

UNITS 367

C++ Statements

Arguments

KILOGRAM_FORCE, KNEWTON,

KPOUND_FORCE, MEGANEWTON,

MICRONEWTON, MILLINEWTON,

NANONEWTON, NEWTON,

OUNCE_FORCE, POUND_FORCE,

POUNDAL}

conjunction with LENGTH, MASS, and TIME.

LENGTH = {ANGSTROM,

CENTIMETER, FOOT, KILOMETER,

INCH, METER, MICROINCH,

MICROMETER, MILE, MILLIMETER,

MILS, NANOMETER, YARD}

conjunction with FORCE, MASS, and TIME.

KPOUND_MASS, MILLIGRAM,

MICROGRAM, NANOGRAM,

OUNCE_MASS, POUND_MASS,

SLINCH, SLUG, TONNE, US_TON}

conjunction with FORCE, LENGTH, and TIME.

NONE}

each unit individually. MKS implies meter, kilogram,

second and newton. CGS implies centimeter, gram,

second and dyne. FPS implies foot, pound mass, second

and pound force. IPS implies inch, pound mass, second

and pound force. NONE implies that the dataset is

written non dimensionally and that Adams/Solver (C++)

sets UCF = 1.

MILLISECONDS, MINUTE,

NANOSECOND, SECOND}

conjunction with FORCE, LENGTH, and MASS.

UCF = r

prefer to work in a system of units not covered by any of

the choices listed above. The UCF is the conversion

factor from model mass units to dynamical mass units as

shown by the following equation:

Mass

Force = ------------- Acceleration

UCF

Examples of how to calculate the UCF for your choice of

units are given below in the Extended Definition of the

UNITS statement.

368 Adams/Solver

C++ Statements

Extended Definition

The UNITS statement sets the appropriate units for an Adams/Solver (C++) analysis and allows

Adams/View to account for your choice. Usually the choice of units is simply a matter of preference or

convenience. However, sometimes the choice of units can significantly affect the solution calculated by

Adams/Solver (C++), or even whether a solution can be found. The reasons for this are related to the scale

of the problem, as discussed below.

In most cases, you select a system of units by using the SYSTEM argument or the FORCE, MASS,

LENGTH, and TIME arguments. For cases not covered by the predefined choices, specifying the

appropriate UCF still allows Adams/Solver (C++) to make correct calculations. Note that if the UNITS

statement is not used in a model, Adams/Solver (C++) will treat the model the same as if the UNITS

statement were used to specify SYSTEM = NONE. Adams/Solver (C++) always uses radians as the unit

for angular measurements.

Understanding the UCF

Adams/Solver (C++) always calculates and uses a UCF, even when you don't use the option to specify it

explicitly. It is worth understanding how this works because it can help you select the appropriate units

for a model that may suffer from scaling problems.

To discuss the UCF, let us define the terms model units and dynamical units. Model units are whatever

choices you make for units for force, mass, length, and time. That is, you write you model using model

units. Dynamical units are any valid choice of units for force, mass, length, and time such that Newton's

2nd law (for a particle in one dimension)

F = MA

(1)

is true when written using that choice of units. The CGS and MKS options for the SYSTEM argument

of the UNITS statement are dynamical units. Model units may be dynamical units, but that is not a

requirement.

To work with model units that are not dynamical units, the UCF is defined to make Newton's 2nd law

valid with that choice of model units by dividing the inertia values by the UCF to account for the

inconsistency of the model units. To see why this is legitimate, consider a system of model units (denoted

by the "primes") F', M', L', and T', and any valid system of dynamical units F, M, L, and T, where the

model units are related to the dynamical units by the scale factors sF, sM, sL, and sT:

sFF' = F

(2)

sMM' = M

(3)

s LL ' = 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

UNITS 369

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 sT2

UCF = -----------sM sL

(8)

to combine the four scale factors into one, Equation (7) can then be rewritten as

M'

F' = ------------ A'

UCF

(9)

So, in what units does Adams/Solver (C++) actually express equations to perform computations? For

quantities of force, length, and time, the units for computations are the same as model units. For

quantities of mass and rotational inertia, they are model units divided the UCF. (Note that quantities of

angle are always expressed in radians for internal computations. It is not possible make another choice

with Adams/Solver (C++).)

What if multiple systems of model units have the same UCF, as for the SYSTEM choices of CGS and

MKS: how does Adams/Solver (C++) "know" which it is using? The answer is, it does not, at least as far

as the solving the equations of motion are concerned. But, you as the modeler must know what model

units you have chosen. You will write your model with force, mass, length, and time expressed in these

units, which will affect the numerical values of model parameters such as spring and damping rates.

Forces and torques expressed in model units will then cause inertias expressed in model units, divided by

the UCF, to have translational and angular accelerations in model units. The first and second integrals of

the accelerations will then lead to translational and angular velocities, and translational displacements in

model units. (To reiterate, angular displacements are always in radians.)

However, if you do use the UNITS statement to choose the force, mass, length, and time units explicitly,

or use the SYSTEM argument to choose one of CGS, FPS, IPS, or MKS, Adams/View will have

information about the model units. It can then use this information for pre- and post-processing, such as

for switching unit systems (even for angles) prior to sending a model to Adams/Solver (C++) for analysis,

and for putting unit-labels on output plots and charts. Thus, unless you must use the UCF argument for

the UNITS statement, it is recommended that you avoid doing so.

370 Adams/Solver

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

UNITS 371

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

(Value in model units) * SF = (Value in Newtons)

Model Units

SF

CENTINEWTON

0.01

DYNE

1.0e-5

KILOGRAM_FORCE

9.80665 ()

KNEWTON

1000

KPOUND_FORCE

4448.2216152605 (, )

MEGANEWTON

1.0e6

MICRONEWTON

1.0e-6

MILLINEWTON

0.001

NANONEWTON

1.0e-9

OUNCE_FORCE

0.27801385095378125 (, , )

POUND_FORCE

4.4482216152605 (, )

POUNDAL

0.138254954376 (, )

Depends on the definition standard gravity = 9.80665 m/s2, exactly.

It may seem that SF is approximate for the OUNCE_FORCE, but it turns out that 17 digits are just enough to represent it exactly.

372 Adams/Solver

C++ Statements

Table 2

(Value in model units) * SM = (Value in kilograms)

Model Units

SM

GRAM

0.001

KPOUND_MASS

453.59237 ()

MILLIGRAM

1.0e-6

MICROGRAM

1.0e-9

NANOGRAM

1.0e-12

OUNCE_MASS

0.028349523125 ()

POUND_MASS

0.45359237 ()

SLINCH

175.12683524647638 (, , )

SLUG

14.593902937206365 (, , )

TONNE

1000

US_TON

907.18474 ()

Depends on the definition standard gravity = 9.80665 m/s2, exactly.

Approximate to 17 digits.

Table 3

(Value in model units) * SL = (Value in meters)

Model Units

SL

ANGSTROM

1.0e-10

CENTIMETER

0.01

FOOT

0.3048

KILOMETER

1000

INCH

0.0254

MICROINCH

2.54e-08

MICROMETER

1.0e-6

MILE

1609.344

MILLIMETER

0.001

MILS

2.54e-05

NANOMETER

1.0e-9

YARD

0.9144

UNITS 373

C++ Statements

Table 4

(Value in model units) * ST = (Value in seconds)

Model Units

ST

DAY

86400

HOUR

3600

MICROSECOND

1.0e-6

MILLISECOND

0.001

MINUTE

60

NANOSECOND

1.0e-9

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.

374 Adams/Solver

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

user-written subroutine to define a variable. If you want to

define the variable with an expression, FUNCTION must be

followed with an equal sign and the expression. If you want

to define the variable with a user-written subroutine,

FUNCTION must be followed with an equal sign, the

character string USER, and the selected values (r1[,...,r30])

that Adams/Solver (C++) passes to the user-written

subroutine VARSUB.

IC = r

Adams/Solver (C++) may adjust the value of IC when it

performs an initial condition analysis. Entering an accurate

value for IC may help Adams/Solver (C++) converge to the

initial conditions solution.

ROUTINE = libname::subname

subroutine VARSUB.

Learn more about the ROUTINE Argument.

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.

VARIABLE 375

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:

functions. If a defined system of equations does not have a stable solution,

convergence may fail for the entire Adams/Solver (C++) model. The following

example refers to this type of VARIABLE statement:

VARIABLE/1, FUNCTION= VARVAL(1)+1

When looked at as an algebraic equation, it looks like the following:

V=V+1.

However, when Adams/Solver (C++) tries to solve this equation using the

Newton-Raphson iteration, the solution diverges and Adams/Solver (C++)

displays a message on the screen indicating that the solution has failed to

converge.

The IC argument should be used whenever a zero value might cause a floating

point exception or lead Adams/Solver (C++) away from the desired solution.

Examples

VARIABLE/4, FUNCTION = IMPACT(DZ(10,90),

, VZ(10,90), 1, 3E5, 1.2, 1,.05)

This VARIABLE statement defines an impact function. You may refer to this function as VARVAL(4) in

other function expressions. This may make the other expressions more concise and readable, and might

avoid repeated impact function calculations.

See other Generic systems modeling available.

376 Adams/Solver

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

VFORCE translational force. The direction of this component is

parallel to the x-axis of the RM marker.

FY=e

VFORCE translational force. The direction of this component is

parallel to the y-axis of the RM marker.

FZ=e

VFORCE translational force. The direction of this component is

parallel to the z-axis of the RM marker.

force components in a user-defined subroutine VFOSUB.

I=id

action force. You must ensure that the I marker is a fixed marker

and on a different part than the JFLOAT marker. Because I is a

fixed marker, Adams/Solver (C++) always applies the force at a

fixed point on the part.

JFLOAT=id

reaction force. You must ensure that the JFLOAT marker is a

floating marker and on a different part than the I marker.

Adams/Solver (C++) moves the JFLOAT marker to keep it

superimposed on the I marker, which means that the reaction force

may move with respect to the part. Adams/Solver (C++) does not

calculate reaction forces when the JFLOAT marker is on the ground

part.

VFORCE 377

C++ Statements

RM=id

components. You must ensure that RM is a fixed marker. RM may

be the same as I and may be on any part in your system.

ROUTINE=libname::subname

VFOSUB.

Learn more about the ROUTINE Argument.

Extended Definition

The VFORCE statement creates an Adams/Solver (C++) translational vector force element that applies

a three-component force between two parts of the system. The element applies an action force to the part

to which the I marker belongs and a corresponding reaction force to the part to which the JFLOAT marker

belongs. The VFORCE statement establishes the position of the JFLOAT marker. As the system moves,

Adams/Solver (C++) moves the JFLOAT marker on its part to keep the JFLOAT and I markers

superimposed. Therefore, Adams/Solver (C++) applies the reaction force to the JFLOAT 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

Values:

where:

Fa is the action applied to the I marker

FX is the user-defined function defining the magnitude and sign of the x-component

FY is the user-defined function defining the magnitude and sign of the y-component

FZ is the user-defined function defining the magnitude and sign of the z-component

378 Adams/Solver

C++ Statements

Reaction

Applied to: JFLOAT marker

Values:

Fr = -Fa

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.

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.

VFORCE 379

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.

380 Adams/Solver

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

torque components in an externally-defined subroutine VTOSUB.

I=id

applies the action torque. You must ensure that the I marker is a

fixed marker and on a different part than the JFLOAT marker.

JFLOAT=id

applies the reaction torque. You must ensure that the JFLOAT

marker is a floating marker and on a different part than the I marker.

Adams/Solver (C++) moves the JFLOAT marker to keep it

superimposed on the I marker. Adams/Solver (C++) does not

calculate reaction forces when the JFLOAT marker is on the ground

part.

RM=id

components. You must ensure that RM is a fixed marker. RM may

be the same as I and on any part in the system.

ROUTINE=libname::subname

VTOSUB.

TX=e

exerted by the VTORQUE element. The direction of this torque

component is parallel to the x-axis of the RM marker in the sense of

the right-hand rule (that is, a positive torque causes a

counterclockwise rotation).

VTORQUE 381

C++ Statements

TY=e

exerted by the VTORQUE element. The direction of this torque

component is parallel to the y-axis of the RM marker in the sense of

the right-hand rule (that is, a positive torque causes a

counterclockwise rotation).

TZ=e

exerted by the VTORQUE element. The direction of this torque

component is parallel to the z-axis of the RM marker in the sense of

the right-hand rule (that is, a positive torque causes a

counterclockwise rotation).

Extended Definition

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

Values:

where:

Ta is the action applied to the I marker

TX is the user-defined function defining the magnitude and sign of the x-component according

TY is the user-defined function defining the magnitude and sign of the y-component according

382 Adams/Solver

C++ Statements

TZ is the user-defined function defining the magnitude and sign of the z-component according to

Reaction

Values:

Tr = - Ta

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.

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

VTORQUE 383

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.

- R Programming Course NotesUploaded byXayden
- Backtest Your Trading Strategies White PaperUploaded bybloombm1
- REXXUploaded byjaya2001
- TSMP4002 - SmartPlant 3D Programming II Labs v7 SP4Uploaded byLin Xi
- PLAXIS Tutorial ManualUploaded byPeteris Skels
- Shimpo Able VRS BrochureUploaded byElectromate
- Ferris Wheel ReportUploaded byViknaraj Subramaniam
- DIN ISO Programming USer Manual 2010Uploaded byReymondo Bundoc
- harvard how to use scratchUploaded byRavish Aggarwal
- eTrust SeOSUploaded byBanda del Latigo
- C++ Lab ManualUploaded bychristine booduan
- QbasicUploaded byMadhunath Yadav
- Short Manual Turbo-prog v1.02_enUploaded byNicolae Popescu
- EnterpriseTrack_V8.0_Integration_API_Reference_Guide.pdfUploaded byBhavish Parkala
- Delta Dynamic Object-Oriented Programming LanguageUploaded byWanderingGirl
- Fm Read_textUploaded byedmondo77
- C++Uploaded byajucool777xxx
- Share ParameterUploaded byWunNa
- Clone Rman COA v1.0 (2)Uploaded byborra venkatesh
- Ch7 Printer File FunctionsUploaded byMaran Ganapathy
- motor rf.pdfUploaded byedgar
- p 120 - 122Uploaded byNermeen Mohameed N M
- Ci Int Routing StatesUploaded byAlex Andwanda
- Ug60 Model Namelist 1.4Uploaded byfatimah
- Running Jobs ReportsUploaded bymboya2
- cos1512_201_2012_2_bUploaded byLina Slabbert-van Der Walt
- Functions.pptxUploaded byRyle Arbon
- Sub ProgramsUploaded byYuli Anggraini
- Session_6Uploaded byAravindh
- SIEMENS Put-GetUploaded byknightfelix12

- 1-s2.0-S2452321616000093-mainUploaded byNamelezz Shadoww
- E 274 - 97 _RTI3NA__Uploaded byNamelezz Shadoww
- Effect of proc cond on birefringence devl IM.pdfUploaded byNamelezz Shadoww
- Strain Gage Preparation Paper REF ASTMD3039Uploaded byNamelezz Shadoww
- JEC Forum Register FormUploaded byNamelezz Shadoww
- v-link-manualUploaded bysakthisrini
- Sim Ulia Installation GuideUploaded byamit raj
- 2006 Yu Tablets With Material Gradients Fabricated by Three-dimensional PrintingUploaded byNamelezz Shadoww
- Material Spec for 6600Uploaded byNamelezz Shadoww
- UL94 Flammability TestsUploaded byLuis Carlos
- 2501 Series Compression PlatensUploaded byNamelezz Shadoww
- e1188 Environmental Testing of Aerospace EquipUploaded byNamelezz Shadoww
- AC7122-P Rev BUploaded byNamelezz Shadoww
- AC7122-R Rev CUploaded byNamelezz Shadoww
- คู่มือ font-install-7Uploaded byNamelezz Shadoww
- 26827_24249_Prepreg - ET445 Epoxy Matrix Prepreg - BNS.01.01.14Uploaded byNamelezz Shadoww
- Us 7117730Uploaded byNamelezz Shadoww
- 8th Gen Processor Family s Platform Datasheet Vol 1Uploaded byNamelezz Shadoww
- 8th Gen Processor Family s Platform Datasheet Vol 1Uploaded byHoang Nguyen
- Tyre Classification Tyre Size DesignationUploaded byNamelezz Shadoww
- RIVAS Sleepers RO Tests UIUC Champaign 06 2014Uploaded byNamelezz Shadoww
- Modulus-of-Elasticity.pdfUploaded byNamelezz Shadoww
- Robert WagonerUploaded byAnonymous AnQvu46
- Complete Guide to ChainUploaded byVijay Gohil
- PneumaticTire_HS-810-561Uploaded byScott Kimbrough
- Metric UnitsUploaded byNamelezz Shadoww
- Shen and Korpus - 2015 - Numerical Simulations of Ship Self-Propulsion andUploaded byNamelezz Shadoww
- Guidelines-for-writing-thesis-or-dissertationUploaded bybernadeth_rema
- 24th IKV International Plastics Technology ColloquiumUploaded byNamelezz Shadoww

- Physics Mechanics 110A notes UCSDUploaded byChris Werry
- 3 1 paired data and graphing ordered pairsUploaded byapi-233527181
- An Intuitive Explanation of Medial Axis TransformationUploaded byatom
- Lin Alg Lecture NotesUploaded bypattyq12
- ASCE 70-5 WINDUploaded bynarasimmans
- combinepdf.pdfUploaded byAlexander Monroe
- super hero transformation projectUploaded byapi-394725139
- NovometUV User Guide in EnglishUploaded byOscar Castro
- 2012-1813. DH Representation - ExamplesUploaded bymodisuryaharsha
- Lab Notebook Policy and Format for Chemistry Lab ReportsUploaded byyumt
- rr10107-engineering-graphicsUploaded bySRINIVASA RAO GANTA
- CG-Question-Bank.docUploaded byPratik Chatterjee
- Numerical Control systemUploaded byHimanshu
- Staad Pro NotesUploaded byAnonymous nwByj9L
- Space MatrixUploaded byLaaj Chaudhry
- Polymath TutorialUploaded byAbdi Rageedi
- Maths - Must Do (60%) Year 8 (08 Oct 2009)Uploaded byYenny Tiga
- Visual Effects and CompositingUploaded bytan nguyen
- DrawingPrintingiOSUploaded byWovgh Last
- Nonlinear Analysis of Transmission Towers 1992Uploaded bycisco
- BK2 Chapter 1 Coordinate geometry.pdfUploaded byFathima Nusrath
- 3D-Geometry-13-14Uploaded bypreetam
- SAT II Math Level 2 Subject Test Notes: FunctionsUploaded bytomcantyyy
- 5_ Problem Solving ManualUploaded byJuan Pablo Azcuña C.
- ANALYSIS OF ROOF BOLT SYSTEMS.pdfUploaded byjulio1051
- E-book Visual Analytics MovementUploaded byim lia
- ArcWelding OM 3HAC028931-EnUploaded bymartinimartiini
- AeroAcquire_Manual_3.6Uploaded byglowingbrakes
- IEC61131-3 Motion Library (Chapter 3)Uploaded byMican Doru
- Kupdf.com Class 10 Nso 5 Years e Book14Uploaded byAAVANI