Using the Adams/View Function Builder 1

Using the Adams/View Function Builder

The Adams/View Function Builder is a versatile tool inside of Adams/View, part of the MD Adams
2010® suite of software, that lets you write expressions, functions, and subroutines to define forces,
measures, and motion in Adams products. You can create and modify functions and parameterize values
for various entities.
This section provides references and procedures for writing expressions, functions, and subroutines using
the Function Builder in Adams/View.
2 Adams/View Function Builder
Learning Function Builder Basics

Learning Function Builder Basics

You use two major types of functions in the Function Builder: design-time and run-time functions.
Depending on the type of function you want to use, you can work either in the expression mode or the
run-time mode of the Function Builder.
• Types of Functions
• Function Builder Modes

Types of Functions
The following two sections provide details about the two major types of functions you can use in the
Function Builder:
• Design-Time Functions
• Run-Time Functions

Design-Time Functions
Design-time functions allow you to parametrically configure your model for optimization and sensitivity
studies. Adams/View evaluates design-time functions only during the design process, and not during a
simulation, except for optimization and design studies.
The Function Builder gives you access to over two hundred design-time functions. In addition, you can
create your own user-written functions. The Function Builder categorizes all system-supplied functions
based on their functionality. The following table lists the design-time functions categories:
Design-Time Function Categories

Category:
Math Functions
Location/Orientation Functions
Modeling Functions
Matrix/Array Functions
String Functions
Database Functions
Miscellaneous Functions

Besides the categories listed above, the Function Builder includes a category called All Functions that
lists all design-time functions in alphabetical order.
For more information and examples for each design-time function, see Design-Time Function
Descriptions.
 Using the Adams/View Function Builder 3
Learning Function Builder Basics

Run-Time Functions
Run-time functions allow you to specify mathematical relationships between simulation states that
directly define the behavior of your model. Adams updates the run-time functions only during a
simulation.
The Function Builder gives you access to over one hundred run-time functions, that it categorizes based
on their functionality. The following table lists the run-time functions categories:
Run-Time Function Categories

Category:
Displacement Functions
Velocity Functions
Acceleration Functions
Contact Functions
Spline Functions
Force in Object Functions
Resultant Force Functions
Math Functions
Data Element Access
User-Written Subroutine Invocation
Constants & Variables

Besides the categories listed above, the Function Builder includes a category named All Functions. This
category contains all the run-time functions, grouped by functionality.
For more information and examples for each run-time function, see Run-Time Function Descriptions.

Function Builder Modes

The Function Builder has two different modes: expression mode and run-time mode. Adams/View gives
you access to the appropriate Function Builder mode based on the type of operation you want to perform.
The following table shows what types of operations you can perform in each mode.
Operations and Function Builder Mode

For this operation: Use this mode:

Building Expressions Expression
Creating or Modifying Computed Measures Expression
4 Adams/View Function Builder
Learning Function Builder Basics

For this operation: Use this mode:

Building Design-Time Functions Expression
Building Run-Time Functions Run-time
Creating or Modifying Function Measures Run-time

The following two sections introduce you to the Function Builder modes:
• Expression Mode
• Run-Time Mode

Expression Mode
In expression mode you can create expressions, which are the basis of all parameterization. Adams
updates expressions when it detects that dependencies have been changed. Performing optimization and
design studies can affect the dependencies for some expressions.
In addition to design-time functions, expressions can include the following elements:
• Design variables
• Operators
• Operands
• Database Access

For detailed information on expressions and their elements, see Expression Language Reference.
To learn more about the expression mode, see Working in Expression Mode.

Run-Time Mode
When working in run-time mode, the Function Builder allows you to combine run-time functions with a
variety of elements to build functions. After you define the functions, Adams/Solver uses them during
the simulation process.
The following sections introduce you to the run-time function elements.
• Design Variables
• Numerical Values
• Operators

Design Variables
Design variables are a means of storing data that you can later use and modify. You can use design
variables throughout the Adams/View command language. For example, you can define the radius of a
cylinder in terms of a design variable:
 Using the Adams/View Function Builder 5
Learning Function Builder Basics

variable create variable=my_radius real=40 units=lengthgeometry

modify shape cylinder &cylinder_name =
.model_1.PART_1.CYLINDER_1 &radius = (my_radius)
For more information on design variables, see Expression Language Reference.
Numerical Values
In run-time mode you can use integers and real numbers. Adams doesn't support complex numbers at this
time.
Operators
You can use the standard set of FORTRAN operators in the functions you create in run-time mode. The
operators table below lists the operators Adams/View supports in this mode. The table lists the operators
by precedence, with grouping being the highest precedence operator.
• Different from FORTRAN convention, when in run-time mode, the unary minus operator has
precedence over the exponentiation operator, and exponentiation associates from left to right.
Operators

This operator: Has this role:

() Grouping
- Unary minus = negation
** Exponentiation
/ Division
* Multiplication
+ Addition
- Subtraction

To learn more about the run-time mode, see Working in Run-Time Mode.

Accessing the Function Builder

You can access the Function Builder in different ways, depending on the operation you are performing.
Adams/View displays the Function Builder in either the run-time or expression mode, reflecting the way
you accessed it. For an overview of the Function Builder modes, see Learning Function Builder Basics.
The following table shows what types of operations you can perform in the expression mode, and how
you can access it:
6 Adams/View Function Builder
Learning Function Builder Basics

Accessing the Expression Mode for Basic Operations

To do the following: Access the expression mode from:

Build expressions The Build menu
Create or modify computed measures The Build menu
Build design-time functions Text boxes that accept expressions

The following table shows what types of operations you can perform in the run-time mode, and how you
can access it:
Accessing the Run-Time Mode for Basic Operations

To do the following: Access the run-time mode using:

Create or modify function measures The Build menu
Build run-time functions Text boxes that accept run-time functions

The following sections provide step-by-step instructions on accessing the Function Builder modes:
• Working in Expression Mode
• Working in Run-Time Mode

Working in Expression Mode

You access the Function Builder in expression mode in several ways, depending on the operation you are
performing. The Function Builder might look slightly different depending on the operation for which you
intend to use it. For example, if you open the Function Builder to build a custom function, you'll notice
that it includes boxes for entering general attributes for functions.
For information on design-time functions, functions you can use in expression mode, see Design-Time
Function Descriptions.

In expression mode you can perform three basic types of operations:

• Building Expressions
• Creating or Modifying Computed Measures
• Building Design-Time Functions

Building Expressions
You use the expression mode when you want to build expressions to use in various operations. Some of
the operations for which you can use expressions include parameterizing values for point and marker
 Using the Adams/View Function Builder 7
Learning Function Builder Basics

locations, parameterizing values for geometry dimensions, and working with design variables. For more
information on expressions, see Expression Language Reference.
To perform such operations, you can access the expression mode from the pop-up menus of boxes that
can be parameterized.

To access the expression mode from a box:

1. Right-click any box that accepts expressions, point to Parameterize, and then select Expression
Builder.

The Function Builder appears in expression mode, as shown next.

2. Build your expression, and then select OK.

Adams/View inserts the expression in the box from which you displayed the Function Builder.

Creating or Modifying Computed Measures

If you want to create or modify computed measures, you use the expression mode of the Function
Builder. To create or modify computed measures, access the expression mode from the Build menu, as
shown below:
To access the expression mode from the Build menu:
8 Adams/View Function Builder
Learning Function Builder Basics

1. From the Build menu, point to Measure, point to Computed, and then select New.

The Function Builder appears as shown next

2. Create your computed measure, and then select OK.

Building Design-Time Functions

You can also use the expression mode when you want to build custom functions. To build functions, you
can access the expression mode from the Build menu.
To access the expression mode from the Build menu:
 Using the Adams/View Function Builder 9
Learning Function Builder Basics

1. From the Build menu, point to Function, and then select New.

The Function Builder appears as shown next.

2. Create your custom function, and then select OK.

Working in Run-Time Mode

You can access the run-time mode of the Function Builder in several ways, depending on the operation
you want to perform. The Function Builder might look slightly different depending on the operation for
which you intend to use it. For example, if you open the Function Builder to build function measures, it
includes boxes for entering general attributes for the measure.
For information on run-time functions, functions you can use in run-time mode, see Run-Time Functions.
In run-time mode, you can perform two basic types of operations. In addition, you can set how
Adams/View references database objects.
• Setting Default Database Object References
• Building Run-Time Functions
• Creating or Modifying Function Measures
10 Adams/View Function Builder
Learning Function Builder Basics

Setting Default Database Object References

Run-time functions reference Adams/View objects using one of the following methods:
• The object's full name. For example: DX(.Model_1.Part_2.Mar_15).
• The object's short name, which is only that portion of the object's name required to uniquely
identify it. For example, if a marker is the only marker named Mar_15 in your model, then only
MAR_15 appears. For example: DX(Mar_15).
If, however, you have several parts with markers named Mar_15, then the part to which
the marker belongs and its name appear. For example: DX(Part_2.Mar_15).
• The object's Adams ID, which is an integer used to identify the object in the Adams/Solver
dataset (.adm) file. For example: DX(15).
The option you choose determines whether Adams/View uses full object name, short object names, or
Adams IDs when displaying run-time functions in the Information window and in the Modify dialog
boxes. This option also determines the naming the Function Builder Assist box uses for object names or
Adams IDs to generate run-time functions.
• Regardless of the option you select, you can enter the object's full or short name or its Adams ID
while writing functions.

To set the default function references:

1. From the Settings menu, select Names.

The Defaults Name dialog box appears.

2. Select the desired option.
3. SelectOK.

Building Run-Time Functions

You use the run-time mode of the Function Builder when you want to build run-time functions to use in
various operations. Some of the operations for which you can use run-time functions include working
with applied forces, motions, and differential equations. To perform such operations, you can access the
run-time mode of the Function Builder from the pop-up menus of boxes that accept run-time functions.
For example, to build functions for motions, you access the run-time mode as described next.
 Using the Adams/View Function Builder 11
Learning Function Builder Basics

To access the run-time mode from a box:

1. Right-click any box that accepts run-time functions, and then select Function Builder.

The Function Builder appears as shown next.

2. Create a function, and then select OK.

Adams/View inserts the function in the box from which you displayed the Function Builder.

Creating or Modifying Function Measures

You can also use the run-time mode when you want to create or modify function measures. To create or
modify function measures, you can access the run-time mode of the Function Builder from the Build
menu, as explained next.
12 Adams/View Function Builder
Learning Function Builder Basics

To access the run-time mode from the Build menu:

1. On the Build menu, point to Measure, point to Function, and then select New.

The Function Builder appears as shown next.

2. Create or modify your function measure, and then select OK.

 Using the Adams/View Function Builder 13
Performing Operations in the Function Builder

Performing Operations in the Function Builder

The Adams/View Function Builder lets you perform many operations to help you build functions and
create and modify measures. The Function Builder Operations table below provides a quick overview of
the Function Builder operations and the modes in which they are supported.
For an overview of the Function Builder, see Learning Function Builder Basics. For information on the
Function Builder modes, see Accessing the Function Builder.
Function Builder Operations

This operation: Available in this mode:

Getting Data Owned by an Object Expression
Evaluating Functions Expression
Setting Plot Limits Run-time
Verifying Function Syntax Run-time
Setting Measure Attributes Both
Creating a Measure Strip Chart Both
Getting Object Data Both
Plotting Functions Both
Getting Assistance Both
Inserting Operators in Function Definitions Both
Displaying System-Supplied Function Categories Both

The following sections explain the Function Builder operations and also provide some examples of
common Function Builder uses:
• Function Builder Operations
• Example - Building Functions for Motions
• Example - Parameterizing Values for Marker Locations

Function Builder Operations

The Function Builder can perform a variety of operations to help you build functions and expressions,
depending on its current mode. Read the following sections for details on the Function Builder
operations:
• Getting Object Names and Data Dictionary
• Evaluating Functions
• Plotting Using the Function Builder
14 Adams/View Function Builder
Performing Operations in the Function Builder

• Verifying Function Syntax

• Setting Measure Attributes
• Creating a Measure Strip Chart
• Getting Assistance
• Inserting Operators in Function Definitions
• Displaying System-Supplied Function Categories

Getting Object Names and Data Dictionary

The following two sections explain how you can get an object's name and data dictionary:
• Getting Object Data
• Getting Data Owned by an Object

Getting Object Data

When working in either expression or run-time mode, the Function Builder allows you to get a specific
object name and insert it into the function definition. When working in expression mode, after you get
an object name, you can display its data dictionary. For information on obtaining an object's data
dictionary, see Getting Data Owned by an Object.

To get object data:

1. From the option menu located under the Getting Object Data label, select the desired object type.
2. Right-click the text box to the right of the object type you chose in Step 1, point to the object type
name, and then select Browse to look for an object name.

To insert an object name into the function definition:

After you've specified the object name, you can insert it into the function definition.
 Using the Adams/View Function Builder 15
Performing Operations in the Function Builder

• Select Insert Object Name.

Adams/View inserts the name of the object in the function definition, in the function work area.

Getting Data Owned by an Object

When in expression mode, the Function Builder enables you to get the data owned by an object and use
it in a function definition. The list containing the data owned by objects and the aliases associated with
them, is called the data dictionary.
If you want to use a certain data object in the function definition, you can browse for it in the data
dictionary, and once you find it, insert it in the function work area.
16 Adams/View Function Builder
Performing Operations in the Function Builder

To access the data dictionary:

1. Select Get Data Owned by Object.

The Selections dialog box appears, containing the data dictionary associated with the object you
specified, as shown next.

Data Dictionary for Markers

2. Select an item from the data dictionary.

3. Select OK. Adams/View inserts the item into the function text area.

Evaluating Functions
When in expression mode, the Function Builder gives you the option to see the values to which your
functions evaluate.

To evaluate a function:
1. Make sure there is a function in the function text area.
 Using the Adams/View Function Builder 17
Performing Operations in the Function Builder

2. Select Evaluate.
Adams/View displays the value of the function next to Function Value.

Plotting Using the Function Builder

Using the Function Builder, you can plot the values of some functions. The following two sections
explain how to plot functions using the Function Builder.
Plotting Functions
Adams/View gives you the option to preview a plot of your function. You can use the plotting feature
whenever your function evaluates to multiple values.
When in run-time mode, time is presumed to be the independent variable when plotting a function (for
example, SIN(TIME)).
To plot a function:
1. Make sure you have a correct function in the function work area.
2. Select Plot.
Adams/View displays a plot of your results.

Note: You can only plot the run-time functions that are in the math category and can be
interpreted as design-time functions.

Setting Plot Limits

When in run-time mode, you can set limits for the horizontal axis values. Adams/View plots the
independent data on the horizontal axis.

To set plot limits:

1. Make sure that there is a correct function in the function work area.
18 Adams/View Function Builder
Performing Operations in the Function Builder

2. Select Plot Limits.

A dialog box appears, prompting you for the values that you want to use.

3. Enter the beginning and ending values and the number of points to be computed, and then select
OK.

Verifying Function Syntax

When working in run-time mode, you can do a cursory check to determine if your function syntax is
correct. If the function syntax is incorrect, Adams/View gives you an error message pointing out the
problem area. Otherwise, it informs you that the function syntax is correct.

To verify function syntax:

1. Make sure that there is a function in the function work area.
2. Select Verify.

Setting Measure Attributes

When creating or modifying a computed or a function measure, you can set measure attributes to be used
when plotting the measure for these three attributes categories:
• General - Specify the units and the legend text.
• Axis - Specify the text for the axis label, the axis type, as well as the lower and upper limit for
the axis.
• Curve - Specify the curve color, thickness, line type, and symbol.
 Using the Adams/View Function Builder 19
Performing Operations in the Function Builder

To set measure attributes:

• Enter the desired attributes in the boxes provided, select attributes from the option menus, or
select default to use the Adams/View defaults.

Creating a Measure Strip Chart

When creating or modifying a computed or a function measure, you can choose to create a strip chart of
the measure.

To create a measure strip chart:

1. Create or modify the measure.
2. Select Create Strip Chart.
3. Select OK.
Adams/View displays a strip chart of your measure.
For more information on using strip charts, see Setting Up Strip Charts in Adams/View online help.

Getting Assistance
You can get assistance when working with system-supplied functions in either run-time or expression
mode. The Assist dialog box lists all the arguments specific to the function for which you need assistance,
and prompts you for argument values. Once you enter the argument values and close the Assist dialog
box, Adams/View automatically inserts those values into the function work area.
When entering values in the Assist dialog box, do not enclose them in parenthesis, braces, or quotation
marks. Adams/View automatically enters these as needed, before displaying expressions in the function
work area.
20 Adams/View Function Builder
Performing Operations in the Function Builder

To get assistance:
1. Select a function from the list of system-supplied functions.
2. Select Assist.
The Assist dialog box appears.

Note: There are a few functions for which Adams/View doesn't provide assistance. When you ask
for assistance with a function for which assistance is not available, a message appears.
Select OK to exit the message dialog box.

Inserting Operators in Function Definitions

Regardless of whether you are in expression or run-time mode, you can use the Operators tool to
insert operators in the function definition, in the function work area.

To insert operators in a function definition:

1. Right-click the Operators tool.

A pop-up menu displays the available operators.

2. Select the desired operator.

Adams/View inserts the operator in the function text area.

Displaying System-Supplied Function Categories

When working in either expression or run-time mode, you can display a list of any system-supplied
functions. The math category is the default for both the run-time and the design-time functions. The
Function Builder lists the functions under their category name. To see all the functions in a given
category, scroll up and down the list of functions.
Table 1 lists the design-time functions categories and Table 2 lists the run-time functions categories.

Table 1. Design-Time Functions Categories

Category:
Math Functions
Location/Orientation Functions
Modeling Functions
Matrix/Array Functions
 Using the Adams/View Function Builder 21
Performing Operations in the Function Builder

Category:
String Functions
Database Functions
Miscellaneous Functions

Table 2. Run-Time Functions Categories

Category:
Displacement Functions
Velocity Functions
Acceleration Functions
Contact Functions
Spline Functions
Force in Object Functions
Resultant Force Functions
Math Functions
Data Element Access
User-Written Subroutine Invocation
Constants & Variables

To display system-supplied function categories:

1. Select the functions option menu, and then select the desired category.

The Function Builder displays the list of functions beneath the category name.
22 Adams/View Function Builder
Performing Operations in the Function Builder

2. Select the desired function from the list.

The function name and arguments appear under the function list.
 Using the Adams/View Function Builder 23
Expression Language Reference

Expression Language Reference

This section explains how you can use expressions in Adams/View to compute values or to parameterize
your model. Parametrization lets you keep the associativity between model objects.
Learn more about:
• Using Expressions in Adams/View
• Expression Syntax
• Circular Expression Updating
• Location and Orientation
• Arrays
• Units

Using Expressions in Adams/View

You use expressions in Adams/View in the expression mode of the Function Builder. Expressions are
combinations of constants, operators, functions, and database object references, all enclosed in
parentheses. In Adams/View you can use expressions to specify parameter values, such as locations of
markers or functions of motions.
Adams/View uses expressions for two purposes:
• To compute values for you, such as when you are entering the radius of a cylinder and the value
is not a simple number, but is the result of a mathematical computation. Instead of using a
calculator to determine the actual number, you can enter the expression directly and let
Adams/View perform the computation for you.

• To parameterize your model. Expressions can contain references to other data values in
Adams/View. These expressions do not remain constant; Adams updates them each time the
referenced data changes. Using expressions in this way allows you to make changes to one value
and have this change propagate throughout your entire model. This is called parameterizing your
model. If you are familiar with spreadsheets, this is identical to defining a cell as a function of
another cell.
You construct Adams/View expressions during model building. When Adams/View reads an expression,
it either evaluates it and stores the value in its database, or stores the expression itself.
Adams/View includes variable objects intended for use with expressions. When creating an Adams/View
variable, you give it a name and a value. You can then include this variable, by name, in expressions; if
you change the value of the variable, then Adams/View updates the expression. In fact, any design
variable or other object that changes will cause any expression that used it to re-evaluate. This allows you
to parameterize your model using design variables. You can use such a parameterized model to do design
studies, design of experiments, and optimizations.
Learn more (Expression Example).
24 Adams/View Function Builder
Expression Language Reference

Expression Syntax
The following sections introduce the elements you can use in expressions, and their proper syntax:
• Data Types
• Operands
• Accessing the Database
• Data Dictionary
• Operators
• Naming Conflicts

Data Types
All operands and the computed values of expressions are data that have a particular type. For information
on operands, see Operands. There are five data types that Adams/View expressions support: integer, real,
string, matrix, and database object references. You can combine data of different types in an expression
and Adams/View coerces the data to the type needed to evaluate the expression. The following table lists
the data types and their use.

Data type: Use:

Integer Whole numbers in the range -maxint... +maxint, where maxint is machine dependent
(usually around two billion)
Real Most numeric values
String Character strings of varying length
Object Database objects
Matrix One or two-dimensional collections of values of the same type, or one of the above
types

Operands
Operands allow you to indicate what you want to operate on. The kinds of operands allowed in
Adams/View expressions are:
• Literal Constants
• Symbolic Constants
• Functions
• Database Objects and Their Component Values

Literal Constants
The first kind of operand is a literal constant value. Here are some examples of literal constant values:
 Using the Adams/View Function Builder 25
Expression Language Reference

Constant Value Examples

Constant value: Example:

Integer 2
Real 3.2
String "x"
Object .model_1.part_5.marker_13
Matrix - Array of strings {"x", "y"}
Matrix - Array of reals {[35,0], [3,6], [1,5]}

Symbolic Constants
The second kind of operand in an Adams/View expression is the symbolic constant. Adams/View defines
some frequently used constants with mnemonics, so you can use them easily and uniformly in your
expressions. The table below lists the symbolic constants and their values.
Symbolic Constants

This constant: Has this value:

TRUE or YES or ON 1
FALSE or NO or OFF 0
PI  = 3.1415
HALF_PI   2 = 1.5707
THREE_HALVES_PI  3   2 = 4.7122
TWO_PI 2 = 6.283
SIN45 sin    4  = 0.0137
SQRT2 2 = 1.414
RTOD 180   = 57.2974
DTOR   180 = 0.0174
VERSION [Adams Release Version #]
NONE see explanation below

NONE is a constant that behaves in a unique way. It can be coerced to any type and allows you to erase
values from the database when used in certain contexts.
If used in arithmetic expressions, NONE equates to zero (10 + NONE is equal to 10). If used in string
expressions, NONE is the empty string. Both of these facts can occasionally be useful in forcing type
conversion of some value. For instance, the concatenation operator (//) takes a pair of strings and
26 Adams/View Function Builder
Expression Language Reference

concatenates them into one: NONE // 2 forces the number 2 to become a character string, and NONE +
"10" forces the string "10" to become the number 10.
The real power of the NONE constant is evident when it is used by itself in an expression, as shown by
the following example.
Certain physical parameters of a model make a distinction between the value zero and a non-existent
value. This is especially true during the solution of initial conditions of a model. Assume that you have
an example model consisting of two parts joined together with a fixed joint. An initial conditions solution
computes the initial velocities of these parts. If you assign one of the parts an explicit velocity, then
Adams/Solver sees that the two parts are constrained and sets the initial velocity of the other. This can
only work if the second part has no velocity; if its velocity is undefined.
This command says that this part is not moving in the x direction, so its velocity is zero:
part modify rigid_body initial_velocity part=part_2 vx=0.0
The following command says that the velocity of this part is undefined, so you must examine other parts
of the model to determine its initial velocity:
part modify rigid_body initial_velocity part=part_2 vx=(NONE)
In general, setting a parameter to NONE sets that parameter's value to non-existent.
Functions
A function is an operand that takes an argument list and computes a value based on the values contained
in the list. Each argument is an expression that is evaluated and then given to the function. Common
examples are SIN( ), SQRT( ), and ABS( ).
Adams/View offers a wide variety of system-supplied design-time functions. For a complete list of
design-time functions and how to use them, see Design-Time Functions.
The EVAL function is a special purpose design-time function that allows removal of subexpressions and
dependencies from an expression. EVAL computes the value of its argument, without type coercion, and
replaces itself with this value. This means that when you recall an expression from the database it never
contains an EVAL function.
For example, if you create a variable whose value contains EVAL:
variable create variable=test real=(EVAL (2+2) / EVAL (2*3))
the database value for this variable is (4/6) and this is exactly the same as typing:
variable create variable=test real=(4/6)
There are two reasons to use the EVAL function:
• To eliminate costly recomputation of constant subexpressions. For example:
(EVAL(SQRT(2.2) + SIN(.55) + ATAN2(3,2)) + x)
is replaced by:
(57.8027713349 + x)
 Using the Adams/View Function Builder 27
Expression Language Reference

Note that the second expression is significantly faster, but lacks the readability of the
first. It's very difficult to determine how Adams derived the constant 57.8027713349,
and without some documentation you would never guess that it is actually the value
SQRT(2.2) + SIN(.55) + ATAN(3,2).
Therefore, you use EVAL on subexpressions only when you can measure real time-
savings, and document the resulting values thoroughly.
• To eliminate dependencies. You might encounter this problem when using loops:

for variable = XXX start=1 end=10

marker create marker=(UNIQUE_NAME("marker")) &
location=(EVAL(xxx)), 0, 0
end

If you don't use EVAL when defining the location of these markers, Adams
parameterizes them to the variable xxx and moves them at each iteration of the loop.
This would result in all of the markers being piled up at 10,0,0 after the loop terminated.
Database Objects and Their Component Values
Through expressions you can access most values stored in the Adams/View database, regardless of
whether you entered them through the command language or read them from a file. Adams/View lets you
access character strings, real numbers, integers, database objects, arrays, and boolean values.
To identify the database values you want to reference, use extensions of their Adams/View hierarchical
names by entering an entity's name and appending to it the name of the desired data field. The data an
object owns is listed in the data dictionary. For more information on the data dictionary, see Getting Data
Owned by an Object.

Accessing the Database

You can access the database to retrieve values from it to use in computing new values. To access the
database, use the dot name notation. You have access to character strings, real numbers, integer numbers,
database objects, arrays of real numbers and boolean values. In this release you do not have access to
option values. The following sections provide more information on database access:
• Syntax
• Syntax Examples
• Cautions
• Aliases

Reasons to access the Adams/View database values include using the:

• Volume of one object to determine the mass of another.
• Locations of two coordinate systems to compute the orientation of a joint.
• Name of an object to derive new names for its children. For example, the name of a marker
might be based upon the name of its parent part.
28 Adams/View Function Builder
Expression Language Reference

To identify the database values you want to reference, use extensions of their Adams/View hierarchical
names. This means you enter an entity's name and append the name of the desired data field to it. For
example, to access the mass of the part named .model_1.part_1 you would enter,
.model_1.part_1.mass
Based on this, Adams/View returns the real number value of the mass. We chose the name mass based
on the full parameter name we used to set its value in the Adams/View command language. That is:
part create rigid_body mass_properties part_name=.model_1.part_1
mass=1.0
When accessing the value of a design variable, you don't need the data field. For example, in the
following commands, the expressions in the second and third command return the same value:
variable create variable_name=DV_1 real_value=100
variable create variable_name=DV_2 real_value=(DV_1.real_value)
variable create variable_name=DV_3 real_value=(DV_1)
Syntax
There is no specific command associated with database access. Adams/View allows database access in
any command parameter where it allows an expression. See Learning Function Builder Basics, for more
information on using expressions in Adams/View.
In the references given below, the dot (.) is used to separate components in the hierarchical name (just as
it does in the current Adams/View command language). You must enclose this name in parenthesis, to
tell Adams/View to recognize it as an expression. Note that enclosing a run-time function in parenthesis
will not make it become an expression.
References can be either rooted or local. Rooted references have the following characteristics:
• Begin with a dot.
• Contain each specific component in the naming hierarchy (see the Rooted References table
below).
• Parse faster than local references because they can be found by looking at the highest level of the
database.
Rooted References

Database access: Type: Value retrieved:

.some_model.some_part.mass Real Mass of a part
.model_1.title String Title of model from .ADM file
.model_1.circle_1.sides Integer Number of sides of the circle
.model_1.part_1.location Array Three-element location array
.model_1.joint_1.i_marker Object The i_marker used in joint_1
 Using the Adams/View Function Builder 29
Expression Language Reference

Local references have the following characteristics:

• Begin anywhere in the hierarchy before the field name.
• Contain only enough names to specify the object uniquely (see the Local References table
below).
• Parse slower than rooted references because the entire database must be searched to find the
specified object.
• All database names are case insensitive, as are all other parts of the Adams/View command
language.
Local References

Database access: Type: Value retrieved:

some_part.mass Real The mass of some part
part_1.name String The name of the part--"part_1"
part_1.location[2] Real The second (y) element of location
marker_1 Object The marker_1 database object
coup.joint_name[indx].i_ Real The second location of the i marker of the joint that is
marker_name.location[2] at the indxth position in the coupler named coup

Syntax Examples
The following examples show the proper syntax for a variety of operations.
Setting a value:
part modify rigid_body mass_properties part=part_1 & mass=100!
Computing a mass:
part create rigid_body mass_properties part=part_2
& mass=(part_1.mass / 2.0)!
Computing a mass from a volume:
geometry create shape frustum frustum_name=fru_1
& top_radius=5 &
bottom_radius=10 &
length= 20part create rigid_body mass_properties part=part_2
&
mass=((fru_1.length * (fru_1.top_radius +
fru_1.bottom_radius) / 2)**2 *PI)
Cautions
If you create a marker named "location" on part_1, then the following ambiguity can arise:
(part_1.location) meaning the marker named "location"
30 Adams/View Function Builder
Expression Language Reference

or
(part_1.location) meaning the location field of part_1
The first interpretation in the above example is how Adams would treat the expression. The algorithm
used is:
1. Start at the database root and look for the first name, part_1 in this case.
2. Repeatedly look for a child object with the name following what you have already found, that is,
location.
3. If you can't find a child object in the database, assume the name is a field and look it up.
In this particular case, either interpretation of expression (part_1.location) is valid in most contexts, but
can produce very different results.
Aliases
You use aliases to reference fields on objects in the database. In addition to the parameters you see in
commands and panels, there are many aliases for the components of aggregate fields, as listed in the data
dictionary. (For more information on the data dictionary, see Getting Data Owned by an Object.) For
instance, a marker location is a three-element array of real numbers. It has three aliases: loc_x for the first
value, loc_y for the second, and loc_z for the third. In these cases you can enter the following:
marker create marker_name=new_marker
location=(old_marker.loc_x), 1, 0
or
marker create marker_name=new_marker
location=(old_marker.location[1]), 1, 0
When you use the alias (in the first example), the command executes faster, since no arithmetic has to be
done to index the array element.
The following fields list some examples of aliases:
part.location
marker.location

Indexed array: Alias:

alias location[1] loc_x
alias location[2] loc_y
alias location[3] loc_z
 Using the Adams/View Function Builder 31
Expression Language Reference

tire.inertia_moments

Indexed array: Alias:

alias inertia_moments[1] ixx
alias inertia_moments[2] iyy

For example, to obtain the x and y locations of Part_1, you could enter the following expression in the
Function Builder:
({(.model_1.PART_1.location[1]),(.model_1.PART_1.loc_y)})
In this case, Adams/View would return the location -50.0, -200.0.

Data Dictionary
The data dictionary lists the field names and the aliases associated with them, as they appear in
expressions. You can access the data dictionary through the Function Builder, as explained in Getting
Object Data.

Fields
Some database fields can't be parameterized. To determine if a specific field can be parameterized, try to
parameterize it and examine the result. If the result is a constant value, then that field can't be
parameterized. Adams/View evaluates any expression that you enter in a field, and stores its result in the
database.

Operators
You use operators to specify what you want to do to the operands. The operators table below lists the
operators supported in Adams/View expressions. They are listed by precedence, with grouping being the
highest precedence operator.

Note: Just as in FORTRAN, the exponentiation operator has precedence over the unary minus
operator, and exponentiation associates from right to left

Operators

Operator: It means:
() Grouping
[] Indexing. Any matrix or multi-valued database object can be indexed.
** Exponentiation
- Unary minus = negation
32 Adams/View Function Builder
Expression Language Reference

Operator: It means:
*/ Multiplication/division
@ Matrix multiplication
+- Addition/subtraction
Relational. These operators allow you to compare objects of the same type.

less than
< less than or equal to
<= equal to
== greater than
> greater than or equal to
>= not equal to
!=
! Logical NOT. True if operand is false.
&& Logical AND. True if both operands are not zero.
|| Logical OR. True if either operand is not zero.
// String/array concatenation. If either operand is a character string, the other is coerced
into a string, and they are combined. If one or both are arrays, then they are coerced to
arrays with like elements and concatenated using the STACK function (see the STACK
function example).

Real expressions containing integer division convert operands to real before division. This results in
values as Adams/View computes them, using mixed-mode arithmetic,
1.0 + 1/3 = 1.333
not as Fortran and C compute them,
1.0 + 1/3 = 1.0
Also, in Adams/View, 8/10 is equal to 0.8.
Whenever Adams/View encounters a value of an inappropriate type in an expression, it attempts to
coerce it to the proper type. If coercion fails, Adams/View doesn't evaluate the expression and generates
an error message. Operators determine coercion: the symbol + forces its operands to be numeric.
Coercion is not order-dependent. The following table provides coercion examples:
 Using the Adams/View Function Builder 33
Expression Language Reference

Coercion Examples

Expression: Result: Description:

2 + "2" 4 The character string is coerced to integer before
arithmetic is performed.
2 + 2 // 3 "43" Addition has higher precedence than concatenation;
numbers are coerced to strings before concatenation.

(2+2=4; 4//3=43)
marker_1 + 1 Error Cannot convert database object to integer.

Naming Conflicts
In Adams/View you can create objects with names matching symbolic constants or matching the name
of a data field of the created object. However, you should avoid doing this because it can make
expressions confusing. If you must, however, Adams/View has precedence rules for resolving these name
conflicts. Consider the commands:
model create model=model_1
part create rigid_body name_and_position part_name=PI
part create rigid_body name_and_position part_name=part_1
marker create marker_name=.model_1.part_1.location
The name of part PI matches the symbolic constant PI, and the marker name .model_1.part_1.location
matches the location field in the part named .model_1.part_1.
In the case of an object name being the same as a symbolic constant, using local names results in an error
because Adams/View looks for symbolic constants before database objects. Therefore, you need to use
a rooted name to access the objects. For example:
(PI.mass) Returns errors--PI is interpreted as a symbolic
constant
(.model_1.PI.mass) Returns the mass of part named PI
In the case of naming an object the same as a data field in the object being created, Adams/View always
returns the object instead of the field. For example, (part_1.location) returns the marker named location,
not the location of the part.

Circular Expression Updating

Adams/View monitors the values referenced by each expression. If you change a value used in an
expression, Adams/View immediately updates the expression.
When Adams/View evaluates an expression, it can in turn cause the value of other expressions to change.
Those expressions are re-evaluated to determine their new values. If an expression depends on its current
34 Adams/View Function Builder
Expression Language Reference

value (either directly or indirectly), evaluation could continue endlessly. To avoid problems,
Adams/View only resolves such expressions one level deep.
For example, take the following expressions:
variable create variable_name=I integer_value=1
variable create variable_name=J integer_value=(I+1)
variable create variable_name=K integer_value=(J+2)
variable modify variable_name=I integer_value=(K+3)
When variable I is modified to reference K, Adams/View determines that J depends on I and re-evaluates
the value of J. Next, Adams/View determines that K depends on J and re-evaluates the value of K. Finally,
Adams/View determines that I depends on K, but because I has already been updated, the re-evaluation
is complete. Since variables might update in a different order, you might get varying results at different
times.
It is possible to come up with expressions whose re-evaluation is unpredictable. Take, for example, the
following commands:
variable modify variable_name=J integer_value=(K+M)
variable modify variable_name=K integer_value=(J+M)
variable modify variable_name=M integer_value=200
The third modify command changes the value of M, causing the values of J and K to be recomputed once.
Their order of evaluation is unpredictable, hence the outcome of this computation is not defined and the
results are not reliable. Use the EVAL function in these situations to eliminate circular references.

Location and Orientation

Adams/View stores the positions (location and orientation) of objects in Cartesian/Euler coordinates,
relative to the parent of the object containing the position (a marker's location is stored relative to the
coordinate system of the part that owns the marker and all part locations are stored relative to the
coordinate system of the model that owns the parts). When positions are specified with literal values, not
expressions, Adams/View computes database values using the current unit settings, and the default
coordinate system (using the RELATIVE_TO parameter) before storing them.
When you use an expression to specify a position, Adams/View stores the expression directly. Therefore,
you must specify all position expressions consistent with how Adams/View stores the positions. If you
use an expression to specify the x, y, and z location of a marker, the coordinate system type must be
Cartesian.
When you reference location and orientation values in an expression, Adams/View uses their values
exactly as they are stored. If you reference the location of a marker, its value is in Cartesian coordinates
relative to its parent part.
You can use expressions to specify individual position components or an entire location or orientation.
An example of using an expression to specify an individual component of a location is:
marker modify marker=marker_1 &
location=(2*CYL1.length),3,5.
 Using the Adams/View Function Builder 35
Expression Language Reference

An example of using an expression to specify an entire location is:

marker modify marker=marker_1 &
location=(LOC_RELATIVE_TO({2*cylinder_1.length,0,0},marker_1)
).
Adams/View supplies functions to specify positions parametrically. Some functions transform the
locations and orientations from one coordinate system to another. Other functions allow you to
parameterize your model similar to the more complex Adams/View positioning features, such as
RELATIVE_TO, ALONG_AXIS, and IN_PLANE. Certain functions, such as LOC_RELATIVE_TO,
work independently of any local reference frame. If part, marker or other similar statements have a
location or orientation parameter, the RELATIVE_TO can modify the values you supply.
For example, you might execute the following statements:
part create rigid_body name_and_location create part=part_1 location=1,1,1
part create rigid_body name_and_location create part=part_2 location=2,2,2
marker create marker=marker_2 location=0,0,0 relative_to=part_1
The above statements place marker_2 on part_1. In this case, the RELATIVE_TO parameter modifies
the marker location you supplied.
When you use expressions for location or orientation, Adams/View ignores the RELATIVE_TO
parameter. In the following example, the RELATIVE_TO parameter plays no role for the location, but
does apply to the orientation, since it doesn't have an expression:
marker create marker=marker_3
location=(LOC_RELATIVE_TO({0,0,0}, part_1)) &
orientation=90d,0,0
relative_to=(Part_2)
Locating Objects in Both Absolute and Relative Terms
To allow you flexibility in entering locations and orientations for objects, such as parts and markers,
Adams/View lets you specify a relative_to reference frame.
For example, you might know where a particular marker should be placed in absolute space, or you might
know its location with respect to its part. In the first case, you could create the marker as follows:
marker create marker=.mod_1.part_1.marker_1
location=0,2,4 relative_to=.mod_1
In the second case, you would create the marker relative to part_1 to which it belongs:
marker create marker=.mod_1.part_1.marker_1
location=0,1,2 relative_to=.mod_1.part_1
This works for any reference frame (marker or part) that you might want. All you need to do is just create
an object (markers are convenient) at the correct location and with the correct orientation, then specify
new locations and orientations relative_to that object.
When defining the locations or orientation of objects using expressions, you cannot use a relative_to
reference frame. With the above commands, Adams/View transforms the information you supply for
location and relative_to into a location relative to the part that owns the marker, and discards the values
36 Adams/View Function Builder
Expression Language Reference

you entered. This loss of information is usually of no consequence, as you can easily reconstruct it (that
is, you can set relative_to to anything you want and see the location or orientation expressed in that
reference frame).
In both of the above cases, the value stored in the database for marker1's location is (0,1,2), and the value
you supplied in the relative_to parameter is discarded. (Not only is the location stored relative to the part,
it is also stored in Cartesian coordinates, so if you are using cylindrical or spherical coordinates on data
entry, that information is also discarded.) Expressions are not this easily manipulated. The original
information that you enter for a location expression must be maintained in the Adams/View database to
evaluate that expression.
This means that there are restrictions when you want to use expressions:
• You must set defaults units coordinate_system_type=cartesian.
• You must set defaults units orientation_type=body313.
• Any use of the relative_to parameter must be equivalent to system ground, as in
relative_to=.mod_1.
Here is an example of a common mistake made with relative_to locations. In the example, marker_3 on
part_3 must maintain its position in space but with respect to marker-2, which is on another part. It must
be located at a position 5.0 units along the axis of marker_2 using LOC_ON_AXIS to compute the
location of marker_3. See the diagram below.
 Using the Adams/View Function Builder 37
Expression Language Reference

marker create marker=.mod1.part_3.marker_3 &

location=(LOC_ON_AXIS(marker_2, 5, "X"))

Note: The text of the expression can break across lines.

However, LOC_ON_AXIS places the marker one unit off in the direction (it is at a global position of
(5,11,0) instead of the expected (4,11,0)). The LOC_ON_AXIS function computes a location in global
space, so when you use the results of this function directly to locate a marker, the marker might not
appear where you expect it. The solution is to use the results of the LOC_ON_AXIS function as an
argument to the LOC_RELATIVE_TO function, which transforms the global result into that which the
marker expects:
marker create marker=.mod1.part_3.marker_3 & location=
(LOC_RELATIVE_TO(LOC_ON_AXIS(marker_2, 5, "X"), .mod1))
Without this, the value is implicitly used relative to the owning part of the marker, therefore marker_3
appears in the wrong location.

Arrays
In the Adams/View expression language, an array is a collection of values of the same scalar type.
Array Examples

Array: Example:
{1, 2, 3} Array of integers
{"red", "green", "blue"} Array of character strings
{.model_1, .model_1.part_1, part_3} Array of objects
{1.2, 3.4, 5.6} Array of real numbers

Arrays of real numbers can be multi-dimensional. This type of array is called a matrix and is explained
in Matrices of Real Numbers.
When you create an array with elements of different type, Adams computes the element type to be the
least common denominator, that is, something that works for all of the elements. Here are the rules for
determining element type:
1. A string in an array forces all other elements to become strings:
{1, "red", marker_1} becomes {"1", "red",
".model_1.part_1.marker_1"}
2. If objects and numbers are mixed, the element type is string (since objects cannot be coerced to
numbers and numbers cannot be coerced to objects):
38 Adams/View Function Builder
Expression Language Reference

{0, marker_1} becomes {"0", ".model_1.part_1.marker_1"}

3. Mixed integer and real numbers are all converted to real numbers:
{1, 2.5, 3} becomes {1.0, 2.5, 3.0}
The next sections explain the different types of arrays.
• Empty Arrays
• Concantenating Arrays
• Matrices of Real Numbers

Empty Arrays
Adams/View allows arrays to be empty. This is denoted by a pair of braces {}.
variable create variable=list real=({})
Note that this is distinctly different than the use of NONE; the value of the variable named list is an array
that contains no values.
The following command creates a variable, named nothing, that contains an undefined value:
variable create variable=nothing real=(NONE)
The next section shows how such variables are different in a practical sense.

Concatenating Arrays
The concatenation operator works with arrays to attach one array to the end of another. The following
sequence of commands creates a variable, named list, that contains the 11 values from 10 to 20 (the
SERIES function would provide a more effective way of doing this):

variable create variable=list real=({})

for variable=value start=10 end=20
variable modify variable=list real=(EVAL(list // {value}))
end
The values resulting from the above example are: {10,11,12,13, ..... 20}.
If you create the initial value for list using NONE, as in the following example, you end up with a 12-
element array containing an undefined value as the first element, followed by the values 10 through 20.
variable create variable=list real=(NONE)
The values resulting from the above example are: {0,10,11,12,13,..... 20}. In this case, the undefined
value is 0.

Matrices of Real Numbers

Adams/View stores multi-valued parameter values as real-valued two dimensional matrices.
The following sections provide more information regarding matrices of real numbers:
 Using the Adams/View Function Builder 39
Expression Language Reference

• Entering Matrices in Expressions

• Indexing
• Database Fields Containing Multiple Data
• Operators On Matrices
• Scalar Math on Matrices

The way Adams/View stores parameter values is important because it allows you to use matrix
multiplication between any two real-valued arrays that have the proper shape. The following table shows
how Adams/View stores different parameter values.
How Multi-Valued Parameters are Stored

These parameter Are stored as: General math matrix

values: syntax:
Location and orientation
1
2
3
Polyline location lists Mx3 matrices
1 2 3
4 5 6
7 8 9
Adams/Solver dense-matrix MxN matrices
data elements 1 2 
3 4 
All other real-valued 1xN matrices
matrices (such as spline x 1 2 
values or curve y-axis data)

For example, if you've obtained a 3x3 transformation matrix via the TMAT function, you could use it to
define a polyline, polyline_3. Here, polyline_3's location matrix has been parametrically defined as being
dependent upon the array of polyline_2's location, and the angular orientation of marker_1.
40 Adams/View Function Builder
Expression Language Reference

Note: @ is the matrix multiplication operator.

Adams automatically converts a 1x1 matrix into a scalar if the context demands it, such as if the matrix
is being passed as a parameter to a function that requires a scalar.

Entering Matrices in Expressions

When entering parameter values that are not expressions, simply enter the numbers one after another. For
example, consider the polyline defined below by three points:
geometry create curve polyline polyline_name=polyline_1 &
location=({{1,2,3}, {4,5,6}, {7,8,9}})
or
geometry create curve polyline polyline_name=polyline_1 &
location=({[1,2,3], [4,5,6], [7,8,9]})
To enter a matrix in an expression, enclose the matrix in braces ({ }). Enter a multi-dimensional matrix
in braces ({ }) or brackets ([ ]), depending on whether you want to enter column-major or row-major
format, respectively. Each element inside a set of brackets denotes a row in the matrix. Each element
inside a set of braces denotes a column in the matrix.
 Using the Adams/View Function Builder 41
Expression Language Reference

Creating Matrix Expressions of Various Dimensions

General math matrix Matrix

Adams matrix syntax: syntax: dimension:
3x1
1
2
3
3x2
1 2
3 4
5 6
{[11,12,13], [21,22,23], [31,32,33]} = 3x3
11 12 13
21 22 23
{{11,21,31}, {12,22,32}, {13,23,33}}
31 32 33
{[1,2,3]} = {{1}, {2}, {3}} [1 2 3] 1x3

Indexing
Indexing allows you to reference elements within a matrix, as shown in the table below:
42 Adams/View Function Builder
Expression Language Reference

Indexing in Adams

Adams index Mathematical

syntax: description: Math result: Adams result:
Element in 2nd row, 8
1st column of the 3 x 9
1 matrix 8
7
{[5,4,3]}[1,2] Element in 1st row, 4
2nd column of the 1 5 4 3
x 3 matrix
{[8,9], [5,6]}[2,1] Element in 2nd row, 5
1st column of 2 x 2 8 9
matrix 5 6
{1,2,3}[2] Element in 2nd row, 2
(see Note below) of the 1
3 x 1 matrix 2
3

Note: You can omit the second index when a matrix is 1xN (1 row) or Nx1 (1 column).

You can use ranges of indexes to reference several elements of a matrix as shown in the table below:
Using Ranges of Indexes

Adams index Mathematical

syntax: description: Math result: Adams result:
{[1,2,3], [4,5,6], 2nd to 3rd rows of {[4,5], [7,8]}
[7,8,9]}[2:3,1:2] the 1st to 2nd 1 2 3
column 4 5 6
7 8 9

You can also extract a complete row of a matrix as shown in the table below:
 Using the Adams/View Function Builder 43
Expression Language Reference

Extracting a Complete Row

Adams index Mathematical

syntax: description: Math result: Adams result:
{9,8,7}[2] Element in 2nd row 8
in 3 x 1 matrix 9
8
7
{9,8,7}[2,1:1] Element in 2nd row, 8
1st column of 3 x 1 9
matrix 8
7
{9,8,7}[2,*] Element in 2nd row, 8
all columns of 3 x 1 9
matrix 8
7
{[8,9], [5,6]} [1,1:2] Element in 1st row, {[8,9]}
1st to 2nd column of 8 9
2 x 2 matrix 5 6
{[8,9], [5,6]}[1,*] Element in 1st row, {[8,9]}
all columns of a 2 x 8 9
2 matrix 5 6

Note: * denotes all rows or all columns, depending on its placement.

Adams/View also allows you to extract a column of a matrix:

44 Adams/View Function Builder
Expression Language Reference

Extracting a Complete Column

Adams Index Mathematical

Syntax: Description: Math Result: Adams Result:
{[8,9], [5,6]}[1:2,1] Element in rows 1 to {8,5}
2, 1st column of a 2 8 9
x 2 matrix 5 6
{[8, 9], [5, 6]} [*,1] Elements in all {8,5}
rows, 1st column of 8 9
a 2 x 2 matrix 5 6
{[1,2,3], [4,5,6], Elements in all {1,4,7}
[7,8,9]} [*,1] rows, 1st column in 1 2 3
a 3 x 3 matrix 4 5 6
7 8 9

Note: Indexing automatically converts any matrix with one element into a scalar.

Database Fields Containing Multiple Data

Database fields containing more than one real number produce matrices. For fields containing location
or orientation information, Adams/View creates a 3 X 1 matrix:
marker create marker=marker_1 location=8,7,6
3x1 Matrix

Expression: Result:
marker_1.location {8,7,6}
marker_1.location [2] 7

Adams/View handles fields containing more than one location or orientation as 3xN matrices. For
example, consider the three-point polyline defined below:
geometry create curve polyline polyline=polyline_1 loc=1,2,3,
4,5,6, 7,8,9
 Using the Adams/View Function Builder 45
Expression Language Reference

3xN Matrix

Expression: Result:
polyline_1.location {{1,2,3}, {4,5,6}, {7,8,9}}

or

{[1,4,7], [2,5,8], [3,6,9]}

polyline_1.location[*,2] {4,5,6}
polyline_1.location[2,3] 8

Note the usefulness of this matrix format. If you have a 3 x 3 transformation matrix, T (T, as produced
by the TMAT function), then post-multiplication by any matrix of locations or orientations produces a
new matrix of the same shape. For example:
T @ marker_1.location (3x3 times 3x1) produces a 3x1 matrix.
T @ polyline_1.location (3x3 times 3xN) produces a 3xN matrix.
Using matrix composition with database objects, you can create a three-point polyline from marker
locations:
geometry create curve polyline polyline=polyline_1 &
loc=({marker_1.location, {0,0,0}, marker_2.location})
The illustration below shows a three-point polyline:

For fields with multiple values, but with a single dimension, you create a 1 X N matrix:
data_element create spline spline=spline_1 x=1,2,3,4,5
y=2,3,4,5,6
46 Adams/View Function Builder
Expression Language Reference

1xN Matrix

Expression: Result:
spline_1.x {[1,2,3,4,5]}
spline.x[2] 2

Note: The same indexing operations that you can perform on database fields you can perform on
a matrix with the same shape.

Operators On Matrices
The following table lists the operators by precedence, from highest to lowest. All the standard binary
operators are applicable to same-shape matrices (SSM), that is, matrices with the same row and column
order, in a pair-wise fashion. Only one operator, the matrix multiplication operator (@), is not defined for
SSM.
Operators on Matrices

Expression: Result: Comments:

2 ** {0,1,2} (20,21,22) = {1,2,4} Exponentiation
{0,1,2,} ** 2 (02,12,22) = {0,1,4,}
{1,2,3} ** {4,5,6} (14,25,36) = {1,32, 729}
-{0,1,2} {0,-1,-2} Negation
{[1,2]} @ {3,4} Matrix multiplication
3 = 1  3 + 2  4 = 11
12
4

{1,2} @ {[3,4]} Matrix multiplication

1 3 4 =   3 4   6 8  
34 =
2 6 8

2 * {0,1,2} {0,2,4} Scalar multiplication

{0,1,2,} * 2 {0,2,4} Scalar multiplication
{1,2,3} * {5,6,7} {5,12,21} Pairwise multiplication
{[3,2]} * {[2,4]} {[6,8]} Pairwise multiplication
2 / {1,2,3} {2,1,0.667} Division
{0,1,2} / 2 {0,0.5,1}
{1,2,3} / {5,6,7} {0.2,0.333,0.429}
2 + {0,1,2} {2,3,4} Addition
{0,1,2} + 2 {2,3,4}
{1,2,3} + {5,6,7} {6,8,10}
 Using the Adams/View Function Builder 47
Expression Language Reference

Expression: Result: Comments:

2 - {0,1,2} {2,1,0} Subtraction
{0,1,2} - 2 {-2,-1,0}
{1,2,3} - {5,6,7} {-4,-4,-4}
2 == {0,1,2} {0,0,1} Equality
{0,0,0} == 0 {1,1,1}
{1,2,3 }== {1,2,3} {1,1,1}
2 != {0,1,2} {1,1,0} Inequality
{0,0,0} != 0 {0,0,0}
{1,2,3} != {1,2,3} {0,0,0}
2 <= {2,4,6} {1,1,1} Less than or equal
{2,4,6 } <= {3,4,5} {1,1,0} (All other relational
operators act similarly.)
!{0,1,2} {1,0,0} Logical NOT
2 && {0,1,2} {0,1,1} Logical AND
{0,1,2} && 2 {0,1,1}
{1,2,3} && {5,6,7} {1,1,1}
2 || {0,1,2} {1,1,1} Logical OR
{0,1,2 }|| 2 {1,1,1}
{1,2,3} || {5,6,7} {1,1,1}

Scalar Math on Matrices

All scalar math functions (including user-written functions) that take one or two real arguments and
produce a real argument are applied to matrices in the same fashion as the unary and binary operators in
the previous section:
Examples of Scalar Math on Matrices

Expression: Result:
SIN({1,2,3}) {0.841471, 0.909297, 0.141120}
ATAN2({1,2,3}, {3,2,1}) {0.321751, 0.785398, 1.249046}
ATAN2(3, {2,1}) {0.982794, 1.249046}

If you write a function ADD(x,y) that computes x+y, then, ADD(1,2) returns 3 and ADD({1,2,3},
{4,5,6}) returns {5,7,9}.
48 Adams/View Function Builder
Expression Language Reference

Units
Adams/View allows you to assign units to numbers to explicitly define dimensions. For instance, the
number 90 might be meaningful in the context of an angle only if it has units of degrees, while the number
3.14159 should probably have units of radians. Therefore, Adams/View allows you to place labels on
these values: (90d) or (3.14159r).
The following sections introduce you to unit sensitivity and unit labels:
• Unit Sensitivity
• Unit Labels

Unit Sensitivity
The expressions you store in the database can be unit-sensitive, meaning that changing the current units
results in a different value for the expression.
For example, if your model mass units are grams (g) and you have the part commands,
part_1 mass = 20
part_2 mass = (part_1.mass + 10)
then the mass of part_2 is 30 g.
Changing your model mass units to kilograms (kg) changes the mass of part_2 to 10.02 kg, because the
mass of part_1 changed to 0.02 kg and part_2 = part_1 + 10. When this happens, Adams/View issues the
following message:
WARNING: The following values have changed due to unit
sensitivity:
WARNING: .model_1.part_2.mass
Here's why: in the expression (part_1.mass + 10), 10 is a unitless constant. The value is 10 of whatever
the context defines. When the units are grams, it is 10 grams; when the units are kilograms, it is 10
kilograms. On the other hand, the mass of part_1 is 20 grams (0.02 kg) independent of the current model
units.
To make this expression non-unit-sensitive, simply add the unit label g after the 10.
part_2 mass=(part_1.mass + 10g)
Changing the model mass units, in this case from grams to kilograms, changes the mass of part_2 to 0.03
kg.
• In general, any expression that adds or subtracts a unitless constant to a unit-sensitive value is
also unit-sensitive.
Symbolic constants such as PI and RTOD are unitless, as are generic reals and integers like 10 in the
example above.
Expressions can also become unit-sensitive whenever involving any of the three trigonometric functions:
SIN, COS, or TAN. When the angle parameter is a unitless constant, it is in the current angle units. If your
angle units are radians, the expression calculates cosine of 45 radians:
 Using the Adams/View Function Builder 49
Expression Language Reference

(COS(45))
To make this expression non-unit-sensitive, simply add the unit label d after the 45, to calculate cosine
of 45 degrees:
(COS(45d))

Unit Labels
To label an expression with units, you can use either simple unit labels or composed unit labels:
• Simple Unit Labels
• Composed Unit Labels

Simple Unit Labels

Simple unit labels are derived from the DEFAULTS UNITS command. Any unique abbreviation for a
simple unit label is acceptable (radians = radian = radia = radi = rad = ra = r, since r doesn't conflict with
any abbreviation for other units).
All of the simple unit labels, and their minimal abbreviations are listed in the table shown next, by their
base units, in alphabetical order:
50 Adams/View Function Builder
Expression Language Reference

Simple Unit Labels and Their Minimal Abbreviations

Base units: Simple unit labels: Minimal abbreviations:

Length angstrom angs
centimeter centimeter
cm c
foot f
inch i
kilometer kilometer
km km
m m
meter met
microinch microi
micrometer microm
mile mile
mils mils
millimeter millimeter
mm mm
nanometer nanom
yard y
Angle am am
angular_minutes angular_m
angular_seconds angular_s
as as
degree d
radian r
revolutions re
Mass gram g
kg kg
kilogram kilogram
kpound_mass kpound_m
lbm lbm
megagram meg
microgram microg
milligram millig
nanogram nanog
ounce_mass ounce_m
pound_mass pound_m
slinch sli
slug sl
tonne t
us_ton us_
 Using the Adams/View Function Builder 51
Expression Language Reference

Base units: Simple unit labels: Minimal abbreviations:

Time day da
hour ho
microsecond micros
millisecond millis
minute min
ms ms
nanosecond nanos
second s
Force centinewton ce
dyne dy
kg_force kg_
kilogram_force kilogram_force
knewton kn
kpound_force kpound_f
lbf lbf
meganewton megan
micronewton micron
millinewton millin
nanonewton nanon
newton ne
ounce_force ounce_f
poundal pounda
pound_force pound_f
Frequency hz hz
radians/second radians/sec

Note: For kilopound mass, kilonewton, and kilopound force, enter kpound_mass, knewton, and
kpound_force, respectively

There are three exceptions to unique aliases, as shown in the following table:
Exceptions to Aliases

Aliases: Unit labels:

d Degrees, although it conflicts with dynes
kg Kilograms, although it conflicts with kg_force
m Meters, although it conflicts with mile, minute, ms, millisecond, and millinewton
N Newtons, although it conflicts with nanonewton
r Radians although it conflicts with revolutions
52 Adams/View Function Builder
Expression Language Reference

The next table shows some examples of simple unit labels associated with a number within expressions:
Simple Unit Labels Associated with Numbers

Syntax: Comment:
1millimeter Full label
1.2 inch Spaces are not significant
24in You can use abbreviations
PI rad You can apply unit labels to any expression, including symbolic constants

Composed Unit Labels

Composed unit labels allow you to create aggregate units in a general way. You can do this by combining
simple unit labels via operators. There are three operators you can use to compose aggregate units from
existing simple units:
Operators Used in Composing Aggregate Units

Operator: Notation: Comment:

exponentiation ** Right operand must be an integer: inch**2
multiplication - or * Foot-pound_f = foot*pound_f
division /

The following table lists examples of composed unit labels:

Composed Unit Labels

3.3 (newton*meter) Torque

9.8 (meter/sec**2) Composed acceleration
PI (rad/sec**2) Angular acceleration
(SQRT(1)*3)(in - lbf) Multiplication with a dash '-'
1.2 (inch / (sec*deg)) ERROR! no parenthesis allowed inside composed units
1.2 (inch / sec / deg) Correct way to compose this

Note: To eliminate ambiguity, always enclose unit labels in parentheses. In general, if you see
units associated with numbers produced by the list_info command in a command file or
anywhere else, you can take that units string and use it in an expression.
 Using the Adams/View Function Builder 53
Adams/View Function Builder Glossary

Adams/View Function Builder Glossary

A B C D E F G H I J K L M
N O P Q R S T U V W X Y Z

A-B

Acceleration Functions
Run-time functions that return a requested magnitude or component of the translational or rotational
acceleration vector between two markers.

Adams/View
MSC Software's powerful modeling and simulating environment.

Akima Fitting Method

Returns an interpolated value from a curve or surface.

Aliases
Alternate names you can use when referencing fields on objects in the database.

Argument
A value which is applied to a function as an input.

Array
In the Adams/View expression language, an array is a collection of values of the same scalar type.
B-spline Fitting Method
Returns a B-spline or a user-written curve created by a CURVE data element.

C-D

Coercion
Changing the type of a value. For example, changing from real numbers to character strings.

Command Window
An Adams/View window where you can enter commands directly, instead of using menus. The
commands correspond to menu selections and the parameters correspond to dialog box choices. You can
either enter a full command or an abbreviation of a command.
54 Adams/View Function Builder
Adams/View Function Builder Glossary

Compiled Functions
Functions you can write in C or Fortran, link into Adams/View, and then even use in an Adams/View
expression. See also the definition for Interpreted Functions.

Constant
An operand which is either literal, such as 3.2 or "hello", or symbolic, such as PI or SQRT2.

Contact Functions
Run-time functions you can use to define collision forces.

Cubic Fitting Method

Returns an interpolated value from a curve or surface.

Data Dictionary
Lists the names of the object types, and the fields associated with them, as they appear in expressions.

Data Types
The types of operands and computed values of expressions. There are five types: integer, real, string,
matrix, and database object.

Database Access
You can access the database to retrieve values from it to use in computing new values.

Database Functions
Design-time functions that facilitate your access to the database.

Database Objects
Objects stored in the Adams/View database.

Design-Time Functions
Allow you to parametrically configure the system being analyzed for such effects as optimization and
sensitivity studies.

Design Variables
Variables that store data which you can later use and modify.
 Using the Adams/View Function Builder 55
Adams/View Function Builder Glossary

Displacement Functions
Run-time functions that return scalar measures associated with a particular component of the
translational displacement vector from one coordinate system marker to another or an angular
displacement from one coordinate system marker to another.

E-F

Empty Array
Array that does not contain any values; denoted by a pair of braces { }.

Expressions
Combinations of constants, operators, functions, and database object references, all enclosed in
parentheses. You use expressions to specify parameters in your model or to allow Adams/View to
calculate values.

Expression Mode
Function Builder mode in which Adams updates the functions you create during the modeling process.

Force
An effect that has magnitude and direction and that causes motion of a body when there is no other
external effect on that body. In Adams/View, force can refer to both translational and rotational forces.

Force in Object Functions

Run-time functions that return instantaneous force values generated by modeling elements.

Function
An operand that takes a list of arguments and computes a value based on the values in the list. Each
argument in the list is an expression that is evaluated and given to the function. Common functions are:
SIN( ), ABS ( ), and THETA( ).

Function Builder
Adams/View tool that allows you to build functions and parameterize values for various entities.

Function Category
Collection of functions grouped according to their type. For example, the function categories include:
math functions, string functions, and database functions.
56 Adams/View Function Builder
Adams/View Function Builder Glossary

I-J

Interpreted Functions
User-written design-time functions created in Adams/View by using the function create command. They
may be used in Adams/View expressions. See also the definition for Compiled Functions.

K-L

Location / Orientation Functions

Design-time functions you can use to compute one or more locations or orientations from a variety of
input parameters.

M-N

Math Functions
Design-time or run-time functions that apply to scalar numbers or matrices. When working in design-
time, if you input a scalar, Adams returns a scalar, and if you input a matrix, Adams returns a matrix.

Matrix
A multi-dimensional collection of numeric values; a special case of array.

Matrix / Array Functions

Design-time functions that allow you to easily perform common matrix operations.

Miscellaneous Functions
Design-time functions that include a variety of functions.

Modeling Functions
Design-time functions that return a requested kinematic measurement between markers or parts.

O-P

Object
See the definition for Database Objects.

Operands
Operands allow you to indicate what you want to operate on. The following are types of operands: literal
constants, symbolic constants, function results, and database objects and their component values.
 Using the Adams/View Function Builder 57
Adams/View Function Builder Glossary

Operators
Operators allow you to specify what you want to do to operands.

Optimization
Helps you find an optimal design. You define the design objective and specify the model parameters that
can change.

Orientation Angles
Angles that define three rotations about the axes of a coordinate system.

Parameterization
Allows you to define an invariant relationship between model objects or their values.

Q-R

Resultant Force Functions

Run-time functions that return either the net applied action and reaction force between two markers, or
the net applied action-only forces at a marker.

Run-Time Functions
Allow you to specify mathematical relationships between variables that directly define the behavior of
your model.

Run-Time Mode
Function Builder mode in which you define the functions Adams/Solver uses during a simulation.

S-T

Single-Component Force
A force defined as one resultant magnitude along a direction.

Spline Functions
Run-time functions you can use during a simulation to define smooth functions to approximately fit data
points.

String Functions
Design-time functions that allow you to manipulate character strings.
58 Adams/View Function Builder
Adams/View Function Builder Glossary

Symbolic Constant
A kind of operand in an Adams/View expression, represented by an easily understood name, such as PI.

System-supplied Functions
Functions built into Adams/View or Adams/Solver.

U-V

User-written Functions
Design-time functions you can create yourself. There are two types of user-written functions: interpreted
and compiled.

Velocity Functions
Run-time functions that return a requested magnitude or component of the translational or rotational
velocity vector between two markers.
 Design-Time Functions 59

Design-Time Functions
60 Adams/View Function Builder
About Design-Time Functions

About Design-Time Functions

Design-time functions allow you to parametrically configure the system you're analyzing for such effects
as optimization and sensitivity studies.
This section provides examples of Adams design functions by type. The two major types of design-time
functions are:
• User-Written Functions
• System-Supplied Functions

In the Function Builder, you can enter expressions on multiple lines. Once you apply an expression,
however, it appears in the code on one line.

User-Written Functions
User-written functions are functions you can create yourself. There are two types of user-written
functions: interpreted and compiled.
The following sections explain the user-written functions:
• Interpreted Functions
• Compiled Functions
• Examples Involving Compiled Functions

Interpreted Functions
Interpreted functions consist of text inserted into an expression when Adams evaluates the expression.
You can create these functions in the command window, using the FUNCTION command. When you
create them, you must specify the text of the function and the parameter names. When you use these
functions, Adams substitutes the user parameters into the function text in place of the parameter names.
For example:
function create function_name = MID_PT &
text_of_expression = "LOC_ALONG_LINE(P1,P2,DM(P1,P2)/2)" &
argument_names = "P1", "P2" &
type = location_orientation
In the example above, P1 and P2 are the formal arguments to the function MID_PT.
In the following example, Adams positions marker_3 half way between marker_1 and marker_ 2:
marker create marker_name = marker_3 location=(MID_PT(marker_1,
marker_2))
 Design-Time Functions 61
About Design-Time Functions

Compiled Functions
You can also write compiled functions in C or FORTRAN, link them into Adams/View, and even use
them in an Adams/View expression. You can use these functions in the same way you would use the built-
in functions.
Register the user-written functions by calling a subroutine built in to Adams/View. You must place this
subroutine call in the registration subroutine supplied in source-code form with Adams/View.

To create your own compiled function:

1. Locate and copy the appropriate source code templates from $topdir/aview/user_subs. If you are
programming in C, copy vc_init_usr.c. If you are programming in FORTRAN, copy vf_init_usr.f.
2. Write and debug your function by modifying the template. You can debug by compiling your
function in debug mode, linking the executable in debug mode and using your native debugger.
3. Add your new function to the registration subroutine.
4. Link your new function and the modified registration subroutine with Adams/View. Depending
on the platform you're on, look for instructions in the Running and Configuring Adams help.
5. Use your new function in an expression.
You can use the programming language's normal parameter passing method to access parameters. Adams
allows you to use this mechanism only for a fixed set of parameter lists and return values. You can find
the set of allowable parameter lists in the files $topdir/aview/user_subs/mdi_c.h and
$topdir/aview/user_subs/mdi_f.f.
Registering functions allows you to add functions with arbitrary names. User-written functions have
precedence over system-supplied functions. If you register a function with the name SQRT, then your
new function is called whenever you use this name in an expression. You can't register a function that has
the same name as an existing literal constant. For example, Adams/View rejects names such as PI and
RTOD, and returns an error message.
If you have a function that duplicates a constant name, change the text name as shown next:
vc_function_add("RTOD", (FUNCTION)rtod, fn_R_RR, 2, 0); /* Won't
work */
to
vc_function_add("MYRTOD", (FUNCTION)rtod, fn_R_RR, 2, 0); /*
Will work */
When you register a function you must also specify the number and type of parameters, to give the
expression parser the information it needs to make sure the input and output data for the function are
correct.

Examples Involving Compiled Functions

The following examples show how you can write your own compiled functions and how you can access
arrays within compiled functions:
62 Adams/View Function Builder
About Design-Time Functions

• Writing Your Own Compiled Functions

• Accessing Arrays Within Compiled Functions

Writing Your Own Compiled Functions

This example adds a function that computes the remainder between two reals. When the function is
registered in Adams/View, its type, and the number and types of its parameters are defined, so the parser
can validate the input and output data.
Your code might look like this:
#include "mdi_c.h" /* This file is in $topdir/aview/user_subs */
#include <math.h>
typedef double REAL;
REAL remainder (REAL number, REAL denom)
{
int i;
return(number - (i * denom) );
}
#inlcude "mdi_vc.h"
void vc_initialize_user ()
}
REAL remainder ();
vc_function_add("REMAINDER",(FUNCTION) remainder, fn_fn_R_RR, 2,
0) ;
}
You must register the function in Adams/View. Do this by modifying a function that is supplied in source
code form (in the file $topdir/aview/user_subs/vc_init_usr.c), compiling and linking it with Adams/View,
as shown next:
#include "mdi_vc.h"
void vc_initialize_user ( )
{
REAL dist2 ( ) ;
vc_function_add("DIST2", (FUNCTION)dist2, fn_R_RR, 2, 0);
}
To use this function in an expression in Adams/View, type:
variable set variable=myvar real=(EVAL(REMAINDER(101.0/17.0)))
If you perform an error check within your user-written function, you can cause the function to abort and
report an error message by using the following routine:
void vc_error(char *Msg, ...);
The Msg parameter is a C format, and the optional parameters are the same as with a printf. Note that this
function does not return to the calling routine.
Accessing Arrays Within Compiled Functions
In the Adams/View expression language, an array is a collection of values of the same scalar type. For
more information on arrays, see Arrays.
 Design-Time Functions 63
About Design-Time Functions

The following C prototypes define the functional interface to the array object:
#define vc_MAX_RANK 7 /* Only 2 are usable in this release. */
typedef int vc_DIMS[vc_MAX_RANK];
typedef int vc_BNDS[vc_MAX_RANK][2];
typedef void *vc_ARRAY
;typedef int BOOL; /* True or false values */
typedef double REAL;
vc_ARRAY *vc_array_create(vc_DIMS Dims, int Rank, BOOL
ColumnVector);
void vc_array_set_values(vc_ARRAY *A, REAL *Values, int Index,
int Count);
void vc_array_get_values(vc_ARRAY *A, REAL *Values, int Index,
int Count);
REAL *vc_array_values (vc_ARRAY *A);
void vc_array_set_dims(vc_ARRAY *A, vc_DIMS Dims, int
Rank, BOOL ColumnVector);
void vc_array_get_dims(vc_ARRAY *A, vc_DIMS Dims, int
*Rank, BOOL *ColumnVector);
int vc_array_compute_index(vc_ARRAY *A, vc_BNDS Bounds, int
nBounds);
void vc_array_form_submatrix(vc_ARRAY *A, vc_BNDS Bounds, int
nIndex);
int vc_array_element_count(vc_ARRAY *A);
BOOL vc_array_same_shape(vc_ARRAY *A1, vc_ARRAY *A2);
vc_EL vc_array_elements (vc_ARRAY A);
void vc_array_set_element_type (vc_ARRAY A, EXPR_TYPE
ElementType);
EXPR_TYPE vc_array_element_type (vc_ARRAY A);
void vc_array_coerce_element_type (vc_ARRAY A, EXPR_TYPE
ElementType);
void vc_array_set_string_element (vc_ARRAY A, char *Value,
int Index);
int vc_array_source_object (vc_ARRAY A);

The source code for the DMAT function is given below as an example of how to use this interface:
vc_ARRAY vc_dmat(vc_ARRAY A)
{
vc_ARRAY NewArray;
vc_DIMS Dims;
int Size;
int Rank;
BOOL ColV;
REAL *Values;
int i;
vc_array_get_dims(A, Dims, &Rank, &ColV);
/* Verify the shape of the input array */
if ( Rank > 2 || Dims[0] != 1 && Dims[1] != 1 )
{ vc_error("DMAT only works with a 1xN or Nx1 matrix, this
one is %dx%d", Dims[0], Dims[1]);
}
Size = vc_array_element_count(A);/* Set up dimensions of new
array */
64 Adams/View Function Builder
About Design-Time Functions

Dims[0] = Size;
Dims[1] = Size;
NewArray = vc_array_create(Dims, 2, TRUE);
Values = vc_array_values(A); /* Fetch the values for the
diagonal */
for ( i = 0; i < Size; i++ )
{ vc_array_set_values(NewArray, &Values[i], i*(Size+1), 1);
}
return(NewArray);
}

System-Supplied Functions
The Function Builder gives you access to over two hundred system-supplied, design-time functions. In
addition, you can create your own user-written functions.
Design-time functions are evaluated only during the modeling process, not during a simulation. Note that
although some design-time functions have the same names as certain run-time functions, they work with
the model definition only, not with the model at an analysis-time step. Adams/View does, however,
evaluate design-time functions during design studies and optimization.
The Function Builder categorizes all system-supplied functions based on their functionality. For
example, a category might include all math functions or all database functions. A category named All
Functions lists all the functions in alphabetical order. You can use and access the system-supplied design-
time functions from the Function Builder, as outlined in Working in Expression Mode.
The following sections introduce the system-supplied function categories as they appear in the Function
Builder:
• Math Functions
• Location/Orientation Functions
• Modeling Functions
• Matrix/Array Functions
• String Functions
• Database Functions
• Miscellaneous Functions

Math Functions
Math functions apply to scalar numbers or matrixes. If you input a scalar, Adams returns scalar. If you
input a matrix, Adams returns a matrix.
Where to Find the Math Functions
 Design-Time Functions 65
About Design-Time Functions

The following table lists the names and definitions for the math functions:

This function: Returns:

ABS The absolute value of an expression that represents a numerical value.
ACOS The arc cosine of an expression that represents a numerical value.
AINT The nearest integer whose magnitude is not larger than the integer value of a
specified expression that represents a numerical value.
ANINT The nearest integer whose magnitude is not larger than the real value of an
expression that represents a numerical value
ASIN The arc sine of an expression that represents a numerical value.
ATAN The arc tangent of an expression that represents a numerical value.
ATAN2 The arc tangent of two expressions, each representing a numerical value.
CEIL The smallest integer greater than x.
COS The cosine of an expression that represents a numerical value.
COSH The hyperbolic cosine of an expression that represents a numerical value.
DIM The positive difference of the instantaneous values of two expressions, each
representing a numerical value.
EXP Returns the exponential for each element of x.
FLOOR The largest integer that is less than x.
INT The nearest value whose magnitude is not larger than x.
LOG The natural logarithm of an expression that represents a numerical value.
LOG10 Log to base 10 of an expression that represents a numerical value.
MAG The magnitude of a vector.
MOD The remainder of one expression, representing a numerical value, divided by
another expression representing a numerical value.
NINT The whole number nearest to the input value.
RAND A pseudo-random value on the closed interval [0.0, 1.0], from a uniform
distribution.
RTOI An integer representation of the input value, where the input value is a real
number.
SIGN A numerical value which takes its sign from one argument and its magnitude
from another.
SIN The sine of an expression that represents a numerical value.
SINH The hyperbolic sine of an expression that represents a numerical value.
SQRT The square root of an expression that represents a numerical value.
66 Adams/View Function Builder
About Design-Time Functions

This function: Returns:

TAN The tangent of an expression that represents a numerical value.
TANH The hyperbolic tangent of an expression that represents a numerical value.

Location/Orientation Functions
You can use location/orientation functions to compute one or more locations or orientations from a
variety of input parameters.
Where to Find the Location/Orientation Functions
The following table lists the names and definitions for the location/orientation functions:

This function: Returns:

LOC_ALONG_LINE An array of three numbers defining a location expressed in the
global coordinate system.
LOC_BY_FLEXBODY_NODEID The location as a three-dimensional vector of a node on a flexible
body.
LOC_CYLINDRICAL An array of three numbers, that are the Cartesian coordinates (x, y,
z) for a point, equivalent to the cylindrical coordinates (r, , z) for
the same point.
LOC_FRAME_MIRROR An array of three numbers representing a location in the global
coordinate system, which mirrors another location across a plane of
a coordinate system object.
LOC_GLOBAL An array of three numbers representing the global coordinates of a
location obtained from transforming the local coordinates by a
specified location.
LOC_INLINE An array of three numbers representing the transformation and
normalization of coordinates for a location you specified.
LOC_LOC An array of three numbers representing the transformation of
coordinates location in a new coordinate system object.
LOC_LOCAL An array of three numbers representing a location obtained by
transforming a location expressed in the global coordinate system,
to a new local coordinate system object.
LOC_MIRROR An array of three numbers representing a location in the global
coordinate system, which mirrors another location across a plane of
a coordinate system object.
LOC_ON_AXIS An array of three numbers representing a location, expressed in the
global coordinate system, obtained from translating a certain
distance along a specified axis of a coordinate system object.
 Design-Time Functions 67
About Design-Time Functions

This function: Returns:

LOC_ON_LINE An array of three numbers representing the global coordinates of a
location along a line defined by two points.
LOC_PERPENDICULAR A location normal to a plane, one unit away from the first point in
the plane.
LOC_PLANE_MIRROR An array of three numbers representing a location expressed in the
global coordinate system of a location mirrored across the specified
plane.
LOC_RELATIVE_TO An array of three numbers, representing a location, by transforming
a specified location that is relative to a coordinate system object.
LOC_SPHERICAL Cartesian coordinates (x, y, z) that are equivalent to spherical
coordinates (  ,  ,  ).
LOC_TO_FLEXBODY_NODEID The node ID of the flexible body that is closest to the specified
location
LOC_X_AXIS A normal vector defining the x-axis of a coordinate system object
in the global coordinate system.
LOC_Y_AXIS A normal vector defining the y-axis of a coordinate system object
in the global coordinate system.
LOC_Z_AXIS A normal vector defining the z-axis of a coordinate system object
in the global coordinate system.
ORI_ALIGN_AXIS An orientation that aligns one axis of a coordinate system object
with an axis of another.
ORI_ALONG_AXIS_EUL An orientation that aligns one axis of a coordinate system object
with an axis of another.
ORI_ALL_AXES A body-fixed 313 Euler sequence describing an orientation in
which the first axis of a coordinate system object is parallel to, and
co-directed with, a line defined by the first two points in a plane,
and its second axis is parallel to the plane.
ORI_ALONG_AXIS The alignment of a specified axis from one coordinate system
object to another.
ORI_FRAME_MIRROR An orientation that has the specified axes mirrored about a plane
within a coordinate system object.
ORI_GLOBAL An angle expressed in a coordinate system object to the global
coordinate system.
ORI_IN_PLANE An orientation by directing one of the axes and defining one of the
planes within a coordinate system object.
ORI_LOCAL An orientation, expressed in the global frame, in the local frame of
the coordinate system object.
68 Adams/View Function Builder
About Design-Time Functions

This function: Returns:

ORI_MIRROR An orientation by performing a mirroring of the given orientations
that reflect the specified axes.
ORI_ONE_AXIS A body-fixed 313 Euler rotation sequence expressed in the global
coordinate system when given a line that is parallel to, and co-
directed with, a specified axis.
ORI_ORI An orientation that represents the same orientation as expressed in
the local frame of one coordinate system object to the local frame
of another coordinate system object.
ORI_PLANE_MIRROR A sequence of body-fixed 313 Euler rotations by performing a
mirroring of orientations.
ORI_RELATIVE_TO An orientation of a coordinate system object as specified by an
angle.

Modeling Functions
Kinematic modeling functions return a requested displacement measurement between markers or parts.
Although these functions have the same names as certain run-time functions, they only compute an
instantaneous value in the context of a design-time function. These functions work with the model
definition only, not with a model at an analysis-time step.
Modeling functions' arguments use any coordinate system entity (marker, part), any entity implying a
coordinate system (model, geometry) or zero (0). If an argument uses a coordinate system entity or any
entity implying a coordinate system, it is referred to as a coordinate system object. If the argument is zero,
Adams defaults to the global coordinate system.
Where to Find the Modeling Functions
The following table lists the names and definitions for the modeling functions:

This function: Returns:

AX The angular displacement from one coordinate system object to another.
AY The angular displacement from one coordinate system object to another.
AZ The angular displacement from one coordinate system object to another.
DM The magnitude of the translational displacement from one coordinate system object
to another.
DX An x component of translational displacement from one coordinate system object
to another.
DY A y component of translational displacement from one coordinate system object to
another.
 Design-Time Functions 69
About Design-Time Functions

This function: Returns:

DZ A z component of translational displacement from one coordinate system object to
another.
PHI The third angle associated with a body-fixed 313 rotation sequence from one
coordinate system object to another.
PITCH The negative value of the second angle associated with a body-fixed 321 rotation
sequence from one coordinate system object to another.
PSI The first angle associated with a body-fixed 313 rotation sequence from one
coordinate system object to another.
ROLL The third angle associated with a body-fixed 321 rotation sequence from one
coordinate system object to another.
THETA The second angle associated with a body-fixed 313 rotation sequence from one
coordinate system object to another.
YAW The first angle associated with a body-fixed 321 rotation sequence from one
coordinate system object to another.

Matrix/Array Functions
Matrix/array functions allow you to easily perform common matrix operations.
Where to Find the Matrix/Array Functions
The following table lists the names and definitions for the matrix/array functions:

This function: Returns:

AKIMA_SPLINE An interpolated curve created from input points with a specified number
of values.
AKIMA_SPLINE2 An Akima-spline fit of the dependent values.
ALIGN Shifts values in an array to start at a particular value (often used to shift a
curve so that the value at its starting point is 0--aligning along the curve to
0)
ALLM The logical product of the elements of a matrix.
ANGLES A 3x1 matrix containing angles from the transformation matrix in D.
ANYM The logical sum of the elements of a matrix.
APPEND The rows of one matrix appended to the rows of another matrix.
BALANCE A similarity transformation T such that B = T/A*T has, as nearly as
possible, approximately equal row and column norms.
BARTLETT The new array when the Bartlett window is applied to the input array.
BLACKMAN The new array when the Blackman window is applied to the input array.
70 Adams/View Function Builder
About Design-Time Functions

This function: Returns:

BODEABCD Returns gain and/or phase values for the frequency response function for
a linear system specified by ABCD linear state matrices.
BODELSE Returns output gain and/or phase values for the frequency response
function for an Adams/View linear state equation element.
BODELSM Computes the Bode response for a given set of A, B, C, and D matrices.
BODESEQ Returns the gain and/or phase values calculated from two sequences of
time-based values describing the input and output of a linear system.
BODETFCOEF Returns the gain and/or phase values for the frequency response function
of a transfer function specified by its numerators and denominators.
BODETFS Returns the gain and/or phase values for the frequency response function
of an Adams transfer function element.
BUTTER_DENOMINATOR Calculates the denominator coefficients for the Butterworth filter.
BUTTER_FILTER Filter a curve with the butterworth filter specified by the order and cutoff
frequency.
BUTTER_NUMERATOR Calculates the numerator coefficients for the butterworth filter.
BUTTORD_FREQUENCY Calculates the cutoff frequency for the butterworth filter.
BUTTORD_ORDER Calculates the order for the butterworth filter.
CENTER A non-statistical mean of the values in an array.
CLIP An MxNumvals matrix of values extracted from an MxN matrix.
COLS The number of columns in a given matrix.
COMPRESS An array consisting of the non-empty values in the input array.
COND Returns the condition number of a matrix.
CONVERT_ANGLES A body-fixed 313 sequence converted into a user-specified sequence.
CROSS The cross-product of two matrixes.
CSPLINE An interpolated curve created from input points with a specified number
of values.
CUBIC_SPLINE An interpolated curve created from input points with a specified number
of values.
DET The determinant of a square matrix.
DETREND A 1xN array of detrended data computed by subtracting the linear least
squares fit from the input data stream.
DIFF A 1xN array of approximations to the derivatives at the points in the input
data.
DIFFERENTIATE The derivative at each input point on curve C.
DMAT A square matrix with the elements of M along the diagonal, and zero
elsewhere.
 Design-Time Functions 71
About Design-Time Functions

This function: Returns:

DOE_MATRIX Returns a matrix of DOE experiments, a row from that matrix or the count
of rows from that matrix.
DOE_NUM_TERMS Returns the number of terms in the polynomial produced by the
OPTIMIZE FIT_RESPONSE_SURFACE command.
DOT The dot product of two matrixes.
EIG_DI Returns a vector of the imaginary components of the generalized eigen
vectors of matrices A and B.
EIG_DR Returns a vector of the real components of the generalized eigen vectors
of matrices A and B.
EIG_VI Returns a vector of the imaginary components of the generalized eigen
vectors of matrices A and B.
EIG_VR Returns a vector of the real components of the generalized eigen vectors
of matrices A and B.
EIGENVALUES_I Returns a vector of the imaginary components of the generalized eigen
vectors of matrices A and B.
EIGENVALUES_R Returns a vector of real components of the generalized eigen vectors of
matrices A and B.
ELEMENT Text that indicates if a real value is an element of an array.
EXCLUDE An array with a specified value excluded from it.
FFTMAG A 1xN array of magnitudes calculated by applying the FFT function to
input values.
FFTPHASE A 1xN array of phase values calculated by applying the FFT function to
input values.
FILTER A 1xN array of filtered input values, where N is the number of input
values.
FILTFILT Zero phase digital filtering.
FIRST The first element in an array if an element exists; otherwise, returns a 0.
FIRST_N The first N elements of an array.
FREQUENCY The FFT frequencies of an array of time values.
GRIDDATA A real array of Zi values corresponding to the ordered pairs in Xi, and Yi.
HAMMING A 1xN array of values after applying the HAMMING window function.
HANNING A 1xN array of values after applying the HANNING window function.
HERMITE_SPLINE An interpolated curve created from input points with a specified number
of values.
INCLUDE A value included into an array if the value is not already there.
INTEGR The integral produced at each input point on curve C.
72 Adams/View Function Builder
About Design-Time Functions

This function: Returns:

INTEGRATE A curve of integrals produced from an input curve.
INTERP1 The Yi values corresponding to the Xi values
INTERP2 The Zi values corresponding to the Xi and Yi points.
INTERPFT An array of Y values nY long if given the x array and integer value nY.
INVERSE The inverse matrix of a square matrix.
LAST The last element of an array if an element exists; otherwise, returns a 0.
LAST_N The last N element of an array.
LINEAR_SPLINE An interpolated curve created from input points with a specified number
of values.
MAX The value of the largest element of a matrix.
MAXI The index of the largest element of a matrix.
MEAN The mean of a matrix.
MESHGRID The X or Y grid coordinates.
MIN The value of the smallest element of a matrix.
MINI The index of the smallest element of a matrix.
NORM Scalar representing the norm of a matrix.
NORM2 The square root of the sum of the squares of the elements of a matrix.
NORMALIZE The normalized elements of a matrix.
NOTAKNOT_SPLINE An interpolated curve created from input points with a specified number
of values.
PARZEN The 1xN array of values after applying the PARZEN window function.
POLYFIT Returns the coefficients of a polynomial fitted to the supplied function
data.
PROD The product of the elements of a matrix by performing a matrix reduction
using multiplication.
PSD The power spectral density computed from the complex Fourier
coefficients.
PWELCH Estimate the power spectral density (PSD) of a signal using Welch's
method.
RECTANGULAR The 1xN array of values after applying the RECTANGULAR window
function.
RESAMPLE A curve resampled over a new interval with the spline algorithm you
specified.
RESHAPE A new matrix created from an existing matrix with dimensions you
specified in the shape-descriptor array.
 Design-Time Functions 73
About Design-Time Functions

This function: Returns:

REVERSE A reversed one-dimensional input array.
RMS The root mean square of the values.
ROWS The number of rows in a matrix.
SERIES An array it generated based on a start value, a number of increments, and
an array length.
SERIES2 An increment it calculated based on start and end values and a given
number of increments.
SHAPE The dimensions of a matrix.
SIM_TIME The simulation time for the last step of the default simulation.
SORT A matrix sorted in the direction you specified.
SORT_BY An array sorted by another array in the direction you specified.
SORT_INDEX The indexes of a matrix sorted in the direction you specified.
SPLINE An interpolated curve created from the input points with the number of
points you specified.
SSQ The sum of the squares of the elements of a matrix.
STACK The concatenation of two matrixes with the same number of columns.
STEP An array of y values, on a step curve, corresponding to the x values.
SUM The sum of the elements of a matrix by performing a matrix reduction
using addition.
TILDE The TILDE function of an array.
TMAT A 3x3 transformation matrix using the values in the orientation sequence
you specified.
TMAT3 Returns a 3x3 transformation matrix using the values in the orientation
sequence you specify.
TRANSPOSE The transpose of a matrix.
TRIANGULAR Apply the triangular window to the input array and return the new array.
UNIQUE An array from which it deleted all duplicate elements.
UNWRAP Unwraps phase angles in degree by changing absolute jumps greater than
180 degree to their 360 degree complement.
VAL An array element nearest to the number you specified.
VALAT A number from an array located at the same position as a number found in
another array.
VALI The index of the element in an array nearest to the number you specified.
WELCH A 1xN array of values after applying the WELCH window function.
74 Adams/View Function Builder
About Design-Time Functions

String Functions
String functions allow you to manipulate character strings.
Where to Find the String Functions
The following table lists the names and definitions for the string functions:

This function: Returns:

STATUS_PRINT A text string to all status bars.
STR_CASE A string from an input string that has been modified according to an integer
value.
STR_CHR A character whose ASCII value is mapped to an input integer.
STR_COMPARE A numeric value indicating the relative alphabetical ordering of two strings.
STR_DATE A string containing the current time and/or date information according to a
format string.
STR_DELETE A string that results from deleting a specified number of characters starting
from a specified location on an input string.
STR_FIND The starting location of the first occurrence of a string within another string.
STR_FIND_COUNT The number of occurrences of a string found within another string.
STR_FIND_IN_STRIN Returns the index into the array if the string is found, zero if not found.
GS
STR_FIND_N The numerical position of a character in a string found within another string.
STR_INSERT A string constructed by inserting a string into another string at a specified
insertion point.
STR_IS_REAL A boolean truth value indicating that the input character string argument
represents a valid real number.
STR_IS_SPACE A 1 (true) if a string is empty; otherwise, returns 0 (false).
STR_LENGTH A numerical value corresponding to the length of a string.
STR_MATCH A 1 (true) if a specified string is found within another string; otherwise,
returns 0 (false).
STR_PRINT A string it writes into the aview.log file.
STR_REMOVE_WHIT A string that is the result of removing all leading and trailing spaces (blank
ESPACE spaces, tab spaces) from the input string.
STR_SPLIT An array of strings built from substrings, which are separated from each other
with a specified character, and are located within another string.
STR_SPRINTF A character string constructed by formatting the array of values in the format
string.
 Design-Time Functions 75
About Design-Time Functions

This function: Returns:

STR_SUBSTR A substring with a designated number of characters starting at a specified
point within a string.
STR_TIMESTAMP The current date and time in the default format.
STR_XLATE A new string formed by replacing all occurrences of one or more characters
found within the input string, with an equal number of characters.

Some of the functions in the Miscellaneous Functions category are related to the functions in this
category. Those functions are:
• ON_OFF
• STOI
• STOO
• STOR

Database Functions
Database functions facilitate your access to the database.
Where to Find the Database Functions
The following table lists the names and definitions for the database functions:

This function: Returns:

DB_ACTIVE A Boolean value indicating that the object will or will not
take part in simulations.
DB_ANCESTOR Returns the first ancestor of an object of the type you specify.
DB_CHANGED A 1 if an element in the database has changed; returns a 0 if
there was no change.
DB_CHILDREN An array of objects of a given type that are children of the
object you specified.
DB_COUNT The number of values in a given field of the object you
specified.
DB_DEFAULT The default object of a given type.
DB_DEFAULT_NAME Returns the name for the given object based on the state of the
default for formatting names.
DB_DEFAULT_NAME_FOR_TYPE Returns the name for the given object based on the state of the
default for formatting names.
DB_DELETE_DEPENDENTS An array of objects that are dependents of the object you
specified.
76 Adams/View Function Builder
About Design-Time Functions

This function: Returns:

DB_DEL_PARAM_DEPENDENTS An array of all the parametric expressions that depend on the
object you specified.
DB_DEL_UNPARAM_DEPENDENTS A constant integer value of zero, and deletes all the
parametric expressions that depend on the object you
specified.
DB_DEPENDENTS An array of all objects of a given type that are dependents of
the object you specified.
DB_EXISTS A 1 if the object you specified exists; returns a 0 if it doesn't.
DB_FIELD_FILTER An array, from a given array of field names, containing a
subset of the original array.
DB_FIELD_TYPE A string that describes the type of data in a field beneath the
object type you specified.
DB_FILTER_NAME An array of objects whose names match the filter parameters
you specified.
DB_FILTER_TYPE An array of objects whose types match the filter parameters
you specified.
DB_FULL_NAME_FROM_SHORT Returns the full name for the named object of the specified
type.
DB_FULL_TYPE_FIELDS An array of strings for the names of the fields (including
aliases) for the object you specified.
DB_IMMEDIATE_CHILDREN An array of all objects that are immediate children of the
object you specified.
DB_OBJECT_COUNT The number of object names in the array of database objects
you specified.
DB_OBJ_EXISTS Returns a logical value indicating whether the specified
object exists as an immediate child of the parent object.
DB_OBJ_EXISTS_EXHAUSTIVE Returns a boolean value indicating whether the object
specified exists or not.
DB_OF_CLASS A 1 if an object is a member of a given class; returns a 0 if it
is not.
DB_OF_TYPE_EXISTS Returns a 1 if an object with the name and type you specified
exits; returns a 0 if it does not exist.
DB_OLDEST_ANCESTOR Returns the most distant ancestor of an object of the type
specified.
DB_REFERENTS An array of objects of a given type that are referenced by the
object you specified.
DB_SHORT_NAME Returns the shortest unique name for the given object.
 Design-Time Functions 77
About Design-Time Functions

This function: Returns:

DB_TWO_WAY An array of objects that have two-way associativity with the
object you specified.
DB_TYPE A string representing an object type.
DB_TYPE_FIELDS An array of strings for the names of the fields (excluding
aliases) for the object type you specified.

Some of the functions in the Miscellaneous Functions category are related to the functions in this
category. Those functions are:

• EXPR_EXISTS • UNIQUE_FULL_NAME
• EXPR_STRING • UNIQUE_NAME
• PARAM_STRING • USER_STRING

Back to top

Miscellaneous Functions
To further assist you, we've divided the miscellaneous functions into four groups, as listed below.
• Database Functions Group
• GUI Functions Group
• String Functions Group
• System Functions Group

Database Functions Group

The following table lists the names and definitions for the functions in the database functions group:

This function: Returns:

EXPR_EXISTS A 1 if an expression exists in a given field of an object that you
specify; returns a 0 if it does not.
EXPR_REFERENCE A string containing the name of the reference to the expression.
EXPR_STRING A text string containing an expression in a given field of an object
that you specify.
PARAM_STRING A parameter's values as they appear in an Adams command file.
UNIQUE_FULL_NAME A text string containing a unique full name for the type of object
you specified.
UNIQUE_ID Returns an adams_id unique for objects of the specified type.
78 Adams/View Function Builder
About Design-Time Functions

This function: Returns:

UNIQUE_LOCAL_NAME Returns a name of the form BASE_1, where "BASE" is a prefix
that you supply and the number ("1" in this case) is computed by
the function.
UNIQUE_NAME A text string that is a unique database name.
UNIQUE_NAME_IN_HIERARCHY A text string that is a unique database name, taking into account
the inherent hierarchy in the given input
UNIQUE_PARTIAL_NAME A character string containing a unique object name.
UNITS_CONVERSION_FACTOR Returns the numeric conversion factor from the given unit value
to the current default units.
UNITS_STRING A text string containing a units string associated with another
string.
UNITS_TYPE Returns the character string value of the given unit type using the
provided integer value.
UNITS_VALUE Returns the character string value of the given unit type using the
default units settings.
USER_STRING A text string containing a value in the Object Field.

GUI Functions Group

The following table lists the names and definitions for the functions in the GUI (graphical user interface)
functions group:

This function: Returns:

AGGREGATE_MASS Aggregate mass information.
ALERT An alert box using the labels you specify.
ALERT2 Displays the contents of the variable on separate lines and
presents an OK button. It always returns 1.
ALERT3 Displays the contents of the variable on separate lines and
presents an alert window with up to three buttons
containing specified labels.
FILE_ALERT An integer representing the command button you
selected after Adams/View displayed the Alert dialog
box.
FIND_MACRO_FROM_COMMAND KEY of the macro using the specified commands.
NODE_ID_CLOSEST An integer node ID associated with the node of the
flexible body closest to a specified marker.
 Design-Time Functions 79
About Design-Time Functions

This function: Returns:

NODE_IDS_CLOSEST_TO Array containing node IDs (integers) of number of nodes
on the flexible body closest to the specified marker.
NODE_IDS_IN_VOLUME Array containing node IDs for all nodes on the flexible
body, which reside inside the volume of a specified
geometry object.
NODE_ID_IS_INTERFACE Returns one or zero to indicate whether the specified
node of a flexible body is an interface node.
NODE_IDS_WITHIN_RADIUS Array of node IDs associated with all the
nodes of the flexible body within a radius
of a specified marker.
NODE_NODE_CLOSEST Returns an integer node id associated with a node of the
flexible body, o_new_flex, closest to node, nodeId, on
the flexible body o_old_flex.
PICK_OBJECT KEY of the selected object.
SECURITY_CHECK Returns a one or zero depending on whether or not the
product name is properly licensed.
SELECT_DIRECTORY Returns the name of the directory you selected from the
directory browser
SELECT_FIELD A selected field as a string.
SELECT_FILE A file name you selected.
SELECT_MULTI_TEXT An array of strings you selected.
SELECT_OBJECT A selected object, using the Database Navigator to
provide you with selections.
SELECT_OBJECTS An array of selected objects, using the Database
Navigator to provide you with selections.
SELECT_REQUEST_IDS An array of integers representing the selected IDs.
SELECT_TEXT The string you selected.
SELECT_TYPE A selection list of object types.
TABLE_COLUMN_SELECTED_CELLS An array of integers representing the 1-based row
numbers of selected cells within a specified column in a
table.
TABLE_GET_CELLS An array of strings representing the contents of the cells
within the specified row/column range.
TABLE_GET_DIMENSION An integer representing the number of rows or columns
in a table or the number of cells in a row or column.
TABLE_GET_REALS Returns an array of reals representing the contents of the
cells within the specified row/column range.
80 Adams/View Function Builder
About Design-Time Functions

This function: Returns:

TABLE_GET_SELECTED_COLS Returns the column numbers for the columns in a data
table that are currently selected. A column is considered
as 'selected' if at least one of its cells is selected
TABLE_GET_SELECTED_ROWS Returns the row numbers for the rows in a data table that
are currently selected. A row is considered as 'selected' if
at least one of its cells is selected.
TIMER_CPU Either starts or ends a timer for measuring the
accumulated time in CPU seconds used since the
beginning of the process execution
TIMER_ELAPSED Either starts or ends a timer for measuring the elapsed
time in seconds.

String Functions Group

The following table lists the names and definitions for the functions in the string functions group:

This function: Returns:

ON_OFF The character string on or off, depending on the state of the argument.
STOI An integer STOI has converted from a string.
STOO A database object STOO has converted from a character string.
STOR A real number STOR has converted from a string.

System Functions Group

The following table lists the names and definitions for the functions in the system functions group:

This function: Returns:

BACKUP_FILE A backup of a specified file.
CHDIR A 1 if CHDIR succeeded in changing to the directory you specified,
or a 0 if it failed.
EXECUTE_VIEW_COMMAND A numerical value indicating whether
EXECUTE_VIEW_COMMAND succeeded or failed in executing
an Adams/View command.
FILE_DIRECTORY_NAME A directory name from the file specification.
FILE_EXISTS A 1 if a file exists, and a 0 if it doesn't.
FILE_MINUS_EXT The file name with its extension removed.
FILE_TEMP_NAME A string that has a non-existent temporary file name.
 Design-Time Functions 81
About Design-Time Functions

This function: Returns:

GETCWD The current working directory as a character string.
GETENV Text string containing the value of the environment variable you
specified.
MKDIR A numerical value indicating whether MKDIR succeeded in creating
a user-specified directory.
PARSE_STATUS An array of integer status codes corresponding to the given search
tag.
PUTENV The string value that PUTENV assigned to an environment variable.
REMOVE_FILE A 0 if successful in deleting a file; otherwise, it returns a nonzero
value.
RENAME_FILE A specified file.
RMDIR A 1 if successful in removing the directory; otherwise, it returns 0.
SIM_STATUS An array of simulation status codes corresponding to the tag:
ALVSIM:STATUS.
SYS_INFO A character string containing information about the system.
TERM_STATUS An array of simulation status codes corresponding to the tags:
A3TERM:STATUS and TERM:STATUS.
UNIQUE_FILE_NAME A string that is the name of a non-existent file.

Design-Time Function Descriptions

For each function we provide the following:
• Definition - A brief description of the function.
• Format - The function name and format as they appear in the Function Builder.
• Arguments - The arguments used by the function, and a short description of each argument.
• symbol - The mathematical equation relevant to the function.
• Examples - One or more examples of how to use the function.

When referring to argument names, we use the following convention:

Notation: Stands for:

G Ground
O Object
R Reference frame
82 Adams/View Function Builder
Functions: A - C

Functions: A - C
 Design-Time Functions 83
Functions: A - C

ABS
Returns the absolute value of an expression that represents a numerical value.

Format
ABS(x)

Argument

x Any valid expression that evaluates to a real number.

Example
The following example illustrates the use of the ABS function:

Function ABS(3*(-.89))
Result 2.67

Learn more about math functions.

84 Adams/View Function Builder
Functions: A - C

ACOS
Returns the arc cosine of an expression that represents a numerical value. The evaluated expression must
return a value whose absolute value is less than or equal to 1.0. The value ACOS returns lies in the range
[0,  ], that is, 0  ACOS(x)   .

Format
ACOS(x)

Argument

x Any valid expression that evaluates to a real number.

Examples
The following examples illustrate the use of the ACOS function:

Function ACOS(.75)
Result 41

Function ACOS(PI/4)
Result 38

Learn more about math functions.

 Design-Time Functions 85
Functions: A - C

AGGREGATE_MASS
Calculates and stores aggregate mass information, which you can then use in parametrics or store in
variables for future use.

Format
aggregate_mass(array_of_objects, reference_frame_key, type_string)

Arguments

array_of_objects A single object or an array of objects of the type models, bodies, and tires. If
you specify a model, it must be the only object passed in.
reference_frame_key A reference frame for reporting the aggregate mass center of mass (cm)
position and inertia marker angles. If you enter none, the default is with
respect to the global coordinate system.
type_string The type of aggregate mass information desired. The choices are:

• mass - Mass value (one real)

• cm_pos - Center of mass location (three reals)
• im_ang - Inertia marker angles (three reals)
• inertias - Inertia properties (six reals)
• all - Returns all of the above (13 reals)

Examples
Computing Mass

The following example provides the mass of PART_2 and PART_3:

AGGREGATE_MASS( {PART_2, PART_3} , 0 , "mass" )

Note that the objects must be in an array; therefore, the curly braces are required. In this example, the
reference frame key has been set to zero because the value of mass is independent of the reference frame.
Computing CM Location
The following example returns the location of the cm for the aggregation of PART_2 and PART_3. The
location array will be computed and reported with respect to the ground.MARKER_3 reference frame.
AGGREGATE_MASS( {PART_2, PART_3} , ground.MARKER_3 ,"CM_Pos" )
Obtaining Inertia Matrix Entries
86 Adams/View Function Builder
Functions: A - C

The following example returns the off-diagonal entries of the inertia matrix for the aggregation of
PART_2 and PART_3 in the ground reference frame. Note that array indexing has been used to return the
4th, 5th, and 6th entries from the returned array.
AGGREGATE_MASS( {PART_2, PART_3} , 0 , "inertias" )[4:6]
Alternatively, you can use the all type string and use array indexing to extract only the last three values.
In this example, the computation is relative to PART_2.MARKER_1.
AGGREGATE_MASS({PART_2,PART_3}, PART_2.MARKER_1 , "All")[11:13]

Note: If you use the option all, use a no_units temporary variable to get all of the quantities at
once, and then pass it to individual variables with the proper unit setting.

Learn more about GUI functions.

 Design-Time Functions 87
Functions: A - C

AINT
Returns the nearest integer whose magnitude is not larger than the integer value of a specified expression
that represents a numerical value.
AINT(x) evaluates to different values under different conditions:
AINT(x) = 0 if ABS(x)< 1
AINT(x) = int(x) if ABS(x) 1
The value of the mathematical function AINT of a variable x is equal to x if x is an integer. If x is not an
integer, then AINT(x) is equal to the integer nearest to x, whose magnitude is not greater than the
magnitude of x.

Format
AINT(x)

Argument

x Any valid expression that evaluates to a real number.

Examples
The following examples illustrate the use of the AINT function:

Function AINT(-6.5)
Result -6

Function AINT(4.6)
Result 4

Learn more about math functions.

88 Adams/View Function Builder
Functions: A - C

AKIMA_SPLINE
Creates an interpolated curve from input points with a specified number of values. Interpolates using the
Akima method.
The algorithm that fits the akima spline is from the Journal of the Association of Computing Machinery
(Vol. 17, No. 4, October 1970).
The length of the Independent Data array must be the same as the Dependent Data array.

Format
AKIMA SPLINE (Independent Data, Dependent Data, Number of Output Values)

Arguments

Independent Data A 1xN array of x values for the curve to be interpolated. The x values
must be in ascending order, and the length of the array must be greater
than or equal to 4.
Dependent Data A 1xN array of y values for the curve to be interpolated.
Number of Output Values The number of values to be generated in the output array.

Example
The following function interpolates a set of four points with ordinal values from 1 to 4 and abscissal
values as shown, into a series of 10 abscissal values:

Function AKIMA_SPLINE({1, 2, 3, 4}, {0, 2, 1, 3}, 10)

Result {0.0, 1.0, 1.667, 2.0, 1.778, 1.222, 1.0, 1.333, 2.0, 3.0}

To compute the ordinal values for these splined values, you can use the SERIES2 function as follows:

Function SERIES2(1, 4, 10)

Result {1.0, 1.333, 1.667, 2.0, 2.333, 2.667, 3.0, 3.333, 3.667, 4.0}

Learn more about matrix/array functions.

 Design-Time Functions 89
Functions: A - C

AKIMA_SPLINE2
Returns an Akima-spline fit of the dependent values. It clips the output data to start at the maximum start
point of the two independent value arrays and ending at the minimum end point of the two independent
value arrays.
When the FLAG is 1, AKIMA_SPLINE2 uses the first set of independent values to determine the step
size. When FLAG is 0, it uses the second set of independent values.

Format
AKIMA_SPLINE2 (Independent Data, Dependent Data, Independent Data2, FLAG)

Arguments

Independent Data A 1xN array of x values for curve1 to be interpolated. The x values must be in
ascending order, and the length of the array must be greater than or equal to 4.
Dependent Data A 1xN array of y values for curve1 to be interpolated.
Independent Data2 A 1xN array of x values for curve2 to be interpolated. The x values must be in
ascending order, and the length of the array must be greater than or equal to 4.
FLAG Integer indicating whether the first or second set of independent values were
used to determine the output step size.

Learn more about matrix/array functions.

90 Adams/View Function Builder
Functions: A - C

ALERT
Returns an alert box using the labels you specify. It is recommended to use EVAL() function when using
ALERT, both to avoid unnecessary parameterization and for it to function properly.

Format
ALERT (Type, Message Text, Button 1 Label, Button 2 Label, Button 3 Label, Default Choice)

Arguments

Type Text string indicating the type of alert box. There are five types from which to
choose:

• Error
• Warning
• Information
• Working
• Question
Message Text Text string making up the alert box message.
Button 1 Label Text string describing a command button.
Button 2 Label Text string describing a command button.
Button 3 Label Text string describing a command button.
Default Choice Integer value (1, 2 or 3) indicating which command button is the default choice.

Example
The following function creates an alert box:

Function ALERT("Information", "Create a test?", "Yes", "No", "Cancel", 2)

Result Alert box with "No" as the default choice

Learn more about GUI functions.

 Design-Time Functions 91
Functions: A - C

ALERT2
Displays the contents of the variable on separate lines and presents an OK button. It always returns 1. It
is recommended to use EVAL() function when using ALERT2, both to avoid unnecessary
parameterization and for it to function properly.

Format
ALERT2 (var, type)

Arguments

var A reference to a string variable.

type A character string indicating the type of alert box. These values come from the ALERT function:

• Error
• Warning
• Information
• Working
• Question

Example
var set var=msg str="Out of", "disk", "space"
var set var=OK int=(ALERT2 (msg.self, "ERROR"))
Learn more about GUI functions.
92 Adams/View Function Builder
Functions: A - C

ALERT3
Displays the contents of the variable on separate lines and presents an alert window with up to three
buttons containing specified labels. It is recommended to use EVAL() function when using ALERT3,
both to avoid unnecessary parameterization and for it to function properly.

Format
ALERT3 (var, type, b1, b2, b3, choice)

Arguments

var A reference to a string variable.

type A character string indicating the type of alert box. These values come from the ALERT
function:

• Error
• Warning
• Information
• Working
• Question
b1 A character string to display on button 1.
b2 A character string to display on button 2.
b3 A character string to display on button 3.
choice An integer designating the default button number.

Example
var set var=msg str="Out of", "disk", "space"
var set var=OK int=(ALERT3 (msg.self, "ERROR", "OK", "Cancel",
"", 1))
Learn more about GUI functions.
 Design-Time Functions 93
Functions: A - C

ALIGN
Shifts values in an array to start at a particular value (often used to shift a curve so that the value at its
starting point is 0--aligning along the curve to 0).

Format
ALIGN (real array, real number)

Argument

real array Array of values to align (shift).

real number First value from aligned array.

Examples
The following example shifts curve_1 to start at the same value as curve_2.
ALIGN (.plot_1.curve_1, .plot_1.curve_2.Y_data[1])
The following example shifts curve_1 to start at 0.
ALIGN (.plot_1.curve_1, 0)
Learn more about matrix/array functions.
94 Adams/View Function Builder
Functions: A - C

ALLM
Returns the logical product of the elements of a matrix. If all values are nonzero, then the result is
nonzero.

Format
ALLM (M)

Argument

M A matrix of arbitrary shape.

Examples
The following examples illustrate the use of the ALLM function:

Function ALLM({1, 0, 1})

Result 0

Function ALLM({1, 2, 3})

Result 1

Function ALLM({[1, 1], [1, 0]})

Result 0

Learn more about matrix/array functions.

 Design-Time Functions 95
Functions: A - C

ANGLES
Returns a 3x1 matrix containing angles from the transformation matrix in D.

Format
ANGLES (D, OriType)

Arguments

D 3 x 3 matrix of direction cosines.

OriType Character string specifying the Euler sequence that is desired as output. To define the
rotation sequence, enter space or body (character case is ignored), followed by three digits,
such as 313 or 123.

Example
The following function performs the inverse of the TMAT function:
ANGLES(DCOS, "body313")
You can obtain the current default orientation type string with this expression:
(user_string(".system_defaults.orientation_type"))
Learn more about matrix/array functions.
96 Adams/View Function Builder
Functions: A - C

ANINT
Returns the nearest integer whose magnitude is not larger than the real value of an expression that
represents a numerical value.
ANINT(x) evaluates to different values under different conditions, as defined below:
ANINT(x) = int(x + .5) if x > 0
ANINT(x) = int(x - .5) if x < 0
The value of the mathematical function ANINT of a variable x is equal to x if x is an integer. If x is not
an integer, then ANINT(x) is equal to the integer nearest to x whose magnitude is not greater than the
magnitude of x.

Format
ANINT(x)

Argument

x Any valid expression that evaluates to a real number.

Examples
The following examples illustrate the use of the ANINT function:

Function ANINT(-4.6)
Result -5

Function ANINT(4.6)
Result 5

Learn more about math functions.

 Design-Time Functions 97
Functions: A - C

ANYM
Returns the logical sum of the elements of a matrix. If any value is nonzero, the result is nonzero.

Format
ANYM (M)

Argument

M A matrix of arbitrary shape.

Examples
The following examples illustrate the use of the ANYM function:

Function ANYM({8, 0, 1})

Result 1

Function ANYM({0, 0, 0})

Result 0

Function ANYM({[4, 0], [0, 0]})

Result 1

Learn more about matrix/array functions.

98 Adams/View Function Builder
Functions: A - C

APPEND
Returns the rows of one matrix appended to the rows of another matrix. The two matrixes must have the
same number of rows. If one matrix is an NxM matrix and the other matrix is an NxP matrix, then
APPEND returns an Nx(M+P) matrix.

Format
APPEND (M1,M2)

Arguments

M1 A matrix of arbitrary shape.

M2 A matrix with the same number of rows as M1.

Example
The following example illustrates the use of the APPEND function:

Function APPEND(M1, M2)

Returns {{1,2,3,11,12,13,14}, {4,5,6,15,16,17,18}}

1,2,3,11,12,13,14

4,5,6,15,16,17,18

Matrixes M1 and M2 are defined as follows:

M1 = {{1,2,3},{4,5,6}} and M2 = {{11,12,13,14},{15,16,17,18}}
1,2,3 11,13,14,15
4,5,6 15,16,17,18
Learn more about matrix/array functions.
 Design-Time Functions 99
Functions: A - C

Array HOT_SPOTS (Name array, Integer array, Real array)

Returns all of the spots on the Body that exceed the specified Threshold. Learn more about HOT_SPOTS.

Arguments
• Name array
• Body: Name of flexible body or part with a rigid stress object.
• Analysis: Name of analysis (optional)
• Integer array
• Value: Flag for value of stress or strain to use.
• Type: Flag for stress (1) or strain (2) (optional). Default is stress (1).
• Real array
• Threshold: Return all hot spots that exceed this value.
• Radius: Distance between hot spots (unit of length).
• Start: Time to start checking for hot spots (optional). Default is the beginning of the analysis.
• End: Time to stop checking for hot spots (optional). Default is the end of the analysis.

Returns
• Real 6 x N array - N rows of hot-spot data with the following information:
• X, Y, Z: Location of hot spot on body, with respect to local part reference frame (LPRF).
• Time: Time when the maximum value occurred.
• Value: Maximum value of hot spot.
• Node: Node ID of hot spot.
100 Adams/View Function Builder
Functions: A - C

Array TOP_SPOTS (Name array, Integer array, Real array)

Returns a fixed number of the hottest spots in the Body. Learn more about TOP_SPOTS function.

Arguments
• Name array
• Body: Name of flexible body or part with a rigid stress object.
• Analysis: Name of analysis (optional)
• Integer array
• Value: Flag for value of stress or strain to use.
• Type: Flag for stress (1) or strain (2) (optional). Default is stress (1).
• Real array
• Percent: Number of hot spots to return, expressed as a percentage (%). If set to zero (0.0), the
count argument is used to determine how many to return.
• Radius: Distance between hot spots (unit of length).
• Start: Time in the analysis to start checking for hot spots (optional). Default is the beginning
of the analysis (unit of time).
• End: Time in the analysis to end check for hot spots (optional). Default is the end of the
analysis (unit of time).
• Count: Number of hot spots to return.

Returns
• Real 6xN array - N rows of hot-spot data with the following information:
• X, Y, Z: Location of hot spot on body (with respect to LPRF).
• Time: Time when the maximum value occurred.
• Value: Maximum value of hot spot.
• Node: Node ID of hot spot.
 Design-Time Functions 101
Functions: A - C

ASIN
Returns the arc sine of an expression that represents a numerical value. ASIN is defined only when the
absolute value of the expression is  1. The range of ASIN is [ –  /2,  /2] (that is, –  /2 < ASIN(x)
<  /2).

Format
ASIN(x)

Argument

x Any valid expression that evaluates to a real number.

Example
The following function calculates the value of the expression DX(marker_2, marker_1, marker_2) /
DM(marker_2, marker_1). It then applies the ASIN function to the result and returns its arc sine. The
location of marker_1 and marker_2 is shown in the figure below.

Function ASIN(DY(marker_2, marker_1, marker_2) / DM(marker_2, marker_1))

Returns 45

Learn more about math functions.

102 Adams/View Function Builder
Functions: A - C

ATAN
Returns the arc tangent of an expression that represents a numerical value. The range of ATAN is [-
 /2,  /2] (that is, –  /2 < ATAN(x) <  /2).

Format
ATAN(x)

Argument

x Any valid expression that evaluates to a real number.

Example
The following example illustrates the use of the ATAN function. The location of marker_1 and marker_2
is shown in the figure below.

Function ATAN(DX(marker_2, marker_1, marker_2) /

DY(marker_2, marker_1, marker_2))
Returns 45

Learn more about math functions.

 Design-Time Functions 103
Functions: A - C

ATAN2
Returns the arc tangent of two expressions, each representing a numerical value. x1 and x2 themselves
can be expressions.

–   atan 2  x 1 x 2   
atan 2  x 1 x 2   0 if x1  0
atan 2  x 1 x 2  = 0 if x 1 = 0 x 2  0
atan 2  x 1 x 2  =  if x 1 = 0 x 2  0
atan 2  x 1 x 2   0 if x1  0

abs  atan 2  x 1 x 2   = --- if x2 = 0
2
atan 2  x 1 x 2  undefined if x 1 = 0 and x 2 = 0

Format
ATAN2(x1, x2)

Arguments

x1 Any valid expression that evaluates to a real number.

x2 Any valid expression that evaluates to a real number.

Example
The following function shows the arc tangent of the expression a/b where a is the x component of the
distance between marker_2 and marker_1 and b is the y component of the distance between marker_2
and marker_1. The location of marker_1 and marker_2 is shown in the figure below.

Function ATAN2 (DX(marker_2, marker_1, marker_2), DY(marker_2, marker_1, marker_2))

Result 45
104 Adams/View Function Builder
Functions: A - C

Learn more about math functions.

 Design-Time Functions 105
Functions: A - C

AX
Returns the angular displacement from one coordinate system object to another, and accounts for angle
wrapping.

Format
AX (Object, Reference Frame)

Arguments

Object Coordinate system object to which the angular displacement is measured.

Reference Frame Coordinate system object from which the angular displacement is measured, using
an x-axis rotation.

symbol
Mathematically, AX is calculated as follows (angle wrapping is accounted for):

AX = atan  – ẑ o  ŷ R ẑ o  ẑ R 

where:

• ẑ o is the z-axis of the Object, O.

• ŷ R is the y-axis of the Reference Frame, R.
• ẑ R is the z-axis of the Reference Frame, R.

Example
In the following illustration, the AX function returns the angle between the y-axes of marker_O and
marker_R:

Function AX(marker_O, marker_R)

Result 35
106 Adams/View Function Builder
Functions: A - C

Note: Because this function is independent of the rotation sequence, attempting y-axis and z-axis
rotations in conjunction with it may return an output that doesn't make sense.

Tip: If you want to change the AX function so it does not account for angle wrapping, use the
MOD function. For example, use the function:
(MOD(AX(.model_1.PART_1.MAR_2,
.model_1.ground.MAR_1)+PI,2*PI)-PI)
The MOD function achieves the cyclic effect and the +PI and -PI shift the curve
accordingly.
Learn more about modeling functions.
 Design-Time Functions 107
Functions: A - C

AY
Returns the angular displacement from one coordinate system object to another, and accounts for angle
wrapping.

Format
AY (Object, Reference Frame)

Arguments

Object Coordinate system object to which the angular displacement is measured.

Reference Frame Coordinate system object from which the angular displacement is measured, using
a y-axis rotation.

symbol
Mathematically, AY is calculated as follows (angle wrapping is accounted for):

AY = atan  ẑ o  x̂ R ẑ o  ẑ R 

where:

• ẑ o is the z-axis of the Object, O.

• ẑ R is the z-axis of the Reference Frame, R.
• x̂ R is the x-axis of the Reference Frame, R.

Example
In the following illustration, the AY function returns the angle between the x-axes of marker_O and
marker_R:

Function AY(marker_O, marker_R)

Result 35
108 Adams/View Function Builder
Functions: A - C

Note: Because this function is independent of the rotation sequence, attempting y-axis and z-axis
rotations in conjunction with it may return an output that doesn't make sense.

Tip: If you want to change the AY function so it does not account for angle wrapping, use the
MOD function. For example, use the function:
(MOD(AY(.model_1.PART_1.MAR_2,
.model_1.ground.MAR_1)+PI,2*PI)-PI)
The MOD function achieves the cyclic effect and the +PI and -PI shift the curve
accordingly.
Learn more about modeling functions.
 Design-Time Functions 109
Functions: A - C

AZ
Returns the angular displacement from one coordinate system object to another, and accounts for angle
wrapping.

Format
AZ (Object, Reference Frame)

Arguments

Object Coordinate system object to which the angular displacement is measured.

Reference Frame Coordinate system object from which the angular displacement is measured using
a z-axis rotation.

symbol
Mathematically, AZ is calculated as follows (angle wrapping is accounted for):

AZ = atan  x̂ o  ŷ R x̂ o  x̂ R 

where:

• x̂ o is the x-axis of the Object, O.

• x̂ R is the x-axis of the Reference Frame, R.
• ŷ R is the y-axis of the Reference Frame, R.

Example
In the following illustration, the AZ function returns the angle between the x-axes of marker_O and
marker_R:

Function AZ(marker_O, marker_R)

Result 35
110 Adams/View Function Builder
Functions: A - C

Note: Because this function is independent of the rotation sequence, attempting y-axis and x-axis
rotations in conjunction with it may return an output that doesn't make sense.

Tip: If you want to change the AZ function so it does not account for angle wrapping, use the
MOD function. For example, use the function:
(MOD(AZ(.model_1.PART_1.MAR_2,
.model_1.ground.MAR_1)+PI,2*PI)-PI)
The MOD function achieves the cyclic effect and the +PI and -PI shift the curve
accordingly.
Learn more about modeling functions.
 Design-Time Functions 111
Functions: A - C

BACKUP_FILE
Renames the specified file to a backup file. The name of the backup file on UNIX is file_name appended
with %. On Windows, the last character of file_name is replaced with a q.

Format
BACKUP_FILE( file_name)

Argument

file_name String containing the name of the file to back up.

Example
The following example renames foo.dat to foo.dat% (on UNIX) or foo.daq (on Windows):
var set var=bkup int=(eval(BACKUP_FILE("foo.dat")))
Learn more about system functions.
112 Adams/View Function Builder
Functions: A - C

BALANCE
Finds a similarity transformation T such that B = T/A*T has, as nearly as possible, approximately equal
row and column norms. T is a permutation of a diagonal matrix whose elements are integer powers of
two so that the balancing does not introduce any round-off error, then returns B.

Format
BALANCE(A)

Arguments

A A square matrix.

Example
The following example illustrates the use of the BALANCE function:

Function BALANCE({{1,2},{3,4}})
Result {{1,2}, {3,4}}

Learn more about matrix/array functions.

This portion of the Adams/View Function Builder documentation, ©2006, has been reproduced here with
permission from MathWorks, ©1994-2000 The MathWorks Inc.
 Design-Time Functions 113
Functions: A - C

BARTLETT
Apply the Bartlett window to the input array and return the new array.

Format
BARTLETT (a)

Arguments

a An array.

Example
The following is an illustration of the BARTLETT function:

Function bartlett ({1, 2, 3, 4, 2})

Result {0, 1, 3, 2, 0}

Learn more about matrix/array functions.

114 Adams/View Function Builder
Functions: A - C

BARTLETT_WINDOW
Generate the Bartlett window.

Format
BARTLETT_WINDOW (n)

Arguments

n An integer value.

Example
The following is an illustration of the BARTLETT_WINDOW function:

Function bartlett_window (5)

Result {0, 0.5000, 1.0000, 0.5000, 0}

Learn more about matrix/array functions.

 Design-Time Functions 115
Functions: A - C

BLACKMAN
Apply the Blackman window to the input array and return the new array.

Format
BLACKMAN (a)

Arguments

a An array.

Example
The following is an illustration of the BLACKMAN function:

Function blackman ({1,2 3,4,2})

Result {0.0000, 0.6800, 3.0000, 1.3600, 0.0000}

Learn more about matrix/array functions.

116 Adams/View Function Builder
Functions: A - C

BLACKMAN_WINDOW
Generate the Blackman window.

Format
BLACKMAN_WINDOW (n)

Arguments

n An integer value.

Example
The following is an illustration of the BLACKMAN_WINDOW function:

Function blackman_window (5)

Result {0.0000, 0.3400, 1.0000, 0.3400, 0.0000}

Learn more about matrix/array functions.

 Design-Time Functions 117
Functions: A - C

BODEABCD
Returns gain and/or phase values for the frequency response function for a linear system specified by
ABCD linear state matrices.

Format
BODEABCD (OUTTYPE, OUTINDEX, A, B, C, D, FREQSTART, FREQEND, FREQARG)

Arguments

OUTTYPE Flag used to determine whether to return gain data, phase data, or both.

OUTTYPE Values

The value of OUTTYPE serves as a key to control the type of sampling that
Adams/View has to do (linear step size, linear sample count or logarithmic sample
count) and whether the gain, the phase, or both are computed. When both the gain and
the phase are computed, all the gains are followed by all the phases, which is rarely
convenient. We recommend that you compute gain and phase separately, unless CPU
time dictates taking advantage of the efficiencies of computing both at once. The
following table explains the values of OUTTYPE:
FREQARG FREQARG
linearly- logarithmically-
Fixed linear spacing spaced spaced
per FREQARG: samples: samples:
Gain and Phase 0 3 6
Gain 1 4 7
Phase 2 5 8
OUTINDEX Index used to determine whether to return all outputs or a particular one. Index values
are as follows:

• OUTINDEX = 0 (all outputs are returned)

• OUTINDEX > 0 (nth output is returned)
A, B, C, D Adams/View matrices containing linear state matrices.
FREQSTAR First frequency of requested range.
T
FREQEND Last frequency of requested range.
FREQARG Frequency count that depends on OUTTYPE. When OUTYPE is 0,1 or 2, FREQARG
is the step size. When OUTTYPE is a number between 4 and 8, FREQARG is the
number of samples.
118 Adams/View Function Builder
Functions: A - C

Examples
The following example assumes that you have four Adams/View matrices, ABCD, as follows:
data_element create matrix full &
matrix_name = .model_1.A &
input_order = by_row &
row_count = 3 &
column_count = 3 &
values = 0.0, 1.0, 0.0, 0.0, 0.0, 1.0, -0.22,-1.14,-0.4
data_element create matrix full &
matrix_name = .model_1.B &
input_order = by_column &
row_count = 3 &
column_count = 1 &
values = 0.0, 0.0, 1.0
data_element create matrix full &
matrix_name = .model_1.C &
input_order = by_row &
row_count = 1 &
column_count = 3 &
values = 0.01, 0.0, 0.0
data_element create matrix full &
matrix_name = .model_1.D &
input_order = by_column &
row_count = 1 &
column_count = 1 &
values = 0.0
Because the four matrices are equivalent to the transfer function used in the BODETFCOEF and
BODETFS examples, you will get identical results when you write the following command (see Using
the OUTTYPE Key):

var set var=bode_mag_log real=(BODEABCD(7, 1, .model_1.A, &

.model_1.B, .model_1.C, .model_1.D, 0.01, 10, 100))
Learn more about matrix/array functions.
 Design-Time Functions 119
Functions: A - C

BODELSE
Returns output gain and/or phase values for the frequency response function for an Adams/View linear
state equation element.

Format
BODELSE (OUTTYPE, OUTINDEX, O_LSE, FREQSTART, FREQEND, FREQARG)

Arguments

OUTTYPE Flag used to determine whether to return gain data, phase data, or both. For additional
information, see OUTTYPE Values.
OUTINDEX Index used to determine whether to return all outputs or a particular one. Index values
are as follows:

• OUTINDEX = 0 (all outputs are returned)

• OUTINDEX > 0 (nth output is returned)
O_LSE Adams linear state equation entity.
FREQSTART First frequency of requested range.
FREQEND Last frequency of requested range.
FREQARG Frequency count that depends on the OUTTYPE. When OUTYPE is 0,1 or 2,
FREQARG is the step size. When OUTTYPE is a number between 4 and 8,
FREQARG is the number of samples.

Examples
In the following example, the ABCD matrices from BODEABCD are encapsulated in an Adams linear
state equation element, as follows:
model create model=model_1
measure create function &
measure_name = .model_1.MEASURE_1 &
function = "" &
units = no_units &
create = no
data_element create array x_state_array &
array_name = .model_1.x &
size = 3
data_element create array y_output_array &
array_name = .model_1.y &
size = 1
data_element create array u_input_array &
array_name = .model_1.u &
size = 1 &
variable_name = .model_1.MEASURE_1
part create equation linear_state_equation &
120 Adams/View Function Builder
Functions: A - C

linear_state_equation_name = .model_1.LSE &

x_state_array_name = .model_1.x &
u_input_array_name = .model_1.u &
y_output_array_name = .model_1.y &
a_state_matrix_name = .model_1.A &
b_input_matrix_name = .model_1.B &
c_output_matrix_name = .model_1.C &
static_hold = on
Because the four matrices are equivalent to the transfer function used in the BODETFCOEF and
BODETFS examples, you will get identical results when you write the following command (see Using
the OUTTYPE Key):

variable set variable=bode_mag_log real=(BODELSE(7, 1,

.model_1.lse, 0.01, 10, 100))
Learn more about matrix/array functions.
 Design-Time Functions 121
Functions: A - C

BODELSM
Computes the Bode response for a given set of A, B, C, and D matrices. These matrices are usually
produced as the result of a linear system analysis.

Format
BODELSM (resultType, outIndex, LSM, freqStart, freqEnd, freqStep)

Arguments

resultType Specifies the components for BODELSM to return, and how the freqStep argument is
used. Below are the values and their meaning:
Value Returned values: Step computation:
0 mag and phase Fixed frequency step
1 mag only Fixed frequency step
2 phase only Fixed frequency step
3 mag and phase Linear sample count
4 mag only Linear sample count
5 phase only Linear sample count
6 mag and phase Logarithmic sample count
7 mag only Logarithmic sample count
8 phase only Logarithmic sample count
outIndex Specifies the row of the two-dimensional output matrix that is to be returned.

• OUTINDEX = 0 (all outputs are returned)

• OUTINDEX > 0 (nth output is returned)
If both phases and magnitudes are to be returned, then there are two rows for each
input/output combination and the magnitudes are stored first.
LSM The Adams/View linear state matrix object containing the matrices computed by the
system linearization.
freqStart Low frequency in the omega vector.
122 Adams/View Function Builder
Functions: A - C

freqEnd High frequency in omega.

freqStep Depending on the value of resultType, this can denote either the number of samples, the
linear step size, or a logarithmic step size.

• For a fixed frequency step, this value is the actual step size of the omega vector.
For example, if freqStart is given as 10 and freqEnd is 20, a value of 2 for
freqStep produces sample frequencies of 10, 12, 14, 16, 18, and 20.
• For linear sample count, this value denotes the number of intervals in the omega
vector, and is used to compute a linear step size. Using the same example from
above, but with freqStep =5, we get 10, 12.5, 15, 17.5, and 20.
• For logarithmic sample count, the behavior is similar to the linear sample count,
but the increments are used for the exponent resulting in a logarithmic
progression. Using the same values supplied in the previous example, the sample
becomes 10.0, 11.9, 14,1, 16.8, and 20.0.

Examples
simulation single statematrix &
state_matrices_name=.model_1.Analysis.Stmat_1 & plant_input_name
= .model_1.pinput & plant_output_name =.model_1.poutput
If the system has a pair of inputs and a pair of outputs, there will be four response curves, corresponding
to the row indices as follows:
row 1 = input 1/output 1
row 2 = input 1/output 2
row 3 = input 2/output 1
row 4 = input 2/output 2
var cre var=mags rea=(BodeLSM (4, 3, Stmat_1, 1, 100, 50))
Learn more about matrix/array functions.
 Design-Time Functions 123
Functions: A - C

BODESEQ
Returns the gain and/or phase values calculated from two sequences of time-based values describing the
input and output of a linear system. The sequences are 1xN arrays of time data or measure entities.

Format
BODESEQ (OUTTYPE, SEQ1, SEQ2, NUMOUT)

Arguments

OUTTYPE Flag used to determine whether to return gain data, phase data, or both. For additional
information, please see OUTTYPE Values.
SEQ1 A 1xN array of time-dependent values. A measure element may be used in place of
an array.
SEQ2 A 1xN array of time-dependent values. A measure element may be used in place of
an array.
NUMOUT Integer number of requested output values.

Extended Definition
When a Bode plot is generated for two sequences of values, the sequences are assumed to be the input to
a linear system and the output that corresponds to that input. The sequences are the excitation of the linear
system and the response due to that excitation.
Adams/View computes a Fast Fourier Transform (FFT) of the two sequences and the Bode plot is simply
the magnitude and the phase of the complex ratio of the output FFT to the input FFT.
Learn more about matrix/array functions.
124 Adams/View Function Builder
Functions: A - C

BODETFCOEF
Returns the gain and/or phase values for the frequency response function of a transfer function specified
by its numerators and denominators.

Format
BODETFCOEF (OUTTYPE, NUMER, DENOM, FREQSTART, FREQEND, FREQARG)

Arguments

OUTTYPE Flag used to determine whether to return gain data, phase data, or both. For additional
information, see OUTTYPE Values.
NUMER A 1xN array of transfer function numerators.
DENOM A 1xN array of transfer function denominators.
FREQSTART First frequency of requested range.
FREQEND Last frequency of requested range.
FREQARG Frequency count that depends on the OUTTYPE. When OUTYPE is 0,1 or 2,
FREQARG is the step size. When OUTTYPE is a number between 4 and 8,
FREQARG is the number of samples.

Examples
You can create Bode data with 100 logarithmically-spaced samples between .01 and 10, by writing the
following command:
variable set variable=bode_log_mag real=(BODETFCOEF & (7, {[
0.01]},{[ 1. , 0.4 , 1.14 , 0.22]},0.01, 10., 100)
Using the OUTTYPE Key
The OUTTYPE key controls the frequencies at which Adams/View computes the Bode data. In the
example above, we used OUTTYPE=7 for logarithmically-spaced gain values.
If you want to generate an array of the corresponding frequencies, write the following command:
variable set variable=log_freq real=(10**series(-2., 0.030303,
100))
To sample on a linear scale, write the following command:
variable set variable=bode_log_mag real=(BODETFCOEF (4, {[
0.01]},{[ 1. , 0.4 , 1.14 , 0.22]},0.01, 10., 100)
To generate the corresponding frequencies, write the following command:
variable set variable=lin_freq real=(series(0.01, 0.100909,
100))
Learn more about matrix/array functions.
 Design-Time Functions 125
Functions: A - C

BODETFS
Returns the gain and/or phase values for the frequency response function of an Adams transfer function
element.

Format
BODETFS (OUTTYPE, TFSISO, FREQSTART, FREQEND, FREQSTEP)

Arguments

OUTTYPE Flag used to determine whether to return gain data, phase data, or both. For
additional information, see OUTTYPE Values.
TFSISO An Adams transfer function entity.
FREQSTART First frequency of requested range.
FREQEND Last frequency of requested range.
FREQSTEP Frequency count that depends on the OUTTYPE. When OUTTYPE is 0,1 or 2,
FREQARG is the step size. When OUTTYPE is a number between 4 and 8,
FREQARG is the number of samples.

Examples
The following function assumes that you created an Adams transfer function element, as follows:
model create model=model_1
measure create function &
measure_name = .model_1.MEASURE_1 &
function = "" &
units = no_units &
create = no
data_element create array x_state_array &
array_name = .model_1.x &
size = 3
data_element create array y_output_array &
array_name = .model_1.y &
size = 1
data_element create array u_input_array &
array_name = .model_1.u &
size = 1 &
variable_name = .model_1.MEASURE_1
part create equation transfer_function &
transfer_function_name = .model_1.TRANSFER_FUNCTION_1 &
x_state_array_name = .model_1.x &
u_input_array_name = .model_1.u &
y_output_array_name = .model_1.y &
static_hold = on &
numerator_coefficients = 0.01 &
denominator_coefficients = 1.0, 0.4, 1.14, 0.22
126 Adams/View Function Builder
Functions: A - C

Because the transfer function is equivalent to the four matrices used in the BODEABCD and BODELSE
examples, you will get identical results when you write the following command (see Using the OUTTYPE
Key):

variable set variable=bode_mag_log real=(BODETFS (7,

.model_1.TRANSFER_FUNCTION_1, 0.01, 10.0, 100))
Learn more about matrix/array functions.
 Design-Time Functions 127
Functions: A - C

BUTTER_DENOMINATOR
Calculates the denominator coefficients for the Butterworth filter.

Format
BUTTER_DENOMINATOR (n, wn, fType, isDigital) returns ARRAY

Argument

n An integer value indicating the order of the Butterworth filter.

wn Array of values indicating the cutoff frequency that can have one or two elements.
fType A text string. The filter type, can be one of {low, high, pass, stop}.
isDigital A Boolean value.

Example
The following example illustrates the BUTTER_DENOMINATOR function:

Function butter_denominator (6, {0.1951, 0.4081}, "pass", 1)

Result {1.0000, -5.8240, 17.6909, -35.8509, 53.4731, -61.3642, 55.3780,0-39.5185, 22.1585, -
9.5439, 3.0209, -0.6376, 0.0708}

Learn more about matrix/array functions.

128 Adams/View Function Builder
Functions: A - C

BUTTER_FILTER
Filter a curve with the Butterworth filter specified by the order and cutoff frequency.

Format
BUTTER_FILTER (x, y, fType, order, cutoff, isAnalog, isTwoPass) returns ARRAY

Argument

x An array of the x-axis of the curve, usually time.

y An array of the y-axis of the curve.
fType A text string. The filter type, can be one of {low, high, pass, stop}.
order An integer indicating the order of the Butterworth filter.
cutoff An array. The cutoff frequency can have one or two elements. Here the cutoff frequency
does not normalize.
isAnalog A Boolean value indicating whether it uses analog filtering.
isTwoPass A Boolean value indicating whether it uses zero-phase filtering.

Learn more about matrix/array functions.

 Design-Time Functions 129
Functions: A - C

BUTTER_NUMERATOR
Calculates the numerator coefficients for the Butterworth filter.

Format
BUTTER_NUMERATOR (n, wn, fType, isDigital) returns ARRAY

Arguments

n An integer value indicating the order of the Butterworth filter.

wn An array of values indicating that the cutoff frequency can have one or two elements.
fType A text string. The filter type, can be one of {low, high, pass, stop}.
isDigital A Boolean value.

Example
The following example illustrates the BUTTER_NUMERATOR function:

Function butter_numerator (6, {0.1951, 0.4081}, "pass", 1)

Result {0.0005, 0, 0.0070, 0, -0.0094, 0, 0.0070, 0, -0.002, 8, 0,0.005}

Learn more about matrix/array functions.

130 Adams/View Function Builder
Functions: A - C

BUTTORD_FREQUENCY
Calculates the cutoff frequency for the Butterworth filter.

Format
BUTTORD_FREQUENCY (wp, ws, rp, rs, isDigital) returns ARRAY

Arguments

wp ARRAY: Passband corner frequency. wp, the cutoff frequency, has a value between 0 and
1, where 1 corresponds to half the sampling frequency (the Nyquist frequency).
ws ARRAY: Stopband corner frequency. ws is in the same units as wp; it has a value between
0 and 1, where 1 corresponds to half the sampling frequency (the Nyquist frequency).
rp REAL: Passband ripple, in decibels. This value is the maximum permissible passband loss
in decibels. The passband is 0<w<1p.
rs REAL: Stopband attenuation, in decibels. This value is the number of decibels the stopband
is down from the passband. The stopband is Ws<w<1.
isDigital A Boolean value.

Example
The following is an illustration of the BUTTORD_FREQUENCY function:

Function buttord_frequency ({0.2, 0.4}, {0.1, 0.5}, 3.0, 30.0, 1)

Result {0.19151, 04081}

Note: wp and ws must have the same array size, either one or two. It returns an array of size 1 or
two.

Learn more about matrix/array functions.

 Design-Time Functions 131
Functions: A - C

BUTTORD_ORDER
Calculates the order for the Butterworth filter.

Format
BUTTORD_ORDER (wp, ws, rp, rs, isDigital)

Arguments

wp ARRAY: Passband corner frequency. wp, the cutoff frequency, has a value between 0 and
1, where 1 corresponds to half the sampling frequency (the Nyquist frequency).
ws ARRAY: Stopband corner frequency. ws is in the same units as wp; it has a value between
0 and 1, where 1 corresponds to half the sampling frequency (the Nyquist frequency.)
rp REAL: Passband ripple, in decibels. This value is the maximum permissible passband loss
in decibels. The passband is 0<w<1p.
rs REAL: Stopband attenuation, in decibels. This value is the number of decibels the stopband
is down from the passband. The stopband is Ws<w<1.
isDigital A Boolean value.

Example
The following is an illustration of the BUTTORD_ORDER function:

Function buttord_order ({0.2, 0.4}, {0.1, 0.5}, 3.0, 30.0, 1)

Result 6

Note: wp and ws must have the same array size, either one or two.

Learn more about matrix/array functions.

132 Adams/View Function Builder
Functions: A - C

CEIL
Returns the smallest integer greater than x.

Format
CEIL(x)

Argument

x Any valid expression that evaluates to a real number.

Example
The following example illustrates the use of the CEIL function:

Function CEIL(10.001)
Result 11

Learn more about math functions.

 Design-Time Functions 133
Functions: A - C

CENTER
Returns a non-statistical mean of the values in an array.

Format
CENTER (A)

Argument

A Array of arbitrary shape.

Equation
Mathematically, CENTER is calculated as follows:

MIN  A  + MAX  A 
CENTER  A  = ------------------------------------------------
2.0

Example
The following example illustrates the use of the CENTER function:

Function CENTER ({1, 0, 4, 3})

Result 2.5

Learn more about matrix/array functions.

134 Adams/View Function Builder
Functions: A - C

CHDIR
Returns a 1 if CHDIR succeeded in changing to the directory you specified, or a 0 if it failed.

Format
CHDIR (String)

Argument

String Text string that specifies a directory.

Example
The result of the following function indicates the change to the /tmp directory:

Function CHDIR("/tmp")
Result 1

Learn more about system functions.

 Design-Time Functions 135
Functions: A - C

CLIP
Returns an MxNumvals matrix of values extracted from an MxN matrix, where:
• Output[I,1] = A[I,Start]
• Output[I,Numvals] = A[I,Start+Numvals-1]

The following conditions apply to the equations above:

• I=1 to M
• 1 < Start < N
• Numvals < (N-Start+1)

Format
CLIP (A, Start, Numvals)

Arguments

A An MxN matrix of real values.

Start The index to the first column of values to be included in the output.
Numvals The number of columns to be included in the output.

Example
The following example illustrates the use of the CLIP function:

Function CLIP( {[8, 10], [12,14], [16, 18]} , 1 ,1 )

Result 8, 12, 16

Learn more about matrix/array functions.

136 Adams/View Function Builder
Functions: A - C

COLS
Returns the number of columns in a given matrix.

Format
COLS (M)

Argument

M A given matrix.

Examples
The following examples illustrate the use of the COLS function:

Function COLS({1, 2, 3})

Result 1

Function COLS({[1, 2, 3]})

Result 3

Function COLS(marker_1.location)
Result 1

Learn more about matrix/array functions.

 Design-Time Functions 137
Functions: A - C

COMPRESS
Returns an array consisting of the non-empty values in the input array. An entry in the array is empty for
a value type as indicated below:
• Reals - Zero
• KEYS - Zero (that is, null_key)
• Integers - Zero
• Strings - The empty string or all spaces

In cases where the entire input array is empty, COMPRESS returns an array with a single value consisting
of zero for integer, real, or key arrays, and the empty string for string arrays.

Format
COMPRESS (any_array)

Arguments

any_array COMPRESS can accept any type of array (integer, real, database object, or string).

The array that is returned contains values of the same type.

Examples
variable create variable=my_ints int=1, 0, 0, 2, 0, 3, 0, 0
variable create variable=my_reals rea=1.1,0.0, 2.2, 3.3,0.0,
0.0, 4.4, 0.0
variable create variable=my_strings str=" ", "a", "", " b", "",
"", "c ", ""
variable create variable=my_strings2 str=" ", "", "", " "
variable create variable=compressed_ints
int=(eval(COMPRESS(my_ints)))
variable create variable=compressed_reals
rea=(eval(COMPRESS(my_reals)))
variable create variable=compressed_strings
str=(eval(COMPRESS(my_strings)))
variable create variable=compressed_strings2
str=(eval(COMPRESS(my_strings2)))
COMPRESS produces the following:
compressed_ints = 1, 2, 3 compressed_reals = 1.1, 2.2,
3.3, 4.4 compressed_strings = "a", " b", "c "
compressed_strings2 = ""
Learn more about matrix/array functions.
138 Adams/View Function Builder
Functions: A - C

COND
Returns the condition number of a matrix. The condition number of a matrix measures the sensitivity of
the solution of a system of linear equations to errors in the data. It gives an indication of the accuracy of
the results from matrix inversion and the linear equation solution.

Format
COND (squareMatrix)

Argument

squareMatrix A square matrix representing a linear system.

Learn more about matrix/array functions.

 Design-Time Functions 139
Functions: A - C

CONVERT_ANGLES
Converts a body-fixed 313 sequence into a user-specified sequence.

Format
CONVERT_ANGLES (E, OriType)

Arguments

E 3x1 or 1x3 Euler orientation sequence.

OriType Character string describing the contents of E. To define the rotation sequence, enter
space or body (character case is ignored), followed by three digits, such as 313 or 123.

The following list contains all the possible values for OriType:
Body121 Space121
Body123 Space123
Body131 Space131
Body132 Space132
Body212 Space212
Body213 Space213
Body231 Space231
Body232 Space232
Body312 Space312
Body313 Space313
Body321 Space321
Body323 Space323

Example
The following function converts input angles into a body-fixed 123 sequence:
CONVERT_ANGLES (E, "body123")
This function is shorthand for:
ANGLES(TMAT(E, "body313"), OriType)
The current default orientation type string can be obtained with the expression:
USER_STRING(".system_defaults.orientation_type")
Learn more about matrix/array functions.
140 Adams/View Function Builder
Functions: A - C

COS
Returns the cosine of an expression that represents a numerical value.

COS(x) = (ex + e-x) / 2.0Format

COS(x)

Argument

x Any valid expression that evaluates to a real number.

Example
The following example illustrates the use of the COS function. The location of marker_1 and marker_2
is shown in the figure below.

Function COS(DX(marker_2, marker_1, marker_2))

Result .99

Learn more about math functions.

 Design-Time Functions 141
Functions: A - C

COSH
Returns the hyperbolic cosine of an expression that represents a numerical value.
COSH(x) = (ex + e-x) / 2.0Format
COSH(x)

Argument

x Any valid expression that evaluates to a real number.

Example
The following function returns the hyperbolic cosine of the z component of the displacement of marker_2
with respect to marker_1. The result is computed in the coordinate system of marker_1. The location of
marker_1 and marker_2 is shown in the figure below.

Function COSH(DZ(marker_2, marker_1, marker_1))

Result 1

Learn more about math functions.

142 Adams/View Function Builder
Functions: A - C

CROSS
Returns the cross-product of two matrices.

Format
CROSS (M1, M2)

Arguments

M1 First matrix.
M2 Second matrix.
Note: CROSS will only accept 3x1 or 1x3 arrays.

The following example illustrates the use of the CROSS function:

Function CROSS({1,0,0}, {0,1,0})

Result {0, 0, 1}

Learn more about matrix/array functions.

 Design-Time Functions 143
Functions: A - C

CSPLINE
Creates an interpolated curve from input points with a specified number of values. Interpolates using the
cubic splines.
The algorithm that fits the cubic spline is from Computer Methods for Mathematical Computations by
Forsythe, Malcolm and Moler (1977, Prentice-Hall: Englewood Cliffs, NJ). The INTEGR function uses
the same algorithm.
The length of the Independent Data array must be equal to the Dependent Data array.

Format
CSPLINE (Independent Data, Dependent Data, Number of Output Values)

Arguments

Independent Data A 1xN array of x values for the curve to be interpolated. These x
values must be in ascending order, and the length of the array must be
greater than or equal to 4.
Dependent Data A 1xN array of y values for the curve to be interpolated.
Number of Output Values The number of values to be generated in the output array.

Example
The following function interpolates a set of four points with ordinal values from 1 to 4 and abscissal
values as shown, into a series of 10 abscissal values:

Function CSPLINE({1, 2, 3, 4}, {0, 2, 1, 3}, 10)

Result {0.0, 0.936, 1.704, 2.0, 1.741, 1.259, 1.0, 1.296, 2.037, 3.0}

To compute the ordinal values for these splined values, you can use the SERIES2 function as follows:

Function SERIES2(1, 4, 10)

Result {1.0, 1.333, 1.667, 2.0, 2.333, 2.667, 3.0, 3.333, 3.667, 4.0}

Learn more about matrix/array functions.

144 Adams/View Function Builder
Functions: A - C

CUBIC_SPLINE
Creates an interpolated curve from input points with a specified number of values. Interpolates using a
third order Lagrangian polynomial.
The length of the Independent Data array must be equal to the Dependent Data array.
Reference: Digital Computation and Numerical Methods. Southworth, 1965. Chapter 8.7

Format
CUBIC_SPLINE (Independent Data, Dependent Data, Number of Output Values)

Arguments

Independent Data A 1xN array of x values for the curve to be interpolated. The x
values must be in ascending order, and the length of the array must
be greater than or equal to 4.
Dependent Data A 1xN array of y values for the curve to be interpolated.
Number of Output Values The number of values to be generated in the output array.

Example
The following function interpolates a set of four points with ordinal values from 1 to 4 and abscissal
values as shown, into a series of 10 abscissal values:

Function CUBIC_SPLINE({1, 2, 3, 4}, {0, 2, 1, 3}, 10)

Result {0.0, 1.0, 1.667, 2.0, 2.0, 1.667, 1.0, 1.333, 2.0, 3.0}

To compute the ordinal values for these splined values, you can use the SERIES2 function as follows:

Function SERIES2(1, 4, 10)

Result {1.0, 1.333, 1.667, 2.0, 2.333, 2.667, 3.0, 3.333, 3.667, 4.0}

Learn more about matrix/array functions.

 Design-Time Functions 145
Functions: D - E

Functions: D - E
146 Adams/View Function Builder
Functions: D - E

DB_ACTIVE
Returns a Boolean value indicating that the object will or will not take part in simulations. Activity
checking is done recursively and through the group mechanism, so you get a true indication as to whether
this element is truly active (accessing the attr.active field will not tell you this).

Note: This function will NOT work reliably in the "spreadsheet" mode, and therefore must be
enclosed in an eval ( ) function call.

Format
DB_ACTIVE (object)

Argument

object A database object about which activity information is desired.

Example
The following is an illustration of how the DB_ACTIVE function is used:
in condition=(eval (db_active(.model_1.part_1))) ! Then the
part and all of its children will be included in ! subsquent
simulations.end
Learn more about database functions.
 Design-Time Functions 147
Functions: D - E

DB_ANCESTOR
Returns the first ancestor of an object of the type you specify. This ancestor might be the direct parent of
the given object, its grandparent, or some more distant object.
If the given child has no ancestor of the specified type, then the function returns NONE.

Format
DB_ANCESTOR (Child,Type)

Argument

Child The object whose ancestor is to be found.

Type A character string specifying the object type of the returned value.

Example
The following is an illustration of how the DB_ANCESTOR function is used:

Function DB_ANCESTOR (.model_1.part_1.marker_1, "model" )

Result .model_1

Learn more about database functions.

148 Adams/View Function Builder
Functions: D - E

DB_CHANGED
Returns a 1 if an element in the database has changed; returns a 0 if there was no change.

Format
DB_CHANGED ( )

Argument
None

Example
The following command sequence prompts you to cancel a file read, if the database contains unsaved
modifications:

Learn more about database functions.

 Design-Time Functions 149
Functions: D - E

DB_CHILDREN
Returns an array of objects of a given type, that are children of the object you specified.

Format
DB_CHILDREN (Object Name, Object Type)

Arguments

Object Name Name of a database object.

Object Type Character string (see DB_TYPE).

Example
The following function provides information on a marker in the default model:

Learn more about database functions.

150 Adams/View Function Builder
Functions: D - E

DB_COUNT
Returns the number of values in a given field of the object you specified.

Format
DB_COUNT (Object Name, Field Name)

Arguments

Object Name Name of a database object.

Field Name Character string.

Example
The following function creates a variable with an integer value of 3:
variable create variable=xx real_value=1,2,5variable create
variable=nn & integer_value=(DB_COUNT(xx.self, "real_value"))
Learn more about database functions.
 Design-Time Functions 151
Functions: D - E

DB_DEFAULT
Returns the default object of a given type. Uses the database object named system_defaults to specify the
default object.

Format
DB_DEFAULT (Defaults Object Name, Object Type)

Arguments

Defaults Object Name Name of the defaults in the database, always system_defaults.
Object Type Character string (see DB_TYPE).

Example
The following function creates a variable that is the default part:
variable create variable=default_part &
object_value=(DB_DEFAULT(system_defaults, "part"))
Learn more about database functions.
152 Adams/View Function Builder
Functions: D - E

DB_DEFAULT_NAME
Returns the name for the given object based on the state of the default for formatting names. The name
will be either a full name or a minimum unique name.

Format
DB_DEFAULT_NAME (object)

Arguments

object Any Adams/View object.

Examples
If you have two markers (one on par1 and one on ground) and call the function as follows:
DB_DEFAULT_NAME(.model_1.par1.mar1)
you should see the following when the default is set to minimum unique names or Adams IDs:
par1.mar1
and the following when the default is set to full names:
.model_1.par1.mar1
Learn more about database functions.
 Design-Time Functions 153
Functions: D - E

DB_DEFAULT_NAME_FOR_TYPE
Returns the name for the given object based on the state of the default for formatting names. The name
will be unique only for objects of the specified type.

Format
DB_DEFAULT_NAME_FOR_TYPE (object, type)

Arguments

object Any Adams/View object.

type String for the object's type or class.

Examples
If you have two objects named joint1 (one in the model and one in an analysis) and call the function as
follows:
DB_DEFAULT_NAME_FOR_TYPE(.model_1.joint1, "constraint")
you should see the following when the default is set to minimum unique names or Adams IDs:
joint1
and the following when the default is set to full names:
.model_1.joint1
Learn more about database functions.
154 Adams/View Function Builder
Functions: D - E

DB_DELETE_DEPENDENTS
Returns an array of objects that are dependents of the object you specified. Each of the objects in the array
normally prevent the specified object from being deleted.

Format
DB_DELETE_DEPENDENTS (Object Name)

Argument

Object Name Name of a database object.

Example
The following function returns an alert if par_1 has dependent objects:

Learn more about database functions.

 Design-Time Functions 155
Functions: D - E

DB_DEL_PARAM_DEPENDENTS
Returns an array of all the parametric expressions that depend on the object you specified.

Format
DB_DEL_PARAM_DEPENDENTS (Object Name)

Argument

Object Name Name of a database object.

Example
The following sequence of commands finds objects with parametric dependencies on par3:

Learn more about database functions.

156 Adams/View Function Builder
Functions: D - E

DB_DEL_UNPARAM_DEPENDENTS
Returns a constant integer value of zero, and deletes all the parametric expressions that depend on the
object you specified.

Format
DB_DEL_UNPARAM_DEPENDENTS (Object Name)

Argument

Object Name Name of a database object.

Example
The following commands delete all parametric dependencies on par3:

Learn more about database functions.

 Design-Time Functions 157
Functions: D - E

DB_DEPENDENTS
Returns an array of all objects of a given type that are dependents of the object you specified.

Format
DB_DEPENDENTS (Object Name, Object Type)

Arguments

Object Name Name of a database object.

Object Type Character string (see DB_TYPE).

Example
The following example lists information about all marker objects that depend on the design variable,
DV_1. Note that .self is appended to DV_1 so the functions refers to the design variable object DV_1
and not the value in DV_1.

Learn more about database functions.

158 Adams/View Function Builder
Functions: D - E

DB_EXISTS
Returns a 1 if the object you specified exists; returns a 0 if it doesn't.

Format
DB_EXISTS (Name String)

Argument

Name String Character string representing the name of an object.

Example
The following function creates marker_3 if .mod1.par1 exists:
if condition=(DB_EXISTS(".mod1.par1")) marker create
marker=marker_3
end
Learn more about database functions.
 Design-Time Functions 159
Functions: D - E

DB_FIELD_FILTER
Returns an array, from a given array of field names, containing a subset of the original array. The values
in the array must meet the requirements that you specify in filter parameters.

Format
DB_FIELD_FILTER (Filter Strings, Field Strings)

Arguments

Filter Strings Array of character strings that is similar to the macro parameter specification language
used in Adams/View:

• object_type = database_object_type uses the type specified as the

database_object_type for field lookups. The value of database_object_type is
one of the values returned by the function SELECT_TYPE (but cannot be a
class name).
• t = type selects all fields that can hold an object of type. type can be the
following subset of types from the macro language:
If type is: The field holds:
Bool A boolean value.
String Strings
Real Real numbers
Integer Integer numbers
Point Ordered triples, such as location and orientation.
Database_object_type A database object
160 Adams/View Function Builder
Functions: D - E

• c = n where n  0 ; n = 0 means an open array, n > 0 means a fixed array of

length exactly equal to n.
• alias = boolean indicates whether the field is or is not an alias for some other
field. Values for boolean are:
• True = field must be an alias.
• False = field must not be an alias.

If you do not specify an alias, then the field can be either an alias or not.
• assoc = relation indicates the field has a particular relationship to the object.
Values for relation are:
• Child
• Reference
• Twoway
Field Strings List of field names you want to filter.

Example
The following is a typical calling sequence that produces all the real scalar fields for the spring damper
object:

Learn more about database functions.

 Design-Time Functions 161
Functions: D - E

DB_FIELD_TYPE
Returns a string that describes the type of data in a field beneath the object type you specified.

Format
DB_FIELD_TYPE (Object Type, Field Name)

Arguments

Object Type Name of a database object (see DB_TYPE).

Field Name Character string.

Example
The following example determines that the width field on the Graphic_Interface_Dialog_Box object is
of the type REAL (keep the expression on one line):

Function variable create variable=var6 &

string=(DB_FIELD_TYPE
("Graphic_Interface_Dialog_Box", "width"))
Result REAL

Learn more about database functions.

162 Adams/View Function Builder
Functions: D - E

DB_FILTER_NAME
Returns an array of objects whose names match the filter parameters you specified.

Format
DB_FILTER_NAME (Objects to Filter, Filter String)

Arguments

Objects to Filter Array of database objects

Filter String Character string containing a wildcard sequence to use when matching object
names.

Example
The following example assigns the color yellow to all the markers whose names start with a or c:

Learn more about database functions.

 Design-Time Functions 163
Functions: D - E

DB_FILTER_TYPE
Returns an array of objects whose types match the filter parameters you specified.

Format
DB_FILTER_TYPE (Objects to Filter, Filter Type String)

Arguments

Objects to Filter Array of database objects.

Filter Type String Character string (see DB_TYPE).

Example
The following example returns information about markers in the select list:

Learn more about database functions.

164 Adams/View Function Builder
Functions: D - E

DB_FULL_NAME_FROM_SHORT
Returns the full name for the named object of the specified type. The input name can be either a full name
or a minimum unique name.

Format
DB_FULL_NAME_FROM SHORT (short_name, type)

Arguments

short_name Short name of the object.

type String for the object’s type or class.

Examples
If you have two objects named joint1 (one in the model and one in an analysis) and call the function as
follows:
DB_FULL_NAME_FROM_SHORT("joint1", "constraint")
you should see:
.model_1.joint1
Learn more about database functions.
 Design-Time Functions 165
Functions: D - E

DB_FULL_TYPE_FIELDS
Returns an array of strings for the names of the fields (including aliases) for the object you specified.

Format
DB_FULL_TYPE_FIELDS (Objects Type String)

Argument

Objects Type String Character string denoting an object type (see DB_TYPE).

Example
The following commands find all the field names on a marker:

Learn more about database functions.

166 Adams/View Function Builder
Functions: D - E

DB_IMMEDIATE_CHILDREN
Returns an array of all objects that are immediate children of the object you specified.

Format
DB_IMMEDIATE_CHILDREN (Object Name, Object Type)

Arguments

Object Name Name of a database object.

Object Type Character string (see DB_TYPE).

Examples
The following commands display all the names of the modeling objects in model_1:

Learn more about database functions.

 Design-Time Functions 167
Functions: D - E

DB_OBJECT_COUNT
Returns the number of object names in the array of database objects you specified.

Format
DB_OBJECT_COUNT (Objects)

Argument

Objects Names of database objects.

Example
The following example stores the number of objects on the select_list in the variable
NumSelectedObjects:
variable set variable=NumSelectedObjects
int=(EVAL(DB_OBJECT_COUNT(select_list.objects)))
Learn more about database functions.
168 Adams/View Function Builder
Functions: D - E

DB_OBJ_EXISTS
Returns a logical value indicating whether the specified object exists as an immediate child of the parent
object.

Format
DB_OBJ_EXISTS (Parent, Name)

Arguments

Parent The object defining the search domain.

Name A character string naming the object for which you are searching.

Examples
The following illustrates the use of DB_OBJ_EXISTS:

Function DB_OBJ_EXISTS(.model_1.par1, "mar1")

Result Returns 0 if mar1 does not exist, 1 if it does.

Learn more about database functions.

 Design-Time Functions 169
Functions: D - E

DB_OBJ_EXISTS_EXHAUSTIVE
Returns a Boolean value indicating whether the object specified exists or not. It does an exhaustive search
through the specified object context to find anything with a given name.

Format
DB_OBJ_EXISTS_EXHAUSTIVE (ContextObject, Name)

Arguments

ContextObject The object in which to search for a child with the given name.
Name A character string naming the object.

Examples
You might branch your command file based upon the existence of a particular object:
if condition=(db_obj_exists_exhaustive(.model_1, "marker_1"))
Learn more about database functions.
170 Adams/View Function Builder
Functions: D - E

DB_OF_CLASS
Returns a 1 if an object is a member of a given class; returns a 0 if it is not. The class_name is one of the
values the SELECT_TYPE function presents, and can be either a type name or a class name.

Format
DB_OF_CLASS (Object Name, Object Class)

Arguments

Object Name Name of a database object.

Object Class Character string (see DB_TYPE).

Example
The following example changes the color of the object represented by the variable myobject, if the
variable is a marker:
if cond=(DB_OF_CLASS(myobject,"marker")) marker attribute
marker=(myobject) color=red end
Learn more about database functions.
 Design-Time Functions 171
Functions: D - E

DB_OF_TYPE_EXISTS
Returns a 1 if an object with the name and type you specified exits; returns a 0 if it does not exist.
Distinguishes between objects with the same name but different type, and is especially useful when full
path name isn't known.

Format
DB_OF_TYPE_EXISTS (Name String, Object Type)

Argument

Name String Character string representing the name of an object.

Object Type Character string, see DB_TYPE.

Example
if condition=(DB_OF_TYPE_EXISTS(".mod1.par1.node1", "marker"))
marker copy marker=.mod1node1 new_marker=.mod1.ground.node1 end
Learn more about database functions.
172 Adams/View Function Builder
Functions: D - E

DB_OLDEST_ANCESTOR
Returns the most distant ancestor of an object of the type specified. This ancestor might be the direct
parent of the given object, its grandparent, or some more distant object. This can be helpful to find the
top-level model when submodels are present.
If the given child has no ancestor of the specified type, then the function returns NONE.

Format
DB_OLDEST_ANCESTOR (Child,Type)

Argument

Child The object whose ancestor is to be found.

Type A character string specifying the object type of the returned value.

Example
The following example illustrates the use of the DB_OLDEST_ANCESTOR function:

Function DB_OLDEST_ANCESTOR (.model_1.part_1.marker_1,"model" )

Result .model_1

Learn more about database functions.

 Design-Time Functions 173
Functions: D - E

DB_REFERENTS
Returns an array of objects of a given type that are referenced by the object you specified.

Format
DB_REFERENTS (Object Name, Object Type)

Arguments

Object Name Name of a database object.

Object Type Character string (see DB_TYPE).

Example
The following example stores the array of objects that refer to rev1, in the variable db06:

Learn more about database functions.

174 Adams/View Function Builder
Functions: D - E

DB_SHORT_NAME
Returns the shortest unique name for the given object. This name may become non-unique when new
objects are created, so it is best not to use this value to generate names for files that will be present for a
long time.

Format
DB_SHORT_NAME (object)

Arguments

object Any Adams/View object.

Examples
If you have two markers with the same name on two different parts, and call the function as follows:
DB_SHORT_NAME(.model_1.par1.mar1)
you should see:
par1.mar1
as the result.
Learn more about database functions.
 Design-Time Functions 175
Functions: D - E

DB_TWO_WAY
Returns an array of objects that have two-way associativity with the object you specified. Two-way
associativity involves a two-way relationship, such as between a model and a view displaying that model,
where one or the other may be deleted and the remaining one will not be affected.

Format
DB_TWO_WAY (Object Name, Object Type)

Arguments

Object Name Name of a database object.

Object Type Character string (see DB_TYPE).

Example
The following commands store the array of objects that have two-way associativity to .mod1 in variable
db07:

Learn more about database functions.

176 Adams/View Function Builder
Functions: D - E

DB_TYPE
Returns a string representing an object type.

Format
DB_TYPE (Object Name)

Argument

Object Name Name of a database object (see SELECT_TYPE).

Examples
The following example processes the part1 object only if it is a part:
if cond=(DB_TYPE(part1)=="part") list info part=(part1)end
Learn more about database functions.
 Design-Time Functions 177
Functions: D - E

DB_TYPE_FIELDS
Returns an array of strings for the names of the fields (excluding aliases) for the object type you specified.

Format
DB_TYPE_FIELDS (Objects Type String)

Argument

Object Type String Character string denoting an object type (see DB_TYPE).

Example
The following commands return all the field names for maker:

Learn more about database functions.

178 Adams/View Function Builder
Functions: D - E

DET
Returns the determinant of a square matrix.

Format
DET (M)

Argument

M A square matrix.

Example
The following example illustrates the use of the DET function:

Function DET ({[1,2,0], [2,2,-1], [3,1,1]})

Result -8.0

Learn more about matrix/array functions.

 Design-Time Functions 179
Functions: D - E

DETREND
Returns a 1xN array of detrended data computed by subtracting the linear least squares fit from the input
data stream.

Format
DETREND (INDEP, DEPEND)

Arguments

INDEP A 1xN array of independent data.

DEPEND A 1xN array of data dependent on input independent data.

Example
The following example illustrates the use of the DETREND function:

Function DETREND(SERIES(0,1,5), {0,1,4,9,16})

Result 2.0, -1.0, -2.0, -1.0, 2.0

Learn more about matrix/array functions.

180 Adams/View Function Builder
Functions: D - E

DIFF
Returns a 1xN array of approximations to the derivatives at the points in the input data. To compute the
derivative, the DIFF function fits a cubic spline to the input data and returns the derivatives of the
approximating polynomials at each point.
The length of the INDEP array must be equal to the DEPEND array.

Format
DIFF (INDEP, DEPEND)

Arguments

INDEP A 1xN array of independent data. These x values must be in ascending order, and the
length of the array must be greater than or equal to 4.
DEPEND A 1xN array of dependent data on input independent data.

Example
The following example illustrates the use of the DIFF function:

Function DIFF(SERIES(0,1,5), {0,1,4,9,16})

Result 0, 2.0, 4.0, 6.0, 8.0

Learn more about matrix/array functions.

 Design-Time Functions 181
Functions: D - E

DIFFERENTIATE
Returns the derivative at each input point on curve C. To compute the derivative at each point, the
DIFFERENTIATE function fits a cubic spline to a 2xN matrix representation of curve C and returns the
derivatives of the approximating polynomials at each point. The curve of derivatives that
DIFFERENTIATE returns has the same x values as curve C.

Format
DIFFERENTIATE (C)

Argument

C Input curve.

Example
The following xy_plot command creates a curve, diff1, whose x values are the same as the x values of
curve1 on plot1:
xy_plots curve create curve=diff1 &
x_values=(.plot1.curve1.x_data.values) &
y_values=(DIFFERENTIATE({.plot1.curve1.x_data.values, &
.plot1.curve1.y_data.values})[2,*])
The matrix that DIFFERENTIATE receives is 2xN:
• The first row has the x values of curve1.
• The second row has the y values of curve1.

DIFFERENTIATE returns two rows:

• The first is the same as the x values of curve1.
• The second is the derivatives of curve1.

Learn more about matrix/array functions.

182 Adams/View Function Builder
Functions: D - E

DIM
Returns the positive difference of the instantaneous values of two expressions, each representing a
numerical value.

DIM(x1, x2) = 0 if x1  x2
DIM(x1, x2) =x1-x2 if x1 > x2

Note: DIM is a discontinuous function. Use it with caution.

Format
DIM(x1, x2)

Arguments

x1 Any valid expression that evaluates to a real number.

x2 Any valid expression that evaluates to a real number.

Example
The following example illustrates the use of the DIM function:

Function DIM(5*4,5)
Results 15

Learn more about math functions.

 Design-Time Functions 183
Functions: D - E

DM
Returns the magnitude of the translational displacement from one coordinate system object to another.

Format
DM (Object 1,Object 2)

Arguments

Object 1 Coordinate system object to which the translational displacement magnitude is measured.
Object 2 Coordinate system object from which the translational displacement magnitude is
measured.

symbol
Mathematically, DM is calculated as follows:

DM =   R 01 – R 02    R 01 – R 02  

where:

• R 01 is the displacement of the Object 1, O1, in the global coordinate system.

• R 02 is the displacement of the Object 2, O2, in the global coordinate system.

Example
In the following illustration, the DM function returns a number greater than or equal to 0.

Function DM (marker_O1, marker_O2)

Result 13
184 Adams/View Function Builder
Functions: D - E

Learn more about modeling functions.

 Design-Time Functions 185
Functions: D - E

DMAT
Returns a square matrix with the elements of M along the diagonal, and zero elsewhere. This is useful for
scaling locations.

Format
DMAT(M)

Argument

M An Nx1 or 1xN array.

Example
The following example illustrates the use of the DMAT function:

Function DMAT({1, 2, 3})

Result {{1, 0, 0}, {0, 2, 0}, {0, 0, 3}}

Another possible use is:

DMAT({1, 1, 2.5}) @ polyline.location
This computes a new collection of locations with the z component scaled by a factor of 2.5.
Learn more about matrix/array functions.
186 Adams/View Function Builder
Functions: D - E

DOE_MATRIX
Returns either a:
• Matrix of design of experiments (DOE) a row from that matrix
• The count of rows from that matrix

The argument array contains the information needed to construct the matrix and to determine the results
which you want returned.

Format
DOE_MATRIX (ARGUMENT_ARRAY)

Arguments

ARGUMENT_ARRAY An array of integers containing either three or four values.

The first value is the type of algorithm to use to create the matrix.

Use these numbers in the first entry of the array:

• 0 - Casewise
• 1 - Central Composite
• 2 - Box-Behnken
• 3 - Full Factorial
The second entry in the array indicates the number of variables that are to
be used for the DOE.

The third entry indicates the number of levels on each variable.

The fourth entry indicates whether you want the data centered or 1-based.
Centered data is what the SIMULATION and OPTIMIZE commands
require, but 1-based can be useful if you are writing your own DOE loop
using the FOR command. A value of one indicates that the data should be
centered, and a value of zero indicates that it should be 1-based.

If the fifth entry does not exist, then the result of the function is a complete
DOE matrix, which will have nTrials rows and nVariables columns. If you
enter zero as the fifth array value, then the result of the function is just the
number of trials in that DOE matrix. Any other value indicates that just that
row of the matrix is to be returned.
 Design-Time Functions 187
Functions: D - E

Examples
The following example returns the number of trials for the Box-Behnken matrix with two variables each
having five levels. The value returned is 9.
DOE_MATRIX({2, 2, 5, 0, 0})
This example returns the fifth row of the Full Factorial matrix with variables variables each having three
levels. The centered values returned are {-1, -1, 0, 0}.
DOE_MATRIX({3, 4, 3, 1, 5})
This example returns the Central Composite matrix for two variables with three levels. The value
returned is the centered data:
DOE_MATRIX({1, 2, 3, 1})
{{0, 0}, {0, -1}, {0, 1}, {-1, 0}, {1, 0}, {-1, -1}, {-1, 1}, {1, -1}, {1, 1}}
Learn more about matrix/array functions.
188 Adams/View Function Builder
Functions: D - E

DOE_NUM_TERMS
Returns the number of terms in the polynomial that the OPTIMIZE_FIT_RESPONSE_SURFACE
command produces. The OPTIMIZE_FIT_RESPONSE _SURFACE command takes a parameter to
specify the degree for each variable in the solution, and produces a polynomial, accordingly. The input
to DOE_NUM_TERMS is an array of these same integers that you supply to the
OPTIMIZE_FIT_RESPONSE_SURFACE command in it POLYNOMIAL_DEGREES parameter.

Format
DOE_NUM_TERMS(ORDER_ARRAY)

Arguments

ORDER_ARRAY An array of integers giving the degree of each variable in the polynomial.

Examples
The following examples illustrate the use of the DOE_NUM_TERMS function:

Function DOE_NUM_TERMS({1,1,1})
Result Returns 4 (the intercept term is included)

Function DOE_NUM_TERMS({1,2,2,1})
Result Returns 8

Learn more about matrix/array functions.

 Design-Time Functions 189
Functions: D - E

DOT
Returns the dot product of two matrixes.

Format
DOT (M1, M2)

Arguments

M1 First matrix.
M2 Second matrix.

Example
The following example illustrates the use of the DOT function:

Function DOT({1,1,0},{1,0,1})
Result 1

Learn more about matrix/array functions.

190 Adams/View Function Builder
Functions: D - E

DX
Returns an x component of translational displacement from one coordinate system object to another.

Format
DX (Object 1, Object 2, Reference Frame)

Arguments

Object 1 Coordinate system object to which the translational displacement component is

measured.
Object 2 Coordinate system object from which the translational displacement component is
measured.
Reference Frame Coordinate system object defining the x-axis; used to measure the translational
displacement component.

symbol
Mathematically, DX is calculated as follows:

DX =  R 01 – R 02   x̂ R
where:

• R 01 is the displacement of the Object 1, O1, in the global coordinate system.

• R 02 is the displacement of the Object 2, O2, in the global coordinate system.

• x̂ R is the unit vector along the x-axis of the Reference Frame, R.
 Design-Time Functions 191
Functions: D - E

Example
In the following illustration, the DX function returns the x component of the translational displacement
from marker_O2 to marker_O1, along the x-axis of marker_R:

Function DX(marker_O1, marker_O2, marker_R)

Result 12

Learn more about modeling functions

192 Adams/View Function Builder
Functions: D - E

DY
Returns a y component of translational displacement from one coordinate system object to another.

Format
DY (Object 1, Object 2, Reference Frame)

Arguments

Object 1 Coordinate system object to which the translational displacement component is

measured.
Object 2 Coordinate system object from which the translational displacement component is
measured.
Reference Frame Coordinate system object defining the y-axis; used to measure the translational
displacement component.

symbol
Mathematically, DY is calculated as follows:

DY =  R 01 – R 02   ŷ R
where:

• R 01 is the displacement of the Object 1, O1, in the global coordinate system.

• R 02 is the displacement of the Object 2, O2, in the global coordinate system.

• ŷ R is the unit vector along the y-axis of the Reference Frame, R.
 Design-Time Functions 193
Functions: D - E

Example
In the following illustration, the DY function returns the y component of the translational displacement
from marker_O2 to marker_O1, along the y-axis of marker_R:

Function DY(marker_O1, marker_O2, marker_R)

Result -5

Learn more about modeling functions

194 Adams/View Function Builder
Functions: D - E

DZ
Returns a z component of translational displacement from one coordinate system object to another.

Format
DZ (Object 1, Object 2, Reference Frame)

Arguments

Object 1 Coordinate system object to which the translational displacement component is

measured.
Object 2 Coordinate system object from which the translational displacement component is
measured.
Reference Frame Coordinate system object that defines the z-axis; used to measure the translational
displacement component.

symbol
Mathematically, DZ is calculated as follows:

DZ =  R 01 – R 02   ẑ R
where:

• R 01 is the displacement of the Object 1, O1, in the global coordinate system.

• R 02 is the displacement of the Object 2, O2, in the global coordinate system.

• ẑ R is the unit vector along the z-axis of the Reference Frame, R.
 Design-Time Functions 195
Functions: D - E

Example
In the following illustration, the DZ function returns the z component of the translational displacement
from marker_O2 to marker_O1, along the z-axis of marker_R:

Function DZ(marker_O1, marker_O2, marker_R)

Result 0

Learn more about modeling functions

196 Adams/View Function Builder
Functions: D - E

EIG_DI
Returns a vector of the imaginary components of the generalized eigenvectors of matrices A and B.

Format
EIG_DI (A, B)

Arguments

A,B A pair of like-sized square matrices.

Examples
The following example illustrates the use of the EIG_DI function:

Function EIG_DI ({{1,2},{3,4}}, {{5,6},{7,8}})

Result {4.9884522991E-08, 0.0, 0.0, -4.9884522991E-08}

Learn more about matrix/array functions.

 Design-Time Functions 197
Functions: D - E

EIG_DR
Returns a vector of the real components of the generalized eigenvectors of matrices A and B.

Format
EIG_DR (A, B)

Arguments

A, B A pair of like-sized square matrices.

Examples
The following illustrates the use of the EIG_DR function:

Function EIG_DR ({{1,2},{3,4}}, {{5,6},{7,8}})

Result {1.0, 0.0, 0.0, 1.0}

Learn more about matrix/array functions.

198 Adams/View Function Builder
Functions: D - E

EIG_VI
Returns a vector of the imaginary components of the generalized eigenvectors of matrices A and B.

Format
EIG_VI (A, B)

Arguments

A, B A pair of like-sized square matrices.

Examples
The following example illustrates the use of the EIG_VI function:

Function EIG_VI ({{1,2},{3,4}}, {{5,6},{7,8}})

Result {5.7669324483E-09, 6.7041961058E-09, -5.7669324483E-09, -6.7041961058E-09}

Learn more about matrix/array functions.

 Design-Time Functions 199
Functions: D - E

EIG_VR
Returns a vector of the real components of the generalized eigenvectors of matrices A and B.

Format
EIG_VR (A, B)

Arguments

A, B A pair of like-sized square matrices.

Examples
The following example illustrates the use of the EIG_VR function:

Function EIG_VR ({{1,2},{3,4}}, {{5,6},{7,8}})

Result {0.9999999933, -0.9999999933, 0.9999999933, -0.9999999933}

Learn more about matrix/array functions.

200 Adams/View Function Builder
Functions: D - E

EIGENVALUES_I
Returns a vector of the imaginary components of the generalized eigenvectors of matrices A and B.

Format
EIGENVALUES_I (A, B)

Arguments

A, B A pair of like-sized square matrices.

Examples
The following example illustrates the use of the EIGENVALUES_I function:

Function EIGENVALUES_I({{1,2},{3,4}}, {{5,6},{7,8}})

Result {5.7669345583E-09, 6.7041961058E-09, -5.7669345583E-09, -6.7041961058E-09}

Learn more about matrix/array functions.

 Design-Time Functions 201
Functions: D - E

EIGENVALUES_R
Returns a vector of real components of the generalized eigenvectors of matrices A and B.

Format
EIGENVALUES_R (A, B)

Arguments

A, B A pair of like-sized square matrices.

Examples
The following example illustrates the use of the EIGENVALUES_R function:

Function EIGENVALUES_R({{1,2},{3,4}}, {{5,6},{7,8}})

Result {0.9999999933, -0.9999999933, 0.9999999933, -0.9999999933}

Learn more about matrix/array functions.

202 Adams/View Function Builder
Functions: D - E

ELEMENT
Indicates if a real value is an element of an array.

Format
ELEMENT (A, X)

Arguments

A An array.
B A real number.

Examples
For the following examples, assume that array A contains a list of integers from 1 through 10:

Function ELEMENT(".MOD1.A",3)
Result true

Function ELEMENT(".MOD1.A",11)
Result false

Learn more about matrix/array functions.

 Design-Time Functions 203
Functions: D - E

EXCLUDE
Excludes a value from an array.

Format
EXCLUDE (A, X)

Arguments

A An array.
X A real number.

Example
Assume that the array in the following function contains the values 1 through 10:

Function EXCLUDE(.MOD1.A,4)
Result removes 4 from the list

Learn more about matrix/array functions.

204 Adams/View Function Builder
Functions: D - E

EXECUTE_VIEW_COMMAND
Returns a numerical value indicating whether EXECUTE_VIEW_COMMAND succeeded or failed in
executing an Adams/View command. If the command was successful, EXECUTE_VIEW_COMMAND
returns a 1; otherwise, it returns a 0.

Format
EXECUTE_VIEW_COMMAND (Command)

Argument

Command Character string containing an Adams/View command.

Example
The following example illustrates the use of the EXECUTE_VIEW_COMMAND function:

Function EXECUTE_VIEW_COMMAND("marker create marker=" // UNIQUE_NAME("mar"))

Result returns a 1 and creates a marker with a unique name

Learn more about system functions.

 Design-Time Functions 205
Functions: D - E

EXP
Returns the exponential for each element of x.

Format
EXP(x)

Argument

X Any valid expression that evaluates to a real number.

Example
The following example illustrates the use of the EXP function. The location of marker_1 and marker_2
is shown in the figure below.

Function EXP(DX(marker_2, marker_1, marker_1))

Result 54.6

Learn more about math functions.

EXPR_EXISTS
Returns a 1 if an expression exists in a given field of an object that you specify; returns a 0 if it does not.
206 Adams/View Function Builder
Functions: D - E

Format
EXPR_EXISTS (Object Field)

Argument

Object Field Character string denoting the name of an object suffixed with a field name.

Examples
The following examples assume that you created a marker as follows:
marker create marker=mar1 location=(loc_relative_to({0,0,0},
mar2)) ori=1,2,3

Function EXPR_EXISTS(".mar1.location")
Result 1 (true)

Function EXPR_EXISTS(".mar1.orientation")
Result 0 (false)

Learn more about database functions.

 Design-Time Functions 207
Functions: D - E

EXPR_REFERENCE
Returns a string containing the name of the reference to the expression. If no expression is found,
EXPR_REFERENCE returns an empty string. Similarly, if the reference index is out of bounds, it returns
an empty string.

Format
EXPR_REFERENCE (Expression, Reference)

Argument

Exression A character string name of a database field.

Reference A numeric index into the list of references to that field.

Examples
var set var=load_dep
&str=(eval(expr_reference(".mod.par.mar.loc", 1)))
Learn more about database functions.
208 Adams/View Function Builder
Functions: D - E

EXPR_STRING
Returns a text string containing an expression in a given field of an object that you specify.

Format
EXPR_STRING (Object Field)

Argument

Object Field Character string denoting the name of an object suffixed with a field name.

Examples
The following examples assume that you created a marker as follows:
marker create marker=mar1 location=(loc_relative_to({0,0,0},
mar2)) ori=1,2,3

Function EXPR_STRING("mar1.location")
Result "(LOC_RELATIVE_TO({0, 0, 0}, .mod1.ground.mar2))"

Function EXPR_STRING(".mar1.orientation")
Result " " (an empty string)

Learn more about database functions.

 Design-Time Functions 209
Functions: F - L

Functions: F - L
FFTMAG
Returns an array of magnitudes calculated by applying the FFT function to input values. FFTMAG is
very useful in determining the natural frequencies of a data stream.

Format
FFTMAG (A, N)

Arguments

A An array of real values.

N An integer value which indicates the number output magnitudes. This must be greater than or
equal to the number of input values. If N is an odd number, the function returns (N+1)/2
output values. If N is an even number, (N/2 + 1) number of values will be returned.

Example
The following example illustrates the use of the FFTMAG function:

Function FFTMAG({0, 1, 4, 9, 16}, 5)

Result 12.0, 7.1968, 4.2197

Learn more about matrix/array functions.

210 Adams/View Function Builder
Functions: F - L

FFTPHASE
Returns an array of phase values calculated by applying the FFT function to input values.

Format
FFTPHASE (A, N)

Arguments

A An array of real values.

N An integer value which indicates the number output values. This must be greater than or equal
to the number of input values. If N is an odd number, the function returns (N+1)/2 output
values. If N is an even number, (N/2 + 1) number of values will be returned.

Example
The following example illustrates the use of the FFTPHASE function:

Function FFTPHASE({0, 1, 4, 9, 16}, 5)

Result 0.0, 107.012, 157.356

Learn more about matrix/array functions.

 Design-Time Functions 211
Functions: F - L

FILE_ALERT
Returns an integer representing the command button you selected after Adams/View displayed the Alert
dialog box. Returns a 0 if a named file does not exist.
The Alert dialog box contains the message: <file name> exists. Create backup copy? It has three
command buttons labeled Yes, No, and Cancel.

Format
FILE_ALERT (File Name)

Argument

File Name Text string naming a file.

Example
The following example illustrates the use of the FILE_ALERT function:

Function FILE_ALERT("aview.log%")
Result returns an Alert box, as shown below.

Learn more about GUI functions.

212 Adams/View Function Builder
Functions: F - L

FILE_DIRECTORY_NAME
Returns a directory name from the file specification.

Format
FILE_DIRECTORY_NAME(file_name)

Argument

file_name Character string containing the local or full-file name.

Example
The following example illustrates the use of the FILE_DIRECTORY_NAME function:
var set var=$_self.dir string_value=
(eval (FILE_DIRECTORY_NAME ("my_dir/my_file.dat")))
returns "my_dir"
Learn more about system functions.
 Design-Time Functions 213
Functions: F - L

FILE_EXISTS
Returns a 1 if a file exists, and a 0 if it doesn't.

Format
FILE_EXISTS (File Name)

Argument

File Name The name of the file you're looking for.

Examples
For the following examples, assume that a file named aview.log% exists, and avkiew.log% does not.

Function FILE_EXISTS(aview.log%)
Result 1

Function FILE_EXISTS(avkiew.log%)
Result 0

Learn more about system functions.

214 Adams/View Function Builder
Functions: F - L

FILE_MINUS_EXT
Returns the file name with its extension removed.

Format
FILE_MINUS_EXT (file_name)

Argument

file_name Character string containing the file name with or without a directory specification.

Examples
The following example illustrates the use of the FILE_MINUS_EXT function:
var set var=.file_no_ext string_value=
(eval (FILE_MINUS_EXT ("my_file.dat")))
returns "my_file"
Learn more about system functions.
 Design-Time Functions 215
Functions: F - L

FILE_TEMP_NAME
Returns a string that has a non-existent temporary file name. Each time it is called, it returns a new name,
so you should evaluate it using the EVAL function, as shown in the example below.

Format
FILE_TEMP_NAME (None)

Argument
None

Example
The following command creates a file name and stores it in the variable named new_file:
variable set variable=new_file str=(eval(FILE_TEMP_NAME( )))
Learn more about system functions.
216 Adams/View Function Builder
Functions: F - L

FILTER
Returns a 1xN array of filtered input values, where N is the number of input values. The coefficients of
the transfer function define the filter.

Format
FILTER (Independent Variable, Dependent Variable, Numerator Coefficients, Denominator Coefficients,
Filtering Method)

Arguments

Independent Variable A 1xN array of independent values.

Dependent Variable A 1xN array of dependent values as a function of the independent values.
Numerator Coefficients A set of numerator coefficients in the transfer function.
 Design-Time Functions 217
Functions: F - L

Denominator A set of denominator coefficients in the transfer function. The number of

Coefficients denominator coefficients can't be lower than the number of numerator
coefficients.
Filtering Method There are two filtering methods: continuous and discrete.

• Continuous - The continuous (or analog) filter, transforms the

input data into frequency space, passes it through the transfer
function, and returns it to physical space. A nonzero value
indicates the use of the continuous filter.

In the following equations, the notation is defined as follows:

• a = user-supplied numerator coefficient
• b = user-supplied denominator coefficient
• z = dependent value
• n = number of numerator coefficients
• m = number of denominator coefficients

The numerator coefficients for a continuous filter are used as

follows:
a0  z n + a1  z  n – 1  + a2  z  n – 2  + 

The denominator coefficients for a continuous filter are used as

follows:
b 0  z m + b 1  z  m – 1  + a b2  z  m – 2  + 
• Discrete - The discrete (or digital) filter applies the transfer
function directly to the input data stream in physical space. A 0
indicates the use of the discrete filter.

The numerator coefficients for a discrete filter are used as follows:

a 0 + a 1  z  –1  + a 2  z  –2  + 

The denominator coefficients for a continuous filter are used as

follows:
b 0 + b 1  z  –1  + b 2  z  –2  + 

Example
The following function returns a 1xN array of numbers that represent the filtered data:
FILTER(.mod1.FUNC_MEA_1.TIME, .mod1.FUNC_MEA_1, Q, {1.0,0,0},
{1.0,12.7,81.0}, 1)
218 Adams/View Function Builder
Functions: F - L

Learn more about matrix/array functions.

 Design-Time Functions 219
Functions: F - L

FILTFILT
Zero-phase digital filtering.

Format
filtfilt (b, a, x) returns ARRAY

Argument

b An array indicating the numerator coefficients of the filter.

a An array indicating the denominator coefficients of the filter.
x An array indicating the array of data to be filtered.

Learn more about matrix/array functions.

220 Adams/View Function Builder
Functions: F - L

FIND_MACRO_FROM_COMMAND
Checks if a macro is defined using the specified user_entered_command (command_str). Returns its
KEY if one exists; otherwise, it returns None.
FIND_MACRO_FROM_COMMAND does not check to determine if the user_entered_command
conflicts with the built-in Adams/View command language.

Format
FIND_MACRO_FROM_COMMAND(command_str)

command_str A string containing the user_entered_command of interest.

var set var=mac_str &string=(eval(FIND_MACRO_FROM_COMMAND("mdi

acontrols info")))
if cond=(mac_str != "")
! a macro already exists for those commands....
! mac_str contains the name of the existing macro
else
! no macro exists for those commands
end
Learn more about GUI functions.
 Design-Time Functions 221
Functions: F - L

FIRST
Returns the first element in an array if an element exists; otherwise, returns a 0.

Format
FIRST (A)

Argument

A An array.

Examples
The following examples illustrate the use of the FIRST function:

Function FIRST ({})

Result 0.0

Function FIRST ({1,2,3})

Result 1

Learn more about matrix/array functions.

222 Adams/View Function Builder
Functions: F - L

FIRST_N
Returns the first N elements of an array.

Format
FIRST_N (A,N)

Arguments

A An array.
N Number of elements to return.

Examples
The following examples illustrate the use of the FIRST_N function:

Function FIRST_N ({ }, 3)
Result {}

Function FIRST_N ({1,2,3,4}, 2)

Result {1,2}

Function FIRST_N ({1,2,3,}, 4)

Result {1,2,3}

Learn more about matrix/array functions.

 Design-Time Functions 223
Functions: F - L

FLOOR
Returns the largest integer that is less than x.

Format
FLOOR(x)

Argument

x Any valid expression that evaluates to a real number.

Examples
The following examples illustrate the use of the FLOOR function:

Function FLOOR (.7)

Result 0

Function FLOOR (-5.7)

Result -6

Function FLOOR (3.9)

Result 3

Learn more about math functions.

224 Adams/View Function Builder
Functions: F - L

FREQUENCY
Returns the FFT frequencies of an array of time values. The result is given in Hz.

Format
FREQUENCY (A, N)

Arguments

A An array of time values from which the frequencies will be computed. The time values
should be evenly spaced.
N An integer value which indicates the number of output values. This must be greater than or
equal to the number of input values. If N is an odd number, the function returns (N+1)/2
output values. If N is an even number, (N/2 + 1) number of values will be returned.

Example
The following examples assume that the current time units setting is in seconds:

Function FREQUENCY({0,1,2,3,4}, 10)

Result 0.0, 0.1, 0.2, 0.3, 0.4, 0.5

Function FREQUENCY({0,1,2,3,4}, 5)
Result 0.0, 0.2, 0.4

Learn more about matrix/array functions.

 Design-Time Functions 225
Functions: F - L

GETCWD
Returns the current working directory as a character string.

Format
GETCWD ()

Argument
None

Example
The following function returns the name of my current working directory:

Function GETCWD()
Result /usr/people/documentation

Learn more about system functions.

226 Adams/View Function Builder
Functions: F - L

GETENV
Returns a text string containing the value of the environment variable you specified.

Format
GETENV (Environment Variable)

Argument

Environment Variable Character string representing an environment variable.

Example
The following function returns the name of the registered user, in this case, tmazz:

Function GETENV("USER")
Result tmazz

Learn more about system functions.

 Design-Time Functions 227
Functions: F - L

GRIDDATA
Calls the MATLAB GRIDDATA function. Returns a real array of Zi values corresponding to the ordered
pairs in Xi, and Yi.

Format
GRIDDATA (x, y, z, Xi, Yi)

Argument

x The x values of the original data for which the grid is to be computed.
y The y values of the original data.
z The z values of the original data.
Xi The x values of the points at which the grid is to be evaluated.
Yi The y values of the points.

Example
variable create variable=Xi real=1,2,3,1,2,3,1,2,3
variable create variable=Yi real=1,1,1,2,2,2,3,3,3
variable create variable=Zi real=(GRIDDATA({1,1,4,4},{5,5,6,6},
Xi, Yi,))
produces a value of
{5,0, 5.33, 5.67, 5.0, 5.33, 5.67, 5.0, 5.33, 5.67}
corresponding to the points
(1,1, 5.0)(2,1, 5.33)(3,1, 5.67)(1,2, 5.0)(2,2, 5.33)(3,2,
5.67)(1,3, 5.0)(2,3, 5.33)(3,3, 5.67)
Learn more about matrix/array functions.
228 Adams/View Function Builder
Functions: F - L

GUICLEANUP
The function is effective only on Windows platforms. It takes a dialog name as the single argument and
unloads it, thereby deleting all QT widgets (controls) associated with the dialog, reducing the HANDLE
(USER Objects) count of the parent process e.g. 'aview'. On Windows platforms, the maximum allowable
HANDLE limit for a process is 10,000, after which, programs are known to behave erratically.
The function has been provided so that users can tackle this limitation, inherent to Windows platforms
and can carry on with their normal working. As such, the function, though available on other platforms,
does nothing.

Format
GUICLEANUP(object)

Argument

Object The dialog box name

Example
The function takes just one argument, which is the name of the dialog whose widgets have to be
unloaded. Please note that it is recommended that the function be used only through an eval() call. The
following example describes this in detail,
var cre var = temp int = ( eval ( guicleanup (about_adams) ) ) ... recommended

var cre var = temp int = ( guicleanup (about_adams) ) ... not recommended
Failing to use the GUICLEANUP function in an eval() statement introduces an undesireable dependency
between the dialog and the variable and may lead to unpredictable behaviour.

Note: The function CANNOT be used to unload the function-builder dialog.

 Design-Time Functions 229
Functions: F - L

HAMMING
Returns a 1xN array of values after applying the HAMMING window function.

Format
HAMMING (a)

Argument

a A 1xN array of real numbers.

Example
The following example illustrates the use of the HAMMING function:

Function HAMMING ({1,2,3,4,2})

Result {0.0800, 1.0800, 3.0000, 2.1600, 0.1600}

Learn more about matrix/array functions.

230 Adams/View Function Builder
Functions: F - L

HAMMING_WINDOW
Generate the HAMMING window. The HAMMING window function forces the end points toward zero,
and smooths the remaining points toward the end points.

Format
hamming_window (n)

Arguments

n An integer value.

Example
The following example illustrates the use of the HAMMING_WINDOW function:

Function hamming_window (5)

Result {0.0800, 0.5400, 1.0000, 0.5400, 0.0800}

Learn more about matrix/array functions.

 Design-Time Functions 231
Functions: F - L

HANNING
Returns a 1xN array of values after applying the HANNING window function.

Format
HANNING (A)

Argument

A A 1xN array of real numbers.

Example
The following example illustrates the use of the HANNING function:

Function HANNING ({1,2,3,4,2})

Result {0.0, 1.0, 3.0, 2.0, 0.0}

Learn more about matrix/array functions.

232 Adams/View Function Builder
Functions: F - L

HANNING_WINDOW
Generate the HANNING window. The HANNING window function forces the end points to become zero,
and smooths the remaining points toward the end points.

Format
hanning_window (n)

Arguments

n An integer value.

Example
The following example illustrates the use of the HANNING_WINDOW function:

Function hanning_window (5)

Result {0.2500, 0.7500, 1.0000, 0.7500, 0.2500}

Learn more about matrix/array functions.

 Design-Time Functions 233
Functions: F - L

HERMITE_SPLINE
Creates an interpolated curve from input points with a specified number of values. Interpolates using the
Hermite cubic spline.
The length of the Independent Data array must be equal to the Dependent Data array.

Format
HERMITE_SPLINE (Independent Data, Dependent Data, Number of Output Values)

Arguments

Independent Data A 1xN array of x values for the curve to be interpolated. The x values of
the points must be in ascending order, and the length of the array must
be greater than or equal to 4.
Dependent Data A 1xN array of y values for the curve to be interpolated.
Number of Output Values The number of values to be generated in the output array.

Example
The following function interpolates a set of four points with ordinal values from 1 to 4 and abscissal
values as shown, into a series of 10 abscissal values.

Function HERMITE_SPLINE({1, 2, 3, 4}, {0, 2, 1, 3}, 10)

Result {0.0, 1.037, 1.741, 2.0, 1.741, 1.259, 1.0, 1.259, 1.963, 3.0}

To compute the ordinal values for these splined values, you can use the SERIES2 function as follows:

Function SERIES2(1, 4, 10)

Result {1.0, 1.333, 1.667, 2.0, 2.333, 2.667, 3.0, 3.333, 3.667, 4.0}

Learn more about matrix/array functions.

234 Adams/View Function Builder
Functions: F - L

INCLUDE
Includes a value into an array if the value is not already there.

Format
INCLUDE (A, X)

Arguments

A An array.
X A real value.

Example
Assume that the array in the following function contains the values 1 through 10:

Function INCLUDE(.MOD1.A,11)
Result includes 11 as an element of the array

Learn more about matrix/array functions.

 Design-Time Functions 235
Functions: F - L

INT
Returns the nearest real value whose magnitude is not larger than x. If x is less than 0, returns CEIL;
otherwise, returns FLOOR of x.

Format
INT(x)

Argument

x Any valid expression that evaluates to a real number.

Examples
The following examples illustrate the use of the INT function:

Function Result
INT(4.8) 4.0
INT (.38) 0.0
INT (-3.9) -3.0

Learn more about math functions.

236 Adams/View Function Builder
Functions: F - L

INTEGR
Produces the integral at each input point on curve C. The curve is presented to this function as two arrays
containing the ordinal and abscissal components of the curve. To compute the integral at each point,
INTEGR fits a cubic spline to the curve and returns the integrals of the approximating polynomials at
each point. The curve of integrals that INTEGR returns has the same number of values as each of the
arguments.
The algorithm that fits the cubic spline is from Computer Methods for Mathematical Computations by
Forsythe, Malcolm and Moler (1977, Prentice-Hall: Englewood Cliffs, NJ). The CSPLINE function uses
the same algorithm.

Format
INTEGR (Independent Points, Dependent Points)

Arguments

Independent Points The X or ordinal values of the curve to be integrated.

Dependent Points The Y or abscissal values of the curve to be integrated.

Example
The following example illustrates the use of the INTEGR function:

Function INTEGR(SERIES(0,1,5), {0,1,4,9,16})

Result 0.0, 0.333, 2.667, 9.0, 21.333

Learn more about matrix/array functions.

 Design-Time Functions 237
Functions: F - L

INTEGRATE
Produces a curve of integrals from an input curve. To compute the integral at each point, the
INTEGRATE function fits a cubic spline to the 2xN matrix representation of curve C, and returns the
integrals of the approximating polynomials at each point. The curve of integrals that INTEGRATE
returns has the same X values as curve C.

Format
INTEGRATE (C)

Argument

C Input curve.

Example
The following xy_plot command creates a curve, int1, whose x values are the same as the x values of
curve1 on plot1. The matrix that INTEGRATE receives, is 2xN:
• The first row is the x values of curve1.
• The second row is the y values of curve1.

INTEGRATE returns two rows:

• The first is the same as the x values of curve1.
• The second is the integrals of curve1.
xy_plots curve create curve=diff1 &
x_values=(.curve1.x_data.values) &
y_values (INTEGRATE &
({.curve1.x_data.values,.curve1.y_data.values})[2,*])
Learn more about matrix/array functions.
238 Adams/View Function Builder
Functions: F - L

INTERP
The INTERP function returns the iord derivative of the interpolated value of SPLINE/id at time=x. The
INTERP function supports time-series splines, which are splines that include a FILE argument that
specifies a time history file of type DAC or RPC III.

Format
INTERP (Indep_Var, Method, Spline_name, Deriv_order)

Arguments

Independent Variable Enter a real variable that specifies the value of time, the independent variable
along the x-axis of the time series spline that is being interpolated.
Derivative Order Select the order of the derivative that Adams/Solver takes at the interpolated
point, and then returns through INTERP.

• Curve Coordinates (0) - Take no derivative (default)

• 1st Derivative (1)
• 2nd Derivative (2)
Interpolation Method Select the method of interpolation:

• Linear (1)
• Cubic (3)
Spline Name Enter the name of the SPLINE statement in the Adams/Solver dataset. The
SPLINE statement must reference time series data from a DAC or RPC III
file.

Examples
As part of the Adams/Durability feature, the INTERP function lets you specify how you want to
interpolate spline data from an RPC III or DAC time history file. An example is shown below of how to
specify the INTERP function in Adams/Solver for durability analysis.
For durability analysis, the INTERP function appears in a motion or force statement, and looks as
follows:
INTERP(time, 3, spline id)
where:

• time is the independent variable of the interpolation. For durability analysis, this real variable is
always time or an expression that includes time.
• 3 is the method of interpolation, which indicates cubic interpolation between data points. 1,
which indicates linear interpolation, is also a valid entry.
 Design-Time Functions 239
Functions: F - L

• spline id is the identifier of the spline that specifies the RPC III or DAC file input. Setting up a
Spline in Adams/Durability.

For more information on the INTERP function, see INTERP for Adams/Solver (C++) or INTERP for
Adams/Solver (FORTRAN).
240 Adams/View Function Builder
Functions: F - L

INTERP1
Calls the MATLAB INTERP1 function and returns a real array. Given a curve described by x and y, the
INTERP1 function returns the Yi values corresponding to the Xi values.

Format
INTERP1 (x, y, Xi, method)

Argument

x The x values of the input curve.

y The y values of the input curve.
Xi The x values at which to evaluate the spline.
method A character string that indicates the interpolation method to be used. These come directly
from the MATLAB function with the same name:

nearest - Nearest neighbor interpolation.

linear - Linear interpolation.
spline - Cubic spline interpolation
pchip - Piecewise cubic Hermite interpolation.
cubic - Same as pchip.
v5cubic - Cubic interpolation used in MATLAB 5.

Example
This example shows the relative shapes of the arrays involved when using the function:
variable create variable=Yi & real=(interp1({1,2,3},
{1,2,3}, {1.2,2.5}, "spline"))
produces a value for Yi of
{1.25,2.5}
corresponding to the points
(1.5,1.5)(2.5,2.5)
Learn more about matrix/array functions.
 Design-Time Functions 241
Functions: F - L

INTERP2
Calls the MATLAB INTERP2 function and returns a real array. Given a 3D surface described by x, y,
and z, the INTERP2 function returns the Zi values corresponding to the Xi and Yi points.

Format
INTERP2 (x, y, z, Xi, Yi method)

Argument

x The x values of the input surface.

y The y values of the input surface.
z The z values of the input surface.
Xi Evaluates the splined curves at the x coordinates.
Yi Evaluates the splined curves at the y coordinates.

Xi and Yi may be of different size, as they describe a grid rather than a collection of ordered
pairs, though the number of Xi's must be greater than or equal to the number of Yi's.
method A character string that indicates the interpolation method to be used. These come directly
from the MATLAB function of the same name:

nearest - Nearest neighbor interpolation.

linear - Bilinear interpolation.

spline - Cubic spline interpolation.

cubic - Bicubic interpolation.

Example
Note that the z array is a surface corresponding to each x-y pair:
variable create variable=Zi &
real=(interp2({1,2,3},{1,2,3},{{1,2,3},{1,2,3},
{1,2,3}},{1.5,2.5},{1.5,2.5},"spline"))
produces value for ZI
{1.5,2.5,1.5,2.5}
corresponding to the points
(1.5,1.5,1.5)
(1.5,2.5,2.5)
(2.5,1.5,1.5)
(2.5,2.5,2.5)
242 Adams/View Function Builder
Functions: F - L

Learn more about matrix/array functions.

 Design-Time Functions 243
Functions: F - L

INTERPFT
Calls the MATLAB INTERPFT function to perform one-dimensional interpolation using the FFT
method. The INTERPFT function returns an array of Y values nY long if given the x array and integer
value nY.

Format
INTERPFT (x, nY,)

Argument

x An array of real numbers containing the x values to interpolate.

nY The count of y values to return.

Example
variable create variable=Y real=(interpft({1,2,3},5))
returns a value for Y of
{1.0, 1.1419, 2.4697, 3.1484, 2.2401}
Learn more about matrix/array functions.
244 Adams/View Function Builder
Functions: F - L

INVERSE
Returns the inverse matrix of a square matrix. If an inverse doesn't exist, it generates an error.

Format
INVERSE(M)

Argument

M A square matrix.

Example
The following example illustrates the use of the INVERSE function:

Function INVERSE({[1,2.0], [2,1,-1], [3,1,1]})

Result {[-.25, .25, .25], [.625, -.125, -.125], [.125, -.625, .375]}

Learn more about matrix/array functions.

 Design-Time Functions 245
Functions: F - L

LAST
Returns the last element of an array if an element exists; otherwise, returns a 0.

Format
LAST (A)

Argument

A An array.

Examples
The following examples illustrate the use of the LAST function:

Function LAST({})
Result 0.0

Function LAST({1})
Result 1

Function LAST({1,2,3})
Result 3

Learn more about matrix/array functions.

246 Adams/View Function Builder
Functions: F - L

LAST_N
Returns the last N element of an array.

Format
LAST_N (A,N)

Arguments

A An array.
N Number of elements to return.

Examples
The following examples illustrate the use of the LAST function:

Function LAST_N({3},2)
Result {}

Function LAST_N({1,2,3},0)
Result {}

Function LAST_N({1,2,3},2)
Result {2,3}

Learn more about matrix/array functions.

 Design-Time Functions 247
Functions: F - L

LINEAR_SPLINE
Creates an interpolated curve from input points with a specified number of values. Interpolates using
linear interpolation.
The length of the Independent Data array must be the same as the Dependent Data array.
The algorithm that fits the linear spline is from Digital Computation and Numerical Methods, chapter
8.1.2 (Southworth, 1965).

Format
LINEAR_SPLINE (Independent Data, Dependent Data, Number of Output Values)

Arguments

Independent Data A 1xN array of x values for the curve to be interpolated. The x values
must be in ascending order, and the length of the array must be greater
than or equal to 4.
Dependent Data A 1xN array of y values for the curve to be interpolated.
Number of Output Values The number of values to be generated in the output array.

Example
The following function interpolates a set of four points with ordinal values from 1 to 4 and abscissal
values as shown, into a series of 10 abscissal values.

Function LINEAR_SPLINE({1, 2, 3, 4}, {0, 2, 1, 3}, 10)

Result {0.0, .667, 1.333, 2.0, 1.667, 1.333, 1.0, 1.667, 2.333, 3.0}

To compute the ordinal values for these splined values, you can use the SERIES2 function as follows:

Function SERIES2(1, 4, 10)

Result {1.0, 1.333, 1.667, 2.0, 2.333, 2.667, 3.0, 3.333, 3.667, 4.0}

Learn more about matrix/array functions.

248 Adams/View Function Builder
Functions: F - L

LOC_ALONG_LINE
Returns an array of three numbers defining a location expressed in the global coordinate system. The
location is a specified distance along the line from one coordinate system object to another.

Format
LOC_ALONG_LINE (Object for Start Point, Object for Point on Line, Distance)

Arguments

Object for Start Point Coordinate system object defining the starting point of the line.
Object for Point on Line Coordinate system object defining a point on the line.
Distance Distance along the line.
 Design-Time Functions 249
Functions: F - L

Example
In the following illustration, the LOC_ALONG_LINE function returns an array of three numbers
representing a location:

Function LOC_ALONG_LINE(marker_2, marker_1, 5)

Result 7.5, 9.5, 0

Note: The line between the coordinate system objects is not affected by the objects' orientations.

Learn more about location/orientation functions.

250 Adams/View Function Builder
Functions: F - L

LOC_BY_FLEXBODY_NODEID
Returns the location as a three-dimensional vector of a node on a flexible body.

Format
loc_by_flexbody_nodeid (flex_body, node_id)

flex_body Name of the flexible body.

node_id Node number.

Returns
If the node ID does not exist in the flexible body, LOC_BY_FLEXBODY_NODEID returns a location
at the origin (0, 0, 0) with no warning.

Example
The following example creates a marker on ground that is coincident to node 1000 of flexible body link:
marker create marker=.ground.marker_1 &
location = (eval(LOC_BY_FLEXBODY_NODEID(link, 1000)))
Learn about location/orientation functions.

See more node ID functions.

 Design-Time Functions 251
Functions: F - L

LOC_CYLINDRICAL
Returns an array of three numbers that are the Cartesian coordinates (x, y, z) for a point equivalent to the
cylindrical coordinates (r,  , z) for the same point. Both sets of coordinates are relative to the global
coordinate system origin and axes. The relationship between the coordinates is:

• x = r cos 
• y = r sin 
• z=z

Format
LOC_CYLINDRICAL (R, Theta, Z)

Arguments

R The radius of the circle on which the point lies.

Theta (  ) Rotation about the z-axis starting from the x-axis. The positive or negative sense of the
rotation is defined by the right-hand rule.
Z Distance along the global z-axis.
252 Adams/View Function Builder
Functions: F - L

Example
In the following illustration, the LOC_CYLINDRICAL function returns an array of three numbers that
are the Cartesian coordinates for a point.

Function LOC_CYLINDRICAL(1,30,0)
Result 0.866, 0.5, 0

Note: Assumes that the default for angular displacement units is degrees.

Learn more about location/orientation functions.

 Design-Time Functions 253
Functions: F - L

LOC_FRAME_MIRROR
Returns an array of three numbers representing a location in the global coordinate system, which mirrors
another location across a plane of a coordinate system object.

Format
LOC_FRAME_MIRROR (Location, Frame Object, Plane Name)

Arguments

Location Array of numbers that specifies a location expressed in the global coordinate system.
Frame Object Coordinate system object that defines the plane of reflection.
Plane Name Character string that specifies one of the three planes in a coordinate system object.
xy, yx, xz, zx, yz, and zy (character case is insignificant) are the only possible values.
Character order is insignificant; that is, xy is the same as yx.

Example
In the following illustration, the LOC_FRAME_MIRROR function returns an array of three numbers
representing a location:

Function LOC_FRAME_MIRROR({7,7,0}, marker_1, "xy")

Result 7, 5, 0 (in the global coordinate system)

Note: In this example, the xy plane of coordinate system object, marker_1, is parallel to the
global xz plane.
254 Adams/View Function Builder
Functions: F - L

Learn more about location/orientation functions.

 Design-Time Functions 255
Functions: F - L

LOC_GLOBAL
Returns an array of three numbers representing the global coordinates of a location obtained from
transforming the local coordinates by a specified location.

Format
LOC_GLOBAL (Location, Frame Object)

Arguments

Location Array of numbers that specify a location expressed relative to a local coordinate
system.
Frame Object Coordinate system object in which the local coordinates are expressed.
256 Adams/View Function Builder
Functions: F - L

Example
In the following illustration, the LOC_GLOBAL function returns an array of three numbers representing
the global coordinates of a location:

Function LOC_GLOBAL({-5, -8, 0}, marker_1)

Result 14, 12, 0 (in the global coordinate system)

Learn more about location/orientation functions.

 Design-Time Functions 257
Functions: F - L

LOC_INLINE
Returns an array of three numbers representing the transformation and normalization of coordinates for
a location you specified. The location's coordinates are originally expressed in terms of one coordinate
system and then transformed to the equivalent coordinates, as expressed relative to a new coordinate
system.

Format
LOC_INLINE (Location, In Frame Object, To Frame Object)

Arguments

Location Array of three numbers specifiying a location expressed in terms of the original
coordinate system.
In Frame Object Starting coordinate system object in which location coordinates are input.
To Frame Object New coordinate system into which the location coordinates are transformed.
258 Adams/View Function Builder
Functions: F - L

Examples
In the following illustration, the LOC_INLINE function returns an array of three numbers representing
the transformation and normalization of coordinates for a specified location:

Function LOC_INLINE({-8, -2, 0}, marker_1, marker_2)

Result 0.8, 0.6, 0.0

Note: LOC_INLINE normalizes the transformed coordinates before returning them.

 Design-Time Functions 259
Functions: F - L

In the following illustration, the LOC_INLINE function returns an array of three numbers representing
the transformation and normalization of coordinates for a specified location:

Function LOC_INLINE({-6, -2, 0}, marker_1, marker_2)

Result -0.98, -0.19, 0.0

Learn more about location/orientation functions.

260 Adams/View Function Builder
Functions: F - L

LOC_LOC
Returns an array of three numbers representing the transformation of coordinates location in a new
coordinate system object.

Format
LOC_LOC (Location, In Frame Object, To Frame Object)

Arguments

Location An array of numbers specifying a location as expressed in the original coordinate

system.
In Frame Object The original coordinate system object that expresses the location.
To Frame Object The original coordinate system object into which the location is to be transformed.
 Design-Time Functions 261
Functions: F - L

Example
In the following illustration, the LOC_LOC function returns an array of three numbers representing the
transformation of coordinates location in a new coordinate system object:

Function LOC_LOC({-6, 12, 0}, marker_1, marker_2)

Result -2, 8, 0 (with respect to marker_2)

Learn more about location/orientation functions.

262 Adams/View Function Builder
Functions: F - L

LOC_LOCAL
Returns an array of three numbers representing a location obtained by transforming a location expressed
in the global coordinate system, to a new local coordinate system object.

Format
LOC_LOCAL (Location, Frame Object)

Arguments

Location An array of numbers specifying a location expressed in the global coordinate system.
Frame Object A new local coordinate system into which the locations are to be transformed.
 Design-Time Functions 263
Functions: F - L

Example
In the following illustration, the LOC_LOCAL function returns an array of three numbers representing
a location:

Function LOC_LOCAL({-4, -7, 0}, marker_2)

Result -23, 11, 0 (in the marker_2 coordinate system)

Learn more about location/orientation functions.

264 Adams/View Function Builder
Functions: F - L

LOC_MIRROR
Returns an array of three numbers representing a location in the global coordinate system, which mirrors
another location across a plane of a coordinate system object.

Format
LOC_MIRROR (Location, Frame Object, Plane Name)

Arguments

Location Array of numbers that specifies a location expressed in the global coordinate system.
Frame Object Coordinate system object that defines the plane of reflection.
Plane Name Character string that specifies one of the three planes in a coordinate system object.
xy, yx, xz, zx, yz, and zy (character case is insignificant) are the only possible values.
Character order is insignificant; that is, xy is the same as yx.

Example
In the following illustration, the LOC_MIRROR function returns an array of three numbers representing
a location:

Function LOC_MIRROR({7,7,0}, marker_1, "xy")

Result 7, 5, 0 (in the global coordinate system)

Note: In this example, the xy plane of coordinate system object, marker_1, is parallel to the
global xz plane.
 Design-Time Functions 265
Functions: F - L

Learn more about location/orientation functions.

266 Adams/View Function Builder
Functions: F - L

LOC_ON_AXIS
Returns an array of three numbers representing a location expressed in the global coordinate system,
obtained from translating a certain distance along a specified axis of a coordinate system object.

Format
LOC_ON_AXIS (Frame Object, Distance, Axis Name)

Arguments

Frame Object Coordinate system object on whose axis you want your point to lie.
Distance Real number stating how far to move along the specified axis.
Axis Name Single-character string denoting the coordinate system axis. Valid values are x, y, and
z (character case is insignificant).

Examples
In the following illustration, the LOC_ON_AXIS function returns an array of three numbers representing
a location:

Function LOC_ON_AXIS(marker_2, 5, "x")

Result 4, 11, 0
 Design-Time Functions 267
Functions: F - L

In the following illustration, the LOC_ON_AXIS function returns an array of three numbers representing
a location:

Function LOC_ON_AXIS(marker_2, 5, "y")

Result -1, 6, 0
268 Adams/View Function Builder
Functions: F - L

In the following illustration, the LOC_ON_AXIS function returns an array of three numbers representing
a location:

Function LOC_ON_AXIS(marker_2, 5, "z")

Result 4, 6, 5

Learn more about location/orientation functions.

 Design-Time Functions 269
Functions: F - L

LOC_ON_LINE
Returns an array of three numbers representing the global coordinates of a location along a line defined
by two points.

Format
LOC_ON_LINE (Line Point Locations, Distance)

Arguments

Line Point Locations 3x2 matrix containing two points describing a line. The coordinates of the
points are expressed in the global coordinate system.
Distance Real number, measured from the first point, that determines how far to move
along the line.
270 Adams/View Function Builder
Functions: F - L

Example
In the following illustration, the LOC_ON_LINE function returns an array of three numbers representing
the global coordinates of a location:

Function LOC_ON_LINE({{7,5,0},{15,11,0}}, 7)
Result 12.6, 9.2, 0.0

Learn more about location/orientation functions.

 Design-Time Functions 271
Functions: F - L

LOC_PERPENDICULAR
Returns a location normal to a plane, one unit away from the first point in the plane.
LOC_PERPENDICULAR can also be used to orient a marker by directing an axis toward a point one
unit away from the first point in the plane.

Format
LOC_PERPENDICULAR (Plane Point Locations)

Arguments

Plane Point Locations 3x3 matrix providing three non-colinear points describing a plane.

Example
The following example illustrates the use of the LOC_PERPENDICULAR function:

Function LOC_PERPENDICULAR({{10,12,0},{14,12,0},{12,10,0}})
Result 10, 12, 1

Learn more about location/orientation functions.

272 Adams/View Function Builder
Functions: F - L

LOC_PLANE_MIRROR
Returns an array of three numbers representing a location expressed in the global coordinate system of a
location mirrored across the specified plane.

Format
LOC_PLANE_MIRROR (Location, Plane Point Locations)

Arguments

Location Array of numbers specifying a location expressed in the global coordinate

system.
Plane Point Locations 3x3 matrix providing three non-colinear points describing a plane. The points
are expressed in the global coordinate system.
 Design-Time Functions 273
Functions: F - L

Example
In the following illustration, the LOC_PLANE_MIRROR function returns an array of three numbers
representing a location:

Function LOC_PLANE_MIRROR({2,4,0},{{10,12,0},{14,12,0},{12,10,0}})
Result 2, 4, 0

Learn more about location/orientation functions.

274 Adams/View Function Builder
Functions: F - L

LOC_RELATIVE_TO
Returns an array of three numbers representing a location, by transforming a specified location that is
relative to a coordinate system object.

Format
LOC_RELATIVE_TO (Location, Frame Object)

Arguments

Location Array of numbers specifying a location expressed in a coordinate system object.

Frame Object Coordinate system object.

Example
In the following illustration, the LOC_RELATIVE_TO function returns an array of three numbers
representing a location:

Function LOC_RELATIVE_TO({16,8,0}, marker_2)

Result -4, 22, 0
 Design-Time Functions 275
Functions: F - L

Learn more about location/orientation functions.

276 Adams/View Function Builder
Functions: F - L

LOC_SPHERICAL
Returns Cartesian coordinates (x, y, z) that are equivalent to spherical coordinates (  ,  ,  ). In this
case:

• x=  sin  cos 
• y=  sin  sin 
• z=  sin 

Format
LOC_SPHERICAL (Rho, Theta, Phi)

Arguments

Rho The radius of the sphere.

Theta Counterclockwise rotation about z.
Phi Counterclockwise rotation about x.

Example
The following example illustrates the use of the LOC_SPHERICAL function:

Function LOC_SPHERICAL(10, 8, 0)
Result 1.39, 0, 9.9

Learn more about location/orientation functions.

 Design-Time Functions 277
Functions: F - L

LOC_TO_FLEXBODY_NODEID
Returns the node ID of the flexible body that is closest to the specified location.

Format
loc_to_flexbody_nodeid (flex_body, location)

Arguments

flex_body Name of the flexible body.

location Three-dimensional vector.

Example
The following example assigns the node number on flexible body, link, closest to the point located at (10,
20, 30) to the variable .node_id.
var set var=.node_id int=(eval(LOC_TO_FLEXBODY_NODEID(link,
{10,20,30})))
Learn about location/orientation functions.
278 Adams/View Function Builder
Functions: F - L

LOC_X_AXIS
Returns a normal vector defining the x-axis of a coordinate system object in the global coordinate system.
You often use LOC_X_AXIS with the orientation functions or with the function LOC_ON_LINE.

Format
LOC_X_AXIS (Frame Object)

Argument

Frame Object Coordinate system object.

Example
In the following illustration, the LOC_X_AXIS function returns a normal vector defining the x-axis of
marker_2:

Function LOC_X_AXIS(marker_2)
Result 1, 0, 0
 Design-Time Functions 279
Functions: F - L

LOC_Y_AXIS
Returns a normal vector defining the y-axis of a coordinate system object in the global coordinate system.
You often use LOC_Y_AXIS with the orientation functions or with the function LOC_ON_LINE.

Format
LOC_Y_AXIS (Frame Object)

Argument

Frame Object Coordinate system object.

Example
In the following illustration, the LOC_Y_AXIS function returns a normal vector defining the y-axis of
marker_2:

Function LOC_Y_AXIS(marker_2)
Result 0, 1, 0
280 Adams/View Function Builder
Functions: F - L

LOC_Z_AXIS
Returns a normal vector defining the z-axis of a coordinate system object in the global coordinate system.
You often use LOC_Z_AXIS with the orientation functions or with the function LOC_ON_LINE.

Format
LOC_Z_AXIS (Frame Object)

Argument

Frame Object Coordinate system object.

Example
In the following illustration, the LOC_Z_AXIS function returns a normal vector defining the z-axis of
marker_2:

Function LOC_Z_AXIS(marker_2)
Result 0, 0, 1
 Design-Time Functions 281
Functions: F - L

LOG
Returns the natural logarithm of an expression that represents a numerical value.
If ey= x then LOG(x)= x. The LOG function is defined only for positive values of x (that is, x > 0). It is
undefined for all other values.

Format
LOG(x)

Argument

x Any valid expression that evaluates to a real number.

Example
The following example illustrates the use of the LOG function:

Function LOG(30)
Result 3.4

Learn more about math functions.

282 Adams/View Function Builder
Functions: F - L

LOG10
Returns log to base 10 of an expression that represents a numerical value.
If 10y = x, then LOG10(x) = y. The LOG10 function is defined only for positive values of x (that is, x >
0). It is undefined for all other values.

Format
LOG10(x)

Argument

x Any valid expression that evaluates to a real number.

Example
The following example illustrates the use of the LOG10 function:

Function LOG10(42)
Result 1.6

Learn more about math functions.

 Design-Time Functions 283
Functions: M - P

Functions: M - P
MAG
Returns the magnitude of a vector.

MAG  x y z  = x2 + y2 + z2

Format
MAG(x, y, z)

Arguments

x Real value.
y Real value.
z Real value.

Example
The following example illustrates the use of the MAG function:

Function MAG(5,3,1)
Result 5.91

Learn more about math functions.

284 Adams/View Function Builder
Functions: M - P

MAX
Returns the value of the largest element of a matrix.

Format
MAX (M)

Argument

M A matrix.

Example
The following example illustrates the use of the MAX function:

Function MAX({{2,4,5},{1,8,2}})
Result 8.0

Learn more about matrix/array functions.

 Design-Time Functions 285
Functions: M - P

MAXI
Returns the index of the largest element of a matrix.

Format
MAXI (M)

Argument

M A matrix.

Example
The following example illustrates the use of the MAXI function:

Function MAXI({0.1, 0.2, 0.3, 3.3})

Result 4

Learn more about matrix/array functions.

286 Adams/View Function Builder
Functions: M - P

MEAN
Returns the mean of a matrix.

Format
MEAN (M)

Argument

M A matrix.

Example
The following example illustrates the use of the MEAN function:

Function MEAN({0.1, 0.2, 0.3, 3.4})

Result 1.0

Learn more about matrix/array functions.

 Design-Time Functions 287
Functions: M - P

MEASURE
The MEASURE performs calculations using simulation results. The calculations that can be specified
are equivalent to the characteristics that can be measured using Object Measures.
Note that the Measure function uses the results from the most recent simulation. This limitation exists
because any model modification and run after the measured simulation could invalidate the MEASURE
calculations (for example, the measured object no longer exists).

Format
MEASURE (object, CoordSystem, RefFrame, characteristic, component)

Argument

object The object that the user is measuring

CoordSystem The key of a marker indicating the coordinate system the result will be reported in.
RefFrame The reference frame in which any time derivatives needed to compute the measure
quantity will be computed. The RefFrame can be thought of the reference frame which
the 'observer' is fixed in.
characteristic The characteristic to be measured. Available characteristics for an object are displayed
in the characteristic list of the plot builder when the object is selected in the object list.
component The component of characteristic to be measured. Available components for an
object/characteristic combination can be viewed in the component list of the plot
builder when the object and characteristic are picked in their respective lists.

Example
The following example illustrates the use of the MEASURE function:
After simulating, if user want to store the x locations of PART_2's cm then:

Function MEASURE ( part_2, MARKER_1, MARKER_1, cm_position, 1)

288 Adams/View Function Builder
Functions: M - P

MESHGRID
Calls the MATLAB MESHGRID function and returns a real array. Given the x and y vectors, the
MESHGRID function returns the X or Y grid coordinates.

Format
MESHGRID (x, y, XorY)

Arguments

x The x coordinates of the grid.

y The y coordinates of the grid.
XorY A switch value indicating whether the x or y coordinates of the griddata is desired: 0
means x, 1 means y.

Example
You could use the following to compute the X values for input to the GRIDDATA:
variable create variable=xx real=(meshgrid({1,2},{10,11,12},0))
which produces these values for xx
{1.0,1.0,1.0,2.0,2.0,2.0}
To create the Y vector for the same grid, use:
variable create variable=yy real=(meshgrid({1,2},{10,110,12},
1))
which produces a value for yy of
{10.0,11.0,12.0,10.0,11.0,12.0}
Learn more about matrix/array functions.
 Design-Time Functions 289
Functions: M - P

MIN
Returns the value of the smallest element of a matrix.

Format
MIN (M)

Argument

M A matrix.

Example
The following example illustrates the use of the MIN function:

Function MIN({{2,4,5},{1,8,2}})
Result 1.0

Learn more about matrix/array functions.

290 Adams/View Function Builder
Functions: M - P

MINI
Returns the index of the smallest element of a matrix.

Format
MINI (M)

Argument

M A matrix.

Example
The following example illustrates the use of the MINI function:

Function MINI({0.1, 0.2, 0.3, 3.3})

Result 1

Learn more about matrix/array functions.

 Design-Time Functions 291
Functions: M - P

MKDIR
Returns a numerical value indicating whether MKDIR succeeded in creating a user-specified directory.
If successful, it returns a 1; otherwise, it returns a 0.

Format
MKDIR (String)

Argument

String Text string that names a directory.

Example
The following function creates a new directory, named my_directory:

Function MKDIR("my_directory")
Result 1

Learn more about system functions.

292 Adams/View Function Builder
Functions: M - P

MOD
Returns the remainder of one expression, representing a numerical value, divided by another expression
representing a numerical value:
MOD(x1, x2) = x1 - INT(x1/x2) * x2

Format
MOD(x1, x2)

Arguments

x1 Any valid expression that evaluates to a real number.

x2 Any valid expression that evaluates to a real number.

Example
The following example illustrates the use of the MOD function:

Function MOD(45,16)
Result 13

Learn more about math functions.

 Design-Time Functions 293
Functions: M - P

NINT
Returns the whole number nearest to the input value.

Format
NINT(x)

Argument

x Any valid expression that evaluates to a real number.

Examples
The following examples illustrate the use of the NINT function:

Function NINT(4.78)
Result 5

Function NINT(-.25)
Result 0

Learn more about math functions.

294 Adams/View Function Builder
Functions: M - P

NODE_ID_CLOSEST
Returns an integer node ID associated with the node of a flexible body closest to a marker. If you set intpt
to 1, NODE_ID_CLOSEST considers only the interface nodes.

Format
inode_id_closest (marker, flex_body, intpt)

Arguments

marker Name of the marker object.

flex_body Name of the flexible body object.
intpt Integer flag:

• 1 - Consider only interface nodes.

• 0 - Consider all nodes.

Returns
If NODE_ID_CLOSEST finds no node, it returns a integer value of zero (0) with no warning.

Example
The figure on the next page shows a flexible body, link, with two interface points at nodes 10000 and
20000. There is also a marker on ground, marker_1. The example below finds the interface node on link
that is closest to marker_1 and assigns its node number to the integer variable .int_node.
var set var=.int_node int=(eval(node_id_closest(marker_1, link,
1)))

Learn more about GUI functions.

 Design-Time Functions 295
Functions: M - P

NODE_ID_IS_INTERFACE
Indicates whether the specified node of a flexible body is an interface node by returning 1 for yes, 0 for
no.

Format
NODE_ID_IS_INTERFACE(flexible_body, node_id)

Arguments

flexible_body Key of flexible body.

node_id Specifies the node ID on flexible body.

Example
if cond=(NODE_ID_IS_INTERFACE(FlexBodyObj, ThisNode))
Learn more about GUI functions.
296 Adams/View Function Builder
Functions: M - P

NODE_IDS_CLOSEST_TO
Returns array containing node IDs (integers) of the number (num) of
nodes on a flexible body closest to a specified marker.

Format
node_ids_closest_to (marker, flex_body, num, intpt)

Arguments

marker Name of the marker object.

flex_body Name of the flexible body object.
num Number of nodes requested.
intpt Integer flag:

• 1 - Consider only interface nodes.

• 0 - Consider all nodes.

Returns
If NODES_IDS_CLOSEST_TO finds no nodes, it returns a single
integer value of -1 with no warning.

Example
The following example displays the three nodes on the flexible body
named link closest to marker_1 on ground. It displays the nodes in the
Info window, as shown in the figure below.
 Design-Time Functions 297
Functions: M - P

var set var=.nodes int=(eval(node_ids_closest_to(marker_1, link,

3, 0))) &
comments = "3 closest nodes to marker"

Learn more about GUI functions.

298 Adams/View Function Builder
Functions: M - P

NODE_IDS_IN_VOLUME
Returns an array containing node IDs (integers) for all nodes on a flexible body, which reside inside the
volume of the geometry object, geom. geom must be either a spherical ellipsoid or a cylinder.

Format
node_ids_in_volume (flex_body, geom)

Arguments

flex_body Name of the flexible body object.

geom Name of the geometry object. The geometry object must be either a cylinder or a
spherical ellipsoid (that is, xscale==yscale==zscale).

Returns
If NODE_IDS_IN_VOLUME finds no nodes, it returns a single integer value of -1 with no warning.

Example
The following example assigns the value of -1 to variable .nodes because none of the nodes of the flexible
body, link, are contained in the geometric object, sphere, as shown in the figure below.
 Design-Time Functions 299
Functions: M - P

var set var=.nodes int=(eval(node_ids_in_volume(link, sphere)))

Learn more about GUI functions.

300 Adams/View Function Builder
Functions: M - P

NODE_IDS_WITHIN_RADIUS
Returns an array of node IDs (integers) associated with all the nodes of a flexible body within a radius of
a marker. If you set intpt to 1, NODE_IDS_WITHIN_RADIUS only considers interface nodes.

Format
node_ids_within_radius (marker, flex_body, radius, intpt)

Arguments

marker Name of the marker object.

flex_body Name of the flexible body object.
radius Radius around marker to check for nodes.
intpt Integer flag:

• 1 - Consider only interface nodes.

• 0 - Consider all nodes.

Returns
If NODE_IDS_WITHIN_RADIUS finds no nodes, it returns a single integer value of -1 with no warning.

Example
The figure shown below shows the flexible body, link, with a circle of radius 5.75 centered at the location
of marker, link.marker_2. All 10 nodes located within this circle are labeled in the figure. The following
command assigns these node numbers to the variable .nodes:
var set var=.nodes
int=(eval(node_ids_within_radius(.model_1.link.marker_2,.model_1
.link, 5.75,0)))
 Design-Time Functions 301
Functions: M - P

Learn more about GUI functions.

302 Adams/View Function Builder
Functions: M - P

NODE_NODE_CLOSEST
Returns an integer node ID associated with a node of the flexible body, o_new_flex, closest to node,
old_nodeId, on the flexible body o_old_flex. If intptis set to 1, only the interface nodes are considered.

Format
int vc_node_node_closest(KEY o_old_flex, KEY o_new_flex, int old_nodeID, intpt)

Arguments

KEY o_old_flex The old flexible body.

Key o_new_flex The new flexible body.
nodeId The node ID on the old flexible body.
intpt An integer flag:

• 1: Consider only interface nodes

• 0: Consider all nodes

Example
The following example:
variable set variable = tmp &
integer=(eval(node_node_closest(old_part, new_part,
old_node_id1)))
returns the ID of the interface node on new_part closest to the location of the old_node_id on old_part.
Learn more about GUI functions.
 Design-Time Functions 303
Functions: M - P

NORM
Calls the MATLAB NORM function. This returns a real scalar. The norm of a matrix is a scalar that gives
some measure of the magnitude of the elements of the matrix. The NORM function calculates the largest
singular value of the input array, A, max(svd(A)).

Format
NORM (A)

Argument

A An array of real values.

Example
variable create variable=N real=(norm({1,2,3}))
produces a value of 3.7417 for N.
Learn more about matrix/array functions.
304 Adams/View Function Builder
Functions: M - P

NORM2
Returns the square root of the sum of the squares of the elements of a matrix.
The NORM2 function could also be written as SQRT(SUM
(N ** 2)) or SQRT(SSQ(N)), but these would execute slower than NORM2.

Format
NORM2 (M)

Argument

M A matrix.

Example
The following example illustrates the use of the NORM2 function:

Function NORM2({[1, 2], [3, 4]})

Result 5.47722 (SQRT(1**2 + 2**2 + 3**2 + 4**2))

Learn more about matrix/array functions.

 Design-Time Functions 305
Functions: M - P

NORMALIZE
Returns the normalized elements of a matrix.
The function NORMALIZE could also be written as M/NORM2(M), but this would execute much
slower than NORMALIZE.

Format
NORMALIZE (M)

Argument

M A matrix.

Example
The following example illustrates the use of the NORMALIZE function:

Function ({3,4,5})
Result {0.424, 0.566, 0.707}

Learn more about matrix/array functions.

306 Adams/View Function Builder
Functions: M - P

NOTAKNOT_SPLINE
Creates an interpolated curve from input points with a specified number of values. Interpolates using the
Not-a-knot cubic spline.
The length of the Independent Data array must be the same as the Dependent Data array.

Format
NOTAKNOT_SPLINE (Independent Data, Dependent Data, Number of Output Values)

Arguments

Independent Data A 1xN array of x values for the curve to be interpolated. The x values of
the points must be in ascending order, and the length of the array must
be greater than or equal to 4.
Dependent Data A 1xN array of y values for the curve to be interpolated.
Number of Output Values The number of values to be generated in the output array.

Example
The following function interpolates a set of four points with ordinal values from 1 to 4 and abscissal
values as shown, into a series of 10 abscissal values:

Function NOTAKNOT_SPLINE({1, 2, 3, 4}, {0, 2, 1, 3}, 10)

Result {0.0, 1.370, 1.963, 2.0, 1.704, 1.296, 1.0, 1.037, 1.630, 3.0}

To compute the ordinal values for these splined values, you can use the SERIES2 function as follows:

Function SERIES2(1, 4, 10)

Result {1.0, 1.333, 1.667, 2.0, 2.333, 2.667, 3.0, 3.333, 3.667, 4.0}

Learn more about matrix/array functions.

 Design-Time Functions 307
Functions: M - P

ON_OFF
Returns the character string on or off, depending on the state of the argument.

Format
ON_OFF (State)

Argument

State Integer value denoting a Boolean value of on (1) or off (0).

Example
The following example illustrates the use of the ON_OFF function:

Function ON_OFF(1)
Result on

Learn more about string functions.

308 Adams/View Function Builder
Functions: M - P

ORI_ALIGN_AXIS
Returns an orientation that aligns one axis of a coordinate system object with an axis of another. It only
aligns one axis and leaves the others in unspecified orientations.

Format
ORI_ALIGN_AXIS (Frame Object, Axis Spec)

Arguments

Frame Object Coordinate system object defining the alignment.

Axis Spec Character string defining the type of alignment.

All of the valid strings are xx, xy, xz, yx, yy, yz, zx, zy, zz, x+x, x+y, x+z, y+x, y+y,
y+z, z+x, z+y, z+z, x-x, x-y, x-z, y-x, y-y, y-z, z-x, z-y, and z-z. The first character
defines the axis of the result. The last character defines the axis of the coordinate
system object to which the result is aligned. For example, xy aligns the x-axis of the
result with the y-axis of the coordinate system object.

You can insert either "-" or "+" as the middle character. For example, if you insert "-
" as in z-z, this indicates that the z-axis of the result is to be aligned in the opposite
direction of the z-axis in frame.

The Axis Spec parameters xx, x+x, yy, y+y, zz, and z+z are identity values resulting
in the global orientation of the coordinate system object. You can, however, compute
this orientation more efficiently by using the function ORI_GLOBAL.
 Design-Time Functions 309
Functions: M - P

Example
In the following illustration, the ORI_ALIGN_AXIS function returns all the angles of rotation associated
with a body-fixed 313 rotation sequence:

Function ORI_ALIGN_AXIS(marker_1, "z-z")

Result 90, 180, 0

Learn more about location/orientation functions.

310 Adams/View Function Builder
Functions: M - P

ORI_ALIGN_AXIS_EUL
Returns an orientation that aligns one axis of a coordinate system object with an axis of another. It only
aligns one axis and leaves the others in undefined orientations.

Format
ORI_ALIGN_AXIS_EUL (Orientation, Axis Spec)

Arguments

Orientation An orientation that defines the axes about which the coordinate system object is to be
oriented.
Axis Spec A character string defining the type of alignment.
All of the valid strings are xx, xy, xz, yx, yy, yz, zx, zy, zz, x+x, x+y, x+z, y+x, y+y, y+z,
z+x, z+y, z+z, x-x, x-y, x-z, y-x, y-y, y-z, z-x, z-y, and z-z. The first character defines the
axis of the result. The last character defines the axis of the frame to which the result is
aligned. For example, xy aligns the x-axis of the result with the y-axis of the coordinate
system object.

You can insert either “-” or “+” as the middle character. For example, if you insert “-” as
in z-z, this indicates that the z-axis of the result is to be aligned in the opposite direction
of the z-axis in frame.

The Axis Spec parameters xx, x+x, yy, y+y, zz, and z+z are identity values, resulting in
the global orientation of the coordinate system object. You can, however, compute this
orientation more efficiently by using the function ORI_GLOBAL.

Example
In the following illustration, the ORI_ALIGN_AXIS_EUL function returns all the angles of rotation
associated with a body-fixed 313 rotation sequence:

Function ORI_ALIGN_AXIS_EUL({8,10,0}, “z-z”)

Result 188, 170, 90
 Design-Time Functions 311
Functions: M - P

Learn more about location/orientation functions.

312 Adams/View Function Builder
Functions: M - P

ORI_ALL_AXES
Returns a body-fixed 313 Euler sequence describing an orientation in which the first axis of a coordinate
system object is parallel to, and co-directed with, a line defined by the first two points in a plane, and its
second axis is parallel to the plane.

Format
ORI_ALL_AXES (Plane Point Locations, Axes Names)

Arguments

Plane Point Locations 3x3 matrix providing three non-colinear points describing a plane. The points
are expressed in the global coordinate system.
Axes Names Character string indicating which two axes to orient.

xy, yx, xz, zx, yz, and zy are the only possible values (character case is
insignificant). Also, since each value defines a distinct orientation, xy is not
the same as yx.

Examples
In the following illustration, the ORI_ALL_AXES function returns a body-fixed 313 Euler sequence
describing an orientation, as specified.

Function ORI_ALL_AXES({{14,18,0},{10,14,0},{16,14,0}}, "xz")

Result 45, 90, 180
 Design-Time Functions 313
Functions: M - P

In the following illustration, the ORI_ALL_AXES function returns a body-fixed 313 Euler sequence
describing an orientation, as specified:

Function ORI_ALL_AXES({{14,18,0},{10,14,0},{16,14,0}}, zx)

Result 315, 90, 0

Learn more about location/orientation functions.

314 Adams/View Function Builder
Functions: M - P

ORI_ALONG_AXIS
Returns the alignment of a specified axis from one coordinate system object to another. This function has
an underlying parameter that allows it to express the resulting orientation in the proper coordinate system
object.

Note: ORI_ALONG_AXIS duplicates the actions of the ALONG_AXIS_ORIENTATION

parameter on the PART and MARKER commands.

Format
ORI_ALONG_AXIS (From Frame, To Frame, Axis Name)

From Frame Coordinate system object that defines a starting point for the orientation vector.
To Frame Coordinate system object that defines the ending point for the orientation vector.
Axis Name Character string indicating which axis is to be aligned. The possible values are x, y or
z (character case is not significant).

Example
In the following illustration, the ORI_ALONG_AXIS function returns the alignment of a specified axis:

Function ORI_ALONG_AXIS(marker_1, marker_2, "y")

Result 315, 0, 0
 Design-Time Functions 315
Functions: M - P

Note: The returned y axis is aligned with the line through marker_1 and marker_2.

Learn more about location/orientation functions.

316 Adams/View Function Builder
Functions: M - P

ORI_FRAME_MIRROR
Returns an orientation that has the specified axes mirrored about a plane within a coordinate system
object.

Format
ORI_FRAME_MIRROR (Body Fixed 313 Angles, Frame Object, Plane Name, Axes Name)

Body Fixed 313 Angles Array of body-fixed 313 Euler rotation sequences, expressed in the global
coordinate system.
Frame Object Coordinate system object defining the plane of reflection.
Plane Name Character string that selects one of three planes in a coordinate system
object. xy, yx, xz, zx, yz, and zy are the only possible value (character case
is insignificant). Also, order is insignificant; that is, xy is the same as yx.
Axes Name Character string that indicates which axes to mirror. xy, yx, xz, zx, yz, and
zy are the only possible values (character case is insignificant). Also, order
is insignificant; that is, xy is the same as yx.

Example
In the following illustration, the ORI_FRAME_MIRROR function returns an orientation, as specified:

Function ORI_FRAME_MIRROR({6,14,0}, marker_1, “xz”, “xz”)

Result 174, 14, 180
 Design-Time Functions 317
Functions: M - P

Learn more about location/orientation functions.

318 Adams/View Function Builder
Functions: M - P

ORI_GLOBAL
Resolves an angle expressed in a coordinate system object to the global coordinate system.
ORI_GLOBAL is the shorthand for ORI_ORI.

Format
ORI_GLOBAL(Orientation, Frame Object)

Arguments

Orientation Array of body-fixed 313 Euler rotations to be transformed to the global coordinate
system.
Frame Object Coordinate system object in which each sequence in the angle is expressed.

Example
In the following illustration, the ORI_GLOBAL function returns an orientation, as specified:

Function ORI_GLOBAL({marker_2.orientation}, marker_1)

Result 270, 0, 0

Learn more about location/orientation functions.

 Design-Time Functions 319
Functions: M - P

ORI_IN_PLANE
Returns an orientation by directing one of the axes and defining one of the planes within a coordinate
system object. ORI_IN_PLANE has an underlying parameter that allows it to express the resulting
orientation in the proper coordinate system object.

Note: ORI_IN_PLANE duplicates the actions of the IN_PLANE_ORIENTATION parameter on

the PART and MARKER commands.

Format
ORI_IN_PLANE (Frame Object 1, Frame Object 2, Frame Object 3, Directed Axes & Coordinate)

Frame Object 1 Coordinate system object defining a starting point for the orientation
plane.
Frame Object 2 Coordinate system object defining another point for the orientation
plane.
Frame Object 3 Coordinate system object defining another point for the orientation
plane.
Directed Axes & Coordinate Character string defining which axis is to be directed and which
coordinate system object plane is to be oriented. The possible values
for this parameter are: x_xy, x_xz, y_yx, y_yz, z_zx, or z_zy.
320 Adams/View Function Builder
Functions: M - P

Example
In the following illustration, the ORI_IN_PLANE function returns an orientation, as specified:

Function ORI_IN_PLANE(marker_1, marker_2, marker_3, "z_zy")

Result 135, 90, 90

Learn more about location/orientation functions.

 Design-Time Functions 321
Functions: M - P

ORI_LOCAL
Returns an orientation, expressed in the global frame, in the local frame of the coordinate system object.
ORI_LOCAL is the shorthand for ORI_ORI.

Format
ORI_LOCAL (Orientation, Frame Object)

Arguments

Orientation Array of body-based 313 Euler rotations expressed in the global coordinate system.
Frame Object Coordinate system object into which the rotations are to be transformed.

Example
The following example illustrates the use of the ORI_LOCAL function.

Function ORI_LOCAL({marker_1.orientation}, marker_2)

Result 90, 0, 0

Learn more about location/orientation functions.

322 Adams/View Function Builder
Functions: M - P

ORI_MIRROR
Returns an orientation by performing a mirroring of the given orientations that reflect the specified axes.

Format
ORI_MIRROR (Body Fixed 313 Angles, Frame Object, Plane Name, Axes Name)

Arguments

Body Fixed 313 Angles Array of body-fixed 313 Euler rotation sequences, expressed in a coordinate
system object.
Frame Object Coordinate system object that defines the plane of reflection.
Plane Name Character string selecting one of three planes in the coordinate system
object.

The only possible values are: xy, yx, xz, zx, yz, and zy (character case is
insignificant). Character order is insignificant; that is, xy is the same as yx.
Axes Name Character string indicating which axes to mirror.

The only possible values are: xy, yx, xz, zx, yz, and zy (character case is
insignificant). Character order is insignificant; that is, xy is the same as yx.

Example
In the following illustration, the ORI_MIRROR function returns an orientation, as specified:

Function ORI_MIRROR({{10,8,0}}, marker_1, “xy”, “xy”)

Result 190, 8, 180
 Design-Time Functions 323
Functions: M - P

Note: Because complete mirroring would change the right-handedness of the mirrored coordinate
system object, only partial mirroring is possible. To perform partial mirroring, you must
choose two axes to be mirrored, with the remaining axis pointing in the direction required
to maintain a right-handed system.

Learn more about location/orientation functions.

324 Adams/View Function Builder
Functions: M - P

ORI_ONE_AXIS
Returns a body-fixed 313 Euler rotation sequence expressed in the global coordinate system when given
a line that is parallel to, and co-directed with, a specified axis. The resulting rotation about the directed
axis is arbitrary with ORI_ONE_AXIS.
If you want to simultaneously control the orientation of the x, y, and z axes, use the ORI_ALL_AXES
function.

Format
ORI_ONE_AXIS (Line Point Locations, Axes Name)

Arguments

Line Point Locations A 3x2 matrix containing two points that describe a line. The points are
expressed in the global coordinate system.
Axed Name A single character string indicating which axis is to be oriented along the line.
The only possible values are x, y, or z (character case is insignificant).

Examples
In the following illustration, the ORI_ONE_AXIS function returns a body-fixed 313 Euler sequence:

Function ORI_ONE_AXIS({{10,16,0}, {8,16,0}}, "x")

Result 270, 90, 90
 Design-Time Functions 325
Functions: M - P

In the following illustration, the ORI_ONE_AXIS function returns a body-fixed 313 Euler sequence:

Function ORI_ONE_AXIS({{10,16,0}, {8,16,0}}, "z")

Result 180, 180, 0

In the following illustration, the ORI_ONE_AXIS function returns a body-fixed 313 Euler sequence:

Function ORI_ONE_AXIS({{10,16,0}, {8,16,0}}, "y")

Result 90, 0, 0
326 Adams/View Function Builder
Functions: M - P

Learn more about location/orientation functions.

 Design-Time Functions 327
Functions: M - P

ORI_ORI
Returns an orientation that represents the same orientation as expressed in the local frame of one
coordinate system object, to the local frame of another coordinate system object. Given an orientation
expressed in one coordinate system object, ORI_ORI produces a new orientation (representing the same
orientation) that is expressed in another coordinate system object.

Format
ORI_ORI (Orientation, From Frame Object, To Frame Object)

Arguments

Orientation Array of body-fixed 313 Euler rotations.

From Frame Object Coordinate system object in which each sequence in the angle is expressed.
To Frame Object Coordinate system object into which the rotations are to be transformed.

Example
In the following illustration, the ORI_ORI function returns an orientation, as specified:

Function ORI_ORI({marker_1.orientation}, marker_1, marker_2)

Result 180, 90, 90

Learn more about location/orientation functions.

328 Adams/View Function Builder
Functions: M - P

ORI_PLANE_MIRROR
Returns a sequence of body-fixed 313 Euler rotations by performing a mirroring of orientations. Using
an orientation, ORI_PLANE_MIRROR produces a new sequence describing an orientation that mirrors
the specified axes.

Format
ORI_PLANE_MIRROR (Angles, Plane Point Locations, Axes Names)

Arguments

Angles Array of body-fixed 313 Euler rotation sequences expressed in the global
coordinate system.
Plane Point Locations 3x3 matrix providing three non-colinear points described in a plane. The
points are expressed in the global coordinate system.
Axes Names Character string indicating which axes to mirror.

xy, yx, xz, zx, yz, and zy are the only possible values (character case is
insignificant). Character order is insignificant; that is, xy is the same as yx.

Examples
In the following illustration, the ORI_PLANE_MIRROR function returns a sequence of body-fixed 313
Euler rotations:

Function ORI_PLANE_MIRROR({marker_1.orientation},{{18,6,0},{18,12,0},{21,6,0}}, "xy")

Result 0, 0, 0
 Design-Time Functions 329
Functions: M - P

In the following illustration, the ORI_PLANE_MIRROR function returns a sequence of body-fixed 313
Euler rotations:

Function ORI_PLANE_MIRROR ({marker_1.orientation}, {{18,6,0}, {18,12,0},{21,6,0}}, "yz")

Result 180, 180, 0
330 Adams/View Function Builder
Functions: M - P

In the following illustration, the ORI_PLANE_MIRROR function returns a sequence of body-fixed 313
Euler rotations:

Function ORI_PLANE_MIRROR({marker_1.orientation},{{18,6,0},{18,12,0},{21,6,0}}, "xz")

Result 0, 180, 0

Note: Because complete mirroring would change the right-handedness of the mirrored
coordinate system object, only partial mirroring is possible. To perform partial mirroring,
you must choose two axes to be mirrored, with the remaining axis pointing in the direction
required to maintain a right-handed system.

In the example that follows, assume an orientation (CSO1) that points z to the right, x to the back, and y
up. Reflecting this orientation about the x-y plane (which is vertical and goes front to back), while
specifying a reflection (CSO2) of the xz axes causes z to point to the left, x to the back, and y down.
 Design-Time Functions 331
Functions: M - P

Learn more about location/orientation functions.

332 Adams/View Function Builder
Functions: M - P

ORI_RELATIVE_TO
Returns an orientation of a coordinate system object as specified by an angle. This parametric
representation of ORI_RELATIVE_TO maintains the relationship regardless of how other objects are
moved.
This function is shorthand for ORI_ORI (Orientation, Frame Object, To Frame Object) where the To
Frame Object is the underlying parameter. The underlying parameter determines the proper coordinate
system object for the transformations.

Format
ORI_RELATIVE_TO (Body 313 Rotations, Frame Object)

Arguments

Body 313 Rotations Array of body-fixed 313 Euler rotations.

Frame Object Coordinate system object in which each sequence in angle is expressed.

Example
The following example illustrates the use of the ORI_RELATIVE_TO function:

Function ORI_RELATIVE_TO({marker_1.orientation}, marker_2)

Result 180, 90, 180
 Design-Time Functions 333
Functions: M - P

Learn more about location/orientation functions.

334 Adams/View Function Builder
Functions: M - P

OTABLE_CHANGED_CELLS
Returns true or false (1, 0) depending on whether or not the object table contains any changed cell.

Format
OTABLE_CHANGED_CELLS(KEY o_otable)

Arguments

o_table Object table of interest.

Example
if cond=(OTABLE_CHANGED_CELLS(my_otable))
 Design-Time Functions 335
Functions: M - P

PARAM_STRING
Returns a parameter's values as they appear in an Adams command file.

Format
PARAM_STRING (Object Field)

Argument

Object Field Character string denoting the name of an object followed by a field name (for example,
mar1.orientation).

Examples
The following examples assume that you created a marker as follows:
marker create marker=mar1 location=(loc_relative_to({0,0,0},
mar2)) ori=1,2,3

Function PARAM_STRING("mar1.location")
Result "(LOC_RELATIVE_TO({0, 0, 0}, .mod1.ground.mar2))"

Function PARAM_STRING("mar1.orientation")
Result "1.0, 2.0, 3.0"

Learn more about database functions.

336 Adams/View Function Builder
Functions: M - P

PARSE_STATUS
Parses an Adams message file (usually with an .msg extension), and returns an array of integer status
codes corresponding to the given search tag.

Format
PARSE_STATUS(fileName, tag)

Arguments

fileName Name of the message file in which to search for status codes.
tag Character string indicating the status coes to extract.

Examples
A typical message file contains pairs of lines that look like the following:
ALVSIM:STATUS
Simulate status=0
or
A3TERM:STATUS
Termination status=-995
This function finds lines that match the contents of tag, and returns the numeric value following the equal
sign on the line following the tag match. It does this for the entire file, returning an array of status codes,
in the order in which it found them.
For example, if the above lines were to appear in test.msg, then you could execute the following
command and receive an array containing a single element, -995, as the result:
variable create variable=status
integer=(parse_status("test.msg", "A3TERM:STATUS"))

Tip: Use the LAST function if you want to retrieve only the final value. You could change the
example on the previous page to read as follows if you want to retrieve only the final value
in the file:
variable create variable=finalStatus &
integer=(last(parse_status("test.msg",
"A3TERM:STATUS")))

Learn more about system functions.

 Design-Time Functions 337
Functions: M - P

PARZEN
Returns the 1xN array of values after applying the PARZEN window function.

Format
PARZEN (a)

Argument

a 1xN array of real numbers.

Example
The following example illustrates the use of the PARZEN function:

Function PARZEN ({1,2,3,4,2})

Result {0.333, 1.333, 3.0, 2.667, 0.667}

Learn more about matrix/array functions.

338 Adams/View Function Builder
Functions: M - P

PARZEN_WINDOW
Generate the PARZEN window. The PARZEN window function gently forces the end points toward zero,
and smooths the remaining points.

Format
PARZEN_WINDOW (n)

Arguments

n An integer value.

Example
The following is an example of the use of the PARZEN_WINDOW function:

Function PARZEN_WINDOW(5)
Result {0.3333, 0.6667, 1.0000, 0.6667, 0.3333}

Learn more about matrix/array functions.

 Design-Time Functions 339
Functions: M - P

PHI
Returns the third angle associated with a Body 313 rotation sequence from one coordinate system object
to another. This third rotation is referred to as the phi,  , angle, and is used in association with the psi, 
, (1st rotation) and theta,  , (2nd rotation) angles.
Positive angular displacement is determined by the right-hand rule.

Format
PHI (Object, Reference Frame)

Arguments

Object Coordinate system object whose rotation is being measured.

Reference Frame Coordinate system marker with respect wi which the rotation is being measured.

Example
The following example illustrates the use of the PHI function:
PHI(marker_O, marker_R)
See the illustration for PSI.
Learn more about modeling functions.
340 Adams/View Function Builder
Functions: M - P

PICK_OBJECT
Prompts the user to select an object of a specified type from the screen. Returns the KEY of the selected
object.

Format
PICK_OBJECT(obj_type)

Argument

obj_type String indicating the type of object to be selected.

Example
var set var=pick_obj obj=(eval(PICK_OBJECT("marker")))
Learn more about GUI functions.
 Design-Time Functions 341
Functions: M - P

PITCH
Returns the negative value of the second angle associated with a Body 321 rotation sequence from one
coordinate system object to another. This angle is referred to as the pitch angle, and is used in association
with the yaw (1st rotation) and roll (3rd rotation) angles.

Note: Opposite from convention, this function calculates the negative of the second Body 321
angle.

Format
PITCH (Object, Reference Frame)

Arguments

Object Coordinate system object whose rotation is being measured.

Reference Frame Coordinate system object with respect to which the rotation is being measured.

Example
The following example illustrates the use of the PITCH function:
PITCH(marker_O, marker_R)
See the illustration for YAW.
Learn more about modeling functions.
342 Adams/View Function Builder
Functions: M - P

POLYFIT
Returns the coefficients of a polynomial fitted to the supplied function data.

Format
POLYFIT (x, y, order)

Arguments

x The array of x values.

y The array of y values.
order The maximum order of the polynomial, the returned coefficients are from 0th order to this
value.

Examples
The following commands:
var cre var=xx rea=(series2(0, 20, 20))
var cre var=yy rea=(1.0 + 1.2*xx + 2.5*xx**2 + 2.0*xx**3)
var cre var=pp rea=(polyfit(xx, yy, 5))
produce the array result.
The coefficients are ordered from the 0th order to the nth order from left to right.
[1.0, 1.2, 2.5, 2.0, 0.0, 0.0]
Learn more about matrix/array functions.
 Design-Time Functions 343
Functions: M - P

POLYVAL
Calls the MATLAB POLYVAL function and returns a real array. The POLYVAL function returns the y
values on the polynomial curve if given p, containing the polynomial coefficients, and an array of x
values. Note that the list of coefficients, p, is the reverse of that the MATLAB function requires. This
function complements the POLYFIT function, and POLYVAL uses the output coefficients from it
directly.

Format
POLYVAL (p, x)

Arguments

p The array of coefficients for the polynomial, constructing a polynomial:

f(x) = p0 + p1*x + p2*x2 + ... + pn*xn

x The array of x values at which to evaluate the polynomial.

Example
variable create variable=Yp real=(polyval({1,2,3},{5,7,9}))
produces a value for Yp of
{86.0, 162.0, 262.0}
344 Adams/View Function Builder
Functions: M - P

PROD
Returns the product of the elements of a matrix by performing a matrix reduction using multiplication.

Format
PROD (M)

Argument

M A matrix.

Example
The following example illustrates the use of the PROD function:

Function PROD({2, 3, 4})

Result 24

Learn more about matrix/array functions.

 Design-Time Functions 345
Functions: M - P

PSD
Computes the power spectral density from the complex Fourier coefficients. The PSD function uses the
periodogram estimate, as explained in Numerical Recipes (1989), equations 12.7.5, page 421.

Format
PSD (Values, Number of Output Values)

Arguments

Values The series values from which the FFT coefficients are computed. The
PSD function is computed from these complex coefficients.
Number of Output Values Indicates how many values should be returned; must be at least as many
as the number of input values, but not less than two.

Example
The following example illustrates the use of the PSD function:

Function PSD({0,1,4,9,16},7)
Result 144.0, 250.786, 167.080, 91.006, 51.367, 38.688, 17.016

Learn more about matrix/array functions.

346 Adams/View Function Builder
Functions: M - P

PSI
Returns the first angle associated with a body-fixed 313 rotation sequence from one coordinate system
object to another. This first rotation is referred to as the psi,  , angle, and is used in association with
the theta,  , (2nd rotation) and phi,  , (3rd rotation) angles.
Positive angular displacement is determined by the right-hand rule.

Format
PSI (Object, Reference Frame)

Arguments

Object Coordinate system object whose rotation is being measured.

Reference Frame The coordinate system marker with respect to which the rotation is being
measured.

Example
The following example illustrates the use of the PSI function:
PSI(marker_O, marker_R)
The following illustrations show the rotation sequence for PSI, THETA, and PHI:
 Design-Time Functions 347
Functions: M - P

Learn more about modeling functions.

348 Adams/View Function Builder
Functions: M - P

PUTENV
Returns the string value that PUTENV assigned to an environment variable. If successful, it returns a 0;
otherwise, it returns a non-zero value. PUTENV only affects the environment of the current executable.

Format
PUTENV (Environment Variable, Value)

Arguments

Environment Variable Character string denoting an environment variable.

Value Character string to be stored as the value of the environment variable.

Example
The following function, assigns the value X11 to MDI_AVIEW_WIN:

Function (PUTENV("MDI_AVIEW_WIN","X11"))
Result 0

Learn more about system functions.

 Design-Time Functions 349
Functions: M - P

PWELCH
Estimate the power spectral density (PSD) of a signal using Welch's method. Here we use MATLAB to
compute the PSD. This way the sum of the PSD is equal to the time-integral squared amplitude of the
original signal.

Format
PWELCH+ (a, nFft, Fs, win, nOverLap) returns ARRAY

Arguments

a An array indicating the sequence of signal to estimate the power spectral density.
nFft An integer indicating the length of FFT to be used.
Fs A real value indicating the frequency of the signal.
win An array indicating the array of the window to be used.
nOverLap An integer indicating the number of overlaps.

Learn more about matrix/array functions.

350 Adams/View Function Builder
Functions: R - S

Functions: R - S
RAND
Returns a pseudo-random value on the closed interval [0.0, 1.0], from a uniform distribution.

Note: The spectral distribution of this sequence may not meet your needs. You might consider
writing your own function if the demands of your application require a high-quality,
pseudo-random sequence. For further information on implementing the RAND( ) function
in Adams/View, refer to the main pages on your system to see how the Standard C library
function 'rand()' is implemented.

Format
RAND()

Argument
None

Examples
The following examples illustrate the use of the RAND function:

Function RAND ()
Result 0.59893834

Function RAND ()
Result 0.28873462

Learn more about math functions.

 Design-Time Functions 351
Functions: R - S

Real LIFE (FlexBody [, Analysis])

Returns the minimum life of a flexible body for the specified analysis. Learn more about LIFE function.

Arguments
• FlexBody: Name of flexible body.
• Analysis: Name of analysis (optional)

Returns
• Real value: Minimum life of body.
352 Adams/View Function Builder
Functions: R - S

Real MAX_STRESS (Body, Criterion)

Returns the maximum value of stress for the Body for the default analysis. Learn more about
MAX_STRESS function.

Arguments
• Body: Name of flexible body or part with a rigid stress object.
• Value: Flag for value of stress to use.

Returns
• Real value: Minimum life of body.
 Design-Time Functions 353
Functions: R - S

RECTANGULAR
Returns the 1xN array of values after applying the RECTANGULAR window function.

Format
rectangular (a)

Argument

a An array.

Example
The following example illustrates the use of the RECTANGULAR function:

Function RECTANGULAR ({1, 2, 3, 4, 2})

Result {1.0, 2.0, 3.0, 4.0, 2.0}

Learn more about matrix/array functions.

354 Adams/View Function Builder
Functions: R - S

RECTANGULAR_WINDOW
Generate the RECTANGULAR window.

Format
RECTANGULAR_WINDOW (n)

Argument

n An integer value.

Example
The following example is an illustration of the RECTANGULAR_WINDOW function:

Function RECTANGULAR_WINDOW (5)

Result {1, 1, 1, 1, 1}

Learn more about matrix/array functions.

 Design-Time Functions 355
Functions: R - S

REMOVE_FILE
Removes a file. If successful, it returns a 0; otherwise, it returns a nonzero value. REMOVE_FILE will
succeed in deleting a file that you opened with the file text open command, even if you did not close the
file.

Format
REMOVE_FILE (File Name)

Argument

File Name The file to be deleted.

Example
The following example illustrates the use of the REMOVE_FILE function:

Function REMOVE_FILE("Test_File.doc")
Result deletes Test_File.doc and returns a 0

Learn more about system functions.

356 Adams/View Function Builder
Functions: R - S

RENAME_FILE
Renames a specified file. If successful, it returns a 0; otherwise, it returns a nonzero value.

Format
RENAME_FILE (File Name, New File Name)

Arguments

File Name Text string containing the current file name.

New File Name Text string containing the new file name.

Example
The following example illustrates the use of the RENAME_FILE function:

Function RENAME_FILE("Test.mif.backup", "Test.doc")

Result renames the specified file as Test.doc and returns a 0

Learn more about system functions.

 Design-Time Functions 357
Functions: R - S

RESAMPLE
Takes a curve and resamples it over a new interval with the spline algorithm you specified.

Format
RESAMPLE (Curve, Sample Interval, Spline Type, Number of Spline Points)

Arguments

Curve A 2xN array of points to be interpolated.

Sample Interval The x values corresponding to the output data.
Spline Type The spline algorithm to use for interpolation. It must be one of the
following character strings:

• AKIMA = interpolates using the Akima method.

• CSPLINE = interpolates using the cubic splines.
• CUBIC = interpolates using a third-order Lagrangian polynomial.
• LINEAR = interpolates using linear interpolation.
• NOTAKNOT = interpolates using Not-a-knot cubic spline.
• HERMITE = interpolates using Hermite cubic spline.
Number of Spline Points Number of values to be generated in the internal smoothed curve.

Example
The following example illustrates the use of the RESAMPLE function:

Function RESAMPLE({[1, 2, 3, 4], [2, 3, 2, 1]}, "CUBIC", 200)

Result {0.015, 2.0, 3.0, 2.0, 1.0, 0.0}

Learn more about matrix/array functions.

358 Adams/View Function Builder
Functions: R - S

RESHAPE
Creates a new matrix from an existing matrix with dimensions you specified in the shape-descriptor
array.
RESHAPE produces valid results for any matrix with any given shape dimensions, getting values from
M in a cyclic fashion.

Format
RESHAPE (M,S)

Arguments

M A matrix.
S A shape-descriptor array. Can contain up to two dimensions.

Examples
The following example illustrates the use of the RESHAPE function:

Function RESHAPE({1, 0, 0, 0}, {3, 3})

Result {[1, 0, 0], [0, 1, 0], [0, 0, 1]}

Because scalars are coerced into 1x1 matrices, you can also have the following:

Function RESHAPE(1, {2, 2})

Result {[1, 1], [1, 1]}

Learn more about matrix/array functions.

 Design-Time Functions 359
Functions: R - S

REVERSE
Reverses the one-dimensional input array. The function type is generic, so it will reverse arrays of
integers, strings, doubles, or anything you specify.

Format
REVERSE (array)

Arguments

array A one-dimensional array.

Example
The following example illustrates the use of the REVERSE function:

Function REVERSE({"hello", "world"})

Result {"world", "hello"}

Learn more about matrix/array functions.

360 Adams/View Function Builder
Functions: R - S

RMDIR
Removes a specified directory .Uses the operating system rmdir function. Returns 1 if successful in
removing the directory; otherwise, it returns 0.

Format
RMDIR (path)

Arguments

path Name of the directory to remove.

Examples
var set var=deldir int=(eval(RMDIR("/usr/people/foo")))
Learn more about system functions.
 Design-Time Functions 361
Functions: R - S

RMS
Returns the root mean square of the values.

Format
RMS (Values)

Argument

Values The array of values for which to compute the RMS function.

Example
The following example illustrates the use of the RMS function:

Function RMS({0,1,4,9,16})
Result (SQRT(MEAN({0,1,4,9,16}**2)))

Learn more about matrix/array functions.

362 Adams/View Function Builder
Functions: R - S

ROLL
Returns the third angle associated with a Body 321 rotation sequence from one coordinate system object
to another. This angle is referred to as the roll angle, and is used in association with the yaw (1st rotation)
and pitch (2nd rotation) angles.
Positive angular displacement is determined by the right-hand rule.

Format
ROLL (Object, Reference Frame)

Arguments

Object Coordinate system object whose rotation is being measured.

Reference Frame Coordinate system object with respect to which the rotation is being measured.

Example
The following example illustrates the use of the ROLL function:
ROLL(marker_O, marker_R)
See the illustration for YAW.
Learn more about modeling functions.
 Design-Time Functions 363
Functions: R - S

ROWS
Returns the number of rows in a matrix.

Format
ROWS (M)

Argument

M A matrix.

Example
The following example illustrates the use of the ROWS function:

Function ROWS({1, 2, 3})

Result 3

Learn more about matrix/array functions.

364 Adams/View Function Builder
Functions: R - S

RTOI
Returns an integer representation of the input value, where the input value is a real number.

Format
RTOI(x)

Argument

x Any valid expression that evaluates to a real number.

Examples
The following examples illustrate the use of the RTOI function:

Function RTOI (.09)

Result 0

Function RTOI (7.7)

Result 7

Learn more about math functions.

 Design-Time Functions 365
Functions: R - S

SECURITY_CHECK
Returns a 1 or 0, depending on whether or not the product name is properly licensed.

Format
SECURITY_CHECK (ProductName)

Argument

ProductName A character string representing the product name.

The string is case sensitive. For example, the product name string for Adams/View is
AVIEW, so strings such as Aview, aview, AView, will fail.

Examples
var set var=fea_is_licensed & int=(eval(security_check("FEA")))
Learn more about GUI functions.
366 Adams/View Function Builder
Functions: R - S

SELECT_DIRECTORY
Returns the name of the directory you selected from the directory browser.

Format
SELECT_DIRECTORY (Dir)

Argument

DIR The directory to which to initialize the directory browser.

Example
SELECT_DIRECTORY("/staff/guest/files")
Learn more about GUI functions.
Design-Time Functions 367
Functions: R - S
368 Adams/View Function Builder
Functions: R - S

SELECT_FIELD
Returns a selected field as a string. SELECT_FIELD displays a selection list of fields, belonging to a
specified object, from which you can choose specific fields.

Format
SELECT_FIELD (Object)

Argument

Object A database object used to determine the type of object for which you want to see the
fields.

Example
The following example displays a select list allowing you to select a field from the list:
SELECT_FIELD(.model_1.part_1)
Learn more about GUI functions.
 Design-Time Functions 369
Functions: R - S

SELECT_FILE
Returns a file name you selected. SELECT_FILE displays the file name in the File Navigator.

Format
SELECT_FILE (File Filter, Directory)

Arguments

File Filter A character string containing a wildcard pattern, used to filter the file selections for
display.
Directory The directory where the file of interest is located.

Example
The following function returns a list of command files from which you can make a selection:
SELECT_FILE("*.cmd", "/staff/user")
Learn more about GUI functions.
370 Adams/View Function Builder
Functions: R - S

SELECT_MULTI_TEXT
Returns an array of strings you selected. SELECT_MULTI_TEXT displays a list of the strings you
supplied, and allows you to choose specific strings.

Format
SELECT_MULTI_TEXT (Strings)

Argument

Strings An array of strings to be displayed.

Example
The following example illustrates the use of the SELECT_MULTI_TEXT function:
SELECT_MULTI_TEXT({"one", "2", "three", "we"})
Learn more about GUI functions.
 Design-Time Functions 371
Functions: R - S

SELECT_OBJECT
Returns a selected object, using the Database Navigator to provide you with selections.
SELECT_OBJECT filters the list of selections using three pieces of information you specify:
• Parent of the objects
• Name of the objects
• Type of the objects

Format
SELECT_OBJECT (Parent, Wildcard, Type)

Arguments

Parent A database object defining the scope of the search used to find the displayed objects.
Wildcard A character string defining a name matching the pattern filter for the displayed objects.
Type A character string defining the type of the object to display.

Example
The following example displays all parts in model_1 whose names start with lin:
SELECT_OBJECT(.model_1, "lin*", "part")
Learn more about GUI functions.
372 Adams/View Function Builder
Functions: R - S

SELECT_OBJECTS
Returns an array of selected objects, using the Database Navigator to provide you with selections.
SELECT_OBJECTS filters the list of selections using three pieces of information you specify:
• Parent of the objects
• Name of the objects
• Type of the objects

Format
SELECT_OBJECTS (Parent, Wildcard, Type)

Arguments

Parent A database object defining the scope of the search used to find the displayed objects.
Wildcard A character string defining a name matching pattern filter for the displayed objects.
Type A character string defining the type of the object to display.

Example
The following example displays all the parts in model_1 whose names start with lin:
SELECT_OBJECT(.model_1, "lin*", "part")
Learn more about GUI functions.
 Design-Time Functions 373
Functions: R - S

SELECT_REQUEST_IDS
For a given request file, prompts the user to select request IDs of interest and returns an array of integers
representing the selected IDs.

Format
SELECT_REQUEST_IDS(request_file_name)

Argument

request_file_name String repesenting request file name.

Example
variable set variable=myids
int=(eval(SELECT_REQUEST_IDS("testuser.req")))
Learn more about GUI functions.
374 Adams/View Function Builder
Functions: R - S

SELECT_TEXT
Returns the string you selected. SELECT_TEXT displays a list of strings from which you can choose a
specific string.

Format
SELECT_TEXT (Strings)

Argument

Strings An array of strings to be displayed.

Example
The following example illustrates the use of the SELECT_TEXT function:
SELECT_TEXT({"one", "yes", "maybe"})
Learn more about GUI functions.
 Design-Time Functions 375
Functions: R - S

SELECT_TYPE
Returns a selection list of object types. Returns the selection as a string.

Format
SELECT_TYPE (Object Type)

Argument

Object Type The class or object type for which you want to see derived class or object types. Use
the value all to display the most inclusive list.

Example
The following example displays a list of all constraint types, such as joint and primitive joint:
SELECT_TYPE("Constraint")
Learn more about GUI functions.
376 Adams/View Function Builder
Functions: R - S

SERIES
Generates an array based on a start value, an increment value, and an array length.

Format
SERIES (Real, Real, Integer)

Arguments

Real Start value.

Real Increment value.
Integer Array length.

Example
The following example illustrates the use of the SERIES function:

Function SERIES(1,2,3)
Result 1, 3, 5

Learn more about matrix/array functions.

 Design-Time Functions 377
Functions: R - S

SHAPE
Returns the dimensions of a matrix.

Format
SHAPE (M)

Argument

M A matrix.

Example
The following example illustrates the use of the SHAPE function:

Function SHAPE({1, 2, 3})

Result {3, 1}

Learn more about matrix/array functions.

378 Adams/View Function Builder
Functions: R - S

SERIES2
Calculates an increment based on start and end values and a given number of increments.

Format
SERIES 2 (Real, Real, Integer)

Arguments

Real Start value.

Real End value.
Integer Number of increments.

Example
The following example illustrates the use of the SERIES2 function:

Function SERIES2(2, 8, 4)
Result 2, 4, 6, 8

Learn more about matrix/array functions.

 Design-Time Functions 379
Functions: R - S

SIGN
Returns a numerical value which takes its sign from one argument and its magnitude from another:
SIGN(x1, x2) = ABS(x1) if x2 > 0SIGN(x1, x2) = -ABS(x1) if x2 <
0

Note: SIGN is discontinuous. Use this function with care

Format
SIGN(x1, x2)

Arguments

x1 Any valid expression that evaluates to a real number.

x2 Any valid expression that evaluates to a real number.

Example
The following examples illustrate the use of the SIGN function:

Function SIGN(9.6, 4.5)

Result 9.6

Function SIGN(-4.7, 1.2)

Result 4.7

Function SIGN(5.3, -6.5)

Result -5.3

Function SIGN(-2.5, - 5.2)

Result -2.5

Learn more about math functions.

380 Adams/View Function Builder
Functions: R - S

SIM_STATUS
Parses an Adams message file (usually with an .msg extension), and returns an array of simulation status
codes corresponding to the tag: ALVSIM:STATUS.
This function is shorthand for PARSE_STATUS (fileName, ALVSIM:STATUS). For complete details,
see PARSE_STATUS.

Format
SIM_STATUS (fileName)

Argument

fileName Name of the file in which to look for simulation status codes.

Example
Executing the following command, returns an array of integers corresponding to the termination status
codes found in the file test.msg:
variable create variable=status integer=(sim_status("test.msg"))
Learn more about system functions.
 Design-Time Functions 381
Functions: R - S

SIM_TIME
Returns the simulation time for the last step of the default simulation. If there is no default simulation,
then SIM_TIME generates an error.

Format
SIM_TIME ()

Argument
None

Example
The following example illustrates the use of the SIM_TIME function:

Function SIM_TIME()
Result 0.45

Learn more about matrix/array functions.

382 Adams/View Function Builder
Functions: R - S

SIN
Returns the sine of an expression that represents a numerical value.

Format
SIN(x)

Argument

x Any valid expression that evaluates to a real number.

Example
The following example illustrates the use of the SIN function. The location of marker_1 and marker_2 is
shown in the figure below.

Function SIN(AZ(marker_2, marker_1, marker_1))

Result 0.707

Learn more about math functions.

 Design-Time Functions 383
Functions: R - S

SINH
Returns the hyperbolic sine of an expression that represents a numerical value:
SINH(x) = (ex - e-x) / 2.0Format
SINH(x)

Argument

x Any valid expression that evaluates to a real number.

Example
The following example illustrates the use of the SINH function. The location of marker_1 and marker_2
is shown in the figure below.

Function SINH(DX(marker_1, marker_2, marker_2))

Result -27.3

Learn more about math functions.

384 Adams/View Function Builder
Functions: R - S

SORT
Returns a matrix sorted in the direction you specified.

Format
SORT (M, D)

Arguments

M A matrix.
D Direction in which the matrix is sorted:

• a = ascending
• d = descending

Example
The following example illustrates the use of the SORT function:

Function SORT({3,2,1},"a")
Result {1,2,3}

Learn more about matrix/array functions.

 Design-Time Functions 385
Functions: R - S

SORT_BY
Returns an array sorted by another array in the direction you specified.

Format
SORT_BY (M1, M2, D)

Arguments

M1 MxN matrix by which an array is sorted.

M2 MxN matrix the function will return.
D Direction in which the matrix is sorted:

• a = ascending
• d = descending

Examples
The following examples illustrate the use of the SORT_BY function:

Function SORT_BY( {15, 19, 12} , {[4, 6, 9]} , "d" )

Result 6.0, 4.0, 9.0

Function SORT_BY( {84, 91, 84} , {[4, 6, 9]} , "d" )

Result 6.0, 9.0, 4.0

Learn more about matrix/array functions.

386 Adams/View Function Builder
Functions: R - S

SORT_INDEX
Returns the indexes of a matrix sorted in the direction you specified.

Format
SORT_INDEX (M, D)

Arguments

M A matrix.
D Direction in which the matrix is sorted:

• a = ascending
• d = descending

Example
The following example illustrates the use of the SORT_INDEX function:

Function SORT_INDEX({3,5,4,2},"a")
Result {4,1,3,2}

Learn more about matrix/array functions.

 Design-Time Functions 387
Functions: R - S

SPLINE
Creates an interpolated curve from the input points with the number of points you specified. Interpolates
using the spline algorithm you specified.

Format
SPLINE (Points, Spline Type, Number of Output Points)

Arguments

Points A 2xN array of points to be interpolated. The x values of the points must
be in ascending order, and the length of the array must be greater than or
equal to 4.
Spline Type The spline algorithm to use for interpolation. It must be one of the
following character strings:

• AKIMA = interpolates using the Akima method.

• CSPLINE = interpolates using the cubic splines.
• CUBIC = interpolates using a third-order Lagrangian
polynomial.
• LINEAR = interpolates using linear interpolation.
• NOTAKNOT = interpolates using Not-a-knot cubic spline.
• HERMITE = interpolates using Hermite cubic spline.
Number of Output Points Number of values to be generated in the output array.

Example
The following function interpolates a set of four points with ordinal values from 1 to 4 and abscissal
values as shown, into a series of 10 points using the cubic spline interpolation method.

Function SPLINE({[1, 2, 3, 4], [0, 2, 1, 3]}, "CSPLINE", 10)

Result {[1.0, 1.333, 1.667, 2.0, 2.333, 2.667, 3.0, 3.333, 3.667, 4.0], [0.0, 0.963, 1.704, 2.0, 1.741,
1.259, 1.0, 1.296, 2.037, 3.0]}

Learn more about matrix/array functions.

388 Adams/View Function Builder
Functions: R - S

SQRT
Returns the square root of an expression that represents a numerical value. The square root function is
defined only for non-negative values of the argument x.

Format
SQRT(x)

Argument

x Any valid expression that evaluates to a real number.

Example
The following example illustrates the use of the SQRT function:

Function SQRT(5*45)
Result 15

Learn more about math functions.

 Design-Time Functions 389
Functions: R - S

SSQ
Returns the sum of the squares of the elements of a matrix.

Format
SSQ (M)

Argument

M A matrix.

Example
The following example illustrates the use of the SSQ function:

Function SSQ({[1, 2], [3, 4]})

Result 30 (1**2 + 2**2 + 3**2 + 4**2)

Learn more about matrix/array functions.

390 Adams/View Function Builder
Functions: R - S

STACK
Returns the concatenation of two matrixes with the same number of columns.

Format
STACK (M1, M2)

Arguments

M1 A matrix of arbitrary shape.

M2 A matrix with the same number of columns as M1.

Example
The following example illustrates the use of the STACK function:

Function STACK({[1,2], [3,4]}, {[1,1], [2,2]})

Result {[1,2,1,1], [3,4,2,2]}

Learn more about matrix/array functions.

 Design-Time Functions 391
Functions: R - S

STATUS_PRINT
Returns a text string to all status bars.

Format
STATUS_PRINT (Status String)

Argument

Status String Text string.

Example
The following function displays the string in all window status bars, and returns its argument:

Function STATUS_PRINT("List")
Result List

Learn more about string functions.

392 Adams/View Function Builder
Functions: R - S

STEP
Returns an array of y values, on a step curve, corresponding to the x values.

Format
STEP (A, xo, ho,x1,h1)

Arguments

A An array of x values.
xo Value of x at which the step starts ramping from ho to h1.
ho Value of h when x is less than or equal to xo.
x1 Value of x at which the step function reaches h1.
h1 Value of h when x is greater than or equal to h1.

Example
The following example steps smoothly from 0.0 to 1.0 over the interval (2.0, 8.0). It has tails from 0 to 2
and from 8 to 10.
STEP(SERIES(0, 0.1, 100), 2.0, 0.0, 8.0,

1.0)
Learn more about matrix/array functions.
 Design-Time Functions 393
Functions: R - S

STOI
Performs an explicit conversion from string to integer. You usually don't need to use STOI because
Adams automatically coerces strings into integers, when the context demands it.

Format
STOI (String)

Arguments

String A character string representation of a number.

Examples
The following example illustrates the use of the STOI function:

Function STOI("1")
Result 1

Learn more about string functions.

394 Adams/View Function Builder
Functions: R - S

STOO
Performs an explicit conversion of a character string to a database object. You usually don't need to use
STOO because Adams automatically coerces strings naming objects into database objects, when the
context demands it. On the other hand, there are cases, when you need to explicitly convert a string to a
database object so you can use it later. For example, you need to convert a string to a database object
when you are synthesizing a name.

Format
STOO (String)

Arguments

String A character string representation of an object's name.

Examples
The following example illustrates the use of the STOO function:
marker create marker=.model_1.ground.mar1
variable create variable=.model_1.Index int=1
variable create variable=obj &
obj=(STOO(".model_1.ground.mar"//.model_1.Index))
list variable
Learn more about string functions.
 Design-Time Functions 395
Functions: R - S

STOR
Perform an explicit conversion from string to real number. You usually don't need to use STOR because
Adams automatically coerces strings into real values, when the context demands it.

Format
STOR (string)

Arguments

String A character string representation of a number.

Example
The following example illustrates the use of the STOR function:

Function STOR("12")
Result 12.0

Learn more about string functions.

396 Adams/View Function Builder
Functions: R - S

STR_CASE
Returns a string from an input string that has been modified according to an integer value.

Format
STR_CASE (String to Change, Case)

Arguments

String to Change Text string.

Case Integer value that determines case type as noted in the list below:

• 1 = Upper case
• 2 = Lower case
• 3 = Mixed case
• 4 = Sentence case

Examples
The following functions return modified strings, as specified:

Function STR_CASE("this is a TEST!",1)

Result THIS IS A TEST!

Function STR_CASE("this is a TEST!",2)

Result this is a test!

Function STR_CASE("this is a TEST!",3)

Result This Is A Test!

Function: STR_CASE("this is a TEST!",4)

Result This is a test!

Learn more about string functions.

 Design-Time Functions 397
Functions: R - S

STR_CHR
Returns a character whose ASCII value is mapped to an input integer.

Format
STR_CHR (Integer Value)

Argument

Integer Value ASCII value to be mapped.

Example
The following example returns the ASCII value of the letter A:

Function STR_CHR(65)
Result A

Learn more about string functions.

398 Adams/View Function Builder
Functions: R - S

STR_COMPARE
Returns a numeric value indicating the relative alphabetical ordering of two strings. Returns 0 if the two
strings are the same. Returns a positive number if the second string comes before the first. Returns a
negative number if the second string comes after the first.

Format
STR_COMPARE (String 1, String 2)

Arguments

String 1 Text string.

String 2 Text string.

Examples
The following function shows that the two strings are identical:

Function STR_COMPARE("adjective","adjective")
Result 0

The following function returns a positive number (whatever the numerical characters are), indicating that
the second string comes before the first string:

Function STR_COMPARE("verb","subject")
Result 3

The following function returns a negative number (whatever the numerical characters are), indicating that
the second string comes after the first string in ASCII character order:

Function STR_COMPARE("subject","verb")
Result -3

Learn more about string functions.

 Design-Time Functions 399
Functions: R - S

STR_DATE
Returns a string containing the current time and/or date information according to a format string.

Format
STR_DATE (Format String)

Argument

Note: All of the formatting directives described below are supported on non-Windows platforms,
but some are not supported on Windows. If the specified formatting directive is not
supported, then the function will simply return the input string.

Text string that uses the formatting directives listed below. If you supply an empty string (""), it defaults
to "%d %b %Y %H:%M".

The available formatting directives (expressed as current date, time or time zone) are:
Format String Description Supported
on Windows
(Y/N)
%a Abbreviated weekday name Y
%A Full weekday name Y
%b Abbreviated month name Y
%B Full month name Y
%c Date and time as %a %b %d %H:%M:&S %Y Y
%C Century number (the year divided by 100 and truncated to N
integer) as a decimal number (00-99)
%d Day of month (01-31) Y
%D Date as %m/%d/%y N
%e Day of month (1-31: single digits are preceded by a blank space) N
%h Abbreviated month name N
%H Hour (00-23) Y
%I Hour (01-12) Y
%j Day number of year (001-366) Y
%m Month number (01-12) Y
%M Minute (00-59) Y
%p Equivalent of either AM or PM Y
400 Adams/View Function Builder
Functions: R - S

%r Time as %I:%M:%S [AM|PM] N

%R Time as %H:%M N
%S Seconds (00-61), allows for leap seconds Y
%T Time as %H:%M:%S N
%U Week number of year (00-53), Sunday is first day of week one Y
%y Year within century (00-99) Y
%Y Year as century and year (for example, 1986) Y
%Z Time zone name or no characters if no time zone exists Y

Windows Only
If # flag is used as prefix to any formatting code, the meaning of the format changes as described below:

Format code Meaning

%#a, %#A, %#b, %#B, %#p, %#X, %#z, # flag is ignored.
%#Z, %#%
%#c Long date and time representation, appropriate for
current locale. For example: "Tuesday, March 14,
1995, 12:41:29".
%#x Long date representation, appropriate to current locale.
For example: "Tuesday, March 14, 1995".
%#d, %#H, %#I, %#j, %#m, %#M, %#S, Remove leading zeros (if any).
%#U, %#w, %#W, %#y, %#Y

Examples
The following function returns the current date and time in the stated argument format (January 5, 1998,
is the current date):

Function STR_DATE("%Y %m %d, %H:%M:%S")

Result 1998 01 05, 19:55:48

The following function returns the current date and time in the underlying argument format (January 5,
1998 is the current date):

Function STR_DATE("%c")
Result Mon Jan 5 10:35:01 1998
 Design-Time Functions 401
Functions: R - S

The following function returns the current date and time in the default format (January 5, 1998 is the
current date):

Function STR_DATE("")
Result 05 Jan 1998 13:22

The following function simply returns the input string, if the specified directive is invalid/not supported:

Function STR_DATE("ABC%D")
Result ABC%D

Learn more about string functions.

402 Adams/View Function Builder
Functions: R - S

STR_DELETE
Returns a string that results from deleting a specified number of characters starting from a specified
location on an input string.

Format
STR_DELETE (Input String, Starting Position, Number to Delete)

Arguments

Input String Text string.

Starting Position Integer value indicating the start location.
Number to Delete Integer value indicating the number of characters to delete.

Examples
The following function deletes the ninth character in the string and returns the resulting phrase:

Function STR_DELETE ("This is your life", 9, 1)

Result This is our life

In the following function, the out-of-range negative value (-100) of the Starting Position becomes 1:

Function STR_DELETE ("This is your life", -100, 10)

Result ur life

In the following function, the out of range positive value (100) of the Starting Position doesn't have any
effect on the string:

Function STR_DELETE ("This is your life", 100, 10)

Result returns the original string

Learn more about string functions.

 Design-Time Functions 403
Functions: R - S

STR_FIND
Returns the starting location of the first occurrence of a string within another string. If there is no match,
it returns a 0.

Format
STR_FIND (Base String, Search String)

Arguments

Base String Text string.

Search String Text string.

Examples
The following examples illustrate the use of the STR_FIND function:

Function STR_FIND ("Hello", "l")

Result 3

Function STR_FIND ("Hello", "o")

Result 5

The following function uses a second character in its search criteria to return 4, because letter "l" appears
twice in the word hello:

Function STR_FIND ("Hello", "lo")

Result 4

Learn more about string functions.

404 Adams/View Function Builder
Functions: R - S

STR_FIND_COUNT
Returns the number of occurrences of a string found within another string. Overlapping matches are not
included.

Format
STR_FIND_COUNT (Base String, Search String)

Base String Text string.

Search String Text string.

Examples
The following examples illustrate the use of the STR_FIND_COUNT function:

Function STR_FIND_COUNT("hammer stammer", "mm")

Result 2

Function STR_FIND_COUNT("hellllo jello", "ll")

Result 3

The following function returns 2 because the overlapping, matching 9's from 239990 to 129990 are not
included:

Function STR_FIND_COUNT("239990 129990", "99")

Result 2

Learn more about string functions.

 Design-Time Functions 405
Functions: R - S

STR_FIND_IN_STRINGS
Searches for a string in an array of strings. Returns the index into the array if the string is found, zero if
not found.

Format
STR_FIND_IN_STRINGS(array_of_strings, string)

Arguments

array_of_strings The array of strings to search.

string The string to search for.

Example
if cond=(STR_FIND_IN_STRINGS(unit_names, "force"))
Learn more about string functions.
406 Adams/View Function Builder
Functions: R - S

STR_FIND_N
Returns the numerical position of a character in a string found within another string. Returns 0 if not
found. Overlapping matches are not included.

Format
STR_FIND_N (Base String, Search String, Nth Occurrence)

Arguments

Base String Text string.

Search String Text string.
Nth Occurance Integer value indicating the number of string occurrences to be found.

Examples
The following function returns 10 because the second occurrence of string an begins at character position
10:

Function STR_FIND_N("meant human", "an", 2)

Result 10

The following function returns 16 because the overlapping, matching #'s from 43### to 55###9 are not
included, so the third occurrence of string ## begins at character position 16:

Function STR_FIND_N("43### 55###9 22##5", "##", 3)

Result 16

Learn more about string functions.

 Design-Time Functions 407
Functions: R - S

STR_INSERT
Returns a string constructed by inserting a string into another string at a specified insertion point.

Format
STR_INSERT (Destination String, Source String, Insert Position)

Arguments

Destination String Text string.

Source String Text string.
Insert Position Integer value noting the destination point in the string where the insertion is to
occur.

Examples
For the following function, blank spaces are needed in the Source String, before and after the text, in
order to return the desired output:

Function STR_INSERT ("That'sfolks", " all ", 7)

Result That's all folks

As with the STR_DELETE function, Insert Position can have any value, as shown in the following
example:

Function STR_INSERT ("A", "B", -10)

Result BA

Learn more about string functions.

408 Adams/View Function Builder
Functions: R - S

STR_IS_REAL
Returns a boolean truth value indicating that the input character string argument represents a valid real
number.

Format
STR_IS_REAL (String)

Argument

String Represents a real number.

Examples
The following examples illustrate the use of the STR_IS_REAL function:
if condition=(str_is_real ("Hi, Mom.")) ! returns
false
if condition=(str_is_real ($field_1_value))
Learn more about string functions.
 Design-Time Functions 409
Functions: R - S

STR_IS_SPACE
Returns 1 (true) if a string is empty; otherwise, returns 0 (false).

Format
STR_IS_SPACE (Input String)

Argument

Input String Text string.

Examples
The following examples illustrate the use of the STR_IS_SPACE function:

Function STR_IS_SPACE(" ")

Result 1

Function STR_IS_SPACE(" hello ")

Result 0

Learn more about string functions.

410 Adams/View Function Builder
Functions: R - S

STR_LENGTH
Returns a numerical value corresponding to the length of a string.

Format
STR_LENGTH (Input String)

Argument

Input String Text String.

Examples
The following example illustrates the use of the STR_LENGTH function:

Function STR_LENGTH ("Hello there")

Result 11

The following function returns 10 because the double slash marks (//) concatenated the two strings into
one:

Function STR_LENGTH ("Hello" // "there")

Result 10

Learn more about string functions.

 Design-Time Functions 411
Functions: R - S

STR_MATCH
Returns 1 (true) if a specified string is found within another string; otherwise, returns 0 (false).

Format
STR_MATCH (Pattern String, Input String)

Arguments

Pattern String Text string. The argument uses wildcards to define the pattern to match.

STR_MATCH uses four wildcard matching sequences:

This wildcard: Matches:
* an arbitrary sequence of characters
? one character
[char] any of the characters within the brackets
{string1,string2} any of the characters strings within the braces
Longer strings should appear before shorter ones when occurring in the sequence:
abc, ab, a.
Input String Text string.
412 Adams/View Function Builder
Functions: R - S

Examples
The following functions return 1 or 0, depending on whether a match occurred or not:

Function STR_MATCH("f?d","fad")
Result 1

Function STR_MATCH("f[xyz]d","fxd")
Result 1

Function STR_MATCH("f{ab,bc,cd}d","fbcx")
Result 0

Function STR_MATCH("1?{800,888}?[2ABC][3DEF]*, "1-800-2357205)

Result 1

Learn more about string functions.

 Design-Time Functions 413
Functions: R - S

STR_PRINT
Writes a string into the aview.log file. It is very useful for debugging.

Format
STR_PRINT (String)

Argument

String Text string.

Examples
In the following functions, the double slash marks (//) allow two or more strings to be concatenated into
a single string:

Function STR_PRINT("My variable is " // DV1)

Result writes My variable is 45 into aview.log (DV1 is equal to 45)

Function STR_PRINT("My variable is " // eval(STR_MATCH ("f*d", "fed")))

Result writes My variable is 1 into aview.log because a match occurred

Function STR_PRINT("My variable is " // eval(STR_MATCH ("f*d", "fet")))

Result writes My variable is 0 into aview.log because a match did not occur

Learn more about string functions .

414 Adams/View Function Builder
Functions: R - S

STR_REMOVE_WHITESPACE
A string that is the result of removing all leading and trailing spaces (blank spaces, tab spaces) from the
input string.

Format
STR_REMOVE_WHITESPACE (Input String)

Argument

Input String Text string.

Example
The following function returns the string without the spaces before and after it:

Function STR_REMOVE_WHITESPACE(" It's summer ")

Result It's summer

Learn more about string functions.

 Design-Time Functions 415
Functions: R - S

STR_SPLIT
Returns an array of strings built from substrings, which are separated from each other with a specified
character, and are located within another string.

Format
STR_SPLIT (Input Text String, Separator Character)

Arguments

Input Text String Text string. This string is unaltered during the evaluation of the function.
Separator Character Specified character that separates the substrings.

Examples
In the following functions, the second example string looks similar to the first one. It is different,
however, because the separator character has been changed to a # symbol so that a semi-colon could be
included with the first returned string (apple;). If a character needs to be included in the output, it cannot
be used as a separator character.
In all cases, STR_SPLIT trims any leading or trailing white spaces on the substrings:

Function STR_SPLIT(" apple; orange; grape ", ";")

Result apple, orange, grape

Function STR_SPLIT(" apple; # orange# grape ", "#")

Result apple;, orange, grape

Learn more about string functions.

416 Adams/View Function Builder
Functions: R - S

STR_SPRINTF
Returns a character string constructed by formatting the array of values in the format string.

Format
STR_SPRINTF (Format String, {Array of Values})

Arguments

Format String A C language format string.

Array of Values Array of values used to satisfy the format elements in the format string.

Example
The following example illustrates the use of the STR_SPRINTF function:

Function STR_SPRINTF("The %s of %s is %03d%%.", {"value", "angle", 2})

Result The value of the angle is 002%

Learn more about string functions.

 Design-Time Functions 417
Functions: R - S

STR_SUBSTR
Returns a substring with a designated number of characters starting at a specified point within a string.

Format
STR_SUBSTR (Input String, Starting Position, Length)

Arguments

Input String Text string.

Starting Position Integer value that determines the starting point of the substring.
Length Integer value that designates the number of characters in the substring.

Examples
The following function returns a substring of the input string:

Function STR_SUBSTR ("This is one string", 9, 8)

Result one stri

The following example shows that the Starting Position and Length arguments can have any value and
not cause errors:

Function STR_SUBSTR ("This is a string", -1000, 100)

Result returns the original string, since the values are out of range

Learn more about string functions.

418 Adams/View Function Builder
Functions: R - S

STR_TIMESTAMP
Returns the current date and time in the default format.

Format
STR_TIMESTAMP ()

Argument

None No argument is needed; this function returns the current date in the following format:

%Y/%m/%d,%H:%M:%S

Example
The following function returns the current date and time (Jan 5, 1998, is the current date):

Function STR_TIMESTAMP()
Result 1998/01/05,02:30:28

Learn more about string functions.

 Design-Time Functions 419
Functions: R - S

STR_XLATE
Returns a new string formed by replacing all occurrences of one or more characters found within the input
string, with an equal number of characters.

Format
STR_XLATE(Input String, From String, To String)

Arguments

Input String Text string.

From String Text string; must have the same number of characters as the To String.
To String Text string; must have the same number of characters as the From String.

Example
The following example illustrates the use of the STR_XLATE function:

Function STR_XLATE ("Why/-are/-you/-here/-?", "/-", ">_")

Result Why>_are>_you>_here>_?

Learn more about string functions.

420 Adams/View Function Builder
Functions: R - S

SUM
Returns the sum of the elements of a matrix by performing a matrix reduction using addition.

Format
SUM (M)

Argument

M A matrix.

Examples
The following examples illustrate the use of the SUM function:

Function SUM({[1, 2], [3, 4]})

Result 10

Function M = {[1, 2], [3, 4]}): {SUM(M[1]), SUM(M[2])}

Result {3, 7}

Learn more about matrix/array functions.

 Design-Time Functions 421
Functions: R - S

SYS_INFO
Returns a character string containing information that you requested about the system.

Format
SYS_INFO (info_type)

Argument

info_type A character string indicating the type of system information you want returned. Below
are five values that you can query:

GID - Numeric group id

GROUPNAME - Group name
HOSTNAME - Host name
UID - Numeric user id
USERNAME - User name
REALNAME - The user's name, if it is known.

Example
variable create variable=HostName str=(sys_info("hostname"))
Returns a value of the host machine, for example, SERV1.
Learn more about system functions.
422 Adams/View Function Builder
Functions: T - Z

Functions: T - Z
 Design-Time Functions 423
Functions: T - Z

TABLE_COLUMN_SELECTED_CELLS
Returns an array of integers representing the 1-based row numbers of selected cells within a specified
column in a table. If no cells are selected in the column, returns a 0.

Format
TABLE_COLUMN_SELECTED_CELLS (Column, O_table, Dummy1, Dummy2, Dummy3)

Arguments

Column Column number (1-based).

O_table Data/object table of interest.
Dummy1,2,3 Not currently used.

Example
The variable the_selected_cells will contain the row numbers (1-based) for all the cells that you select in
column 1:

Learn more about GUI functions.

424 Adams/View Function Builder
Functions: T - Z

TABLE_GET_CELLS
Returns an array of strings representing the contents of the cells within the specified row/column range.
Values are retrieved in column order.

Format
TABLE_GET_CELLS (O_table, Start_row, End_row, Start_col, End_col, Behavior, Ignore trailing
blanks)

Arguments

O_table Data/object table of interest.

Start_row / End_row The 1-based starting and ending rows of interest.
startCol, endCol The 1-based integer starting and ending columns of interest.
Behavior String that indicates how to treat blank cells. The options are:

• Blank = use an empty string.

• Zero = use a 0 for the contents of the cell.
• Failure = cause the entire retrieval to fail
Ignore trailing blanks Boolean value that indicates if the blanks at the ends of columns are to be
ignored when retrieving values. Applicable only when an entire row or
column is being processed.

Example
The following function gets the contents of the cells of the first two rows of the first two columns:

Learn more about GUI functions.

 Design-Time Functions 425
Functions: T - Z

TABLE_GET_DIMENSION
Returns an integer representing the number of rows or columns in a table or the number of cells in a row
or column.

Format
TABLE_GET_DIMENSION (O_table, Rows_or_cols)

Arguments

O_table Data/object table of interest.

Rows_or_cols String "rows" or "cols" to indicate desired dimension.

Examples
The following example returns the number of rows in a table:

The following example returns the number of columns in a table:

Learn more about GUI functions.

426 Adams/View Function Builder
Functions: T - Z

TABLE_GET_REALS
Returns an array of reals representing the contents of the cells within the specified row/column range.
Values are retrieved in column order.

Format
TABLE_GET_REALS (o_table, startRow,endRow,startCol,endCol, blankBehavior,
ignoreTrailingBlanks)

Arguments

o_table Data/object table of interest.

startRow, endRow The 1-based integer starting and ending rows of interest.
startCol, endCol The 1-based integer starting and ending columns of interest.
blankBehavior String indicating how to treat blank cells:

• zero- use a zero for the contents of the cell.

• failure-causes the entire retrieval to fail.
ignoreTrailingBlanks Boolean value (an integer of 1 or 0) to indicate if the blanks at the ends of
columns are to be ignored altogether when retrieving values. Applicable only
for the cases where an entire single row or column is being processed.

Returns an array of reals representing the contents of the cells within the
specified row/column range. Values are retrieved in column order.

Learn more about GUI functions.

 Design-Time Functions 427
Functions: T - Z

TABLE_GET_SELECTED_COLS
Returns the column numbers for the columns in a data table that are currently selected. A column is
considered as 'selected' if at least one of its cells is selected.
The function returns an array of integers representing the selected columns in the specified table.

Format
TABLE_GET_SELECTED_COLS(table)

Arguments

table A valid Data table object.

Example
1. interface dialog_box display dialog_box_name = .gui.spline_cremod ...(display any dbox that
contains a data table)
2. Manually select one or more of the cells in the table
3. variable create variable_name = sel_cols integer_value =
(eval(TABLE_GET_SELECTED_COLS(.gui.spline_cremod.c_tabular.dt_2d))) .. (use the
function)
4. Check the value of the created variable against the selection done in step2.

Note: The function returns a zero to indicate a no-selection condition. The function will also
return a zero when the input parameter 'table' is invalid (e.g. the dialog containing the table
is not loaded).

Learn more about GUI functions.

428 Adams/View Function Builder
Functions: T - Z

TABLE_GET_SELECTED_ROWS
Returns the row numbers for the rows in a data table that are currently selected. A row is considered as
'selected' if at least one of its cells is selected.
The function returns an array of integers representing the selected rows in the specified table.

Format
TABLE_GET_SELECTED_ROWS(table)

Arguments

table A valid Data table object.

Example
1. interface dialog_box display dialog_box_name = .gui.spline_cremod ...(display any dbox that
contains a data table)
2. Manually select one or more of the cells in the table
3. variable create variable_name = sel_rows integer_value =
(eval(TABLE_GET_SELECTED_ROWS(.gui.spline_cremod.c_tabular.dt_2d))) .. (use the
function)
4. Check the value of the created variable against the selection done in step2.

Note: The function returns a zero to indicate a no-selection condition. The function will also
return a zero when the input parameter 'table' is invalid (e.g. the dialog containing the table
is not loaded).

Learn more about GUI functions.

 Design-Time Functions 429
Functions: T - Z

TAN
Returns the tangent of an expression that represents a numerical value.

Format
TAN(x)

Argument

x Any valid expression that evaluates to a real number.

Example
The following example illustrates the use of the TAN function. The location of marker_1 and marker_2
is shown in the figure below.

Function TAN(7*DX(marker_1, marker_2, marker_2))

Result -.53

Learn more about math functions.

430 Adams/View Function Builder
Functions: T - Z

TANH
Returns the hyperbolic tangent of an expression that represents a numerical value:

TANH(x) = (ex-e-x)/(ex+e-x)

Format
TANH(x)

Argument

x Any valid expression that evaluates to a real number.

Example
Using a hyperbolic tangent, the following function defines a smooth step function that transitions from a
value of -1 to 1. The smoothness is controlled by the modifier, in this case 5.

Function TANH(5*(TIME-1.5))
Result -6.99

Learn more about math functions.

 Design-Time Functions 431
Functions: T - Z

TERM_STATUS
Parses an Adams message file (usually with an .msg extension), and returns an array of simulation status
codes corresponding to the tags: A3TERM:STATUS and TERM:STATUS.
This function is shorthand for the following expression:
STACK(PARSE_STATUS(fileName, "A3TERM:STATUS"), PARSE_STATUS(fileName,
"TERM:STATUS"))
For complete details, see PARSE_STATUS.
Note that this function returns its error codes as indicated in the expression above. First, it returns all the
A3TERM:STATUS codes found in the file. Then, it returns all the TERM:STATUS codes that are
appended to them.

Format
TERM_STATUS (fileName)

Argument

fileName Name of the file in which to look for simulation status codes.

Example
Executing the following command:
variable create variable=status
integer=(term_status("test.msg"))
Returns an array of integers corresponding to the termination status codes found in the file test.msg.
Learn more about system functions.
432 Adams/View Function Builder
Functions: T - Z

THETA
Returns the second angle associated with a Body 313 rotation sequence from one coordinate system
object to another. This second rotation is referred to as the theta,  , angle, and is used in association
with the psi,  , (1st rotation) and phi,  , (3rd rotation) angles.
Positive angular displacement is determined by the right-hand rule.

Format
THETA (Object, Reference Frame)

Arguments

Object Coordinate system object whose rotation is being measured.

Reference Frame Coordinate system object with respect to which the rotation is being measured.

Example
The following example illustrates the use of the THETA function:
THETA(marker_O, marker_R)See the illustration for PSI.
Learn more about modeling functions.
 Design-Time Functions 433
Functions: T - Z

TILDE
Returns the TILDE function of an array. You can use TILDE only on 3x1 matrixes.

Format
TILDE (A)

Argument

A An array.

Example
The following example illustrates the use of the TILDE function:

Function TILDE({x, y, z})

Result {[ 0, -z, y], [z, 0, -x], [-y, x, 0]}

Learn more about matrix/array functions.

434 Adams/View Function Builder
Functions: T - Z

TIMER_CPU
Either starts or ends a timer for measuring the accumulated time in CPU seconds used since the beginning
of the process execution.
If the endFlag is 0, then the timer is started and the current cpu runtime is returned. If the endFlag is 1,
then the timer is stopped and the cpu time since the last timer start is returned.

Note: The time is returned in seconds.

Format
TIMER_CPU(endFlag) returns REAL

Argument

startFlag If the endFlag is 0, then the timer is started and the current elapsed CPU is returned.

If the endFlag is 1, then the timer is stopped and the elapsed CUP time since the last timer
started is returned.

Example
variable set variable=mycpu real=(eval(timer_cpu(0)))
file command read file=mybidcmdfile
variable set variable=mycpu=real=(eval(timer_cpu(0)))
variable set var=foo string=(eval(str_print("file read took "
//mycpu//"cpuseconds")))
Learn more about GUI functions.
 Design-Time Functions 435
Functions: T - Z

TIMER_ELAPSED
Either starts or ends a timer for measuring the elapsed time in seconds.
If the endFlag is 0, then the timer is started and the current elapsed time is returned. If the endFlag is 1,
then the timer is stopped and the time since the last timer start is returned.

Note: This measures elapsed time, so time is always ticking away, unlike cpu time, for which time
only ticks away when the cpu is busy.

Format
TIMER_ELAPSED (endFlag) returns REAL

Arguments

startFlag If the endFlag is 0, then the timer is started and the current elapsed CPU is returned.

If the endFlag is 1, then the timer is stopped and the elapsed CUP time since the last timer
started is returned.

Example
variable set variable=myelapse real=(eval(timer_elapsed(0)))
file command read file=mybigcmdfile
var set var=foo string=(eval(str_print("file read
took"//myelapse//"seconds")))
Learn more about GUI functions.
436 Adams/View Function Builder
Functions: T - Z

TMAT3
Returns a 3x3 transformation matrix using the values in the orientation sequence you specify.

Format
TMAT3 (E, OriType, OriSequence)

Arguments

E 3x1 Euler orientation sequence.

OriType A single character, either "s" or "b" (character case is ignored), denoting that E contains
either space- or body-based rotations.
OriSequence A three digit integer specifying the axes about which the rotations take place. 313
would indicate that E[1] rotates about Z, E[2] rotates about X and E[3] rotates about Z.

Example
A typical invocation of this function might look like this:
TMAT3(mar1.orientation, "s" 123)
Learn more about matrix/array functions.
 Design-Time Functions 437
Functions: T - Z

TMAT
Returns a 3x3 transformation matrix using the values in the orientation sequence you specified.

Format
TMAT (E, OriType)

Arguments

E 3x1 Euler orientation sequence.

OriType Character string describing the contents of E. To define the rotation sequence, enter space
or body (character case is ignored), followed by three digits, such as 313 or 123.

Example
The following example illustrates the use of the TMAT function:
TMAT(mar1.orientation, "space123")
You can obtain the current default orientation type string with the expression:
(user_string(".system_defaults.orientation_type"))
Learn more about matrix/array functions.
438 Adams/View Function Builder
Functions: T - Z

TRANSPOSE
Returns the transpose of a matrix.

Format
TRANSPOSE (M)

Argument

M A matrix.

Examples
The following examples illustrate the use of the TRANSPOSE function:

Function TRANSPOSE({1,2,3}
Result {[1,2,3]}

Function TRANSPOSE({[1,2],[3,4]})
Result {[1,3],[2,4]}

Learn more about matrix/array functions.

 Design-Time Functions 439
Functions: T - Z

TRIANGULAR
Apply the TRIANGULAR window to the input array and return the new array.

Format
TRIANGULAR (a)

Argument

a An array.

Example
The following example is an illustration of the TRIANGULAR function:

Function triangular ({1, 2, 3, 4, 2})

Result {0.3333 1.3333 3.0000 2.6667 0.6667}

Learn more about matrix/array functions.

440 Adams/View Function Builder
Functions: T - Z

TRIANGULAR_WINDOW
Generate the TRIANGULAR window.

Format
TRIANGULAR_WINDOW (n)

Argument

n An integer.

Example
The following example is an illustration of the TRIANGULAR_WINDOW function:

Function triangular_window (5)

Result {0.3333 0.6667 1.0000 0.6667 0.3333}

Learn more about matrix/array functions.

 Design-Time Functions 441
Functions: T - Z

UNIQUE
Deletes all duplicate elements from an array.

Format
UNIQUE (Array)

Argument

Array An array.

Example
The following example illustrates the use of the UNIQUE function:

Function UNIQUE ({9, 1, 1})

Result 1.0, 9.0

Learn more about matrix/array functions.

442 Adams/View Function Builder
Functions: T - Z

UNIQUE_FILE_NAME
Returns a string that is the name of a non-existent file. It is the file system analogous to the database
UNIQUE_NAME function.

Format
UNIQUE_FILE_NAME (Initial File Name)

Argument

Initial File Name Prefix to use when creating the unique name.

Example
The following example illustrates the use of the UNIQUE_FILE_NAME function:

Function UNIQUE_FILE_NAME("test")
Result test_1

Learn more about datatbase functions.

 Design-Time Functions 443
Functions: T - Z

UNIQUE_ID
Returns an Adams_ID unique for objects of the specified type.

Format
UNIQUE_ID (char * type)

Argument

type Text string representing an entity type.

Example
var cre var=dv1 int=(eval(UNIQUE_ID("marker")))
Learn more about database functions.
444 Adams/View Function Builder
Functions: T - Z

UNIQUE_FULL_NAME
Returns a text string containing a unique full name for the specified type of object. If no default parent
exists for the type you specified, UNIQUE_FULL_NAME returns an empty string.

Format
UNIQUE_FULL_NAME (Type)

Argument

Type Text string that represents an entity type.

Example
The following example illustrates the use of the UNIQUE_FULL_NAME function:

Function UNIQUE_FULL_NAME("marker")
Result .model_1.ground.MAR

Learn more about database functions.

 Design-Time Functions 445
Functions: T - Z

UNIQUE_LOCAL_NAME
Returns a name of the form BASE_1, where BASE is a prefix that you supply and the number (1 in this
case) is computed by the function. The returned name is unique for children of the specified parent.

Format
UNIQUE_LOCAL_NAME (Parent, Base)

Argument

Parent The object defining the search domain for children.

Base A character string specifying the prefix part of the name to be produced.

Examples
The following illustrates the UNIQUE_LOCAL_NAME function:

Function UNIQUE_LOCAL_NAME(.model_1, "PAR")

Result Returns PAR_2 if PAR_1 already exists.

Learn more about database functions.

446 Adams/View Function Builder
Functions: T - Z

UNIQUE_NAME
Returns a text string that is a unique database name.

Format
UNIQUE_NAME (Base Name)

Argument

Base Name Starting point for a unique database name.

Example
The following example illustrates the use of the UNIQUE_NAME function:

Function UNIQUE_NAME("stat")
Result stat_1

Learn more about database functions.

 Design-Time Functions 447
Functions: T - Z

UNIQUE_NAME_IN_HIERARCHY
Returns a text string that is a unique database name, taking into account the inherent hierarchy in the
given input.This function is essentially a smarter form of UNIQUE_NAME. If an entity myname_1
already exists under .model_1, then UNIQUE_NAME_IN_HIERARCHY(“.model_1.myname”)
would return .model_1.myname_2 ensuring that the output is truly unique in the hierarchy specified
in the input. Note that an entity myname_2 might already exist under a different model, but the value
returned would still be .model_1.myname_2 as this name is still unique within the hierarchy of
.model_1.

Format
UNIQUE_NAME_IN_HIERARCHY (Base Name)

Argument

Base Name Starting point for a unique database name.

Example
The following example illustrates the use of the UNIQUE_NAME_IN_HIERARCHY function:
Assume that an object stat_1 already exists in the database.

Function UNIQUE_NAME_IN_HIERARCHY("stat")
Result stat_2

Learn more about database functions.

448 Adams/View Function Builder
Functions: T - Z

UNIQUE_PARTIAL_NAME
Returns a character string containing a unique object name.

Format
UNIQUE_PARTIAL_NAME (Parent, Type)

Arguments

Parent A database object defining the scope within which the name must be unique.
Type A character string defining the type of the object for which this name will be used.

Example
The following example produces PAR_1:
UNIQUE_PARTIAL_NAME(.model_1, "part")
Learn more about database functions.
 Design-Time Functions 449
Functions: T - Z

UNITS_STRING
Returns a text string containing a unit string associated with another string.

Format
UNITS_STRING (Object Field)

Argument

Object Field Character string that names the field of an object.

Example
The following example illustrates the use of the UNITS_STRING function:

Function UNITS_STRING(".mod1.part1.density")
Result returns something like kg/mm**3

Learn more about database functions.

450 Adams/View Function Builder
Functions: T - Z

UNITS_CONVERSION_FACTOR
Returns the numeric conversion factor from the given unit value to the current default units.

Format
UNITS_CONVERSION_FACTOR (UnitsValue)

Argument

UnitsValue A units value string defining the units from which you want to convert.

Examples
The following illustrates the use of the UNITS_CONVERSION_FACTOR function:

Function UNITS_CONVERSION_FACTOR("inch")
Result Returns 12.0 if the default length units are set to foot.

Learn more about database functions.

 Design-Time Functions 451
Functions: T - Z

UNITS_TYPE
Returns the character string value of the given unit type using the provided integer value.

Format
UNITS_TYPE (UnitsType)

Arguments

Units An encoded units value.

Examples
The following is an illustration of the UNITS_TYPE function:

Function var cre var=x rea=1 units="mass/time**3"

UNITS_TYPE(x.units)
Result Returns mass/time**3

Learn more about database functions.

452 Adams/View Function Builder
Functions: T - Z

UNITS_VALUE
Returns the character string value of the given unit type using the default units settings.

Format
UNITS_VALUE (UnitsType)

Argument

Units A units type string, such as angle or length/time**2.

Examples
The return values for these examples depend on the current default settings for units, and are given to
show the form of the result, not the actual values

Function UNITS_VALUE("angle")
Result Returns degrees

Function UNITS_VALUE("acceleration*time")
Result Returns foot/second

Learn more about database functions.

 Design-Time Functions 453
Functions: T - Z

UNWRAP
Unwraps phase angles in degree by changing absolute jumps greater than 180 degree to their 360 degree
complement.

Format
vc_unwrap (a) returns ARRAY

Argument

a An array indicating the phase angles to be unwrapped.

Learn more about matrix/array functions.

454 Adams/View Function Builder
Functions: T - Z

USER_STRING
Returns a text string containing a value in the Object Field. The Object Field must be a string.
USER_STRING is similar to EXPR_STRING, except that it always returns a non-empty value;
EXPR_STRING only returns a value when the field's value is defined with an expression.

Format
USER_STRING (Object Field)

Argument

Object Field Character string containing an object name and field reference.

Example
The following example illustrates the use of the USER_STRING function:
USER_STRING(".mod1.mar1.location")
Learn more about database functions.
 Design-Time Functions 455
Functions: T - Z

VAL
Returns an array element nearest the number you specified.

Format
VAL (A, X)

Arguments

A An array.
X A real number.

Example
The following example illustrates the use of the VAL function:

Function VAL({2,0,3}, 2.2)

Result 2

Learn more about matrix/array functions.

456 Adams/View Function Builder
Functions: T - Z

VALAT
Returns a value from the Y_array at the same position as X_value was found in the X_array. X_array and
Y_array must be the same length.

Note: This function expects the values in X_array to be sorted in ascending order.

Format
VALAT(X_array, Y_array, X_value)

Arguments

X_array An array of at least two real values that determine the range of the curve. Values must be
in ascending order.
Y_array An array containing the same number of real values as the X_array. Used to define the
domain of the curve.
value A value which "indexes" into the X_array.

Examples
model create model=mod1
variable create variable=x_array rea=-1,0,2,3
variable create variable=y_array rea= 1,2,3,4
variable create variable=xx rea=0.0
variable create variable=yy rea=(VALAT(x_array, y_array, xx))
VALAT produces values as follows:

xx -2, -1, 0, 1, 2, 3, 4
yy 0, 1, 2, 2.5, 3, 4, 5

Learn more about matrix/array functions.

 Design-Time Functions 457
Functions: T - Z

VALI
Returns the index of the element in an array nearest to the number you specify.

Format
VALI (A, X)

Arguments

A An array.
X A real number.

Example
The following example illustrates the use of the VALI function:

Function VALI({2,0,3}, 2.2)

Result 1

Learn more about matrix/array functions.

458 Adams/View Function Builder
Functions: T - Z

WELCH
Returns a 1xN array of values after applying the WELCH_WINDOW function.

Format
WELCH (a)

Argument

a A 1xN array of real numbers.

Example
The following example illustrates the use of the WELCH function:

Function WELCH ({1,2,3,4,2})

Result {0.556, 1.778, 3.0, 3.556, 1.111}

Learn more about matrix/array functions.

 Design-Time Functions 459
Functions: T - Z

WELCH_WINDOW
Generate the WELCH window. The WELCH_WINDOW function gently forces the end points toward
zero and smooths the remaining points.

Format
WELCH_WINDOW (n)

Argument

n An integer.

Example
The following example is an illustration of the WELCH_WINDOW function:

Function welch_window (5)

Result {0.5556, 0.8889, 1.0000, 0.8889, 0.5556}

Learn more about matrix/array functions.

460 Adams/View Function Builder
Functions: T - Z

YAW
Returns the first angle associated with a body-fixed 321 rotation sequence from one coordinate system
object to another. This angle is referred to as the yaw angle, and is used in association with the pitch (2nd
rotation) and roll (3rd rotation) angles.
Positive angular displacement is determined by the right-hand rule.

Format
YAW (Object, Reference Frame)

Arguments

Object Coordinate system object whose rotation is being measured.

Reference Frame Coordinate system object with respect to which the rotation is being measured.

Example
The following example illustrates the use of the YAW function:
YAW(marker_O, marker_R)
The following illustrations show the rotation sequence for YAW, PITCH, and ROLL:
 Design-Time Functions 461
Functions: T - Z

In Adams, PITCH is defined as the negative value of the second Body 321 rotation angle.
462 Adams/View Function Builder
Functions: T - Z

There are always two equivalent sets of rotation angles that yield the same final rotation.
Learn more about modeling functions.
 Run-Time Functions 461

Run-Time Functions
462 Adams/View Function Builder
About Run-Time Functions

About Run-Time Functions

Run-time functions allow you to specify mathematical relationships between the simulation states that
directly define the behavior of the system.
During the run time of your simulation, many system states change: time elapses linearly, parts displace,
and applied forces change in a variety of ways (such as, sinusoidal, and non-linear). Adams/View allows
you to manipulate the states of these system variables with run-time functions. Using run-time functions
you can build dependencies, such as a motion that's a function of (TIME)2 or a force that's a function of
velocity vertical displacement.
You can work with run-time functions from boxes that expect run-time functions, most commonly found
when working with applied forces and generated motions. You build a run-time function in the Function
Builder and then insert the function in the box that accepts run-time functions. To learn how to use the
Function Builder to work with run-time functions, please refer to the first three chapters of this guide.
When you enter in the Function Builder a function longer than 80 characters per line, Adams/View alerts
you that your function is too long. If your function is longer than 80 characters per line, it is best to split
it into two or more lines.

Note: While writing run-time functions, you can use either full names of objects or Adams IDs.
In run-time functions, you can use design variables that represent real numbers, integers,
or references to objects.

Learn more about:

• Run-Time Functions Categories
• Run-Time Functions Examples

Run-Time Functions Categories

This section introduces you to the run-time functions categories as they appear in the Function Builder.
For more details regarding each function, please see Run-Time Functions Examples.
Note that although some run-time functions have the same names as certain design-time functions, they
only work with a model at an analysis-time step.
The following sections give you an overview of the run-time functions categories. The functions
categories are presented in the order they appear in the Function Builder.
• Displacement Functions
• Velocity Functions
• Acceleration Functions
• Contact Functions
 Run-Time Functions 463
About Run-Time Functions

• Spline Functions
• Force in Object Functions
• Resultant Force Functions
• Math Functions
• Data Element Access
• User-Written Subroutine Invocation
• Constants & Variables

Displacement Functions
Displacement functions return scalar measures associated with a particular component of the
translational displacement vector from one coordinate system marker to another or an angular
displacement from one coordinate system marker to another.
You can use the displacement functions during a simulation to obtain from Adams the displacement
measurements of an object. Displacement functions provide measurements that can be useful in:
• Plotting displacement measurements.
• Creating equations which depend on the displacement of an object.
• Monitoring the displacement of an object and triggering the occurrence of special events when
the displacement reaches a certain value.
The following table lists the names and definitions for the displacement functions:

This function: Returns:

Distance Along X (DX) An x component of the translational displacement vector
from one coordinate system marker to another.
Distance Along Y (DY) A y component of the translational displacement vector
from one coordinate system marker to another.
Distance Along Z (DZ) A z component of the translational displacement vector
from one coordinate system marker to another.
Distance Magnitude (DM) The magnitude of the translational displacement vector
from one coordinate system marker to another.
Angle About X (AX) The rotational displacement (in radians) of one
coordinate system marker about the x-axis of another.
Angle About Y (AY) The rotational displacement (in radians) of one
coordinate system marker about the y-axis of another.
Angle About Z (AZ) The rotational displacement (in radians) of one
coordinate system marker about the z-axis of another.
464 Adams/View Function Builder
About Run-Time Functions

This function: Returns:

B321 Sequence: 1st Rotation (YAW) The first angle of rotation (in radians) associated with a
body-fixed 321 rotation sequence from one coordinate
system marker to another.
B321 Sequence: 2nd Rotation (PITCH) The negative of the second angle of rotation (in radians)
associated with a body-fixed 321 rotation sequence from
one coordinate system marker to another.
B321 Sequence: 3rd Rotation (ROLL) The third angle of rotation (in radians) associated with a
body-fixed 321 rotation sequence from one coordinate
system marker to another.
B313 Sequence: 1st Rotation (PSI) The first angle of rotation (in radians) associated with a
body-fixed 313 rotation sequence from one coordinate
system marker to another.
B313 Sequence: 2nd Rotation (THETA) The second angle of rotation (in radians) associated with
a body-fixed 313 rotation sequence from one coordinate
system marker to another.
B313 Sequence: 3rd Rotation (PHI) The third angle of rotation (in radians) associated with a
body-fixed 313 rotation sequence from one coordinate
system marker to another.

Velocity Functions
Velocity functions return a requested magnitude or component of the translational or rotational velocity
vector between two markers.
You can use the velocity functions during a simulation to obtain from Adams the velocity measurements
of an object. Velocity functions provide measurements that can be useful in:
• Plotting velocity measurements.
• Creating equations that depend on the velocity of an object.
• Monitoring the velocity of an object and triggering the occurrence of special events when the
velocity reaches a certain value.
The following table lists the names and definitions for the velocity functions:

Function: Returns:
Velocity Along X (VX) An x component of the difference between the velocity vectors
of two coordinate system markers.
Velocity Along Y (VY) A y component of the difference between the velocity vectors of
two coordinate system markers.
Velocity Along Z (VZ) A z component of the difference between the velocity vectors of
two coordinate system markers.
 Run-Time Functions 465
About Run-Time Functions

Function: Returns:
Velocity Magnitude (VM) The magnitude of the first time-derivative of the displacement
vector between two coordinate system markers.
Angular Velocity About X (WX) An x component of the difference between the angular velocity
vectors of two coordinate system markers.
Angular Velocity About Y (WY) A y component of the difference between the angular velocity
vectors of two coordinate system markers.
Angular Velocity About Z (WZ) A z component of the difference between the angular velocity
vectors of two coordinate system markers.
Angular Velocity Magnitude (WM) The magnitude of the difference between the angular velocity
vectors of two coordinate system markers.
Velocity Along Line-of-Sight (VR) The radial (relative) velocity to one coordinate system marker
from another.

Acceleration Functions
Acceleration functions return a requested magnitude or component of the translational or rotational
acceleration vector between two markers.
You can use the acceleration functions during a simulation to obtain from Adams the acceleration
measurements of an object. Acceleration functions provide measurements that can be useful in:
• Plotting acceleration measurements.
• Creating equations that depend on the acceleration of an object.
• Monitoring the acceleration of an object and triggering the occurrence of special events when the
acceleration reaches a certain value.
·
The WDT prefix used for angular acceleration functions implies  or omega-dot, the time derivative of
angular velocity.
The following table lists the names and definitions for the acceleration functions:

Function: Returns:
Acceleration Along X (ACCX) An x component of the difference between the
acceleration vectors of two coordinate system markers.
Acceleration Along Y (ACCY) A y component of the difference between the acceleration
vectors of two coordinate system markers.
Acceleration Along Z (ACCZ) A z component of the difference between the acceleration
vectors of two coordinate system markers.
466 Adams/View Function Builder
About Run-Time Functions

Function: Returns:
Acceleration Magnitude (ACCM) The magnitude of the second time-derivative of the
displacement vector to one coordinate system marker
from another coordinate system marker.
Angular Acceleration About X (WDTX) An x component of the difference between the angular
acceleration vectors of two coordinate system markers.
Angular Acceleration About Y (WDTY) A y component of the difference between the angular
acceleration vectors of two coordinate system markers.
Angular Acceleration About Z (WDTZ) A z component of the difference between the angular
acceleration vectors of two coordinate system markers.
Angular Acceleration Magnitude (WDTM) The magnitude of the difference between the angular
acceleration vectors of two coordinate system markers.

Contact Functions
You can use contact functions to define collision forces. The functions are built so as to turn on and off
during simulation, which makes them useful for representing bodies that come into intermittent contact
with one another.
The following table lists the names and definitions for the contact functions:

Function: Returns:
One-sided Impact (IMPACT) A real number for a force magnitude corresponding to a one-sided
collision, using a compression-only nonlinear spring-damper
formulation.
Two-sided Impact (BISTOP) A real number for a force magnitude corresponding to a two-sided
collision, using a compression-only nonlinear spring-damper
formulation.

Spline Functions
Splining is a method of interpolation that allows derivation of intermediate locations on a curve or surface
between known points.
You can use spline functions during a simulation to define smooth functions to approximately fit data
points. Spline functions can be useful when:
• Driving a motion with test data.
• Defining a force with test data.
• Plotting smooth curves through data points.

The following sections provide more information about splines:

• Interpolation Methods Overview
 Run-Time Functions 467
About Run-Time Functions

• Comparison of Interpolation Methods

• Where to Find the Spline Functions

Interpolation Methods Overview

Adams/View allows you to use three interpolation methods, as shown below:

Interpolation Fit Function

methods: characteristic: name: Advantages: Disadvantages:
Cubic spline Global CUBSPL • Accurate derivatives • Not as fast
• Curve • Some
• Surface waviness

B-spline Global CURVE • Accurate derivatives Curve only (no

• Can be user-defined surface)
with CURSUB
Akima Local AKISPL • Fast Inaccurate
• Curve derivatives

• Surface

Comparison of Interpolation Methods

The Akima interpolation is a local fit. Local methods require information only about points in the vicinity
of the interval being interpolated to define the coefficients of the cubic polynomial. This means that each
data point in an Akima spline only affects the nearby portion of the curve. Since it uses local methods,
Akima is very fast.
Akima always produces good results for the value of the function being approximated. AKISPL returns
good estimates for the first derivative of the approximated function when the data points are evenly
spaced. In instances where the data points are unevenly spaced, the estimate of the first derivative may
be in error. In all cases, the second derivative of the function being approximated is unreliable.
The cubic interpolation is a global fit. Global methods use all the given points to calculate all the
coefficients for all the intervals in question, simultaneously. Therefore, each data point affects the entire
cubic spline: if you move one point the whole curve changes accordingly, making a cubic spline wigglier
and harder to force into a desired shape. This is especially noticeable on functions with linear portions or
sharp changes in the curve. In these cases, a cubic spline will almost always have more wiggles than an
Akima spline.
Both global and local methods work well on smoothly-curving functions.
CUBSPL, though not as fast as AKISPL, always produces good results for the value of the function being
approximated, as well as its first and second derivatives. The data points don't have to be evenly spaced.
The solution process often requires estimates of derivatives of the functions being defined. The smoother
a derivative is, the easier it is for the solution process to converge.
468 Adams/View Function Builder
About Run-Time Functions

Smooth (continuous) second derivatives are important if you use the spline in a motion. The second
derivative is the acceleration enforced by the motion, which defines the reaction force required to drive
the motion. A discontinuity in the second derivative means a discontinuity in the acceleration and
therefore in the reaction force. This can cause poor solver performance or even failure to converge at the
point of discontinuity.
The B-spline interpolation method is primarily designed to describe 3D geometric curves. Although the
B-spline can be useful for geometric applications, you should use AKISPL or CUBSPL to construct most
motions, forces, and other such entities.
Where to Find the Spline Functions
The following table lists the names and definitions for the spline functions:

Function: Returns:
Cubic Fitting Method (CUBSPL) Either a derivative of a curve or an interpolated value from a curve
or surface.
B-Spline Fitting Method (CURVE) A B-spline or a user-written curve created by a CURVE data
element.
Akima Fitting Method (AKISPL) Either a derivative of a curve or an interpolated value from a curve
or surface.
INTERP Derivative of the interpolated value of a spline.

Force in Object Functions

Force in object functions are used to return instantaneous force values generated by modeling elements.
The following sections further explain the force in object functions:
• Using the Force in Object Functions
• Constraint Characteristics
• Force Characteristics
• Using a Force in Object Function
• Where to Find the Force in Object Functions

Using the Force in Object Functions

You can use the force in object functions during a simulation to obtain from Adams the force
measurements due to constraints (such as joints and motions), compliant connections (such as spring-
dampers and bushings), and applied forces (such as multiple-component general-equation force
elements). The force in object functions provide measurements that can be useful in:
• Plotting the force measurements.
• Creating equations for other forces whose magnitudes depend on these forces.
 Run-Time Functions 469
About Run-Time Functions

• Monitoring force magnitudes and triggering the occurrence of special events when these forces
reach certain values.
Constraint Characteristics
Most constraints have the following characteristics:
• Connect two bodies, referred to as the first body and second body or the action and reaction body
respectively.
• Are applied at two distinct points, though sometimes coincident.
• Depend on coordinate system axes to define constraint direction.
• Apply whatever forces are required to prevent movement in certain directions.
• Do not require the user to define the magnitudes of the forces they apply since Adams
automatically calculates force magnitudes.
Force Characteristics
Most forces have the following characteristics:
• Are applied to two bodies, referred to as the first body and second body.
• Are applied at two distinct points, though sometimes coincident.
• Depend on coordinate system axes to define force application.
• Require the user to define the magnitudes of the forces they apply.

In Adams, you can define force magnitudes in two ways:

1. With linear spring-damper-like elements that use predefined equations that automatically depend
only on displacement and velocity directly; for these forces you can simply input stiffness and
damping coefficients.
2. With multiple-component, general-equation force elements that have no predefined equations.
These allow you to create your own force magnitude equations with no restrictions on the
dependencies.
When you define your own equations for force magnitudes, you have to tell Adams what the force
depends on. For instance, a force could depend on the displacement between two coordinate system
markers or their relative velocity or acceleration, or the force applied to a coordinate system marker by
a constraint or force element.To help you define these dependencies, Adams offers you displacement
functions (Displacement Functions), velocity functions (Velocity Functions), acceleration functions
(Acceleration Functions), resultant force functions (Resultant Force Functions), as well as force in object
functions.
Whenever you use the force in object functions, you must tell Adams how you want the force to be
measured. You must specify:
• Which force-applying object you want to measure. For example: joint_4, motion_6, sforce_3,
gforce_19, and so on.
• On which body you want to take the measurement, the first body or the second body.
470 Adams/View Function Builder
About Run-Time Functions

• Which force vector component you want to obtain.

Using a Force in Object Function

In this example we'll calculate the force acting on a block located on an incline, as illustrated in body 1.
Before working through this example, reference Six-component Force/Torque (GFORCE).
This example consists of a system defined as follows:
• A translational joint (JOINT_1) connects a block and an incline by way of coordinate system
markers named block.marker_14 and incline.marker_15.
• A fixed joint (JOINT_2) connects the incline to ground by way of incline.marker_32 and
ground.marker_33.
• A general-equation, multiple-component force, named GForce_7 is applied to the block, normal
to the surface of the incline.
• The GForce_7 is applied to block.marker_28 and ground.marker_29, so that the block is the
action body and ground is the reaction body.
• There is no gravity.

In this example, GFORCE is defined as: F = 30ŷ 28 + 40ẑ 28 .

The GFORCE yields different results, as we change the arguments used:
 Run-Time Functions 471
About Run-Time Functions

GFORCE(GForce_7, 0, 2, block.marker_28) = 0
GFORCE(GForce_7, 0, 3, block.marker_28) = 30
GFORCE(GForce_7, 0, 4, block.marker_28) = 40
GFORCE(GForce_7, 0, 1, block.marker_14) = 50
GFORCE(GForce_7, 0, 2, block.marker_14) = - 40
GFORCE(GForce_7, 0, 3, block.marker_14) = 0
GFORCE(GForce_7, 0, 4, block.marker_14) = - 30
GFORCE(GForce_7, 1, 1, block.marker_28) = 50
GFORCE(GForce_7, 1, 2, block.marker_28) = 0
GFORCE(GForce_7, 1, 3, block.marker_28) = - 30
GFORCE(GForce_7, 1, 4, block.marker_28) = - 40
Where to Find the Force in Object Functions
The following table lists the names and definitions for the force in object functions:

Function: Returns:
Joint Force (JOINT) A force or torque induced by a specified joint on one of
the two bodies connected by the joint object.
Motion Force (MOTION) A force or torque component induced by a specified
motion on one of the two bodies affected by the motion
object.
Point-to-Curve Force (PTCV) A force or torque induced by a specified point-to-curve
object on one of the two bodies connected by the point-
to-curve object.
Curve-to-Curve Force (CVCV) A force or torque induced by a specified curve-to-curve
object on one of the two bodies connected by the curve-
to-curve object.
Joint Primitive Force (JPRIM) A force or torque induced by a specified joint primitive
on one of the two bodies connected by the joint primitive.
Single-component Force (SFORCE) A force or torque applied by a specified single-
component force on one or two bodies directly affected
by the single-component force.
Three-component Force (VFORCE) A force or torque applied by a specified three-component
force on one or two bodies directly affected by the three-
component force.
472 Adams/View Function Builder
About Run-Time Functions

Function: Returns:
Three-component Torque (VTORQ) A force or torque applied by a specified three-component
torque on one or two bodies directly affected by the
three-component torque.
Six-component Force/Torque (GFORCE) A force or torque applied by a specified six-component
force/torque on one or two bodies directly affected by the
six-component force / torque.
Multipoint Force (NFORCE) A force or torque applied by a specified multipoint force
on one or two bodies directly affected by the multipoint
force.
Beam Force (BEAM) A force or torque applied by a specified beam force on
one or two bodies directly affected by the beam force.
Bushing Force (BUSH) A force or torque applied by a specified bushing force on
one or two bodies directly affected by the bushing force.
Field Force (FIELD) A force or torque applied by a specified field force on one
or two bodies directly affected by the field force.
Spring-Damper Force (SPDP) A force or torque applied by a specified spring-damper
force on one or two bodies affected by the spring-damper
force.

Resultant Force Functions

Resultant force functions return either the net applied action and reaction force between two markers, or
the net applied action-only forces at a marker.
Where to Find the Resultant Force Functions
The following table lists the names and definitions for the resultant force functions:

Function: Returns:
Sum of Forces Along X (FX) An x component of the net translational force acting at one
coordinate system marker due to all applied forces and constraints
acting between that coordinate system marker and another.
Sum of Forces Along Y (FY) A y component of the net translational force acting at one
coordinate system marker due to all applied forces and constraints
acting between that coordinate system marker and another.
Sum of Forces Along Z (FZ) A z component of the net translational force acting at one
coordinate system marker due to all applied forces and constraints
acting between that coordinate system marker and another.
 Run-Time Functions 473
About Run-Time Functions

Function: Returns:
Sum of Forces Magnitude (FM) The magnitude of the net translational force acting at one
coordinate system marker due to all applied forces and constraints
acting between that coordinate system marker and another.
Sum of Torques About X (TX) An x component of the net torque acting at one coordinate system
marker due to all applied torques and constraints acting between
that coordinate system marker and another.
Sum of Torques About Y (TY) A y component of the net torque acting at one coordinate system
marker due to all applied torques and constraints acting between
that coordinate system marker and another.
Sum of Torques About Z (TZ) A z component of the net torque acting at one coordinate system
marker due to all applied torques and constraints acting between
that coordinate system marker and another.
Sum of Torques Magnitude (TM) The magnitude of the net torque acting at one coordinate system
marker due to all applied torques and constraints acting between
that coordinate system marker and another.

Math Functions
Math functions apply to scalar numbers or matrices. If you input a scalar, Adams returns a scalar. If you
input a matrix, Adams returns a matrix.
Where to Find the Math Functions
The following table lists the names and definitions for the math functions:

Function: Does the following:

ABS Returns the absolute value of an expression that
represents a numerical value.
ACOS Returns the arc cosine of an expression that represents a
numerical value.
AINT Returns the nearest integer whose magnitude is not larger
than the integer value of a specified expression that
represents a numerical value.
ANINT Returns the nearest integer whose magnitude is not larger
than the real value of an expression that represents a
numerical value.
ASIN Returns the arc sine of an expression that represents a
numerical value.
ATAN Returns the arc tangent of an expression that represents a
numerical value.
474 Adams/View Function Builder
About Run-Time Functions

Function: Does the following:

ATAN2 Returns the arc tangent of two expressions each
representing a numerical value.
Chebyshev Polynomial (CHEBY) Evaluates a Chebyshev polynomial at a user-specified
numerical value.
COS Returns the cosine of an expression that represents a
numerical value.
COSH Returns the hyperbolic cosine of an expression that
represents a numerical value.
DIM Returns the positive difference of the instantaneous
values of two expressions, each representing a numerical
value.
EXP Returns the value ex, where x is any expression that
represents a numerical value.
Fourier Cosine Series (FORCOS) Evaluates a Fourier Cosine series at a user-specified
value x.
Fourier Sine Series (FORSIN) Evaluates a Fourier Sine series at a user-specified value
x.
Haversine Step (HAVSIN) Defines a haversine function. HAVSIN is most often
used to represent a smooth transition between two
functions.
Inverse Power Spectral Density (INVPSD) Regenerates a time signal from a power spectral density
description.
LOG Returns the natural logarithm of an expression that
represents a numerical value.
LOG10 Returns log to base 10 of an expression that represents a
numerical value.
MAX Returns the maximum of two expressions that represent
numerical values.
MIN Returns the minimum of two expressions that represent
numerical values.
MOD Returns the remainder when one expression representing
a numerical value is divided by another expression that
represents a numerical value.
Polynomial (POLY) Evaluates a standard polynomial at a user-specified value
x.
SIGN Transfers the sign of one expression representing a
numerical value to the magnitude of another expression
representing a numerical value.
 Run-Time Functions 475
About Run-Time Functions

Function: Does the following:

Simple Harmonic (SHF) Evaluates a simple harmonic function.
SIN Returns the sine of an expression that represents a
numerical value.
SINH Returns the hyperbolic sine of an expression that
represents a numerical value.
SQRT Returns the square root of an expression that represents a
numerical value.
STEP Approximates the Heaviside step function with a cubic
polynomial.
STEP5 Provides approximations to the Heaviside step function
with a quintic polynomial.
SWEEP Returns a constant amplitude sinusoidal function with
linearly increasing frequency.
TAN Returns the tangent of an expression that represents a
numerical value.
TANH Returns the hyperbolic tangent of an expression that
represents a numerical value.

Data Element Access

Data elements give you access to the values of states of generic system modeling entities.
Where to Find Data Elements
The following table lists the names and definitions for the data elements available through the Function
Builder:

Function: Returns:
Algebraic Variable Value (VARVAL) The current value of the variable defined by the specified
state variable modeling entity.
Array Element Value (ARYVAL) The value of the specified element of the specified array
modeling entity.
Differential Variable Integrated Value (DIF) The integrated value of the variable defined by the
specified differential equation modeling entity.
Differential Variable Value (DIF1) The value of the variable defined by the specified
differential equation modeling entity.
Plant Input Value (PINVAL) The run-time value of a plant input.
Plant Output Value (POUVAL) The run-time value of a plant output.
476 Adams/View Function Builder
About Run-Time Functions

User-Written Subroutine Invocation

The user-written subroutine invocation allows for values to be passed into subroutines that you create in
order to define enhanced function expressions. Only certain modeling elements allow you to define them
by way of your own customized subroutines. For more information about subroutines, see the guide,
Using Adams/Solver Subroutines.
Where to Find the User-Written Subroutine
The following table lists the name and definition for the user-written subroutine.

Function: Does the following:

USER Passes one or more values that are used as parameters in a user-written
subroutine.

Constants & Variables

Constants and variables represent values that are frequently used to perform mechanical system
simulation, such as time or conversion functions between angular units of radians and degrees.
Where to Find Constants and Variables
The following table lists the names and definitions for the constants and variables:

Function: Returns:
PI The ratio of the circumference of a circle to its diameter (  ).
RTOD The radians-to-degree units conversion factor (180/  ).
DTOR The degrees-to-radian units conversion factor (  /180).
TIME The current simulation time.
MODE An integer value indicating the current analysis mode.

Run-Time Functions Descriptions

For each function we provide the following:
• Definition - A brief description of the function.
• Format - The function name and format as they appear in the Function Builder.
• Arguments - The arguments used by the function, and a short description of each argument.
• Equation - The mathematical equation relevant to the function.
• Examples - One or more examples of how you can use the function.
 Run-Time Functions 477
About Run-Time Functions

When referring to argument names, we use the following convention:

This notation: Stands for:

T To Marker/Applied To Marker
F From Marker/Applied From Marker
A Along/About Marker
R Reference Frame
G Ground
478 Adams/View Function Builder
Functions: A - M

Functions: A - M
 Run-Time Functions 479
Functions: A - M

ABS
Returns the absolute value of an expression that represents a numerical value.

Format
ABS (x)

Argument

x Any valid expression that evaluates to a real number.

Examples
The following function returns the absolute instantaneous value of the expression (-
10*TIME+15*TIME**2), where TIME is the current simulation time:
ABS(-10*TIME+15*TIME**2)
The following use of the ABS function will prevent instances where the argument of the square root
function becomes negative:
SQRT(ABS(10-DX(marker_T, marker_F, marker_A)))
Learn more about math functions.
480 Adams/View Function Builder
Functions: A - M

Acceleration Along X (ACCX)

Returns an x component of the difference between the acceleration vectors of two coordinate system
markers.

Format
ACCX (To Marker, From Marker, Along Marker, Reference Frame)

Arguments

To Marker (Required) The coordinate system marker whose acceleration is being measured.
From Marker (Optional) The coordinate system marker whose acceleration is subtracted off. If
you don't specify this argument, it defaults to the global origin.
Along Marker (Optional) The coordinate system marker along whose x-axis the acceleration is
measured. If you don't specify this argument, it defaults to the global x-axis.
Reference Frame (Optional) The coordinate system marker in which time-derivatives are
calculated. If you don't specify this argument, it defaults to the ground reference
frame.

Equation
Mathematically, ACCX is calculated as follows:

R 2 R 2
d d
ACCX = RT – R F  x̂ A
d t2 dt2
where:

• RT is the position vector from the global origin to the To Marker, T.

R 2
d
• RT is the second time-derivative of R T with respect to the Reference Frame, R.
dt2

• RF is the position vector from the global origin to the From Marker, F.

R 2
d
• RF is the second time-derivative of R F with respect to the Reference Frame, R.
dt2
• x̂ A is the unit vector along the x-axis of the Along Marker, A.
 Run-Time Functions 481
Functions: A - M

Example
The following function returns the x component of the acceleration vector of marker_T with respect to
marker_F. The vector is expressed in the coordinate system of marker_A. All time-derivatives are taken
in the ground reference frame, since the Reference Frame, R, is not specified.
ACCX(marker_T, marker_F, marker_A)
Learn more about acceleration functions.
482 Adams/View Function Builder
Functions: A - M

Acceleration Along Y (ACCY)

Returns a y component of the difference between the acceleration vectors of two coordinate system
markers.

Format
ACCY (To Marker, From Marker, Along Marker, Reference Frame)

Arguments

To Marker (Required) The coordinate system marker whose acceleration is being measured.
From Marker (Optional) The coordinate system marker whose acceleration is subtracted off. If
you don't specify this argument, it defaults to the global origin.
Along Marker (Optional) The coordinate system marker along whose y-axis the acceleration is
measured. If you don't specify this argument, it defaults to the global y-axis.
Reference Frame (Optional) The coordinate system marker in which time-derivatives are
calculated. If you don't specify this argument, it defaults to the ground reference
frame.

Equation
Mathematically, ACCY is calculated as follows:

R 2 R 2
d d
ACCY = RT – R F  ŷ A
d t2 dt2
where:

• RT is the position vector from the global origin to the To Marker, T.

R 2
d
• RT is the second time-derivative of R T with respect to the Reference Frame, R.
dt2

• RF is the position vector from the global origin to the From Marker, F.

R 2
d
• RF is the second time-derivative of R F with respect to the Reference Frame, R.
dt2
• ŷ A is the unit vector along the y-axis of the Along Marker, A.
 Run-Time Functions 483
Functions: A - M

Example
The following function returns the y component of the acceleration vector of marker_T with respect to
marker_F. The vector is expressed in the coordinate system of marker_A. All time-derivatives are taken
in the ground reference frame, since the Reference Frame, R, is not specified.
ACCY(marker_T, marker_F, marker_A)
Learn more about acceleration functions.
484 Adams/View Function Builder
Functions: A - M

Acceleration Along Z (ACCZ)

Returns a z component of the difference between the acceleration vectors of two coordinate system
markers.

Format
ACCZ (To Marker, From Marker, Along Marker, Reference Frame)

Arguments

To Marker (Required) The coordinate system marker whose acceleration is being measured.
From Marker (Optional) The coordinate system marker whose acceleration is subtracted off. If
you don't specify this argument, it defaults to the global origin.
Along Marker (Optional) The coordinate system marker along whose z-axis the acceleration is
measured. If you don't specify this argument, it defaults to the global z-axis.
Reference Frame (Optional) The coordinate system marker in which time-derivatives are
calculated. If you don't specify this argument, it defaults to the ground reference
frame.

Equation
Mathematically, ACCZ is calculated as follows:

R 2 R 2
d d
ACCZ = RT – R F  ẑ A
d t2 dt2
where:

• RT is the position vector from the global origin to the To Marker, T.

R 2
d
• RT is the second time-derivative of R T with respect to the Reference Frame, R.
dt2

• RF is the position vector from the global origin to the From Marker, F.

R 2
d
• RF is the second time-derivative of R F with respect to the Reference Frame, R.
dt2
• ẑ A is the unit vector along the z-axis of the Along Marker, A.
 Run-Time Functions 485
Functions: A - M

Example
The following function returns the z component of the acceleration vector of marker_T with respect to
marker_F. The vector is expressed in the coordinate system of marker_A. All time-derivatives are taken
in the ground reference frame, since the Reference Frame, R, is not specified.
ACCZ(marker_T, marker_F, marker_A)
Learn more about acceleration functions.
486 Adams/View Function Builder
Functions: A - M

Acceleration Magnitude (ACCM)

Returns the magnitude of the second time-derivative of the displacement vector to one coordinate system
marker from another coordinate system marker.

Format
ACCM (To Marker, From Marker, Reference Frame)

Arguments

To Marker (Required) The coordinate system marker whose acceleration is being measured.
From Marker (Optional) The coordinate system marker whose acceleration is being subtracted
off. If you don't specify this argument, it defaults to the global origin.
Reference Frame (Optional) The coordinate system marker in which time-derivatives are
calculated. If you don't specify this argument, it defaults to the ground reference
frame.

Equation
Mathematically, ACCM is calculated as follows:

R 2 R 2 R 2 R 2

 d d d d
ACCM = RT – R F   RT – R F
 dt2 dt2   d t2 d t2 
where:

• RT is the position vector from the global origin to the To Marker, T.

R 2
d
• RT is the second time-derivative of RT with respect to the Reference Frame, R.
dt 2

• RF is the position vector from the global origin to the From Marker, F.

R 2
d
• RF is the second time-derivative of RF with respect to the Reference Frame, R.
dt2

Example
The following function returns the magnitude of the translational acceleration of marker_T with respect
to marker_F. All vector time-derivatives are taken in the reference frame of marker_R.
 Run-Time Functions 487
Functions: A - M

ACCM(marker_T, marker_F, marker_R)

Learn more about acceleration functions.
488 Adams/View Function Builder
Functions: A - M

AINT
Returns the nearest integer whose magnitude is not larger than the integer value of a specified expression
that represents a numerical value:
AINT(x) = 0 if ABS(x)< 1
AINT(x)= int(x) if ABS(x)> 1
The value of int(x) is equal to x if x is an integer. If x is not an integer, then int(x) is equal to the integer
nearest to x, whose magnitude is not greater than the magnitude of x. Thus,
int(-7.0) = -7, int(-4.8) = -4, and int(4.8) = 4.

Note: AINT is not a differentiable function. Be careful when using this function in an expression
that defines a force or motion input to the system.

Format
AINT (x)

Argument

x Any valid expression that evaluates to a real number.

Examples
The following functions show how AINT truncates results towards 0:

Function AINT(0.85)
Result 0

Function AINT(-0.5)
Result 0

Function AINT(4.6)
Result 4

Function AINT(-6.8)
Result -6

Learn more about math functions.

 Run-Time Functions 489
Functions: A - M

ACOS
Returns the arc cosine of an expression that represents a numerical value. The evaluated expression must
return a value whose absolute value is  1 . The value returned by ACOS lies in the range [0,  ], that
is, 0 < ACOS(x) < .

Format
ACOS (x)

Argument

X Any valid expression that evaluates to a real number.

Example
The following function calculates the angle (in radians) between the line from marker_11 to marker_21
and the line from marker_41 to marker_31:
ACOS((DX(marker_21, marker_11) * DX(marker_31, marker_41) +
DY(marker_21, marker_11) * DY(marker_31, marker_41) +
DZ(marker_21, marker_11) * DZ(marker_31, marker_41))/
(DM(marker_21, marker_11) * DM(marker_31, marker_41))
Learn more about math functions.
490 Adams/View Function Builder
Functions: A - M

Algebraic Variable Value (VARVAL)

Returns the current value of the variable defined by the specified state variable modeling entity.

Format
VARVAL(Algebraic Variable Name)

Argument

Algebraic Variable Name Name of an existing state variable modeling entity; defined by an object
name.

Example
The following example illustrates the use of the VARVAL function:
VARVAL(variable_37)
Learn more about data element access.
 Run-Time Functions 491
Functions: A - M

Akima Fitting Method (AKISPL)

Returns either a derivative of a curve or an interpolated value from a curve or surface. The curve is fit
exactly through a set of discrete data points using an Akima spline fitting method.

Format
AKISPL (First Independent Variable, Second Independent Variable, Spline Name, Derivative Order)

Arguments

First Independent (Required) Real variable that represents the first independent variable in
Variable the spline.
Second Independent (Optional) Real variable that represents the second independent variable
Varialble in the spline.
Spline Name (Required) The name of the existing data element spline modeling
entity that defines the set of discrete data points to be used for the
interpolation.
Derivative Order (Optional) The order of the derivative to be taken at the interpolated
point (integer).

The legal values are:

• 0 - returns the curve coordinate value

• 1 - returns the first derivative
• 2 - returns the second derivative
Note: Derivative Order may not be specified when interpolating on
a surface; that is, when the Second Independent Variable = 0.

Example
A spline, spline_1, is defined with discrete data as shown in the following table. The data is then used to
generate the interpolation function using the Akima spline fitting method. Since the spline defines a curve
rather than a surface, the Second Independent Variable must be set to 0.
In the following example, given the tabular data and a value for the independent variable, the AKISPL
returns the interpolated value for the dependent variable:
f = AKISPL(DX(marker_1, marker_2, marker_2), 0, spline_1)

Independent variable (x): Dependent variable (y):

-4.0 -3.6
-3.0 -2.5
492 Adams/View Function Builder
Functions: A - M

Independent variable (x): Dependent variable (y):

-2.0 -1.2
-1.0 -0.4
0.0 0.0
1 0.4
2 1.2
3 2.5
4 3.6

Spline Defined Based on Tabular Data

Learn more about spline functions.

 Run-Time Functions 493
Functions: A - M

Angle About X (AX)

Returns the rotational displacement (in radians) of one coordinate system marker about the x-axis of
another.

Format
AX (To Marker, From Marker)

Arguments

To Marker (Required) The coordinate system marker whose rotation is being measured.
From Marker (Optional) The coordinate system marker with respect to which the rotation is being
measured. If you don't specify this argument, it defaults to the global coordinate
system.

Equation
Mathematically, AX is calculated as follows:

AX = atan 2  ŷ T  ẑ F ŷ T  ŷ F 
where:

• ŷ T is the y-axis of the To Marker, T.

• ŷ F is the y-axis of the From Marker, F.

• ẑ F is the z-axis of the From Marker, F.

Example
The following function returns the angle between the y-axes of marker_T and marker_F:

Function AX(marker_T, marker_F)

Result 0.5235 or  /6
494 Adams/View Function Builder
Functions: A - M

Learn more about displacement functions.

 Run-Time Functions 495
Functions: A - M

Angle About Y (AY)

Returns the rotational displacement (in radians) of one coordinate system marker about the y-axis of
another.

Format
AY (To Marker, From Marker)

Arguments

To Marker (Required) The coordinate system marker whose rotation is being measured.
From Marker (Optional) The coordinate system marker with respect to which the rotation is
being measured. If not specified, this argument defaults to the global coordinate
system.

Equation
Mathematically, AY is calculated as follows:

AY = atan 2  ẑ T  x̂ F ẑ T  ẑ F 
where:

• ẑ T is the z-axis of To Marker.

• ẑ F is the z-axis of From Marker.

• x̂ F is the x-axis of From Marker.

Example
The following function returns the angle between the x-axes of marker_T and marker_F:

Function AY(marker_T, marker_F)

Result 0.5235 or  /6
496 Adams/View Function Builder
Functions: A - M

Learn more about displacement functions.

 Run-Time Functions 497
Functions: A - M

Angle About Z (AZ)

Returns the rotational displacement (in radians) of one coordinate system marker about the z-axis of
another.

Format
AZ (To Marker, From Marker)

Arguments

To Marker (Required) The coordinate system marker whose rotation is being measured.
From Marker (Optional) The coordinate system marker with respect to which the rotation is being
measured. If not specified, this argument defaults to the global coordinate system.

Equation
Mathematically, AZ is calculated as follows:

AZ = atan 2  x̂ T  ŷ F x̂ T  x̂ F 
where:

• x̂ T is the x-axis of To Marker.

• x̂ F is the x-axis of From Marker.

• ŷ F is the y-axis of From Marker.

Example
The following function returns the angle between the x-axes of marker_T and marker_F:

Function AZ(marker_T, marker_F)

Result 0.6109 or  /5.1428
498 Adams/View Function Builder
Functions: A - M

Learn more about displacement functions.

 Run-Time Functions 499
Functions: A - M

Angular Acceleration About X (WDTX)

Returns an x component of the difference between the angular acceleration vectors of two coordinate
system markers.

Format
WDTX (To Marker, From Marker, About Marker, Reference Frame)

Arguments

To Marker (Required) The coordinate system marker whose angular acceleration is being
measured.
From Marker (Optional) The coordinate system marker whose angular acceleration is
subtracted off. If you don't specify this argument, it defaults to the global origin.
About Marker (Optional) The coordinate system marker about whose x-axis acceleration is
measured. If you don't specify this argument, it defaults to the global coordinate
axis.
Reference Frame (Optional) The coordinate system marker in which time-derivatives are
calculated. If you don't specify this argument, it defaults to the ground reference
frame.

Equation
Mathematically, WDTX is calculated as follows:

R d R d
WDTX = T –  F  x̂ A
dt dt
where:

•  T is the angular velocity vector of the To Marker, T, with respect to the ground reference
frame.
R d
•  T is the time-derivative of  T with respect to the Reference Frame, R.
dt
•  F is the angular velocity vector of the From Marker, F, with respect to the ground reference
frame.
R d
•  F is the time-derivative of  F with respect to the Reference Frame, R.
dt
• x̂ A is the unit vector along the x-axis of the About Marker, A.
500 Adams/View Function Builder
Functions: A - M

Example
The following example returns the x component of the angular acceleration vector of marker_T, with
respect to marker_F, as seen in the global coordinate system of marker_A and measured in the reference
frame of marker_R:
WDTX(marker_T, marker_F, marker_A, marker_R)
Learn more about acceleration functions.
 Run-Time Functions 501
Functions: A - M

Angular Acceleration About Y (WDTY)

Returns a y component of the difference between the angular acceleration vectors of two coordinate
system markers.

Format
WDTY (To Marker, From Marker, About Marker, Reference Frame)

Arguments

To Marker (Required) The coordinate system marker whose angular acceleration is being
measured.
From Marker (Optional) The coordinate system marker whose angular acceleration is
subtracted off. If you don't specify this argument, it defaults to the global origin.
About Marker (Optional) The coordinate system marker about whose x-axis acceleration is
measured. If you don't specify this argument, it defaults to the global coordinate
axis.
Reference Frame (Optional) The coordinate system marker in which time-derivatives are
calculated. If you don't specify this argument, it defaults to the ground reference
frame.

Equation
Mathematically, WDTY is calculated as follows:

R d R d
WDTY = T –  F  ŷ A
dt dt
where:

•  T is the angular velocity vector of the To Marker, T, with respect to the ground reference
frame.
R d
•  T is the time-derivative of  T with respect to the Reference Frame, R.
dt
•  F is the angular velocity vector of the From Marker, F, with respect to the ground reference
frame.
R d
•  F is the time-derivative of  F with respect to the Reference Frame, R.
dt
• ŷ A is the unit vector along the y-axis of the About Marker, A.
502 Adams/View Function Builder
Functions: A - M

Example
The following example returns the y component of the angular acceleration vector of marker_T, with
respect to marker_F, as seen in the global coordinate system of marker_A and measured in the reference
frame of marker_R:
WDTY(marker_T, marker_F, marker_A, marker_R)
Learn more about acceleration functions.
 Run-Time Functions 503
Functions: A - M

Angular Acceleration About Z (WDTZ)

Returns a z component of the difference between the angular acceleration vectors of two coordinate
system markers.

Format
WDTZ (To Marker, From Marker, About Marker, Reference Frame)

Arguments

To Marker (Required) The coordinate system marker whose angular acceleration is being
measured.
From Marker (Optional) The coordinate system marker whose angular acceleration is
subtracted off. If you don't specify this argument, it defaults to the global origin.
About Marker (Optional) The coordinate system marker about whose x-axis acceleration is
measured. If you don't specify this argument, it defaults to the global coordinate
axis.
Reference Frame (Optional) The coordinate system marker in which time-derivatives are
calculated. If you don't specify this argument, it defaults to the ground reference
frame.

Equation
Mathematically, WDTZ is calculated as follows:

R d R d
WDTZ = T –  F  ẑ A
dt dt
where:

•  T is the angular velocity vector of the To Marker, T, with respect to the ground reference
frame.
R d
•  T is the time-derivative of  T with respect to the Reference Frame, R.
dt
•  F is the angular velocity vector of the From Marker, F, with respect to the ground reference
frame.
R d
•  F is the time-derivative of  F with respect to the Reference Frame, R.
dt
• ẑ A is the unit vector along the z-axis of the About Marker, A.
504 Adams/View Function Builder
Functions: A - M

Example
The following example returns the z component of the angular acceleration vector of marker_T, with
respect to marker_F, as seen in the global coordinate system of marker_A and measured in the reference
frame of marker_R:
WDTZ(marker_T, marker_F, marker_A, marker_R)
Learn more about acceleration functions.
 Run-Time Functions 505
Functions: A - M

Angular Acceleration Magnitude (WDTM)

Returns the magnitude of the difference between the angular acceleration vectors of two coordinate
system markers.

Format
WDTM (To Marker, From Marker, Reference Frame)

Arguments

To Marker (Required) The coordinate system marker whose angular acceleration is being
measured.
From Marker (Optional) The coordinate system marker whose angular acceleration is
subtracted off. If you don't specify this argument, it defaults to the global origin.
Reference Frame (Optional) The coordinate system marker in which time-derivatives are
calculated. If you don't specify this argument, it defaults to the ground reference
frame.

Equation
Mathematically, WDTM is calculated as follows:

R d R d R d R d

WDTM =  T –    T –  F
 dt d t F  dt dt
where:

•  T is the angular velocity vector of the To Marker, T, with respect to the ground reference
frame.
R
d
•  is the time-derivative of  T with respect to the Reference Frame, R.
dt T
•  F is the angular velocity vector of the From Marker, F, with respect to the ground reference
frame.
R d
•  F is the time-derivative of  F with respect to the Reference Frame, R.
dt
506 Adams/View Function Builder
Functions: A - M

Example
The following example returns the magnitude of the angular acceleration vector of marker_T, with
respect to marker_F, as seen in the global coordinate system of marker_A and measured in the reference
frame of marker_R:
WDTM(marker_T, marker_F)
Learn more about acceleration functions.
 Run-Time Functions 507
Functions: A - M

Angular Velocity About X (WX)

Returns an x component of the difference between the angular velocity vectors of two coordinate system
markers.

Format
WX (To Marker, From Marker, About Marker)

Arguments

To Marker (Required) The coordinate system marker whose angular velocity is being
measured.
From Marker (Optional) The coordinate system marker whose angular velocity is subtracted off.
If you don't specify this argument, it defaults to the global coordinate system.
About Marker (Optional) The coordinate system marker about whose x-axis the angular velocity
is measured. If you don't specify this argument, it defaults to the global x-axis.

Equation
Mathematically, WX is calculated as follows:

G G
WX =  T – F   x̂ A
where:

G
• T is the angular velocity vector of the To Marker, T, with respect to the ground reference
frame, G.
G
• F is the angular velocity vector of the From Marker, F, with respect to the ground reference
frame, G.

• x̂ A is the unit vector along the x-axis of the About Marker, A.

Example
The following function returns the x component of the angular velocity between marker_T and marker_F,
as measured in the coordinate system of marker_A:
WX(marker_T, marker_F, marker_A)
Learn more about velocity functions.
508 Adams/View Function Builder
Functions: A - M

Angular Velocity About Y (WY)

Returns a y component of the difference between the angular velocity vectors of two coordinate system
markers.

Format
WY (To Marker, From Marker, About Marker)

Arguments

To Marker (Required) The coordinate system marker whose angular velocity is being
measured.
From Marker (Optional) The coordinate system marker whose angular velocity is subtracted
off. If you don't specify this argument, it defaults to the global coordinate
system.
About Marker (Optional) The coordinate system marker about whose y-axis the angular
velocity is measured. If you don't specify this argument, it defaults to the global
y-axis.

Equation
Mathematically, WY is calculated as follows:

G G
WY =  T – F   ŷ A
where:

G
• T is the angular velocity vector of the To Marker, T, with respect to the ground reference
frame, G.
G
• F is the angular velocity vector of the From Marker, F, with respect to the ground reference
frame, G.

• ŷ A is the unit vector along the y-axis of the About Marker, A.

Example
The following function returns the y component of the angular velocity between marker_T and marker_F,
as measured in the coordinate system of marker_A:
WY(marker_T, marker_F, marker_A)
Learn more about velocity functions.
 Run-Time Functions 509
Functions: A - M

Angular Velocity About Z (WZ)

Returns a z component of the difference between the angular velocity vectors of two coordinate system
markers.

Format
WZ (To Marker, From Marker, About Marker)

Arguments

To Marker (Required) The coordinate system marker whose angular velocity is being
measured.
From Marker (Optional) The coordinate system marker whose angular velocity is subtracted
off. If you don't specify this argument, it defaults to the global coordinate system.
About Marker (Optional) The coordinate system marker about whose z-axis the angular velocity
is measured. If you don't specify this argument, it defaults to the global z-axis.

Equation
Mathematically, WZ is calculated as follows:

G G
WZ =  T – F   ẑ A
where:

G
• T is the angular velocity vector of the To Marker, T, with respect to the ground reference
frame, G.
G
• F is the angular velocity vector of the From Marker, F, with respect to the ground reference
frame, G.

• ŷ A is the unit vector along the z-axis of the About Marker, A.

Example
The following function returns the z component of the angular velocity between marker_T and marker_F,
as measured in the coordinate system of marker_A:
WZ(marker_T, marker_F, marker_A)
Learn more about velocity functions.
510 Adams/View Function Builder
Functions: A - M

Angular Velocity Magnitude (WM)

Returns the magnitude of the difference between the angular velocity vectors of two coordinate system
markers.

Format
WM (To Marker, From Marker)

Arguments

To Marker (Required) The coordinate system marker whose angular velocity is being
measured.
From Marker (Optional) The coordinate system marker whose angular velocity is subtracted off.
If not specified, this argument defaults to the global coordinate system.

Equation
Mathematically, WM is calculated as follows:

G G G G

WM =  T – F    T – F 
where:

G
• T is the angular velocity vector of the To Marker, T, with respect to the ground reference
frame, G.
G
• F is the angular velocity vector of the From Marker, F, with respect to the ground reference
frame, G.

Example
The following example returns the magnitude of the angular velocity vector between marker_T and
marker_F:
WM(marker_T, marker_F)
Learn more about velocity functions.
 Run-Time Functions 511
Functions: A - M

ANINT
Returns the nearest integer whose magnitude is not larger than the real value of an expression that
represents a numerical value:
ANINT(x) = INT(x + 0.5) if x > 0
ANINT(x) = INT(x - 0.5) if x < 0
The value of the mathematical function INT of a variable x is equal to x if x is an integer. If x is not an
integer, then INT(x) is equal to the nearest integer to x, whose magnitude is not greater than the
magnitude of x. Thus,
INT(-7.0) = -7, INT(-4.8) = -4, and INT(4.8) = 4.

Format
ANINT (x)

Argument

x Any valid expression that evaluates to a real number.

Examples
The following functions show how ANINT rounds the results to the nearest integer:

Function ANINT(-0.9)
Result -1

Function ANINT(0.33)
Result 0

Function ANINT(-4.6)
Result -5

Function AINT(4.6)
Result 5

Learn more about math functions.

512 Adams/View Function Builder
Functions: A - M

Array Element Value (ARYVAL)

Returns the value of the specified element of the specified array modeling entity.

Format
ARYVAL(Array Name, Element Number)

Arguments

Array Name Name of an existing array modeling entity; defined by an object name.
Element Number The number of the element within the array whose value you want to get.

Example
The following example illustrates the use of the ARYVAL function:
ARYVAL(array_45,3)
Learn more about data element access.
 Run-Time Functions 513
Functions: A - M

ASIN
Returns the arc sine of an expression that represents a numerical value. ASIN is defined only when the
absolute value of the expression is <1 . The range of ASIN is –   2   2 (that is,

–   2  asin   x      2   ).

Format
ASIN(x)

Argument

x Any valid expression that evaluates to a real number.

Example
The following function calculates the value of the expression:
DX(marker_21, marker_11) / DM(marker_21, marker_11)
and then applies the ASIN function to the result and returns its arc sine in radians:
ASIN(DX(marker_21, marker_11) / DM(marker_21, marker_11))
514 Adams/View Function Builder
Functions: A - M

ATAN
Returns the arc tangent of an expression that represents a numerical value. The range of ATAN is [-90o,
90o] (that is, -90o < ATAN(x) < 90o).

Format
ATAN(x)

Argument

x Any valid expression that evaluates to a real number.

Examples
The arc tangent (in radians) of the expression a/b where a is the x component of the distance between
marker_2 and marker_3 and b is the y component of the distance between marker_2 and marker_3.
ATAN(DX(marker_2, marker_3)/ DY(marker_2, marker_3))
The figure below shows angle (in radians) between the line joining marker_3 and marker_4 and the
global x-axis:
ATAN(DY(marker_4, marker_3)/ DX(marker_4, marker_3))

Learn more about math functions.

 Run-Time Functions 515
Functions: A - M

ATAN2
Returns the arc tangent of two expressions, each representing a numerical value. x1 and x2 themselves
may be expressions.
< ATAN2(x1, x2) <
ATAN2(x1, x2) > 0 if x1 > 0
ATAN2(x1, x2) = 0 if x1 = 0, x2 > 0
ATAN2(x1, x2) = if x1 = 0, x2 < 0
ATAN2(x1, x2) < 0 if x1 < 0
ABS(ATAN2(x1, x2))= if x2 = 0
ATAN2(x1, x2) undefined if x1 = 0, and x2 = 0

Format
ATAN2(x1, x2)

Arguments

x1 Any valid expression that evaluates to a real number.

x2 Any valid expression that evaluates to a real number.

Example
The following function shows arc tangent (in radians) of the expression a/b where a is the x component
of the distance between marker_2 and marker_3 and b is the y component of the distance between
marker_2 and marker_3:
ATAN2(DX(marker_2, marker_3), DY(marker_2, marker_3))
Learn more about math functions.
516 Adams/View Function Builder
Functions: A - M

B-Spline Fitting Method (CURVE)

Returns a B-spline or a user-written curve created by a CURVE data element.

Format
CURVE (Independent Variable, Derivative Order, Direction, Curve Name)

Arguments

Independent Variable Real variable that represents the independent variable at which the curve will
be evaluated (function).

If the curve is a B-spline, the Independent Variable must be in the range: -

1 Independent Variable 1. If the curve is user-written (computed by a
CURSUB), the Independent Variable must be in the range: Min_Parameter
Independent Variable Max_Parameter where Min_Parameter and
Max_Parameter are specified on the CURVE data element.
Derivative Order Order of the derivative that you want returned from the curve.

The legal values are:

• 0 - returns the curve coordinate value

• 1 - returns the first derivative
• 2 - returns the second derivative
Direction Direction in which you want the curve evaluated.

The legal values are:

• 1 - returns the x coordinate or derivative

• 2 - returns the y coordinate or derivative
• 3 - returns the z coordinate or derivative
Curve Name Name of the curve to reference (curve object).

Example
The following function returns the x direction evaluated value of curve_1 at point TIME, where TIME is
the current simulation time:
CURVE(TIME, 0, 1, curve_1)
Learn more about spline functions.
 Run-Time Functions 517
Functions: A - M

B313 Sequence: 1st Rotation (PSI)

Returns the first angle of rotation (in radians) associated with a body-fixed 313 rotation sequence from
one coordinate system marker to another. This first rotation is referred to as the psi,  , angle, and is used
in association with the theta,  , (2nd rotation) and phi,  , (3rd rotation) angles.
Positive angular displacement is determined by the right-hand rule.

Format
PSI (To Marker, From Marker)

Arguments

To Marker (Required) The coordinate system marker whose rotation is being measured.
From Marker (Optional) The coordinate system marker with respect to which the rotation is
being measured. If you don't specify this argument, it defaults to the global
coordinate system.

Example
The following example returns all the angles of rotation associated with a body-fixed 313 rotation
sequence:
518 Adams/View Function Builder
Functions: A - M
 Run-Time Functions 519
Functions: A - M

There are always at least two equivalent sets of rotation angles that yield the same final orientation. Using
the above example, the same final orientation is achieved by using either of the following sets of rotation
angles:

PSI (marker_T, marker_F) = +90o -90o

THETA (marker_T, marker_F) = -90o or +90o
PHI (marker_T, marker_F) = +90o -90o

Learn more about displacement functions.

520 Adams/View Function Builder
Functions: A - M

B313 Sequence: 3rd Rotation (PHI)

Returns the third angle of rotation (in radians) associated with a Body 313 rotation sequence from one
coordinate system marker to another. This third rotation is referred to as the phi,  , angle, and is

used in association with the psi,  , (1st rotation) and theta,  , (2nd rotation) angles.

Positive angular displacement is determined by the right-hand rule.

Format
PHI (To Marker, From Marker)

Arguments

To Marker (Required) The coordinate system marker whose rotation is being measured.
From Marker (Optional) The coordinate system marker with respect to which the rotation is
being measured. If not specified, this argument defaults to the global coordinate
system.

Example
The following example illustrates the use of the PHI function:
PHI(marker_T, marker_F)
See the illustration for B313 Sequence: 1st Rotation (PSI).
Learn more about displacement functions.
 Run-Time Functions 521
Functions: A - M

B313 Sequence: 2nd Rotation (THETA)

Returns the second angle of rotation (in radians) associated with a Body 313 rotation sequence from one

coordinate system marker to another. This second rotation is referred to as the theta,  , angle, and

is used in association with the psi,  , (1st rotation) and phi,  , (3rd rotation) angles.

Positive angular displacement is determined by the right-hand rule.

Format
THETA (To Marker, From Marker)

Arguments

To Marker (Required) The coordinate system marker whose rotation is being measured.
From Marker (Optional) The coordinate system marker with respect to which the rotation is
being measured. If not specified, this argument defaults to the global coordinate
system.

Example
The following example illustrates the use of the THETA function:
THETA(marker_T, marker_F)
See the illustration for B313 Sequence: 1st Rotation (PSI).
Learn more about displacement functions.
522 Adams/View Function Builder
Functions: A - M

B321 Sequence: 1st Rotation (YAW)

Returns the first angle of rotation (in radians) associated with a body-fixed 321 rotation sequence from
one coordinate system marker to another. This angle is referred to as the yaw angle, and is used in
association with the pitch (2nd rotation) and roll (3rd rotation) angles.
Positive angular displacement is determined by the right-hand rule.

Format
YAW (To Marker, From Marker)

Arguments

To Marker (Required) The coordinate system marker whose rotation is being measured.
From Marker (Optional) The coordinate system marker with respect to which the rotation is
being measured. If you don't specify this argument, it defaults to the global
coordinate system.

Example
The following example returns all the angles of rotation associated with a body-fixed 321 rotation
sequence:
 Run-Time Functions 523
Functions: A - M

There are always at least two equivalent sets of rotation angles that yield the same final orientation. Using
the above example, the same final orientation can be achieved by using any of the following sets of
rotation angles.
524 Adams/View Function Builder
Functions: A - M

Learn more about displacement functions

 Run-Time Functions 525
Functions: A - M

B321 Sequence: 2nd Rotation (PITCH)

Returns the negative of the second angle of rotation (in radians) associated with a body-fixed 321 rotation
sequence from one coordinate system marker to another. This angle is referred to as the pitch angle, and
is used in association with the yaw (1st rotation) and roll (3rd rotation) angles.
\

Note: Opposite from convention, this function calculates the negative of the second body-fixed
321 angle.

Format
PITCH (To Marker, From Marker)

Arguments

To Marker (Required) The coordinate system marker whose rotation is being measured.
From Marker (Optional) The coordinate system marker with respect to which the rotation is
being measured. If not specified, this argument defaults to the global coordinate
system.

Example
The following example illustrates the use of the PITCH function:
PITCH(marker_T, marker_F)
See the illustration for B321 Sequence: 1st Rotation (YAW).
Learn more about displacement functions.
526 Adams/View Function Builder
Functions: A - M

B321 Sequence: 3rd Rotation (ROLL)

Returns the third angle of rotation (in radians) associated with a Body 321 rotation sequence from one
coordinate system marker to another. This angle is referred to as the roll angle, and is used in association
with the yaw (1st rotation) and pitch (2nd rotation) angles.
Positive angular displacement is determined by the right-hand rule.

Format
ROLL (To Marker, From Marker)

Arguments

To Marker (Required) The coordinate system marker whose rotation is being measured.
From Marker (Optional) The coordinate system marker with respect to which the rotation is
being measured. If not specified, this argument defaults to the global coordinate
system.

Example
The following example illustrates the use of the ROLL function:
ROLL(marker_T, marker_F)
See the illustration for B321 Sequence: 1st Rotation (YAW).
Learn more about displacement functions.
 Run-Time Functions 527
Functions: A - M

Beam Force (BEAM)

Returns a force or torque applied by a specified beam force on one or two bodies directly affected by the
beam force.

Format
BEAM (Beam Force Name, On This Body, Force Component, Along/About Axes)

Arguments

Beam Force Name (Required) Beam force for which the force is measured.
On This Body (Required) Body on which the force is measured.

The legal values are:

• 0 = forces and torques on the first body, at the I marker

• 1 = forces and torques on the second body, at the J marker
Force Component (Required) Force or torque component you want to measure.

The legal values are:

• Fm = 1 = force magnitude
• Fx = 2 = x component of the force
• Fy = 3 = y component of the force
• Fz = 4 = z component of the force
• Tm = 5 = torque magnitude
• Tx = 6 = x component of the torque
• Ty = 7 = y component of the torque
• Tz = 8 = z component of the torque
Along/About Axes (Optional) Coordinate system marker in which the results are measured.

To have your results measured in the global coordinate system, do one of

the following:

• If you're entering your function through the Assist dialog box,

leave the Along/About Axes text box empty.
• If you're entering your function directly in the function text box,
enter a 0.
528 Adams/View Function Builder
Functions: A - M

Example
The following function returns the z component of the force vector acting on the first body (at the I
marker) of .model_2.beam_1, measured along the z-axis of the global coordinate system:
BEAM(.model_2.beam_1, 0, 4, 0)
Learn more about force in object functions.
 Run-Time Functions 529
Functions: A - M

Bushing Force (BUSH)

Returns a force or torque applied by a specified bushing force on one or two bodies directly affected by
the bushing force.

Format
BUSH (Bushing Force Name, On This Body, Force Component, Along/About Axes)

Arguments

Bushing Force Name (Required) Bushing force for which the force is measured.
On This Body (Required) Body on which the force is measured.

The legal values are:

• 0 = forces and torques on the first body, at the I marker

• 1 = forces and torques on the second body, at the J marker
Force Component (Required) Force or torque component you want to measure.

The legal values are:

• Fm = 1 = force magnitude
• Fx = 2 = x component of the force
• Fy = 3 = y component of the force
• Fz = 4 = z component of the force
• Tm = 5 = torque magnitude
• Tx = 6 = x component of the torque
• Ty = 7 = y component of the torque
• Tz = 8 = z component of the torque
Along/About Axes (Optional) Coordinate system marker in which the results are measured.

To have your results measured in the global coordinate system, do one of

the following:

• If you're entering your function through the Assist dialog box,

leave the Along/About Axes text box empty.
• If you're entering your function directly in the function text box,
enter a 0.
530 Adams/View Function Builder
Functions: A - M

Example
The following function returns the y component of the torque vector acting on the first body (at the I
marker) of .model_2.bushing_1, measured along the y-axis of the global coordinate system:
BUSH(.model_2.bushing_1, 0, 7, 0)
Learn more about force in object functions.
 Run-Time Functions 531
Functions: A - M

Chebyshev Polynomial (CHEBY)

Evaluates a Chebyshev polynomial at a user-specified numerical value.

Format
CHEBY (x, Shift, Coefficients)

Arguments

x Real variable that specifies the independent variable.

Shift Real variable that specifies a shift in the Chebyshev polynomial.
Coefficients Real variables that define as many as thirty-one coefficients for the Chebyshev
polynomial.

Example
The following example illustrates the use of the CHEBY function:
CHEBY(TIME, 1, 1, 0, -1)
The above function defines the following quadratic Chebyshev polynomial (where TIME is the current
simulation time):
CHEBY = 1 + 0 * (TIME-1) - 1 * [2 (TIME-1)2 - 1]
= -2*TIME2 + 4*TIME
Learn more about math functions.
532 Adams/View Function Builder
Functions: A - M

CONTACT
The CONTACT function returns the component comp of the force in CONTACT/id in the coordinate
system of marker rm. If jflag is set to zero, Adams/Solver (FORTRAN) returns the value of the
force/torque that acts on the I marker of CONTACT. If jflag is set to 1, Adams/Solver (FORTRAN)
returns the value that acts on the J marker. To obtain results in the global coordinate system, you can
specify rm as zero.

Format
CONTACT (id, jflag, comp, rm)

Arguments

id An integer specifying the identification number of the CONTACT.

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

• 0 = forces and moments at the I marker

• 1 = forces and moment at the J marker
comp An integer value that specifies the component of the CONTACT to be returned.

• 1 - magnitude of the force applied by all incidents of contact id

• 2 - x-component of the force applied by all incidents of contact id
• 3 - y-component of the force applied by all incidents of contact id
• 4 - z-component of the force applied by all incidents of contact id
• 5 - magnitude of the torque applied by all incidents of contact id
• 6 - x-component of the torque applied by all incidents of contact id
• 7 - y-component of the torque applied by all incidents of contact id
• 8 - z-component of the torque applied by all incidents of contact id
rm The coordinate system in which the results are expressed. To return the results in the
global coordinate system, set rm = 0.

Examples
REQUEST/1
, F2= CONTACT(11,0,2,0)\
, F3= CONTACT(11,0,3,0)\
, F4= CONTACT(11,0,4,0)\
, F6= CONTACT(11,0,6,0)\
, F7= CONTACT(11,0,7,0)\
, F8= CONTACT(11,0,8,0)
 Run-Time Functions 533
Functions: A - M

This REQUEST statement outputs the x-, y- and z-components of the force and torque at the I marker of
CONTACT/11. Since rm is specified as zero, all vectors are expressed in the global coordinate system.
534 Adams/View Function Builder
Functions: A - M

COS
Returns the cosine of an expression that represents a numerical value.

Format
COS (x)

Argument

x Any valid expression that evaluates to a real number.

Example

The following function returns the cosine of 2*  *TIME, where TIME is the current simulation time:
COS(2*  *TIME)
Learn more about math functions.
 Run-Time Functions 535
Functions: A - M

COSH
Returns the hyperbolic cosine of an expression that represents a numerical value.
COSH(x) = (ex + e-x)/2.0

Format
COSH(x)

Argument

x Any valid expression that evaluates to a real number.

Example
The following function returns the hyperbolic cosine of the z component of the displacement of marker_2
with respect to marker_1. The result is computed in the coordinate system of marker_1.
COSH(DZ(marker_2, marker_1, marker_1))
Learn more about math functions.
536 Adams/View Function Builder
Functions: A - M

Cubic Fitting Method (CUBSPL)

Returns either a derivative of a curve or an interpolated value from a curve or surface. The curve is fit
exactly through a set of discrete data points using a standard cubic spline fitting method.

Format
CUBSPL (First Independent Variable, Second Independent Variable, Spline Name, Derivative Order)

Arguments

First Independent Variable (Required) A real variable that represents the first independent
variable of the spline.
Second Independent Variable (Optional) A real variable that represents the second independent
variable of the spline.
Spline Name (Required) The name of the existing data element spline modeling
entity that defines the set of discrete data points to be used for the
interpolation.
Derivative Order (Optional) The order of the derivative to be taken at the interpolated
point (integer).

The legal values are:

• 0 - returns the curve coordinate value

• 1 - returns the first derivative
• 2 - returns the second derivative
Note: Derivative Order may not be specified when interpolating
on a surface; that is, when the Second Independent
Variable  0.

Example
A spline, spline_1, is defined with discrete data as shown in the following table. The data is then used to
generate the interpolation function using the Cubic spline fitting method. Since the spline defines a curve
rather than a surface, the Second Independent Variable must be set to 0.
The following example returns the interpolated value of the spline of displacement over time, to define
a motion function:
 Run-Time Functions 537
Functions: A - M

Motion = CUBSPL(TIME, 0, spline_1)

Independent variable (Time) Dependent variable (Displacement)

0 100
1 125
2 130
3 80
4 40
5 20

Spline Defined Based on Tabular Data

Learn more about spline functions.

538 Adams/View Function Builder
Functions: A - M

Curve-to-Curve Force (CVCV)

Returns a force or torque induced by a specified curve-to-curve object on one of the two bodies connected
by the curve-to-curve object.

Note: CVCV can only be used for output purposes. Therefore, it can be used only with output
request and sensor objects.

Format
CVCV (Curve-to-curve Name, On This Body, Force Component, Along/About Axes)

Arguments

Curve-to-curve Name (Required) Curve-to-curve for which the force is measured.

On This Body (Required) Body on which the force is measured.

The legal values are:

• 0 = forces and torques on the first body, at the I marker

• 1 = forces and torques on the second body, at the J marker
 Run-Time Functions 539
Functions: A - M

Force Component (Required) Force or torque component you want to measure.

The legal values are:

• Fm = 1 = force magnitude
• Fx = 2 = x component of the force
• Fy = 3 = y component of the force
• Fz = 4 = z component of the force
• Tm = 5 = torque magnitude
• Tx = 6 = x component of the torque
• Ty = 7 = y component of the torque
• Tz = 8 = z component of the torque
Along/About Axes (Optional) Coordinate system marker in which the results are measured.

To have your results measured in the global coordinate system, do one of the
following:

• If you're entering your function through the Assist dialog box, leave
the Along/About Axes text box empty.
• If you're entering your function directly in the function text box, enter
a 0.

Example
The following function returns the y component of the force vector acting on the first body (at the I
marker) of .model_1.cvcv_31, measured along the y-axis of the global coordinate system:
CVCV(.model_1.cvcv_31, 0, 3, 0)
Learn more about force in object functions.
540 Adams/View Function Builder
Functions: A - M

DELAY
The DELAY function returns the value of an expression at a delayed time.
The DELAY function is useful to define Delay Differential Equations (DDE) or Delay Differential-
Algebraic Equations (DDAE) of the retarded type (when delays are positive). Neither DDE nor DDAE
of the advance type (negative delays) are supported. The DELAY function can be used in MOTION and
GCON definitions (possibly involving neutral type of DDE or DDAE).
During linearization the DELAY function is approximated by a first order polynomial equivalent to an
order 1 Padé approximant.
The user does not require to specify a buffer size. Adams/Solver (C++) will manage a variable-size buffer
automatically.

Format
DELAY (Delayed_Expression, Delay_Magnitude, Initial_Expression_Value, Delay_Logic_Array)

Arguments

Delayed_Expression Adams expression to be delayed.

Delay_Magnitude Adams expression defining the magnitude of the delay. The delay can be
constant or state dependent. The magnitude of the delay must be positive.
Negative values will be taken as zero.
Initial_Expression_Value Initial history of the expression; the history must provide for the values
of 'e_delayed' for the values of time less than zero (t<0). The history must
be a function of TIME or a constant.
Delay_Logic_Array ADAMS-ID of the Delay_Logic_Array or default 0 should be passed as
the parameter

The equations:

x' 1  t  = 5x 2  t –  
x' 2  t  = 3x 1  t x 2  t –  
 = x 1 – 3x 2  0
x 2  t  = 0.95 t  0
could be modeled in Adams as follows:
DIF/1, FU=5*DELAY(DIF(2), DIF(1)-3*DIF(2), 0.95))
DIF/2, FU=3*DIF(1)*DELAY(DIF(2), DIF(1)-3*DIF(2), 0.95)
or
 Run-Time Functions 541
Functions: A - M

VARIABLE/1, FU=DELAY(DIF(2), DIF(1)-3*DIF(2), 0.95)

DIF/1, FU=5*VARVAL(1)
DIF/2, FU=3*DIF(1)*VARVAL(1)
Notice that the integrator will take care of using zero for the delay when the expression for the delay
is negative.

Example:
part create equation differential_equation differential_equation_name
= DIFF1 initial_condition = 1 function = (DELAY(DIFF1, 1,1,777)
Learn more about Constants & Variables.
542 Adams/View Function Builder
Functions: A - M

Differential Variable Integrated Value (DIF)

Returns the integrated value of the variable defined by the specified differential equation modeling entity.

Format
DIF(Differential Variable Name)

Argument

Differential Variable Name Name of an existing differential equation modeling entity; defined by
an object name.

Example
The following example illustrates the use of the DIF function:
DIF(diffeq_6)
Learn more about data element access.
 Run-Time Functions 543
Functions: A - M

Differential Variable Value (DIF1)

Returns the value of the variable defined by the specified differential equation modeling entity.

Format
DIF1(Differential Variable Name)

Argument

Differential Variable Name Name of an existing differential equation modeling entity; defined by
an object name.

Example
The following example illustrates the use of the DIF1 function:
DIF1(.diffeq_4)
Learn more about data element access.
544 Adams/View Function Builder
Functions: A - M

DIM
Returns the positive difference of the instantaneous values of two expressions, each representing a
numerical value.
DIM(x1, x2) = 0 if x1  x2
DIM(x1, x2) = x1-x2 if x1 > x2

Note: DIM is a discontinuous function and must be used with caution.

Format
DIM(x1,x2)

Arguments

x1 Any valid expression that evaluates to a real number.

x2 Any valid expression that evaluates to a real number.

Example

The following function returns 0 as long as TIME  5 , and TIME - 5 for TIME > 5. TIME is the
current simulation time.
DIM(TIME,5)
Learn more about math functions.
 Run-Time Functions 545
Functions: A - M

Distance Along X (DX)

Returns an x component of the translational displacement vector from one coordinate system marker to
another.

Format
DX (To Marker, From Marker, Along Marker)

Arguments

To Marker (Required) Coordinate system marker to which the distance is measured.

From Marker (Optional) Coordinate system marker from which the distance is measured.
Along Marker (Optional) Coordinate system marker along whose x-axis the distance is measured.
Note: If not specified, optional arguments default to global coordinate system.

Equation
Mathematically, DX is calculated as follows:

DX =  R T – R F   x̂ A

where:

• R T is the position vector from the global origin to the To Marker, T.

• R F is the position vector from the global origin to the From Marker, F.

• x̂ A is the unit vector along the x-axis of the Along Marker, A.

Example
The following function returns the x component of the displacement vector from marker_F to marker_T,
along the x-axis of marker_A:

Function DX(marker_T, marker_F, marker_A)

Result 12
546 Adams/View Function Builder
Functions: A - M

Learn more about displacement functions.

 Run-Time Functions 547
Functions: A - M

Distance Along Y (DY)

Returns a y component of the translational displacement vector from one coordinate system marker to
another.

Format
DY (To Marker, From Marker, Along Marker)

Arguments

To Marker (Required) Coordinate system marker to which the distance is measured.

From Marker (Optional) Coordinate system marker from which the distance is measured.
Along Marker (Optional) Coordinate system marker along whose y-axis the distance is
measured.
Note: If not specified, optional arguments default to global coordinate system.

Equation
Mathematically, DY is calculated as follows:

DY =  R T – R F   ŷ A

where:

• RT is the position vector from the global origin to the To Marker, T.

• RF is the position vector from the global origin to the From Marker, F.

• ŷ A is the unit vector along the y-axis of the Along Marker, A.

Example
The following function returns the y component of the displacement vector from marker_F to marker_T,
along the y-axis of marker_A:

Function DY(marker_T, marker_F, marker_A)

Result -5
548 Adams/View Function Builder
Functions: A - M

Learn more about displacement functions.

 Run-Time Functions 549
Functions: A - M

Distance Along Z (DZ)

Returns a z component of the translational displacement vector from one coordinate system marker to
another.

Format
DZ (To Marker, From Marker, Along Marker)

Arguments

To Marker (Required) Coordinate system marker to which the distance is measured.

From Marker (Optional) Coordinate system marker from which the distance is measured.
Along Marker (Optional) Coordinate system marker along whose z-axis the distance is
measured.
Note: If not specified, optional arguments default to global coordinate system.

Equation
Mathematically, DZ is calculated as follows:

DZ =  R T – R F   ẑ A
where:

• R T is the position vector from the global origin to the To Marker, T.

• R F is the position vector from the global origin to the From Marker, F.
• ẑ A is the unit vector along the z-axis of Along Marker, A.

Example
The following function returns the z component of the displacement vector from marker_F to marker_T,
along the z-axis of marker_A:

Function DZ(marker_T, marker_F, marker_A)

Result 0
550 Adams/View Function Builder
Functions: A - M

Learn more about displacement functions.

 Run-Time Functions 551
Functions: A - M

Distance Magnitude (DM)

Returns the magnitude of the translational displacement vector from one coordinate system marker to
another.

Format
DM (To Marker, From Marker)

Arguments

To Marker (Required) Coordinate system marker to which the distance is measured.

From Marker (Optional) Coordinate system marker from which the distance is measured. If not
specified, this argument defaults to the global coordinate system.

Equation
Mathematically, DM is calculated as follows:

DM =  RT – RF    RT – RF 
where:

• R T is the position vector from the global origin to the To Marker, T.

• R F is the position vector from the global origin to the From Marker, F.

Example
The following function returns a number greater than or equal to 0:

Function DM(marker_T, marker_F)

Result 13
552 Adams/View Function Builder
Functions: A - M

Learn more about displacement functions.

 Run-Time Functions 553
Functions: A - M

DTOR
Returns the degrees-to-radian units conversion factor (  /180), same as (PI/180).

Format
DTOR

Argument
None

Example
The following example represents a value of 30 degrees in units of radians:
30d*DTOR or (30 *PI/180)
Learn more about Constants and Variables.
554 Adams/View Function Builder
Functions: A - M

EXP
Returns the value ex, where x is any expression that represents a numerical value.

Format
EXP(x)

Argument

x Any valid expression that evaluates to a real number.

Example
The following function returns e2*TIME, where TIME is the current simulation time:
EXP(2*TIME)
Learn more about math functions.
 Run-Time Functions 555
Functions: A - M

Field Force (FIELD)

Returns a force or torque applied by a specified field force on one or two bodies directly affected by the
field force.

Format
FIELD (Field Force Name, On This Body, Force Component, Along/About Axes)

Arguments

Field Force Name (Required) Field force for which the force is measured.
On This Body (Required) Body on which the force is measured.

The legal values are:

• 0 = forces and torques on the first body, at the I marker

• 1 = forces and torques on the second body, at the J marker
Force Component (Required) Force or torque component you want to measure.

The legal values are:

• Fm = 1 = force magnitude
• Fx = 2 = x component of the force
• Fy = 3 = y component of the force
• Fz = 4 = z component of the force
• Tm = 5 = torque magnitude
• Tx = 6 = x component of the torque
• Ty = 7 = y component of the torque
• Tz = 8 = z component of the torque
Along/About Axes (Optional) Coordinate system marker in which the results are measured.

To have your results measured in the global coordinate system, do one of the
following:

• If you're entering your function through the Assist dialog box, leave the
Along/About Axes text box empty.
• If you're entering your function directly in the function text box, enter a
0.
556 Adams/View Function Builder
Functions: A - M

Example
The following function returns the magnitude of the torque acting on the second body (at the J marker)
of .model_1.field_11, measured in the global coordinate system:
FIELD(.model_1.field_11, 1, 5, 0)
Learn more about force in object functions.
 Run-Time Functions 557
Functions: A - M

Fourier Cosine Series (FORCOS)

Evaluates a Fourier Cosine series at a user-specified value x.

Format
FORCOS (x, Shift, Frequency, Coefficients)

Arguments

x Real variable that specifies the independent variable.

Shift Real variable that specifies a shift in the Fourier Cosine series.
Frequency Real variable that specifies the fundamental frequency of the series. Adams assumes
that  is in radians per unit of the independent variable unless you use a D after the
value for degrees.
Coefficients Real variables that define as many as thirty-one coefficients for the Fourier Cosine
series.

Example
The following function defines a Fourier Cosine, which is a harmonic function of time with no shift, and
a fundamental frequency of 1 cycle (360 degrees) per time unit:
COS(TIME, 0, 360D, 1, 2, 3, 4)
The function defined is as follows:
FORCOS = 1 + 2*COS(360D*TIME)+
3*COS(2*360D*TIME)+
4*COS(3*360D*TIME)
TIME is the current simulation time.
Learn more about math functions.
558 Adams/View Function Builder
Functions: A - M

Fourier Sine Series (FORSIN)

Evaluates a Fourier Sine series at a user-specified value x.

Format
FORSIN (x, Shift, Frequency, Coefficients)

Arguments

x Real variable that specifies the independent variable.

Shift Real variable that specifies a shift in the Fourier Sine series.
Frequency Real variable that specifies the fundamental frequency of the series. Assume that 
is in radians per unit of the independent variable unless you use a D after the value
for degrees.
Coefficients The real variables that define as many as thirty-one coefficients for the Fourier Sine
series.

Example
The following function defines a Fourier Sine, which is a harmonic function of TIME with a -0.25 shift,
and a fundamental frequency of 0.5 cycle (  radians) per time unit:

FORSIN(TIME,-0.25, PI, 0, 1, 2, 3)
The function defined is as follows:
FORSIN = 0 + SIN(  *(TIME + 0.25))
+ 2*SIN(2  *(TIME + 0.25))
+ 3*SIN(3  *(TIME + 0.25))
TIME is the current simulation time.
Learn more about math functions.
 Run-Time Functions 559
Functions: A - M

Haversine Step (HAVSIN)

Defines a haversine function. HAVSIN is most often used to represent a smooth transition between two
functions.

Note: The HAVSIN function behavior is similar to the behavior of the STEP functions. HAVSIN
is much smoother than either of these functions. The smoothness, however, causes its
derivatives to be slightly larger than that of STEP

The following plot shows a comparison between HAVSIN and STEP, STEP5, and TANH.

Format
HAVSIN (x, Begin At, End At, Initial Function Value, Final Function Value)

Arguments

x Real variable that specifies the independent variable.

Begin At Real variable that specifies the x value at which the haversine function
begins.
560 Adams/View Function Builder
Functions: A - M

End At Real variable that specifies the x value at which the haversine function
ends.
Initial Function Value Initial value of the haversine function.
Final Function Value Final value of the haversine function.

Example
The following function defines a smooth step function from time 1 to time 2 with a displacement from 0
to 1:
HAVSIN(TIME, 1, 0, 2, 1)

Learn more about math functions.

 Run-Time Functions 561
Functions: A - M

IF
Allows you to conditionally define a function expression.

Note: Using the IF function will likely cause discontinuities in the derivatives of the function
evaluation, which can cause the integrator to decrease the time step size or fail. We
recommend that you use the STEP function instead of the IF.

Format
IF(Expression1: Expression2, Expression3, Expression4)

Arguments

Expression1 The expression Adams evaluates.

Expression2 If the value of Expression1 is less than 0, IF returns Expression2.
Expression3 If the value of Expression1 is 0, IF returns Expression3.
Expression4 If the value of Expression1 is greater than 0, IF returns
Expression4.

Example
In the following illustration, the expression returns different values depending on the value of the variable
called time:

Function IF(time-2.5:0,0.5,1)
Result 0.0 if time < 2.5

0.5 if time = 2.5

1.0 if time > 2.5

562 Adams/View Function Builder
Functions: A - M

Learn more about constants and variables.

 Run-Time Functions 563
Functions: A - M

Inverse Power Spectral Density (INVPSD)

Regenerates a time signal from a power spectral density description.

Format
INVPSD (Independent Variable, Spline Name, Min Frequency, Max Frequency, Num Frequencies, Use
Logarithmic, Random Number Seed)

Arguments

Independent Variable or x Independent variable

Spline Name Name of the spline containing the PSD data versus frequency.
Min Frequency or f0 Real variable that specifies the lowest frequency to be regenerated.
Max Frequency or f1 Real variable that specifies the highest frequency to be regenerated.
Num Frequencies or nf Real variable that specifies the number of frequencies. This number
is supposed to be larger than 1 and less than 200.
Use Logarithmic or linlog Real variable that acts as a flag indicating whether the PSD data
points are interpolated in the linear or logarithmic domain.

The legal values are:

• yes (0) - linear domain

• no (1) - logarithmic domain
Random Number Seed or Seed Real variable that specifies a seed for a random number generator,
used to calculate the phase shifts. During a simulation, PSD can be
called with up to a maximum of 20 different seeds.

Equation
Mathematically, INVPSD is calculated as follows:

nf

INVPSD =   Ai  sin  2fi  x + i  

i=1

The regenerated signal consists of a series of sinusoidal functions where the amplitudes, Ai, are
determined in such a way that the effective value for the PSD and the time signal are the same. The phase
angle,  i  0   i  2  , is calculated by a pseudo-random number generator.
Using the same seed value will always result in the same set of phase angles.
564 Adams/View Function Builder
Functions: A - M

Example
For the power spectral density data shown in Figure 1, INVPSD(TIME, spline_1, 1, 10, 20, 0, 0)
regenerates the time signal shown in Figure 2.
Figure 1. PSD vs. Frequency in Log-Log Scale

Figure 2. Regenerated Time Signal

Learn more about math functions.

 Run-Time Functions 565
Functions: A - M

INTERP
The INTERP function returns the iord derivative of the interpolated value of SPLINE/id at time=x. The
INTERP function supports time-series splines, which are splines that include a FILE argument that
specifies a time history file of type DAC or RPC III.

Format
INTERP (Indep_Var, Method, Spline_name, Deriv_order)

Arguments

Independent Variable Enter a real variable that specifies the value of time, the independent
variable along the x-axis of the time series spline that is being interpolated.
Derivative Order Select the order of the derivative that Adams/Solver takes at the
interpolated point, and then returns through INTERP.

• Curve Coordinates (0) - Take no derivative (default)

• 1st Derivative (1)
• 2nd Derivative (2)
Interpolation Method Select the method of interpolation:

• Linear (1)
• Cubic (3)
Spline Name Enter the name of the SPLINE statement in the Adams/Solver dataset. The
SPLINE statement must reference time series data from a DAC or RPC III
file.

Examples
As part of the Adams/Durability feature, the INTERP function lets you specify how you want to
interpolate spline data from an RPC III or DAC time history file. An example is shown below of how to
specify the INTERP function in Adams/Solver for durability analysis.
For durability analysis, the INTERP function appears in a motion or force statement, and looks as
follows:
INTERP(time, 3, spline id)
where:

• time is the independent variable of the interpolation. For durability analysis, this real variable is
always time or an expression that includes time.
• 3 is the method of interpolation, which indicates cubic interpolation between data points. 1,
which indicates linear interpolation, is also a valid entry.
566 Adams/View Function Builder
Functions: A - M

• spline id is the identifier of the spline that specifies the RPC III or DAC file input. Setting up a
Spline in Adams/Durability.

For more information on the INTERP function, see INTERP for Adams/Solver (C++) or INTERP for
Adams/Solver (FORTRAN).
 Run-Time Functions 567
Functions: A - M

Joint Force (JOINT)

Returns a force or torque induced by a specified joint on one of the two bodies connected by the joint
object.

Format
JOINT (Joint Name, On This Body, Force Component, Along/About Axes)

Arguments

Joint Name (Required) Joint for which the force is measured.

On This Body (Required) Body on which the force is measured.

The legal values are:

• 0 = forces and torques on the first body, at the I marker

• 1 = forces and torques on the second body, at the J marker
Force Component (Required) Force or torque component you want to measure.

The legal values are:

• Fm = 1 = force magnitude
• Fx = 2 = x component of the force
• Fy = 3 = y component of the force
• Fz = 4 = z component of the force
• Tm = 5 = torque magnitude
• Tx = 6 = x component of the torque
• Ty = 7 = y component of the torque
• Tz = 8 = z component of the torque
Along/About Axes (Optional) Coordinate system marker in which the results are measured.

To have your results measured in the global coordinate system, do one of the
following:

• If you're entering your function through the Assist dialog box, leave the
Along/About Axes text box empty.
• If you're entering your function directly in the function text box, enter a
0.
568 Adams/View Function Builder
Functions: A - M

Example
The following function returns the magnitude of the force vector acting on the first body (at the I marker)
of .model_1.joint_1 in the global coordinate system.
JOINT(.model_1.joint_1, 0, 1, 0)
Learn more about force in object functions.
 Run-Time Functions 569
Functions: A - M

Joint Primitive Force (JPRIM)

Returns a force or torque induced by a specified joint primitive on one of the two bodies connected by
the joint primitive.

Format
JPRIM (Joint Primitive Name, On This Body, Force Component, Along/About Axes)

Arguments

Joint Primitive Name (Required) Joint primitive for which the force is measured.
On This Body (Required) Body on which the force is measured.

The legal values are:

• 0 = forces and torques on the first body, at the I marker

• 1 = forces and torques on the second body, at the J marker
Force Component (Required) Force or torque component you want to measure.

The legal values are:

• Fm = 1 = force magnitude
• Fx = 2 = x component of the force
• Fy = 3 = y component of the force
• Fz = 4 = z component of the force
• Tm = 5 = torque magnitude
• Tx = 6 = x component of the torque
• Ty = 7 = y component of the torque
• Tz = 8 = z component of the torque
Along/About Axes (Optional) Coordinate system marker in which the results are measured.

To have your results measured in the global coordinate system, do one of

the following:

• If you're entering your function through the Assist dialog box,

leave the Along/About Axes text box empty.
• If you're entering your function directly in the function text box,
enter a 0.
570 Adams/View Function Builder
Functions: A - M

Example
The following function returns the z component of the torque vector acting on the second body (at the J
marker) of .model_1.jprim_21 measured along the z-axis of .model_1.part_1.mar_11:
JPRIM(.model_1.jprim_21, 1, 8, .model_1.part_1.mar_11)
Learn more about force in object functions.
 Run-Time Functions 571
Functions: A - M

LOG
Returns the natural logarithm of an expression that represents a numerical value.
If ex = a then LOG(a) = x. The LOG function is defined only for positive values of a (that is, a > 0). It's
undefined for all other values.

Format
LOG(x)

Argument

x Any valid expression that evaluates to a real number.

Example
The following function returns the natural logarithm of the expression (1+TIME), where TIME is the
current simulation time:
LOG(1+TIME)
Learn more about math functions.
572 Adams/View Function Builder
Functions: A - M

LOG10
Returns log to base 10 of an expression that represents a numerical value.
If 10x = a, then LOG10(a) = x. The LOG10 function is defined only for positive values of a (that is, a >
0). It is undefined for all other values.

Format
LOG10(x)

Argument

x Any valid expression that evaluates to a real number.

Example
The following function returns the base 10 logarithm of the expression:
LOG10(1+VM(marker_21, marker_31))
Learn more about math functions.
 Run-Time Functions 573
Functions: A - M

MIN
Returns the minimum of two expressions that represent numerical values:
MIN(x1,x2) = x1 if x1 < x2MIN(x1,x2) = x2 if x2 < x1

Note: The MIN function is generally discontinuous. Use this function expression with care when
specifying force or motion input.

Format
MIN(x1,x2)

Arguments

x1 Any valid expression that evaluates to a real number.

x2 Any valid expression that evaluates to a real number.

Example
The following function is designed to always return a negative or zero value:
MIN(0, (25D-AZ(marker_2, marker_1)))
Learn more about math functions.
574 Adams/View Function Builder
Functions: A - M

MAX
Returns the maximum of two expressions that represent numerical values:
MAX(x1,x2) = x1 if x1 > x2MAX(x1,x2) = x2 if x2 > x1

Note: MAX is generally discontinuous. Use this function expression with care when specifying
force or motion input.

Format
MAX(x1,x2)

Arguments

x1 Any valid expression that evaluates to a real number.

x2 Any valid expression that evaluates to a real number.

Example
The following function is designed to always return a non-negative value:
MAX(0, (25D-AZ(marker_2, marker_1)))
Learn more about math functions.
 Run-Time Functions 575
Functions: A - M

MOD
Returns the remainder when one expression representing a numerical value is divided by another
expression that represents a numerical value:
MOD(a1, a2) = a1 - INT(a1/a2) * a2

Note: MAX is generally discontinuous. Use this function expression with care when specifying
force or motion input.

Format
MOD(x1,x2)

Arguments

x1 Any valid expression that evaluates to a real number.

x2 Any valid expression that evaluates to a real number.

Examples
The following examples illustrate the use of the MOD function:

Function MOD(45, 15)

Result 0

Function MOD(45, 16)

Result 13

Learn more about math functions.

576 Adams/View Function Builder
Functions: A - M

MODE
Returns an integer value indicating the current analysis mode.
The following are possible integer values and their corresponding analysis modes:
• 1 = Kinematics
• 2 = Reserved
• 3 = Initial conditions
• 4 = Dynamics
• 5 = Statics
• 6 = Quasi-statics
• 7 = Linear analysis

Format
MODE

Argument
None

Example
The following example combines the MODE function with the IF function to define a value applied only
during statics, quasi-static and linear analysis modes. For these analysis modes, we use the value of -50.
For all other analyses modes, we use the value 0.
IF(MODE-4: 0, 0, -50)
Learn more about constants and variables.
 Run-Time Functions 577
Functions: A - M

Motion Force (MOTION)

Returns a force or torque component induced by a specified motion on one of the two bodies affected by
the motion object.

Format
MOTION (Motion Name, On This Body, Force Component, Along/About Axes)

Arguments

Motion Name (Required) Motion for which the force is measured.

On This Body (Required) Body on which the force is measured.

The legal values are:

• 0 = forces and torques on the first body, at the I marker

• 1 = forces and torques on the second body, at the J marker
Force Component (Required) Force or torque component you want to measure.

The legal values are:

• Fm = 1 = force magnitude
• Fx = 2 = x component of the force
• Fy = 3 = y component of the force
• Fz = 4 = z component of the force
• Tm = 5 = torque magnitude
• Tx = 6 = x component of the torque
• Ty = 7 = y component of the torque
• Tz = 8 = z component of the torque
Along/About Axes (Optional)

Coordinate system marker in which the results are measured.

To have your results measured in the global coordinate system, do one of the
following:

• If you're entering your function through the Assist dialog box, leave the
Along/About Axes text box empty.
• If you're entering your function directly in the function text box, enter a
0.
578 Adams/View Function Builder
Functions: A - M

Example
The following function returns the z component of the torque vector acting on the second body (at the J
marker) affected by .model_1.motion_1, measured about the z-axis of .model_1.ground.marker_11:
MOTION(.model_1.motion_1, 1, 8, .model_1.ground.marker_11)
Learn more about force in object functions.
 Run-Time Functions 579
Functions: N - Z

Functions: N - Z
580 Adams/View Function Builder
Functions: N - Z

Multipoint Force (NFORCE)

Returns a force or torque applied by a specified multipoint force on one or two bodies directly affected
by the multipoint force.

Note: NFORCE can only be used for output purposes. Therefore, it can be used only with output
request and sensor objects.

Format
NFORCE (Multipoint Force Name, At This Marker, Force Component, Along/About Axes)

Arguments

Multipoint Force Name (Required) Multipoint force for which the force is measured.
At This Marker (Required) Marker on which the force is measured.

The legal values are:

• 0 = forces and torques on the I marker

• 1 = forces and torques on the J marker
 Run-Time Functions 581
Functions: N - Z

Force Component (Required) Force or torque component you want to measure.

The legal values are:

• Fm = 1 = force magnitude
• Fx = 2 = x component of the force
• Fy = 3 = y component of the force
• Fz = 4 = z component of the force
• Tm = 5 = torque magnitude
• Tx = 6 = x component of the torque
• Ty = 7 = y component of the torque
• Tz = 8 = z component of the torque
Along/About Axes (Optional) Coordinate system marker in which the results are measured.

To have your results measured in the global coordinate system, do one

of the following:

• If you're entering your function through the Assist dialog box,

leave the Along/About Axes text box empty.
• If you're entering your function directly in the function text box,
enter a 0.

Example
The following function returns the y component of the force vector acting on the second body (at the J
marker) of .model_3.nforce_41, measured along the y-axis of .model_3.part_5.marker_3:
NFORCE(.model_3.nfo_5, 1, 3, .model_3.part_5.marker_3)
Learn more about force in object functions.
582 Adams/View Function Builder
Functions: N - Z

One-sided Impact (IMPACT)

Returns a real number for a force magnitude corresponding to a one-sided collision, using a compression-
only nonlinear spring-damper formulation.

Format
IMPACT (Displacement Variable, Velocity Variable, Trigger for Displacement Variable, Stiffness
Coefficient, Stiffness Force Exponent, Damping Coefficient, Damping Ramp-up Distance)

Arguments

Displacement Variable A measure of the distance between colliding bodies; defined by a run-
time displacement function.
Velocity Variable A measure of the time derivative of the distance between colliding
bodies; defined by a run-time velocity function.
Trigger for Displacement Independent variable value at which to turn the one-sided impact on and
Variable off; defined by a real number, a run-time function, a design-time
function, a design variable or an expression.
Stiffness Coefficient or K Stiffness coefficient for spring force; defined by a real number, a run-
time function, a design-time function, a design variable or an expression.
Stiffness Force Exponent Exponent for nonlinear spring force; defined by a real number, a run-time
function, a design-time function, a design variable or an expression.
Damping Coefficient or C Damping coefficient for damper force; defined by a real number, a run-
time function, a design-time function, a design variable or an expression.
Damping Ramp-up Distance over which to gradually turn on damping once impact is
Distance triggered; defined by a real number, a run-time function, a design-time
function, a design variable or an expression.

Equation
The IMPACT function turns a force on and off depending on the value of the independent variable, as
follows:

 Off if q  q o 
F IMPACT =  
 On if q  q o 

Mathematically, IMPACT is calculated as follows:

MAX  0 K  q o – q  e – Cq·  STEP  q q o – d 1 q o 0  

where:
 Run-Time Functions 583
Functions: N - Z

• q is the displacement variable

• q· is the velocity variable

• qo is the trigger for displacement variable
• K is the stiffness coefficient
• C is the damping coefficient
• d is the damping ramp-up distance

Compression-only Spring Force from IMPACT Function

Compression-only Damping Force from IMPACT Function

584 Adams/View Function Builder
Functions: N - Z

Examples
You can use the IMPACT function to create a user-defined collision force (such as a single-component
force), for example, when a sphere hits a flat surface:
Sphere Hitting Flat Surface

Note: Assume that the flat surface being contacted by the sphere is an infinite plane.

IMPACT(DZ(marker_1, marker_2, marker_2), VZ(marker_1, marker_2,

marker_2, marker_2),15, 100, 1.2, 2.5, 0.01)
where:

• DZ(marker_1, marker_2, marker_2) defines the instantaneous displacement of marker_1 with

respect to marker_2 along the z-axis of marker_2.
• VZ(marker_1, marker_2, marker_2, marker_2) defines the velocity of marker_1 with respect to
part_2 minus the velocity of marker_2 with respect to part_2 along the z-axis of marker_2.
• The displacement trigger is the radius of the sphere, in this case 15 length units.
• The stiffness coefficient is 100.
• The stiffness force exponent is 1.2.
• The damping coefficient is 2.5.
• The penetration at which full damping is applied is 0.01 length unit.

Learn more about contact functions.

 Run-Time Functions 585
Functions: N - Z

PI
Returns the ratio of the circumference of a circle to its diameter (  ).

Format
PI

Argument
None

Example
The following example illustrates the use of the PI function:
2*PI*50
Learn more about constants and variables.
586 Adams/View Function Builder
Functions: N - Z

PLANT INPUT VALUE (PINVAL)

Returns the run-time value of a plant input.

Format
PINVAL (Plant Input Name, Element Number)

Arguments

Plant Input Name Name of the plant input to reference.

Element Number The element number in the list of inputs for the given plant input name.

Example
model_1.PIN corresponds to a definition of a plant input list. This plant input list contains three input
variables, defined as follows:
(model_1.VAR_1, model_1.VAR_2, model_1.VAR_3)
where:

• model_1.VAR_1 = "sin(TIME)"
• model_1.VAR_2 = "2"
• model_1.VAR_3 = "5"

Then PINVAL(model_1.PIN, 3) is equal to 5 at all times in the simulation.

Learn more about data element access.
 Run-Time Functions 587
Functions: N - Z

Plant Output Value (POUVAL)

Returns the run-time value of a plant output.

Format
POUVAL(Plant Output Name, Element Number)

Arguments

Plant Output Name Name of the plant output to reference.

Element Number The element number in the list of outputs for the given plant output name.

Examples
model_1.POU corresponds to a definition of a plant output list. This plant output list contains three input
variables, defined as follows:
(model_1.VAR_1, model_1.VAR_2, model_1.VAR_3)
where:

• model_1.VAR_1 = "sin(2*PI*TIME)"
• model_1.VAR_2 = "2"
• model_1.VAR_3 = "5"

At any time in the simulation,

Function POUVAL(model_1.POU,1)
Result sin(2*PI*TIME)

At .75 seconds into the simulation,

Function POUVAL(model_1.PIN,1)
Result -1

Learn more about data element access.

588 Adams/View Function Builder
Functions: N - Z

Point-to-Curve Force (PTCV)

Returns a force or torque induced by a specified point-to-curve object on one of the two bodies connected
by the point-to-curve object.

Note: PTCV can only be used for output purposes. Therefore, it can be used only with output
request and sensor objects.

Format
PTCV (Point-to-Curve Name, On This Body, Component, Along/About Axes)

Arguments

Point-to-Curve (Required) Point-to-curve object for which the force is measured.

Name
On This Body (Required) Body on which the force is measured.

The legal values are:

• 0 = forces and torques on the first body, at the I marker

• 1 = forces and torques on the second body, at the J marker
 Run-Time Functions 589
Functions: N - Z

Force Component (Required) Force or torque component you want to measure.

The legal values are:

• Fm = 1 = force magnitude
• Fx = 2 = x component of the force
• Fy = 3 = y component of the force
• Fz = 4 = z component of the force
• Tm = 5 = torque magnitude
• Tx = 6 = x component of the torque
• Ty = 7 = y component of the torque
• Tz = 8 = z component of the torque
Along/About Axes (Optional) Coordinate system marker in which the results are measured.

To have your results measured in the global coordinate system, do one of the
following:

• If you're entering your function through the Assist dialog box, leave the
Along/About Axes text box empty.
• If you're entering your function directly in the function text box, enter a 0.

Example
The following function returns the x component of the force vector acting on the first body (at the I
marker) of .model_1.ptcv_31, measured along the x-axis of the global coordinate system:
PTCV(.model_1.ptcv_31, 0, 2, 0)
Learn more about force in object functions.
590 Adams/View Function Builder
Functions: N - Z

Polynomial Fitted (POLYFIT)

Returns the coefficients of a polynomial fitted to the supplied function data.

Format
POLYFIT (x, y, order)

Arguments

x Array of x values.
y Array of y values.
order Maximum order of the polynomical. The coefficients are returned in increasing order
(from zeroth order to this value).

Examples
The following commands produce the array result.
var cre var=xx rea=(series2(0, 20, 20))
var cre var=yy rea=(1.0 + 1.2*xx + 2.5*xx**2 + 2.0*xx**3)
var cre var=pp rea=(polyfit(xx, yy, 5))
Array result:
[1.0, 1.2, 2.5, 2.0, 0.0, 0.0]
The coefficients are ordered from the zeroth order to the nth order, from left to right.
Learn more about math functions.
 Run-Time Functions 591
Functions: N - Z

Polynomial (POLY)
Evaluates a standard polynomial at a user-specified value x.

Format
POLY (x, Shift, Coefficients)

Arguments

x Real variable that specifies the independent variable.

Shift Real variable that specifies a shift in the polynomial.
Coefficients Real variables that define as many as thirty-one coefficients for the polynomial
series.

Examples
The following function defines a quadratic polynomial function with respect to the system variable
TIME:

Function POLY(TIME, 0, 0, 0, 1)
Expanded function POLY = TIME2

The following function defines a linear function with respect to the system variable TIME:

Function POLY(TIME, 5, 0, 10)

Expanded function POLY=10*(TIME-5)

The following function defines a cubic polynomial function with respect to the system variable TIME:

Function POLY(TIME, 10, 0, 25, 0, 0.75)

Expanded function POLY=-25*[TIME-10]+ 0.75*[TIME-10]3

Learn more about math functions.

592 Adams/View Function Builder
Functions: N - Z

RTOD
Returns the radians-to-degree units conversion factor (180/  ), same as (180/PI).

Format
RTOD

Argument
None

Example
The following example returns the roll angle, in degrees, to marker_2 from marker_4:
RTOD*ROLL(marker_2, marker_4)
Learn more about constants and variables.
 Run-Time Functions 593
Functions: N - Z

SIGN
Transfers the sign of one expression representing a numerical value to the magnitude of another
expression representing a numerical value:
SIGN(a1, a2) = ABS(a1) if a2 > 0
SIGN(a1, a2) = -ABS(a1) if a2 < 0

Note: SIGN is discontinuous. Use this function with care to avoid creating expressions that are
discontinuous.

Format
SIGN (x1,x2)

Arguments

x1 Any valid expression that evaluates to a real number.

x2 Any valid expression that evaluates to a real number.

Example
In the following function,
When VZ(marker_2, marker_3) > 0, the value is ABS(TIME). When
VZ(marker_2, marker_3)< 0, the value is -
ABS(TIME). SIGN(TIME,VZ(marker_2, marker_3))
Learn more about math functions.
594 Adams/View Function Builder
Functions: N - Z

Simple Harmonic (SHF)

Evaluates a simple harmonic function.

Format
SHF (x, Shift, Amplitude, Frequency, Phase Shift, Average Value of Displacement)

Arguments

x Real variable that specifies the independent variable.

Shift or x0 Real variable that specifies the offset in the independent variable x.
Amplitude or a Real variable that specifies the amplitude of the harmonic function.
Frequency or  Real variable that specifies the frequency of the harmonic function. It is
assumed that  is in radians per unit of the independent variable unless
you use a D after the value for degrees.
Phase Shift or phi Real variable that specifies a phase shift in the harmonic function.
Adams assumes that phi is in radians unless you use a D after the value.
Average Value of Real variable that specifies the average value of displacement of the
Displacement or b harmonic function.

Equation
Mathematically, SHF is defined as follows:
SHF = a*SIN(  *(x-x0)-phi)+b
where:

• x = Independent variable
• x0 = Shift

•  = Frequency
• phi = Phase Shift
• a = Amplitude
• b = Average Value of Displacement

Example
The following example illustrates the use of the SHF function:
SHF(TIME, 25D, PI, 360D, 0, 5)
The following function defines the harmonic function:
SHF = 5+PI*SIN(360D*(TIME-25D))
 Run-Time Functions 595
Functions: N - Z

In the function:
• x = TIME
• x0 = 25 degrees

•  = 1 cycle (360D)
• phi = 0
• a = PI
• b=5

Learn more about math functions.

596 Adams/View Function Builder
Functions: N - Z

SIN
Returns the sine of an expression that represents a numerical value.

Format
SIN(x)

Argument

x Any valid expression that evaluates to a real number.

Example
The following example returns the sine of 10*TIME, where TIME is the current simulation time:
SIN(10*TIME)
Learn more about math functions.
 Run-Time Functions 597
Functions: N - Z

Single-component Force (SFORCE)

Returns a force or torque applied by a specified single-component force on one or two bodies directly
affected by the single-component force.

Format
SFORCE (Single-component Force, On This Body, Force Component, Along/About Axes)

Arguments

Single-component (Required) Single-component force for which the force is measured.

Force
On This Body (Required) Body on which the force is measured.

The legal values are:

• 0 = forces and torques on the first body, at the I marker

• 1 = forces and torques on the second body, at the J marker
Force Component (Required) Force or torque component you want to measure.

The legal values are:

• Fm = 1 = force magnitude
• Fx = 2 = x component of the force
• Fy = 3 = y component of the force
• Fz = 4 = z component of the force
• Tm = 5 = torque magnitude
• Tx = 6 = x component of the torque
• Ty = 7 = y component of the torque
• Tz = 8 = z component of the torque
Along/About Axes (Optional)Coordinate system marker in which the results are measured.

To have your results measured in the global coordinate system, do one of the
following:

• If you're entering your function through the Assist dialog box, leave
the Along/About Axes text box empty.
• If you're entering your function directly in the function text box, enter
a 0.
598 Adams/View Function Builder
Functions: N - Z

Example
The following function returns the y component of the torque vector acting on the first body (at the I
marker) of .model_1.force_1, measured along the y-axis of the global coordinate system:
SFORCE(.model_1.force_1, 0, 7, 0)
Learn more about force in object functions.
 Run-Time Functions 599
Functions: N - Z

SINH
Returns the hyperbolic sine of an expression that represents a numerical value:
SINH(x) = (ex-e-x)/2.0

Format
SINH(x)

Argument

x Any valid expression that evaluates to a real number.

Example
The following example returns the hyperbolic sine of the x component of the displacement of marker_21
with respect to marker_32:
SINH(DX(marker_21, marker_32))
Learn more about math functions.
600 Adams/View Function Builder
Functions: N - Z

Six-component Force/Torque (GFORCE)

Returns a force or torque applied by a specified six-component force/torque on one or two bodies directly
affected by the six-component force/torque.

Format
GFORCE (Six-component Force/Torque, On This Body, Force Component, Along/About Axes)

Arguments

Six-component Force/Torque (Required) Six-component force/torque for which the force is

measured.
On This Body (Required) Body on which the force is measured.

The legal values are:

• 0 = forces and torques on the first body, at the I marker

• 1 = forces and torques on the second body, at the J marker
Force Component (Required) Force or torque component you want to measure.

The legal values are:

• Fm = 1 = force magnitude
• Fx = 2 = x component of the force
• Fy = 3 = y component of the force
• Fz = 4 = z component of the force
• Tm = 5 = torque magnitude
• Tx = 6 = x component of the torque
• Ty = 7 = y component of the torque
• Tz = 8 = z component of the torque
Along/About Axes (Optional) Coordinate system marker in which the results are
measured.

To have your results measured in the global coordinate system, do

one of the following:

• If you're entering your function through the Assist dialog

box, leave the Along/About Axes text box empty.
• If you're entering your function directly in the function text
box, enter a 0.
 Run-Time Functions 601
Functions: N - Z

Example
The following function returns the z component of the force vector acting on the first body (at the I
marker) of .model_3.gforce_31, measured along the z-axis of marker_23:
GFORCE(.model_3.gforce_31, 0, 4, marker_23)
Learn more about force in object functions.
602 Adams/View Function Builder
Functions: N - Z

Spring-Damper Force (SPDP)

Returns a force or torque applied by a specified spring-damper force on one or two bodies affected by the
spring-damper force.

Format
SPDP (Spring-Damper Force Name, On This Body, Force Component, Along/About Axes)

Arguments

Spring-Damper Force (Required) Spring-damper force for which the force is measured.
Name
On This Body (Required) Body on which the force is measured.

The legal values are:

• 0 = forces and torques on the first body, at the I marker

• 1 = forces and torques on the second body, at the J marker
Force Component (Required) Force or torque component you want to measure.

The legal values are:

• Fm = 1 = force magnitude
• Fx = 2 = x component of the force
• Fy = 3 = y component of the force
• Fz = 4 = z component of the force
• Tm = 5 = torque magnitude
• Tx = 6 = x component of the torque
• Ty = 7 = y component of the torque
• Tz = 8 = z component of the torque
Along/About Axes (Optional) Coordinate system marker in which the results are measured.

To have your results measured in the global coordinate system, do one of

the following:

• If you're entering your function through the Assist dialog box, leave
the Along/About Axes text box empty.
• If you're entering your function directly in the function text box,
enter a 0.
 Run-Time Functions 603
Functions: N - Z

Example
The following function returns the z component of the force vector acting on the first body (at the I
marker) of .model_1.spring_31, measured along the z-axis of the global coordinate system:
SPDP(.model_1.spring_15, 0, 4, 0)
Learn more about force in object functions.
604 Adams/View Function Builder
Functions: N - Z

SQRT
Returns the square root of an expression that represents a numerical value. The square root function is
defined only for non-negative values of x.

Format
SQRT(x)

Argument

x Any valid expression that evaluates to a real number.

Example
The following function returns the square root of the expression TIME:

Function SQRT(TIME*TIME)
Result TIME

Learn more about math functions.

 Run-Time Functions 605
Functions: N - Z

STEP
Approximates the Heaviside step function with a cubic polynomial.

Note: STEP has continuous first derivatives, but its second derivatives are discontinuous at x=x0
and x=x1. Haversine Step (HAVSIN), STEP5, and TANH offer other approximations for the
Heaviside step function. These have a higher degree of continuity and differentiability, but
can have larger derivatives.

See Haversine Step (HAVSIN) for a plot comparing STEP, STEP5, TANH, and Haversine
Step (HAVSIN).

Format
STEP (x, Begin At, Initial Function Value, End At, Final Function Value)

Arguments

x Independent variable.
Begin At or x0 Value of independent variable at which the STEP function begins;
defined by a real number, an expression or a design variable.
Initial Function Value or h0 Initial value of the step; defined by a real number, an expression, a
design variable or a run-time function.
End At or x1 Value of independent variable at which the STEP function ends;
defined by a real number, an expression or a design variable.
Final Function Value or h1 Final value of the step; defined by a real number, an expression, a
design variable or a run-time function.

Extended Definition
The STEP function approximates the Heaviside step function with a cubic polynomial. The following
figure illustrates the STEP function.
606 Adams/View Function Builder
Functions: N - Z

The equation defining the STEP function is:

a = h1 – h2

 =  x – xo    x1 – xo 

 ho : x  xo 
 
STEP =  h o – a   2  3 – 2  : xo  x  x 1 
 
 h1 : x  x1 

Example
Using a cubic polynomial, the following function defines a smooth step function from 3 to 4, with a
displacement from 0 to 1:
STEP((2, 3, 3.5, 4, 5), 3, 0, 4, 1)
This example produces the following results:
0.0, 0.0, 0.5, 1.0, 1.0
Learn more about math functions.
 Run-Time Functions 607
Functions: N - Z

STEP5
Provides approximations to the Heaviside step function with a quintic polynomial.

Note: STEP5 has continuous first and second derivatives, but its third derivative is discontinuous
at x=x0 and x=x1.

See Haversine Step (HAVSIN) for a plot comparing STEP, STEP5, TANH, and Haversine
Step (HAVSIN).

Format
STEP5 (x, Begin At, Initial Function Value, End At, Final Function Value)

Arguments

x Independent variable.
Begin At or x0 Real variable that specifies the x value at which the STEP5 function
begins.
Initial Function Value or h0 Initial value of the step.
End At or x1 Real variable that specifies the x value at which the STEP5 function
ends.
Final Function Value or h1 Final value of the step.

Example
Using a quintic polynomial, the following function defines a smooth step function from time 1 to time 2
with a displacement from 0 to 1:
STEP5(TIME, 1, 0, 2, 1)
Learn more about math functions.
608 Adams/View Function Builder
Functions: N - Z

Sum of Forces Along X (FX)

Returns an x component of the net translational force acting at one coordinate system marker due to all
applied forces and constraints acting between that coordinate system marker and another.

Format
FX (Applied To Marker, Applied From Marker, Along Marker)

Arguments

Applied To Marker (Required) Measure of the sume of all forces applied to this coordinate
system marker.
Applied From Marker (Optional) Measure the sum of all forces applied from this coordinate system
marker. If you don't specify this argument, it returns the x component of all
the action-only single-component forces acting at the Applied To Marker.
Along Marker (Optional) Measure the sum of all forces in the x direction of this coordinate
system marker. If you don't specify this argument, it defaults to the global
origin.

Equation
Mathematically, FX is calculated as follows:

FX =  FT F  x̂A
where:

•
 FT F is the sum of all applied and constraint forces involving both the Applied To Marker,
T, and the Applied From Marker, F.

• x̂ A is the x-axis of the Along Marker, A.

Example
The following function returns the x component of the sum of all forces acting at marker_T. All forces
acting between marker_T and marker_F are included in this calculation.

Function FX(marker_T, marker_F, marker_A)

Result 4
 Run-Time Functions 609
Functions: N - Z

Learn more about resultant force functions.

610 Adams/View Function Builder
Functions: N - Z

Sum of Forces Along Y (FY)

Returns a y component of the net translational force acting at one coordinate system marker due to all
applied forces and constraints acting between that coordinate system marker and another.

Format
FY (Applied To Marker, Applied From Marker, Along Marker)

Arguments

Applied To Marker (Required) Measure the sum of all forces applied to this coordinate system
marker.
Applied From Marker (Optional) Measure the sum of all forces applied from this coordinate
system marker. If you don't specify this argument, it returns the y
component of all the action-only single-component forces acting at the
Applied To Marker.
Along Marker (Optional) Measure the sum of all forces in the y direction of this coordinate
system marker. If you don't specify this argument, it defaults to the global
origin.

Equation
Mathematically, FY is calculated as follows:

FY =  FT F  ŷA
where:

•
 FT F is the sum of all applied and constraint forces involving both the Applied To Marker,
T, and the Applied From Marker, F.

• ŷ A is the y-axis of the Along Marker, A.

Example
The following function returns the y component of the sum of all forces acting at marker_T. All forces
acting between marker_T and marker_F are included in this calculation.

Function FY(marker_T, marker_F, marker_A)

Result 3
 Run-Time Functions 611
Functions: N - Z

Learn more about resultant force functions.

612 Adams/View Function Builder
Functions: N - Z

Sum of Forces Along Z (FZ)

Returns a z component of the net translational force acting at one coordinate system marker due to all
applied forces and constraints acting between that coordinate system marker and another.

Format
FZ (Applied To Marker, Applied From Marker, Along Marker)

Arguments

Applied To Marker (Required) Measure the sum of all forces applied to this coordinate
system marker.
Applied From Marker (Optional) Measure the sum of all forces applied from this coordinate
system marker. If you don't specify this argument, it returns the z
component of all the action-only single-component forces acting at the
Applied To Marker.
Along Marker (Optional) Measure the sum of all forces in the z direction of this
coordinate system marker. If you don't specify this argument, it defaults
to the global origin.

Equation
Mathematically, FZ is calculated as follows:

FZ =  FT F  ẑA
where:

•
 FT F is the sum of all applied and constraint forces involving both the Applied To
Marker, T, and the Applied From Marker, F.

• ẑ A is the z-axis of the Along Marker, A.

Example
The following function returns the z component of the sum of all forces acting at marker_T. All forces
acting between marker_T and marker_F are included in this calculation.

Function FZ(marker_T, marker_F, marker_A)

Result 0
 Run-Time Functions 613
Functions: N - Z

Learn more about resultant force functions.

614 Adams/View Function Builder
Functions: N - Z

Sum of Forces Magnitude (FM)

Returns the magnitude of the net translational force acting at one coordinate system marker due to all
applied forces and constraints acting between that coordinate system marker and another.

Format
FM (Applied To Marker, Applied From Marker)

Arguments

Applied To Marker (Required) Measure the sum of all forces applied to this coordinate
system marker.
Applied From Marker (Optional) Measure the sum of all forces applied from this coordinate
system marker. If you don’t specify this argument, it returns the
magnitude of the net translational force at the Applied To Marker due to
action-only single-component forces acting at the Applied To Marker.

Equation
Mathematically, FM is calculated as follows:

FM =  FT F   FT F
where:

•
 FT F is the sum of all applied and constraint forces involving both the Applied To

Marker, T, and the Applied From Marker, F.

Example
The following function returns the magnitude of the sum of all forces acting at marker_T. All forces
acting between marker_T and marker_F are included in this calculation:

Function FM(marker_T, marker_F)

Result 5
 Run-Time Functions 615
Functions: N - Z

Learn more about resultant force functions.

616 Adams/View Function Builder
Functions: N - Z

Sum of Torques About X (TX)

Returns an x component of the net torque acting at one coordinate system marker due to all applied
torques and constraints acting between that coordinate system marker and another.

Format
TX (Applied To Marker, Applied From Marker, About Marker)

Arguments

Applied To Marker (Required) Measure the sum of all torques applied to this coordinate
system marker.
Applied From Marker (Optional) Measure the sum of all torques applied from this coordinate
system marker. If you don't specify this argument, it returns the x
component of all the action-only single-component torques acting at the
Applied To Marker.
About Marker (Optional) Measure the sum of all torques about the x-axis of this
coordinate system marker. If you don't specify this argument, it defaults
to the global coordinate system.

Equation
Mathematically, TX is calculated as follows:

TX =  TT F  x̂A
where:

•
 TT F is the sum of all applied and constraint torques involving both the Applied To
Marker, T, and the Applied From Marker, F.

• x̂ A is the x-axis of the About Marker, A.

Example
The following function returns the x component of the sum of all torques acting at marker_T. All torques
acting between marker_T and marker_F are included in this calculation.

Function TX(marker_T, marker_F, marker_A)

Result 5.3
 Run-Time Functions 617
Functions: N - Z

Learn more about resultant force functions.

618 Adams/View Function Builder
Functions: N - Z

Sum of Torques About Y (TY)

Returns a y component of the net torque acting at one coordinate system marker due to all applied torques
and constraints acting between that coordinate system marker and another.

Format
TY (Applied To Marker, Applied From Marker, About Marker)

Arguments

Applied To Marker (Required) Measure the sum of all torques applied to this coordinate system
marker.
Applied From Marker (Optional) Measure the sum of all torques applied from this coordinate
system marker. If you don't specify this argument, it returns the x
component of all the action-only single-component torques acting at the
Applied To Marker.
About Marker (Optional) Measure the sum of all torques about the y-axis of this coordinate
system marker. If you don't specify this argument, it defaults to the global
coordinate system.

Equation
Mathematically, TY is calculated as follows:

TY =  TT F  ŷA
where:

•
 TT F is the sum of all applied and constraint torques involving both the Applied To

Marker, T, and the Applied From Marker, F.

• ŷ A is the y-axis of the About Marker, A.

Examples
The following function returns the y component of the sum of all torques acting at marker_T. All torques
acting between marker_T and marker_F are included in this calculation.

Function TY(marker_T, marker_F, marker_A)

Result 7.2
 Run-Time Functions 619
Functions: N - Z

Learn more about resultant force functions.

620 Adams/View Function Builder
Functions: N - Z

Sum of Torques About Z (TZ)

Returns a z component of the net torque acting at one coordinate system marker due to all applied torques
and constraints acting between that coordinate system marker and another.

Format
TZ (Applied To Marker, Applied From Marker, About Marker)

Arguments

Applied To Marker (Required) Measure the sum of all torques applied to this coordinate
system marker.
Applied From Marker (Optional) Measure the sum of all torques applied from this coordinate
system marker. If you don't specify this argument, it returns the x
component of all the action-only single-component torques acting at the
Applied To Marker.
About Marker (Optional) Measure the sum of all torques about the z-axis of this
coordinate system marker. If you don't specify this argument, it defaults
to the global coordinate system.

Equation
Mathematically, TZ is calculated as follows:

TZ =  TT F  ẑA
where:

•
 TT F  x̂A is the sum of all applied and constraint torques involving both the Applied

To Marker, T, and the Applied From Marker, F.

• ẑ A is the z-axis of the About Marker, A.

Example
The following function returns the z component of the sum of all torques acting at marker_T. All torques
acting between marker_T and marker_F are included in this calculation.

Function TZ(marker_T, marker_F, marker_A)

Result 9.7
 Run-Time Functions 621
Functions: N - Z

Learn more about resultant force functions.

622 Adams/View Function Builder
Functions: N - Z

Sum of Torques Magnitude (TM)

Returns the magnitude of the net torque acting at one coordinate system marker due to all applied torques
and constraints acting between that coordinate system marker and another.

Format
TM (Applied To Marker, Applied From Marker)

Arguments

Applied To Marker (Required) Measure the sum of all torques applied to this coordinate system
maker.
Applied From Marker (Optional) Measure the sum of all torques applied from this coordinate
system maker. If you don't specify this argument, it returns the magnitude of
the sum of all torques at the Applied To Marker due to action-only torque
acting at the Applied To Marker.

Equation
Mathematically, TM is calculated as follows:

TM =  TT F   TT F
where:

 TT F  x̂A is the sum of all applied and constraint torques involving both the Applied To

Marker, T, and the Applied From Marker, F.

Example
The following function returns the magnitude of the sum of all torques acting at marker_T. All torques
acting between marker_T and marker_F are included in this calculation.

Function TM(marker_T, marker_F)

Result 13.19
 Run-Time Functions 623
Functions: N - Z

Learn more about resultant force functions.

624 Adams/View Function Builder
Functions: N - Z

SWEEP
Returns a constant amplitude sinusoidal function with linearly increasing frequency.

Format
SWEEP (Independent Variable, Amplitude, Start Value, Start Frequency, End Value, End Frequency,
Delta X)

Arguments

Independent Variable or x Independent variable.

Amplitude or a Real variable that specifies the amplitude.
Start Value or x0 Real variable that specifies the independent variable value at which the
SWEEP function begins.
Start Frequency or f0 Real variable that specifies the initial frequency.
End Value or x1 Real variable that specifies the independent variable value at which the
SWEEP function ends.
End Frequency or f1 Real variable that defines the final frequency.
Delta X or dx Real variable that specifies the interval in which the SWEEP function
becomes fully active.

Equation
Mathematically, SWEEP is calculated as follows:
SWEEP = STEP5(x,0,0,dx,1)* a * sin(2  *(freq(x)*x + PHASE(x)))
where:

 fo if x  x o 
 
  f 1 – f o  x – 2x o 
freq  x  =  f o + ------------------- ----------------- if x o  x  x 1 
 2 x1 – xo 
 f 
 1 if x  x 1 

 0 if x  x o 
 
 0.5  x o2 
PHASE  x  =   f 1 – f o  ----------------- if x o  x  x 1 
 x1 – xo 
 
 0.5DO   f 1 – f o    x 0 – x 1  if x  x 1 
 Run-Time Functions 625
Functions: N - Z

Example
The following function defines a sinusoidal function with a frequency increasing from 2 to 6Hz within
the time interval 0 to 5:
SWEEP(TIME, 1.0, 0.0, 2.0, 5.0, 6.0, 0.01)

Learn more about math functions.

626 Adams/View Function Builder
Functions: N - Z

TAN
Returns the tangent of an expression that represents a numerical value.

Format
TAN(x)

Argument

x Any valid expression that evaluates to a real number.

Example
The following function returns the tangent of 10*TIME, where TIME is the current simulation time:
TAN(10*TIME)
Learn more about math functions.
 Run-Time Functions 627
Functions: N - Z

TANH
Returns the hyperbolic tangent of an expression that represents a numerical value:
TANH(x) = (ex-e-x)/(xa+exa)

Note: See Haversine Step (HAVSIN) for a plot comparing STEP, STEP5, TANH, and Haversine
Step (HAVSIN).

Format
TANH(x)

Argument

x Any valid expression that evaluates to a real number.

Example
Using a hyperbolic tangent, the following function defines a smooth step function that transitions from a
value of 0 to 1:
TANH(5*(TIME-1.5))
Learn more about math functions.
628 Adams/View Function Builder
Functions: N - Z

Three-component Force (VFORCE)

Returns a force or torque applied by a specified three-component force on one or two bodies directly
affected by the three-component force.

Format
VFORCE (Three-component Force, On This Body, Force Component, Along Axes)

Arguments

Three-component Force (Required) Three-component force for which the force is measured.
On This Body (Required) Body on which the force is measured.

The legal values are:

• 0 = forces and torques on the first body, at the I marker

• 1 = forces and torques on the second body, at the J marker
Force Component (Required) Force or torque component you want to measure.

The legal values are:

• Fm = 1 = force magnitude
• Fx = 2 = x component of the force
• Fy = 3 = y component of the force
• Fz = 4 = z component of the force
• Tm = 5 = torque magnitude
• Tx = 6 = x component of the torque
• Ty = 7 = y component of the torque
• Tz = 8 = z component of the torque
Along/About Axes (Optional) Coordinate system marker in which the results are measured.

To have your results measured in the global coordinate system, do one of

the following:

• If you're entering your function through the Assist dialog box,

leave the Along/About Axes text box empty.
• If you're entering your function directly in the function text box,
enter a 0.
 Run-Time Functions 629
Functions: N - Z

Examples
The following function returns the x component of the force vector acting on the second body (at the J
marker) due to the three-component force named .model_1.vforce_31, measured along the x-axis of the
global coordinate system:
VFORCE(.model_1.vforce_31, 1, 2, 0)
The following function returns the z component of the force vector acting on the first body (at the I
marker) due to the three-component force named .contact_force, measured along the z-axis of marker_6:
VFORCE(contact_force, 0, 4, marker_6)
Learn more about force in object functions.
630 Adams/View Function Builder
Functions: N - Z

Three-component Torque (VTORQ)

Returns a force or torque applied by a specified three-component torque on one or two bodies directly
affected by the three-component torque.

Format
VTORQ (Three-component Torque, On This Body, Component, About Axes)

Arguments

Three-component Torque (Required) Three-component torque for which the force is

measured.
On This Body (Required) Body on which the force is measured.

The legal values are:

• 0 = forces and torques on the first body, at the I marker

• 1 = forces and torques on the second body, at the J marker
Force Component (Required) Force or torque component you want to measure.

The legal values are:

• Fm = 1 = force magnitude
• Fx = 2 = x component of the force
• Fy = 3 = y component of the force
• Fz = 4 = z component of the force
• Tm = 5 = torque magnitude
• Tx = 6 = x component of the torque
• Ty = 7 = y component of the torque
• Tz = 8 = z component of the torque
About Axes (Optional) Coordinate system marker in which the results are
measured.

To have your results measured in the global coordinate system, do

one of the following:

• If you're entering your function through the Assist dialog

box, leave the Along/About Axes text box empty.
• If you're entering your function directly in the function text
box, enter a 0.
 Run-Time Functions 631
Functions: N - Z

Example
The following function returns the x component of the torque vector acting on the second body (at the J
marker) of .model_1.vtorque_31, measured along the x-axis of marker_2:
VTORQ(.model_1.vtorque_1, 1, 6, marker_2)
Learn more about force in object functions.
632 Adams/View Function Builder
Functions: N - Z

TIME
Returns the current simulation time.

Format
TIME

Argument
None

Example
The following example and illustration represent a linearly-increasing function of simulation time with
a slope of 2:
2*TIME

Learn more about constants and variables.

 Run-Time Functions 633
Functions: N - Z

Two-sided Impact (BISTOP)

Returns a real number for a force magnitude corresponding to a two-sided collision, using a compression-
only nonlinear spring-damper formulation.

Format
BISTOP (Displacement Variable, Velocity Variable, Low Trigger for Displacement Variable, High
Trigger for Displacement Variable, Stiffness Coefficient, Stiffness Force Exponent, Damping
Coefficient, Damping Ramp-up Distance)

Arguments

Displacement Variable A measure of the distance between colliding bodies; defined by a run-
time displacement function.
Velocity Variable A measure of the time derivative of the distance between colliding
bodies; defined by a run-time velocity function.
Low Trigger for Lower value for independent variable at which to trigger the first side
Displacement Value of two-sided impact.
High Trigger for Higher value for independent variable at which to trigger the second
Displacement Value side of two-sided impact.
Stiffness Coefficient or K Stiffness coefficient for spring force; defined by a real number, a run-
time function, a design-time function, a design variable or an
expression.
Stiffness Force Exponent Exponent for nonlinear spring force; defined by a real number, a run-
time function, a design-time function, a design variable or an
expression.
Damping Coefficient or C Damping coefficient for damper force; defined by a real number, a run-
time function, a design-time function, a design variable or an
expression.
Damping Ramp-up Distance over which to gradually turn on damping once impact is
Distance triggered; defined by a real number, a run-time function, a design-time
function, a design variable or an expression.

Equation
The BISTOP function turns a force on and off depending on the value of the independent variable q, as
follows:

On if q  q o 
F BISTOP =  
 Off if q 1  q  q 2 

Mathematically, BISTOP is calculated as follows:

634 Adams/View Function Builder
Functions: N - Z

·
 K  q 1 – q  – Cq  STEP  q q 1 – d 1 q 1 0  if q  q 1
e

 
F BISTOP =  0 if q 1  q  q 2 
 
 K  q – q 2  e – Cq·  STEP  q q 2 0 q 2 + d 1  if q 2  q 

Example
You can use the BISTOP function for the system shown in the figure below:
BISTOP(DX(marker_1, marker_2, marker_2),VX(marker_1, marker_2,
marker_2, marker_2),5.2, 22.4, 100, 1.2, 2.5, 0.005)where 22.4
was derived from 5.2 + 28.7 - 11.5.
BISTOP Example

Learn more about contact functions.

 Run-Time Functions 635
Functions: N - Z

USER
Passes one or more values that are used as parameters in a user-written subroutine.
For information on subroutines, see the online help for Adams/Solver Subroutines.

Format
USER(Parameters)

Argument

Parameters Real values that define the parameters for use by the user-written subroutine. Up to
thirty parameters may be defined.

Example
To model a simple spring damper in a SFORCE subroutine, you need information about the i and j
marker, stiffness and damping, as well as the free length. Assume the following:
• i marker id = 1
• j marker id = 2
• stiffness (k) = 1e5N/mm
• damping coefficient (c) = 10ns/mm
• free length (FL) = 1e3mm

Given the above information, the USER function is:

USER (1, 2, 1e5, 10, 1e3)
Learn more about user-written subroutine invocation.
636 Adams/View Function Builder
Functions: N - Z

Velocity Along Line-of-Sight (VR)

Returns the radial (relative) velocity to one coordinate system marker from another. The vector time
derivative is taken in a reference coordinate system marker.
When the two markers move away from each other, VR is positive. When the two markers approach each
other, VR is negative.

Format
VR (To Marker, From Marker, Reference Frame)

Arguments

To Marker (Required) The coordinate system marker whose velocity is being measured.
From Marker (Optional) The coordinate system marker whose velocity is subtracted off. If
you don't specify this argument, it defaults to the global origin.
Reference Frame (Optional) The coordinate system marker in which the time-derivatives are
calculated. If you don't specify this argument, it defaults to the ground
reference frame.

Equation
Mathematically, VR is calculated as follows:

R d R d
RT – R   RT – RF 
dt dt F
VR = -----------------------------------------------------------------------------
DM  T F 
where:

• R T is the position vector from the global origin to the To Marker, T.

R d
• R T is the time-derivative of R T with respect to the Reference Frame, R.
dt

• R F [ is the position vector from the global origin to the From Marker, F.
R d
• R F is the time-derivative of R F with respect to the Reference Frame, R.
dt
• DM(T,F) is the distance between the To Marker, T, and the From Marker, F.
 Run-Time Functions 637
Functions: N - Z

Example
The following function returns the radial (relative) velocity of the velocity vector between marker_T and
marker_F. The vector time-derivative is taken in the reference frame of marker_R.
VR(marker_T, marker_F, marker_R)
Learn more about velocity functions.
638 Adams/View Function Builder
Functions: N - Z

Velocity Along X (VX)

Returns an x component of the difference between the velocity vectors of two coordinate system markers.

Format
VX (To Marker, From Marker, Along Marker, Reference Frame)

Arguments

To Marker (Required) The coordinate system marker whose velocity is being measured.
From Marker (Optional) The coordinate system marker whose velocity is subtracted off. If
you don't specify this argument, it defaults to the global origin.
Along Marker (Optional) The coordinate system marker along whose x-axis the velocity is
measured. If you don't specify this argument, it defaults to the global x-axis.
Reference Frame (Optional) The coordinate system marker in which the time derivatives are
calculated. If you don't specify this argument, it defaults to the ground
reference frame.

Equation
Mathematically, VX is calculated as follows:

R d R d
VX = RT – R F  x̂ A
dt dt
where:

• R T is the position vector from the global origin to the To Marker, T.

R d
• R T is the time-derivative of R T with respect to the Reference Frame, R.
dt

• R F is the position vector from the global origin to the From Marker, F.
R d
• R F is the time-derivative of R F with respect to the Reference Frame, R.
dt
• x̂ A is the unit vector along the x-axis of the Along Marker, A.
 Run-Time Functions 639
Functions: N - Z

Example
The following function returns the x component of the velocity vector between marker_T and marker_F.
The vector is expressed in the coordinate system of marker_A. All time-derivatives are calculated in the
reference frame of marker_R.
VX(marker_T, marker_F, marker_A, marker_R)
Learn more about velocity functions.
640 Adams/View Function Builder
Functions: N - Z

Velocity Along Y (VY)

Returns a y component of the difference between the velocity vectors of two coordinate system markers.

Format
VY (To Marker, From Marker, Along Marker, Reference Frame)

Arguments

To Marker (Required) The coordinate system marker whose velocity is being measured.
From Marker (Optional) The coordinate system marker whose velocity is subtracted off. If you
don't specify this argument, it defaults to the global origin.
Along Marker (Optional) The coordinate system marker along whose y-axis the velocity is
measured. If you don't specify this argument, it defaults to the global y-axis.
Reference Frame (Optional) The coordinate system marker in which the time derivatives are
calculated. If you don't specify this argument, it defaults to the ground reference
frame.

Equation
Mathematically, VY is calculated as follows:

R d R d
VY = RT – R F  ŷ A
dt dt
where:

• R T is the position vector from the global origin to the To Marker, T.

R d
• R T is the time-derivative of R T with respect to the Reference Frame, R.
dt

• R F is the position vector from the global origin to the From Marker, F.
R d
• R F is the time-derivative of R F with respect to the Reference Frame, R.
dt
• ŷ A is the unit vector along the y-axis of the Along Marker, A.
 Run-Time Functions 641
Functions: N - Z

Example
The following function returns the y component of the velocity vector between marker_T and marker_F.
The vector is expressed in the coordinate system of marker_A. All time-derivatives are calculated in the
reference frame of marker_R.
VY(marker_T, marker_F, marker_A, marker_R)
Learn more about velocity functions.
642 Adams/View Function Builder
Functions: N - Z

Velocity Along Z (VZ)

Returns a z component of the difference between the velocity vectors of two coordinate system markers.

Format
VZ (To Marker, From Marker, Along Marker, Reference Frame)

Arguments

To Marker (Required) The coordinate system marker whose velocity is being measured.
From Marker (Optional) The coordinate system marker whose velocity is subtracted off. If you
don't specify this argument, it defaults to the global origin.
Along Marker (Optional) The coordinate system marker along whose z-axis the velocity is
measured. If you don't specify this argument, it defaults to the global z-axis.
Reference Frame (Optional) The coordinate system marker in which the time derivatives are
calculated. If you don't specify this argument, it defaults to the ground reference
frame.

Equation
Mathematically, VZ is calculated as follows:

R d R d
VZ = RT – R F  ẑ A
dt dt
where:

• R T is the position vector from the global origin to the To Marker, T.

R d
• R T is the time-derivative of R T with respect to the Reference Frame, R.
dt

• R F is the position vector from the global origin to the From Marker, F.
R d
• R F is the time-derivative of R F with respect to the Reference Frame, R.
dt
• ẑ A is the unit vector along the z-axis of the Along Marker, A.
 Run-Time Functions 643
Functions: N - Z

Example
The following function returns the z component of the velocity vector between marker_T and marker_F.
The vector is expressed in the coordinate system of marker_A. All time-derivatives are calculated in the
reference frame of marker_R.
VZ(marker_T, marker_F, marker_A, marker_R)
Learn more about velocity functions.
644 Adams/View Function Builder
Functions: N - Z

Velocity Magnitude (VM)

Returns the magnitude of the first time-derivative of the displacement vector between two coordinate
system markers.

Format
VM (To Marker, From Marker, Reference Frame)

Arguments

To Marker (Required) The coordinate system marker whose velocity is being measured.
From Marker (Optional) The coordinate system marker whose velocity is subtracted off. If you
don't specify this argument, it defaults to the global origin.
Reference Frame (Optional) The coordinate system marker in which the time derivatives are
calculated. If you don't specify this argument, it defaults to the ground reference
frame.

Equation
Mathematically, VM is calculated as follows:

R d R d R d R d

VM =  RT – R   RT – R F .
 dt d t F  dt dt 

where:

• R T is the position vector from the global origin to the To Marker, T.

R d
• R T is the time-derivative of R T with respect to the Reference Frame, R.
dt

• R F is the position vector from the global origin to the From Marker, F.
R d
• R F is the time-derivative of R F with respect to the Reference Frame, R.
dt

Example
The following function returns the magnitude of the velocity vector between marker_T and marker_F.
The vector time-derivative is taken in the reference frame of marker_R.
VM(marker_T, marker_F, marker_R)
Learn more about velocity functions.
 Product-Specific Functions 645

Product-Specific Functions
When using a template-based or plugin product with Adams/View, the Function Builder includes some
product-specific functions.
646 Adams/View Function Builder
Adams/Solver (C++)

Adams/Solver (C++)

• Q
• QDDOT
• QDOT
• DELAY
• AO
• CPU
• HSIZE
• NJAC
• NRHS
• ORDER
• UV
• MAG
• TRANS
• ACCXYZ
• DXYZ
• FXYZ
• TXYZ
• UVX
• UVY
• UVZ
• VXYZ
• WXYZ
• WDTXYZ
 Product-Specific Functions 647
Adams/Durability

Adams/Durability
When using Adams/Durability, you can use its functions to interrogate a flexible or rigid body for useful
stress, strain, or life data. The user functions are:
• HOT_SPOTS
• LIFE
• MAX_STRESS
• TOP_SPOTS

These functions facilitate the definition of a design objective or variable that can be used in a design of
experiments (DOE) or optimization study. When Adams/Durability is loaded, you can find these
functions in the Misc. Functions category of the Adams/View Function Builder.
648 Adams/View Function Builder
Template-Based Products

Template-Based Products
This topic lists utility functions that help you extend the Adams/View macro language in template-based
products. The functions help you access information that is not easy to access using the standard
Adams/View macro language. You can use the utility functions in macros and in dialog boxes.
• Units-Conversion Functions
• String Functions
• Database Functions
• File Functions
• Database Lookup Functions
• Miscellaneous Functions
 Adams/View Function Builder Examples 649

Adams/View Function Builder Examples

Select an example to help you become more familiar with the Function Builder:
• Expression Example
• Example - Building Functions for Motions
• Example - Parameterizing Values for Marker Locations
• Writing Your Own Compiled Functions
• Accessing Arrays Within Compiled Functions
650 Adams/View Function Builder
Expression Example

Expression Example
The following example illustrates how you can parameterize the mass of one part in relation to the mass
of another, using the Adams/View command language in the command window.
If you want to define the mass of a part (part_2) as twice the mass of another part (part_1), you could use
the following command:
part modify rigid_body mass_properties part_name=part_2 &
mass=(EVAL(part_1.mass*2))

Note: You must enclose all Adams/View expressions in parentheses.

Using the EVAL function, Adams/View instantaneously computes the value for the expression and stores
the value in the database. It maintains no parametric relationship. If the mass of part_1 subsequently
changes, it doesn't affect the mass of part_2.
If you use the same command without the EVAL function, you get the same instantaneous effect as the
previous command. However, if the mass of part_1 changes, then Adams/View automatically updates the
mass of part_2. Therefore, Adams/View maintains the parametric relationship:
part modify rigid_body mass_properties part_name=part_2 &
mass=(part_1.mass * 2)>
Note that some parameters act as though you supplied the EVAL function, even if you did not.
You can find more examples of using expressions in Adams/View in the directory:
install_dir/aview/examples, where install_dir is the directory in which you installed Adams.
 Adams/View Function Builder Examples 651
Example - Building Functions for Motions

Example - Building Functions for Motions

This example demonstrates how you can restrict the angle of movement of a link using the Simple
Harmonic (SHF) function.

To build a function for motion:

1. Create a link and place a revolute joint and a rotational joint motion at one end of the link.

2. Right-click the motion screen icon, and then select Modify.

The Impose Joint Motion dialog box appears.
3. Clear the F(time) text box.
4. Right-click the F(time) text box, and then select Function Builder.
5. From the Math Functions category, select Simple Harmonic.
6. Select Assist.
652 Adams/View Function Builder
Example - Building Functions for Motions

7. The Simple Harmonic Function dialog box appears. Fill in the dialog box as shown next:

8. Select OK in the following dialog boxes, in the order listed:

a. The Simple Harmonic Function dialog box.
The function you just defined appears in the function work area of the Function Builder.
b. The Function Builder.
The function appears in the F(time) text box.
c. The Impose Joint Motion dialog box.
The motion now uses the function you built.

Note: Adams/View cannot plot the Simple Harmonic function in the Function Builder, because
it can't interpret it as a design-time function.
 Adams/View Function Builder Examples 653
Example - Parameterizing Values for Marker Locations

Example - Parameterizing Values for Marker Locations

This example shows how to use the LOC_ALONG_LINE function to parameterize the location of a marker
with respect to another marker.

To parameterize a location:
1. Create three markers, MAR_1, MAR_2, and MAR_3, placed randomly.
2. Right-click the MAR_2 screen icon, and then select Modify.
The Marker Modify dialog box appears.
3. Clear the coordinate values from the Location text box.
4. Right-click the Location text box, point to Parameterize, and then select Expression Builder.
The Function Builder appears in expression mode.
5. Clear the text from the function work area.
6. From the Location/Orientation function category, select LOC_ALONG_LINE.
7. Select Assist.
The LOC_ALONG_LINE dialog box appears.
8. From the box pop-up menus, use Browse to insert:
• MAR_1 in Object for Start Point text box.
• MAR_3 in Object for Point on Line text box.
9. In the Distance text box, enter 50.
10. Select OK in the following dialog boxes, in the order listed:
• The LOC_ALONG_LINE dialog box.
The function you just defined appears in the function work area of the Function Builder.
• The Function Builder.
The function appears in the Location text box.
• The Marker Modify dialog box.
MAR_2 is now 50 units from MAR_1. MAR_1 and MAR_2 are parameterized. As a result,
if you move one marker, the other marker moves along with it.
654 Adams/View Function Builder
Example - Parameterizing Values for Marker Locations